starmen1265
94e1af0da0
关键改进： - 详细说明 Phase 3→4→5→6 的自动衔接逻辑 - 列出常见错误行为（等待用户确认） - 明确：子代理完成 → 汇报 → 判断阶段 → 立即启动下一步
478 lines
14 KiB
Markdown
478 lines
14 KiB
Markdown
---
|
||
name: dev-workflow
|
||
description: "Spec-Driven 开发流程技能，支持 Cross-Debate 和 Cross-Review。当用户说'添加功能'、'开发XXX'时使用。"
|
||
---
|
||
|
||
# dev-workflow - Agent Engineering 开发流程
|
||
|
||
## 什么时候使用
|
||
|
||
当用户发送包含以下模式的消息时触发：
|
||
|
||
| 触发词 | 行为 |
|
||
|--------|------|
|
||
| `添加功能` + 描述 | 开始 Agent Engineering 开发流程 |
|
||
| `开发` + 描述 | 同上 |
|
||
| `实现` + 描述 | 同上 |
|
||
|
||
## 环境变量
|
||
|
||
| 变量名 | 用途 | 必需 |
|
||
|--------|------|------|
|
||
| `GITEA_TOKEN` | Gitea API Token（创建 PR） | 是 |
|
||
| `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 模式）
|
||
|
||
```
|
||
用户描述需求
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 1: Cross-Debate（方案辩论） │
|
||
│ - 3个 Agent 分别出方案 │
|
||
│ - 交叉审查对方方案 │
|
||
│ - 汇总统一方案 │
|
||
│ - ⏸️ 等待用户确认 ← 唯一介入点 │
|
||
└─────────────────────────────────────┘
|
||
↓ 用户确认后自动继续
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 2: 分支创建 │
|
||
│ - 创建 feature/* 分支 │
|
||
│ - 自动继续 → │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 3: 子代理开发 │
|
||
│ - 基于 spec 启动开发子代理 │
|
||
│ - ⚠️ 验证工作目录和代码 │
|
||
│ - 本地测试通过 │
|
||
│ - 提交代码到功能分支 │
|
||
│ - 自动继续 → │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 4: Cross-Review（交叉审核） │
|
||
│ - 3个 Agent 交叉审核代码 │
|
||
│ - 汇总问题列表 │
|
||
│ - 自动修复 │
|
||
│ - 多轮迭代直到通过 │
|
||
│ - 自动继续 → │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 5: 安全审计 │
|
||
│ - 搜索安全最佳实践 │
|
||
│ - 审计权限/注入/密钥等问题 │
|
||
│ - 修复安全漏洞 │
|
||
│ - 自动继续 → │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ Phase 6: 创建 PR │
|
||
│ - 调用 Gitea API 创建 PR │
|
||
│ - ⚠️ 禁止 auto-merge │
|
||
│ - ⏸️ 等待用户审核 ← 唯一介入点 │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
用户决定是否合并 PR
|
||
```
|
||
|
||
---
|
||
|
||
## 执行步骤详解
|
||
|
||
### Phase 1: Cross-Debate（方案辩论）
|
||
|
||
#### Step 1.1: 启动多 Agent 辩论
|
||
|
||
使用 `sessions_spawn` 并行启动 3 个 Agent：
|
||
|
||
```
|
||
# Agent 1: Claude Code（偏保守，重视安全）
|
||
sessions_spawn(
|
||
task="为以下需求设计方案。你是保守派，重视安全性和稳定性。
|
||
需求：{{用户需求}}
|
||
输出：1) 技术方案 2) 潜在风险 3) 实现步骤",
|
||
agentId="claude-code",
|
||
runtime="subagent"
|
||
)
|
||
|
||
# Agent 2: Codex（偏全面，考虑边界情况）
|
||
sessions_spawn(
|
||
task="为以下需求设计方案。你是全面派，考虑所有边界情况。
|
||
需求：{{用户需求}}
|
||
输出：1) 技术方案 2) 边界情况 3) 实现步骤",
|
||
agentId="codex",
|
||
runtime="subagent"
|
||
)
|
||
|
||
# Agent 3: Gemini CLI（偏快速，先出方案再补细节）
|
||
sessions_spawn(
|
||
task="为以下需求设计方案。你是快速派，优先快速实现。
|
||
需求：{{用户需求}}
|
||
输出：1) 技术方案 2) MVP范围 3) 实现步骤",
|
||
agentId="gemini",
|
||
runtime="subagent"
|
||
)
|
||
```
|
||
|
||
#### Step 1.2: 交叉审查
|
||
|
||
让三个 Agent 互相审查对方方案，承认盲点，补充建议。
|
||
|
||
#### Step 1.3: 汇总统一方案
|
||
|
||
收集审查结果后，生成**统一方案**（不是让用户选择 A/B/C）：
|
||
|
||
```
|
||
## 🗳️ Cross-Debate 结果
|
||
|
||
### 共识点
|
||
- ✅ 使用 XX 技术栈
|
||
- ✅ 需要 YY 数据结构
|
||
|
||
### 统一方案
|
||
[经过辩论补充后的最终方案]
|
||
|
||
✅ 确认开始实施？
|
||
```
|
||
|
||
#### Step 1.4: 用户确认
|
||
|
||
**这是唯一的介入点！** 用户确认后，Phase 2-6 自动执行。
|
||
|
||
---
|
||
|
||
### Phase 2: 分支创建（自动执行）
|
||
|
||
```bash
|
||
git checkout main && git pull
|
||
git checkout -b feature/<描述>
|
||
```
|
||
|
||
**完成后自动进入 Phase 3，不等待用户确认！**
|
||
|
||
---
|
||
|
||
### Phase 3: 子代理开发（自动执行）
|
||
|
||
#### Step 3.1: 启动开发子代理
|
||
|
||
```
|
||
sessions_spawn(
|
||
task="""根据 spec 开发 {{功能名称}}
|
||
|
||
## 工作目录（重要！）
|
||
在 {{REPO_PATH}} 目录下工作，不要使用其他目录！
|
||
|
||
## Spec 文件
|
||
读取 {{REPO_PATH}}/.planning/spec.md
|
||
|
||
## 要求
|
||
1. 只写目标，自己探索怎么实现
|
||
2. 本地测试通过后再提交
|
||
3. 提交信息遵循 Conventional Commits
|
||
|
||
## 安全约束
|
||
- 不能 fail-open
|
||
- 并发请求不能超额
|
||
""",
|
||
cwd="{{REPO_PATH}}", # 明确指定工作目录
|
||
runtime="subagent"
|
||
)
|
||
```
|
||
|
||
#### 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（交叉审核）（自动执行）
|
||
|
||
#### Step 4.1: 启动多 Agent 审核
|
||
|
||
```
|
||
sessions_spawn(task="审查代码变更...", runtime="subagent")
|
||
sessions_spawn(task="审查代码变更...", runtime="subagent")
|
||
sessions_spawn(task="审查测试覆盖...", runtime="subagent")
|
||
```
|
||
|
||
#### Step 4.2: 汇总问题并修复
|
||
|
||
自动修复 Critical/High 问题，不需要用户确认。
|
||
|
||
#### Step 4.3: 多轮迭代
|
||
|
||
重复审核直到通过。
|
||
|
||
**完成后自动进入 Phase 5，不等待用户确认！**
|
||
|
||
---
|
||
|
||
### Phase 5: 安全审计（自动执行）
|
||
|
||
```
|
||
sessions_spawn(
|
||
task="""安全审计代码...""",
|
||
runtime="subagent"
|
||
)
|
||
```
|
||
|
||
自动修复安全问题。
|
||
|
||
**完成后自动进入 Phase 6，不等待用户确认！**
|
||
|
||
---
|
||
|
||
### Phase 6: 创建 PR
|
||
|
||
```bash
|
||
python3 dev_workflow.py create-pr --branch feature/xxx --title "PR 标题"
|
||
```
|
||
|
||
**⚠️ 禁止 auto-merge**
|
||
|
||
PR 创建后告知用户：
|
||
|
||
```
|
||
✅ PR #xxx 已创建
|
||
|
||
**分支:** feature/xxx
|
||
**链接:** http://192.168.1.22:8418/starmen1265/kb-skills/pulls/xxx
|
||
|
||
**已完成：**
|
||
- ✅ Cross-Debate（3个Agent辩论）
|
||
- ✅ Cross-Review（3个Agent审核，X轮）
|
||
- ✅ 安全审计
|
||
|
||
**这是第二个介入点：** 请审核 PR，决定是否合并。
|
||
```
|
||
|
||
---
|
||
|
||
## CLI 命令
|
||
|
||
```bash
|
||
# 创建 spec（从 Cross-Debate 结果）
|
||
python3 dev_workflow.py create-spec --title "标题" --description "描述"
|
||
|
||
# 从 spec 创建分支
|
||
python3 dev_workflow.py create-branch --spec .planning/spec.md
|
||
|
||
# 创建 PR（禁止 auto-merge）
|
||
python3 dev_workflow.py create-pr --branch feature/xxx --title "PR标题"
|
||
|
||
# 查看当前状态
|
||
python3 dev_workflow.py status
|
||
|
||
# 查看 Cross 模式统计
|
||
python3 dev_workflow.py stats
|
||
|
||
# 记录事件
|
||
python3 dev_workflow.py record-event --type debate --mode cross
|
||
```
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 🔄 子代理完成时的自动衔接行为（关键！）
|
||
|
||
**这是 Cross 模式能否自动运行的关键！**
|
||
|
||
当收到子代理完成事件时，必须检查当前阶段并自动启动下一步：
|
||
|
||
### Phase 3 开发完成后 → 自动进入 Phase 4
|
||
|
||
```
|
||
收到子代理完成事件
|
||
↓
|
||
检查：是否是开发子代理（label 包含 "dev-"）
|
||
↓ 是
|
||
验证代码：
|
||
- 检查文件是否存在
|
||
- 检查 git log 是否有新提交
|
||
- 运行测试
|
||
↓
|
||
✅ 不等待用户确认
|
||
↓
|
||
立即启动 Phase 4 Cross-Review：
|
||
sessions_spawn(label="review-1", ...)
|
||
sessions_spawn(label="review-2", ...)
|
||
sessions_spawn(label="review-3", ...)
|
||
```
|
||
|
||
### Phase 4 审查完成后 → 自动修复 → 自动进入 Phase 5
|
||
|
||
```
|
||
收到所有审查子代理完成事件
|
||
↓
|
||
汇总问题：
|
||
- Critical: 必须修复
|
||
- High: 建议修复
|
||
↓
|
||
如有问题 → 启动修复子代理：
|
||
sessions_spawn(label="fix-review-issues", ...)
|
||
↓
|
||
修复完成 → ✅ 不等待用户确认
|
||
↓
|
||
立即启动 Phase 5 安全审计：
|
||
sessions_spawn(label="security-audit", ...)
|
||
```
|
||
|
||
### Phase 5 审计完成后 → 自动修复 → 自动进入 Phase 6
|
||
|
||
```
|
||
收到审计子代理完成事件
|
||
↓
|
||
如有问题 → 启动安全修复子代理：
|
||
sessions_spawn(label="fix-security", ...)
|
||
↓
|
||
修复完成 → ✅ 不等待用户确认
|
||
↓
|
||
立即推送分支：
|
||
git push -u origin feature/xxx
|
||
↓
|
||
提供 PR 创建链接
|
||
↓
|
||
⏸️ 这是第二个介入点 - 等待用户审核 PR
|
||
```
|
||
|
||
### ⚠️ 常见错误行为（必须避免）
|
||
|
||
```
|
||
❌ 错误：子代理完成 → 汇报结果 → 等待用户说"继续"
|
||
✅ 正确：子代理完成 → 汇报结果 → 判断阶段 → 立即启动下一步
|
||
|
||
❌ 错误：Phase 4 完成 → 告诉用户"审查完成" → 等待
|
||
✅ 正确：Phase 4 完成 → 汇总问题 → 修复 → Phase 5
|
||
|
||
❌ 错误：每个阶段都汇报并等待确认
|
||
✅ 正确：只有 Phase 1 和 Phase 6 需要用户介入
|
||
```
|
||
|
||
### 状态追踪（可选）
|
||
|
||
可以用文件追踪当前阶段：
|
||
|
||
```bash
|
||
# 记录当前阶段
|
||
echo '{"phase": 4, "status": "in_progress"}' > .planning/workflow-state.json
|
||
|
||
# 子代理完成时读取并判断
|
||
python3 -c "import json; s=json.load(open('.planning/workflow-state.json')); print(s['phase'])"
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 已知问题与改进
|
||
|
||
### 问题 1: 子代理工作目录错误
|
||
|
||
**现象**：子代理把代码写到 `~/.openclaw/agents/xxx/workspace/` 而不是目标仓库
|
||
|
||
**解决方案**：
|
||
1. 在任务描述中明确指定工作目录
|
||
2. 在 Phase 3 增加验证步骤
|
||
|
||
### 问题 2: 子代理虚假报告
|
||
|
||
**现象**：子代理报告完成了开发，但实际没有提交任何代码
|
||
|
||
**解决方案**：
|
||
1. 在 Phase 3 增加验证步骤
|
||
2. 检查 git log 确认有新提交
|
||
|
||
---
|
||
|
||
## 六条铁律
|
||
|
||
1. **Briefing 写目标，不写文件** - 你是 PM，Agent 是工程师
|
||
2. **Agent 共识需要人类验证** - 三个 AI 同意不代表正确
|
||
3. **本地完成所有工作再推远端** - 实现、测试、审核、修复全在本地
|
||
4. **安全约束要写进 Briefing** - "不能 fail-open"、"并发不能超额"
|
||
5. **密钥永远不过聊天** - 用环境变量文件，命令里用变量名
|
||
6. **Briefing 必须包含产品上下文** - 用户画像、产品定位、商业模式
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. 确保 `GITEA_TOKEN` 已配置
|
||
2. 功能分支命名遵循规范
|
||
3. 提交信息遵循 Conventional Commits
|
||
4. 开发前先 pull 最新代码
|
||
5. **禁止 auto-merge** - 流程错误比代码 bug 更贵
|
||
6. **Phase 2-5 自动执行** - 不需要用户推动，只有 Phase 1 和 Phase 6 需要用户介入
|