A2UI Issue Triage Criteria 实战指南：分类、优先级与自动化值守流程

A2UI Issue Triage Criteria 实战指南：分类、优先级与自动化值守流程

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui

本篇技术指南以 A2UI 仓库中 a2ui-issue-triage 技能的分类判定文档 为核心骨架，系统讲解 A2UI 项目在 GitHub 上对 Issue 进行分类、设定优先级、推荐负责人与起草回复的完整值守流程。读完本文，你将掌握 P0–P4 优先级体系的语义、四类 status 标签的使用规则、Bug/功能/咨询三类 Issue 的标准处理动作，以及从fetch_issues.py到apply_triage.py的自动化分诊工具链的底层实现。

一、文档定位：三份"权威事实源"（Canonical Sources of Truth）

triage_criteria.md本身是一份"执行规则手册"，它规定了一线值守工程师（oncall engineer）和分诊 Agent 在操作 Issue 时必须遵守的分类、优先级、负责人与回复规范。为了避免规则漂移，它没有把全部细节重复内联，而是明确指向仓库内三份权威文档：

写作回复时，要求逐字复制标准模板文本，保证对外口径一致；所有被分诊的 Issue 都必须打上status: first-line-handled标签，作为"已被一线处理过"的标记。

二、优先级体系：P0–P4 的语义与维护不变式

triage_criteria.md直接引用 triage.md 中的优先级定义。A2UI 的优先级与其他 Dash 团队保持一致，核心目标是持续保证：外部 PR 得到处理、Issue 得到优先级排序并被跟进、分支数量可观测。

各优先级的精确含义如下：

• P0：非常紧急（very urgent），必须立即指派负责人；
• P1：正在积极处理中（actively being worked on），应当指派负责人；
• P2：预计在常规规划流程中于三个月内升级为 P1；
• P3：暂未列入计划，但未来可能成为优先事项；
• P4：团队不计划投入（we do not plan to invest），Issue 保持打开状态留作记录。

配套的 PR 评审不变式是：只要满足以下任一条件，团队就会评审外部贡献者的 PR——PR 对应一个 P0–P3 的 Issue（P4 的 PR 不会被评审）、Issue 已由 A2UI 团队指派（作为 assignee 或在 Issue 描述首行标明）或带type: contributions-welcome标签、或者变更在团队看来绝对清晰且显然必要。PR 描述中应当链接其对应的 Issue。

三、分诊使用的 GitHub 标签全集

仓库中与分诊相关的标签分为优先级标签、状态标签和类型/规模标签三类：

• 优先级：P0、P1、P2、P3、P4
• 状态：status: needs-team-input（需要团队输入）、status: needs-triage（待分诊）、status: first-line-handled（一线已处理）、status: waiting-for-author-response（等待作者回复）
• 其他：size: small、type: contributions-welcome

其中两个标签是自动化的：status: needs-triage完全由机器人管理；status: waiting-for-author-response由人工添加，一旦作者回复会被自动清除。

自动化分诊机器人如何工作

triage.mjs 脚本通过 GitHub Actions 工作流运行，负责在所有打开的条目上对账status: needs-triage标签，规则如下：

1. 跳过的条目：带status: waiting-for-author-response的条目（作者发帖/评论/评审后自动移除该标签）；已指派的 Issue（假定团队成员在跟进）。
2. Issue 被标记needs-triage的条件：缺少优先级标签；P0/P1 高优先级但没有 assignee；超过优先级对应的"过期阈值"（P0 超过 1 天、P1 超过 30 天、P2 超过 90 天，P3/P4 永不因过期被标记）；最新的人类评论来自外部贡献者。
3. PR 被标记的条件：由外部贡献者打开，且没有维护者回应作者的最新贡献（维护者自己的 PR 不标记）。
4. 透明度：自动化脚本会在控制台打印哪些条目被标记/取消标记及原因，便于跟踪分诊进度。

