wehub/othmanadi--planning-with-files

Fork 0

Files

T

wehub-resource-sync e3eac057bf docs: make Chinese README the default

2026-07-13 10:40:49 +00:00

42 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Planning with Files

📣 v3.0.0: 新增**：为长时间运行的 agent 提供可选的自主模式与门控模式，并配有完成门控，在计划真正完成前会拦住 agent。现有配置无需任何改动。

像 Manus 一样工作 — 这家 AI agent 公司已被 Meta 以 20 亿美元 收购。

planning-with-files 是面向 AI coding agents 的持久化、基于文件的规划 skill。它将 task_plan.md、findings.md 和 progress.md 保存在磁盘上，使 agent 能够在 上下文丢失、/clear 和崩溃后继续工作，并提供可选的完成门控，在计划真正完成前会拦住 agent。通过 SKILL.md 标准可安装到 60+ 个 agent 上。

💬 作者的话

感谢每一位 star、fork 并分享这个 skill 的人。这个项目在不到 24 小时内就火了，社区的支持令人难以置信。

如果这个 skill 能帮你更高效地工作，那就是我想要的全部。

🌍 社区已交付成果

分支与扩展

分支	作者	他们做了什么
devis	@st01cs	访谈优先工作流、`/devis:intv` 与 `/devis:impl` 命令、保证激活
multi-manus-planning	@kmichels	多项目支持、SessionStart git 同步
plan-cascade	@Taoidle	多级任务编排、并行执行、多智能体协作
agentfund-skill	@RioTheGreat-ai	面向 AI agents 的众筹，基于 Base 上的里程碑托管
openclaw-github-repo-commander	@wd041216-bit	面向 OpenClaw 的 7 阶段 GitHub 仓库审计、优化与清理工作流

实际应用

项目	是什么
lincolnwan/Planning-with-files-copilot-agent	整个 Copilot agent 仓库围绕 planning-with-files skill 构建
cooragent/ClarityFinance	AI 金融 agent 框架 — 直接致谢 Planning-with-Files 方法
oeftimie/vv-claude-harness	基于 Manus 风格持久化 markdown 规划的 Claude Code harness
jessepwj/CCteam-creator	使用基于文件规划的多智能体团队编排 skill

Skill 注册表与中心

注册表	是什么
buzhangsan/skill-manager	双语（EN/中文）skill 中心，索引 31,000+ Claude Code skills — planning-with-files 可一键安装。

做了什么？提个 issue 即可上榜！

🤝 贡献者

完整贡献者名单见 CONTRIBUTORS.md。

📦 版本发布与会话恢复

当前版本：v3.4.1

