编程语言AI
Planning with Files：基于文件的 AI 代理规划工作流实践
介绍 Planning with Files 插件，通过 task_plan.md、findings.md、progress.md 三个文件将 AI 代理的任务规划、发现与进度持久化到文件系统，解决长任务中上下文丢失和目标漂移问题。结合 Hooks 机制强制校验状态，支持会话恢复，适用于复杂多步骤的 AI 开发或调研任务。
介绍 Planning with Files 插件，通过 task_plan.md、findings.md、progress.md 三个文件将 AI 代理的任务规划、发现与进度持久化到文件系统，解决长任务中上下文丢失和目标漂移问题。结合 Hooks 机制强制校验状态，支持会话恢复，适用于复杂多步骤的 AI 开发或调研任务。
简介：一个将任务规划、进度与知识落地的 Markdown 文件工作流插件，支持 Claude Code、Cursor、Gemini CLI 等。
核心价值：解决 AI 在长任务中上下文漂移、记忆丢失的问题，通过持久化文件实现可追溯的过程记录。
在使用 AI 处理复杂任务（如写文章、做调研、改项目）时，常出现前 10 分钟顺畅，随后因上下文重置或工具调用过多导致 AI'遗忘'目标、重复失败的情况。planning-with-files 不依赖更长的 Prompt，而是将重要信息从临时上下文迁移到文件系统，形成持久的工作记忆。
AI 代理的上下文类似 RAM（有限、易失），而文件系统类似 Disk（持久、容量大）。常见痛点包括：
| 痛点 | 典型表现 | 后果 |
|---|---|---|
| 易失记忆 | 上下文重置后计划和结论丢失 | 返工、重复问答 |
| 目标漂移 | 工具调用多了开始偏题 | 交付不符合目标 |
| 错误不留痕 | 失败未记录，下次重踩坑 | 效率降低 |
| 上下文塞爆 | 资料堆在对话里未写入文件 | 不可追溯 |
解决之道在于将工作流改为'可持久化'。
该模式维护三个核心文件：
task_plan.md → 任务分阶段与状态（计划与对齐）
findings.md → 研究发现与关键决策（知识沉淀）
progress.md → 会话日志、操作记录、测试结果（过程可追溯）
Hooks 负责在关键时点读取/提醒，脚本负责初始化与校验，Session Recovery 负责在 /clear 后补全遗漏信息。
这是一种偏工程实现的 上下文工程（Context Engineering） 方案。通过将上下文从'聊天记录'迁移到'文件系统'，实现：
task_plan.md/findings.md/progress.md 为最新事实依据。项目在 skills/planning-with-files/reference.md 中总结了 Manus 的 6 条原则，本项目将其转化为可操作的工具：
| 原则 | 原文要点 | 本项目落地 |
|---|---|---|
| Design Around KV-Cache | Keep prompt prefixes STABLE | 稳定流程与文件结构 |
| Mask, Don't Remove | Don't dynamically remove tools | allowed-tools 白名单 |
| Filesystem as External Memory | Markdown is working memory | 三文件外部化记忆 |
| Manipulate Attention Through Recitation | Re-read task_plan.md before decision | PreToolUse 回显计划 |
| Keep the Wrong Stuff In | Leave wrong turns in context | 记录 Errors 不静默重试 |
| Don't Get Few-Shotted | Uniformity breeds fragility | 适度引入变化避免循环 |
经验总结：
task_plan.md。每进行两次查看/搜索操作，必须立刻将关键发现写进 findings.md。零散片段若不进入文本文件，会在上下文压缩后消失。
claude plugins install OthmanAdi/planning-with-files
安装后可用命令：
/plan (v2.11.0+)：规划命令/planning：开始会话与规划流程task_plan.md / findings.md / progress.md。task_plan.md 写清 Goal，拆 3–7 个 phases。findings.md（2-Action Rule）。check-complete.sh 确认 phases 全部 complete。每次开始长任务前，建议跑一次 session-catchup.py，确认上一次会话是否有未写入三文件的关键信息。
${CLAUDE_PLUGIN_ROOT}/templates/）。/clear 之后不断档当上下文满需 /clear 时，session-catchup.py 机制如下：
~/.claude/projects/<sanitized-project>/ 下的历史会话文件。Write/Edit 工具调用，定位三文件最后更新时间。操作顺序：
session-catchup.py 看报告，补全缺失信息。git diff --stat 确认真实改动，写入 progress.md。| 不建议用 | 原因 | 替代 |
|---|---|---|
| 一句话问答/单文件小改 | 创建成本高于收益 | 直接问/直接改 |
| 不打算落盘任何过程 | 失去意义 | 至少写 task_plan.md |
| 团队不需要可追溯 | 复盘成本回收难 | 只保留关键 decisions |
预计超过 5 次工具调用或跨多会话的任务通常适用。
仓库示例展示了 Todo App 开发过程，体现三文件如何协同：
## Current Phase
Phase 1
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Document findings in findings.md
- **Status:** in_progress
## Research Findings
- Python's `argparse` module is perfect for CLI subcommands
- `json` module handles file persistence easily
错误需双写入：
task_plan.md 的 Errors Encountered：避免复现。progress.md 的 Error Log：便于追溯。每个 Loop 包含：
task_plan.md（对齐目标）真正起作用的是 SKILL.md 中的行为约束，通过 hooks 和脚本将流程变为可重复机制。
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning...
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks: ...
---
YAML 格式提供机器可读的配置，明确身份、能力边界和触发机制。
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
每次关键动作前输出 task_plan.md 前 30 行，强制将 Goal/当前阶段塞回注意力窗口。
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated...'
写入文件后提醒更新 phase 状态，防止遗忘。
调用 check-complete.sh 脚本，验证所有 phases 是否均为 complete，将主观完成感变为可验证规则。
利用 scripts/session-catchup.py 生成 catchup 报告，将丢失的状态同步回三文件。
/plan。task_plan.md 写 Goal，拆 3 个 phase。findings.md。progress.md。check-complete.sh 直到 phases 全部 complete。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online