过期时间基于"最后一次人类贡献"（评论、评审或创建）而非updated_at计算，避免机器人编辑重置计时器。工作流按日计划（UTC 15:00 / PST 07:00）、手动触发，以及 Issue 事件（打开、编辑、打标签、取消标签、指派、取消指派、重新打开）、新评论、PR 评审提交时自动运行。

四、Issue 分类与操作动作流

triage_criteria.md将 Issue 分为三大类，每一类都有明确的"分析（Analysis）→ 动作（Action）"流程。

4.1 Bug 报告

分析阶段：

• 复现（Reproduction）：除非复现步骤简单清晰且环境可以立即搭好，否则不要尝试本地复现。如果需要检出分支或克隆 PR 仓库来复现，必须在临时克隆或 git worktree 中进行（例如<appDataDir>/brain/<conversation-id>/scratch/issue_12345_repro/），完成后清理所有临时文件、worktree 和克隆。
• 静态分析（Static Analysis）：对于复杂 Bug，分析日志、堆栈跟踪以及相关规范文件（如specification/下的 JSON Schema）来诊断问题。

动作阶段：

• 若缺少复现步骤或日志：动作设为needs_info，打上status: waiting-for-author-response标签，并使用 triage-templates.md 中的"请求信息（Requesting Information）"模板回复；
• 若已验证：建议合适的优先级（P0–P3），并根据路径映射和文件提交历史推荐受影响组件的负责人。

路径映射规则为：renderers/lit路径下的问题归属 Lit renderer 维护者，specification/归属规范维护者等。负责人推荐可以通过文件提交历史来辅助判定，例如运行：

git log -n 5 --format="%ae" <file>

4.2 功能请求

分析阶段：核对该请求是否与 A2UI 路线图 以及受影响组件的设计哲学一致。

动作阶段：

• 与路线图一致：动作设为backlog，优先级P2或P3，并建议组件/类型标签（如component: standard catalog specification、type: feature/enhancement）；
• 超出范围：优先级设为P4，动作仍为backlog（保持 Issue 打开），回复使用 Out of Scope / Roadmap Conflict 模板。

4.3 支持请求与咨询

分析阶段：判断 Issue 本质是使用或安装问题而非 Bug。

动作阶段：动作设为close_resolved或close_invalid；直接回答问题或提供相关指南链接（如 quickstart.md）或 GitHub Discussions，然后关闭 Issue。

五、回复准则（Response Guidelines）

起草回复时，triage_criteria.md给出了三条硬性要求：

1. 直接（Be direct）：直接说明正在采取的动作或当下需要什么；
2. 去芜存菁（Eliminate fluff）：不要使用客套话（例如 "I hope this helps"）；
3. 参照模板（Refer to templates）：草稿评论必须与权威模板保持同步，逐字复制 triage-templates.md 中的标准文本。

值得注意的是，apply_triage.py 在实现层面对"同步模板"做了双重保障：发布评论前强制为回复加上A2UI Triage:前缀，并且会在发布前检查该评论是否已存在，避免重复发布。

六、标准回复模板的完整用例

triage-templates.md 提供了覆盖常见场景的标准回复，triage_criteria.md的分类规则正是围绕这些模板设计的：

Issue 类：

• Weekly A2UI Compliance Report（AI 生成的合规报告类 Issue）：优先级 P3，动作backlog（保持打开），回复说明"已按约定分配 P3 优先级，需要更好的工作流以便跟进发现的问题"；
• 已指派但无优先级的 Issue：优先级 P2，动作assign_and_fix（保留现有 assignee），回复说明"分配 P2 以移出分诊队列，如需调整请修改优先级"；
• 过期的 P2 Issue：仅添加评论，提示"在下一个规划周期应与其它 P2 一起考虑升级为 P1"；
• 过期且已指派的 P1 Issue：仅添加评论，用分诊流程的 ping 询问"此 Issue 是否仍在你的雷达上？"；
• 超范围 / 路线图冲突：优先级 P4，动作backlog，完整回复强调"超出 A2UI 协议路线图当前范围，标记为 P4：我们不计划投入，针对它的 PR 不会被评审；保持打开作为请求记录"。

