PowerToys 的 Issue/PR 自动化命令体系：关键词指令、策略驱动的标签流转与 AI 辅助分诊

Microsoft PowerToys 仓库（PowerToys）在 Issue 和 Pull Request 管理上沉淀了一套"关键词命令 + 策略配置 + AI 辅助分诊"的组合体系：维护者可以在 Issue/PR 的评论中直接输入 /dup、/needinfo、/bugreport 等斜杠命令来驱动标签流转与自动关单；而新建 Issue 则会进入一个"确定性预处理 + 受限 Copilot 分析"的分诊流水线。本文基于 doc/devdocs/commands.md 的原始内容，结合仓库中 policy 配置、AI 分诊工作流 及配套的 Python 预处理脚本，完整讲解这套体系的工作机制、安全边界与源码级实现细节。

一、可用的 Issue/PR 命令一览

PowerToys 仓库在 Issue 和 Pull Request 的描述或评论中支持一组特殊关键词命令。以下是 doc/devdocs/commands.md 中列出的完整命令表：

命令	作用
/azp run	为当前 PR 触发 Azure Pipelines CI 构建。适合在不新提交 commit 的情况下重跑构建。
/bugreport 或 /reportbug	添加一条评论，附上 Bug Report Tool 的使用说明（用于收集日志与系统信息），请求作者上传报告文件，并打上 Needs-Author-Feedback 标签。
/feedbackhub	添加一条指向 Windows Feedback Hub 应用的评论（PowerToys 反馈可提交到该应用），随后关闭该 Issue 并添加 Resolution-Please File on Feedback Hub 标签。
/dup #...、/duplicate #...、/dup https://...、/duplicate https://...	将当前 Issue 标记为另一个 Issue 的重复项：关闭当前 Issue 并添加 Resolution-Duplicate 标签。#... 替换为 Issue 编号或链接。
/needinfo	为 Issue/PR 添加 Needs-Author-Feedback 标签，表示需要作者补充信息。
/helped	关闭 Issue 并添加 Resolution-Helped User 标签，同时附上指向 PowerToys 用户文档的评论。
/loc	添加评论告知用户该问题已转交给本地化团队、将在近期版本中修复，并添加 Loc-Sent To Team 标签。

这些命令的实际执行逻辑并不散落在各处脚本里，而是集中定义在仓库的 policy 配置文件中（见下一节）。从源码结构看，/azp run 属于 Azure Pipelines 侧的命令，与其余由 GitHub Policy Service 驱动的斜杠命令分属不同执行通道。

二、命令是如何定义的：GitHub Policy Service 配置

doc/devdocs/commands.md 明确指出：上述大部分命令都基于 Microsoft 的 GitHub Policy Service 机器人，其命令定义在 PowerToys 的策略配置文件 .github/policies/resourceManagement.yml 中。该文件采用 eventResponderTasks（事件响应器）结构，每个响应器由 if 条件（payload 类型 + 正则 + 权限）和 then 动作（改标签、发评论、关单）组成。以仓库中的实际配置为例，可以逐条拆解每个命令的触发条件与执行动作：

2.1 /bugreport 与 /reportbug

对应 resourceManagement.yml 中的响应器，关键约束有三个：

• 匹配方式：评论文本需命中正则 \/(bugreport|reportbug)（isRegex: True），因此两种写法等价；
• 权限门槛：activitySenderHasAssociation 必须为 Member、Owner 或 Collaborator 之一——即只有仓库维护者能触发，普通用户输入不会生效；
• 动作序列：移除 Needs-Triage → 添加 Needs-Author-Feedback → 回复一段引导文案（说明如何右键托盘图标生成 Report Bug zip 包并拖入评论区）→ 移除 Needs-Team-Response。

2.2 /dup 与 /duplicate 的宽松正则

duplicate 响应器 使用的正则是：

