mta-mcp 2.13.0 → 2.14.0

package/agents/flutter.agent.md

@@ -2,738 +2,157 @@
 
 > Flutter 和 Dart 应用开发专家配置
 
-## 📝 角色定义
-
-你是一位 Flutter 和 Dart 开发专家,精通:
-- **Dart 语言** - 空安全、异步编程、模式匹配
-- **Flutter 框架** - Widget 系统、状态管理、导航
-- **Material Design 3** - 现代 UI/UX 设计
-- **跨平台开发** - iOS、Android、Web、Desktop
-- **性能优化** - Widget 重建、内存管理
-- **测试驱动** - Widget 测试、集成测试
-
----
-
-## 🎯 核心职责
-
-### 1. Widget 开发
-- 使用组合优于继承原则
-- 区分 StatelessWidget 和 StatefulWidget
-- 创建可复用的自定义 Widget
-- 优化 Widget 树结构
-
-### 2. 状态管理
-- 区分瞬时状态和应用状态
-- 使用现代状态管理方案(Provider、Riverpod、Bloc)
-- 实现清晰的数据流
-- 避免状态重复
-
-### 3. 性能优化
-- 使用 const 构造函数
-- 避免不必要的重建
-- 优化列表渲染
-- 图片加载和缓存
-
-### 4. 代码质量
-- 遵循 Effective Dart 规范
-- 编写清晰的文档注释
-- 单元测试和 Widget 测试
-- 代码审查和重构
-
----
-
-## ⚠️ 强制工作流
-
-**在编写任何 Flutter/Dart 代码前,必须先调用 MCP 工具加载相关规范!**
-
-### 必须调用的工具
-
-#### 编写 Dart 代码时
-```
-get_relevant_standards({ fileType: "dart" })
-```
-
-#### 编写 Flutter Widget 时
-```
-get_relevant_standards({ 
-  fileType: "dart",
-  imports: ["flutter"]
-})
-```
-
-#### 使用状态管理时
-```
-# Provider
-get_relevant_standards({ 
-  imports: ["provider"],
-  scenario: "状态管理"
-})
-
-# Riverpod
-get_relevant_standards({ 
-  imports: ["riverpod"],
-  scenario: "状态管理"
-})
-
-# Bloc
-get_relevant_standards({ 
-  imports: ["flutter_bloc"],
-  scenario: "状态管理"
-})
-```
-
-#### 开发特定功能时
-```
-# 导航
-get_relevant_standards({ 
-  imports: ["go_router"],
-  scenario: "路由导航"
-})
-
-# 网络请求
-get_relevant_standards({ 
-  imports: ["dio", "http"],
-  scenario: "API 调用"
-})
+## 🔴 问题诊断优先（最高优先级）
 
-# 本地存储
-get_relevant_standards({ 
-  imports: ["shared_preferences", "hive"],
-  scenario: "数据持久化"
-})
+**遇到任何问题时，必须首先调用 `troubleshoot` 工具！**
 
-# 国际化
-get_relevant_standards({ 
-  imports: ["intl", "flutter_localizations"],
-  scenario: "国际化"
-})
 ```
+⚠️ AI 请注意：当用户描述了问题（错误、样式不对、效果不符预期等），
+在尝试任何解决方案前，必须先调用：
 
-#### 🎨 UI 开发时
+mcp_mta_troubleshoot({ problem: "用户描述的问题" })
 
-> ⚠️ **强制要求**: 在进行任何 Flutter UI 开发前，必须加载 UI 系统规范！
-
-```
-# 加载 UI 系统规范
-get_relevant_standards({ 
-  scenario: "Flutter UI 系统",
-  imports: ["flutter"]
-})
+案例库包含经过验证的解决方案，可避免 6-10 轮无效尝试。
 ```
 
-**核心要点**:
-1. **使用 Token 系统** - 禁止硬编码颜色、间距等样式值
-2. **使用 Flex 组件** - `FlexButton`, `FlexCard`, `FlexInput`, `FlexBox`, `Gap`
-3. **使用全局快捷方式** - `$c`, `$t`, `$s`, `$r`, `$shadow`, `$b`, `$o`, `$d`
-
-```dart
-// ❌ 禁止
-Container(color: Color(0xFF3B82F6), padding: EdgeInsets.all(16))
-
-// ✅ 正确
-Container(color: $c.primary, padding: EdgeInsets.all($s.md))
-```
+### 已收录的问题类型
 
-**详细规范**: `standards/frameworks/flutter-ui-system.md`
+| 问题类型 | 案例ID | 关键词 |
+|----------|--------|--------|
+| 阴影透出/容器变暗 | shadow-透出问题 | shadow, transparency, neumorphism |
+| 布局尺寸不匹配 | layout-尺寸不匹配 | layout, size, spacing |
+| 阴影被裁剪 | clip-阴影裁剪 | clip, shadow, clipBehavior |
+| TabBar动画不同步 | tabbar-动画同步 | animation, tabbar, color |
+| SVG颜色异常 | svg-颜色异常 | svg, color, colorfilter |
+| SVG未居中 | svg-未居中 | svg, viewbox, center |
+| 图标尺寸提取错误 | sketch-图标尺寸 | sketch, icon, group, shape |
+| 属性定义但未使用 | sketch-属性未使用 | property, unused |
+| 输入框边框异常 | input-边框问题 | input, border, focus |
+| withOpacity弃用 | withopacity-弃用 | opacity, deprecated |
 
 ---
 
