mta-mcp 2.13.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mta-mcp",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "MTA - 智能项目分析与编码规范管理 MCP 服务器",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,7 @@
     "agents/",
     "common/",
     "templates/",
+    "troubleshooting/",
     "README.md"
   ],
   "scripts": {

package/troubleshooting/README.md

@@ -0,0 +1,366 @@
+# 故障排除案例库
+
+> 基于真实项目经验总结的问题解决方案，通过 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 (11 个案例)
+
+| 案例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 |
+| 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.14.0  
+**案例总数**: 12 个  
+**最后更新**: 2026-01-17
+
+---
+
+## 📖 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

package/troubleshooting/USAGE_GUIDE.md

@@ -0,0 +1,289 @@
+# 故障排除案例库使用指南
+
+> 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