Archify:让编码 agent 交付可验证的交互式架构图

把「讲清楚」变成一道可验收的工序

Archify 是一个 agent skill：给它一段自然语言描述、一个问题，或者一张粘贴进来的 Mermaid 图，它产出的不是图片，而是一个自包含的可交互 HTML——可以本地打开、可以发给同事、可以在浏览器里探索节点与路径，也可以导出成 PNG、JPEG、WebP、SVG 甚至 WebM。仓库对自己的定位很克制：它不是通用画图编辑器，也不是 Mermaid 的一套皮肤，而是「把技术意图变成沟通工件」的生成与验收流水线。产物默认是单个 HTML 文件，源码是可编辑的 typed JSON，二次开发直接在这两者之上做。

安装只有一条命令 npx skills add tt-a1i/archify -g，官方适配 Cursor、Claude Code、Codex CLI 与 OpenCode。许可证 MIT，收录时版本 v3.0.1（2026-09-28），代码血缘上源自 Cocoon-AI/architecture-diagram-generator（MIT v1.0）。社区侧的信号包括 GitHub Trending 周榜全语言第一（作者 2026-09-01 公布截图）、量子位的项目报道与开发者专访，以及 midudev 等开发者的公开分享。

五种图，一套 typed JSON IR

Archify 把「图」收敛成五种语义类型，每种都有自己的 JSON schema 与 showcase 示例：architecture（组件、服务、存储与边界）、workflow（CI/CD、审批、工具调用、runbook）、sequence（调用链、缓存回退、鉴权、异步轨迹）、dataflow（管线、血缘、敏感数据边界）、lifecycle（状态、重试、等待与终态）。选型不确定时不要猜，仓库给了一个零依赖 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

Mermaid 是输入而不是模板：flowchart 读成 workflow（组件地图则读成 architecture）、sequenceDiagram 读成 sequence、stateDiagram 读成 lifecycle，读的是拓扑与语义，不机械搬运 Mermaid 的样式。布局判断刻意交给 agent——层级、间距、路由、强调由模型决定，共享的自动端点则确定性地铺开，避免把一堆箭头堆在同一个中点上。每次请求落在独立文件夹 .archify/<type>-<slug>-<时间戳>/ 里，candidate.json 与产物 HTML 同目录，修复重跑复用同一文件夹，历史版本不被覆盖。

finalize：四道门、一张回执、非零即失败

整个交付链路被压成一条命令。finalize 依次跑 showcase 校验、渲染交付、严格 provenance 检查与真实浏览器检查，任何一道门不过就停在原地；退出码非零永远不算成功，SKILL.md 把这句话写成了硬规则。通过时产出一张紧凑回执：稳定的规则码、精确的失败 subject、测量到的证据、以及仅受支持的修复控件——给 agent 的不是 Node 堆栈，也不是「再试一次」的模糊建议。修复上限两轮，超出就要回到语义层面重想。

flowchart LR
    A["candidate.json"] --> B["validate: schema + 布局规则"]
    B --> C["deliver: 同目录渲染候选"]
    C --> D["check: 严格 provenance"]
    D --> E["browser-check: 真实浏览器"]
    E --> F["回执: 规则码 + subject + 证据 + 修复控件"]
    B -->|非零| G["停在原地, 原子替换不发生"]
    E -->|通过| H["原子替换目标 HTML"]

只有通过的候选才会原子替换目标文件，所以上一张验证过的图永远不会被半成品顶掉。可选的 preview 是 loopback-only 的桌面模式：在 127.0.0.1 随机端口监听一个 JSON 文件，只在最新候选通过全部门禁后刷新，保存不完整或非法时保留上一张好图。失败回执里的 diagnostics[] 只允许按各自 subject 的 supportedFixes 修，视觉审查则单独成项，不与自动门禁混报。

真相优先：交互只复用作者写下的拓扑

