huashu-design：在 Agent 里打一句话拿回能交付的设计

5233 字 · 2026-10-30 · ~14 min read

相关标签：Frontend, UI, Design, Skills, AI, GitHub, 源码分析, ByAI

huashu-design（默认分支 master，整理时 HEAD 为 4fc7bfd，2026-10-23）

AI 参与说明（Agent：Cursor）：本文依据上述提交的 SKILL.md、README.md、SECURITY.md、LICENSE，以及 references/directions.md、references/brand-asset-protocol.md、references/design-styles.md、references/critique-guide.md、references/editable-pptx.md、assets/animations.jsx 与仓库文件树整理。风格样张数量按该提交下 assets/style-specimens/ 的 jpg 清点。作者在 README 里报告的耗时、盲选和方差没有复跑。模型 grok-4.7-high-fast，提供方 xAI，执行入口 Cursor Cloud。reasoning effort 未作为独立字段取得运行记录。中文正文按项目 humanizer-zh 编辑。

想在 Claude Code、Cursor 或 Codex 里说一句「做个观鸟记录 App 的原型」，拿回能点开的 HTML，可以用 huashu-design。它是花叔（花生，GitHub alchaincyf）维护的 Agent Skill，SKILL.md 里的版本是 3.0.0，许可证是 MIT（2026-05-14 起，个人和商用都不必另行授权）。安装命令是：

bash

npx skills add alchaincyf/huashu-design

HTML 在这里是媒介，和别人用 Figma、After Effects 或 InDesign 交稿是同一类事：交互原型、1920×1080 的演讲 deck、时间轴动画、信息图，以及一套可执行的设计评审。生产级 Web App、要做 SEO 的站点、需要后端的系统，SKILL.md 写明不走这个 skill。

先认识几个名称

英文术语	中文名称	简要解释
Three-direction gate	三方向门	新的视觉设计先交出三个方向的真实初稿，选定之后才做完
Core Asset Protocol	核心资产协议	认得出品牌靠 logo、产品图和界面截图，色值和字体只是辅助
Look ledger	外观账本	记下每次交付的底色、色板、字体和版式，下一次主动避开
design lint	设计体检	只检查裂图、字号、对比度、报错和模板装饰，不给好看打分
Tweaks	Tweaks	在页面侧边改配色、字型和密度，选择存在浏览器 localStorage
Stage / Sprite	舞台 / 片段	动画按整段时间和片段起止来排，片段内再用进度插值

Any new visual design passes the three-direction gate before execution. Specifying a style or a brand does not waive it. The agent shows real drafts and stops, including in unattended sessions. Logo, product photography, and UI screenshots outrank color values and type specs.

SKILL.md 把这道门写进所有模块共用的窄桥；英文 README 仍把同一段叫 Design Direction Advisor，并写成需求模糊时的 fallback。以 SKILL.md 和 references/directions.md 为准：只要会产出新的视觉，就先走三方向门。指定「Apple 风格」只是把三个方向收进 Apple 的语境，选择权仍在看过初稿的人手里。

和 Claude Design 的差别，README 用一句话收住：Claude Design 是浏览器里的图形产品，huashu-design 是装进任意兼容 Agent 的 skill，交付物是 HTML、MP4、GIF、可编辑 PPTX 和 PDF。图形界面那一层在这里不出现。

它交付什么

README 的能力表给出的是作者标注的典型耗时，不是完成时限。下表的交付形态以仓库里的模块和脚本为准。

你要的东西	交回来的是什么	主要依据
网页或 App 原型	可点击的 HTML；手机原型用 `assets/ios_frame.jsx` 等机身框	`references/modules/web.md`、`references/app-prototype.md`
演讲幻灯片	浏览器里放的 HTML deck，以及可编辑的 PPTX	`references/editable-pptx.md`、`scripts/html2pptx.js`
时间轴动画	本地导出的 MP4 / GIF，可加 BGM	`assets/animations.jsx`、`references/modules/motion.md`
信息图	以 HTML/CSS 排的长图或图表，再导出 PDF / PNG / SVG	`references/modules/infographic.md`
方向本身	六格缩略图加三版完整初稿，另外三张留作备选	`references/directions.md`
评审	概念先过关，再按五个执行维度写 Keep / Fix / Quick Wins	`references/critique-guide.md`
改参数	Tweaks 面板，刷新后仍保留	`references/tweaks-system.md`

