# 设计 Agent 构建方案：Huashu Design 调用方式与任务路线

问题开始时间：2026-06-11-03-34-08

资料来源：
- GitHub 仓库：<https://github.com/alchaincyf/huashu-design>
- 本地下载目录：`文档润色流和知识库构建流/huashu-design`
- 本次核对的 GitHub HEAD：`55ff7cc03e0817a39a7987a6331b7eef17faf40c`
- 重点阅读文件：`README.md`、`README.en.md`、`SKILL.md`、`references/*.md`、`scripts/*.js|*.mjs|*.sh|*.py`、`test-prompts.json`

## 1. 总体定位

`huashu-design` 是一个跨 agent 通用的设计 skill。它把 HTML 当作视觉设计媒介，用于快速制作可交付的高保真视觉产物：

- 产品发布动画；
- 可点击 App / Web 原型；
- HTML 幻灯片和可编辑 PPTX；
- 信息图、数据可视化、印刷级图文；
- 多风格设计变体；
- 设计方向顾问；
- 5 维度专家评审。

它强调“你是用 HTML 工作的设计师，不是程序员”。因此任务核心不是写网页代码，而是根据产物类型切换身份：动画师、UX 设计师、幻灯片设计师、原型师、信息图设计师。

不适用场景：
- 生产级 Web App；
- SEO 网站；
- 需要后端的动态系统；
- 长期维护型业务系统。

这些应使用普通前端工程或 `frontend-design` 类 skill，而不是 `huashu-design`。

## 2. 安装与调用入口

### 2.1 安装

```bash
npx skills add alchaincyf/huashu-design
```

支持 Claude Code、Cursor、Codex、OpenClaw、Hermes 等 markdown skill 兼容 agent。

本项目本地资料路径：

```text
文档润色流和知识库构建流/huashu-design/
```

### 2.2 自然语言调用

```text
做一个 AI 番茄钟 iOS 原型，4-6 个核心屏幕，能点击切换。
```

```text
把这段产品逻辑做成 30 秒发布动画，导出 MP4、60fps MP4 和 GIF。
```

```text
做一套 10 页产品 pitch deck，先给 2 页 showcase 定视觉 grammar，再导出 PDF；之后我可能要可编辑 PPTX。
```

```text
基于这些数据做一张 1080×1920 的竖版信息图，要求印刷级排版和真实数据标注。
```

```text
请对这个设计做 5 维度专家评审，并给出 Keep / Fix / Quick Wins。
```

## 3. 核心规则

### 3.1 事实验证先于假设

涉及具体产品、公司、技术、版本、规格、发布日期时，第一步必须搜索核实：

```text
产品存在性 / 发布状态 / 最新版本 / 关键规格
```

确认后写入 `product-facts.md`，再进入设计。

适用场景：
- 产品发布动画；
- 品牌官网；
- 某公司 App 原型；
- 具体竞品对比 deck；
- 新技术、新模型、新产品介绍图。

### 3.2 核心资产协议

只要设计里出现真实品牌或真实产品，就必须收集品牌资产。资产优先级：

| 资产 | 必需性 |
|---|---|
| Logo | 任何品牌必需 |
| 产品图 / 渲染图 | 实体产品必需 |
| UI 截图 | 数字产品必需 |
| 品牌色 | 辅助识别 |
| 字体 | 辅助识别 |
| 气质关键词 | Agent 自检 |

5 步流程：

```text
问用户资产清单
  -> 搜官方渠道
  -> 下载 logo / 产品图 / UI 截图
  -> 验证真实性和质量
  -> 固化为 brand-spec.md
```

硬底线：
- 不用 CSS 剪影或手画 SVG 代替真实产品图；
- 不凭记忆猜品牌色；
- 找不到 logo 时停下问用户；
- 品牌资产写入 `brand-spec.md` 后，所有 HTML 都引用该 spec。

### 3.3 Junior Designer 工作流

`huashu-design` 的默认工作姿态是 junior designer 给 manager 汇报：

```text
一次性问清问题
  -> 写 assumptions + placeholders + reasoning
  -> 尽早 show
  -> 填真实内容
  -> 做 variations / Tweaks
  -> Playwright 验证
  -> 交付
```

意义：先暴露假设，尽早让用户纠偏，避免做完后大返工。

### 3.4 反 AI Slop

