PR 工作流
面向维护者的 PR 治理合同，适用于目标分支为 master 的 PR。分支保护设置、DoR/DoD 就绪合同以及故障恢复协议均在此处。日常审查工作详见 审查者手册。面向贡献者的流程请参见 如何贡献。
治理目标
该工作流的存在是为了在高 PR 量下保持以下五项内容正确无误：
- 合并吞吐量是可预测的。
- CI 信号质量保持高水平，反馈快速，误报率低。
- 安全审查明确针对高风险区域。
- 变更易于理解和回滚。
- 仓库中的工件不包含个人或敏感数据。
实现这一功能的控制循环是分层设计的：
- 接收分类：根据路径、大小、风险标签将 PR 分流到适当的审查深度。
- 确定性验证：合并门控依赖可复现的检查，而非主观评论。
- 基于风险的审查深度：对高风险后果和安全边界进行深入审查，同时让低风险工作保持高效。
- 回滚优先合并约定：每条合并路径都包含具体的恢复方案。
自动化负责路径/范围标签、手动问题仪表板规划报告以及 CI 门禁。风险、大小、类型和贡献者层级标签属于维护者在接收时的决策，除非某个维护中的工作流明确负责这些标签。最终合并责任由人工维护者和 PR 作者承担。带有 risk:high 或 domain:security 任一标签的 PR 需要深度审查，并获得两项相互独立的 Core Team 批准；自动化审查不计作 Core Team 批准。
项目看板合约
项目看板是一个自动化规划看板，而非权威的 PR 评审队列。
使用看板来管理问题就绪状态、路由证据、路线图分组、依赖关系、阻塞状态以及过期豁免原因。这些信号变化足够缓慢，因此看板字段或规划泳道能够持续发挥作用。
当前自动化是手动且仅用于报告。project-dashboard-plan.yml 在 workflow_dispatch 下针对单个 issue 编号运行，读取 issue 负载，并写入步骤摘要，建议一个最符合该 issue 当前标签和状态的现有 Project Status 值。它不会写入 Project 字段、编辑 issue、添加标签、发布评论，也不会在 issue 事件上自动运行。
此规划拆分的 JSON 摘要位于 project-board-contract.json 中。将其视为仅报告规划器和未来看板刷新自动化的契约，而不是对自动 issue 事件运行或主动修改 GitHub Project 的批准。对 Live ProjectV2 的写入需要已批准的字段映射、项目范围凭据或 app 安装，以及在维护者依赖它之前，将计划状态与实时 Project 状态进行比较的回读。
请勿将原生 PR 审查状态镜像到手动看板泳道。GitHub PR 状态拥有审查决策、必需检查、可合并性、冲突、过期批准和合并就绪状态。如果看板后续显示派生的 PR 路由信息（如 DIRTY、BEHIND 或 APPROVED），应将其视为 GitHub 状态的仪表盘视图，而非独立的事实来源。
这样可以保持看板的实用性，而无需在每次推送、审查或 CI 运行后都要求维护者更新它。
大小和风险的自动标记是两个独立的工作流问题。#9345 可能会在 PR 更新时重新计算确定性的大小标签。在维护者审查证据并单独启用风险标签变更之前，其风险分类器仍处于仅报告模式。风险自动化必须遵循 risk:manual，直到维护者移除该覆盖项。issue-dashboard 规划器不会应用或重新计算 PR 的风险、大小或类型标签。
问题路由依据
问题分类仍然是维护者共同承担的责任。已接受的问题无需在保持开放状态之前建立固定的负责人映射，CODEOWNERS 也不会让代码负责人对其匹配区域内的每一个问题负责。
当某种特殊状态会导致 Issue 无法被纳入常规审查或过期清理时，该 Issue 需要提供贡献者可见的路由依据：status:no-stale、活跃的发布/RFC/设计追踪状态，或被推迟的维护者决定。status:blocked 沿用其更简单的规则：记录尚未解决的阻塞项，并在阻塞项解除后重新评估过期保护。
我会持续使用这些含义。
| 路由信号 | 方式 | 并不意味着 |
|---|---|---|
| 负责人 | 有人正在积极实施、调查或推进当前的工作。 | 对每个相关问题的永久区域所有权或被动责任。 |
| 路由依据 | 可见的问题评论、正文部分、公开字段、看板字段或关联的跟踪记录会记录特殊处理的原因以及下一个决策环节。 | 自动实现所有权或永久区域所有权。 |
| 追踪器/RFC 界面 | 活跃的发布跟踪器、RFC 或设计跟踪器在其保持最新状态时可以作为协调载体。 | 在跟踪器关闭、偏移或不再代表有效决策后，提供永久性陈旧保护。 |
| 项目看板字段 | 用于就绪状态、路由依据、阻塞状态或过期豁免理由的可选规划信号，仅在其可见且持续维护时适用。 | 私有的过时策略来源或原生 PR 审查状态的替代项。 |
| 标签和 CODEOWNERS | 持久化分类、可能的领域路由以及 PR 审查咨询提示。 | 所有权或过期保护本身。 |
CODEOWNERS 是一种 PR 审查路由机制。当某个问题明显涉及某个路径时，它可以帮助识别应当咨询的人员，但它并不创建问题归属关系，也不应被复制到过时的策略中充当私有路由映射表。
路由的依据在于下一步决策，而非交付归属。已路由的 issue 不应停留在“已认领“的悬而未决状态；下一次可见的更新应当明确以下结果之一：指派一名活跃的实现者、使 issue 达到可供贡献者参与的状态、将其路由至某个跟踪器或里程碑、记录阻塞因素、安排一个具体的维护者决策节点，或附带理由将其关闭/推迟。
仅当议题记录了需要做出何种决策、该决策将在何处跟踪以及何时复审时，将其安排进入维护者分流流程才是有效的。在完成该分流环节后，应将分流路由替换为活跃的实现者、可供贡献者参与的范围、跟踪器或里程碑路由、阻塞/延期状态，或关闭理由。
对于受保护的 issue，在添加或保留 status:no-stale 之前，请同时记录免于过期处理的原因和下一个决策节点。有用的可见证据来源包括：
- 负责人正在积极处理，并附有在 issue 中可见的说明、正文部分或追踪条目，解释为何不应进行过期处理；
- 问题评论、问题正文部分或记录过期豁免原因和后续决策界面的公开问题字段；
- 对普通问题读者可见且持续维护的公开 Project 字段；
- 记录该问题为何保持开放状态以及何时应重新审视的关联公共跟踪记录、里程碑、RFC 或设计问题。
活跃的发布跟踪器以及活跃的 RFC 或设计跟踪器是持久性的协调载体。当 issue 标题、正文、标签或里程碑明确表明这是一个活跃的跟踪器或 RFC 时，跟踪器本身即可提供过期豁免理由以及贡献者可见的路由载体；无需在每个 issue 上重复添加评论。当里程碑关闭、跟踪器偏离当前发布状态、RFC 达成决议、被取代或关闭，或该 issue 不再代表活跃的项目决策载体时，应重新审视该豁免。
当需要 tracker 标记标签时，使用 type:tracker。它适用于仅包含 issue 的父协调面，例如发布 tracker、roadmap 或 epic tracker、RFC/设计 tracker、实现批次 tracker、清理 tracker 和审计 tracker。不要将其应用于普通子 issue、普通功能请求、bug、PR，或仅从 tracker 链接出来的条目。type:tracker 有助于人类和自动化找到父级面；它不能替代必需的 stale 豁免原因、下一决策面、milestone、assignee 或关闭标准。如果 live 标签尚不存在，不要用 roadmap、type:roadmap 或其他别名替代；请通过单独的精确标签包创建并迁移规范标签。
如果以上情况均不存在，且该 issue 不是活跃的追踪器或 RFC，则该 issue 在分类工作继续期间仍可保持开放状态，但不应将 status:no-stale 作为永久挡箭牌依赖。在过期豁免审计落地之前，缺失原因或路由证据属于审计发现及建议修正项，而非自动触发过期关闭的条件。
命名里程碑策略
命名里程碑是能力域中针对有限范围成果的有限交付批次，而不是永久性的领域待办列表。根据此政策，命名里程碑应围绕成果组织，而不是围绕编号版本发布；Parking Lot 和 Icebox 是暂存区，而不是命名里程碑。将每个新里程碑命名为 Domain: Bounded Outcome。优先使用 RPC Client: Authentication & Authorization，而不是 Auth 这类宽泛且可复用的名称。组合标题会占用其中命名的每个领域。
将每个已开启的命名里程碑视为活跃状态。在开启另一个里程碑之前，维护者必须明确确认有足够的协调和审查能力来支持新增批次。记录该批次为何不能等待，以及预计下一个关闭的是哪个当前里程碑。当容量耗尽时，在某个里程碑关闭或拟议工作合并到现有批次之前，不得再开启其他命名里程碑。每当维护者可用性或审查负载发生重大变化时，都要重新评估容量。
每个域最多保留一个处于活动状态的命名里程碑。经维护者明确批准的例外情况下，如果决策记录了增加的协调成本为何合理，则同一域中的独立成果可以并行推进。
每个有名称的里程碑都需要明确的范围和关闭标准，但截止日期并非必需。不要让已暂停的批次保持开放：重新分配其中未完成的工作，并关闭该里程碑。在关闭任何有名称的里程碑之前，关闭或重新分配每个未完成的问题，并添加关闭备注，说明结果是已完成、已取消还是已被取代。已关闭的有名称里程碑应保持关闭。只有在存在足够连贯的范围、能够定义另一个有限结果时，后续工作才能构成新的有名称里程碑。根据该结果为里程碑命名；默认不要创建滚动式的 v2、v2.1 或类似的后续里程碑。
GitHub 允许一个 issue 或拉取请求仅属于一个里程碑。完成指定 cohort 所需的工作，在完成前始终保留在该指定里程碑中，即使它随某个编号版本发布。请在版本发布跟踪器和变更日志中记录版本包含情况。对于指定 cohort 之外的紧急 bug、维护工作及其他与版本发布绑定的工作，请使用编号版本里程碑。
一旦某个命名里程碑处于活动状态，新接收的工作仅限于完成其指定批次所需的工作：直接范围、阻塞项、依赖项和回归问题。按意图分流其他工作：
| 目的地 | 用于 |
|---|---|
| 当前命名的里程碑 | 完成里程碑所定义群体所需的工作。 |
| 编号的发布里程碑 | 不属于指定群组的紧急 bug 修复、维护或其他受版本发布约束的工作。 |
| RFC 或设计问题 | 设计或治理方向尚未确定的工作。 |
停车场 | 在维护者决定下一个具体归属位置之前的短期路由。 |
Icebox | 对于拥有活动命名里程碑的域，当其不属于当前批次且近期未安排时，属于有效的未来工作。 |
PR 通道
PR 通道是路由预期，而非另一套必需的标签体系。可借助它们来判断一个 PR 需要多少审查深度、排序优先级以及维护者关注度。CODEOWNERS、GitHub 原生审查状态、CI、标签、关联议题以及明确的关系关键字仍承载着实际的路由数据。
| Lane | 常见示例 | 预期移动 |
|---|---|---|
| A：维护快速通道 | 仅文档更正、不改变行为的小型测试、元数据/模板修复、范围明确的示例、在保留权限和发布行为前提下的 CI/工具链修复 | 最轻量级审查；当 CI、模板、标签和隐私检查都通过后即可快速合并。通常为 risk:low 和 size:XS 或 size:S。 |
| B：缺陷修复专用通道 | 有明确失败行为的小型缺陷修复，针对特定提供商/通道/工具且经过聚焦验证的修复，以及在所报告路径之外保持行为不变的兼容性修复。 | 由一位了解子系统的审阅者进行常规审查，除非风险或所有权另有要求。当关联的 issue 确实得到解决、验证可信且 CI 通过时即可合并。 |
| 功能切片泳道 | 新增功能开发、新增提供方/通道/工具支持、新增配置项、范围明确的用户可见行为变更 | 常规审查外加针对边界的专项验证。里程碑契合度很重要，PR 应当说明它是实现、依赖于还是关联到某个跟踪项。 |
| D：架构、迁移和升级审查通道 | 具体的信任、凭据、兼容性、治理、发布权限、迁移、生命周期、持久性、权限或工具链最低版本边界；任何带有 risk:high 或 domain:security 的 PR | 深入审查、与变更风险相匹配的证据，以及回滚和兼容性分析。带有 risk:high 或 domain:security 的 PR 还需要两名独立 Core Team 成员的批准。 |
| E：取代、替换和重叠通道 | 多个 PR 解决同一问题、较新的 PR 取代较旧的 PR、从其他 PR 延续而来的贡献者工作、因当前 master 而过时的旧 PR | 在深入审查前先做好协调。尽可能选择一个规范路径，仅在准确的情况下使用 Supersedes #N，并在工作被实质性延续时保留署名归属。 |
除非原生 GitHub 状态和 CODEOWNERS 无法回答路由问题，否则不要为这些 lane 单独搭建手动 PR 看板。在常规 lane 审查前先检查原生 GitHub 合并状态：DIRTY 表示需先解决冲突；单独的 BEHIND 只是可合并性的常规维护，并非面向作者的阻塞项。
必需的仓库设置
master 分支的保护设置：
- 合并前要求状态检查。
- 需要检查
CI Required Gate。 - 合并前需要拉取请求审查。
- 要求受保护路径需经 CODEOWNERS 审查。
.github/**（包括.github/workflows/**）归.github/CODEOWNERS中列出的维护者所有，因此工作流变更需要相应负责维护者的审查。 - 将分支 / 规则集绕过权限限制为组织所有者。
- 当推送新提交时，撤销过期的审批。
- 限制强制推送。
- 所有贡献者的 PR 都直接指向
master分支。
就绪定义（DoR）
在请求审查之前，PR 应具备以下内容：
- PR 模板已完整填写。
- 明确范围边界（哪些内容已更改 / 哪些内容未更改）。
- 已附验证证据，为实际命令输出，而非“CI 将进行检查”。
- 安全和隐私、兼容性，以及（对于高风险路径的）回滚字段已填写完成。
- 隐私与数据卫生规则已满足，措辞中立且限定于项目范围的测试。参见 隐私。
- 不可避免时，身份类表述使用 ZeroClaw / 项目原生标签。
完成定义（DoD）
合并前：
CI Required Gate为绿色。- 所需审阅者已批准（包括任何 CODEOWNERS 路径）；带有
risk:high或domain:security的 PR 已获得两项独立的 Core Team 批准。 - 风险标签与实际差异和后果相匹配，而不是笼统的组件位置。请参阅 标签。
- 迁移/兼容性影响已记录。
- 回滚路径具体且快速。
维护者合并检查清单
每次合并：
- 范围明确且易于理解。
- CI 门禁已通过。
- 当文档发生变化时，文档质量检查已通过。
- 安全和隐私字段已完整；证据已脱敏/匿名化。
- 带有
risk:high或domain:security的 PR 必须获得两项独立的 Core Team 批准；自动化审查不计入其中。 - 如果使用了 AI 辅助，工作流笔记足以保证可复现性。
- 回滚计划是明确的。
- 提交标题遵循 Conventional Commits 规范。
使用压缩合并（squash-merge），并在提交正文中保留完整的提交历史。squash-merge 技能会同时生成紫色的 Merged 徽章和符合 conventional-commits 格式的正文，调用方式请参阅 Skills。
AI / 代理贡献政策
欢迎使用 AI 辅助的 PR。审查也可以由代理辅助完成。
必需：
- 清除 PR 摘要，明确范围边界。
- 明确的测试/验证证据。
- 高风险变更的安全影响和回滚说明。
推荐：
- 当自动化显著影响变更时，简要的工具/工作流说明。
- 用于可复现性的可选提示/计划片段。
我们不要求贡献者量化 AI 与人工的行所有权。差异和验证证据足以说明问题。
对于 AI 相关的 PR，审查者会重点关注：
- 合同兼容性。
- 安全边界。
- 错误处理。
- 性能和内存回归。
- 作者是否能够回答关于行为和影响范围的问题（意图理解）。
审查服务等级协议（SLA）和队列规则
- 首要维护者审查目标：48 小时内。
- 被阻止的 PR 会收到一个可操作的清单评论，而不是一系列部分审查。
status:no-stale保留用于已接受或其他长期存续的工作，前提是记录了 stale 豁免原因，并在该 issue 尚未受其他 stale 排除规则保护时提供贡献者可见的路由证据。活跃的发布跟踪器以及活跃的 RFC 或设计跟踪器，在其保持活跃期间，可将跟踪器本身作为该可见原因和路由载体。缺失上述事实的现有豁免在 stale 豁免修复补丁落地之前均视为审计发现项。
对于堆叠工作，要求显式使用 Depends on #...，以确保审查顺序是确定的。
在操作上应用这一确定性顺序：先于子项确定优先级并审查父项；当父项无法审查时，延后对子项的深入审查，除非某个范围受限的独立切片能从提前审查中受益；父项落地后，刷新并重新验证子项。父项变得可审查，并不会使先前收集的子项证据自动成为最新证据。
如需获取实时 GitHub 队列的仅报告快照，请运行 python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table。--queue 的值包括 near-ready、maintainer、second-core、author-action、stacked、mine 和 all；--format 接受 table、json 或 links。near-ready 会将维护者队列缩小为 GitHub 搜索状态成功的 PR，使维护者可以从合并前可能需要较少工作的候选项开始；它不能证明 PR 可合并或审批已充分。all 会独立运行共享队列，因此同一个 PR 可能出现在多个队列中；添加 --author LOGIN 可包含 mine 队列。GitHub 搜索提供候选列表。只有 author-action 会读取时间线详细信息来估算未回应请求的时长，只有 second-core 会读取审查信息，以查找当前 head 上的一个 Core 审批。该命令从不写入队列状态或修改 GitHub，并会将缺失或含糊的详细信息报告为未知。它是工作选择辅助工具，而不是合并就绪性的证据。
对于替换操作，必须显式使用 Supersedes #...。有关归属和模板规则，请参阅 替换 PR。
审阅者侧的队列管理、积压清理顺序、过期处理和标签维护，详见 Reviewer Playbook。
安全性和稳定性规则
请仔细检查以下路径，因为其中通常包含与边界相关的行为：
crates/zeroclaw-runtime/（包括src/security/）crates/zeroclaw-gateway/（入口、身份验证、配对）crates/zeroclaw-tools/（任何具有执行能力的组件）.github/workflows/和发布流水线
仅凭路径位置不足以选择 risk:high。请根据 标签 → 风险标签 对实际差异及其后果进行分类。对于信任边界、凭据边界、兼容性边界、治理边界、发布权限边界或跨领域安全边界，如果 PR 带有 risk:high 或 domain:security，则需进行深入审查。
即使 diff 很小，也应特别关注这些 crate 内部的文件系统访问边界以及网络或身份验证行为。
**risk:high 或 domain:security PR 的最低要求：**威胁或风险说明、缓解措施说明、回滚步骤，以及两位相互独立的 Core Team 成员的批准。
对于 risk:high 或 domain:security PR：建议编写一个用于验证边界行为的针对性测试，并额外提供一个明确的故障模式场景及预期的降级行为。
对于跨越这些边界的代理辅助贡献，审阅者还会核实作者能否讲清运行时行为和影响范围，而不只是粘贴验证输出。
故障恢复
如果合并的 PR 导致回归：
- 立即在
master上执行 revert。 - 打开一个带有根本原因分析的后续问题。
- 重新引入该修复，并附带覆盖该失败模式的回归测试。
优先快速恢复服务质量，而非延迟的完美修复。
本页未涵盖的内容
- 日常审查机制：参见 Reviewer Playbook 和 PR Review Protocol。
- 标签阈值和定义：参见 Labels。
- 隐私与 PII 规则：参见 Privacy。
- 取代归属和模板：参阅 Superseding PRs。
- CI 工作流清单与分类处理：参见 CI & Actions。
- 发布流程：参见 Release Runbook。