mta-mcp 3.10.0 → 3.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mta-mcp",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "description": "MTA - 智能编码助手 MCP 服务器（规范 + 技能 + 诊断 + 模板 + 记忆 + 思考）",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,7 @@
     "standards/",
     "agents/",
     "templates/",
+    "troubleshooting/",
     "README.md"
   ],
   "scripts": {

package/standards/mcp-tools/sketch-mcp.md

@@ -20,6 +20,7 @@ Sketch MCP 是用于从 Sketch 设计文件中提取 UI 参数的工具。本文
 | **居中边距** | 上边距=8, 下边距=8 | 容器用 `alignment: center` |
 | **渐变方向** | from={x:0,y:0}, to={x:1,y:1} | Flutter `Alignment(-1,-1) → (1,1)` |
 | **透明度** | `#1C2B4580` | `0x80 = 128/255 = 0.5` |
+| **Text topOffset** | 字号=24, 帧高=33 | `topOffset=4.5`, `StrutStyle.height=33/24=1.375` |
 
 ### 标准流程
 
@@ -44,9 +45,20 @@ const angle = Math.atan2(to.y - from.y, to.x - from.x) * 180 / Math.PI + 90;
 
 // 透明度（从 8 位十六进制）
 const alpha = parseInt(colorHex.slice(7, 9), 16) / 255;
+
+// Sketch "适应布局" Text 帧高留白（topOffset）
+// Sketch Text 图层在「适应布局」模式下：frameHeight ≈ fontSize × 1.375
+// 文字视觉上沿不在 frame.y，而是 frame.y + topOffset
+const topOffset = (frameHeight - fontSize) / 2;  // 如 (33-24)/2 = 4.5px
+
+// Flutter StrutStyle.height（消除 CJK 字体 ascent/descent 不对称导致的视觉偏下）
+const strutHeight = frameHeight / fontSize;  // 如 33/24 = 1.375
+// 使用方式：StrutStyle(fontSize: fs, height: strutHeight, forceStrutHeight: true, leading: 0)
 ```
 
-> 📖 **详细案例**：参考 [TextField 垂直居中问题](../troubleshooting-cases/flutter/textfield-vertical-centering.md)，展示了如何从测量数据计算行高和配置参数。
+> 📖 **详细案例**：
+> - [Text 普通文字垂直居中偏下（StrutStyle）](../troubleshooting-cases/flutter/text-vertical-centering-strutstyle.md)
+> - [TextField 垂直居中问题](../troubleshooting-cases/flutter/textfield-vertical-centering.md)
 
 ---
 
@@ -1201,6 +1213,7 @@ function convertGradient(gradient, framework) {
 - [设计稿还原指南](../workflows/design-restoration-guide.md)
 - [测量模板](../../templates/design-measurement/README.md)
 - [TextField 居中案例](../troubleshooting-cases/flutter/textfield-vertical-centering.md)
+- [Text 普通文字垂直居中偏下（StrutStyle）](../troubleshooting-cases/flutter/text-vertical-centering-strutstyle.md)
 
 ---
 

package/standards/troubleshooting-cases/flutter/text-vertical-centering-strutstyle.md

@@ -0,0 +1,161 @@
+# Text 普通文字垂直居中偏下问题
+
+**问题标签**: `Text`, `居中`, `偏下`, `垂直对齐`, `StrutStyle`, `字体`, `行高`, `topOffset`
+**问题类型**: `UI 对齐`
+**严重程度**: 高
+**节省时间**: 多轮对话 → 1 次修复
+
+---
+
+## 问题描述
+
+在 Row/Column/Container 中放置 `Text` widget，设计稿上文字在容器内垂直居中，但 Flutter 实际渲染时文字位置**视觉偏下**。
+
+典型场景：
+- 邀请码卡片中的大号文字（fs=24）在 height=105 的 Row 里偏下
+- 任何固定高度容器内的中文 Text 视觉上不居中
+
+---
+
+## 问题根因
+
+### 两重偏差叠加
+
+**① Sketch "适应布局" 帧高留白（topOffset）**
+
+Sketch Text 图层在"适应布局（Fit Content）"模式下：
+
+```
+帧高（frameHeight） ≈ fontSize × 1.375
+topOffset = (frameHeight - fontSize) / 2
+```
+
+示例：fontSize=24 → frameHeight=33 → topOffset=4.5px
+
+设计稿测量的 Y 坐标是帧的起点，**实际文字视觉上沿 = Y + topOffset**。
+如果用原始 Y 坐标计算间距，偏差最大可达 4.5px。
+
+**② Flutter 字体 ascent/descent 不对称**
+
+Flutter 渲染 CJK 字体时，字形的上行距（ascent）默认大于下行距（descent），
+即使容器用 `crossAxisAlignment.center`，字形的视觉重心也会**偏下**。
+
+系统主动做补偿的唯一方式：通过 `StrutStyle.forceStrutHeight` 强制等量分配 leading。
+
+---
+
+## 测量数据解读
+
+使用 `artboard-measure.js` 运行后，Text 图层会输出：
+
+```json
+{
+  "text": {
+    "content": "邀请码 ：",
+    "fontSize": 24,
+    "topOffset": 4.5,
+    "visualHeight": 24
+  },
+  "layoutIntent": {
+    "visualSpacing": {
+      "note": "Text 图层存在 topOffset=4.5px，视觉上沿比 frame.y 低 4.5px",
+      "paddingTopVisual": 40.5,
+      "paddingBottomVisual": 40.5
+    }
+  }
+}
+```
+
+`topOffset` 即是两重偏差中第一重的来源，同时也是 Flutter 修正所需的行高比例基准：
+
+```
+StrutStyle.height = frameHeight / fontSize = 33 / 24 = 1.375
+```
+
+---
+
+## 正确方案
+
+### 从 Sketch 获取数值
+
+运行 `artboard-measure.js` 后查看：
+- `text.fontSize`：字号
+- `text.topOffset`：帧留白（= (frameHeight - fontSize) / 2）
+- `layoutIntent.visualSpacing`：视觉修正后的实际间距
+
+计算 `StrutStyle.height`：
+
+```javascript
+// 方式一：从 topOffset 反推
+const strutHeight = (fontSize + topOffset * 2) / fontSize;
+// 等价于：strutHeight = frameHeight / fontSize
+
+// 方式二：直接用 frameHeight
+const strutHeight = frameHeight / fontSize;  // 通常约 1.375
+```
+
+### Flutter 代码
+
+```dart
+Row(
+  crossAxisAlignment: CrossAxisAlignment.center,
+  children: [
+    Text(
+      '邀请码 ：',
+      // forceStrutHeight 强制 leading 均匀分配于字形上下
+      // height = frameHeight / fontSize = 33 / 24 = 1.375
+      strutStyle: const StrutStyle(
+        fontSize: 24,
+        height: 1.375,
+        forceStrutHeight: true,
+        leading: 0,
+      ),
+      style: TextStyle(
+        fontSize: 24,
+        fontWeight: FontWeight.w600,
+        color: DesignColors.textPrimary,
+      ),
+    ),
+  ],
+)
+```
+
+### 参数说明
+
+| 参数 | 值 | 说明 |
+|------|----|------|
+| `fontSize` | 与 TextStyle 相同 | StrutStyle 必须指定字号 |
+| `height` | `frameHeight / fontSize` ≈ 1.375 | 与 Sketch 帧高比例一致 |
+| `forceStrutHeight` | `true` | 强制启用，否则 height 对 CJK 字体可能无效 |
+| `leading` | `0` | 禁用额外行间距，让 height 完全控制 |
+
+> ⚠️ **注意**：`StrutStyle` 只需设置在含文字的 `Text` widget 上，不是 `TextStyle`。
+> `TextStyle.height` 控制行高，**不等于** `StrutStyle`，两者机制不同，不可混用。
+
+---
+
+## 与 TextField 居中问题的区别
+
+| 场景 | 使用方案 | 关键参数 |
+|------|---------|---------|
+| **Text** 在固定容器里偏下 | `StrutStyle` | `forceStrutHeight: true, leading: 0` |
+| **TextField** placeholder/光标偏下 | `style.height` + `contentPadding` | `isDense: true, contentPadding: EdgeInsets.zero` |
+
+两个问题表现相似，但修复路径完全不同，不可混用。
+
+---
+
+## 举一反三
+
+以下场景均可使用本方案：
+
+- 大号标题文字在卡片中视觉偏下
+- Icon + Text 水平排列，文字视觉位置比图标低
+- 数字（Helvetica Bold）与中文单位（PingFang SC）混排时竖向不对齐
+  → 分别给数字文字和单位文字设置各自的 `StrutStyle`
+
+---
+
+**维护团队**: MTA工作室
+**创建日期**: 2026-02-25
+**来源**: welfare_page.dart 邀请码卡片深度还原实战

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

@@ -111,6 +111,7 @@ Container: height=36, alignment=Alignment.center
 | 问题场景 | 关键属性 | 注意事项 |
 |----------|----------|----------|
 | TextField 居中 | `style.height`, `hintStyle.height` | 两者必须相同 |
+| **Text 垂直居中偏下** | `StrutStyle` | `forceStrutHeight:true, leading:0, height=frameHeight/fontSize` |
 | 容器阴影 | `clipBehavior` | 设为 `Clip.none` 避免裁剪 |
 | Gap 间距 | `Gap()` vs `Gap.h()` | 默认垂直，`.h()` 水平 |
 | SVG 颜色 | `colorFilter` | 不要覆盖，保留原色 |
@@ -151,7 +152,8 @@ Container: height=36, alignment=Alignment.center
 
 - [ ] 已获取目标元素的**容器尺寸**
 - [ ] 已获取**所有子元素**的位置和尺寸
-- [ ] 已获取文本的**Y 坐标、高度、字号**
+- [ ] 已获取文本的**Y 坐标、帧高、字号**（注意帧高 ≠ 字号，差值为 topOffset）
+- [ ] Text 图层已计算 `topOffset = (frameHeight - fontSize) / 2`（Sketch 适应布局偏差）
 - [ ] 已**计算**行高倍数和边距
 - [ ] 已确认相关属性（style/hintStyle）**配置一致**
 - [ ] 已一次性配置**完整方案**
@@ -161,4 +163,4 @@ Container: height=36, alignment=Alignment.center
 
 **维护团队**: MTA工作室  
 **创建日期**: 2026-01-19  
-**版本**: v1.0
+**版本**: v1.1（2026-02-25 新增 Text topOffset / StrutStyle 垂直居中修正）

package/templates/design-measurement/component-measurement.js

@@ -1,52 +1,105 @@
 /**
- * 组件测量模板 - 自动计算相对边距
+ * 组件测量模板 - 自动计算相对边距（含文字垂直对齐修正）
  * 用途：测量单个组件的完整布局参数
- * 
+ *
+ * 文字垂直修正说明：
+ *   Sketch 中 Text 选择"适应布局"时，layer.frame.height = fontSize × 自动行高系数（≈1.375）。
+ *   文字像素内容在该高度内垂直居中，因此框架顶部到可视文字上沿存在偏移量：
+ *     topOffset = (frameHeight - fontSize) / 2
+ *
+ *   相对边距中"视觉距父容器顶部"= 原始 paddingTop + topOffset，
+ *   这才是设计稿中视觉上希望体现的间距。
+ *
  * 使用方式：在 Sketch 中选中目标组件，运行此脚本
  */
 const sketch = require('sketch')
 
+// 计算 Text 图层的垂直光学偏移量
+// 返回 null 表示非文字图层或无需修正
+function getTextVerticalOffset(layer) {
+  if (layer.type !== 'Text') return null
+  var fontSize = (layer.style && layer.style.fontSize) ? layer.style.fontSize : 0
+  if (!fontSize) return null
+  var frameH = layer.frame.height
+  var topOffset = (frameH - fontSize) / 2
+  return {
+    fontSize: fontSize,
+    frameHeight: frameH,
+    topOffset: topOffset,
+    // 视觉文字上沿相对于 frame 顶部的偏移（正值 = 文字内容比 frame 低 topOffset px）
+    visualTop: layer.frame.y + topOffset,
+    visualBottom: layer.frame.y + frameH - topOffset,
+    visualHeight: fontSize
+  }
+}
+
 const sel = sketch.getSelectedDocument().selectedLayers.layers
 if (!sel.length) {
   console.log('请先选中一个组件')
 } else {
   const layer = sel[0]
   const parent = layer.parent
-  
+  const textMetrics = getTextVerticalOffset(layer)
+
   // 基础信息
   console.log('=== 组件测量结果 ===')
   console.log(`名称: ${layer.name}`)
   console.log(`类型: ${layer.type}`)
-  
+
   // 尺寸信息
   console.log(`\n--- 尺寸 ---`)
   console.log(`宽度: ${layer.frame.width}`)
   console.log(`高度: ${layer.frame.height}`)
-  
+  if (textMetrics) {
+    console.log(`[文字] 字号: ${textMetrics.fontSize}  自动行高框高: ${textMetrics.frameHeight}`)
+    console.log(`[文字] 顶部光学偏移 topOffset: ${textMetrics.topOffset.toFixed(1)}px  (可视文字高度: ${textMetrics.visualHeight})`)
+  }
+
   // 绝对坐标（供参考）
   console.log(`\n--- 绝对坐标（供参考）---`)
-  console.log(`x: ${layer.frame.x}`)
-  console.log(`y: ${layer.frame.y}`)
-  
-  // ⭐ 关键：计算相对边距（可直接使用）
-  console.log(`\n--- 相对边距（可直接使用）---`)
+  console.log(`frame.x: ${layer.frame.x}  frame.y: ${layer.frame.y}`)
+  if (textMetrics) {
+    console.log(`[文字] 视觉上沿 y: ${textMetrics.visualTop.toFixed(1)}  视觉下沿 y: ${textMetrics.visualBottom.toFixed(1)}`)
+  }
+
+  // 关键：计算相对边距
+  console.log(`\n--- 相对边距 ---`)
   if (parent && parent.frame) {
     const paddingLeft = layer.frame.x - parent.frame.x
     const paddingTop = layer.frame.y - parent.frame.y
     const paddingRight = (parent.frame.x + parent.frame.width) - (layer.frame.x + layer.frame.width)
     const paddingBottom = (parent.frame.y + parent.frame.height) - (layer.frame.y + layer.frame.height)
-    
-    console.log(`距父容器左边: ${paddingLeft}`)
-    console.log(`距父容器顶部: ${paddingTop}`)
-    console.log(`距父容器右边: ${paddingRight}`)
-    console.log(`距父容器底部: ${paddingBottom}`)
+
+    console.log(`距父容器左边:   ${paddingLeft.toFixed(1)}`)
+    console.log(`距父容器顶部:   ${paddingTop.toFixed(1)}  (frame.y 原始值)`)
+    console.log(`距父容器右边:   ${paddingRight.toFixed(1)}`)
+    console.log(`距父容器底部:   ${paddingBottom.toFixed(1)}  (frame 原始值)`)
     console.log(`父容器: ${parent.name} (${parent.frame.width}x${parent.frame.height})`)
+
+    if (textMetrics) {
+      // 视觉边距：从文字像素内容计算，而非从 frame 计算
+      const visualPaddingTop = paddingTop + textMetrics.topOffset
+      const visualPaddingBottom = paddingBottom + textMetrics.topOffset
+      console.log(`\n--- 文字视觉边距（修正后，推荐使用）---`)
+      console.log(`视觉距父容器顶部: ${visualPaddingTop.toFixed(1)}  (= framePaddingTop ${paddingTop.toFixed(1)} + topOffset ${textMetrics.topOffset.toFixed(1)})`)
+      console.log(`视觉距父容器底部: ${visualPaddingBottom.toFixed(1)}`)
+      console.log(`\n  说明: 设计师在 Sketch 中看到的上下间距是"视觉边距"，`)
+      console.log(`        Flutter Positioned.top 应使用"frame paddingTop"(${paddingTop.toFixed(1)})，`)
+      console.log(`        因为 Flutter Text 自身也会在字号上下添加相似行高空间。`)
+      console.log(`        若视觉偏差明显，可尝试 top: ${(paddingTop - textMetrics.topOffset).toFixed(1)} 使视觉上沿对齐。`)
+    }
   } else {
     console.log('无父容器或为顶层元素')
   }
-  
+
   // 框架转换提示
-  console.log(`\n--- 框架转换 ---`)
-  console.log(`Flutter: padding: EdgeInsets.fromLTRB(${layer.frame.x}, ${layer.frame.y}, 0, 0)`)
-  console.log(`CSS: padding: ${layer.frame.y}px ${layer.frame.x}px;`)
+  console.log(`\n--- Flutter 代码参考 ---`)
+  if (parent && parent.frame) {
+    const paddingLeft = layer.frame.x - parent.frame.x
+    const paddingTop = layer.frame.y - parent.frame.y
+    console.log(`Positioned(left: ${paddingLeft.toFixed(1)}, top: ${paddingTop.toFixed(1)}, child: ...)`)
+    if (textMetrics) {
+      console.log(`// 若需要视觉上沿对齐: top: ${(paddingTop - textMetrics.topOffset).toFixed(1)}`)
+    }
+  }
 }

