Archify

在聊天中生成漂亮的架构、技术工作流、时序、数据流和生命周期图。在暗色/亮色主题间切换。复制到剪贴板，或导出清晰的最高 4 倍分辨率的 PNG / JPEG / WebP / SVG。

Archify 是 Claude、Codex CLI 和 opencode 的智能体技能。它将以纯英语描述的系统或流程转化为一个精致、自包含的技术图表——单个 HTML 文件，您可以打开、切换主题、复制到剪贴板，并以最高分辨率导出。

• 无需设计技能 — 用英语描述架构，即可获得图表
• 同样支持工作流、时序、数据流和生命周期图 — 可以绘制技术流程、审批、工具调用、CI/CD、运行手册、请求调用链、数据管道、PII 边界和状态机
• 内置主题切换 — 一键切换暗色/亮色，跨会话保持
• 复制 PNG 到剪贴板 — 一键操作，直接粘贴到 Slack / Notion / GitHub
• 超清晰图像导出 — PNG / JPEG / WebP 以最高 4 倍原始分辨率原生渲染（无上采样模糊），或 SVG 真矢量
• SVG 遵循系统暗色/亮色 — 导出的 SVG 附带两组变量 + @media (prefers-color-scheme)，因此放入 GitHub README 中会自动跟随读者的颜色偏好（无需再用 <picture> 包裹两个 PNG）
• 自包含 HTML — 生成的文件零依赖，直接发送即可分享
• 通过对话迭代 — “添加 Redis”、“将认证移到左边”、“为 API 使用翡翠色”

项目页面: tt-a1i.github.io/archify

中文

预览

同一张图，两种主题，一键切换：

Dark	Light

导出菜单 — 复制 PNG 到剪贴板以及 4 种下载格式（所有光栅导出最高 4 倍原始分辨率）：

实时示例: examples/web-app.html — 在浏览器中打开，按 T 切换主题，按 E 打开导出。在 URL 后附加 ?theme=light 或 ?openExport=1 以获得可确定的截图。

图表类型

Archify 现在有五种主要输出：

类型	用途	如何请求
Architecture	系统组件、云资源、数据库、缓存、服务、边界、安全组	描述系统结构
Workflow	请求生命周期、审批流程、工具调用、CI/CD、运行手册、事件响应	描述参与方、步骤顺序和关键分支
Sequence	API 调用链、请求生命周期、缓存回退、鉴权检查、异步追踪、服务交互	描述谁调用谁、调用顺序以及返回内容
Data Flow	数据管道、ETL/ELT、分析事件、PII 隔离、仓库同步、数据血统、下游消费者	描述数据源、处理阶段、存储、敏感边界和消费者
Lifecycle	状态机、订单/任务/部署/智能体运行生命周期、等待状态、重试、取消、超时、终止状态	描述状态、转换事件、重试路径和终止结果

工作流并非试图取代所有通用流程图。它是一种技术交流图：泳道、语义颜色、清晰的主路径以及次要的异步/审批/追踪路径。

Use archify to draw a workflow:
User submits a request -> Agent plans -> Approval Gate if needed -> Tool Call -> Trace Log -> Final Reply

在此处打开示例: examples/workflow-agent-tool-call-rendered.html.

时序图解释一段时间内更窄的交互：

Use archify to draw a sequence diagram:
User opens a page, the frontend calls the API, the API verifies JWT, reads Redis, falls back to Postgres on cache miss, returns JSON, and emits trace.

在此处打开示例: examples/sequence-cache-miss-request.html.

数据流图解释数据资产如何移动和变化：

Use archify to draw a data flow:
Web and Mobile emit analytics events, Edge API collects them, Consent Gate filters PII, Kafka carries accepted events,
Warehouse stores analytics tables, Feature Store derives daily features, Dashboards and an ML Model consume downstream data.

在此处打开示例: examples/dataflow-product-analytics.html.

生命周期图解释对象如何改变状态：

Use archify to draw a lifecycle diagram:
Agent Run starts at Queued, moves through Planning, Executing, and Reviewing. It can pause at Needs Approval,
wait at Blocked, retry after Failed, end at Cancelled or Expired, or finish at Completed.

在此处打开示例: examples/lifecycle-agent-run.html.

新特性

