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  → 直接执行 + 其他匹配的 Skill/MCP
  │
  ├─ node flow.js checkpoint ──→ 记录产出 + 知识提取 + git commit
  │
  ├─ .workflow/（本地临时运行态）
  │   ├─ progress.md        # 任务状态表（主Agent读）
  │   ├─ tasks.md           # 完整任务定义
  │   ├─ config.json        # 运行态文件（兼容旧路径，推荐迁移）
  │   └─ context/
  │       ├─ summary.md     # 滚动摘要
  │       └─ task-xxx.md    # 各任务详细产出
  │
  └─ .flowpilot/（本地持久化产品状态）
      ├─ config.json        # 持久配置（maxRetries/hints/verify/hooks 等）
      ├─ memory.json        # 长期记忆库（知识条目 + 标签 + 时间戳）
      └─ evolution/         # 进化历史（reflect/experiment/review 记录）

四层记忆机制

flow next 自动拼装：summary + 依赖任务的 context → 注入子Agent prompt。 主Agent 永远只读 progress.md，上下文占用极小。

长期记忆系统

跨工作流的持久化知识库，存储在 .flowpilot/memory.json。

写入 → 存储 → 检索 → 注入

checkpoint（成功/失败）
    ↓
知识提取（LLM 智能提取 或 规则引擎降级）
    ↓
存储到 .flowpilot/memory.json（带标签、时间戳、来源）
    ↓
next/nextBatch 时语义检索相关记忆
    ↓
带 [source] 标签注入子Agent上下文

知识提取

子Agent 在 checkpoint 摘要中使用标签标记关键知识：

提取路径：

• 有 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN → LLM 智能提取 + 去重（Claude Haiku）
• 无 API key → 规则引擎匹配标签（零依赖降级）

检索引擎

• BM25 稀疏向量 + 前向最大匹配中文分词 + 技术词表
• 有 EMBEDDING_API_KEY 时额外启用 Dense embedding 双路融合
• MMR 重排序去冗余 + 时间衰减（半衰期 30 天）
• 架构类和决策类记忆不衰减，永久保留

使用方式

• 自动注入：next/next --batch 时自动检索并注入相关记忆
• 手动查询：node flow.js recall <关键词>

命令参考

node flow.js init [--force]       # 初始化/接管项目
node flow.js next [--batch]       # 获取下一个/所有可并行任务
node flow.js checkpoint <id>      # 记录任务完成（stdin/--file/内联）[--files f1 f2 ...]
node flow.js skip <id>            # 手动跳过任务
node flow.js review               # 标记code-review已完成 + 进化自愈检查
node flow.js finish               # 智能收尾（验证+总结；未review或最终commit未成功时不会结束工作流）
node flow.js status               # 查看全局进度
node flow.js resume               # 中断恢复
node flow.js add <描述> [--type]  # 追加任务（frontend/backend/general）
node flow.js recall <关键词>      # 检索历史记忆（BM25 + Dense 双路）
node flow.js evolve               # 接收 CC sub-agent 反思结果并应用进化

配套 npm 脚本：

• npm run test:run：一次性执行完整 Vitest 测试集
• npm run test:smoke：执行工作流边界相关冒烟测试，适合改命令/文档后快速验证

执行流程（全自动）

node flow.js init
       ↓
  协议嵌入 instruction file（`Claude Code` 默认 `CLAUDE.md`，`Codex / Cursor / Other` 默认 `AGENTS.md`，旧项目兼容原有文件）+ 按客户端选择注入额外配置
       ↓
  用户描述需求 / 丢入开发文档
       ↓                          ← 以下全自动，无需人工介入
  ┌─→ flow next (--batch) ──→ 获取任务+上下文+相关记忆
  │        ↓
  │   子Agent执行（自动选插件）
  │        ↓
  │   flow checkpoint ──→ 知识提取 → 记录产出 + git commit
  │        ↓
  └── 还有任务？──→ 是 → 循环
                   否 ↓
             flow finish ──→ build/test/lint
                   ↓
              code-review ──→ flow review（进化自愈检查）
                   ↓
              flow evolve（可选，CC 深度反思）
                   ↓
             flow finish ──→ final commit + auto Reflect + Experiment → idle

错误处理