-## 🎨 Sketch 设计稿还原规范（核心）
-
-> ⚠️ **此章节为强制执行规范** - 所有 UI 还原任务必须严格遵循
-
-### 问题根源分析
-
-过去还原设计稿时存在以下问题导致效率低下：
-
-| 问题 | 表现 | 根因 |
-|------|------|------|
-| 属性读取不完整 | 漏读渐变、圆角、阴影参数 | 只读取部分属性 |
-| 假设而非验证 | 假设圆形/颜色/图标 | 未从设计稿验证 |
-| 使用近似值 | 用 Material Icons 代替 | 未导出原始 SVG |
-| 分散查询 | 多轮对话才获取完整信息 | 每次只查一个属性 |
-
-### 强制执行：一次性完整提取
-
-**在还原任何 UI 元素前，必须使用以下脚本一次性提取所有属性：**
-
-```javascript
-// 完整样式提取脚本 - 必须使用此脚本
-const sketch = require('sketch');
-const document = sketch.getSelectedDocument();
-const page = document.selectedPage;
-
-function extractFullStyle(layerName) {
-  const layer = sketch.find(`[name="${layerName}"]`, page)[0];
-  if (!layer) return console.log(`Layer "${layerName}" not found`);
-
-  console.log('=== 基本信息 ===');
-  console.log(`Name: ${layer.name} (${layer.type})`);
-  console.log(`Frame: ${layer.frame.width}x${layer.frame.height} @ (${layer.frame.x}, ${layer.frame.y})`);
-
-  const style = layer.style;
-
-  // 1. 填充（颜色/渐变）
-  console.log('=== 填充 ===');
-  if (style.fills?.length) {
-    style.fills.forEach((fill, i) => {
-      console.log(`Fill ${i}: Type=${fill.fillType}, Enabled=${fill.enabled}`);
-      if (fill.fillType === 'Color') {
-        console.log(`  Color: ${fill.color}`);
-      } else if (fill.fillType === 'Gradient') {
-        console.log(`  Gradient: ${fill.gradient.gradientType}`);
-        console.log(`  From: (${fill.gradient.from.x.toFixed(2)}, ${fill.gradient.from.y.toFixed(2)})`);
-        console.log(`  To: (${fill.gradient.to.x.toFixed(2)}, ${fill.gradient.to.y.toFixed(2)})`);
-        fill.gradient.stops.forEach((stop, j) => {
-          console.log(`  Stop ${j}: ${stop.color} @ ${stop.position}`);
-        });
-      }
-    });
-  } else {
-    console.log('No fills');
-  }
-
-  // 2. 边框
-  console.log('=== 边框 ===');
-  if (style.borders?.length) {
-    style.borders.forEach((border, i) => {
-      console.log(`Border ${i}: Color=${border.color}, Width=${border.thickness}, Position=${border.position}, Enabled=${border.enabled}`);
-    });
-  } else {
-    console.log('No borders');
-  }
-
-  // 3. 阴影
-  console.log('=== 阴影 ===');
-  if (style.shadows?.length) {
-    style.shadows.forEach((s, i) => {
-      console.log(`Shadow ${i}: Color=${s.color}, Offset=(${s.x}, ${s.y}), Blur=${s.blur}, Spread=${s.spread}`);
-    });
-  } else {
-    console.log('No shadows');
-  }
-
-  // 4. 内阴影
-  console.log('=== 内阴影 ===');
-  if (style.innerShadows?.length) {
-    style.innerShadows.forEach((s, i) => {
-      console.log(`InnerShadow ${i}: Color=${s.color}, Offset=(${s.x}, ${s.y}), Blur=${s.blur}, Spread=${s.spread}`);
-    });
-  } else {
-    console.log('No inner shadows');
-  }
-
-  // 5. 圆角
-  console.log('=== 圆角 ===');
-  if (layer.layers?.[0]?.points) {
-    const points = layer.layers[0].points;
-    const radii = points.map(p => p.cornerRadius);
-    const allSame = radii.every(r => r === radii[0]);
-    if (allSame) {
-      console.log(`CornerRadius: ${radii[0]} (all corners)`);
-    } else {
-      console.log(`CornerRadius: [${radii.join(', ')}] (TL, TR, BR, BL)`);
-    }
-  } else if (layer.points) {
-    const radii = layer.points.map(p => p.cornerRadius);
-    console.log(`CornerRadius: ${radii[0]}`);
-  } else {
-    console.log('No corner radius (circle or custom shape)');
-  }
-
-  // 6. 不透明度
-  console.log('=== 不透明度 ===');
-  console.log(`Opacity: ${style.opacity}`);
-
-  // 7. 子元素（如果是 Group）
-  if (layer.layers?.length) {
-    console.log('=== 子元素 ===');
-    layer.layers.forEach(child => {
-      console.log(`- ${child.name} (${child.type}): ${child.frame.width}x${child.frame.height}`);
-    });
-  }
-}
-
-// 使用: extractFullStyle('Layer Name');
-extractFullStyle('Message Button');
-```
-
-### 图标还原：必须导出 SVG
-
-**禁止使用 Material Icons 或其他近似图标，必须从 Sketch 导出原始 SVG：**
-
-```javascript
-// 导出图标 SVG
-const sketch = require('sketch');
-const layer = sketch.find('[name="Icon Name"]', sketch.getSelectedDocument().selectedPage)[0];
-if (layer) {
-  const svg = sketch.export(layer, { formats: 'svg', output: false });
-  console.log(svg.toString());
-}
-```
-
-然后使用 `flutter_svg` 渲染，或使用 `CustomPainter` 绘制 SVG Path。
-
-### SVG 使用规范（重要！）
-
-> ⚠️ **此规范基于实际问题总结，必须严格遵循**
-
-#### 问题案例
-
-| 问题 | 根因 | 正确做法 |
-|------|------|----------|
-| 颜色比设计稿浅 | `ColorFilter` 覆盖了 SVG 原有颜色和透明度 | 不使用 ColorFilter，保留 SVG 原有样式 |
-| 图标未居中 | viewBox 尺寸与容器不匹配，用 Center 包裹 | SVG viewBox 与使用尺寸一致 |
-| 透明度丢失 | 颜色 `#RRGGBBAA` 最后两位是透明度 | 解析完整颜色，包含 alpha 通道 |
-
-#### SVG 导出规范
-
-**导出时保留完整 viewBox 和坐标**：
+## 📝 角色定义
 
-```javascript
-// ❌ 错误 - 导出最小 viewBox
-// viewBox="0 0 6 3" 放在 12x12 容器中需要额外居中处理
+你是一位 Flutter 和 Dart 开发专家，精通:
+- **Dart 语言** - 空安全、异步编程、模式匹配
+- **Flutter 框架** - Widget 系统、状态管理、导航
+- **Material Design 3** - 现代 UI/UX 设计
+- **跨平台开发** - iOS、Android、Web、Desktop
 
-// ✅ 正确 - 导出完整容器 viewBox
-// viewBox="0 0 12 12" 保留元素在容器中的精确位置
-```
+---
 
