1. 为什么我最后只留下 fireworks-tech-graph 这一个画图 Skill

Claude Code 画架构图这件事，我前后折腾过不少方案。最早是让它直接吐 Mermaid，结果复杂一点的微服务拓扑就挤成一团；后来换成让它写 HTML+SVG，可控性上来了，但每次都要重新调色、调间距、调字体，画一张图的时间够我改三版需求。直到用上 fireworks-tech-graph 这个 Skill，我才算把「描述系统 → 拿到能直接贴进 PPT 的高清图」这条链路跑顺。

fireworks-tech-graph 是什么？一句话：它是挂在 Claude Code 里的架构图生成 Skill，把「画什么图」和「长什么样」拆成两个维度让你选。画什么图有 14 种，覆盖 UML 类图、时序图、状态机，以及 AI 领域专属的 RAG Pipeline、Agentic RAG、Multi-Agent、ToolCallFlow、记忆架构、特性对比矩阵；长什么样有 7 种风格，Flat Icon、Dark Terminal、Blueprint、Notion Clean、Glassmorphism、Claude Official、OpenAI Official。输出是 SVG（可继续编辑）加 1920px 高清 PNG，Retina 屏下不虚，直接丢进文档或 PPT 都不掉价。

它适合谁？三类人最划算。第一类是写技术方案、做架构评审的工程师，需要快速把脑子里的分层画出来；第二类是写博客、做分享的技术作者，图要好看但不能花太多时间；第三类是做 AI 应用的人，RAG、Agent、向量库这些结构用通用 UML 工具画出来总差点意思，而这个 Skill 内置了 AI 语义——LLM 画成双边框矩形加闪电标记，Agent 画成六边形，Vector Store 画成同心圆柱，Graph DB 画成三圆环，你描述模式它就懂。

这篇不堆概念，直接给你可复制的安装命令、配置片段、触发指令和排障清单。我试过从零到出图大概十分钟，其中八分钟在等依赖装完。下面按「先装好 → 再配好 → 再画对 → 再排错」的顺序走，每一步都能单独验证。

2. 装 fireworks-tech-graph 前，先把 Claude Code 和 TaoToken 这条链路接稳

很多人卡在第一步不是 Skill 装不上，而是 Claude Code 本身没连上模型，或者连上了但 Key 配错，导致后面所有指令都石沉大海。所以先把底座搭好，再装 Skill。

TaoToken 在这里的角色是给 Claude Code 提供模型接入的入口。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 这个地址后面不加任何参数。你需要先在控制台建一个 API Key，控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。建好之后复制那串 sk- 开头的字符串，后面配置要用。

Claude Code 的接入配置有两种常见写法，取决于你用的是环境变量还是配置文件。环境变量方式最直接，在 shell 的 rc 文件里加：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的Key" export ANTHROPIC_MODEL="claude-sonnet-4-5-20250929"

如果你用的是 Claude Code 的 settings 文件，路径通常在~/.claude/settings.json，内容长这样：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929" } }

这里有个坑要提前说：Base URL 一定写https://taotoken.net/api，不要自作聪明加/v1或者结尾斜杠，加了大概率 404。Model ID 要写全，别只写claude-sonnet，有些客户端会匹配不上。配完之后重启终端，跑一句claude --version确认命令在，再进 Claude Code 发一句「你好」看有没有正常回复。这一步通了，再往下装 Skill。

装 fireworks-tech-graph 有三种方式，按省心程度排：

方式一是命令行一键装，前提是本机有 Node.js：

npx skills add yizhiyanhua-ai/fireworks-tech-graph

方式二是在 Claude Code 对话框里用自然语言让它装，直接发：

帮我安装 fireworks-tech-graph 这个 skill，GitHub 地址是：https://github.com/yizhiyanhua-ai/fireworks-tech-graph

方式三是手动克隆，适合想自己管文件或者前两种网络受限的情况：

git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph

装完还有一步不能漏：这个 Skill 导出高清 PNG 依赖rsvg-convert，也就是 librsvg 这个工具。macOS 用brew install librsvg，Ubuntu/Debian 用sudo apt install librsvg2-bin。不装的话 SVG 能出，但 PNG 那步会报错。装完重启一次 Claude Code，让它重新加载 Skill 列表。

3. 可复制配置：把风格、尺寸、输出路径写进 settings 和触发指令

Skill 装好只是有了能力，真正决定出图质量的是你怎么下指令。fireworks-tech-graph 的触发逻辑是「风格 + 图表类型 + 系统描述 + 输出参数」四件套，缺一个它就会用默认值，默认值不一定是你想要的。

