1. 为什么 /clear 之后 AI 就“失忆”了
如果你用 Claude Code、Cursor、Codex 这类 AI 编程助手跑过一个稍微大点的活，大概率经历过这个场景：任务拆了七八步，代码改到一半，上下文窗口告警，你不得不敲下/clear。新会话第一句话，它礼貌地问你：“请告诉我你的任务是什么，我们进行到哪了？”
这不是模型笨，而是它的“待办清单”本来就活在上下文窗口里。上下文窗口相当于内存（RAM），易失、有限、一压缩就丢；而磁盘是持久、近乎无限的。planning-with-files 这个 2.6 万星的 Skill 做的事情非常朴素：把任务计划、调研笔记、会话日志写进项目根目录的三个 Markdown 文件，再用每轮对话都会触发的 Hook 把它们重新灌回上下文。上下文窗口会死，计划不会。
它适合谁？经常让 AI 跑长任务、跨多个会话协作的人——重构、加整套功能、跨文件迁移，一做就是几十上百轮。如果你只做三五轮小修小补，装它反而增加摩擦。它不适合谁？宿主不支持 Hook、又懒得折腾配置的人，因为拿不到 Hook，它就退化成一份“模型不一定看”的计划模板。
我试过在同一个项目里连续跑三个会话，中途/clear两次，靠的就是这套“硬盘即记忆”的工作流。下面把落地配置、Hook 片段、目录结构和验证动作完整拆开，顺带说明怎么用 TaoToken 统一 Key 通道接入模型，省得每个工具都去配一遍 Key。
2. TaoToken 前置：统一 Key 通道接入模型
planning-with-files 本身不碰模型，它只是把状态落到磁盘。真正调用模型的是 Claude Code、Codex、Cursor 这些宿主。问题在于，这些工具各自有各自的 Key 配置方式，换一个工具就要重新配一遍，团队里几个人共用环境时更乱。TaoToken 在这里的角色是统一 Key 通道：一个 Key，多个工具复用，Base URL 指向https://taotoken.net/api。
先拿 Key。打开官网https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册后在控制台创建 API Key。控制台地址是https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite，API Keys 管理页在https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite。拿到形如sk-xxxx的 Key 之后，先别急着往各个工具里塞，先确认模型 ID 和接入文档。
模型对话可以在https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite里先试一句，确认 Key 有效、模型能回。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有各工具的 Base URL 和参数说明。如果你打算长期跑编码任务或者 Agent 循环，Coding Plan 在https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite，比按量计费更适合高频调用。
这里要强调一个原则：planning-with-files 负责“记忆”，TaoToken 负责“通道”，两者职责不重叠。你不需要为了用这个 Skill 去改模型，也不需要为了统一 Key 去动 Skill 的文件结构。配置的时候把 Base URL、Key、Model ID 三件套写全，缺一个都会在验证请求时报错。
3. 可复制配置：Hook 片段与目录结构
这一节是全文最核心的部分，所有片段都可以直接复制。先看目录结构。planning-with-files 要求智能体在项目根目录建且只建三个 Markdown：
your-project/ ├── task_plan.md # 阶段 + 复选框，记录进度；/clear 后的恢复点 ├── findings.md # 调研笔记和关键决策，边做边追加 └── progress.md # 会话日志和测试结果三个文件分工清楚：task_plan.md是项目甘特图加待办，把任务拆成 Phase，每个阶段带可勾选复选框，标注in_progress/complete；findings.md是技术决策日志，沉淀“为什么这么决定”“查到的坑”；progress.md是工作日志，记录每个会话干了什么、跑了什么测试。计划文件默认被.gitignore忽略，是纯本地工作状态，不会污染代码仓库。多任务并行时用隔离目录.planning/YYYY-MM-DD-slug/，再用一个.active_plan文件指定当前激活哪个计划。
接下来是 Hook 配置。Claude Code 用户最推荐走插件路线，因为只有插件路线才自带 Hook 和斜杠命令，而 Hook 正是这个项目的灵魂。在 Claude Code 输入框里敲：
/plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-files@planning-with-files装完输入/plan触发，或者直接说“帮我规划这个任务”，它对多步骤任务也会自动触发。装完务必用/plan-doctor验证 Hook 真的在跑。
如果你用的是遵循 Agent Skills 标准的工具（Codex、Cursor、Gemini CLI 等 60+ 工具），可以用一行命令：
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g这条会装到~/.agents/skills/。但要注意：这条路线的 Hook 依赖 frontmatter，项目级安装时可能因为“目录未被信任”而静默失效。Hook 对你很重要的话，优先用各工具的原生插件方式。中文用户可以用本地化版本：
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g有一个细节值得点赞：状态标记（如**Status:** complete）故意保留英文不翻译，因为完成门的check-complete.sh是用grep -F精确匹配这些词的，翻译了门就失效。
对于需要自己接 Hook 的工具，配置片段长这样（以 settings 为例，路径与原文一致）：
{ "hooks": { "SessionStart": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash ~/.claude/plugins/cache/planning-with-files/planning-with-files/scripts/session-start.sh" } ] } ], "UserPromptSubmit": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash ~/.claude/plugins/cache/planning-with-files/planning-with-files/scripts/inject-plan.sh" } ] } ], "PreCompact": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash ~/.claude/plugins/cache/planning-with-files/planning-with-files/scripts/pre-compact.sh" } ] } ] } }Codex 用户如果走auth.json路线，把 Base URL、Key、Model ID 三件套写全：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "你的ModelID" }Cline MCP 或 CC Switch 的场景同理，Base URL 填https://taotoken.net/api，Key 填控制台生成的，Model ID 按接入文档里的写。三件套缺一不可，尤其是 Model ID，写错了会在验证请求时直接报reading choices之类的解析错误。
4. 验证请求：一次 /clear 前后的完整动作
配置写完不算完，得验证 Hook 真的在工作。这一节给一套可复制的验证动作，从/plan到/clear再到恢复，全程可跟做。
第一步，触发规划。在项目里输入/plan，或者直接说“帮我规划这个任务：给订单服务加一套过期券核销逻辑 + 测试”。它会在项目根目录生成三个 Markdown。打开task_plan.md，你应该看到类似这样的结构：
# Task Plan ## Phase 1: 调研现有券逻辑 - [x] 阅读 coupon_service.py - [x] 确认过期判断入口 **Status:** complete ## Phase 2: 实现核销逻辑 - [ ] 编写 expire_check 函数 - [ ] 接入订单流程 **Status:** in_progress ## Phase 3: 补测试 - [ ] 边界用例 - [ ] 集成测试 **Status:** pending第二步，让它开干。每轮你发消息，UserPromptSubmitHook 都会把计划的“当前目标 + 下一步 + 活跃阶段”重新注入上下文。README 里管这个注入块叫===BEGIN PLAN DATA===，是真实格式。你可以观察它是否始终记得当前阶段，而不是跑偏到无关文件。
第三步，制造一次失败。故意让某个测试挂掉，看它是否把失败原因写进findings.md或progress.md。这一步是验证“错误持久化”有没有生效——同一个坑不会因为上下文被压缩而重踩。
第四步，/clear。这是关键动作。清空会话后，新开会话，SessionStartHook 会自动把当前计划读进来。你输入continue，它应该直接接着当前阶段干，而不是问你“任务是什么”。如果它问你任务是什么，说明 Hook 没生效，去跑/plan-doctor。
第五步，验证完成门。开启 gated 模式后，只要task_plan.md里还存在in_progress的阶段，智能体想结束回合都会被拦住。你可以故意让它“交差”，看它是否被按住。门里带了阻断次数上限和停滞检测，万一计划本身卡死，不会把你锁在永远出不来的会话里。
第六步，验证防篡改。批准过的计划会算一个 SHA-256 哈希，如果计划正文被悄悄改写，注入时直接拒绝并报[PLAN TAMPERED]。你可以手动改一下task_plan.md的正文，看下一次注入是否报警。
关于模型通道的验证，可以在https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite里发一句测试，确认 Key 和 Model ID 都对。如果宿主里报401，先查 Key；报local proxy failed，查 Base URL 是否写成了https://taotoken.net/api；报reading choices，查 Model ID 是否和接入文档一致。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
配置过程中最容易踩的坑集中在几个报错上，逐个对照排查。
401 Unauthorized：Key 无效或没带上。检查auth.json或 settings 里的api_key字段是否填了完整的sk-xxxx，有没有多余空格。如果用的是环境变量，确认变量名和工具要求的一致。TaoToken 的 Key 在 API Keys 页生成，生成后只显示一次，丢了就重新建一个。
local proxy failed：Base URL 写错了。正确写法是https://taotoken.net/api，注意不要加 UTM 参数，也不要写成首页地址。有些工具会在 Base URL 后面自动拼/v1，如果你的工具这么做，确认最终请求路径是https://taotoken.net/api/v1/...。如果工具不支持自动拼接，就在 Base URL 里写全。
reading choices或cannot read property choices：模型返回格式和工具预期不匹配，通常是 Model ID 写错了。去接入文档https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite核对当前可用的 Model ID，别用记忆里的旧名字。三件套里 Model ID 是最容易写错的一个。
OAuth相关报错：有些工具默认走 OAuth 登录，不走 API Key。如果你要用 TaoToken 统一 Key，需要在工具设置里切换到 API Key 模式，关掉 OAuth。Claude Code 的插件路线一般不受影响，但 Codex 和部分 IDE 插件需要手动切。
Hook 静默失效：这是 planning-with-files 最常见的坑。表现是/clear之后它还是问你任务是什么。原因通常是项目信任没开、frontmatter hook 没注册，或者纯 Skill 安装拿不到 Hook。跑/plan-doctor，它会逐项检查解析、注入、哈希、安装面和每次触发的延迟，告诉你 Hook 到底有没有在工作。实测下来，/plan-doctor是装完必跑的一条命令。
并行写保护触发：你开了两个会话同时改一个计划，一个把勾选项勾上、另一个基于旧版本又存回去，勾选就丢了。并行写保护会检测“已勾选项或已完成阶段在两轮之间倒退”并提醒你。遇到提醒时，关掉一个会话，或者用.active_plan明确当前激活的计划。
6. 长期编码与 Agent 场景的接入建议
如果你只是偶尔跑长任务，插件路线加/plan-doctor就够了。但如果你经常让 AI 一连跑一两个小时、横跨多个会话，甚至跑无人值守的自主循环，那值得把通道也统一掉。TaoToken 的 Coding Plan 在https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite，适合高频调用的编码和 Agent 场景，比每次单独配 Key 省事。
回到 planning-with-files 本身，它最值得学的不是那三个文件，而是两个认知：状态要落到模型之外的确定性介质上，关键约束要用 Hook 强制、而不是靠提示词央求。v3 加的完成门、SHA-256 防篡改、并行写保护，都是冲“长时间无人值守”去的。作者自己的评测数据是断言通过率 96.7%（29/30），配套 706 个测试，盲测 A/B 三战三胜，内部恢复基准显示有计划文件的新会话平均 5.0 轮恢复状态，裸智能体要 13.3 轮。这些是作者自己跑的内部基准，不是第三方独立评测，而且作者注明 5.0 vs 13.3 用的是早期默认的“回放会话记录”模式，现在的默认自动恢复只读项目文件，所以那个数字是历史证据。能这么自曝其短的项目，反而更值得信任。
最后给一个实用技巧：装完先跑/plan-doctor，确认 Hook 在跑，再去跑长任务。Hook 是“悄悄失效”的重灾区，别等到/clear之后才发现它没工作。项目地址在https://github.com/OthmanAdi/planning-with-files，MIT 协议，60+ 智能体通用，还有完整中文版。经常跑长任务的人，装上试试。