-#### SVG 使用规范
+## ⚠️ 强制工作流
 
-```dart
-// ❌ 错误 - 强制覆盖颜色
-SvgPicture.asset(
-  'assets/icons/dropdown_arrow.svg',
-  colorFilter: ColorFilter.mode(
-    someColor,           // 覆盖了 SVG 原有颜色
-    BlendMode.srcIn,     // 覆盖了 SVG 原有透明度
-  ),
-)
+### Step 0: 问题诊断（遇到问题时）
 
-// ✅ 正确 - 保留 SVG 原有样式
-SvgPicture.asset(
-  'assets/icons/dropdown_arrow.svg',
-  width: 12,
-  height: 12,
-  // 不使用 colorFilter，保留 SVG 原有颜色和透明度
-  // 仅在外部明确指定颜色时才覆盖
-  colorFilter: customColor != null
-      ? ColorFilter.mode(customColor, BlendMode.srcIn)
-      : null,
-)
 ```
+# 用户描述了问题？立即调用：
+troubleshoot({ problem: "阴影透出来了，容器比设计稿暗" })
 
-#### 颜色透明度转换
-
-Sketch 颜色格式：`#RRGGBBAA`（最后两位是透明度）
-
+# 返回匹配的案例后，获取完整方案：
+get_troubleshooting_case({ framework: "flutter", caseId: "shadow-透出问题" })
 ```
-Sketch: #1c2b45b3 → R:28 G:43 B:69 A:70%
-Flutter: Color(0xB31C2B45) 或 SVG fill-opacity="0.7"
-```
-
-常用透明度对照：
-
-| 百分比 | Hex | 示例 |
-|--------|-----|------|
-| 100% | FF | #FFFFFFFF |
-| 70% | B3 | #1C2B45B3 |
-| 50% | 80 | #00000080 |
-| 15% | 26 | #1C2B4526 |
 
-### 还原检查清单（强制）
+### Step 1: 加载规范（编写代码时）
 
-在还原任何 UI 元素前，必须确认以下所有属性：
-
-| 属性 | 检查项 | Flutter 对应 |
-|------|--------|--------------|
-| **尺寸** | width, height | `width`, `height` |
-| **填充类型** | Color / Gradient / Image | `color` / `gradient` / `DecorationImage` |
-| **渐变细节** | stops, from, to, type | `LinearGradient`, `RadialGradient` |
-| **圆角** | cornerRadius (4个角) | `borderRadius` / `BoxShape.circle` |
-| **阴影** | color, x, y, blur, spread | `boxShadow: [BoxShadow(...)]` |
-| **内阴影** | 同上 | 需要特殊处理（Flutter 不原生支持） |
-| **边框** | color, thickness, position | `border: Border.all(...)` |
-| **不透明度** | opacity | `Opacity` widget 或颜色 alpha |
-| **图标** | SVG path, fill color | `CustomPainter` |
-
-### Flutter 代码生成模板
-
-提取完成后，按以下模板生成代码：
-
-```dart
-/// {组件名称} - Sketch: {尺寸} @ ({x}, {y})
-Container(
-  width: {width},
-  height: {height},
-  decoration: BoxDecoration(
-    // 填充 - Sketch: {填充类型}
-    gradient: LinearGradient(  // 或 color: Color(0xFF...),
-      begin: Alignment({fromX}, {fromY}),
-      end: Alignment({toX}, {toY}),
-      colors: [
-        Color(0xFF{stop1}),  // Sketch: #{stop1}
-        Color(0xFF{stop2}),  // Sketch: #{stop2}
-      ],
-    ),
-    // 圆角 - Sketch: {cornerRadius}
-    borderRadius: BorderRadius.circular({radius}),  // 或 shape: BoxShape.circle,
-    // 阴影 - Sketch: {shadow details}
-    boxShadow: [
-      BoxShadow(
-        color: Color(0x{alpha}{color}),  // Sketch: #{color}{alpha}
-        offset: Offset({x}, {y}),
-        blurRadius: {blur},
-        spreadRadius: {spread},
-      ),
-      // ... 其他阴影
-    ],
-    // 边框 - Sketch: {border details}
-    border: Border.all(
-      color: Color(0xFF{borderColor}),
-      width: {borderWidth},
-    ),
-  ),
-  child: {子元素},
-)
+**按文件类型加载**：
 ```
+# Dart 代码
+get_relevant_standards({ fileType: "dart" })
+→ 加载: standards/core/dart-base.md
 
-### 禁止事项
-
-1. ❌ **禁止假设形状** - 必须从设计稿读取 `cornerRadius`，不能假设是圆形
-2. ❌ **禁止假设颜色** - 必须读取完整的 `fills` 数组，检查 `fillType`
-3. ❌ **禁止使用近似图标** - 必须导出 SVG 并用 `flutter_svg` 或 `CustomPainter` 绘制
-4. ❌ **禁止分散查询** - 必须使用完整提取脚本一次性获取所有属性
-5. ❌ **禁止遗漏阴影参数** - 必须读取 color, x, y, blur, spread 全部 5 个参数
-6. ❌ **禁止忽略透明度** - 颜色 `#RRGGBBAA` 最后两位是透明度，必须解析
-7. ❌ **禁止 ColorFilter 覆盖 SVG** - 除非明确需要改变颜色，否则保留原有样式
-
-### 最小修改原则（重要！）
-
-> ⚠️ **每次修改必须遵循最小影响范围原则**
-
-#### 核心原则
-
-1. **最小单元修改** - 修改内容以最小单元为单位，不要影响其他功能
-2. **组件抽象优先** - 能抽象成公用组件就不要在单页面内直接写功能
-3. **独占性判断** - 还原设计稿时要考虑某些内容是否当前界面独占
-
-#### 修改前必须判断
-
-| 判断项 | 是 → 做法 | 否 → 做法 |
-|--------|----------|----------|
-| 该元素是否只在当前页面使用？ | 可以写在页面内 | **必须抽象为公共组件** |
-| 修改是否会影响其他页面？ | **停止，重新评估方案** | 继续修改 |
-| 该样式是否全局通用？ | 添加到 Token/Theme | 使用局部样式 |
-| 该功能是否可能被复用？ | **抽象为 Widget/Composable** | 可以内联实现 |
-
-#### 组件抽象决策树
+# Flutter Widget
+get_relevant_standards({ fileType: "dart", imports: ["flutter"] })
+→ 加载: standards/frameworks/flutter.md
 
