本操作手册是 pr-workflow.md 的运营配套文档。
如需更广泛的文档导航，请使用 docs/README.md。
- 目的： 定义确定性的评审者操作模型，在高 PR 量下保持高评审质量。
- 受众： 维护者、评审者和代理辅助评审者。
- 范围： 提交分类、风险到深度的路由、深度评审检查、自动化覆盖和交接协议。
- 非目标： 替代
CONTRIBUTING.md中的 PR 政策权威或 CI 文件中的工作流权威。
在阅读完整细节前使用本节进行快速路由。
- 留下一个可执行的检查清单评论。
- 在提交阻塞问题修复前停止深度评审。
前往：
- 默认按
risk: high处理。 - 要求深度评审和显式的回滚证据。
前往：
- 应用覆盖协议（
risk: manual，去重评论/标签）。 - 带着显式理由继续评审。
前往：
- 交接时提供范围/风险/验证/阻塞项信息。
- 分配具体的下一步操作。
前往：
| 风险标签 | 典型变更路径 | 最低评审深度 | 所需证据 |
|---|---|---|---|
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:* 标签。
对于每个新 PR：
- 确认模板完整性（
summary、validation、security、rollback）。 - 确认标签存在且合理：
size:*、risk:*- 范围标签（例如
provider、channel、security） - 模块级标签（
channel:*、provider:*、tool:*） - 适用时的贡献者等级标签
- 确认 CI 信号状态（
CI Required Gate）。 - 确认范围单一（除非有理由，否则拒绝混合的大型 PR）。
- 确认隐私/数据卫生和中立测试措辞要求已满足。
如果任何提交要求失败，留下一个可执行的检查清单评论，而非进行深度评审。
- 范围边界明确且可信。
- 存在验证命令且结果一致。
- 用户-facing 行为变更已文档化。
- 作者理解行为和影响范围（尤其是代理辅助的 PR）。
- 回滚路径具体（不只是"revert"）。
- 兼容性/迁移影响清晰。
- 差异产物中无个人/敏感数据泄露；示例/测试保持中立且符合项目范围。
- 如果存在类似身份的措辞，使用 ZeroClaw/项目原生角色（而非个人或真实世界身份）。
- 命名和架构边界遵循项目契约（
AGENTS.md、CONTRIBUTING.md）。
对于高风险 PR，验证每个类别至少有一个具体示例：
- 安全边界： 保留默认拒绝行为，无意外的范围扩大。
- 故障模式： 错误处理显式且安全降级。
- 契约稳定性： CLI/配置/API 兼容性保留或已文档化迁移方案。
- 可观测性： 故障可诊断且不泄露密钥。
- 回滚安全性： 回滚路径和影响范围清晰。
优先使用检查清单风格的评论，带有一个明确的结果：
- 可合并（说明原因）。
- 需要作者操作（有序的阻塞项列表）。
- 需要更深入的安全/运行时评审（说明确切风险和所需证据）。
避免模糊的评论，以免造成不必要的来回延迟。
使用标签保持积压可执行：
- 不完整的 bug 报告标记为
r:needs-repro。 - 使用/支持问题标记为
r:support，更适合路由到 bug 积压之外。 - 不可操作的重复/噪音标记为
duplicate/invalid。 - 等待外部阻塞项的已接受工作标记为
no-stale。 - 当日志/有效负载包含个人标识符或敏感数据时，要求脱敏。
当评审需求超过容量时，按以下顺序应用：
- 将活跃的 bug/安全 PR（
size: XS/S）保持在队列顶部。 - 要求重叠的 PR 合并；经确认后将旧 PR 关闭为
superseded。 - 在 stale 关闭窗口开始前，将休眠 PR 标记为
stale-candidate。 - 重新打开 stale/被取代的技术工作前，要求 rebase + 新的验证。
当自动化输出产生评审副作用时使用：
- 错误的风险标签： 添加
risk: manual，然后设置预期的risk:*标签。 - Issue 分类时错误的自动关闭： 重新打开 Issue，移除路由标签，留下一条澄清评论。
- 标签垃圾信息/噪音： 保留一条规范的维护者评论，移除冗余的路由标签。
- 模糊的 PR 范围： 深度评审前要求拆分。
如果将评审交接给另一位维护者/代理，包含：
- 范围摘要。
- 当前风险等级和理由。
- 已验证的内容。
- 未解决的阻塞项。
- 建议的下一步操作。
- 评审 stale 队列，仅对已接受但被阻塞的工作应用
no-stale。 - 优先处理
size: XS/S的 bug/安全 PR。 - 将重复出现的支持问题转化为文档更新和自动响应指引。
- README.md — 文档分类和导航。
- pr-workflow.md — 治理工作流和合并契约。
- ci-map.md — CI 所有者和分类地图。
- actions-source-policy.md — Action 源白名单政策。
- 所有者： 负责评审质量和队列吞吐量的维护者。
- 更新触发条件： PR 政策变更、风险路由模型变更或自动化覆盖行为变更。
- 最后审核： 2026-02-18。