Archify：把代码库或一段系统描述变成可交互的系统地图——A…

一、Agent 出 JSON，Archify 出 HTML

README 第一行加粗的定义把职责切得很干净：Archify is a Node.js rendering and validation system for Cursor, Claude Code, Codex CLI, and OpenCode. Agents produce typed JSON IR; Archify deterministically compiles it into HTML/SVG.

拆开看有三个关键词。渲染与校验——它两件事都做，不是只管画。类型化 JSON IR——中间产物是有 schema 的结构化数据，不是自由文本。确定性编译——同样的 IR 必然得到同样的 HTML，这一步不交给模型的随机性。

紧随其后的四条卖点，每一条都对应一个真实场景：打开就能讲（五种图型、四套预设、明暗主题、内置品牌标记、有限动效）；合并前评审架构变更（两份已校验快照对比 Before / Delta / After，给出精确的 added、removed、changed、moved、rerouted 事实）；每次交互都有据可依（搜索节点、按需打开经版本校验的源码、追溯上游 / 下游的作者声明可达范围与精确路径、比较角色、播放引导故事，而不凭空编造拓扑）；一个文件即可信任与分享（自包含 HTML 外加 PNG、SVG、WebM 与 1200×630 分享卡片）。

注意第三条里那个词：authored。整份 README 反复强调自己展示的是作者写下的关系，而不是推断出来的运行时影响。这一点后面还会出现。

二、五类图型，五种沟通目的

README 给了一张选型表，三列分别是图型、最适合的场景、以及提示词里应该写什么。这张表其实是使用 Archify 的核心方法论。

• Architecture——组件、服务、存储、边界；提示词要给范围、核心组件、主路径。
• Workflow——CI/CD、审批、工具调用、runbook；要给参与者、顺序、分支、异常。
• Sequence——API 调用、缓存回退、鉴权、异步链路；要给调用方、被调方、返回值、时序。
• Data Flow——数据管道、血缘、PII、消费方；要给源头、变换、存储、边界。
• Lifecycle——状态、重试、等待、终态；要给状态、事件、重试与取消路径。

Architecture 还有一个可选的 deployment-ownership profile，README 用了个很硬的表述：fails closed——当作者声明的 owner、区域放置、私有数据库范围或命名 crossings 缺失时，它直接判定不通过，绝不做隐式推断，也不去探测真实基础设施。这种「宁可不给、不可瞎猜」的姿态，是它区别于一般图生成工具的分水岭。

面向设计或 PR 评审的还有 Architecture Delta：拿两份已校验的 Before / After 快照对比，产出机器可读的 receipt。你可以选中一条作者声明的变更，或播放一段有限的、仅供观看的 Review——它不推断影响面、风险，也不判断合并是否安全。

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

实在拿不准选哪类图，除了交互式场景指南，还可以直接问零依赖的 CLI：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

三、三条装法，七个落点

（一）全局安装与 Cursor 的显式命令

最短的一条：

npx skills add tt-a1i/archify -g

如果要给 Cursor 装，README 给了一条非交互的显式命令，把 skill 名、agent、作用域、复制方式与确认位全部写死：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

（二）不想装：临时用一次

npx skills use tt-a1i/archify@archify --agent codex

另外还有 DSH 社区的 opt-in 入口：dsh plugin –profile web add @tt-a1i/archify-dsh@0.1.0，对应开发者预览版 @deepseek-ai/dsh@0.1.0-rc.6，要求 Node ^22.19.0 || >=24.0.0，README 明确写了它不是 DeepSeek 官方产品、无遥测。

（三）七个安装落点

Installation options 那张表把每个客户端的目录都点名了：Claude Code 放 ~/.claude/skills/ 或项目级 .claude/skills/；Codex CLI 放 ~/.agents/skills/ 或 .agents/skills/；opencode 放 ~/.config/opencode/skills/、.opencode/skills/ 或 .agents/skills/；Claude.ai 走 Settings → Capabilities → Skills 上传 archify.zip（能力取决于沙箱里有没有 Node.js）；Project Knowledge 上传 zip 后只能走提示词驱动的架构回退路径；Raven 则是手动把 zip 解压到 ~/.raven/workspace/skills，得到 ~/.raven/workspace/skills/archify——README 特意注明 Raven 不是 agent switcher 的目标。