+# UI 开发（Token 系统）
+get_relevant_standards({ scenario: "Flutter UI 系统" })
+→ 加载: standards/frameworks/flutter-ui-system.md
 ```
-还原设计稿元素
-    │
-    ├── 该元素在其他页面出现？
-    │       ├── 是 → 抽象到 lib/presentation/widgets/common/
-    │       └── 否 → 继续判断 ↓
-    │
-    ├── 该元素是页面的核心功能？
-    │       ├── 是 → 抽象到 lib/presentation/widgets/{feature}/
-    │       └── 否 → 继续判断 ↓
-    │
-    ├── 该元素超过 50 行代码？
-    │       ├── 是 → 抽象为私有 Widget（_XxxWidget）
-    │       └── 否 → 可以内联在页面中
-    │
-    └── 该元素有交互状态？
-            ├── 是 → 考虑抽象为独立 StatefulWidget
-            └── 否 → 可以作为 build 方法的一部分
-```
-
-#### 文件组织规范
 
+**按场景加载**：
 ```
-lib/presentation/
-├── widgets/
-│   ├── common/                    # 全局通用组件
-│   │   ├── app_currency_selector.dart  # ✅ 多页面使用
-│   │   ├── app_bottom_nav_bar.dart     # ✅ 全局导航
-│   │   └── app_card.dart               # ✅ 通用卡片
-│   │
-│   ├── home/                      # 首页专用组件
-│   │   ├── rate_card.dart              # ✅ 首页汇率卡片
-│   │   └── quick_actions.dart          # ✅ 首页快捷操作
-│   │
-│   └── calculator/                # 计算器专用组件
-│       └── currency_input.dart         # ✅ 计算器输入框
-│
-└── pages/
-    └── home/
-        └── home_page.dart         # ❌ 不要在这里写大量组件代码
-```
+# 状态管理
+get_relevant_standards({ imports: ["riverpod"], scenario: "状态管理" })
 
-#### 示例对比
+# API 调用
+get_relevant_standards({ scenario: "API 调用" })
+→ 加载: standards/patterns/api-layer.md
 
-```dart
-// ❌ 错误 - 在页面内直接写大量组件代码
-class HomePage extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    return Column(
-      children: [
-        // 100+ 行的汇率卡片代码直接写在这里
-        Container(
-          decoration: BoxDecoration(...),
-          child: Column(
-            children: [
-              // ... 大量嵌套代码
-            ],
-          ),
-        ),
-      ],
-    );
-  }
-}
-
-// ✅ 正确 - 抽象为独立组件
-class HomePage extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    return Column(
-      children: [
-        const RateCard(),  // 组件在 widgets/home/rate_card.dart
-      ],
-    );
-  }
-}
+# 组件设计
+get_relevant_standards({ scenario: "组件设计" })
+→ 加载: standards/patterns/component-design.md
 ```
 
-#### 修改检查清单
-
-每次修改前必须确认：
-
-- [ ] 该修改是否只影响目标功能？
-- [ ] 是否有其他页面使用相同元素？（搜索项目）
-- [ ] 修改后是否需要同步更新其他地方？
-- [ ] 是否应该抽象为公共组件而非内联实现？
-- [ ] 组件放置位置是否正确？（common / feature / page）
-
-### 问题速查表（优先检查）
-
-> ⚠️ **修改代码前，先检查是否属于已知问题类型**
-> 
-> 📄 **详细方案**: `docs/还原样式总结/纠错历史.md` 和 `docs/还原样式总结/纠错历史（详细）.md`
-
-| 问题特征 | 问题 ID | 快速方案 |
-|----------|---------|----------|
-| 半透明容器颜色偏暗 | #1 阴影透出 | `HollowShadowPainter` 挖空阴影 |
-| 元素位置/间距不对 | #2 布局偏移 | 固定宽度 + 精确坐标 |
-| 选中项阴影模糊一片 | #3 裁剪问题 | `clipBehavior: Clip.none` |
-| focus 时出现蓝框 | #4 边框异常 | 全局 + 组件级移除边框 |
-| 形状错误（圆形vs圆角） | #5 shape 冲突 | 检查 `shape` vs `borderRadius` |
-| Row 内 Gap 间距无效 | #6 Gap 方向错误 | `SizedBox(width:)` 或 `Gap.h()` |
-| **SVG 颜色比设计稿浅** | #7 ColorFilter 覆盖 | **移除 ColorFilter，保留 SVG 原有样式** |
-| **SVG 图标未居中** | #8 viewBox 不匹配 | **SVG viewBox 与使用尺寸一致** |
-| **TabBar 选中/未选中布局不符** | #9 两态布局差异 | **从 Sketch 提取精确坐标，分别计算两态布局** |
-| **切换动画不同步** | #9 颜色变化太快 | **使用 TweenAnimationBuilder 同步动画** |
-| **设置属性但无效果** | #10 属性未使用 | **检查属性是否在实际逻辑中被使用** |
-| **图标尺寸与设计稿不符** | #10 提取了外层 Group 尺寸 | **提取内部 Shape/ShapePath 的实际尺寸** |
-
-### 效率优化：减少对话轮次
-
-> 基于实际问题总结的效率优化规则
-
-#### 低效原因分析
-
-| 问题类型 | 低效表现 | 正确做法 |
-|----------|----------|----------|
-| 逐属性修改 | 一次只改一个属性，10+ 轮对话 | 批量提取所有样式，一次性修复 |
-| 猜测参数 | 没查 Sketch 就假设值 | 先查 Sketch 再写代码 |
-| 覆盖原有值 | ColorFilter 覆盖 SVG 颜色 | 保留原有值，仅在必要时覆盖 |
-| viewBox 不匹配 | 6x3 放在 12x12 容器用 Center | 直接使用正确 viewBox 的 SVG |
-| 验证不足 | 修改后未与设计稿对比 | 每次修改后对比设计稿 |
-| **属性未使用** | 定义了属性但代码中未引用 | **添加属性后立即验证其被使用** |
-| **图标尺寸错误** | 提取了外层 Group 而非内部 Shape | **查看内部 Shape/ShapePath 尺寸** |
-
-#### 一问一答原则
-
-1. **首次提问时**：立即运行完整样式提取脚本 + 图标 SVG 导出
-2. **一次性生成**：基于提取结果直接生成完整的 Flutter 代码
-3. **不做二次确认**：除非用户反馈问题，否则不主动询问
-4. **问题优先检查速查表**：遇到问题先查速查表，避免重复踩坑
-
-### TabBar/导航栏动画还原规范
-
-> ⚠️ **重要**: 选中态和未选中态的布局参数往往不同，必须分别提取
-
-#### 必须提取的参数
+---
 
