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

发布时间:2026/9/29 9:59:34

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 的真正落点。
延伸阅读

更多相关文章

2026/9/29 9:54:33

箱形图:科研数据分布诊断的黄金标准

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/29 10:54:40

2026实测百度网盘下载慢?用Motrix与直链插件实现PanDownload满速

在平时使用网盘保存或者获取资料的时候,大家最关心的往往就是传输效率。有时候看着进度条走得非常缓慢,确实会让人感到有些着急。其实很多朋友可能会直接觉得是网络平台出了状况,但实际情况中,我们本地使用的设备和具体的设置环境…

2026/9/29 10:54:40

2026最新百度网盘提速指南:IDM多线程与PanDownload双方案对比

现代生活中文件往来越来越频繁,大家对传输效率的期待也越来越高。每当看到下载数值掉到几十甚至几千字节每秒的时候,大家的心情难免会变得烦躁,总觉得是网络链路出了大故障。 其实仔细排查就会发现,网络传输是一个环环相扣的过程…

2026/9/29 10:54:40

2026实测PanDownload最新稳定版:百度网盘多线程免限速满速下载

平时我们在保存和下载学习资料或者工作文件的时候,经常会遇到下载进度特别慢的情况。看着进度条几乎停滞不前,确实很让人头疼,其实很多时候问题并不全在远端,我们自己这边的设备和使用习惯往往也是关键因素。 有时候大家交流心得…

2026/9/29 10:54:40

元宝 LeetCode 129. 求根节点到叶节点数字之和 C语言实现

这是 LeetCode 129 题 “求根节点到叶节点数字之和” 的 C语言 实现。 解题思路:深度优先搜索(DFS) C 语言中我们可以通过递归函数来实现 DFS:传递累加值:定义递归函数 “dfs(struct TreeNode* node, int current_sum)…

2026/9/29 10:49:39

IEC 61131-3标准下梯形图编程与多品牌PLC程序移植指南

做PLC这一行久了,你会发现一个很有趣的现象:不管是刚入行的电气工程师,还是干了十几年的老手,大家手里的“武器”各不相同——有人用三菱,有人用西门子,有人用台达,还有人被客户指定必须用AB或者…

2026/9/28 3:03:23

东莞市品牌网站建设报价常见报错与解决

东莞品牌网站建设报价单背后:一份保姆级建站教程避坑实录 网站做好了没人访问,这大概是很多老板最头疼的事。花了大几万做的品牌站,上线后流量惨淡,比路边摊还冷清。别急着骂外包公司,很多“东莞品牌网站建设报价”里藏着不少猫腻,比如用模板站冒充定制…

2026/9/28 6:05:15

如何划分训练/验证集:Spirula Studio五种eval_mode策略详解

如何划分训练/验证集:Spirula Studio五种eval_mode策略详解 【免费下载链接】spirula-studio Cross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA. 项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio Sp…

2026/9/29 7:00:49

SEO怎么推广速查手册新手避坑实战指南

SEO怎么推广速查手册新手避坑实战指南 模板网站太丑不够用?别急着加滤镜,那是治标不治本。很多老板盯着后台流量掉得眼红,却还在纠结首页Banner的圆角是不是3像素。这就像穿着西装去挖土,姿势不对,努力白费。我整理这份 速查手册…

2026/9/29 0:04:04

AI Evals实战指南:从零搭建LLM应用评估体系与CI/CD集成

1. 为什么AI Evals值得你花时间搞明白做LLM应用的人,迟早会撞上同一堵墙:模型输出飘忽不定,今天答得好好的,明天换个问法就胡说八道。你改了一版提示词,感觉好像好了点,但到底好了多少?说不清。…

2026/9/29 0:04:04

Java采购管理系统实战:从数据库设计到事务一致性

简介:这是一套面向Java Web初学者与课程设计者的采购管理系统完整源码,采用JSP技术搭建,配合MySQL数据库,用于解决企业采购信息的管理问题,适合作为毕业设计、课程大作业或进销存类项目的参考模板。系统实现了用户登录…

2026/9/29 3:53:39

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/29 9:46:12

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/29 6:36:14

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