动画引擎在 assets/animations.jsx：Stage 管整段时间，Sprite 管 start / end 之间的片段，片段里用 useSprite() 读 0 到 1 的进度，再用 interpolate 和 Easing 插值。文件头写明这是借鉴 Remotion 的轻量时间轴，挂在 window.Animations 上。README 写的典型耗时是 8–12 分钟；≥20 秒的片子开工前要有 导演稿.md，≥45 秒的成片渲染可以由可选的 scripts/design-gate-hook.sh 拦住，直到 direction-approved.md 存在。这个 hook 不会自动写进 Agent 的 settings.json。

PPTX 有两条路，不要在同一个项目里混用。还没写 HTML、希望 PowerPoint 里是真文本框时，按 references/editable-pptx.md 从第一行就满足约束：文字放在 <p> 或标题标签里，画布用 960pt × 540pt（对应 pptxgenjs 的 LAYOUT_WIDE），再由 scripts/html2pptx.js 按 computed style 翻译。已经做好的视觉稿走 references/pptx-from-rendered-html.md，读渲染后的坐标，不必为了导出重写结构。pptxgenjs 不能拿客户现成的 pptx 当母版继承。README 的局限也写了：这不是能拖进 Figma 改图层、或拖进 Keynote 改文字位置的文件。

评审文件比 README 表格里的「5 维度」多一道门。references/critique-guide.md（文件内版本 v1.0，日期 2026-02-13）把概念/立意放在最前面：换个客户名还成立，这一维直接 ≤5，总评封顶 6.0。后面才是哲学一致性、视觉层级、细节执行、功能性和创新性，各 0–10，输出 Keep、Fix 和最多三条 Quick Wins。场景会改侧重，例如信息图把功能和层级放在创新前面，App 把功能和细节执行放在哲学前面。概念这一维对所有场景都先算。

装上之后先看目录

npx skills add alchaincyf/huashu-design 之后，安装目录里必须同时有 references/、assets/、scripts/、demos/。README 写明：skills CLI ≤1.5.15 有过只同步 SKILL.md 的问题，1.5.19 修复；若目录里只剩主文件，先 npm i -g skills@latest 再装一次。仍不行就克隆整仓，例如：

bash

git clone https://github.com/alchaincyf/huashu-design.git ~/.claude/skills/huashu-design

Claude Code、Cursor、Codex 以及其他能读 skills 的 Agent 都用同一份目录。脚本路径相对 skill 根目录，不是用户项目目录。Windows 上把 python3 换成 python。

开工时 skill 建议先跑三件不阻塞的自检：learn.py 带出这个人以前说过的品味原话，design_lint.py ledger 看最近交付长什么样，capabilities.py 看本机有没有生图、兄弟 skill、Node、ffmpeg 和 Playwright。没有记录就继续做。没装 Python 版 Playwright 时，design lint 会跳过并给出安装命令。

从一句话到选定方向

flowchart TD
  A["一句需求"] --> B["核实产品是否已发布"]
  B --> C{"点名了品牌或产品?"}
  C -->|是| D["核心资产协议<br/>brand-spec.md"]
  C -->|否| E["从已有上下文取素材"]
  D --> F["六个候选"]
  E --> F
  F --> G["六格缩略图"]
  G --> H["三版完整初稿"]
  H --> I["design lint"]
  I --> J["停下来等选择"]
  J --> K["direction-approved.md"]
  K --> L["做完并写入外观账本"]

图里每一步都对应仓库里的一个文件或脚本。用户说「继续」只表示进入下一步，不表示跳过这一步的 gate。跳过必须当次说清楚，并把原话或理由写进对应 gate 文件。

三方向门

references/directions.md 要求选择发生在看见视觉之后。提问只有一轮，最多 3 个问题，logo、色板、VI 和参考站一次问全。用户不回答，就标上 assumption 继续。重述需求的最后一句是「我做 3 个方向给你看」。没看到稿就让人选风格，文件里写成无效选择。

