在 FactoryAI Droid 中集成 planning-with-filesSkills 自动发现、Hook 生命周期与三文件持久规划实战指南【免费下载链接】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本文以 docs/factory.md 为核心讲解如何把 planning-with-files 的文件级持久规划技能安装到 FactoryAI Droid并深入剖析其.factory/skills/自动发现机制、UserPromptSubmit/PreToolUse/PostToolUse/Stop 等 Hook 生命周期以及 task_plan.md、findings.md、progress.md 三文件模式的团队协作用法。读完本文你将掌握两种安装方式、技能自动激活技巧、Hook 背后源码级的运行原理以及如何为团队定制一套可在会话中断后自动恢复进度的规划工作流。一、FactoryAI Droid 为什么需要文件级规划FactoryAI Droid 与大多数编码 Agent 一样工作记忆默认存活在上下文窗口里——上下文一旦被/clear、压缩compaction或崩溃清空任务目标、当前阶段和已积累的调研结论就全部丢失。planning-with-files 的核心思路是把规划状态落盘用task_plan.md、findings.md、progress.md三个 Markdown 文件充当 Agent 的磁盘工作记忆配合生命周期 Hook 在每轮对话开始前把规划上下文重新注入窗口。FactoryAI Droid 支持从.factory/skills/目录自动发现技能Skills无需手工注册。这意味着把技能文件放进仓库或用户目录后Droid 会在任务描述匹配时自动调用它而不需要任何斜杠命令。二、安装两种官方方式方法一Workspace 安装推荐团队共享把技能提交进项目仓库全团队随代码同步获得该技能# 在你的项目仓库中 git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files # 将 Factory 技能复制到你的仓库 cp -r /tmp/planning-with-files/.factory . # 提交以与团队共享 git add .factory/ git commit -m Add planning-with-files skill for Factory Droid git push # 清理 rm -rf /tmp/planning-with-files提交后团队中所有使用 FactoryAI Droid 的成员都会自动获得该技能。这种方式的优势在于技能随仓库版本化、可审计、改动通过 git 同步到每一个人。方法二个人安装仅本人使用如果只想自己使用不污染项目仓库# 克隆仓库 git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files # 复制到个人 Factory 技能目录 mkdir -p ~/.factory/skills cp -r /tmp/planning-with-files/.factory/skills/planning-with-files ~/.factory/skills/ # 清理 rm -rf /tmp/planning-with-files个人安装让技能跨项目可用即使切换团队也不会丢失缺点是不与队友共享。安装验证重启 FactoryAI Droid 会话后技能会在你处理复杂任务时自动激活。从仓库源码可以确认这个个人路径是被 Hook 调度器显式支持的在 .factory/skills/planning-with-files/SKILL.md 的 frontmatter 中每个 Hook 的命令都包含候选路径查找链其中明确列出$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh与文档中的个人安装路径完全一致。仓库测试 tests/test_skill_hook_dispatch_parity.py 同样把.factory映射到$HOME/.factory/skills/planning-with-files/scripts/验证了这条安装路径的分发一致性。三、技能如何自动激活FactoryAI Droid 会扫描任务描述在以下场景自动激活该技能提到复杂任务complex task或多步骤项目multi-step project请求规划或组织planning / organization开始研究型任务research tasks项目需要超过 5 个步骤提高激活命中率的触发短语在请求中使用以下措辞可以显著提高自动激活概率Create a task plan for...为……创建任务计划This is a multi-step project...这是一个多步骤项目……I need planning for...我需要为……做规划Help me organize this complex task...帮我组织这个复杂任务……示例请求I need to build a REST API with authentication, database integration, and comprehensive testing. This is a complex multi-step project that will require careful planning.FactoryAI Droid 会自动调用planning-with-files并创建三个规划文件。四、技能激活后创建的三文件结构文件用途位置task_plan.md阶段Phases、进度、决策项目根目录findings.md研究结果、发现项目根目录progress.md会话日志、测试结果项目根目录仓库中随技能一起分发的是模板文件位于.factory/skills/planning-with-files/templates/templates/task_plan.md — 阶段跟踪模板templates/findings.md — 研究存储模板templates/progress.md — 会话日志模板以task_plan.md模板为例其结构包含## Goal一句话目标、## Next Step下一步动作指针、## Current Phase当前阶段、## Phases3~7 个可验证阶段每个阶段用- [ ]复选框加**Status:** pending / in_progress / complete标记进度以及## Key Questions、## Decisions Made、## Errors Encountered等区块。这套结构不是随意设计的——状态值pending/in_progress/complete会被 scripts/check-complete.sh 用grep精确匹配用于完成度统计和 Stop 门控因此模板注释明确要求使用这三个固定状态值。findings.md模板则包含## Requirements、## Research Findings、## Technical Decisions、## Issues Encountered、## Resources和## Visual/Browser Findings其中最后一项专门用于把图片、PDF、图表等视觉信息在丢失前转化为文本。这与技能中的2-Action Rule直接呼应。五、使用模式从启动到收尾的完整循环1. 启动复杂任务用复杂度指示词描述任务Im building a user authentication system. This is a multi-phase project requiring database setup, API endpoints, testing, and documentation.2. 技能自动激活FactoryAI Droid 调用planning-with-files并创建规划文件。3. 按阶段推进激活后 AI 会创建带阶段的task_plan.md随工作完成更新进度把调研存入findings.md在progress.md记录操作在重大决策前重新读取规划文件4. 全程追踪所有重要信息都写入磁盘而不是留在上下文窗口里。在 v3 及以上版本中初始化脚本 scripts/init-session.sh 还支持更多模式直接运行./init-session.sh Backend Refactor会创建.planning/日期-slug/隔离规划目录并写入.planning/.active_plan--autonomous启用自主模式写入.mode标记、随机 nonce、自动对计划做 SHA-256 公证--gated在自主模式基础上额外启用完成门控Stop 门。这些能力可以让 FactoryAI Droid 的会话在并行多任务时互不干扰——每个任务有自己的规划目录用export PLAN_IDid把终端钉在指定计划上。六、Hook 生命周期让规划机械化而非靠自觉FactoryAI Droid 支持 hooks——在生命周期事件中自动执行 shell 命令的机制。技能随附的 SKILL.md 中注册了以下 Hookv2.23.0 引入当前仓库版本为 v3.17.0已扩展至 5 个事件Hook 事件作用UserPromptSubmit检测活动计划并提醒读取规划文件PreToolUse在 Write/Edit/Bash/Read 操作前读取task_plan.md前 30 行PostToolUse文件变更后提醒更新progress.mdStop停止前运行check-complete.sh验证所有阶段是否完成PreCompactv3 新增上下文压缩前提醒刷新进度这些 Hook 在复制.factory/目录后即自动生效无需额外配置。源码视角Hook 如何被调度从 .factory/skills/planning-with-files/SKILL.md 的 frontmatter 可以看到所有事件都通过一个统一的候选路径查找链定位scripts/skill-hook.sh然后按事件分发UserPromptSubmit直接输出注入器injector的 stdout作为模型上下文注入即BEGIN-PWF-DATA框架的计划数据块PreToolUse匹配Write|Edit|Bash|Read|Glob|Grep把注入结果序列化为hookSpecificOutput.additionalContextJSONPostToolUse匹配Write|Edit先校验计划有效性validate上下文返回PWF_PLAN_ACCEPTED_V1再通过 turn-marker 缓存做到每轮只提醒一次Stop保留宿主传入的原始 JSON用于识别stop_hook_active防止递归续跑并把 stdin 原样交给gate-stop.sh或check-complete.sh --gate完成门控判断。注入器本身scripts/inject-plan.sh用BEGIN-PWF-DATA框架封装计划块并带 kind、nonce、bytes、sha256 等元数据pretool上下文只注入计划头部head -30兼顾上下文成本与目标保持。从 v3.17.0 起同一逻辑还有一个单进程 Python 孪生实现inject-plan.pyPWF_FAST_PATH0可强制走 shell 参考链路两者输出字节级一致。完成门控的判定逻辑check-complete.sh是完成验证的核心它统计### Phase标题数作为阶段总数同时对**Status:**与[inline]两种状态格式按字段取大值计数避免混用格式时漏判in_progress阶段。在--gate模式下只有当所有条件同时成立才会真正阻塞停止plan-dir/.mode存在且包含gate显式选择门控且项目根的.mode是下限slug 计划只能加严不能放松存在in_progress阶段而非单纯complete totalstdin 的 Stop JSON 未设置stop_hook_activetrue阻塞计数器.stop_blocks未达到上限PWF_GATE_CAP默认 20ledger 行数自上次阻塞以来有推进防停滞死循环。任一条件不满足即回退为告警输出并放行停止确保计划未完成永远不会单独困住一个会话。七、技能内置的行为准则3-Strike 错误协议出错时 AI 依次执行第 1 次尝试诊断并修复第 2 次尝试换一种方法第 3 次尝试更广泛地重新思考3 次失败后上报给你这个协议在 SKILL.md 中有完整展开第 2 次尝试明确要求绝不重复完全相同的失败动作第 3 次尝试要求质疑假设、寻找新方案、考虑更新计划失败 3 次后必须向用户说明尝试过程与具体错误。2-Action 规则每执行 2 次搜索/查看操作后发现必须保存到findings.md——防止视觉/多模态信息丢失。对应模板中## Visual/Browser Findings区块的设计意图。Read Before Decide重大决策前AI 重新读取规划文件以刷新目标——防止长会话中的目标漂移goal drift。这与每轮注入机制一起构成了对抗上下文腐烂context rot的双重防线。八、团队工作流对比维度Workspace 技能.factory/skills/个人技能~/.factory/skills/团队覆盖全员可用仅本人规划一致性跨项目一致个人行为版本控制随仓库 git 管理无变更同步通过 git 同步需手动更新跨团队保留换团队即失效永久保留Workspace 安装被文档推荐为首选正是因为它把规划技能变成团队基础设施的一部分。九、为什么这样设计能奏效Manus 式上下文工程这是 Manus AI 成功背后的模式Markdown is my working memory on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables. — Manus AI核心洞察上下文窗口 RAM易失文件系统 磁盘持久。重要信息要写到磁盘而不是留在上下文里。planning-with-files 正是把这句话工程化为可复制的技能三文件是工作记忆Hook 是自动化的记忆刷新机制/clear、压缩、崩溃之后新会话通过读取磁盘文件即可恢复到当前阶段而不是从零重新向用户索要任务描述。十、故障排查技能未激活添加触发短语在请求中使用 complex task、multi-step、planning显式说明提及阶段数量或复杂度重启 DroidFactoryAI Droid 在重启时重新扫描技能文件未创建检查当前目录是否可写是否存在文件权限问题Droid 是否有文件系统访问权限需要模板模板位于Workspace.factory/skills/planning-with-files/templates/个人~/.factory/skills/planning-with-files/templates/复制到项目根目录后按需定制。十一、高级定制修改技能本身编辑.factory/skills/planning-with-files/SKILL.md可定制修改 description 中的触发短语调整规划模式添加团队专属规则注意SKILL.md 的 frontmatter 中description字段同时承担技能发现与 Hook 分发两重职责修改时需保持 YAML 结构合法并避免在命令字段中使用裸---早期版本曾因此破坏 frontmatter 解析相关教训见 README.md 发布记录。添加自定义模板把自定义模板放入.factory/skills/planning-with-files/templates/FactoryAI Droid 会自动引用它们。仓库中该目录已包含default与analytics两套模板analytics_task_plan.md、analytics_findings.mdinit-session.sh通过--template analytics参数选择后者适用于数据探索类会话。十二、环境变量与进阶控制在 FactoryAI Droid 环境中以下环境变量可进一步控制规划行为均为可选变量作用PLAN_IDslug把会话钉在.planning/下某个具体计划上并行多任务隔离PWF_PLAN_ROOT绝对路径用绝对路径绑定项目根适用于 cwd 是共享父目录的场景PLANNING_DISABLED1单次调用级退出开关跳过所有计划读取一次性/CI 会话PWF_GATE_CAPNStop 门最大连续阻塞次数默认 20PWF_INJECTsmart用目标下一步当前阶段进行中阶段全文最近三条决策替换固定head -50注入窗口PWF_FAST_PATH0强制 Hook 走参考 shell 链路而非inject-plan.py快速路径十三、进一步阅读快速开始指南 — 5 步完成首次规划会话工作流详解 — 日常使用、计划生命周期、主题交接安装指南 — 全部安装路径与路由矩阵故障排查 — Hook 静默失效时的/plan-doctor自检Manus 原则参考 — 三文件模式背后的思想来源真实示例 — 实际会话案例技能本体.factory/skills/planning-with-files/SKILL.md测试佐证tests/test_skill_hook_dispatch_parity.py、tests/test_public_capability_disclosure.py【免费下载链接】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），仅供参考