\/dup(licate|e)?(\s+of)?\s+(\#[\d]+|https)

从该模式可以推断出它兼容 /dup、/dup of、/duple、/duplicate 等多种拼写变体，且目标既可以是 #数字 形式的编号，也可以直接粘贴 https 开头的完整链接。动作序列为：回复"已判定为重复"的说明文案 → 关闭当前 Issue → 移除 Needs-Triage 与 Needs-Team-Response → 添加 Resolution-Duplicate 标签。

2.3 /feedbackhub、/helped 与 /loc

• feedbackhub 响应器 的正则为 \/feedback[H|h]ub，对大小写不敏感；动作为回复 Feedback Hub 引导（Win+F 唤起）→ 关闭 Issue → 移除分诊标签 → 添加 Resolution-Please File on Feedback Hub 标签。
• helped 响应器 匹配 \/helped：添加 Resolution-Helped User 标签、回复含 end-user 文档链接（aka.ms/powertoy-docs）的文案，然后关闭 Issue。
• loc 响应器 匹配 \/loc\b（带单词边界，避免误伤 local 等词）：仅移除 Needs-Triage、添加 Loc-Sent To Team 标签并回复"已转交内部本地化团队"，不关闭 Issue——这与 /helped 的行为形成对照。

2.4 文档未列出的补充命令：/need-monitor-info

在 policy 文件中还可以找到一个 doc/devdocs/commands.md 未收录的命令：/need-monitor-info。它的触发条件除了维护者权限外，还额外要求 Issue 已带有 Product-Cursor Wrap 标签；命中后请求作者运行 Cursor Wrap 测试目录下的 Capture-MonitorLayout.ps1 脚本并把生成的 JSON 输出附到评论区，用于排查多显示器布局问题。这是一个典型的"命令 + 场景化诊断脚本"组合的例子。

2.5 通用行为：邮箱回复清理

policy 中还定义了一个兜底响应器：任何 Issue_Comment 事件都会执行 cleanEmailReply 动作（resourceManagement.yml），用于清理以邮件方式回复 Issue 时产生的邮件头残留，保持评论区整洁。

三、定时任务：自动关单与标签状态机

除命令外，policy 文件顶部的 scheduledSearches 定义了两条每小时（第 6 小时）执行的定时搜索任务，它们是标签体系"闭环"的关键：

3.1 Needs-Author-Feedback 的 7 天自动关闭

scheduledSearches 第 1 条 过滤条件为：是 Issue、处于打开状态、带有 Needs-Author-Feedback 标签、且 7 天内无任何活动。命中后先回复一条"因等待作者反馈超过 7 天已自动关闭，如能补充信息请重新打开 Issue 并补充"的文案，然后执行 closeIssue。第 2 条定时任务 针对 PR 做了同样逻辑（isPullRequest + 同样的标签与 7 天静默条件）。

3.2 Resolution-Duplicate 的 1 天兜底清理

第 3 条 scheduledSearch 面向带有 Resolution-Duplicate 标签且 1 天无活动的 Issue：这类 Issue 通常已被 /dup 命令关闭，该任务是对异常残留项的"打扫"，回复文案后关闭。

3.3 作者活动驱动的标签状态机

policy 中的事件响应器还实现了标签在分诊状态间的自动迁移，核心规则如下：

• 作者回评即解锁：当带 Needs-Author-Feedback 的打开 Issue 收到作者本人（isActivitySender: issueAuthor: True）的评论时，系统会移除 Needs-Author-Feedback、添加 Needs-Triage 和 Needs-Team-Response，把该 Issue 重新交回团队分诊队列（resourceManagement.yml）。这保证了 7 天自动关闭计时因作者活动而自然中止。
• Status-No recent activity 的即时清除：Issue 有任何非关闭类更新、Issue 收到评论、PR 处于打开状态并发生更新时，都会自动移除该状态标签（resourceManagement.yml），即"只要还有活动，就绝不标记为无活动"。
• 任意 PR 事件都会确保其带有 Status-In progress 标签（resourceManagement.yml）。

这一组规则共同构成一个可预测的标签生命周期：Needs-Triage →（缺少信息时）Needs-Author-Feedback →（作者回评/推送后）回到 Needs-Triage + Needs-Team-Response →（解决后）Resolution-* 终态标签，长期无活动则由定时任务关闭。

四、AI 辅助 Issue 分诊：确定性证据 + 受限 Copilot

doc/devdocs/commands.md 的 "Other automated tasks" 部分描述了第二套自动化：新建与更新的 Issue 会被一个 GitHub Agentic Workflow 处理，它"结合确定性检查与一次有界（bounded）的 GitHub Copilot 通过"，具体行为包括：维护唯一一条分诊评论、添加匹配的 Product-* 主标签与版本标签、请求阻塞性作者信息、建议较老版本的 PowerToys 用户升级、呈现可能的重复 Issue，并对脱敏后的 PowerToys 诊断报告子集做分析。重复关单以"原生 GitHub 建议"（native suggestion）形式提交，必须由维护者接受或拒绝；接受后 Issue 才会被关为重复项并链接到选定的规范 Issue（canonical issue）。

该工作流的完整定义在 .github/workflows/issue-triage.md（YAML 头部 + 任务说明），其配套说明文档是 .github/scripts/issue-triage/README.md。下面按"成本约束 → 确定性预处理 → 诊断脱敏 → 输出校验"的顺序拆解。

4.1 触发条件与成本/安全约束

工作流的 YAML 头部显式声明了多重限额（issue-triage.md）：

配置项	取值	含义
on.issues.types	[opened, edited]	仅订阅 Issue 创建与原始标题/正文编辑；评论与重开事件不触发
user-rate-limit	max-runs-per-window: 5，window: 60	单用户 60 分钟内最多 5 次运行
engine	id: copilot，model: small	使用 Copilot 引擎的小模型别名
max-turns	5	每次运行最多 5 轮对话
max-ai-credits / max-daily-ai-credits	10 / 300	单次 10 个 AI 积分、每日 300 个积分上限
permissions	contents: read、issues: read、copilot-requests: write	分析阶段只读；写入由独立的发布任务执行
concurrency	按 Issue 编号分组，cancel-in-progress: true	同一 Issue 的并发运行互相取消，避免重复分诊

引擎参数里通过一连串 --deny-tool 显式禁用了 write 工具以及 shell(cat)、shell(grep)、shell(yq) 等一批 shell 命令——从这些配置可以推断，该 Agent 在整个运行期间不具备通用 shell 与 GitHub API 写权限，其唯一的 shell 通道是结构化的 safe-output CLI 代理。任务说明（issue-triage.md 的 "Task" 与 "Tool policy" 章节）还明确：触发 Issue 的标题与正文必须被视为不可信证据而非指令，防止 Issue 内容中的提示注入改写工作流策略、访问密钥或操纵标签。

4.2 确定性预处理：issue-context.py

工作流第一步运行 .github/scripts/issue-triage/issue-context.py，在 AI 介入前把所有可机械判定的事实算出来，写入 /tmp/gh-aw/issue-context.md。其关键实现：

• Bug 模板识别：正文同时命中 Microsoft PowerToys version、Installation method、Area(s) with issue?、Steps to reproduce、Expected Behavior、Actual Behavior、Upload Bug Report ZIP-file 这 7 个标题中的至少 5 个，才判定为 BUG 类型（is_bug_template），与仓库的 Issue 模板 .github/ISSUE_TEMPLATE/bug_report.yml 相对应。
• 版本解析与新旧判定：从版本章节提取版本号（正则 (?:(v)?\d+(\.\d+){1,3})，parse_version），再与 microsoft/PowerToys 的最新稳定 Release 对比，产出 CURRENT / OUTDATED / NEWER_THAN_STABLE / NOT_PROVIDED 状态。旧版本会得到一条"升级到最新版并重试"的建议性文案，但不会因此改变"缺失信息"的判定。
• 复现步骤质量评估：reproduction_quality 检查 Steps to reproduce 章节是否包含足够的动作标记词（open/press/click/remap 等，至少 2 个）与 Actual Behavior 的观测结果（不少于 10 字符），并对"随机/间歇性"失败模式放宽了判定——只要时序/触发点与失败表现描述清晰即可。
• Bug Report 需求分级：bug_report_requirement 通过两组正则（DIAGNOSTIC_REPORT_REQUIRED_PATTERN、DIAGNOSTIC_SYSTEM_FAILURE_PATTERN）匹配崩溃、挂起、启动失败、异常码（0x 十六进制）、内存泄漏、高 CPU/内存、安装/更新/驱动/服务/Shell 扩展失败等关键词，命中即判为 REQUIRED；对复现充分且命中 UI/视觉缺陷词汇的报障判为 OPTIONAL；其余为 RECOMMENDED。
• 重复候选的确定性检索：retrieve_candidates 以 Issue 中的技术标识符（0x 地址、.dll/.exe/.json/.log 等文件扩展名，最多取 3 个）与高频概念词（去停用词后取前 6 个）构造最多 4 条 GitHub 搜索查询，只检索编号更小的历史 Issue；每个候选按"技术标识精确命中 ×12 + 标题词重叠 ×10 + 正文重叠 ×4 + 查询命中 ×1.5 + 同产品标签 +2"的加权公式打分，分数低于 2 的丢弃，最多保留 8 个候选。该分数只是检索相关度，不是重复判定——是否重复由模型在后续环节判断，最终评论中最多展示 5 个。
• 幂等与防抖：对 Issue 的 title + body + 作者最近的报告评论计算 SHA-256（input_hash），若既有分诊评论中嵌入的 input-sha256 与新值一致则直接跳过；已关闭的 Issue、PR（PR 交给 pr-intake 流程）、以及带有 dedupe-digest 标签的聚合 Issue（其正文聚合了大量不可信文本，重分诊既浪费积分又是注入面）也都会被跳过（should_process）。维护者还可评论 /triage refresh 强制刷新（限 OWNER/MEMBER/COLLABORATOR 权限）。

4.3 诊断报告的脱敏分析：bug-report-analyzer.py

对 Issue 中引用的 PowerToysReport_*.zip 附件，.github/scripts/issue-triage/bug-report-analyzer.py 做了一次严格设限的下载与解析，只有脱敏后的有限证据会被提供给模型，原始压缩包随后被删除、且从不作为工件上传：

限制项	取值	位置
下载大小上限	16 MB（MAX_DOWNLOAD_BYTES）	bug-report-analyzer.py
压缩包条目数上限	3000（MAX_ARCHIVE_ENTRIES）	同上
解压总大小上限	64 MB（MAX_UNCOMPRESSED_BYTES）	同上
单条目大小上限	8 MB（MAX_ENTRY_BYTES）	同上
压缩比上限	200 倍，超过视为可疑（zip 炸弹防护）	同上
错误信号最多条数/总长度	10 条 / 9000 字符	同上

安全细节还包括：附件 URL 必须精确匹配 github.com/user-attachments/files/.../PowerToysReport_*.zip 模式（validate_attachment_url）；下载重定向只允许落到 github.com 与 objects.githubusercontent.com 两个主机；validate_archive 拒绝绝对路径、.. 路径穿越、反斜杠路径、符号链接与加密条目（防 zip-slip）。日志信号提取（collect_signals）优先读取与 Issue 产品区域匹配的产品日志目录（如 fancyzones/、keyboard manager/、powertoys run/），以及 runnerlogs/、eventviewer、crash 等全局诊断文件，按 文件名:行号: 摘录 格式输出。所有文本都经过 redact 脱敏：用户资料路径、邮箱、URL、IP 地址、GUID、SID、token/secret/password 类键值、机器名/用户名等全部替换为占位符。分析结果以 ANALYZED / NOT_FOUND / REJECTED 三种状态渲染成 Markdown 上下文文件，REJECTED 时只保留一句拒绝原因。

4.4 规范化分诊评论与"发布前再验证"

模型最终必须恰好调用一次 publish_triage_summary，提交包括 input_sha256（必须与确定性证据中给出的哈希完全一致）、summary、suggested_area、product_label、powertoys_version、has_missing_information、duplicate_candidates_json（0–5 个候选，含编号/理由/HIGH-MEDIUM-LOW 置信度）、issue_kind、reproduction_quality、bug_report_requirement、bug_report_status、bug_report_findings、bug_report_confidence、issue_language 在内的结构化输出（issue-triage.md "Required output"）。任务说明反复强调：模型绝不直接管理标签或 Issue 状态，这些动作全部由确定性的发布任务（deterministic publisher）完成。

发布任务（issue-triage.md "safe-outputs"）在写入前执行了严格的"重建-校验"流程，防止陈旧或被篡改的模型输出落库：

1. 以 ISSUE_TRIAGE_FORCE_EVIDENCE=true 重新拉取当前 Issue、重跑 issue-context.py 与 bug-report-analyzer.py，重建当前时刻的确定性证据；
2. 运行 .github/scripts/issue-triage/verify-agent-output.py 将模型输出与重建后的证据比对——产品标签只接受确定性候选，重复候选编号必须在允许集合内，输入哈希必须匹配；
3. 评论写入时查找已带 <!-- powertoys-ai-triage:canonical:v1 --> 标记的既有评论并原地更新（保证每个 Issue 只有一条规范分诊评论），且正文中的邮件地址、IP、SID、GUID、URL、token 等再次做脱敏，技术标识（0x 地址、.dll/.xaml/.log 等）自动转为行内代码格式；
4. 若 Issue 已关闭则跳过一切写入；标签只增不删版本类标签，Product-* 标签的匹配以仓库实际存在的标签为准（先按区域归一化匹配，再按模型请求的标签名回退匹配）。

4.5 重复关单：原生建议 + 人工确认 + 自我回滚

当存在验证通过的重复候选时，发布任务会按置信度排序取最高者，调用 GitHub API 的 state: { value: "closed", suggest: true, confidence: ... } 端点提交挂起式关单建议（issue-triage.md），state_reason 为 duplicate 并携带规范 Issue 的 duplicate_issue_id。这段逻辑还包含一个防御性检查：如果 GitHub 在"建议"模式下竟然直接把 Issue 关了（检测到关闭者是 github-actions[bot] 且时间戳晚于建议提交时刻），工作流会立即把 Issue 重新打开并使运行失败。这与其 README 中"绝不从模型输出直接关闭 Issue、每一条关单建议都保持挂起等待人工接受/拒绝"的原则一致（README.md）。

README.md 还记录了已退役的自动化：基于 GitHub Models 的自动去重器与 Issue/PR 区域打标签器均已移除——Issue 打标签由本工作流取代，PR 的确定性变更路径打标签则移交给 PR intake 流程。

五、Needs-Author-Feedback 标签的完整生命周期

把 policy 定时任务、AI 分诊与 PR intake 三处规则拼起来，这个标签的完整语义是（doc/devdocs/commands.md "The Needs-Author-Feedback label" 一节 + 源码印证）：

1. 打标来源：维护者执行 /needinfo、/bugreport；AI 分诊判定存在阻塞性缺失信息（复现步骤不足、必需的诊断报告缺失/被拒、或正文为非英文需要翻译）时由发布任务自动添加（issue-triage.md）。
2. 7 天静默自动关闭：Issue 与 PR 各有一条每小时巡检的定时任务，静默满 7 天即关（见 3.1 节）。
3. 作者回评清除（Issue）：作者本人评论触发 policy 响应器，标签被移除并转入 Needs-Triage + Needs-Team-Response。
4. 作者推送清除（PR）：对非 draft PR 的 push 会重跑 PR intake 工作流，重新计算该标签（pr-intake README 描述的生命周期规则）。
5. 手动移除标签即禁用定时关闭：一旦标签被移除（无论何种途径），定时任务的自然不再命中该 Issue，等效于"取消预约关单"。

六、PR intake：确定性 PR 分诊

与 Issue 分诊互补，.github/workflows/pr-intake.yml 负责 PR 侧的自动化。其设计要点（来自 pr-intake README 与工作流文件）：

• 不执行 PR 头部的任何代码：工作流基于 pull_request_target 触发，检出的是默认分支上的受信工作流源码，Node 脚本 .github/scripts/pr-intake/pr-intake.mjs 完全通过 GitHub API 读取 PR 数据；第三方 action 按提交哈希固定版本。
• 增量的 Product-* 打标签：根据变更文件路径的历史映射添加产品标签，最长路径前缀优先；更具体的产品命中时压制泛化的 Settings/General 标签；已有产品标签从不被移除；命中多个映射根的 PR 会获得每个对应标签。
• 就绪检查：对非 draft PR 确定性地校验 closing 引用、合并冲突与视觉证据（仅当变更路径触及产品 UI 文件时才要求截图）；缺失引用仅为提示性，而无效引用、合并冲突、合并状态未知、缺少必需视觉证据则会阻塞 Ready for review 状态。
• 单一规范评论：需要作者处理的事项集中维护在一条评论中；PR 完全干净且无历史评论时则不打扰作者。
• 健壮性上限：从不可信 PR 正文解析出的 closing 引用有数量上限，验证并发也有上限，防止精心构造的正文耗尽 API 配额。

七、贡献意图识别：把"想参与"的 Issue 参与者引向主帖

doc/devdocs/commands.md 提到的最后一项自动化是"贡献意图过滤"：当用户在 Issue 或 PR 中表达贡献意愿（例如说出 "I want to contribute"），机器人会添加一条评论，链接到 PowerToys 的 "Would you like to contribute to PowerToys?" 贡献主帖（issue #28769），提醒用户到该帖中报名，因为维护者看不到所有评论。

在 policy 配置中，它对应 resourceManagement.yml 中唯一的"无权限门槛"响应器——任何身份的人命中即触发。其正则为：

I(( would|'d) (like|love|be happy)| want) (to help|helping|to contribute|contributing|to implement|implementing|to fix|fixing)

可看出它覆盖了 "I want to contribute"、"I'd love to help"、"I would like to implement"、"I want to fix" 等常见表达。回复文案中也以 "I'm a bot (beep!)" 自我表明机器人身份，为可能的误判留出余地。

八、本地验证与延伸阅读

这套自动化体系的可验证性同样落在仓库中：AI 分诊与 PR intake 都提供了可离线运行的聚焦测试：

python -m unittest discover .github\scripts\issue-triage\tests -v
node --test .github\scripts\pr-intake\tests\pr-intake.test.mjs

测试分别覆盖 .github/scripts/issue-triage/tests/ 下的工作流契约、Issue 上下文解析、Bug 报告分析器与 Agent 输出校验逻辑，以及 .github/scripts/pr-intake/tests/pr-intake.test.mjs。

值得注意的工程取舍是：整个体系中 AI 只被允许做"判断"，所有"动作"（评论、标签、关单建议）都落在确定性代码路径上，且动作执行前会基于当前 Issue 状态重建证据做二次校验。对读者而言，若在自己的仓库中设计类似的 Issue/PR 自动化，PowerToys 提供的可借鉴模式包括：policy 文件中"正则 + 角色门槛 + 动作序列"的声明式命令定义、定时巡检与事件响应的分工、基于输入哈希的分诊幂等控制、对用户上传附件的大小/路径/压缩比多重限制与全文脱敏，以及"模型输出 → 确定性校验 → 挂起式人工确认"的关单链路。

参考文件

• 原始文档：doc/devdocs/commands.md
• 策略配置：.github/policies/resourceManagement.yml
• AI 分诊工作流：.github/workflows/issue-triage.md
• 分诊脚本说明：.github/scripts/issue-triage/README.md
• 确定性预处理：.github/scripts/issue-triage/issue-context.py
• 诊断报告脱敏分析：.github/scripts/issue-triage/bug-report-analyzer.py
• Agent 输出校验：.github/scripts/issue-triage/verify-agent-output.py
• PR intake 工作流：.github/workflows/pr-intake.yml、.github/scripts/pr-intake/README.md
• Issue 模板：.github/ISSUE_TEMPLATE/bug_report.yml