# 评审者操作手册

本操作手册是 [`pr-workflow.md`](./pr-workflow.zh-CN.md) 的运营配套文档。
如需更广泛的文档导航，请使用 [`docs/README.md`](../../../README.zh-CN.md)。

## 0. 摘要

- **目的：** 定义确定性的评审者操作模型，在高 PR 量下保持高评审质量。
- **受众：** 维护者、评审者和代理辅助评审者。
- **范围：** 提交分类、风险到深度的路由、深度评审检查、自动化覆盖和交接协议。
- **非目标：** 替代 `CONTRIBUTING.md` 中的 PR 政策权威或 CI 文件中的工作流权威。

---

## 1. 按评审场景快速路由

在阅读完整细节前使用本节进行快速路由。

### 1.1 前 5 分钟提交检查失败

1. 留下一个可执行的检查清单评论。
2. 在提交阻塞问题修复前停止深度评审。

前往：

- [第 3.1 节](#31-五分钟提交分类)

### 1.2 风险高或不明确

1. 默认按 `risk: high` 处理。
2. 要求深度评审和显式的回滚证据。

前往：

- [第 2 节](#2-评审深度决策矩阵)
- [第 3.3 节](#33-深度评审检查清单高风险)

### 1.3 自动化输出错误/有噪音

1. 应用覆盖协议（`risk: manual`，去重评论/标签）。
2. 带着显式理由继续评审。

前往：

- [第 5 节](#5-自动化覆盖协议)

### 1.4 需要评审交接

1. 交接时提供范围/风险/验证/阻塞项信息。
2. 分配具体的下一步操作。

前往：

- [第 6 节](#6-交接协议)

---

## 2. 评审深度决策矩阵

| 风险标签 | 典型变更路径 | 最低评审深度 | 所需证据 |
|---|---|---|---|
| `risk: low` | 文档/测试/琐事、孤立的非运行时变更 | 1 名评审者 + CI 门控 | 一致的本地验证 + 无行为歧义 |
| `risk: medium` | `src/providers/**`、`src/channels/**`、`src/memory/**`、`src/config/**` | 1 名了解子系统的评审者 + 行为验证 | 聚焦的场景证明 + 显式副作用说明 |
| `risk: high` | `src/security/**`、`src/runtime/**`、`src/gateway/**`、`src/tools/**`、`.github/workflows/**` | 快速分类 + 深度评审 + 回滚就绪 | 安全/故障模式检查 + 清晰的回滚方案 |

不确定时，按 `risk: high` 处理。

如果自动化风险标签在上下文下不正确，维护者可以应用 `risk: manual` 并显式设置最终的 `risk:*` 标签。

---

## 3. 标准评审工作流

### 3.1 五分钟提交分类

对于每个新 PR：

1. 确认模板完整性（`summary`、`validation`、`security`、`rollback`）。
2. 确认标签存在且合理：
   - `size:*`、`risk:*`
   - 范围标签（例如 `provider`、`channel`、`security`）
   - 模块级标签（`channel:*`、`provider:*`、`tool:*`）
   - 适用时的贡献者等级标签
3. 确认 CI 信号状态（`CI Required Gate`）。
4. 确认范围单一（除非有理由，否则拒绝混合的大型 PR）。
5. 确认隐私/数据卫生和中立测试措辞要求已满足。

如果任何提交要求失败，留下一个可执行的检查清单评论，而非进行深度评审。

### 3.2 快速通道检查清单（所有 PR）

- 范围边界明确且可信。
- 存在验证命令且结果一致。
- 用户-facing 行为变更已文档化。
- 作者理解行为和影响范围（尤其是代理辅助的 PR）。
- 回滚路径具体（不只是"revert"）。
- 兼容性/迁移影响清晰。
- 差异产物中无个人/敏感数据泄露；示例/测试保持中立且符合项目范围。
- 如果存在类似身份的措辞，使用 ZeroClaw/项目原生角色（而非个人或真实世界身份）。
- 命名和架构边界遵循项目契约（`AGENTS.md`、`CONTRIBUTING.md`）。

### 3.3 深度评审检查清单（高风险）

对于高风险 PR，验证每个类别至少有一个具体示例：

- **安全边界：** 保留默认拒绝行为，无意外的范围扩大。
- **故障模式：** 错误处理显式且安全降级。
- **契约稳定性：** CLI/配置/API 兼容性保留或已文档化迁移方案。
- **可观测性：** 故障可诊断且不泄露密钥。
- **回滚安全性：** 回滚路径和影响范围清晰。

### 3.4 评审评论结果风格

优先使用检查清单风格的评论，带有一个明确的结果：

- **可合并**（说明原因）。
- **需要作者操作**（有序的阻塞项列表）。
- **需要更深入的安全/运行时评审**（说明确切风险和所需证据）。

避免模糊的评论，以免造成不必要的来回延迟。

---

## 4. Issue 分类和积压治理

### 4.1 Issue 分类标签操作手册

使用标签保持积压可执行：

- 不完整的 bug 报告标记为 `r:needs-repro`。
- 使用/支持问题标记为 `r:support`，更适合路由到 bug 积压之外。
- 不可操作的重复/噪音标记为 `duplicate` / `invalid`。
- 等待外部阻塞项的已接受工作标记为 `no-stale`。
- 当日志/有效负载包含个人标识符或敏感数据时，要求脱敏。

### 4.2 PR 积压清理协议

当评审需求超过容量时，按以下顺序应用：

1. 将活跃的 bug/安全 PR（`size: XS/S`）保持在队列顶部。
2. 要求重叠的 PR 合并；经确认后将旧 PR 关闭为 `superseded`。
3. 在 stale 关闭窗口开始前，将休眠 PR 标记为 `stale-candidate`。
4. 重新打开 stale/被取代的技术工作前，要求 rebase + 新的验证。

---

## 5. 自动化覆盖协议

当自动化输出产生评审副作用时使用：

1. **错误的风险标签：** 添加 `risk: manual`，然后设置预期的 `risk:*` 标签。
2. **Issue 分类时错误的自动关闭：** 重新打开 Issue，移除路由标签，留下一条澄清评论。
3. **标签垃圾信息/噪音：** 保留一条规范的维护者评论，移除冗余的路由标签。
4. **模糊的 PR 范围：** 深度评审前要求拆分。

---

## 6. 交接协议

如果将评审交接给另一位维护者/代理，包含：

1. 范围摘要。
2. 当前风险等级和理由。
3. 已验证的内容。
4. 未解决的阻塞项。
5. 建议的下一步操作。

---

## 7. 每周队列卫生

- 评审 stale 队列，仅对已接受但被阻塞的工作应用 `no-stale`。
- 优先处理 `size: XS/S` 的 bug/安全 PR。
- 将重复出现的支持问题转化为文档更新和自动响应指引。

---

## 8. 相关文档

- [README.md](../../../README.zh-CN.md) — 文档分类和导航。
- [pr-workflow.md](./pr-workflow.zh-CN.md) — 治理工作流和合并契约。
- [ci-map.md](./ci-map.zh-CN.md) — CI 所有者和分类地图。
- [actions-source-policy.md](./actions-source-policy.zh-CN.md) — Action 源白名单政策。

---

## 9. 维护说明

- **所有者：** 负责评审质量和队列吞吐量的维护者。
- **更新触发条件：** PR 政策变更、风险路由模型变更或自动化覆盖行为变更。
- **最后审核：** 2026-02-18。
