> 本页出自《Agent Harness 工程：从源码里读出的设计决策》，作者 王吕（公众号 Codeflow，wanglv93@gmail.com）。
> 修订版 1.1 · 2026-08-27。网页版：https://agent-harness.codeflow.cc/book/chapter-16/ ；全书：https://agent-harness.codeflow.cc/ 。
> 引用或转述时请注明作者与出处。

# 第 16 章 · 接进交付流水线：issue 进，PR 出

---

## 16.1 自动化交付前沿：已实现自动化的半场与坚守人工的终局

前 15 章详尽解构了 Coding Agent 本体的构建、记忆演进、安全沙箱与会话运行时；本章则聚焦于如何将 Agent 规范地接入现代工程团队的真实生产交付流水线（Issue → PR → CI/CD → Production）。

当前业界工程实践呈现出高度清晰的半场分界：
- **「Issue 进，PR 出」的前半程已高度成熟**：GitHub Copilot、OpenAI Codex、Anthropic Claude Code 与 Cognition Devin 均已在超大规模生产环境中实现日常化运行；
- **「PR 合并与生产发布」的后半程严守人工审批**：主流代码托管平台与企业级安全合规体系均强制将「Agent 禁止自主 Approve、禁止自主 Merge、生产部署需人工放行」设为不可绕过的硬性安全边界。

自动化流水线建设的核心准则是：**严禁跳过确定性基础直接接入 Agent**。没有严密测试套件与结构化 Issue 规范作为基底，盲目引入 Agent 只会指数级放大系统缺陷，导致工程师陷入漫长的人工排错泥潭。

---

## 16.2 现代交付流水线的四层架构体系

![图 16-1：四层交付流程与人的位置](https://agent-harness.codeflow.cc/figures/ch16-1-delivery-layers.svg)

图 16-1 展示了现代软件工程交付流水线的四层递进拓扑与人机协作边界：流水线自底向上划分为标准化的 Issue 结构化规范（定义 SLA 与验收断言）、确定性的规则自动化分诊（有限状态机处理）、非确定性的 Coding Agent 编码探索（云沙箱隔离执行），以及 Agentic CI/CD 质量门禁；而在整个自动化链条的终点，系统强制保留人工审核 PR 与人工审批生产发布两道硬性卡点，构建坚固的质量与安全防线。

### 16.2.1 第 1 层 · Issue 即提示词：结构化任务规格设计

GitHub 官方核心指导原则指出：**"it's useful to think of the issue you assign to Copilot as a prompt"**。高水准的 Issue 规范即是最高质量的 Agent 任务提示词。

构建生产级 Issue 规范的五大准则：
1. **如同指导新同事般详尽**：明确定义改动范围、预期影响、关联模块与详尽验收断言；
2. **原子化任务拆解**：严禁提交过于宽泛的宏任务，依托 Sub-issues 将大需求拆解为独立可验证的微任务；
3. **提供可运行的确定性验证命令（Pass/Fail）**：为 Agent 提供单条即可执行的测试/构建命令，提供明确的反馈回路；
4. **仓库通用约定下沉**：将代码风格、构建规范与提交指南集中写入根目录指令文件（如 `AGENTS.md`），Issue 仅聚焦具体任务差量；
5. **严守任务排除负面清单**：跨仓库大规模重构、缺乏测试的历史遗留代码、高危安全鉴权逻辑严禁直接交由 Agent 独立处理。

### 16.2.2 第 2 层 · 确定性规则自动化：能用代码解决的坚决不用模型

在引入 LLM 之前，必须首先将所有具备确定性逻辑的流程沉淀为规则状态机（IssueOps）：
- 基于 GitHub App Token / Webhook 驱动有限状态机（FSM）流转；
- 自动化处理标签打标、负责人分派、重复 Issue 查重与分诊 SLA 统计（如 Time in Label）；
- 严禁调用昂贵且不稳定的 LLM 去执行简单的 `if/else` 规则判断。

表 16-1：主流 IssueOps 机器人架构对比

| 架构形态 | 代表工程方案 | 适用场景与维护成本 |
|---|---|---|
| **集中式服务 + 仓内声明** | Kubernetes Prow、triagebot | 适合超大型单体仓，支持基于 OWNERS 细粒度授权；需独立运维服务 |
| **声明式策略引擎** | microsoft-github-policy-service | 适合非开发人员维护标准化 if/then 业务规则 |
| **纯 Actions Serverless** | GitHub Actions Workflow 体系 | 零独立运维成本，直接复用平台内置算力 |

### 16.2.3 第 3 层 · Coding Agent 隔离执行拓扑

表 16-2 汇总了业界主流 Coding Agent 产品的运行模式与权限边界。

表 16-2：主流 Coding Agent 产品的触发、沙箱与 PR 生成模式

| 产品方案 | 核心触发事件 | 运行时隔离环境 | PR 产出与合并控制 |
|---|---|---|---|
| **GitHub Copilot Cloud Agent** | Assign Issue 显式派发 | Actions 临时隔离容器 | 自动提交 Draft PR，严格禁止自批自合 |
| **Claude Code Action** | 评论 `@claude` 或打标签 | 仓库 Actions Runner | 仅推送独立分支并生成链接，由人工确认开 PR |
| **OpenAI Codex Cloud** | PR 评论 `@codex` | 独立云沙箱（默认切断外网） | 需人工点击触发 PR 生成 |
| **Devin** | Linear/Jira 状态流转 | 每任务独立全新虚拟机镜像 | 自动提交 PR 并回写工单进度 |

**云端 Agent 执行的七大安全底线**：
1. 仅限具备写权限（Write Permission）的受信团队成员可触发；
2. 运行环境必须为单任务隔离的一次性沙箱/虚拟机；
3. 只能向特定命名空间分支推送代码，物理禁止直接操作默认分支；
4. **Agent 严格禁止拥有 PR Approve 与 Merge 权限**；
5. Agent 提交的代码变更默认不自动触发特权 CI 流水线；
6. 容器网络出站默认施加严格白名单限制；
7. 外部评论与 Issue 文本入模前必须完成隐匿控制字符清洗与安全转义（第 11 章）。

### 16.2.4 第 4 层 · 确定性测试前置过滤与 Agentic CI/CD

AI 模型的引入是为流水线注入非确定性推理能力，但其产出必须受到确定性测试套件的严格过滤：
- **Meta TestGen-LLM 黄金过滤范式**：Agent 生成的测试用例必须连续通过三道机器断言（可编译构建 → 无 Flaky 稳定通过 → 实测提升代码覆盖率），唯有通过全部过滤的产物方可推送给工程师评审；
- **AI Code Review 作为辅助预检门禁**：在人工介入前预先扫描 P0/P1 级语义缺陷，但其输出同样按不可信数据对待。

---

## 16.3 判断标准：交付流水线建设的四大准则

### 判断标准一：严格遵循递进建设顺序

必须在 Issue 结构化规范与确定性规则自动化完全跑通后，方可引入 Coding Agent，严禁在混乱的流程之上叠加 AI。

### 判断标准二：严格对照任务适宜性负面清单

表 16-3：Coding Agent 任务分派决策矩阵

| 坚决禁止派发给 Agent 的任务 | 强烈推荐派发给 Agent 的任务 |
|---|---|
| 涉及多个分布式代码仓的架构级大重构 | 单仓库内部边界清晰的局部模块迭代 |
| 缺乏单测且无历史文档的黑盒遗留代码 | 具备完善单元测试与断言覆盖的核心模块 |
| 生产核心链路突发严重事故与应急排障 | 日常低风险缺陷修复与语法版本平迁 |
| 核心鉴权逻辑、支付与合规敏感模块变更 | 结构化测试用例补全与接口文档对齐 |

### 判断标准三：必须配备单条命令可断言的验证信号

每个分派给 Agent 的任务，必须能够通过单条命令返回确定的 Pass/Fail 状态，否则严禁进入全自动流水线。

### 判断标准四：合并与发布卡点必须强制保留人工确认

系统必须确保任何合入主干的代码均存在明确的人工责任人，杜绝无人值守下的幽灵代码合入。

---

## 16.4 反面证据与失败模式

### 反面证据一：资深工程师的主观体感与实测产出可能发生背离

METR 严格受控实验（针对资深开源维护者的随机对照测试）显示：在自身高度熟悉的成熟代码库中，使用 AI 导致任务完成耗时实际增加了 19%，但受访者事后主观估计自己提速了 20%。流水线效能评估必须依赖客观数据，绝不能依赖主观体感。

### 反面证据二：恶意 Issue 诱导有害补丁的成功率高达 90%

对抗性测试研究表明，黑客构造的恶意 Bug 报告有高达 90% 的概率诱导 Agent 产出包含漏洞的有害代码，最强的前置防御仅能拦截 47%。人工代码审查是不可替代的安全防线。

### 失败模式：跳过确定性规则与测试基线直接接入 Agent

缺乏测试覆盖的系统在接入 Agent 后，只会以极高的速度批量生成包含隐蔽缺陷的低质代码，引发灾难性的系统崩溃。

---

## 16.5 可以直接采用的最小实现

### 16.5.1 生产级 Issue 规范模板

````markdown
## 1. 业务背景与缺陷现状
<简明描述问题现状、预期表现及复现步骤>

## 2. 验收标准与断言清单
- [ ] 核心功能断言 1: <具体可验证行为>
- [ ] 边界异常断言 2: <输入非法参数时返回特定错误码>
- [ ] 单元测试要求: 必须补充对应的单测覆盖新增逻辑

## 3. 确定性验证命令
```bash
pnpm test:unit -- packages/core/src/session.test.ts
```

## 4. 涉及文件与模块
- `packages/core/src/session.ts` — 核心逻辑修改
````

### 16.5.2 三段式代码审查流（Three-Stage Review Pipeline）

```
[Coding Agent 产出 PR]
       │
       ▼
[确定性过滤流水线] ── (编译失败 / 测试未过 / 覆盖率下降) ──> [自动打回重试]
       │
       ▼ (100% 确定性通过)
[AI Reviewer 预审] ── (扫描高危 P0 缺陷并打标) ──> [非阻塞建议标注]
       │
       ▼
[工程师人工终审 (Final Human Gate)] ──> [人工 Approve 并合并]
```

### 16.5.3 核心效能与质量监控指标矩阵

表 16-4：自动化交付流水线核心度量体系

| 度量指标名称 | 监控目标与业务价值 | 起步推荐基线与预警阈值 |
|---|---|---|
| **Time in Label (`needs-triage`)** | 衡量 Issue 自动化分诊与响应 SLA | 目标 $\le 1$ 个工作日内完成分诊 |
| **Agent PR 合并成功率** | 评估任务分派合理性与 Agent 交付质量 | 先建立基线，若连续两月下滑需收紧任务派发 |
| **Agent PR 人审交互轮次** | 评估代码可读性与团队审查负载 | 期望中位数 $\le 2$ 轮交互 |
| **变更失败率（CFR）与 MTTR** | DORA 核心稳定性指标，防范缺陷扩散 | 必须维持不高于引入 Agent 前的历史基线 |

---

作者 王吕 · 《Agent Harness 工程：从源码里读出的设计决策》 · https://agent-harness.codeflow.cc/book/chapter-16/