planning-with-files

核心用法

planning-with-files 是一套模仿 Manus AI 工作流的本地任务规划系统，专为复杂多步骤任务设计。其核心机制是将"易失的上下文窗口"（RAM）转化为"持久化的文件系统"（Disk），通过三个核心 Markdown 文件实现工作状态的全生命周期管理：

• task_plan.md：任务总览与阶段追踪，包含目标、阶段划分、决策记录及错误日志
• findings.md：研究发现与知识沉淀，用于保存搜索、浏览、分析过程中获得的关键信息
• progress.md：会话日志与执行记录，实时跟踪操作历史、测试结果与状态变更

使用时遵循"先规划后执行"原则：任何超过 5 个工具调用的复杂任务，必须先创建规划文件；执行中遵守"2-操作规则"（每两次浏览/搜索后立即保存发现）；决策前重读计划，完成后立即更新状态。系统还支持会话恢复机制，可在 /clear 后自动重建上下文。

显著优点

1. 上下文持久化：彻底解决了大模型上下文窗口有限导致的"失忆"问题，关键信息落盘存储
2. 结构化思维：强制要求任务拆解为阶段，提升复杂项目的可控性与可交付性
3. 错误知识积累：内置错误日志表格与"3-次失败升级"协议，避免重复踩坑
4. 跨会话连续性：通过 session-catchup.py 脚本实现会话中断后的状态恢复
5. 零网络依赖：纯本地文件操作，无隐私泄露风险，适合敏感项目
6. 平台兼容：提供 Windows（PowerShell）与 Unix（Bash）双平台脚本支持

潜在缺点与局限性

1. 手动维护负担：文件更新依赖人工触发，无法自动同步工具执行状态
2. 无协作能力：单用户本地文件模式，不支持团队实时协作
3. 模板学习成本：新用户需理解三种文件的职责边界与更新时机
4. 路径管理风险：缺乏强制性的路径规范化验证，存在误操作可能（见安全报告）
5. 过度规划陷阱：简单任务若强制使用，反而降低效率

适合的目标群体

• AI 辅助开发者：使用 Claude Code 等工具进行多文件项目开发的工程师
• 研究人员：需要长期跟踪文献、实验数据与研究发现的学术工作者
• 产品经理：管理复杂需求拆解与迭代规划的 PM
• 技术写作者：撰写长篇技术文档或教程，需分阶段推进的创作者
• 任何需要>5 步工具调用的复杂任务执行者

使用风险

1. 文件污染风险：若未正确区分"技能目录"与"项目目录"，可能将规划文件误写入技能安装位置
2. 路径遍历隐患：当前版本缺乏严格的 path.resolve()() 验证，恶意构造的文件名理论上可能突破项目边界（实际风险较低）
3. 钩子执行失败：PreToolUse//PostToolUse` 钩子依赖 shell 环境，Windows 环境下 PowerShell 执行策略可能阻止脚本运行
4. 版本兼容：v2.10.0 引入的自动恢复功能依赖 Python 环境，极简容器中可能不可用
5. 性能开销：高频文件读写（每次工具调用触发钩子）在极大规模项目中可能产生 I/O 瓶颈

核心用法

planning-with-files 是一套模仿 Manus Agent 工作模式的文件级任务规划系统，通过创建三个核心 Markdown 文件来持久化管理复杂任务：

1. task_plan.md — 阶段规划、进度追踪、决策记录
2. findings.md — 研究发现、关键信息归档
3. progress.md — 会话日志、执行记录

启动复杂任务前必须创建这三个文件，执行过程中遵循"2-Action Rule"（每两次查看/搜索操作后立即保存发现）、"Read Before Decide"（重大决策前重读计划）、"3-Strike Error Protocol"（三次失败必须升级）等核心规则。

显著优点

• 状态持久化：将易失的上下文窗口内容转存到文件系统，支持跨会话恢复
• 结构化方法论：内置 Manus 验证的规划流程，降低复杂任务失控风险
• 自动Hook集成：PreToolUse/PostToolUse/Stop 钩子自动检查进度、提示更新
• 零依赖：纯原生代码实现（shell + Python标准库），无第三方包风险
• 会话恢复：v2.2.0+ 支持 /clear 后自动恢复上下文，通过 session-catchup.py 读取历史会话

潜在局限

• 适用范围有限：简单问答、单文件编辑等轻量任务无需此模式，强行使用增加 overhead
• 文件污染风险：频繁创建 markdown 文件可能导致项目目录结构杂乱
• Hook 依赖性：核心自动化依赖 hook 配置，若用户禁用 hooks 则失去自动检查能力
• Windows 兼容复杂度：脚本需适配 PowerShell/pwsh/sh 多种执行环境
• 学习曲线：需要理解"RAM vs Disk"类比、掌握 5-Question Reboot Test 等方法论

适合人群

• 处理研究型项目（需要跨多轮对话累积发现）
• 执行构建类任务（代码生成、项目脚手架、多步骤部署）
• 需要严格进度追踪的复杂工作流
• 频繁遭遇上下文截断的长会话用户

常规风险

• 权限申请合理性警告：需 Bash 权限执行辅助脚本，虽当前脚本安全，但存在未来被篡改的理论风险
• 会话文件读取：session-catchup.py 访问 ~/.claude/projects/ 下的 JSONL 会话文件，虽用途正当但涉及用户历史数据
• 维护者账号较新：clawdbot 组织 GitHub 公开信息有限，建议持续观察更新