---
name: dev-pipeline
description: 通用研发流水线 — 从需求分析到功能上线的全流程 Agent 协作方案。定义角色、阶段、质量门禁、测试分层和流转规则。
version: 1.0.0
date: 2026-06-30
author: 马总管 🐎
metadata:
  openclaw:
    emoji: "🔧"
    tags: [研发流程, subagent, 多模型协作, 流水线, devops, 质量门禁, 测试分层]
    requires:
      bins: []
  hermes:
    tags: [研发流程, subagent, 多模型协作, 流水线, devops, 质量门禁, 测试分层]
---

# 通用研发流水线（Dev Pipeline）

> **版本**: v1.0.0（通用版）
> **创建日期**: 2026-06-30
> **维护者**: 马总管 🐎
> **适用平台**: Hermes Agent / OpenClaw / 其他 AgentSkills 兼容平台

## 一、概述

组建一个完整的研发小单元，覆盖从需求分析到功能上线的全流程。由总管负责调度，通过 delegate_task / subagent 机制将各阶段任务分派给不同角色的子 Agent，每个角色使用最适合的模型。

### 流程总览

```
用户（提需求）
 │
 ▼
┌──────────────────────────────────────────────┐
│  ① 需求分析 — 总管                              │
│  理解业务意图，输出结构化需求文档，跟用户确认        │
└──────────┬───────────────────────────────────┘
           ▼ [QG1: 需求门禁]
┌──────────────────────────────────────────────┐
│  ② 技术方案 — 架构师                            │
│  读代码库 + 需求文档，输出设计方案                 │
│  总管 review 方案，必要时跟用户确认                │
└──────────┬───────────────────────────────────┘
           ▼ [QG2: 设计门禁]
┌──────────────────────────────────────────────┐
│  ③ UI设计 — 设计师                    (可选)   │
│  输出设计规范（配色/字体/间距/组件样式代码）         │
│  仅面向用户的项目需要，纯后端/API可跳过             │
└──────────┬───────────────────────────────────┘
           ▼
┌──────────────────────────────────────────────┐
│  ④ 编码实现（结对编程模式，可选）                  │
│  ④a 主程序员写代码                               │
│  ④b 结对程序员 review+改进                       │
│  大型/中型启用结对，小型/热修复单程序员             │
└──────────┬───────────────────────────────────┘
           ▼ [QG3: 编码门禁]
┌──────────────────────────────────────────────┐
│  ⑤ 代码审查 — 审查员                            │
│  Review 代码变更，输出结构化审查报告               │
│  ├─ REQUEST_CHANGES → 回到④让程序员修改          │
│  └─ APPROVED → 进入下一阶段                      │
└──────────┬───────────────────────────────────┘
           ▼
┌──────────────────────────────────────────────┐
│  ⑥ 测试验证 — 测试员                            │
│  分层编写测试（单元+集成+冒烟）并执行              │
│  ├─ PARTIAL_FAIL → 回到④让程序员修复             │
│  └─ ALL_PASS → 进入下一阶段                      │
└──────────┬───────────────────────────────────┘
           ▼ [QG4: 测试门禁]
┌──────────────────────────────────────────────┐
│  ⑦ 部署上线 — 总管                              │
│  构建、部署、验证，汇报结果给用户                   │
└──────────────────────────────────────────────┘
```

### 角色定义

| 角色 | 代号 | 流程阶段 | 推荐模型类型 |
|------|------|---------|-------------|
| 🧑‍💼 总管 | PM | ①需求分析 ⑦部署上线 | 快速响应模型（日常对话） |
| 🏗️ 架构师 | ARCH | ②技术方案 | 强推理模型（复杂推理） |
| 🎨 设计师 | UI | ③UI设计 | 编码版模型（设计+编码） |
| 💻 主程序员 | DEV | ④编码实现 | 深度推理编码模型 |
| 👥 结对程序员 | DEV2 | ④编码实现(review) | 与主程序员不同家族模型 |
| 🔍 审查员 | REVIEW | ⑤代码审查 | 深度推理模型 |
| 🧪 测试员 | QA | ⑥测试验证 | Agent/Tool 能力强的模型 |

**模型选择原则**：
- 编码/审查/测试使用**不同模型家族**，消除单模型偏见
- 主程序员和结对程序员用不同厂商模型，交叉审视
- 测试员与编码员信息隔离（测试员不看实现思路）

### 流程裁剪规则

并非所有需求都必须走完全部阶段。由总管根据需求规模判断裁剪：

