mta-mcp 2.17.0 → 3.0.0

package/troubleshooting/USAGE_GUIDE.md

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

package/troubleshooting/flutter/clip-/351/230/264/345/275/261/350/243/201/345/211/252.md

@@ -1,244 +0,0 @@
-# Flutter clipBehavior 阴影裁剪问题
-
-> **问题标签**: `clip`, `shadow`, `layout`, `overflow`, `neumorphism`  
-> **问题类型**: 布局裁剪  
-> **框架**: Flutter  
-> **严重程度**: 中等（视觉问题）
-
----
-
-## 🔍 问题识别
-
-### 自动检测特征
-
-```dart
-// 代码模式匹配 - 嵌套容器带阴影
-Container(
-  // 外层容器有 padding
-  padding: EdgeInsets.all(6),
-  child: Container(
-    decoration: BoxDecoration(
-      boxShadow: [...], // 内层有阴影
-    ),
-  ),
-)
-```
-
-### 用户描述关键词
-- "阴影模糊一片"
-- "阴影没有清晰边界"
-- "阴影被裁剪了"
-- "新拟态效果不清晰"
-- "选中项看不出凸起效果"
-
-### 问题特征
-- [ ] 新拟态选中项阴影看起来"模糊一片"
-- [ ] 阴影没有清晰的边界
-- [ ] 选中项与背景融为一体
-- [ ] 类似效果的其他组件显示正常
-
----
-
-## ❌ 常见错误排查路线（避免重复）
-
-| 尝试方向 | 为什么无效 | 浪费时间 |
-|----------|-----------|---------|
-| 调整阴影参数 (blur/offset) | 问题不在阴影本身 | 2-3 轮对话 |
-| 嵌套两层 Container (外层阴影/内层渐变) | 阴影仍在裁剪区域内 | 2-3 轮对话 |
-| 添加白色边框产生锐利边缘 | 边框过于明显，产生分层感 | 1-2 轮对话 |
-| 使用叠加渐变模拟内阴影 | 效果不自然 | 1-2 轮对话 |
-| 只设置 Stack 的 clipBehavior | 外层 Container 仍会裁剪 | 1 轮对话 |
-
-**总计浪费**: 7-11 轮对话
-
----
-
-## ✅ 正确解决方案
-
-### 核心原理
-
-**问题根源**：Flutter 的 `Container`、`Padding`、`ClipRRect` 等组件**默认会裁剪**超出边界的内容，包括 `BoxShadow` 阴影。
-
-```
-问题结构:
-Container (默认 clipBehavior: Clip.hardEdge)
-└── Padding (padding: 6)
-    └── Container
-        └── 带阴影的滑块  ← 阴影被最外层 Container 裁剪！
-```
-
-### 解决步骤
-
-#### 1. 设置 clipBehavior: Clip.none
-
-```dart
-Container(
-  clipBehavior: Clip.none, // ← 关键！允许内容溢出
-  decoration: BoxDecoration(
-    color: config.backgroundColor,
-    borderRadius: BorderRadius.circular(config.borderRadius),
-  ),
-  child: Stack(
-    clipBehavior: Clip.none, // ← Stack 也要设置
-    children: [
-      // ...
-    ],
-  ),
-)
-```
-
-#### 2. 重构布局结构
-
-**错误的结构**（会裁剪）：
-```dart
-Container(
-  padding: EdgeInsets.all(6), // padding 会导致裁剪
-  child: Stack(
-    children: [
-      Container(boxShadow: [...]), // 阴影被外层裁剪
-    ],
-  ),
-)
-```
-
-**正确的结构**（不裁剪）：
-```dart
-Container(
-  clipBehavior: Clip.none,
-  child: Stack(
-    clipBehavior: Clip.none,
-    children: [
-      Positioned( // 使用 Positioned 代替 padding
-        left: 6,
-        top: 6,
-        bottom: 6,
-        right: 6,
-        child: Container(boxShadow: [...]),
-      ),
-    ],
-  ),
-)
-```
-
-#### 3. 完整示例
-
-```dart
-@override
-Widget build(BuildContext context) {
-  final config = _getConfig();
-  final selectedIndex = items.indexWhere((item) => item.value == selectedValue);
-  final innerPadding = padding ?? const EdgeInsets.all(6);
-
-  return LayoutBuilder(
-    builder: (context, outerConstraints) {
-      final totalWidth = outerConstraints.maxWidth;
-      final innerWidth = totalWidth - innerPadding.horizontal;
-      final itemWidth = innerWidth / items.length;
-
-      return Container(
-        height: height,
-        clipBehavior: Clip.none, // 关键点1：允许溢出
-        decoration: BoxDecoration(
-          color: config.backgroundColor,
-          borderRadius: BorderRadius.circular(config.borderRadius),
-          boxShadow: config.shadow,
-        ),
-        child: Stack(
-          clipBehavior: Clip.none, // 关键点2：Stack 也允许溢出
-          children: [
-            // 滑动背景 - 使用 Positioned 精确定位
-            if (selectedIndex != -1)
-              Positioned(
-                left: innerPadding.left + (itemWidth * selectedIndex),
-                top: innerPadding.top,
-                bottom: innerPadding.bottom,
-                width: itemWidth,
-                child: AnimatedContainer(
-                  duration: $d.fast,
-                  curve: Curves.easeInOut,
-                  decoration: BoxDecoration(
-                    gradient: config.selectedGradient,
-                    borderRadius: BorderRadius.circular(12),
-                    boxShadow: config.selectedShadow, // 阴影在这里
-                  ),
-                ),
-              ),
-
-            // 文本层 - 使用 Padding 而非容器的 padding
-            Padding(
-              padding: innerPadding,
-              child: Row(
-                children: items.map((item) {
-                  return Expanded(
-                    child: GestureDetector(
-                      onTap: () => onChanged(item.value),
-                      child: Container(
-                        alignment: Alignment.center,
-                        child: Text(item.label, ...),
-                      ),
-                    ),
-                  );
-                }).toList(),
-              ),
-            ),
-          ],
-        ),
-      );
-    },
-  );
-}
-```
-
----
-
-## 📋 关键改动点
-
-### 1. clipBehavior 设置
-- ✅ Container: `clipBehavior: Clip.none`
-- ✅ Stack: `clipBehavior: Clip.none`
-- ✅ 所有可能裁剪的父组件都要设置
-
-### 2. 布局方式
-- ❌ Container 的 padding 属性
-- ✅ Positioned 精确定位
-- ✅ Padding widget 包裹内容
-
-### 3. 使用 LayoutBuilder
-提前计算尺寸，避免布局错误：
-```dart
-LayoutBuilder(
-  builder: (context, constraints) {
-    final totalWidth = constraints.maxWidth;
-    final innerWidth = totalWidth - padding.horizontal;
-    final itemWidth = innerWidth / items.length;
-    // ...
-  },
-)
-```
-
----
-
-## 💡 clipBehavior 值说明
-
-| 值 | 行为 | 性能 | 使用场景 |
-|----|------|------|---------|
-| `Clip.none` | 不裁剪，允许溢出 | 最好 | **需要显示阴影** |
-| `Clip.hardEdge` | 硬边裁剪（默认） | 好 | 一般容器 |
-| `Clip.antiAlias` | 抗锯齿裁剪 | 中 | 圆角需要平滑 |
-| `Clip.antiAliasWithSaveLayer` | 最高质量裁剪 | 差 | 尽量避免 |
-
-**推荐**：需要阴影时使用 `Clip.none`，其他情况保持默认。
-
----
-
-## 🔗 相关案例
-
-- [shadow-透出问题](./shadow-透出问题.md) - 另一个阴影相关问题
-- [layout-尺寸不匹配](./layout-尺寸不匹配.md) - 使用 Positioned 精确布局
-
----
-
-**来源**: my_flutter 项目实战经验  
-**创建日期**: 2025-12-31  
-**最后验证**: 2026-01-16  
-**节省时间**: 7-11 轮对话