关于联网，README 有一段罕见的细致交代：Archify 可能会 GET 一份固定的稳定 manifest，仅用于显示可选更新提醒，从不下载或安装更新。成功检查后间隔约 72 小时（±20%）；活跃使用中若失败，会分别在 6 小时和 24 小时后重试。服务端只能看到常规 HTTP 元数据（IP 与时间），收不到版本号、Agent 信息、项目数据、提示词、账户 / 设备 ID 或 ETag。想彻底关掉，设 ARCHIFY_UPDATE_CHECK_DISABLED=1。

四、没有仓库也能起一张图

README 用加粗写了一句：No repository is required。你只要在任意 agent 聊天里描述系统：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

想要源码证据时才需要打开仓库，README 给的提示词模板是这样的：

Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

最后一句很实用——把补充细节放进卡片，而不是继续加边。之后可以在聊天里继续收敛：加个 Redis、把鉴权挪到左边、高亮回滚路径，类型化的源文件一直保留着，支持定点迭代。

README 举的实证是对 mco-org/mco 在 commit 9f1a1cf 上的追踪，产出了一张可勾选的地图，并且 Proof Lab 里收录了全部 11 个已签入场景及其 JSON 源、命名视图与校验凭据。

五、Why Archify：八条理由里的四根支柱

（一）版面判断优先于自动布局

第一条就划清了界限：Layout judgment over generic auto-layout——层级、间距、走线、强调由 Agent 决定；共享的自动端点会确定性地散开，而不是把一堆箭头堆在同一个中点上。这条直接解释了为什么它不打算做通用自动布局。

（二）类型化 IR 与交付前的原子校验

每个有渲染器支持的模式都有 schema 与可复现的源文件。交付前必须通过原子校验：schema、布局、HTML/SVG、路径、以及标签与走线的净空检查——五项全过，候选产物才会原子地替换上一个已知良好输出。

（三）失败给的是修复回执，不是堆栈

这条是我认为最见工程素养的：validate –json 与 deliver –json 失败时返回稳定的规则码、精确的出错主体、实测证据，以及仅支持的修复手段，而不是抛一个 Node 堆栈或一句「再试一次」。README 还划了流程边界：只应用每个 diagnostics[] 主体下的 supportedFixes，且限定在 Skill 的两轮修正之内；视觉评审仍是独立环节。

（四）Last-good 预览与真实的交互

可选的桌面预览循环只盯一个 JSON 文件，只有最新候选通过全部门禁后才刷新；保存不完整或不合法时，画面上留着上一张已验证的图。交互层面，focus、上下游 reach、精确 route、角色比较与 guided story 全部复用作者声明的节点与关系，不编造拓扑，也不声称运行时影响。源码证据只在被要求时出现——那些节点会把自己标成 SRC n，打开的 Git 校验文件与行范围钉在某一个公开 commit 上；普通产物则完全不含源码。

六、从生成到交付的五步

How it works 是一张五行的表：Generate（Agent 从描述生成类型化 JSON IR）→ Validate（内置校验器与布局规则检查，失败以机器可读 JSON 指出精确的本地修复点）→ Preview（可选，仅回环的桌面会话盯一个源文件，只重载已验证版本，失败保留 last-good）→ Deliver（同目录渲染候选并检查，只有通过的产物才原子替换目标，可选的 –open 再打开那个确切文件）→ Iterate（Agent 更新源文件，无关结构保持稳定）。

仓库里几个常用命令：

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

