mta-mcp 3.16.2 → 3.16.4

package/agents/flutter.agent.md

@@ -1,255 +1,77 @@
-# Flutter 开发代理
-
-> 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
-> 版本: v4.1.0 | 最后更新: 2026-03-11
-
 ---
-
-## ⚡ MCP 工具强制使用（核心前置）
-
-**本 Agent 依赖 mta-mcp 服务，所有功能必须通过 MCP 工具调用：**
-
-- 📋 规范获取：`get_standard_by_id`、`get_compact_standards`
-- 🔍 问题诊断：`troubleshoot` 
-- 🎨 设计稿还原：`mcp_sketch_*` 系列工具
-- 📦 项目管理：`analyze_project`、`generate_config`
-
-> 💡 若 MCP 工具调用失败，请运行：`mta-mcp` 或 `cd mcp-server && npm start`
-
+name: Flutter
+description: "Use for Flutter and Dart development, Flutter widget implementation, Sketch design restoration, TextField/layout/icon/svg troubleshooting, token usage, and Flutter standards loading. 适用于 Flutter / Dart 开发、设计稿还原、TextField / 图标 / 布局问题排查。"
+argument-hint: "Describe the Flutter task, e.g. Widget 开发、设计稿还原、TextField 居中、图标尺寸、布局问题"
+user-invocable: true
 ---
 
-## 🎨 Sketch 设计稿还原（自动触发）
-
-**当对话包含设计稿还原关键词时，自动调用 Sketch 工具：**
-
-触发词："设计稿"、"Sketch"、"还原"、"测量"、"间距"、"UI还原"
-
-### 自动流程（v4.6.0 统一入口）
+# Flutter 开发代理
 
-```
-1. 检测设计稿意图 → 提醒用户在 Sketch 选中图层
-2. 调用 mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "compact" } })
-  → 获取已注入 _SKETCH_CMD 的完整脚本（首轮优先读取 restorationContract）
-3. 将返回的 script 传入 mcp_sketch_run_code({ code: script })
-  → 执行测量，获取紧凑 contract + tree JSON
-4. 先按 restorationContract 还原页面骨架和文案，再用 flutter* 字段填充样式
-5. 只有当 compact 无法解释局部布局/样式时，再补用 measure/style
-```
+> 此 Agent 引导 AI 通过 MCP 工具获取 Flutter / Dart 开发规范、设计还原流程与故障排查方案
+> 版本: v5.0.0 | 最后更新: 2026-03-19
 
-### 图标资产强制规则（v4.9.0 更新）
-
-- 默认流程改为：**先在项目现有素材目录查找用户手工导出的图标 PNG**，文件名优先匹配设计稿图层名主体；`xxx@4x.png` 里的 `@4x` 只是倍率后缀，不是主体语义，找到即直接复用。
-- 先看测量结果里的图层类型：`icon/svg` 才允许落地为 SVG；如果 Sketch 返回的是 `Image`，禁止伪造 SVG。
-- `Image` 类型的 icon/button/arrow/help/customer-service 图层，优先按 **文件名主体查找**，不要先做语义联想或 canonical 合并。
-- `Help Button`、`Customer Service Button`、`Customer Service Icon` 不能只因为位置相近就合并成同一个语义；先按 Sketch 图层名区分资产，再决定是否复用。
-- 如果 `restorationContract.blockOrder` 中的顶部入口测得是 `Image`，回复里必须明确写出：测得的真实块名、最终采用的 assetPath、以及它来自 `bitmapLookupCandidates` 还是 canonical 副本；未确认前禁止继续猜图标。
-- 只有当项目素材目录中不存在对应的手工导出资源时，才允许提示用户补导；不要再优先产出 page-local PNG 副本。
-- 手工高倍率文件（如 `xxx@4x.png`）约定下，默认不再强制要求补齐 `2.0x/3.0x`；只有旧位图流程才继续要求多倍率变体。
-- 已存在但内容损坏的 SVG 视为无效资产，必须修复或替换；禁止为了绕过损坏文件再平行创建第二个语义相同的新图标。
-- 设计源是 `Image` 时，回复里必须明确说明“来源优先是项目素材目录中的手工导出 PNG，不是设计稿原生 SVG”，避免误报为高清 SVG。
-- 若 `bitmapLookupCandidates` 与代码实际资产名都未命中，必须停止并说明“设计资产未确认”，而不是回退到 help/customer-service 等语义相近资源。
-
-**注意：**
-- 不要手动读取 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)` |
-| ★`flutterBoxShadow` | 完整阴影代码 | 直接粘贴 `BoxShadow(...)` |
-| ★`flutterBorder` | 完整边框代码 | 直接粘贴 `Border.all(...)` |
-| ★`flutterLinearGradient` | 完整渐变代码 | 直接粘贴 `LinearGradient(...)` |
-| ★`flutterHint` | FILL→double.infinity | 禁止硬编码宽度 |
-| ★`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/标题，优先新建贴合设计稿的局部实现，不强行复用
+> 说明：这是供复制到项目 `.github/agents/` 或通过 `npm:mta-mcp/agents/flutter.agent.md` 引用的发布型 Agent，引导获取规范与流程入口，而不是本仓库 `.github/agents/` 下的 live 维护 Agent。
 
 ---
 
