mta-mcp 2.13.0 → 2.14.0

package/troubleshooting/flutter/sketch-/345/256/214/346/225/264/346/217/220/345/217/226.md

@@ -0,0 +1,201 @@
+# Sketch 设计稿样式不完整提取问题
+
+> **问题标签**: `sketch`, `design`, `extraction`, `incomplete`, `一次性提取`  
+> **框架**: Flutter  
+> **严重程度**: 高（导致多轮对话和返工）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "漏了xxx属性"
+- "渐变怎么还原"
+- "阴影参数是多少"
+- "这个图标是圆形的吗"
+- "设计稿上的圆角多大"
+
+### 问题特征
+- [ ] AI 每次只查询单个属性（颜色、尺寸、阴影等）
+- [ ] 需要多轮对话才能获取完整样式信息
+- [ ] 使用近似值代替精确值（如 Material Icons 代替 SVG）
+- [ ] 假设属性而非验证（假设是圆形、假设颜色相同等）
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：分散查询导致信息不完整，浪费时间。
+
+| 问题 | 表现 | 根因 |
+|------|------|------|
+| 属性读取不完整 | 漏读渐变、圆角、阴影参数 | 只读取部分属性 |
+| 假设而非验证 | 假设圆形/颜色/图标 | 未从设计稿验证 |
+| 使用近似值 | 用 Material Icons 代替 | 未导出原始 SVG |
+| 分散查询 | 多轮对话才获取完整信息 | 每次只查一个属性 |
+
+---
+
+## ✅ 正确解决方案
+
+### 强制执行：一次性完整提取脚本
+
+**在还原任何 UI 元素前，必须使用以下脚本一次性提取所有属性：**
+
+```javascript
+// Sketch 完整样式提取脚本 - 必须使用
+const sketch = require('sketch');
+const document = sketch.getSelectedDocument();
+const page = document.selectedPage;
+
+function extractFullStyle(layerName) {
+  const layer = sketch.find(`[name="${layerName}"]`, page)[0];
+  if (!layer) return console.log(`Layer "${layerName}" not found`);
+
+  console.log('=== 基本信息 ===');
+  console.log(`Name: ${layer.name} (${layer.type})`);
+  console.log(`Frame: ${layer.frame.width}x${layer.frame.height} @ (${layer.frame.x}, ${layer.frame.y})`);
+
+  const style = layer.style;
+
+  // 1. 填充（颜色/渐变）
+  console.log('=== 填充 ===');
+  if (style.fills?.length) {
+    style.fills.forEach((fill, i) => {
+      console.log(`Fill ${i}: Type=${fill.fillType}, Enabled=${fill.enabled}`);
+      if (fill.fillType === 'Color') {
+        console.log(`  Color: ${fill.color}`);
+      } else if (fill.fillType === 'Gradient') {
+        console.log(`  Gradient: ${fill.gradient.gradientType}`);
+        console.log(`  From: (${fill.gradient.from.x.toFixed(2)}, ${fill.gradient.from.y.toFixed(2)})`);
+        console.log(`  To: (${fill.gradient.to.x.toFixed(2)}, ${fill.gradient.to.y.toFixed(2)})`);
+        fill.gradient.stops.forEach((stop, j) => {
+          console.log(`  Stop ${j}: ${stop.color} @ ${stop.position}`);
+        });
+      }
+    });
+  } else {
+    console.log('No fills');
+  }
+
+  // 2. 边框
+  console.log('=== 边框 ===');
+  if (style.borders?.length) {
+    style.borders.forEach((border, i) => {
+      console.log(`Border ${i}: Color=${border.color}, Width=${border.thickness}, Position=${border.position}, Enabled=${border.enabled}`);
+    });
+  } else {
+    console.log('No borders');
+  }
+
+  // 3. 阴影
+  console.log('=== 阴影 ===');
+  if (style.shadows?.length) {
+    style.shadows.forEach((s, i) => {
+      console.log(`Shadow ${i}: Color=${s.color}, Offset=(${s.x}, ${s.y}), Blur=${s.blur}, Spread=${s.spread}`);
+    });
+  } else {
+    console.log('No shadows');
+  }
+
+  // 4. 内阴影
+  console.log('=== 内阴影 ===');
+  if (style.innerShadows?.length) {
+    style.innerShadows.forEach((s, i) => {
+      console.log(`InnerShadow ${i}: Color=${s.color}, Offset=(${s.x}, ${s.y}), Blur=${s.blur}, Spread=${s.spread}`);
+    });
+  } else {
+    console.log('No inner shadows');
+  }
+
+  // 5. 圆角
+  console.log('=== 圆角 ===');
+  if (layer.layers?.[0]?.points) {
+    const points = layer.layers[0].points;
+    const radii = points.map(p => p.cornerRadius);
+    const allSame = radii.every(r => r === radii[0]);
+    if (allSame) {
+      console.log(`CornerRadius: ${radii[0]} (all corners)`);
+    } else {
+      console.log(`CornerRadius: [${radii.join(', ')}] (TL, TR, BR, BL)`);
+    }
+  } else if (layer.points) {
+    const radii = layer.points.map(p => p.cornerRadius);
+    console.log(`CornerRadius: ${radii[0]}`);
+  } else {
+    console.log('No corner radius (circle or custom shape)');
+  }
+
+  // 6. 不透明度
+  console.log('=== 不透明度 ===');
+  console.log(`Opacity: ${style.opacity}`);
+
+  // 7. 子元素（如果是 Group）
+  if (layer.layers?.length) {
+    console.log('=== 子元素 ===');
+    layer.layers.forEach(child => {
+      console.log(`- ${child.name} (${child.type}): ${child.frame.width}x${child.frame.height}`);
+    });
+  }
+}
+
+// 使用示例
+extractFullStyle('Button Background');
+extractFullStyle('Icon');
+```
+
+### 图标导出：必须使用 SVG
+
+**禁止使用 Material Icons 或其他近似图标：**
+
+```javascript
+// 导出图标 SVG
+const sketch = require('sketch');
+const layer = sketch.find('[name="Icon Name"]', sketch.getSelectedDocument().selectedPage)[0];
+if (layer) {
+  const svg = sketch.export(layer, { formats: 'svg', output: false });
+  console.log(svg.toString());
+}
+```
+
+### 还原检查清单（强制）
+
+在还原任何 UI 元素前，必须确认以下所有属性：
+
+| 属性 | 检查项 | Flutter 对应 |
+|------|--------|--------------|
+| 尺寸 | width, height | `SizedBox(width:, height:)` |
+| 位置 | x, y | `Positioned(left:, top:)` |
+| 颜色/渐变 | fills[0] | `BoxDecoration(color:, gradient:)` |
+| 圆角 | cornerRadius | `BorderRadius.circular()` |
+| 边框 | borders | `Border.all()` |
+| 阴影 | shadows | `BoxShadow()` |
+| 透明度 | opacity | `Opacity(opacity:)` |
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 每次只查一个属性 | 需要多轮对话才能获取完整信息 | 5-10 轮 |
+| 假设是圆形 | 未验证 cornerRadius，可能是圆角矩形 | 2-3 轮 |
+| 使用 Material Icons | 与设计稿不完全一致 | 3-5 轮 |
+| 忽略渐变参数 | 只看到 from/to，未读取 stops | 2-4 轮 |
+
+---
+
+## 📁 适用场景
+
+- ✅ 从 Sketch 设计稿还原任何 UI 元素
+- ✅ 需要获取完整样式信息
+- ✅ 包含渐变、阴影、复杂圆角的设计
+- ✅ 图标还原（必须导出 SVG）
+
+---
+
+## 🔗 相关案例
+
+- [sketch-图标尺寸.md](./sketch-图标尺寸.md) - 图标尺寸提取错误
+- [svg-颜色异常.md](./svg-颜色异常.md) - SVG 颜色处理问题
+- [svg-未居中.md](./svg-未居中.md) - SVG 居中问题