三版共用一份 spec，spec 只写要说什么，不写长什么样。输出尺寸必须相同，否则无法横比。内容必需的图和具名产品的 logo 先取齐。

候选是六个，不是三个。两位气质不同的设计师各做一版，借的是思维，不临摹某件作品的皮。两件同一媒介里核实过的作品各做一版：做 App 找 App，做 deck 找出版物，先用 scripts/ref_board.py 截下来再拆网格和字号。秒数轮盘再从风格库抽两号。六个都画成约 480×300 的缩略图，放在 design-demos/thumbs.html。然后按「单看就够好、彼此不一样、不撞最近的项目、三张里最多一张用力过头」挑三张做成完整 HTML。没选上的三张作为备选一起展示。摆出截图和方向卡就结束这一回合，用户的原话写入 direction-approved.md。

秒数轮盘用当前秒数 S（date +%S）。产出分区取 S % 分区风格数 + 1，中文与东亚分区再取 S % 12 + 1。抽到和外观账本最近 3 个交付同类的，顺延下一号。还原度低于 70% 的风格必须标明哪一部分降级，不能假装做出了原版质感。

豁免只有三种，而且都要落档：这次会话明说跳过；同一项目里方向已经选定，后面只是迭代；纯机械操作，例如已有 HTML 转 PDF/PPTX、截图、改文字。弱 runtime 可以把三版从并行改成串行，甚至改成 1 个完整主版加 2 个轻量变体，但不能取消三张方向卡，也不能取消真实资产和可读性底线。

作者在 directions.md 里用三轮内部盲选解释现在为什么「加选项，不加禁令」。第一轮三版只换皮。第二轮强迫每版先定一个大隐喻，页面被做成档案柜或地铁图，4 题输 3 题。第三轮为了躲开模型的默认外观，限制暖纸衬线和深底单点缀，结果三版一起变得规整、无聊，又输给没有这些禁令的旧做法。所以外观家族本身可以留：三版挤在同一个家族，或和最近的项目撞了，才换。

directions.md 里的酱油厂例子把差异放在骨架上。原研哉那张是一屏一张真照片、一句话，胆量花在盐霜特写，form 写成「酱油要晒 180 天，节奏就放慢」。现实参照那张是竖排标题加右三栏，只用两种颜色，form 写成老字号的「方子」。轮盘抽到媒体级粗野主义时，首屏用超大的「酱」切进去，form 写成一个字讲完一家酱园。

可读性不随风格放宽：网页正文至少 14px、标签至少 12px；deck 正文至少 24px、标签至少 16px；给手机看的 1080 宽长图，正文至少 36px、标签至少 28px（按画布像素）。正文对比度至少 4.5:1。

核心资产协议

references/brand-asset-protocol.md 把旧称「品牌资产协议」收成核心资产协议。两类任务都触发：为某个品牌做物料；画面里出现任何认得出的产品，包括对比、榜单和评测。出现几个产品就取几个官方 logo。普通主题词（咖啡、历史、健身）不是品牌，不要去找「咖啡的 logo」。

识别度的顺序是 logo、产品图或 UI 截图，然后才是色值、字体和气质词。只抽出 hex、用 CSS 剪影代替产品、找不到素材还静默硬做，文件里都写成违反协议。logo 完全找不到就停下问人。

五步是问清单、搜官方渠道、下载、验证、写成 brand-spec.md。数字产品的 logo，文件建议先走 svgl 或 simpleicons，再退到品牌页、页面里的 inline SVG，最后用 Google favicon。下载后要用 file 确认不是空壳 HTML。其他素材有一条「5-10-2-8」：交叉搜 5 轮，至少凑 10 个候选，留下 2 个，每个自评至少 8/10；不够就用标明「待补」的灰块，不用 7 分图充数。logo 不适用这条少选规则，有就必须用。