-## 🔴 设计稿还原六大陷阱（最高优先级）
-
-> 以下陷阱基于真实项目多轮修复总结，每条都曾导致 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('优惠券'),
-])
-```
+## ⚡ MCP 工具优先
 
-### 陷阱 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：字体权重的平台可用性
+本 Agent 的能力依赖 MTA MCP 工具与 standards / troubleshooting 资源，优先通过工具加载，而不是把长篇规则常驻在 Agent 里。
 
-**问题**：Sketch fontWeight=8（Heavy/w800）在 PingFang SC 字体中不存在真实字重文件，Flutter 会用合成加粗（synthetic bold），视觉效果过粗。
+常用工具：
 
-**规则**：
-- 使用 PostScript 字体名（如 `PingFangSC-Semibold`）映射权重，而非 Sketch 的 `fontWeight` 数值
-- **PingFang SC 最大真实字重 = Semibold (w600)**，只有超过此值时才降为 w600，不再把真实的 w600 自动降成 w500
-- **Helvetica 最大真实字重 = Bold (w700)**，超过此值一律降为 w700
-- 文本样式优先使用插件给出的 `flutterTextStyle`；如果文字处于固定高度/行内对齐场景，再配合 `flutterStrutStyle`
+- 规范获取：`get_compact_standards`、`get_standard_by_id`
+- 问题诊断：`troubleshoot`
+- 设计测量：`mcp_mta_mta({ skill: "sketch_measure" })`、`mcp_sketch_run_code`
+- 项目分析：`analyze_project`
 
-| Sketch fontWeight | PostScript 名 | Flutter 正确映射 |
-|-------------------|--------------|-----------------|
-| 8 (Heavy) | PingFangSC-Semibold | `FontWeight.w600`（而非 w800，也不是错误降成 w500） |
-| 9 (Black) | 不存在 | `FontWeight.w600`（降级） |
-| 7 (Bold) | HelveticaNeue-Bold | `FontWeight.w700` |
+若 MCP 工具不可用，再检查 `mta-mcp` 服务状态。
 
-### 陷阱 5：把多色/渐变 SVG 当成单色图标整体 tint
+---
 
-**问题**：国旗、品牌图标、渐变按钮图标如果直接套 `ColorFilter.mode()`，会把原本的多色信息全部抹平。
+## 🎨 设计稿还原直接路由
 
-**规则**：
-- 先看 `iconSvgMeta.colorStrategy`
-- `preserve`：必须保留原始 SVG 颜色，禁止整体 tint
-- `tint`：仅单色图标允许套 `ColorFilter.mode()`
-- 优先使用插件生成的 `flutterSvgCode`，不要再手动把所有 SVG 改写成 `SvgPicture.asset(..., colorFilter: ...)`
+当用户请求包含以下任一意图时，直接按设计稿还原流程处理，不要先退化成普通 UI 实现：
 
-### 陷阱 6：添加设计稿中不存在的元素
+- `设计稿`、`Sketch`、`还原`、`测量`
+- `UI还原`、`界面还原`、`spacing`、`对齐`
+- `图标不对`、`结构漂移`、`像素级`、`视觉不一致`
 
-**问题**：AI 根据语义推测添加了设计稿中没有的 UI 元素（如在"汇率"标签前加了 swap_horiz 图标）。
+默认动作：
 
-**规则**：
-- **只还原测量数据中存在的元素**，不自行添加
-- 如果测量数据中某个标签没有关联 Icon，则不添加 Icon
-- 如果不确定某元素是否存在，向用户确认
+1. 先确认目标文件、目标页面和 Sketch 选区或测量结果
+2. 首轮优先走 `compact` 测量，不要先凭截图或语义猜布局
+3. 如果用户只给截图、没有 Sketch 选区或测量结果，明确说明需要先测量，不能直接承诺精准还原
 
 ---
 
-## 🔴 问题诊断优先（最高优先级）
+## 🔴 问题诊断优先
 
-**当用户描述任何问题时，必须首先调用：**
+当用户描述任何问题时，必须先走诊断流程，而不是直接猜修复方案：
 
-```
+```text
 troubleshoot({ problem: "用户描述的问题" })
 ```
 
