← 返回公开文章

Archify 研究报告：对话式、可验证技术图生成器

/research/archify-research-guide.md

Archify 不是“把 Mermaid 换个主题”的美化器，也不是 Excalidraw/Figma 那类自由画布。它的定位更窄：让编码 Agent 先理解一个系统或仓库，再产出一份类型化 JSON IR；Archify 用本地 Node.js CLI 对这份 IR 做 schema、布局、连线、导出物校验，最后生成一个可交互、可分享的独立 HTML/SVG 技术图。

我的判断：值得试用，但要把它当成“Agent 交付图的验证/渲染层”，不要当成自动代码理解器或通用画图工具。 它最有价值的地方不是视觉风格，而是把 Agent 画图这件事加上了可复现源文件、机器可读错误、原子交付和 viewer 交互边界。风险也在同一个地方：拓扑和取舍仍由 Agent 生成，Archify 能验证“图合法、路线清楚、来源可绑定”，但不能自动证明 Agent 真的理解了系统。

项目基本信息

截至本机抓取时间 2026-09-07 10:35 CST，GitHub API 显示：

它解决什么问题

普通 Agent 很擅长“写一段架构说明”，但把说明变成可读图时经常有几个问题：

  1. 图形不可复现：同一个提示词多跑一次，布局、节点、标签可能大变。
  2. 错误难修：图坏了以后，Agent 看到的往往只是渲染失败或一堆浏览器/Node 栈，不知道该改哪个节点、哪条边。
  3. 好看和可信混在一起：一张漂亮图可能有错误连线、线穿节点、标签挡路径，也可能在交互里“暗示”不存在的关系。
  4. 分享成本高：图能在本地看，但很难作为一个单文件成品发给别人、嵌进文档或导出社交分享图。

Archify 的答案是：让 Agent 输出一个受 schema 约束的 JSON IR，再由 CLI 做 deterministic compile。README 里明确把它描述成“Agent 生成 Typed JSON IR，Archify 确定性编译成 HTML/SVG”；archify/SKILL.md 则把工作流写得更硬：先选择图类型，读对应 schema 和例子，写候选 JSON，每次候选都跑 validate，最终用 deliver 做原子交付。

最实用的能力

1. 五类技术图，而不是单一架构图

Archify 现在支持五种类型：

这比“只会画系统组件框图”有用得多。现实里的架构沟通经常不是问“系统有哪些服务”，而是问“一次请求怎么走”“一次发布怎么失败回滚”“一份数据从哪来到哪去”。Archify 把这些问题拆成了不同 schema 和 renderer，方向是对的。

2. Typed JSON IR + 严格 schema

archify/schemas/README.md 说明每种图都有独立 JSON schema，要求 schema_version、diagram_type、meta.title 和对应结构数组，并且大量位置 additionalProperties: false：未知字段不会被静默忽略。

这对 Agent 画图很关键。没有 schema 时，Agent 很容易写出“看起来合理但工具不认”的字段；有 schema 后，错误可以回到具体路径和字段。workflow 还引入了 v2 readable compiler，同时保留 v1 固定布局兼容：这说明项目已经开始认真处理“老图继续可用”和“新图更可读”的版本边界。

3. 原子交付和机器回执

archify/references/delivery-contract.md 把 validate、deliver、visual-check 分得很清楚：

这个边界做得不错。尤其是“失败保留 previous trusted artifact”“不要在失败 deliver 后对旧文件跑 visual-check”这类规则，说明维护者真正遇到过 Agent 交付中的坑，而不是只做一个漂亮 demo。

4. Viewer 交互是“读图工具”，不是随便编造关系

README 和 changelog 反复强调：focus、上游/下游 reach、route probe、semantic lens、story、relationship preview 都复用作者写入的节点和关系，不推断运行时影响，也不冒充 blast radius。

这点很重要。很多交互式图表一旦加动画和高亮，就很容易让读者以为“这里真的有实时流量/依赖影响”。Archify 的设计原则是“交互可以帮助阅读，但不能凭空增加事实”。这也是它比单纯 HTML 动画图更可信的地方。

5. Architecture Delta：合并前看架构变化

CHANGELOG.md 里 v2.13.0 引入了 archify compare architecture base.json head.json：它对两份 architecture 快照做 Before / Delta / After，对新增、删除、语义变化、移动和重路由做精确 ID 匹配，并生成 HTML 和机器 receipt。