package/troubleshooting/flutter/sketch-/345/261/236/346/200/247/346/234/252/344/275/277/347/224/250.md

@@ -0,0 +1,139 @@
+# 组件属性定义但未使用问题
+
+> **问题标签**: `property`, `unused`, `debug`, `widget`  
+> **框架**: Flutter  
+> **严重程度**: 高（功能无效）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "设置了属性但没效果"
+- "参数不生效"
+- "改了值但 UI 没变化"
+- "属性没有被使用"
+
+### 问题特征
+- [ ] 在组件类中定义了新属性
+- [ ] 修改属性值后 UI 没有变化
+- [ ] 没有编译错误
+- [ ] 运行正常但功能不符合预期
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：在类中定义了属性，但在 `build` 方法中没有实际使用该属性。
+
+```dart
+// ❌ 错误示例：定义了 iconSize 但没使用
+class MyIcon extends StatelessWidget {
+  const MyIcon({
+    super.key,
+    this.iconSize = 24.0, // 定义了属性
+  });
+  
+  final double iconSize; // 有这个字段
+  
+  @override
+  Widget build(BuildContext context) {
+    return Icon(
+      Icons.star,
+      size: 24.0, // ← 直接写死了！没用 iconSize
+    );
+  }
+}
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 1. 验证属性被使用
+
+```bash
+# 搜索属性在文件中的使用情况
+grep -n "iconSize" lib/widgets/my_icon.dart
+
+# 期望输出：
+# 5: this.iconSize = 24.0,   ← 定义
+# 8: final double iconSize;  ← 字段
+# 14: size: iconSize,        ← 使用 ✅
+```
+
+### 2. 正确使用属性
+
+```dart
+// ✅ 正确示例
+class MyIcon extends StatelessWidget {
+  const MyIcon({
+    super.key,
+    this.iconSize = 24.0,
+  });
+  
+  final double iconSize;
+  
+  @override
+  Widget build(BuildContext context) {
+    return Icon(
+      Icons.star,
+      size: iconSize, // ← 使用属性
+    );
+  }
+}
+```
+
+### 3. 添加属性后的验证清单
+
+每次添加新属性后必须检查：
+
+- [ ] 属性在 constructor 中定义
+- [ ] 属性有对应的 final 字段
+- [ ] 属性在 build 方法中被引用
+- [ ] 修改属性值后 UI 确实变化
+
+---
+
+## 📝 快速调试方法
+
+```dart
+// 临时添加打印语句验证
+@override
+Widget build(BuildContext context) {
+  print('🔍 iconSize: $iconSize'); // 确认值正确
+  return Icon(
+    Icons.star,
+    size: iconSize,
+  );
+}
+```
+
+```dart
+// 或使用断言
+@override
+Widget build(BuildContext context) {
+  assert(iconSize > 0, 'iconSize must be positive');
+  // ...
+}
+```
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整属性默认值 | 如果没使用，改默认值也没用 | 1-2 轮对话 |
+| 添加更多属性 | 同样的问题会重复 | 2-3 轮对话 |
+| 检查父组件传值 | 如果子组件没用，传什么都一样 | 1-2 轮对话 |
+
+**最佳做法**：先 grep 确认属性被使用，再调试其他问题
+
+---
+
+## 📁 适用场景
+
+- ✅ 自定义 Widget 开发
+- ✅ 组件可配置化
+- ✅ 任何涉及属性传递的场景

package/troubleshooting/flutter/svg-/346/234/252/345/261/205/344/270/255.md

@@ -0,0 +1,120 @@
+# Flutter SVG 未居中问题
+
+> **问题标签**: `svg`, `viewbox`, `center`, `alignment`, `icon`  
+> **框架**: Flutter  
+> **严重程度**: 低（布局问题）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "SVG 图标没有居中"
+- "图标位置偏了"
+- "需要用 Center 包裹"
+- "viewBox 不对"
+
+### 问题特征
+- [ ] SVG 显示位置与预期不符
+- [ ] 需要额外的 Center/Align 组件包裹
+- [ ] SVG viewBox 尺寸与使用尺寸不匹配
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 导出 SVG 时，viewBox 可能是图形的最小边界框，而非设计稿中的容器尺寸。
+
+```xml
+<!-- ❌ 问题：viewBox 是最小边界框 -->
+<!-- 箭头图标实际尺寸是 6x3，但需要放在 12x12 的容器中 -->
+<svg viewBox="0 0 6 3">
+  <path d="..."/>
+</svg>
+```
+
+```dart
+// 放在 12x12 容器中，图标会被拉伸或需要额外居中处理
+SvgPicture.asset('arrow.svg', width: 12, height: 12);
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 方案1：导出时保留完整 viewBox（推荐）
+
+在 Sketch 中导出 SVG 时，选择图标所在的外层容器（Group），而非内部的形状：
+
+```javascript
+// Sketch 脚本：导出完整容器的 SVG
+const sketch = require('sketch');
+const layer = sketch.find('[name="Icon Container"]')[0]; // 选择外层 Group
+const svg = sketch.export(layer, { formats: 'svg', output: false });
+```
+
+```xml
+<!-- ✅ 正确：viewBox 包含完整容器空间 -->
+<svg viewBox="0 0 12 12">
+  <!-- 箭头在容器中的正确位置 -->
+  <path transform="translate(3, 4.5)" d="..."/>
+</svg>
+```
+
+### 方案2：Flutter 中手动设置对齐
+
+```dart
+// 如果 SVG 无法重新导出，在 Flutter 中处理
+SizedBox(
+  width: 12,
+  height: 12,
+  child: Center(
+    child: SvgPicture.asset(
+      'arrow.svg',
+      width: 6,  // 使用 SVG 实际尺寸
+      height: 3,
+    ),
+  ),
+)
+```
+
+---
+
+## 📝 Sketch 图标导出检查清单
+
+1. **确认选择正确的图层**
+   - 选择外层 Group/Frame，而非内部 Shape
+   - 外层应该是设计稿中图标的"点击区域"尺寸
+
+2. **验证导出的 viewBox**
+   ```bash
+   # 检查 SVG 文件的 viewBox
+   head -3 assets/icons/arrow.svg
+   # 应该看到 viewBox="0 0 12 12" 而非 viewBox="0 0 6 3"
+   ```
+
+3. **检查 Flutter 中的使用**
+   ```dart
+   // 宽高应该与 viewBox 匹配
+   SvgPicture.asset('arrow.svg', width: 12, height: 12);
+   ```
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 用 Center 包裹 | 治标不治本，每个图标都要处理 | 1 轮对话/图标 |
+| 调整 alignment 属性 | SvgPicture 的 alignment 可能不生效 | 1-2 轮对话 |
+| 修改 SVG 的 transform | 需要计算精确偏移量 | 2-3 轮对话 |
+
+**最佳做法**：从源头修复，重新导出正确 viewBox 的 SVG
+
+---
+
+## 📁 适用场景
+
+- ✅ 小尺寸图标（箭头、点击指示器等）
+- ✅ 需要放在固定容器中的图标
+- ✅ TabBar、按钮中的图标