默认避免：
- 紫色科技渐变；
- emoji 当图标；
- 圆角卡片 + 左侧彩色 border accent；
- 手画 SVG 人脸、设备、场景；
- 没依据的数据卡、假 quote；
- Inter / Roboto / system font 作为全局 display；
- 均匀深蓝底 + 通用霓虹 glow。

正向做法：
- 从品牌资产和真实内容出发；
- 用 `text-wrap: pretty`、CSS Grid、明确字体配对；
- 使用 `oklch()` 或真实品牌色；
- 没素材就诚实 placeholder，不编造。

## 4. 设计方向顾问模式

触发条件：
- 用户只说“做个好看的”“帮我设计”“做个 XX”，没有风格参考；
- 没有 design system、截图、Figma、品牌规范；
- 用户明确要求“推荐风格”“给几个方向”；
- 用户不知道自己想要什么风格。

默认流程：

```text
Phase 1: 最多 3 个问题澄清目标、受众、输出格式，同时索要 logo / 品牌色 / 参考
Phase 2: 用 200 字以上重述需求本质
Phase 3: 写 500 字以上设计 spec，统一尺寸、内容、气质、限制
Phase 3.5: 判断图片是否内容必需，必要时先取真图或官方 logo
Phase 4: 三套逻辑并行或串行出三版真实视觉
Phase 5: 用户基于截图选择、混合或重跑
Phase 6: 对选中方向做完整 Junior Designer pass
```

三套逻辑：

| 逻辑 | 做法 | 作用 |
|---|---|---|
| 秒数轮盘 | `date +%S`，从网页 20 或 PPT 20 风格库抽一个 | 打破模型总选安全极简的惯性 |
| 现实参照 | 找一个真实优秀案例或获奖案例，拆解后迁移 | 用现实高标准锚定 |
| 最佳设计师 | 假设无限预算，选择最适合该任务的设计师或工作室哲学 | 做更贴合内容的定制方向 |

风格库位置：

```text
references/design-styles.md
```

包含网页 20 种 + PPT 20 种 HTML 原生风格，并标注大胆 / 中性 / 安静、还原度和字体替代。

## 5. 不同需求的完成方式

### 5.1 产品发布动画 / Launch Film

适用：
- 产品升级宣传片；
- 品牌 launch film；
- launch trailer；
- 30 秒级高规格 hero animation；
- 用户要求 Apple 级、超级碗级、10x 细节。

路线：

```text
事实验证
  -> 核心资产协议
  -> 写 director's notes
  -> Stage + Sprite 实施动画
  -> 关键帧截图验证
  -> 导出 MP4 / 60fps MP4 / GIF
  -> 加 BGM + SFX
```

高规格 launch film 先写 director's notes，不直接写 HTML。结构包括：
- Director's Statement；
- Visual System；
- Story Arc；
- Shot-by-Shot Storyboard；
- Production Manifest。

调用口令：

```text
请用 huashu-design 做一个 30 秒产品发布动画。先核实产品事实和官方资产，再写 director's notes，之后用 Stage/Sprite 做 HTML 动画，并导出 MP4、60fps MP4 和 GIF。
```

关键 reference：

```text
references/launch-film-director-notes.md
references/animations.md
references/animation-best-practices.md
references/animation-pitfalls.md
references/video-export.md
references/audio-design-rules.md
references/sfx-library.md
```

常用脚本：

```bash
node scripts/render-video.js animation.html
bash scripts/convert-formats.sh animation.mp4
bash scripts/add-music.sh animation-60fps.mp4 --mood=tech
```

高质量 Stage 动画可用真 60fps 确定性渲染：

```bash
node scripts/render-video-seek.js animation.html --fps=60
```

注意：
- 动画产出默认加 `Created by Huashu-Design` 水印；
- 第三方品牌非官方动画应加“非官方出品”前缀；
- 用户明确不要水印时移除。

### 5.2 带解说的长视频 / 教程科普

适用：
- 5-20 分钟知识科普；
- 带配音教程；
- 长概念解释视频；
- “5 分钟讲清楚 XX”。

路线：

```text
先写解说稿
  -> scene-id 分段和 cue 标记
  -> TTS 生成 voiceover.mp3 + timeline.json
  -> 用 NarrationStage 根据真实音频时间驱动画面
  -> 渲染无声画面
  -> 混入人声和 BGM
```

调用口令：

```text
请用 huashu-design 做一个 5 分钟带解说的科普视频。先写解说稿，按 cue 生成时间线，再用 NarrationStage 做连续运动叙事，不要做成带配音的 PPT。
```

