oss-issue-triage

OSS 问题分流

你负责设计系统，决定项目收到的问题和拉取请求如何处理——标签、受理流程、响应承诺、值班轮换、关闭规则——并使之与维护者实际拥有的处理能力相匹配。

队列失控，不是因为标签不对，而是因为涌入量超出了可用精力，却没有成文规则说明如何处理超出的部分。把这笔账算清楚，再据此进行设计。

机器生成的提交在 2025 年打破了其中一项平衡。RedMonk 的 Kate Holterhoff 在 2026 年 5 月为安全报告中的这种不对称现象命名：“如今，生成一份听起来像那么回事的漏洞报告，只需花几分钱的 token。评估它是否属实，仍要耗费专家一小时。”涌入量不再受人力限制，而分流能力依然有限，因此每套设计都必须为数量制定应对方案，不能只考虑分类。

不要分流单个项目、整理首次贡献队列、审查代码或处理行为准则事件。将这些工作转交给其他流程：

• 首次贡献路径、适合新手上手的问题：samber/developer-relations-skills@oss-contributor-onboarding
• 将重复问题补充到文档中：samber/developer-relations-skills@developer-troubleshooting-docs
• 敌对行为：samber/developer-relations-skills@developer-community-moderation
• 谁来决定范围：samber/developer-relations-skills@oss-governance
• 维护者自身的处理能力、暂时退下或交接职责：samber/developer-relations-skills@oss-maintainer-sustainability
• 功能请求的产品决策及对请求者的回复：samber/developer-relations-skills@developer-feedback-loop
• 更广泛的衡量框架：samber/developer-relations-skills@developer-community-health

访谈

每次只问一个问题；尽可能采用选择题，并跳过用户已回答的问题。问题 1-6 决定后续所有工作；如果没有这些答案，你设计的就是一个虚构项目的流程。

记忆：记录当前任务或项目背景的少量信息。如果记忆存储在文件中，请使用 devrel-context.md；如果使用的是其他记忆系统，则以该系统为准。将任务信息放在不同部分。完成的任务要删除。为任务添加日期；一般项目背景不加日期。不同任务的部分访谈回答可能有所不同。

1. 工作量上限是多少：今天有多少人负责分诊，在工作量大的月份里，每人每周能投入多少小时？是否有人可以增加分诊人员或更改跟踪器设置？
2. 是否有必须在某个日期前落实的要求——例如发布、审计，或已向他人公布的响应目标？
3. 你想清空这个待处理队列，还是想建立一个明年更换维护者后仍能运作的系统？
4. 队列有多大：未关闭的问题、未关闭的外部拉取请求，以及最早条目的创建时间？
5. 收到的内容主要是什么——错误报告、功能请求，还是使用问题？
6. 项目由志愿者维护、由公司支持，还是两者兼有？是否有人承担合同规定的响应义务？
7. 使用的是哪个跟踪器？你能否更改其中的标签、模板和自动化？目前有哪些现成配置（标签、模板、贡献指南、机器人）？
8. 外部拉取请求是否算作这里的分诊工作，还是由单独的审查流程负责？
9. 过去一年，低质量或机器生成的提交所占比例是否有所增加？能否估算？
10. 目前通过什么渠道接收安全报告——公开跟踪器、私密渠道，还是没有明确渠道？
11. 使用问题应该转到哪里——论坛、聊天、讨论区，还是目前没有渠道？
12. 谁可以关闭问题？谁决定哪些内容超出范围？是什么促使你现在着手处理？

如果问题 1 的回答实际上是每周可投入时间为零，就停止设计并如实说明：真正可行的交付内容是减少受理量，并发布“本项目处于维护模式”的声明，而不是制定没人会执行的分类体系。

问题 1、2 和 3 的答案会重新排列下方的所有选项；说明哪些选项因此发生了变化。

• 时间紧迫：优先安排本周可采取的措施（缩短承诺、设置分流选项、检查方向）；降低需要一个季度才能见效的措施的优先级。
• “明年仍能运作”：优先考虑增加分诊人员和使用经过验证的表单；这两项措施的收益不会在任何单个月内体现。
• 工作量上限低：应删除选项，而不是降低其优先级——如果无权增加人员，那么“增加分诊人员”就不是可用手段，不应出现在交付内容中。

第 1 步 - 先衡量队列，再进行更改

导出跟踪器中的问题并运行基线分析；之后的每项决策都应参考这些数据。

gh issue list --state all --limit 2000 \
  --json number,title,state,createdAt,updatedAt,closedAt,labels,author,comments > issues.json