package/troubleshooting/flutter/svg-/351/242/234/350/211/262/345/274/202/345/270/270.md

@@ -0,0 +1,117 @@
+# Flutter SVG 颜色异常问题
+
+> **问题标签**: `svg`, `color`, `colorfilter`, `transparency`, `icon`  
+> **框架**: Flutter  
+> **严重程度**: 中等（视觉问题）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "SVG 颜色比设计稿浅"
+- "图标颜色不对"
+- "透明度丢失"
+- "图标颜色变淡了"
+
+### 问题特征
+- [ ] 使用 flutter_svg 加载 SVG 图标
+- [ ] 使用了 ColorFilter.mode
+- [ ] SVG 原本有透明度（如 #1C2B45B3）
+- [ ] 实际显示颜色比设计稿浅
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：`ColorFilter.mode(color, BlendMode.srcIn)` 会完全覆盖 SVG 的原有颜色和透明度。
+
+```dart
+// Sketch 设计稿：#1C2B45B3（70% 透明度的深蓝色）
+// SVG 文件中：fill="#1C2B45" fill-opacity="0.7"
+
+// ❌ 使用 ColorFilter 后：
+SvgPicture.asset(
+  'icon.svg',
+  colorFilter: ColorFilter.mode(
+    Color(0xFF1C2B45), // 只有颜色，没有透明度
+    BlendMode.srcIn,   // 完全覆盖原有样式
+  ),
+)
+// 结果：显示为 100% 的深蓝色，比设计稿深/浅
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 方案1：保留 SVG 原有样式（推荐）
+
+```dart
+// ✅ 不使用 colorFilter，保留 SVG 原有颜色和透明度
+SvgPicture.asset(
+  'assets/icons/dropdown_arrow.svg',
+  width: 12,
+  height: 12,
+  // 不传 colorFilter
+)
+```
+
+### 方案2：需要动态颜色时，包含透明度
+
+```dart
+// ✅ 如果必须使用 colorFilter，颜色要包含 alpha
+SvgPicture.asset(
+  'icon.svg',
+  colorFilter: customColor != null
+      ? ColorFilter.mode(
+          customColor.withValues(alpha: 0.7), // 保留透明度
+          BlendMode.srcIn,
+        )
+      : null, // 无自定义颜色时保留原样式
+)
+```
+
+### 方案3：SVG 导出时保留透明度信息
+
+```xml
+<!-- Sketch 导出 SVG 时确保保留 fill-opacity -->
+<path fill="#1C2B45" fill-opacity="0.7" d="..."/>
+```
+
+---
+
+## 📝 Sketch 颜色透明度转换
+
+Sketch 颜色格式：`#RRGGBBAA`（最后两位是透明度）
+
+| Sketch | Flutter | 说明 |
+|--------|---------|------|
+| #1C2B45B3 | Color(0xB31C2B45) | 70% 透明度 |
+| #00000080 | Color(0x80000000) | 50% 透明度 |
+| #FFFFFF26 | Color(0x26FFFFFF) | 15% 透明度 |
+
+**常用透明度对照表**：
+- 100% = FF
+- 70% = B3
+- 50% = 80
+- 30% = 4D
+- 15% = 26
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整 SVG 本身的颜色 | ColorFilter 会覆盖 | 1-2 轮对话 |
+| 修改 BlendMode | srcIn 是正确的混合模式 | 1-2 轮对话 |
+| 用 Opacity widget 包裹 | 影响整个图标，不是颜色透明度 | 1 轮对话 |
+
+---
+
+## 📁 适用场景
+
+- ✅ 设计稿中有透明度的图标
+- ✅ TabBar 图标
+- ✅ 任何使用 flutter_svg 的场景

