# 故障排除案例库

> 基于真实项目经验总结的问题解决方案，通过 MCP 工具让 AI 快速获取经验

---

## 🎯 定位与职责

### Troubleshooting vs Standards

| 维度 | Troubleshooting（问题解决） | Standards（编码规范） |
|------|---------------------------|---------------------|
| **用途** | 解决具体问题和错误 | 定义编码风格和最佳实践 |
| **使用时机** | 遇到错误、异常、效果不符 | 编写新功能、参考推荐写法 |
| **内容** | 完整解决方案 + 错误路线 | 禁止模式 + 推荐写法 |
| **示例** | "阴影透出问题如何解决" | "如何使用 Token 系统" |
| **MCP 工具** | `troubleshoot()` | `get_relevant_standards()` |

**简单判断**：
- 有明确的"问题" → **Troubleshooting**
- 需要"规范"指导 → **Standards**

---

## 🎯 核心理念

**问题是避免不了的，但踩过的坑不应该重复踩！**

### 旧流程（低效）
1. AI 猜测方案 A → 失败 → 2-3 轮对话
2. AI 猜测方案 B → 失败 → 2-3 轮对话  
3. 用户提示"去 troubleshooting 看看" → 成功
4. **浪费 6-10 轮对话**

### 新流程（高效）
1. AI 调用 `troubleshoot` 工具 → 直接获得验证方案 → **1 轮解决！**

---

## 🚀 MCP 工具

### `troubleshoot` - 语义化查询（推荐 ⭐）

直接传入问题描述，系统自动识别框架和提取关键词：

```typescript
// AI 直接传入用户描述
troubleshoot({ 
  problem: "Flutter 新拟态阴影透出来了，容器比设计稿暗" 
})

// 系统自动：
// 1. 检测框架 → Flutter
// 2. 提取关键词 → [shadow, 阴影, 新拟态, neumorphism]
// 3. 搜索匹配案例
// 4. 返回排序后的结果（包含预览摘要和应避免的错误路线）
```

**返回示例**：
```json
{
  "detectedFramework": "flutter",
  "extractedKeywords": ["shadow", "阴影", "新拟态"],
  "cases": [
    {
      "caseId": "shadow-透出问题",
      "title": "Flutter 阴影透出问题",
      "score": 70,
      "preview": "根本原因：BoxDecoration 的阴影是画在透明底上...",
      "wrongApproaches": ["降低阴影透明度 → 无效，颜色会变淡"]
    }
  ]
}
```

### `query_troubleshooting_cases` - 精确查询

当需要指定框架或关键词时使用：

```typescript
query_troubleshooting_cases({ 
  framework: "flutter",
  keywords: ["shadow", "transparency"],
  errorMessage: "阴影透出来了"
})
```

### `get_troubleshooting_case` - 获取完整方案

```typescript
get_troubleshooting_case({ 
  framework: "flutter", 
  caseId: "shadow-透出问题" 
})
```

### `list_troubleshooting_cases` - 列出所有案例

```typescript
list_troubleshooting_cases({ framework: "flutter" })
```

---

## 📚 案例清单

### Flutter (14 个案例)

| 案例ID | 问题类型 | 关键词 |
|--------|----------|--------|
| shadow-透出问题 | 阴影透出/容器变暗 | shadow, transparency, neumorphism |
| clip-阴影裁剪 | 阴影被裁剪 | clip, clipBehavior |
| layout-尺寸不匹配 | 布局尺寸偏移 | layout, size, spacing |
| input-边框问题 | 输入框边框异常 | input, border, focus |
| input-字段缺失 | 组件字段缺失 | property, field |
| tabbar-动画同步 | TabBar动画不同步 | animation, tabbar, color |
| svg-颜色异常 | SVG颜色不对 | svg, color, colorfilter |
| svg-未居中 | SVG未居中 | svg, viewbox, center |
| sketch-图标尺寸 | 图标尺寸提取错误 | sketch, icon, group, shape |
| sketch-属性未使用 | 属性定义但未使用 | property, unused |
| sketch-背景层高度 | Frame与_background高度差异 | sketch, frame, background, height, _bg |
| sketch-列表item区域 | 列表首尾item高度不一致 | sketch, list, menu, padding, divider |
| sketch-structural-drift | 测量正确但页面结构被业务语义改写 | sketch, measure, 结构漂移, route title, l10n, cta |
| withopacity-弃用 | withOpacity弃用警告 | opacity, deprecated |

### Vue3 (1 个案例)

| 案例ID | 问题类型 | 关键词 |
|--------|----------|--------|
| table-边框问题 | Element Plus表格边框 | table, border, css |

---

## 📝 案例格式规范

每个案例文件需包含以下结构：

```markdown
# {问题标题}

> **问题标签**: `tag1`, `tag2`, `tag3`  
> **框架**: Flutter / Vue3 / React  
> **严重程度**: 低/中等/高

---

## 🔍 问题识别

### 用户描述关键词
- "xxx"
- "yyy"

### 问题特征
- [ ] 特征1
- [ ] 特征2

---

## 🎯 核心原理

**根本原因**：...

---

## ✅ 正确解决方案

### 方案代码
\`\`\`dart
// 正确代码示例
\`\`\`

---

## ❌ 常见错误排查路线（避免重复）

| 尝试方向 | 为什么无效 | 浪费时间 |
|----------|-----------|---------|
| xxx | xxx | 1-2 轮 |

---

## 📁 适用场景

- ✅ 场景1
- ✅ 场景2
```

