# 故障排除案例库使用指南

> v2.13.0 新增功能 - 让 Copilot 从你的经验中学习

---

## 🎯 核心价值

### 问题场景

你正在还原 UI 设计稿，遇到阴影透出问题：

**传统流程**（需要 8-10 轮对话）：
```
你: 阴影不对
Copilot: 试试降低透明度？
你: 没用
Copilot: 改改阴影颜色？
你: 还是不对
Copilot: 调整 blurRadius？
你: 治标不治本
...（反复多轮）
最后: 使用 CustomPainter 绘制空心阴影
```

**使用案例库**（1 轮解决）：
```
你: Flutter 新拟态阴影透出问题
Copilot: [查询案例库] 找到匹配案例 "shadow-透出问题"
       根因：BoxShadow 绘制在容器下方，半透明背景导致阴影透出
       方案：使用 HollowShadowPainter
       [直接提供完整代码]
你: 完美！
```

**节省**: 7-9 轮对话，约 10-15 分钟

---

## 🚀 快速开始

### 1. 更新 MCP 服务器

```bash
cd /Users/pailasi/Work/copilot-prompts/mcp-server
npm run build
```

### 2. 在 Copilot Chat 中使用

#### 场景 A：遇到具体问题

```
@copilot 我的 Flutter 新拟态容器背景比设计稿暗，阴影好像透出来了
```

Copilot 会自动：
1. 识别关键词：`flutter`, `新拟态`, `阴影透出`
2. 调用 `query_troubleshooting_cases`
3. 返回最相关的案例和解决方案

#### 场景 B：主动查询

```
@copilot 查询 Vue3 表格边框相关的故障排除案例
```

#### 场景 C：列出所有案例

```
@copilot 列出所有 Flutter 故障排除案例
```

---

## 🧪 MCP 工具使用

### query_troubleshooting_cases

**参数**：
```typescript
{
  framework?: "flutter" | "vue3" | "react" | "common",
  keywords?: string[],          // 问题关键词
  errorMessage?: string,        // 错误信息
  codePattern?: string,         // 问题代码片段
  limit?: number                // 最多返回案例数（默认5）
}
```

**返回**：
```typescript
{
  cases: [
    {
      id: "shadow-透出问题",
      title: "Flutter 阴影透出问题",
      framework: "flutter",
      tags: ["shadow", "neumorphism", "transparency"],
      matchScore: 85,           // 匹配度 0-100
      timeSaved: "6-10轮对话",
      preview: "问题根源：BoxShadow 绘制在容器下方..."
    }
  ],
  totalFound: 3,
  queryInfo: { framework: "flutter", keywords: ["shadow"] }
}
```

### get_troubleshooting_case

**获取案例完整内容**：
```typescript
{
  framework: "flutter",
  caseId: "shadow-透出问题"
}
```

**返回**：
```typescript
{
  content: "# Flutter 阴影透出问题\n\n...",  // 完整 Markdown
  metadata: { ... }
}
```

---

## 📝 贡献案例

### 何时创建案例？

- ✅ 问题需要 **3 轮以上对话**才解决
- ✅ 错误路线明确（知道哪些方案无效）
- ✅ 有明确的**正确方案**
- ✅ 问题有**通用性**（其他项目可能遇到）

### 案例模板

在 `troubleshooting/{framework}/` 下创建 Markdown 文件：

```markdown
# 问题标题

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

---

## 🔍 问题识别

### 自动检测特征
- 代码模式：\`\`\`dart ... \`\`\`
- 错误信息关键词

### 用户描述关键词
- "xxx不对"
- "xxx比设计稿暗"

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

---

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

| 尝试方向 | 为什么无效 | 浪费时间 |
|----------|-----------|---------|
| 方案A | 原因 | 2轮 |
| 方案B | 原因 | 3轮 |

**总计浪费**: X 轮对话

---

## ✅ 正确解决方案

### 核心原理
解释问题根因...

### 解决方法
\`\`\`dart
// 完整代码
\`\`\`

### 使用示例
\`\`\`dart
// 实际应用
\`\`\`

---

## 📋 适用场景
- ✅ 场景1
- ✅ 场景2

## 🔗 相关案例
- [相关案例1](./xxx.md)

---

**来源**: 项目名  
**创建日期**: YYYY-MM-DD  
**节省时间**: X-Y 轮对话
```

---

## 🤖 Agent 集成

最新的 Agent 配置已自动包含案例库查询：

### Flutter Agent

```markdown
## ⚠️ 强制工作流

### 步骤 0: 遇到问题时优先查询案例库 🆘

**如果遇到以下情况，立即查询故障排除案例：**
- 编译错误或运行时错误
- UI 还原与设计稿不符
- 需要多轮对话才能解决的问题

\`\`\`
query_troubleshooting_cases({
  framework: "flutter",
  keywords: ["问题关键词"],
  errorMessage: "错误描述"
})
\`\`\`
```

### Vue3 Agent

```markdown
### 步骤 0: 遇到问题时优先查询案例库 🆘

**常见问题关键词**：
- `table`, `border` - 表格边框问题
- `i18n`, `hardcode` - 国际化硬编码
- `css`, `style` - 样式冲突
```

---

## 📊 效果统计

基于 my_flutter 项目实测：

| 问题类型 | 传统耗时 | 使用案例库 | 节省 |
|---------|---------|-----------|------|
| 新拟态阴影透出 | 10轮 | 1轮 | 90% |
| 输入框布局不匹配 | 6轮 | 1-2轮 | 70% |
| 组件字段缺失 | 3轮 | 1轮 | 66% |

**平均节省**: 4-8 轮对话/问题

---

## 🔮 路线图

### v2.13.0 ✅
- [x] 基础案例库结构
- [x] MCP 工具实现
- [x] Agent 集成
- [x] Flutter 首个案例
- [x] Vue3 首个案例

### v2.14.0（规划中）
- [ ] 自动问题检测（基于错误信息）
- [ ] 代码模式匹配
- [ ] 更多框架支持（React, Angular）
- [ ] 案例贡献工作流

### v2.15.0（规划中）
- [ ] AI 辅助案例生成
- [ ] 相似问题推荐
- [ ] 案例有效性反馈机制

---

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