Skip to content

Latest commit

 

History

History
366 lines (242 loc) · 12.6 KB

pr-workflow.zh-CN.md

File metadata and controls

366 lines (242 loc) · 12.6 KB

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

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

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

相关参考：

0. 摘要

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

1. 按 PR 场景快速路由

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

1.1 提交信息不完整

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

前往：

1.2 CI Required Gate 检查失败

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

前往：

1.3 涉及高风险路径

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

前往：

1.4 PR 已被取代或重复

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

前往：

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. 相关文档

16. 维护说明

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