版本	亮点
v3.4.1	Codex hooks 现可在 Windows 上运行（closes #201，由 @mahdiit 报告）。 `.codex/hooks.json` 命令此前仅为 POSIX，因此在 Windows 上原生命令解释器会卡在 `python3`（Store 别名）、`2>/dev/null`，以及 `\|\| true` 成功守卫（其 `true` 不是 Windows 命令）上，导致每个 hook 都报告 `hook exited with code 1`。每个 hook 现带有按 hook 的 `commandWindows` 覆盖（POSIX 的 `command` 保持不动，因此 macOS 与 Linux 不变），经新的 `pwf-hook.cmd` 启动器路由（通过 `py -3` 使用真正的 Python，回退到 `python`，绝不用 Store 的 `python3` 别名）；对三个 shell hooks，还有新的 `run_sh.py` 入口。`codex_hook_adapter` 通过锚定 `git.exe` 解析 Git for Windows 的 `sh.exe`，因此即使 Git 的 `usr\bin` 不在 PATH 上，shell 脚本也能运行。Codex hook 套件全绿（17 个测试），并新增跨平台与仅 Windows 覆盖。
v3.4.0	`PLANNING_DISABLED=1` 按次调用的一次性会话退出开关（closes #195，由 @marcmuon 报告）。一次性的 `codex exec` 运行（CI 评审机器人、只读研究 agents、嵌套编排器）若仅与未完成计划共享 cwd，会被劫持：注入计划上下文、将实际输出重定向到 `progress.md`、向 `task_plan.md` 追加伪造的已完成阶段。所有 Codex hook 入口、Python 适配器路由以及规范调度器（`inject-plan.sh`、`gate-stop.sh`、`check-complete.sh`/`.ps1`）在设置 `PLANNING_DISABLED=1` 时，现在会在读取计划前退出；PreToolUse 仍发出 allow 决策，使工具调用可继续。该守卫随每个分发副本提供，包括五个语言变体。还修正了 `docs/codex.md` 中关于 Stop hook 会阻塞的过时说法（自 v3.1.0 起已不阻塞）。套件 200 通过。
v3.3.0	Pi 扩展 hooks 现通过 `/plan-execute` 等待用户明确批准（PR #193 by @Dikshj，closes #190，由 @lazyst 请求）。Pi 扩展此前只要存在 `task_plan.md` 就会激活全部 hooks，因此在用户仍在审阅草稿计划时，计划注入、工具前复述、写入后提醒与自动继续就可能开始。扩展现保持被动并显示状态行，直到用 `/plan-execute` 批准当前活动计划；批准范围限定于当前会话与计划路径，在会话生命周期事件上重置，且 `/plan-execute reset` 会回到被动审阅。带有被篡改 SHA-256 证明的计划无法批准。套件 188 通过，外加 21 个 Pi 扩展 vitest 测试。
v3.2.0	仓库健康审计：session-catchup.py 在 Windows 上不可用，以及「0/0 phases」误报状态（closes #191，addresses #103，closes #188）。 `session-catchup.py`（「在 `/clear` 后恢复」背后的机制）从未正确清理 Windows 风格路径，且三次读取没有显式编码，因此在 Windows 上静默无作为且不报错。`inject-plan.sh` 的包含守卫在 8.3 短名或 `/tmp` 别名路径下也会静默丢弃计划注入与篡改检测。两处均已修复。另外，`check-complete.sh`/`.ps1` 与三个 IDE 专用 Stop hooks 对任何没有 `### Phase` 标题的 `task_plan.md` 误报「0/0 phases complete」（#191，由 @mixian939 报告）；凡出现该模式处均已修复，包括规范脚本。`--template analytics` 标志（v2.29.0）在每个已安装 skill 包中都静默回退到默认模板；分析模板现真正随包发布到 `init-session.sh` 读取的位置。合并 PR #187（@Stephen-abc：Windows 测试编码修复、过时安装路径文档）与 PR #192（@igorcosta：Autohand Code 设置文档）。新增 `SECURITY.md` 并启用私有漏洞报告（@AvitalAviv）。修正 `AGENTS.md` 中贡献者 PR 合并指引，原先会引导 agents 以会改写作者归属的方式 squash-merge。套件 186 通过、5 跳过、0 失败。
v3.1.3	热修复：v3.1.2 中 SKILL.md frontmatter 为无效 YAML。 v3.1.2 的 description 刷新加入了冒号，而英文 SKILL.md 仍将 `description` 保持未加引号，YAML 因此拒绝 frontmatter（"mapping values are not allowed here"），可能破坏 skill 加载与模型触发描述。v3.1.3 在规范文件与七个英文 IDE 变体中为 description 加引号（与已加引号的翻译变体一致；解析值相同），并增加 `tests/test_skill_frontmatter_valid.py` 以将每个 SKILL.md frontmatter 校验为 YAML。套件 184 通过。
v3.1.2	Session-catchup 命令可在插件运行时之外工作、`.hermes` 对齐、刷新 skill 描述（PR #186 by @shunfeng8421 closes #185，由 @xwang118 报告）。文档中的 Restore Context 命令使用了 `${CLAUDE_PLUGIN_ROOT}`，而插件运行时仅在 hook 执行内设置该变量，因此仅 skill 安装（`npx skills add`、Codex、Cursor）在 shell 中运行时得到空变量与损坏的 `/scripts/...` 路径。现对规范文件、`.codebuddy` 以及五个语言变体使用 `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"`；`.hermes` 变体对 `$HERMES_HOME` 采用了相同回退。八个英文 SKILL.md 描述已刷新，以面向 AI coding agents 的规划与上下文丢失存活为首要说明，`Use when` 触发与翻译变体未变。仅文档；套件 180 通过。
v3.1.1	Codex 校验命令检查规范的 `hooks` 功能标志（PR #184 by @Fat-Jan）。`docs/codex.md` 校验块运行 `codex features list \| rg '^codex_hooks\s'`，但 Codex 在 0.129.0 中将规范功能键从 `codex_hooks` 改为 `hooks`（openai/codex#20522）。别名在配置中仍可解析，但 `codex features list` 只打印 `hooks`，因此旧模式在当前 Codex 上匹配不到任何内容，并把已正确配置的用户导向升级路径。该命令现 grep `^(hooks\|codex_hooks)\s`，故障排除句子覆盖两个名称，与文件自 v2.39.0 起携带的 `hooks = true` 指引一致。仅文档；套件 180 通过。
v3.1.0	Codex Stop hook 不再因未完成计划而阻塞、原生 Codex PreCompact 对齐、Pi 扩展测试套件，以及准确的 SHA-cache 文档（PR #180 by @2023Anita closes #178，PR #181 by @GongYuanCaiJi，PR #175 与 PR #174 by @mvanhorn close #163 与 #164）。`.codex` 的 Stop 适配器去掉了推动 Codex agents 自动继续未完成阶段的 `{"decision":"block"}` 路径；现仅发出建议性进度同步提醒，符合 v3 原则：仅因未完成计划从不阻塞 stop。原生 `.codex/hooks.json` 路由补上了相对规范 SKILL.md 缺失的 PreCompact hook（`pre-compact.sh`），在从不触发该事件的运行时上保持休眠。Pi 扩展获得 TypeScript 集成套件，覆盖全部八个生命周期处理器、四种运行时模式与证明门控。`docs/perf-notes.md` 记录证明 SHA 缓存，并更正为 v3 的 `$XDG_CACHE_HOME/pwf-sha` 位置。套件 180 通过。
v3.0.0	面向长时间运行 agentic 运行的自主模式与门控模式、结构化运行账本、可选完成门控（无破坏性变更：无模式标记时 hooks 产生与 v2.43 字节级相同的输出）。`init-session --autonomous` 对强模型取消按工具调用的计划再注入，保留回合开始注入；`--gated` 增加刻意的 Stop-hook 完成门控，仅在五个条件同时成立时阻塞（门控模式、存在 `in_progress` 阶段、`stop_hook_active` 为 false、阻塞次数未达上限、自上次阻塞以来账本有进展），因此仅未完成计划不会困住会话。新的仅追加 JSONL 运行账本（`ledger-append`、`ledger-summary`、`phase-status`，sh + ps1）在 v3 模式中以固定形状摘要取代原始 `progress.md` 尾部。v3 模式默认开启证明，未证明的计划体在注入时被拒绝。每会话 nonce 分隔符，SHA 缓存移至 `$XDG_CACHE_HOME/pwf-sha`，plan-dir 解析器中的 realpath 包含检查。Hook 标量由薄调度器取代（`inject-plan.sh`、`gate-stop.sh`），在两个 `scripts/` 位置均随附。新的 `templates/task_plan_autonomous.md` 含 `DependsOn`/`Owner`/`AcceptanceCheck` 字段，`MIGRATION.md` 中的 v2 到 v3 迁移指南，主机能力分层已文档化（硬阻塞、跟进注入、仅通知）。套件 178 通过，外加位置对齐与门控/账本/init-mode/包含测试。
v2.43.0	CONTRIBUTING.md + OpenCode 文档修复 + `.continue`/`.gemini`/`.kiro` 变体同步至对齐（PR #171 by @Skulli485，issue #172 by @luyanfeng，issues #159/#160/#161）：仓库根目录首次出现 `CONTRIBUTING.md`，由 GitHub 在 PR 创建流程中自动展示。发现手动安装块引用了加倍路径（`planning-with-files/planning-with-files/SKILL.md`）后，`docs/opencode.md` 快速安装从 `git clone` 改为 `npx skills add`。三个长期落后的 IDE SKILL.md 变体提升到 v2.43.0 对齐：`.continue` 自 v2.34.0（落后 9 个版本）、`.gemini` 自 v2.34.0（落后 9 个版本）、`.kiro` 自 v2.32.0-kiro（落后 11 个版本），保留 IDE 专用 frontmatter、hook 形态与 Kiro Agent Skill 布局。
v2.42.0	POSIX `init-session.sh` 可移植性 + 插件与 skill 安装透明度 + Topic Handoff 文档（PR #169 与 PR #170 by @carterusedulm2-maker）：`init-session.sh` 及其 7 个镜像将 `[[ ]]` bash 特有写法换为 POSIX 的 `[ ]`，以便测试通过 `sh`（而非 `bash` shebang）调用脚本时，`tests/test_init_session_slug.py` 在 `dash`（Ubuntu）下干净运行。规范 SKILL.md 增加安装范围说明：`/plugin install` 随附带有 `/plan-goal` 与 `/plan-loop` 的 `commands/` 文件夹，但 `npx skills add`（以及 ClawHub）不会。两种包装器的手动回退步骤均内联文档化，使仅 skill 会话可通过直接调用 Claude Code 原生的 `/goal` 与 `/loop` 原语产生相同效果。`docs/quickstart.md` 与 `docs/workflow.md` 增加可选的 Topic Handoff Pattern，用于超长运行的运维主题（`handoffs/<topic>.md` 与 `progress.md` 并列）。
v2.41.0	Windows exec-bit 测试跳过 + 证明锁定文档（PR #167 by @gauravvojha，Issue #166；PR #168 by @CleanDev-Fix，Issue #165）：`test_script_permissions.py` 现于 Windows 上以类级 `pytest.mark.skipif(sys.platform == "win32")` 跳过，因为 NTFS 不存储 POSIX 可执行位；自 v2.34.1 起存在的 2 个既有 Windows exec-bit 失败已解决。新的专用 `docs/attestation-locking.md` 页面记录 `attest-plan.sh` 写入路径、原子 temp-rename 保证、可选的 `flock` 建议锁，以及并行会话推荐的 slug-mode 工作流。
v2.40.1	Pi 适配器 SKILL.md 同步缺口 + npm scope 修正（PR #158 by @TomXPRIME）：v2.39.0 之后 `.pi` 的 SKILL.md 落后于规范 Claude Code 副本；v2.40.1 回移植 Rule 7（完成后继续）、Security Boundary 章节、覆盖 `set-active-plan.sh`/`resolve-plan-dir.sh`/`attest-plan.sh` 与并行任务工作流的扩展 Scripts 章节，以及「将网页内容写入 task_plan.md」反模式行。Pi npm 包从无 scope 的 `pi-planning-with-files` 重命名为 `@tomxprime/planning-with-files`，与包作者命名空间一致；安装文档相应更新。作者、仓库、许可证与 bugs URL 均保留。
v2.40.0	Slug-mode 解析修复 + 性能缓存 + KV-cache 卫生 + Pi 误报修复（来自 v2.40 研发实验的 9 项）：hook 解析顺序反转，使 slug-mode 优先于遗留 root；`.active_plan` 的目标目录与内容对照安全标识符正则校验；`check-complete.sh` 遵循 `$PLAN_ID` 与 `.active_plan`；Pi 扩展的 `isDangerousBashCommand` 改为词边界正则数组，使无害的 `git push origin <branch>` 不再触发警告；按 mtime 键控的 SHA-256 缓存降低 Windows Git Bash 上证明 hook 延迟；`progress.md` 尾部时间戳规范化以稳定 KV-cache 前缀；`resolve-plan-dir.sh` 的 mtime 解析在 GNU/BSD/macOS/Alpine/Git Bash 上可移植，并带 python+perl 回退；`attest-plan.sh` 使用原子 temp-rename 与可选的 `flock` 关闭并发写入竞态。130 通过 / 2 个既有 Windows exec-bit 失败，+20 个新测试。
v2.39.0	Pi Coding Agent 完整 hook 对齐扩展 + Codex hooks 标志修复（PR #157 by @TomXPRIME，Issue #154 by @DLI1996）：`.pi` 适配器附带 TypeScript 扩展，将八个 Pi 生命周期事件映射为 skill 在 Claude Code 上提供的相同行为，并有四模式系统（`auto`/`parity`/`cache-safe`/`notify`），可自动检测 DeepSeek 并保持 KV-cache 前缀稳定。Pi 运行时读取规范 v2.37 `attest-plan.sh` 写入的同一 `.attestation` 文件，因此证明一次即可在两个运行时锁定计划。四个斜杠命令（`/plan-status`、`/plan-attest`、`/plan-goal`、`/plan-loop`）镜像其 Claude Code 对应项。另外，`docs/codex.md` 从 `codex_hooks = true` 换为 `hooks = true` 以匹配当前 OpenAI 规范键，并附别名说明，避免将旧配置用户推去迁移。
v2.38.1	Claude Code skill 选择器中 description 字段乱码（经 Discussion #153 by @bmyury 暴露）：hook 命令嵌入了 `'---BEGIN PLAN DATA---'` 计划注入分隔符；Claude Code 的 skill 发现加载器在第一个 `---` 处切分 frontmatter，并将截断值读为 description。在规范 SKILL.md、全部五个语言变体、`.codebuddy/.codex/.cursor` 适配器镜像与 `clawhub-upload` 中改为 `===BEGIN PLAN DATA===` / `===END PLAN DATA===`。Hook 执行与篡改证明从未受影响；仅显示的元数据。
v2.38.0	Claude Code 回合循环集成 + OpenCode SQLite 修复：新的 PreCompact hook 在 `/compact` 与 autoCompact 时触发，在压缩完成前提示刷新进度，并在已证明时打印活动的 Plan-SHA256。新的 `/plan-goal` 斜杠命令与 Claude Code 的 `/goal`（v2.1.139，2026 年 5 月 12 日）组合：从活动计划推导终止条件。新的 `/plan-loop` 与 `/loop`（v2.1.72+）组合：默认 10 分钟 tick 重新读取规划文件并运行 check-complete。新的 `templates/loop.md` 作为裸 `/loop` 的规划感知默认。Session-catchup 为 OpenCode 的 SQLite 迁移重写。Codex 获得 `PermissionRequest` 适配器，在权限提示处展示计划上下文。
v2.37.0	哈希证明 + 对齐提升器（closes #150, #151）：`/plan-attest` 用 SHA-256 锁定 `task_plan.md`；hooks 在篡改时阻止注入。`scripts/bump-version.py` + 对齐测试消灭了 v2.34.1、v2.36.0、v2.36.2 与 v2.36.3 背后的「漏掉一个变体」回归类。（感谢 @oaabahussain！）
v2.36.3	并行规划脚本现随 skill 发布：v2.36.0 安装的 skill 中缺失 `resolve-plan-dir.sh` 与 `set-active-plan.sh`；现已纳入规范 + 全部 IDE 镜像，并更新 SKILL.md 文档
v2.36.2	规范脚本同步（PR #149）：`skills/planning-with-files/scripts/init-session.sh` 缺失 v2.36.0 的 slug mode；现已与 IDE 镜像同步 + 回归测试。（感谢 @voidborne-d！）
v2.36.1	安全加固：移除 Stop hook 缓存搜索，ExecutionPolicy Bypass 改为 RemoteSigned，增加 prompt injection 分隔符。（Gen Agent Trust Hub FAIL 已解决）
v2.36.0	并行计划隔离 + Codex 会话隔离（closes #146, #148）：`init-session.sh` slug mode、`set-active-plan.sh`、`resolve-plan-dir.sh`，全部 Codex hooks 经 resolver 路由，会话附着门控。Hermes 文档（closes #147）：集成说明加入 `docs/hermes.md`。34 个新测试。（感谢 @githubYiheng、@09ashishkapoor、@shawnli1874！）
v2.35.1	Shebang 可移植性修复：hook 脚本中将 `/bin/bash` 改为 `/usr/bin/env bash`，修复 NixOS 及其他 bash 不在 `/bin/bash` 的系统上的兼容性。（感谢 @Emin017！）
v2.35.0	Hermes 适配器 + NLPM 审计加固：Hermes platform 17 支持（感谢 @bailob！），NLPM 审计修复 Python PATH 解析、session-catchup 注入上限、Pi PowerShell 语法（感谢 @xiaolai！）
v2.34.1	Stop hook Windows 可移植性修复（closes #133）：`export SD=` 在 Windows Git Bash hook 上下文中失败；插件缓存结构下的回退路径错误。已在全部 13 个 SKILL.md 变体中修复。（感谢 @nazeshinjite！）
v2.34.0	Codex hooks 全面恢复（closes #132）：`.codex/hooks.json` + 生命周期脚本回归 — SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop。Tessl CI 用于 SKILL.md 质量评审。Exec bit 修复。补上 4 位缺失贡献者。（感谢 @Leon-Algo、@popey！）
v2.33.0	多语言扩展：新增阿拉伯语、德语与西班牙语 skill 变体（感谢社区贡献者！）
v2.32.0	Codex session catchup 重写（感谢 @ebrevdo！）、Loaditout A 级安全徽章、Stop hook Git Bash 修复
v2.31.0	Codex hooks.json 集成完整生命周期 hooks（感谢 @Leon-Algo！）
v2.30.1	修复：恢复 Codex 脚本可执行位（感谢 @Leon-Algo！）
v2.30.0	`CLAUDE_SKILL_DIR` 变量，IDE 配置迁至按 IDE 的分支，plugin.json 从 2.23.0 升级
v2.29.0	分析工作流模板：用于数据探索会话的 `--template analytics` 标志（感谢 @mvanhorn！）
v2.28.0	繁体中文（zh-TW）skill 变体（感谢 @waynelee2048！）
v2.26.2	修复：hook 命令中的 `---` 破坏 YAML frontmatter 解析，hooks 现可正确注册
v2.26.1	修复：`/clear` 后的 session catchup、Windows 路径清理 + 内容注入（感谢 @tony-stark-eth！）
v2.26.0	IDE 审计：Factory hooks、Copilot errorOccurred hook、Gemini hooks、缺陷修复
v2.18.2	Mastra Code hooks 修复（hooks.json + 文档准确性）
v2.18.1	Copilot 乱码完整修复
v2.18.0	BoxLite sandbox 运行时集成
v2.17.0	Mastra Code 支持 + 全部 IDE SKILL.md 规范修复
v2.16.1	Copilot 乱码修复：PS1 UTF-8 编码 + bash ensure_ascii（感谢 @Hexiaopi！）
v2.16.0	GitHub Copilot hooks 支持（感谢 @lincolnwan！）
v2.27.0	Kiro Agent Skill 布局（感谢 @EListenX！）
v2.15.1	Session catchup 误报修复（感谢 @gydx6！）
v2.15.0	`/plan:status` 命令、OpenCode 兼容性修复
v2.14.0	Pi Agent 支持、OpenClaw 文档更新、Codex 路径修复
v2.11.0	便于自动补全的 `/plan` 命令
v2.10.0	Kiro steering files 支持
v2.7.0	Gemini CLI 支持
v2.2.0	会话恢复、Windows PowerShell、感知操作系统的 hooks

