本周 GitHub 第一！diagram-design：让 AI 画出设计师都挑不出毛病的图表

1. 为什么 AI 画的图总像“半成品”如果你用 Claude Code 写过技术文档大概率经历过这个场景让 AI 画一张微服务架构图它给你吐出一堆圆角方框加箭头配色是默认的蓝灰字体是系统 sans节点间距全靠感觉。图能看但放到文章里就是和正文风格打架最后要么自己开 Figma 重画半小时要么干脆删掉不画。diagram-design 这个项目就是冲着这个痛点来的。它是给 Claude Code、Codex、Pi 这类 AI 编码助手用的图表设计技能包本周冲到 GitHub 热榜第一。核心能力一句话你让 AI 画架构图、流程图、时序图它输出的是编辑级排版质量的 HTML SVG自带浅色、深色、全编辑风三套皮肤浏览器双击即开没有构建步骤、没有 JS 依赖、没有外部图片。它适合谁三类人最值得装一是经常写技术博客或内部文档的工程师图的质量直接影响阅读体验二是做方案汇报要出架构图、数据流图的人投影场景下字号和对比度有专门优化三是手里已经有一堆 draw.io 或 Mermaid 旧图、想批量升级视觉风格的人它支持导入重绘并输出保真台账。我试过在 Claude Code 里装完直接让它画一张网关架构图从自然语言描述到 HTML 文件落盘不到两分钟打开浏览器那一刻确实和之前 Mermaid 的输出不在一个量级。下面把完整链路拆开讲包括 settings.json 和 config.toml 骨架、TaoToken 统一 Key 的配置方式以及三步验证动作确保你能复现同样的效果。2. 前置准备TaoToken 统一 Key 与 Claude Code 环境diagram-design 本身是纯本地的 skill 包不依赖网络请求就能生成图表。但你在 Claude Code 里调用它时模型推理这一层需要走 API。如果你同时用多个模型或工具每个都单独配 Key 会很乱TaoToken 的作用就是提供一个统一的 API 入口把模型调用收敛到一处管理。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要先去控制台创建一个 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完在 API Keys 页面复制出来地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后Claude Code 的配置分两层一层是 Claude Code 自身的 settings.json控制模型走哪个端点另一层是项目级的 config.toml控制 diagram-design 这个 skill 的行为参数。两者不要混在一起写。先看 settings.json 的骨架。这个文件通常放在~/.claude/settings.json或项目根目录的.claude/settings.json取决于你想全局生效还是项目级生效{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey }, permissions: { allow: [ Bash(playwright:*), Bash(python:*), Read, Write ] } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_API_KEY填你刚才复制的 Key。permissions 里放行 playwright 和 python 是因为后面导出 PNG 要用到 Playwright 光栅化不放行的话 Claude Code 执行导出命令时会卡在权限确认。再看 config.toml 骨架。这个文件放在项目根目录diagram-design 读取它来决定默认输出风格和尺寸[diagram] default_style minimal-light default_format html default_size doc-wide default_detail balanced [diagram.brand] profile default accent #E07A5F paper #FAFAF8 ink #1A1A1A [export] png_scale 2 svg_inject_fonts truedefault_style三个可选值minimal-light、minimal-dark、full-editorial。default_size支持doc-inline、doc-wide、slide-16x9、slide-4x3、social-og、print-a4。default_detail三档faithful最多 24 节点、balanced最多 12 节点、simplified最多 7 节点。brand 段可以先留默认后面品牌匹配那步会自动改写。如果你用的是 Codex 而不是 Claude Code配置文件换成~/.codex/config.toml模型端点字段名不同但 TaoToken 的 API 地址和 Key 是同一套不用重复申请。3. 安装 diagram-design 并跑通第一张图安装命令按你用的 Agent 选一条。Claude Code 里执行/plugin marketplace add cathrynlavery/diagram-design /plugin install diagram-designdiagram-design装完后 Claude Code 对第三方市场默认关闭自动更新需要手动开一次。运行/plugin进 Marketplaces选 diagram-designEnable auto-update然后按提示运行/reload-plugins。这一步别跳过否则后续 skill 更新不会自动拉取。Codex 用户执行codex plugin marketplace add cathrynlavery/diagram-design codex plugin add diagram-designdiagram-design想立即更新运行codex plugin marketplace upgrade diagram-design。Pi 用户执行pi install https://github.com/cathrynlavery/diagram-design然后在会话里运行/reload用/skill:diagram-design显式调用。装好后直接用自然语言让 AI 画图。比如画一个微服务网关的架构图frontend、backend、database、Redis cacheAI 会自动选图类型、构建 HTML、保存文件。你也可以从模板直接开始省去等待生成的时间cp skills/diagram-design/assets/template.html my-diagram.html cp skills/diagram-design/assets/template-full.html my-diagram.html cp skills/diagram-design/assets/template-motion.html my-diagram.html第一个是极简浅色第二个是编辑风带摘要卡第三个是可选无障碍动效。模板文件里已经预置了设计系统的 token你只需要改节点内容。这里有个容易踩的坑模板里的坐标和宽度必须能被 4 整除这是 diagram-design 设计系统的硬约束。如果你手动改坐标写成13px或27px渲染出来会有半像素模糊CI 的几何检查也会失败。改的时候统一用 4 的倍数比如12、16、24、32。4. 品牌匹配60 秒让图表变成你的风格这是整个 skill 里最实用的功能。你不需要手动调色让 skill 读你的网站自动提取品牌色和字体映射到图表的语义角色上。操作方式是在 Claude Code 里说onboard diagram-design to https://yoursite.comAgent 会抓取首页提取主色调和字体栈然后映射到五个语义角色paper 是背景、ink 是文字、muted 是次要信息、accent 是强调色、link 是链接色。映射完会展示一份拟修改的 diff你确认后说yes, apply it它写入references/style-guide.md。之后每张新图都用你的品牌色。映射规则是这样的body背景色变成 paper主文字颜色变成 ink次要说明文字变成 muted卡片或容器变成 paper-2最常用的品牌色CTA、链接、标题变成 accenth1字体变成 title 字体body字体变成 node-name 字体code和pre字体变成 sublabel 字体。它还会自动做 WCAG AA 对比度检查。如果你网站的颜色在图表字号9 到 12px下对比度不达标它会提议一个调整值并解释原因。这个细节很关键因为很多品牌色在正文大字号下没问题缩到图表节点里就糊了。多客户场景下品牌可以存成命名 profile。每个客户项目加一个.diagram-design标记文件里面写profile: slug不同项目用不同品牌互不覆盖。比如你同时给 A 公司和 B 公司做方案切项目目录就自动切品牌不用手动改配置。5. 从 draw.io / Mermaid 重绘与导出手里已经有旧图的话不用重画直接导入重绘/diagram-design:import-drawio platform.drawio /diagram-design:import-drawio platform.drawio --sizeslide-16x9 --detailsimplified --audienceexecutive /diagram-design:import-mermaid architecture.mmd --sizeslide-16x9四个调节旋钮控制输出Format 选 html、svg、png 或 htmlpngSize 选 doc-inline、doc-wide、slide-16x9、slide-4x3、social-og、print-a4 等对应不同的 viewBox 和字号梯度投影场景用 16px 节点名而不是 12pxDetail 选 faithful、balanced 或 simplified通过固定降级梯保留多少源信息Audience 选 engineer、mixed 或 executive改变措辞而非数量比如Auth Service / JWT · RS256 · :8443会变成Auth Service / token check再变成Sign-in。每次导入结束会输出保真台账明确告诉你合并了什么、折叠了什么、丢弃了什么。比如Detail: balanced · 12 source nodes → 8 drawn Collapsed: Token valid? decision → edge label on Gateway → Auth Dropped: 1 sticky note (legacy path, to be retired) — unconnected in source Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)支持读取.drawio、.drawio.xml、.drawio.png内嵌图、.drawio.svg包括编辑器里看着像 base64 乱码的压缩内容。Mermaid 支持.mmd、.mermaid和 Markdown 里的 fenced 代码块。导出 PNG 或 SVG 的命令/export-diagram path/to/diagram.html /export-diagram path/to/diagram.html --svg-only /export-diagram path/to/diagram.html --png-only --scale3Claude Code 里用/diagram-design:export-diagram path/to/diagram.html。SVG 导出会提取svg节点并注入 Google Fonts可以独立在浏览器、Figma、Illustrator 里打开。PNG 通过 Playwright 光栅化默认 2 倍一次性安装依赖pip install playwright playwright install chromium6. 三步验证生成、渲染、对比设计稿装完配完怎么确认效果真的到位按这三步走。第一步生成验证。在 Claude Code 里发一条明确的画图指令比如“画一个带 401 token 刷新的 bearer 调用时序图”观察 Agent 是否自动加载了type-sequence.md而不是把所有类型文件都读一遍。如果它加载了多余文件说明 skill 的按需加载没生效检查/reload-plugins是否执行过。第二步渲染验证。用浏览器打开生成的 HTML 文件检查三件事节点间距是否均匀、强调色是否只出现在 1 到 2 个焦点上、等宽字体是否只用在端口和 URL 这类技术内容上。如果发现标签遮挡了后续节点说明几何检查没过手动调坐标时确保能被 4 整除。第三步对比设计稿。如果你做了品牌匹配把生成的图和你的网站截图并排看重点看 accent 色是否一致、标题字体是否匹配、背景色是否协调。对比度不达标的话skill 会给出调整建议按建议改style-guide.md里的 token 值。三步都过了说明链路跑通。之后每张图都可以复用这套配置不用重复调。7. 常见报错与排查报错一/plugin install后找不到 diagram-design 命令。原因是 Claude Code 对第三方市场默认关闭自动更新插件元数据没拉全。解决方式是运行/plugin进 Marketplaces 手动 Enable auto-update然后/reload-plugins。如果还不行检查 settings.json 里的ANTHROPIC_BASE_URL是否指向https://taotoken.net/api端点不对会导致插件市场请求失败。报错二导出 PNG 时报playwright not found。这是 Playwright 没装或 Chromium 没下载。执行pip install playwright playwright install chromium注意两条命令都要跑只装 pip 包不下载浏览器内核一样会报错。如果公司网络限制下载可以先--svg-only导出 SVG用其他工具转 PNG。报错三生成的图坐标模糊、有半像素。这是坐标没被 4 整除。diagram-design 的设计系统要求所有坐标、宽度、间距能被 4 整除手动改模板时容易忽略。检查 HTML 里所有x、y、width、height的值统一改成 4 的倍数。报错四品牌匹配后颜色对比度不达标。网站品牌色在正文大字号下没问题但图表字号只有 9 到 12px对比度要求更高。skill 会提议调整值按建议改references/style-guide.md里的 accent 或 ink 值。如果不想改品牌色可以把该节点的字号调大一级或者把 accent 只用在非文字元素上。报错五导入 draw.io 后节点丢失。看保真台账里的 Dropped 行通常是源文件里有未连接的 sticky note 或游离节点skill 默认丢弃。如果确实需要保留把--detail调到faithful最多支持 24 节点或者手动在源文件里把游离节点连上主流程。8. 资源入口与下一步diagram-design 的完整能力远不止上面这些27 种图表类型每种都有三个静态变体覆盖架构、流程、状态、层级、对比、时间、数据、飞轮、数据平台等场景。它的质量门禁体系也是生产级的CI 在 Linux、Windows、macOS 上跨平台运行几何标签放置检查、语义路由验证、文档同步检查都有独立脚本。如果你主要做长期编码和 Agent 开发建议走 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 把模型调用和图表生成收敛到一套配置里。如果只是想先验证模型输出效果可以去模型对话页面试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的端点和参数说明。Claude Code 相关的配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后留一个实用技巧diagram-design 的 README 里有一句判断标准画图前先问自己读者从这张图学到的比从一段写得好的话多吗如果不多就别画。这个原则比任何工具都重要工具只是让该画的图变得更好看。