docs: restructure root READMEs with do as recommended workflow

Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>
2026-02-05 02:30:26 +08:00 · 2026-01-24 14:27:41 +08:00
parent b49dad842a
commit eb066395c2
2 changed files with 237 additions and 915 deletions
--- a/README_CN.md
+++ b/README_CN.md
@@ -2,25 +2,11 @@

 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code)
-[![Version](https://img.shields.io/badge/Version-5.6-green)](https://github.com/cexll/myclaude)
+[![Version](https://img.shields.io/badge/Version-6.x-green)](https://github.com/cexll/myclaude)

-> AI 驱动的开发自动化 - 多后端执行架构 (Codex/Claude/Gemini)
+> AI 驱动的开发自动化 - 多后端执行架构 (Codex/Claude/Gemini/OpenCode)

-## 核心概念：多后端架构
-
-本系统采用**双智能体架构**与可插拔 AI 后端：
-
-| 角色 | 智能体 | 职责 |
-|------|-------|------|
-| **编排者** | Claude Code | 规划、上下文收集、验证、用户交互 |
-| **执行者** | codeagent-wrapper | 代码编辑、测试执行（Codex/Claude/Gemini 后端）|
-
-**为什么分离？**
- Claude Code 擅长理解上下文和编排复杂工作流
- 专业后端（Codex 擅长代码、Claude 擅长推理、Gemini 擅长原型）专注执行
- 通过 `--backend codex|claude|gemini` 匹配模型与任务
-
-## 快速开始（windows上请在Powershell中执行）
+## 快速开始

 ```bash
 git clone https://github.com/cexll/myclaude.git
@@ -28,72 +14,125 @@ cd myclaude
 python3 install.py --install-dir ~/.claude
 ```

-## 工作流概览
+## 模块概览

-### 0. OmO 多智能体编排器（复杂任务推荐）
+| 模块 | 描述 | 文档 |
+|------|------|------|
+| [do](skills/do/README.md) | **推荐** - 7 阶段功能开发 + codeagent 编排 | `/do` 命令 |
+| [dev](dev-workflow/README.md) | 轻量级开发工作流 + Codex 集成 | `/dev` 命令 |
+| [omo](skills/omo/README.md) | 多智能体编排 + 智能路由 | `/omo` 命令 |
+| [bmad](bmad-agile-workflow/README.md) | BMAD 敏捷工作流 + 6 个专业智能体 | `/bmad-pilot` 命令 |
+| [requirements](requirements-driven-workflow/README.md) | 轻量级需求到代码流水线 | `/requirements-pilot` 命令 |
+| [essentials](development-essentials/README.md) | 核心开发命令和工具 | `/code`, `/debug` 等 |
+| [sparv](skills/sparv/README.md) | SPARV 工作流 (Specify→Plan→Act→Review→Vault) | `/sparv` 命令 |
+| course | 课程开发（组合 dev + product-requirements + test-cases） | 组合模块 |

-**基于风险信号智能路由任务到专业智能体的多智能体编排系统。**
+## 核心架构
+
+| 角色 | 智能体 | 职责 |
+|------|-------|------|
+| **编排者** | Claude Code | 规划、上下文收集、验证 |
+| **执行者** | codeagent-wrapper | 代码编辑、测试执行（Codex/Claude/Gemini/OpenCode 后端）|
+
+## 工作流详解
+
+### do 工作流（推荐）
+
+7 阶段功能开发，通过 codeagent-wrapper 编排多个智能体。**大多数功能开发任务的首选工作流。**

 ```bash
-/omo "分析并修复这个认证 bug"
+/do "添加用户登录功能"
 ```

-**智能体层级：**
-| 智能体 | 角色 | 后端 | 模型 |
-|-------|------|------|------|
-| `oracle` | 技术顾问 | Claude | claude-opus-4-5 |
-| `librarian` | 外部研究 | Claude | claude-sonnet-4-5 |
-| `explore` | 代码库搜索 | OpenCode | grok-code |
-| `develop` | 代码实现 | Codex | gpt-5.2 |
-| `frontend-ui-ux-engineer` | UI/UX 专家 | Gemini | gemini-3-pro |
-| `document-writer` | 文档撰写 | Gemini | gemini-3-flash |
+**7 阶段：**
+| 阶段 | 名称 | 目标 |
+|------|------|------|
+| 1 | Discovery | 理解需求 |
+| 2 | Exploration | 映射代码库模式 |
+| 3 | Clarification | 解决歧义（**强制**）|
+| 4 | Architecture | 设计实现方案 |
+| 5 | Implementation | 构建功能（**需审批**）|
+| 6 | Review | 捕获缺陷 |
+| 7 | Summary | 记录结果 |

-**路由信号（非固定流水线）：**
- 代码位置不明确 → `explore`
- 外部库/API → `librarian`
- 高风险/多文件变更 → `oracle`
- 需要实现 → `develop` / `frontend-ui-ux-engineer`
-
-**常用配方：**
- 解释代码：`explore`
- 位置已知的小修复：直接 `develop`
- Bug 修复，位置未知：`explore → develop`
- 跨模块重构：`explore → oracle → develop`
- 外部 API 集成：`explore + librarian → oracle → develop`
-
-**适用场景：** 复杂 bug 调查、多文件重构、架构决策
+**智能体：**
+- `code-explorer` - 代码追踪、架构映射
+- `code-architect` - 设计方案、文件规划
+- `code-reviewer` - 代码审查、简化建议
+- `develop` - 实现代码、运行测试

 ---

-### 1. Dev 工作流（推荐）
+### Dev 工作流

-**大多数开发任务的首选工作流。**
+轻量级开发工作流，适合简单功能开发。

 ```bash
 /dev "实现 JWT 用户认证"
 ```

 **6 步流程：**
-1. **需求澄清** - 交互式问答明确范围
-2. **Codex 深度分析** - 代码库探索和架构决策
-3. **开发计划生成** - 结构化任务分解和测试要求
-4. **并行执行** - Codex 并发执行任务
-5. **覆盖率验证** - 强制 ≥90% 测试覆盖率
-6. **完成总结** - 文件变更和覆盖率报告
-
-**核心特性：**
- Claude Code 编排，Codex 执行所有代码变更
- 自动任务并行化提升速度
- 强制 90% 测试覆盖率门禁
- 失败自动回滚
-
-**适用场景：** 功能开发、重构、带测试的 bug 修复
+1. 需求澄清 - 交互式问答
+2. Codex 深度分析 - 代码库探索
+3. 开发计划生成 - 结构化任务分解
+4. 并行执行 - Codex 并发执行
+5. 覆盖率验证 - 强制 ≥90%
+6. 完成总结 - 报告生成

 ---

-### 2. BMAD 敏捷工作流
+### OmO 多智能体编排器

-**包含 6 个专业智能体的完整企业敏捷方法论。**
+基于风险信号智能路由任务到专业智能体。
+
+```bash
+/omo "分析并修复这个认证 bug"
+```
+
+**智能体层级：**
+| 智能体 | 角色 | 后端 |
+|-------|------|------|
+| `oracle` | 技术顾问 | Claude |
+| `librarian` | 外部研究 | Claude |
+| `explore` | 代码库搜索 | OpenCode |
+| `develop` | 代码实现 | Codex |
+| `frontend-ui-ux-engineer` | UI/UX 专家 | Gemini |
+| `document-writer` | 文档撰写 | Gemini |
+
+**常用配方：**
+- 解释代码：`explore`
+- 位置已知的小修复：直接 `develop`
+- Bug 修复（位置未知）：`explore → develop`
+- 跨模块重构：`explore → oracle → develop`
+
+---
+
+### SPARV 工作流
+
+极简 5 阶段工作流：Specify → Plan → Act → Review → Vault。
+
+```bash
+/sparv "实现订单导出功能"
+```
+
+**核心规则：**
+- **10 分规格门**：得分 0-10，必须 >=9 才能进入 Plan
+- **2 动作保存**：每 2 次工具调用写入 journal.md
+- **3 失败协议**：连续 3 次失败后停止并上报
+- **EHRB**：高风险操作需明确确认
+
+**评分维度（各 0-2 分）：**
+1. Value - 为什么做，可验证的收益
+2. Scope - MVP + 不在范围内的内容
+3. Acceptance - 可测试的验收标准
+4. Boundaries - 错误/性能/兼容/安全边界
+5. Risk - EHRB/依赖/未知 + 处理方式
+
+---
+
+### BMAD 敏捷工作流
+
+完整企业敏捷方法论 + 6 个专业智能体。

 ```bash
 /bmad-pilot "构建电商结账系统"
@@ -104,43 +143,36 @@ python3 install.py --install-dir ~/.claude
 |-------|------|
 | Product Owner | 需求与用户故事 |
 | Architect | 系统设计与技术决策 |
-| Tech Lead | Sprint 规划与任务分解 |
+| Scrum Master | Sprint 规划与任务分解 |
 | Developer | 实现 |
 | Code Reviewer | 质量保证 |
 | QA Engineer | 测试与验证 |

-**流程：**
-```
-需求 → 架构 → Sprint计划 → 开发 → 审查 → QA
- ↓      ↓       ↓         ↓      ↓      ↓
-PRD.md DESIGN.md SPRINT.md Code REVIEW.md TEST.md
-```
-
-**适用场景：** 大型功能、团队协作、企业项目
+**审批门：**
+- PRD 完成后（90+ 分）需用户审批
+- 架构完成后（90+ 分）需用户审批

 ---

-### 3. 需求驱动工作流
+### 需求驱动工作流

-**轻量级需求到代码流水线。**
+轻量级需求到代码流水线。

 ```bash
 /requirements-pilot "实现 API 限流"
 ```

-**流程：**
-1. 带质量评分的需求生成
-2. 实现规划
-3. 代码生成
-4. 审查和测试
-
-**适用场景：** 快速原型、明确定义的功能
+**100 分质量评分：**
+- 功能清晰度：30 分
+- 技术具体性：25 分
+- 实现完整性：25 分
+- 业务上下文：20 分

 ---

-### 4. 开发基础命令
+### 开发基础命令

-**日常编码任务的直接命令。**
+日常编码任务的直接命令。

 | 命令 | 用途 |
 |------|------|
@@ -152,16 +184,12 @@ PRD.md DESIGN.md SPRINT.md Code REVIEW.md TEST.md
 | `/refactor` | 代码重构 |
 | `/docs` | 编写文档 |

-**适用场景：** 快速任务，无需工作流开销
-
 ---

 ## 安装

-### 模块化安装（推荐）
-
 ```bash
-# 安装所有启用的模块（默认：dev + essentials）
+# 安装所有启用的模块
 python3 install.py --install-dir ~/.claude

 # 安装特定模块
@@ -170,314 +198,77 @@ python3 install.py --module dev
 # 列出可用模块
 python3 install.py --list-modules

-# 强制覆盖现有文件
+# 强制覆盖
 python3 install.py --force
 ```

-### 可用模块
+### 模块配置

-| 模块 | 默认 | 描述 |
-|------|------|------|
-| `dev` | ✓ 启用 | Dev 工作流 + Codex 集成 |
-| `essentials` | ✓ 启用 | 核心开发命令 |
-| `bmad` | 禁用 | 完整 BMAD 敏捷工作流 |
-| `requirements` | 禁用 | 需求驱动工作流 |
-
-### 安装内容
-
-```
-~/.claude/
-├── bin/
-│   └── codeagent-wrapper    # 主可执行文件
-├── CLAUDE.md                # 核心指令和角色定义
-├── commands/                # 斜杠命令 (/dev, /code 等)
-├── agents/                  # 智能体定义
-├── skills/
-│   └── codex/
-│       └── SKILL.md         # Codex 集成技能
-├── config.json              # 配置文件
-└── installed_modules.json   # 安装状态
-```
-
-### 自定义安装目录
-
-默认情况下，myclaude 安装到 `~/.claude`。您可以使用 `INSTALL_DIR` 环境变量自定义安装目录：
-
-```bash
-# 安装到自定义目录
-INSTALL_DIR=/opt/myclaude bash install.sh
-
-# 相应更新您的 PATH
-export PATH="/opt/myclaude/bin:$PATH"
-```
-
-**目录结构：**
- `$INSTALL_DIR/bin/` - codeagent-wrapper 可执行文件
- `$INSTALL_DIR/skills/` - 技能定义
- `$INSTALL_DIR/config.json` - 配置文件
- `$INSTALL_DIR/commands/` - 斜杠命令定义
- `$INSTALL_DIR/agents/` - 智能体定义
-
-**注意：** 使用自定义安装目录时，请确保将 `$INSTALL_DIR/bin` 添加到您的 `PATH` 环境变量中。
-
-### 配置
-
-编辑 `config.json` 自定义：
+编辑 `config.json` 启用/禁用模块：

 ```json
 {
-  "version": "1.0",
-  "install_dir": "~/.claude",
  "modules": {
-    "dev": {
-      "enabled": true,
-      "operations": [
-        {"type": "merge_dir", "source": "dev-workflow"},
-        {"type": "copy_file", "source": "memorys/CLAUDE.md", "target": "CLAUDE.md"},
-        {"type": "copy_file", "source": "skills/codex/SKILL.md", "target": "skills/codex/SKILL.md"},
-        {"type": "run_command", "command": "bash install.sh"}
-      ]
-    }
+    "dev": { "enabled": true },
+    "bmad": { "enabled": false },
+    "requirements": { "enabled": false },
+    "essentials": { "enabled": false },
+    "omo": { "enabled": false },
+    "sparv": { "enabled": false },
+    "do": { "enabled": false },
+    "course": { "enabled": false }
  }
 }
 ```

-**操作类型：**
-| 类型 | 描述 |
-|------|------|
-| `merge_dir` | 合并子目录 (commands/, agents/) 到安装目录 |
-| `copy_dir` | 复制整个目录 |
-| `copy_file` | 复制单个文件到目标路径 |
-| `run_command` | 执行 shell 命令 |
-
---
-
-## Codex 集成
-
-`codex` 技能使 Claude Code 能够将代码执行委托给 Codex CLI。
-
-### 工作流中的使用
-
-```bash
-# 通过技能调用 Codex
-codeagent-wrapper - <<'EOF'
-在 @src/auth.ts 中实现 JWT 验证
-EOF
-```
-
-### 并行执行
-
-```bash
-codeagent-wrapper --parallel <<'EOF'
---TASK---
-id: backend_api
-workdir: /project/backend
---CONTENT---
-实现 /api/users 的 REST 端点
-
---TASK---
-id: frontend_ui
-workdir: /project/frontend
-dependencies: backend_api
---CONTENT---
-创建消费 API 的 React 组件
-EOF
-```
-
-### 安装 Codex Wrapper
-
-```bash
-# 自动（通过 dev 模块）
-python3 install.py --module dev
-
-# 手动
-bash install.sh
-```
-
-#### Windows 系统
-
-Windows 系统会将 `codeagent-wrapper.exe` 安装到 `%USERPROFILE%\bin`。
-
-```powershell
-# PowerShell（推荐）
-powershell -ExecutionPolicy Bypass -File install.ps1
-
-# 批处理（cmd）
-install.bat
-```
-
-**添加到 PATH**（如果安装程序未自动检测）：
-
-```powershell
-# PowerShell - 永久添加（当前用户）
-[Environment]::SetEnvironmentVariable('PATH', "$HOME\bin;" + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')
-
-# PowerShell - 仅当前会话
-$Env:PATH = "$HOME\bin;$Env:PATH"
-```
-
-```batch
-REM cmd.exe - 永久添加（当前用户）（建议使用上面的 PowerShell 方法）
-REM 警告：此命令会展开 %PATH% 包含系统 PATH，导致重复
-REM 注意：使用 reg add 而非 setx 以避免 1024 字符截断限制
-reg add "HKCU\Environment" /v Path /t REG_EXPAND_SZ /d "%USERPROFILE%\bin;%PATH%" /f
-```
-
---
-
 ## 工作流选择指南

-| 场景 | 推荐工作流 |
-|------|----------|
-| 带测试的新功能 | `/dev` |
-| 快速 bug 修复 | `/debug` 或 `/code` |
-| 大型多 Sprint 功能 | `/bmad-pilot` |
-| 原型或 POC | `/requirements-pilot` |
-| 代码审查 | `/review` |
-| 性能问题 | `/optimize` |
+| 场景 | 推荐 |
+|------|------|
+| 功能开发（默认） | `/do` |
+| 轻量级功能 | `/dev` |
+| Bug 调查 + 修复 | `/omo` |
+| 大型企业项目 | `/bmad-pilot` |
+| 快速原型 | `/requirements-pilot` |
+| 简单任务 | `/code`, `/debug` |

---
+## 后端 CLI 要求
+
+| 后端 | 必需功能 |
+|------|----------|
+| Codex | `codex e`, `--json`, `-C`, `resume` |
+| Claude | `--output-format stream-json`, `-r` |
+| Gemini | `-o stream-json`, `-y`, `-r` |

 ## 故障排查

-### 常见问题
-
 **Codex wrapper 未找到：**
 ```bash
-# 安装程序会自动添加 PATH，检查是否已添加
-if [[ ":$PATH:" != *":$HOME/.claude/bin:"* ]]; then
-    echo "PATH not configured. Reinstalling..."
-    bash install.sh
-fi
-
-# 或手动添加（幂等性命令）
-[[ ":$PATH:" != *":$HOME/.claude/bin:"* ]] && echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
-```
-
-**权限被拒绝：**
-```bash
-python3 install.py --install-dir ~/.claude --force
+bash install.sh
 ```

 **模块未加载：**
 ```bash
-# 检查安装状态
 cat ~/.claude/installed_modules.json
-
-# 重新安装特定模块
-python3 install.py --module dev --force
+python3 install.py --module <name> --force
 ```

---
+## FAQ

-## 常见问题 (FAQ)
+| 问题 | 解决方案 |
+|------|----------|
+| "Unknown event format" | 日志显示问题，可忽略 |
+| Gemini 无法读取 .gitignore 文件 | 从 .gitignore 移除或使用其他后端 |
+| `/dev` 执行慢 | 检查日志，尝试更快模型，使用单一仓库 |
+| Codex 权限拒绝 | 在 ~/.codex/config.yaml 设置 `approval_policy = "never"` |

-### Q1: `codeagent-wrapper` 执行时报错 "Unknown event format"
-
-**问题描述：**
-执行 `codeagent-wrapper` 时出现错误：
-```
-Unknown event format: {"type":"turn.started"}
-Unknown event format: {"type":"assistant", ...}
-```
-
-**解决方案：**
-这是日志事件流的显示问题，不影响实际功能执行。预计在下个版本中修复。如需排查其他问题，可忽略此日志输出。
-
-**相关 Issue：** [#96](https://github.com/cexll/myclaude/issues/96)
-
---
-
-### Q2: Gemini 无法读取 `.gitignore` 忽略的文件
-
-**问题描述：**
-使用 `codeagent-wrapper --backend gemini` 时，无法读取 `.claude/` 等被 `.gitignore` 忽略的目录中的文件。
-
-**解决方案：**
- **方案一：** 在项目根目录的 `.gitignore` 中取消对 `.claude/` 的忽略
- **方案二：** 确保需要读取的文件不在 `.gitignore` 忽略列表中
-
-**相关 Issue：** [#75](https://github.com/cexll/myclaude/issues/75)
-
---
-
-### Q3: `/dev` 命令并行执行特别慢
-
-**问题描述：**
-使用 `/dev` 命令开发简单功能耗时过长（超过30分钟），无法了解任务执行状态。
-
-**解决方案：**
-1. **检查日志：** 查看 `C:\Users\User\AppData\Local\Temp\codeagent-wrapper-*.log` 分析瓶颈
-2. **调整后端：**
-   - 尝试使用 `gpt-5.1-codex-max` 等更快的模型
-   - 在 WSL 环境下运行速度可能更快
-3. **工作区选择：** 使用独立的代码仓库而非包含多个子项目的 monorepo
-
-**相关 Issue：** [#77](https://github.com/cexll/myclaude/issues/77)
-
---
-
-### Q4: 新版 Go 实现的 Codex 权限不足
-
-**问题描述：**
-升级到新版 Go 实现的 Codex 后，出现权限不足的错误。
-
-**解决方案：**
-在 `~/.codex/config.yaml` 中添加以下配置（Windows: `c:\user\.codex\config.toml`）：
-```yaml
-model = "gpt-5.1-codex-max"
-model_reasoning_effort = "high"
-model_reasoning_summary = "detailed"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-disable_response_storage = true
-network_access = true
-```
-
-**关键配置说明：**
- `approval_policy = "never"` - 移除审批限制
- `sandbox_mode = "workspace-write"` - 允许工作区写入权限
- `network_access = true` - 启用网络访问
-
-**相关 Issue：** [#31](https://github.com/cexll/myclaude/issues/31)
-
---
-
-### Q5: 执行时遇到权限拒绝或沙箱限制
-
-**问题描述：**
-运行 codeagent-wrapper 时出现权限错误或沙箱限制。
-
-**解决方案：**
-设置以下环境变量：
-```bash
-export CODEX_BYPASS_SANDBOX=true
-export CODEAGENT_SKIP_PERMISSIONS=true
-```
-
-或添加到 shell 配置文件（`~/.zshrc` 或 `~/.bashrc`）：
-```bash
-echo 'export CODEX_BYPASS_SANDBOX=true' >> ~/.zshrc
-echo 'export CODEAGENT_SKIP_PERMISSIONS=true' >> ~/.zshrc
-```
-
-**注意：** 这些设置会绕过安全限制，请仅在可信环境中使用。
-
---
-
-**仍有疑问？** 请访问 [GitHub Issues](https://github.com/cexll/myclaude/issues) 搜索或提交新问题。
-
---
+更多问题请访问 [GitHub Issues](https://github.com/cexll/myclaude/issues)。

 ## 许可证

-AGPL-3.0 License - 查看 [LICENSE](LICENSE)
+AGPL-3.0 - 查看 [LICENSE](LICENSE)

 ## 支持

- **问题反馈**: [GitHub Issues](https://github.com/cexll/myclaude/issues)
- **文档**: [docs/](docs/)
-
---
-
-**Claude Code + Codex = 更好的开发** - 编排遇见执行。
+- [GitHub Issues](https://github.com/cexll/myclaude/issues)
+- [文档](docs/)