llp

如果你经常让 AI 画架构图，却得到一堆对不上代码、难分享、难评审的「示意图」，Archify 值得一试。

它是一个面向 Cursor / Claude Code / Codex / OpenCode 的 Agent Skill：你在对话里描述系统或让 Agent 读仓库，它产出带类型约束的 JSON IR，再确定性编译成可交互的自包含 HTML（附带 PNG / SVG / WebM 等导出）。不是换皮 Mermaid，而是「可验证、可分享」的技术地图。

仓库：https://github.com/tt-a1i/archify
官网：https://tt-a1i.github.io/archify/

它解决什么问题

常见痛点：

• 手画图慢，改一次布局崩一次
• Mermaid 适合文档，不适合「对着仓库讲清楚主路径」
• AI 自由发挥容易编造节点、边和运行时影响

Archify 的默认姿势是：

1. Agent 生成带 schema 的 JSON
2. 本地校验全部通过才交付展示件
3. 结果是一个 HTML 单文件：可打开、可演示、可贴进 PR / README

上图来自官方 Proof Lab 的真实产物，不是产品假图。

安装（Cursor）

全局安装一条命令即可：

npx skills add tt-a1i/archify -g

想明确指定 Cursor、非交互安装：

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

官方也提供「按 Agent 一键生成命令」的入口：
https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture

安装后，在 Cursor 对话里直接说「用 Archify …」即可触发。

可选：设置 ARCHIFY_UPDATE_CHECK_DISABLED=1 可关闭更新提醒网络请求。默认更新检查不会上传项目内容或账号信息。

三分钟上手：从自然语言开画

不需要仓库。 在 Cursor 里直接说：

用 Archify 画：Browser -> API -> Redis 缓存 -> PostgreSQL 回退。

或者更完整一点：

Use Archify to draw a high-level runtime architecture:
Browser -> API Gateway -> Auth Service -> Order Service -> Redis cache -> PostgreSQL.
Highlight the primary happy path, put secondary details in cards, keep 8–12 core components.

你会得到一个可打开的 HTML。之后继续用自然语言迭代，例如：

• 加 Redis
• 把 Auth 挪到左边
• 高亮回滚路径
• 切到深色主题

五种图，怎么选

拿不准？用官方场景向导：https://tt-a1i.github.io/archify/guide.html
或 CLI：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"

Workflow

Sequence

Data Flow

Lifecycle

Architecture 还支持可选的 deployment-ownership 画像：缺作者声明的 owner / 区域 / 私有库范围时会 fail-closed，不会偷偷去扫你的线上基础设施。

主题、演示与导出

同一张图可一键切深色 / 浅色：

Dark	Light

导出菜单可复制 PNG 到剪贴板，或下载静态 / 动图格式；Copy Share Card 适合 README、发版说明、社交封面（1200×630）。

交互也按「作者写过的事实」来，而不是 AI 现场编拓扑：

• 播放一段有限的 Guided Story
• 查看某条 authored Route
• 比较语义角色（如 backend vs database）

进阶：从真实仓库映射

打开仓库后可以这样问：

分析这个仓库，然后用 Archify 画高阶 runtime architecture。
只保留 8–12 个核心组件，画一条主路径，外部依赖和信任边界写清楚。
细节放进卡片，不要为了「看起来丰富」乱加边。

官方有一份从公开仓库 mco-org/mco 映射出来的案例：

在线打开：https://tt-a1i.github.io/archify/cases/mco-runtime.architecture.html?theme=dark&present=1#view=dispatch-path

需要源码证据时，Evidence-backed Architecture 节点会标 SRC n，并打开钉在某个公开 commit 上的文件与行号；普通图默认不绑源码，保持干净。

PR / 设计评审还可以用 Architecture Delta：对比 Before / Delta / After 两个校验过的快照，给出 added / removed / changed / moved / rerouted 的机器可读收据，不推断风险或是否可合并。

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

推荐工作流（我怎么用）

1. 先定图种：架构拓扑用 Architecture；接口时序用 Sequence；流水线用 Data Flow。
2. 先窄后宽：第一版只要主路径，细节进卡片。
3. 校验不过就修 JSON：看 validate --json / deliver --json 的 rule code，按收据修，而不是盲目重画。
4. 分享 HTML：邮件、飞书、PR 评论直接挂单文件；需要封面再导出 Share Card。
5. 评审用 Delta：合并前对比两版 IR，避免「口头说改了」却对不上图。

更多可交互样例看 Proof Lab：https://tt-a1i.github.io/archify/gallery.html

常见问题

Q：和 Mermaid 什么关系？
A：不是 Mermaid 主题。Archify 强调 typed IR、校验门禁、自包含 HTML 与可演示交互。

Q：会不会编造线上影响？
A：Reach / Route / Story 只复用作者写过的节点与关系，不宣称 runtime impact。Deployment ownership 也不会隐式探测云账号。

Q：必须装在全局吗？
A：不必须。可用 npx skills use tt-a1i/archify@archify --agent … 临时试用；也支持项目级安装。

Q：支持哪些 Agent？
A：Cursor、Claude Code、Codex、OpenCode；Raven 走 ZIP 手动安装到 ~/.raven/workspace/skills/archify。

小结

Archify 把「让 AI 画图」变成「生成可校验、可迭代、可分享的技术地图」。对需要写设计文档、做 PR 架构评审、或给同事演示系统主路径的人特别友好。

• GitHub：https://github.com/tt-a1i/archify
• 文档站：https://tt-a1i.github.io/archify/
• 场景向导：https://tt-a1i.github.io/archify/guide.html
• Proof Lab：https://tt-a1i.github.io/archify/gallery.html

许可证：MIT。图片与样例来自 Archify 官方仓库与文档站点，版权归属原作者 tt-a1i。