| 需求规模 | 定义 | 走哪些阶段 | 结对编程 | 示例 |
|---------|------|-----------|---------|------|
| 🔴 大型 | 新功能/新模块/架构变更 | ①②③④⑤⑥⑦ 全流程 | ✅ 启用 | 新增模块、系统重构 |
| 🟡 中型 | 现有功能扩展/较复杂 Bug | ①④⑤⑥ 跳过②③设计 | ✅ 启用 | 加导出功能、修复复杂 Bug |
| 🟡 中型(含UI) | 现有功能扩展+UI改版 | ①③④⑤⑥ 跳过②方案设计 | ✅ 启用 | 界面改版、新增交互页面 |
| 🟢 小型 | 简单修改/配置变更 | ①④⑥ 最小流程 | ❌ 单程序员 | 改字段校验、加配置项 |
| ⚪ 微型 | 一行代码/纯配置 | 总管直接做，不 delegate | — | 改文案、调参数 |
| 🔥 热修复 | 线上紧急 Bug | ④⑥⑦ 跳过需求和审查 | ❌ 单程序员 | 线上崩溃、数据错误 |

**裁剪原则**：
- ①需求分析（总管）永远不跳过——再小的需求也要先确认理解对了（热修复除外）
- ⑤代码审查在中型以上需求中必须执行
- ⑥测试验证在有代码变更时必须执行（至少验证不破坏现有功能）
- 总管负责判断需求规模，有争议时向用户确认

### 项目目录规范（建议）

- 所有研发项目统一放在 `~/projects-dev/` 下（可自定义）
- 每个项目一个子目录，git 初始化管理
- 便于代码审查阶段做 diff 和回滚

## 二、质量门禁

> 详细规范见 `references/quality-gates.md`

### 门禁总览

| 门禁 | 位置 | 关键检查 | 通过条件 |
|------|------|---------|---------|
| QG1 | 需求→设计 | 产物完整性、验收标准可测试、用户确认 | 全部通过 |
| QG2 | 设计→编码 | 文件变更清单、API与需求对齐 | 无阻断问题 |
| QG3 | 编码→审查 | 编译通过、lint通过、变更与设计一致 | 自检全通过 |
| QG4 | 测试→部署 | 测试全通过、覆盖率达标、无回归、用户确认 | 全部通过 |

### 重试与超时机制

**重试策略：**
```
第1次失败 → 同模型重试，附带失败原因
第2次失败 → 换备用模型重试
第3次失败 → 上报用户，进入人工介入
```

**超时保护：**

| 阶段 | 超时时间 | 超时处理 |
|------|---------|---------|
| ②设计 | 30分钟 | 终止，记录已有产出，人工介入 |
| ③编码 | 50分钟 | 终止，保留已写代码，人工介入 |
| ④审查 | 25分钟 | 终止，标记"审查超时"，直接进测试 |
| ⑤测试 | 40分钟 | 终止，保留已有测试结果，人工介入 |

## 三、阶段产物规范

> 完整模板见 `templates/stage-artifacts.md`

每个阶段的子 Agent **必须**输出结构化 YAML 产物。总管负责校验产物格式。

### 产物设计原则

1. **结构化优先**：用 YAML Schema 约束，减少解析歧义
2. **摘要辅助**：每个产物附带自然语言摘要，帮助 LLM 快速定位
3. **决策可追溯**：记录关键决策的理由和替代方案
4. **问题前传**：显式列出 open_issues，确保下游关注
5. **信息隔离**：审查员不看编码 prompt，测试员不看实现思路

### 产物传递规则

```
① 需求产物 ──→ ②架构师（完整） + ④程序员（验收标准）
② 设计产物 ──→ ③设计师（页面/组件清单） + ④程序员（完整）+ ⑤审查员（摘要+文件清单）
③ UI设计产物 ──→ ④程序员（完整设计规范+组件样式）
④ 编码产物 ──→ ⑤审查员（git diff + 产物） + ⑥测试员（签名+验收标准）
⑤ 审查产物 ──→ ④程序员（如需修改：issues列表）
⑥ 测试产物 ──→ ④程序员（如有失败：failed_tests）/ ⑦总管（如全通过）
```

**关键**：测试员只接收接口签名和验收标准，不接收编码思路和实现 prompt。

## 四、测试分层策略

> 详细规范见 `references/testing-strategy.md`

### 测试金字塔

```
        ╱╲
       ╱ 冒烟 ╲         ← 5-10%
      ╱────────╲
     ╱  集成测试  ╲      ← 20-30%
    ╱──────────────╲
   ╱    单元测试     ╲   ← 60-70%
  ╱──────────────────╲
```