色值从已下载的 SVG、HTML、CSS 里提取，过滤黑白灰，不靠记忆。文件里的反例包括：把 Kimi 记成橙色（实际写的是 #1783FF），把截图里演示用的喜茶红当成产品自己的颜色，以及大疆 Pocket 4 只抽了色、没放 logo 和产品图，做出一条换任何品牌都成立的黑底科技动画。对比页同样不豁免：2026-06-06 的五家 Coding Agent deck 只抽了品牌色，五个 logo 一个没取，协议随后把触发条件扩到「画面里点名的真实产品」。

README 还记录了作者自己的对照：v1 和 v2 各跑 6 个 agent，v2 的稳定性方差比 v1 低 5 倍。这是仓库内的自述，本文没有复跑。

84 种风格库

references/design-styles.md 写明 84 种，并按分区给了样张。该提交的 assets/style-specimens/ 里，分区 jpg 是 web 20、ppt 20、info 20、app 12、east 12，另有五张 sheet-*.jpg 总览。中文与东亚 12 种跨媒介，中文内容可以优先翻。assets/showcases/INDEX.md 是另一套更早的预制样例，8 个场景 × 3 种风格共 24 个，不要把它当成 3.0 的 84 种库。

库的定位写在文件开头：用户已经给了内容、品牌或参考，设计从那里长出来，不要为了用库而套库。秒数轮盘才从这里抽。每条风格标了大胆、中性或安静，以及纯 HTML/CSS、无生图时的还原度。条目里的 hex 和字体是锚点。用之前走色彩推导三步：从品牌资产、内容真图或文化语境采样；用 oklch 收到 2–3 个有彩色加一组中性色；写一句话说明这个色为什么属于这份内容。写不出这句话，就是在抄配方。字体配对与「已被用烂名单」以 references/typography.md 为准，和条目冲突时听前者。

暖色出版物（奶油纸底加赤陶橙）在库里还原度标到 97%，同时被点名：这也是模型不加约束时最容易滑进去的样子。SKILL.md 描述的默认审美是暖奶油底、高反差衬线标题、陶土色点缀、全大写小标签和 01/02/03 编号。可以用，但三个方向不能都挤在这里，外观账本里最近用过就换。

另外一批顺手的模板装饰要删：每个标题上方一行全大写小标签、「A · B · C」中点连接、按钮尾巴的箭头、标题里只给一个词换色，以及内容并不是序列时的 01/02/03。上一代常见的紫渐变、emoji 图标、左侧彩条圆角卡片、用 SVG 画人脸，同样不要。没有数据、评价或 logo 墙，就留诚实占位，不编。

体检、账本，以及尽早给看

scripts/design_lint.py 的文件头写得很窄：它不判断好不好看。红灯是裂图、字小到读不了、对比度不够、控制台报错，交付前要修。黄灯是上面那些模板装饰，删掉结构本身，换个符号躲过检测不算改。外观家族只是提示。compare 看三版是不是换皮；品牌把颜色和字体锁死时加 --brand，只比骨架。ledger add 把底色、色板、字体、粗略版式、项目名和绝对路径记下来，ledger check 用来看新方向是否撞上最近的项目。

品味原话走另一条线。scripts/learn.py add --kind preference 逐字记下「太素了」「A 的结构加 C 的颜色」这类表态，并写明适用范围。记的时候要告诉用户一句：这句进了本机品味档案，不要就可以不记。审查打分和用户的选择冲突时，以用户为准。

README 把 Junior Designer 写成默认习惯：开工前一次把问题问完；HTML 里先写 assumptions、placeholders 和 reasoning；灰色方块也可以先给看；填内容、做变体、开 Tweaks 再各给看一次。理解错了早改。这是工作节奏。硬停点仍然是三方向门和 gate 文件，不是「先给看」这句话本身。

SKILL.md 收工还有三件事：对最终文件跑 design_lint.py check，用 ledger add 记外观，用 learn.py harvest 收回这次值得留的教训。三方向初稿放在项目下的 design-demos/，不要散到 ~/Downloads。单文件交付时把图片和 logo 以 base64 嵌进去。交付前用浏览器或 Playwright 看过。

可以怎么开口

README 给了四句可以直接用的 prompt：

text