python3 scripts/triage-baseline.py issues.json --triage-prefix "kind/,priority/"
python3 scripts/triage-baseline.py issues.json --stale-days 120 --format json > baseline.json

此分析会根据 JSON 数组、JSON Lines 或 CSV 报告：

• 未关闭条目数
• 条目年龄的中位数和第 90 百分位数
• 未分诊条目占比
• 不活跃条目数
• 首次人工响应时间的中位数和第 90 百分位数
• 新建与关闭条目的流量
• 标签使用情况，包括仅使用一次的标签

如果没有可运行脚本的环境，就手动抽查 50 个未关闭条目，并估算相同的数据——估算也比盲目设计好；没有基线，就无法判断重新设计是否有效。

提出任何方案前，先复述这些数据：如果队列中 80% 是使用问题，所需的干预措施就与 80% 是未获答复的错误报告时不同。

然后追问，逐条处理的方式是否掩盖了什么：这些条目是否集中在少数共同问题上？ 对于积压严重的队列，将具有共同根因的问题归并到一个跟踪问题下，并将其余问题引导至该跟踪问题，通常比逐条分诊能清理更多积压。应在设计逐条处理机制之前，先决定按条目处理还是进行归并。

步骤 2 - 计算处理能力

用分诊人员数量 × 每周分诊次数 × 每次分诊分钟数 ÷ 每项所需分钟数，计算处理能力，并与基线流入量进行比较。

不要套用固定的每项处理分钟数。在步骤 9 中记录试点分诊时长，并采用项目自身的数据；在此之前，3 分钟只是本技能设定的规划占位值，并非行业实测数据。深入调查不属于分诊工作，而是分诊安排的工作。

当处理能力低于流入量时，任何标签方案都无法解决问题。有 3 种方法可以弥补差距；应根据每小时维护者工时能缓解多少队列来选择，而不是看哪种方法最快就能实施：

• 效率：减少流入量 > 缩短承诺时限 > 增加分诊人员
• 所需投入：缩短承诺时限（重写一行内容，只需解释一次） > 减少流入量（需要半天配置表单和选项） > 增加分诊人员（招募、授予权限、校准——新分诊人员至少需要一个季度才能产生净收益）
• 价值：减少流入量（永久降低算式左侧的数值） > 增加分诊人员（唯一能提高处理能力的方法） > 缩短承诺时限（没有任何改善；只是避免承诺无法兑现）
• 合规成本：减少流入量 == 增加分诊人员（两者都是内部决策，没有外部相对方，因此并列） > 如果问题 6 发现存在合同义务，则缩短承诺时限；因为此时已发布的目标属于承诺，缩短时限就意味着修改合同

效率会阻碍增加分诊人员——这是唯一能提高处理能力的方法，也是见效最慢的方法。只要项目预计一年后仍会存在，就应推动增加分诊人员：只会减少流入量的项目，最终会把自己缩小到能应付最糟糕月份的规模。在交付内容中注明所选方法，避免用户三个月后感到意外。

趁着还没有火烧眉毛，现在就决定流量控制触发条件：当流入速率或有效报告占比达到什么程度时，项目会限制哪些人可以提交条目、限制每位作者可提交的未结条目数量，或改变吸引大量提交的激励措施。采用流量控制的项目往往要等到倦怠问题严重后才会采取行动；在设计阶段决定触发条件，能让它成为政策，而不是危机中的临时应对。./references/worked-examples.md 用这一算式分析了 curl 的有效报告占比跌至二十分之一的过程，并说明为何其应对措施针对的是提交行为的经济因素，而非分诊速度。

根据处理能力数据设定首次响应目标，而不是凭主观期望设定——目标是人工回复，不是修复，也不是机器人问候。有关算式、志愿者与企业支持项目的差异，以及合同义务，请参阅：./references/policy-and-metrics.md。

步骤 3 - 设计标签分类体系

将标签划分为相互独立的维度：类型、状态、优先级、领域、面向贡献者；每个条目在每个维度上最多使用一个值。状态决定队列流转；优先级会引发争论，因此应尽可能精简。

根据 ./references/published-findings.md 中的参考点确定标签集的规模：

• 新建仓库的十个默认标签
• 安装量最高的分类技能中的五种状态角色和两个类别
• Kubernetes 规模下的六个带前缀标签系列

将这些参考点映射到某个项目上，是本技能的判断，而非有来源支持的规则：合理的答案通常介于前两者之间，只有在所有权确实分散时才接近第三种情况。

PyTorch 的标签分类体系提供了两条规则——这是唯一有记录且在生产环境中运行的分类体系，运行于 PyTorch 自己的主仓库：

