Archify：把系统描述变成可验证的交互式架构图

当团队需要解释一次缓存回源、审批流程或服务边界时，纯文本容易丢失关系，普通绘图工具又很难让图和源码保持一致。Archify 把这项绘图任务放进 Agent 对话：Agent 负责把描述整理成 Typed JSON IR，仓库里的 Schema、Renderer 和 Validator 再把 JSON IR 确定性地编译成一个可分享的 HTML/SVG 成品。生成结果可以搜索节点、追踪作者写出的路径、切换主题，并导出 PNG、SVG、WebM 或 1200×630 分享卡片。

Archify 不是一个在线白板，也不是给 Mermaid 换皮肤的主题。Archify 更适合“需要一张能复核、能迭代、能带走的技术图”的场景：合并前比较架构快照、给新成员讲清一次请求链路、把数据血缘和敏感边界放进评审材料。仓库当前是单一复杂 Skill，Skill 包之外的 Renderer、Schema、示例和契约共同构成可执行的支持层。

GitHub 仓库信息

信息	内容
项目标题	Archify
项目描述	面向 Agent 的技能，用于生成漂亮、可验证的架构、工作流、时序、数据流和生命周期图，并输出带交互和动效的独立 HTML。
GitHub 仓库	tt-a1i/archify
官网地址	tt-a1i.github.io/archify
主要开发语言	JavaScript 73.03%、HTML 26.8%、Mermaid 0.09%、Shell 0.08%
开源许可证	MIT
最近代码更新	2026-09-14（GitHub pushed_at；核对日期：2026-09-14）

仓库 README 的当前开发版本为 v2.17.0-dev.1，最近公开 Release 是 v2.16.0。两者不要混写：前者描述 main 上的开发状态，后者是 GitHub Release 页面上可回溯的发布标签。

一张 Skill，五种图表

公开 Skill 只有 archify 一个；archify/ 目录下同时包含命令入口、五套 JSON Schema、渲染器、示例、测试和四份参考契约。选择图表时先决定要解释的关系，再决定视觉预设：

Skill 的支持资源各有边界：references/ 放作者、交付和 Viewer Runtime 契约；schemas/ 定义 Typed JSON IR；renderers/ 负责五类图和共享诊断；bin/ 暴露 guide、validate、preview、deliver 等命令；scripts/ 生成或检查 Validator、品牌标记和示例；assets/template.html 提供独立 Viewer 的 HTML 外壳。当前快照没有单独的 templates/ 目录，也没有额外的 instructions 文件；examples/ 是字段形状和阅读结果的起点，不能直接当作新系统的事实。

类型	适合回答的问题	Prompt 中至少写清
architecture	哪些组件协作，边界和外部依赖在哪里？	范围、核心组件、主要路径
workflow	一个流程怎样经过参与者、分支和异常？	参与者、顺序、分支、例外
sequence	一次调用按什么时间顺序发生？	调用方、被调用方、返回、时序
dataflow	数据从哪里来，经过什么转换，谁消费？	来源、转换、存储、边界
lifecycle	状态如何推进、重试、取消并结束？	状态、事件、重试、终态

例如“浏览器请求 Redis，未命中后回源 PostgreSQL”适合 sequence；“服务、数据库和信任边界的静态关系”适合 architecture；“Kafka Topic、消费者组和死信队列”更接近 dataflow。场景不清楚时，可以让 CLI 给出类型建议：

# 在仓库根目录执行；CLI 位于 archify/bin/
node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json

guide 只返回选型建议，不会替你虚构组件事实。真正的事实仍来自 Prompt、仓库源码或你提供的 Mermaid 拓扑。

安装和支持范围

Skill 的默认安装命令由 skills CLI 处理：

npx skills add tt-a1i/archify -g

不想写入全局目录，可以临时使用：

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

仓库 README 列出的主路径如下：

Agent 或环境	安装位置或方式	备注
Codex CLI	~/.agents/skills/ 或 .agents/skills/	完整 Renderer 与校验流程
Claude Code	~/.claude/skills/ 或 .claude/skills/	完整流程
Cursor	使用 skills add，或打开官方 Agent-aware quick start	支持全局和当前项目两种范围
OpenCode	~/.config/opencode/skills/、.opencode/skills/ 或 .agents/skills/	完整流程
Raven	解压 archify.zip 到 ~/.raven/workspace/skills	手动安装，不属于 Agent 切换器目标
DeepSeek Harness	dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0	社区集成，需显式启用，不是官方 DeepSeek 产品

包内 skill-release.json 把当前开发版本标为 2.17.0-dev.1，并指向固定的更新清单 URL。安装后的检查器只显示可选提醒，不会下载或安装更新；设置 ARCHIFY_UPDATE_CHECK_DISABLED=1 可关闭网络检查和提醒状态写入。卸载时删除对应 Agent 的 archify Skill 目录；DeepSeek Harness 使用 dsh plugin --profile web remove @tt-a1i/archify-dsh。