preview 被明确定义为仅回环的桌面模式：在随机 127.0.0.1 端口上盯一个 JSON 文件，失败时保留上一次已验证输出，Ctrl-C 停止，且不引入任何生成的 HTML 运行时；测试或想手动开 URL 时用 –no-open。deliver –open 是提交后的一次性交接：打开器失败不影响成功判定，JSON 仍在 stdout，绝对回退路径写到 stderr。

本地化设置就三行：meta.locale 取 en 或 zh-CN，只本地化页面标题、图例、状态 / 错误、无障碍文案与 HTML/SVG 的 lang——永远不翻译作者写下的内容；不填就保留请求语言的文案，若回退到英文需明确告知。静态产物会省略 animation，默认用 classic。

七、键盘上的探索与导出

生成的 HTML 自带一整套快捷键：? 打开事实性的图例，/ 搜索并聚焦语义节点，聚焦后按 Upstream / Downstream 追溯作者声明的可达范围，R 或 PATH 探测有向路径，L 或 LENS 比较两个语义角色，M 打开总览雷达，P 与 [ ] 播放引导故事或切换变更章节，F 进入演示舞台，S 循环视觉风格、T 切主题、E 打开导出，+ - 0 缩放与复位。

可分享的稳定链接支持 #focus=<id>、#focus=<id>&reach=upstream|downstream、#relation=<id>、#route=<source>~<target>、#lens=<kind>~<kind> 与 #view=<view-id>。读者触发的动效是有限的，尊重 prefers-reduced-motion，且不会进入正式导出件。

导出菜单可以把 PNG 复制到剪贴板，也能下载静态或带动效的格式；其中 Copy Share Card 给的是标准的 1200×630 图，适合 README、release 或社交帖子。追完一条路径后，Export → Route Share Card 会把那条作者声明的路径连同完整架构作为上下文，一起存成 1200×630 PNG；追完 Upstream / Downstream reach 后导出的 Reach Share Card 则只捕捉那一次精确的读取，不宣称任何运行时影响。

八、它明确宣布不做的事

README 在 Reference and scope 一节列了四项「刻意不在当前范围内」：自动解析 Mermaid、通用自动布局、托管分享、WYSIWYG 编辑。加上 Why Archify 末尾那句定性——它不是通用绘图编辑器，也不是 Mermaid 主题，而是把技术意图转成沟通产物——边界就很清楚了。

Sponsors 一节出现了两家：APINEBULA（一个 API 接 Claude、GPT、Gemini，通过 Archify 注册可用代码 Archify 打九折）与 EverMind（做 agent 记忆基础设施，其 Raven harness 把 Archify 作为 Skill 支持）。License 是 MIT，可自由使用、修改与分发。仓库当前版本 v2.17.0-dev.1，元数据上 54,725 Stars、3,587 Forks、140 个开放 Issue——对一个 2026 年 4 月才创建的项目来说，这个斜率相当陡。

九、写在最后

Archify 抓住的是一个很具体的痛点：AI 能画出看起来很像样的架构图，但你不敢把它放进评审材料，因为你不知道图里的箭头哪些是真的。它的解法不是让模型画得更准，而是在模型与产物之间插一层可校验的中间表示——类型化 JSON IR 让结构可复现，原子校验让失败可定位，修复回执让重试有依据，last-good 机制让坏版本永远盖不掉好版本，而「不推断运行时影响」的自我约束让每一条边都可以被追问来源。

当 Agent 开始参与架构决策，这类「可验证性基础设施」的价值会越来越超过「生成能力」本身。Archify 把这件事做到了一个相当克制的位置：它不替你判断，只保证你写下的东西被忠实、可重复、可追溯地呈现出来。

在撰写本文的过程中，我主要参考了以下来源：GitHub 仓库 tt-a1i/archify 的 README（Quick start / Choose the right diagram / Installation options / Why Archify / How it works / Explore and share / Reference and scope 各节）、项目页 tt-a1i.github.io/archify、Scenario guide 与 Proof Lab，以及仓库 meta 数据。文中数值以官方公开信息为准，可能随版本更新而变化。