diff --git a/dev-workflow/SKILL.md b/dev-workflow/SKILL.md index e201695..862ba7b 100644 --- a/dev-workflow/SKILL.md +++ b/dev-workflow/SKILL.md @@ -23,6 +23,31 @@ description: "Spec-Driven 开发流程技能，支持 Cross-Debate 和 Cross-Rev | `GITEA_URL` | Gitea 服务地址 | 否（默认 http://192.168.1.22:8418） | | `GITEA_REPO` | 仓库路径 | 否（默认 starmen1265/kb-skills） | +--- + +## 🎯 核心原则 + +### 自动流程衔接 + +**Phase 2-5 自动执行，不在中间阶段暂停等待用户！** + +``` +Phase 1 → 用户确认方案 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → 用户合并 PR + ↑ ↑ + 唯一介入点 唯一介入点 +``` + +### 用户介入点（只有 2 个） + +| 阶段 | 介入方式 | 说明 | +|------|---------|------| +| **Phase 1** | 方案选择 | Cross-Debate 后选择或调整方案 | +| **Phase 6** | 最终审核 | 查看 PR，决定是否合并 | + +**其他阶段自动执行，不需要用户推动！** + +--- + ## 工作流程（Cross 模式） ``` @@ -31,31 +56,33 @@ description: "Spec-Driven 开发流程技能，支持 Cross-Debate 和 Cross-Rev ┌─────────────────────────────────────┐ │ Phase 1: Cross-Debate（方案辩论） │ │ - 3个 Agent 分别出方案 │ -│ - 汇总辩论结果 │ -│ - 用户选择/调整方案 │ -│ - 生成统一 spec.md │ +│ - 交叉审查对方方案 │ +│ - 汇总统一方案 │ +│ - ⏸️ 等待用户确认 ← 唯一介入点 │ └─────────────────────────────────────┘ - ↓ + ↓ 用户确认后自动继续 ┌─────────────────────────────────────┐ │ Phase 2: 分支创建 │ │ - 创建 feature/* 分支 │ -│ - 切换到功能分支 │ +│ - 自动继续 → │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Phase 3: 子代理开发 │ │ - 基于 spec 启动开发子代理 │ -│ - 子代理执行开发任务 │ +│ - ⚠️ 验证工作目录和代码 │ │ - 本地测试通过 │ │ - 提交代码到功能分支 │ +│ - 自动继续 → │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Phase 4: Cross-Review（交叉审核） │ │ - 3个 Agent 交叉审核代码 │ │ - 汇总问题列表 │ -│ - 自动修复（或请求用户确认） │ +│ - 自动修复 │ │ - 多轮迭代直到通过 │ +│ - 自动继续 → │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ @@ -63,26 +90,19 @@ description: "Spec-Driven 开发流程技能，支持 Cross-Debate 和 Cross-Rev │ - 搜索安全最佳实践 │ │ - 审计权限/注入/密钥等问题 │ │ - 修复安全漏洞 │ +│ - 自动继续 → │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Phase 6: 创建 PR │ │ - 调用 Gitea API 创建 PR │ │ - ⚠️ 禁止 auto-merge │ -│ - 返回 PR 编号 │ +│ - ⏸️ 等待用户审核 ← 唯一介入点 │ └─────────────────────────────────────┘ ↓ -通知 pr-review-gate 最终审查 +用户决定是否合并 PR ``` -## 用户介入点 - -| 阶段 | 介入方式 | 说明 | -|------|---------|------| -| **Phase 1** | 方案选择 | Cross-Debate 后选择或调整方案 | -| **Phase 4** | 可选确认 | 有无法决定的问题时介入 | -| **Phase 6** | 最终审核 | 查看 PR，决定是否合并 | - --- ## 执行步骤详解 @@ -100,7 +120,7 @@ sessions_spawn( 需求：{{用户需求}} 输出：1) 技术方案 2) 潜在风险 3) 实现步骤", agentId="claude-code", - runtime="acp" + runtime="subagent" ) # Agent 2: Codex（偏全面，考虑边界情况） @@ -109,7 +129,7 @@ sessions_spawn( 需求：{{用户需求}} 输出：1) 技术方案 2) 边界情况 3) 实现步骤", agentId="codex", - runtime="acp" + runtime="subagent" ) # Agent 3: Gemini CLI（偏快速，先出方案再补细节） @@ -118,20 +138,18 @@ sessions_spawn( 需求：{{用户需求}} 输出：1) 技术方案 2) MVP范围 3) 实现步骤", agentId="gemini", - runtime="acp" + runtime="subagent" ) ``` -#### Step 1.2: 汇总辩论结果 +#### Step 1.2: 交叉审查 -收集三个方案后： -1. 提取共同点（通常是正确的方向） -2. 列出分歧点（需要用户决策） -3. 生成辩论汇总报告 +让三个 Agent 互相审查对方方案，承认盲点，补充建议。 -#### Step 1.3: 用户选择方案 +#### Step 1.3: 汇总统一方案 + +收集审查结果后，生成**统一方案**（不是让用户选择 A/B/C）： -向用户展示： ``` ## 🗳️ Cross-Debate 结果 @@ -139,48 +157,45 @@ sessions_spawn( - ✅ 使用 XX 技术栈 - ✅ 需要 YY 数据结构 -### 分歧点 -| Agent | 方案 | 理由 | -|-------|------|------| -| Claude Code | 方案A | 安全性更高 | -| Codex | 方案B | 考虑边界情况 | -| Gemini | 方案C | 实现更快 | +### 统一方案 +[经过辩论补充后的最终方案] -请选择方案（A/B/C）或提出调整： +✅ 确认开始实施？ ``` -#### Step 1.4: 生成 Spec +#### Step 1.4: 用户确认 -用户确认后，创建 `.planning/spec.md` 文件。 +**这是唯一的介入点！** 用户确认后，Phase 2-6 自动执行。 --- -### Phase 2: 分支创建 +### Phase 2: 分支创建（自动执行） ```bash -python3 dev_workflow.py create-branch --spec .planning/spec.md +git checkout main && git pull +git checkout -b feature/<描述> ``` -分支命名规则： -- `feature/<简短描述>` - 新功能 -- `fix/<简短描述>` - Bug 修复 -- `refactor/<简短描述>` - 重构 +**完成后自动进入 Phase 3，不等待用户确认！** --- -### Phase 3: 子代理开发 +### Phase 3: 子代理开发（自动执行） -使用 `sessions_spawn` 启动开发子代理： +#### Step 3.1: 启动开发子代理 ``` sessions_spawn( task="""根据 spec 开发 {{功能名称}} + ## 工作目录（重要！） + 在 {{REPO_PATH}} 目录下工作，不要使用其他目录！ + ## Spec 文件 - 读取 .planning/spec.md + 读取 {{REPO_PATH}}/.planning/spec.md ## 要求 - 1. 只写目标，不指定具体文件（自己探索） + 1. 只写目标，自己探索怎么实现 2. 本地测试通过后再提交 3. 提交信息遵循 Conventional Commits @@ -188,111 +203,105 @@ sessions_spawn( - 不能 fail-open - 并发请求不能超额 """, - cwd="~/work/kb-skills", - runtime="acp" + cwd="{{REPO_PATH}}", # 明确指定工作目录 + runtime="subagent" ) ``` -**Briefing 原则：** -- ✅ 写目标：Pro 用户改成月度字符预算 -- ✅ 写约束：砍掉所有按次计费逻辑 -- ❌ 不写文件：改 src/api/user.ts +#### Step 3.2: ⚠️ 验证子代理工作（关键步骤） + +**子代理可能：** +1. 写入错误的工作目录 +2. 报告虚假结果 + +**必须验证：** + +```python +def verify_subagent_work(repo_path: str, expected_files: list) -> dict: + """验证子代理是否正确完成了工作""" + + # 1. 检查代码是否写入正确位置 + for file in expected_files: + if not Path(f"{repo_path}/{file}").exists(): + return { + "success": False, + "error": f"文件不存在于正确位置: {file}", + "hint": "子代理可能写入了错误的工作目录" + } + + # 2. 检查是否有新的 git 提交 + result = run_cmd(f"cd {repo_path} && git log origin/main..HEAD --oneline") + if not result.stdout.strip(): + return { + "success": False, + "error": "没有新的提交", + "hint": "子代理可能只报告了结果但没有实际开发" + } + + # 3. 运行测试 + result = run_cmd(f"cd {repo_path} && python3 -m pytest") + if result.returncode != 0: + return { + "success": False, + "error": "测试未通过", + "hint": result.stderr + } + + return {"success": True} +``` + +**如果验证失败：** +1. 检查子代理是否写入了 `~/.openclaw/agents/xxx/workspace/` 而不是目标仓库 +2. 手动修复或重新启动子代理 + +**完成后自动进入 Phase 4，不等待用户确认！** --- -### Phase 4: Cross-Review（交叉审核） +### Phase 4: Cross-Review（交叉审核）（自动执行） #### Step 4.1: 启动多 Agent 审核 ``` -# Agent 1: 纯代码审查 -sessions_spawn( - task="审查当前分支的代码变更。纯看代码，不给参考文档。 - 检查：1) 逻辑错误 2) 边界情况 3) 代码风格", - agentId="claude-code", - runtime="acp" -) - -# Agent 2: 带文档审查 -sessions_spawn( - task="审查当前分支的代码变更。先搜索相关官方文档，再审代码。 - 检查：1) API使用正确性 2) 最佳实践 3) 文档一致性", - agentId="codex", - runtime="acp" -) - -# Agent 3: 测试覆盖审查 -sessions_spawn( - task="审查当前分支的测试覆盖。检查： - 1) 单元测试覆盖 2) 边界情况测试 3) 集成测试", - agentId="gemini", - runtime="acp" -) +sessions_spawn(task="审查代码变更...", runtime="subagent") +sessions_spawn(task="审查代码变更...", runtime="subagent") +sessions_spawn(task="审查测试覆盖...", runtime="subagent") ``` #### Step 4.2: 汇总问题并修复 -```json -{ - "critical": [ - "外键顺序 bug：扣费逻辑先写子表再写父表" - ], - "high": [ - "RPC 权限暴露：任何登录用户都能直接调" - ], - "medium": [ - "Booster 购买没验证 payment_status" - ] -} -``` - -自动修复或请求用户确认。 +自动修复 Critical/High 问题，不需要用户确认。 #### Step 4.3: 多轮迭代 -如果发现问题： -1. 修复后重新触发 Cross-Review -2. 重复直到无 Critical/High 问题 +重复审核直到通过。 + +**完成后自动进入 Phase 5，不等待用户确认！** --- -### Phase 5: 安全审计 +### Phase 5: 安全审计（自动执行） ``` sessions_spawn( - task="""安全审计当前分支代码。 - - ## 审计清单 - 1. 搜索 OWASP Top 10 相关最佳实践 - 2. 搜索平台（如 Stripe/Supabase）安全文档 - 3. 检查以下问题： - - SQL 注入 - - 权限暴露（如 PostgreSQL 函数权限） - - 密钥泄露（检查日志、错误信息） - - fail-open 问题 - - 并发竞态条件 - - ## 输出 - - Critical 漏洞（必须修复） - - High 风险（建议修复） - - 安全建议 - """, - agentId="claude-code", - runtime="acp" + task="""安全审计代码...""", + runtime="subagent" ) ``` +自动修复安全问题。 + +**完成后自动进入 Phase 6，不等待用户确认！** + --- ### Phase 6: 创建 PR -开发完成后： - ```bash python3 dev_workflow.py create-pr --branch feature/xxx --title "PR 标题" ``` -**⚠️ 禁止 auto-merge**：必须等待用户最终审核。 +**⚠️ 禁止 auto-merge** PR 创建后告知用户： @@ -307,7 +316,7 @@ PR 创建后告知用户： - ✅ Cross-Review（3个Agent审核，X轮） - ✅ 安全审计 -**下一步：** 请审核 PR，确认无误后合并。 +**这是第二个介入点：** 请审核 PR，决定是否合并。 ``` --- @@ -327,22 +336,32 @@ python3 dev_workflow.py create-pr --branch feature/xxx --title "PR标题" # 查看当前状态 python3 dev_workflow.py status -# 记录 Cross-Debate 结果 -python3 dev_workflow.py record-debate --file .planning/debate.md +# 查看 Cross 模式统计 +python3 dev_workflow.py stats -# 记录 Cross-Review 结果 -python3 dev_workflow.py record-review --round 1 --issues '[{"level":"critical","desc":"..."}]' +# 记录事件 +python3 dev_workflow.py record-event --type debate --mode cross ``` --- -## 与其他技能的协作 +## ⚠️ 已知问题与改进 -| 技能 | 协作方式 | -|------|----------| -| **pr-review-gate** | PR 创建后触发最终审查 | -| **kb-workflow** | 可复用其目录结构 | -| **GSD** | 采用其 Spec-Driven 方法论 | +### 问题 1: 子代理工作目录错误 + +**现象**：子代理把代码写到 `~/.openclaw/agents/xxx/workspace/` 而不是目标仓库 + +**解决方案**： +1. 在任务描述中明确指定工作目录 +2. 在 Phase 3 增加验证步骤 + +### 问题 2: 子代理虚假报告 + +**现象**：子代理报告完成了开发，但实际没有提交任何代码 + +**解决方案**： +1. 在 Phase 3 增加验证步骤 +2. 检查 git log 确认有新提交 --- @@ -364,3 +383,4 @@ python3 dev_workflow.py record-review --round 1 --issues '[{"level":"critical"," 3. 提交信息遵循 Conventional Commits 4. 开发前先 pull 最新代码 5. **禁止 auto-merge** - 流程错误比代码 bug 更贵 +6. **Phase 2-5 自动执行** - 不需要用户推动，只有 Phase 1 和 Phase 6 需要用户介入