openclaw/agents/haonan/workspace/dev-workflow/SKILL.md

name, description

name	description
dev-workflow	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: 交叉审查

必须启动 3 个交叉审查子代理！

每个派别派出一个审查者，审查所有三个方案：

# 审查者 1（保守派视角）
sessions_spawn(
  task="审查三个方案，承认保守派盲点，补充建议。
        方案A（保守派）：...
        方案B（全面派）：...
        方案C（快速派）：...
        输出：推荐方案 + 统一建议",
  runtime="subagent"
)

# 审查者 2（全面派视角）
sessions_spawn(
  task="审查三个方案，承认全面派盲点，补充建议。
        方案A（保守派）：...
        方案B（全面派）：...
        方案C（快速派）：...
        输出：推荐方案 + 统一建议",
  runtime="subagent"
)

# 审查者 3（快速派视角）
sessions_spawn(
  task="审查三个方案，承认快速派盲点，补充建议。
        方案A（保守派）：...
        方案B（全面派）：...
        方案C（快速派）：...
        输出：推荐方案 + 统一建议",
  runtime="subagent"
)

收集 3 个审查结果后，汇总统一方案。

Step 1.3: 汇总统一方案

收集审查结果后，生成统一方案（不是让用户选择 A/B/C）：

## 🗳️ Cross-Debate 结果

### 共识点
- ✅ 使用 XX 技术栈
- ✅ 需要 YY 数据结构

### 统一方案
[经过辩论补充后的最终方案]

✅ 确认开始实施？

Step 1.4: 用户确认

这是唯一的介入点！ 用户确认后，Phase 2-6 自动执行。

---

Phase 2: 分支创建（自动执行）

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. 报告虚假结果

必须验证：

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 审核

必须启动 3 个审查子代理！

# 审查者 1：代码逻辑
sessions_spawn(
  task="审查代码逻辑。检查：1) 逻辑错误 2) 边界情况 3) 代码风格。
        仓库：{{REPO_PATH}}
        分支：{{BRANCH}}
        输出：Critical/High/Medium 问题列表",
  runtime="subagent"
)

# 审查者 2：安全性
sessions_spawn(
  task="审查代码安全。检查：1) 权限控制 2) 注入风险 3) 敏感数据泄露。
        仓库：{{REPO_PATH}}
        分支：{{BRANCH}}
        输出：Critical/High/Medium 问题列表",
  runtime="subagent"
)

# 审查者 3：测试覆盖
sessions_spawn(
  task="审查测试覆盖。检查：1) 单元测试 2) 边界测试 3) 集成测试。
        仓库：{{REPO_PATH}}
        分支：{{BRANCH}}
        输出：缺失测试 + 测试建议",
  runtime="subagent"
)

⚠️ 必须等待所有 3 个审查完成后再继续！

Step 4.2: 汇总问题并修复

自动修复 Critical/High 问题，不需要用户确认。

Step 4.3: 多轮迭代

重复审核直到通过。

完成后自动进入 Phase 5，不等待用户确认！

---

Phase 5: 安全审计（自动执行）

sessions_spawn(
  task="""安全审计代码...""",
  runtime="subagent"
)

自动修复安全问题。

完成后自动进入 Phase 6，不等待用户确认！

---

Phase 6: 创建 PR

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 命令

# 创建 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

---

⚠️ 已知问题与改进

问题 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 需要用户介入