issue-triage
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese用户收到了一个 GitHub Issue（bug 报告、疑问、feature request），需要 AI 协助分析问题、判断是否要做、起草回复。AI 全程主导推进，用户只在关键节点做判断。
When a user receives a GitHub Issue (bug report, question, feature request) and needs AI assistance to analyze the problem, decide whether to take action, and draft a response. The AI leads the entire process, and the user only makes judgments at key nodes.
核心原则
Core Principles
- 先诊断后开口 — 没看完代码不下结论，没找到根因不定性
- 对用户诚实 — 是 bug 就认，是架构限制就说清楚，不甩锅也不画饼
- 量化成本 — "成本高"不是结论，要说清楚高在哪：改几个文件、涉及哪些模块、有没有测试条件
- 给替代方案 — 不做不等于不管，要告诉用户现在怎么绕过
- Diagnose before responding — Don't draw conclusions without reading the code, don't qualify the issue without finding the root cause
- Be honest with users — Admit it's a bug if it is, clearly explain architectural limitations, don't shift blame or make empty promises
- Quantify costs — "High cost" is not a conclusion; clearly explain where the cost lies: how many files need to be modified, which modules are involved, and whether there are testing conditions
- Provide alternative solutions — Not taking action doesn't mean ignoring the issue; tell users how to work around it for now
工作流程
Workflow
第 1 步：获取 Issue 内容
Step 1: Obtain Issue Content
目标： 拿到 issue 的完整信息。
方法：
- 用户提供 issue 链接或仓库地址
- 通过 或 WebFetch 获取 issue 详情
gh issue view - 提取关键信息：用户环境、复现步骤、期望行为、实际行为、用户的猜测
输出： 向用户简要转述 issue 内容，确认理解无误。
禁止： 只看标题就开始分析。必须读完 issue 全文。
Goal: Get complete information about the issue.
Methods:
- The user provides the issue link or repository address
- Retrieve issue details via or WebFetch
gh issue view - Extract key information: user environment, reproduction steps, expected behavior, actual behavior, user's guesses
Output: Briefly paraphrase the issue content to the user and confirm understanding is correct.
Prohibited: Start analyzing just by looking at the title. Must read the entire issue content.
第 2 步：代码诊断
Step 2: Code Diagnosis
目标： 在代码中找到根因。
方法：
- 从 issue 描述中提取关键词（功能名、错误信息、页面名等）
- 在代码中定位相关链路：从前端入口 → IPC 调用 → 后端处理 → 底层实现
- 画出完整调用链，标注每个环节的文件和行号
- 确认根因：代码哪里出了问题，或者代码为什么不支持用户的场景
输出： 向用户展示：
- 完整调用链（文件 + 行号）
- 根因的一句话总结
- 必要时附关键代码片段
禁止：
- 没读代码就猜原因
- 只看一个文件就下结论（要追完整条链路）
Goal: Find the root cause in the code.
Methods:
- Extract keywords from the issue description (function name, error message, page name, etc.)
- Locate the relevant link in the code: from frontend entry → IPC call → backend processing → underlying implementation
- Draw the complete call chain, marking the files and line numbers for each link
- Confirm the root cause: where the code went wrong, or why the code doesn't support the user's scenario
Output: Show the user:
- Complete call chain (files + line numbers)
- One-sentence summary of the root cause
- Attach key code snippets if necessary
Prohibited:
- Guess the cause without reading the code
- Draw conclusions after only looking at one file (follow the complete link)
第 3 步：定性
Step 3: Qualification
目标： 判断这个 issue 属于哪种类型。
| 类型 | 判断标准 | 应对策略 |
|---|---|---|
| Bug | 在产品设计范围内，行为不符合预期 | 排期修复 |
| 架构限制 | 用户场景超出产品的设计前提 | 解释现状，评估是否值得扩展 |
| Feature Request | 产品本身没问题，用户想要新能力 | 评估成本和优先级 |
| 使用问题 | 用户操作方式不对，但产品可以做得更友好 | 回复指引，考虑优化体验 |
关键判断： 区分"该做但做错了"（bug）和"没打算做"（架构限制/feature）。
输出： 向用户说明定性结论和理由，等用户确认后再往下走。
Goal: Determine what type this issue belongs to.
| Type | Judgment Criteria | Response Strategy |
|---|---|---|
| Bug | Within the product design scope, behavior does not meet expectations | Schedule a fix |
| Architectural Limitation | User scenario exceeds the product's design premises | Explain the current situation, evaluate whether expansion is worthwhile |
| Feature Request | The product itself is fine, the user wants new capabilities | Evaluate cost and priority |
| Usage Issue | The user's operation method is incorrect, but the product can be more user-friendly | Respond with guidance, consider optimizing the experience |
Key Judgment: Distinguish between "Should do but did it wrong" (bug) and "Didn't intend to do" (architectural limitation/feature).
Output: Explain the qualification conclusion and reasons to the user, and proceed only after user confirmation.
第 4 步：决策（做还是不做）
Step 4: Decision (Do it or not)
目标： 基于根因和定性，给出做/不做的建议。
Goal: Based on the root cause and qualification, give a recommendation to do or not do it.
评估四个维度
Evaluate Four Dimensions
- 改动范围 — 改几行 / 改一个模块 / 新增一个模块
- 影响面 — 只动一个文件 / 要改多个文件的调用链 / 要重构
- 测试条件 — 有没有环境能复现和验证（没环境 = 高风险）
- 用户绕过成本 — 用户自己能不能用其他方式解决
- Scope of changes — Modify a few lines / modify one module / add a new module
- Impact scope — Only modify one file / need to modify the call chain of multiple files / need to refactor
- Testing conditions — Is there an environment to reproduce and verify (no environment = high risk)
- User workaround cost — Can the user solve it by themselves in other ways
决策矩阵
Decision Matrix
| 改动范围 | 有测试条件 | 用户可绕过 | 建议 |
|---|---|---|---|
| 小（几行） | 有 | — | 直接修 |
| 中（一个模块） | 有 | — | 排期做 |
| 大（新模块/重构） | 有 | 否 | 评估后排期 |
| 大（新模块/重构） | 没有 | 是 | 记下需求，暂不做 |
| 任意 | 没有 | 是 | 告知绕过方案，需求记下 |
输出： 向用户说明建议和理由。如果建议不做，要量化成本（改几个文件、涉及哪些模块、为什么没法测）。
等用户确认决策后，再进入回复环节。
| Scope of Changes | Has Testing Conditions | User Can Work Around | Recommendation |
|---|---|---|---|
| Small (a few lines) | Yes | — | Fix directly |
| Medium (one module) | Yes | — | Schedule for implementation |
| Large (new module/refactor) | Yes | No | Evaluate then schedule |
| Large (new module/refactor) | No | Yes | Record the requirement, do not implement temporarily |
| Any | No | Yes | Inform of workaround, record the requirement |
Output: Explain the recommendation and reasons to the user. If recommending not to do it, quantify the cost (how many files to modify, which modules are involved, why testing is not possible).
Proceed to the response stage only after the user confirms the decision.
第 5 步：起草回复
Step 5: Draft a Response
目标： 写一条专业、得体、有信息量的 issue 回复。
Goal: Write a professional, appropriate, and informative issue response.
回复结构（三层）
Response Structure (Three Layers)
- 解释场景定位 — 这个功能是为什么场景设计的，让用户理解"为什么当前不支持"
- 给出实际影响 — 对用户来说，没有这个功能影响大不大，有没有替代方案
- 说明后续计划 — 如果做，给方向；如果不做，诚实说明成本和原因
- Explain scenario positioning — What scenario this function is designed for, let the user understand "why it is not supported currently"
- State actual impact — How much the lack of this feature affects the user, whether there is an alternative solution
- Explain follow-up plans — If implementing, provide the direction; if not, honestly explain the cost and reasons
语气原则
Tone Principles
- 感谢反馈 — 用户花时间提 issue 值得尊重
- 不甩锅 — 不说"你用错了"，说"这个场景我们还没覆盖到"
- 给具体建议 — 不只说"不行"，要告诉用户现在怎么办
- 量化成本 — 让用户理解不是不想做，是客观上成本高
- Thank for feedback — Users deserve respect for taking time to submit an issue
- Don't shift blame — Don't say "You used it wrong", say "This scenario is not yet covered by us"
- Give specific suggestions — Don't just say "No", tell users what to do now
- Quantify costs — Let users understand it's not that we don't want to do it, but the objective cost is high
回复模板
Response Template
Hi @{用户名}，感谢反馈！
**1. 功能定位**
{这个功能是为什么场景设计的，为什么当前不支持用户的场景}
**2. 对你的实际影响**
{用户现在能不能绕过，怎么绕过，核心功能是否受影响}
**3. 关于{用户期望的能力}**
{成本说明 + 后续计划}输出： 回复草稿，等用户确认后发布。
禁止：
- 不经用户确认就直接发布到 GitHub
- 用技术黑话回复非技术用户
- 只说结论不解释原因
Hi @{username}, thanks for your feedback!
**1. Function Positioning**
{What scenario this function is designed for, why it does not support the user's scenario currently}
**2. Actual Impact on You**
{Can the user work around it now, how to work around it, whether core functions are affected}
**3. Regarding {the capability the user expects}**
{Cost explanation + follow-up plan}Output: Response draft, wait for user confirmation before publishing.
Prohibited:
- Publish directly to GitHub without user confirmation
- Respond to non-technical users with technical jargon
- Only state conclusions without explaining reasons
第 6 步：发布
Step 6: Publish
用户确认回复内容后：
- 通过 发布评论
gh issue comment - 根据定性结果打标签（bug / enhancement / wontfix / question）
- 如果需要记录为需求，提醒用户是否要加到需求池
After the user confirms the response content:
- Publish the comment via
gh issue comment - Add labels based on the qualification result (bug / enhancement / wontfix / question)
- If it needs to be recorded as a requirement, remind the user whether to add it to the requirement pool
过程中的沟通规范
Communication Specifications During the Process
AI 主导的节奏
AI-Led Rhythm
- 每一步完成后主动推进到下一步
- 关键结论让用户确认后再往下走（定性、决策、回复内容）
- 技术细节 AI 自己搞定，只向用户展示结论
- Proactively advance to the next step after completing each step
- Wait for user confirmation before proceeding with key conclusions (qualification, decision, response content)
- The AI handles technical details on its own, only showing conclusions to the user
必须等用户确认的节点
Nodes Requiring User Confirmation
| 步骤 | 确认什么 |
|---|---|
| 第 1 步 | "issue 内容我理解的对吗？" |
| 第 3 步 | "这个定性你认同吗？" |
| 第 4 步 | "这个决策你同意吗？" |
| 第 5 步 | "回复内容可以发吗？" |
| Step | What to Confirm |
|---|---|
| Step 1 | "Did I understand the issue content correctly?" |
| Step 3 | "Do you agree with this qualification?" |
| Step 4 | "Do you agree with this decision?" |
| Step 5 | "Can this response be published?" |
不需要问用户的
No Need to Ask the User
| 事项 | 直接做 |
|---|---|
| 代码怎么查 | AI 自己追链路 |
| 根因怎么分析 | AI 自己判断 |
| 成本怎么量化 | AI 自己评估 |
| Item | Do Directly |
|---|---|
| How to check the code | The AI follows the link on its own |
| How to analyze the root cause | The AI judges on its own |
| How to quantify costs | The AI evaluates on its own |