mta-mcp 1.0.2 → 1.0.4

package/package.json

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

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

@@ -52,7 +52,148 @@ function getLayerColor(layer) {
 }
 ```
 
-### 问题 2：Symbol 内部样式读取
+### 问题 2：fontWeight 数值不准确（重要）
+
+**严重程度**: 🔴 高
+
+**现象**：`layer.style.fontWeight` 返回的数值（如 8）不能直接映射到 Flutter/CSS 字重。
+
+```javascript
+// ❌ 错误方式 - fontWeight 值不可靠
+layer.style.fontWeight  // 返回 8，但实际可能是 Semibold(w600) 而非 ExtraBold(w800)
+```
+
+**原因**：Sketch API 的 `fontWeight` 属性返回的是内部权重值，不是标准的 100-900 字重值。
+
+**解决方案**：通过 `sketchObject.font()` 获取真实的 PostScript 字体名称：
+
+```javascript
+function getTextFontInfo(textLayer) {
+  const result = {
+    fontSize: textLayer.style.fontSize,
+    fontFamily: textLayer.style.fontFamily,
+    fontWeight: textLayer.style.fontWeight,  // 仅供参考
+    fontName: null,  // 关键：真实字体名称
+    displayName: null
+  };
+  
+  // 获取真实字体名称
+  if (textLayer.sketchObject && textLayer.sketchObject.font) {
+    const font = textLayer.sketchObject.font();
+    if (font) {
+      result.fontName = String(font.fontName());      // 如 "PingFangSC-Semibold"
+      result.displayName = String(font.displayName()); // 如 "苹方-简 中粗体"
+      result.familyName = String(font.familyName());   // 如 "PingFang SC"
+    }
+  }
+  
+  return result;
+}
+```
+
+**PostScript 字体名到 Flutter FontWeight 映射**：
+
+| PostScript 后缀 | 中文名 | Flutter | CSS |
+|----------------|--------|---------|-----|
+| `-Thin` | 极细 | w100 | 100 |
+| `-Ultralight` | 纤细 | w200 | 200 |
+| `-Light` | 细体 | w300 | 300 |
+| `-Regular` | 常规 | w400 | 400 |
+| `-Medium` | 中等 | w500 | 500 |
+| `-Semibold` | 中粗体 | w600 | 600 |
+| `-Bold` | 粗体 | w700 | 700 |
+| `-Heavy` | 特粗 | w800 | 800 |
+| `-Black` | 黑体 | w900 | 900 |
+
+### 问题 3：图标必须从设计稿导出
+
+**严重程度**: 🔴 高
+
+**现象**：AI 可能会自己生成图标 SVG，而不是从设计稿中提取。
+
+**正确做法**：使用 `sketch.export` API 导出设计稿中的图标：
+
+```javascript
+const sketch = require('sketch');
+
+function exportIconAsSVG(layer) {
+  // 导出为 Buffer
+  const buffer = sketch.export(layer, {
+    formats: 'svg',
+    output: false,  // 关键：返回 Buffer 而非写文件
+    scales: '1'
+  });
+  
+  // Buffer 转字符串
+  const svgString = buffer.toString('utf-8');
+  
+  // 清理 SVG（移除 Sketch 生成的多余属性）
+  return svgString
+    .replace(/id="[^"]*"/g, '')
+    .replace(/sketch:type="[^"]*"/g, '')
+    .replace(/xmlns:sketch="[^"]*"/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+```
+
+**在 Flutter 中使用导出的 SVG**：
+
+```dart
+// 方式1：内联 SVG（推荐小图标）
+SvgPicture.string(
+  '''<svg>...</svg>''',
+  width: 24,
+  height: 24,
+)
+
+// 方式2：保存为文件（推荐大图标）
+// 将导出的 SVG 保存到 assets/icons/ 目录
+SvgPicture.asset('assets/icons/notification.svg')
+```
+
+### 问题 4：列表项间距测量
+
+**严重程度**: 🔴 高
+
+**现象**：列表中多个同类元素的间距可能不一致，需要逐个测量。
+
+**测量脚本**：
+
+```javascript
+function measureListSpacing(container) {
+  const children = container.layers;
+  const spacings = [];
+  
+  for (let i = 0; i < children.length - 1; i++) {
+    const current = children[i];
+    const next = children[i + 1];
+    
+    // 垂直间距 = 下一个元素的 y - (当前元素的 y + 高度)
+    const spacing = next.frame.y - (current.frame.y + current.frame.height);
+    
+    spacings.push({
+      between: `${current.name} → ${next.name}`,
+      spacing: Math.round(spacing)
+    });
+  }
+  
+  // 检查是否一致
+  const uniqueSpacings = [...new Set(spacings.map(s => s.spacing))];
+  
+  return {
+    spacings,
+    isConsistent: uniqueSpacings.length === 1,
+    recommendedSpacing: uniqueSpacings.length === 1 
+      ? uniqueSpacings[0] 
+      : Math.round(spacings.reduce((a, b) => a + b.spacing, 0) / spacings.length)
+  };
+}
+```
+
+**注意**：如果设计稿中间距不一致，应与设计师确认是故意还是误差。代码中应使用统一间距。
+
+### 问题 5：Symbol 内部样式读取
 
 **严重程度**: 🟡 中
 
@@ -69,7 +210,7 @@ if (layer.type === 'SymbolInstance') {
 }
 ```
 
-### 问题 3：阴影数组顺序
+### 问题 6：阴影数组顺序
 
 **严重程度**: 🟢 低
 
@@ -346,4 +487,11 @@ function convertGradient(gradient, framework) {
 
 **维护者**: MTA工作室  
 **创建日期**: 2026-01-20  
-**最后更新**: 2026-01-20
+**最后更新**: 2026-01-21
+
+### 更新日志
+
+| 版本 | 日期 | 更新内容 |
+|------|------|---------|
+| v1.0 | 2026-01-20 | 初始版本 |
+| v1.1 | 2026-01-21 | 新增：fontWeight不可靠问题及fontName获取方案、图标导出规范、列表间距测量脚本 |

package/standards/workflows/design-restoration.md

@@ -83,16 +83,53 @@ color: "#1C2B45"    // 丢失透明度
 
 设计稿中的字重名称需要映射为数值：
 
-| 设计稿名称 | 数值 | Flutter | CSS |
-|-----------|------|---------|-----|
-| Thin | 100 | FontWeight.w100 | font-weight: 100 |
-| Light | 300 | FontWeight.w300 | font-weight: 300 |
-| Regular | 400 | FontWeight.w400 | font-weight: 400 |
-| Medium | 500 | FontWeight.w500 | font-weight: 500 |
-| SemiBold | 600 | FontWeight.w600 | font-weight: 600 |
-| Bold | 700 | FontWeight.w700 | font-weight: 700 |
+| 设计稿名称 | PostScript 后缀 | 数值 | Flutter | CSS |
+|-----------|----------------|------|---------|-----|
+| Thin | -Thin | 100 | FontWeight.w100 | font-weight: 100 |
+| Ultralight | -Ultralight | 200 | FontWeight.w200 | font-weight: 200 |
+| Light | -Light | 300 | FontWeight.w300 | font-weight: 300 |
+| Regular | -Regular | 400 | FontWeight.w400 | font-weight: 400 |
+| Medium | -Medium | 500 | FontWeight.w500 | font-weight: 500 |
+| SemiBold | -Semibold | 600 | FontWeight.w600 | font-weight: 600 |
+| Bold | -Bold | 700 | FontWeight.w700 | font-weight: 700 |
+| Heavy/ExtraBold | -Heavy | 800 | FontWeight.w800 | font-weight: 800 |
+| Black | -Black | 900 | FontWeight.w900 | font-weight: 900 |
 
-#### 4. 行高计算差异
+> ⚠️ **重要**：Sketch API 的 `fontWeight` 属性返回的数值（如 8）不可靠！必须通过 `sketchObject.font().fontName()` 获取真实的 PostScript 字体名称（如 `PingFangSC-Semibold`），然后根据后缀映射。
+
+#### 4. 图标必须从设计稿导出
+
+**绝对禁止**：AI 自己生成图标 SVG
+
+**正确做法**：使用设计工具 API 导出设计稿中的图标
+
+```javascript
+// Sketch 导出示例
+const buffer = sketch.export(iconLayer, {
+  formats: 'svg',
+  output: false,
+  scales: '1'
+});
+const svgString = buffer.toString('utf-8');
+```
+
+**原因**：
+- 设计师精心调整过图标的线条粗细、比例、细节
+- AI 生成的图标风格可能与设计稿不一致
+- 图标是品牌视觉的重要组成部分
+
+#### 5. 列表间距必须逐个测量
+
+**问题**：同一列表中的元素间距可能不完全一致
+
+**正确做法**：测量每对相邻元素的间距，取多数值或与设计师确认
+
+```javascript
+// 间距计算公式
+spacing = nextElement.y - (currentElement.y + currentElement.height)
+```
+
+#### 6. 行高计算差异
 
 不同框架对行高的处理不同：
 
@@ -356,6 +393,7 @@ function getFigmaColor(paint) {
 | 版本 | 日期 | 更新内容 |
 |------|------|---------|
 | v1.0 | 2026-01-20 | 初始版本，包含渐变色读取问题解决方案 |
+| v1.1 | 2026-01-21 | 新增：字重映射完整表（含PostScript后缀）、图标导出强制要求、列表间距测量规范 |
 
 ---
 

package/templates/README.md

@@ -70,6 +70,11 @@ templates/
 │   ├── api-layer/
 │   └── themes/
 ├── react/                    # React 项目模板（预留）
+├── design-measurement/       # 设计稿测量模板 ✅ 新增
+│   ├── README.md             # 使用指南
+│   ├── component-measurement.js  # 组件测量
+│   ├── style-extraction.js   # 样式提取
+│   └── gap-measurement.js    # 间距测量
 └── common/                   # 跨框架通用模板
     └── types/                # TypeScript 类型定义 ✅
 ```
@@ -108,6 +113,15 @@ templates/
 |------|--------|------|------|
 | `common/types` | types, 类型 | TypeScript 通用类型 | ✅ 可用 |
 
+### 设计稿测量模板 🆕
+
+| 模板 | 关键词 | 说明 | 状态 |
+|------|--------|------|------|
+| `design-measurement` | 测量, measure | 设计稿测量脚本合集 | ✅ 可用 |
+| `component-measurement.js` | 组件, 边距 | 组件尺寸+相对边距 | ✅ 可用 |
+| `style-extraction.js` | 样式, 渐变, 阴影 | 完整样式提取 | ✅ 可用 |
+| `gap-measurement.js` | 间距, gap | 同级元素间距 | ✅ 可用 |
+
 ---
 
 ## 🔧 模板规范

package/templates/design-measurement/README.md

@@ -0,0 +1,81 @@
+# 🎨 设计稿测量模板
+
+> 适用于 Sketch MCP、Figma 等设计工具的测量脚本模板
+
+---
+
+## 🤖 Agent 使用指令
+
+**触发词**：
+- "测量选中的组件"
+- "获取设计稿边距"
+- "分析图层样式"
+- "获取渐变色参数"
+
+**自动匹配模板**：
+
+| 场景 | 对应模板 |
+|------|----------|
+| 分析整体结构 | `structure-overview.js` |
+| 测量单个组件 | `component-measurement.js` |
+| 计算间距关系 | `gap-measurement.js` |
+| 提取样式参数 | `style-extraction.js` |
+| 分析嵌套Symbol | `nested-symbol-analysis.js` |
+
+---
+
+## 📁 模板文件
+
+### 1. structure-overview.js
+用途：分析选中元素的整体结构和层级
+
+### 2. component-measurement.js  
+用途：测量单个组件的尺寸、边距、内边距（自动计算相对值）
+
+### 3. gap-measurement.js
+用途：计算同级元素之间的间距
+
+### 4. style-extraction.js
+用途：提取颜色、渐变、阴影、圆角等样式参数
+
+### 5. nested-symbol-analysis.js
+用途：递归分析 Symbol 内部嵌套结构
+
+---
+
+## 🔧 使用方式
+
+### 方式一：直接调用 MCP 工具
+```
+调用 get_standard_by_id({ id: 'sketch-mcp' }) 获取完整脚本
+```
+
+### 方式二：复制模板脚本
+```javascript
+// 从模板文件中复制脚本到 mcp_sketch_run_code
+```
+
+---
+
+## ⚠️ 核心原则
+
+1. **测量 = 记录 + 计算**
+   - 记录绝对坐标
+   - 立即计算相对边距
+   - 转换为目标框架可用的值
+
+2. **坐标系转换**
+   - iOS SafeArea 偏移：44px（刘海屏）/ 20px（非刘海）
+   - Android 状态栏：24-48dp
+   - Web：通常不需要
+
+3. **渐变角度转换**
+   - Sketch: from{x,y} → to{x,y}（0-1 范围）
+   - CSS: `linear-gradient(angle, ...)`
+   - Flutter: `Alignment(x, y)`（-1 到 1 范围）
+
+---
+
+**维护者**: MTA工作室  
+**版本**: v1.0  
+**创建日期**: 2025-01-21

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

@@ -0,0 +1,52 @@
+/**
+ * 组件测量模板 - 自动计算相对边距
+ * 用途：测量单个组件的完整布局参数
+ * 
+ * 使用方式：在 Sketch 中选中目标组件，运行此脚本
+ */
+const sketch = require('sketch')
+
+const sel = sketch.getSelectedDocument().selectedLayers.layers
+if (!sel.length) {
+  console.log('请先选中一个组件')
+} else {
+  const layer = sel[0]
+  const parent = layer.parent
+  
+  // 基础信息
+  console.log('=== 组件测量结果 ===')
+  console.log(`名称: ${layer.name}`)
+  console.log(`类型: ${layer.type}`)
+  
+  // 尺寸信息
+  console.log(`\n--- 尺寸 ---`)
+  console.log(`宽度: ${layer.frame.width}`)
+  console.log(`高度: ${layer.frame.height}`)
+  
+  // 绝对坐标（供参考）
+  console.log(`\n--- 绝对坐标（供参考）---`)
+  console.log(`x: ${layer.frame.x}`)
+  console.log(`y: ${layer.frame.y}`)
+  
+  // ⭐ 关键：计算相对边距（可直接使用）
+  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(`父容器: ${parent.name} (${parent.frame.width}x${parent.frame.height})`)
+  } 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;`)
+}

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

@@ -0,0 +1,79 @@
+/**
+ * 间距测量模板 - 计算同级元素间距
+ * 用途：测量多个元素之间的垂直/水平间距
+ * 
+ * 使用方式：在 Sketch 中选中多个同级元素，运行此脚本
+ */
+const sketch = require('sketch')
+
+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})`)
+  }
+  
+  // 按 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})`)
+  }
+  
+  // 汇总信息
+  console.log('\n=== 汇总 ===')
+  const verticalGaps = []
+  const horizontalGaps = []
+  
+  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)
+  }
+  
+  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 uniqueVGaps = [...new Set(verticalGaps)]
+  const uniqueHGaps = [...new Set(horizontalGaps)]
+  
+  if (uniqueVGaps.length === 1) {
+    console.log(`垂直间距统一: ${uniqueVGaps[0]}px → 可使用 flex gap 或 Column mainAxisSpacing`)
+  } else {
+    console.log(`垂直间距不统一: ${verticalGaps.join(', ')} → 需要单独设置`)
+  }
+  
+  if (uniqueHGaps.length === 1) {
+    console.log(`水平间距统一: ${uniqueHGaps[0]}px → 可使用 flex gap 或 Row mainAxisSpacing`)
+  } else {
+    console.log(`水平间距不统一: ${horizontalGaps.join(', ')} → 需要单独设置`)
+  }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 样式提取模板 - 完整样式参数
+ * 用途：提取颜色、渐变、阴影、圆角等样式
+ * 
+ * 使用方式：在 Sketch 中选中目标元素，运行此脚本
+ */
+const sketch = require('sketch')
+
+const sel = sketch.getSelectedDocument().selectedLayers.layers
+if (!sel.length) {
+  console.log('请先选中一个元素')
+} else {
+  const layer = sel[0]
+  const style = layer.style
+  
+  console.log('=== 样式提取结果 ===')
+  console.log(`元素: ${layer.name}`)
+  
+  // 圆角
+  if (layer.style?.corners) {
+    console.log(`\n--- 圆角 ---`)
+    console.log(`圆角: ${JSON.stringify(layer.style.corners.radii)}`)
+  }
+  
+  // 填充（颜色/渐变）
+  if (style?.fills?.length) {
+    console.log(`\n--- 填充 ---`)
+    style.fills.forEach((fill, i) => {
+      if (fill.fillType === 'Color') {
+        console.log(`填充${i}: 纯色 ${fill.color}`)
+        // 转换提示
+        const hex = fill.color
+        console.log(`  CSS: background: ${hex};`)
+        console.log(`  Flutter: Color(0xFF${hex.replace('#', '').toUpperCase()})`)
+      } else if (fill.fillType === 'Gradient') {
+        console.log(`填充${i}: 渐变`)
+        console.log(`  类型: ${fill.gradient.gradientType}`)
+        console.log(`  起点: from(${fill.gradient.from.x}, ${fill.gradient.from.y})`)
+        console.log(`  终点: to(${fill.gradient.to.x}, ${fill.gradient.to.y})`)
+        console.log(`  色标:`)
+        fill.gradient.stops.forEach((stop, j) => {
+          console.log(`    ${j}: ${stop.color} at ${(stop.position * 100).toFixed(0)}%`)
+        })
+        
+        // 计算渐变角度
+        const dx = fill.gradient.to.x - fill.gradient.from.x
+        const dy = fill.gradient.to.y - fill.gradient.from.y
+        const angle = Math.round(Math.atan2(dy, dx) * 180 / Math.PI + 90)
+        
+        // CSS 转换
+        const colors = fill.gradient.stops.map(s => `${s.color} ${(s.position * 100).toFixed(0)}%`).join(', ')
+        console.log(`  CSS: linear-gradient(${angle}deg, ${colors})`)
+        
+        // Flutter 转换
+        const fromX = (fill.gradient.from.x * 2 - 1).toFixed(2)
+        const fromY = (fill.gradient.from.y * 2 - 1).toFixed(2)
+        const toX = (fill.gradient.to.x * 2 - 1).toFixed(2)
+        const toY = (fill.gradient.to.y * 2 - 1).toFixed(2)
+        console.log(`  Flutter: begin: Alignment(${fromX}, ${fromY}), end: Alignment(${toX}, ${toY})`)
+      }
+    })
+  }
+  
+  // 边框
+  if (style?.borders?.length) {
+    console.log(`\n--- 边框 ---`)
+    style.borders.forEach((border, i) => {
+      console.log(`边框${i}: ${border.color} 宽度=${border.thickness}`)
+      console.log(`  CSS: border: ${border.thickness}px solid ${border.color};`)
+    })
+  }
+  
+  // 阴影
+  if (style?.shadows?.length) {
+    console.log(`\n--- 阴影 ---`)
+    style.shadows.forEach((shadow, i) => {
+      console.log(`阴影${i}:`)
+      console.log(`  颜色: ${shadow.color}`)
+      console.log(`  偏移: x=${shadow.x}, y=${shadow.y}`)
+      console.log(`  模糊: ${shadow.blur}`)
+      console.log(`  扩展: ${shadow.spread}`)
+      console.log(`  CSS: box-shadow: ${shadow.x}px ${shadow.y}px ${shadow.blur}px ${shadow.spread}px ${shadow.color};`)
+    })
+  }
+  
+  // 内阴影
+  if (style?.innerShadows?.length) {
+    console.log(`\n--- 内阴影 ---`)
+    style.innerShadows.forEach((shadow, i) => {
+      console.log(`内阴影${i}:`)
+      console.log(`  颜色: ${shadow.color}`)
+      console.log(`  偏移: x=${shadow.x}, y=${shadow.y}`)
+      console.log(`  模糊: ${shadow.blur}`)
+      console.log(`  CSS: box-shadow: inset ${shadow.x}px ${shadow.y}px ${shadow.blur}px ${shadow.color};`)
+    })
+  }
+  
+  // 文字样式（如果是文本）
+  if (layer.type === 'Text') {
+    console.log(`\n--- 文字样式 ---`)
+    const textStyle = layer.style
+    console.log(`内容: ${layer.text}`)
+    console.log(`字体: ${textStyle.fontFamily || 'default'}`)
+    console.log(`字号: ${textStyle.fontSize}`)
+    console.log(`行高: ${textStyle.lineHeight || 'auto'}`)
+    console.log(`颜色: ${textStyle.textColor}`)
+    console.log(`对齐: ${textStyle.alignment}`)
+  }
+}