6bnbn

FlowPilot

# FlowPilot [English](README.en.md) **一个文件，一句开发需求，全自动开发。** 把 `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` 个子任务 > - 子任务契约：下发子任务时必须明确 `代理名称 / 任务定义 / 执行动作 / 预期结果` ## 快速开始 ```bash # 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` 中断后直接继续： ```bash # 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 被工作流真正消费，退化自动回滚 | 模块 | 评分 | 借鉴内容 | |------|------|----------| | 记忆系统 | 100% | BM25 稀疏向量（FNV-1a 20-bit）、Dense Vector 检索、RRF 三源融合、Multimodal 嵌入、10语言分词、TTL+LRU 缓存 | | 循环检测 | 100% | 重复失败/乒乓/全局熔断三策略 + FNV-1a 哈希 + 警告注入（独创） | | 历史进化 | 100% | 三阶段循环（Reflect→Experiment→Review）、心跳自检、预快照回滚、协议自修改、活跃时间窗口 | | 知识提取 | 95% | LLM + 规则引擎双路径、标签提取、决策模式匹配、30+ 技术栈检测 | --- 🔥 **子代理执行可视化增强** — 协议层新增子代理进度上报机制（建议每 30 秒更新 phase），formatter 实时显示任务激活时长（⏱️ X分X秒），超过 5 分钟显示超时预警（⚠️ 超时） 🔥 **Codex 并发上限调整为 50** — 通过分析 Codex CLI 源码，发现默认并发上限为 6，需在 `~/.codex/config.toml` 中配置： ```toml [agents] max_threads = 50 ``` --- ## 为什么用 FlowPilot 传统 CC 开发：你是项目经理——拆任务、分配、跟进、验收，全程盯着。 FlowPilot：你是甲方——只说要什么，剩下的全自动。 | 传统 CC 开发 | FlowPilot 开发 | |-------------|---------------| | 手动拆任务、一个个跟 CC 说 | 说一句需求，自动拆解 10+ 个任务 | | 上下文满了要从头来 | 新窗口一句话，从断点继续，零丢失 | | 一次只能做一件事 | 多个子Agent并行开发，速度翻倍 | | 做到一半忘了之前的决策 | 四层记忆 + 跨工作流长期记忆，100个任务也不迷路 | | 每次手动 git commit | 每完成一个任务自动提交，收尾自动跑测试 | | 换个项目要重新配置 | 单文件复制即用，Node/Rust/Go/Python/Java/C++/Makefile 通吃 | | 每次都犯同样的错 | 自我进化引擎，每轮自动反思优化，越跑越聪明 | ### 和主流方案的区别 **vs Claude Code 原生子Agent（Task 工具）** CC 自带 Task 工具能派子Agent，但它是**无状态**的——上下文绑定在当前对话，关窗口就没了。FlowPilot 在此之上解决了三个原生做不到的事： 1. **不怕中断**：所有状态持久化在磁盘，compact、崩溃、关窗口都无所谓，`resume` 一键继续 2. **不怕膨胀**：主Agent 永远只读 progress.md（< 100 行），100 个任务也不会变慢 3. **自动并行**：依赖图分析 + 批量派发，不用手动决定谁先谁后 | | 原生 Task | FlowPilot | |---|-----------|-----------| | 状态持久化 | 对话内，compact 即丢 | 磁盘文件，永不丢失 | | 中断恢复 | 依赖对话历史，compact 后状态易丢 | 磁盘恢复，`resume` 一键继续 | | 并行调度 | 手动安排 | 自动依赖分析，批量派发 | | 上下文膨胀 | 主Agent越做越慢 | 四层记忆，主Agent < 100 行 | | git 提交 | 手动 | 每个任务自动 commit | | 收尾验证 | 无 | 自动 build/test/lint | | 跨会话记忆 | 无，每次从零开始 | 长期记忆库，自动检索注入 | | 自我优化 | 无 | 三阶段进化，越跑越聪明 | **vs OpenSpec（规格驱动框架）** [OpenSpec](https://github.com/Fission-AI/OpenSpec) 解决的是「写代码之前怎么把需求想清楚」，产出是 proposal/spec/design 文档。FlowPilot 解决的是「需求清楚之后怎么全自动执行」，产出是可运行的代码和 git 历史。 | | OpenSpec | FlowPilot | |---|---------|-----------| | 定位 | 规划层：需求 → 规格文档 | 执行层：任务 → 代码 → 提交 | | 产出 | Markdown 文档 | 可运行代码 + git 历史 | | 执行 | 文档写完仍需人工/AI 逐个实现 | 全自动派发、并行执行、自动提交 | | 适用范围 | 工具无关，20+ AI 助手 | 面向 Claude Code / Codex / Cursor / snow-cli 等客户端，深度集成 | FlowPilot 的核心优势是**端到端自动化**——从需求到代码到提交到验证，中间不需要人。OpenSpec 在规划阶段更强，两者已实现集成： **OpenSpec + FlowPilot 集成**：FlowPilot 的任务解析器自动兼容 OpenSpec 的 checkbox 格式（`- [ ] 1.1 Task`），无需格式转换。工作流协议内置双路径： | 路径 | 触发条件 | 流程 | |------|---------|------| | Path A（标准） | 默认 | brainstorming → 生成任务 → `flow.js init` | | Path B（OpenSpec） | 项目有 `openspec/` + CLI 可用 | `/opsx:new` → `/opsx:ff` → `cat tasks.md \| flow.js init` | 此外，协议会自动检测项目根目录的 `tasks.md` 文件并询问用户确认，也支持用户在消息中直接提供任务列表。 ## 30 秒体验 ```bash 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 行： | 层级 | 谁读 | 内容 | |------|------|------| | progress.md | 主Agent | 极简状态表（一行一个任务） | | task-xxx.md | 子Agent | 每个任务的详细产出和决策 | | summary.md | 子Agent | 滚动摘要（超10个任务自动压缩） | | memory.json | 子Agent | 跨工作流长期记忆（自动检索注入） | 子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 应用结果 ``` | 阶段 | 触发时机 | 做什么 | |------|---------|--------| | Reflect | finish 末尾 | LLM 或规则分析工作流统计，输出 findings + experiments | | Experiment | finish 末尾 | 自动调整 config 参数和协议模板，保存完整快照 | | Review | review 时 | 对比进化前后指标，恶化自动回滚，检查配置完整性 | ### 收尾总结 — 清目录前先把结果说清楚 `flow finish` 在删除临时工作流目录前，会先完成两件事： 1. 在终端输出本轮工作流最终总结 2. 在 `.workflow/final-summary.md` 落一份同样的总结，然后再执行清理 总结会列出所有任务，并用下面的标记显示状态： ```text ✓ 已完成 ⊘ 已跳过 ✗ 已失败 ○ 未完成 ``` 这样用户在 `.workflow/` 被清掉之前，就已经能在终端看见完整结果；同时流程内也可以验证“先总结、后清理”的顺序。需要注意的是：未执行 `flow review` 时，`flow finish` 不会结束工作流；即使 `review` 已完成，也只有最终 commit 真正成功后才会清理 `.workflow/` 并回到 idle。若 `review` 已完成但当前没有待提交文件，FlowPilot 会补一个显式最终收尾提交，以保持“只有 committed 才能结束工作流”的严格语义。 进化结果直接影响工作流行为： | 参数 | 作用 | |------|------| | `maxRetries` | checkpoint 失败时决定重试次数 | | `hints` | 注入到子Agent上下文作为"进化建议" | - 成功时：优化重试与经验规则 - 失败时：增加前置检查建议，优化重试与验证策略 - 有 `ANTHROPIC_API_KEY` 时用 LLM 深度分析，没有则用规则引擎——零依赖约束下的优雅降级 ### 单文件通吃一切 — 零依赖，复制即用 - 单文件 `dist/flow.js`，当前构建产物约 `213KB` - 零运行时依赖，只需 Node.js - 自动识别 8 种项目类型，收尾时自动跑对应的验证命令，并区分通过 / 跳过 / 未发现命令 ## 文档 - [快速上手](docs/quick-start.md) — 不懂原理也能用，3 步开始全自动开发 - [详细使用指南](docs/usage-guide.md) — 完整命令说明、并行开发技巧、任务设计实战示例 ## 前置准备 建议先安装插件 / 技能，否则多代理和上下文增强能力会降级。 `Claude Code` 可在 CC 中执行 `/plugin` 打开插件商店，选择安装： - `superpowers` — 需求拆解头脑风暴 - `frontend-design` — 前端任务 - `feature-dev` — 后端任务 - `code-review` — 收尾代码审查 - `context7` — 实时查阅第三方库文档 不同客户端的并行 / 自动运行开关： - `Claude Code` - 在 `~/.claude/settings.json` 中添加： ```json "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } ``` - `Codex` - 在 `~/.codex/config.toml` 中加入： ```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/` 目录。 ## 初始化与客户端选项 ```bash # 构建单文件 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` 跳过所有权限确认，实现真正的无人值守。 中断恢复： ```bash 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 记录） ``` ## 四层记忆机制 | 层级 | 文件 | 读者 | 内容 | |------|------|------|------| | 第一层 | progress.md | 主Agent | 极简状态表（ID/标题/状态/摘要） | | 第二层 | context/task-xxx.md | 子Agent | 每个任务的详细产出和决策记录 | | 第三层 | context/summary.md | 子Agent | 滚动摘要（技术栈/架构决策/已完成模块） | | 第四层 | .flowpilot/memory.json | 子Agent | 跨工作流长期记忆（标签化知识条目） | `flow next` 自动拼装：summary + 依赖任务的 context → 注入子Agent prompt。 主Agent 永远只读 progress.md，上下文占用极小。 ## 长期记忆系统 跨工作流的持久化知识库，存储在 `.flowpilot/memory.json`。 ### 写入 → 存储 → 检索 → 注入 ``` checkpoint（成功/失败） ↓ 知识提取（LLM 智能提取 或 规则引擎降级） ↓ 存储到 .flowpilot/memory.json（带标签、时间戳、来源） ↓ next/nextBatch 时语义检索相关记忆 ↓ 带 [source] 标签注入子Agent上下文 ``` ### 知识提取 子Agent 在 checkpoint 摘要中使用标签标记关键知识： | 标签 | 用途 | 示例 | |------|------|------| | `[REMEMBER]` | 通用经验 | `[REMEMBER] Vite 需要配置 resolve.alias 才能用 @ 路径` | | `[DECISION]` | 架构/技术决策 | `[DECISION] 选用 Zustand 而非 Redux，因为项目规模小` | | `[ARCHITECTURE]` | 系统架构 | `[ARCHITECTURE] 采用 monorepo + turborepo 结构` | 提取路径： - 有 `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 <关键词>` ## 命令参考 ```bash 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` | LLM 智能提取 + 进化反思 | 启用 Claude Haiku 进行知识提取和去重 | | `ANTHROPIC_AUTH_TOKEN` | 同上（二选一） | 与 `ANTHROPIC_API_KEY` 等效，优先使用 | | `ANTHROPIC_BASE_URL` | API 中转地址 | 自定义 API endpoint，适用于代理/镜像场景 | | `EMBEDDING_API_KEY` | Dense embedding 双路融合 | 启用向量嵌入，与 BM25 融合提升检索精度 | 降级策略： - 无 `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN` → 知识提取降级到规则引擎匹配标签 - 无 `EMBEDDING_API_KEY` → 检索仅用 BM25 稀疏向量（仍然有效） ## 开发 ```bash 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](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/`（本地持久状态） 常见做法： ```bash 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/`