FlowPilot

English

一个文件，一句开发需求，全自动开发。

把 flow.js 丢进任何项目，打开你选择的客户端（Claude Code / Codex / Cursor / snow-cli 等）描述你要做什么，然后去喝杯咖啡。 回来的时候，代码写好了，测试跑完了，git 也提交了。

新增说明：现已兼容 Claude Code、Codex、Cursor、snow-cli 和其他客户端；init 时可直接选择目标客户端并生成对应的 instruction file / 配置。

新增说明：内置 instruction file / 客户端增强模板现已将输出风格作为硬约束，要求回答遵循：先结论、后细节、简洁直给、终端友好；同时补强了依赖分析、并行调度、危险操作确认等执行约束，FlowPilot 自己的终端输出也会强化分组、状态图标与下一步提示。 这次升级不仅包含表现层优化：更友好的话术、更清晰的分组、更直观的终端排版之外，也同步增强了中断恢复、收尾边界、实时进度上报与验证策略。使用前请以最新文档和命令实际输出为准。

多客户端全自动并行开关：

• Claude Code：开启 Agent Teams
• Codex：在 ~/.codex/config.toml 中设置 multi_agent = true，建议直接用 codex --yolo
• Cursor：开启 Agents，并将 Auto-Run Mode 调成 Run Everything

Codex 增强规则预览：

• 标准执行流程：任务分析 → 并行调度与子任务下发 → 结果汇总 → 递归迭代
• 并行约束：无前置依赖且无写冲突的任务优先并发；单轮最多同时下发 50 个子任务
• 子任务契约：下发子任务时必须明确 代理名称 / 任务定义 / 执行动作 / 预期结果

快速开始

# 1. 构建并复制到你的项目
cd FlowPilot && npm install && npm run build
cp dist/flow.js /your/project/

# 2. 初始化（会显示客户端选项）
cd /your/project
node flow.js init

# 3. 启动客户端，直接描述需求
claude --dangerously-skip-permissions

初始化时会直接显示客户端选项：

• Claude Code：生成 CLAUDE.md + .claude/settings.json
• Codex：生成 AGENTS.md，并附加 Codex 平台增强规则（并行调度 + 子任务契约）
• Cursor / Other：生成通用版 AGENTS.md
• snow-cli：生成 AGENTS.md + ROLE.md

中断后直接继续：

# Claude Code
claude --dangerously-skip-permissions --continue

# Codex
codex --yolo

• Claude Code：推荐直接用 --continue / --resume
• Codex：重新进入项目目录后启动 codex --yolo，然后说「继续任务」
• Cursor：重新打开项目，在原会话或新会话中说「继续任务」
• snow-cli / 其他客户端：重新进入项目目录，恢复或新开会话后说「继续任务」

需要更完整说明时，再往下看「初始化与客户端选项」「执行流程」「错误处理」。

最近更新

🔥 OpenSpec 集成 — 任务解析器兼容 OpenSpec checkbox 格式，双路径协议自动选择标准/OpenSpec 规划流程，支持 tasks.md 自动发现与用户确认

🧠 长期记忆系统 — checkpoint 自动提取知识存入 .flowpilot/memory.json，BM25 + Dense 双路检索，MMR 重排序 + 时间衰减，next 时自动注入相关记忆到子Agent上下文

🔄 自我进化引擎（完整闭环） — Reflect → Experiment → Review 三阶段循环，成功/失败均触发进化，参数写入 config 被工作流真正消费，退化自动回滚

🔥 子代理执行可视化增强 — 协议层新增子代理进度上报机制（建议每 30 秒更新 phase），formatter 实时显示任务激活时长（⏱️ X分X秒），超过 5 分钟显示超时预警（⚠️ 超时）

🔥 Codex 并发上限调整为 50 — 通过分析 Codex CLI 源码，发现默认并发上限为 6，需在 ~/.codex/config.toml 中配置：

[agents]
max_threads = 50

为什么用 FlowPilot

传统 CC 开发：你是项目经理——拆任务、分配、跟进、验收，全程盯着。 FlowPilot：你是甲方——只说要什么，剩下的全自动。

和主流方案的区别

vs Claude Code 原生子Agent（Task 工具）

CC 自带 Task 工具能派子Agent，但它是无状态的——上下文绑定在当前对话，关窗口就没了。FlowPilot 在此之上解决了三个原生做不到的事：

1. 不怕中断：所有状态持久化在磁盘，compact、崩溃、关窗口都无所谓，resume 一键继续
2. 不怕膨胀：主Agent 永远只读 progress.md（< 100 行），100 个任务也不会变慢
3. 自动并行：依赖图分析 + 批量派发，不用手动决定谁先谁后

vs OpenSpec（规格驱动框架）

