Archify

聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切。导出最高 4× 清晰 PNG / JPEG / WebP / SVG，或直接复制到剪贴板。

Archify 是一个可用于 Claude、Codex CLI 和 opencode 的 agent skill：你用大白话描述自己的系统或流程，它就把你的描述变成一张做工精细的技术图 —— 一个单文件 HTML，在浏览器里打开就能切主题、复制到剪贴板、导出成各种图片格式。

• 不需要会画图 —— 把组件和连接关系说给 Claude 就行
• 支持 workflow / sequence / data flow / lifecycle —— 技术流程、审批链、工具调用、CI/CD、请求调用链、数据管线、PII 边界、状态机都可以画
• 内置主题切换 —— 深色 / 浅色一键切，浏览器记住偏好
• 一键复制到剪贴板 —— 直接贴到 Slack、飞书、微信、Notion、GitHub issue
• 导出图片超清晰 —— PNG / JPEG / WebP 全部由浏览器在最高 4× 源分辨率下原生光栅化（不是位图放大，没有糊），或导出 SVG 做真矢量
• SVG 自动跟系统深浅色 —— 导出的 SVG 内嵌两套变量 + @media (prefers-color-scheme)，贴到 GitHub README 里，读者切深浅色图跟着切（不用两张 PNG + <picture> 包起来）
• 内置质量闭环 —— renderer 驱动的图会经过 JSON schema 校验、布局检查、HTML/SVG artifact 检查，再做定向迭代
• 语义技术标签 —— 可以把组件写成 aws.lambda、postgres、redis、github-actions、openai 等；Archify 会把它们映射到合适的视觉类别，不需要完整图标库
• 单文件 HTML —— 生成的 HTML 零运行时依赖，发一个文件就能分享
• 聊天迭代 —— "把 Redis 挪到左边"、"鉴权服务换成玫红"、"加个 Kafka"

60 秒开始：

npx skills add tt-a1i/archify -g

然后告诉你的 agent：使用 archify 梳理这个仓库的运行时架构。

快速开始

1. 安装

npx skills add tt-a1i/archify -g

这条命令通过开源的 skills CLI 为支持的 Agent 安装 Archify。

如果只想临时体验，不做永久安装：

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

需要时可以把 codex 换成 claude-code 或 opencode。

2. 先画一个边界清楚的视图

不要一开始就要求一张图解释整个仓库。先从 Overview 开始：

分析这个仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，突出一条主要请求或数据路径，并标出外部依赖与信任边界。
辅助信息放进说明卡片，不要继续增加连线。

如果只想解释一条调用链：

使用 archify 画出这条登录流程：Browser -> Web App -> API -> JWT 校验 ->
Redis Session 查询 -> PostgreSQL 回源。把缓存未命中作为次要路径。

3. 在对话中细调

只要当前会话里仍保留源 JSON，就可以继续说：增加 Redis、把鉴权移到左侧、突出回滚路径。

最终得到的是一个可直接在现代浏览器中打开的 HTML 文件，并可导出 PNG、JPEG、WebP 或 SVG。

图表类型

先确定你想回答的问题，再选择对应视图：

为什么用 Archify

• 用布局判断代替通用自动布局 —— Agent 根据要讲的故事决定层级、间距、线路和视觉重点。
• Typed JSON IR —— 五种图都由对应 Schema 和 Renderer 驱动。
• 交付前验证 —— Schema、布局、HTML 和 SVG 检查会尽早发现结构错误和明显的可读性问题。
• 便于分享 —— 一个 HTML 文件即可打开，无需服务器或前端框架；外部字体不可用时会使用本地字体。
• 语义技术标签 —— postgres、redis、aws.lambda、github-actions 等名称会参与视觉分类，不需要沉重的图标运行时。

Archify 不是通用绘图编辑器，也不是 Mermaid 换肤工具。它的目标是把技术意图编译成适合沟通的成品图。

安装方式

推荐直接使用：

npx skills add tt-a1i/archify -g

Claude.ai 的 Skills 上传入口：

手动安装就是把压缩包解压到对应目录。分发包已包含独立校验器，不需要执行 npm install。

工作原理

Renderer 驱动的图会经过一条简短、可检查的流水线：

从仓库源码运行 CLI：

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json
node bin/archify.mjs check /tmp/workflow.html
node bin/archify.mjs examples

演示场景可以选择开启轻量 Trace 动画：

{ "meta": { "title": "Release Flow", "animation": "trace" } }

动画会遵循 prefers-reduced-motion。不设置 animation 时保持静态。

使用生成结果

在现代浏览器中打开 HTML，右上角提供两个入口：

• Theme —— 切换深色和浅色，快捷键 <kbd>T</kbd>。
• Export —— 复制 PNG，或下载 PNG、JPEG、WebP、SVG，快捷键 <kbd>E</kbd>。

位图会以浏览器允许的最高安全分辨率原生渲染，最高 4×。图太大时会自动降到 3× 或 2×，避免超过 Canvas 限制。

导出的 SVG 同时包含深色、浅色变量和 prefers-color-scheme，因此同一个文件可以跟随读者的系统主题。

常用 URL 参数：

• ?theme=light 或 ?theme=dark —— 固定初始主题。
• ?openExport=1 —— 加载后自动打开导出菜单。

WebP 和剪贴板能力取决于浏览器。外部字体不可用时，HTML 会使用本地字体 fallback。

Prompt 模板

仓库概览

梳理这个仓库的运行时架构，最多保留 12 个核心组件。
展示主要请求路径、外部系统和信任边界，把实现细节放进说明卡片。

CI/CD Workflow

画一张 CI/CD workflow：pull request -> tests -> approval -> build image ->
staging -> smoke test -> production。把 rollback 画成次要失败路径。

数据血缘

画一张从 Web、Mobile 事件经过 Consent Gate、Kafka、Warehouse、Feature Store，
最终到 Dashboard 和 ML 消费方的数据流图，并明确标出 PII 边界。

参考

语义标签会参与颜色和分组：

Renderer 输入请查看 Schema 说明，版本历史请查看 CHANGELOG.md。

当前状态与路线图

Archify 2.10 的五种 Renderer 模式都已经使用 Typed JSON IR。接下来的重点是稳定局部修改、改善布局诊断，并让生成结果更容易检查和分享。

规划和产品边界请查看 ROADMAP.md。自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不是目标。

致谢

Archify 基于 Cocoon AI 的 Cocoon-AI/architecture-diagram-generator v1.0 进行 Fork 和重写。

原项目的视觉语言仍归功于 Cocoon AI。Archify 2.x 在其基础上增加了主题、导出、Typed Renderer、校验、无障碍支持和统一 CLI。两个项目都采用 MIT License。

License

MIT —— 可以自由使用、修改和分发。