### 覆盖率阈值

| 项目规模 | 行覆盖 | 分支覆盖 | 函数覆盖 |
|---------|--------|---------|---------|
| 大型(新项目) | ≥ 70% | ≥ 60% | ≥ 80% |
| 中型(新功能) | ≥ 60% | ≥ 50% | ≥ 75% |
| 小型(bug修复) | 修改行100% | — | — |

## 五、各阶段执行规范

### ① 需求分析（总管直接执行）

**输入**: 用户的口头/文字需求
**输出**: 结构化需求产物（见 `templates/stage-artifacts.md` ①）

**规则**: 必须跟用户确认需求文档后才进入下一阶段。

### ② 技术方案（delegate → 架构师）

**输入**: 需求产物（完整） + 现有代码库上下文
**输出**: 结构化设计产物（见 `templates/stage-artifacts.md` ②）

**规则**: 总管 review 方案，重大决策需跟用户确认。

### ③ UI设计（delegate → 设计师）— 可选

**适用条件**: 面向用户的项目（H5、小程序、Web应用）。纯后端/API/CLI项目跳过此阶段。

**输入**: 需求产物 + 技术方案中的页面/组件清单 + 用户指定的风格偏好
**输出**: 结构化UI设计产物（见 `templates/stage-artifacts.md` ③）

**设计产物包含**:
1. 设计规范（Design Token）：配色、字体、间距、圆角、阴影
2. 组件样式清单：每个组件的具体 CSS/Tailwind 类名
3. 页面布局描述：各页面的结构和组件组合方式
4. 交互说明：关键交互的状态变化

**规则**:
- 设计师不需要画图，输出可直接使用的代码级设计规范
- 风格偏好由用户指定（如微信风格、Material Design 等）
- 设计规范以 Tailwind CSS 类名为主要表达方式

### ④ 编码实现（结对编程模式，可选）

**模式**: 主程序员写代码 → 结对程序员 review+改进 → 产出最终代码

**④a 主程序员（delegate）**

**输入**: 技术方案产物（完整） + UI设计产物（如有） + 需求产物中的验收标准
**输出**: 实现代码 + 结构化编码产物（见 `templates/stage-artifacts.md` ④）

**④b 结对程序员（delegate）— 大型/中型项目启用**

**输入**: 主程序员产出的代码（git diff） + 技术方案摘要 + 验收标准
**输出**: review 意见 + 改进后的代码

**结对编程规则**:
- 大型/中型项目：必须启用结对，主程序员写完 → 结对程序员 review+改进
- 小型/热修复：单主程序员即可，跳过④b
- 结对程序员的改动也会进入⑤代码审查，形成三道审视（结对→审查→测试）
- 结对程序员不重写代码，只做 review 和针对性改进

**规则**:
- 一次只实现一个功能点，避免大规模变更
- 单次 delegate 涉及文件 ≤ 10 个，超过则拆分
- 严禁在前台运行常驻进程（如 `npm run dev`），必须后台运行
- 完成后必须运行 `git add -A && git commit`

### ⑤ 代码审查（delegate → 审查员）

**输入**: 代码变更（git diff） + 需求摘要 + 技术方案摘要（**不含编码 prompt**）
**输出**: 结构化审查产物（见 `templates/stage-artifacts.md` ⑤）

**审查维度（七维度）**:

| 维度 | 严重级别 | 检查重点 |
|------|---------|---------|
| 安全性 | 🔴 阻断 | SQL注入、XSS、硬编码密钥、路径遍历 |
| 正确性 | 🔴 阻断 | 逻辑错误、边界条件、空值处理、资源泄露 |
| 数据契约 | 🔴 阻断 | 前端 TS 接口与 API 实际返回字段一致性 |
| 性能 | 🟡 警告 | 算法复杂度、N+1查询、内存泄漏 |
| 可维护性 | 🟡 警告 | 函数长度、命名规范、DRY原则 |
| 规范 | 🟢 建议 | 代码风格、项目约定 |
| 测试 | 🟡 警告 | 测试覆盖、Mock合理性 |

**规则**: 审查不通过 → 问题反馈给程序员修改 → 修改后重新审查。最多 3 轮。

### ⑥ 测试验证（delegate → 测试员）

**输入**: 接口签名 + 验收标准（**不含实现思路和编码 prompt**）
**输出**: 测试代码 + 结构化测试产物（见 `templates/stage-artifacts.md` ⑥）