查看全部版本发布 · CHANGELOG

v2.36.0 已发布并行计划隔离（.planning/YYYY-MM-DD-slug/ 目录）与 Codex 会话隔离。experimental/isolated-planning 分支是更早的原型；master 现为规范主分支。

会话恢复

当你的上下文写满并运行 /clear 时，此 skill 会自动恢复你之前的会话。

工作原理：

在当前 IDE 的会话存储中检查是否有先前会话数据（Claude Code 为 ~/.claude/projects/，Codex 为 ~/.codex/sessions/）
查找规划文件最后一次更新的时间
提取此后发生的对话（可能已丢失的上下文）
显示追赶报告，便于你同步状态

专业提示： 在清空上下文前禁用 auto-compact，以尽可能保留更多上下文：

{ "autoCompact": false }

🛠️ 支持的 IDE（18+ 平台）

增强支持（hooks + 生命周期自动化）

这些 IDE 配有专用 hook 配置，可在使用工具前自动重读你的计划、提醒你更新进度，并在停止前验证是否完成：

IDE	安装指南	集成方式
Claude Code	安装	Plugin + SKILL.md + Hooks
Cursor	Cursor 配置	Skills + hooks.json
GitHub Copilot	Copilot 配置	Hooks（含 errorOccurred）
Mastra Code	Mastra 配置	Skills + Hooks
Gemini CLI	Gemini 配置	Skills + Hooks
Kiro	Kiro 配置	Agent Skills
Codex	Codex 配置	Skills + Hooks
Hermes Agent	Hermes 配置	Skill + Project Plugin
CodeBuddy	CodeBuddy 配置	Skills + Hooks
FactoryAI Droid	Factory 配置	Skills + Hooks
OpenCode	OpenCode 配置	Skills + Custom session storage