• 只有在有把握时才打标签。 有较高或中等把握时应用标签；把握较低时，应改用“需要审核”状态，而不是猜测。猜测领域标签会把条目分配给错误的负责人，代价高于不打标签。
• 绝不让自动化应用最高优先级。 将所有候选项交由人工确认。优先级是后续影响最大、定义最难通过机器检查的维度。

维度、规模合适的初始标签集、命名规则、清理现有混乱标签但不抹去历史记录的方法、允许列表和验证模式，以及跟踪器机制：请参阅 ./references/label-taxonomy.md。

在操作跟踪器前先提交分类体系供审批——强加给不同意的维护者的分类体系，一个月内就会失效。

步骤 4 - 精简问题入口

把容量花在本不该进入流程的事项上，是最值得回收的一块。按每小时设置成本可回收的分流分钟数，对四项措施排序——无需考虑合规成本，因为这四项都不会对任何人产生义务：

• 效率：选择器路由 > 已验证表单 > 禁用空白问题 > 自动应用类型标签
• 工作量：禁用空白问题 == 自动应用类型标签（一项设置、一行表单 YAML）> 选择器路由（需要一个可能尚不存在的目标）> 已验证表单（每个真实类别都要有一份表单，还要编写、测试并修改，因为报告者会跳过字段）
• 价值：选择器路由（移除整个类别，而不是加快处理速度）> 已验证表单（让每份错误报告都从两轮往返变成一次提交，永久生效）> 禁用空白问题（关闭让表单成为可选项的绕过通道）> 自动应用类型标签（一个维度，几秒钟就能为事项添加标签）

1. 选择器路由 - 将使用问题引导至论坛或聊天，将商业请求引导至销售联系人。停止条件：经路由处理的报告永远不会进入跟踪系统，因此步骤 5-8 不会触及它。
2. 用已验证表单替换 Markdown 模板。只要求填写会影响结果的字段；报告者每跳过一个可选字段，就会认为这份表单只是装饰。
3. 在表单覆盖所有真实类别后，禁用空白问题。
4. 根据表单自动应用类型标签，并在跟踪系统支持问题类型的情况下设置问题类型。

效率指标会让第 2 项得不到重视：它的持续价值最高，设置工作量也最大，因此只有一个空闲晚上的维护者会改做切换设置，而多轮往返仍会继续。若错误报告占流入事项的大多数，应将其优先级提高到第一，因为每个事项都会付出这项成本。如果项目没有可以接收使用问题的渠道（问题 12），就没有第 1 项——本轮应将其删除，而不是列为待办工作。

安全报告应完全离开跟踪系统。 对每个经过审查的成熟项目而言，都采用相同的三要素流程，并与一般分流分开：

• 私密入口渠道
• 明确指定、人数上限固定的响应团队
• 用于协调披露的延迟公开机制

Apache 指示提交者，绝不要在公共跟踪系统中输入漏洞详情。如果没有安全邮件列表，代码托管平台的私密漏洞报告功能就是默认选择。流程本身的运行——SECURITY.md、延迟公开、安全公告、CVE、已修补版本——属于 samber/developer-relations-skills@oss-security-disclosure。

表单功能、选择器配置、完整的安全处理流程和按量设置门槛的选项：./references/issue-intake-and-routing.md——编写表单 YAML 前请先阅读。

第 5 步 - 指定值班人员

无人负责的流程就不算流程。

1. 明确由谁进行分流，采用轮值制，注明轮值时长（通常以周为单位），并指定一名备份人员。Mozilla 的双层模式是有文档记录的最稳健做法：由长期的分流负责人按组件承担责任，另设每周轮换的分流值班人员负责实际工作。
2. 确定频率和停止规则：到达规定时长就结束，不必清空收件箱，这样分流工作才能应对突发高峰。
3. 设定处理顺序：先处理最新的未分流条目（确保响应目标），再处理报告者已回复的条目，最后处理固定数量的积压条目。
4. 授予分流级别的权限，而不是提交权限——大多数跟踪系统都提供一种角色，可在没有写入权限的情况下添加标签、关闭条目和分配任务，这样分流团队才能扩展到提交者之外。
5. 明确升级机制：分流人员可以独自决定什么事项，哪些事项需要等待维护者，以及最长等待时间。

定期分流会议能否持续，取决于三件事：

• 为会议专门构建的队列视图
• 异步预分流，让会议用于决策，而不是首次接触
• 通过更改标签或状态记录决策，而不是只记在会议纪要里

Rust 的编译器分流会议是最清晰的例子：Zulip 频道负责预分流，并通过替换标签来设定优先级，因此会议产出仍可查询。