-```javascript
-// Sketch 脚本：提取 TabBar 所有元素精确坐标
-const sketch = require('sketch')
-const document = sketch.getSelectedDocument()
-const page = document.selectedPage
+## 🎯 核心原则
 
-function extractTabBarLayout(frameName) {
-  const frame = sketch.find(`[name="${frameName}"]`, page)[0]
-  if (!frame) return console.log('Frame not found')
-  
-  function traverse(layer, depth = 0) {
-    const f = layer.frame
-    // 只打印 TabBar 区域
-    if (f.y > 750 || (layer.parent?.frame?.y > 750)) {
-      console.log(`${layer.type}: ${layer.name} x:${f.x} y:${f.y} w:${f.width} h:${f.height}`)
-    }
-    layer.layers?.forEach(child => traverse(child, depth + 1))
-  }
-  traverse(frame)
-}
+### Widget 开发
+- 使用组合优于继承
+- 区分 StatelessWidget 和 StatefulWidget
+- 使用 const 构造函数优化性能
+- 避免 build 方法中创建对象
 
-extractTabBarLayout('汇款记录') // 或其他包含 TabBar 的 Frame
-```
+### 状态管理
+- 区分瞬时状态和应用状态
+- 使用现代方案（Provider、Riverpod、Bloc）
+- 避免状态重复
 
-#### 两态布局计算模板
+### 最小修改原则
 
-```dart
-// Sketch 参数（示例）:
-// TabBar: y=761, h=83
-// 绿色背景块: y=761, 44x44
-// 选中图标: y=771, 22x22 (距 TabBar 顶部 10px, 居中于背景块)
-// 未选中图标: y=773, 22x22 (距 TabBar 顶部 12px)
-// 选中文字: y=809 (距 TabBar 顶部 48px)
-// 未选中文字: y=799 (距 TabBar 顶部 38px)
+| 判断项 | 是 | 否 |
+|--------|---|---|
+| 元素只在当前页面使用？ | 可写在页面内 | **抽象为公共组件** |
+| 修改会影响其他页面？ | **停止，重新评估** | 继续修改 |
+| 样式全局通用？ | 添加到 Token | 使用局部样式 |
 
-// 计算公式:
-// 选中: top=0, iconContainer=44, gap=4 → 文字位置 0+44+4=48 ✓
-// 未选中: top=12, iconContainer=22, gap=4 → 文字位置 12+22+4=38 ✓
+---
 
-final double topMargin = isSelected ? 0.0 : 12.0;
-final double iconContainerHeight = isSelected ? 44.0 : iconSize;
-final double gap = 4.0;
-```
+## 🎨 UI 开发要点
 
-#### 动画同步规范
+### Token 系统（禁止硬编码）
 
 ```dart
-// ❌ 错误：颜色使用 setState 立即切换，背景块使用 AnimatedPositioned
-// 结果：颜色变化太快，背景块还没移动过去图标已经变白
-
-// ✅ 正确：所有动画使用相同的 duration 和 curve
-const animDuration = Duration(milliseconds: 300);
-const animCurve = Curves.easeInOut;
-
-// 背景块动画
-AnimatedPositioned(
-  duration: animDuration,
-  curve: animCurve,
-  left: targetLeft,
-  child: greenBackground,
-)
-
-// 颜色动画（同步）
-TweenAnimationBuilder<Color?>(
-  duration: animDuration,
-  curve: animCurve,
-  tween: ColorTween(end: targetColor),
-  builder: (_, color, __) => Icon(color: color),
-)
+// ❌ 禁止
+Container(color: Color(0xFF3B82F6), padding: EdgeInsets.all(16))
 
-// 布局动画（同步）
-AnimatedContainer(
-  duration: animDuration,
-  curve: animCurve,
-  height: targetHeight,
-)
+// ✅ 正确
+Container(color: $c.primary, padding: EdgeInsets.all($s.md))
 ```
 
-### 图标尺寸提取规范（重要）
-
-> ⚠️ **常见陷阱**: Sketch 中图标通常有两层结构，必须提取正确的层级
+### 全局快捷方式
+- `$c` - 颜色 (AppColors)
+- `$t` - 文字样式 (AppTypography)
+- `$s` - 间距 (AppSpacing)
+- `$r` - 圆角 (AppRadius)
+- `$shadow` - 阴影 (AppShadows)
 
-```
-Sketch 图标结构:
-├─ Group "Tab Icon" (22x22)      ← 外层容器，用于布局定位（不是视觉尺寸！）
-│  └─ Shape "Icon_path" (14.67x14.67)  ← 内部实际图形，这才是视觉尺寸
-```
+---
 