这个能力比普通“画当前架构图”更接近工程价值：设计评审、PR 评审、文档更新时，真正关心的是“这次变更改了什么”，而不是每次重新看一整张静态图。不过它也明确不声称风险、blast radius、merge safety；它只是对作者写入的快照做差异证明。

6. Repository Evidence Passport：源码证据可绑定，但范围克制

Archify 支持 architecture 图声明公开 GitHub repo、完整 commit SHA，以及每个组件 1–3 个相对源码路径；配合 --repo-root 可以验证 origin、commit、blob 和行号范围。验证通过后，Viewer 里可以打开源码证据。

这是一个很聪明的边界：它不是自动代码索引器，也不是 RAG；它只是让“这张图上的某个节点为什么存在”可以指回一个固定公开提交。对文档、PR 说明、开源项目讲解有价值；对私有仓库或需要深层语义分析的场景，仍然要靠外部代码理解工具。

7. 导出和分享形态完整

README 里列的输出形态包括独立 HTML、PNG、SVG、WebM、1200×630 Share Card、Route Share Card、Reach Share Card。Proof Lab 也收录了 11 个 checked-in 场景、JSON source、named views 和 validation receipts。

如果只是内部临时看图，未必需要这么多导出。但如果要写 README、发 release note、给评审会、做社交预览图，这套导出形态能省很多二次处理。

核心工作流 / 架构

Archify 的工作流可以概括成一条链：

用户描述 / 仓库上下文
  → Agent 选择图类型并生成 Typed JSON IR
  → Archify schema + renderer/layout/composition validation
  → deliver 冻结规格、生成候选 HTML、做 artifact checks
  → 原子替换输出 HTML，并返回 SHA-256/bytes receipt
  → Reader 在单文件 Viewer 中搜索、聚焦、追踪路径、播放故事、导出

注意这里最关键的设计选择：Archify 没有把自动布局当作核心竞争力。 ROADMAP.md 明确说过，Mermaid parser + dagre/auto-layout 的方向被实验证明不够好，已经被杀掉；项目认为“布局判断”本身就是产品的一部分，Agent/Claude 需要在回路里决定层级、留白、主路径和强调关系。

这也解释了它为什么采用 JSON IR 而不是 Mermaid/DOT/GraphML：Archify 的 IR 不只是节点和边，还包含布局、卡片、视图、语言、视觉 preset、边界、证据、导出和 viewer 语义。传统图 DSL 更适合自动排版和长期文本维护；Archify 更像“Agent 生成的交付物规格”。

仓库结构上，核心代码集中在：

我统计到 archify/ 核心 runtime 约 51 个文件、约 22.9k 行文本；测试目录 114 个文件、约 30.4k 行；仓库里还包含大量生成 HTML、截图、GIF、benchmark 和 docs 资产，所以整体体积比核心代码大很多。

安装与使用形态

README 给出的主路径是：

npx skills add tt-a1i/archify -g

临时体验：

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

显式安装到 Cursor：

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

支持面包括 Cursor、Claude Code、Codex CLI、OpenCode、Raven 手动 ZIP、Claude.ai Skill 上传、Project Knowledge fallback，以及实验性的 DeepSeek Harness 插件。

需要注意两点：

  1. archify/package.json 是 private: true，核心运行时不是一个普通 npm library 包；README 里的 npx skills ... 是通过 skills CLI 安装 GitHub Skill。npm 上我验证到 skills 包当前 latest 为 1.5.24。
  2. DeepSeek Harness 插件 @tt-a1i/archify-dsh@0.1.0 确实在 npm 可见，描述为 experimental / community integration，要求 Node ^22.19.0 || >=24.0.0，不是官方 DeepSeek 产品，也不提供原生 render/validate/deliver tool，只是把 Archify Skill 暴露给 DSH。

本机实测结果

我没有只看 README，做了一轮隔离 smoke test。环境：/tmp/archify 浅克隆，HEAD c6519401f7b91b9d43011657880893b0a8955548；Node v22.19.0，npm 9.2.0。

已通过

未完全通过 / 风险信号

成熟度判断

这个项目不像一个周末 demo。几个信号比较强：

但它也处在高速变化期。main 是 v2.17.0-dev.1，稳定版是 v2.16.0，open PR 多于 open issue，说明项目还在密集迭代。对生产文档链路来说，应固定 release 或 commit，不要追 main。

和同类工具的区别

Archify 最容易被误解成 “Mermaid alternative”。这个说法只对一半。

