---
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 自己评估 |