Archify 教程：从描述到经过验证的交互式架构图

Archify 不是在线画板。它是一项供编码代理调用的 skill：代理先写类型化 JSON，仓库里的规则检查节点、连线和版面，再输出一个可离线打开的交互式 HTML。当前覆盖架构、工作流、时序、数据流和生命周期五类图。

1. 先理解生成链路

一次完整流程是：描述目标或提供仓库证据，代理选择图类型并写 JSON，验证器检查 schema 与质量规则，渲染器生成自包含 HTML，最后才交付正式文件。图中的关系仍来自代理写入的事实。验证器不会连接真实基础设施，也不会判断一项代码修改是否安全。

官方 README建议首张架构图只放 8 至 12 个核心组件、一条主路径、外部依赖和信任边界。细节放说明卡片，通常比继续加线更容易读。

2. 安装和最小试用

全局安装使用：

npx skills add tt-a1i/archify -g

只想在 Codex 中临时试用，可运行：

npx skills use tt-a1i/archify@archify --agent codex

然后给出一个有明确方向的请求，例如：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

这个例子不需要代码仓库。如果要求它描述已有系统，应先打开仓库，并让代理给每个重要组件和边提供源码依据。

3. 从源码使用验证与交付命令

官方仓库提供零依赖 Node CLI。克隆仓库后，可以按下面的顺序理解流程：

node bin/archify.mjs doctor
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

preview 用来查看候选，deliver 才写正式目标。官方说明 deliver 会先生成同目录候选并验证，通过后原子替换目标。这能防止半成品覆盖现有图，但不能替你确认业务事实。

4. 输出和边界

查看器支持明暗主题、节点搜索、路径和上下游关系追踪，也能导出 PNG、SVG、WebM 及 1200×630 分享卡片。Architecture Delta 可以对照 Before、Delta 和 After 三份已验证数据；它只显示作者写入的变化，不会推断线上影响、风险或是否可合并。

当前明确不支持自动解析 Mermaid，也不是通用自动布局器；项目没有托管分享平台和所见即所得编辑器。布局质量仍取决于代理的结构选择和你的复核。

5. 更新检查与商业化判断

Archify 可请求固定的稳定版 manifest 来提示更新，不自动下载或安装。官方说明请求不携带版本、代理、项目数据、提示词、账号、设备 ID 或 ETag；服务器仍能看到常规的 IP 和时间。要完全关闭请求和本地提醒状态写入，设置：

export ARCHIFY_UPDATE_CHECK_DISABLED=1

仓库以 MIT 发布，安装和生成流程没有充值、订阅配额分发或付费下载。

6. 与 Mermaid 对比

Mermaid用接近 Markdown 的文本语法渲染 20 多种图，源码短，适合版本控制，并能在 GitHub Markdown 里直接显示。Archify 使用代理生成的类型化 JSON，把 schema 验证、交互式查看器和验证后交付串起来。

README 里的一张简单流程图，Mermaid 往往更直接。若团队需要追踪路径、切换视图、导出分享卡片，并希望代理产图先经过结构检查，再评估 Archify。

常见问题