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 Permalink 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 Permalink 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 Permalink Blame History