starmen1265/kb-skills
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(dev-workflow): 改进 Cross 模式流程

Browse Source 
关键改进：
1. 自动流程衔接 - Phase 2-5 自动执行，不在中间阶段暂停
2. 明确用户介入点 - 只有 Phase 1（方案确认）和 Phase 6（PR合并）需要介入
3. 子代理工作验证 - 检查代码是否写入正确位置、是否有新提交

已知问题：
- 子代理可能写入错误的工作目录
- 子代理可能报告虚假结果
- 需要在 Phase 3 增加验证步骤
This commit is contained in:
starmen1265
2026-03-09 15:36:13 +08:00
parent cee3598d37
commit 77bc46b9ed
1 changed files with 148 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev-workflow/SKILL.md
+148 -128
View File
@@ -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 需要用户介入