package/templates/design-measurement/gap-measurement.js

@@ -1,79 +1,114 @@
 /**
- * 间距测量模板 - 计算同级元素间距
+ * 间距测量模板 - 计算同级元素间距（含文字垂直对齐修正）
  * 用途：测量多个元素之间的垂直/水平间距
- * 
+ *
+ * 文字垂直修正说明：
+ *   Sketch Text"适应布局"时 frameHeight = fontSize × 行高系数（≈1.375），
+ *   文字像素内容在框内垂直居中，topOffset = (frameH - fontSize) / 2。
+ *   两个元素之间的"视觉间距"需要减去相邻文字图层的 topOffset：
+ *     · 下方是 Text：visualGap = rawGap + topOffset(next)
+ *     · 上方是 Text：visualGap = rawGap + bottomOffset(current) = rawGap + topOffset(current)
+ *     · 两者都是 Text：visualGap = rawGap + topOffset(current) + topOffset(next)
+ *
  * 使用方式：在 Sketch 中选中多个同级元素，运行此脚本
  */
 const sketch = require('sketch')
 
+// 计算 Text 图层的垂直光学偏移量，非 Text 返回 topOffset=0
+function textOffset(layer) {
+  if (layer.type !== 'Text') return 0
+  var fs = (layer.style && layer.style.fontSize) ? layer.style.fontSize : 0
+  if (!fs) return 0
+  return (layer.frame.height - fs) / 2
+}
+
+// 格式化显示名（类型前缀 + 文字内容或图层名）
+function labelOf(layer) {
+  if (layer.type === 'Text') return `[T]"${layer.text || layer.name}"`
+  return `[${layer.type}]${layer.name}`
+}
+
 const sel = sketch.getSelectedDocument().selectedLayers.layers
 if (sel.length < 2) {
   console.log('请选中至少2个元素来计算间距')
 } else {
   // 按 Y 坐标排序（从上到下）
   const sortedByY = [...sel].sort((a, b) => a.frame.y - b.frame.y)
-  
+
   console.log('=== 垂直间距测量 ===')
   console.log(`选中元素数量: ${sel.length}`)
-  
+
   for (let i = 0; i < sortedByY.length - 1; i++) {
-    const current = sortedByY[i]
-    const next = sortedByY[i + 1]
-    
-    // 计算垂直间距 = 下一个元素顶部 - 当前元素底部
-    const gap = next.frame.y - (current.frame.y + current.frame.height)
-    
-    console.log(`\n${current.name} ↓ ${next.name}`)
-    console.log(`  垂直间距: ${gap}px`)
-    console.log(`  CSS: margin-bottom: ${gap}px; 或 gap: ${gap}px;`)
-    console.log(`  Flutter: SizedBox(height: ${gap})`)
+    const cur = sortedByY[i]
+    const nxt = sortedByY[i + 1]
+
+    // frame 间距（Sketch 坐标原始值）
+    const rawGap = nxt.frame.y - (cur.frame.y + cur.frame.height)
+
+    // 视觉间距修正：减去当前元素底部光学空白，减去下一元素顶部光学空白
+    const curBottomOffset = textOffset(cur)   // Text 底部行高空白
+    const nxtTopOffset    = textOffset(nxt)   // Text 顶部行高空白
+    const visualGap = rawGap + curBottomOffset + nxtTopOffset
+
+    console.log(`\n${labelOf(cur)} ↓ ${labelOf(nxt)}`)
+    console.log(`  frame 原始间距:   ${rawGap.toFixed(1)}px`)
+
+    if (curBottomOffset || nxtTopOffset) {
+      const parts = []
+      if (curBottomOffset) parts.push(`上方文字底部偏移 +${curBottomOffset.toFixed(1)}`)
+      if (nxtTopOffset)    parts.push(`下方文字顶部偏移 +${nxtTopOffset.toFixed(1)}`)
+      console.log(`  视觉修正来源:     ${parts.join(', ')}`)
+      console.log(`  视觉间距(推荐):  ${visualGap.toFixed(1)}px`)
+    }
+
+    console.log(`  SizedBox(height: ${visualGap.toFixed(1)})`)
   }
-  
+
   // 按 X 坐标排序（从左到右）
   const sortedByX = [...sel].sort((a, b) => a.frame.x - b.frame.x)
-  
+
   console.log('\n=== 水平间距测量 ===')
-  
+
   for (let i = 0; i < sortedByX.length - 1; i++) {
-    const current = sortedByX[i]
-    const next = sortedByX[i + 1]
-    
-    // 计算水平间距 = 下一个元素左边 - 当前元素右边
-    const gap = next.frame.x - (current.frame.x + current.frame.width)
-    
-    console.log(`\n${current.name} → ${next.name}`)
-    console.log(`  水平间距: ${gap}px`)
-    console.log(`  CSS: margin-right: ${gap}px; 或 gap: ${gap}px;`)
-    console.log(`  Flutter: SizedBox(width: ${gap})`)
+    const cur = sortedByX[i]
+    const nxt = sortedByX[i + 1]
+
+    const rawGap = nxt.frame.x - (cur.frame.x + cur.frame.width)
+
+    console.log(`\n${labelOf(cur)} → ${labelOf(nxt)}`)
+    console.log(`  水平间距: ${rawGap.toFixed(1)}px`)
+    console.log(`  SizedBox(width: ${rawGap.toFixed(1)})`)
+    // 水平方向文字偏移通常不影响左右间距，不做修正
   }
-  
-  // 汇总信息
+
+  // 汇总
   console.log('\n=== 汇总 ===')
-  const verticalGaps = []
-  const horizontalGaps = []
-  
+  const vGaps = []
+  const hGaps = []
+
   for (let i = 0; i < sortedByY.length - 1; i++) {
-    const gap = sortedByY[i + 1].frame.y - (sortedByY[i].frame.y + sortedByY[i].frame.height)
-    verticalGaps.push(gap)
+    const cur = sortedByY[i]
+    const nxt = sortedByY[i + 1]
+    const vis = nxt.frame.y - (cur.frame.y + cur.frame.height) + textOffset(cur) + textOffset(nxt)
+    vGaps.push(+vis.toFixed(1))
   }
-  
   for (let i = 0; i < sortedByX.length - 1; i++) {
-    const gap = sortedByX[i + 1].frame.x - (sortedByX[i].frame.x + sortedByX[i].frame.width)
-    horizontalGaps.push(gap)
+    const g = sortedByX[i + 1].frame.x - (sortedByX[i].frame.x + sortedByX[i].frame.width)
+    hGaps.push(+g.toFixed(1))
   }
-  
-  const uniqueVGaps = [...new Set(verticalGaps)]
-  const uniqueHGaps = [...new Set(horizontalGaps)]
-  
-  if (uniqueVGaps.length === 1) {
-    console.log(`垂直间距统一: ${uniqueVGaps[0]}px → 可使用 flex gap 或 Column mainAxisSpacing`)
+
+  const uniqueV = [...new Set(vGaps)]
+  const uniqueH = [...new Set(hGaps)]
+
+  if (uniqueV.length === 1) {
+    console.log(`垂直视觉间距统一: ${uniqueV[0]}px → Column spacing: ${uniqueV[0]}`)
   } else {
-    console.log(`垂直间距不统一: ${verticalGaps.join(', ')} → 需要单独设置`)
+    console.log(`垂直视觉间距不统一: ${vGaps.join(', ')} → 需要单独设置`)
   }
-  
-  if (uniqueHGaps.length === 1) {
-    console.log(`水平间距统一: ${uniqueHGaps[0]}px → 可使用 flex gap 或 Row mainAxisSpacing`)
+
+  if (uniqueH.length === 1) {
+    console.log(`水平间距统一: ${uniqueH[0]}px → Row spacing: ${uniqueH[0]}`)
   } else {
-    console.log(`水平间距不统一: ${horizontalGaps.join(', ')} → 需要单独设置`)
+    console.log(`水平间距不统一: ${hGaps.join(', ')} → 需要单独设置`)
   }
 }

package/templates/design-measurement/style-extraction.js

@@ -105,5 +105,18 @@ if (!sel.length) {
     console.log(`行高: ${textStyle.lineHeight || 'auto'}`)
     console.log(`颜色: ${textStyle.textColor}`)
     console.log(`对齐: ${textStyle.alignment}`)
+
+    // 文字垂直光学偏移（适应布局时 frameHeight > fontSize，文字居中）
+    const fs = textStyle.fontSize || 0
+    const frameH = layer.frame.height
+    if (fs && frameH > fs) {
+      const topOffset = (frameH - fs) / 2
+      console.log(`\n--- 文字垂直居中修正（适应布局）---`)
+      console.log(`frame 高度: ${frameH}  字号: ${fs}`)
+      console.log(`topOffset: ${topOffset.toFixed(1)}px  (frame 顶到可视文字上沿的间距)`)
+      console.log(`视觉文字上沿 y: ${(layer.frame.y + topOffset).toFixed(1)}  (= frame.y ${layer.frame.y} + topOffset ${topOffset.toFixed(1)})`)
+      console.log(`注意: Flutter Positioned.top 使用 frame.y 即可，因为 Flutter Text 本身有等效行高空间；`)
+      console.log(`      若定位出现 ${topOffset.toFixed(1)}px 偏差，可将 top 调整为 ${(layer.frame.y - topOffset).toFixed(1)}`)
+    }
   }
 }