mta-mcp 3.16.4 → 3.17.0

package/agents/flutter.agent.md

@@ -8,7 +8,7 @@ user-invocable: true
 # Flutter 开发代理
 
 > 此 Agent 引导 AI 通过 MCP 工具获取 Flutter / Dart 开发规范、设计还原流程与故障排查方案
-> 版本: v5.0.0 | 最后更新: 2026-03-19
+> 版本: v5.1.0 | 最后更新: 2026-03-20
 
 > 说明：这是供复制到项目 `.github/agents/` 或通过 `npm:mta-mcp/agents/flutter.agent.md` 引用的发布型 Agent，引导获取规范与流程入口，而不是本仓库 `.github/agents/` 下的 live 维护 Agent。
 
@@ -121,6 +121,12 @@ Flutter 设计稿还原必须遵循 measure-first 流程，禁止直接凭截图
 6. compact 不够解释局部样式时，再补 measure / style
 ```
 
+补充执行细节：
+
+- 不要手动拼接 `_SKETCH_CMD` 或回退到旧测量脚本，Sketch 入口以 `sketch_measure` 返回结果为准
+- `bodyCopyLedger` / `navCopyLedger` 默认视为文案真值，禁止直接换成现有页面标题、业务分组名或路由文案
+- 如果通用页面壳会自动带出多余 section、标题或 CTA，优先做贴合设计稿的局部实现，不要为了复用把结构带偏
+
 ### 详细规范补加载顺序
 
 - 设计稿还原首轮：`get_standard_by_id({ id: 'design-restoration' })` + `get_standard_by_id({ id: 'sketch-mcp' })`
@@ -133,18 +139,25 @@ Flutter 设计稿还原必须遵循 measure-first 流程，禁止直接凭截图
 - 如果存在 `topPrimaryEntry`，禁止擅自迁移成底部固定按钮
 - 如果 `bottomNavigation.present=true` 且 contract 未声明额外 bottom CTA，禁止再叠加一层底部固定操作条
 - 搜索框、输入框、选择器、Tab、提交按钮必须至少具备最小可用交互，不能只还原成静态容器
-- 先搜项目现有素材目录，再决定是否新增资产；`@2x/@3x/@4x` 是倍率后缀，不是新语义
+- 图标和顶部入口先搜项目现有素材目录，再决定是否新增资产；`@2x/@3x/@4x` 只是倍率后缀，不是主体语义
 - Sketch 测得是 `Image` 时，必须按位图处理，禁止伪造为 SVG
+- `Image` 类型的 help/customer-service/support/button/arrow 入口，优先按设计稿图层名主体查找现有 PNG，不要先做语义联想或 canonical 合并
+- `Help Button`、`Customer Service Button`、`Customer Service Icon` 不能只因为位置相近就复用成同一语义资源
 - 如果 `bitmapLookupCandidates` 与现有素材都未命中，必须明确说明“设计资产未确认”，不要回退到语义相近资源
+- 顶部关键位图入口落地时，必须明确写出测得块名和最终采用的 assetPath；未确认前禁止继续猜图标
 - 如果测量结果给出 `iconContentBounds.containerSize` 与 `contentSize`，必须分离占位尺寸与图形渲染尺寸，不能直接用 `Group frame` 作为图标尺寸
+- 如果存在 `siblingIconAlignment.maxSlotSize`，同行 Icon 先统一槽位，再在槽位内居中实际图形尺寸，避免文字错位
 - 如果 `iconSvgMeta.colorStrategy=preserve`，或 SVG 含多色/透明度/渐变路径，禁止再加 `ColorFilter`
+- 带 `<filter>`、整按钮阴影或页面级 transform 的 SVG，不要直接当普通 `SvgPicture.asset` 贴上去；优先还原容器，再单独处理箭头/路径
 
 ### 高频硬边界
 
-- 先搜项目现有素材目录，再决定是否新增资产
+- 先按设计稿块名主体搜现有素材，关键位图入口不做语义猜测
 - Sketch 测得是 `Image` 时，禁止伪造为 SVG
-- `restorationContract` 优先于现有页面标题、分组和 CTA 习惯
+- `restorationContract` 与 copy ledgers 优先于现有页面标题、分组和 CTA 习惯
 - 顶部入口不能擅自迁移成底部固定按钮
+- Icon 必须区分槽位尺寸与图形尺寸；同行 Icon 要统一槽位
+- preserve SVG 禁止二次染色
 - 搜索框、输入框、选择器、Tab、提交按钮必须至少具备最小可用交互
 - 设计资产未确认时必须停止说明，不能靠语义猜图标
 
@@ -154,6 +167,8 @@ Flutter 设计稿还原必须遵循 measure-first 流程，禁止直接凭截图
 - 结构与业务语义冲突：`get_standard_by_id({ id: 'design-restoration' })`
 - 测量字段与 Flutter 映射：`get_standard_by_id({ id: 'sketch-mcp' })`
 - 跨端语法转换：`get_standard_by_id({ id: 'syntax-mapping' })`
+- 位图入口、旧资源复用或 help/customer-service 语义混用：`get_standard_by_id({ id: 'sketch-pitfalls' })`
+- preserve SVG 被二次染色、viewBox 偏移或多色图标异常：先 `troubleshoot`，再补 `get_standard_by_id({ id: 'sketch-pitfalls' })`
 
 ---
 
@@ -168,6 +183,8 @@ Flutter 设计稿还原必须遵循 measure-first 流程，禁止直接凭截图
 - ✅ 复杂问题先诊断，再改代码
 - ✅ 设计稿还原先服从 `restorationContract`
 - ✅ 优先复用现有资产与项目模式
+- ✅ 关键位图入口先给出测得块名与 assetPath，再决定是否继续还原
+- ✅ 高交互控件至少补最小可用行为，即使先用本地状态或占位数据
 
 ### 禁止
 
@@ -176,6 +193,8 @@ Flutter 设计稿还原必须遵循 measure-first 流程，禁止直接凭截图
 - ❌ 用 `Group frame` 直接当作 Icon 渲染尺寸
 - ❌ 用现有业务语义覆盖设计稿骨架
 - ❌ 对复杂状态仍然直接堆 `setState`
+- ❌ 把 help/customer-service/support 这类 `Image` 入口替换成语义相近但来源不明的旧位图
+- ❌ 对 preserve SVG 再套统一 `ColorFilter`
 
 ### Token 快捷方式