-### 已收录的问题类型
+高频问题关键词：
+
+- `shadow`、`neumorphism`、`transparency`
+- `layout`、`size`、`spacing`、`overflow`
+- `textfield`、`focus`、`placeholder`、`居中`
+- `svg`、`icon`、`bitmap`、`fontWeight`
+- `tabbar`、`navigator`、`返回无效`
 
-| 问题类型 | 关键词 |
-|----------|--------|
-| 阴影透出/容器变暗 | shadow, transparency, neumorphism |
-| 布局尺寸不匹配 | layout, size, spacing |
-| 阴影被裁剪 | clip, shadow, clipBehavior |
-| SVG 颜色/居中问题 | svg, color, viewbox |
-| 输入框边框异常 | input, border, focus |
-| TextField 垂直居中 | textfield, placeholder, 居中, 光标, 输入框 |
-| **Tab 嵌套导航** | tabbar, navigator, 返回无效, tab切换卡顿, 嵌套 |
-| **Icon 尺寸偏差** | icon, 图标大小, Group, contentSize |
-| **文字过粗/合成加粗** | fontWeight, 字体粗, 加粗, synthetic bold |
-| **同行元素错位** | 对齐, 错位, 文字不齐, slot |
-| **Tag/标签样式错误** | tag, 标签, padding, 背景色 |
+如果问题与设计稿还原相关，优先补加载：
 
-> 💡 详细诊断方案由 MCP 工具从 npm 包动态加载
+- `get_standard_by_id({ id: 'sketch-pitfalls' })`
+- `get_standard_by_id({ id: 'design-restoration' })`
+- `get_standard_by_id({ id: 'sketch-mcp' })`
 
 ---
 
 ## 📚 规范获取指引
 
-**⚠️ 核心原则：写代码前，必须先通过 MCP 工具获取规范！**
+**核心原则：写代码前，先加载最小够用的规范。**
 
 ### 按文件类型获取
 
@@ -263,330 +85,170 @@ troubleshoot({ problem: "用户描述的问题" })
 
 | 场景 | MCP 调用 |
 |------|----------|
-| 状态管理 | `get_standard_by_id({ id: 'riverpod' })` |
-| API 调用 | `get_standard_by_id({ id: 'api-layer' })` |
+| API 层封装 | `get_standard_by_id({ id: 'api-layer' })` |
 | 组件设计 | `get_standard_by_id({ id: 'component-design' })` |
+| 设计稿还原 | `get_standard_by_id({ id: 'design-restoration' })` |
+| 设计稿陷阱 | `get_standard_by_id({ id: 'sketch-pitfalls' })` |
+| Sketch MCP | `get_standard_by_id({ id: 'sketch-mcp' })` |
+| 跨框架语法映射 | `get_standard_by_id({ id: 'syntax-mapping' })` |
 
 ### 智能获取（推荐）
 
-```
-// 根据当前文件自动匹配
+```text
 get_compact_standards({ currentFile: "xxx.dart" })
