企业官网建设流程全解析

1. 团队里为什么要给 Codex 单独装一个架构图 Skill

上周三下午，我们组一个同学在 Codex CLI 里敲了句“把订单履约链路画成架构图”，回车之后出来的东西让评审会当场卡住：一张图里 26 个节点，全部是同样大小的圆角矩形，连线横七竖八，网关、服务、缓存、队列在视觉上完全平权，没人能一眼看出哪层调哪层。他在对话里补了三轮提示词，“用分层布局”“区分颜色”“少画点圆角”，模型每次都点头，产出依旧是满屏圆角框。问题不在模型能力，在于对话式生成没有一份稳定的产出契约——同一个需求，每次渲染出来的结构都不一样。

解决思路是把“画架构图”从一次性提示词变成可复用的 Skill：把风格约定、分层规则、渲染脚本、禁止事项全部固化成文件，让 Codex 每次触发时读同一份规范。这类做法在开源社区热度很高，很多团队都在把自己的架构图工作流封装成 Agent Skill。但在动手装 Skill 之前，有一件事必须先落到团队账上：这些 Skill 跑起来会持续消耗 Token，而这些消耗必须挂在团队自己的 Key 上，而不是散落在每个人的个人账号里。

所以本文的路径是：先到 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=codex_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 的出口改到 TaoToken

Codex 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_KEY="YOUR_API_KEY" # 校验是否注入成功，只回显长度，避免 Key 出现在终端历史里 echo -n "$TAOTOKEN_API_KEY" | wc -c

第三，Key 的创建入口统一走 TaoToken 控制台，不要从别人那里复制粘贴。团队里每个人用自己的 Key，或者至少每个仓库用一把独立 Key，后面做 Token 归属统计时才有粒度。创建入口在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=codex_skill_key ，建议现在就建一把，命名规范见第 5 节。

第四，model字段要和你在 TaoToken 侧实际可用的模型名一致。模型对话页里能直接试跑和确认模型 ID，地址是 https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=codex_skill_chat 。先在那里发一条“用一句话描述分层架构”，确认 Key 和模型都通，再回来写 Skill，能省掉大量排查时间。

配置完成后跑一次最小验证：

codex exec "输出一段 20 字以内的文字，证明链路可用"

如果这一步返回正常文本，说明出口已经指向 TaoToken，Key 也注入成功。此时再装架构图 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 - 节点间距：同层横向 ranksep=0.6，层间 ranksep=1.1 ## 布局 - 自左向右（rankdir=LR） - 同层节点强制对齐（rank=same）

render_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" \ -Grankdir=LR \ -Gnodesep=0.6 \ -Granksep=1.1 \ -Nfontname=Helvetica \ -Nfontsize=11 \ -Efontname=Helvetica \ -Efontsize=9 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 源文件里显式使用rank=same和分层子图，不依赖渲染器自动布局。例如：

digraph order_flow { rankdir=LR; node [shape=box, style=filled, fontname="Helvetica", fontsize=11]; edge [fontname="Helvetica", fontsize=9]; 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" [label="HTTPS"]; "H5" -> "API-Gateway" [label="HTTPS"]; "API-Gateway" -> "Order-Svc" [label="gRPC"]; "Order-Svc" -> "Stock-Svc" [label="gRPC"]; "Order-Svc" -> "Order-DB" [label="SQL"]; "Order-Svc" -> "MQ" [label="publish"]; }

这份源文件里的关键点是shape=box配合显式分层子图。只要形状统一、层级由子图强制约束，视觉上就不会退回到“一堆一模一样圆角框”的状态。

第三类是修改需求表达不清。业务同学常说的“这块再往下放一点”“这里连根线过去”，直接丢给模型会导致大范围重排。更稳的做法是先让模型只输出建议的 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_source=taotoken_aicg_blog_end&utm_content=codex_skill_key_mgmt 。每个仓库的环境变量只对应自己那把 Key：

# 在 order 仓库的 .envrc 或 CI 变量中 export TAOTOKEN_API_KEY="YOUR_API_KEY"

第二层，按任务打标签。Codex 的调用不好直接打标签，所以在仓库里加一个极薄的包装脚本，把任务名写进日志：

#!/usr/bin/env bash # scripts/arch-task.sh set -euo pipefail TASK="${1:?用法: arch-task.sh <任务名> <提示词>}" PROMPT="${2:?缺少提示词}" LOG="docs/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 却没走脚本，需要补规范。

记录表至少包含这些列：

后两列“输入/输出 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”。另一种情况是源文件里写了shape=box，但渲染脚本里带了覆盖形状的参数，渲染阶段把样式改回去了，需要检查render_dot.sh的参数列表。

问题三：请求返回 401 或 404。

401 基本是 Key 没有正确注入。按顺序检查：env_key写的变量名与export的变量名是否完全一致（大小写敏感）；是否在同一个 shell 会话里执行的codex；Key 是否被误加了引号导致值里带空格。可以用下面这条命令做不含 Key 内容的校验：

if [ -n "${TAOTOKEN_API_KEY:-}" ]; then echo "Key 已注入，长度 $(printf '%s' "$TAOTOKEN_API_KEY" | wc -c)" else echo "Key 未注入，请检查环境变量名" fi

404 通常是base_url写多或写少了路径。正确值就是https://taotoken.net/api，不要补/v1，也不要漏掉/api。如果确认无误仍然 404，先去模型对话页发一条消息，用同一把 Key 验证服务侧是否正常：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=codex_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_source=taotoken_aicg_blog_end&utm_content=codex_skill_claude_code 。

8. 落地节奏建议：从一把 Key 到一套规范

如果你准备在团队里推这套方案，建议按两周节奏走，不要一次性全铺开。

第一周，先在前端或后端挑一个仓库试点。动作是：到 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=codex_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_source=taotoken_aicg_blog_end&utm_content=codex_skill_plan 。

回到最开始那个场景：评审会上再有人贴出一张满屏圆角框的架构图，你可以直接问一句“dot 源文件在哪”。如果答不上来，说明它没有走 Skill；如果答得上来但样式不对，说明style-guide.md需要补规则。到这一步，“画架构图”就不再是一次撞运气的对话，而是一条有输入、有产出、有成本记录的工程流程。

现在就可以动手：先去模型对话页确认你能用的模型 ID（https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=codex_skill_cta_chat ），再按需选择套餐（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=codex_skill_cta_plan ），然后创建属于这个仓库的 Key（https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=codex_skill_cta_keys ），把config.toml里的base_url填成https://taotoken.net/api，最后照着 Claude Code 文档把另一侧的settings.json对齐（https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=codex_skill_cta_doc ）。四步走完，你的架构图 Skill 和它的 Token 账本，就都在自己手里了。