关键 reference：

```text
references/voiceover-pipeline.md
assets/narration_stage.jsx
scripts/tts-doubao.mjs
scripts/narrate-pipeline.mjs
scripts/render-narration.sh
scripts/mix-voiceover.sh
```

注意：
- 画面应是一段连续运动叙事，不是一页页 fade-in/out；
- 必须选 1-2 个贯穿全片的 hero element；
- 默认带字幕。

### 5.3 可点击 App 原型

适用：
- iOS / Android App 原型；
- Habit Tracker、读书笔记、跑步记录、AI 工具、Dashboard 类移动产品；
- 多屏交互 demo。

默认交付：

```text
平铺 4-6 个主界面
  + 每台设备都能点击
  + tab / modal / card / toggle 有状态反馈
  + Playwright 点击测试
```

默认架构：
- 单文件 inline React；
- 所有 JSX、data、styles 直接写在主 HTML；
- 本地图片用 base64；
- 不假设用户会启动服务器。

iOS 原型必须使用：

```text
assets/ios_frame.jsx
```

禁止手写 Dynamic Island、status bar、Home Indicator。

调用口令：

```text
请用 huashu-design 做一个跑步记录 App 的 iOS 原型，默认平铺 5 个核心界面，每台都能交互。使用 ios_frame.jsx，不要手写设备框；完成后跑 Playwright 点击测试。
```

核心屏幕示例：
- 今日总览；
- 跑步中实时数据；
- 路线地图；
- 历史记录；
- 月度统计；
- 设置。

验证：

```bash
python scripts/verify.py prototype.html --viewports 1440x900
```

交互测试最少覆盖：
- 进入详情；
- tab 切换；
- 关键按钮或弹层；
- 页面无 `pageerror`。

### 5.4 Web / SaaS 高保真原型

适用：
- 登录页；
- landing page；
- SaaS dashboard mockup；
- 产品功能演示页；
- 三风格对比。

路线：

```text
问 design context
  -> 有品牌/产品则走资产协议
  -> 模糊则走设计方向顾问三版
  -> 用 design_canvas 展示 variations
  -> 加 Tweaks 调参
  -> Playwright 多视口验证
```

调用口令：

```text
请用 huashu-design 做一个 SaaS 登录页面，先给我 3 个风格方向对比；每个方向都说明视觉逻辑，避免 AI slop。
```

变体展示组件：

```text
assets/design_canvas.jsx
```

Tweaks 适用：
- 颜色主题；
- 字号；
- 信息密度；
- layout；
- dark mode；
- feature flag。

关键 reference：

```text
references/workflow.md
references/design-context.md
references/design-styles.md
references/tweaks-system.md
references/verification.md
```

### 5.5 HTML 幻灯片 / 可编辑 PPT

适用：
- 产品 pitch deck；
- 演讲 PPT；
- 培训课件；
- 汇报材料；
- 研究或商业报告。

硬规则：

```text
HTML deck 永远是基础产物。
PDF / PPTX 都是从 HTML 衍生。
```

默认架构：

```text
项目名/
  index.html              # 从 assets/deck_index.html 复制并改 MANIFEST
  shared/
    tokens.css
  slides/
    01-cover.html
    02-agenda.html
    ...
```

如果 deck ≥ 5 页：

```text
先做 2 页 showcase 定 grammar
  -> 用户确认
  -> 批量做剩余页面
  -> 合成 HTML deck
  -> 导出 PDF
  -> 用户需要时再导出 PPTX
```

调用口令：

```text
请用 huashu-design 做一套 10 页产品 pitch deck。HTML 聚合演示版是基础产物，先做封面和一页内容 showcase 定视觉 grammar；通过后再批量制作，最后导出 PDF。如需可编辑 PPTX，再按 editable-pptx 约束导出。
```

可编辑 PPTX 的 4 条硬约束：
- body 使用 `960pt × 540pt` 匹配 `LAYOUT_WIDE`；
- 所有文字必须用 `<p>` 或 `<h1>`-`<h6>` 包裹；
- 背景、边框、阴影放在外层 `div`，文字标签只承载文字；
- `div` 不用 `background-image`，图片必须用 `<img>`；
- 避免 CSS gradient、web component、复杂 SVG。

常用脚本：