标准 Agent Skills 支持

这些 IDE 实现了 Agent Skills 开放规范。使用 npx skills add 安装——安装器会自动将 skill 放入各 IDE 的发现路径：

IDE	安装指南	Skill 发现路径
Continue	Continue 配置	`.continue/skills/` + .prompt files
Pi Agent	Pi Agent 配置	`.pi/skills/`（npm package)
OpenClaw	OpenClaw 配置	`.openclaw/skills/`（docs)
Autohand Code	Autohand Code 配置	`~/.autohand/skills/` 或 `.autohand/skills/`
Antigravity	Antigravity 配置	`.agent/skills/`（docs)
Kilocode	Kilocode 配置	`.kilocode/skills/`（docs)
AdaL CLI (Sylph AI)	AdaL 配置	`.adal/skills/`（docs)

注意： 如果你的 IDE 使用旧版 Rules 系统而非 Skills，请参阅 legacy-rules-support 分支。

🧱 沙箱运行时（1 个平台）

运行时	状态	指南	说明
BoxLite	✅ 已文档化	BoxLite 配置	在硬件隔离的微 VM 中运行 Claude Code + planning-with-files

注意： BoxLite 是沙箱运行时，而非 IDE。Skills 通过 ClaudeBox 加载——BoxLite 官方的 Claude Code 集成层。

