# 设计工具适配层 — 接口定义

> 本文件定义设计工具的抽象接口。具体实现见 `adapters/{tool}.md`。
> 当前可用适配器：`pencil.md`（Pencil CLI）

## 前置条件

使用前需确认目标工具已安装且可用：

```
pencil --version  # 或其他工具的版本命令
```

## 操作接口

### 1. detect(root_dir)

**用途**：检测项目根目录中是否存在设计文件。

| 参数 | 类型 | 说明 |
|------|------|------|
| root_dir | string | 项目根目录绝对路径 |

**返回**：

```yaml
found: true | false
files:
  - path: "VividSpark1.2.pen"
    size: "988KB"
    modified: "2026-04-09"
tool_type: "pencil" | "figma" | null
```

### 2. extract_structure(file)

**用途**：提取设计文件的页面结构和组件层级。

| 参数 | 类型 | 说明 |
|------|------|------|
| file | string | 设计文件绝对路径 |

**返回**：

```yaml
pages:
  - id: "2dEtF"
    name: "Dashboard"
    type: "frame"
  - id: "Er7uX"
    name: "Auth & Pricing"
    type: "frame"
components:
  - name: "Button"
    instances: 12
  - name: "Card"
    instances: 8
```

### 3. extract_tokens(file)

**用途**：提取设计文件的样式变量（Token）。

| 参数 | 类型 | 说明 |
|------|------|------|
| file | string | 设计文件绝对路径 |

**返回**：

```yaml
colors:
  background: "#0a0a0f"
  foreground: "#ffffff"
  primary: "#ff6b2b"
  card: "#141420"
  border: "#2a2a3a"
  muted_foreground: "#8888a0"
fonts:
  family: "Inter"
  sizes: [12, 14, 16, 18, 20, 24, 32, 48]
  weights: [400, 500, 600, 700]
spacing:
  unit: "4"
  scale: [4, 8, 12, 16, 20, 24, 32, 48, 64]
radii:
  sm: "4"
  md: "8"
  lg: "12"
  xl: "16"
  full: "9999"
shadows:
  sm: "0 1px 2px rgba(0,0,0,0.3)"
  md: "0 4px 8px rgba(0,0,0,0.4)"
  lg: "0 8px 16px rgba(0,0,0,0.5)"
```

### 4. export_screenshots(file, output_dir, pages)

**用途**：导出设计文件中指定页面的截图。

| 参数 | 类型 | 说明 |
|------|------|------|
| file | string | 设计文件绝对路径 |
| output_dir | string | 截图输出目录 |
| pages | string[] | 可选，指定导出的页面 ID。为空则导出所有顶层页面 |

**返回**：

```yaml
screenshots:
  - page_id: "2dEtF"
    page_name: "Dashboard"
    path: "{output_dir}/dashboard.png"
    width: 1440
    height: 900
  - page_id: "Er7uX"
    page_name: "Auth & Pricing"
    path: "{output_dir}/auth-pricing.png"
```

### 5. compare_visuals(img_a, img_b)

**用途**：对比两张截图的视觉差异。

| 参数 | 类型 | 说明 |
|------|------|------|
| img_a | string | 参考截图路径（设计文件导出） |
| img_b | string | 实际截图路径（原型或实现） |

**返回**：

```yaml
score: "85%"
differences:
  - level: "critical" | "moderate" | "minor"
    category: "layout" | "color" | "spacing" | "typography" | "component"
    description: "导航栏位置不一致"
    suggestion: "调整导航栏为固定顶部"
```

## 使用模式

在 d8d 技能步骤文件中引用本接口：

```markdown
#### 设计文件操作

加载 `_d8d/design-tool-adapter/interface.md` 了解可用操作。
加载 `_d8d/design-tool-adapter/adapters/pencil.md` 了解具体命令。

1. 调用 detect(项目根目录) 检测设计文件
2. IF found: 调用 extract_structure() + extract_tokens() 提取设计信息
3. 调用 export_screenshots() 导出页面截图
4. 调用 compare_visuals() 对比设计 vs 实现
```

## 适配器实现指南

新增适配器（如 Figma）只需在 `adapters/` 下创建 `{tool}.md`，实现上述 5 个操作。每个操作需包含：
- 具体的命令或 API 调用
- 输入参数映射
- 输出格式转换（需匹配本接口定义的返回格式）
- 环境要求和前置条件