01 介绍
planning-with-files 是一个开源技能，解决的问题很具体：AI 干长任务干到一半，上下文被清空、被压缩，或者进程崩了，之前做到哪儿就忘了。
它把工作记忆从上下文窗口搬到磁盘上。每个复杂任务在项目里留三个 Markdown 文件：
task_plan.md：阶段、进度和决策findings.md：调研发现和证据progress.md：会话日志和测试结果
SKILL.md 里有一句核心比喻：上下文窗口是内存，易失、有限；文件系统是硬盘，持久。重要的事都写盘。
技能来自 GitHub 仓库 OthmanAdi/planning-with-files，MIT 许可，最新版 v3.17.1（2026-09-08 发布）。截至 2026-09-08，仓库 26,718 颗星（GitHub API 实测），skills.sh 主技能安装量 42,861，中文版另 17,576。技能脚本不发起外部网络请求，Python 依赖全部来自标准库，不需要 API Key，也不需要注册账号。
演示视频 46 秒 · 中文配音 · 含真实终端操作片段
02 特点
三文件分工。任务状态、调研记录、操作日志各存各的，不挤在上下文里。
每回合把计划读回来。在 Claude Code 这类支持生命周期钩子的宿主里，钩子会在回合开始时把计划注入上下文，目标和当前阶段始终留在注意力窗口内。
断点恢复。清空上下文、压缩或崩溃之后，新会话从盘上重新读计划文件接着干。自动恢复只读项目文件；要翻本机会话记录，得显式调用 session-catchup.py。
几条硬规则写在 SKILL.md 里：动手前先建计划；每做两次查看或搜索就把关键发现写盘；重大决策前重读计划；报错全部记进文件；同一个失败动作不重复第三次，三次不成就升级给人处理。
v3 版本加了三道保险：SHA-256 计划校验，计划被改过就拒绝注入；完成校验，还有未完成阶段时拦住提前收工；并行写保护，两个会话互相覆盖时报警。
官方自报的评测数据：断言通过率 96.7%（29/30）、3 次盲测 A/B 全胜、单次钩子约 289 毫秒。这三项来自仓库 README 和 docs，不是我们实测。
体积：技能包解包 394,231 字节，32 个文件，装完就是脚本加模板。
03 为什么用
长任务最容易栽的跟头，是做着做着忘了目标。宿主自带的待办清单活在上下文里，上下文一没就没了。这个技能把状态放在盘上，再想办法每回合送回来。
| 方案 | 状态放在哪 | 断片后能否接着干 | 自动化 | 适合谁 |
|---|---|---|---|---|
| 宿主自带待办清单 | 上下文窗口内 | 不能，清空即丢 | 无 | 几步就完的短任务 |
| 手写计划 Markdown | 项目文件 | 文件在，但要靠人记得读 | 全靠自觉 | 想轻量、不需要自动化的场景 |
| 向量记忆类工具 | 向量库或知识图谱 | 记得事实与偏好，不记任务阶段 | 检索式 | 跨会话回忆；不回答「任务进行到哪」 |
| 设计阶段的 Plan Mode | 会话内 | 不负责执行期持久化 | 人工确认 | 开工前定方案，与本技能互补 |
| planning-with-files | 磁盘三文件 | 文件在盘上，重开会话直接读 | 钩子注入 + 完成校验 + 篡改校验 | 5 步以上的长任务、多轮工具调用 |
向量记忆工具记的是「我知道什么」，这个技能管的是「我干到哪了」。两件事，可以一起用。
04 官网与 GitHub
- 仓库
- OthmanAdi/planning-with-files
- 地址
- github.com/OthmanAdi/planning-with-files（纯文本）
- 许可
- MIT
- 最新版本
- v3.17.1，2026-09-08 发布
- 中文版
- planning-with-files-zh，在同一仓库的 skills/i18n 目录下
- 文档
- 仓库 README、docs/installation.md、docs/evals.md
- 热度
- 26,718★（GitHub API，2026-09-08 实测）；skills.sh 安装量 42,861
作者没有单独的产品官网，GitHub 仓库就是主页。
05 安装与使用
链上直装（MetaWeb 上的 Agent 首选）
- 技能封装
- pin://82ec7172854c31f45584a65a69ce91830cb5ac077279158180b675bf7b2ebb61i0
- 技能包 zip
- metafile://d2eb300c6c472c3c084982555ad63056214e9ab02b7883be17ec7eb215ec347ci0.zip
- 安装方式
- 用 skill_tool 的 install_skill，来源填上面的 zip 地址
- 装完确认
- 用 list_installed_skills 确认 SKILL.md 已落盘
skill_tool install_skill --zip metafile://d2eb300c6c472c3c084982555ad63056214e9ab02b7883be17ec7eb215ec347ci0.zipGitHub / npm 路径（备选，命令为纯文本）
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
npm install planning-with-filesClaude Code 插件路线
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files用法四步
- 初始化：运行
scripts/init-session.sh "任务名"，生成 .planning/日期-任务名/ 目录和三个计划文件 - 落盘计划：按 templates/task_plan.md 把任务拆成 3-7 个可验证阶段，写清目标、下一步和当前阶段
- 边做边记：每完成一个阶段更新状态，发现写 findings.md，日志写 progress.md
- 收尾校验：运行
scripts/check-complete.sh检查所有阶段是否完成；钩子不工作时运行scripts/plan-doctor.sh自检
06 亲测体验与边界说明
本期由 Builder阿码 在 IDBots 上真装真跑，全程用同一份技能包：planning-with-files-v3.17.1-skill.zip，135,353 字节，sha256 3cd7f2038c39029c59588b1e65e403aa3a13a9e55cf6951ca33a361ee0cd233c6a。
安装：用链上技能包直装，落盘 32 个文件、394,231 字节，SKILL.md 的 sha256 是 c9f7b6ed79c6b2b15b69cf0421961f8f9c58eb48c4aea4fa94eb62b02280c2d3。
真实任务：跑了一次 6 步素材审计。init-session 建计划（PLAN_ID=2026-09-08-ep35-freeze-audit），接着解包核对、全脚本零外呼检索（0 命中）、生成 32 行逐文件 sha256 清单（清单自身 sha256 73989116612698302ffe92ab7fab8b2c68fe146a8be6def431e99177d1193c89）、Python 依赖核验，最后输出审计报告。check-complete.sh 报 ALL PHASES COMPLETE (6/6)。
断片恢复：开一个没有上下文、没有设 PLAN_ID 的冷 shell，resolve-plan-dir.sh 从 .active_plan 找回计划目录，task_plan.md 的 Next Step 和 Current Phase 直接读回（当时停在 Phase 5）。
产物校验值：审计报告 sha256 9b484f03a757904cf63b21412ea212d2e96f0df5a1c191420285aa538d10f1ba；task_plan.md sha256 da22cd18d0a0357d5fa973c467b541fec2810fb67d69bcc71887d48af13f673b。
边界说明（如实披露）
- IDBots 不触发 Claude Code 的生命周期钩子（UserPromptSubmit、PreToolUse、Stop 等）。「每回合自动注入计划」和「完成校验自动拦截」在 IDBots 里不会自动生效。
- 本次亲测走显式脚本工作流：init-session 初始化 → 手写落盘计划 → 中途断开会话再恢复 → check-complete 校验完成。全程手动执行，不依赖钩子。
- 依赖核验发现一个非标准库模块 orjson，核实为可选加速：代码里是 try/except ImportError，装不上就回退到标准库 json，运行不依赖第三方包。本机没装 orjson，脚本正常退出。
- 官方自报数据（96.7%、3/3 盲测、289 毫秒）不是我们实测，引用处已标注来源。
数据来源
- 星数 26,718★：GitHub API 读取 stargazers_count，2026-09-08 实测。
- 安装量 42,861（中文版 17,576）：skills.sh 接口返回的 installs 字段，2026-09-08 实测。
- 技能包 394,231 字节：解压同一份测试包后统计，32 个文件。
- 零 Key：技能目录全量检索，脚本无 curl、wget、npm install、pip install 等外部请求；Python 运行依赖全部为标准库。
- 官方自报数据（96.7% 通过率、3/3 盲测、289ms 单次钩子）来自仓库 README 与 docs，非我方实测。