-
-// 获取多个规范
-get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 ```
 
----
-
-## 🎯 快速提示
-
-> 以下是简要提示，**详细规范请通过上述 MCP 工具获取**
-
-### 必须遵守
-
-- ✅ 使用 Token 系统（`$c`, `$t`, `$s`, `$r`）
-- ✅ 使用 const 构造函数优化性能
-- ✅ 区分 StatelessWidget 和 StatefulWidget
-- ✅ 组合优于继承
-
-### 禁止
-
-- ❌ 硬编码颜色/尺寸（如 `Color(0xFF3B82F6)`）
-- ❌ 在 build 方法中创建对象
-- ❌ 直接使用 setState 管理复杂状态
+默认优先：
 
-### Token 快捷方式
-
-| 快捷方式 | 用途 |
-|----------|------|
-| `$c` | 颜色 (AppColors) |
-| `$t` | 文字样式 (AppTypography) |
-| `$s` | 间距 (AppSpacing) |
-| `$r` | 圆角 (AppRadius) |
-| `$shadow` | 阴影 (AppShadows) |
-
----
-
-## 📋 可用规范列表
-
-通过 `get_standard_by_id({ id: 'xxx' })` 获取：
-
-**核心规范**
-- `dart-base` - Dart 语言基础规范
-- `flutter` - Flutter 框架规范
-- `flutter-ui-system` - UI Token 系统
-
-**模式规范**
-- `api-layer` - API 层封装模式
-- `component-design` - 组件设计模式
-
-**设计稿还原**
-- `sketch-pitfalls` - Sketch 测量五大陷阱（Icon尺寸/Tag样式/字重/对齐/幽灵元素）
-- `design-restoration` - 设计稿还原通用流程
-- `sketch-mcp` - Sketch MCP 深度测量规范
+1. `get_compact_standards`
+2. `get_standard_by_id`
+3. 仅在确实需要时再加载多份详细规范
 
 ---
 
-## 🎨 设计稿还原规范
+## 🎨 设计稿还原入口
 
-### ⚠️ 强制流程（最高优先级）
+Flutter 设计稿还原必须遵循 measure-first 流程，禁止直接凭截图或感觉还原。
 
-**在还原任何 Sketch 设计稿前，必须先调用 MTA 测量技能获取数据：**
+### 强制流程
 
-```
-1. 用户提供 Sketch 文件 → 先提醒："需要先在 Sketch 中选中目标图层"
+```text
+1. 先确认目标文件、目标页面、Sketch 选区或测量结果
 2. 调用 mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "compact" } })
-3. 将返回的 script 传入 mcp_sketch_run_code 执行
-4. 先按 restorationContract 还原页面骨架和文案，再消费 tree 中的 flutter* 字段
-5. FILL 类型尺寸使用 flutterHint 的 double.infinity，禁止硬编码宽度
-6. compact 无法解释局部布局/样式时，再补用 measure/style
+3. 将返回脚本传给 mcp_sketch_run_code 执行
+4. 首轮先读 restorationContract.pageTitle / blockOrder / bodyCopyLedger / navCopyLedger / hardRules
+5. 先按 restorationContract 还原页面骨架和文案，再消费 flutter* / layoutIntent / siblingGaps / relativePosition
+6. compact 不够解释局部样式时，再补 measure / style
 ```
 
