troubleshoot git:20261102.ccba1f9A

Immutable. This exact content never changes and is served at /api/v1/blob/add18b74218ccd37.

---
name: troubleshoot
description: 根因分析。在软件工程类项目中，排查复杂、难解问题时必须遵守此流程分析原因。
user-invocable: true
---

# troubleshoot

作为主工程师完成问题的根因分析。
你的目标是输出准确、可执行的诊断结论，为后续修复提供可靠依据。

遵守以下工作流程：

## 1. 根因分析

仔细阅读日志和代码。你的分析应该能够完美解释用户看到的全部现象。
**当且仅当你对于根因的确信度大于85%（也就是说，你的判断中猜测的成分已经很少）时，才输出诊断结论。**

### 1.5 如果无法确定根因？
如果感到问题较难分析，不要假装你已经明白了原因然后盲目修复，那只会让问题扩大！
你可以用以下方式辅助分析：

- **（推荐用于复杂问题）** 构造测试用例 / e2e 测试完整复现问题场景来捕捉问题。不通过的测试用例在本问题解决时应该通过，作为回归测试的验收标准。
- 添加详细调测日志，请求用户实机复现，通过日志准确捕捉问题。
- 对于无法稳定复现的小概率问题，通过 mock 等方式主动构造，找出问题出现的条件。

## 2. 输出诊断结论

明确输出以下内容：
1. **根因**：问题的根本原因。
2. **现象与根因的关联**：解释用户看到的全部现象。
3. **修复路径**：选择最恰当的修复路径，附理由。
4. **置信度**：你对该修改能够达成预期的确信度。
5. **验收标准**

### 2A. 单点修复

如果问题为单点问题，建议精准修复路径。

### 2B. 重构型修复

如果本问题属于更大范围的设计问题，最优雅的解决方法不是"贴狗皮膏药"而是改进设计（这在长远来看大有好处）。
向用户提出你的重构建议！询问用户是否进行重构型修复。

诊断结论及修复方向输出到 `/docs/issues/yymmdd-{issue_name}/yymmdd-{issue_name}.troubleshoot.md`。

## Next Step

用户书面确认诊断结果后，进入修复实施阶段。

**备注:**

如果你连续多次分析都未能达成确信，意味着当前思路不可靠或缺乏关键线索，继续试错只会引入更多不确定性。请清空既有思路从零梳理，并更积极地采用 1.5 所述方法。