Archify 基于 Cocoon-AI/architecture-diagram-generator v1.0（仅暗色，HTML 输出）。2.0 围绕主题化 CSS 变量系统重写了模板，并添加了客户端导出流水线。2.1 增加了复制到剪贴板 + 键盘导航。2.2 增加了打印样式表 + 本地字体回退。2.3 修复了一个长期存在的上采样 bug，使所有光栅导出在 4 倍原始分辨率下真正清晰（同时移除了 2.1 引入的 1× / 2× / 4× 选择器——它只会鼓励选择看起来模糊的比例）。2.4 将 SVG 导出升级为双主题自包含文件——将同一个 .svg 放入 GitHub README，它会自动跟随读者的暗色/亮色偏好。2.5 是一个加固版本：一批经过验证的渲染器和验证错误修复（模板插槽损坏、跨泳道生命周期重叠检测、PNG/SVG 导出中亮色主题泳道颜色、Safari 剪贴板复制）、带有数值阈值和修复建议的 LLM 人体工学验证错误、接受 Mermaid 作为输入方言（通过 SKILL.md 提示映射，非解析器）、CJK 感知文本测量及 CJK 字体回退，以及 golden-file 测试套件。

功能	v1.0	2.0	2.1	2.2	2.3	2.4	2.5
深色主题	是	是	是	是	是	是	是
浅色主题	—	切换	切换	切换	切换 + T 快捷键	同上	同上
PNG / JPEG / WebP 下载	手动截图	2× 位图上采样	1× / 2× / 4× 选择器（仍为上采样）	同上	4× 原生光栅化 — 无模糊	同上	修复了浅色导出泳道颜色
SVG 下载	—	矢量，样式内联（单主题）	同上	同上	同上	双主题自包含（@media prefers-color-scheme）	同上（修复了泳道颜色）
复制 PNG 到剪贴板	—	—	是	同上	是（最高 4×）	同上	修复 Safari
键盘快捷键	—	—	T / E + 菜单导航	同上	同上	同上	同上
无障碍访问	—	—	ARIA + focus-visible	同上	同上	同上	同上（+ 菜单无障碍修复）
打印样式表	—	—	—	是	是（+ 横向 + 双列卡片）	同上	同上
导出时本地字体回退	—	—	—	是	是	同上	+ CJK 字体回退
样式模型	内联 fill / stroke	CSS 自定义属性 + 语义类	同上	同上	同上	同上	同上
类型化渲染器 + 模式验证	—	—	—	—	—	—	是（含测试与 CI）

快速开始

1. 安装技能

Archify 打包为一个智能体技能目录（archify/SKILL.md），因此同一个 archify.zip 适用于 Claude、Codex CLI 和 opencode。

Claude.ai：

1. 下载 archify.zip
2. 前往 设置 -> 能力 -> 技能
3. 点击 + 添加 并上传 zip 文件
4. 开启该技能

Claude Code CLI：

# 全局（所有项目）
unzip archify.zip -d ~/.claude/skills/

# 或项目本地
unzip archify.zip -d ./.claude/skills/

Codex CLI：

# 全局（所有项目）
unzip archify.zip -d ~/.agents/skills/

# 或项目本地
unzip archify.zip -d ./.agents/skills/

opencode：

# 全局（opencode 原生）
unzip archify.zip -d ~/.config/opencode/skills/

# 或项目本地
unzip archify.zip -d ./.opencode/skills/

# 同样适用于上面 Codex 使用的共享智能体目录
unzip archify.zip -d ~/.agents/skills/

类型化渲染器（工作流 / 时序 / 数据流 / 生命周期）依赖 ajv 进行模式验证，需要在已安装的技能目录中执行一次性的 npm install。许多智能体运行时可以在首次使用时自动运行，遵循 SKILL.md 中的设置说明——或者自行运行：

cd ~/.agents/skills/archify && npm install

若不安装依赖，渲染器会跳过模式验证（布局检查仍会运行）。

Claude.ai 项目（替代方案）： 将 archify.zip 上传到你的项目知识库中。

各安装方式的能力如下：

安装方式	能力
Claude Code	完整——运行类型化渲染器 + 模式验证
Codex CLI	完整——安装到 ~/.agents/skills/ 或 .agents/skills/
opencode	完整——安装到 .opencode/skills/、.agents/skills/ 或其他支持的技能目录
Claude.ai（zip 上传）	通常完整——取决于沙盒能否执行 npm install（通常可以）
项目知识库	仅架构模式——无代码执行，纯提示驱动