单一 Skill 的基础档案

archify/SKILL.md 的触发描述覆盖架构、基础设施、安全与网络拓扑、技术工作流、API 时序、数据管线、生命周期和 Mermaid 转换。输入可以是自然语言需求、粘贴的 flowchart/sequenceDiagram/stateDiagram，也可以是需要源码证据的公开代码库。运行时要求 Node.js 18 或更高版本；仓库包自带 Renderer、Schema 和 Validator，不需要在 Skill 目录内执行安装流程。

安装完成后，Agent 会在匹配这些任务时加载 SKILL.md，再按需读取一个模式 Schema、schemas/common.schema.json 和一个示例。普通制图不会自动读取 Viewer Runtime 参考；只有用户要求路径卡片、故事、动效、演示或深链接时才继续加载。以上是 README 与 SKILL.md 的文档声明，本文没有执行 Agent 的实际触发。

边界	行为与确认方式	证据等级
文件写入	作者先写候选 JSON；deliver 在目标同目录生成候选并原子替换最后一份通过检查的 HTML，属于明确的文件覆盖副作用	静态阅读 Skill 与交付契约
浏览器	visual-check 需要浏览器来采集已交付 HTML 的行为证据；不自动修改 HTML	文档声明，未运行
网络	更新检查器按退避策略访问固定 HTTPS manifest；设 ARCHIFY_UPDATE_CHECK_DISABLED=1 可关闭	README/发布清单声明
凭据、付费和消息	默认路径不要求账号、令牌、付费调用或发送消息；源码证据只打开用户指定的公开 revision	当前研究未发现调用，未做运行时验证
Git、发布和部署	Skill 不替用户提交 Git、推送、发布或部署；这些动作仍需用户在外部流程中决定	静态边界判断

仓库还包含 archify/THIRD_PARTY_NOTICES.md 和 assets/JetBrainsMono-OFL.txt。MIT 只覆盖 Archify 代码；再分发字体、生成的品牌标记或第三方素材时，应同时核对这些通知文件。

最短有效体验

下面的路径体现了 Archify 的核心价值，但本次仓库研究没有执行目标仓库代码，因此命令结果属于仓库文档和静态源码确认。先准备 Node.js 18 或更高版本，获取仓库后进入包含 bin/、schemas/ 和 examples/ 的 archify/ 子目录：

使用 archify 创建一张架构图：Browser -> API -> Redis；缓存未命中时 API -> PostgreSQL。
只保留四个节点，标出缓存回源关系，使用中文 authored content。

Agent 应在当前 archify/ 目录创建一个 web-app.architecture.json，随后用 CLI 做确定性校验和交付：

cd archify
node bin/archify.mjs validate architecture web-app.architecture.json --quality showcase --json
node bin/archify.mjs deliver architecture web-app.architecture.json /tmp/web-app.html --quality showcase --json

仓库契约声明，成功的 showcase 校验应包含 9 项 artifact checks、0 个 composition error 和 0 个 warning；这是文档预期，不是本次运行结果。deliver 会在目标同目录检查候选 HTML，通过后原子替换目标并给出规格文件和 HTML 的 SHA-256。失败时读取 JSON 中的 diagnostics[]、subject 和 supportedFixes，只修复被指出的对象，再重新校验。连续两轮修复没有降低错误数时，Skill 契约要求停止并报告诊断，而不是重写整张图。

需要浏览器行为证据时，在交付后、仍位于 archify/ 目录，再运行：

node bin/archify.mjs visual-check /tmp/web-app.html --json

deliver 证明确定性产物检查，visual-check 证明受限浏览器行为；两者都不等同于人工判断视觉是否舒服。本次文章没有运行这两个命令，也没有声称产物已经通过视觉复核。

这条路径的证据链可以按四步复述：自然语言触发 archify，Agent 按需加载模式 Schema 和示例，用户明确允许写入目标文件后执行 validate/deliver，最后用回执和可选 visual-check 验收。Skill 不会因为生成了图就自动获得 Git、发布或生产部署权限。

从 Typed JSON IR 到成品

Archify 的处理链可以拆成五个角色：Agent 生成输入，仓库中的 Schema 约束字段，模式专属 Renderer 负责布局和 SVG，Validator 负责交付门禁，Viewer Runtime 负责阅读交互。仓库文档建议新作者先读一个模式 Schema、schemas/common.schema.json 和一个对应示例，再写出候选 JSON；不要先阅读全部 Renderer 内部实现，也不要在文字里预先规划每个坐标。

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    Prompt[自然语言或 Mermaid 拓扑]
    Agent[Agent 生成 Typed JSON IR]
    Schema[模式 Schema + common schema]
    Renderer[Architecture / Workflow / Sequence / Dataflow / Lifecycle]
    Validator[validate --json]
    Deliver[deliver --json]
    HTML[独立 HTML / SVG / 导出文件]
    Prompt --> Agent --> Schema --> Renderer --> Validator --> Deliver --> HTML
    Validator -.失败诊断 subject / supportedFixes.-> Agent

