mta-mcp 3.10.0 → 3.11.0

package/agents/flutter.agent.md

@@ -1,7 +1,7 @@
 # Flutter 开发代理
 
 > 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
-> 版本: v3.8.0 | 最后更新: 2026-01-26
+> 版本: v4.0.0 | 最后更新: 2026-02-11
 
 ---
 
@@ -42,11 +42,129 @@
 | `siblingGaps` | 元素间距 | `SizedBox(height:)` |
 | `layoutIntent` | 布局方式 | `Column`/`Row`/`Center` |
 | `flutterHints` | 建议代码 | 直接参考 |
+| `iconContentBounds` | Icon 实际路径尺寸 | 渲染用 contentSize，占位用 containerSize |
+| `tagStyle` | Tag/标签容器样式 | background, padding, cornerRadius |
+| `siblingIconAlignment` | 同行 Icon 对齐 | 统一 SizedBox 插槽尺寸 |
 
 **禁止**：未测量就凭感觉还原、硬编码尺寸、忽略 layoutIntent
 
 ---
 
+## 🔴 设计稿还原五大陷阱（最高优先级）
+
+> 以下陷阱基于真实项目多轮修复总结，每条都曾导致 2-5 轮无效对话
+
+### 陷阱 1：Icon Group 尺寸 ≠ 视觉尺寸
+
+**问题**：Sketch Icon 的 Group 容器包含 padding，直接用 Group.frame 渲染会导致 Icon 偏大。
+
+```
+Sketch 结构：
+├─ Group "Fee Icon" (16×16)        ← 外层容器，含 padding
+│  └─ ShapePath "path" (12×12)     ← 实际可见图形
+```
+
+**规则**：
+- 测量插件输出 `iconContentBounds.containerSize`（Group 尺寸）和 `iconContentBounds.contentSize`（路径尺寸）
+- **渲染 SVG 用 `contentSize`**（SvgPicture 的 width/height）
+- **占位槽用 `containerSize`**（外层 SizedBox 的 width/height）
+
+```dart
+// 正确：分离占位与渲染
+SizedBox(
+  width: 16, height: 16,  // containerSize - 占位
+  child: Center(
+    child: SvgPicture.asset('icon.svg',
+      width: 12, height: 12,  // contentSize - 渲染
+    ),
+  ),
+)
+
+// 错误：直接用 Group 尺寸渲染
+SvgPicture.asset('icon.svg', width: 16, height: 16)  // 太大！
+```
+
+### 陷阱 2：同行 Icon 不同尺寸导致文字错位
+
+**问题**：同一行的多个 Icon（如手续费 14px、优惠券 12px）如果直接用各自尺寸，后面的文字起始位置不一致。
+
+**规则**：
+- 测量插件输出 `siblingIconAlignment.maxSlotSize`
+- 所有同行 Icon 用**相同的 SizedBox 占位**，内部 Center 包裹实际 Icon
+
+```dart
+// 正确：统一占位 16px，文字从 20px 位置开始（16 + 4gap）
+Row(children: [
+  SizedBox(width: 16, height: 16, child: Center(
+    child: SvgPicture.asset('fee.svg', width: 14, height: 14),
+  )),
+  Gap(4),
+  Text('手续费'),
+])
+Row(children: [
+  SizedBox(width: 16, height: 16, child: Center(
+    child: SvgPicture.asset('coupon.svg', width: 12, height: 12),
+  )),
+  Gap(4),
+  Text('优惠券'),
+])
+```
+
+### 陷阱 3：Tag/标签容器样式丢失
+
+**问题**：小型 Tag（如"支付宝"标签）的 background、padding、cornerRadius 未从 Sketch 提取，凭感觉写出的样式与设计稿不符。
+
+**规则**：
+- 测量插件输出 `tagStyle`，包含 `background`、`padding`（horizontal/vertical）、`cornerRadius`
+- **直接使用测量值**，不要猜测 padding
+
+```dart
+// 正确：使用测量数据
+Container(
+  padding: EdgeInsets.symmetric(horizontal: 3, vertical: 1),  // 测量值
+  decoration: BoxDecoration(
+    color: Color(0x991676FE),   // 测量的 bg + 透明度
+    borderRadius: BorderRadius.circular(3),  // 测量的圆角
+  ),
+  child: Text('支付宝', style: TextStyle(fontSize: 8)),
+)
+
+// 错误：凭感觉
+Container(
+  padding: EdgeInsets.symmetric(horizontal: 6, vertical: 2),  // 猜的
+  decoration: BoxDecoration(
+    color: Color(0xFF1677FF),   // 丢失透明度
+    borderRadius: BorderRadius.circular(4),  // 猜的
+  ),
+)
+```
+
+### 陷阱 4：字体权重的平台可用性
+
+**问题**：Sketch fontWeight=8（Heavy/w800）在 PingFang SC 字体中不存在真实字重文件，Flutter 会用合成加粗（synthetic bold），视觉效果过粗。
+
+**规则**：
+- 使用 PostScript 字体名（如 `PingFangSC-Semibold`）映射权重，而非 Sketch 的 `fontWeight` 数值
+- **PingFang SC 最大真实字重 = Semibold (w600)**，超过此值一律降为 w600
+- **Helvetica 最大真实字重 = Bold (w700)**，超过此值一律降为 w700
+
+| Sketch fontWeight | PostScript 名 | Flutter 正确映射 |
+|-------------------|--------------|-----------------|
+| 8 (Heavy) | PingFangSC-Semibold | `FontWeight.w600`（而非 w800） |
+| 9 (Black) | 不存在 | `FontWeight.w600`（降级） |
+| 7 (Bold) | HelveticaNeue-Bold | `FontWeight.w700` |
+
+### 陷阱 5：添加设计稿中不存在的元素
+
+**问题**：AI 根据语义推测添加了设计稿中没有的 UI 元素（如在"汇率"标签前加了 swap_horiz 图标）。
+
+**规则**：
+- **只还原测量数据中存在的元素**，不自行添加
+- 如果测量数据中某个标签没有关联 Icon，则不添加 Icon
+- 如果不确定某元素是否存在，向用户确认
+
+---
+
 ## 🔴 问题诊断优先（最高优先级）
 
 **当用户描述任何问题时，必须首先调用：**
@@ -66,6 +184,10 @@ troubleshoot({ problem: "用户描述的问题" })
 | 输入框边框异常 | input, border, focus |
 | TextField 垂直居中 | textfield, placeholder, 居中, 光标, 输入框 |
 | **Tab 嵌套导航** | tabbar, navigator, 返回无效, tab切换卡顿, 嵌套 |
+| **Icon 尺寸偏差** | icon, 图标大小, Group, contentSize |
+| **文字过粗/合成加粗** | fontWeight, 字体粗, 加粗, synthetic bold |
+| **同行元素错位** | 对齐, 错位, 文字不齐, slot |
+| **Tag/标签样式错误** | tag, 标签, padding, 背景色 |
 
 > 💡 详细诊断方案由 MCP 工具从 npm 包动态加载
 
@@ -145,6 +267,11 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 - `api-layer` - API 层封装模式
 - `component-design` - 组件设计模式
 
+**设计稿还原**
+- `sketch-pitfalls` - Sketch 测量五大陷阱（Icon尺寸/Tag样式/字重/对齐/幽灵元素）
+- `design-restoration` - 设计稿还原通用流程
+- `sketch-mcp` - Sketch MCP 深度测量规范
+
 ---
 
 ## 🎨 设计稿还原规范
@@ -172,6 +299,10 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 | `siblingGaps` | 兄弟元素间的间距 | 转换为 `Gap()`、`SizedBox(height:)` |
 | `layoutIntent` | 布局意图（居中、填充等） | 选择 `Center`、`Column`、`Row` |
 | `flutterHints` | 直接可用的 Flutter 代码 | 参考建议代码快速实现 |
+| `iconContentBounds` | Icon 容器 vs 路径尺寸 | containerSize→占位, contentSize→渲染 |
+| `tagStyle` | Tag 容器完整样式 | bg/padding/cornerRadius 精确还原 |
+| `siblingIconAlignment` | 同行 Icon 统一尺寸 | maxSlotSize→统一 SizedBox |
+| `fontName` | PostScript 字体名 | 正确映射 FontWeight（防合成加粗） |
 
 ### 还原检查清单
 
@@ -183,6 +314,11 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 - [ ] 使用 Token 系统（$c, $t, $s, $r）替代硬编码
 - [ ] **计算内容总高度**，验证不超出容器（详见陷阱规范）
 - [ ] **避免 EdgeInsets.symmetric**，精确布局用 EdgeInsets.only
+- [ ] **Icon 用 contentSize 渲染，containerSize 占位**（防 Icon 偏大）
+- [ ] **同行 Icon 统一 SizedBox 占位**（防文字错位）
+- [ ] **Tag 容器使用测量的 padding/bg/cornerRadius**（防样式猜测）
+- [ ] **字体权重检查平台可用性**（PingFang≤w600, Helvetica≤w700）
+- [ ] **只还原测量数据中存在的元素**（防添加幽灵元素）
 
 ### ⚠️ 常见陷阱（必读）
 
@@ -197,6 +333,11 @@ get_standard_by_id({ id: 'sketch-pitfalls' })
 | 固定高度容器 | OVERFLOWED BY X PIXELS | 移除 height，用 MainAxisSize.min |
 | EdgeInsets.symmetric | 溢出 1-5px | 用 EdgeInsets.only 精确控制 |
 | 文本行高 | 容器高度不足 | 计算 fontSize × height 的实际占用 |