先说配置层面。如果你希望每次调用都固定某些参数，可以在项目根目录建一个.claude/skills/fireworks-tech-graph/config.toml，把常用默认值写进去：

[defaults] style = "dark-terminal" width = 1920 height = 1080 format = ["svg", "png"] output_dir = "~/Desktop/arch-diagrams" font = "JetBrains Mono" background = "slate-950" grid = true

这个 TOML 不是必须的，但写了之后你每次只要说「画一个 RAG 架构图」就会自动套用 dark-terminal 风格和 1920 尺寸，省得反复交代。注意 output_dir 用绝对路径或者~开头的路径，相对路径在不同工作目录下会飘。

然后是触发指令的写法。最基础的调用长这样：

用 fireworks-tech-graph 帮我画一个 RAG 系统的架构图，使用 dark terminal 风格，输出到 ~/Desktop/

更可控的写法是把风格、图表类型、组件、连线规则、输出格式全写清楚。比如画一个带向量库和重排序的 RAG Pipeline：

用 fireworks-tech-graph 画 RAG Pipeline 架构图。 风格：glassmorphism，1920px。 组件： - 用户查询入口 - Embedding 模型（双边框矩形 + 闪电标记） - Vector Store（同心圆柱） - Retriever - Reranker - LLM 生成节点 - 记忆模块（Memory） 连线： - 查询到 Embedding 用实线 - Embedding 到 Vector Store 用虚线 - Retriever 到 Reranker 用实线带箭头 输出：SVG + 1920px PNG，保存到 ~/Desktop/rag-arch/

这里的关键是「AI 语义」那部分。你写「Vector Store」它会自动画成同心圆柱，写「Agent」自动六边形，写「LLM」自动双边框加闪电。你不需要告诉它用什么图形，只要用对术语。这也是它比通用画图工具强的地方——它认识 AI 领域的词汇。

如果你要画的是多智能体系统，触发指令可以这样：

用 fireworks-tech-graph 画 Multi-Agent 架构图，Claude Official 风格。 包含：Orchestrator、三个 Worker Agent、Tool 调用层、共享 Memory、外部 API。 连线：Orchestrator 到每个 Agent 用实线，Agent 之间用虚线表示消息传递，Agent 到 Tool 用带箭头实线。 输出 SVG 和 PNG，1920x1080。

风格选择上给个参考：给领导看用 Claude Official 或 Notion Clean，干净不刺眼；技术分享用 Dark Terminal 或 Blueprint，有工程师味道；产品文档用 Glassmorphism，毛玻璃质感确实抓眼球；要打印出来贴墙用 Flat Icon，对比度高。尺寸默认 1920x1080，如果要放进竖版文档可以改成 1080x1920，但布局会重排，建议先出横版再裁。

4. 验证请求：从一段代码结构到成品图的完整跑通流程

配置写完不验证等于没配。这一节给你一条从零到出图的完整链路，每一步都有可观察的结果，哪一步断了立刻能定位。

第一步，确认 Skill 被加载。在 Claude Code 里发：

列出当前可用的 skills

正常情况你会看到 fireworks-tech-graph 出现在列表里。如果没看到，说明安装路径不对或者没重启，回到第 2 节检查~/.claude/skills/下有没有对应目录。

第二步，确认模型链路通。发一句：

用一句话说明你能做什么

如果回复正常，说明 TaoToken 的 Base URL 和 Key 都生效了。如果这里就报 401，直接跳到第 5 节排障。

第三步，给一个真实的代码结构让它画。假设你有个简单的三层应用，直接把结构贴进去：

用 fireworks-tech-graph 画这个系统的架构图，dark terminal 风格： - 前端：React SPA，部署在 CDN - 网关：Nginx 反向代理 - 后端：Node.js API 服务，三个实例 - 数据：PostgreSQL 主从 + Redis 缓存 - 认证：JWT 输出 SVG 和 1920px PNG 到 ~/Desktop/demo-arch/

第四步，观察它的执行过程。正常的话它会先解析你的描述，然后生成 SVG 源码，再调用 rsvg-convert 转 PNG。你会在终端看到类似「Generating SVG...」「Converting to PNG...」的日志。如果卡在转换那步，八成是 librsvg 没装。

第五步，检查产物。去~/Desktop/demo-arch/看有没有两个文件：一个.svg一个.png。SVG 用浏览器打开应该能正常渲染，PNG 用图片查看器打开应该是 1920 宽、Retina 下不糊。如果 SVG 有但 PNG 没有，就是转换依赖的问题；如果两个都没有，就是 Skill 没触发或者指令没被识别。