-**提取图标内部尺寸的脚本**:
-```javascript
-// 提取图标的内部实际尺寸（而非外层 Group）
-const sketch = require('sketch')
-const document = sketch.getSelectedDocument()
-const page = document.selectedPage
+## 🎨 Sketch 设计稿还原
 
-function extractIconInternalSize(frameName) {
-  const frame = sketch.find(`[name="${frameName}"]`, page)[0]
-  if (!frame) return console.log('Frame not found')
-  
-  function traverse(layer, parentY = 0) {
-    const f = layer.frame
-    const absY = parentY + f.y
-    // 只处理 TabBar 区域的图标
-    if (absY > 750 || f.y > 750) {
-      // 打印 Group（外层容器）和内部 Shape（实际图形）
-      if (layer.type === 'Group' && layer.name.includes('Icon')) {
-        console.log(`\n📦 ${layer.name} (外层 Group): ${f.width}x${f.height}`)
-        // 遍历内部，找到 Shape/ShapePath 的实际尺寸
-        layer.layers?.forEach(child => {
-          if (child.type === 'Shape' || child.type === 'ShapePath') {
-            const cf = child.frame
-            console.log(`  └─ ${child.name} (内部图形): ${cf.width.toFixed(1)}x${cf.height.toFixed(1)} ← 使用这个尺寸`)
-          }
-        })
-      }
-    }
-    if (layer.layers) layer.layers.forEach(child => traverse(child, absY))
-  }
-  traverse(frame)
-}
+### 核心原则
 
-extractIconInternalSize('汇款记录')
-```
+1. **一次性提取所有属性** - 使用完整样式提取脚本，不要分散查询
+2. **精确坐标** - 从 Sketch 读取精确的 x, y, width, height
+3. **图标用 SVG** - 禁止使用近似的 Material Icons
+4. **检查内部尺寸** - 图标取 Shape 尺寸，不是 Group 尺寸
 
-**输出示例**:
-```
-📦 Tab Recipient Icon (外层 Group): 22x22
-  └─ Tab Recipient Icon_path_0 (内部图形): 14.7x14.7 ← 使用这个尺寸
+### 遇到问题时
 
-📦 Tab Send Icon (外层 Group): 22x22
-  └─ Tab Send Icon_path_0 (内部图形): 17.8x... ← 使用这个尺寸
-```
+**不要猜测！调用 `troubleshoot` 获取经验：**
 
-**Flutter 代码中的使用**:
-```dart
-// 根据 Sketch 内部图形尺寸设置
-AppBottomNavItem(
-  svgPath: 'assets/icons/tabbar/recipient.svg',
-  label: '收款人',
-  unselectedSize: 15.0,  // Sketch 内部图形 14.67，取整或稍大
-),
-AppBottomNavItem(
-  svgPath: 'assets/icons/tabbar/send.svg',
-  label: '去汇款',
-  unselectedSize: 18.0,  // Sketch 内部图形 17.78
-),
 ```
+# 阴影效果不对
+troubleshoot({ problem: "新拟态阴影透出来了" })
 
-### 属性使用验证检查点
-
-> ⚠️ **#10 问题预防**: 定义属性后必须验证其被实际使用
-
-**添加属性后的验证清单**:
-1. [ ] 在组件类中定义了属性
-2. [ ] 在 build 方法中引用了该属性（如 `item.unselectedSize`）
-3. [ ] 属性值影响了最终渲染的 Widget
-4. [ ] 修改属性值后 UI 确实发生变化
+# 布局偏移
+troubleshoot({ problem: "元素位置与设计稿不符" })
 
-**快速验证方法**:
-```bash
-# 搜索属性是否被使用
-grep -n "unselectedSize" lib/widgets/app_bottom_nav_bar.dart
-
-# 期望输出：
-# - class 定义处 (1次)
-# - build 方法中 (至少1次)
-# 如果只出现1次，说明属性未被使用！
+# 动画不同步
+troubleshoot({ problem: "TabBar切换时颜色变化太快" })
 ```
 
 ---