以下约束直接改变结果是否可信：

• 新 Workflow 使用 schema_version: 2；只有需要保留旧固定几何时才继续使用 v1。
• 默认只写一条清晰主路径，最多约 12 个主要节点；低价值关系应删除，而不是靠更多线路控制挽救。
• meta.animation: "trace"、meta.visual_preset、工程画像和品牌徽标都是显式选项，静态图不会悄悄开启动态或基础设施推断。
• 搜索、上下游可达、路径探查、角色对比和故事播放都复用作者写入的节点与关系，不把图上的可达性解释成真实运行时影响。

因此，Archify 的“可验证”主要约束图的输入、布局和输出，不会自动证明业务拓扑本身正确。需要源码证据时，Architecture 节点可以绑定公开 commit、文件和行号；不提供证据时，结果仍是一张作者声明的设计图。

一个完整执行链怎么读

以 CI/CD 审批为例，用户触发 workflow 任务后，Agent 读取 schemas/workflow.schema.json 和一个示例，写出参与者、顺序、异常分支和边标签。validate 检查 Schema、布局、HTML/SVG、线路以及标签净空；如果某条边遮住无关节点，诊断会指出关系对象及可用修复旋钮。deliver 把同目录候选通过原子方式提交为最后一份可信 HTML，之后用户再决定是否允许 visual-check 在真实浏览器中收集有限行为证据。该链路来自 Skill 和交付契约的静态阅读，未执行目标仓库。

实时预览是另一条显式路径：

node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --no-open

Preview 只监听一个 JSON，在随机 127.0.0.1 端口上工作；候选无效时继续显示上一份通过验证的结果。Preview 不是默认后台服务，按 Ctrl-C 停止，也不会给生成 HTML 注入 Preview Runtime。需要一次性交付时，使用 deliver --open，而不是长期运行 Preview。这里的 examples/... 路径同样以 archify/ 为工作目录。

适用边界和安全判断

Archify 适合技术沟通、设计评审和可重复的图表交付，尤其适合希望把源 JSON 作为可审查资产保存的团队。Archify 不覆盖自动 Mermaid Parser、通用拖拽编辑器、托管分享服务或对线上基础设施的自动探测；这些边界在 README 中被列为非目标。

输入来自仓库源码时，应把“读取源码”和“证明运行时行为”分开。Skill 可以要求 Agent 打开代码库并绑定 revision-verified source，但 deployment-ownership 画像仍只校验作者写入的负责人、区域、私有数据库和边界穿越事实，不会查询云平台。不要把图上的一条箭头当成生产流量证明，也不要在图中放入令牌、Cookie、内部 IP 或未经允许的源码内容。

Skill 自身的更新检查会访问固定的 HTTPS manifest；更新检查器不会上传 Prompt、项目内容、账号或设备 ID。DeepSeek Harness 集成是社区预览版，兼容性和文件回传路径应按其仓库说明单独核对。MIT 许可证允许使用、修改和分发 Archify 代码，但不自动授予第三方架构素材、源码截图或上游系统数据的再分发权。

值得借鉴的设计

Archify 最值得学习的是把“生成好看”拆成一条可复核的生产链：输入使用 Typed JSON IR，模式字段由 Schema 约束，错误返回稳定规则码和局部修复建议，交付阶段原子替换最后一份好图。对 Agent 来说，这比返回一段不可解析的 SVG 更容易继续迭代；对评审者来说，源 JSON、验证回执和 HTML 可以分别保存、比较和归档。

采用 Archify 的成本是明确的：作者需要理解五套输入模型和布局契约，复杂图仍需要人工取舍；visual-check 的浏览器测量不能替代人工视觉评审；源码证据只在公开 commit 和可访问文件范围内成立。若团队只要快速草图，Mermaid 或白板工具成本更低；若需要精确交互、稳定导出和机器门禁，额外的 JSON 与校验成本才值得承担。

继续探索

先从 场景选图指南 选择模式，再看 archify/examples/ 中同类型 JSON。需要理解字段和布局时，优先阅读固定提交下的 SKILL.md、authoring-contract.md 和 delivery-contract.md。仓库主页的 Proof Lab 适合观察已检查场景的交互边界。

参考资料

• Archify GitHub repository
• Archify README（简体中文）
• Archify Skill contract
• Archify authoring contract
• Archify delivery contract
• Archify project page