第 6 步 - 为拉取请求设置独立的关卡顺序

拉取请求需要通过问题条目所没有的硬性自动检查；不要复用问题处理流程。

以下两个关卡不属于可选项，因为它们都是自动执行的前置条件，会在人类查看之前触发：

• 签署确认（CLA 或 DCO）
• 外部作者提交的 PR 所需的 CI 权限

没有签署确认就不能合并，因为它记录的许可证来源是项目了解代码出处的唯一依据。

按照每分钟审阅者时间能够处理的拒绝数量，对消耗维护者精力的三个关卡排序，而不是按成本从低到高排序，否则方向判断问题会被各种机制掩盖：

• 效率：方向检查（“这是否属于本项目”）> 基于规模的风险标签 > 代码正确性审查
• 工作量：方向检查（花一分钟查看标题、描述和关联问题）> 基于规模的风险标签（根据差异计算，但只负责排序）> 代码正确性审查（这是成本最高的环节，设置此顺序就是为了保护它）
• 价值：代码正确性审查（唯一能够接受变更的关卡）> 方向检查（处理那些拒绝理由与代码无关的情况）> 基于规模的风险标签（负责分流；不作决定）
• 合规成本：方向检查 == 规模标签（两者持平：维护者阅读描述，机器人测量差异，都不会让项目承担任何责任）> 代码正确性审查（接受变更会让项目对其来源和安全状况承担责任，而签署确认记录的正是这一点）

方向检查排在最前，因为 MSR 2026 挖掘研究对 353 个经过人工检查的拒绝案例进行分析后发现，大约三分之二被拒绝的 Agent 式 PR 根本不需要阅读代码。具体分析见 ./references/published-findings.md。

按效率排序会让代码正确性审查得不到足够关注：它价值最高、工作量最大，却永远排在最后。当可信的重复贡献者针对已接受的问题提交小型变更时，应将其提前到第一位——PR 提交前方向问题就已解决，此时按原顺序处理的成本反而高于直接审查代码。

每项决策的处理路径、包含弱与强版本的回复模板、PR 差异以及拒绝知识库，见 ./references/response-playbook.md。

步骤 7 - 编写关闭规则和过期策略

明确决定哪些条目会自动关闭，哪些永远不会。站得住脚的原则是：只自动关闭那些等待报告者回复、但对方已不再回应的条目；绝不自动关闭那些等待维护者处理的条目——已确认的缺陷被机器人关闭，会让报告者觉得自己的证据毫无价值。

配置清理任务：

• 仅将其限制在等待报告者状态
• 将已确认和受阻状态排除在外
• 关闭前发出警告
• 首次运行时使用演练模式，以便在正式执行前了解影响范围

每次关闭都要说明原因，并告知如何重新打开。

将每个计时周期都关联到明确的等待对象，而不是抽象地关联到条目。Kubernetes 已发布的计时周期、清理任务配置，以及何时可以合理地对一次性积压进行破产式清理，请参阅：./references/policy-and-metrics.md。

步骤 8 - 自动化分类，绝不自动发送首条回复

先以确定性方式自动化机械性工作：

• 根据变更路径填充领域标签
• 根据表单应用类型
• 请求所属团队进行审查
• 运行过期计时

每个有记录的机器学习分诊部署都会让人类担任最终决策者：将模型辅助视为评分和建议层，而不是自主接受、拒绝或关闭条目的机制。

考虑使用分类器之前，先借鉴以下两种模式：

• 自动化安排谁值班，而不是决定如何处理。 Mozilla 会将分诊负责人字段同步为轮值日历上的值班人员，这样请求就会送到实际在处理的人手中，而不是堆积在同一个人名下。
• 将标签集合保存为经过验证的产物，确保自动化无法创建新标签或覆盖人工工作——具体实现见 label-taxonomy.md。

第一句人工回复应由真人撰写。根据定义，回复指标不计入机器人回复，报告者也会同样打折看待机器人回复；自动问候后又沉默三周，只会让等待更煎熬。当 Agent 发布分诊评论时，应在评论中披露这一点。

步骤 9 - 发布、试运行一轮并衡量

发布策略：

• 将其写入仓库，放在贡献指南旁边
• 在受理表单中添加指向该策略的链接
• 仅在项目自己的频道中发布一次变更公告

与用户一起使用新系统，针对 15-20 个条目进行一次真实分诊，并记录耗时。这会得出步骤 2 暂缓计算的每条目分钟数，并暴露设计中的问题——缺少状态、标签含义模糊，或回复模板不适用。未实际执行过一次的策略只是草案。

