mta-mcp 2.15.0 → 2.17.0

package/agents/flutter.agent.md

@@ -1,7 +1,7 @@
 # Flutter 开发代理
 
 > 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
-> 版本: v3.0.0 | 最后更新: 2026-01-16
+> 版本: v3.1.0 | 最后更新: 2026-01-19
 
 ---
 
@@ -22,6 +22,41 @@ troubleshoot({ problem: "用户描述的问题" })
 | 阴影被裁剪 | clip, shadow, clipBehavior |
 | SVG 颜色/居中问题 | svg, color, viewbox |
 | 输入框边框异常 | input, border, focus |
+| **TextField 垂直居中** | textfield, placeholder, 居中, 光标, 输入框 |
+
+---
+
+## ⚠️ TextField 垂直居中（高频问题）
+
+> 此问题曾导致 15+ 轮对话才修复，必须一步到位
+
+### 问题特征
+- placeholder 和输入内容位置不一致
+- 光标位置偏上/偏下
+- 修改一个问题引发另一个问题
+
+### 正确方案（直接使用）
+
+```dart
+Container(
+  height: 36, // 设计稿容器高度
+  alignment: Alignment.center, // 关键1
+  child: TextField(
+    style: TextStyle(fontSize: 14, height: 1.43), // 关键2: 行高 = 文本高度÷字号
+    decoration: InputDecoration(
+      hintStyle: TextStyle(fontSize: 14, height: 1.43), // 关键3: 必须与style一致
+      contentPadding: EdgeInsets.zero, // 关键4
+      isDense: true, // 关键5
+    ),
+  ),
+)
+```
+
+### 禁止事项
+- ❌ `style.height` ≠ `hintStyle.height`
+- ❌ 同时用 `textAlignVertical` 和 `height`
+- ❌ 用 `strutStyle + forceStrutHeight`
+- ❌ 反复调整 `contentPadding` 试错
 
 ---
 
@@ -101,5 +136,38 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 
 ---
 
+## 🎨 设计稿还原强制规范
+
+> ⚠️ 使用 Sketch/Figma MCP 时必须遵守
+
+### 强制要求：完整读取选中元素及其所有子集
+
+```javascript
+// 正确：一次性获取容器+所有子元素的完整信息
+function extractComplete(element) {
+  // 1. 容器信息
+  console.log(`容器: ${element.frame.width}x${element.frame.height}`);
+  
+  // 2. 所有子元素信息（关键！）
+  element.layers.forEach(child => {
+    console.log(`子元素: ${child.name}`);
+    console.log(`  位置: Y=${child.frame.y}px`);
+    console.log(`  尺寸: ${child.frame.width}x${child.frame.height}`);
+    if (child.type === 'Text') {
+      console.log(`  字号: ${child.style.fontSize}px`);
+      console.log(`  行高: ${child.frame.height / child.style.fontSize}`);
+    }
+  });
+}
+```
+
+### 禁止事项
+- ❌ 只读容器属性，忽略内部元素位置
+- ❌ 每次只查一个属性，分散多轮获取
+- ❌ 假设"差不多"而不验证精确像素值
+- ❌ 用"试错法"调整参数
+
+---
+
 **维护团队**: MTA工作室  
 **设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mta-mcp",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "MTA - 智能项目分析与编码规范管理 MCP 服务器",
   "type": "module",
   "main": "./dist/index.js",

package/standards/frameworks/flutter.md