做一份 AI 心理学的演讲 PPT，推荐 3 个风格方向让我选
做个 AI 番茄钟 iOS 原型，4 个核心屏幕要真能点击
把这段逻辑做成 60 秒动画，导出 MP4 和 GIF
帮我对这个设计做一个 5 维度评审

点了名的产品，同一句话里加上「logo 和产品图按核心资产协议取，色值从文件里抽」。已经有设计系统或仓库时，指给 Agent 看，比从零描述气质有用。SKILL.md 把凭空做 hi-fi 放在最后。

3.0 案例是 README 自己的演示，不是本文复跑的结果。作者写：前五个从发布时新跑的 6 道题里挑选，每道只给一句话，方向由 agent 选。富岳三十六景线上展的三版分别是暗场展厅、三角窗和民国书衣；体检发现两版首屏都用了《神奈川冲浪里》，暗场那版改成《山下白雨》。观鸟 App「鸣迹」先把 2025 年苹果设计奖作品 CapWords 截成参考板，再把 Wikimedia 照片里的鸟撕成贴纸。家常菜谱「今晚吃啥」抽到吕敬人的书籍设计，外观账本又看到最近 6 个交付里 5 个是无衬线标题，于是这一版用了宋体。千里江山图讲座和黑洞科普是两条 deck：前者用长卷缩略条标出当前页在 11.9 米里的位置，后者按 Jonathan Corum 的幻灯片来，标注直接写在图上，并先做事实核查。截图在 v3.0.0 release。

2.0 时期仍可打开的成品包括鹦鹉进化史和「聊聊 skill」演讲 deck。README 的 Demo 画廊动图多标了 2.0 流程，例如方向顾问当时是三套逻辑各出一版，3.0 才改成六张缩略图再挑三版。

数据留在本机

SECURITY.md 的范围是：设计、渲染、导出 MP4 / PDF / PPTX 的主链路在本机完成，不带作者的 API key，也没有 telemetry。会出网的情况都写在同一份清单里。

去哪里	什么时候	送出什么
品牌官网、simpleicons、Google favicon、svgl	做品牌稿、下载公开 logo	普通 GET
`commons.wikimedia.org`	`scripts/fetch_images.py` 找图	搜索词，并打印许可信息
参考作品的 URL	三方向门里跑 `ref_board.py`	无头浏览器打开该页并截图；脚本本身不过滤地址
`fonts.googleapis.com` 等 CDN	你在浏览器里打开生成的 HTML 或样张	字体和库
`ark.cn-beijing.volces.com`	可选，`scripts/cloud/ai-review-video.py`	你自己渲染的视频片段，用你的 `ARK_API_KEY`
`openspeech.bytedance.com`	可选，豆包 TTS	你要合成的旁白文本，用你的 key

云脚本在 scripts/cloud/，不传 --yes 或 HUASHU_CLOUD_OK=1 就不会发请求。版本检查只对 skill 目录执行 git ls-remote --tags，把日期写进该目录的 .last-update-check，不下载、不自动升级。写成 off 就不再查。

本机记忆只有两份，可用 HUASHU_DESIGN_HOME 改位置，删掉目录即忘记：

~/.huashu-design/experience.md：品味原话和教训
~/.huashu-design/ledger.jsonl：外观指纹、项目名、项目绝对路径

capabilities.py 只检查 OPENAI_API_KEY / GEMINI_API_KEY 是否存在，不读取、不打印值。它会列出常见 skills 目录里的文件夹名，用来判断兄弟 skill 是否装了。

边界

适合用它把一次发布、一堂课、一个原型或一张信息图在对话里做完。不适合用它替代生产前端仓库：没有后端、没有 SEO 站点工程、也没有 Figma 图层往返。

README 把自己的上限写成：复杂到 Framer Motion 那一档的动画，以及 3D、物理模拟、粒子，超出 skill 边界；完全空白、又没有任何参考的品牌，从零做 hi-fi 会掉到作者所说的 60–65 分。空白品牌优先补资产或参考，而不是多抽几种风格。

使用前可以先看花叔录的上手教程。3.0 发布片在 launch-3.0.mp4（README 标注 1080p、含配乐、约 24MB），2.0 的带音效 HTML 在 huashu-design-hero。