mta-mcp 2.17.0 → 3.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mta-mcp",
-  "version": "2.17.0",
-  "description": "MTA - 智能项目分析与编码规范管理 MCP 服务器",
+  "version": "3.0.0",
+  "description": "MTA - 智能编码助手 MCP 服务器（规范 + 技能 + 诊断 + 模板）",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,9 +20,7 @@
     "dist/",
     "standards/",
     "agents/",
-    "common/",
     "templates/",
-    "troubleshooting/",
     "README.md"
   ],
   "scripts": {

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

@@ -0,0 +1,497 @@
+# Sketch MCP 最佳实践
+
+> 使用 Sketch MCP 工具准确测量设计稿的规范指南
+
+## 📋 概述
+
+Sketch MCP 是用于从 Sketch 设计文件中提取 UI 参数的工具。本文档记录了使用过程中发现的问题和最佳实践。
+
+---
+
+## ⚠️ 已知问题与解决方案
+
+### 问题 1：渐变色被读取为单色
+
+**严重程度**: 🔴 高
+
+**现象**：
+```javascript
+layer.style.fills[0].color  // 返回 "#4a60b2ff"
+layer.style.fills[0].fillType  // 返回 "Gradient"
+```
+
+当 `fillType` 是 `Gradient` 时，`color` 属性返回的是一个"代表色"，而非实际的渐变颜色。
+
+**解决方案**：
+
+```javascript
+function getLayerColor(layer) {
+  const fills = layer.style?.fills?.filter(f => f.enabled);
+  if (!fills || fills.length === 0) return null;
+  
+  const fill = fills[0];
+  
+  // 关键：先判断 fillType
+  if (fill.fillType === 'Gradient' && fill.gradient) {
+    const g = fill.gradient;
+    return {
+      type: 'gradient',
+      gradientType: g.gradientType,  // Linear | Radial | Angular
+      direction: { from: g.from, to: g.to },
+      colors: g.stops.map(s => ({
+        position: s.position,
+        color: s.color
+      }))
+    };
+  }
+  
+  return {
+    type: 'solid',
+    color: fill.color
+  };
+}
+```
+
+### 问题 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 内部样式读取
+
+**严重程度**: 🟡 中
+
+**现象**：Symbol 实例的内部图层样式可能需要通过 `expandedLayers` 访问。
+
+**解决方案**：
+
+```javascript
+if (layer.type === 'SymbolInstance') {
+  layer.expandedLayers.forEach(nestedLayer => {
+    // 递归处理嵌套图层
+    measureLayer(nestedLayer);
+  });
+}
+```
+
+### 问题 6：阴影数组顺序
+
+**严重程度**: 🟢 低
+
+**现象**：多重阴影的顺序可能与视觉效果不一致。
+
+**解决方案**：记录所有阴影，并按 blur 值或 enabled 状态排序。
+
+---
+
+## 📐 标准测量脚本
+
+### 完整测量函数
+
+```javascript
+const sketch = require('sketch');
+
+/**
+ * 完整的图层测量函数
+ * 正确处理渐变色、阴影、圆角等
+ */
+function measureLayerComplete(layer) {
+  const result = {
+    name: layer.name,
+    type: layer.type,
+    frame: {
+      x: Math.round(layer.frame.x),
+      y: Math.round(layer.frame.y),
+      width: Math.round(layer.frame.width),
+      height: Math.round(layer.frame.height),
+    },
+  };
+  
+  if (!layer.style) return result;
+  
+  // ========== 填充色 ==========
+  const enabledFills = layer.style.fills?.filter(f => f.enabled) || [];
+  if (enabledFills.length > 0) {
+    result.fills = enabledFills.map(fill => {
+      if (fill.fillType === 'Gradient' && fill.gradient) {
+        const g = fill.gradient;
+        return {
+          type: 'gradient',
+          gradientType: g.gradientType,
+          from: g.from,
+          to: g.to,
+          stops: g.stops.map(s => ({
+            position: s.position,
+            color: s.color
+          }))
+        };
+      }
+      return {
+        type: 'solid',
+        color: fill.color
+      };
+    });
+  }
+  
+  // ========== 边框 ==========
+  const enabledBorders = layer.style.borders?.filter(b => b.enabled) || [];
+  if (enabledBorders.length > 0) {
+    result.borders = enabledBorders.map(b => ({
+      color: b.color,
+      thickness: b.thickness,
+      position: b.position  // inside | outside | center
+    }));
+  }
+  
+  // ========== 阴影 ==========
+  const enabledShadows = layer.style.shadows?.filter(s => s.enabled) || [];
+  if (enabledShadows.length > 0) {
+    result.shadows = enabledShadows.map(s => ({
+      color: s.color,
+      blur: s.blur,
+      x: s.x,
+      y: s.y,
+      spread: s.spread || 0,
+      isInner: s.isInnerShadow || false
+    }));
+  }
+  
+  // ========== 内阴影 ==========
+  const innerShadows = layer.style.innerShadows?.filter(s => s.enabled) || [];
+  if (innerShadows.length > 0) {
+    result.innerShadows = innerShadows.map(s => ({
+      color: s.color,
+      blur: s.blur,
+      x: s.x,
+      y: s.y,
+      spread: s.spread || 0
+    }));
+  }
+  
+  // ========== 圆角 ==========
+  if (layer.style.corners) {
+    const radii = layer.style.corners.radii;
+    // 检查是否四角相同
+    if (radii.every(r => r === radii[0])) {
+      result.borderRadius = radii[0];
+    } else {
+      result.borderRadius = radii;  // [topLeft, topRight, bottomRight, bottomLeft]
+    }
+  }
+  
+  // ========== 文字属性 ==========
+  if (layer.type === 'Text') {
+    result.text = {
+      content: layer.text,
+      fontSize: layer.style.fontSize,
+      fontFamily: layer.style.fontFamily,
+      fontWeight: layer.style.fontWeight,
+      textColor: layer.style.textColor,
+      alignment: layer.style.alignment,
+      lineHeight: layer.style.lineHeight,
+      letterSpacing: layer.style.kerning
+    };
+  }
+  
+  // ========== 透明度 ==========
+  if (layer.style.opacity !== undefined && layer.style.opacity !== 1) {
+    result.opacity = layer.style.opacity;
+  }
+  
+  // ========== 模糊效果 ==========
+  if (layer.style.blur?.enabled) {
+    result.blur = {
+      type: layer.style.blur.blurType,
+      radius: layer.style.blur.radius
+    };
+  }
+  
+  return result;
+}
+
+/**
+ * 递归测量整个画板
+ */
+function measureArtboard(artboard) {
+  const results = [];
+  
+  function traverse(layer, depth = 0) {
+    if (layer.hidden) return;
+    
+    const data = measureLayerComplete(layer);
+    data.depth = depth;
+    results.push(data);
+    
+    // 递归子图层
+    if (layer.layers) {
+      layer.layers.forEach(child => traverse(child, depth + 1));
+    }
+    
+    // Symbol 展开图层
+    if (layer.expandedLayers) {
+      layer.expandedLayers.forEach(child => traverse(child, depth + 1));
+    }
+  }
+  
+  traverse(artboard);
+  return results;
+}
+
+// 使用示例
+const doc = sketch.getSelectedDocument();
+const artboard = doc.selectedLayers.layers[0];
+const measurements = measureArtboard(artboard);
+console.log(JSON.stringify(measurements, null, 2));
+```
+
+---
+
+## 🎨 颜色转换
+
+### Sketch 颜色到各框架
+
+```javascript
+/**
+ * 将 Sketch 颜色转换为各框架格式
+ * @param {string} sketchColor - Sketch 颜色格式 "#rrggbbaa"
+ * @param {string} framework - 目标框架
+ */
+function convertColor(sketchColor, framework) {
+  // Sketch 格式: #rrggbbaa
+  const r = parseInt(sketchColor.slice(1, 3), 16);
+  const g = parseInt(sketchColor.slice(3, 5), 16);
+  const b = parseInt(sketchColor.slice(5, 7), 16);
+  const a = parseInt(sketchColor.slice(7, 9), 16) / 255;
+  
+  switch (framework) {
+    case 'flutter':
+      // Flutter: Color(0xAARRGGBB)
+      const flutterHex = sketchColor.slice(7, 9) + sketchColor.slice(1, 7);
+      return `Color(0x${flutterHex.toUpperCase()})`;
+    
+    case 'css':
+      // CSS: rgba(r, g, b, a)
+      if (a === 1) {
+        return sketchColor.slice(0, 7);
+      }
+      return `rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})`;
+    
+    case 'react-native':
+      // React Native: '#RRGGBBAA' 或 'rgba(...)'
+      if (a === 1) {
+        return `'${sketchColor.slice(0, 7)}'`;
+      }
+      return `'rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})'`;
+    
+    default:
+      return sketchColor;
+  }
+}
+
+// 渐变转换
+function convertGradient(gradient, framework) {
+  const colors = gradient.stops.map(s => 
+    convertColor(s.color, framework)
+  );
+  
+  switch (framework) {
+    case 'flutter':
+      return `LinearGradient(
+  begin: Alignment(${gradient.from.x * 2 - 1}, ${gradient.from.y * 2 - 1}),
+  end: Alignment(${gradient.to.x * 2 - 1}, ${gradient.to.y * 2 - 1}),
+  colors: [${colors.join(', ')}],
+)`;
+    
+    case 'css':
+      const angle = Math.atan2(
+        gradient.to.y - gradient.from.y,
+        gradient.to.x - gradient.from.x
+      ) * 180 / Math.PI + 90;
+      return `linear-gradient(${angle}deg, ${colors.join(', ')})`;
+    
+    default:
+      return colors;
+  }
+}
+```
+
+---
+
+## ✅ 使用检查清单
+
+### 开始测量前
+
+- [ ] 确认选中正确的画板/Frame
+- [ ] 检查是否有隐藏图层需要测量
+- [ ] 确认设计稿是最新版本
+
+### 测量过程中
+
+- [ ] 对每个颜色检查 `fillType` 是否为 Gradient
+- [ ] 阴影检查是否有多重阴影
+- [ ] 圆角检查四角是否相同
+- [ ] 文字检查行高是否有定义
+
+### 测量完成后
+
+- [ ] 与设计稿视觉对比
+- [ ] 渐变色验证（最容易出错）
+- [ ] 透明度验证
+- [ ] 响应式适配验证
+
+---
+
+## 📚 相关资源
+
+- [Sketch JavaScript API 文档](https://developer.sketch.com/reference/api/)
+- [设计稿还原规范](../workflows/design-restoration.md)
+- [颜色系统规范](../color-system.md)
+
+---
+
+**维护者**: MTA工作室  
+**创建日期**: 2026-01-20  
+**最后更新**: 2026-01-21
+
+### 更新日志
+
+| 版本 | 日期 | 更新内容 |
+|------|------|---------|
+| v1.0 | 2026-01-20 | 初始版本 |
+| v1.1 | 2026-01-21 | 新增：fontWeight不可靠问题及fontName获取方案、图标导出规范、列表间距测量脚本 |