issue-triage

name	issue-triage
description	GitHub Issue 处理协作流程。当用户收到 issue 需要分析和回复时使用。通过"诊断 → 定性 → 决策 → 回复"四步法，从一个 issue 产出准确的根因分析和得体的用户回复，避免误判问题类型或回复不专业。

用户收到了一个 GitHub Issue（bug 报告、疑问、feature request），需要 AI 协助分析问题、判断是否要做、起草回复。AI 全程主导推进，用户只在关键节点做判断。

核心原则

• 先诊断后开口 — 没看完代码不下结论，没找到根因不定性
• 对用户诚实 — 是 bug 就认，是架构限制就说清楚，不甩锅也不画饼
• 量化成本 — "成本高"不是结论，要说清楚高在哪：改几个文件、涉及哪些模块、有没有测试条件
• 给替代方案 — 不做不等于不管，要告诉用户现在怎么绕过

工作流程

第 1 步：获取 Issue 内容

目标： 拿到 issue 的完整信息。

方法：

1. 用户提供 issue 链接或仓库地址
2. 通过 gh issue view 或 WebFetch 获取 issue 详情
3. 提取关键信息：用户环境、复现步骤、期望行为、实际行为、用户的猜测

输出： 向用户简要转述 issue 内容，确认理解无误。

禁止： 只看标题就开始分析。必须读完 issue 全文。

第 2 步：代码诊断

目标： 在代码中找到根因。

方法：

1. 从 issue 描述中提取关键词（功能名、错误信息、页面名等）
2. 在代码中定位相关链路：从前端入口 → IPC 调用 → 后端处理 → 底层实现
3. 画出完整调用链，标注每个环节的文件和行号
4. 确认根因：代码哪里出了问题，或者代码为什么不支持用户的场景

输出： 向用户展示：

• 完整调用链（文件 + 行号）
• 根因的一句话总结
• 必要时附关键代码片段

禁止：

• 没读代码就猜原因
• 只看一个文件就下结论（要追完整条链路）

第 3 步：定性

目标： 判断这个 issue 属于哪种类型。

类型	判断标准	应对策略
Bug	在产品设计范围内，行为不符合预期	排期修复
架构限制	用户场景超出产品的设计前提	解释现状，评估是否值得扩展
Feature Request	产品本身没问题，用户想要新能力	评估成本和优先级
使用问题	用户操作方式不对，但产品可以做得更友好	回复指引，考虑优化体验

关键判断： 区分"该做但做错了"（bug）和"没打算做"（架构限制/feature）。

输出： 向用户说明定性结论和理由，等用户确认后再往下走。

第 4 步：决策（做还是不做）

目标： 基于根因和定性，给出做/不做的建议。

评估四个维度

1. 改动范围 — 改几行 / 改一个模块 / 新增一个模块
2. 影响面 — 只动一个文件 / 要改多个文件的调用链 / 要重构
3. 测试条件 — 有没有环境能复现和验证（没环境 = 高风险）
4. 用户绕过成本 — 用户自己能不能用其他方式解决

决策矩阵

改动范围	有测试条件	用户可绕过	建议
小（几行）	有	—	直接修
中（一个模块）	有	—	排期做
大（新模块/重构）	有	否	评估后排期
大（新模块/重构）	没有	是	记下需求，暂不做
任意	没有	是	告知绕过方案，需求记下

输出： 向用户说明建议和理由。如果建议不做，要量化成本（改几个文件、涉及哪些模块、为什么没法测）。

等用户确认决策后，再进入回复环节。

第 5 步：起草回复

目标： 写一条专业、得体、有信息量的 issue 回复。

回复结构（三层）

1. 解释场景定位 — 这个功能是为什么场景设计的，让用户理解"为什么当前不支持"
2. 给出实际影响 — 对用户来说，没有这个功能影响大不大，有没有替代方案
3. 说明后续计划 — 如果做，给方向；如果不做，诚实说明成本和原因

语气原则

• 感谢反馈 — 用户花时间提 issue 值得尊重
• 不甩锅 — 不说"你用错了"，说"这个场景我们还没覆盖到"
• 给具体建议 — 不只说"不行"，要告诉用户现在怎么办
• 量化成本 — 让用户理解不是不想做，是客观上成本高

回复模板

Hi @{用户名}，感谢反馈！

**1. 功能定位**
{这个功能是为什么场景设计的，为什么当前不支持用户的场景}

**2. 对你的实际影响**
{用户现在能不能绕过，怎么绕过，核心功能是否受影响}

**3. 关于{用户期望的能力}**
{成本说明 + 后续计划}

输出： 回复草稿，等用户确认后发布。

禁止：

• 不经用户确认就直接发布到 GitHub
• 用技术黑话回复非技术用户
• 只说结论不解释原因

第 6 步：发布

用户确认回复内容后：

1. 通过 gh issue comment 发布评论
2. 根据定性结果打标签（bug / enhancement / wontfix / question）
3. 如果需要记录为需求，提醒用户是否要加到需求池

过程中的沟通规范

AI 主导的节奏

1. 每一步完成后主动推进到下一步
2. 关键结论让用户确认后再往下走（定性、决策、回复内容）
3. 技术细节 AI 自己搞定，只向用户展示结论

必须等用户确认的节点

步骤	确认什么
第 1 步	"issue 内容我理解的对吗？"
第 3 步	"这个定性你认同吗？"
第 4 步	"这个决策你同意吗？"
第 5 步	"回复内容可以发吗？"

不需要问用户的

事项	直接做
代码怎么查	AI 自己追链路
根因怎么分析	AI 自己判断
成本怎么量化	AI 自己评估