在 Mastra Code 中使用 planning-with-files：基于文件持久化规划的完整集成指南

在 Mastra Code 中使用 planning-with-files基于文件持久化规划的完整集成指南【免费下载链接】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-filesplanning-with-files 是一套面向 AI 编码 Agent 的持久化文件规划方案把task_plan.md、findings.md、progress.md三个 Markdown 文件当作磁盘上的工作记忆配合生命周期钩子实现上下文轮转重注入、会话恢复与确定性完成门控。本文面向使用 Mastra Code 的开发者讲解如何在 Mastra Code 中完成该技能的工作区级/个人级安装、hooks 生命周期集成的原理、会话恢复的显式命令以及团队协作与常见问题排查。Mastra Code 与 planning-with-files 的集成方式Mastra Code 原生支持从.mastracode/skills/目录自动发现技能skill。同时它内置了 Claude Code 兼容层也能读取.claude/skills/目录作为回退。二者都能让 planning-with-files 工作但差异在于钩子支持集成途径技能发现位置Hooks 支持.mastracode/专用目录推荐.mastracode/skills/原生支持读取.mastracode/hooks.jsonClaude Code 兼容回退.claude/skills/依赖 Claude Code 插件/技能安装面非原生使用专用.mastracode/目录可获得三项额外能力通过hooks.json注册原生生命周期钩子PreToolUse、PostToolUse、Stop为 Mastra Code 目录结构提供正确的脚本路径解析resolve-plan-dir.sh等避免与 Claude Code 插件根目录产生路径冲突。仓库中.mastracode/目录的完整布局如下hooks.json 与技能文件同根.mastracode/ ├── hooks.json └── skills/ └── planning-with-files/ ├── SKILL.md ├── scripts/ # check-complete、init-session、resolve-plan-dir、skill-hook 等 ├── templates/ # task_plan.md、findings.md、progress.md 模板 └── references/ # examples.md、reference.md注意仓库是只读的安装流程需要你在自己的项目或用户目录中复制这些文件而不是修改仓库本身。安装工作区级与个人级方式一工作区安装推荐团队共享将技能加入你的项目仓库让整个团队共享# 在项目仓库中执行 git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files # 将 Mastra Code 技能复制到你的仓库 cp -r /tmp/planning-with-files/.mastracode . # 提交以共享给团队 git add .mastracode/ git commit -m Add planning-with-files skill for Mastra Code git push # 清理 rm -rf /tmp/planning-with-files完成后团队中所有使用 Mastra Code 的成员都能访问该技能。方式二个人安装仅为自己安装# 克隆仓库 git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files # 将技能复制到个人 Mastra Code 技能目录 mkdir -p ~/.mastracode/skills cp -r /tmp/planning-with-files/.mastracode/skills/planning-with-files ~/.mastracode/skills/ # 复制 hooksplan enforcement 必需 # 如果已存在 ~/.mastracode/hooks.json请手动合并条目 cp /tmp/planning-with-files/.mastracode/hooks.json ~/.mastracode/hooks.json # 清理 rm -rf /tmp/planning-with-files注意如果你已有一个~/.mastracode/hooks.json不要覆盖它。请将技能 hooks.json 中的 PreToolUse、PostToolUse 和 Stop 条目手动合并进现有文件。验证安装ls -la ~/.mastracode/skills/planning-with-files/SKILL.md然后重启 Mastra Code 会话——技能在启动时扫描目录处理复杂任务时自动激活。工作原理hooks 生命周期与三文件机制Hooks通过 hooks.jsonMastra Code 使用独立的hooks.json文件注册生命周期钩子这与 Claude Code 在 SKILL.md frontmatter 中声明 hooks 的方式不同。Mastra Code 按以下优先级读取 hooks.mastracode/hooks.json项目级最高优先级~/.mastracode/hooks.json全局。仓库自带的 .mastracode/hooks.json 预配置了三个钩子HookMatcher作用PreToolUseWrite、Edit、Bash、Read、Glob、Grep读取task_plan.md前 30 行让目标保持在注意力窗口内cat task_plan.md 2/dev/null \| head -30PostToolUseWrite、Edit文件变更后提醒更新计划状态输出[planning-with-files] Update progress.md with what you just did...Stop全部运行check-complete.sh验证所有 phase 是否完成先探测项目内脚本再回退到全局脚本对比仓库根目录的 hooks/hooks.jsonClaude Code 插件版本可以看到差异Claude 插件版通过${CLAUDE_PLUGIN_ROOT}/hooks/claude-hook.sh分发 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop 六个事件而 Mastra Code 版只注册了三个事件、直接内联命令。这也是文档强调两者不冲突、可同时安装的原因。自动激活技能在以下场景激活提到 complex task 或 multi-step project要求 plan out 或 break down 工作请求帮助组织或跟踪进度启动预计需要超过 5 次工具调用的研究任务。三个规划文件激活后技能在项目根目录创建文件用途位置task_plan.mdPhases阶段、进度、决策项目根目录findings.md研究结果、发现项目根目录progress.md会话日志、测试结果项目根目录三份文件的写作规范与核心规则先建计划、2-Action 规则、读后再决策、完成后更新、全量记录错误等见 skills/planning-with-files/SKILL.md完整模板位于 templates/task_plan.md、templates/findings.md、templates/progress.md.mastracode/skills/planning-with-files/templates/下也有对应副本。Claude Code 兼容性Mastra Code 会将.claude/skills/作为回退读取。如果你已经为 Claude Code 安装了 planning-with-files它可以直接工作——但专用.mastracode/安装能提供通过hooks.json的原生 hooksPreToolUse、PostToolUse、Stop针对 Mastra Code 目录的正确脚本路径解析与 Claude Code 插件根目录无路径冲突。从仓库测试 tests/test_skill_hook_dispatch_parity.py 可以印证 Mastra Code 集成是仓库的一等公民测试断言.mastracode/skills/planning-with-files/SKILL.md必须存在test_guard_hooks_bearing_files_found且其 hook 分发必须探测$HOME/.mastracode/skills/planning-with-files/scripts/路径HOST_EXPECTED_PROBES中.mastracode的期望探针。另一个测试 tests/test_stop_hook_dispatch.py 同样将仓库根.mastracode/skills/planning-with-files/SKILL.md列为需要检查的分发文件。会话恢复/clear 与压缩后的上下文重建当上下文占满执行/clear后技能从项目规划文件中恢复选定上下文。自动恢复不会检查 Mastra 或其他宿主host的对话记录存储本地会话记录只能通过下面的显式命令访问。手动运行# Linux/macOS python3 ~/.mastracode/skills/planning-with-files/scripts/session-catchup.py --metadata $(pwd)# Windows PowerShell python $env:USERPROFILE\.mastracode\skills\planning-with-files\scripts\session-catchup.py --metadata (Get-Location)这些显式命令只读取同项目的本地会话记录且仅输出聚合计数。--replay只能用于刻意、有界、以 nonce 为框架的回放。裸调用bare invocation与自动 hooks不会检查 Agent 的会话存储。仓库中的 scripts/session-catchup.py 实现了会话感知的扫描逻辑先找到所有会话中最近的规划文件更新时间点再收集从该点之后直到当前的对话支持 Claude Code.claude/projects/与 OpenCode 等多种 IDE 的检测。其安全边界在 skills/planning-with-files/SKILL.md 的 Security Boundary 一节有明确描述--metadata只输出聚合计数、不包含任何对话/工具命令/路径字节--replay为可选且受限回放内容一律视为不可信数据且该技能没有任何网络上传路径。团队工作流工作区技能推荐工作区安装.mastracode/skills/的优势团队每个人都拥有该技能跨项目保持一致的规划方式随仓库进行版本控制通过 git 同步变更。个人技能个人安装~/.mastracode/skills/的优势在你的所有项目中可用切换团队后依然保留不与队友共享。两种安装方式中 hooks 的读取位置不同工作区安装时钩子来自项目根目录的.mastracode/hooks.json个人安装时来自~/.mastracode/hooks.json——排查钩子问题时需要区分。常见问题排查技能未激活确认文件存在ls ~/.mastracode/skills/planning-with-files/SKILL.md重启 Mastra Code——技能在启动时扫描使用触发短语plan out、break down、organize、track progress。Hooks 未运行Mastra Code 从hooks.json读取钩子而不是从 SKILL.md frontmatter。请确认检查项目根目录存在.mastracode/hooks.json工作区安装或~/.mastracode/hooks.json个人安装确认文件包含 PreToolUse、PostToolUse 和 Stop 条目添加或修改 hooks.json 后重启 Mastra Code。已在用 Claude Code没有冲突。Mastra Code 优先检查.mastracode/skills/然后回退到.claude/skills/。两者可以同时安装。延伸阅读快速入门指南5 步上手规划流程工作流图解三文件协作与 hooks 交互的可视化说明Manus 原则参考技能背后的核心设计理念真实示例完整走查示例故障排查更多常见问题。【免费下载链接】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），仅供参考