PR 类（由维护者手工处理，dashboard 与 apply 脚本仅覆盖 Issue）：

• 被取代的 PR：关闭旧 PR 并链接新 PR，说明"创建了基于你分析和变更的取代 PR，你的原始提交已包含其中"；
• 没有关联 Issue 的复杂 PR：关闭，说明"团队资源有限，评审政策优先处理对应已优先级化 Issue 的 PR"；
• 超出项目范围的 PR：关闭，鼓励寻找更合适的仓库或自建仓库；
• 复杂但未指派给作者的 PR：关闭并链接到对应 Issue，说明"我们只评审指派给该贡献者的 PR"；
• 有冲突的有意义过期 PR：打status: waiting-for-user-response，请作者解决冲突后重新评审；
• 关闭已关闭 Issue 的 PR：直接关闭，说明"关联 Issue 已解决"。

七、从判定文档到自动化工具链：a2ui-issue-triage 技能

triage_criteria.md是 a2ui-issue-triage 技能 的核心引用文档。该技能把上述判定规则落地为四步工作流，全部围绕一个约定俗成的 scratch 目录存放中间产物（<appDataDir>/brain/<conversation-id>/scratch/）。

Step 1：拉取未分诊 Issue。运行 fetch_issues.py 拉取仓库中所有缺少优先级标签的打开 Issue 及其评论：

python3 .agents/skills/a2ui-issue-triage/scripts/fetch_issues.py \ --repo "a2ui-project/a2ui" \ --output-file "<appDataDir>/brain/<conversation-id>/scratch/raw_issues.json"

该脚本依赖 GitHub CLI（gh），依次执行：拉取 assignee 列表并借助git log --format="%an <%ae>"建立"登录名 → 真实姓名"映射（包含子串匹配兜底）；拉取仓库标签（前 150 个）；列出打开 Issue 并过滤掉已带优先级标签或waiting-for-author-response/needs-team-input/first-line-handled状态的条目；再为每个 Issue 拉取评论，最终输出包含repo、assignees、labels、issues、total_issues_count的 JSON 载荷。

Step 2：分析与建议分诊。读取判定文档和标准模板后，为每个 Issue 评估五个字段：

若判定为潜在重复，最多做三次针对性 GitHub 搜索来寻找权威重复 Issue，再建议close_duplicate。

技能还提供了启发式辅助脚本 suggest_triage.py，其guess_triage_heuristics函数体现了判定文档的工程化落地：内置COMPONENT_DIRS路径映射（component: lit renderer→renderers/lit、component: angular renderer→renderers/angular、component: react renderer→renderers/react、component: standard catalog specification/component: specification→specification、component: samples→samples、component: agent library→agent_sdks）；对标题与正文做关键词匹配——lit/angular/react/spec/schema/sdk等推断组件标签，typo/docs/feature/enhancement/error/crash/bug等推断类型标签；Bug 报告若缺少reproduce/steps等关键词则自动建议needs_info动作与status: waiting-for-author-response标签；已指派 Issue 且非合规报告、非needs_info、非 P0/P1 时，遵循模板规则提升为 P2 +assign_and_fix。get_suggested_assignees则对每个组件目录运行git log -n 30 --format="%an <%ae>"，统计排除dependabot/github-actions后的提交者频率，再与合法 assignee 列表做精确或前缀匹配排序。

实际执行时，技能推荐由父 Agent原生编排并行子 Agent（而非用 Python 脚本派生子进程，避免本机 gRPC 凭据策略导致失败）：加载前 N 个（默认 10）Issue，并行调用invoke_subagent让每个子 Agent 依据判定文档返回结构化 JSON，再汇总为issues_to_triage.json。

