iven/hms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): design-handoff 升级为全流程编排器

Browse Source 
- 新增 Step 0: 调用 huashu-design 设计 HTML 原型
- 新增 Step 7: 调用 huashu-design 根据 SPEC 实施代码
- 支持两种输入模式: 从需求开始(完整7步) / 从原型开始(6步)
- 简化文档: 移除冗余的降级代码块，保留核心流程
This commit is contained in:
iven
2026-05-18 01:51:40 +08:00
parent 6759723731
commit 530262590e
1 changed files with 175 additions and 348 deletions
Download Patch File Download Diff File Expand all files Collapse all files

523
.claude/skills/design-handoff/SKILL.md
View File

@@ -1,17 +1,151 @@
---
name: design-handoff
description: 将 HTML 原型转换为结构化设计交付包（截图 + SPEC.md + Token 映射），供新会话 LLM 高保真实现
description: 设计交付编排器 — 调用 huashu-design 设计原型、解析生成 SPEC、再调用 huashu-design 实施代码，覆盖从需求到实现的完整流程
---
# 设计交付 Skill (design-handoff)
# 设计交付编排器 (design-handoff)
将 huashu-design 生成的 HTML 原型转换为结构化设计交付包，使新会话中的 LLM 能够高保真还原 UI 实现。
编排 huashu-design 完成从需求到代码实现的完整流程：
1. 调用 huashu-design 设计 HTML 原型
2. 解析原型生成 SPEC.md + 截图 + Token 映射
3. 调用 huashu-design 根据 SPEC 实施代码
## 触发词
- `design-handoff`
- `设计交付`
- `handoff`
- `设计并实现`
- `从设计到代码`
---
## 输入模式
### 模式 A：从需求开始（完整流程）
用户提供功能需求描述（无 HTML 文件），skill 执行 7 步完整流程。
**输入示例：**
```
/design-handoff 患者端家庭档案管理页面，包含家庭成员列表、添加/编辑/删除操作
```
### 模式 B：从原型开始（仅解析+实施）
用户提供已有 HTML 原型文件路径，跳过 Step 0，从 Step 1 开始。
**输入示例：**
```
/design-handoff docs/design/mp-13-family-profile.html
```
---
## 核心流程（7 步）
### Step 0: 设计原型（仅模式 A）
调用 huashu-design 生成 HTML 原型：
```
Skill("huashu-design", "设计 {用户需求描述}。要求：1) 使用 HMS 设计系统 Token（const T = {...}）2) 包含 IosFrame 设备框 3) 每个页面用 .screen-wrap 包裹 4) 输出到 docs/design/ 目录")
```
**关键要求传递给 huashu-design：**
- 使用项目 Token 系统（`const T = { pri: ..., bg: ..., r: ... }`）
- 每个页面/状态用 `.screen-wrap` 包裹并配中文 label
- 使用 `IosFrame` 组件呈现
- 输出为单文件 HTML，保存到 `docs/design/mp-{编号}-{名称}.html`
**完成后获得：** HTML 原型文件路径，进入 Step 1。
### Step 1: 解析 HTML 原型
调用 `scripts/parse-prototype.mjs` 解析 HTML 文件：
```bash
node .claude/skills/design-handoff/scripts/parse-prototype.mjs <html文件路径>
```
**输出（stdout JSON）：**
- `tokens`: T 对象所有键值对（如 `{"T.pri": "#C4623A", ...}`）
- `inlineStyles`: 内联样式值收集（按 CSS 属性分组）
- `screens`: 每个屏幕的标签和组件名
- `components`: 所有组件函数定义列表
- `variant`: `"patient"` 或 `"doctor"`（根据 T.pri 值自动检测）
**若脚本不存在：** LLM 自行解析 HTML，提取 T 对象和 DOM 结构。
### Step 2: 截图
调用 `scripts/extract-screenshots.mjs` 生成截图：
```bash
node .claude/skills/design-handoff/scripts/extract-screenshots.mjs <html文件路径> <输出目录>
```
**输出：** PNG 文件到输出目录，文件名由中文标签自动翻译为英文。
**若脚本不存在：** 指导用户手动截图，保存到 `docs/design/{原型名}/screenshots/`。
### Step 3: Token 匹配
调用 `scripts/match-tokens.mjs` 进行三层 Token 匹配：
```bash
node .claude/skills/design-handoff/scripts/parse-prototype.mjs <html> > /tmp/parse-result.json
node .claude/skills/design-handoff/scripts/match-tokens.mjs /tmp/parse-result.json .design/tokens.yml
```
**三层匹配算法：**
1. **别名直查** — 在 `aliases.prototype_keys` 中查找已确认映射（支持值条件匹配，区分 patient/doctor variant）
2. **值精确匹配** — 按 CSS 属性上下文消歧（borderRadius→radius, fontSize→typography）
3. **色彩模糊匹配** — RGB 欧几里得距离 < 30 视为近似
**若脚本不存在：** LLM 自行读取 tokens.yml 执行匹配。
### Step 4: 组件映射推断
读取 `defaults/components.yml`，按 DOM 特征推断组件映射。
### Step 5: 交互推断
调用 `scripts/infer-interactions.mjs` 推断交互行为：
```bash
node .claude/skills/design-handoff/scripts/infer-interactions.mjs <html文件路径> .claude/skills/design-handoff/rules/interaction-rules.yml
```
### Step 6: 组装 SPEC.md
将前 5 步数据组装为 SPEC.md，输出到 `docs/design/{原型名}/SPEC.md`。
### Step 7: 实施代码（全流程自动）
调用 huashu-design 根据 SPEC 实施代码：
```
Skill("huashu-design", "请根据以下设计规格实现代码。
设计规格文件: docs/design/{原型名}/SPEC.md
截图参考: docs/design/{原型名}/screenshots/
Token 映射: docs/design/{原型名}/tokens.json
实现要求：
1. 严格按照 SPEC.md 中的 Token 值（var(--tk-*))）设置样式
2. 使用映射的组件库组件（参见 SPEC.md 组件清单）
3. 实现所有交互行为（参见 SPEC.md 交互行为章节）
4. 未匹配的 Token 需确认后补充到 .design/tokens.yml
5. 遵循项目代码规范（CLAUDE.md）")
```
**关键要求传递给 huashu-design：**
- 读取 SPEC.md 中的 Token 映射，用 `var(--tk-*)` CSS 变量
- 使用组件库中已有组件（ContentCard, PrimaryButton, SectionTitle 等）
- 实现交互行为（点击、滚动、表单提交等）
- 输出到正确的页面目录（如 `apps/miniprogram/src/pages/xxx/`）
- 遵循长者模式适配要求
---
@@ -21,265 +155,29 @@ description: 将 HTML 原型转换为结构化设计交付包（截图 + SPEC.md
### 1. 输入验证
确认输入文件为 huashu-design 产物，须同时满足：
- 文件为 `.html` 格式
- 包含 React + Babel 的 script 标签（`<script src="...babel...">` 或 `type="text/babel"`）
- 包含 Token 定义块（`const T = {` 或等效全局样式常量）
**模式 A（从需求开始）：** 无需输入文件验证，直接进入 Step 0。
若不满足，输出错误并终止：
```
[design-handoff] 错误：输入文件不是 huashu-design 产物。
期望特征：
- React/Babel script 标签
- const T = { ... } 样式定义块
请确认输入文件来源。
```
**模式 B（从原型开始）：** 确认输入文件为 huashu-design 产物：
- 文件为 `.html` 格式
- 包含 React + Babel 的 script 标签
- 包含 Token 定义块（`const T = {`）
### 2. Token 配置文件初始化
检查项目根目录下的 `.design/tokens.yml` 是否存在：
- **存在** → 直接使用，跳过初始化
- **不存在** → 从 `defaults/tokens.yml` 复制到 `.design/tokens.yml`
若 `defaults/tokens.yml` 也不存在，输出警告并使用内置最小 Token 集：
```yaml
# 内置最小 Token 集（defaults/tokens.yml 缺失时的降级方案）
color:
primary: "#1890ff"
success: "#52c41a"
warning: "#faad14"
danger: "#ff4d4f"
text: "#333333"
text_secondary: "#666666"
bg: "#ffffff"
bg_secondary: "#f5f5f5"
border: "#d9d9d9"
spacing:
xs: 4
sm: 8
md: 16
lg: 24
xl: 32
fontSize:
h1: 28
h2: 22
body_lg: 18
body: 16
body_sm: 14
caption: 13
radius:
sm: 4
md: 8
lg: 16
pill: 999
```
检查 `.design/tokens.yml` 是否存在：
- **存在** → 直接使用
- **不存在** → 从 `defaults/tokens.yml` 复制
---
## 核心流程（6 步）
### Step 1: 解析 HTML 原型
调用 `scripts/parse-prototype.mjs` 解析输入 HTML 文件：
```bash
node scripts/parse-prototype.mjs <html文件路径>
```
**输出（stdout JSON）：**
- `tokens`: T 对象所有键值对（如 `{"T.pri": "#C4623A", ...}`）
- `inlineStyles`: 内联样式值收集（按 CSS 属性分组，如 `{"fontSize": ["32","28",...], ...}`）
- `screens`: 每个屏幕的标签和组件名（如 `[{"label": "访客首页", "component": "GuestHome"}]`）
- `components`: 所有组件函数定义列表
**若脚本不存在：** LLM 自行解析 HTML，提取 T 对象和 DOM 结构。
### Step 2: 截图
调用 `scripts/extract-screenshots.mjs` 生成截图：
```bash
node scripts/extract-screenshots.mjs <html文件路径> <输出目录>
```
**输出：** PNG 文件到输出目录，文件名由中文标签自动翻译为英文。
- 每个 `.screen-wrap` 生成一张截图（裁掉 IosFrame 设备框、状态栏、Home Indicator）
- 无 `.screen-wrap` 时降级为整页截图 `full-page.png`
**若脚本不存在：** 指导用户手动截图，保存到 `docs/design/{原型名}/screenshots/`。
### Step 3: Token 匹配
调用 `scripts/match-tokens.mjs` 进行三层 Token 匹配：
```bash
# 先保存 Step 1 的输出到临时文件
node scripts/parse-prototype.mjs <html> > /tmp/parse-result.json
node scripts/match-tokens.mjs /tmp/parse-result.json .design/tokens.yml
```
**三层匹配算法：**
1. **别名直查** — 在 `aliases.prototype_keys` 中查找已确认映射
2. **值精确匹配** — 按 CSS 属性上下文消歧（borderRadius→radius, fontSize→typography）
3. **色彩模糊匹配** — RGB 欧几里得距离 < 30 视为近似
**输出（stdout JSON）：**
- `matched`: 已匹配 Token（含 confidence: confirmed/pending/approximate）
- `unmatched`: 未匹配的 Token key 列表
- `inlineTokenMap`: 内联样式值的 Token 映射
- `summary`: 统计（confirmed/pending/approximate/unmatched 数量）
**若脚本不存在：** LLM 自行读取 tokens.yml 执行匹配。
### Step 4: 组件映射推断
读取 `defaults/components.yml`，然后 LLM 按 DOM 特征推断组件映射。
**若 `defaults/components.yml` 不存在：** 使用以下内置组件映射规则：
#### 组件推断规则（8 条）
按优先级从高到低依次匹配，首个命中的规则决定组件类型：
| # | DOM 特征 | 推断组件 | 关键判定信号 |
|---|----------|----------|-------------|
| 1 | 容器节点 + `borderRadius` + `boxShadow` + 内含标题元素 + 正文元素 | `ContentCard` | borderRadius > 0 + boxShadow 存在 + 子节点含标题层级文本 |
| 2 | 左侧竖线装饰（`borderLeft` / `::before` 伪元素宽度 3-6px）+ 标题文本 + 可选右侧链接文字 | `SectionTitle` | 3-6px 左侧彩色边框 + 标题级字号 |
| 3 | 按钮节点 + 主色背景（匹配 `color.primary`）+ 白色文字 + `height` 44-56px | `PrimaryButton` | 背景色 = primary + 文字色 = 白/接近白 + 按钮语义 |
| 4 | 按钮节点 + 边框存在 + 背景透明/白色 + 文字色 = 主色或中性色 | `SecondaryButton` | border 存在 + 背景无填充 + 按钮语义 |
| 5 | 页面最外层容器节点 + `padding` + 可滚动（`overflow: auto/scroll` 或页面 body 级） | `PageShell` | DOM 深度 = 1-2 + padding + 无固定高度 |
| 6 | 小型容器 + 接近正方形/圆形（宽高比 0.8-1.2）+ 包含数字或短文字 + 有背景色 | `StatusTag` | 宽高比 ≈ 1 + 内容简短 + 背景色非白 |
| 7 | 列表行 + 左侧图标区 + 双行文字（主文字 + 副文字）+ 右侧箭头或 chevron 符号 | `ListItem` | 行级容器 + 左图标 + 双行文本 + 右箭头 |
| 8 | 未匹配上述任何规则 | `需新建组件` | 标记为 `Unknown__<描述>`，需在 SPEC.md 中描述视觉特征 |
**推断方法：**
1. 对解析后的 DOM 树做深度优先遍历
2. 对每个非叶子节点，按上述 8 条规则依次检测
3. 命中规则 → 标记组件类型 + 记录判定依据
4. 全部未命中 → 标记 `需新建组件` + 附带节点样式摘要
5. 输出组件映射表到交付包
### Step 5: 交互推断
调用 `scripts/infer-interactions.mjs` 推断交互行为：
```bash
node scripts/infer-interactions.mjs <html文件路径> rules/interaction-rules.yml
```
**输出（stdout JSON）：**
- `interactions`: 每条规则的匹配结果（matched/unmatched、命中的 pattern、location 定位）
- `summary`: matched/unmatched 统计
**若脚本不存在：** LLM 自行推断：
1. 检查 DOM 中的 `onClick` / `onChange` 等事件绑定
2. 检查 CSS 中的 `transition` / `animation` / `@keyframes`
3. 检查 `cursor: pointer` 元素（隐含可点击）
4. 检查 `overflow: scroll/auto` 容器（隐含滚动行为）
5. 按钮语义元素（`<button>`、`role="button"`）推断点击行为
### Step 6: 组装 SPEC.md
读取 `templates/spec-template.md`，将前 5 步收集的数据组装为 SPEC.md。
**若模板不存在：** 使用以下结构：
```markdown
# {原型名称} 设计规格
> 由 design-handoff 自动生成 | 源文件: {HTML文件名} | 生成时间: {ISO日期}
## 1. 概览
- **原型文件**: {文件名}
- **截图**: screenshots/full.png
- **设计 Token 数**: {matched数}/{总Token数} 已匹配
- **组件数**: {组件总数}
- **交互行为数**: {交互总数}
## 2. 设计 Token
### 2.1 颜色
| Token 名称 | 值 | 使用位置 |
|------------|-----|---------|
| ... | ... | ... |
### 2.2 字号
| Token 名称 | 值 (px) | 使用位置 |
|------------|---------|---------|
| ... | ... | ... |
### 2.3 间距
| Token 名称 | 值 (px) | 使用位置 |
|------------|---------|---------|
| ... | ... | ... |
### 2.4 圆角
| Token 名称 | 值 (px) | 使用位置 |
|------------|---------|---------|
| ... | ... | ... |
## 3. 组件清单
### 3.1 组件树
{组件层级树形结构}
### 3.2 组件详情
#### {组件名}
- **推断规则**: 命中规则 #{N}
- **Token 依赖**: [列出使用的 Token]
- **子组件**: [列出子组件]
- **截图**: screenshots/sections/{组件名}.png（如有）
- **样式属性**:
```
{原始 CSS 属性键值对}
```
## 4. 交互行为
| 元素 | 事件类型 | 行为描述 | 实现建议 |
|------|---------|---------|---------|
| ... | click/scroll/input/transition | ... | ... |
## 5. 未匹配项
### 5.1 未匹配 Token
| 值 | 类型 | 出现位置 | 建议 Token 名称 |
|----|------|---------|---------------|
| ... | color/fontSize/spacing/radius | ... | ... |
### 5.2 需新建组件
| 组件名建议 | 视觉特征摘要 | 出现位置 |
|-----------|------------|---------|
| ... | ... | ... |
## 6. 实施注意事项
{LLM 根据原型复杂度自动生成的实现提示}
```
---
## 输出流程
### 目录结构
## 输出目录结构
```
docs/design/
mp-00-visitor.html # 原始原型（不修改）
mp-00-visitor/ # 交付包目录（与原型同名）
mp-00-visitor.html # 原始原型（Step 0 产物或已有文件）
mp-00-visitor/ # 交付包目录
├── SPEC.md # 设计规格文档（Step 6 产物）
├── screenshots/ # 截图目录
├── screenshots/ # 截图目录（Step 2 产物）
│ ├── home.png
│ └── profile.png
├── tokens.json # Token 匹配结果（Step 3 产物）
@@ -290,12 +188,12 @@ docs/design/
```yaml
prototype: {原型文件名}
source: {HTML文件绝对路径}
generated_at: {ISO 8601 时间戳}
source: {HTML文件路径}
variant: patient | doctor
generated_at: {ISO 8601}
tokens:
matched: {数}
unmatched: {数}
pending: {数}
components:
total: {数}
mapped: {数}
@@ -303,120 +201,49 @@ components:
interactions: {数}
```
### 终端输出
---
完成全部步骤后，在终端输出实施 Prompt 模板：
## 终端输出
完成全部步骤后：
```
============================================================
设计交付完成: {原型名}
输出目录: docs/design/{原型名}/
模式: {完整流程 | 仅解析}
Variant: {patient | doctor}
Token 匹配: {matched}/{total} ({unmatched} 未匹配)
组件: {total} ({new} 需新建)
交互: {数} 项
下一步: 调用 huashu-design 实施代码
============================================================
下一步：在新会话中粘贴以下 Prompt 实现设计
--- BEGIN PROMPT ---
请根据设计规格实现 {原型名称} 页面。
设计规格文件: docs/design/{原型名}/SPEC.md
截图参考: docs/design/{原型名}/screenshots/full.png
Token 文件: docs/design/{原型名}/tokens.json
实现要求：
1. 严格按照 SPEC.md 中的 Token 值设置样式
2. 使用 SPEC.md 中映射的组件，若标记为"需新建"则先创建组件
3. 实现所有交互行为（见 SPEC.md 第 4 节）
4. 未匹配的 Token 需确认后补充到 .design/tokens.yml
--- END PROMPT ---
```
---
## 批处理模式
当输入为 glob 模式（如 `docs/design/*.html`）或多个文件路径时：
1. 展开为文件列表
2. 逐个执行 6 步流程（串行，避免截图冲突）
3. 每个文件输出到 `docs/design/{各自原型名}/`
4. 全部完成后生成索引文件：
### docs/design/INDEX.md
```markdown
# 设计交付索引
> 自动生成于 {ISO 日期}
| # | 原型名 | 截图 | SPEC | Token 匹配率 | 组件数 | 状态 |
|---|--------|------|------|------------|--------|------|
| 1 | {名称} | [截图](./{名称}/screenshots/full.png) | [SPEC](./{名称}/SPEC.md) | {N}/{M} | {数} | 待实施 |
| 2 | ... | ... | ... | ... | ... | ... |
```
---
## 待确认项交互
完成 6 步流程后，若有 `pending` 或 `unmatched` Token，需与用户交互确认：
### 输出确认清单
```
[design-handoff] 以下 Token 需要确认：
【待确认 (pending)】
1. 值 "#2b85e4" ≈ color.primary (#1890ff) — 是否作为别名？
2. 值 15px ≈ spacing.lg (24px) — 是否新增 Token spacing.md_lg？
【未匹配 (unmatched)】
3. 值 "#722ed1" — 建议新增 Token: color.accent_purple
4. 值 10px — 建议新增 Token: spacing.ms
请回复序号+确认结果（如 "1:是, 2:新增, 3:color.purple, 4:忽略"）
```
### 处理用户确认
用户确认后：
1. 将 `pending` 项的别名关系写入 `.design/tokens.yml` 的 `aliases` 字段
2. 将 `unmatched` 项中确认新增的 Token 写入 `.design/tokens.yml` 对应分类
3. 更新 `tokens.json` 和 `SPEC.md` 中的匹配状态
### aliases 格式示例
```yaml
# .design/tokens.yml
color:
primary: "#1890ff"
aliases:
blue_hover: "#2b85e4" # 用户确认: primary 的 hover 态别名
accent_purple: "#722ed1" # 用户确认: 新增 accent 色值
```
完成 Step 1-6 后，若有 `pending` 或 `unmatched` Token，需与用户交互确认后再进入 Step 7。
---
## 脚本说明
本 Skill 引用以下脚本（位于 `scripts/` 目录）：
| 脚本 | 用途 |
|------|------|
| `scripts/parse-prototype.mjs` | 解析 HTML 原型为结构化 JSON |
| `scripts/extract-screenshots.mjs` | Playwright 截图（裁掉设备框） |
| `scripts/match-tokens.mjs` | 三层 Token 匹配 |
| `scripts/infer-interactions.mjs` | 交互行为推断 |
| 脚本 | 用途 | 输入 | 输出 |
|------|------|------|------|
| `parse-prototype.mjs` | 解析 HTML 原型为结构化 JSON | HTML 文件路径 | JSON DOM 树 |
| `extract-screenshots.mjs` | 使用 Puppeteer/Playwright 截图 | HTML 文件路径 + 输出目录 | PNG 截图文件 |
| `match-tokens.mjs` | 样式值与 Token 库匹配 | 解析 JSON + tokens.yml | 匹配报告 JSON |
| `infer-interactions.mjs` | 推断交互行为 | 解析 JSON | 交互清单 JSON |
**降级策略：** 每个脚本缺失时，LLM 自行执行对应步骤。
**降级策略：** 每个脚本缺失时，LLM 自行执行对应步骤（详见各 Step 说明）。脚本仅为加速工具，不影响核心功能。
## 模板说明
## 模板与规则
| 文件 | 用途 |
|------|------|
| `templates/spec-template.md` | SPEC.md 的自定义模板（可选） |
| `defaults/tokens.yml` | Token 初始定义（新项目首次使用时复制到 `.design/`） |
| `defaults/components.yml` | 组件映射规则的自定义扩展（可选，覆盖内置 8 条规则） |
## 规则文件
`rules/` 目录可放置额外的设计规范约束文件（如品牌色限制、无障碍要求等），在 Step 4 组件推断和 Step 6 组装 SPEC 时自动加载。
| `templates/spec-template.md` | SPEC.md 模板 |
| `defaults/tokens.yml` | Token 注册表 + 别名映射 |
| `defaults/components.yml` | 组件映射规则 |
| `rules/interaction-rules.yml` | 交互推断规则 |