mta-mcp 1.0.0

package/troubleshooting/flutter/sketch-/345/210/227/350/241/250item/345/214/272/345/237/237.md

@@ -0,0 +1,212 @@
+# Sketch 列表 Item 区域高度不一致问题
+
+> **问题标签**: `sketch`, `list`, `menu`, `item`, `padding`, `divider`  
+> **框架**: Flutter  
+> **严重程度**: 中等（导致列表布局细节偏差）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "第一个/最后一个 item 高度不对"
+- "列表 padding 不均匀"
+- "divider 位置偏移"
+- "底部/顶部留白太多/太少"
+
+### 问题特征
+- [ ] 列表首尾 item 与中间 item 高度不同
+- [ ] 使用统一 padding 导致视觉不平衡
+- [ ] 忽略 divider 在高度计算中的影响
+- [ ] 假设所有 item 高度相同
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：设计稿中列表的首个和末尾 item 通常有不同的 padding，以平衡与容器边缘的视觉关系。
+
+### 典型 Sketch 测量结果
+
+```
+Menu Card_background: 350px
+
+Divider 位置:
+- Divider 1: y=63
+- Divider 2: y=119  
+- Divider 3: y=175
+- Divider 4: y=231
+- Divider 5: y=287
+
+区域高度计算:
+- Item 1: 0 → 63 = 63px
+- Item 2: 63 → 119 = 56px
+- Item 3: 119 → 175 = 56px
+- Item 4: 175 → 231 = 56px
+- Item 5: 231 → 287 = 56px
+- Item 6: 287 → 350 = 63px
+```
+
+**结论**: 首尾 item 63px，中间 item 56px，**不是**统一高度！
+
+---
+
+## ❌ 常见错误
+
+```dart
+// ❌ 错误: 统一 padding
+Padding(
+  padding: const EdgeInsets.symmetric(vertical: 10, horizontal: 16),
+  child: MenuItem(),
+)
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 1. 测量 Icon 精确位置
+
+```javascript
+// 测量所有 icon 的 y 坐标
+const icons = sketch.find('[name*="Icon BG"]', menuCard);
+icons.forEach(icon => {
+  if (icon.frame.height === 36) {
+    console.log(`${icon.name}: y=${icon.frame.y}`);
+  }
+});
+
+// 结果:
+// Item 1 Icon: y=20
+// Item 2 Icon: y=76
+// Item 3 Icon: y=132
+// ...
+```
+
+### 2. 计算每个 item 的 padding
+
+```
+Item 1 (区域 0→63):
+- region_start = 0
+- icon_y = 20 → top = 20
+- icon_bottom = 56
+- divider_y = 63 → bottom = 63 - 56 - 1 = 6
+- 验证: 20 + 36 + 6 + 1 = 63 ✅
+
+Item 2 (区域 64→119):
+- region_start = 64 (divider1 + 1)
+- icon_y = 76 → top = 76 - 64 = 12
+- icon_bottom = 112
+- divider_y = 119 → bottom = 119 - 112 - 1 = 6
+- 验证: 12 + 36 + 6 + 1 = 55... 
+
+等等，56 - 1(divider) = 55，但 12+36+6=54？
+让我重新计算：区域 = 56px 含 divider
+内容区 = 55px，12 + 36 + 7 = 55 ✅
+```
+
+### 3. Flutter 精确实现
+
+```dart
+Widget _buildMenuItem(int index, MenuItem item) {
+  // Sketch 测量 (背景层 350px):
+  // - Item 1: 区域 63px = top:20 + icon:36 + bottom:6 + divider:1
+  // - Item 2-5: 区域 56px = top:12 + icon:36 + bottom:7 + divider:1  
+  // - Item 6: 区域 63px = top:12 + icon:36 + bottom:15 (无 divider)
+  
+  final isFirst = index == 0;
+  final isLast = index == 5; // 6 个 item
+  
+  return Column(
+    mainAxisSize: MainAxisSize.min,
+    children: [
+      Padding(
+        padding: EdgeInsets.fromLTRB(
+          16,
+          isFirst ? 20 : 12,              // 首 item top 更大
+          16,
+          isFirst ? 6 : (isLast ? 15 : 7), // 尾 item bottom 更大
+        ),
+        child: Row(
+          children: [
+            Icon(size: 36),
+            SizedBox(width: 16),
+            Expanded(child: Text(item.title)),
+            ArrowIcon(),
+          ],
+        ),
+      ),
+      
+      // Divider (最后一个不需要)
+      if (!isLast)
+        Container(
+          margin: EdgeInsets.only(left: 68, right: 20),
+          height: 1,
+          color: Color(0x0F1C2B45),
+        ),
+    ],
+  );
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### 从 Sketch 测量计算 padding
+
+```
+top_padding = icon.y - region_start
+bottom_padding = region_end - icon.bottom - divider_height
+```
+
+其中:
+- `region_start` = 上一个 divider.y + 1 (首 item 为 0)
+- `region_end` = 当前 divider.y (尾 item 为 background.height)
+- `icon.bottom` = icon.y + icon.height
+- `divider_height` = 1 (尾 item 为 0)
+
+### 验证公式
+
+```
+区域高度 = top_padding + icon_height + bottom_padding + divider_height
+```
+
+---
+
+## 📊 真实案例数据
+
+### Profile Menu Card (350px)
+
+| Item | 区域 | Top | Icon | Bottom | Divider | 总计 |
+|------|------|-----|------|--------|---------|------|
+| 1 | 0→63 | 20 | 36 | 6 | 1 | 63 |
+| 2 | 63→119 | 12 | 36 | 7 | 1 | 56 |
+| 3 | 119→175 | 12 | 36 | 7 | 1 | 56 |
+| 4 | 175→231 | 12 | 36 | 7 | 1 | 56 |
+| 5 | 231→287 | 12 | 36 | 7 | 1 | 56 |
+| 6 | 287→350 | 12 | 36 | 15 | 0 | 63 |
+
+**总计**: 63 + 56×4 + 63 = 350px ✅
+
+---
+
+## ⚠️ 预防措施
+
+1. **不要假设统一高度**: 始终测量首、中、尾三种 item
+2. **测量 icon 实际 y 坐标**: 不要只看区域高度
+3. **区分有无 divider**: 尾 item 通常无 divider
+4. **使用背景层边界**: 不要用 Frame 高度
+
+---
+
+## 🔗 相关问题
+
+- [sketch-背景层高度.md](./sketch-背景层高度.md) - 背景层 vs Frame 高度
+- [layout-尺寸不匹配.md](./layout-尺寸不匹配.md) - 通用布局问题
+
+---
+
+**创建日期**: 2026-01-19  
+**最后更新**: 2026-01-19  
+**来源**: Profile 页面 Menu Item 布局调试实战

package/troubleshooting/flutter/sketch-/345/233/276/346/240/207/345/260/272/345/257/270.md

@@ -0,0 +1,135 @@
+# Sketch 图标尺寸提取问题
+
+> **问题标签**: `sketch`, `icon`, `size`, `group`, `shape`  
+> **框架**: Flutter  
+> **严重程度**: 中等（还原精度）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "图标尺寸与设计稿不符"
+- "设置了尺寸但没效果"
+- "Group 和 Shape 尺寸不一样"
+- "提取的尺寸是外层容器的"
+
+### 问题特征
+- [ ] 从 Sketch 提取了图标尺寸
+- [ ] 实际显示比预期大或小
+- [ ] Sketch 中图标有 Group 包裹
+- [ ] Group 尺寸与内部 Shape 尺寸不同
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 中图标通常有两层结构，外层 Group 用于布局定位，内层 Shape 才是实际视觉尺寸。
+
+```
+Sketch 图标结构:
+├─ Group "Tab Icon" (22x22)       ← 外层容器，用于布局
+│  └─ Shape "Icon_path" (14.67x14.67)  ← 内部实际图形
+```
+
+如果提取外层 Group 的尺寸，图标会比设计稿看起来大。
+
+---
+
+## ✅ 正确解决方案
+
+### 使用脚本提取内部 Shape 尺寸
+
+```javascript
+// Sketch 脚本：提取图标的内部实际尺寸
+const sketch = require('sketch');
+const document = sketch.getSelectedDocument();
+const page = document.selectedPage;
+
+function extractIconInternalSize(frameName) {
+  const frame = sketch.find(`[name="${frameName}"]`, page)[0];
+  if (!frame) return console.log('Frame not found');
+  
+  function traverse(layer, parentY = 0) {
+    const f = layer.frame;
+    const absY = parentY + f.y;
+    
+    if (layer.type === 'Group' && layer.name.includes('Icon')) {
+      console.log(`\n📦 ${layer.name} (外层 Group): ${f.width}x${f.height}`);
+      layer.layers?.forEach(child => {
+        if (child.type === 'Shape' || child.type === 'ShapePath') {
+          const cf = child.frame;
+          console.log(`  └─ ${child.name} (内部图形): ${cf.width.toFixed(1)}x${cf.height.toFixed(1)} ← 使用这个`);
+        }
+      });
+    }
+    if (layer.layers) layer.layers.forEach(child => traverse(child, absY));
+  }
+  traverse(frame);
+}
+
+extractIconInternalSize('Frame Name');
+```
+
+### 输出示例
+
+```
+📦 Tab Recipient Icon (外层 Group): 22x22
+  └─ Tab Recipient Icon_path_0 (内部图形): 14.7x14.7 ← 使用这个尺寸
+```
+
+### Flutter 中使用正确尺寸
+
+```dart
+// ✅ 使用内部图形的实际尺寸
+SvgPicture.asset(
+  'assets/icons/recipient.svg',
+  width: 15.0,  // 14.7 取整
+  height: 15.0,
+)
+
+// ❌ 错误：使用外层 Group 尺寸
+SvgPicture.asset(
+  'assets/icons/recipient.svg',
+  width: 22.0,  // 这是 Group 尺寸，图标会偏大
+  height: 22.0,
+)
+```
+
+---
+
+## 📝 验证检查清单
+
+1. **确认提取的是 Shape 尺寸**
+   - 不是 Group、Frame、Artboard 的尺寸
+   - 查看脚本输出中带 ← 标记的行
+
+2. **视觉对比验证**
+   - 在模拟器/设备上与设计稿截图对比
+   - 图标边缘应与设计稿完全重合
+
+3. **属性使用验证**
+   ```bash
+   # 搜索确认尺寸属性被使用
+   grep -n "iconSize" lib/widgets/my_widget.dart
+   ```
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整 Flutter 中的尺寸 | 如果基准就错了，调来调去 | 3-5 轮对话 |
+| 添加 transform scale | Hack 方案，难以精确 | 2-3 轮对话 |
+| 重新导出 SVG | 如果不知道问题在哪，重复错误 | 2-3 轮对话 |
+
+**最佳做法**：先用脚本确认正确尺寸，再修改代码
+
+---
+
+## 📁 适用场景
+
+- ✅ TabBar 图标
+- ✅ 按钮内图标
+- ✅ 任何从 Sketch 导出的图标

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 开发
+- ✅ 组件可配置化
+- ✅ 任何涉及属性传递的场景