---

## 🔧 添加新案例

1. 在对应框架目录创建 `.md` 文件（如 `flutter/新问题.md`）
2. 按照上述格式编写内容
3. 确保包含 `问题标签` 行（用于匹配）
4. 运行 `npm run build` 重新构建
5. 测试查询是否能正确匹配

---

**版本**: v2.15.0  
**案例总数**: 14 个  
**最后更新**: 2026-01-19

---

## 📖 Agent 工作流程

Agent（如 flutter.agent.md、vue3.agent.md）被精简为引导文档，核心职责：

1. **检测问题** - 识别用户描述的是问题还是功能需求
2. **调用 troubleshoot** - 如果是问题，先查询案例库
3. **应用方案** - 使用验证过的解决方案
4. **加载规范** - 如果是新功能，加载编码规范

**Agent 精简效果**：
- flutter.agent.md: 1240 行 → 195 行（**-84%**）
- vue3.agent.md: 591 行 → 285 行（**-52%**）

详细方案和代码示例都迁移到了 troubleshooting 案例中。

---

## 📚 当前可用案例

### Flutter

| 案例 | 问题类型 | 关键词 | 节省时间 | 状态 |
|------|---------|--------|---------|------|
| [shadow-透出问题](./flutter/shadow-透出问题.md) | UI渲染 | shadow, neumorphism, transparency | 6-10轮 | ✅ |
| [layout-尺寸不匹配](./flutter/layout-尺寸不匹配.md) | 布局偏差 | layout, sizing, design-spec | 4-7轮 | ✅ |
| [input-字段缺失](./flutter/input-字段缺失.md) | 组件配置 | component, props, missing-field | 2-4轮 | ✅ |
| [clip-阴影裁剪](./flutter/clip-阴影裁剪.md) | 布局裁剪 | clip, shadow, overflow | 7-11轮 | ✅ |
| [input-边框问题](./flutter/input-边框问题.md) | 主题冲突 | textfield, border, focus | 6-9轮 | ✅ |

**总计**: 5 个案例，节省 25-41 轮对话

### Vue 3 + Element Plus

| 案例 | 问题类型 | 关键词 | 节省时间 | 状态 |
|------|---------|--------|---------|------|
| [table-边框问题](./vue3/table-边框问题.md) | 样式冲突 | table, border, css-conflict | 6-10轮 | ✅ |

**总计**: 1 个案例

---

## 🎯 匹配算法优化（v2.13.0）

### 评分维度（总分100+）

1. **标签匹配** (40分) - 关键词出现在案例标签中
2. **标题匹配** (30分) - 关键词出现在案例标题中  
3. **问题类型匹配** (15分) - 关键词与问题分类相关
4. **错误信息匹配** (30分) - 用户描述与案例内容相似度
5. **精确标签奖励** (+15分/个) - 关键词与标签完全一致

### 智能过滤阈值

- **基础**: 分数≥10
- **有错误信息**: 分数≥5（更宽松）
- **关键词≥3个**: 分数≥15（更严格）

### 预览优化

优先级顺序：
1. "核心原理"章节
2. "问题原因"章节
3. "问题识别"章节
4. 文档开头非空内容

---

## ✍️ 贡献案例

### 案例格式规范

每个案例文件应包含：

```markdown
# 问题标题

> **问题标签**: `tag1`, `tag2`  
> **框架**: Flutter/Vue3/React  
> **严重程度**: 低/中/高

## 🔍 问题识别
- 自动检测特征（代码模式）
- 用户描述关键词
- 问题特征 checklist

## ❌ 常见错误排查路线
- 列出无效的尝试方向
- 说明为什么无效
- 估算浪费的时间

## ✅ 正确解决方案
- 核心原理
- 完整代码
- 使用示例

## 📋 适用场景
## 🔗 相关案例
```

### 提交流程

1. 在项目中遇到需要多轮对话才解决的问题
2. 整理问题特征、错误路线、正确方案
3. 按照格式创建 Markdown 文件
4. 提交到对应框架目录

---

## 🤖 技术实现

### MCP 工具定义

```typescript
{
  name: 'query_troubleshooting_cases',
  description: '根据问题特征查询相关的故障排除案例',
  inputSchema: {
    type: 'object',
    properties: {
      framework: { 
        type: 'string',
        enum: ['flutter', 'vue3', 'react', 'common']
      },
      keywords: { 
        type: 'array',
        items: { type: 'string' },
        description: '问题关键词，如 shadow, layout, i18n'
      },
      errorMessage: { 
        type: 'string',
        description: '错误信息或用户描述'
      },
      codePattern: {
        type: 'string',
        description: '问题代码片段'
      }
    }
  }
}
```

### 匹配算法

1. **关键词匹配** - 计算用户输入与案例标签的重合度
2. **错误信息匹配** - 搜索案例中的错误特征
3. **代码模式匹配** - 使用正则匹配已知问题代码
4. **相关性排序** - 按匹配度返回最相关的 3-5 个案例

---

## 📊 效果统计

通过引入故障排除案例库，预计可以：

- **减少对话轮数**: 平均每个问题减少 4-6 轮
- **提高解决率**: 首次建议成功率从 30% → 70%
- **知识复用**: 避免重复踩坑
- **降低 Token 消耗**: 精准推荐减少无效尝试

---

**维护者**: MTA工作室  
**创建日期**: 2026-01-16  
**版本**: v1.0