mta-mcp 1.0.1 → 1.0.3

package/agents/flutter.agent.md

@@ -136,103 +136,26 @@ get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
 
 ---
 
-## 🎨 设计稿还原强制规范
+## 🎨 设计稿还原
 
-> ⚠️ 使用 Sketch/Figma MCP 时必须遵守
+> ⚠️ 详细规范请调用：`get_standard_by_id({ id: 'design-restoration' })`
 
-### 🔴 全局样式优先（最高优先级）
+### 快速提示
 
-**在还原任何 UI 前，必须首先通过项目搜索检查是否存在全局样式规范！**
+| 关键点 | 说明 |
+|--------|------|
+| **渐变色** | 检查 `fillType` 后读取 `gradient.stops`，勿直接用 `color` 属性 |
+| **全局样式** | 还原前先 grep 搜索项目现有 Token（颜色、圆角、阴影） |
+| **新拟态阴影** | 双阴影：右下深色 + 左上高光 |
+| **行高** | Flutter `height` 是比例值，非像素（如 24px/16px = 1.5） |
 
-#### 强制检查流程（搜索发现法）
+### 相关规范
 
-**核心原则**：不假设任何固定值，通过搜索项目代码发现现有规范
-
-##### 1. 圆角检查
-
-```bash
-# 搜索圆角定义
-grep -r "radius\|Radius\|RADIUS\|borderRadius" lib/ --include="*.dart"
-```
-
-**寻找模式**：
-- `DesignRadius` / `AppRadius` / `Radius` 类定义
-- `BorderRadius.circular(数字)` 的常量定义
-- 查看最常用的数值（如 12、16、20）
-
-**使用优先级**：
-1. 项目已有的 Radius 类常量（如 `DesignRadius.lg`）
-2. 查看现有组件中使用频率最高的值
-3. 如无规范，则直接使用设计稿数值，待后续统一
-
-##### 2. 按钮高度检查
-
-```bash
-# 搜索按钮高度定义
-grep -r "ButtonSize\|buttonHeight\|height.*button" lib/ --include="*.dart"
-```
-
-**寻找模式**：
-- `DesignButtonSizes` / `AppButtonSizes` 类
-- `Container(height: 常量)` 包裹的 Button
-- 查看主 CTA、标准按钮、小按钮的高度
-
-##### 3. 阴影检查
-
-```bash
-# 搜索阴影定义
-grep -r "Shadow\|boxShadow\|elevation" lib/ --include="*.dart"
-```
-
-**寻找模式**：
-- `DesignShadows` / `AppShadows` 类
-- `BoxShadow` 配置（offset、blur、color）
-- Neumorphism 阴影模式
-
-##### 4. 颜色检查
-
-```bash
-# 搜索颜色定义
-grep -r "Colors\|AppColors\|DesignColors\|Color(0x" lib/ --include="*.dart"
-```
-
-**寻找模式**：
-- 颜色类定义（通常在 `lib/core/themes/` 或 `lib/constants/`）
-- 查看主色、文字色、背景色的命名规范
-- 渐变色定义（`LinearGradient`）
-
-#### 通用禁止事项
-
-- ❌ **直接硬编码数值** - 应先搜索项目规范
-- ❌ **假设特定类名** - 不同项目命名不同（AppColors vs DesignColors）
-- ❌ **跳过搜索步骤** - 即使觉得"简单"也必须先搜索
-
-### 强制要求：完整读取选中元素及其所有子集
-
-```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}`);
-    }
-  });
-}
-```
-
-### 禁止事项
-- ❌ 只读容器属性，忽略内部元素位置
-- ❌ 每次只查一个属性，分散多轮获取
-- ❌ 假设"差不多"而不验证精确像素值
-- ❌ 用"试错法"调整参数
+| 规范 | 调用方式 |
+|------|----------|
+| 设计稿还原流程 | `get_standard_by_id({ id: 'design-restoration' })` |
+| Sketch MCP 用法 | `get_standard_by_id({ id: 'sketch-mcp' })` |
+| 跨框架语法映射 | `get_standard_by_id({ id: 'syntax-mapping' })` |
 
 ---
 

package/agents/vue3.agent.md

@@ -136,39 +136,26 @@ get_standard_by_id({ ids: ['vue3-composition', 'element-plus', 'i18n'] })
 
 ---
 
-## 🎨 设计稿还原强制规范（跨平台通用）
+## 🎨 设计稿还原
 
-> ⚠️ 还原 Sketch/Figma 设计稿时必须遵守
+> ⚠️ 详细规范请调用：`get_standard_by_id({ id: 'design-restoration' })`
 
-### 🔴 全局样式优先（最高优先级）
+### 快速提示
 
-**在还原任何 UI 前，必须首先检查项目是否存在全局样式规范！**
+| 关键点 | 说明 |
+|--------|------|
+| **渐变色** | 检查 `fillType` 后读取 `gradient.stops`，勿直接用 `color` 属性 |
+| **全局样式** | 还原前先搜索项目现有 CSS 变量 / Token |
+| **渐变语法** | `background: linear-gradient(135deg, #E01020, #B8101A)` |
+| **阴影语法** | `box-shadow: 8px 8px 20px rgba(28,43,69,0.15)` |
 
-#### 检查顺序
+### 相关规范
 
-1. **检查项目设计 Token** - 如 `design_constants.dart`、`design-tokens.ts`
-2. **优先使用语义化常量** - 而非硬编码数值
-3. **颜色/圆角/阴影/间距** - 必须使用全局定义
-
-#### 常见样式对照表
-
-| 类型 | 常见值 | 应使用 |
-|------|--------|--------|
-| **圆角** | 16px | `$radius.lg` / CSS 变量 `--radius-lg` |
-| **圆角** | 12px | `$radius.base` |
-| **圆角** | 8px | `$radius.xs` |
-| **按钮高度** | 56px | `$button.heightCTA` |
-| **按钮高度** | 40px | `$button.heightMedium` |
-| **按钮高度** | 32px | `$button.heightSmall` |
-| **阴影** | 拟物卡片 | `$shadow.card` |
-| **主色** | 红色CTA | `$color.primary` |
-| **文字色** | 深色 | `$color.textPrimary` |
-
-#### 禁止事项
-- ❌ 硬编码 `border-radius: 16px` - 应使用 CSS 变量或常量
-- ❌ 硬编码 `height: 56px` - 应使用按钮尺寸常量
-- ❌ 硬编码 `color: #1C2B45` - 应使用颜色变量
-- ❌ 手写 `box-shadow` - 应使用预设阴影 mixin
+| 规范 | 调用方式 |
+|------|----------|
+| 设计稿还原流程 | `get_standard_by_id({ id: 'design-restoration' })` |
+| Sketch MCP 用法 | `get_standard_by_id({ id: 'sketch-mcp' })` |
+| 跨框架语法映射 | `get_standard_by_id({ id: 'syntax-mapping' })` |
 
 ---
 

package/agents/wechat-miniprogram.agent.md

@@ -85,5 +85,28 @@ miniprogram/
 
 ---
 
+## 🎨 设计稿还原
+
+> ⚠️ 详细规范请调用：`get_standard_by_id({ id: 'design-restoration' })`
+
+### 快速提示
+
+| 关键点 | 说明 |
+|--------|------|
+| **渐变色** | 检查 `fillType` 后读取 `gradient.stops`，勿直接用 `color` 属性 |
+| **全局样式** | 还原前先搜索项目现有变量（app.wxss 中的 CSS 变量） |
+| **rpx 换算** | 设计稿 px * 2 = rpx（基于 750px 设计稿） |
+| **阴影语法** | `box-shadow: 8px 8px 20px rgba(28,43,69,0.15)` |
+
+### 相关规范
+
+| 规范 | 调用方式 |
+|------|----------|
+| 设计稿还原流程 | `get_standard_by_id({ id: 'design-restoration' })` |
+| Sketch MCP 用法 | `get_standard_by_id({ id: 'sketch-mcp' })` |
+| 跨框架语法映射 | `get_standard_by_id({ id: 'syntax-mapping' })` |
+
+---
+
 **维护团队**: MTA工作室  
 **设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取

package/package.json

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

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

@@ -0,0 +1,349 @@
+# 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：Symbol 内部样式读取
+
+**严重程度**: 🟡 中
+
+**现象**：Symbol 实例的内部图层样式可能需要通过 `expandedLayers` 访问。
+
+**解决方案**：
+
+```javascript
+if (layer.type === 'SymbolInstance') {
+  layer.expandedLayers.forEach(nestedLayer => {
+    // 递归处理嵌套图层
+    measureLayer(nestedLayer);
+  });
+}
+```
+
+### 问题 3：阴影数组顺序
+
+**严重程度**: 🟢 低
+
+**现象**：多重阴影的顺序可能与视觉效果不一致。
+
+**解决方案**：记录所有阴影，并按 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-20