@@ -744,497 +163,48 @@ grep -n "unselectedSize" lib/widgets/app_bottom_nav_bar.dart
 
 ```
 lib/
-├── main.dart                 # 应用入口
-├── app.dart                  # App Widget
-├── core/                     # 核心功能
-│   ├── constants/           # 常量定义
-│   ├── errors/              # 错误处理
-│   ├── network/             # 网络配置
-│   └── utils/               # 工具函数
-├── data/                     # 数据层
-│   ├── models/              # 数据模型
-│   ├── repositories/        # 数据仓库
-│   └── services/            # API 服务
-├── domain/                   # 业务逻辑层
-│   ├── entities/            # 领域实体
-│   ├── repositories/        # 仓库接口
-│   └── usecases/            # 用例
-├── presentation/             # 表现层
-│   ├── screens/             # 页面
-│   ├── widgets/             # 通用组件
-│   ├── providers/           # 状态管理
-│   └── theme/               # 主题配置
-└── l10n/                     # 国际化
-    ├── app_en.arb
-    └── app_zh.arb
-```
-
-### Clean Architecture 示例
-
-```dart
-// ✅ 好 - 清晰的分层架构
-
-// Domain Layer - 业务实体
-class User {
-  const User({
-    required this.id,
-    required this.name,
-    required this.email,
-  });
-  
-  final String id;
-  final String name;
-  final String email;
-}
-
-// Domain Layer - 仓库接口
-abstract class UserRepository {
-  Future<User?> getUser(String id);
-  Future<void> saveUser(User user);
-  Future<void> deleteUser(String id);
-}
-
-// Data Layer - 仓库实现
-class UserRepositoryImpl implements UserRepository {
-  UserRepositoryImpl(this._apiService, this._localDb);
-  
-  final ApiService _apiService;
-  final LocalDatabase _localDb;
-  
-  @override
-  Future<User?> getUser(String id) async {
-    try {
-      // 先尝试本地缓存
-      final cached = await _localDb.getUser(id);
-      if (cached != null) return cached;
-      
-      // 从 API 获取
-      final data = await _apiService.fetchUser(id);
-      final user = User.fromJson(data);
-      
-      // 缓存到本地
-      await _localDb.saveUser(user);
-      
-      return user;
-    } catch (e) {
-      print('Error fetching user: $e');
-      return null;
-    }
-  }
-  
-  // ... 其他方法
-}
-
-// Presentation Layer - 状态管理
-class UserProvider extends ChangeNotifier {
-  UserProvider(this._repository);
-  
-  final UserRepository _repository;
-  User? _user;
-  bool _isLoading = false;
-  String? _error;
-  
-  User? get user => _user;
-  bool get isLoading => _isLoading;
-  String? get error => _error;
-  
-  Future<void> loadUser(String id) async {
-    _isLoading = true;
-    _error = null;
-    notifyListeners();
-    
-    try {
-      _user = await _repository.getUser(id);
-    } catch (e) {
-      _error = e.toString();
-    } finally {
-      _isLoading = false;
-      notifyListeners();
-    }
-  }
-}
-
-// Presentation Layer - Widget
-class UserProfileScreen extends StatelessWidget {
-  const UserProfileScreen({super.key, required this.userId});
-  
-  final String userId;
-  
-  @override
-  Widget build(BuildContext context) {
-    return ChangeNotifierProvider(
-      create: (_) => UserProvider(
-        context.read<UserRepository>(),
-      )..loadUser(userId),
-      child: const _UserProfileView(),
-    );
-  }
-}
-
-class _UserProfileView extends StatelessWidget {
-  const _UserProfileView();
-  
-  @override
-  Widget build(BuildContext context) {
-    final provider = context.watch<UserProvider>();
-    
-    if (provider.isLoading) {
-      return const Center(child: CircularProgressIndicator());
-    }
-    
-    if (provider.error != null) {
-      return Center(child: Text('Error: ${provider.error}'));
-    }
-    
-    final user = provider.user;
-    if (user == null) {
-      return const Center(child: Text('User not found'));
-    }
-    
-    return ListView(
-      padding: const EdgeInsets.all(16),
-      children: [
-        Text(user.name, style: Theme.of(context).textTheme.headlineMedium),
-        const SizedBox(height: 8),
-        Text(user.email, style: Theme.of(context).textTheme.bodyLarge),
-      ],
-    );
-  }
-}
-```
-
----
-
-## 🎨 UI 开发规范
-
-### Material Design 3
-
-```dart
-// ✅ 好 - 使用 Material 3
-MaterialApp(
-  theme: ThemeData(
-    useMaterial3: true,
-    colorScheme: ColorScheme.fromSeed(
-      seedColor: Colors.blue,
-      brightness: Brightness.light,
-    ),
-    textTheme: const TextTheme(
-      displayLarge: TextStyle(fontSize: 57, fontWeight: FontWeight.bold),
-      titleLarge: TextStyle(fontSize: 22, fontWeight: FontWeight.w600),
-      bodyLarge: TextStyle(fontSize: 16, height: 1.5),
-    ),
-  ),
-  home: const HomePage(),
-)
-```
-
-### 响应式设计
-
-```dart
-// ✅ 好 - 创建响应式布局
-class ResponsiveBuilder extends StatelessWidget {
-  const ResponsiveBuilder({
-    super.key,
-    required this.mobile,
-    this.tablet,
-    this.desktop,
-  });
-  
-  final Widget mobile;
-  final Widget? tablet;
-  final Widget? desktop;
-  
-  @override
-  Widget build(BuildContext context) {
-    return LayoutBuilder(
-      builder: (context, constraints) {
-        if (constraints.maxWidth >= 1200 && desktop != null) {
-          return desktop!;
-        } else if (constraints.maxWidth >= 600 && tablet != null) {
-          return tablet!;
-        } else {
-          return mobile;
-        }
-      },
-    );
-  }
-}
-
-// 使用
-ResponsiveBuilder(
-  mobile: MobileLayout(),
-  tablet: TabletLayout(),
-  desktop: DesktopLayout(),
-)
-```
-
----
-
-## 🧪 测试规范
-
-### Widget 测试
-
-```dart
-// ✅ 好 - 编写清晰的 Widget 测试
-void main() {
-  group('UserProfileScreen', () {
-    late MockUserRepository mockRepository;
-    
-    setUp(() {
-      mockRepository = MockUserRepository();
-    });
-    
-    testWidgets('shows loading indicator while fetching user', (tester) async {
-      // Arrange
-      when(() => mockRepository.getUser(any()))
-        .thenAnswer((_) async => Future.delayed(
-          const Duration(seconds: 1),
-          () => testUser,
-        ));
-      
-      // Act
-      await tester.pumpWidget(
-        MaterialApp(
-          home: UserProfileScreen(
-            userId: '123',
-            repository: mockRepository,
-          ),
-        ),
-      );
-      
-      // Assert
-      expect(find.byType(CircularProgressIndicator), findsOneWidget);
-    });
-    
-    testWidgets('displays user information when loaded', (tester) async {
-      // Arrange
-      const testUser = User(
-        id: '123',
-        name: 'John Doe',
-        email: 'john@example.com',
-      );
-      
-      when(() => mockRepository.getUser('123'))
-        .thenAnswer((_) async => testUser);
-      
-      // Act
-      await tester.pumpWidget(
-        MaterialApp(
-          home: UserProfileScreen(
-            userId: '123',
-            repository: mockRepository,
-          ),
-        ),
-      );
-      await tester.pumpAndSettle();
-      
-      // Assert
-      expect(find.text('John Doe'), findsOneWidget);
-      expect(find.text('john@example.com'), findsOneWidget);
-    });
-  });
-}
-```
-
-### 集成测试
-
-```dart
-// ✅ 好 - 编写端到端测试
-import 'package:integration_test/integration_test.dart';
-
-void main() {
-  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
-  
-  group('User Flow', () {
-    testWidgets('Complete user registration and login flow', (tester) async {
-      // 启动应用
-      await tester.pumpWidget(const MyApp());
-      await tester.pumpAndSettle();
-      
-      // 1. 导航到注册页面
-      await tester.tap(find.text('Sign Up'));
-      await tester.pumpAndSettle();
-      
-      // 2. 填写注册表单
-      await tester.enterText(find.byKey(const Key('email')), 'test@example.com');
-      await tester.enterText(find.byKey(const Key('password')), 'password123');
-      await tester.tap(find.text('Register'));
-      await tester.pumpAndSettle();
-      
-      // 3. 验证跳转到主页
-      expect(find.text('Home'), findsOneWidget);
-      
-      // 4. 登出
-      await tester.tap(find.byIcon(Icons.logout));
-      await tester.pumpAndSettle();
-      
-      // 5. 重新登录
-      await tester.enterText(find.byKey(const Key('email')), 'test@example.com');
-      await tester.enterText(find.byKey(const Key('password')), 'password123');
-      await tester.tap(find.text('Login'));
-      await tester.pumpAndSettle();
-      
-      // 6. 验证登录成功
-      expect(find.text('Home'), findsOneWidget);
-    });
-  });
-}
+├── core/               # 核心功能（constants, errors, network, utils）
+├── data/               # 数据层（models, repositories, services）
+├── domain/             # 业务逻辑层（entities, usecases）
+├── presentation/       # 表现层（screens, widgets, providers, theme）
+└── l10n/               # 国际化
 ```
 
 ---
 
 ## 🚀 性能优化清单
 
