1. 为什么要把 Architecture Diagram Skill 封装成独立应用如果你已经在 Codex、Claude Code 这类 AI 助手里反复调用 architecture-diagram Skill大概会遇到一个共同的别扭点每次画架构图都要重新组织一段自然语言描述生成完 HTML 文件后还得自己找地方存、自己命名、自己整理。一次两次还行当成日常动作就会明显感到流程是断的。Architecture Diagram Skill 本身解决的是「把自然语言描述转成内联 SVG CSS 的独立 HTML 架构图」这件事。它理解组件、连接关系、技术栈、协议、端口和部署边界输出的是可离线查看、可交付、可归档的文件。这个能力很强但它默认活在对话窗口里没有固定的输入界面也没有结果管理。iThinkAir 的价值就在这里它能把一个 Skill 技能化再基于技能生成一款带首页、带表单、带图库的应用。换句话说原本「描述—生成—下载—整理」的散点动作被收拢成一个字段明确、操作连续、结果可检索的产品界面。这篇要做的就是把 architecture-diagram 封装成「架构图生成器」同时把底层模型通道统一到 TaoToken 的 Key 上让 Skill 调用走一条稳定、可配置、可验证的 API 链路。适合谁看已经在用 AI 助手画架构图、想把它产品化的开发者需要给团队沉淀架构资产的技术负责人以及想把 Skill 接入统一模型通道、不想每个工具各配一套 Key 的工程同学。下面从 TaoToken 的前置配置讲起一路走到一次真实的架构图生成请求验证。2. TaoToken 前置统一 Key 与 API 通道准备在 iThinkAir 里跑 Skill底层还是要调模型。如果每个 Skill、每个应用都单独配一套厂商 Key维护成本会迅速失控。TaoToken 在这里扮演的是统一入口一个 Key、一条 API 通道覆盖对话、编码、Agent 等不同调用场景配置一次就能被多个工具复用。你需要先拿到两样东西API Key 和 API 地址。Key 在控制台的 API Keys 页面创建地址固定为https://taotoken.net/api。注意这个 API 地址后面不加任何查询参数保持干净避免某些客户端在拼接路径时出现重复斜杠或参数污染。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentithinkair-arch-skill创建时建议按用途命名比如ithinkair-arch-diagram这样后面在 iThinkAir 的配置里一眼能对上。Key 只在创建时完整显示一次复制后先存到本地密码管理器别直接贴进会提交到 Git 的文件。如果你还想先确认模型通道是否正常可以先用模型对话页面做一次最小验证确认 Key 有效、额度正常再去配 iThinkAir模型对话验证https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentithinkair-arch-skill接入相关的字段说明和路径规则以官方文档为准遇到 404 或鉴权失败时优先对照文档核对 base URL 和请求头接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentithinkair-arch-skill前置准备做完你手里应该有一个可用的 API Key、确认过的 API 地址https://taotoken.net/api、以及一次成功的对话验证记录。接下来进入 iThinkAir 的配置文件环节。3. 可复制配置config.toml 与 settings.json 骨架iThinkAir 的技能化与应用生成底层配置通常分两层一层是模型通道配置config.toml一层是应用与技能绑定配置settings.json。下面给出可直接复制的骨架字段名按你本地 iThinkAir 版本为准重点是结构和取值逻辑。先看config.toml它负责声明模型提供方、API 地址和鉴权方式# config.toml —— 模型通道统一配置 [provider] name taotoken # API 地址保持干净不加查询参数 base_url https://taotoken.net/api # 建议从环境变量读取避免明文入库 api_key_env TAOTOKEN_API_KEY [provider.headers] Content-Type application/json [model] # 按你实际可用的模型名填写 default claude-sonnet timeout_seconds 120 max_retries 2 [skill.architecture_diagram] enabled true # 技能包解析后的标识技能化完成后可在技能列表确认 skill_id architecture-diagram output_format html inline_svg true这里有两个容易踩的点。第一base_url只写到/api不要自己拼/v1/chat/completions之类的完整路径客户端会按自己的规则补全拼多了会 404。第二api_key_env走环境变量别把 Key 写死在 toml 里尤其是这个文件可能被同步或备份。再看settings.json它负责把技能和应用绑定起来并定义生成架构图时的输入字段{ app: { name: 架构图生成器, entry: index.html, features: [generate, gallery] }, skill_bindings: [ { skill_id: architecture-diagram, provider: taotoken, model: claude-sonnet, params: { theme: dark, inline_svg: true, export: [png, pdf] } } ], form_schema: { title: { type: string, required: true }, requirement: { type: text, required: true }, layers: { type: array, items: string } }, gallery: { searchable: true, sortable: true, actions: [preview, download, edit, delete] } }form_schema决定了「生成架构图」页面上的输入项gallery决定了架构图库的检索与操作能力。把这两个骨架填好应用的基本形态就定了。设置环境变量后启动 iThinkAirexport TAOTOKEN_API_KEY你的Key ithinkair serve --config ./config.toml --settings ./settings.json启动日志里如果出现 provider 初始化和 skill 加载成功的记录说明配置被正确读取。如果报 provider 未注册多半是name和客户端内置的 provider 标识对不上回文档核对一下。4. 验证请求跑通一次架构图生成配置就绪后最关键的一步是验证 Skill 到架构图生成器的完整链路。不要一上来就点界面按钮先用一次命令行请求确认模型通道和 Skill 调用都通这样出问题时能快速定位是通道问题还是应用层问题。先做一次最小连通性验证确认 Key 和 base URL 有效curl -sS https://taotoken.net/api/v1/messages \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, max_tokens: 64, messages: [ { role: user, content: 只回复 ok } ] }返回里能看到正常的响应体说明通道没问题。如果返回 401检查 Key 是否复制完整、是否带了多余空格返回 404检查 base URL 是否被拼错。通道确认后触发一次真实的架构图生成。在 iThinkAir 的「生成架构图」页面填写标题和需求需求尽量按「组件 关系 边界 约束」来写。以云原生数据中台为例标题云原生数据中台架构 需求 - 数据采集层使用 Flink 与 Spark支持实时与离线两条链路 - 存储层使用 HDFS 与 Iceberg实现湖仓融合 - 计算层使用 Presto 与 ClickHouse - 服务层通过 API Gateway 对外提供查询接口 - 全部组件部署在 Kubernetes 集群内使用 Helm 管理 - 标注实时数仓与离线数仓的数据流向点击「立即生成架构图」后应用会调用绑定的 architecture-diagram Skill把这段描述转成内联 SVG 的 HTML 文件。生成完成后预览窗口会打开你应该能看到 Kubernetes 集群边界、实时与离线两条链路以及 Flink、Spark、Iceberg、ClickHouse、Presto、API Gateway 之间的连线关系。验证成功的标志有三个预览能正常渲染、组件与连线符合描述、生成的文件能导出为 PNG 或 PDF。如果预览是空白先看浏览器控制台有没有 SVG 解析错误如果组件缺失多半是需求描述里层级没写清回到编辑功能补充组件关系再生成一次。5. 本篇常见错排查链路跑通之前报错基本集中在几个固定位置。下面按现象归类方便你对照排查。鉴权类401 / 403。最常见的是 Key 没读到环境变量。检查TAOTOKEN_API_KEY是否在当前 shell 会话里 export 过echo $TAOTOKEN_API_KEY能打印出值才算生效。如果用了 systemd 或容器启动环境变量要显式传入不会自动继承。路径类404 / 405。几乎都是 base URL 拼错。config.toml里只写https://taotoken.net/api不要补/v1或/chat/completions。客户端会按 provider 规则补全路径你补了它就重复了。技能类skill not found。技能化没完成或者skill_id和技能列表里的标识不一致。回到 iThinkAir 技能页面确认 architecture-diagram 已出现在列表中再核对settings.json里的skill_id。生成类预览空白或组件缺失。空白先查 SVG 是否被转义inline_svg要设为 true组件缺失是需求描述问题把「微服务架构」这种模糊说法换成明确的组件、协议、端口和边界重新生成。导出类PNG / PDF 失败。检查params.export是否包含对应格式以及运行环境是否有无头浏览器依赖。部分环境需要额外安装渲染依赖按 iThinkAir 启动日志的提示补齐。超时类请求 120 秒未返回。架构图生成属于长输出任务timeout_seconds建议不低于 120。如果频繁超时把需求拆成「先出结构、再补细节」两轮比一次塞进所有约束更稳。排查时有个通用原则先用 curl 验证通道再用应用验证 Skill。通道不通就别在应用层折腾通道通了再逐层往上查能省掉大量来回试错。6. 长期使用与 Coding Plan 接入建议把 architecture-diagram 封装成应用之后真正的收益在于复用。生成的架构图会自动进入架构图库支持按标题或需求搜索、排序以及预览、下载、编辑、删除。对需要持续迭代方案的团队来说这把一次性的 AI 输出沉淀成了可检索、可修改的架构资产不再散落在各个对话和本地目录里。如果你后续还要把这类 Skill 接到编码助手或 Agent 工作流里比如让 Claude Code 在写方案时直接调用架构图能力建议把模型通道统一到 Coding Plan避免对话、编码、Agent 各配一套 KeyCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentithinkair-arch-skill需要新增或轮换 Key 时回到控制台 API Keys 页面操作命名保持和用途一致方便审计API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentithinkair-arch-skill配置字段和路径规则有疑问时以接入文档为准接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentithinkair-arch-skill最后给一个实操建议把「组件 关系 边界 约束」写成需求模板存进团队文档每次生成架构图直接套用。需求写得越结构化生成结果越稳定返工越少。这套模板配合统一 Key 配置基本能让架构图生成从一次性尝试变成日常动作。