mta-mcp 2.17.0 → 3.0.0

package/common/typescript-strict.md

@@ -1,186 +0,0 @@
-# TypeScript 严格模式指南
-
-适用于所有需要高质量类型安全的 TypeScript 项目
-
-## 🎯 核心原则
-
-1. **零 any**: 绝不使用 `any` 类型，使用 `unknown` 或具体类型
-2. **严格空检查**: 启用 `strictNullChecks`，明确处理 `null`/`undefined`
-3. **完整类型定义**: 所有函数参数、返回值、变量都有明确类型
-4. **类型推断优先**: 让 TypeScript 推断简单类型，复杂类型显式声明
-
-## 📝 tsconfig.json 配置
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "strictBindCallApply": true,
-    "strictPropertyInitialization": true,
-    "noImplicitThis": true,
-    "alwaysStrict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true
-  }
-}
-```
-
-## ✅ 最佳实践
-
-### 类型定义
-```typescript
-// ✅ 好
-interface User {
-  id: number
-  name: string
-  email?: string  // 可选属性
-}
-
-function getUser(id: number): Promise<User | null> {
-  // ...
-}
-
-// ❌ 坏
-function getUser(id: any): any {
-  // ...
-}
-```
-
-### 空值处理
-```typescript
-// ✅ 好
-const user: User | null = await getUser(1)
-if (user) {
-  console.log(user.name)
-}
-
-// 或使用可选链
-console.log(user?.name)
-
-// ❌ 坏
-const user = await getUser(1)
-console.log(user.name)  // 可能报错
-```
-
-### 联合类型
-```typescript
-// ✅ 好
-type Status = 'pending' | 'success' | 'error'
-
-function handleStatus(status: Status) {
-  switch (status) {
-    case 'pending': return 'Loading...'
-    case 'success': return 'Done!'
-    case 'error': return 'Failed!'
-  }
-}
-
-// ❌ 坏
-function handleStatus(status: string) {
-  // 失去类型约束
-}
-```
-
-### 泛型使用
-```typescript
-// ✅ 好
-function fetchData<T>(url: string): Promise<T> {
-  return fetch(url).then(res => res.json())
-}
-
-interface Product {
-  id: number
-  name: string
-}
-
-const products = await fetchData<Product[]>('/api/products')
-
-// ❌ 坏
-function fetchData(url: string): Promise<any> {
-  return fetch(url).then(res => res.json())
-}
-```
-
-## ⚠️ 禁止模式
-
-- ❌ `any` 类型
-- ❌ 类型断言 `as any`
-- ❌ `@ts-ignore` / `@ts-nocheck`
-- ❌ 隐式 any (`noImplicitAny: false`)
-- ❌ 非空断言 `!` (除非确定安全)
-
-## 📋 代码审查清单
-
-- [ ] 所有函数有明确的参数类型和返回值类型
-- [ ] 没有使用 `any` 类型
-- [ ] 正确处理可能为 `null`/`undefined` 的值
-- [ ] 使用联合类型而非宽泛的 `string`/`number`
-- [ ] 复杂对象有接口定义
-- [ ] 泛型使用恰当
-
-## 🔧 常见场景
-
-### API 响应处理
-```typescript
-interface ApiResponse<T> {
-  success: boolean
-  data?: T
-  error?: string
-}
-
-async function callApi<T>(endpoint: string): Promise<ApiResponse<T>> {
-  try {
-    const response = await fetch(endpoint)
-    const data = await response.json()
-    return { success: true, data }
-  } catch (error) {
-    return { 
-      success: false, 
-      error: error instanceof Error ? error.message : 'Unknown error' 
-    }
-  }
-}
-```
-
-### 类型守卫
-```typescript
-function isUser(obj: unknown): obj is User {
-  return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    'id' in obj &&
-    'name' in obj
-  )
-}
-
-const data: unknown = await fetchData()
-if (isUser(data)) {
-  console.log(data.name)  // TypeScript 知道 data 是 User
-}
-```
-
----
-
-## ⚠️ 重要：配置文件管理
-
-### Copilot 配置 .gitignore
-
-**推荐做法：**将自动生成的 `.github/copilot-instructions.md` 添加到 `.gitignore`
-
-```gitignore
-# Copilot 配置(自动生成)
-.github/copilot-instructions.md
-```
-
-**适用项目：**
-- TypeScript 应用（React、Vue、Angular）
-- Node.js 后端服务
-- TypeScript 工具库
-- 所有使用 TypeScript 的项目
-
-**详细指南**: 参考 [Copilot .gitignore 通用指南](../docs/guides/COPILOT_GITIGNORE_GUIDE.md)

package/troubleshooting/README.md

@@ -1,368 +0,0 @@
-# 故障排除案例库
-
-> 基于真实项目经验总结的问题解决方案，通过 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 (13 个案例)
-
-| 案例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 |
-| 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