{
  "markdown": "# claude-flow\n\n**[English](README_EN.md)**\n\n> 让 Claude Code 拥有结构化项目认知 + 自主执行能力的开源框架。\n\n## 这是什么？\n\n两套互补的系统，让 Claude Code 从\"每次对话从零开始\"变成\"像读完所有内部文档的新员工\"：\n\n1. **4 层项目配置** — Constitution → Rules → Skills → Commands，用渐进式披露控制 token 成本（[详细文档](docs/project-config.md)）\n2. **8 层自主执行引擎** — 目标审查 → DAG 分解 → 并行执行 → 三级验证 → 元学习（[详细文档](docs/autonomous-engine.md)）\n\n**特点**：\n- 一条命令自动分析项目并生成所有配置，无需手动填写\n- 3 个专业化 Agent 模板（功能实现、代码审查、对抗测试）\n- 4 个实用工具脚本（持久化循环、分层代码地图、模块级规则加载、Lint 反馈闭环）\n- 防护 Hooks（文件保护 + compact 后上下文恢复）+ deny 权限模板\n- CI/CD 模板（GitHub Actions 构建/测试 + AI 代码审查）\n- 代码审查标准模板（REVIEW.md，3 维度 × 3 级别）\n- **引擎 Preset 系统**：`--preset unity` 一键叠加 Unity 专属配置（batch mode 脚本、AutoTest 框架、C# 运行时）\n- 从 100+ 配置文件的实际项目中提炼的方法论\n\n---\n\n## 快速开始\n\n### 方式 A：Claude Code 插件（推荐）\n\n直接在 Claude Code 中安装，无需复制文件到项目：\n\n```bash\n# 1. 添加插件市场\n/plugin marketplace add CookiRui/claude-flow\n\n# 2. 安装核心插件\n/plugin install claude-flow@claude-flow\n\n# 3. （可选）安装 Unity 开发插件\n/plugin install claude-flow-unity@claude-flow\n\n# 4. 初始化项目配置\n/claude-flow:init\n```\n\n> **Unity 用户注意**：插件方式与 `--preset unity` 现在**等价** —— 插件内含 `unity-runtime/` C# 代码，`/claude-flow-unity:init-unity` 会自动复制到你的 `Assets/Scripts/`。autotest 工作流可直接使用，无需额外操作。\n\n**插件提供的能力**（安装即可用，无需配置）：\n- Skills: `/claude-flow:tdd`, `/claude-flow:verification`, `/claude-flow:brainstorming`, `/claude-flow:deep-task`, `/claude-flow:bug-fix`, `/claude-flow:feature-plan-creator`, `/claude-flow:autosolve`, `/claude-flow:upgrade`\n- Agents: `feature-builder`, `code-reviewer`, `test-writer`\n- Hooks: 文件保护、危险命令拦截、上下文恢复、compact 前保存、lint 反馈\n- Scripts: `persistent-solve.py`, `repo-map.py`, `scope-loader.py`, `lint-feedback.sh`\n\n运行 `/claude-flow:init` 会自动分析你的项目并生成项目级配置（constitution、rules、CLAUDE.md 等）。\n\n### 方式 B：npx 安装\n\n```bash\nnpx claude-autosolve init                              # 安装核心到当前目录\nnpx claude-autosolve init --preset unity               # 安装核心 + Unity preset\nnpx claude-autosolve init /path/to/project --force     # 安装到指定目录，强制覆盖\n```\n\n### 方式 C：Python 安装\n\n```bash\ngit clone https://github.com/CookiRui/claude-flow.git\ncd claude-flow\npython install.py /path/to/your-project                # 核心\npython install.py /path/to/your-project --preset unity  # 核心 + Unity\n```\n\n已有文件不会被覆盖，加 `--force` 强制覆盖。\n\n**可用 Preset**：`unity`（更多引擎 preset 计划中）\n\n### 让 AI 自动配置\n\n在项目目录下启动 Claude Code，运行：\n\n```\n/claude-flow:init          # 插件方式\n/init-project              # npx/Python 安装方式\n```\n\n**已有项目** — AI 会自动：\n- 扫描代码库，识别语言、框架、架构模式\n- 生成 constitution（AI 不知道就会写错的项目约束）\n- 生成 rules（编码规范补充细则）\n- 生成 .claudeignore（排除构建产物和依赖）\n- 配置 Hooks（lint 自动反馈闭环）\n- 按需生成项目特有的 Skills（自定义框架/API 使用指南）\n\n**新项目（空目录）** — AI 会引导你：\n- 描述项目的语言、框架、架构\n- 自动生成项目脚手架（manifest、目录结构、入口文件）\n- 基于你的描述生成所有 claude-flow 配置\n\n**整个过程只需确认一次 AI 的分析结果，不需要手动填任何占位符。**\n\n### 3. 开始使用\n\n```\n> 给用户接口加一个按邮箱查询的功能          # 日常开发，AI 自动遵循 constitution\n> /feature-plan-creator 用户权限系统         # 复杂功能：需求分析 → 技术方案 → 微任务\n> /bug-fix 登录偶尔返回 500                  # 修 Bug：诊断 → 回归测试 → 修复 → 经验固化\n> /deep-task 将认证系统从 session 迁移到 JWT  # 复杂任务：DAG 分解 → 并行执行 → 三级验证\n```\n\n超出单会话的超大型任务（XL 级）：\n\n```bash\n# DAG 模式（默认）：自动分解为子任务，原子化执行，费用追踪\npython scripts/persistent-solve.py \"重构整个数据层架构\"\n\n# 递归 DAG 模式：按复杂度递归拆解 + 看板输出\npython scripts/persistent-solve.py \"重构整个数据层架构\" --recursive\n\n# 控制预算\npython scripts/persistent-solve.py \"重构整个数据层架构\" --max-budget-usd 3.0 --per-task-budget 0.3\n```\n\n---\n\n## 内置命令\n\n> 插件方式使用 `/claude-flow:` 前缀（如 `/claude-flow:deep-task`），npx/Python 安装使用无前缀版本（如 `/deep-task`）。\n\n| 插件命令 | 安装命令 | 用途 |\n|---------|---------|------|\n| `/claude-flow:init` | `/init-project` | 自动分析项目并生成所有 claude-flow 配置 |\n| `/claude-flow:feature-plan-creator <name>` | `/feature-plan-creator <name>` | 需求确认 → 技术方案 → ≤5 分钟微任务拆解 |\n| `/claude-flow:bug-fix <description>` | `/bug-fix <description>` | 根因诊断 → 回归测试 → 修复 → 经验固化 |\n| `/claude-flow:deep-task <goal>` | `/deep-task <goal>` | 8 层自主引擎：复杂度分流 → DAG 分解 → 并行 Agent → 三级验证 → 元学习 |\n| `/claude-flow:autosolve <goal>` | `/autosolve <goal>` | 持久化 DAG 调度器 + 看板可视化 |\n| `/claude-flow:upgrade` | `/upgrade` | 升级 claude-flow 到最新版本 |\n| `/claude-flow:install-codex` | `/install-codex` | 在 Claude Code 内安装 OpenAI codex-plugin-cc，调用 Codex 做代码审查 / 任务委托 |\n| `/claude-flow:tdd` | (Skill) | TDD 强制执行：RED-GREEN-REFACTOR 循环 |\n| `/claude-flow:verification` | (Skill) | 完成前验证：5 维度检查清单 |\n| `/claude-flow:brainstorming` | (Skill) | 设计探索：苏格拉底式需求细化 |\n\n---\n\n## 项目结构\n\n### 插件结构（Claude Code Marketplace）\n\n```\nplugins/\n├── claude-flow/                       # 核心插件\n│   ├── .claude-plugin/plugin.json     # 插件清单\n│   ├── skills/                        # 9 个 Skill（tdd/verification/deep-task/...）\n│   ├── agents/                        # 3 个 Agent（feature-builder/code-reviewer/test-writer）\n│   ├── hooks/                         # 6 个 Hook 脚本 + hooks.json\n│   └── bin/                           # CLI 工具（persistent-solve/repo-map/scope-loader/...）\n└── claude-flow-unity/                 # Unity 引擎插件\n    ├── .claude-plugin/plugin.json     # 插件清单\n    ├── skills/                        # autotest + init-unity\n    ├── agents/                        # unity-dev + git-ops\n    ├── hooks/                         # .meta 验证 hook\n    └── bin/                           # Unity batch mode 脚本\n```\n\n### 模板结构（npx/Python 安装）\n\n```\ntemplate/                              # 核心模板（所有项目都装）\n├── CLAUDE.md                          # 根入口：架构速览\n├── REVIEW.md                          # 代码审查标准（3 维度 × 3 级别）\n├── .claudeignore                      # AI 忽略文件配置\n├── .github/workflows/ci.yml           # CI/CD 模板（构建/测试 + AI 代码审查）\n└── .claude/\n    ├── constitution.md                # 宪法模板（4-7 条核心约束 + 强制执行协议）\n    ├── settings.json                  # 预配置 Hooks + deny 权限\n    ├── agents/                        # 3 个 Agent（功能实现/代码审查/对抗测试）\n    ├── hooks/                         # 文件保护 + compact 上下文恢复\n    ├── rules/                         # 编码风格 + Git 工作流 + 安全\n    ├── skills/                        # TDD + 验证 + Skill 模板\n    └── commands/                      # init-project / deep-task / bug-fix / ...\n\npresets/                               # 引擎专属叠加层\n└── unity/                             # Unity preset（--preset unity 安装）\n    ├── .claude/\n    │   ├── scripts/                   # 8 个 batch mode 脚本（编译/测试/资产操作）\n    │   ├── rules/                     # unity-scripts / unity-assets / cli-tools\n    │   ├── hooks/                     # validate-bash / validate-meta-staged\n    │   ├── agents/                    # unity-dev / git-ops + 更新版 feature-builder/test-writer\n    │   └── skills/autotest/           # AutoTest 框架使用指南\n    ├── unity-runtime/                 # C# 运行时（26 文件 + 3 asmdef）\n    │   ├── Scripts/Gameplay/AutoTest/ # IInputProvider + TestInputProvider + AutoTestBridge\n    │   ├── Scripts/Tools/Editor/      # BatchMode + AutoTest Core/Runner/Results + UnityOps\n    │   └── Scripts/Tests/Editor/      # SanityTests + asmdef\n    ├── .gitea/workflows/              # Gitea CI（编译+测试+AI 审查）\n    ├── REVIEW.md                      # 含 Unity 性能规则的增强版\n    ├── .gitignore                     # Unity 专用\n    └── .gitattributes                 # LFS 模式（贴图/模型/音频）\n```\n\n---\n\n## 工具脚本\n\n### persistent-solve.py — 原子化 DAG 调度器\n\n```bash\n# DAG 模式（默认）：Claude 分解目标为子任务 DAG → 每个子任务独立 claude -p 调用\npython scripts/persistent-solve.py \"让游戏帧率稳定 60fps\"\npython scripts/persistent-solve.py \"重构认证系统\" --max-budget-usd 3.0 --per-task-budget 0.3\n\n# 递归 DAG 模式：自动按复杂度递归拆解，直到所有叶子任务 ≤5 分钟\npython scripts/persistent-solve.py \"重构整个数据层架构\" --recursive\npython scripts/persistent-solve.py \"重构整个数据层架构\" --recursive --verify-level l2\n\n# Legacy 模式：原始 WIP 握手循环（一轮一个完整会话）\npython scripts/persistent-solve.py \"修复内存泄漏\" --mode legacy\n\n# 通用选项\npython scripts/persistent-solve.py \"目标\" --max-rounds 5 --max-time 3600\n```\n\n**DAG 模式**（默认）将目标分解为子任务 DAG，每个子任务作为独立的 `claude -p` 调用执行。支持：\n- **费用追踪**：通过 `--output-format json` 获取每个子任务的 token 用量和费用\n- **预算控制**：`--max-budget-usd` 总预算 + `--per-task-budget` 单任务预算，到达即熔断\n- **并行执行**：无文件冲突的子任务通过 `ThreadPoolExecutor` 进程级并行\n- **熔断保护**：预算、时间、轮次、无进展检测四重熔断\n\n**递归 DAG 模式**（`--recursive`）在 DAG 模式基础上增加递归拆解能力：\n- **递归拆解**：按复杂度自动收敛（C≤2 停止，C≥3 继续递归），硬上限 5 层深度\n- **原子提交**：每个叶子任务产出一个独立 checkpoint commit\n- **验证分级**：按复杂度自动选择验证级别（C:1-2 → L1，C:3-4 → L1+L2，C:5 → L1+L2+L3）\n- **局部重规划**：失败时只重新拆解失败节点及其下游，不影响已完成的分支\n- **看板输出**：实时写 `kanban.json` + 终端树形进度显示\n\n**看板输出**（`kanban.json`）：执行过程中自动生成 `.claude-flow/kanban.json`，包含任务树结构、状态汇总（total/done/failed/pending/running）和费用追踪（total_cost_usd）。终端同步显示树形进度：\n```\n[running] 重构整个数据层架构  ($2.34)\n├─ [done] T1: 数据模型重构  ($0.40)  abc1234\n│  ├─ [done] T1.1: 实体定义  ($0.15)  def5678\n│  └─ [done] T1.2: 关系映射  ($0.25)  ghi9012\n├─ [running] T2: 查询层重写  ($0.80)\n└─ [pending] T3: 迁移脚本\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--recursive` | `False` | 启用递归 DAG 拆解（显式 opt-in） |\n| `--kanban` | `True` | 启用看板输出（终端树形 + JSON 文件） |\n| `--kanban-path PATH` | `.claude-flow/kanban.json` | 看板 JSON 输出路径 |\n| `--verify-level` | `auto` | 验证级别覆盖（`auto`\\|`l1`\\|`l2`\\|`l3`，auto = 按复杂度分级） |\n\n**Legacy 模式** 保留原始行为：每轮一个完整 Claude 会话，通过 `.claude-flow/wip.md` 在会话间传递进度。\n\n> **何时用 `/deep-task` vs `persistent-solve.py`**：大多数 L 级任务，`/deep-task` 在单会话内就能完成（并行 Agent + 模型路由）。只有真正超出单会话预算的 XL 级任务才需要 `persistent-solve.py`。\n\n### repo-map.py — 分层代码地图生成器\n\n```bash\n# 分层模式（默认）：生成 L0 全局概览 + L1 模块级符号索引\npython scripts/repo-map.py /path/to/project\npython scripts/repo-map.py /path/to/project --incremental   # 增量更新（基于 git diff）\npython scripts/repo-map.py /path/to/project --level L0      # 仅生成 L0\npython scripts/repo-map.py /path/to/project --level L1 --module auth  # 仅生成某模块 L1\npython scripts/repo-map.py /path/to/project --list-modules   # 列出检测到的模块\n\n# 传统平面模式（向后兼容）\npython scripts/repo-map.py /path/to/project --format md      # 输出 .repo-map.md\npython scripts/repo-map.py /path/to/project --format json     # 输出 .repo-map.json\n```\n\n**分层输出**（`.repo-map/` 目录）：\n- **L0**（`L0.md`）— 全局概览：模块表格 + 跨模块依赖 + 关键入口点（<100 行，始终注入上下文）\n- **L1**（`modules/{name}.md`）— 模块级符号索引：按文件分组的类/函数/方法（<200 行，按需加载）\n- **L2** — 按需展开：直接读取源文件（无需生成）\n\n**增量更新**：`--incremental` 基于 git diff 仅重扫变更文件，与缓存合并，大幅减少重建时间。\n**模块自动检测**：从顶级目录自动检测模块，支持 `config.json` 手动配置。\n\n### scope-loader.py — 模块级作用域规则加载器\n\n```bash\npython scripts/scope-loader.py                                    # 从 git diff 自动检测\npython scripts/scope-loader.py --files \"net/client.py,ui/app.py\"  # 指定文件\npython scripts/scope-loader.py --module networking                 # 指定模块\npython scripts/scope-loader.py --format json                      # JSON 输出\npython scripts/scope-loader.py --format inject                    # stdout 注入（默认）\n```\n\n根据 git diff 影响范围，自动加载相关模块的 constitution 和 rules。支持：\n- **模块检测**：与 repo-map.py 共享模块边界（顶级目录 + config.json 配置）\n- **继承机制**：模块 constitution 叠加根级约束（不替换），可添加模块特有规则\n- **输出格式**：inject（stdout 注入，供 hook 使用）或 JSON（供程序消费）\n\n### lint-feedback.sh — 双向 Lint/Test 反馈闭环\n\n配置为 Claude Code Hook：编辑 → 自动 lint → 失败 → 错误反馈给 AI → AI 自动修复 → 再 lint → 通过。支持 ESLint / Ruff / dotnet format / golangci-lint / Clippy。\n\n---\n\n## Unity Preset\n\n`--preset unity` 在核心模板之上叠加完整的 Unity 自动化测试链路：\n\n```bash\nnpx claude-autosolve init --preset unity\n```\n\n**叠加内容**：\n\n| 类别 | 内容 |\n|------|------|\n| **Batch Mode 脚本** | 编译、EditMode 测试、PlayMode/AutoTest、资产操作、编译日志解析 |\n| **C# 运行时** | AutoTest 框架（TestCase/TestAction/TestCondition/TypeRegistry）+ IInputProvider 确定性输入注入 + BatchPlayModeRunner + UnityOps |\n| **Unity Rules** | C# 命名规范、.meta 文件安全、热路径零分配、CompareTag、组件缓存 |\n| **Unity Hooks** | validate-bash（拦截 rm Library 等）、validate-meta-staged（.meta 提交完整性） |\n| **Unity Agents** | unity-dev（C# 开发）、git-ops（Git+LFS+.meta） |\n| **AutoTest Skill** | IInputProvider 模式、JSON 测试用例格式、三阶段执行生命周期 |\n| **CI/CD** | Gitea Actions（编译检查 + EditMode 测试 + Claude Code PR 审查） |\n| **REVIEW.md** | 新增 PERF-U1~U10 移动端性能规则 + Unity/C# 技术检查清单 |\n\n**自动化测试完整链路**：\n\n```\nunity-editmode-test.sh  → Unity TestRunner (NUnit)  → XML → JSON\nunity-game-test.sh      → BatchPlayModeRunner → AutoTest 框架 → result.json\nunity-compile.sh        → Unity batch mode 编译    → compile.log → JSON\nunity-ops.sh            → UnityOpsRunner → 场景/预制体/材质操作 → result.json\n```\n\n所有脚本使用 `{placeholder}` 模板化，`/init-project` 自动检测 Unity 项目并填充具体值。\n\n---\n\n## 文档\n\n| 文档                                                  | 内容                                       |\n|-------------------------------------------------------|--------------------------------------------|\n| [4 层项目配置方法论](docs/project-config.md)           | Constitution/Rules/Skills/Commands 完整指南 |\n| [8 层自主执行引擎](docs/autonomous-engine.md)          | 设计原理 + 实操路径 + 场景速查 + 踩坑记录 |\n| [持久化循环](docs/persistent-loop.md)                  | 跨会话 WIP 机制 + 持久化循环调度器          |\n\n---\n\n## 与其他方案的对比\n\n| 特性             | claude-flow                            | 原生 Claude Code              | Superpower-style 方案        |\n|------------------|----------------------------------------|-------------------------------|------------------------------|\n| 项目认知结构     | 4 层分级（Constitution→Commands）      | 平面 CLAUDE.md                | 宪法 + Rules（无 Skills 层） |\n| Agent 协作       | 3 专业 Agent（功能实现 / 代码审查 / 对抗测试）| 无内置模板              | 无                           |\n| Hooks 防护       | 文件保护 + Lint 反馈 + compact 上下文恢复 | 单向 Hooks                 | 无                           |\n| 代码审查标准     | REVIEW.md 模板（3 维度 × 3 级别）      | 无                            | 无                           |\n| CI/CD 模板       | GitHub Actions（构建/测试 + AI 审查）  | 无                            | 无                           |\n| 费用预算控制     | `--max-budget-usd` 实际费用追踪 + 熔断 | 无                            | 无                           |\n| 自主执行引擎     | 8 层 `/deep-task`（DAG→并行Agent→验证→元学习）| 无                       | 无                           |\n| 一键初始化       | `/init-project` 自动分析生成           | 无                            | 手动配置                     |\n| 跨会话持久化     | 递归 DAG 调度 + 看板输出 + WIP + 费用追踪 | 无                            | 无                           |\n| 验证体系         | 三级 + 多 Agent 对抗循环（Reviewer↔Executor 收敛）| 无                     | 无                           |\n| 内置 TDD 强制    | ✅ 通过宪法强制执行                     | ❌                            | ❌                           |\n\n---\n\n## 适用场景\n\n- **中大型项目**：多模块、多人协作、有明确架构约束\n- **长期维护项目**：需要 AI 持续理解项目演进\n- **质量敏感项目**：需要 TDD、验证清单、回归测试保障\n- **复杂任务**：跨模块重构、性能优化、新子系统开发\n\n- **新项目**：从空目录开始，AI 引导式搭建脚手架 + 配置\n\n**不适用**：一次性脚本、快速原型、探索性实验（直接用原生 Claude Code 更高效）。\n\n---\n\n## License\n\nMIT\n",
  "bytes": 13985,
  "sha": "3bd95bf609b7488978feaa6c67d96f0fae75710789331e46e163738e993a54a2",
  "repo_slug": "cookirui/claude-flow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cookirui_claude_flow_claude_flow_965fd515/readme"
}