package/troubleshooting/flutter/tabbar-/345/212/250/347/224/273/345/220/214/346/255/245.md

@@ -0,0 +1,107 @@
+# Flutter TabBar 动画同步问题
+
+> **问题标签**: `tabbar`, `animation`, `neumorphism`, `color`, `sync`  
+> **框架**: Flutter  
+> **严重程度**: 中等（视觉体验）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "颜色变化太快"
+- "动画不同步"
+- "背景块还没移动图标就变色了"
+- "选中/未选中切换不流畅"
+
+### 问题特征
+- [ ] TabBar 有背景滑块动画
+- [ ] 图标/文字颜色需要随选中状态变化
+- [ ] 背景块使用 AnimatedPositioned/AnimatedContainer
+- [ ] 颜色使用 setState 直接切换
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：背景块使用了动画（如 AnimatedPositioned），但颜色切换使用 `setState` 立即更新，导致颜色变化比背景块移动快。
+
+```dart
+// ❌ 错误：颜色立即变化
+setState(() {
+  selectedIndex = newIndex; // 颜色立即切换
+});
+// 同时 AnimatedPositioned 的背景块需要 300ms 移动
+// 结果：图标已经变白，背景还没移到位
+```
+
+---
+
+## ✅ 正确解决方案
+
+**使用 TweenAnimationBuilder 同步所有动画**
+
+```dart
+const animDuration = Duration(milliseconds: 300);
+const animCurve = Curves.easeInOut;
+
+// 背景块动画
+AnimatedPositioned(
+  duration: animDuration,
+  curve: animCurve,
+  left: targetLeft,
+  child: greenBackground,
+)
+
+// 颜色动画（同步）
+TweenAnimationBuilder<Color?>(
+  duration: animDuration,
+  curve: animCurve,
+  tween: ColorTween(
+    begin: isSelected ? unselectedColor : selectedColor,
+    end: isSelected ? selectedColor : unselectedColor,
+  ),
+  builder: (_, color, child) => Icon(
+    icon,
+    color: color,
+    size: iconSize,
+  ),
+)
+
+// 布局动画（同步）
+AnimatedContainer(
+  duration: animDuration,
+  curve: animCurve,
+  height: isSelected ? 44.0 : 22.0,
+  child: icon,
+)
+```
+
+### 关键要点
+1. **统一动画参数**：所有动画使用相同的 `duration` 和 `curve`
+2. **颜色也要动画**：使用 `TweenAnimationBuilder<Color?>` 而非直接 setState
+3. **布局也要动画**：如果选中/未选中的布局不同，也要使用 AnimatedContainer
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整动画时长 | 不解决同步问题 | 1-2 轮对话 |
+| 使用 AnimatedSwitcher | 会导致整个组件重建 | 2-3 轮对话 |
+| 添加延迟切换颜色 | Hack 方案，难以精确匹配 | 2-3 轮对话 |
+
+---
+
+## 📁 适用场景
+
+- ✅ 底部导航栏 TabBar
+- ✅ 分段控制器 SegmentedControl
+- ✅ 任何需要"选中滑块 + 颜色变化"的组件
+
+---
+
+## 🔗 相关案例
+
+- [clip-阴影裁剪](./clip-阴影裁剪.md) - 滑块阴影被裁剪问题