```bash
node scripts/export_deck_pdf.mjs --slides slides --out output/deck.pdf
node scripts/export_deck_pptx.mjs --slides slides --out output/deck.pptx
node scripts/gen_deck_thumbs.mjs --slides slides --out thumbs
```

关键 reference：

```text
references/slide-decks.md
references/editable-pptx.md
assets/deck_index.html
assets/deck_stage.js
scripts/html2pptx.js
```

注意：
- 不要为了 PPTX 牺牲 HTML 视觉质量，除非用户明确要求可编辑 PPTX；
- 如果用户既要动画又要可编辑 PPTX，要说明两者存在格式矛盾。

### 5.6 信息图 / 数据可视化

适用：
- 竖版长图；
- 横版信息图；
- 社交媒体数据卡；
- 文章内数据图；
- 印刷级图文。

常见规格：
- 竖版长图：`1080×1920`；
- 横版：`1920×1080`；
- 方形：`1080×1080`；
- 印刷文档正文最小 `10pt`，标题 `18-36pt`。

路线：

```text
确认数据来源
  -> 不编造数据
  -> 选信息层级：标题 -> 核心数据 -> 细节
  -> 用 CSS Grid / SVG / 图表组件排版
  -> 导出 PDF / PNG / SVG
  -> Playwright 截图检查
```

调用口令：

```text
请用 huashu-design 基于这批真实数据做一张 1080×1920 竖版信息图。要求信息层级清楚、数据不变形、可导出 PDF/PNG，设计上避免装饰性数据 slop。
```

推荐风格参考：
- Fathom；
- Müller-Brockmann；
- Stamen；
- Takram；
- Tufte 信息设计。

关键 reference：

```text
references/scene-templates.md
references/content-guidelines.md
references/design-styles.md
references/verification.md
```

### 5.7 多版本探索 / 设计变体

适用：
- 用户要“多做几个版本”；
- 第一版用户不满意但说不清；
- 多平台分发；
- 客户没拍板风格；
- 需要从保守到新颖形成一张地图。

路线：

```text
同一份内容 spec
  -> 3 个或 6 个独立设计方向
  -> 每版独立输出 HTML + 截图
  -> 5 维度审校
  -> 分配适合的使用场景
```

调用口令：

```text
请用 huashu-design 多视角并行做 6 个完全不同的视觉版本。每个版本指定不同设计师/导演/工作室 DNA，输出 HTML、关键帧截图和简短 README，最后做 5 维度评审和使用场景分配。
```

关键 reference：

```text
references/multi-perspective-parallel-case-study.md
references/critique-guide.md
```

若当前 agent 没有 subagent 能力，则串行做三版，但每版必须只读同一份 spec，不参考前一版，避免趋同。

### 5.8 设计评审

适用：
- “好不好看”；
- “帮我 review this design”；
- “打分”；
- “哪里能改得更专业”；
- 交付前主动质检。

5 个维度：
- 哲学一致性；
- 视觉层级；
- 细节执行；
- 功能性；
- 创新性。

输出结构：

```text
总体评分
分项评分
Keep
Fix
Quick Wins
```

调用口令：

```text
请用 huashu-design 的 5 维度专家评审体系检查这个 HTML 设计，给出评分、严重问题、修复方式和 5 分钟内最值得做的 3 个 quick wins。
```

关键 reference：

```text
references/critique-guide.md
```

## 6. 常用脚本索引

| 脚本 | 用途 |
|---|---|
| `scripts/verify.py` | Playwright 打开 HTML、截图、抓控制台错误 |
| `scripts/fetch_images.py` | 从 Wikimedia Commons 抓公共领域 / CC 真图 |
| `scripts/render-video.js` | HTML 动画录制为 25fps MP4 |
| `scripts/render-video-seek.js` | Stage 动画逐帧 seek，确定性真 60fps |
| `scripts/convert-formats.sh` | MP4 派生 60fps MP4 和 GIF |
| `scripts/add-music.sh` | 给 MP4 添加 BGM |
| `scripts/mix-voiceover.sh` | 混入旁白音频 |
| `scripts/render-narration.sh` | 解说驱动动画最终渲染 |
| `scripts/tts-doubao.mjs` | 豆包 TTS |
| `scripts/narrate-pipeline.mjs` | 解说稿转 voiceover + timeline |
| `scripts/export_deck_pdf.mjs` | 多文件 HTML deck 导出 PDF |
| `scripts/export_deck_stage_pdf.mjs` | 单文件 deck-stage 导出 PDF |
| `scripts/export_deck_pptx.mjs` | HTML deck 导出可编辑 PPTX |
| `scripts/html2pptx.js` | DOM computedStyle 转 PowerPoint 对象 |
| `scripts/gen_deck_thumbs.mjs` | 给 deck 概览墙生成缩略图 |

