admin/BZJZ_Material

Fork 0

Files

admin 33a9a132ce docs: add huashu design agent guide

2026-06-11 03:39:35 +08:00

19 KiB

Raw Blame History

设计 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 安装

npx skills add alchaincyf/huashu-design

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

本项目本地资料路径：

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

2.2 自然语言调用

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

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

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

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

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

3. 核心规则

3.1 事实验证先于假设

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

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

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

适用场景：

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

3.2 核心资产协议

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

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

5 步流程：

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

硬底线：

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

3.3 Junior Designer 工作流

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

一次性问清问题
  -> 写 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、品牌规范；
用户明确要求“推荐风格”“给几个方向”；
用户不知道自己想要什么风格。

默认流程：

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 风格库抽一个	打破模型总选安全极简的惯性
现实参照	找一个真实优秀案例或获奖案例，拆解后迁移	用现实高标准锚定
最佳设计师	假设无限预算，选择最适合该任务的设计师或工作室哲学	做更贴合内容的定制方向

风格库位置：

references/design-styles.md

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

5. 不同需求的完成方式

5.1 产品发布动画 / Launch Film

适用：

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

路线：

事实验证
  -> 核心资产协议
  -> 写 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。

调用口令：

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

关键 reference：

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

常用脚本：

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 确定性渲染：

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

注意：

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

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

适用：

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

路线：

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

调用口令：

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

关键 reference：

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。

默认交付：

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

默认架构：

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

iOS 原型必须使用：

assets/ios_frame.jsx

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

调用口令：

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

核心屏幕示例：

今日总览；
跑步中实时数据；
路线地图；
历史记录；
月度统计；
设置。

验证：

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

交互测试最少覆盖：

进入详情；
tab 切换；
关键按钮或弹层；
页面无 pageerror。

5.4 Web / SaaS 高保真原型

适用：

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

路线：

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

调用口令：

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

变体展示组件：

assets/design_canvas.jsx

Tweaks 适用：

颜色主题；
字号；
信息密度；
layout；
dark mode；
feature flag。

关键 reference：

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；
培训课件；
汇报材料；
研究或商业报告。

硬规则：

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

默认架构：

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

如果 deck ≥ 5 页：

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

调用口令：

请用 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。

常用脚本：

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：

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。

路线：

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

调用口令：

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

推荐风格参考：

Fathom；
Müller-Brockmann；
Stamen；
Takram；
Tufte 信息设计。

关键 reference：

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

5.7 多版本探索 / 设计变体

适用：

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

路线：

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

调用口令：

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

关键 reference：

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

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

5.8 设计评审

适用：

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

5 个维度：

哲学一致性；
视觉层级；
细节执行；
功能性；
创新性。

输出结构：

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

调用口令：

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

关键 reference：

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`	小型单文件幻灯片

使用方式：

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

8. 验证与交付

所有 HTML 产出都应验证：

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

多视口：

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

幻灯片逐页：

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

验证清单：

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

9. 最小调用模板

模板 A：模糊需求

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

模板 B：品牌物料

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

模板 C：App 原型

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

模板 D：PPT / Deck

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

模板 E：动画视频

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

模板 F：信息图

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

模板 G：设计评审

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

10. 对本项目的使用建议

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

19 KiB Raw Blame History Unescape Escape

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

1. 总体定位

2. 安装与调用入口

2.1 安装

2.2 自然语言调用

3. 核心规则

3.1 事实验证先于假设

3.2 核心资产协议

3.3 Junior Designer 工作流

3.4 反 AI Slop

4. 设计方向顾问模式

5. 不同需求的完成方式

5.1 产品发布动画 / Launch Film

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

5.3 可点击 App 原型

5.4 Web / SaaS 高保真原型

5.5 HTML 幻灯片 / 可编辑 PPT

5.6 信息图 / 数据可视化

5.7 多版本探索 / 设计变体

5.8 设计评审

6. 常用脚本索引

7. Starter Components 索引

8. 验证与交付

9. 最小调用模板

模板 A：模糊需求

模板 B：品牌物料

模板 C：App 原型

模板 D：PPT / Deck

模板 E：动画视频

模板 F：信息图

模板 G：设计评审

10. 对本项目的使用建议

19 KiB

Raw Blame History