mta-mcp 3.14.2 → 3.15.1

package/agents/flutter.agent.md

@@ -1,7 +1,7 @@
 # Flutter 开发代理
 
 > 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
-> 版本: v4.0.0 | 最后更新: 2026-02-11
+> 版本: v4.1.0 | 最后更新: 2026-03-11
 
 ---
 
@@ -28,28 +28,33 @@
 
 ```
 1. 检测设计稿意图 → 提醒用户在 Sketch 选中图层
-2. 调用 mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "measure" } })
-   → 获取已注入 _SKETCH_CMD 的完整脚本（sketch-tools.js v4.6.0）
+2. 调用 mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "compact" } })
+  → 获取已注入 _SKETCH_CMD 的完整脚本（首轮优先读取 restorationContract）
 3. 将返回的 script 传入 mcp_sketch_run_code({ code: script })
-   → 执行测量，获取完整 Layout Intent JSON
-4. 基于测量数据中的 flutter* 字段精准生成代码
+  → 执行测量，获取紧凑 contract + tree JSON
+4. 先按 restorationContract 还原页面骨架和文案，再用 flutter* 字段填充样式
+5. 只有当 compact 无法解释局部布局/样式时，再补用 measure/style
 ```
 
 **注意：**
 - 不要手动读取 artboard-measure.js（已废弃，合并进 sketch-tools.js）
 - 不要手动拼接 _SKETCH_CMD（由 sketch_measure skill 自动处理）
 - 测量结果中所有颜色均包含 `flutterColor: "Color(0xAARRGGBB)"` 格式，可直接使用
+- 设计稿还原时，restorationContract 优先于现有业务组件、路由标题、i18n 文案和常见 CTA 习惯
 
 ### 测量数据关键字段（v4.6.0 新增带★标记）
 
 | 字段 | 用途 | Flutter 应用 |
 |------|------|-------------|
+| `restorationContract` | 页面级骨架合同 | 先读 `blockOrder/copyLedger/hardRules`，禁止结构漂移 |
 | `absoluteRect` | 绝对位置尺寸 | `width:`, `height:` |
 | `relativePosition` | 内边距 | `EdgeInsets` |
 | `siblingGaps` | 元素间距 | `SizedBox(height:)` |
 | `layoutIntent` | 布局方式 | `Column`/`Row`/`Center` |
 | `flutterHints` | 建议代码 | 直接参考 |
 | `iconContentBounds` | Icon 实际路径尺寸 | 渲染用 contentSize，占位用 containerSize |
+| `iconSvgMarkup` | Sketch 真实导出的 SVG 字符串 | 优先于猜测文件名，必要时直接落盘 |
+| `iconSvgMeta.colorStrategy` | SVG 颜色策略 | `preserve` 保原色，`tint` 仅单色图标可着色 |
 | `tagStyle` | Tag/标签容器样式 | background, padding, cornerRadius |
 | `siblingIconAlignment` | 同行 Icon 对齐 | 统一 SizedBox 插槽尺寸 |
 | ★`flutterColor` | Flutter 颜色格式 | 直接粘贴 `Color(0xAARRGGBB)` |
@@ -57,14 +62,24 @@
 | ★`flutterBorder` | 完整边框代码 | 直接粘贴 `Border.all(...)` |
 | ★`flutterLinearGradient` | 完整渐变代码 | 直接粘贴 `LinearGradient(...)` |
 | ★`flutterHint` | FILL→double.infinity | 禁止硬编码宽度 |
-| ★`flutterSvgCode` | 完整 SVG 加载代码 | 直接粘贴 `SvgPicture.asset(...)` |
+| ★`flutterSvgCode` | 完整 SVG 加载代码 | 优先使用 `SvgPicture.string(actualSvg...)` |
 | ★`iconFillColor` | 图标填充色 | 已含 Flutter Color 格式 |
+| ★`flutterTextStyle` | 完整文本样式提示 | 含 `fontFamily/height/letterSpacing/fontWeight/color` |
+| ★`flutterStrutStyle` | 行盒校准提示 | 固定高度文本直接使用 `StrutStyle(...)` |
 
 **禁止**：未测量就凭感觉还原、硬编码尺寸、忽略 layoutIntent、手动拼接颜色十六进制
 
+### 页面级 Contract 规则（v4.1.0 新增）
+
+- 先读 `restorationContract.blockOrder`：先还原顶层结构顺序，再处理局部样式
+- `bodyCopyLedger` / `navCopyLedger` 是文案真值：默认禁止改成现有页面标题、业务分组名、路由文案
+- `topPrimaryEntry` 存在时禁止下沉为底部 CTA
+- `bottomNavigation.present=true` 且未测得额外 CTA 时，禁止再叠加一层固定底部按钮
+- 若现有项目通用组件会引入多余 section/CTA/标题，优先新建贴合设计稿的局部实现，不强行复用
+
 ---
 
-## 🔴 设计稿还原五大陷阱（最高优先级）
+## 🔴 设计稿还原六大陷阱（最高优先级）
 
 > 以下陷阱基于真实项目多轮修复总结，每条都曾导致 2-5 轮无效对话
 