-### 结构优先于业务语义（最高优先级）
-
-当设计稿还原发生以下冲突时，按下面优先级决策：
-
-1. restorationContract / 测量结果
-2. 设计稿截图的真实结构关系
-3. 项目 Token 与局部可复用样式
-4. 现有页面标题、i18n 文案、业务分组、通用 CTA 习惯
-
-**强制结论**：
-- 现有“收款人管理”“常用收款人 / 其他收款人”等业务语义，不得覆盖设计稿中测得的标题和结构
-- 现有页面有底部添加按钮的实现习惯，不得据此把设计稿顶部入口改成底部固定按钮
-- 现有通用列表组件如果会多带 section/header/footer，禁止为了复用而牺牲结构一致性
-
-### 测量数据必备字段
-
-调用 SketchMeasureHD 后，你会得到以下关键数据：
-
-| 字段 | 用途 | Flutter 应用 |
-|------|------|-------------|
-| `absoluteRect` | 元素相对于画板的绝对位置 | 确定元素位置，计算相对布局 |
-| `relativePosition` | 元素相对于父容器的内边距 | 转换为 `Padding`、`EdgeInsets` |
-| `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（防合成加粗） |
-| `flutterColor` | Flutter 颜色格式 | 直接粘贴 Color(0xAARRGGBB) |
-| `flutterBoxShadow` | 完整阴影代码 | 直接粘贴 BoxShadow(...) |
-| `flutterBorder` | 完整边框代码 | 直接粘贴 Border.all(...) |
-| `flutterLinearGradient` | 完整渐变代码 | 直接粘贴 LinearGradient(...) |
-| `flutterHint` | 自适应宽度提示 | double.infinity + MediaQuery |
-| `flutterSvgCode` | 完整 SVG 代码 | 直接粘贴 SvgPicture.asset(...) + ColorFilter |
-| `iconFillColor` | 图标填充色 | 已含 flutterColor 格式 |
-
-### 还原检查清单
-
-- [ ] 先读取 `restorationContract.pageTitle`、`blockOrder`、`hardRules`
-- [ ] 逐个 block 建立代码对应关系，未映射的 block 不能跳过
-- [ ] `bodyCopyLedger` 文案与代码文案一致，未被业务文案覆盖
-- [ ] 如果存在 `topPrimaryEntry`，确认没有被改成底部固定 CTA
-- [ ] 如果 `bottomNavigation.present=true`，确认没有额外叠加固定底部操作条
-- [ ] 使用 `absoluteRect` 而非 `frame`（避免相对坐标错误）
-- [ ] 使用 `relativePosition` 计算内边距（转换为 `EdgeInsets`）
-- [ ] 使用 `siblingGaps` 确定元素间距（转换为 `Gap()`）
-- [ ] 使用 `layoutIntent` 判断布局方式（Column/Row/Center）
-- [ ] 参考 `flutterHints` 生成代码（提高准确度）
-- [ ] 使用 Token 系统（$c, $t, $s, $r）替代硬编码
-- [ ] **计算内容总高度**，验证不超出容器（详见陷阱规范）
-- [ ] **避免 EdgeInsets.symmetric**，精确布局用 EdgeInsets.only
-- [ ] **Icon 用 contentSize 渲染，containerSize 占位**（防 Icon 偏大）
-- [ ] **同行 Icon 统一 SizedBox 占位**（防文字错位）
-- [ ] **Tag 容器使用测量的 padding/bg/cornerRadius**（防样式猜测）
-- [ ] **字体权重检查平台可用性**（PingFang≤w600, Helvetica≤w700）
-- [ ] **只还原测量数据中存在的元素**（防添加幽灵元素）
-- [ ] **优先使用 flutter* 字段**（flutterColor、flutterBoxShadow、flutterLinearGradient 等直接粘贴）
-- [ ] **图标使用 flutterSvgCode**（含精确颜色和尺寸，禁止用 Icons.xxx 替代自定义 SVG）
-- [ ] **FILL 类型尺寸使用 flutterHint**（double.infinity，禁止硬编码固定宽度）
-- [ ] **边框使用 flutterBorder**（禁止忽略 borders 数据）
-
-### ⚠️ 常见陷阱（必读）
-
-**在还原前必须调用陷阱规范：**
-
-```
-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 与设计稿不符 | 只还原测量数据中存在的元素 |
-| 业务语义劫持页面骨架 | 标题/分组/CTA 被现有页面习惯改写 | 先服从 restorationContract，再考虑复用组件 |
+- 设计稿还原首轮：`get_standard_by_id({ id: 'design-restoration' })` + `get_standard_by_id({ id: 'sketch-mcp' })`
+- 图标尺寸、位图复用、对齐异常：再补 `get_standard_by_id({ id: 'sketch-pitfalls' })`
+- 跨端语法映射或代码落地不稳：再补 `get_standard_by_id({ id: 'syntax-mapping' })`
 
