审查者手册
用于审查 PR 和分类问题的操作模型。其规模设计旨在在高负载下保持高质量的审查；通过风险进行路由，使高风险路径获得所需的关注，而无需让每个小改动都经过相同的关卡。
有关实际的拉取请求获取流程和审查结论机制，请参阅 PR 审查协议。本页面是 操作模型；协议是 流程。
快速路径
使用本节在深入阅读之前进行路由。每一行都链接到详细说明该部分的章节。
使用 PR lanes 确定路由预期；使用本手册的风险矩阵确定审查深度。
| 情况 | 操作 | 章节 |
|---|---|---|
| 前 5 分钟内摄入失败 | 留下一条可操作的检查清单评论，停止深入审查。 | 五分钟摄入 |
| 风险或安全边界分类不明确 | 向上归类，并在合并前与维护者协商解决 | 审查深度矩阵 |
| Diff 添加了一个并行解释层 | 验证它派生自规范来源，或明确指向规范来源 | 漂移面审查 |
| 自动化输出不正确或存在噪声 | 应用覆盖协议 | 自动化覆盖 |
| 需要移交另一位维护者 | 使用交接模板 | 交接 |
深度矩阵
| 触发器 | 常规工作 | 最小深度 | 所需证据 |
|---|---|---|---|
risk:low | 不会影响生产、兼容性、构建、发布或治理的文档、本地化内容、测试夹具、生成的引用或机械元数据 | 1 名审查者 + CI 门禁 | 一致的验证证据，无行为歧义 |
risk:medium | 常规的行为、运行时、网关、提供程序、通道、工具、配置、应用和 CI 工作 | 1 个子系统感知审查员 + 行为验证 | 聚焦场景证明，显式副作用 |
risk:high 或 domain:security | 一个具体的信任边界、凭据边界、兼容性边界、治理边界、发布授权边界或横切安全边界 | 快速分流 + 深度审查 + 回滚就绪 + 两项独立的 Core Team 审批 | 安全性和故障模式检查，回滚清晰度 |
domain:security 仍独立于 risk:*：只有存在实际的安全或信任边界时才使用它，而不应仅仅因为变更组件具有安全属性就使用。任一标签都会触发相同的深度审查流程，并要求获得两名相互独立的 Core 成员批准。自动化审查不计入 Core Team 批准。
如有疑问，请按更高类别分类，并请维护者在合并前确定边界。
风险标签目前由人工维护。#9345 规定，任何未来的风险分类器在维护者单独启用变更前都只能以仅报告模式运行。请遵循标签自动化契约：risk:manual 会在应保留维护者更正时冻结自动风险替换，但绝不会降低审查或批准要求。
标签属于维护者元数据。如果正确的标签显而易见且你拥有相应权限，请在完成审查前自行修正。仅当标签选择存在歧义，或没有具备标签权限的人员可用时，才询问作者。
标准工作流程
五分钟摄入量
对于每一个新的 PR，在查看任何代码之前：
- 确认 PR 模板填写完整：摘要、验证证据、安全与隐私、兼容性、回滚方案（适用于中/高风险变更）。
- 确认标签存在且合理：
size:*、risk:*、范围标签，以及适用情况下的贡献者等级。 - 确认
CI Required Gate信号状态。 - 确认范围是一个重要的考量因素。除非对混合功能有明确的理由，否则包含多种功能的超大 PR 会被退回要求拆分。
- 确认隐私/数据卫生规则。请参阅 隐私 获取完整规则。
- 如果 PR 更改了视觉呈现，请确认作者使用了实际受支持的界面，并提供了尺寸具有代表性且符合隐私安全要求的屏幕截图。声明未执行冒烟测试只能记录这一缺口，但并不能满足该要求。
如果任何准入检查失败，请留下一条可操作的清单评论并停止。不要对未通过准入的 PR 进行深度审查：在这一层进行反复沟通的成本，比在分析完差异后再进行要低。
快速通道清单（每个 PR）
- 作用域边界明确且可信。
- 行为变更会根据控制性契约进行检查：架构文档、事实来源模块、trait 边界、现有测试、公开 API 形状、源代码注释，或维护者的明确决定。
- PR 正文溯源为 true。引用的 RFC、审计、issue、PR、路径、生成的工件或后续发现均存在，并支持该声明。
- 验证证据会命名所依赖的检查，以及它们为何覆盖已更改的行为。
- 直接用户可观察的声明需标识用户边界，并提供能够到达该边界的最小可信证据；当单元测试、模拟测试、编译或通用 CI 证据不足以覆盖时，请使用 User-boundary proof。
- 视觉呈现变更包括来自可识别修订版本的实际界面证据，以及包含足够周围布局、可用于评估结果的屏幕截图。字符串断言、仅组件快照和辅助函数级渲染器测试不能替代此证明。交互和过渡声明还需注明用户操作和观察到的结果。
- 当 fresh 所需的 CI 已覆盖相同的 head、target 和 feature set 时，不需要重复的本地 Cargo。只有当它对应于所需 gate 中的一个明确缺口时，才要求额外验证，例如 macOS/Windows 测试、跨平台 Clippy、桌面覆盖、发布目标构建、过期的 CI 或不可用的 CI。
- 用户可见的行为变更已记录。
- 作者展示了对行为和影响范围的理解（尤其是对于 AI 辅助的 PR）。
- 回滚路径是明确的；而“revert”并不明确。
- 兼容性和迁移影响是明确的。
- MSRV、固定工具链或其他版本下限变更会被标记为影响兼容性：PR 会说明谁必须升级，CI 和安装程序基线保持一致，并且当该变更可能影响源码构建用户时，发布说明会注明新的最低版本要求。
- 没有个人数据或敏感数据泄露到差异制品中；测试使用中性、项目范围内的占位符。
- 命名和架构边界遵循项目契约（
AGENTS.md，Architecture overview）。
漂移面评审
将新增的重复性解释层视为评审风险。PR 不应添加注释、示例、生成的快照、映射表、配置镜像或并行注册表，重复描述已由代码、模式、测试、WIT、配置或运行时分派定义的行为，除非该新层是从相应权威来源机械生成的，或明确指向该来源。
当新增内容可能与源头脱节，且未来的读者、审阅者或自动化流程可能将其视为比源头更权威时，应予以阻止或要求修改。常见的例子包括：描述代码未强制约束的行为的注释、手工复制枚举或 schema 列表的文档、快照实现细节而非用户可观察行为的测试，以及复制已归属于另一模块的键空间的注册表。
优先选择以下分辨率之一：
- 移除重复的界面，并使规范所有者更易读。
- 从规范所有者生成辅助平面。
- 将复述替换为源指针，并附上该指针归属此处的原因。
why 注释仍然受欢迎，尤其是当它们捕捉到类型系统和测试无法表达的非显而易见的不变量、风险或权衡时。它们应当解释意图，而非重述附近的控制流，也不应成为第二份契约。
共享键空间的类型化分发
对于共享键空间，例如 wire 方法名称、编译后的 channel 类型键、provider 槽位或 frontend/backend 注册表键，应在 API 或配置边界解析原始字符串来应用此规则。下游代码应通过枚举、宏生成的表、trait/factory 注册表或其他规范所有者进行分派。不要添加并行的字符串 match 分支、手写的分发表，或必须靠审阅者记忆来保持同步的重复列表。
这并非禁止在 API 边界使用字符串常量。它防止出现第二个分发面——在那里添加新变体时可以编译通过，却悄然跳过某个消费者。好的例子是用于线路方法名的 RPC Method 注册表，以及用于通道编译键的 CHANNEL_COMPILE_SPECS，其中由单一权威所有者驱动下游的覆盖范围。
深度审查清单（仅限高风险项）
对于带有 risk:high 或 domain:security 的 PR，请为每个类别验证一个具体示例。一个具体实例胜过五个泛泛的声明。
- 安全边界：保留默认拒绝行为，避免意外扩大作用域。
- 故障模式：错误处理明确，安全降级。
- 契约稳定性：保留 CLI、配置或 API 兼容性，或提供迁移文档。
- Diff 形状：大型或新的集成 PR 现在是连贯的、合并有理由的、不容易拆分的，并且不是主要重复的机制。
- 生成的工件：影响策略、schema、路由、迁移、lockfiles、发布工件、能力、包、运行时行为或审阅者证据的生成文件，按源码同等标准审查。
- 工具链兼容性：MSRV 或固定工具链的变更是有意为之的，且在 CI/Docker/安装相关各处保持一致，并已为下游/源码构建用户记录说明。
- 可观测性：在不泄露敏感信息的情况下诊断故障。
- 回滚安全性：回滚路径和影响范围清晰明确。
注释形状
优先使用清单式注释，每条注释明确一个结果：
- 准备合并（说明原因）。
- 需要作者操作（按顺序排列的阻塞项列表）。
- 需要更深入的安全或运行时审查（说明具体风险及所需证据）。
模糊的注释会导致不必要的往返沟通。如果你发现自己正在写“这可能是一个问题”，请多花 30 秒，将其转化为具体的场景，或者直接删除该注释。
问题分类
相同的风险路由原则同样适用于问题（issues），但标签和信号有所不同。
Issue 的 risk:* 标签描述的是报告中预估的修复影响范围。PR 的 risk:* 标签描述的是正在审查的实际 diff。当 Issue 转为 PR 时，应重新评估风险，而不是自动沿用 Issue 上的标签。
分类标签
| 标签 | 何时使用 |
|---|---|
r:needs-repro | 缺少确定性复现步骤的错误报告。阻止对此进行更深入的分类处理。 |
r:support | 使用或帮助问题更适合在错误跟踪系统之外处理。 |
status:accepted | 团队已接受该 RFC 或工作项。仅当该 issue 还需要防止过期保护时，才添加 status:no-stale。 |
status:blocked | 有效的工作正在等待外部依赖、维护者决策或关联的前置条件。请记录该阻塞项；只有在该阻塞项尚未解决期间，此操作才属于过期保护。 |
status:in-progress | 一个开放的 PR 正在积极处理该议题。在过期检查过程中依赖此状态前，请重新核查 PR 的实时状态。 |
status:no-stale | 已接受或其他长期存续的工作应保持开放状态，且尚未受到其他陈旧豁免的保护。请使用项目看板约定中贡献者可见的来源记录原因和路由证据。活跃的发布跟踪器以及活跃的 RFC 或设计跟踪器，在其保持活跃状态期间，可将跟踪器本身用作可见的原因和路由界面。 |
type:tracker | 发布、roadmap、RFC/设计讨论串、实现批次、清理或审计的活动父级协调问题。仅在该活动标签存在时使用；不要替换为 roadmap 或 type:roadmap。这只是一个查找/路由标记，本身并不表示防止陈旧。 |
good first issue | XS/S 级别、自包含、有完整文档且验收标准清晰的工作，包含相关代码或文档链接、指定的导师或联系人，且上手风险低。 |
help wanted | 维护者希望外部协助处理且可供审查的、可执行且无阻塞的工作。请勿将其用作通用的有效/无归属标记。 |
Assignee 表示有人正在处理。路由依据记录了为何某个问题需要特殊的过期保护、跟踪器处理或延迟的维护者决策。status:blocked 仅需记录未解决的阻塞项，除非它同时还需要单独的 status:no-stale 保护。项目看板约定定义了可接受的依据来源和路由结果。标签可以标识可能的领域，但仅凭标签并不代表归属权或过期保护。
分辨率标签
仅在关闭或从活动队列中移除条目时使用解决方案标签。它们用于说明最终结果；对于应保持开放的工作项，它们不会取代 status:* 生命周期标签。标签指南是当前解决方案标签定义和迁移保留项的权威来源。
对于重复项，在关闭或重定向讨论之前，请先链接到规范的目标。对于无效报告，请说明是什么导致该报告无法处理，或者它应该被提交到何处。对于我们明确选择不去处理的工作，请使用看板级别的 Won't Do / 实时 wontfix 路径，并留下简要的理由说明。
对于已替换的 PR 或 issue 路径，请使用替代 PR，并在相关时保留贡献者署名。
如果报告中的日志或有效载荷包含个人标识符或敏感数据，请在进行更深入的分诊之前请求脱敏。分诊过程不得传播此类暴露。
讨论管理
只有当存在管理员或定期审查机制时,Discussions 才是受维护的社区阵地。默认的审查周期为每周由维护者对新建及近期活跃的讨论帖进行一次梳理。可以指定一名管理员负责该阵地的梳理工作,但管理员维护的是阵地本身;他们并不会因此成为其中出现的每一个问题、想法或实现的责任人。
在每次 Discussions 处理过程中：
- 检查新的和近期活跃的话题，关注分类是否合适、未回答的问答、垃圾内容、敏感数据，以及已产生具体项目成果的话题。
- 当社区对话仍处于探索阶段、可在 Discussions 中得到解答，或可作为展示、演示、投票、公告或广泛反馈的话题时，请将此类轻量级交流保留在 Discussions 中。
- 将具体成果提升到对应的跟踪渠道：缺陷和已接受的功能范围归入 issues，架构提案归入 RFC issues，PR 相关的细节归入 PR 评论，长期有效的运作规则归入维护者或贡献者文档。
- 在原始讨论中收尾，附上简短总结，并链接到现在负责该结果的 issue、RFC、PR 或文档。仅当分类和结果确实准确时，才标记为答案。
- 将安全敏感的话题引导至安全问题中的私有漏洞报告渠道，根据隐私处理敏感数据，并关闭纯广告或与项目无关的话题。对于有用的项目相关演示或集成内容，若其并非要求维护者跟踪处理，则将其保留为社区展示材料。
如果未按照文档规定的周期审查 Discussions，请勿将其作为必需的接收渠道呈现。在恢复管理员或审查周期之前，应将其视为被动归档。
PR 积压清理
选择下一轮审查时，使用仅报告队列快照：
python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table
该命令是对 GitHub 实时状态的按需视图，不是持久队列，也不是合并裁决的依据。此 all 快照会独立运行共享通道，因此同一个 PR 可能出现在多个通道中；添加 --author LOGIN 可包含 mine。使用 --queue near-ready 可从 GitHub 搜索状态成功且由维护者路由的 PR 开始；这会优先处理可能更接近合并的候选项，但不表示它们可合并或已获得足够批准。使用 --format json 进行检查或下游报告，使用 --format links 获取 GitHub 搜索链接。GitHub 搜索提供候选列表；脚本仅读取时间线以确定作者操作距今的时长，并且仅读取评审以确定当前头提交的 second-Core 路由。缺失或有歧义的细节仍视为未知。在实际评审期间确认可合并性、检查结果以及批准是否适用。优先处理并评审 Depends on #... 父 PR，然后再处理子 PR；如果父 PR 无法评审，则推迟对子 PR 的深入评审，除非某个边界明确的独立部分可从提前评审中受益；然后在父 PR 合并后刷新并重新验证子 PR。堆叠 PR 仍属于单独的报告通道，不会仅仅因为存在时间较长就具备评审条件。
当审查需求超过容量时：
- 将活跃的 bug 和安全 PR（
size:XS或size:S）置于队列顶部。 - 请重叠的 PR 进行合并；在作者确认后，以被取代或被替换为由关闭较旧的 PR。归属规则请参阅 Superseding PRs。
- 使用下面的 PR 过期处理流程。PR 积压清理使用
needs-author-action和stale-candidate；问题过期扫描则依据规范的问题过期策略使用status:stale。
当维护者提交请求变更（request-changes）的评审，并且下一步操作需要由 PR 作者完成时，请在同一评审/标签操作中应用 needs-author-action。如果所请求的变更可由维护者修复，且维护者打算自行推送清理，或者由另一位维护者或负责人接管该分支，或者该阻塞是在等待维护者决策而非作者工作时，则不要添加该标签。
| 状态 | 何时使用 | 必需的公开说明 | 后续 |
|---|---|---|---|
needs-author-action | 下一步 PR 需要作者来处理：rebase、解决冲突、拆分范围、回复审阅意见、按要求修改代码，或重新进行验证。 | 审查或评论指明了具体操作。当变更请求审查将下一步操作交由作者处理时，应应用此标签。 | 当作者推送实质性更新或提供所请求的信息时，移除该标签，然后继续正常审查。这本身并不是关闭警告。 |
stale-candidate | 先前的作者操作请求一直未获回复，导致该 PR 现在阻塞了有用的审查；或者相对于当前 master，该分支显然已过时、脏乱或已废弃。不要将处于可见维护者计划、明确依赖、活跃负责人或已记录的回访日期下的搁置工作升级为 stale。 | 注释会标明所请求的操作和一个后续日期，通常是 7-10 天后，除非维护者选择更长的期限。它应将陈旧的分支与仍然有效的 bug 或功能请求区分开来。 | 在跟进日期，重新检查实时状态。如果作者已回复，或者该分支已变为可审查，则移除或继续保持 stale-candidate 不开启。如果仍无回复，且没有维护者接手或替代路径，则以 backlog 清理为由关闭，并提供明确的重新开启或替代路径。 |
如果底层 bug 或功能需求仍然有效，请将其保留在 issue、跟踪行、替代 PR 或接手计划中，而不要暗示该想法已被拒绝。对于任何已因长期未活动而关闭的内容，重新开启前都需要 rebase + 最新的验证证据。
自动化覆盖
当自动化输出产生审查副作用时，请使用此方法：
- 风险标签错误：设置预期的
risk:*标签。如果将来启用了风险自动化，还应遵循 标签自动化契约 中关于risk:manual的规定；此覆盖设置不会绕过risk:high OR domain:security审批规则。 - 问题分流时错误地自动关闭：重新打开，移除该路由标签，并留下一条澄清说明的评论。
- 标记垃圾信息或噪音：保留一条规范的维护者注释，移除冗余的路由标签。
- PR 范围不明确：在深入审查之前先要求拆分；不要试图同时审查两个不相关的关注点。
交接
在将审查权移交其他维护者或代理时，请包含：
- 范围摘要。
- 当前风险类别及理由。
- 你已验证的内容。
- 未解决的阻塞项。
- 建议的下一步操作。
这有助于降低上下文丢失的风险，并避免下一位审阅者重复执行你已经完成的拉取操作。
每周队列清理
- 遍历过期队列。仅在符合项目看板约定规则的情况下应用
status:no-stale：当已接受或其他长期存续的工作有保持开放状态的明确记录原因、对贡献者可见的路由证据，且没有其他过期排除规则已经适用时。当 issue 本身明确指明了活跃的协调或决策范围时，活跃的发布跟踪器以及活跃的 RFC 或设计跟踪器默认可以保留过期保护；当里程碑关闭、跟踪器偏离实时状态、RFC 做出决策、被取代或关闭，或 issue 不再代表活跃的项目决策范围时，需重新审视它们。在过期豁免审计落地之前，将缺少这些事实的现有status:no-staleissue 视为审计发现，而非自动过期候选项。 - 优先处理
size:XS或size:S的 bug 和安全 PR。 - 将重复出现的支持问题转化为文档改进和自动回复指导。
目标是建立这样一个队列：每个开放的 PR 都处于以下状态之一——正在被积极审查、等待作者处理，或者被某些外部因素阻塞，而绝不能仅仅因为没人处理而搁置。