tt-a1i/archify
GitHub: tt-a1i/archify
一款 AI agent 技能插件，通过自然语言对话自动生成多种技术架构图表并支持多格式高清导出。
Stars: 4655 | Forks: 412
# Archify
**在对话中生成精美的架构图、技术工作流、时序图、数据流图和生命周期图。支持深色/浅色切换。支持复制到剪贴板或导出最高 4× 分辨率的无损 PNG / JPEG / WebP / SVG。**
Archify 是一个专为 Claude、Codex CLI 和 opencode 设计的 agent skill。它能将你对系统或流程的纯英文描述转化为一张精美且独立的技术图表——一个单一的 HTML 文件，你可以打开它、切换主题、复制到剪贴板，并以最高分辨率导出。
- **无需设计技巧** —— 用英文描述你的架构，即可获得图表
- **同时支持工作流、时序图、数据流图和生命周期图** —— 可绘制技术流程、审批流、工具调用、CI/CD、运行手册、请求调用链、数据流水线、PII 边界和状态机
- **内置主题切换** —— 一键切换深浅色模式，并跨会话持久化保存
- **复制 PNG 到剪贴板** —— 一键复制，直接粘贴到 Slack / Notion / GitHub
- **超清图像导出** —— PNG / JPEG / WebP 以最高 4× 源分辨率原生渲染（无上采样模糊），或导出为真正的矢量 SVG 格式
- **SVG 遵循系统深色/浅色模式** —— 导出的 SVG 自带两套变量集 + `@media (prefers-color-scheme)`，将其放入 GitHub README 中即可自动跟随读者的颜色偏好（无需再用 `` 包裹两张 PNG）
- **内置验证循环** —— 基于渲染器的图表会经过 JSON schema 校验、布局检查、HTML/SVG 产物检查以及针对性迭代
- **语义化技术标签** —— 将组件描述为 `aws.lambda`、`postgres`、`redis`、`github-actions`、`openai` 等；Archify 会将它们映射到正确的视觉类别，无需完整的图标库
- **独立完整的 HTML** —— 生成的文件零依赖，直接发送文件即可分享
- **通过对话迭代** —— “add Redis”、“move auth to the left”、“use emerald for the API”
**项目主页：** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)
**60 秒开始：**
```
npx skills add tt-a1i/archify -g
```
然后向你的 agent 提问：`Use archify to map this repository's runtime architecture.`
## 预览
同一张图表，两种主题，一键切换：
| 深色 | 浅色 |
|---|---|
|  |  |
导出菜单 —— 支持复制 PNG 到剪贴板以及 4 种下载格式（所有位图导出均支持最高 4× 源分辨率）：
在线示例：[`examples/web-app.html`](examples/web-app.html) —— 在浏览器中打开，按 T 切换主题，按 E 打开导出菜单。在 URL 后追加 `?theme=light` 或 `?openExport=1` 可用于生成确定的截图。
## 图表类型
Archify 目前有五种主要输出形式：
| 类型 | 适用场景 | 如何提问 |
|---|---|---|
| **架构图** | 系统组件、云资源、数据库、缓存、服务、边界、安全组 | 描述系统结构 |
| **工作流** | 请求生命周期、审批流程、工具调用、CI/CD、运行手册、故障响应 | 描述参与者、步骤顺序和关键分支 |
| **时序图** | API 调用链、请求生命周期、缓存回退、身份验证、异步追踪、服务交互 | 描述谁在什么顺序下调用了谁，以及返回了什么 |
| **数据流图** | 数据流水线、ETL/ELT、分析事件、PII 隔离、数仓同步、血缘、下游消费者 | 描述数据源、处理阶段、存储、敏感度边界和消费者 |
| **生命周期图** | 状态机、订单/任务/部署/agent运行生命周期、等待状态、重试、取消、超时、终止状态 | 描述状态、转换事件、重试路径和最终结果 |
架构图用于说明系统结构 —— 组件、边界以及它们之间的连接方式：
```
Use archify to draw an architecture diagram:
React frontend calls a Node.js API backed by PostgreSQL and Redis, deployed on AWS behind CloudFront.
```
SaaS 图表示例：[`examples/web-app.html`](examples/web-app.html)。
真实仓库示例（基于渲染器的 JSON IR）：
- [`examples/archify-repo.html`](examples/archify-repo.html) —— 本项目的 skill → JSON IR → 渲染器流水线
- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) —— 同样的流水线，使用 `layout.mode: "grid"`（`row`/`col` 布局）
- [`examples/maka-architecture.html`](examples/maka-architecture.html) —— 第三方桌面 agent 工作台 (Maka)
工作流并不是要取代所有通用的流程图。它是一种技术沟通图表：包含泳道、语义化颜色、清晰的主路径，以及辅助的异步 / 审批 / 追踪路径。
```
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`](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`](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`](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`](examples/lifecycle-agent-run.html)。
## 最新动态
Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0（仅深色模式，HTML 输出）分支开发。**2.0** 版本围绕可主题化的 CSS 变量系统重写了模板，并添加了客户端导出流水线。**2.1** 增加了复制到剪贴板和键盘导航功能。**2.2** 增加了打印样式表和本地字体回退。**2.3** 修复了位图上采样错误，使导出在最高 4× 源分辨率下真正清晰。**2.4** 将 SVG 导出升级为双主题独立文件。**2.5** 添加了基于渲染器的工作流 / 时序图 / 数据流图 / 生命周期图模式，Mermaid 输入指引，支持 CJK 的文本测量，基准测试和 CI。**2.6** 使架构渲染器达到了 schema + 布局验证的一致性。**2.7** 通过阶段标题、分组、异常泳道、主路径检查、同泳道正交路由和渲染后 HTML/SVG 检查器强化了工作流图表。**2.8** 增加了可选的追踪动画，并拒绝跨越无关节点的工作流路由。**2.9** 添加了统一的 CLI (`bin/archify.mjs`) 和真实仓库架构示例。**2.10** 添加了可操作的验证器提示、可选的架构网格布局 (`row`/`col`)，以及用于计算布局 JSON 的 `archify inspect`。
| 功能 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 | 2.8 | 2.9 | 2.10 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 深色主题 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 同上 | 同上 | 同上 |
| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + T 快捷键 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 |
| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图上采样 | 1× / 2× / 4× 选择器（仍为上采样） | 同上 | **4× 原生栅格化 —— 无模糊** | 同上 | **修复了浅色导出泳道颜色** | 同上 | 同上 | 同上 | 同上 | 同上 |
| SVG 下载 | — | 矢量图，内联样式（单主题） | 同上 | 同上 | 同上 | **双主题独立文件** (`@media prefers-color-scheme`) | 同上（修复了泳道颜色） | 同上 | 同上 | 同上 | 同上 | 同上 |
| 复制 PNG 到剪贴板 | — | — | 是 | 同上 | 是（最高 4×） | 同上 | **修复了 Safari 兼容性** | 同上 | 同上 | 同上 | 同上 | 同上 |
| 键盘快捷键 | — | — | T / E + 菜单导航 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 |
| 无障碍访问 | — | — | ARIA + focus-visible | 同上 | 同上 | 同上 | 同上（+ 菜单 a11y 修复） | 同上 | 同上 | 同上 | 同上 | 同上 |
| 打印样式表 | — | — | — | 是 | 是（+ 横向 + 双列卡片） | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 |
| 导出时使用本地字体回退 | — | — | — | 是 | 是 | 同上 | **+ CJK 字体回退** | 同上 | 同上 | 同上 | 同上 | 同上 |
| 样式模型 | 内联 `fill` / `stroke` | CSS 自定义属性 + 语义化类名 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 | 同上 |
| 类型化渲染器 + schema 验证 | — | — | — | — | — | — | 工作流 / 时序图 / 数据流图 / 生命周期图 | **+ 架构图** | 同上 | 同上 | 同上 | 同上 |
| 工作流结构辅助 | — | — | — | — | — | — | 泳道 + 路由边线 | 同上 | **阶段、分组、异常泳道、mainPath lint** | **路由交叉防护** | 同上 | 同上 |
| 渲染后产物检查器 | — | — | — | — | — | — | — | — | **是** | 同上 | 同上 | 同上 |
| 追踪动画 | — | — | — | — | — | — | — | — | — | **可选开启** | 同上 | 同上 |
| 统一 CLI | — | — | — | — | — | — | — | — | — | — | **是** | 同上 |
| 真实仓库架构示例 | — | — | — | — | — | — | — | — | — | — | **是** | 同上 |
| 架构图网格 + 布局检查 | — | — | — | — | — | — | — | — | — | — | — | **是** |
| 验证器可操作提示 | — | — | — | — | — | — | — | — | — | — | — | **是** |
## 快速开始
### 1. 一行命令安装
全局安装 Archify，然后根据提示选择你的 agent：
```
npx skills add tt-a1i/archify -g
```
想在不永久安装的情况下试一试？这会使用该 skill 的临时副本启动 Codex：
```
npx skills use tt-a1i/archify@archify --agent codex
```
将 `codex` 替换为 `claude-code` 或 `opencode` 即可启动对应的 agent。这些命令使用了开源的 [`skills` CLI](https://github.com/vercel-labs/skills)。
### 2. 复制一个提示词
**映射真实的代码库：**
```
Analyze this repository, then use archify to create an architecture diagram of its runtime components, data flow, external dependencies, and trust boundaries.
```
**解释请求路径：**