mta-mcp 2.16.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mta-mcp",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "MTA - 智能项目分析与编码规范管理 MCP 服务器",
   "type": "module",
   "main": "./dist/index.js",

package/troubleshooting/README.md

@@ -104,7 +104,7 @@ list_troubleshooting_cases({ framework: "flutter" })
 
 ## 📚 案例清单
 
-### Flutter (11 个案例)
+### Flutter (13 个案例)
 
 | 案例ID | 问题类型 | 关键词 |
 |--------|----------|--------|
@@ -118,6 +118,8 @@ list_troubleshooting_cases({ framework: "flutter" })
 | 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 个案例)
@@ -194,9 +196,9 @@ list_troubleshooting_cases({ framework: "flutter" })
 
 ---
 
-**版本**: v2.14.0  
-**案例总数**: 12 个  
-**最后更新**: 2026-01-17
+**版本**: v2.15.0  
+**案例总数**: 14 个  
+**最后更新**: 2026-01-19
 
 ---
 

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-/350/203/214/346/231/257/345/261/202/351/253/230/345/272/246.md

@@ -0,0 +1,264 @@
+# Sketch Frame 与 Background 层高度差异问题
+
+> **问题标签**: `sketch`, `frame`, `background`, `height`, `_background`, `_bg`  
+> **框架**: Flutter  
+> **严重程度**: 高（导致布局错位和多轮返工）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "间距不对"
+- "高度算错了"
+- "内边距有问题"
+- "最后一个 item 高度不对"
+- "卡片高度不匹配"
+
+### 问题特征
+- [ ] 计算的间距与设计稿视觉效果不符
+- [ ] 使用 Frame 高度计算，但结果总是差几像素
+- [ ] Menu/List 的第一个或最后一个 item 高度异常
+- [ ] 多个卡片之间的 gap 计算错误
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 的 Frame（组/画板）高度与其内部 `_background` 或 `_bg` 层高度可能不同。
+
+### Sketch 层级结构示例
+
+```
+Menu Card (Frame)         ← height: 336px ❌ 错误值
+├── Menu Card_background  ← height: 350px ✅ 正确值
+├── Menu Item 1
+├── Divider 1
+├── Menu Item 2
+...
+
+Warning Card (Frame)      ← height: 100px ❌ 错误值
+├── Warning Card_bg       ← height: 127px ✅ 正确值
+├── Warning Text
+├── Button
+```
+
+| 元素 | Frame 高度 | _background 高度 | 差异 |
+|------|------------|------------------|------|
+| Menu Card | 336px | 350px | +14px |
+| Warning Card | 100px | 127px | +27px |
+
+### 为什么会这样？
+
+1. **Auto Layout**: Frame 可能使用 Hug Contents 或固定高度
+2. **阴影/装饰**: _background 层包含了内边距、阴影区域
+3. **Padding 内含**: 背景层可能比 Frame 更大以提供视觉边距
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 使用 Frame 高度计算 gap | 背景层实际更大 | 3-5 轮对话 |
+| 反复调整 padding | 不知道正确的参考值 | 4-6 轮对话 |
+| 假设最后 item 与其他相同 | 底部 padding 通常不同 | 2-3 轮对话 |
+| 只测量 divider 位置 | 忽略了背景层边界 | 2-3 轮对话 |
+
+**总计浪费**: 10-15 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 解决步骤
+
+#### 1. 必须同时测量 Frame 和 _background 层
+
+```javascript
+// Sketch 测量脚本 - 比较 Frame 与背景层高度
+const sketch = require('sketch');
+const doc = sketch.getSelectedDocument();
+const page = doc.selectedPage;
+const target = sketch.find('[name="Profile Page"]', page)[0]; // 替换为目标
+
+function measureBackgroundLayers(container) {
+  const results = {};
+  
+  sketch.find('*', container).forEach(layer => {
+    const name = layer.name;
+    
+    // 查找 Frame 和对应的 _background/_bg 层
+    if (name.includes('Card') || name.includes('Panel')) {
+      results[name] = {
+        type: layer.type,
+        frameHeight: layer.frame.height,
+        y: layer.frame.y
+      };
+    }
+    
+    // 单独记录 _background 和 _bg 层
+    if (name.includes('_background') || name.includes('_bg')) {
+      results[name] = {
+        type: layer.type,
+        height: layer.frame.height,
+        y: layer.frame.y
+      };
+    }
+  });
+  
+  console.log(JSON.stringify(results, null, 2));
+}
+
+measureBackgroundLayers(target);
+```
+
+#### 2. 使用 _background 层高度计算布局
+
+```dart
+// ❌ 错误: 使用 Frame 高度
+const warningCardHeight = 100; // Frame 高度
+const menuCardY = 274;
+const gap = menuCardY - (warningCardY + warningCardHeight);
+// gap = 274 - (130 + 100) = 44px ❌
+
+// ✅ 正确: 使用 _background 层高度
+const warningCardHeight = 127; // _bg 层高度
+const gap = menuCardY - (warningCardY + warningCardHeight);
+// gap = 274 - (130 + 127) = 17px ✅
+```
+
+#### 3. 区分列表首尾 item 的 padding
+
+Menu/List 类组件中，首尾 item 通常与背景边缘有特殊间距：
+
+```javascript
+// 测量 divider 位置和背景层边界
+const dividers = sketch.find('[name*="Divider"]', menuCard);
+const background = sketch.find('[name*="_background"]', menuCard)[0];
+
+dividers.forEach(d => {
+  console.log(`${d.name}: y=${d.frame.y}`);
+});
+console.log(`Background height: ${background.frame.height}`);
+
+// 计算每个区域高度
+// Item 1: 0 → divider1.y
+// Item 2-N-1: divider[i-1].y → divider[i].y  
+// Item N: divider[N-1].y + 1 → background.height
+```
+
+#### 4. Flutter 实现：区分首尾 item
+
+```dart
+Widget _buildMenuItem(int index, MenuItem item) {
+  // Sketch 精确测量 (Menu Card_background = 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)
+  
+  return Padding(
+    padding: EdgeInsets.fromLTRB(
+      16,
+      index == 0 ? 20 : 12,           // 首 item top 更大
+      16,
+      index == 0 ? 6 : (index == 5 ? 15 : 7), // 尾 item bottom 更大
+    ),
+    child: Row(...),
+  );
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### 卡片间距计算
+
+```
+实际 gap = 下一卡片.y - (当前卡片.y + 当前卡片._background.height)
+```
+
+### 列表 item 区域计算
+
+```
+区域[0] = divider[0].y                           // 首 item
+区域[i] = divider[i].y - divider[i-1].y          // 中间 items (含 divider)
+区域[N] = background.height - divider[N-1].y - 1 // 尾 item (无 divider)
+```
+
+### Icon 垂直 padding 计算
+
+```
+top_padding = icon.y - region_start
+bottom_padding = region_end - (icon.y + icon.height) - divider_height
+```
+
+---
+
+## ⚠️ 预防措施
+
+### 提取 Sketch 时的检查清单
+
+- [ ] 是否同时读取了 Frame 高度和 _background/_bg 层高度？
+- [ ] 两者是否相同？如果不同，使用哪个？
+- [ ] 卡片之间的 gap 是否基于视觉边界（_background）计算？
+- [ ] 列表的首尾 item 是否有特殊的 padding？
+
+### 命名约定识别
+
+| 后缀 | 含义 | 使用场景 |
+|------|------|----------|
+| `_background` | 完整背景层 | 用于计算实际高度 |
+| `_bg` | 简化背景层 | 同上 |
+| `_shadow` | 阴影层 | 可能影响视觉边界 |
+| `_border` | 边框层 | 不影响高度计算 |
+
+---
+
+## 📊 真实案例
+
+### 案例: Profile 页面卡片间距
+
+**问题**: Warning Card 到 Menu Card 的间距应该是 17px，但计算得到 44px
+
+**错误分析**:
+```
+Menu Card.y = 274
+Warning Card.y = 130
+Warning Card Frame.height = 100  ← 使用了错误的值
+
+gap = 274 - (130 + 100) = 44px ❌
+```
+
+**正确分析**:
+```
+Menu Card.y = 274
+Warning Card.y = 130  
+Warning Card_bg.height = 127  ← 使用 _bg 层高度
+
+gap = 274 - (130 + 127) = 17px ✅
+```
+
+**修复代码**:
+```dart
+// 修改前
+SizedBox(height: 44),
+
+// 修改后
+SizedBox(height: 17),
+```
+
+---
+
+## 🔗 相关问题
+
+- [layout-尺寸不匹配.md](./layout-尺寸不匹配.md) - 通用布局问题
+- [sketch-完整提取.md](./sketch-完整提取.md) - 完整提取脚本
+- [sketch-图标尺寸.md](./sketch-图标尺寸.md) - SVG 尺寸问题
+
+---
+
+**创建日期**: 2026-01-19  
+**最后更新**: 2026-01-19  
+**来源**: Profile 页面 Menu Card 布局调试实战