mta-mcp 2.17.0 → 3.0.0

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}`)
+  }
+}

package/common/i18n.md

@@ -1,385 +0,0 @@
-# 国际化 (i18n) 最佳实践
-
-适用于需要多语言支持的前端项目
-
-## 🎯 核心原则
-
-1. **零硬编码**: 所有用户可见文本必须使用翻译函数
-2. **键名规范**: 使用点分层级结构 (`common.save`, `user.profile.title`)
-3. **参数化**: 动态内容使用参数插值，不拼接字符串
-4. **回退机制**: 提供默认语言作为回退
-
-## 🔧 标准配置 (Vue I18n)
-
-### 目录结构
-```
-src/locales/
-├── index.ts           # i18n 初始化
-├── zh-CN.ts          # 简体中文
-├── en-US.ts          # 英文
-└── ja-JP.ts          # 日文
-```
-
-### 翻译文件示例
-```typescript
-// zh-CN.ts
-export default {
-  common: {
-    save: '保存',
-    cancel: '取消',
-    confirm: '确认',
-    delete: '删除',
-    edit: '编辑',
-    search: '搜索'
-  },
-  user: {
-    profile: {
-      title: '用户资料',
-      name: '姓名',
-      email: '邮箱'
-    }
-  },
-  message: {
-    saveSuccess: '保存成功',
-    deleteConfirm: '确认删除 {name} 吗？',
-    itemsSelected: '已选择 {count} 项'
-  }
-}
-```
-
-## 🎨 单文件 i18n 配置（轻量方案）
-
-**适用于不想引入 vue-i18n 插件的项目，使用自定义实现：**
-
-### 1. 配置位置
-- **翻译文件**: `src/locales/messages.ts` (键值对数组格式)
-- **语言状态**: `src/stores/state/locale.ts` (Pinia Store)
-- **全局注册**: `src/main.ts` (自定义 $t 方法)
-
-### 2. 翻译文件格式
-```typescript
-// src/locales/messages.ts
-// 索引 0 为英文，索引 1 为中文
-
-const messages: Record<string, [string, string]> = {
-  // ========== 通用 ==========
-  是: ['Yes', '是'],
-  否: ['No', '否'],
-  确定: ['OK', '确定'],
-  取消: ['Cancel', '取消'],
-  确认: ['Confirm', '确认'],
-  保存: ['Save', '保存'],
-  提交: ['Submit', '提交'],
-  搜索: ['Search', '搜索'],
-  查询: ['Query', '查询'],
-  重置: ['Reset', '重置'],
-  导出: ['Export', '导出'],
-  新增: ['Add', '新增'],
-  编辑: ['Edit', '编辑'],
-  删除: ['Delete', '删除'],
-  详情: ['Detail', '详情'],
-  操作: ['Operation', '操作'],
-  状态: ['Status', '状态'],
-  备注: ['Remark', '备注'],
-  
-  // ========== 业务模块 ==========
-  订单号: ['Order No', '订单号'],
-  金额: ['Amount', '金额'],
-  // ... 按模块分组
-}
-
-export default messages
-```
-
-### 3. 语言状态管理
-```typescript
-// src/stores/state/locale.ts
-import { ref } from 'vue'
-import { defineStore } from 'pinia'
-
-export const useLocaleStore = defineStore('locale', () => {
-  // 默认中文，可从 localStorage 读取
-  const locale = ref<'zh-cn' | 'en'>(
-    (localStorage.getItem('locale') as 'zh-cn' | 'en') || 'zh-cn'
-  )
-
-  const setLocale = (lang: 'zh-cn' | 'en') => {
-    locale.value = lang
-    localStorage.setItem('locale', lang)
-  }
-
-  const toggleLocale = () => {
-    setLocale(locale.value === 'zh-cn' ? 'en' : 'zh-cn')
-  }
-
-  return { locale, setLocale, toggleLocale }
-})
-```
-
-### 4. main.ts 全局注册
-```typescript
-// src/main.ts
-import { createApp } from 'vue'
-import { createPinia } from 'pinia'
-import App from './App.vue'
-import messages from '@/locales/messages'
-import { useLocaleStore } from '@/stores'
-
-const app = createApp(App)
-const pinia = createPinia()
-
-// ⚠️ 必须先注册 pinia，再使用 store
-app.use(pinia)
-
-// 获取语言状态
-const localeStore = useLocaleStore()
-
-// 注册全局 $t 方法
-app.config.globalProperties.$t = (key: string): string => {
-  const translation = messages[key]
-  if (!translation) {
-    console.warn(`[i18n] Missing translation: ${key}`)
-    return key
-  }
-  // 索引 0 为英文，索引 1 为中文
-  return translation[localeStore.locale === 'zh-cn' ? 1 : 0] || key
-}
-
-app.mount('#app')
-```
-
-### 5. 使用方式
-
-**在模板中（直接使用）：**
-```vue
-<template>
-  <el-button>{{ $t('保存') }}</el-button>
-  <el-table-column :label="$t('订单号')" prop="orderNo" />
-  <el-tag>{{ $t(row.status === 'success' ? '成功' : '失败') }}</el-tag>
-</template>
-```
-
-**在 script 中（需要获取实例）：**
-```typescript
-<script setup lang="ts">
-import { getCurrentInstance } from 'vue'
-
-// ⚠️ 必须通过 getCurrentInstance 获取
-const { appContext } = getCurrentInstance()!
-const $t = appContext.config.globalProperties.$t
-
-// 使用
-ElMessage.success($t('保存成功'))
-ElMessageBox.confirm($t('确认删除吗？'), $t('提示'))
-
-// 表单验证
-const rules = {
-  name: [{ required: true, message: $t('请输入名称'), trigger: 'blur' }]
-}
-</script>
-```
-
-### 6. 添加新翻译键
-
-在 `src/locales/messages.ts` 中按分类添加：
-
-```typescript
-const messages: Record<string, [string, string]> = {
-  // ========== 已有内容 ==========
-  
-  // ========== 新增：交易模块 ==========
-  汇款订单: ['Remittance Order', '汇款订单'],
-  收款订单: ['Collection Order', '收款订单'],
-  交易流水: ['Transaction Record', '交易流水'],
-  
-  // ========== 新增：客户模块 ==========
-  客户名称: ['Customer Name', '客户名称'],
-  联系方式: ['Contact', '联系方式'],
-}
-```
-
-### ❌ 禁止事项
-
-```typescript
-// ❌ 不要引入 useI18n（项目未使用 vue-i18n）
-import { useI18n } from 'vue-i18n'
-
-// ❌ 不要硬编码文本
-<el-button>保存</el-button>
-
-// ❌ 不要字符串拼接
-const msg = '删除' + name + '成功'
-
-// ❌ 不要在翻译值中使用变量（当前实现不支持）
-$t('已选择 {count} 项', { count: 5 })  // 不支持！
-// ✅ 替代方案
-`${$t('已选择')} ${count} ${$t('项')}`
-```
-
-## ✅ 最佳实践
-
-### Vue 组件中使用
-```vue
-<script setup lang="ts">
-import { getCurrentInstance } from 'vue'
-
-// 获取 $t 函数
-const { appContext } = getCurrentInstance()!
-const $t = appContext.config.globalProperties.$t
-</script>
-
-<template>
-  <!-- ✅ 好 -->
-  <el-button>{{ $t('common.save') }}</el-button>
-  <el-table-column :label="$t('user.profile.name')" />
-  
-  <!-- 参数插值 -->
-  <p>{{ $t('message.deleteConfirm', { name: userName }) }}</p>
-  
-  <!-- 复数处理 -->
-  <span>{{ $t('message.itemsSelected', { count: selectedCount }) }}</span>
-  
-  <!-- ❌ 坏 -->
-  <el-button>保存</el-button>
-  <p>确认删除 {{ userName }} 吗？</p>
-</template>
-```
-
-### TypeScript 中使用
-```typescript
-import { ElMessage } from 'element-plus'
-
-// ✅ 好
-ElMessage.success($t('message.saveSuccess'))
-
-// 带参数
-ElMessage.warning($t('message.deleteConfirm', { name: user.name }))
-
-// ❌ 坏
-ElMessage.success('保存成功')
-```
-
-### 动态文本映射
-```typescript
-// ✅ 好 - 使用映射对象
-const statusMap = {
-  pending: $t('status.pending'),
-  success: $t('status.success'),
-  error: $t('status.error')
-}
-
-const statusText = statusMap[status]
-
-// 或在模板中
-{{ { 0: $t('type.input'), 1: $t('type.output') }[row.type] }}
-
-// ❌ 坏 - 硬编码
-const statusMap = {
-  pending: '待处理',
-  success: '成功',
-  error: '失败'
-}
-```
-
-## ⚠️ 禁止模式
-
-- ❌ 硬编码中文/英文文本
-- ❌ 字符串拼接: `'删除' + name + '吗？'`
-- ❌ 在代码中切换语言逻辑: `if (lang === 'zh') { ... }`
-- ❌ 重复的翻译键
-
-## 📋 代码审查清单
-
-- [ ] 所有用户可见文本使用 `$t()`
-- [ ] 翻译键使用点分层级结构
-- [ ] 动态内容使用参数插值
-- [ ] 所有语言文件有相同的键结构
-- [ ] ElMessage/ElMessageBox 的文本已翻译
-- [ ] 表单验证消息已翻译
-
-## 🔧 常见场景
-
-### 表单验证
-```typescript
-const rules = {
-  name: [
-    { 
-      required: true, 
-      message: $t('validation.required', { field: $t('user.profile.name') }), 
-      trigger: 'blur' 
-    },
-    { 
-      min: 2, 
-      max: 20, 
-      message: $t('validation.length', { min: 2, max: 20 }), 
-      trigger: 'blur' 
-    }
-  ]
-}
-```
-
-### 确认对话框
-```typescript
-const handleDelete = async (row: User) => {
-  try {
-    await ElMessageBox.confirm(
-      $t('message.deleteConfirm', { name: row.name }),
-      $t('common.warning'),
-      {
-        confirmButtonText: $t('common.confirm'),
-        cancelButtonText: $t('common.cancel'),
-        type: 'warning'
-      }
-    )
-    // 执行删除
-  } catch (err) {
-    // 用户取消
-  }
-}
-```
-
-### 时间格式化
-```typescript
-// 使用 i18n 的日期格式化
-const formatDate = (date: Date) => {
-  return new Intl.DateTimeFormat(locale.value, {
-    year: 'numeric',
-    month: 'long',
-    day: 'numeric'
-  }).format(date)
-}
-```
-
-## 🌍 语言切换
-
-```typescript
-import { useI18n } from 'vue-i18n'
-
-const { locale } = useI18n()
-
-// 切换语言
-const changeLanguage = (lang: 'zh-CN' | 'en-US') => {
-  locale.value = lang
-  localStorage.setItem('language', lang)
-}
-```
-
----
-
-## ⚠️ 重要：配置文件管理
-
-### Copilot 配置 .gitignore
-
-**推荐做法：**将自动生成的 `.github/copilot-instructions.md` 添加到 `.gitignore`
-
-```gitignore
-# Copilot 配置(自动生成)
-.github/copilot-instructions.md
-```
-
-**适用项目：**
-- 需要国际化的 Web 应用
-- Vue.js、React、Angular 项目
-- 多语言支持的前端项目
-
-**详细指南**: 参考 [Copilot .gitignore 通用指南](../docs/guides/COPILOT_GITIGNORE_GUIDE.md)