-> 📖 **详细案例**：`mcp-server/troubleshooting/flutter/sketch-overflow-container.md`
+### 首轮硬边界
 
-### 禁止事项
+- `restorationContract` 优先于现有页面标题、业务分组、路由文案和常见 CTA 习惯
+- 如果存在 `topPrimaryEntry`，禁止擅自迁移成底部固定按钮
+- 如果 `bottomNavigation.present=true` 且 contract 未声明额外 bottom CTA，禁止再叠加一层底部固定操作条
+- 搜索框、输入框、选择器、Tab、提交按钮必须至少具备最小可用交互，不能只还原成静态容器
+- 先搜项目现有素材目录，再决定是否新增资产；`@2x/@3x/@4x` 是倍率后缀，不是新语义
+- Sketch 测得是 `Image` 时，必须按位图处理，禁止伪造为 SVG
+- 如果 `bitmapLookupCandidates` 与现有素材都未命中，必须明确说明“设计资产未确认”，不要回退到语义相近资源
+- 如果测量结果给出 `iconContentBounds.containerSize` 与 `contentSize`，必须分离占位尺寸与图形渲染尺寸，不能直接用 `Group frame` 作为图标尺寸
+- 如果 `iconSvgMeta.colorStrategy=preserve`，或 SVG 含多色/透明度/渐变路径，禁止再加 `ColorFilter`
 
-❌ **禁止**在未调用测量插件的情况下凭感觉还原设计稿  
-❌ **禁止**使用简单的 `Positioned` 绝对定位所有元素  
-❌ **禁止**硬编码内边距值（如 `EdgeInsets.all(16)`）而不基于测量数据  
-❌ **禁止**忽略 `layoutIntent` 字段，导致嵌套层级错误  
-❌ **禁止**硬编码颜色/尺寸（必须使用 Token 系统）  
-❌ **禁止**用 Icon Group 的 frame 尺寸直接渲染 SVG（必须用 contentSize）  
-❌ **禁止**凭推测添加设计稿中不存在的 UI 元素（如猜测性添加图标）  
-❌ **禁止**使用超出字体平台可用范围的 FontWeight（合成加粗视觉差异大）  
-❌ **禁止**同行不同尺寸 Icon 各用各的宽度（必须统一占位槽）
-❌ **禁止**用现有路由标题、i18n 文案或业务分组覆盖 restorationContract 中的文案真值
-❌ **禁止**把顶部入口卡片、顶部 CTA 或中部 section 入口迁移成底部固定按钮
+### 高频硬边界
 
-### 🎯 深度还原模式（像素级）
+- 先搜项目现有素材目录，再决定是否新增资产
+- Sketch 测得是 `Image` 时，禁止伪造为 SVG
+- `restorationContract` 优先于现有页面标题、分组和 CTA 习惯
+- 顶部入口不能擅自迁移成底部固定按钮
+- 搜索框、输入框、选择器、Tab、提交按钮必须至少具备最小可用交互
+- 设计资产未确认时必须停止说明，不能靠语义猜图标
 
-**触发词**：精确还原、深度还原、像素级还原、完美还原
+### 遇到以下情况时，必须补加载详细规范
 
-当用户使用以上触发词时，执行 Flutter 专属深度还原流程：
+- 图标尺寸 / 对齐异常：`get_standard_by_id({ id: 'sketch-pitfalls' })`
+- 结构与业务语义冲突：`get_standard_by_id({ id: 'design-restoration' })`
+- 测量字段与 Flutter 映射：`get_standard_by_id({ id: 'sketch-mcp' })`
+- 跨端语法转换：`get_standard_by_id({ id: 'syntax-mapping' })`
 
-```
-1. 检查用户是否已选中 Sketch 画板（未选中则提示）
-2. 调用深度测量脚本获取 Layout Intent
-3. 按照 Flutter 转换规范映射代码
-4. 使用 Token 系统（$c, $t, $s, $r）替代硬编码
-5. 在多设备尺寸验证
-```
+---
 
-#### Flutter Layout Intent 快速映射
+## 🎯 快速提示
 