**规则**: 测试不通过 → 失败信息反馈给程序员修复 → 修复后重新测试。最多 3 轮。

### ⑦ 部署上线（总管直接执行）

**输入**: 通过审查和测试的代码
**输出**: 结构化部署产物（见 `templates/stage-artifacts.md` ⑦）

**规则**: 部署前跟用户确认。部署后验证核心功能。

## 六、设计理念与参考文献

### 核心设计理念

| 理念 | 来源 | 落地方式 |
|------|------|---------|
| SOP驱动+结构化输出 | MetaGPT (arXiv:2308.00352) | 7阶段YAML产物模板 |
| 测试与编码分离 | AgentCoder (arXiv:2312.13010) | 不同模型+信息隔离 |
| 多模型交叉审查 | 业界最佳实践 | 编码/审查/测试各用不同模型家族 |
| Task级重试 | CrewAI | 每阶段 max 3 次+备用模型降级 |
| 事件流快照 | OpenHands | git checkpoint 用于崩溃恢复 |
| ACI精简工具 | SWE-agent | 子 agent 按需分配最小工具集 |

### 参考文献

1. MetaGPT — SOP驱动多角色协作，结构化中间产物减少30%信息损失
2. AgentCoder — 独立测试Agent比自测通过率高12-18%
3. ChatDev — 角色扮演对话提升20%完成率
4. SWE-bench — 60%修复失败源于定位错误，强调代码搜索能力
5. Agentless — 简单流水线有时比复杂Agent更有效

> 完整框架对比调研见 `references/framework-comparison.md`

## 七、实战陷阱与最佳实践

### 子 Agent 超时恢复模式

子 Agent 可能在执行过程中超时，但代码文件可能已经写入。超时后总管应执行以下恢复步骤：

1. **检查文件系统** — 查看已生成的文件
2. **检查 git 状态** — 确认子 Agent 是否已自动 commit
3. **验证后端** — 启动服务并测试 API 端点
4. **验证前端** — 确认构建通过
5. **修复关键问题** — 子 Agent 超时前可能来不及处理边界情况
6. **提交修复** — 完成收尾

超时不代表失败——子 Agent 可能完成了 80% 的工作，总管收尾比重新 delegate 更高效。

### 前后端数据契约不一致（高频致命问题）

程序员 Agent 同时写 API 和前端时，TypeScript 接口定义经常与 API 实际返回字段对不上，导致客户端 JS 崩溃。

**防范措施**：
1. 编码完成后，总管用 curl API 抓取实际响应
2. 对比前端 TypeScript 接口定义与 API 实际字段
3. 重点检查：字段名差异、字段是否存在、类型是否匹配
4. 对可能为 undefined 的字段，检查是否有安全访问（`?.`、`|| 默认值`）

### 常驻进程防护规则

子 Agent 禁止前台运行 `npm run dev` / `next start` / `python -m http.server` 等常驻命令，必须后台运行或设超时。违反此规则会导致整个 delegation 链路卡死。

### 代码修改必须提交后再通知构建

修改代码后，必须先 `git status` 确认已 staging、`git log --oneline -1` 确认已提交，再通知用户触发 CI/CD。本地工作区的修改不会自动进入远程仓库。

## 八、附带参考文档

本技能包附带以下参考文档，按通用性分类：

### 通用技术参考（适用于任何项目）

| 文档 | 内容 |
|------|------|
| `references/fastapi-pitfalls.md` | FastAPI 实战陷阱（路由顺序、N+1、NULL处理等） |
| `references/frontend-build-optimization.md` | Vite 代码分割 + 路由懒加载优化 |
| `references/operation-log-pattern.md` | 操作日志系统四层架构模板 |
| `references/testing-strategy.md` | 测试分层策略详情 |
| `references/quality-gates.md` | 质量门禁详情 |
| `references/framework-comparison.md` | AI 编码框架调研对比 |

### 业务模式参考（按需选用）

| 文档 | 适用场景 |
|------|---------|
| `references/excel-data-import.md` | 从 Excel 批量导入业务数据 |
| `references/revenue-allocation-pattern.md` | 人×项目收益归属矩阵 |
| `references/doc-sync-pattern.md` | 里程碑文档同步到仓库 |

## Changelog

| 版本 | 日期 | 变更内容 |
|------|------|---------|
| v1.0.0 | 2026-06-30 | 通用版首发。剥离环境特定信息（API key、服务器IP、具体项目名），保留通用流水线逻辑。适配 OpenClaw/Hermes 等多平台。 |