1. 团队里为什么要给 Codex 单独装一个架构图 Skill上周三下午我们组一个同学在 Codex CLI 里敲了句“把订单履约链路画成架构图”回车之后出来的东西让评审会当场卡住一张图里 26 个节点全部是同样大小的圆角矩形连线横七竖八网关、服务、缓存、队列在视觉上完全平权没人能一眼看出哪层调哪层。他在对话里补了三轮提示词“用分层布局”“区分颜色”“少画点圆角”模型每次都点头产出依旧是满屏圆角框。问题不在模型能力在于对话式生成没有一份稳定的产出契约——同一个需求每次渲染出来的结构都不一样。解决思路是把“画架构图”从一次性提示词变成可复用的 Skill把风格约定、分层规则、渲染脚本、禁止事项全部固化成文件让 Codex 每次触发时读同一份规范。这类做法在开源社区热度很高很多团队都在把自己的架构图工作流封装成 Agent Skill。但在动手装 Skill 之前有一件事必须先落到团队账上这些 Skill 跑起来会持续消耗 Token而这些消耗必须挂在团队自己的 Key 上而不是散落在每个人的个人账号里。所以本文的路径是先到 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_intro 拿一个团队 Key把 Codex 的 Base URL 指向 https://taotoken.net/api再装架构图 Skill最后用 Key 维度把每一次“生成/修复架构图”的 Token 消耗记录清楚。这三个动作的顺序很重要反过来的话你会先跑出一堆图然后发现账单归属一团乱。下文按团队 Tech Lead 的视角展开包含可直接复制的config.toml、Skill 目录骨架、SKILL.md示例、Token 归属记录表以及一套排障清单。所有配置里的 Key 一律用YOUR_API_KEY占位请替换成自己在 TaoToken 控制台创建的真实值。2. 动手装 Skill 之前先把 Codex 的出口改到 TaoTokenCodex CLI 的供应商配置集中在~/.codex/config.toml。很多人装完 Skill 才发现调用失败其实是因为模型请求还在走默认出口与 Skill 本身无关。先把这个文件改对后面所有 Skill 的调用都会自然记在同一个 Key 下。# ~/.codex/config.toml model gpt-5-codex model_provider taotoken approval_policy on-request [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses几个容易踩坑的点第一base_url只写https://taotoken.net/api不要在后面拼/v1。Codex 会按wire_api自行补路径多写一层会出现 404 而不是 401报错信息很难指向根因。第二env_key写的是环境变量名不是 Key 本身。真正的 Key 放到 shell 环境里# macOS / Linux建议写进 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYYOUR_API_KEY # 校验是否注入成功只回显长度避免 Key 出现在终端历史里 echo -n $TAOTOKEN_API_KEY | wc -c第三Key 的创建入口统一走 TaoToken 控制台不要从别人那里复制粘贴。团队里每个人用自己的 Key或者至少每个仓库用一把独立 Key后面做 Token 归属统计时才有粒度。创建入口在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_key 建议现在就建一把命名规范见第 5 节。第四model字段要和你在 TaoToken 侧实际可用的模型名一致。模型对话页里能直接试跑和确认模型 ID地址是 https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_chat 。先在那里发一条“用一句话描述分层架构”确认 Key 和模型都通再回来写 Skill能省掉大量排查时间。配置完成后跑一次最小验证codex exec 输出一段 20 字以内的文字证明链路可用如果这一步返回正常文本说明出口已经指向 TaoTokenKey 也注入成功。此时再装架构图 Skill出问题就一定在 Skill 侧排查范围立刻收窄一半。3. 架构图 Skill 的目录骨架与 SKILL.md 写法Skill 的价值在于“规范和脚本跟着技能走”而不是让模型自由发挥。我们内部用的目录结构是这样~/.codex/skills/arch-diagram/ ├── SKILL.md # 触发条件 产出契约 禁止事项 ├── references/ │ └── style-guide.md # 配色、字号、层级间距 └── scripts/ └── render_dot.sh # 渲染脚本固定渲染参数SKILL.md的头部需要写清楚“什么时候用”这部分直接决定 Skill 会不会被正确触发。写得含糊模型在需要画图时想不起来写得太宽改个 README 也会触发绘图流程。--- name: arch-diagram description: 当用户要求生成、修改或评审系统架构图、部署拓扑图、调用链路图时使用。产出 Graphviz dot 源文件与 svg 渲染结果。 --- # 架构图 Skill ## 适用场景 - 用户明确要求“画架构图 / 拓扑图 / 链路图” - 用户要求对已有架构图做结构调整或视觉修复 - 代码评审中需要补充模块关系图 ## 产出契约必须全部满足 1. 先在 docs/arch/模块名.dot 写入 Graphviz 源文件 2. 再执行 scripts/render_dot.sh docs/arch/模块名.dot 3. 分层顺序固定为接入层 → 网关层 → 服务层 → 数据层 → 外部依赖 4. 单个图节点数量不超过 20超出时拆成两张图并标注关联关系 ## 视觉约定 - 节点形状统一使用 box禁止使用默认圆角矩形 - 接入层、服务层、数据层使用三套不同填充色 - 边标签只写协议或动作不写自然语言长句 ## 禁止事项 - 不生成 mermaid 源文件团队渲染器不统一 - 不在单张图里混排部署节点和业务模块 - 不输出没有源文件的“裸图片”这里有个细节值得展开为什么明确禁用默认圆角矩形。默认形状在很多渲染器里就是带圆角的box而被大量框架渲染出来的图之所以“满屏圆角框”根源是节点形状没有分化所有元素长得一样人眼无法快速建立层级。把形状和颜色绑定到架构层级上比反复调提示词有效得多。style-guide.md放具体数值避免每次生成都重新拍脑袋# 架构图样式规范 ## 颜色 - 接入层#E8F0FE 描边 #1A73E8 - 服务层#E6F4EA 描边 #137333 - 数据层#FEF7E0 描边 #B06000 - 外部依赖白底 虚线描边 #5F6368 ## 字体与尺寸 - 字体Helvetica节点字号 11边标签字号 9 - 节点间距同层横向 ranksep0.6层间 ranksep1.1 ## 布局 - 自左向右rankdirLR - 同层节点强制对齐ranksamerender_dot.sh把渲染参数固定住确保所有人产出同一种视觉风格#!/usr/bin/env bash # scripts/render_dot.sh set -euo pipefail SRC${1:?用法: render_dot.sh 源文件.dot} OUT${SRC%.dot}.svg dot -Tsvg $SRC -o $OUT \ -GrankdirLR \ -Gnodesep0.6 \ -Granksep1.1 \ -NfontnameHelvetica \ -Nfontsize11 \ -EfontnameHelvetica \ -Efontsize9 echo 已渲染: $OUT装完之后用一条命令验证 Skill 是否真的被加载codex exec 使用 arch-diagram Skill把订单履约链路整理成分层架构图预期结果是先出现docs/arch/order-fulfillment.dot随后出现同名 svg。如果只返回一段文字描述而没有源文件说明 Skill 没被触发优先检查SKILL.md的description是否覆盖了用户实际使用的说法。4. 从“满屏圆角框”到可读架构图提示词之外的三个硬约束装上 Skill 之后模型侧的行为稳定了很多但实际使用中还是有三类问题会反复出现。这三类问题的解法都不在提示词里而在约束文件里。第一类是节点膨胀。需求一说“画整个交易域”模型就会把能想到的模块全塞进去最后节点数超过 40。处理方式是在SKILL.md里写死上限并要求超限时拆图。我们的规则是单图节点 ≤ 20超限时按“主链路图 依赖明细图”拆成两张并在主链路图上用一行注释标出另一张图的文件名。第二类是层级混乱。表现是网关节点和数据节点出现在同一水平线上读者无法判断调用方向。处理方式是在 dot 源文件里显式使用ranksame和分层子图不依赖渲染器自动布局。例如digraph order_flow { rankdirLR; node [shapebox, stylefilled, fontnameHelvetica, fontsize11]; edge [fontnameHelvetica, fontsize9]; subgraph cluster_access { label接入层; color#1A73E8; App [fillcolor#E8F0FE]; H5 [fillcolor#E8F0FE]; } subgraph cluster_gateway { label网关层; color#137333; API-Gateway [fillcolor#E6F4EA]; } subgraph cluster_service { label服务层; color#137333; Order-Svc [fillcolor#E6F4EA]; Stock-Svc [fillcolor#E6F4EA]; } subgraph cluster_data { label数据层; color#B06000; Order-DB [fillcolor#FEF7E0]; MQ [fillcolor#FEF7E0]; } App - API-Gateway [labelHTTPS]; H5 - API-Gateway [labelHTTPS]; API-Gateway - Order-Svc [labelgRPC]; Order-Svc - Stock-Svc [labelgRPC]; Order-Svc - Order-DB [labelSQL]; Order-Svc - MQ [labelpublish]; }这份源文件里的关键点是shapebox配合显式分层子图。只要形状统一、层级由子图强制约束视觉上就不会退回到“一堆一模一样圆角框”的状态。第三类是修改需求表达不清。业务同学常说的“这块再往下放一点”“这里连根线过去”直接丢给模型会导致大范围重排。更稳的做法是先让模型只输出建议的 dot 片段人工确认后再让它落盘。codex exec 读取 docs/arch/order-fulfillment.dot只输出需要修改的节点与边不要重写整个文件只输出增量片段能把一次修改的 Token 消耗压下来也让 diff 更容易评审。这一点在按 Key 统计成本时会很有体感第 5 节会讲怎么记录。5. Token 消耗归属Key 命名规范与记录表Skill 装好之后最容易被忽略的是成本归属。Codex 调 Skill 的过程本身会读SKILL.md、读style-guide.md、读现有 dot 源文件这些都是输入 Token生成的 dot 片段和解释是输出 Token。一次“修复架构图”轻则几千 Token重则上万。如果所有消耗混在一个 Key 里月底没人说得清是哪个项目花的。我们的做法是三层结构第一层按仓库分 Key。命名规范固定为tt-团队-仓库-环境-序号例如tt-trade-order-prod-01、tt-trade-order-dev-02。Key 的创建与轮换在 TaoToken 控制台的 API Keys 页面完成地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_key_mgmt 。每个仓库的环境变量只对应自己那把 Key# 在 order 仓库的 .envrc 或 CI 变量中 export TAOTOKEN_API_KEYYOUR_API_KEY第二层按任务打标签。Codex 的调用不好直接打标签所以在仓库里加一个极薄的包装脚本把任务名写进日志#!/usr/bin/env bash # scripts/arch-task.sh set -euo pipefail TASK${1:?用法: arch-task.sh 任务名 提示词} PROMPT${2:?缺少提示词} LOGdocs/arch/token-log.csv START_TS$(date -u %Y-%m-%dT%H:%M:%SZ) codex exec $PROMPT printf %s,%s,%s,%s\n \ $START_TS $TASK ${TAOTOKEN_KEY_ALIAS:-unknown} ${TAOTOKEN_MODEL:-default} \ $LOG echo 已追加记录到 $LOG第三层用控制台的用量视图做对账。每周把控制台里该 Key 的用量和仓库里的token-log.csv条数做个粗略比对次数对不上就说明有人在本地用了同一把 Key 却没走脚本需要补规范。记录表至少包含这些列时间(UTC)任务Key 别名模型输入 Token输出 Token产出文件2025-03-11T07:20Z生成订单履约架构图tt-trade-order-dev-01gpt-5-codex48201960docs/arch/order-fulfillment.dot2025-03-11T09:05Z修复库存链路圆角框tt-trade-order-dev-01gpt-5-codex61101240docs/arch/stock-flow.dot2025-03-12T02:40Z拆分超限节点图tt-trade-order-dev-01gpt-5-codex33502210docs/arch/order-overview.dot后两列“输入/输出 Token”可以先用估算值填等控制台数据出来后修正。关键在于“产出文件”这一列它让一次 Token 消耗和一份可评审的交付物绑定起来评审时说“这张图花了多少钱”才有依据。Key 轮换也要写进规范每季度轮换一次轮换时新建 Key、更新环境变量、删除旧 Key历史用量记录保留。这样做的好处是即使某个 Key 意外泄露影响面也只限于一个仓库的一个季度。6. 团队排障清单Skill 不触发、图还是丑、请求报错装完 Skill 之后的头两周我们集中处理了三类问题整理成清单可以直接复用。问题一Skill 完全没被触发只返回文字描述。排查顺序先看~/.codex/skills/arch-diagram/SKILL.md是否存在且 frontmatter 完整name与description都不能缺再看description里是否包含了团队实际用的说法比如有人习惯说“拓扑图”而不是“架构图”那就把“拓扑图”补进描述最后用最直白的指令触发一次codex exec 使用 arch-diagram Skill 画出当前服务的部署拓扑问题二Skill 触发了图还是满屏圆角框。大概率是模型没读style-guide.md。检查SKILL.md里有没有显式要求“生成前先读取 references/style-guide.md”。另一种情况是源文件里写了shapebox但渲染脚本里带了覆盖形状的参数渲染阶段把样式改回去了需要检查render_dot.sh的参数列表。问题三请求返回 401 或 404。401 基本是 Key 没有正确注入。按顺序检查env_key写的变量名与export的变量名是否完全一致大小写敏感是否在同一个 shell 会话里执行的codexKey 是否被误加了引号导致值里带空格。可以用下面这条命令做不含 Key 内容的校验if [ -n ${TAOTOKEN_API_KEY:-} ]; then echo Key 已注入长度 $(printf %s $TAOTOKEN_API_KEY | wc -c) else echo Key 未注入请检查环境变量名 fi404 通常是base_url写多或写少了路径。正确值就是https://taotoken.net/api不要补/v1也不要漏掉/api。如果确认无误仍然 404先去模型对话页发一条消息用同一把 Key 验证服务侧是否正常https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_troubleshoot 。问题四Token 消耗异常高。常见原因是让模型“重写整个 dot 文件”。改成只输出增量片段单次消耗能明显下降。另一个原因是把长文档整个塞进上下文比如让 Skill 同时读十几个 dot 文件。约定单次最多读两个源文件即可。7. Claude Code 侧的同步配置与 CC Switch 三件套团队里不是所有人只用 Codex有一部分同学主力工具是 Claude Code。同一套 Skill 资产在两边都要能用但配置方式完全不同这里必须分开讲把 Codex 的写法套到 Claude Code、或者反过来都会直接失败。Claude Code 使用settings.json与环境变量配合{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意两点ANTHROPIC_AUTH_TOKEN填的是 Key 值本身不是环境变量名ANTHROPIC_BASE_URL同样只写到https://taotoken.net/api不要附加版本路径。配置完成后用一条简单请求验证链路。如果团队里同时存在多套供应商配置用 CC Switch 切换时要保证“三件套”同步更新三件套指的是 Base URL、API Key、模型名。只改其中一项是最常见的故障来源配置项一Base URL - https://taotoken.net/api 配置项二API Key - YOUR_API_KEY 配置项三模型名 - 与 TaoToken 侧可用模型一致切换完成后做一次确认避免选中了旧配置claude -p 只回答两个字已通需要再强调一次ANTHROPIC_*系列变量只对 Claude Code 生效Codex 读的是config.toml里的model_providers段两者互不通用。团队规范里最好把这条写成显式条款减少新人试错时间。Claude Code 侧的完整配置说明可以参考 TaoToken 的文档页https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_claude_code 。8. 落地节奏建议从一把 Key 到一套规范如果你准备在团队里推这套方案建议按两周节奏走不要一次性全铺开。第一周先在前端或后端挑一个仓库试点。动作是到 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_rollout 创建一把专用 Key改好config.toml装好arch-diagramSkill把这个仓库里最常被讨论的那张架构图重画一遍。这一周的目标不是画得多漂亮而是确认链路通、Skill 能触发、Token 有记录。第二周补规范。内容包括 Key 命名与轮换制度、token-log.csv的提交要求、Skill 的版本管理方式把~/.codex/skills下的目录放进内部仓库用软链接挂到本地、以及评审时“图必须带 dot 源文件”的硬性要求。这一周结束时应该能做到任意一张架构图都能追溯到源文件任意一次生成都能追溯到 Key 和任务名。后续扩容时Codex 和 Claude Code 两边共用同一套 Skill 资产、同一套 Key 命名规范只是配置入口不同。模型和套餐的选择可以按团队实际用量调整Coding Plan 页面有对应的方案说明地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_plan 。回到最开始那个场景评审会上再有人贴出一张满屏圆角框的架构图你可以直接问一句“dot 源文件在哪”。如果答不上来说明它没有走 Skill如果答得上来但样式不对说明style-guide.md需要补规则。到这一步“画架构图”就不再是一次撞运气的对话而是一条有输入、有产出、有成本记录的工程流程。现在就可以动手先去模型对话页确认你能用的模型 IDhttps://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_cta_chat 再按需选择套餐https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_cta_plan 然后创建属于这个仓库的 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_cta_keys 把config.toml里的base_url填成https://taotoken.net/api最后照着 Claude Code 文档把另一侧的settings.json对齐https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_skill_cta_doc 。四步走完你的架构图 Skill 和它的 Token 账本就都在自己手里了。