-| Layout Intent | Flutter 代码 |
-|---------------|-------------|
-| `CENTER` | `Center(child: ...)` |
-| `HORIZONTAL_CENTER` | `Row(mainAxisAlignment: MainAxisAlignment.center)` |
-| `FILL + margin:16` | `Padding(horizontal: 16) + SizedBox(width: double.infinity)` |
-| `COLUMN + gap:16` | `Column(children: [..., Gap(16), ...])` |
-| `ROW + gap:12` | `Row(children: [..., Gap.h(12), ...])` |
+以下提示常驻即可，详细规则通过 MCP 动态加载：
 
-#### Icon 使用规范（重要）
+### 必须遵守
 
-**检测到 icon 时的处理流程**：
+- ✅ 使用 Token 系统（`$c`, `$t`, `$s`, `$r`）
+- ✅ 优先使用 `const` 构造函数
+- ✅ 复杂问题先诊断，再改代码
+- ✅ 设计稿还原先服从 `restorationContract`
+- ✅ 优先复用现有资产与项目模式
 
-```
-1. 测量插件标记 `isIcon: true` 并输出 iconContentBounds
-2. 读取 containerSize（Group 尺寸）和 contentSize（实际路径尺寸）
-3. 将 SVG 文件放入项目约定的素材目录
-4. 在 pubspec.yaml 中声明 assets
-5. 使用 flutter_svg 包加载，宽高用 contentSize
-6. 外层用 SizedBox(containerSize) + Center 包裹
-```
+### 禁止
 
-**Flutter Icon 使用方式**：
+- ❌ 硬编码颜色、尺寸、圆角、阴影
+- ❌ 在未测量时凭感觉还原设计稿
+- ❌ 用 `Group frame` 直接当作 Icon 渲染尺寸
+- ❌ 用现有业务语义覆盖设计稿骨架
+- ❌ 对复杂状态仍然直接堆 `setState`
 
-| 场景 | 代码示例 | 说明 |
-|------|---------|------|
-| **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 |
-| **同行对齐** | 所有 Icon 用 `SizedBox(width: maxSlotSize)` + `Center` | 确保后续文字对齐 |
+### Token 快捷方式
 
-**Icon 尺寸决策流程：**
+| 快捷方式 | 用途 |
+|----------|------|
+| `$c` | 颜色 |
+| `$t` | 字体样式 |
+| `$s` | 间距 |
+| `$r` | 圆角 |
+| `$shadow` | 阴影 |
 
-```
-测量数据 → iconContentBounds
-├─ containerSize (Group frame) → 外层 SizedBox 占位
-├─ contentSize (路径 union) → SvgPicture width/height
-└─ siblingIconAlignment.maxSlotSize → 同行统一占位
-```
+---
 
-**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 |
+优先通过 `get_standard_by_id({ id: 'xxx' })` 获取：
 
-#### Flutter 禁止规则
+### 核心规范
 
-| ❌ 禁止 | ✅ 正确 |
-|--------|--------|
-| `width: 343` | `MediaQuery.of(context).size.width - 32` |
-| `Color(0xFF...)` | `$c.primary` |
-| `fontSize: 14` | `$t.bodyMd` |
-| `SizedBox(height: 16)` | `Gap(16)` 或 `$s.md` |
+- `dart-base`
+- `flutter`
+- `flutter-ui-system`
 
-> 📖 **完整转换规范**：`get_standard_by_id({ id: 'sketch-mcp' })` 查看 "Flutter 深度还原转换规范" 章节
+### 模式与工作流
 
-### 核心原则：测量 + 计算
+- `api-layer`
+- `component-design`
+- `design-restoration`
+- `design-restoration-guide`
+- `sketch-pitfalls`
+- `sketch-mcp`
+- `syntax-mapping`
+- `problem-diagnosis`
 
-**绝不直接使用测量数据！必须分析 Layout Intent 后再转换。**
+### 常见 Flutter 故障案例
 
-```
-测量 → Layout Intent → Flutter 映射 → Token 替换 → 验证
-```
+- `sketch-fontweight-mapping`
+- `sketch-svg-bitmap-export`
+- `textfield-vertical-centering`
+- `input-focus-background-color`
 