## 7. Starter Components 索引

| 组件 | 何时使用 |
|---|---|
| `assets/ios_frame.jsx` | iOS App 原型，标准 iPhone 外壳 |
| `assets/android_frame.jsx` | Android App 原型 |
| `assets/macos_window.jsx` | 桌面 App mockup |
| `assets/browser_window.jsx` | 网页放进浏览器窗口 |
| `assets/design_canvas.jsx` | 并排展示 2 个以上静态 variations |
| `assets/animations.jsx` | Stage + Sprite 时间轴动画 |
| `assets/narration_stage.jsx` | 带解说的长视频动画 |
| `assets/deck_index.html` | 多文件 HTML deck 聚合、概览墙、键盘翻页 |
| `assets/deck_stage.js` | 小型单文件幻灯片 |

使用方式：

```text
读取对应 assets 文件内容
  -> inline 到目标 HTML
  -> slot 进自己的设计
```

## 8. 验证与交付

所有 HTML 产出都应验证：

```bash
python scripts/verify.py path/to/design.html
```

多视口：

```bash
python scripts/verify.py design.html --viewports 1920x1080,1440x900,768x1024,375x667
```

幻灯片逐页：

```bash
python scripts/verify.py deck.html --slides 10
```

验证清单：
- HTML 能打开；
- 无 JavaScript `pageerror`；
- console 无关键错误；
- 字体、图片、emoji 正常；
- 固定尺寸内容无溢出；
- App 原型关键点击路径可用；
- deck 每页独立可读；
- 动画关键帧值得暂停观看；
- 导出视频有 audio stream。

## 9. 最小调用模板

### 模板 A：模糊需求

```text
请用 huashu-design 处理这个模糊设计需求：{需求}。
如果没有品牌或风格参考，进入设计方向顾问模式，先拿同一份 spec 做三版真实视觉截图给我选。
```

### 模板 B：品牌物料

```text
请用 huashu-design 为 {品牌/产品} 做 {物料类型}。
先 WebSearch 核实产品事实，再按核心资产协议收集 logo、产品图、UI 截图和色值，写 brand-spec.md，然后开始设计。
```

### 模板 C：App 原型

```text
请用 huashu-design 做 {App 名称} 的 iOS 原型。
默认平铺 4-6 个主界面，每个 iPhone 都可点击；使用 ios_frame.jsx；完成后用 Playwright 做 tab、详情、modal 的点击验证。
```

### 模板 D：PPT / Deck

```text
请用 huashu-design 做 {主题} 的 {页数} 页 deck。
HTML 聚合演示版是基础产物；如果页数 >=5，先做 2 页 showcase 定视觉 grammar。完成后导出 PDF；如果我要可编辑 PPTX，再按 editable-pptx 约束导出。
```

### 模板 E：动画视频

```text
请用 huashu-design 做 {主题} 的 {时长} 秒动画。
用 Stage/Sprite 写时间轴，先做关键帧验证，再导出 MP4、60fps MP4、GIF，并默认加 BGM + SFX。
```

### 模板 F：信息图

```text
请用 huashu-design 基于以下真实数据制作 {尺寸} 信息图。
不要编造数据；按标题、核心数据、细节建立层级；导出前用 Playwright 截图验证。
```

### 模板 G：设计评审

```text
请用 huashu-design 的 5 维度专家评审检查这个设计，输出评分、Keep、Fix 和 3 个 Quick Wins。
```

## 10. 对本项目的使用建议

- 做金刚石散热项目材料时，可以用 `huashu-design` 做技术路线图、信息图、PPT、汇报动效和产品级展示页。
- 涉及真实企业、设备、材料照片、实验图片时，先建资产目录和 `brand-spec.md`，不要用通用图标或假示意图替代。
- 学术或项目汇报 deck 应优先走 HTML deck + PDF，只有需要同事继续编辑时才额外导出 PPTX。
- 数据图必须用真实数据；没有数据时标 placeholder，不能编造“99%”“10x”等装饰数字。
- 设计产出应和前面的知识库工作流联动：资料入库、证据台账、图片来源记录、最终设计交付都保留可追溯路径。