2. 描述你的系统

以下任意方式均可：

让 AI 分析你的代码库：

分析此代码库并描述其架构。包括所有主要组件、它们如何连接、使用的技术以及任何云服务或集成。格式化为架构图的列表。

自行编写：

- React 前端与 Node.js API 通信
- PostgreSQL 数据库
- Redis 用于缓存
- 托管在 AWS 上，使用 CloudFront CDN

或询问典型架构：

SaaS 应用程序的典型架构是什么？

3. 让 Claude 使用该技能

使用你的 archify 技能根据以下描述创建架构图：

[在此粘贴你的架构描述]

就这样。Claude 会生成一个 HTML 文件，你可以在任何浏览器中打开。通过聊天进行迭代：“添加 Redis”、“将 Postgres 替换为 MySQL”、“高亮认证路径”。

使用输出

在任意浏览器中打开生成的 HTML。右上角有两个按钮：

• 主题按钮（深色 / 浅色）——单击切换，跨会话持久化。快捷键：T。
• 导出菜单——打开一个下拉菜单，包含五个操作（复制 PNG + 下载 PNG / JPEG / WebP / SVG）。快捷键：E。

导出菜单

操作	功能
复制 PNG	将当前图表的 PNG 直接放入剪贴板。粘贴到 Slack、Notion、GitHub、Figma 中。
下载 PNG / JPEG / WebP	保存光栅图像。JPEG/WebP 会在当前主题背景上绘制（无 alpha 通道）；PNG 保留透明度。
下载 SVG	矢量导出，所有样式内联，双主题自包含。文件包含深色和浅色两套 CSS 变量集，以及一条 @media (prefers-color-scheme) 规则——将同一个 .svg 放入 GitHub README 或博客中，它会自动跟随读者的偏好设置。仍可在 Figma / Illustrator 中编辑。无损缩放。

每个光栅导出（复制 PNG、下载 PNG/JPEG/WebP）均由浏览器以最高 4 倍于图表原始分辨率原生渲染（超大图表会降级为 3×/2× 以保持在浏览器画布限制内）——序列化的 SVG 被赋予 width/height 为 4 × viewBox，由浏览器以该分辨率光栅化，然后以自然大小绘制到画布上（无上采样）。这为视网膜显示屏、幻灯片和打印提供了真正清晰的输出。没有缩放拨盘——始终自动选择最大安全清晰度。

键盘快捷键

• T 任意位置——切换主题
• E 任意位置——打开导出菜单
• 菜单内 ↑ ↓——导航操作
• Home / End——跳转到第一个/最后一个操作
• Enter / Space——激活
• Esc——关闭菜单

URL 参数

• ?theme=light 或 ?theme=dark——强制指定起始主题（用于确定性截图、分享链接、嵌入）
• ?openExport=1——加载时自动打开导出菜单（用于演示/文档截图）

注意事项

• WebP 支持取决于浏览器的画布编码器。如果不可用（旧版 Safari），菜单项会变灰并禁用。PNG 和 JPEG 是通用的。
• 剪贴板支持图片需要 ClipboardItem + navigator.clipboard.write（Chromium、Firefox 127+、Safari 16+）。如果不可用，复制 PNG 会变灰。
• 导出中的字体：光栅图像使用系统等宽回退字体（ui-monospace / Menlo / Consolas），因为沙盒化的图像渲染上下文无法获取 Google Fonts。本地安装 JetBrains Mono 可获得像素级完美渲染。

示例提示

Web 应用：

为一个 Web 应用程序创建架构图，包含：
- React 前端
- Node.js/Express API
- PostgreSQL 数据库
- Redis 缓存
- JWT 认证

AWS serverless:

Create an architecture diagram showing:
- CloudFront CDN
- API Gateway
- Lambda functions (Node.js)
- DynamoDB
- S3 for static assets
- Cognito for auth

Microservices:

Create an architecture diagram for a microservices system with:
- React web app and mobile clients
- Kong API Gateway
- User Service (Go), Order Service (Java), Product Service (Python)
- PostgreSQL, MongoDB, and Elasticsearch databases
- Kafka for event streaming
- Kubernetes orchestration

