# Sketch 工具集使用指南

## 文件结构

| 文件 | 作用 | 使用方式 |
|------|------|----------|
| **sketch-tools.js** | 统一可执行入口（measure + layout + style + svg） | MTA skill 自动注入 CMD 变量，传入 `mcp_sketch_run_code` |
| **component-manifest.js** | Symbol→Flutter 组件注册表（纯数据） | AI 直接读取文件内容，**不传入 Sketch 执行** |
| artboard-measure.js | ⚠️ 已废弃（v4.4.0 已整合进 sketch-tools.js） | 仅作版本参考，**禁止直接调用** |
| layout-inspector.js | ⚠️ 已废弃（已整合进 sketch-tools.js） | 仅作版本参考，**禁止直接调用** |

---

## 执行模式

`sketch-tools.js` 通过顶部的 `_SKETCH_CMD` 变量控制执行哪个功能：

| 命令值 | 调用函数 | 适用场景 |
|--------|----------|----------|
| `'measure'` | `artboardMeasure()` | 选中画板/Frame，完整提取所有图层的样式、尺寸、间距、颜色 |
| `'layout'` | `layoutInspect()` | 选中 1 个容器分析子元素布局，或选中 2 个图层分析相对位置 |
| `'style'` | `quickStyleInspect()` | 选中小组件/Symbol，快速检查填充色、阴影、文字等样式属性 |
| `'svg'` | `exportIconAsSVG()` | 选中图标图层，导出为 SVG 并输出路径数据 |
| `'auto'` | `detectAndRun()` | 默认值，自动判断模式（小组件→style，大Frame→measure） |

---

## AI 调用方式（MCP）

### 推荐方式：通过 MTA skill 自动调用

```
// 一步到位：MTA skill 自动读取文件、注入 CMD、返回可执行脚本
mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "measure" } })

// 将返回的 script 传入 Sketch MCP 执行
mcp_sketch_run_code({ code: 返回结果中的script })
```

支持的 cmd 值：`measure`(默认)、`layout`、`style`、`svg`、`auto`

### 备选方式：手动读取文件

不需要安装为 Sketch Plugin。
AI 读取文件内容，注入 _SKETCH_CMD，传入 mcp_sketch_run_code 执行。

调用示例：

```javascript
// AI 注入命令变量（拼接在文件内容最前面），然后传入 mcp_sketch_run_code
const script = "var _SKETCH_CMD = 'layout';\n" + sketchToolsFileContent
```

### 为什么不安装为 Sketch Plugin？

| 方式 | 优点 | 缺点 |
|------|------|------|
| **MCP 调用（推荐）** | AI 可动态注入命令；无需安装；Git 可追踪更新 | 每次调用传输文件内容（约 3300 行） |
| Sketch Plugin 安装 | 可离线使用、键盘快捷键触发 | 无法动态注入 CMD；需手动更新；AI 无法控制执行模式 |

只有在需要**不依赖 AI 手工操作 Sketch** 时才考虑安装 Plugin。AI 驱动的开发流程始终用 MCP。

---

## component-manifest.js 的使用

此文件是 Symbol→Flutter 组件的注册表，不在 Sketch 中执行。AI 读取它来解决 Symbol 黑盒问题。

工作流：
1. 调用 `measure` 命令，遇到 `type: 'SymbolInstance'` 图层
2. AI 读取 `component-manifest.js`，用 `lookupComponent(layer.name)` 查找对应 Flutter 组件
3. 用查找结果替换 `expandedLayers`（Symbol Master 展开层），避免用默认值生成错误代码

---

## 典型调用序列

### 还原一个页面

```
1. 在 Sketch 中选中目标画板
2. AI: mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "measure" } })
3. AI: mcp_sketch_run_code({ code: script }) → 获取完整 JSON
4. AI 读取 component-manifest.js → 解析所有 SymbolInstance
5. AI 利用 flutterColor/flutterBoxShadow/flutterLinearGradient/flutterSvgCode 直接生成代码
6. FILL 类型尺寸使用 flutterHint 的 double.infinity
```

### 排查颜色/样式问题

```
1. 在 Sketch 中选中问题组件
2. AI: mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "style" } })
3. AI: mcp_sketch_run_code({ code: script }) → 获取填充、阴影、文字颜色
4. 对比 Flutter 代码中的 AppColors token（所有颜色已含 flutterColor 格式）
```

### 导出图标

```
1. 在 Sketch 中选中图标路径（不要选含背景圆形的外层 Group）
2. AI: mcp_mta_mta({ skill: "sketch_measure", params: { cmd: "svg" } })
3. AI: mcp_sketch_run_code({ code: script }) → 输出 SVG 路径数据 + backgroundLayerWarnings
```

---

## 版本说明

- **sketch-tools.js v4.5.0** — 统一入口版（整合 artboard-measure v4.4 + layout-inspector v1.0）
- **component-manifest.js v1.0.0** — Symbol 组件注册表

### sketch-tools.js 主要能力

- `extractSymbolOverrides()` — Symbol override 真实值（而非 Master 默认值）
- `extractShapePathSignature()` — ShapePath 语义推断（icon/background/divider）
- `getNativeTextBounds()` — CJK 文本实际渲染宽高（防 Flutter 多换行）
- `inferFlutterDirective()` — 间距模式→Flutter 布局指令（mainAxisAlignment/Spacer/SizedBox）
- `getNativeFillInfo()` / `getNativeTextColor()` — 原生 API 获取精确颜色（含 alpha）
- `getNativeGradientStops()` / `getNativeShadowColors()` — 精确渐变色标和阴影颜色
- `resolveGroupVisualStyle()` — 从 Group 子层提取真实视觉样式（含 Symbol 背景陷阱检测）