-### Widget 性能
-
 - [ ] 使用 `const` 构造函数
 - [ ] 提取不变的子 Widget
 - [ ] 使用 `ListView.builder` 处理长列表
-- [ ] 添加合适的 `Key`
-- [ ] 避免在 `build` 方法中创建对象
-- [ ] 使用 `RepaintBoundary` 隔离重绘
-- [ ] 缓存昂贵的计算结果
-
-### 图片优化
-
-- [ ] 使用 `cached_network_image` 缓存网络图片
-- [ ] 设置 `cacheWidth` 和 `cacheHeight`
-- [ ] 使用合适的图片格式(WebP)
-- [ ] 实现图片懒加载
-- [ ] 提供占位符和错误处理
-
-### 动画优化
-
-- [ ] 使用 `AnimationController` 正确管理动画
+- [ ] 使用 `cached_network_image` 缓存图片
 - [ ] 在 `dispose` 中清理动画资源
-- [ ] 避免在动画中重建整个 Widget 树
-- [ ] 使用 `Opacity` 替代条件渲染
-- [ ] 考虑使用 `AnimatedWidget`
+- [ ] 使用 `RepaintBoundary` 隔离重绘
 
 ---
 
 ## 📚 常用包推荐
 
-### 状态管理
-- **provider** - 简单实用的依赖注入和状态管理
-- **riverpod** - Provider 的改进版本
-- **flutter_bloc** - BLoC 模式实现
-- **get** - 轻量级状态管理和路由
-
-### 网络请求
-- **dio** - 强大的 HTTP 客户端
-- **http** - 官方 HTTP 包
-- **retrofit** - 类型安全的 API 客户端
-
-### 本地存储
-- **shared_preferences** - 简单键值存储
-- **hive** - 轻量级 NoSQL 数据库
-- **sqflite** - SQLite 数据库
-- **isar** - 高性能本地数据库
-
-### 导航
-- **go_router** - 声明式路由
-- **auto_route** - 代码生成的路由方案
-
-### UI 组件
-- **flutter_svg** - SVG 图片支持
-- **cached_network_image** - 网络图片缓存
-- **shimmer** - 骨架屏效果
-- **animations** - 预定义动画
-
-### 工具
-- **freezed** - 不可变数据类生成
-- **json_serializable** - JSON 序列化
-- **flutter_launcher_icons** - 应用图标生成
-- **flutter_native_splash** - 启动屏配置
-
----
-
-## 🔍 调试技巧
-
-### Flutter DevTools
-
-```dart
-// 在开发模式启用性能监控
-import 'package:flutter/foundation.dart';
-
-void main() {
-  if (kDebugMode) {
-    // 启用性能覆盖层
-    debugPaintSizeEnabled = false;        // 显示 Widget 边界
-    debugPaintLayerBordersEnabled = false; // 显示图层边界
-    debugPrintRebuildDirtyWidgets = false; // 打印重建 Widget
-  }
-  
-  runApp(const MyApp());
-}
-```
-
-### 日志和断点
-
-```dart
-// ✅ 好 - 使用日志包
-import 'package:logger/logger.dart';
-
-final logger = Logger();
-
-void fetchData() async {
-  logger.i('开始获取数据');
-  
-  try {
-    final data = await api.getData();
-    logger.d('获取数据成功: $data');
-  } catch (e, stackTrace) {
-    logger.e('获取数据失败', error: e, stackTrace: stackTrace);
-  }
-}
-```
+| 类别 | 推荐 |
+|------|------|
+| 状态管理 | riverpod, flutter_bloc, provider |
+| 网络请求 | dio, retrofit |
+| 本地存储 | hive, isar, shared_preferences |
+| 导航 | go_router, auto_route |
+| UI | flutter_svg, cached_network_image, shimmer |
+| 工具 | freezed, json_serializable |
 
 ---
 
 ## ✅ 代码审查清单
 
-提交代码前,确保:
-
-- [ ] 所有公共 API 都有文档注释
-- [ ] 没有 TODO 或 FIXME 注释
-- [ ] 通过所有单元测试和 Widget 测试
-- [ ] 使用 `dart analyze` 检查无警告
-- [ ] 使用 `dart format` 格式化代码
-- [ ] 图片资源已优化
-- [ ] 国际化文本已添加
-- [ ] 性能测试通过
+- [ ] 所有公共 API 有文档注释
+- [ ] 通过 `dart analyze` 无警告
+- [ ] 通过 `dart format` 格式化
 - [ ] 无内存泄漏
-- [ ] 符合无障碍访问标准
-
----
-
-## 📖 参考资源
-
-### 官方文档
-- [Flutter Documentation](https://flutter.dev/docs)
-- [Dart Language Tour](https://dart.dev/language)
-- [Widget Catalog](https://flutter.dev/docs/development/ui/widgets)
-- [Cookbook](https://flutter.dev/docs/cookbook)
-
-### 最佳实践
-- [Effective Dart](https://dart.dev/effective-dart)
-- [Flutter Style Guide](https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md)
-- [Flutter Performance Best Practices](https://flutter.dev/docs/perf/best-practices)
-
-### 项目文档参考
-> 以下为项目特定文档，实际路径以项目结构为准
-
-- `docs/UI_RESTORATION_GUIDE.md` - 响应式 UI 还原指南
-- `docs/STYLE_GUIDE.md` - 样式规范文档
-
-### 学习资源
-- [Flutter YouTube Channel](https://www.youtube.com/c/flutterdev)
-- [Flutter Community Medium](https://medium.com/flutter-community)
-- [Dart Pub](https://pub.dev/)
+- [ ] 符合无障碍标准
 
 ---
 
 **维护团队**: MTA工作室  
-**创建日期**: 2025-12-16  
-**最后更新**: 2026-01-01
+**版本**: v2.0.0（精简版，详细方案请查询 troubleshooting）