这篇文章只回答一个问题：当你不缺“画图语法”，缺的是“让 Agent 读懂描述或代码仓库，并产出一张别人愿意看完、能点开探索的图”时，开源 Agent 技能 Archify 到底能做什么、不能做什么。
说明：我是 Archify（Apache-2.0 开源）的作者。当前线上稳定版为
v3.2.0（支持 10 种图型与一页式解答 Explainer），完整机器可读事实以 archify.si/llms-full.t… 和 GitHub Release 为准。本文所有成品链接均可直接免注册打开体验。
一、先看真实成品，再看能力
不用装任何东西，直接在浏览器打开下面几个真实生成物，重点看三件事：图是否能点击聚焦、连线是否清晰可读、文字结论是否和源码证据对得上：
- 一页式解答（Explainer）：第一次访问 HTTPS，发出请求前发生了什么
- 一页式解答（Explainer）：P99 从 80ms 暴涨到 600ms、平均值不动是什么原因
- 源码实证一页式解答：finalize 失败时怎么保住旧产物（绑定仓库固定提交）
- 源码实证系统架构案例：MCO 多 Agent 编排运行时架构
- 成品画廊（含非代码的日常生活决策图）：archify.si/gallery
二、它到底怎么工作（为什么不是“让大模型再画一次试试”）
传统让大模型直出 Mermaid 或 SVG 的痛点不在于语法，而在于节点一多，布局重叠、连线乱穿、静态图无法聚焦某条链路。
Archify 把整个链路拆成了确定性流水线：
- Agent 读取输入：自然语言描述、实施计划、已有 Mermaid 草稿，或本地代码仓（可绑定固定 Git commit）。
- 编写结构化中间表示：
- 画图场景：Agent 编写严格受 Schema 约束的 类型化 JSON IR；
- 一页式解答场景（Explainer）：Agent 编写
.archify.md结构化草稿（结论先行 + 分面板佐证）。
- 执行
archify finalize门禁：- JSON Schema / 结构校验 → 确定性几何布局与连线路由 → 真实无头浏览器（Chrome）渲染与碰撞检查 → 输出零运行时依赖的单文件 HTML。
- 双产物交付：交付独立
.html成品 + 源稿（JSON IR 或.archify.md）。HTML 发给同事用浏览器就能离线打开；源稿直接进 Git 仓库做版本管理。
校验边界声明：
finalize校验的是生成物的结构、几何布局与可渲染性，不证明业务事实本身为真，也不自动证明线上运行时行为与图完全一致。涉及源码与数据时，需要作者或 Agent 绑定真实提交与数据来源。
三、十种图型怎么选
选型原则只有一条：先确定读者要回答什么问题，再选图型，不要为了“看起来复杂”上来就画系统架构图。
| 读者要回答的问题 | 图型标识 | 典型工程场景 |
|---|---|---|
| 系统由哪些组件组成，谁依赖谁？ | architecture | 服务边界、职责划分、依赖方向审阅 |
| 一个流程怎么走，在哪里分支或回退？ | workflow | CI/CD 发布流、审批流、异常兜底流程 |
| 谁在什么顺序给谁发了什么消息？ | sequence | 登录鉴权、下单支付、异步回调时序 |
| 数据从哪来、经过什么转换、落到哪？ | dataflow | 埋点管道、ETL 链路、计费结算流向 |
| 一个实体有哪些状态、靠什么事件流转？ | lifecycle | 订单状态机、工单流转、Agent 运行态 |
| 表和表之间怎么关联、主外键是什么？ | erd | 数据库 Schema 评审、模型重构 |
| 类型、接口、字段与继承/组合关系？ | class | 核心领域模型、SDK 接口结构 |
| 层级拆解或树状归属是什么样？ | tree | 仓库目录职责树、组织结构、故障决策树 |
| 事件按什么时间轴先后发生？ | timeline | 线上故障复盘时间线、版本演进里程碑 |
| 总耗时或总预算被哪些阶段消耗了？ | waterfall | 请求尾延迟拆解、构建耗时归因、成本分解 |
而当你的问题是 “为什么会这样 / 该怎么理解这件事”（需要结论 + 表格 + 代码片段 + 内嵌校验图联动阅读）时，直接让 Agent 用 Explainer（一页式解答） 模式即可。
四、安装与第一次运行
支持 Claude Code、Codex CLI、Cursor、Gemini CLI、OpenCode、GitHub Copilot 等主流支持 SKILL.md 的 Coding Agent（运行渲染与校验需本地装有 Node.js）：
Claude Code（全局复制安装）：
npx -y skills@latest add https://archify.si --skill archify --agent claude-code --global --copy --yes
Codex CLI：
npx -y skills@latest add https://archify.si --skill archify --agent codex --global --copy --yes
(注：若只需安装在当前项目，去掉 --global 在项目根目录执行即可；请勿在 skills add 上使用 -g 短参数。)
安装完成后，可以先跑一个最小调用时序图试手：
用 Archify 画一张 sequence 图：浏览器 → CDN → API 网关 → 鉴权服务 → 订单服务 → MySQL。
标出同步调用与超时重试，并给每条消息写一句职责说明。
再试一个一页式解答（观察它在缺少实测数据时是否诚实标注，而不是乱编图表数字）：
用 Archify 生成一页式解答：为什么接口平均耗时正常但 P99 暴涨？
先给结论，再按排队、连接池、慢查询、重试放大四个面板展开；没有实测数据的地方明确写“待补采样数据”，不要编造数字。
五、和 Mermaid / Excalidraw / PlantUML / D2 的诚实对比
| 维度 | Archify | Mermaid | Excalidraw | PlantUML / D2 |
|---|---|---|---|---|
| 主要交付物 | 可交互单文件 HTML + 结构化源稿 | Markdown 代码块内嵌图 | 手绘风格画布 | 文本定义编译出的静态图 |
| 工作方式 | Coding Agent 读描述/仓库生成并过本地门禁 | 手写或 LLM 直出文本语法 | 人手拖拽白板共创 | 工程师编写领域特定语言（DSL） |
| 布局与可读性保障 | JSON Schema + 确定性布局路由 + 浏览器检查 | 由宿主渲染器自动排布 | 人工摆放对齐 | 由编译器引擎排布 |
| 读者交互能力 | 节点聚焦、上下游追踪、路径高亮、深浅主题、导出 | 基础查看为主 | 白板画布交互 | 静态 SVG/PNG 为主 |
| 多人实时白板 | 不支持（非托管服务） | 不支持 | 强 | 不支持 |
| 最适合场景 | 代码仓/复杂逻辑驱动的可审阅交付物与技术复盘 | 嵌在 README / PR 里的轻量小图 | 头脑风暴与实时共创 | 纯文本 Git diff 与 CI 流水线制图 |
什么时候不要选 Archify：
- 只需要在 GitHub
README.md或工单里内嵌一张十几节点的流程图：直接写 Mermaid 最省事，原生 Markdown 就能渲染，没必要生成独立 HTML 文件。 - 团队开会要边聊边拖框改线：用 Excalidraw 或白板工具。Archify 不是所见即所得（WYSIWYG）拖拽编辑器。
- 团队已有成熟的文本 DSL + CI 渲染管线：继续用 PlantUML 或 D2。
- 需要带权限和云存储的托管团队空间：Archify 只在本地生成静态文件，不提供云端托管平台。
六、已知边界与使用建议
- 大仓库需要圈定范围：它不是“丢一个百万行仓库就全自动读懂一切”的黑盒提取器；指定模块目录、入口文件或固定 commit，产出的图才真正准确可信。
- Mermaid 迁移是语义重写而非无损编译：把已有 Mermaid 交给 Archify 时，Agent 会按语义重写为类型化 JSON IR，复杂特化语法需人工核对。
- 导出能力视本地环境而定：交互式 HTML 任何现代浏览器都能直接看；额外导出 PNG / SVG / WebM / PDF 依赖本地浏览器与工具链环境。
七、相关链接
- 开源仓库：github.com/tt-a1i/arch…
- 工具选型与对比矩阵：archify.si/zh/compare
- 快速开始与安装切换器：archify.si/zh/start
- 完整机器可读文档（LLM / RAG 事实源）：archify.si/llms-full.t…