-### 配合 Sketch MCP 使用测量模板
+如果用户描述的是真实故障，优先 `troubleshoot`，再按需加载具体案例或规范。
 
-| 场景 | 模板 | 计算示例 |
-|------|------|---------|
-| 行高 | `component-measurement.js` | `height = 文本高度/字号 = 20/14 = 1.43` |
-| 间距 | `gap-measurement.js` | 检测是否统一间距 → 用 `Gap()` |
-| 居中 | 计算上下边距 | 相等则用 `Alignment.center` |
+---
 
-### 快速提示
+## 🧠 增强工具使用指南
 
-| 关键点 | 说明 |
-|--------|------|
-| **布局选择** | 测量元素 Y/X 坐标，不同则用 `Stack + Positioned`，相同才用 `Row/Column` |
-| **还原原则** | 还原视觉效果，不是参数 - 参数正确不代表效果正确 |
-| **渐变色** | 检查 `fillType` 后读取 `gradient.stops`，勿直接用 `color` 属性 |
-| **全局样式** | 还原前先 grep 搜索项目现有 Token（颜色、圆角、阴影） |
-| **新拟态阴影** | 双阴影：右下深色 + 左上高光 |
-| **行高** | Flutter `height` 是比例值，非像素（如 24px/16px = 1.5） |
+复杂场景可以补用增强能力，但不要把它们当默认入口：
 
-### 🔴 布局选择原则（核心）
+### 知识图谱记忆
 
-**当同一行/列的元素有不同的 top/left 值时，必须使用 Stack + Positioned！**
+适用于：记录项目偏好、UI 约束、设计还原结论、组件约定。
 
-```
-❌ Row/Column: 强制元素对齐到同一轴线，丢失独立位置控制
-✅ Stack + Positioned: 每个元素可独立定位到设计稿指定位置
-```
+### 顺序思考
 
-> 📖 **详细规范**：`get_standard_by_id({ id: 'design-restoration' })` → "布局选择原则" 章节
+适用于：
 
-### 相关规范
+- 大型重构规划
+- 疑难问题定位
+- 多步骤设计还原或复杂依赖分析
 
-| 规范 | 调用方式 |
-|------|----------|
-| 设计稿还原流程 | `get_standard_by_id({ id: 'design-restoration' })` |
-| Sketch MCP 用法 | `get_standard_by_id({ id: 'sketch-mcp' })` |
-| 跨框架语法映射 | `get_standard_by_id({ id: 'syntax-mapping' })` |
+原则：只有在问题确实复杂时才使用，不要对简单 Flutter 请求强行套分步推理。
 
 ---
 
-## 🧠 增强工具使用指南
+## 🎯 维护原则
 
-> MTA 集成了 Memory 和 Sequential Thinking 能力，可在复杂场景中使用
-
-### 知识图谱记忆（mcp_memory_*）
-
-| 场景 | 推荐工具 | 用法 |
-|------|----------|------|
-| 记录项目偏好 | `mcp_memory_create_entities` | 创建实体保存用户偏好、项目配置 |
-| 关联技术栈 | `mcp_memory_create_relations` | 建立实体间关系（项目→使用→框架） |
-| 查找历史 | `mcp_memory_search_nodes` | 搜索之前记录的信息 |
-| 获取完整上下文 | `mcp_memory_read_graph` | 读取整个知识图谱 |
-
-### 顺序思考（mcp_sequential-th_sequentialthinking）
-
-| 场景 | 何时使用 |
-|------|----------|
-| 复杂架构设计 | 需要多步骤推理时 |
-| 疑难问题诊断 | 问题原因不明确时 |
-| 大型重构规划 | 需要系统性思考时 |
+- Agent 负责引导获取规范与流程入口
+- 详细规范放 `standards/`
+- 详细故障方案放 `mcp-server/troubleshooting/`
+- 不再把长篇案例、图标表、像素级映射常驻在 Agent 主体中
 
 ---
 
 **维护团队**: MTA工作室  
-**设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取
+**设计理念**: Agent 只保留 Flutter 开发的高频路由、关键边界和规范入口；详细能力通过 standards 与 troubleshooting 动态加载