Archify 深度拆解：从 Agent Skill 到可验证的交互式架构图

📅 2026-10-09 📂 工具 🏷️ Archify, Agent Skill, 系统设计, 架构图, 工程工具
10 分钟阅读 · 2,680 字

系统架构图最常见的失真，不是画得不够漂亮，而是图上的调用关系、信任边界和运行行为没有事实依据。Archify 试图把“让 Agent 画一张图”变成更受约束的过程：先由作者提供结构化的 Typed JSON 中间表示，再经过类型专属渲染器和机器检查，最后交付一个独立 HTML。它是图表创作与阅读工具，不是能从仓库源码自动还原全部运行时拓扑的静态分析器。

本文按公开仓库在 2026-10-09 可见的 main 提交 48cb9333bce7392010cdc858d10be7f304a28052 拆解。该快照自报版本 2.16.0-dev.0，其测试目录包含 81 个 .test.mjs 文件；这里核查的是实现结构和测试设计，不代表我在本机执行过这 81 个测试。

一、先选对图，而不是先堆节点

仓库把五类视图拆成独立 schema 和 renderer，避免用一张万能流程图承载完全不同的语义：

  • Architecture：组件、服务、存储、外部依赖、信任与部署边界。适合回答“系统由什么组成、主要依赖如何连接”。
  • Workflow：参与者执行的步骤、分支、审批和异常路径。适合 CI/CD、工具调用和 Runbook。
  • Sequence：带时序的请求、响应、回调和异步链路。适合登录、缓存回源、API 调用。
  • Data Flow：数据从哪里来，经过哪些转换、存储和消费者。适合事件管道、ETL、血缘与 PII 流转。
  • Lifecycle：对象状态、事件、重试、等待、取消和终态。适合任务、发布和 Agent 运行过程。

它们共享通用字段，但类型 schema 会限制各自可以表达的概念。选型时应先说清问题：若关心“谁在什么时间调用谁”，用 Sequence；若关心数据经过了哪些加工，选 Data Flow；若状态会重试或回退，选 Lifecycle。不要为了复用现成布局，把状态变化硬画成普通节点和箭头。

二、Typed JSON 是可校验的唯一事实源

每张图从小型 JSON 规格开始。稳定 ID、节点类型、作者定义的关系和可选元数据放在数据层，SVG/HTML 只是它的呈现。共享 schema 加上五种类型 schema 负责字段形状和约束；开发仓库用 Ajv 生成 standalone validators，并把生成结果提交到 Skill 包里。因此安装后的运行时不需要先执行 npm install 才能解析图表规格。

这层设计的价值在于：Agent 的自然语言输出必须落到可检查的数据结构，渲染器只负责把明确的关系转换为布局；文件可以进入版本控制，差异也能以结构化方式比较。代价是作者需要理解 schema 和稳定 ID，不能把 JSON 当作任意字段都能生效的配置文件。未知字段、错误类型或不完整关系应修正数据，而不是靠 CSS 把结果遮过去。

首次使用可以先问 CLI 场景指南，而不是要求 Agent 直接猜布局：

node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json
node archify/bin/archify.mjs doctor

guide 根据场景推荐图表类型和结构提示；doctor 检查 Node 版本、模板、renderer、示例、schema validator、预览运行时和渐进式作者文档是否齐备。它们缩小了选型和环境问题的范围，但不会替作者核实业务事实。

三、从候选 JSON 到可信 HTML 的交付门禁

仓库把快速探索与最终交付分开。可以按下面的路径理解：

场景与代码证据
      ↓
选择 diagram type，编写 Typed JSON
      ↓
validate：schema + renderer + 产物检查 + 组合诊断
      ↓
修复明确诊断，再冻结候选规格
      ↓
deliver：同目录私有快照 -> 渲染 -> 完整检查 -> 原子替换
      ↓
visual-check 自动测量/截图 + 人工浏览器视觉审阅

常用命令如下，路径以仓库根目录执行为例：

node archify/bin/archify.mjs validate workflow archify/examples/agent-tool-call.workflow.json --quality showcase --json
node archify/bin/archify.mjs deliver workflow archify/examples/agent-tool-call.workflow.json /tmp/agent-workflow.html --quality showcase --json
node archify/bin/archify.mjs visual-check /tmp/agent-workflow.html --json

validate 把 schema、renderer 和最终 HTML 检查串起来；标准档与 showcase 档有不同的约束强度。Showcase 要求完整 9 项 artifact checks、零组合错误和零警告。返回的诊断带有 code、subject、evidence 和 supported fixes，适合 Agent 针对具体问题修复，不需要凭感觉重画整张图。

deliver 会读取输入字节并制作与目标文件同目录的私有候选，只有 renderer 与 artifact checker 全部通过才原子替换目标。失败会留下此前可信的文件，不把半成品覆盖上去；JSON 回执包含规格与产物的 SHA-256 和字节数。回执证明的是字节身份和自动检查通过，不证明图在视觉上好读，也不证明图描述了真实生产系统。

