Valhalla静态工程审阅｜Planning with Files 深度评测：用持久化文件解决 AI 长任务的上下文与恢复问题【Agent Skill 特辑 #020】

Valhalla静态工程审阅Planning with Files 深度评测用持久化文件解决 AI 长任务的上下文与恢复问题【Agent Skill 特辑 #020】评测对象planning-with-files仓库https://github.com/OthmanAdi/planning-with-files固定提交9b7d0a007946ae7694216642fd5be78c2f13b6db评测类型证据驱动的只读静态工程审阅评测边界本文仅依据固定源码快照进行分析未执行项目代码、测试、依赖扫描或运行时安全验证。作者Valhalla Matrix治理实验室摘要AI 编码代理在处理短任务时通常表现良好但面对跨文件修改、长时间调试、复杂重构和多阶段交付时容易遇到几个共性问题上下文窗口不足中途压缩后丢失任务状态长任务执行顺序不稳定任务重启后无法恢复进度Agent 重复执行已经完成的步骤用户难以了解当前任务处于什么阶段。planning-with-files采用一种相对直接、但具有工程实用性的思路将任务计划、阶段状态、执行记录和相关元数据持久化到 Markdown 或其他文件中让 AI Agent 通过文件系统维护长任务状态。基于固定提交的静态证据本项目包含274 个受支持源文件181 个 Shell 文件85 个 Python 文件8 个 TypeScript 文件18 个 Skill 条目17 个一级目录或模块入口52 个测试文件线索3 个 CI 工作流线索47 条静态风险命中。从工程结构看它不是一个大型运行时平台而是一个围绕“文件化规划、状态恢复和多 Agent 平台适配”构建的专项工具。项目的优点是目标聚焦、实现路径清晰、测试文件较多主要挑战则集中在 Shell 脚本复杂度、路径边界、跨平台兼容性、Hook 行为一致性和状态文件的可靠性上。核心结论planning-with-files具备较明确的工程价值适合用于验证 AI 长任务的计划持久化和断点恢复方法。但在实际使用前应重点验证路径隔离、脚本参数处理、Hook 生命周期、并发访问和异常恢复行为。一、项目解决了什么问题1. AI 长任务为什么容易失控一个典型的 AI 编码任务可能包含以下步骤理解需求 ↓ 扫描项目 ↓ 制定方案 ↓ 修改多个文件 ↓ 执行测试 ↓ 修复失败 ↓ 重新验证 ↓ 整理交付结果如果这些状态只存在于模型上下文中就会面临几个问题上下文被压缩后早期计划可能丢失Agent 重启后不知道之前完成了哪些工作长任务中途失败时无法准确恢复多轮执行后计划、实际修改和测试结果可能不一致用户无法快速判断当前任务进展。planning-with-files的基本思路是将这些信息写入项目目录中的持久化文件任务计划文件 执行状态文件 阶段记录文件 检查结果 恢复信息于是Agent 的任务状态从仅存在于上下文变成上下文 文件系统中的持久化状态这是一种“外部化任务记忆”的工程实践。二、静态资产概览2.1 源码规模本次扫描识别出 274 个受支持源文件语言文件数量可能承担的职责Shell181Hook、安装、状态管理、文件操作和自动化流程Python85测试、辅助逻辑和验证脚本TypeScript8特定 Agent 平台或扩展入口合计274Shell 文件占比约为三分之二。这与项目的设计目标相符因为文件化规划通常需要完成创建任务目录初始化计划文件解析任务状态检查阶段完成情况写入或读取 Markdown安装 Hook适配不同 Agent 平台计算文件摘要调用外部命令。不过Shell 占比较高也意味着项目的稳定性高度依赖Shell 解释器差异命令行工具可用性环境变量路径格式文件编码子进程退出码错误处理方式。2.2 Skill 表面项目识别出 18 个SKILL.md或技能条目并分布在多个 Agent 平台适配目录中包括.agents .codebuddy .codex .continue .cursor .factory .gemini .hermes .kiro .mastracode .opencode .pi这说明项目并非只服务于一个固定客户端而是尝试将同一套规划方法适配到多个 Agent 工具或开发环境。多平台适配的价值在于降低重复配置成本保持规划方法的一致性便于不同团队采用能够根据平台提供相应 Hook 和扩展入口。与此同时也需要确认不同平台的行为是否一致计划文件是否写入相同位置当前任务状态是否使用同一格式Hook 是否全部安装成功中断和恢复事件是否等价路径解析是否存在平台差异某些平台是否会绕过计划检查。三、核心架构文件化规划与状态恢复根据源码目录和抽样文件可以将项目的工作流程抽象为以下结构否是否是用户任务初始化任务会话生成计划文件拆分阶段与步骤执行当前阶段写入执行记录阶段是否完成进入下一阶段任务是否完成生成完成报告任务中断或上下文压缩读取计划与状态3.1 初始化阶段init-session.sh是重要的静态阅读入口。报告提取到的函数包括slugify short_uuid gen_nonce apply_v3_mode write_default_task_plan从命名可以推断初始化阶段可能涉及将任务名称转换为安全标识生成短 ID生成随机标记应用不同版本的规划模式写入默认任务计划。需要重点验证任务名称是否可能影响路径生成的目录是否存在冲突随机 ID 是否仅用于标识还是承担安全认证作用初始化失败时是否留下半成品文件重复初始化是否会覆盖既有计划计划文件是否使用安全的原子写入方式。3.2 计划注入阶段inject-plan.sh是抽样文件中结构最复杂的入口之一报告提取到的函数包括slug_is_valid norm_slashes canonicalize is_within_root smart_plan_extract这些函数名显示出项目对路径规范化和工作区边界有所关注。其中is_within_root这类逻辑尤其重要。文件化规划系统需要避免出现以下问题计划根目录 ↓ 用户输入路径 ↓ 路径穿越 ↓ 访问计划目录之外的文件理想的路径处理过程应包括统一路径分隔符处理相对路径规范化.和..解析符号链接获取真实路径检查是否仍位于允许根目录内再执行文件读写。仅依赖字符串前缀判断并不足够。例如以下判断可能存在边界问题[[$target$root*]]因为同名前缀目录、符号链接和未规范化路径都可能造成误判。3.3 完成检查阶段check-complete.sh中出现了advisory_report ledger_line_count json_escape first_in_progress_phase这表明项目可能通过计划文件和日志记录判断当前任务是否完成是否还有进行中的阶段记录条数是否符合预期输出是否需要 JSON 转义是否需要生成提醒或报告。这里有一个重要的工程问题“计划上标记为完成”是否等于“实际工作已经完成”例如Agent 可能在修改文件后直接更新状态却没有成功执行测试。因此完成检查最好同时验证计划状态 实际文件变更 测试结果 必需产物 未完成事项否则状态文件可能成为“看起来已完成”的来源而不是实际执行结果的可信证明。3.4 停止门控阶段gate-stop.sh可能承担停止前检查或任务结束门控职责。这类机制通常用于防止 Agent 在以下情况下过早结束仍有未完成阶段存在未处理错误测试尚未执行计划文件未更新还有未提交的任务结果需要用户确认的操作没有完成。但停止门控不能仅依赖自然语言状态。建议将其设计为结构化条件例如completion:plan_status:completepending_phases:0required_checks:tests:passedlint:passeduser_approval:not_requiredside_effects:recorded四、项目的主要工程优势4.1 目标聚焦边界相对清晰与同时包含模型服务、前端、数据库和多个运行时的大型 Agent 平台相比planning-with-files的目标比较集中长任务规划 文件化状态 Hook 触发 多平台适配这种聚焦带来的好处是容易理解便于部署适合个人和小团队试用更容易围绕核心流程编写测试能够快速验证“持久化计划是否改善 Agent 执行”。4.2 测试覆盖方向具有针对性报告列出的测试文件包括tests/test_planning_disabled_optout.py tests/test_check_complete_resolver.py tests/test_nested_plan_isolation.py tests/test_v238_command_files.py tests/test_hook_resolver_integration.py tests/test_precompact_hook.py tests/test_resolver_plan_root_pin.py tests/test_hook_body_v240.py tests/test_path_fix.py tests/test_injection_determinism.py tests/test_session_catchup.py tests/test_ledger_utf8.py tests/test_ps1_windows_encoding.py tests/test_cursor_nested_root_isolation.py tests/test_resolver_parity.py tests/test_plan_attestation.py tests/test_codex_nested_root_isolation.py tests/test_stop_hook_dispatch.py tests/test_gate.py tests/test_line_endings.py tests/test_containment.py tests/test_canonical_script_sync.py从测试名称来看项目已经关注了一些实际问题规划功能关闭或退出嵌套目录隔离Hook 集成计划根目录固定注入稳定性会话恢复UTF-8 和 Windows 编码不同平台行为一致停止门控路径包含关系脚本同步。这比只测试“能否创建一个计划文件”更加接近真实工程场景。4.3 存在计划完整性校验思路attest-plan.sh中出现resolve_plan_file attestation_path_for compute_hash从静态命名看项目可能尝试为计划文件建立摘要或证明文件。如果该机制确实用于运行时校验它可以帮助发现计划文件被外部修改Agent 在执行过程中覆盖计划多个任务误用了同一计划恢复时读取了错误版本计划与执行记录不一致。不过文件哈希只能证明内容变化不能证明内容本身可信。它还需要配合哈希生成者身份版本信息任务 ID时间戳文件位置写入权限失败处理回滚机制。五、需要重点关注的风险5.1 Shell 脚本规模较大181 个 Shell 文件构成了本项目最重要的工程风险面。Shell 适合处理文件、Hook 和命令行环境但其复杂度容易被低估。常见风险包括未加引号的变量展开空格和换行导致参数拆分eval或间接命令执行管道中间步骤失败未被发现set -e行为与预期不一致子 Shell 环境变量丢失命令不存在时错误被吞掉Windows PowerShell 与 Unix Shell 行为不一致临时文件权限过宽并发执行造成状态覆盖。建议对生产可达脚本统一检查set-Eeuopipefail并根据实际环境补充参数白名单--参数终止符明确的临时目录trap清理逻辑命令存在性检查退出码传递日志脱敏文件锁超时控制。5.2 静态风险命中大多出现在测试文件报告列出的前 30 条风险样例中大量路径属于tests/例如tests/test_hook_resolver_integration.py tests/test_injection_determinism.py tests/test_plan_attestation.py tests/test_gate.py tests/test_containment.py这会显著影响风险解读。测试文件中出现 Shell 调用通常是合理的因为测试需要调用被测脚本创建临时目录模拟 Hook检查退出码验证跨平台行为构造路径边界场景。因此47 条静态命中不能直接作为生产风险数量。应将命中按以下维度分类分类处理方式测试代码检查测试隔离和夹具安全示例代码确认不会进入生产包安装脚本高优先级复核Hook 实现高优先级复核核心运行脚本最高优先级复核文档片段检查是否会被自动执行第三方或生成文件单独确认来源5.3 计划文件可能遭遇污染文件化规划的优势是持久化风险也在于持久化。如果 Agent 读取项目中的计划文件、日志或历史记录需要防范计划文件被恶意修改外部输入通过计划文件注入指令一个项目的计划被另一个任务读取嵌套项目共享错误的计划根目录计划状态被提前改为完成旧任务状态影响新任务多个 Agent 并发修改同一文件。建议为计划文件增加任务 ID 工作区根目录 创建时间 最后修改时间 当前版本 文件摘要 写入者 状态变更记录并确保恢复时同时检查计划文件 工作区路径 当前任务 ID 执行日志 文件摘要5.4 多平台 Hook 适配容易产生行为差异项目同时支持多个 Agent 或开发平台。不同平台的 Hook 机制可能存在差异触发事件名称不同输入格式不同环境变量不同当前工作目录不同退出码语义不同是否允许修改上下文不同是否支持阻止后续执行不同。因此需要建立跨平台一致性测试矩阵能力平台 A平台 B平台 C平台 D初始化计划通过/失败通过/失败通过/失败通过/失败写入状态通过/失败通过/失败通过/失败通过/失败中断恢复通过/失败通过/失败通过/失败通过/失败停止门控通过/失败通过/失败通过/失败通过/失败嵌套目录隔离通过/失败通过/失败通过/失败通过/失败六、如何评价这份原始评测报告的数据质量这份原始报告的证据组织总体较好但还存在几个需要改进的地方。6.1 做得较好的地方固定提交明确报告提供了完整 Commit SHA9b7d0a007946ae7694216642fd5be78c2f13b6db这使读者能够复核同一版本避免因为仓库持续变化导致结论漂移。对静态证据边界有明确说明报告多次强调未执行代码未执行测试未进行依赖扫描静态命中需要人工复核测试文件存在不等于测试通过。这是比较重要的研究规范能够减少过度解读。风险样例可定位报告给出了具体文件路径而不是只提供抽象风险数量。例如.agents/skills/planning-with-files/scripts/inject-plan.sh .agents/skills/planning-with-files/scripts/init-session.sh tests/test_containment.py tests/test_plan_attestation.py文件级证据便于后续安排人工审阅和验证。测试命名能够反映实际问题从测试名称可以看出项目关注了嵌套根目录、路径修复、Hook、编码、状态恢复和计划完整性等问题。这些方向与项目定位较匹配。6.2 数据解释需要更加克制文件数量不是质量评分274 个源文件和 181 个 Shell 文件只能说明工程规模和语言构成不能单独说明代码质量维护性安全性性能架构先进程度。AST 结构计数不能等同于复杂度报告中的声明 89 分支 408 循环 141 异常路径 32适合作为源码导航指标不应被直接解释为圈复杂度缺陷概率维护成本性能瓶颈。尤其是 Shell 语法经过词法或结构提取后分支计数可能受到命令替换、条件表达式和脚本风格影响。风险命中应区分测试与生产当前风险样例大部分位于tests/目录。报告虽然写明需要人工复核但最好进一步增加生产可达命中 测试专用命中 构建和安装命中 示例命中 文档命中这样更有利于技术负责人判断风险优先级。“模块表面 broad”不等于模块耦合复杂17 个一级模块根表示项目有多个顶层目录但不能直接证明模块职责清晰内部依赖合理组件可以独立部署跨平台实现一致。报告中已经写了“由一级模块根数量推导不评价内部耦合”这一点是正确的建议在文章正文中继续保持。七、建议的验证清单1. 构建验证记录以下信息操作系统和版本Shell 类型和版本Python 版本Node.js 版本包管理器版本官方安装命令官方测试命令构建结果失败日志生成文件和临时文件。2. 功能验证至少覆盖初始化任务创建计划文件读取当前计划更新阶段状态任务中断任务恢复嵌套项目隔离计划完成检查计划文件摘要停止门控关闭规划功能多平台 Hook 行为。3. 安全验证建议测试测试场景预期结果使用../访问计划根目录之外的文件被拒绝使用符号链接绕过目录限制被拒绝任务名包含空格和特殊字符正确处理两个任务同时初始化不互相覆盖两个 Agent 同时写入状态有锁或明确冲突处理计划文件被外部修改能够发现或记录Shell 参数包含特殊字符不产生额外命令中断任务子进程和临时文件被清理Windows 换行和编码结果一致空计划、损坏计划返回可解释错误4. 质量验证补充确认测试实际通过率测试覆盖率跳过测试的原因CI 是否执行所有关键路径发布包是否包含测试和示例脚本不同平台的脚本是否保持同步依赖是否锁定许可证文件是否完整文档描述是否与当前实现一致。八、最终评价planning-with-files是一个目标清晰、工程边界明确的 Agent 辅助项目。它没有试图解决所有模型能力问题而是聚焦于一个非常具体的痛点如何让 AI Agent 在长任务中记住计划、保持进度并在中断后继续工作。从静态证据看项目的优势主要包括文件化规划思路简单易理解具备多平台 Skill 适配设计了计划初始化、注入、检查和停止门控流程测试文件覆盖了多个真实边界场景关注嵌套目录隔离、路径处理、编码和状态恢复存在计划摘要或完整性校验相关逻辑具备基础 CI 自动化。主要风险和挑战包括Shell 文件数量较多复杂控制流集中在关键脚本中路径处理属于高敏感边界多平台 Hook 可能出现行为差异计划文件存在被污染或状态失真的可能静态风险命中需要区分测试代码和实际执行路径当前报告未提供测试通过率、覆盖率和运行时结果。综合来看可以将该项目评价为一个面向 AI 长任务的轻量级持久化规划工具具有较强的实践价值和较清晰的技术方向适合在隔离环境中开展功能、兼容性和安全验证但当前静态证据不足以支持对生产稳定性和安全性的确定性判断。最值得继续验证的不是“计划文件能否生成”而是以下完整闭环任务初始化 → 计划生成 → 阶段执行 → 状态写入 → 测试记录 → 中断恢复 → 完成校验 → 清理和审计如果这条链路能够在不同平台、不同目录结构和异常场景下保持一致planning-with-files才真正具备作为 AI 编码代理长任务辅助组件的工程基础。