一款 Claude Code 插件，可将你的工作流改造为使用持久化 Markdown 文件进行规划、进度跟踪和知识存储——正是这一模式让 Manus 价值数十亿美元。

快速安装

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

🌐 另有 5 种语言版本

🇸🇦 العربية / Arabic

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

🇩🇪 Deutsch / German

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

🇪🇸 Español / Spanish

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g

🇨🇳 中文版 / Chinese (Simplified)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

🇹🇼 正體中文版 / Chinese (Traditional)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

适用于 Claude Code、Cursor、Codex、Gemini CLI、Autohand Code，以及 40+ 个支持 Agent Skills 规范的 agent。

🔧 Claude Code Plugin（高级功能）

如需 /plan 自动补全命令等 Claude Code 专属功能：

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

就这么简单！现在在 Claude Code 中使用以下任一命令：

命令	自动补全	说明
`/planning-with-files:plan`	输入 `/plan`	开始规划会话（v2.11.0+）
`/planning-with-files:status`	输入 `/plan:status`	一目了然查看规划进度（v2.15.0+）
`/planning-with-files:start`	输入 `/planning`	原始启动命令

替代方案： 如需 /planning-with-files（无前缀），请将 skills 复制到本地文件夹：

macOS/Linux：

cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/

Windows（PowerShell）：

Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"

