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 瓶颈