Step 3：启动审查 Dashboard。运行 launch_dashboard.py，启动本地 HTTP 服务器并自动打开浏览器：

python3 .agents/skills/a2ui-issue-triage/scripts/launch_dashboard.py \ --data-file "<appDataDir>/brain/<conversation-id>/scratch/issues_to_triage.json" \ --output-file "<appDataDir>/brain/<conversation-id>/scratch/triage_decisions.json"

从源码实现看，该服务器绑定随机本地端口（127.0.0.1:0），提供GET /（返回 triage_dashboard.html 界面）、GET /api/comments（读取建议数据）、POST /api/save（把人工审查后的决策写入triage_decisions.json并置退出码 0）、POST /api/abort（置退出码 1）；/api/save与/api/abort都会触发 shutdown 事件结束进程。Dashboard 使用 marked.js 渲染 Markdown、DOMPurify 做 XSS 净化，界面按优先级着色（P0 红、P1 橙、P2 黄、P3 绿、P4 灰）。若用户点击"Abort"（非零退出码），Agent 必须停止并询问用户，不得修改任何 Issue。

Step 4：批量应用到 GitHub。Dashboard 审查通过（退出码 0）后，运行 apply_triage.py：

python3 .agents/skills/a2ui-issue-triage/scripts/apply_triage.py \ --decisions-file "<appDataDir>/brain/<conversation-id>/scratch/triage_decisions.json"

该脚本仅处理approved: true的决策，按 Issue 依次：读取当前标签、移除冲突的旧优先级标签并添加新优先级标签、强制确保status: first-line-handled存在、按needs_info动作管理status: waiting-for-author-response、添加组件/类型标签、指派 assignee、发布带A2UI Triage:前缀且去重的评论，最后按动作执行关闭（close_duplicate→duplicate、close_invalid→not planned、close_resolved→completed）。

八、人工值守的两层职责

配合自动化，triage.md还定义了两个人工程序：

一线分诊（First line triage，每日）：对每个尚未first-line-handled的 Issue——若为 P0 则加P0标签并通知团队聊天群，然后统一打上status: first-line-handled标签。

二线分诊（Second line triage，每周）：处理needs-triage队列，至少完成以下一项：设定优先级（P0/P1 必须指派到人）、回答外部评论、需要更多信息时添加status: waiting-for-author-response。可以手动移除needs-triage标签加速流程，但只要条目仍匹配规则，机器人会重新打上。需要团队输入时按四步流程：加status: needs-team-input标签 → 在团队聊天发布消息并征求输入 → 推动讨论收敛 → 移除该标签。周度分诊结束后，needs-triage列表理想状态下应为空。

九、FAQ 中的设计决策

triage.md的 FAQ 解释了两个容易被误解的设计：

• 为什么允许分支存在？因为来自 fork 的 PR 无法在提交前运行 eval 与 e2e 测试（需要仅原仓库可见的 API key）。禁止分支不会减少工作量（只会转移到 fork），且清理分支所有权清晰，团队成员也更谨慎管理分支。
• 为什么需要 P4 而不是直接关闭？关闭无法留下可检索的关闭原因；外部开发者可以重新打开 Issue 却无法修改标签。保持 P4 打开是"未实现、看似有价值、被认定为 P4"的明确信号，既增加透明度，也让推动优先级提升变得更难。

十、总结

A2UI 的 Issue 分诊体系由三层构成：判定文档（triage_criteria.md）定义分类与动作规则，权威文档（triage.md 与 triage-templates.md）定义优先级语义与标准回复，自动化工具链（fetch → suggest → dashboard → apply 四个脚本）把规则工程化。理解这三层，你既能作为值守工程师手动处理 Issue，也能驱动 Agent 以并行子任务方式批量分诊，并在人机协作中保持回复口径一致、队列状态可追踪。

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui