# ZeroClaw PR 工作流（高协作吞吐量场景）

本文档定义了 ZeroClaw 在高 PR 提交量场景下的处理规则，以保持：

- 高性能
- 高效率
- 高稳定性
- 高可扩展性
- 高可持续性
- 高安全性

相关参考：

- [`docs/README.md`](../../../README.zh-CN.md) 了解文档分类和导航。
- [`ci-map.md`](./ci-map.zh-CN.md) 了解各工作流的所有者、触发条件和分类流程。
- [`reviewer-playbook.md`](./reviewer-playbook.zh-CN.md) 了解评审者日常执行指南。

## 0. 摘要

- **目的：** 为高吞吐量协作提供确定性、基于风险的 PR 操作模型。
- **受众：** 贡献者、维护者和代理辅助评审者。
- **范围：** 仓库设置、PR 生命周期、就绪契约、风险路由、队列规则和恢复协议。
- **非目标：** 替代分支保护配置或 CI 工作流源文件作为实现权威。

---

## 1. 按 PR 场景快速路由

在完整深度评审前使用本节进行快速路由。

### 1.1 提交信息不完整

1. 在一条评论中请求完成模板并补充缺失的验证证据。
2. 在提交阻塞问题解决前停止深度评审。

前往：

- [第 5.1 节](#51-就绪定义dor-请求评审前)

### 1.2 `CI Required Gate` 检查失败

1. 通过 CI 地图路由失败问题，优先修复确定性检查项。
2. 仅在 CI 返回一致信号后重新评估风险。

前往：

- [ci-map.md](./ci-map.zh-CN.md)
- [第 4.2 节](#42-步骤b验证)

### 1.3 涉及高风险路径

1. 升级到深度评审通道。
2. 需要显式的回滚方案、故障模式证据和安全边界检查。

前往：

- [第 9 节](#9-安全和稳定性规则)
- [reviewer-playbook.md](./reviewer-playbook.zh-CN.md)

### 1.4 PR 已被取代或重复

1. 要求显式的取代关联和队列清理。
2. 经维护者确认后关闭被取代的 PR。

前往：

- [第 8.2 节](#82-积压压力控制)

---

## 2. 治理目标和控制循环

### 2.1 治理目标

1. 在高 PR 负载下保持可预测的合并吞吐量。
2. 保持 CI 信号质量（快速反馈、低误报率）。
3. 对风险表面保持显式的安全评审。
4. 保持变更易于理解和回滚。
5. 保持仓库产物无个人/敏感数据泄露。

### 2.2 治理设计逻辑（控制循环）

本工作流采用分层设计，在保持问责清晰的同时减少评审者负担：

1. **提交分类：** 通过路径/大小/风险/模块标签将 PR 路由到合适的评审深度。
2. **确定性验证：** 合并门控依赖可复现的检查，而非主观评论。
3. **基于风险的评审深度：** 高风险路径触发深度评审，低风险路径保持快速流转。
4. **回滚优先的合并契约：** 每个合并路径都包含具体的恢复步骤。

自动化辅助分类和护栏设置，但最终合并问责仍由人类维护者和 PR 作者承担。

---

## 3. 必需的仓库设置

在 `master` 分支上维护以下分支保护规则：

- 合并前要求状态检查通过。
- 要求 `CI Required Gate` 检查通过。
- 合并前要求拉取请求评审。
- 受保护路径要求 CODEOWNERS 评审。
- 对于 `.github/workflows/**`，要求通过 `CI Required Gate`（`WORKFLOW_OWNER_LOGINS`）的所有者审批，且限制组织所有者才能绕过分支/规则集。
- 默认工作流所有者白名单通过 `WORKFLOW_OWNER_LOGINS` 仓库变量配置（当前维护者列表参见 CODEOWNERS）。
- 推送新提交时驳回陈旧的批准。
- 限制受保护分支的强制推送。
- 所有贡献者 PR 直接指向 `master` 分支。

---

## 4. PR 生命周期操作手册

### 4.1 步骤A：提交

- 贡献者提交 PR 时完整填写 `.github/pull_request_template.md`。
- `PR Labeler` 自动应用范围/路径标签 + 大小标签 + 风险标签 + 模块标签（例如 `channel:telegram`、`provider:kimi`、`tool:shell`），并根据已合并 PR 数量应用贡献者等级（`trusted` ≥5 个合并 PR，`experienced` ≥10 个，`principal` ≥20 个，`distinguished` ≥50 个），当存在更具体的模块标签时去重不那么具体的范围标签。
- 对于所有模块前缀，模块标签会被压缩以减少噪音：单个具体模块保留 `prefix:component` 格式，但多个具体模块会折叠为基础范围标签 `prefix`。
- 标签排序按优先级：`risk:*` → `size:*` → 贡献者等级 → 模块/路径标签。
- 维护者可以手动运行 `PR Labeler`（`workflow_dispatch`）的 `audit` 模式查看偏差，或 `repair` 模式标准化整个仓库的受管理标签元数据。
- 在 GitHub 上悬停标签会显示其自动管理的描述（规则/阈值摘要）。
- 受管理标签颜色按显示顺序排列，在长标签行上创建平滑的渐变效果。
- `PR Auto Responder` 发布首次贡献指南，处理低信号项的标签驱动路由，并使用与 `PR Labeler` 相同的阈值自动应用 Issue 贡献者等级（`trusted` ≥5 个，`experienced` ≥10 个，`principal` ≥20 个，`distinguished` ≥50 个）。

### 4.2 步骤B：验证

- `CI Required Gate` 是合并门控。
- 仅文档变更的 PR 使用快速路径，跳过重量级 Rust 任务。
- 非文档 PR 必须通过 lint、测试和发布构建冒烟检查。
- 影响 Rust 代码的 PR 使用与 `master` 推送相同的必需检查集（无 PR 专属构建快捷方式）。

### 4.3 步骤C：评审

- 评审者按风险和大小标签排序优先级。
- 安全敏感路径（`src/security`、`src/runtime`、`src/gateway` 和 CI 工作流）需要维护者关注。
- 大型 PR（`size: L`/`size: XL`）应拆分，除非有充分理由。

### 4.4 步骤D：合并

- 优先使用 **squash 合并** 保持提交历史紧凑。
- PR 标题应遵循约定式提交（Conventional Commit）风格。
- 仅在回滚路径已文档化时合并。

---

## 5. PR 就绪契约（DoR / DoD）

### 5.1 就绪定义（DoR，请求评审前）

- PR 模板已完全填写。
- 范围边界明确（变更了什么 / 没变更什么）。
- 已附加验证证据（不只是"CI 会检查"）。
- 风险路径的安全和回滚字段已填写。
- 已完成隐私/数据卫生检查，测试语言中立且符合项目范围。
- 如果测试/示例中出现类似身份的措辞，已标准化为 ZeroClaw/项目原生标签。

### 5.2 完成定义（DoD，可合并）

- `CI Required Gate` 状态为绿色。
- 所需评审者已批准（包括 CODEOWNERS 路径）。
- 风险等级标签与变更路径匹配。
- 迁移/兼容性影响已文档化。
- 回滚路径具体且快速。

---

## 6. PR 大小和批量策略

### 6.1 大小层级

- `size: XS` ≤ 80 行变更
- `size: S` ≤ 250 行变更
- `size: M` ≤ 500 行变更
- `size: L` ≤ 1000 行变更
- `size: XL` > 1000 行变更

### 6.2 策略

- 默认目标为 `XS/S/M` 大小。
- `L/XL` PR 需要显式理由和更严格的测试证据。
- 如果不可避免需要大型功能，拆分为堆叠 PR。

### 6.3 自动化行为

- `PR Labeler` 根据有效变更行数应用 `size:*` 标签。
- 仅文档/锁文件变更多的 PR 会被标准化以避免大小膨胀。

---

## 7. AI/代理贡献政策

欢迎 AI 辅助的 PR，评审也可以由代理辅助。

### 7.1 要求

1. 清晰的 PR 摘要和范围边界。
2. 显式的测试/验证证据。
3. 风险变更的安全影响和回滚说明。

### 7.2 建议

1. 当自动化对变更有重大影响时，简要说明工具/工作流。
2. 可选的提示词/计划片段以支持可复现性。

我们**不**要求贡献者量化 AI 与人类的代码行占比。

### 7.3 AI 重度参与 PR 的评审重点

- 契约兼容性。
- 安全边界。
- 错误处理和降级行为。
- 性能和内存回归。

---

## 8. 评审 SLA 和队列规则

- 首次维护者分类目标：48 小时内。
- 如果 PR 被阻塞，维护者留下一个可执行的检查清单。
- 使用 `stale` 自动化保持队列健康；维护者可在需要时应用 `no-stale` 标签。
- `pr-hygiene` 自动化每 12 小时检查开放 PR，当 PR 48 小时以上无新提交且落后于 `master` 或头部提交的 `CI Required Gate` 缺失/失败时，发布提醒。

### 8.1 队列预算控制

- 使用评审队列预算：限制每个维护者的并发深度评审 PR 数量，其余保持在分类状态。
- 对于堆叠工作，要求显式的 `Depends on #...` 以使评审顺序确定。

### 8.2 积压压力控制

- 如果新 PR 替代了旧的开放 PR，要求填写 `Supersedes #...`，经维护者确认后关闭旧 PR。
- 标记休眠/冗余 PR 为 `stale-candidate` 或 `superseded` 以减少重复评审工作。

### 8.3 Issue 分类规则

- 不完整的 bug 报告标记为 `r:needs-repro`（深度分类前要求确定性复现步骤）。
- 使用/帮助类问题标记为 `r:support`，更适合在 bug 积压之外处理。
- `invalid` / `duplicate` 标签触发**仅 Issue** 关闭自动化并提供指引。

### 8.4 自动化副作用防护

- `PR Auto Responder` 去重基于标签的评论以避免垃圾信息。
- 自动关闭路由仅适用于 Issue，不适用于 PR。
- 当上下文需要人工覆盖时，维护者可以使用 `risk: manual` 冻结自动化风险重计算。

---

## 9. 安全和稳定性规则

以下区域的变更需要更严格的评审和更强的测试证据：

- `src/security/**`
- 运行时进程管理。
- 网关入口/认证行为（`src/gateway/**`）。
- 文件系统访问边界。
- 网络/认证行为。
- GitHub 工作流和发布流水线。
- 具备执行能力的工具（`src/tools/**`）。

### 9.1 风险 PR 最低要求

- 威胁/风险说明。
- 缓解措施说明。
- 回滚步骤。

### 9.2 高风险 PR 建议

- 包含一个聚焦的测试证明边界行为。
- 包含一个显式的故障模式场景和预期降级表现。

对于代理辅助的贡献，评审者还应验证作者理解运行时行为和影响范围。

---

## 10. 故障恢复协议

如果合并的 PR 导致回归：

1. 立即在 `master` 上回滚 PR。
2. 打开跟进 Issue 进行根因分析。
3. 仅在包含回归测试后重新引入修复。

优先快速恢复服务质量，而非延迟的完美修复。

---

## 11. 维护者合并检查清单

- 范围聚焦且可理解。
- CI 门控为绿色。
- 文档变更时文档质量检查为绿色。
- 安全影响字段已填写完整。
- 隐私/数据卫生字段已填写完整，证据已脱敏/匿名化。
- 代理工作流说明足够支持可复现性（如果使用了自动化）。
- 回滚计划明确。
- 提交标题遵循约定式提交规范。

---

## 12. 代理评审操作模型

为在高 PR 量下保持评审质量稳定，使用双通道评审模型。

### 12.1 通道A：快速分类（代理友好）

- 确认 PR 模板完整性。
- 确认 CI 门控信号（`CI Required Gate`）。
- 通过标签和变更路径确认风险等级。
- 确认存在回滚说明。
- 确认隐私/数据卫生部分和中立措辞要求已满足。
- 确认任何必需的类似身份措辞使用了 ZeroClaw/项目原生术语。

### 12.2 通道B：深度评审（基于风险）

高风险变更（安全/运行时/网关/CI）需要：

- 验证威胁模型假设。
- 验证故障模式和降级行为。
- 验证向后兼容性和迁移影响。
- 验证可观测性/日志影响。

---

## 13. 队列优先级和标签规则

### 13.1 分类顺序建议

1. `size: XS`/`size: S` + bug/安全修复。
2. `size: M` 聚焦变更。
3. `size: L`/`size: XL` 拆分请求或分阶段评审。

### 13.2 标签规则

- 路径标签快速识别子系统所有者。
- 大小标签驱动批量策略。
- 风险标签驱动评审深度（`risk: low/medium/high`）。
- 模块标签（`<module>: <component>`）改进集成特定变更的评审者路由，支持未来新增模块。
- `risk: manual` 允许维护者在自动化缺乏上下文时保留人工风险判断。
- `no-stale` 保留给已接受但被阻塞的工作。

---

## 14. 代理交接契约

当一个代理交接给另一个代理（或维护者）时，包含：

1. 范围边界（变更了什么 / 没变更什么）。
2. 验证证据。
3. 未解决的风险和未知项。
4. 建议的下一步操作。

这可以减少上下文丢失，避免重复深度审查。

---

## 15. 相关文档

- [README.md](../../../README.zh-CN.md) — 文档分类和导航。
- [ci-map.md](./ci-map.zh-CN.md) — CI 工作流所有者和分类地图。
- [reviewer-playbook.md](./reviewer-playbook.zh-CN.md) — 评审者执行模型。
- [actions-source-policy.md](./actions-source-policy.zh-CN.md) — Action 源白名单政策。

---

## 16. 维护说明

- **所有者：** 负责协作治理和合并质量的维护者。
- **更新触发条件：** 分支保护变更、标签/风险政策变更、队列治理更新或代理评审流程变更。
- **最后审核：** 2026-02-18。
