Archify 深度解析：用 Agent Skill 把自然语言与代码仓库生成可验证架构图

1. 为什么你的架构图总是过期从 Archify 的 Agent Skill 工作流说起代码天天在变架构图却停留在三个月前的 PPT 里。这不是懒是工具链断层——Mermaid 能画但评审时不敢信draw.io 好看但改一次要拖半小时AI 随手吐的 SVG 更是好看一次就废。Archify 这个 Agent Skill 想解决的就是这件事让 Cursor、Claude Code 这类 Coding Agent 把自然语言或代码仓库直接编译成可验证的架构图中间走一层类型化 JSON IR交付前过原子校验门禁最后渲染成自包含 HTML。它是什么一句话面向 Coding Agent 的架构可视化 Skill输入是描述或仓库输出是带 schema 的 JSON IR 加可交互 HTML。能做什么支持架构图、工作流、时序图、数据流、生命周期五类图每类都有独立 schema 和校验规则。适合谁已经在用 Cursor / Claude Code / Codex 的架构师和技术负责人尤其是需要把「图即契约」落进 Git 和 PR 评审的团队。我试过把一份 2000 行的支付回调链路丢给它Agent 先读仓库结构再生成 IR校验失败两次后自己修好了——这个过程比手动画图快但前提是你得把 Skill 装对、提示词写清楚。下面按完整工作流拆输入解析、IR 生成、图校验三步每步都给可复制的配置和验证动作。核心检索词先摆出来Archify 是一个 Agent Skill通过 JSON IR 中间表示把自然语言或代码仓库转成可验证架构图适合 Cursor 和 Claude Code 用户做架构即代码。它的价值不在「画得好看」而在「图能进 Git、能 diff、能过 CI 门禁」。2. TaoToken 前置给 Agent 配一个稳定的模型入口Archify 本身是 Skill不绑定模型但它的工作流高度依赖 Agent 的推理质量——IR 生成、校验错误修复、布局判断都靠模型。如果你用 Cursor 或 Claude Code 直连官方 API国内网络下经常遇到超时、限流、OAuth 反复失效。这时候需要一个兼容 Anthropic / OpenAI 协议的模型入口TaoToken 就是干这个的。先说清楚它不是什么不是编辑器替代品不是画图工具是模型 API 的接入层。你要做的三件事拿 Key、配 Base URL、选 Model ID。这三件套在 Cursor、Claude Code、Cline、Codex 里都要填全缺一个就连不上。拿 Key 的路径打开 https://taotoken.net/api-keys 登录后创建新 Key复制保存。注意 Key 只显示一次丢了就重建。Base URL 统一用 https://taotoken.net/api 不要加 UTM 参数不要加尾部斜杠。Model ID 根据你的场景选Claude 系列适合长上下文仓库分析GPT 系列适合快速迭代 IR。具体可用模型列表在 https://taotoken.net/models 查。配好之后Agent 的推理请求走 TaoTokenArchify 的校验和渲染仍在本地 Node 完成——这个分工很重要代码不出本地只有提示词和 IR 片段走网络。如果你对数据边界敏感可以在 Skill 配置里关掉更新检查环境变量ARCHIFY_UPDATE_CHECK_DISABLED1。这一步的验收标准在 Cursor 里发一句「用 Archify 画 Browser→API→Redis→Postgres」Agent 能正常返回 IR 而不是报 401 或连接超时。如果报错先查 Key 和 Base URL再查模型名是否拼错。3. 可复制配置Skill 安装与 JSON IR 骨架这一节给三样东西Skill 安装命令、Agent 落盘路径、可复制的 IR 配置片段。路径和原文一致直接抄。3.1 安装 Skill通用安装npx skills add tt-a1i/archify -gCursor 显式非交互安装npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yesCodex 临时试用不永久安装npx skills use tt-a1i/archifyarchify --agent codex不同 Agent 的落盘位置环境安装位置Claude Code~/.claude/skills/或.claude/skills/Codex CLI~/.agents/skills/或.agents/skills/OpenCode~/.config/opencode/skills/等Cursor通过 skills 安装器落到.agents/skills/archifyRaven解压archify.zip→~/.raven/workspace/skills/archify3.2 Cursor / Claude Code 的模型配置Cursor 在 Settings → Models 里填{ openai.apiKey: 你的TaoToken Key, openai.baseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514 }Claude Code 用settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Cline MCP 配置里同样三件套Base URL 填https://taotoken.net/apiKey 填 TaoToken KeyModel ID 填具体模型名。Codex 的auth.json里base_url和api_key对应填。3.3 Architecture IR 最小骨架以下结构以仓库archify/schemas/architecture.schema.json为准真实项目让 Agent 生成后再 validate{ schema_version: 1, diagram_type: architecture, meta: { title: Checkout Runtime, locale: zh-CN, visual_preset: signal-flow, animation: trace }, components: [ { id: web, label: Web App, kind: frontend }, { id: api, label: Checkout API, kind: backend }, { id: redis, label: Redis Cache, kind: database }, { id: pg, label: PostgreSQL, kind: database }, { id: pay, label: Payment Gateway, kind: external } ], boundaries: [ { id: dmz, label: Public Edge, members: [web] }, { id: core, label: Trust Boundary, members: [api, redis, pg] } ], connections: [ { from: web, to: api, label: HTTPS }, { from: api, to: redis, label: GET cache }, { from: api, to: pg, label: fallback query }, { from: api, to: pay, label: charge } ] }Sequence 片段{ diagram_type: sequence, meta: { title: Cache Miss Path }, participants: [ { id: web, label: Web App }, { id: api, label: API }, { id: redis, label: Redis }, { id: db, label: Postgres } ], messages: [ { from: web, to: api, label: GET /item/42 }, { from: api, to: redis, label: GET item:42 }, { from: redis, to: api, label: MISS, style: return }, { from: api, to: db, label: SELECT ... }, { from: db, to: api, label: row, style: return }, { from: api, to: redis, label: SETEX }, { from: api, to: web, label: 200 JSON, style: return } ] }注意schema_version和diagram_type是必填字段缺一个校验直接失败。kind字段决定语义色frontend / backend / database / external 各有对应配色。4. 验证请求从 doctor 到 deliver 的完整链路配好之后别急着画大图先用官方 demo 跑通链路。这一步的目的是确认 Node 环境、Skill 安装、校验器、渲染器四者都正常。4.1 环境自检cd archify node bin/archify.mjs doctordoctor 会检查 Node 版本、依赖完整性、schema 文件是否存在。如果报Cannot find module说明 Skill 没装全重跑安装命令。4.2 一键演示node bin/archify.mjs demo /tmp/archify-demo这个命令会生成一份示例 IR 并渲染成 HTML输出到/tmp/archify-demo。打开 HTML 能看到交互式架构图试快捷键/搜索聚焦R路径探针P播放引导故事E导出。4.3 校验 IRnode bin/archify.mjs validate workflow \ examples/agent-tool-call.workflow.json \ --quality showcase --json校验失败会返回机器可读诊断包含rule code、subject、evidence、supportedFixes。这是 Agent 自愈的关键——模型读到supportedFixes就知道怎么改不用盲目重试。4.4 监视预览node bin/archify.mjs preview workflow \ examples/agent-tool-call.workflow.json \ /tmp/workflow.html --quality showcasepreview 只监听127.0.0.1校验通过才刷新失败保留 last-good。适合边改 IR 边看效果。4.5 原子交付node bin/archify.mjs deliver workflow \ examples/agent-tool-call.workflow.json \ /tmp/workflow.html --quality showcase --open --jsondeliver 是原子操作候选产物全部检查通过才替换上一份已知良好输出失败则保留旧文件并返回修复收据。这个设计对 Agent 循环极关键。4.6 Architecture Delta 对比node archify/bin/archify.mjs compare architecture \ base.json head.json \ architecture-delta.html --jsoncompare 输出 Before / Delta / After 三段PR 评审时直接看新增、删除、改动、改道四类变更。这是 Archify 区别于普通画图工具的核心能力。4.7 成功结果长什么样打开生成的 HTML你应该看到自包含文件不依赖服务器双主题切换节点可搜索聚焦路径探针能追上下游引导故事按顺序高亮主路径。导出菜单支持 4× PNG、SVG、WebM、1200×630 Share Card。如果 HTML 打开是空白先查浏览器控制台报错再查 IR 里components和connections的 id 是否对得上——引用了不存在的 id 会导致渲染中断。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给排查路径。每个错误都先定位是模型层还是 Skill 层。5.1 401 Unauthorized现象Agent 发请求返回 401或 Cursor 提示invalid api key。排查顺序先确认 TaoToken Key 是否复制完整有没有多余空格再确认 Base URL 是否写成https://taotoken.net/api不要加尾部斜杠最后确认 Model ID 是否在可用列表里。三件套缺一个都会 401。如果 Key 刚创建就 401可能是复制时漏了尾部字符。重建一个 Key 再试。5.2 local proxy failed现象Claude Code 或 Cline 报local proxy failed或connection refused。这通常是本地代理端口冲突或环境变量没生效。检查settings.json里ANTHROPIC_BASE_URL是否被其他配置覆盖检查是否有残留的HTTP_PROXY/HTTPS_PROXY环境变量指向失效地址。清掉这些变量再重启 Agent。5.3 reading choices 报错现象Agent 返回reading choices或cannot read property choices of undefined。这是响应格式不匹配——模型返回的不是 OpenAI 兼容格式。检查 Model ID 是否拼错或者 Base URL 是否指向了错误的端点。TaoToken 的 API 端点统一是https://taotoken.net/api不要写成/v1/chat/completions之外的路径。5.4 OAuth 失效现象Claude Code 反复要求登录或提示OAuth token expired。如果你用的是 API Key 模式不应该走 OAuth。检查settings.json里是否同时存在 OAuth 配置和 API Key 配置两者冲突时优先走 OAuth 导致失败。删掉 OAuth 相关字段只保留ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL。5.5 Skill 校验失败现象validate返回schema_version mismatch或unknown diagram_type。检查 IR 里schema_version是否为1diagram_type是否为architecture/workflow/sequence/dataflow/lifecycle之一。拼写错误或大小写不一致都会失败。5.6 渲染空白现象HTML 打开空白控制台报component id not found。检查connections里的from/to是否都在components的id里定义过。Archify 不做隐式补全引用不存在的 id 直接中断渲染。提示所有校验错误都带supportedFixes把这段 JSON 直接贴回给 Agent它下一轮就能改对。这比你自己读 schema 快得多。6. 语义一致 CTA把架构图变成可评审的工程资产走到这一步你应该已经跑通了「自然语言 → JSON IR → 校验 → HTML」的完整链路。接下来是把这套流程固化进团队习惯。个人尝鲜的验收标准得到一份通过校验的 HTML而不是一张无法修改的截图。团队落地的约定docs/architecture/*.json和生成的*.html一起进库架构相关 PR 必须附 Delta 产物评审清单看校验收据、主路径、信任边界、外部依赖而不是「好不好看」。CI 最小集成思路find docs/architecture -name *.json | while read f; do node archify/bin/archify.mjs validate architecture $f --json || exit 1 done node archify/bin/archify.mjs deliver architecture \ docs/architecture/checkout.json \ docs/architecture/checkout.html --json把「图过期」从人为习惯变成流水线门禁。如果你还没配好模型入口先去 https://taotoken.net/api-keys 拿 Key接入文档在 https://taotoken.net/doc 。想先验证模型对话效果用 https://taotoken.net/chat 。长期做编码和 Agent 协作看 Coding Planhttps://taotoken.net/coding-plan 。Claude Code 用户直接参考 Anthropic 接入页https://taotoken.net/claude-code-anthropic 。最后给一个团队标准提示词直接抄Use archify Architecture Blueprint preset. Scope: runtime path of 服务名 only. Constraints: - 8–12 components max - one primary happy path - explicit trust boundaries - external systems clearly marked - put secondary detail into cards, not extra edges Deliver HTML under docs/architecture/service-runtime.html Also keep the JSON IR alongside for review.Agent 负责从仓库提炼架构师负责审 IR 是否说了真话。图即契约Delta 进 PR这才是 Archify 作为 Agent Skill 的真正落点。