visual-check 再调用本机 Chrome/Chromium 做多个桌面尺寸的溢出测量，并生成浅色/深色截图和回执。自动化结果的 visualReview 仍是 pending；人工看过实际画面后才能说视觉审阅通过。浏览器不可用时该步骤可以标记 skipped，而不能把未截图包装成通过。窄屏以不溢出为目标，项目没有声称窄屏是完整的移动阅读产品。

四、交互探索只回答“作者写了什么”

生成的单文件 Viewer 不只是静态图片。它支持深浅主题、查找节点、语义 Lens、聚焦与可复制链接、按作者关系探查路径，以及有界的章节/故事阅读；还能导出 PNG、JPEG、WebP、SVG、WebM 和用于分享的卡片。默认保持静态阅读，需要演示时才由读者显式开启有限的路径动态。

这里有一条重要的认识边界：路径探查只沿作者写入的有向关系走；上下游 Reach 只呈现图里已定义的关系。它不会从画面距离推断调用，不代表真实流量、因果关系、事故影响面或改动风险。分享卡片是沟通材料，不代替通过校验的 HTML 和真实视觉审阅。

Architecture Delta 同样以两份结构化快照为输入，生成 Before、Delta、After，区分显式新增、删除、语义变化、移动和重路由。它是作者声明的差异，不会自行推演“这次变更会不会导致线上故障”，也不会把只读比较伪装成合并安全结论。

五、源码证据与 Agent 的责任边界

当图必须对应真实仓库时，Skill 指引 Agent 检查入口、运行时边界、存储、传输和部署配置，并可通过 --repo-root 记录来源仓库、revision 与引用数。这个做法让读者有机会从图返回到经过版本绑定的源码依据，但仍依赖 Agent 正确读代码，也依赖操作者选对仓库和 revision。它不等于全量程序分析、运行时追踪或生产环境探测。

实操时应限制源代码检查范围，不要把凭证、.env、客户数据、内部主机名或未公开业务流程放进图、截图和分享卡片。发布前逐项确认节点、箭头方向、协议、同步/异步语义、信任边界和外部服务；尤其是把内部仓库转换成公开 HTML 时，不能因为它有“证据回链”就默认可以公开。

六、安装、运行和维护

公开 README 给出的 Skill 安装示例是 npx skills add tt-a1i/archify -g，仓库页面所有者则显示为 cdyforever/archify。这两个标识在当前快照中不一致，安装前要确认它们是否指向相同代码和预期版本，不要盲目把示例命令当作仓库身份的证明。项目根包声明 MIT，但 archify/package.json 同时标记 private: true；当前交付路线是 Skill/ZIP 与 GitHub Release，不应把它理解成已经发布到 npm registry 的普通依赖包。

运行时要求 Node.js 18 或更高版本。开发检查需要在 archify/ 目录执行 npm ci 和 npm test；CI 的发布工作流使用 Node 22，除完整测试外还运行 WebM 帧烟测、构建 ZIP、对确切 ZIP 做无依赖安装冒烟测试，并检查压缩包与提交版本完全一致。81 个测试文件是维护信号，不是每项使用场景都已证明正确的保证；用户仍应对自己的图做事实与视觉审查。

cd archify
npm ci
npm test
node bin/archify.mjs doctor

若只是日常做图，不需要先安装开发依赖；使用已发布 Skill/归档包即可。需要源码调试或贡献时再跑测试。浏览器截图检查要求本机有 Chrome/Chromium；WebM 烟测还需要相应解码器，所以在没有这些工具的环境里应如实报告跳过原因。

七、什么时候值得用，什么时候不该迷信它

适合用在：把经过代码审查的服务拓扑变成便于新人阅读的资料；评审 API 或 Agent 工具调用顺序；对比架构 JSON 的显式变化；把复杂数据流做成可搜索、可分享的独立页面；要求 Agent 按结构化诊断收敛修图。

不适合直接承担：自动发现所有服务或生产依赖；证明架构图与部署实时一致；做事故爆炸半径、可靠性或安全风险评估；替代代码审查、架构评审和运行监控；未经人工检查就公开内部仓库地图。

最可靠的使用习惯是把图当作“有出处、可校验的作者声明”：先定义范围和证据，再选图型；先确保每条边都能说明来源，再追求展示效果；把自动结构检查与人工事实/视觉审阅分别记录。这样工具提供的是可重复的交付流程，而不是看起来专业就自动为真的答案。

源仓库与核验记录

本文依据公开仓库中的中文 README、CLI 入口、五类 schema/renderer 清单、作者与交付契约、测试目录及 Release 工作流重新整理。实现细节和版本会继续变化，完整代码、变更记录与原始文件以 cdyforever/archify 源仓库 为准。

Live Notes

读者弹幕

留言提交后会先进入审核，审核通过后对其他读者公开。