用 AI 画架构图这件事，难点从来不在"画不出来"，而在"画出来的东西能不能被信任"。Archify 是一个走 Agent-first 路线的开源技能（GitHub 仓库 tt-a1i/archify，星标 81,659，MIT 许可），它把"想理解、规划或分享的事"变成可以探索、修改和分享的交互式 HTML 图。它最值得写清楚的，不是它支持几种图型，而是它在工程上做了一次明确取舍：拒绝通用自动布局，改用 Typed JSON IR + 原子交付门禁。
通用自动布局的两个死结
大多数"AI 画图"的工具链是这样：模型输出 Mermaid 或一段 SVG，渲染器套一个通用布局算法，把节点平均铺开。这条路在小图上没问题，节点一多就暴露两个死结。
第一个死结是语义缺失。 通用布局算法只知道节点和边，不知道哪条路径是"主路径"、哪个组件是"外部依赖"、哪条线是"信任边界"。于是画出来的图在拓扑上没错，在阅读顺序上全错——读者看不出作者想让他先看哪里。
第二个死结是每次重跑结果都不一样。 布局算法带随机性时，同一份源文件两次渲染可能给出两张不同的图，这直接破坏了"可复核"这个前提。
Archify 的官方文档把这个取舍写得很直白：用布局判断代替通用自动布局——由 Agent 根据故事来选择层级、留白、线路和强调关系；共享的自动端点会确定性展开，不再让多支箭头堆在同一个中点。换句话说，布局不是渲染器的随机产物，而是被作者显式写进源文件的一次判断。
Typed JSON IR 换来了什么
取舍的落点就是 Typed JSON IR：每一种 Renderer 模式都有 Schema 和可复现的源文件。它的价值在三个地方体现。
其一，失败可定位。 当 Agent 生成的结构不合法，报错不是一句"渲染失败"，而是机器可读的 JSON，指出准确的局部修复位置。这对自动化流程是决定性的——Agent 可以读着报错去改那一处，而不是把整张图推倒重来。官方文档把这条能力描述为"失败也有结构化修复回执"：validate --json 和 deliver --json 会返回稳定规则码、准确对象、测量证据和真正支持的修复旋钮，不让 Agent 从 Node 堆栈或自由文本里猜。
其二，迭代不互相干扰。 因为源文件是结构化的，Agent 修改其中一处时不会动到无关结构。文档里的例子是：继续说"增加 Redis、把鉴权移到左侧、突出回滚路径"，Archify 会保留 Typed Source，只修改相关部分。
其三，交付前有门禁。 这是它最有工程味的一条：原子交付前校验——Schema、布局、HTML/SVG、线路、以及标签到其他路径的净空检查必须全部通过，Showcase 成品才会替换上一份可信结果。所谓"原子替换"，指通过门禁的结果才整体替换目标文件，而不是边写边覆盖。
预览与交付的边界划得很清
Archify 的预览模式有一个刻意的限制：它是显式启用的桌面创作模式，不是默认后台服务。它只在随机端口监听 127.0.0.1，只观察指定的那一个 JSON 源文件，失败时保留上一份验证输出，用 Ctrl-C 停止。生成的 HTML 也不会携带 Preview Runtime。
交付侧同理：deliver --open 默认关闭，且只在验证成品原子提交之后才执行；如果系统无法打开，交付仍然算成功，JSON 只写 stdout，stderr 给出可手动打开的绝对路径。
这种"宁可少做一步、也不让产物不可信"的设计，和它明确列出的非目标是一致的：自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不在产品范围内。它不打算成为通用绘图编辑器，文档里有一句话把这个边界说得最清楚——"Archify 不是通用绘图编辑器，也不是 Mermaid 主题；它负责把技术意图变成可交流的成品"。
三种默认值和一条本地化边界
源文件里的 meta 段决定成品的表现形态：
{
"meta": {
"locale": "zh-CN",
"animation": "trace",
"visual_preset": "signal-flow"
}
}这里有三条容易被忽略的默认行为。不设置 animation 时结果完全静态——不是因为功能缺失，而是默认值就是静态。classic 始终是默认视觉预设；设计评审、发布说明和技术文档可以显式选择 editorial，获得暖纸张与深墨色的编辑风格，而几何完全不变。meta.locale 的机器翻译范围是有限的：en 与 zh-CN 已内置，其他语言需要同时提供 meta.translations，否则渲染器回退英文并在 stderr 中说明；而作者编写的标题、节点、关系和卡片不会被机器翻译。
在 DeepSeek Harness 里怎么用
DSH 侧的接入是社区集成、需要显式启用：
dsh plugin --profile web add @tt-a1i/archify-dsh站点把它标注为面向开发者预览版 @deepseek-ai/dsh@0.1.2-rc.1 的社区集成，不是 DeepSeek 官方产品，Node 要求 ^22.19.0 || >=24.0.0。目前本站已在 dsh 0.2.0-rc.2 下真实安装成功（L4 真实安装）。需要留意的是 Agent 切换器只为 cursor、codex、claude-code 和 opencode 生成命令，DSH 不在切换器里，所以必须像上面这样显式写命令。
总结
Archify 的核心取舍可以一句话概括：把布局与语义的判断权交给作者，把可复现性和校验交给工程。Typed JSON IR 让失败可定位、迭代不越界，原子交付门禁让"半写入"永远不会顶掉上一份可信成品。想对照同类插件的中文清单与安装形态见 DeepSeek Harness Hub 插件清单。
适合与不适合
适合：需要把系统结构讲给团队看的工程师；做设计评审或 PR 评审、想要 Before / Delta / After 机器回执的人；把架构图当交付物而不是草稿的项目；已经用 Claude Code、Codex CLI、opencode 或 DSH 的 Agent-first 工作流。
不适合：只想随手画草图、不关心可复现的人；需要的是 WYSIWYG 拖拽编辑器的人；依赖 Mermaid 语法做 CI 渲染、不打算换工具链的团队；以及不接受"必须让 Agent 参与生成"这一前提的用户——它没有"打开就能拖"的路径。
标签：Archify、DeepSeek Harness、Typed JSON IR、架构图、原子交付
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。