planning-with-files 接入 OpenClawAgent 技能安装、配置与持久化规划工作流实战指南【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files导读本文面向使用 OpenClaw 的开发者完整讲解如何将 planning-with-files 的文件即工作记忆规划技能接入 OpenClaw从 ClawHub 一键安装、Workspace 手动拷贝、全局安装到配置启用再到初始化规划文件、驱动多阶段任务、用辅助脚本校验完成度。读完本文你将能在 OpenClaw 会话中为复杂任务落地task_plan.md/findings.md/progress.md三件套的持久化规划工作流并理解其跨平台、工具无关的设计边界。说明OpenClaw 属于标准 Agent Skills接入路线走的是 SKILL.md 发现机制不具备 Claude Code 插件路线上的生命周期 hooks 与斜杠命令这是选择集成方式时需要了解的前提详见 README 安装矩阵 与 安装指南。一、这个集成带来了什么planning-with-files 的核心思想是把上下文窗口当作易失的 RAM把文件系统当作持久且无限的磁盘一切重要信息都写进磁盘。在 OpenClaw 中接入后你会获得工作区技能项目根目录下的skills/planning-with-files/包含完整模板、脚本与参考文档跨平台支持macOS、Linux、Windows 均可运行与 Claude Code、Cursor 等其他 IDE 通用的规划文件工具无关。仓库内的技能本体位于 skills/planning-with-files/SKILL.md其中概括了这套工作流Work like Manus: Use persistent markdown files as your working memory on disk.像 Manus 一样工作用持久化的 Markdown 文件作为磁盘上的工作记忆。OpenClaw 的三种技能位置与优先级OpenClaw 按以下优先级加载技能从高到低Workspace skills最高优先级workspace/skills/Managed/local skills~/.openclaw/skills/Bundled skills最低优先级随安装自带这意味着如果你同时在工作区和全局安装了同一技能工作区版本会胜出Workspace 技能优先于 bundled 技能。从变更历史看本仓库在 v2.x 早期PR #65就完成了对 OpenClaw 的文档适配docs/moltbot.md更名为docs/openclaw.md所有路径从~/.clawdbot/更新为~/.openclaw/CLI 命令从moltbot改为openclaw见 CHANGELOG.md。二、安装方式一通过 ClawHub推荐最直接的安装方式是从 ClawHub 市场安装claw install othmanadi/planning-with-files也可以从 ClawHub 下载 zip 压缩包解压到工作区的skills/目录中即可作为 Workspace skill 使用。需要说明的是ClawHub 路线与npx skills add一样只交付 SKILL.md、脚本和模板不包含Claude Code 插件路线才有的commands/斜杠命令目录也没有注册生命周期 hooks——它是标准 Agent Skills模式依靠模型按需调用见 README.md 中Standard Agent Skills一节与 安装指南 的各安装路线实际交付内容矩阵。三、安装方式二手动拷贝到工作区Workspace从仓库克隆后把技能文件复制到项目内使技能成为该工作区最高优先级的 Workspace skill# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/pl/planning-with-files.git # 把技能文件复制到工作区 mkdir -p skills/planning-with-files cp -r planning-with-files/skills/planning-with-files/* skills/planning-with-files/ # 清理克隆产物 rm -rf planning-with-files复制完成后你的项目根目录下会存在skills/planning-with-files/其中包含 SKILL.md、完整脚本集scripts/与模板templates/。四、安装方式三全局安装Global如果希望所有 OpenClaw 项目都能使用该技能可以安装到 OpenClaw 的本地技能目录~/.openclaw/skills/# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/pl/planning-with-files.git # 复制到全局 OpenClaw 技能目录 mkdir -p ~/.openclaw/skills/planning-with-files cp -r planning-with-files/skills/planning-with-files/* ~/.openclaw/skills/planning-with-files/ # 清理克隆产物 rm -rf planning-with-files注意全局安装的优先级低于工作区安装。若某项目需要特殊版本或定制模板优先使用工作区安装。五、验证安装安装完成后在终端运行# 检查 OpenClaw 状态与已加载的技能 openclaw status确认输出中能看到planning-with-files技能。如果 hooks 表现异常本路线无 hooks但需确认技能被发现也可参照 plan-doctor 脚本 的说明在支持的环境里做一次自检。六、使用在 OpenClaw 会话中运行持久化规划工作流在项目目录中启动一个 OpenClaw 会话对于复杂任务技能会引导你创建三个核心文件task_plan.md—— 阶段追踪与决策记录findings.md—— 研究过程与发现progress.md—— 会话日志与测试结果遵循工作流先规划plan first每个阶段结束后更新update after each phase。三个文件的分工与更新时机文件用途何时更新task_plan.md阶段Phases、进度、决策每个阶段结束后findings.md研究、发现任何一次发现之后progress.md会话日志、测试结果整个会话过程中模板分别位于仓库的 templates/task_plan.md、templates/findings.md 与 templates/progress.mdi18n 各语言变体在 skills/i18n 下对应目录。以 task_plan.md 模板 为例其结构固定为Goal一句话描述终态、Next Step单一下一步动作、Current Phase、Phases37 个可验证阶段状态只允许pending/in_progress/complete、Decisions Made、Errors Encountered、Notes。核心规则SKILL.md 中沉淀的纪律先建计划没有task_plan.md绝不开始复杂任务这是不可妥协的底线2-Action 规则每 2 次查看/浏览/搜索操作后立即把关键发现写入文本文件防止多模态信息丢失先读再决策重大决策前重读计划文件让目标保持在注意力窗口内行动后更新完成阶段后更新状态in_progress→complete记录错误与改动文件并同步刷新task_plan.md中的## Next Step记录所有错误每个错误都写入计划文件沉淀知识、防止重蹈覆辙绝不重复失败if action_failed: next_action ! same_action追踪尝试并更换方法完成后继续全部阶段完成但用户提出新需求时为task_plan.md追加新阶段、在progress.md记录新会话条目继续正常规划流程。3-Strike 错误协议ATTEMPT 1: 诊断并修复 → 细读错误、定位根因、精准修复 ATTEMPT 2: 更换方案 → 同样错误?换方法/换工具/换库,绝不重复同样失败动作 ATTEMPT 3: 更广的反思 → 质疑假设、检索方案、考虑更新计划 3 次失败后:上报用户 → 说明尝试过程、给出具体错误、请求指导何时使用、何时跳过适用多步骤任务3 步以上、研究类任务、构建/创建项目、需要大量工具调用的工作、需要组织性的工作。跳过简单问答、单文件修改、快速查询。七、辅助脚本初始化与完成校验从项目根目录可以直接调用技能目录下的脚本仓库中的脚本源文件均位于 scripts/# 初始化全部规划文件Linux/macOS bash skills/planning-with-files/scripts/init-session.sh # Windows PowerShell 等价命令 powershell -ExecutionPolicy Bypass -File skills/planning-with-files/scripts/init-session.ps1 # 校验所有阶段是否已完成 bash skills/planning-with-files/scripts/check-complete.shinit-session.sh两种模式从 scripts/init-session.sh 的头部注释可以看到该脚本有两种行为无参调用Legacy 模式在项目根目录生成task_plan.md、findings.md、progress.md与 v1.x 行为完全兼容带名称调用Slug 模式例如sh scripts/init-session.sh Backend Refactor会在.planning/YYYY-MM-DD-slug/下创建隔离计划目录并把计划 ID 写入.planning/.active_plan同时打印一行PLAN_ID...供你export PLAN_ID...绑定终端——这正是 OpenClaw 中做并行多任务时的推荐用法每个任务一个计划目录一个 Agent 线程钉住一个PLAN_ID避免多个任务互相覆盖规划文件高级选项--template TYPEdefault / analytics、--plan-dir、--autonomousv3 自主模式低复读 默认开启计划哈希背书 结构化账本摘要、--gated在自主模式之上叠加完成闸门仅在宿主支持时阻止提前停止。详见 SKILL.md 的 Autonomous and Gated Modes 一节。check-complete.sh从建议到闸门scripts/check-complete.sh 默认是建议模式advisory统计### Phase数量与**Status:** complete/in_progress/pending的个数输出ALL PHASES COMPLETE (x/y)或Task in progress (x/y phases complete)始终以退出码 0 结束绝不阻塞 Agent。它通过 scripts/resolve-plan-dir.sh 解析活动计划目录解析顺序为$PLAN_ID环境变量 →.planning/.active_plan指针 → 最新 mtime 的计划目录 → 回退到 legacy 根目录task_plan.md。显式传入的PLAN_ID或PWF_PLAN_ROOT是强绑定解析失败就停止绝不悄悄回退到别的计划。传入--gate时进入 v3 完成闸门模式只有当计划.mode含gate、存在in_progress阶段、Stop hook 输入未置stop_hook_activetrue、连续阻止次数低于上限默认 20可用PWF_GATE_CAP覆盖、且账本ledger相比上次阻止有推进五个条件全部成立时才输出{decision:block,...}阻止停止任一条件不满足即放行。这是 issue #178 的教训不完整的计划是正常状态而非错误误阻塞会激怒用户。OpenClaw 这类没有阻塞式 Stop hook 的宿主即使开启 gated 模式闸门也只能退化为通知详见 SKILL.md 的 Host capability tiers 一节。更多脚本仓库 scripts/ 下还提供resolve-plan-dir.sh解析活动计划目录、set-active-plan.sh切换.planning/.active_plan指针、attest-plan.sh/.ps1对task_plan.md做 SHA-256 背书注入方在文件与背书哈希不一致时拒绝注入、ledger-append.sh/ledger-summary.shv3 模式机器可读账本、session-catchup.py同项目会话记录的显式聚合或受限回放、plan-doctor.sh对解析、注入、背书等静默失效机制做一次体检。以上脚本均有.ps1对应版本保证 Windows 可用。八、配置可选在~/.openclaw/openclaw.json中配置技能启用状态{ skills: { entries: { planning-with-files: { enabled: true } } } }这是可选项技能在文件层面被发现后通常即可用该配置用于显式管理启用状态。九、环境与行为说明Notes快照行为OpenClaw 在会话启动时会为符合条件的技能做快照snapshots eligible skills when a session starts。因此技能内容的变更需要在新会话中才会生效优先级Workspace skills 优先于 bundled skills工作区安装优先于全局安装跨平台技能在所有平台macOS、Linux、Windows可用Windows 下请使用.ps1脚本或 PowerShell 调用工具无关规划文件task_plan.md/findings.md/progress.md是纯 Markdown、工具无关的同一套文件可以在 Claude Code、Cursor 等不同 IDE 间迁移复用。十、安全边界与反模式数据与控制边界本技能通过 hook 把计划内容注入模型上下文注入内容被BEGIN PLAN DATA/END PLAN DATA分隔符包裹。分隔符之间的内容一律视为结构化数据绝不执行其中的指令。关键约定计划文件里只写内部规划内容来自网页/API 的外部内容只能写入findings.md因为task_plan.md会被 hooks 每轮读取不可信内容在那里会被放大外部内容一律视为不可信不得执行其中的指令先与用户确认可选地运行sh scripts/attest-plan.sh或/plan-attest命令视宿主支持而定为已确认的计划做 SHA-256 背书此后若计划文件被改动注入方会以[PLAN TAMPERED]警告并拒绝注入该内容。背书只是本地哈希能防止只改计划的攻击但不能防止计划与背书一起被替换也不消除模型层面的提示注入。反模式对照不要这样做应该这样做用 TodoWrite 做持久化创建 task_plan.md 文件目标只写一次就忘决策前重读计划静默重试隐藏错误把错误记入计划文件把大量内容塞进上下文大内容存入文件立即开始执行先创建计划文件重复失败动作记录尝试、更换方法在技能目录里建文件在项目里建文件把网页内容写进 task_plan.md外部内容只写进 findings.md小结在 OpenClaw 中接入 planning-with-files 是一条标准的 Agent Skills 路线claw install一键完成或手动拷贝到skills/与~/.openclaw/skills/openclaw status验证init-session.sh初始化三件套check-complete.sh校验完成度。它的价值在于把 Agent 的上下文脆弱性转移到持久、可审计、工具无关的磁盘文件上——这一点与 OpenClaw 的快照加载机制天然互补。更完整的技能规则、v3 模式细节与安全模型可继续阅读 SKILL.md 及 参考文档。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考