+| Icon 用 Group 尺寸 | Icon 比设计稿大 2-4px | 用 contentSize 渲染，containerSize 占位 |
+| 同行 Icon 不等大 | 文字起始位置不一致 | 统一 SizedBox 插槽 + Center |
+| Tag 凭感觉写样式 | padding/bg/圆角全错 | 使用 tagStyle 测量数据 |
+| 字重超出平台上限 | 文字过粗（合成加粗） | PingFang≤w600, Helvetica≤w700 |
+| 添加不存在的元素 | UI 与设计稿不符 | 只还原测量数据中存在的元素 |
 
 > 📖 **详细案例**：`mcp-server/troubleshooting/flutter/sketch-overflow-container.md`
 
@@ -206,7 +347,11 @@ get_standard_by_id({ id: 'sketch-pitfalls' })
 ❌ **禁止**使用简单的 `Positioned` 绝对定位所有元素  
 ❌ **禁止**硬编码内边距值（如 `EdgeInsets.all(16)`）而不基于测量数据  
 ❌ **禁止**忽略 `layoutIntent` 字段，导致嵌套层级错误  
-❌ **禁止**硬编码颜色/尺寸（必须使用 Token 系统）
+❌ **禁止**硬编码颜色/尺寸（必须使用 Token 系统）  
+❌ **禁止**用 Icon Group 的 frame 尺寸直接渲染 SVG（必须用 contentSize）  
+❌ **禁止**凭推测添加设计稿中不存在的 UI 元素（如猜测性添加图标）  
+❌ **禁止**使用超出字体平台可用范围的 FontWeight（合成加粗视觉差异大）  
+❌ **禁止**同行不同尺寸 Icon 各用各的宽度（必须统一占位槽）
 
 ### 🎯 深度还原模式（像素级）
 
@@ -237,27 +382,41 @@ get_standard_by_id({ id: 'sketch-pitfalls' })
 **检测到 icon 时的处理流程**：
 
 ```
-1. 深度测量脚本会标记 `isIcon: true` 并提示导出为 SVG 200h
-2. 将 SVG 文件放入 assets/icons/ 目录
-3. 在 pubspec.yaml 中声明 assets
-4. 使用 flutter_svg 包加载
+1. 测量插件标记 `isIcon: true` 并输出 iconContentBounds
+2. 读取 containerSize（Group 尺寸）和 contentSize（实际路径尺寸）
+3. 将 SVG 文件放入 assets/icons/ 目录
+4. 在 pubspec.yaml 中声明 assets
+5. 使用 flutter_svg 包加载，宽高用 contentSize
+6. 外层用 SizedBox(containerSize) + Center 包裹
 ```
 
 **Flutter Icon 使用方式**：
 
 | 场景 | 代码示例 | 说明 |
 |------|---------|------|
-| **SVG Icon** | `SvgPicture.asset('assets/icons/menu.svg', width: 24, height: 24, colorFilter: ColorFilter.mode($c.iconPrimary, BlendMode.srcIn))` | 推荐，支持颜色替换 |
+| **SVG Icon（标准）** | `SizedBox(width: 16, height: 16, child: Center(child: SvgPicture.asset('icon.svg', width: 12, height: 12, colorFilter: ColorFilter.mode($c.iconPrimary, BlendMode.srcIn))))` | containerSize 占位 + contentSize 渲染 |
 | **系统 Icon** | `Icon(Icons.menu, size: 24, color: $c.iconPrimary)` | 优先使用 Material Icons |
-| **固定尺寸** | `SizedBox(width: 24, height: 24, child: icon)` | 确保 icon 不被拉伸 |
+| **同行对齐** | 所有 Icon 用 `SizedBox(width: maxSlotSize)` + `Center` | 确保后续文字对齐 |
+
+**Icon 尺寸决策流程：**
+
+```
+测量数据 → iconContentBounds
+├─ containerSize (Group frame) → 外层 SizedBox 占位
+├─ contentSize (路径 union) → SvgPicture width/height
+└─ siblingIconAlignment.maxSlotSize → 同行统一占位
+```
 
-**⚠️ Icon 禁止规则**：
+**Icon 禁止规则**：
 
 | ❌ 禁止 | ✅ 正确 |
 |--------|--------|
 | `Image.asset('icon.png')` | `SvgPicture.asset('icon.svg')` |
 | `width: 32, height: 28` | 保持 1:1 宽高比或使用原始比例 |
 | 硬编码颜色 | `colorFilter: ColorFilter.mode($c.iconPrimary, ...)` |
+| 直接用 Group 尺寸渲染 SVG | 用 contentSize 渲染，containerSize 占位 |
+| 同行 Icon 各用各的宽度 | 统一 maxSlotSize + Center |
+| 凭语义推测添加 Icon | 只添加测量数据中存在的 Icon |
 
 #### Flutter 禁止规则
 

package/dist/index.js

@@ -3332,7 +3332,8 @@ var STANDARD_DIRS = [
   "standards/frameworks",
   "standards/libraries",
   "standards/patterns",
-  "standards/workflows"
+  "standards/workflows",
+  "standards/mcp-tools"
 ];
 var standardsCache = null;
 async function getStandardById(args) {