所有安装方式请参阅 docs/installation.md。

为什么选择这个 Skill？

2025 年 12 月 29 日，Meta 以 20 亿美元收购 Manus. 短短 8 个月内，Manus 从上线到营收超过 1 亿美元。他们的秘诀？上下文工程（Context engineering）。

"Markdown 是我磁盘上的「工作记忆」。由于我会迭代处理信息，且活跃上下文有限，Markdown 文件充当笔记草稿、进度检查点，以及最终交付物的构建块。" — Manus AI

问题所在

Claude Code（以及大多数 AI 智能体）存在以下问题：

记忆易失 — 上下文重置后 TodoWrite 工具会消失
目标漂移 — 经过 50 次以上工具调用后，原始目标会被遗忘
错误被隐藏 — 失败未被记录，导致同样错误反复发生
上下文塞满 — 所有内容塞进上下文，而非持久化存储

解决方案：三文件模式

对于每个复杂任务，创建三个文件：

task_plan.md      → Track phases and progress
findings.md       → Store research and findings
progress.md       → Session log and test results

核心原则

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

Manus 原则

原则	实现方式
文件系统即记忆	存入文件，而非上下文
注意力操控（Attention manipulation）	重大决策前重读计划（hooks）
错误持久化	在计划文件中记录失败
目标追踪	复选框展示进度
完成验证	Stop hook 检查所有阶段