@@ -159,16 +174,27 @@ Container(
 
 **规则**：
 - 使用 PostScript 字体名（如 `PingFangSC-Semibold`）映射权重，而非 Sketch 的 `fontWeight` 数值
-- **PingFang SC 最大真实字重 = Semibold (w600)**，超过此值一律降为 w600
+- **PingFang SC 最大真实字重 = Semibold (w600)**，只有超过此值时才降为 w600，不再把真实的 w600 自动降成 w500
 - **Helvetica 最大真实字重 = Bold (w700)**，超过此值一律降为 w700
+- 文本样式优先使用插件给出的 `flutterTextStyle`；如果文字处于固定高度/行内对齐场景，再配合 `flutterStrutStyle`
 
 | Sketch fontWeight | PostScript 名 | Flutter 正确映射 |
 |-------------------|--------------|-----------------|
-| 8 (Heavy) | PingFangSC-Semibold | `FontWeight.w600`（而非 w800） |
+| 8 (Heavy) | PingFangSC-Semibold | `FontWeight.w600`（而非 w800，也不是错误降成 w500） |
 | 9 (Black) | 不存在 | `FontWeight.w600`（降级） |
 | 7 (Bold) | HelveticaNeue-Bold | `FontWeight.w700` |
 
-### 陷阱 5：添加设计稿中不存在的元素
+### 陷阱 5：把多色/渐变 SVG 当成单色图标整体 tint
+
+**问题**：国旗、品牌图标、渐变按钮图标如果直接套 `ColorFilter.mode()`，会把原本的多色信息全部抹平。
+
+**规则**：
+- 先看 `iconSvgMeta.colorStrategy`
+- `preserve`：必须保留原始 SVG 颜色，禁止整体 tint
+- `tint`：仅单色图标允许套 `ColorFilter.mode()`
+- 优先使用插件生成的 `flutterSvgCode`，不要再手动把所有 SVG 改写成 `SvgPicture.asset(..., colorFilter: ...)`
+
+### 陷阱 6：添加设计稿中不存在的元素
 
 **问题**：AI 根据语义推测添加了设计稿中没有的 UI 元素（如在"汇率"标签前加了 swap_horiz 图标）。
 
@@ -296,12 +322,27 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 
 ```
 1. 用户提供 Sketch 文件 → 先提醒："需要先在 Sketch 中选中目标图层"
-2. 调用 mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "measure" } })
+2. 调用 mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "compact" } })
 3. 将返回的 script 传入 mcp_sketch_run_code 执行
-4. 基于测量数据中的 flutter* 字段精准还原（flutterColor、flutterBoxShadow、flutterSvgCode 等）
+4. 先按 restorationContract 还原页面骨架和文案，再消费 tree 中的 flutter* 字段
 5. FILL 类型尺寸使用 flutterHint 的 double.infinity，禁止硬编码宽度
+6. compact 无法解释局部布局/样式时，再补用 measure/style
 ```
 
+### 结构优先于业务语义（最高优先级）
+
+当设计稿还原发生以下冲突时，按下面优先级决策：
+
+1. restorationContract / 测量结果
+2. 设计稿截图的真实结构关系
+3. 项目 Token 与局部可复用样式
+4. 现有页面标题、i18n 文案、业务分组、通用 CTA 习惯
+
+**强制结论**：
+- 现有“收款人管理”“常用收款人 / 其他收款人”等业务语义，不得覆盖设计稿中测得的标题和结构
+- 现有页面有底部添加按钮的实现习惯，不得据此把设计稿顶部入口改成底部固定按钮
+- 现有通用列表组件如果会多带 section/header/footer，禁止为了复用而牺牲结构一致性
+
 ### 测量数据必备字段
 
 调用 SketchMeasureHD 后，你会得到以下关键数据：
@@ -327,6 +368,11 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 
 ### 还原检查清单
 
+- [ ] 先读取 `restorationContract.pageTitle`、`blockOrder`、`hardRules`
+- [ ] 逐个 block 建立代码对应关系，未映射的 block 不能跳过
+- [ ] `bodyCopyLedger` 文案与代码文案一致，未被业务文案覆盖
+- [ ] 如果存在 `topPrimaryEntry`，确认没有被改成底部固定 CTA
+- [ ] 如果 `bottomNavigation.present=true`，确认没有额外叠加固定底部操作条
 - [ ] 使用 `absoluteRect` 而非 `frame`（避免相对坐标错误）
 - [ ] 使用 `relativePosition` 计算内边距（转换为 `EdgeInsets`）
 - [ ] 使用 `siblingGaps` 确定元素间距（转换为 `Gap()`）
@@ -363,6 +409,7 @@ get_standard_by_id({ id: 'sketch-pitfalls' })
 | Tag 凭感觉写样式 | padding/bg/圆角全错 | 使用 tagStyle 测量数据 |
 | 字重超出平台上限 | 文字过粗（合成加粗） | PingFang≤w600, Helvetica≤w700 |
 | 添加不存在的元素 | UI 与设计稿不符 | 只还原测量数据中存在的元素 |
+| 业务语义劫持页面骨架 | 标题/分组/CTA 被现有页面习惯改写 | 先服从 restorationContract，再考虑复用组件 |
 
 > 📖 **详细案例**：`mcp-server/troubleshooting/flutter/sketch-overflow-container.md`
 
@@ -377,6 +424,8 @@ get_standard_by_id({ id: 'sketch-pitfalls' })
 ❌ **禁止**凭推测添加设计稿中不存在的 UI 元素（如猜测性添加图标）  
 ❌ **禁止**使用超出字体平台可用范围的 FontWeight（合成加粗视觉差异大）  
 ❌ **禁止**同行不同尺寸 Icon 各用各的宽度（必须统一占位槽）
+❌ **禁止**用现有路由标题、i18n 文案或业务分组覆盖 restorationContract 中的文案真值
+❌ **禁止**把顶部入口卡片、顶部 CTA 或中部 section 入口迁移成底部固定按钮
 
 ### 🎯 深度还原模式（像素级）