查看器里的每个「聪明功能」都被同一条纪律约束：focus、上下游 reach、精确 route、角色 lens、故事线，全部复用 authored 的节点与关系，不发明拓扑、不声称运行时影响。Architecture 的可选 deployment-ownership profile 更是 fail closed：作者没写 owner、区域部署、私有库范围或命名 crossing，就直接不通过，绝不隐式推断，也绝不探测线上基础设施。分享卡同样命名自己的 scope——Route Share Card 与 Reach Share Card 都是 1200×630，且保留全图作为上下文，不让一条路径冒充整张架构。

查看器本身是一套键盘驱动的探索界面：? 打开事实性图例、/ 语义搜索节点、R 追踪有向路由、L 比较角色、M 总览雷达、F 演讲台、S 循环视觉风格、T 切换明暗主题、E 导出。深链可恢复 #focus=、#reach=upstream|downstream、#route=a~b、#lens=，发给别人的链接打开就是同一条读法。动效是 opt-in 的、有限的、尊重 prefers-reduced-motion，且永远不进入 canonical 导出；meta.locale 内置 en 与 zh-CN，其它语言走 meta.translations 提供「消息键 → 译文」，缺失时回落英文并明示回落。

源码证据与 Architecture Delta

当一张图必须反映真实代码时，Archify 要求证据而不是印象：Evidence-backed 的 Architecture 节点会标 SRC n，点开是 Git 校验过的文件与行号范围，并且钉在一个公开 commit 上——读者能核对，也能看见证据的保质期。普通产物则保持无源码，不把「我读过代码」当成默认装饰。

面向设计与 PR 评审的是 Architecture Delta：node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json，把验证过的 Before / Delta / After 三张快照并排呈现，附机器回执；可以选一个 authored 变更，或播放一次有限的、仅查看器侧的 Review。它明确不推断影响面、风险或合并安全——对比只陈述 authored 事实的增删改移。

自测：普通模型的下限，和修复轮次的账

仓库内置两套基准，口径都写得很保守。ordinary-model-floor 量「普通模型的首过可用率」：pi agent 跑 3 个模型 × 5 个 case 共 15 条 attempt-1 候选，固定在 commit 66414c7 与同一个 skill SHA-256 上；校准后的 verifier 报 10/15 首过可用，5 条是确定性视觉质量失败，语义与操作失败为零。更诚实的是下一段：换用当前更严格的 verifier 后，原矩阵与修复后矩阵同为 8/15（MiniMax 4/5、DeepSeek 2/5、Qwen 2/5），README 直接写明「单一样本不证明整体提升」。

repair-rounds 量的是反馈循环里的成本：向 checked-in 示例注入 8 类确定性缺陷（meta-missing-output、node-invalid-type、node-long-label、node-duplicate-id、edge-dangling-target、viewbox-oversized、title-overflow、subtitle-overflow），统计修复轮次、首轮披露率、首检出阶段、迟发现率与可行动性。其中两个标题溢出类用不可断行字符串构造，只能靠真实浏览器布局测出来——这正是 browser-check 那道门存在的理由。线上 Proof Lab 收录全部 11 个场景的 JSON 源与验证回执，读者可以逐条复核。

上手与边界

没有 shell 的环境也有兜底：把 architecture SVG 手工放进 assets/template.html，用 CSS 语义类而非内联颜色，并遵守视觉审查契约。更新提示被做进 finalize 回执（bounded 地 GET 一次 manifest，可用 ARCHIFY_UPDATE_CHECK_DISABLED=1 关闭），skill 被明确禁止自行安装或更新——提醒是信息，不是动作。

边界同样清楚：静态输出是默认，动效要用户点名；视觉审查是可选证据，没做就不能在回执里声称做过；它不替代画图工具的自由摆放，也不给 Mermaid 做美容。对需要把架构、流程、时序讲给团队或评审听的工程团队，这套「生成—校验—浏览器验证—回执」的工序，比再画一张会过期的截图更接近可交付物。