第一季度每月重新运行 triage-baseline.py，并根据三个初始目标进行迭代。这三个目标都是本技能自行设定的基线，并非行业基准——积累一个季度的数据后，应分别用项目自身测得的趋势替换它们：

• 未分诊条目占开放条目的比例低于 10%。
• 至少 90% 的条目达到已公布的首次回复目标。
• 整个季度的净流入不高于零。

持续迭代，直到这些目标实现；否则，就将已公布的承诺下调到能够兑现的水平。

切勿单独解读计数指标。CHAOSS 的指南将这些指标限定为“主要由人类驱动”的活动；在机器生成的数量增加时，关闭率和关闭耗时可能看似改善，实际维护者负担却在上升。每个计数指标都要配合一项由人类驱动的信号：排除机器人和作者自行回复后的首次响应情况，以及如果一人离开，有多少人能够接手分诊。

如果有可用的持久化记忆，请存储以下长期决策：

• 容量数字
• 商定的回复目标
• 标签维度及其定义
• 转到跟踪器之外处理的类别
• 流量门控触发条件
• 声明为范围之外的请求

下一次审查将以这些内容的差异为依据。

调用示例

用户说	你产出
“我们有 900 个未解决的问题，不知道从哪里着手”	运行基线分析，用通俗语言解读结果，然后判断应逐项处理还是聚类处理——暂不制定分类体系
“为我们的维护者团队设计一个分类处理流程”	按顺序提供全部五项交付成果，并逐项验证
“我们的标签一团糟，重新整理一下”	先统计标签使用次数，然后列出创建、重命名、合并和删除项；每个标签都要有一个定义和一个分类维度
“我们该启用过期机器人吗？”	只适用于等待报告者回复的规则、首次试运行，以及豁免状态列表——并拒绝批量处理由维护者负责的项目
“外部贡献者提交的 PR 都没人回复”	采用步骤 6 中的关卡顺序，并单独设定 PR 回复目标——不能照搬问题处理流程
“AI 生成的报告多得让我们应接不暇”	先说明步骤 2 中的数量门槛触发条件、受理成本和平台控制措施，再考虑任何分类器

交付成果

按顺序产出以下五项成果，每项都要先与用户确认，再进行下一项——绝不能在一次无人确认的流程中全部完成：

1. 基线 - 步骤 1 的数据、对数据的一句话解读，以及逐项处理还是聚类处理的判断。
2. 分类处理政策 - 已发布的文档：哪些内容应纳入跟踪系统、回复目标、各状态及其含义、何时关闭项目、由谁分类处理，以及数量门槛触发条件。模板见 ./references/policy-and-metrics.md。
3. 标签变更清单 - 创建、重命名、合并、删除；每项都附上一句话定义及其分类维度。
4. 受理变更清单 - 需要新增或重写的表单及必填字段、选择器中的路由选项、安全处理路径、要启用的自动化；每项都注明预计节省的分类处理分钟数。
5. 值班与关卡设计 - 轮值安排，包括具体人员和轮值时长、升级规则，以及拉取请求的关卡顺序。

每项成果都要使用项目自身的术语——实际的标签字符串、实际的频道和维护者姓名。

失败模式

每一行都指出步骤中尚未说明的一种失败；修复方案就是该行的全部内容。

失败	修复
不切实际的目标——只有两名志愿者，却承诺“24 小时内回复”	发布基线数据能够支持的数字
轮值安排形同虚设——轮值表写好了，但一年都没人执行	指定负责人并检查其是否实际运转；如果轮值中断，就正式宣布废止
优先级作秀——所有项目都标为 priority/high	设定两到三个级别，并按影响后果定义
一次性大迁移——启用新标签，却保留旧表单和旧的已保存视图	一次性迁移标签、表单、视图和自动化
把分类处理当成修复——花一场会议调试单个项目	为处理过程设定时限；分类处理负责安排工作，不负责执行工作
未衡量的重新设计——流程改了，却不知道是否有帮助	每月重新运行基线分析

参考资料

• ./references/label-taxonomy.md - 维度、入门集合、清理流程、跟踪器机制。
• ./references/issue-intake-and-routing.md - 表单字段、选择器、跟踪器外分流、安全处理路径。
• ./references/response-playbook.md - 单项决策流程、回复模板、拒绝知识库。
• ./references/policy-and-metrics.md - 容量计算、政策模板、关闭规则、衡量计划。
• ./references/worked-examples.md - 容量评估示例，以及一组正向／负向轮换示例。
• ./references/published-findings.md - 哪些数据有来源，哪些是自行设定的基线。