@@ -996,6 +996,84 @@ class UserProfile extends StatelessWidget {
 
 ---
 
+## 📝 TextField 垂直居中规范（重要）
+
+> ⚠️ **此问题曾导致 15+ 轮对话才修复，必须一步到位**
+
+### 问题场景
+TextField 中 placeholder、光标、输入内容三者需要在固定高度容器中垂直居中对齐。
+
+### 正确方案（一步到位）
+
+```dart
+// ✅ 正确 - Container.alignment + 统一 height + contentPadding.zero
+Widget _buildCenteredTextField(String placeholder, TextEditingController controller) {
+  return Container(
+    height: 36, // 固定容器高度
+    alignment: Alignment.center, // 关键1：让 TextField 整体居中
+    child: TextField(
+      controller: controller,
+      textAlign: TextAlign.center,
+      style: const TextStyle(
+        fontSize: 14,
+        height: 1.43, // 关键2：行高 = 期望文本高度 ÷ 字号
+      ),
+      decoration: InputDecoration(
+        hintText: placeholder,
+        hintStyle: const TextStyle(
+          fontSize: 14,
+          height: 1.43, // 关键3：必须与 style.height 完全一致
+        ),
+        contentPadding: EdgeInsets.zero, // 关键4：清除默认 padding
+        isDense: true, // 关键5：移除额外空间
+        border: InputBorder.none,
+      ),
+    ),
+  );
+}
+
+// ❌ 错误 - 会导致 placeholder 和输入内容位置不一致
+TextField(
+  textAlignVertical: TextAlignVertical.center, // 只影响输入内容
+  style: TextStyle(fontSize: 14, height: 1.43),
+  decoration: InputDecoration(
+    hintStyle: TextStyle(fontSize: 14), // height 不一致！
+    contentPadding: EdgeInsets.symmetric(vertical: 8), // 干扰居中
+  ),
+)
+```
+
+### 行高计算公式
+
+从设计稿获取：
+- 容器高度：36px
+- 文本 Y 坐标：8px（距顶部）
+- 文本高度：20px
+- 字号：14px
+
+```
+height = 文本高度 ÷ 字号 = 20 ÷ 14 = 1.43
+```
+
+### 禁止事项
+
+| 禁止 | 原因 |
+|------|------|
+| `style.height` ≠ `hintStyle.height` | placeholder 和输入内容位置不一致 |
+| 同时用 `textAlignVertical` 和 `height` | 产生冲突，效果不可预测 |
+| 用 `strutStyle + forceStrutHeight` | 可能压缩文字 |
+| 反复调整 `contentPadding` 试错 | 应先确定行高配置 |
+
+### 调试顺序（遇到问题时）
+
+1. 先从设计稿获取：容器高度、文本 Y 坐标、文本高度
+2. 计算 `height = 文本高度 ÷ 字号`
+3. 确保 `style.height` = `hintStyle.height`
+4. 设置 `Container.alignment: Alignment.center`
+5. 设置 `contentPadding: EdgeInsets.zero` + `isDense: true`
+
+---
+
 ## 🎨 Sketch/Figma 设计稿还原规范
 
 > ⚠️ **此章节为强制执行规范** - 所有 UI 还原任务必须严格遵循

package/standards/troubleshooting-cases/flutter/textfield-vertical-centering.md

@@ -0,0 +1,107 @@
+# TextField 垂直居中问题
+
+**问题标签**: `textfield`, `居中`, `placeholder`, `光标`, `输入框`, `vertical-align`  
+**问题类型**: `UI 对齐`  
+**严重程度**: 高  
+**节省时间**: 15+ 轮对话 → 1 轮
+
+---
+
+## 问题描述
+
+TextField 中 placeholder、光标、输入内容三者需要在固定高度容器中垂直居中对齐，但出现以下问题：
+- placeholder 和输入内容位置不一致
+- 光标位置偏上或偏下
+- 修改一个问题引发另一个问题
+
+## 问题根因
+
+Flutter TextField 的垂直对齐涉及多个相互作用的属性：
+- `style.height` - 输入文本的行高
+- `hintStyle.height` - placeholder 的行高
+- `contentPadding` - 内边距
+- `isDense` - 紧凑模式
+- `textAlignVertical` - 垂直对齐
+- `strutStyle` - 行高基准
+
+**核心问题**：这些属性相互影响，单独调整一个可能破坏其他元素的对齐。
+
+## 错误尝试（导致反复）
+
+| 尝试 | 结果 |
+|------|------|
+| 只调整 `contentPadding` | 整体偏移，不居中 |
+| 用 `textAlignVertical: center` | 只影响输入内容，placeholder 不动 |
+| 用 `strutStyle + forceStrutHeight` | 文字被压缩变形 |
+| `style.height` ≠ `hintStyle.height` | placeholder 和输入内容位置不一致 |
+
+## 正确方案
+
+### 从设计稿获取数值
+
+```javascript
+// Sketch 提取脚本
+const container = sketch.find('[name="Input"]', artboard)[0];
+const text = container.layers.find(l => l.type === 'Text');
+
+console.log(`容器高度: ${container.frame.height}px`);        // 36
+console.log(`文本 Y 坐标: ${text.frame.y}px`);               // 8
+console.log(`文本高度: ${text.frame.height}px`);              // 20
+console.log(`字号: ${text.style.fontSize}px`);                // 14
+console.log(`行高倍数: ${text.frame.height / text.style.fontSize}`);  // 1.43
+```
+
+### Flutter 代码
+
+```dart
+Container(
+  height: 36, // 设计稿容器高度
+  alignment: Alignment.center, // 关键1：让 TextField 整体居中
+  child: TextField(
+    textAlign: TextAlign.center,
+    style: const TextStyle(
+      fontSize: 14,
+      height: 1.43, // 关键2：行高 = 文本高度÷字号 = 20÷14
+    ),
+    decoration: InputDecoration(
+      hintText: placeholder,
+      hintStyle: const TextStyle(
+        fontSize: 14,
+        height: 1.43, // 关键3：必须与 style.height 完全一致
+      ),
+      contentPadding: EdgeInsets.zero, // 关键4：清除默认 padding
+      isDense: true, // 关键5：移除额外空间
+      border: InputBorder.none,
+    ),
+  ),
+)
+```
+
+## 关键原则
+
+| 原则 | 说明 |
+|------|------|
+| `style.height` = `hintStyle.height` | 两者必须相同，否则位置不一致 |
+| `Container.alignment` 控制居中 | 不要用 `textAlignVertical` |
+| `contentPadding: EdgeInsets.zero` | 让 Container.alignment 生效 |
+| 先计算再编码 | 行高 = 文本高度 ÷ 字号 |
+
+## 禁止事项
+
+- ❌ `style.height` ≠ `hintStyle.height`
+- ❌ 同时使用 `textAlignVertical` 和 `height`
+- ❌ 使用 `strutStyle + forceStrutHeight`
+- ❌ 反复调整 `contentPadding` 试错
+
+## 验证方法
+
+1. 点击输入框，检查光标位置
+2. 输入文字，检查文字位置
+3. 清空输入，检查 placeholder 位置
+4. 三者应该在同一垂直位置
+
+---
+
+**案例来源**: 汇款记录筛选弹窗金额输入框  
+**创建日期**: 2026-01-19  
+**版本**: v1.0

package/standards/workflows/design-restoration-guide.md

@@ -0,0 +1,164 @@
+# 设计稿还原通用规范
+
+> 适用于使用 Sketch、Figma 等设计工具 MCP 进行 UI 还原的所有场景
+
+## 🔴 核心问题
+
+本规范基于真实案例总结：**一个简单的输入框垂直居中问题，经历了 15+ 轮对话才修复**。
+
+### 问题根源分析
+
+| 问题 | 表现 | 后果 |
+|------|------|------|
+| **属性读取不完整** | 只读容器尺寸，忽略内部文本位置 | 无法精确计算边距和行高 |
+| **分散查询** | 每次只问一个属性 | 信息不完整，反复补充 |
+| **假设而非验证** | "应该差不多居中" | 实际偏差明显 |
+| **试错式调整** | 逐个调整参数看效果 | 改了 A 问题引发 B 问题 |
+
+---
+
+## ✅ 强制执行规范
+
+### 1. 完整读取选中元素及其所有子集
+
+**⚠️ 这是最重要的规则**
+
+```javascript
+// 正确示例：一次性获取完整信息
+function extractCompleteInfo(element) {
+  console.log('=== 容器信息 ===');
+  console.log(`尺寸: ${element.frame.width}x${element.frame.height}px`);
+  
+  console.log('=== 所有子元素 ===');
+  element.layers.forEach((child, index) => {
+    console.log(`\n子元素 ${index}: ${child.name} (${child.type})`);
+    console.log(`  X: ${child.frame.x}px, Y: ${child.frame.y}px`);
+    console.log(`  宽: ${child.frame.width}px, 高: ${child.frame.height}px`);
+    
+    if (child.type === 'Text') {
+      console.log(`  字号: ${child.style.fontSize}px`);
+      console.log(`  字重: ${child.style.fontWeight}`);
+      console.log(`  颜色: ${child.style.textColor}`);
+      console.log(`  行高倍数: ${(child.frame.height / child.style.fontSize).toFixed(2)}`);
+    }
+    
+    // 递归处理嵌套子元素
+    if (child.layers && child.layers.length > 0) {
+      child.layers.forEach(nested => {
+        console.log(`    嵌套: ${nested.name} (${nested.type})`);
+        console.log(`    位置: Y=${nested.frame.y}px`);
+      });
+    }
+  });
+  
+  console.log('=== 计算结果 ===');
+  const textChild = element.layers.find(l => l.type === 'Text');
+  if (textChild) {
+    const topSpace = textChild.frame.y;
+    const bottomSpace = element.frame.height - textChild.frame.y - textChild.frame.height;
+    console.log(`文本上边距: ${topSpace}px`);
+    console.log(`文本下边距: ${bottomSpace}px`);
+    console.log(`是否居中: ${Math.abs(topSpace - bottomSpace) < 2 ? '是' : '否'}`);
+  }
+}
+```
+
+### 2. 必须获取的完整信息清单
+
+| 元素类型 | 必须获取的属性 | 用途 |
+|----------|----------------|------|
+| **容器** | width, height, padding, 背景色/渐变 | 外层布局 |
+| **文本** | Y 坐标, height, fontSize, fontWeight, color | 计算行高和边距 |
+| **图标** | viewBox, path, fill, fill-opacity | 完整导出 SVG |
+| **渐变** | 所有 stops（颜色+位置）, from, to | 精确还原 |
+| **阴影** | x, y, blur, spread, color (全部 5 个) | 完整阴影 |
+| **边框** | color, width, position | 边框样式 |
+
+### 3. 计算而非试错
+
+**正确流程**：
+```
+1. 从设计稿获取精确数值
+2. 计算目标框架需要的参数
+3. 一次性配置完整方案
+4. 验证结果
+```
+
+**示例：TextField 行高计算**
+```
+设计稿数据:
+- 容器高度: 36px
+- 文本 Y 坐标: 8px
+- 文本高度: 20px
+- 字号: 14px
+
+计算:
+- 行高倍数 = 文本高度 ÷ 字号 = 20 ÷ 14 = 1.43
+- 上边距 = 文本 Y 坐标 = 8px
+- 下边距 = 容器高度 - Y - 文本高度 = 36 - 8 - 20 = 8px
+
+Flutter 配置:
+style: TextStyle(fontSize: 14, height: 1.43)
+Container: height=36, alignment=Alignment.center
+```
+
+---
+
+## 📋 框架特定注意事项
+
+### Flutter
+
+| 问题场景 | 关键属性 | 注意事项 |
+|----------|----------|----------|
+| TextField 居中 | `style.height`, `hintStyle.height` | 两者必须相同 |
+| 容器阴影 | `clipBehavior` | 设为 `Clip.none` 避免裁剪 |
+| Gap 间距 | `Gap()` vs `Gap.h()` | 默认垂直，`.h()` 水平 |
+| SVG 颜色 | `colorFilter` | 不要覆盖，保留原色 |
+
+### Vue/CSS
+
+| 问题场景 | 关键属性 | 注意事项 |
+|----------|----------|----------|
+| Flex 居中 | `align-items`, `justify-content` | 注意主轴方向 |
+| 文本居中 | `line-height` | 设为容器高度实现垂直居中 |
+| 边框问题 | `box-sizing` | 使用 `border-box` |
+| 阴影裁剪 | `overflow` | 避免 `hidden` 裁剪阴影 |
+
+### React Native
+
+| 问题场景 | 关键属性 | 注意事项 |
+|----------|----------|----------|
+| 文本居中 | `textAlignVertical` | 仅 Android 生效 |
+| 输入框 | `includeFontPadding` | Android 设为 false |
+| 阴影 | `elevation` vs `shadow*` | 平台差异 |
+
+---
+
+## 🚫 禁止事项
+
+1. ❌ **禁止只读容器属性** - 必须读取所有子元素
+2. ❌ **禁止分散查询** - 一次性获取完整信息
+3. ❌ **禁止假设数值** - 必须从设计稿读取精确像素
+4. ❌ **禁止试错调整** - 先计算，再编码
+5. ❌ **禁止忽略透明度** - 颜色 `#RRGGBBAA` 最后两位是透明度
+6. ❌ **禁止属性不一致** - 相关属性（如 style 和 hintStyle）必须统一配置
+
+---
+
+## ✅ 检查清单
+
+还原任何设计稿元素前：
+
+- [ ] 已获取目标元素的**容器尺寸**
+- [ ] 已获取**所有子元素**的位置和尺寸
+- [ ] 已获取文本的**Y 坐标、高度、字号**
+- [ ] 已**计算**行高倍数和边距
+- [ ] 已确认相关属性（style/hintStyle）**配置一致**
+- [ ] 已一次性配置**完整方案**
+- [ ] 已验证**所有相关元素**符合预期
+
+---
+
+**维护团队**: MTA工作室  
+**创建日期**: 2026-01-19  
+**版本**: v1.0

package/standards/workflows/problem-diagnosis.md

@@ -194,6 +194,74 @@
 
 ---
 
+## 🎨 设计稿还原专项规范
+
+> ⚠️ **此章节基于真实案例：一个输入框居中问题反复 15+ 轮对话才修复**
+
+### 设计稿工具使用规范（Sketch/Figma）
+
+#### 强制要求：完整读取选中元素及其所有子集
+
+**问题根源**：
+- 只读取了容器属性，忽略了内部文本的精确位置
+- 每次只查询一个属性，导致信息不完整
+- 假设而非验证具体数值
+
+**正确做法**：
+
+```javascript
+// 示例：读取输入框完整信息（包含所有子集）
+function extractInputFieldComplete(inputGroup) {
+  console.log('=== 容器信息 ===');
+  console.log(`宽度: ${inputGroup.frame.width}px`);
+  console.log(`高度: ${inputGroup.frame.height}px`);
+  
+  console.log('=== 内部文本（子集）===');
+  const text = inputGroup.layers.find(l => l.type === 'Text');
+  console.log(`文本 Y 坐标: ${text.frame.y}px`);  // 关键：距容器顶部距离
+  console.log(`文本高度: ${text.frame.height}px`); // 关键：计算行高
+  console.log(`字号: ${text.style.fontSize}px`);
+  
+  console.log('=== 计算结果 ===');
+  const topSpace = text.frame.y;
+  const bottomSpace = inputGroup.frame.height - text.frame.y - text.frame.height;
+  console.log(`上边距: ${topSpace}px`);
+  console.log(`下边距: ${bottomSpace}px`);
+  console.log(`行高倍数: ${(text.frame.height / text.style.fontSize).toFixed(2)}`);
+}
+```
+
+#### 必须获取的信息清单
+
+| 元素类型 | 必须获取 | 用途 |
+|----------|----------|------|
+| 容器 | width, height, padding | 外层尺寸 |
+| 文本 | fontSize, Y坐标, height, fontWeight | 计算行高和边距 |
+| 图标/SVG | viewBox, path, fill-opacity | 完整导出 |
+| 渐变 | stops（所有节点）, from, to | 精确还原 |
+| 阴影 | x, y, blur, spread, color | 全部5个参数 |
+
+### 反复修复问题的根因分析
+
+| 导致反复的原因 | 正确做法 |
+|----------------|----------|
+| 只读取容器高度，不读内部文本 Y 坐标 | 一次性获取容器+所有子元素的完整信息 |
+| 用"试错法"调整参数 | 先计算精确值（如行高=文本高度÷字号） |
+| 修改 A 属性引发 B 问题 | 理解属性之间的相互作用关系 |
+| 假设"差不多居中" | 从设计稿获取精确像素值验证 |
+
+### 设计稿还原检查清单
+
+修复任何设计还原问题前：
+
+- [ ] 已获取目标元素的**完整信息**（容器+所有子集）
+- [ ] 已计算精确数值（行高、边距、颜色透明度）
+- [ ] 已理解框架渲染机制（如 Flutter TextField 的多属性相互作用）
+- [ ] 一次性配置完整方案，而非逐个属性调整
+- [ ] 验证所有相关元素（placeholder、光标、输入内容）都符合预期
+
+---
+
 ## ✅ 检查清单
 
 修复任何问题前，确认以下检查项：

package/standards/workflows/textfield-centering-guide.md

@@ -0,0 +1,157 @@
+# Flutter TextField 垂直居中纠错指南
+
+> 本文档基于一次真实案例总结：修复一个简单的输入框垂直居中问题，经历了 **15+ 轮对话**，涉及多种方案反复尝试
+
+## 📋 问题总结
+
+### 问题描述
+输入框需要实现 placeholder、光标、输入内容三者在容器中垂直居中对齐。
+
+### 问题根因
+Flutter TextField 的垂直对齐涉及**多个相互作用的属性**，修改一个属性可能影响其他元素的位置，导致"改了 A 问题引发 B 问题"的循环。
+
+### 反复失败的原因
+
+| 尝试次数 | 方案 | 结果 |
+|----------|------|------|
+| 1 | contentPadding: vertical: 10 | 整体偏下 |
+| 2 | textAlignVertical: center | 只影响输入内容，placeholder 不动 |
+| 3 | 移除 contentPadding | 整体偏上 |
+| 4 | strutStyle + height: 1.0 | 文字被压缩，更难看 |
+| 5 | Container.alignment + contentPadding: 8 | 输入内容正常，placeholder 偏下 |
+| 6 | hintStyle height: 1.2 | placeholder 移动，但不够 |
+| 7 | hintStyle height: 1.0 | placeholder 过于靠上 |
+| 8-15 | 各种组合... | 来回折腾 |
+
+### 根本问题
+**没有一开始就理解 TextField 的渲染模型**，而是"试错式"调整参数。
+
+---
+
+## ✅ 正确方案（一步到位）
+
+### 设计规格（从 Sketch 获取）
+- 容器高度：36px
+- 文本 Y 坐标：8px（距顶部）
+- 文本高度：20px
+- 字号：14px
+- 行高倍数：1.43（20 ÷ 14 = 1.43）
+
+### Flutter 正确配置
+
+```dart
+Widget _buildCenteredTextField({
+  required String placeholder,
+  required TextEditingController controller,
+}) {
+  return Container(
+    height: 36,
+    decoration: BoxDecoration(
+      // ... 背景、圆角、阴影
+    ),
+    alignment: Alignment.center, // 关键：让 TextField 在容器中居中
+    child: TextField(
+      controller: controller,
+      textAlign: TextAlign.center, // 水平居中
+      // 不要使用 textAlignVertical，会导致 placeholder 和输入内容位置不一致
+      style: const TextStyle(
+        fontSize: 14,
+        height: 1.43, // 关键：与 hintStyle 保持一致
+        fontWeight: FontWeight.w600,
+      ),
+      decoration: InputDecoration(
+        hintText: placeholder,
+        hintStyle: const TextStyle(
+          fontSize: 14,
+          height: 1.43, // 关键：与 style 完全一致
+          fontWeight: FontWeight.w600,
+        ),
+        contentPadding: EdgeInsets.zero, // 关键：清除默认 padding
+        isDense: true, // 关键：移除额外空间
+        border: InputBorder.none,
+        enabledBorder: InputBorder.none,
+        focusedBorder: InputBorder.none,
+      ),
+    ),
+  );
+}
+```
+
+### 关键原则
+
+| 属性 | 作用 | 注意事项 |
+|------|------|----------|
+| `Container.alignment: Alignment.center` | 让 TextField 整体在容器中居中 | 必须配合 `contentPadding: EdgeInsets.zero` |
+| `style.height` 和 `hintStyle.height` | 控制行高 | **必须相同**，否则 placeholder 和输入内容位置不一致 |
+| `contentPadding: EdgeInsets.zero` | 清除默认间距 | 让 Container.alignment 生效 |
+| `isDense: true` | 移除 TextField 默认空间 | 减少干扰因素 |
+| `textAlignVertical` | **不推荐使用** | 只影响输入内容，不影响 placeholder |
+
+---
+
+## 📌 简版纠错指南
+
+### TextField 垂直居中三步法
+
+```dart
+// Step 1: Container 提供高度和居中
+Container(
+  height: 36,
+  alignment: Alignment.center,
+  child: TextField(
+    // Step 2: style 和 hintStyle 使用相同的 height
+    style: TextStyle(fontSize: 14, height: 1.43),
+    decoration: InputDecoration(
+      hintStyle: TextStyle(fontSize: 14, height: 1.43),
+      // Step 3: 清除 padding，启用 isDense
+      contentPadding: EdgeInsets.zero,
+      isDense: true,
+    ),
+  ),
+)
+```
+
+### 禁止事项
+
+1. ❌ **禁止 style.height 和 hintStyle.height 不一致** - 会导致 placeholder 和输入内容位置不同
+2. ❌ **禁止同时使用 textAlignVertical 和 height** - 会产生冲突
+3. ❌ **禁止 strutStyle + forceStrutHeight** - 可能压缩文字
+4. ❌ **禁止反复调整 contentPadding 试错** - 先确定行高配置
+
+### 调试顺序
+
+遇到 TextField 垂直对齐问题时，按以下顺序检查：
+
+1. **先确认设计规格** - 容器高度、文本高度、计算行高倍数
+2. **配置 height** - style 和 hintStyle 使用相同的 height
+3. **配置 Container** - alignment: Alignment.center
+4. **清除干扰** - contentPadding: EdgeInsets.zero, isDense: true
+5. **移除冲突属性** - 不要用 textAlignVertical 和 strutStyle
+
+---
+
+## 🎯 案例复盘
+
+### 为什么需要 15+ 轮对话？
+
+| 问题 | 正确做法 |
+|------|----------|
+| 没有先计算行高倍数 | 从设计稿提取：文本高度 ÷ 字号 = height |
+| 逐个尝试属性 | 一次性配置完整方案 |
+| 改了 A 引发 B | 理解属性之间的关系 |
+| 没有统一 style 和 hintStyle | 两者必须完全一致 |
+
+### 正确的工作流
+
+```
+1. 从 Sketch 获取完整规格（容器高度、文本 Y 坐标、文本高度）
+2. 计算 height = 文本高度 ÷ 字号
+3. 一次性配置完整方案（Container.alignment + 相同 height + contentPadding.zero + isDense）
+4. 验证三者（placeholder、光标、输入内容）是否对齐
+```
+
+---
+
+**创建日期**: 2026-01-19  
+**案例来源**: 汇款记录筛选弹窗金额输入框  
+**解决方案**: Container.alignment + 统一 height + contentPadding.zero

package/troubleshooting/README.md

@@ -104,7 +104,7 @@ list_troubleshooting_cases({ framework: "flutter" })
 
 ## 📚 案例清单
 
-### Flutter (11 个案例)
+### Flutter (13 个案例)
 
 | 案例ID | 问题类型 | 关键词 |
 |--------|----------|--------|
@@ -118,6 +118,8 @@ list_troubleshooting_cases({ framework: "flutter" })
 | svg-未居中 | SVG未居中 | svg, viewbox, center |
 | sketch-图标尺寸 | 图标尺寸提取错误 | sketch, icon, group, shape |
 | sketch-属性未使用 | 属性定义但未使用 | property, unused |
+| sketch-背景层高度 | Frame与_background高度差异 | sketch, frame, background, height, _bg |
+| sketch-列表item区域 | 列表首尾item高度不一致 | sketch, list, menu, padding, divider |
 | withopacity-弃用 | withOpacity弃用警告 | opacity, deprecated |
 
 ### Vue3 (1 个案例)
@@ -194,9 +196,9 @@ list_troubleshooting_cases({ framework: "flutter" })
 
 ---
 
-**版本**: v2.14.0  
-**案例总数**: 12 个  
-**最后更新**: 2026-01-17
+**版本**: v2.15.0  
+**案例总数**: 14 个  
+**最后更新**: 2026-01-19
 
 ---
 

package/troubleshooting/flutter/sketch-/345/210/227/350/241/250item/345/214/272/345/237/237.md

@@ -0,0 +1,212 @@
+# Sketch 列表 Item 区域高度不一致问题
+
+> **问题标签**: `sketch`, `list`, `menu`, `item`, `padding`, `divider`  
+> **框架**: Flutter  
+> **严重程度**: 中等（导致列表布局细节偏差）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "第一个/最后一个 item 高度不对"
+- "列表 padding 不均匀"
+- "divider 位置偏移"
+- "底部/顶部留白太多/太少"
+
+### 问题特征
+- [ ] 列表首尾 item 与中间 item 高度不同
+- [ ] 使用统一 padding 导致视觉不平衡
+- [ ] 忽略 divider 在高度计算中的影响
+- [ ] 假设所有 item 高度相同
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：设计稿中列表的首个和末尾 item 通常有不同的 padding，以平衡与容器边缘的视觉关系。
+
+### 典型 Sketch 测量结果
+
+```
+Menu Card_background: 350px
+
+Divider 位置:
+- Divider 1: y=63
+- Divider 2: y=119  
+- Divider 3: y=175
+- Divider 4: y=231
+- Divider 5: y=287
+
+区域高度计算:
+- Item 1: 0 → 63 = 63px
+- Item 2: 63 → 119 = 56px
+- Item 3: 119 → 175 = 56px
+- Item 4: 175 → 231 = 56px
+- Item 5: 231 → 287 = 56px
+- Item 6: 287 → 350 = 63px
+```
+
+**结论**: 首尾 item 63px，中间 item 56px，**不是**统一高度！
+
+---
+
+## ❌ 常见错误
+
+```dart
+// ❌ 错误: 统一 padding
+Padding(
+  padding: const EdgeInsets.symmetric(vertical: 10, horizontal: 16),
+  child: MenuItem(),
+)
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 1. 测量 Icon 精确位置
+
+```javascript
+// 测量所有 icon 的 y 坐标
+const icons = sketch.find('[name*="Icon BG"]', menuCard);
+icons.forEach(icon => {
+  if (icon.frame.height === 36) {
+    console.log(`${icon.name}: y=${icon.frame.y}`);
+  }
+});
+
+// 结果:
+// Item 1 Icon: y=20
+// Item 2 Icon: y=76
+// Item 3 Icon: y=132
+// ...
+```
+
+### 2. 计算每个 item 的 padding
+
+```
+Item 1 (区域 0→63):
+- region_start = 0
+- icon_y = 20 → top = 20
+- icon_bottom = 56
+- divider_y = 63 → bottom = 63 - 56 - 1 = 6
+- 验证: 20 + 36 + 6 + 1 = 63 ✅
+
+Item 2 (区域 64→119):
+- region_start = 64 (divider1 + 1)
+- icon_y = 76 → top = 76 - 64 = 12
+- icon_bottom = 112
+- divider_y = 119 → bottom = 119 - 112 - 1 = 6
+- 验证: 12 + 36 + 6 + 1 = 55... 
+
+等等，56 - 1(divider) = 55，但 12+36+6=54？
+让我重新计算：区域 = 56px 含 divider
+内容区 = 55px，12 + 36 + 7 = 55 ✅
+```
+
+### 3. Flutter 精确实现
+
+```dart
+Widget _buildMenuItem(int index, MenuItem item) {
+  // Sketch 测量 (背景层 350px):
+  // - Item 1: 区域 63px = top:20 + icon:36 + bottom:6 + divider:1
+  // - Item 2-5: 区域 56px = top:12 + icon:36 + bottom:7 + divider:1  
+  // - Item 6: 区域 63px = top:12 + icon:36 + bottom:15 (无 divider)
+  
+  final isFirst = index == 0;
+  final isLast = index == 5; // 6 个 item
+  
+  return Column(
+    mainAxisSize: MainAxisSize.min,
+    children: [
+      Padding(
+        padding: EdgeInsets.fromLTRB(
+          16,
+          isFirst ? 20 : 12,              // 首 item top 更大
+          16,
+          isFirst ? 6 : (isLast ? 15 : 7), // 尾 item bottom 更大
+        ),
+        child: Row(
+          children: [
+            Icon(size: 36),
+            SizedBox(width: 16),
+            Expanded(child: Text(item.title)),
+            ArrowIcon(),
+          ],
+        ),
+      ),
+      
+      // Divider (最后一个不需要)
+      if (!isLast)
+        Container(
+          margin: EdgeInsets.only(left: 68, right: 20),
+          height: 1,
+          color: Color(0x0F1C2B45),
+        ),
+    ],
+  );
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### 从 Sketch 测量计算 padding
+
+```
+top_padding = icon.y - region_start
+bottom_padding = region_end - icon.bottom - divider_height
+```
+
+其中:
+- `region_start` = 上一个 divider.y + 1 (首 item 为 0)
+- `region_end` = 当前 divider.y (尾 item 为 background.height)
+- `icon.bottom` = icon.y + icon.height
+- `divider_height` = 1 (尾 item 为 0)
+
+### 验证公式
+
+```
+区域高度 = top_padding + icon_height + bottom_padding + divider_height
+```
+
+---
+
+## 📊 真实案例数据
+
+### Profile Menu Card (350px)
+
+| Item | 区域 | Top | Icon | Bottom | Divider | 总计 |
+|------|------|-----|------|--------|---------|------|
+| 1 | 0→63 | 20 | 36 | 6 | 1 | 63 |
+| 2 | 63→119 | 12 | 36 | 7 | 1 | 56 |
+| 3 | 119→175 | 12 | 36 | 7 | 1 | 56 |
+| 4 | 175→231 | 12 | 36 | 7 | 1 | 56 |
+| 5 | 231→287 | 12 | 36 | 7 | 1 | 56 |
+| 6 | 287→350 | 12 | 36 | 15 | 0 | 63 |
+
+**总计**: 63 + 56×4 + 63 = 350px ✅
+
+---
+
+## ⚠️ 预防措施
+
+1. **不要假设统一高度**: 始终测量首、中、尾三种 item
+2. **测量 icon 实际 y 坐标**: 不要只看区域高度
+3. **区分有无 divider**: 尾 item 通常无 divider
+4. **使用背景层边界**: 不要用 Frame 高度
+
+---
+
+## 🔗 相关问题
+
+- [sketch-背景层高度.md](./sketch-背景层高度.md) - 背景层 vs Frame 高度
+- [layout-尺寸不匹配.md](./layout-尺寸不匹配.md) - 通用布局问题
+
+---
+
+**创建日期**: 2026-01-19  
+**最后更新**: 2026-01-19  
+**来源**: Profile 页面 Menu Item 布局调试实战

package/troubleshooting/flutter/sketch-/350/203/214/346/231/257/345/261/202/351/253/230/345/272/246.md

@@ -0,0 +1,264 @@
+# Sketch Frame 与 Background 层高度差异问题
+
+> **问题标签**: `sketch`, `frame`, `background`, `height`, `_background`, `_bg`  
+> **框架**: Flutter  
+> **严重程度**: 高（导致布局错位和多轮返工）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "间距不对"
+- "高度算错了"
+- "内边距有问题"
+- "最后一个 item 高度不对"
+- "卡片高度不匹配"
+
+### 问题特征
+- [ ] 计算的间距与设计稿视觉效果不符
+- [ ] 使用 Frame 高度计算，但结果总是差几像素
+- [ ] Menu/List 的第一个或最后一个 item 高度异常
+- [ ] 多个卡片之间的 gap 计算错误
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 的 Frame（组/画板）高度与其内部 `_background` 或 `_bg` 层高度可能不同。
+
+### Sketch 层级结构示例
+
+```
+Menu Card (Frame)         ← height: 336px ❌ 错误值
+├── Menu Card_background  ← height: 350px ✅ 正确值
+├── Menu Item 1
+├── Divider 1
+├── Menu Item 2
+...
+
+Warning Card (Frame)      ← height: 100px ❌ 错误值
+├── Warning Card_bg       ← height: 127px ✅ 正确值
+├── Warning Text
+├── Button
+```
+
+| 元素 | Frame 高度 | _background 高度 | 差异 |
+|------|------------|------------------|------|
+| Menu Card | 336px | 350px | +14px |
+| Warning Card | 100px | 127px | +27px |
+
+### 为什么会这样？
+
+1. **Auto Layout**: Frame 可能使用 Hug Contents 或固定高度
+2. **阴影/装饰**: _background 层包含了内边距、阴影区域
+3. **Padding 内含**: 背景层可能比 Frame 更大以提供视觉边距
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 使用 Frame 高度计算 gap | 背景层实际更大 | 3-5 轮对话 |
+| 反复调整 padding | 不知道正确的参考值 | 4-6 轮对话 |
+| 假设最后 item 与其他相同 | 底部 padding 通常不同 | 2-3 轮对话 |
+| 只测量 divider 位置 | 忽略了背景层边界 | 2-3 轮对话 |
+
+**总计浪费**: 10-15 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 解决步骤
+
+#### 1. 必须同时测量 Frame 和 _background 层
+
+```javascript
+// Sketch 测量脚本 - 比较 Frame 与背景层高度
+const sketch = require('sketch');
+const doc = sketch.getSelectedDocument();
+const page = doc.selectedPage;
+const target = sketch.find('[name="Profile Page"]', page)[0]; // 替换为目标
+
+function measureBackgroundLayers(container) {
+  const results = {};
+  
+  sketch.find('*', container).forEach(layer => {
+    const name = layer.name;
+    
+    // 查找 Frame 和对应的 _background/_bg 层
+    if (name.includes('Card') || name.includes('Panel')) {
+      results[name] = {
+        type: layer.type,
+        frameHeight: layer.frame.height,
+        y: layer.frame.y
+      };
+    }
+    
+    // 单独记录 _background 和 _bg 层
+    if (name.includes('_background') || name.includes('_bg')) {
+      results[name] = {
+        type: layer.type,
+        height: layer.frame.height,
+        y: layer.frame.y
+      };
+    }
+  });
+  
+  console.log(JSON.stringify(results, null, 2));
+}
+
+measureBackgroundLayers(target);
+```
+
+#### 2. 使用 _background 层高度计算布局
+
+```dart
+// ❌ 错误: 使用 Frame 高度
+const warningCardHeight = 100; // Frame 高度
+const menuCardY = 274;
+const gap = menuCardY - (warningCardY + warningCardHeight);
+// gap = 274 - (130 + 100) = 44px ❌
+
+// ✅ 正确: 使用 _background 层高度
+const warningCardHeight = 127; // _bg 层高度
+const gap = menuCardY - (warningCardY + warningCardHeight);
+// gap = 274 - (130 + 127) = 17px ✅
+```
+
+#### 3. 区分列表首尾 item 的 padding
+
+Menu/List 类组件中，首尾 item 通常与背景边缘有特殊间距：
+
+```javascript
+// 测量 divider 位置和背景层边界
+const dividers = sketch.find('[name*="Divider"]', menuCard);
+const background = sketch.find('[name*="_background"]', menuCard)[0];
+
+dividers.forEach(d => {
+  console.log(`${d.name}: y=${d.frame.y}`);
+});
+console.log(`Background height: ${background.frame.height}`);
+
+// 计算每个区域高度
+// Item 1: 0 → divider1.y
+// Item 2-N-1: divider[i-1].y → divider[i].y  
+// Item N: divider[N-1].y + 1 → background.height
+```
+
+#### 4. Flutter 实现：区分首尾 item
+
+```dart
+Widget _buildMenuItem(int index, MenuItem item) {
+  // Sketch 精确测量 (Menu Card_background = 350px):
+  // - Item 1: 区域63px = top:20 + icon:36 + bottom:6 + divider:1
+  // - Item 2-5: 区域56px = top:12 + icon:36 + bottom:7 + divider:1
+  // - Item 6: 区域63px = top:12 + icon:36 + bottom:15 (无divider)
+  
+  return Padding(
+    padding: EdgeInsets.fromLTRB(
+      16,
+      index == 0 ? 20 : 12,           // 首 item top 更大
+      16,
+      index == 0 ? 6 : (index == 5 ? 15 : 7), // 尾 item bottom 更大
+    ),
+    child: Row(...),
+  );
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### 卡片间距计算
+
+```
+实际 gap = 下一卡片.y - (当前卡片.y + 当前卡片._background.height)
+```
+
+### 列表 item 区域计算
+
+```
+区域[0] = divider[0].y                           // 首 item
+区域[i] = divider[i].y - divider[i-1].y          // 中间 items (含 divider)
+区域[N] = background.height - divider[N-1].y - 1 // 尾 item (无 divider)
+```
+
+### Icon 垂直 padding 计算
+
+```
+top_padding = icon.y - region_start
+bottom_padding = region_end - (icon.y + icon.height) - divider_height
+```
+
+---
+
+## ⚠️ 预防措施
+
+### 提取 Sketch 时的检查清单
+
+- [ ] 是否同时读取了 Frame 高度和 _background/_bg 层高度？
+- [ ] 两者是否相同？如果不同，使用哪个？
+- [ ] 卡片之间的 gap 是否基于视觉边界（_background）计算？
+- [ ] 列表的首尾 item 是否有特殊的 padding？
+
+### 命名约定识别
+
+| 后缀 | 含义 | 使用场景 |
+|------|------|----------|
+| `_background` | 完整背景层 | 用于计算实际高度 |
+| `_bg` | 简化背景层 | 同上 |
+| `_shadow` | 阴影层 | 可能影响视觉边界 |
+| `_border` | 边框层 | 不影响高度计算 |
+
+---
+
+## 📊 真实案例
+
+### 案例: Profile 页面卡片间距
+
+**问题**: Warning Card 到 Menu Card 的间距应该是 17px，但计算得到 44px
+
+**错误分析**:
+```
+Menu Card.y = 274
+Warning Card.y = 130
+Warning Card Frame.height = 100  ← 使用了错误的值
+
+gap = 274 - (130 + 100) = 44px ❌
+```
+
+**正确分析**:
+```
+Menu Card.y = 274
+Warning Card.y = 130  
+Warning Card_bg.height = 127  ← 使用 _bg 层高度
+
+gap = 274 - (130 + 127) = 17px ✅
+```
+
+**修复代码**:
+```dart
+// 修改前
+SizedBox(height: 44),
+
+// 修改后
+SizedBox(height: 17),
+```
+
+---
+
+## 🔗 相关问题
+
+- [layout-尺寸不匹配.md](./layout-尺寸不匹配.md) - 通用布局问题
+- [sketch-完整提取.md](./sketch-完整提取.md) - 完整提取脚本
+- [sketch-图标尺寸.md](./sketch-图标尺寸.md) - SVG 尺寸问题
+
+---
+
+**创建日期**: 2026-01-19  
+**最后更新**: 2026-01-19  
+**来源**: Profile 页面 Menu Card 布局调试实战