Data flow / product analytics:

Use archify to draw a data flow:
- Web App and Mobile SDK produce clickstream events
- Edge API collects events
- Consent Gate filters identity and PII
- Kafka/Event Stream carries accepted events
- Warehouse stores normalized facts
- Feature Store derives daily feature vectors
- Dashboards and ML Model consume downstream data

State machine / lifecycle:

Use archify to draw a lifecycle diagram:
- A task starts at Queued
- Planning builds the plan
- Executing calls tools
- Reviewing checks quality
- Needs Approval and Blocked are wait states
- Failed can retry, while Cancelled / Expired / Completed are terminal states

Color palette

Component Type	Color	Use for
Frontend	Cyan	客户端应用、UI、边缘设备
Backend	Emerald	服务器、API、服务
Database	Violet	数据库、存储、AI/ML
Cloud / AWS	Amber	云服务、基础设施
Security	Rose	认证、安全组、加密
Message Bus	Orange	Kafka、RabbitMQ、SNS、事件总线
External	Slate	通用、外部系统

每种颜色都有协调的暗色模式和亮色模式变体，可通过主题切换一起切换。

Technical details

• Styling: CSS custom properties on :root + [data-theme="light"]；SVG elements reference semantic classes (c-frontend、t-muted、a-emphasis等)。在<html>上切换data-theme会重新主题化整个图表，包括渐变、网格、箭头和遮罩矩形。
• Export pipeline: SVG被克隆，宿主<style>内联到克隆中，当前主题变量被解析并写入克隆的:root规则中。对于栅格格式，克隆的width/height设置为4 × viewBox，以便浏览器以目标分辨率原生栅格化矢量；canvas被调整为匹配大小，图像以自然尺寸绘制（无bitmap上采样）。然后toBlob(mime)生成文件。JPEG会获得明确的背景填充，因为它没有alpha通道。如果目标分辨率超过浏览器的canvas限制，pipeline会自动降级到3×或2×，确保导出仍然成功。
• Self-contained output: 单个HTML文件，Google Fonts链接 + 内联SVG + 约19 KB的嵌入式JS。无需构建步骤，无JS框架，无服务器——生成的HTML本身零依赖（类型化的渲染器需要npm install安装ajv，参见Install）。
• Browser support: 任何现代浏览器（Chrome、Safari、Firefox、Edge）。需要Image + canvas.toBlob支持image/webp以导出WebP。

Attribution

Archify是Cocoon-AI/architecture-diagram-generator（MIT，v1.0）的一个分支/重写，作者是Cocoon AI。原版简洁的视觉设计——调色板、网格背景、摘要卡片布局、JetBrains Mono字体——得以保留。原有的美学风格归功于原作者。

Archify 2.x 的贡献包括：

• 将模板重构为基于CSS变量的主题系统（暗色+亮色）
• 主题切换 + localStorage持久化 + prefers-color-scheme默认设置
• 内置PNG/JPEG/WebP/SVG导出菜单 + 复制到剪贴板
• 4倍原生栅格化（修复上采样模糊）
• 双主题自包含SVG导出（单个文件跟随宿主的prefers-color-scheme）
• 键盘导航 + 无障碍语义
• 打印样式表 + 本地字体回退
• 更新了SKILL.md以引导Claude使用基于类的（可主题化）图表

两个项目均采用MIT许可。

Roadmap

参见 ROADMAP.md。

下一步是 v3.0 — JSON IR 稳定化：一个最小的diagram.json中间格式，使Claude能够本地编辑坐标而不影响无关组件，输出对git diff友好，主题/调色板切换无需重新渲染。

关于Mermaid导入： 自动Mermaid解析器路径在实验表明自动布局 + archify CSS并不比原生Mermaid更有意义后已被砍掉（参见 experiments/v3-mermaid-validation/RESULT.md）。Archify的美学核心是Claude的布局判断，而非CSS。你仍然可以粘贴Mermaid代码，让Claude从头开始布局archify风格的图表——它通过SKILL.md中的提示进行，而不是解析器。

之前的v2.4 / v2.5计划（?exportScale=N、色盲友好调色板、分享链接）也被放弃了。理由参见 ROADMAP “Not planned” 部分。

License

MIT — 免费使用、修改和分发。

Contributing

欢迎提交Issues、PR和共享图表。