使用方法

安装后，AI 智能体将：

若未提供任务描述，询问你的任务
在项目目录中创建 task_plan.md、findings.md 和 progress.md
重大决策前重读计划（传统模式下通过 PreToolUse hook；自主模式则在会话开始与阶段切换时注入，避免强模型承担每次工具调用的额外开销）
文件写入后提醒你更新状态（通过 PostToolUse hook）
将发现存入 findings.md，而非塞进上下文
记录错误供日后参考
停止前验证完成（通过 Stop hook）

调用方式：

/planning-with-files:plan — 输入 /plan 在自动补全中查找（v2.11.0+）
/planning-with-files:start — 输入 /planning 在自动补全中查找
/planning-with-files — 仅当你将 skills 复制到 ~/.claude/skills/ 时

完整五步指南请参阅 docs/quickstart.md。

基准测试结果

方法论说明： 96.7% 这一数字来自在 claude-sonnet-4-6 上运行的 v2.21.0 评估（2026-03-06）。它衡量的是文件模式保真度（智能体是否创建并维护三文件结构），而非长程自主运行中的目标漂移。较新模型及自主模式相关工作尚未纳入该数字。完整方法论、数据集与断言列表：docs/evals.md。

使用 Anthropic 的 skill-creator 框架（v2.22.0）正式评估，模型 claude-sonnet-4-6，2026-03-06。10 个并行子智能体，5 种任务类型，30 条可客观验证的断言，3 次盲测 A/B 对比。

测试项	使用 skill	未使用 skill
通过率（30 条断言）	96.7% (29/30)	6.7% (2/30)
遵循三文件模式	5/5 evals	0/5 evals
盲测 A/B 胜出	3/3 (100%)	0/3
平均评分量表得分	10.0/10	6.8/10

完整方法论与结果 · 技术详解

关键规则

先建计划 — 没有 task_plan.md 绝不开始
两步操作规则 — 每进行 2 次 view/browser 操作后保存发现
记录所有错误 — 有助于避免重复犯错
绝不重复失败 — 追踪尝试次数，调整方法

