9dae3a2be6
新增: - _d8d/design-tool-adapter/interface.md: 5 个抽象操作接口 - _d8d/design-tool-adapter/adapters/pencil.md: Pencil CLI 实现 修改: - d8d-prototype step-01/step-07: 去除 mcp__pencil 硬编码，改用适配层 - d8d-iterate phase-00/01/03: 新增设计文件变更检测和重新提取 - d8d-requirements phase-00/02/workflow: 设计文件检测改用适配层 - d8d-skills-sync: 新增 _d8d/ 目录同步支持 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
164 lines
3.7 KiB
Markdown
164 lines
3.7 KiB
Markdown
# 设计工具适配层 — 接口定义
|
||
|
||
> 本文件定义设计工具的抽象接口。具体实现见 `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 调用
|
||
- 输入参数映射
|
||
- 输出格式转换（需匹配本接口定义的返回格式）
|
||
- 环境要求和前置条件
|