OpenSpec 解决的是「写代码之前怎么把需求想清楚」，产出是 proposal/spec/design 文档。FlowPilot 解决的是「需求清楚之后怎么全自动执行」，产出是可运行的代码和 git 历史。

FlowPilot 的核心优势是端到端自动化——从需求到代码到提交到验证，中间不需要人。OpenSpec 在规划阶段更强，两者已实现集成：

OpenSpec + FlowPilot 集成：FlowPilot 的任务解析器自动兼容 OpenSpec 的 checkbox 格式（- [ ] 1.1 Task），无需格式转换。工作流协议内置双路径：

此外，协议会自动检测项目根目录的 tasks.md 文件并询问用户确认，也支持用户在消息中直接提供任务列表。

30 秒体验

cp dist/flow.js 你的项目/
cd 你的项目
node flow.js init

打开 Claude Code，直接描述需求：

你：帮我做一个电商系统，用户注册、商品管理、购物车、订单支付

（然后就不用管了）

CC 会自动：拆解任务 → 识别依赖 → 并行派发子Agent → 写代码 → checkpoint → git commit → 跑 build/test/lint → 全部完成。

flow finish 现在会真正执行自动验证，而不是停留在“尽力探测”。如果当前工作流根目录本身没有可检测脚本，但只包含一个可识别子项目（例如 FlowPilot/），它会自动进入该子项目执行验证命令；对 vitest 测试脚本也会自动补成 --run，避免 finish 卡在 watch 模式。

核心优势

无限上下文 — 做 100 个任务也不会 compact 丢失

四层记忆架构，主Agent 上下文永远 < 100 行：

子Agent 自行记录产出，主Agent 不膨胀。就算 compact 了，文件还在，恢复即继续。长期记忆跨工作流持久化，上一轮学到的经验自动注入下一轮。

并行开发 — 不是一个个做，是一起做

串行：数据库 → 用户API → 商品API → 用户页 → 商品页    （5轮）
并行：数据库 → [用户API, 商品API] → [用户页, 商品页]   （3轮）

flow next --batch 自动找出所有可并行的任务，主Agent 在同一条消息中派发多个子Agent 同时执行。

万步零偏移 — 中断恢复不丢一步

关窗口、断网、compact、CC 崩溃，随便来：

新窗口 → 说：继续任务 → flow resume
  ├─ 若无待接管变更：重置未完成任务 → 继续
  └─ 若有待处理变更：暂停调度 → adopt / 确认并处理列出的本任务变更后 restart → 再继续

所有状态持久化在文件里，不依赖对话历史。哪怕并行执行中 3 个子Agent 同时中断，恢复后也不会盲目重派；若检测到工作流期间新增但归属未明的变更，FlowPilot 会暂停并要求人工确认，而不是暗示你整文件 git restore。只有列出的 task-owned 变更才适合 adopt 或在处理后 restart。

迭代审查 — 跑完一轮再来一轮，越改越好

一轮工作流全自动跑完后，可以再起一轮新的工作流审查上一轮的产出：检查实现是否偏离需求、补漏洞、提升代码质量。全程耗时极短，多迭代几轮也不费事。对比原生使用 CC Agent Teams 手动调度，效率提升显著，性价比极高——省下来的时间，陪陪家人不好吗？

第一轮：需求 → 全自动实现 → 代码产出
第二轮：审查 → 发现偏离/缺陷 → 自动修补
第三轮：精修 → 代码质量提升 → 收尾验证

自我进化 — 每跑一轮，下一轮更聪明

FlowPilot 内置三阶段有机进化循环，成功和失败均触发进化，结果写入 .flowpilot/config.json，被 maxRetries / hints / verify / hooks 真正消费；历史上曾存在的 parallelLimit 不再参与运行时批次裁剪，也不会被自动进化改写：

finish() 触发：
  Reflect（反思）→ 分析本轮成败模式（失败链、重试热点、类型集中度）
  Experiment（实验）→ 自动调整 config 参数和协议模板，保存完整快照

review() 触发：
  Review（自愈）→ 对比进化前后指标，退化则自动回滚

Finalization 阶段（可选补充）：
  需要额外人工反思时，CC sub-agent + brainstorming 技能深度反思 → node flow.js evolve 应用结果

收尾总结 — 清目录前先把结果说清楚

flow finish 在删除临时工作流目录前，会先完成两件事：

1. 在终端输出本轮工作流最终总结
2. 在 .workflow/final-summary.md 落一份同样的总结，然后再执行清理

总结会列出所有任务，并用下面的标记显示状态：

✓ 已完成
⊘ 已跳过
✗ 已失败
○ 未完成