适用场景

适用于：

多步骤任务（3 步以上）
研究类任务
构建/创建项目
跨越大量工具调用的任务

不适用于：

简单问答
单文件编辑
快速查询

文件结构

planning-with-files/
├── commands/                # Plugin commands
│   ├── plan.md              # /planning-with-files:plan command (v2.11.0+)
│   ├── plan-ar.md           # Arabic /plan command (v2.33.0+)
│   ├── plan-de.md           # German /plan command (v2.33.0+)
│   ├── plan-es.md           # Spanish /plan command (v2.33.0+)
│   └── start.md             # /planning-with-files:start command
├── templates/               # Root-level templates (for CLAUDE_PLUGIN_ROOT)
├── scripts/                 # Root-level scripts (for CLAUDE_PLUGIN_ROOT)
├── docs/                    # Documentation
│   ├── installation.md
│   ├── quickstart.md
│   ├── workflow.md
│   ├── troubleshooting.md
│   ├── gemini.md            # Gemini CLI setup
│   ├── cursor.md
│   ├── windows.md
│   ├── kilocode.md
│   ├── codex.md
│   ├── opencode.md
│   ├── mastra.md             # Mastra Code setup
│   └── boxlite.md            # BoxLite sandbox setup
├── examples/                # Integration examples
│   └── boxlite/             # BoxLite quickstart
│       ├── README.md
│       └── quickstart.py
├── planning-with-files/     # Plugin skill folder
│   ├── SKILL.md
│   ├── templates/
│   └── scripts/
├── skills/                  # Skill variants
│   ├── planning-with-files/     # English (default)
│   │   ├── SKILL.md
│   │   ├── examples.md
│   │   ├── reference.md
│   │   ├── templates/
│   │   └── scripts/
│   │       ├── init-session.sh
│   │       ├── check-complete.sh
│   │       ├── init-session.ps1   # Windows PowerShell
│   │       └── check-complete.ps1 # Windows PowerShell
│   ├── planning-with-files-ar/   # Arabic (v2.33.0+)
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   └── scripts/
│   ├── planning-with-files-de/   # German (v2.33.0+)
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   └── scripts/
│   ├── planning-with-files-es/   # Spanish (v2.33.0+)
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   └── scripts/
│   ├── planning-with-files-zh/   # Chinese Simplified (v2.25.0+)
│   └── planning-with-files-zht/  # Chinese Traditional (v2.28.0+)
├── .gemini/                 # Gemini CLI skills + hooks
│   ├── settings.json        # Hook configuration (v2.26.0)
│   ├── hooks/               # Hook scripts (SessionStart, BeforeTool, AfterTool, BeforeModel, SessionEnd)
│   └── skills/
│       └── planning-with-files/
├── .codex/                  # Codex CLI skills + hooks
│   └── skills/
├── .opencode/               # OpenCode skills (custom session storage)
│   └── skills/
├── .claude-plugin/          # Plugin manifest
├── .cursor/                 # Cursor skills + hooks
│   ├── hooks.json           # Hook configuration
│   ├── hooks/               # Hook scripts (bash + PowerShell)
│   └── skills/
├── .codebuddy/              # CodeBuddy skills + hooks
│   └── skills/
├── .factory/                # FactoryAI Droid skills + hooks (v2.26.0)
│   └── skills/
├── .pi/                     # Pi Agent skills (npm package)
│   └── skills/
│       └── planning-with-files/
├── .continue/               # Continue.dev skills + prompt files
│   ├── prompts/             # .prompt file for slash commands
│   └── skills/
├── .github/                 # GitHub Copilot hooks (incl. errorOccurred)
│   └── hooks/
│       ├── planning-with-files.json  # Hook configuration
│       └── scripts/         # Hook scripts (bash + PowerShell)
├── .mastracode/             # Mastra Code skills + hooks
│   └── skills/
├── .kiro/                   # Kiro Agent Skills (v2.27.0+)
│   └── skills/
├── CHANGELOG.md
├── CITATION.cff
├── LICENSE
└── README.md

常见问题

如何在 /clear 或崩溃后避免编程智能体丢失计划？

计划保存在磁盘上的 task_plan.md、findings.md 和 progress.md 中，而不仅存在于上下文窗口。每轮开始时，UserPromptSubmit hook 会重新注入当前计划；在 /clear 或新会话之后，该 skill 会从磁盘重读文件（会话恢复），从而让智能体自动恢复目标与进度。