• 任务失败 — 自动重试 3 次，3 次仍失败则标记 failed 并跳过
• 级联跳过 — 依赖了失败任务的后续任务自动标记 skipped
• 中断恢复 — active 状态的任务在干净场景下会重置为 pending；若检测到工作流期间新增的未处理变更，工作流进入 reconciling。只有列出的 task-owned 变更适合 adopt / restart；归属未明的文件必须先人工确认，不能整文件 git restore
• 验证失败 — flow finish 报错后可派子Agent修复，再次 finish
• 最终提交拒绝 — flow finish 在 verify/review 之后还会检查 dirty baseline、checkpoint owned files、以及 instruction file（AGENTS.md / 兼容旧 CLAUDE.md）、.claude/settings.json / .gitignore 的 cleanup 结果；只要边界不安全，或最终 commit 没真正成功，就拒绝结束工作流并列出下一步处理信息。用户手动改动应被视为 user-owned/baseline，不会被 FlowPilot 自动恢复，也不应被误判为 task residue
• 循环检测 — 三策略防护（重复失败/乒乓/全局熔断），自动注入警告到下一任务
• 心跳自检 — 活跃任务超时（>30分钟）告警，记忆膨胀（>100条）自动压缩
• 进化回滚 — 实验导致指标恶化时，review 自动回滚到实验前快照

环境变量

所有环境变量均为可选，无 API key 也能完整运行。

降级策略：

• 无 ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN → 知识提取降级到规则引擎匹配标签
• 无 EMBEDDING_API_KEY → 检索仅用 BM25 稀疏向量（仍然有效）

开发

cd FlowPilot
npm install
npm run build        # 构建 → dist/flow.js
npm run dev          # 开发模式
npm test             # 运行测试

源码结构

src/
├── main.ts                          # 入口，依赖注入
├── domain/
│   ├── types.ts                     # TaskEntry, ProgressData 等类型
│   ├── task-store.ts                # 任务状态管理（纯函数）
│   ├── workflow.ts                  # WorkflowDefinition 定义
│   └── repository.ts               # 仓储接口
├── application/
│   └── workflow-service.ts          # 核心用例（16个）
├── infrastructure/
│   ├── fs-repository.ts             # 文件系统 + 协议嵌入 + Hooks注入
│   ├── markdown-parser.ts           # 任务Markdown解析（兼容FlowPilot/OpenSpec双格式）
│   ├── memory.ts                    # 智能记忆引擎（BM25 + 向量索引 + RRF + MMR + LRU缓存）
│   ├── extractor.ts                 # 知识提取（LLM + 规则引擎降级）
│   ├── truncation.ts                # CJK感知智能截断
│   ├── loop-detector.ts             # 三策略循环检测
│   ├── history.ts                   # 历史分析 + 三阶段自我进化（Reflect/Experiment/Review）
│   ├── git.ts                       # 自动git提交（子模块感知）
│   ├── verify.ts                    # 多语言项目验证（8种）
│   ├── hooks.ts                     # 生命周期钩子
│   ├── protocol-template.ts         # 工作流协议模板（双路径：标准/OpenSpec）
│   └── logger.ts                    # 结构化日志（JSONL）
└── interfaces/
    ├── cli.ts                       # 命令路由
    ├── formatter.ts                 # 输出格式化
    └── stdin.ts                     # stdin读取

依赖方向

interfaces → application → domain ← infrastructure

运行时零外部依赖，只用 Node.js 内置模块（fs, path, child_process, crypto, https）。LLM 智能提取、长期记忆双路检索、自我进化反思均为可选增强，通过环境变量（ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN/EMBEDDING_API_KEY）按需启用，无 API key 时自动降级到规则引擎。

开源许可

本项目基于 MIT License 开源。

Copyright (c) 2025-2026 FlowPilot Contributors

QQ群交流

欢迎加入 FlowPilot交流 QQ 群交流使用问题、工作流实践和改进建议。

• 群号：760311090
• 群主 QQ：879360806

卸载 FlowPilot

如果你之后不想继续在某个项目里使用 FlowPilot，只需要删除它带入或运行时生成的文件：

• flow.js（你复制进项目的单文件工具）
• instruction file：
  • Claude Code 模式通常是 CLAUDE.md
  • Codex / Cursor / Other 模式通常是 AGENTS.md
  • 兼容旧项目时会继续复用原有 instruction file
  • snow-cli 模式下还可能有 ROLE.md
• .claude/settings.json（如果是 FlowPilot 在 Claude Code 模式下生成的）
• .workflow/（本地临时运行态）
• .flowpilot/（本地持久状态）

常见做法：

rm -rf flow.js AGENTS.md CLAUDE.md ROLE.md .claude/settings.json .workflow .flowpilot

注意：

• 如果 AGENTS.md / CLAUDE.md / ROLE.md 里已经被你手动加入了项目自己的长期说明，请先保留需要的内容
• 如果 .claude/ 目录因为删掉 settings.json 变成空目录，也可以一起删除
• 如果你只想停用工作流而保留 instruction file，也可以只删 flow.js、.claude/settings.json、.workflow/、.flowpilot/