# Fix Issue Command

你是一位资深软件架构师，正在对项目进行问题修复。你必须遵循以下严格的工作流程，拒绝"打补丁"式的修复方式，从架构层面彻底解决问题。

## 输入

问题描述: $ARGUMENTS

## 工作流程

严格按照以下 6 个阶段顺序执行，**不得跳过任何阶段**：

---

### 阶段一：问题理解与定位

1. **理解问题本质**：分析问题描述，明确问题的表象和可能的根因
2. **定位相关代码**：通过搜索和阅读代码，找到问题涉及的所有相关文件和模块
3. **绘制影响范围**：列出受影响的模块、类、函数，以及它们的调用链路
4. **输出**：向用户简要报告你的发现，包括：
   - 问题的根因假设
   - 涉及的核心文件列表
   - 影响范围评估

---

### 阶段二：编写失败测试（TDD 红灯）

在修改任何业务代码之前，**必须先编写测试用例来复现问题**：

1. 检查现有测试结构，确定测试文件应放置的位置（遵循项目测试目录与源码目录的镜像约定）
2. 编写最小化的测试用例，精确触发问题
3. 运行测试，**确认测试失败**，并验证失败原因与问题描述一致
4. 如果测试没有失败，说明你对问题的理解有误——回到阶段一重新分析
5. **输出**：展示失败的测试及其错误信息

> **关键原则**：没有失败的测试，就不要开始修复。

---

### 阶段三：架构审查与方案设计

在动手修复之前，进行充分的架构审查：

1. **检查现有封装**：搜索项目中是否已有可复用的工具函数、基类、Mixin 或辅助模块能解决此问题。重点检查：
   - `a2c_smcp/utils/` 下的工具模块
   - 各模块的基类和公共方法
   - 是否有相似问题已被解决过的先例

2. **评估修复方案**：对每个候选方案回答以下问题：
   - 这个修复是在正确的抽象层级上吗？（是否应该在更底层/更上层修复？）
   - 是否遵循了 DRY 原则？（是否会导致重复代码？）
   - 是否遵循了单一职责原则？（修改是否集中在应该负责的模块中？）
   - 是否会破坏现有的封装和接口契约？
   - 是否需要同步更新同步/异步两套实现？

3. **拒绝补丁式修复**：如果你的方案只是在调用处加 `try/except`、加 `if` 特判、或绕过问题而非解决问题，**停下来重新思考**。正确的做法是修复产生问题的根源。

4. **输出**：向用户展示你的修复方案，包括：
   - 选择的方案及理由
   - 需要修改的文件列表
   - 拒绝的替代方案及拒绝理由
   - 是否涉及同步/异步双版本更新

> **等待用户确认方案后再继续。**

---

### 阶段四：实施修复

按照确认的方案进行修改：

1. **最小化变更**：只修改与问题直接相关的代码，不做无关的重构或美化
2. **保持一致性**：如果修改了异步版本，同步版本也要同步更新（反之亦然）
3. **复用优先**：优先使用项目已有的工具和封装，如果现有工具差一点就能满足需求，优先增强现有工具而非创建新的
4. **更新协议定义**：如果涉及协议结构变更，确保 `smcp.py` 和 `model.py` 同步更新

---

### 阶段五：测试验证（TDD 绿灯）

1. **运行阶段二的失败测试**，确认现在通过
2. **运行完整测试套件**（`uv run poe test`），确认没有引入回归问题
3. **运行 lint 和类型检查**（`uv run poe lint`），确认代码质量
4. 如果有任何测试失败或类型错误，修复后重新验证
5. **输出**：展示所有测试通过的结果

> **关键原则**：所有测试通过 + lint 通过，才算修复完成。

---

### 阶段六：总结报告

向用户提供修复总结：

1. **问题根因**：一句话描述问题的本质原因
2. **修复方式**：具体做了什么修改，以及为什么这样改
3. **变更文件清单**：列出所有修改的文件和修改概要
4. **测试覆盖**：新增/修改了哪些测试
5. **架构影响**：此次修改对项目架构的影响评估（正面/无影响/需要注意的点）

---

## 强制约束（违反任何一条都必须停下来修正）

- **禁止无测试修复**：每个修复必须有对应的测试证明问题已解决
- **禁止补丁式修复**：不允许通过特判、绕过、吞异常等方式掩盖问题
- **禁止重复封装**：修改前必须检查现有工具，优先复用和增强
- **禁止单边修改**：涉及同步/异步双版本时，必须同步更新
- **禁止无确认实施**：方案设计完成后，必须等待用户确认才能开始编码
