核心问题: 类型化 JSON 契约 + 确定性校验 + 单文件 HTML 产物,是否真的比你现在用的画图工具让架构评审更快、更可信?
RepoDaily 采用评分
RepoDaily 将该项目的采用分评为 92/100（强）：分数来自文章来源、安装路径、生产风险、差异化、许可证清晰度以及 AI/Agent 适配度。
包含 5 个来源、覆盖 3 类来源；如有 RepoDaily 独有模块，会进一步提高证据分。
检测到 6 个工作流步骤、5 个下一步动作，以及 3 个命令/安装信号。
趋势热度为 +1,002 stars；如内容中有 release、issue 或维护信号，会提高维护可信度。
采纳风险标记为 medium，并包含 5 条安全说明与 4 条跳过条件。
3 个机会视角、5 个替代方案，以及 4 个类型化模块支撑差异化判断。
文章中包含许可证来源或许可证表述。
文章正文和元数据中检测到 7 个 AI/Agent 相关信号。
项目概览
Archify 是一个 Agent 技能——装进 Raven、Cursor、Claude Code、Codex CLI 或 OpenCode 的能力包——在对话里把代码库或文字系统描述变成精致的交互式系统图。安装只需一条命令:`npx skills add tt-a1i/archify -g`。产物是一个自包含 HTML 文件,覆盖五种图类型(架构图、工作流图、时序图、数据流图、生命周期图),带四种预设、深浅双主题、内置品牌标识和有限动画;同一产物还能导出 PNG、SVG、WebM 和 1200×630 分享卡。
它的差异点不在画得好看,而在"每次交互都有据可查"。Archify 使用类型化 JSON 中间表示和确定性校验,README 明确承诺:可搜索节点、可选打开经版本校验的源码、追踪上游/下游的受控可达范围与精确路由、比较角色、播放引导式故事,而且不凭空捏造拓扑。面向代码评审,两张经过校验的快照可以按 Before/Delta/After 对比,并给出精确的新增、删除、变更、移动和改道事实——这是可以直接贴进 Pull Request 的产物。
项目版本推进很快。当前开发标识是 v2.16.0-dev.0,位于 changelog 的 Unreleased 区,内容是有界的查看器本地化:五个渲染器都接受 `meta.locale` 的 `en` 和 `zh-CN` 取值,本地化范围仅限渲染器自有的查看器 UI、无障碍文案、默认图例和文档标题,不翻译作者撰写的内容。上一个正式版 2.15.0(2026-08-17)带来了作者品牌标识(107 个带出处的矢量标识、`archify brands` 发现命令)、时序图的 `meta.column_fit: "spread"` 列宽布局,以及独立的 DeepSeek Harness 发行包 `@tt-a1i/archify-dsh`。2.14.0(2026-08-11)新增 `archify visual-check <output.html> --json`,在 1440×900、1600×1000、1920×1080、2048×1320 四个视口测量首屏包含度。
出处与许可值得说清楚。LICENSE 是 MIT,但有两条版权声明:2025 年 Cocoon AI 的原始项目 "architecture-diagram-generator",以及 2026 年 tt-a1i 的 Archify。渲染器包位于 `archify/` 目录,要求 Node.js 18 及以上,CI 覆盖 Node 18、20、22、24。2026-08-27 当天该仓库排名第 5、期间新增 1,002 星,主语言为 HTML,README 挂着 Trendshift 徽章和两家具名赞助方——APINEBULA 与 EverMind(其 Raven 框架以 Skill 形式支持 Archify)。
为什么现在变热
- 期间新增 1,002 星、排名第 5,README 开头就是一条命令完成安装:`npx skills add tt-a1i/archify -g`。
- 开箱即用支持多家 Agent:Raven、Cursor、Claude Code、Codex CLI、OpenCode,2.15.0 还补了 DeepSeek Harness 专属快速上手。
- 产物是单个自包含 HTML 文件——无需服务器、无运行时依赖——同一产物可直接导出 PNG、SVG、WebM 和 1200×630 分享卡。
- 把"可验证"当卖点:类型化 JSON 中间表示、确定性校验、经版本校验的源码链接,以及带精确新增/删除/变更/移动/改道事实的 Before/Delta/After 快照对比。
- 发版节奏紧凑且内容具体:2.14.0 在 2026-08-11、2.15.0 在 2026-08-17,每次都有具名新特性和已修复缺陷,而不是含糊的改进。
解决什么问题
- 架构图会腐烂,因为它们是在与代码脱节的工具里手绘出来的。
- 让 Agent 生成图时,评审者分不清拓扑是核实过的还是编出来的;Archify 的答案类型化 JSON 契约 + 确定性校验 + 经版本校验的源码链接。
- 图文件散落在各种编辑器里,要分享一个可评审的交互视图往往只能截图或购买托管服务。
- 合并前的架构变更评审缺少标准产物;Archify 把带精确差异事实的 Before/Delta/After 快照定位成这个产物。
- 演示尺寸下导出质量容易崩,所以 2.14.0 加入了 1440×900 到 2048×1320 的包含度测量和 1200×630 分享卡。
工作原理
- 在 Node.js 18+ 环境全局安装技能:`npx skills add tt-a1i/archify -g`。Cursor 用户可在 tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture 获取精确的全局与项目级命令。
- 按 README 的示例提示 Agent:`Use archify to map this repository's runtime architecture.`
- Agent 把仓库或系统描述编译成 Archify 的 schema-v1 类型化 JSON 中间表示;`via`、命名路由、通道、边和标签位置这类显式几何保持权威,不被悄悄改写。
- 校验器和渲染器在真实浏览器布局中检查几何、投影文字、层叠顺序、遮罩、交互和导出;面向 Agent 的失败落入 `diagnostics[]`,带稳定的 `code`、精确的 `subject`、具体的 `evidence` 和可执行的 `supportedFixes`。
- 得到一个自包含 HTML 文件——五种图类型、四种预设、深浅双主题——外加 PNG、SVG、WebM 和 1200×630 分享卡导出。
- 可选执行 `archify visual-check <output.html> --json`,在 1440×900、1600×1000、1920×1080、2048×1320 测量首屏包含度,并在两个端点尺寸采集深浅色证据。
产品演示与界面预览
架构解读:这是一份契约,不只是画图器
渲染器包位于 `archify/` 目录,要求 Node.js 18 及以上,CI 覆盖 Node 18、20、22、24。CONTRIBUTING.md 明确写道:Archify 的公开行为比一个渲染函数大得多,并列出哪些算契约——既有的 schema-v1 类型化 JSON 在经过评审的破坏性规则和迁移路径引入之前保持有效;`via`、命名路由、通道、边、标签位置这类显式作者几何保持权威,不会被静默重写。
失败处理是为 Agent 设计的,而不是让人去日志里扒文字:面向 Agent 的失败进入 `diagnostics[]`,带稳定的 `code`、精确的 `subject`、具体的 `evidence` 和可执行的 `supportedFixes`。贡献指南还区分了保持广泛兼容的 `standard` 档与 `showcase` 档——后者新增失败必须指出真实且可修复的缺陷,并返回稳定的机器可读诊断。一条贯穿设计的工程判断值得引用:合法的 SVG 不等于好图,因为几何、投影文字、层叠顺序、遮罩、交互、导出和真实浏览器布局可能各自独立地出错。
2.15.0 加入了作者品牌标识层:五种图类型都可在主节点上写显式 `brand`,目录收录 107 个带出处的矢量标识并可通过 `archify brands` 发现;未知官方 URL 必须走摘要固定的抓取命令,流水线校验作者 SHA-256 后才嵌入独立 HTML,并在内容漂移、格式错误、目标不安全或整图超时的情况下拒绘(fail closed);远程 SVG 直接拒绝。未发布的 v2.16.0-dev.0 在五个渲染器中加入 `meta.locale`(`en` 与 `zh-CN`),只本地化查看器自有的 UI、无障碍文案、默认图例、文档标题和语言元数据——作者文案不会被翻译,不支持的作者语言会回退到明确披露的英文查看器。
命令面
- `npx skills add tt-a1i/archify -g`——README 给出的全局技能安装;Cursor 专属快速上手在 tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture。
- `Use archify to map this repository's runtime architecture.`——README 给出的第一条标准提示词。
- `archify brands`——随 2.15.0 的 107 个带出处矢量标识一起引入的品牌目录发现命令。
- `archify visual-check <output.html> --json`——2.14.0 新增;在 1440×900、1600×1000、1920×1080、2048×1320 测量首屏包含度,在两个端点尺寸采集深浅色证据,写出相对路径的对照表,并产出保持 `visualReview: "pending"` 的机器回执;Chrome 缺失时报告 `skipped` 而非假通过。
- `--quality` 后面不跟值时 CLI 会直接拒绝,不再静默接受不完整命令(2.15.0 修复)。
- `meta.column_fit: "spread"`——时序图可选的宽 viewBox 布局(2.15.0);固定宽度布局仍是默认。
上手路径
- 准备 Node.js 18 或更高环境;changelog 把运行时描述为零安装、无依赖。
- 执行 `npx skills add tt-a1i/archify -g` 安装,然后打开一个你对架构了如指掌的仓库。
- 提示 Agent 映射该仓库的运行时架构,等待单个 HTML 产物生成。
- 在 HTML 里搜索你认识的一个节点,追踪它的上游/下游受控可达范围,并使用打开经版本校验源码的选项。
- 运行 `archify visual-check <output.html> --json`,核对 1440×900 与 2048×1320 的包含度测量以及 pending 状态的 visualReview 回执。
- 在 JSON 中间表示里故意制造一处错误,确认失败以带 code、subject、evidence、supportedFixes 的 `diagnostics[]` 条目出现,而不是渲染出一张坏图。
维护风险
- 当前标识是 changelog Unreleased 区的 v2.16.0-dev.0;最新正式版是 2026-08-17 的 2.15.0。直接从 main 拉取可能带上未发布行为,例如 `meta.locale` 本地化。
- changelog 显示节奏很紧——2.14.0 在 2026-08-11、2.15.0 在 2026-08-17——修复快,但也意味着契约面仍在移动。
- MIT LICENSE 带两条版权声明:2025 年 Cocoon AI(原始 "architecture-diagram-generator")与 2026 年 tt-a1i(Archify),项目治理权已经易手一次。
- 契约治理写在 CONTRIBUTING.md 里而非外部规范:schema、渲染器契约、校验规则、安装路径和导出的改动必须先开规划 issue,先就用户价值、兼容边界和非目标达成一致再实现。
- 抵消因素:CI 覆盖 Node 18/20/22/24;DeepSeek Harness 打包验收检查覆盖 macOS、Linux、Windows 的命令解析;2.15.0 的 DSH 发行包对非 DSH 用户不添加探测、遥测或行为变化。
谁适合关注
适合关注
- 合并前评审架构变更:用带精确新增、删除、变更、移动、改道事实的 Before/Delta/After 快照直接附在 Pull Request 上。
- 在 Cursor、Claude Code、Codex CLI、Raven 或 OpenCode 里工作、希望在对话内直接出图而不是切到独立编辑器的人。
- 新人入职文档和设计评审,只需附上一个自包含 HTML 文件,可离线打开、可交互探索。
- 双语文档场景:未发布的 `meta.locale` 支持把查看器界面本地化为 `en` 和 `zh-CN`,且不改动作者内容。
可以先跳过
- 需要常驻在线的图服务或 Confluence/Notion 插件的人不适用——产物是静态自包含 HTML 文件。
- 期待图内容被翻译的人不适用:`meta.locale` 只本地化渲染器自有的查看器 UI、图例、标题和无障碍文案;作者文案保持原语言。
- 必须锁定稳定版本号的人要谨慎——当前标识是开发版 v2.16.0-dev.0;若 2.15.0 缺你需要的 Unreleased 特性,请等打 tag。
- 品牌流程依赖远程 SVG 标识的人不适用:2.15.0 明确拒绝远程 SVG,并对未验证的品牌字节拒绘。
风险与注意事项
MIT 许可、无依赖的 Node 18 运行时、覆盖四个 Node 版本的 CI 以及成文的兼容性契约都降低了技术风险;但项目自我标识为开发版、治理权已易手一次,且契约决策集中在一个贡献者群体手中。
- README 和 changelog 都把 v2.16.0-dev.0 标为当前标识;最新的查看器本地化能力只存在于 Unreleased 区。
- LICENSE 的双版权(2025 年 Cocoon AI 的原始 "architecture-diagram-generator"、2026 年 tt-a1i)说明这套代码已经历过一次易主。
- 兼容性保证(schema-v1 有效性、作者几何权威、`standard` 档行为)靠 CONTRIBUTING.md 的规范与评审执行,不是外部独立版本化的规范。
- 正向抵消:零安装无依赖的 Node 18 运行时、Node 18/20/22/24 的 CI、visual-check 对 Chrome 缺失报告 `skipped` 而非假通过、品牌资产走摘要固定并校验 SHA-256 且漂移即拒绘。
- MIT 许可:可自由使用、复制、修改、合并、出版、分发、再许可及销售,需保留声明;文件附带标准的无担保免责条款。
- 品牌资产按敌意输入加固:未知官方 URL 需走摘要固定的抓取;渲染、校验、交付环节重新拉取有界的 PNG/JPEG/WebP/ICO 字节,校验作者 SHA-256 后嵌入独立 HTML,并在内容漂移、格式错误、目标不安全或整图超时的情况下拒绘;远程 SVG 被拒绝。
- CONTRIBUTING.md 禁止在提示词、JSON 固件、日志、截图、生成产物和包测试中出现密钥、访问令牌、凭据、私有仓库内容、个人数据和客户数据。
- 安全漏洞必须走该仓库的 GitHub 私密安全报告渠道,不得公开 issue 或披露利用细节。
- DeepSeek Harness 发行包 `@tt-a1i/archify-dsh` 是纯 Skill 捆绑包,按 2.15.0 changelog,对非 DSH 用户不添加探测、遥测或行为变化。
替代方案比较
| 方案 | 适用场景 | 代价 |
|---|---|---|
Mermaid | 需要在 GitHub 等 markdown 宿主中原生渲染文本定义的图,不需要 Agent 参与或快照差异对比。 | 免费,开源(MIT)。 |
D2 | 想要独立的声明式图语言和 CLI,不依赖任何编码 Agent。 | 免费,开源。 |
PlantUML | 需要从纯文本定义生成标准形态的 UML 产物,且已有渲染管线。 | 免费,开源;嵌入专有工具前请核对许可条款。 |
diagrams.net (draw.io) | 需要手工 GUI 排版和白板协作,而不是由契约校验生成的图。 | 免费,开源;托管应用与部分集成另收费。 |
Structurizr DSL | 用 C4 方法建模,希望有工作区支撑的单一事实来源来派生多视图。 | DSL 免费开源;云服务单独售卖。 |
这个趋势说明了什么
合并门禁里的架构差异
带精确新增、删除、变更、移动、改道事实的 Before/Delta/After 对比,是主流画图工具都没有的能力,而它恰好贴合 Pull Request 评审。
围绕一次真实的重构 PR 生成两张经过校验的快照,核对差异事实是否与你手工验证的 diff 一致。
双语内部文档
未发布的 `meta.locale` 取值 `en` 和 `zh-CN` 会在五个渲染器中本地化查看器 UI、无障碍文案、默认图例和文档标题,不支持的语言会明确回退到英文查看器。
把同一张图分别用 `meta.locale` 的 `en` 和 `zh-CN` 渲染两次,确认查看器界面、图例和标题变化而作者标签不变。
品牌一致的外部文档
107 个带出处的矢量标识、`archify brands` 发现命令和 SHA-256 校验嵌入,让生成图直接携带官方徽标而无需手工处理素材。
查你的组织标识是否在目录里,再重渲染一次,确认走的是摘要固定抓取并校验通过的路径,而不是静默重新拉取。
RepoDaily 判断
Archify 拿下 1,002 星的单日表现,靠的是同时攻击生成式图最弱的两点——可信与可分享:类型化 JSON 契约、确定性校验、Agent 可读的 `diagnostics[]` 失败,以及一个能导出 PNG、SVG、WebM 和 1200×630 分享卡的自包含 HTML。带精确新增、删除、变更、移动、改道事实的 Before/Delta/After 快照差异,在同类工具里确实少见。需要稳定请锁定正式版 2.15.0 而非 v2.16.0-dev.0 开发标识;依赖 schema-v1 产物前先读 CONTRIBUTING.md 的契约规则;并留意 MIT LICENSE 里 2025 年 Cocoon AI 的项目出处。