1. 为什么架构图总是画不准从 skill-Archify 的定位说起skill-Archify 是一个专门用来生成技术架构图、工作流图、时序图、数据流图的技能skill它和通用绘图工具最大的区别在于它先理解系统结构再动手画图。很多开发者画架构图时踩过的坑不是图不好看而是图画错了——把本该是父子关系的模块画成了平行节点把串行调用画成了并行分支把数据流向标反。这类事实性错误在评审会上被指出来返工成本很高。skill-Archify 的思路是先让模型把系统拆解成结构化节点和边反复校验层级关系确认无误后再渲染成可交互、可导出、可追踪的图。它适合需要快速产出规范图的开发者尤其是手里有代码仓库、n8n 工作流、Agent 技术结构想自动转成架构图或数据流图的场景。这篇内容聚焦它在架构图、工作流图、时序图、数据流图四类场景下的配置落地给出可复制的 settings.json / config.toml 骨架以及通过 TaoToken 统一 Key 和 API 通道接入的完整步骤最后跑通一次架构图生成请求来验证通道与输出是否正常。我试过把 Archify 接到本地配置里最大的感受是图能不能画对一半取决于 skill 本身的结构化能力另一半取决于模型通道是否稳定、Key 是否统一管理。下面从 TaoToken 的前置准备开始讲。2. TaoToken 前置准备统一 Key 与 API 通道TaoToken 在这里扮演的角色是统一的模型接入层。你不需要为每个 skill 单独维护一套 Key而是把模型调用收敛到一个 API 通道上skill-Archify 只负责结构化理解和绘图逻辑模型请求走 TaoToken。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址https://taotoken.net/api 这个地址不加 UTM 参数直接用于配置你需要先拿到一个可用的 API Key。进入控制台创建 Key控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建完 Key 后建议先确认两件事一是这个 Key 对应的模型权限是否覆盖你要用的模型架构图生成通常需要较强的结构化推理能力二是配额是否够跑几轮校验请求因为 Archify 会反复检查结构单次出图可能触发多次模型调用。注意Key 只保存在本地配置文件或环境变量里不要写进会提交到 Git 的代码。下面配置骨架里我用占位符YOUR_TAOTOKEN_KEY表示。如果你打算长期做编码和 Agent 类任务可以看下 Coding Plan 的额度方案架构图生成这种多轮校验的场景对调用次数比较敏感Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里配置字段有疑问时对照查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content3. 可复制配置settings.json 与 config.toml 骨架skill-Archify 的配置分两层一层是模型通道配置指向 TaoToken一层是 skill 自身的行为配置图类型、校验轮数、导出格式。下面给两份骨架按你的运行环境选一份。3.1 settings.json 骨架适用于 JSON 配置的宿主{ model_provider: { name: taotoken, base_url: https://taotoken.net/api, api_key: YOUR_TAOTOKEN_KEY, default_model: claude-sonnet-4-5, timeout_seconds: 120, max_retries: 3 }, skill_archify: { diagram_types: [architecture, workflow, sequence, dataflow], structure_first: true, validate_rounds: 2, export_formats: [svg, png, json], interactive: true, trace_nodes: true, layout_engine: dagre, direction: TB } }几个关键字段说明structure_first设为 true 时Archify 会先输出结构化节点/边清单再渲染图。这是它减少事实错误的核心开关建议保持开启。validate_rounds是结构校验轮数。设成 2 表示模型会自查两遍层级关系父子节点、平行节点、串并行调用会被重新核对。轮数越高越准但调用次数也越多。direction控制图的走向TB是自上而下架构图常用时序图一般用LR从左到右。3.2 config.toml 骨架适用于 TOML 配置的宿主[model_provider] name taotoken base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY default_model claude-sonnet-4-5 timeout_seconds 120 max_retries 3 [skill_archify] diagram_types [architecture, workflow, sequence, dataflow] structure_first true validate_rounds 2 export_formats [svg, png, json] interactive true trace_nodes true layout_engine dagre direction TB3.3 四类图的参数对照不同图类型对参数敏感度不一样下面这张表可以直接对照调整图类型推荐 directionvalidate_rounds关键配置典型输入架构图TB2structure_firsttrue代码仓库结构、模块清单工作流图LR2trace_nodestruen8n 任务、Agent 步骤时序图LR1interactivetrue调用链、接口交互数据流图LR2export_formats 含 json数据管道、ETL 流程时序图校验轮数可以降到 1因为调用顺序相对线性过度校验反而拖慢出图。数据流图建议导出 json方便后续追踪节点来源。4. 跑通一次架构图生成请求验证通道与输出配置写好后先别急着画复杂系统用一个最小架构图请求验证通道是否通、输出是否正常。4.1 准备输入给 Archify 一段简单的系统描述比如一个三层结构的服务系统包含三层 - 接入层API Gateway负责路由和鉴权 - 服务层User Service、Order Service两者都依赖 Database - 数据层PostgreSQL 主库Redis 缓存 API Gateway 调用 User Service 和 Order Service User Service 和 Order Service 都读写 PostgreSQL Order Service 额外读写 Redis。4.2 发起生成请求在宿主里触发 Archify指定图类型为 architecture# 以命令行宿主为例实际触发方式按你的宿主而定 archify generate \ --input ./sample-system.txt \ --type architecture \ --config ./settings.json \ --output ./out/architecture.svg如果你的宿主是通过对话触发直接说「用 Archify 画一张架构图输入是 sample-system.txt导出 svg」即可。4.3 检查结构化输出请求发出后先看 Archify 返回的结构化清单而不是直接看图。正常输出应该类似{ nodes: [ {id: gateway, label: API Gateway, layer: access}, {id: user_svc, label: User Service, layer: service}, {id: order_svc, label: Order Service, layer: service}, {id: pg, label: PostgreSQL, layer: data}, {id: redis, label: Redis, layer: data} ], edges: [ {from: gateway, to: user_svc, type: call}, {from: gateway, to: order_svc, type: call}, {from: user_svc, to: pg, type: read_write}, {from: order_svc, to: pg, type: read_write}, {from: order_svc, to: redis, type: read_write} ] }重点核对三件事层级是否正确gateway 在 access 层不该和服务层平级、边方向是否正确gateway 指向 service不是反过来、依赖是否完整Order Service 到 Redis 的边有没有丢。4.4 确认渲染结果结构化清单没问题后再看导出的 svg。如果图里出现了父子节点被画成平行节点、或者边方向反了说明validate_rounds不够或模型通道返回被截断。通道正常的标志是请求在 timeout 内返回、结构化清单完整、svg 可打开且节点数与清单一致。想单独验证模型通道是否稳定可以用模型对话入口发一条测试请求模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content5. 本篇常见错排查5.1 报错401 UnauthorizedKey 没生效。检查api_key字段是否填了真实 Key有没有多余空格以及 Key 是否被禁用。如果用的是环境变量确认宿主能读到。5.2 报错404 或 base_url 拼接错误base_url必须是https://taotoken.net/api不要在后面多加/v1之类的路径除非接入文档明确要求。拼接错误会导致请求打到不存在的端点。5.3 图能出但结构错父子节点变平行这是structure_first没开或validate_rounds太低。把structure_first设为 truevalidate_rounds提到 2 或 3重新生成。如果还错检查输入描述本身是否把层级写清楚了——Archify 理解的是你给的结构输入含糊它也会含糊。5.4 请求超时架构图生成涉及多轮校验单次请求时间较长。把timeout_seconds提到 120 或更高max_retries设 3。如果频繁超时可能是模型通道负载问题换一个时间段重试。5.5 导出格式不支持export_formats里写的格式要和宿主支持的渲染器匹配。svg 和 png 通用性最好json 适合后续追踪。如果导出报错先只保留 svg 测试。5.6 时序图顺序错乱时序图对direction敏感设成LR。如果调用顺序还是乱检查输入里有没有明确标注步骤序号Archify 会按你给的顺序理解。6. 把 Archify 接进日常出图流程配置跑通后日常用法可以固定成一条链路代码仓库或工作流描述作为输入Archify 先出结构化清单人工核对层级和依赖确认后渲染导出。人工审核这一步不能省Archify 能减少事实错误但业务语义对不对最终要人来判断。如果你要长期跑编码和 Agent 类任务把模型通道统一到 TaoToken 上Key 和配额集中管理比每个 skill 单独配一套省心。需要更大额度时看 Coding Plan接入细节对照接入文档模型通道单独验证用模型对话入口。