第六步，验证可编辑性。用 VS Code 或任何文本编辑器打开那个 SVG，你应该能看到结构清晰的<rect>、<path>、<text>标签。这意味着你可以手动改颜色、改文字、改位置，不用重新生成。这是 SVG 相对 PNG 的核心优势，也是我推荐默认输出 SVG 的原因。

跑通这一遍之后，你可以把第三步的指令换成自己真实的系统结构。复杂系统建议拆成多张图，比如「全局总览 + 核心业务链路 + 数据流细节」三张，每张单独生成。一次性让它在 1920 画布上塞二十个服务，结果一定是挤成一团，拆图比调参数有效。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth 逐个拆

这一节按真实遇到的报错来，每条都给现象、原因、修法。

401 Unauthorized。现象是 Claude Code 发任何消息都回 401。原因通常是 Key 错了、Key 过期了、或者 Base URL 写错导致请求打到了别的地方。修法：先去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 Key 还在、还有额度；然后检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api，结尾不要有斜杠，不要加/v1；最后确认ANTHROPIC_AUTH_TOKEN没有多余空格或换行。改完重启终端。

local proxy failed。现象是连接被拒或者超时。这个报错通常和本地网络配置有关，检查你的 shell 里有没有残留的HTTP_PROXY、HTTPS_PROXY环境变量指向一个已经关掉的本地端口。用env | grep -i proxy看一眼，有的话unset掉再试。另外确认ANTHROPIC_BASE_URL是 https 不是 http。

Error reading choices / reading choices 相关报错。现象是模型返回了内容但客户端解析失败。这多半是 Model ID 写得不完整或者不被识别。修法：把ANTHROPIC_MODEL写成完整的模型标识，比如claude-sonnet-4-5-20250929，不要简写。如果换了模型还是报，检查 settings.json 里有没有重复的 model 字段互相覆盖。

OAuth 相关报错。现象是提示需要登录或者 token 无效。Claude Code 在某些版本会尝试走 OAuth 流程，如果你用的是 API Key 模式，需要确认没有同时启用 OAuth 配置。检查~/.claude/下有没有冲突的凭据文件，必要时清掉重新用 Key 配置。如果你用的是 Codex 的auth.json那套，确认里面的 base_url 和 key 字段和 TaoToken 的一致。

PNG 转换失败 / rsvg-convert not found。现象是 SVG 生成了但 PNG 那步报命令找不到。修法就是装 librsvg：macOSbrew install librsvg，Ubuntusudo apt install librsvg2-bin。装完which rsvg-convert确认路径在，再重启 Claude Code。

Skill 不触发。现象是你说了「画架构图」但它没用 fireworks-tech-graph。原因可能是指令里没提 Skill 名字，或者 Skill 没加载。修法：指令里明确写「用 fireworks-tech-graph」，然后确认~/.claude/skills/fireworks-tech-graph/目录存在且里面有 SKILL.md 之类的定义文件。

出图但风格不对。现象是图出来了但是默认风格不是你指定的。检查风格名拼写，dark-terminal和dark terminal有的版本都认，但DarkTerminal可能不认。保险起见用连字符小写。另外确认 config.toml 里的默认值没有覆盖你的指令参数。

排障的核心思路是分层：先确认模型链路通（发普通消息），再确认 Skill 加载（列 skills），再确认指令被识别（看执行日志），最后确认产物生成（看文件）。哪层断修哪层，不要一上来就重装。

6. 把这条链路用顺之后，我的实际工作流

跑通之后我现在的习惯是：新项目先在 Claude Code 里把目录结构和依赖关系描述一遍，让它用 fireworks-tech-graph 出一张 dark-terminal 的全局图，存到项目docs/下。写方案的时候直接引用这张 SVG，需要改的时候在 SVG 里手动调两个文字，不用重新生成。给非技术同事看的时候，换 Glassmorphism 风格再出一版 PNG，观感立刻不一样。

如果你还没配好 Claude Code 的模型接入，先去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 拿 Key，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 有完整说明。想先试试模型对话效果，可以走 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。如果你打算长期用 Claude Code 做编码和 Agent 相关的事，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 可以看看。

最后留一个我踩过的坑：别在同一个对话里连续让它画五张不同风格的图，上下文会串，第二张开始风格可能飘。一张图一个对话，或者画完一张清一次上下文，出图稳定性会好很多。