这样用户在 .workflow/ 被清掉之前，就已经能在终端看见完整结果；同时流程内也可以验证“先总结、后清理”的顺序。需要注意的是：未执行 flow review 时，flow finish 不会结束工作流；即使 review 已完成，也只有最终 commit 真正成功后才会清理 .workflow/ 并回到 idle。若 review 已完成但当前没有待提交文件，FlowPilot 会补一个显式最终收尾提交，以保持“只有 committed 才能结束工作流”的严格语义。

进化结果直接影响工作流行为：

• 成功时：优化重试与经验规则
• 失败时：增加前置检查建议，优化重试与验证策略
• 有 ANTHROPIC_API_KEY 时用 LLM 深度分析，没有则用规则引擎——零依赖约束下的优雅降级

单文件通吃一切 — 零依赖，复制即用

• 单文件 dist/flow.js，当前构建产物约 213KB
• 零运行时依赖，只需 Node.js
• 自动识别 8 种项目类型，收尾时自动跑对应的验证命令，并区分通过 / 跳过 / 未发现命令

文档

• 快速上手 — 不懂原理也能用，3 步开始全自动开发
• 详细使用指南 — 完整命令说明、并行开发技巧、任务设计实战示例

前置准备

建议先安装插件 / 技能，否则多代理和上下文增强能力会降级。

Claude Code 可在 CC 中执行 /plugin 打开插件商店，选择安装：

• superpowers — 需求拆解头脑风暴
• frontend-design — 前端任务
• feature-dev — 后端任务
• code-review — 收尾代码审查
• context7 — 实时查阅第三方库文档

不同客户端的并行 / 自动运行开关：

• Claude Code
  • 在 ~/.claude/settings.json 中添加：

    "env": {
      "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
    }
    

• Codex
  • 在 ~/.codex/config.toml 中加入：

    [agents]
    max_threads = 50          # 子代理并发上限，默认 6
    
    [features]
    multi_agent = true
    

  • 全自动运行建议使用：codex --yolo
• Cursor
  • 在设置的 Agents 中开启 Agents
  • 将 Auto-Run Mode 调成 Run Everything
• 其他客户端
  • 没有统一标准，请先按各自文档自测多代理 / 自动运行能力

node flow.js init 在接管模式下会直接显示客户端选项：

• Claude Code：生成 CLAUDE.md + .claude/settings.json
• Codex：生成 AGENTS.md，并附加 Codex 平台增强规则（如多代理并行调度约定）
• Cursor / Other：生成通用版 AGENTS.md
• snow-cli：生成 AGENTS.md + ROLE.md（两者内容保持一致）

缺失插件会在输出中提醒。

setup/init 写入的 instruction file（Claude Code 默认 CLAUDE.md，Codex / Cursor / Other 默认 AGENTS.md，旧项目继续兼容已有文件）、.claude/settings.json、.gitignore 遵循 ownership-based cleanup：FlowPilot 只清理自己创建或注入的部分，不会自动恢复你的手动改动；cleanup 后若仍有真正的用户残留改动，flow finish 会停在 finishing 并提示你人工处理，而不是把这些用户改动误判成可自动清理的 workflow residue。

默认情况下，FlowPilot 还会在项目 .gitignore 中确保以下本地状态被忽略：.workflow/（本地临时运行态）、.flowpilot/（本地持久化产品状态）、.claude/settings.json（本地集成配置）、.claude/worktrees/（本地工作树目录）。不会忽略整个 .claude/ 目录。

初始化与客户端选项

# 构建单文件
cd FlowPilot && npm install && npm run build

# 自动化验证脚本
npm run test:smoke
npm run test:run

# 复制到任意项目
cp dist/flow.js /your/project/
cd /your/project

# 初始化（显示客户端选项；按客户端生成对应 instruction file）
node flow.js init

# 全自动模式启动 CC，直接描述需求，剩下的全自动
claude --dangerously-skip-permissions

--dangerously-skip-permissions 跳过所有权限确认，实现真正的无人值守。

中断恢复：

claude --dangerously-skip-permissions --continue   # 接续最近一次对话
claude --dangerously-skip-permissions --resume     # 从历史对话列表选择

如果恢复时工作区仍然有未归档变更，resume 会明确告诉你哪些是启动前就存在的 baseline 未归档变更，哪些是由显式 ownership 支撑的 task-owned 变更，哪些是工作流期间新增但归属未明的变更（可能包含你的手动修改/删除）；如果 dirty baseline 缺失，也会直接说明“无法证明这是干净重启，也无法可靠区分用户操作与任务残留”。

架构概览

主Agent（调度器，< 100行上下文）
  │
  ├─ node flow.js next ──→ 返回任务 + 依赖上下文 + 相关记忆
  │
  ├─ 子Agent（Task工具派发）
  │   ├─ frontend → /frontend-design 插件 + 其他匹配的 Skill/MCP
  │   ├─ backend  → /feature-dev 插件 + 其他匹配的 Skill/MCP
  │   └─ general