所以它的优势不是替代所有图表工具，而是在下面这种缝隙里特别有用：你已经让 Agent 分析系统，但不信任它随手画出的图；你需要一个可验证、可复现、能交付给人的最终图。

风险、不足和避坑

1. 它不是代码理解引擎

Archify 可以验证 repository evidence 的 commit、路径、blob、行号，但不会自动完成深层代码语义理解。README 里“从真实仓库读出来”的 MCO 案例是一个 checked map，不代表随便给一个仓库就能自动得到正确架构。真正的系统理解仍取决于前置 Agent 的代码阅读能力。

2. 首次出图质量不是必然稳定

benchmarks/ordinary-model-floor/README.md 的措辞很克制：它测的是普通 coding agent 能否第一次就产出可用 Archify 图，并强调 reference fixtures 不是模型证据。保留的 2026-07-26 三模型样本在当前 verifier 下是 8/15 first-pass usable。也就是说，Archify 提供了门禁，但不承诺 Agent 一次就画对。

3. Visual-check 和人眼审查要分开

项目文档在这点上很诚实：deliver 不等于视觉审查，visual-check 也只是自动浏览器证据。本机 smoke 中 visual-check 还因为 Chrome load event timeout 失败。真正要把图放进重要文档或评审，至少要看一遍最终 HTML / PNG，尤其检查中文、长标签、路径遮挡和深浅主题。

4. 全局安装前先试 project-local 或临时路径

npx skills add ... -g 会改全局 Agent Skill 配置。研究或试用阶段更建议先用 skills use 临时体验，或者把 release ZIP 解到隔离目录，用本地 CLI 直接跑 doctor / guide / validate / deliver。

5. 自动更新提醒虽克制，但仍有网络请求

README 说明安装后的 Skill 可能低频 GET https://tt-a1i.github.io/archify/skill-updates/archify/stable.json，只做可选更新提醒，不下载、不安装、不上传版本/项目/提示词/账户信息。需要完全离线或严格无网络时设置：

ARCHIFY_UPDATE_CHECK_DISABLED=1

6. Brand capture 和源码证据会碰到外部资源边界

内置品牌库是本地的；未知站点的 brand capture 才需要显式命令和 digest pin。源码证据目前面向公开 GitHub revision。涉及私有仓库、内部域名、敏感路径时，不要让 Agent 直接生成可分享 HTML 前就把证据链写进去。

7. 生成 HTML 较大

我本地生成的两个 HTML 分别约 715 KB 和 723 KB；仓库里的 showcase HTML 也多在 700 KB 级别。单文件分享很方便，但如果大量嵌入文档或博客，要考虑加载体积和资产管理。

8. 当前 dev dependency audit 有高危提示

npm audit 对 fast-uri / ajv 的 high severity 提示需要关注。它未必影响零依赖打包 Skill 的普通运行时，但会影响贡献者开发环境和 release 构建可信度。建议等维护者升级到不受影响的 fast-uri >=3.1.6 后再把它纳入长期自动化链路。

适用边界与试用条件

适合试：

不适合：

对老大的价值判断

如果只选一个切入点，我建议把 Archify 当成 Codex/OpenCode 研究某个 repo 后的“最终交付图生成器”，而不是日常所有图表的默认工具。

推荐试用路线：

  1. 不全局安装，先在 /tmp 或单个试验 repo 用本地 clone 跑 CLI。
  2. 选一个中等复杂度项目，让 Codex 先读代码，再要求它用 Archify 生成 8–12 个核心组件的 architecture 图。
  3. 强制返回 JSON source、HTML artifact、validate / deliver receipt。
  4. 手工打开 HTML 看可读性，不接受只说“validation passed”。
  5. 如果第一张图有明显价值，再考虑安装成 Codex/OpenCode project-local Skill；等 fast-uri audit 和本机 visual-check timeout 问题确认后，再纳入更长期的文档自动化。

它不应该替代 BuJo research 里的 inline SVG 图文报告规则。BuJo 的长文图表更强调“图文交织、Markdown 可读、长期引用”；Archify 更适合生成一个独立互动 HTML，用在项目评审、演示和外部分享。

一句话结论

Archify 是一个很认真、工程边界清楚的 Agent Skill：它把“Agent 画技术图”从随手出图推进到可验证交付物。现在可以试，但应从 project-local / release 固定版本 / 人眼复核开始，不要盲目全局接入。

参考资料