英文 · 简体中文

Archify

在聊天中生成优美的架构、技术工作流、序列、数据流和生命周期图。切换深色/浅色主题。复制到剪贴板或导出清晰高达4倍分辨率的PNG/JPEG/WebP/SVG。

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

• 无需设计技能 — 用英文描述您的架构，即可得到图表
• 工作流、序列、数据流和生命周期图同样支持 — 可绘制技术流程、审批、工具调用、CI/CD、runbook、请求调用链、数据管道、PII 边界和状态机
• 内置主题切换 — 一键切换深色/浅色，跨会话持久化
• 复制 PNG 到剪贴板 — 一键操作，直接粘贴到 Slack / Notion / GitHub
• 超清晰图像导出 — 以高达源分辨率4倍的原生渲染 PNG / JPEG / WebP（无上采样模糊），或导出 SVG 获得真正矢量图
• SVG 跟随系统深色/浅色 — 导出的 SVG 同时包含两组变量 + @media (prefers-color-scheme)，将其放入 GitHub README 后即可跟随读者的颜色偏好（无需再用两个 PNG 包裹在 <picture> 中）
• 内置验证循环 — 基于渲染器的图表经过 JSON schema 验证、布局检查、HTML/SVG 构件检查和针对性迭代
• 语义化技术标签 — 用 aws.lambda、postgres、redis、github-actions、openai 等描述组件；Archify 将其映射到正确的视觉类别，无需完整的图标库
• 自包含 HTML — 生成的文件零依赖，直接发送即可分享
• 通过聊天迭代 — “添加 Redis”、“将认证移到左边”、“为 API 使用翡翠色”

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

60 秒开始使用:

npx skills add tt-a1i/archify -g

然后向您的 agent 提问：使用 archify 绘制此存储库的运行时架构。

预览

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

深色	浅色

导出菜单 — 复制 PNG 到剪贴板及 4 种下载格式（所有栅格导出可达源分辨率的 4 倍）：

示例文件：examples/web-app.html。下载或克隆仓库，本地打开文件，然后按 T 切换主题或按 E 打开导出。

快速开始

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. 请求一个清晰的视图

先从概览入手，而不是让一个图表解释整个仓库：

分析此仓库，然后使用 archify 创建一个高级运行时架构图。
显示 8–12 个核心组件、一个主要请求或数据路径、外部依赖和信任边界。
将支持细节放在卡片中，而不要添加更多连线。

对于聚焦的流程：

使用 archify 绘制此登录流程：浏览器 -> Web 应用 -> API -> JWT 验证 ->
Redis 会话查找 -> PostgreSQL 回退。将缓存未命中路径设为次要。

3. 在聊天中优化

在会话中源 JSON 仍可用时，要求进行针对性修改，例如 添加 Redis、将认证移到左边 或 突出显示回滚路径。

Archify 返回一个自包含的 HTML 文件，可在任何现代浏览器中打开，并导出为 PNG、JPEG、WebP 或 SVG。

图表类型

选择与您要回答的问题相匹配的视图：

类型	最佳用途	在提示词中包含
架构	组件、服务、存储、边界	范围、核心组件、主要路径
工作流	CI/CD、审批、工具调用、runbook	参与者、顺序、分支、异常
序列	API 调用、缓存回退、认证、异步追踪	调用方、被调用方、返回、时机
数据流	管道、血统、PII、下游消费者	源、转换、存储、边界
生命周期	状态机、重试、等待、终态	状态、事件、重试与取消路径

架构示例：

• examples/web-app.html — 紧凑的 SaaS 架构
• examples/archify-repo.html — Archify 的技能 → JSON IR → 渲染器管道
• examples/archify-repo-grid.html — 显式 row / col 网格定位
• examples/maka-architecture.html — 第三方桌面 agent 工作台

工作流使用泳道、清晰的主路径和克制的次要分支。

序列聚焦于一段时间内的一个交互。

数据流显式标注移动、转换和敏感边界。

生命周期区分正常进展、等待状态、重试和最终结果。

为什么选择 Archify

• 布局判断优于通用自动布局 — agent 为所讲述的故事选择层级、间距、路径和重点。
• 类型化 JSON IR — 架构、工作流、序列、数据流和生命周期图使用基于渲染器的 schema。
• 交付前验证 — schema、布局、HTML 和 SVG 检查可在尽早捕获畸形或不可读的输出。
• 可移植的输出 — 一个 HTML 文件，无需服务器或框架，当外部字体不可用时使用本地字体回退。
• 语义化技术标签 — 诸如 postgres、redis、aws.lambda 和 github-actions 等名称引导视觉分类，无需笨重的图标运行时。

Archify 并非通用绘图编辑器或 Mermaid 主题。它的职责是将技术意图转化为精良的沟通产物。

安装选项

主要安装命令是：

npx skills add tt-a1i/archify -g

相同的 archify.zip 也可手动安装：

界面	安装位置或方法	能力
Claude Code	~/.claude/skills/ 或 .claude/skills/	完整渲染器 + 验证工作流
Codex CLI	~/.agents/skills/ 或 .agents/skills/	完整渲染器 + 验证工作流
opencode	~/.config/opencode/skills/、.opencode/skills/ 或 .agents/skills/	完整渲染器 + 验证工作流
Claude.ai	在「设置 → 能力 → 技能」下上传 archify.zip	取决于沙箱中的 Node.js 访问权限
项目知识	将 archify.zip 上传至项目	仅限提示驱动的架构模式

手动安装即将压缩包解压到对应的目录。打包好的技能无需执行 npm install。

工作原理

基于渲染器的图表遵循一个小巧且可检查的循环：

步骤	发生了什么
生成 JSON IR	智能体创建类型化描述，而非手工编辑最终的 SVG 标记。
验证	内置的独立验证器在不安装运行时依赖的情况下检查 schema。
渲染	选定的渲染器生成 HTML/SVG 产物。
检查	布局和产物检查用于捕获无效坐标、格式错误的 SVG 以及不安全的路由。
迭代	对 JSON IR 应用有针对性的更改，同时保持无关结构稳定。

打包的 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

可选跟踪动画可为演示启用：

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

动画遵循 prefers-reduced-motion。省略 animation 则得到静态图表。

使用输出

在现代化浏览器中打开生成的 HTML。右上角的控件提供：

• 主题 — 切换深色/浅色模式。快捷键：T。
• 导出 — 复制 PNG 或下载 PNG、JPEG、WebP、SVG。快捷键：E。

格式	用途
复制 PNG	Slack、Notion、GitHub 评论及快速审查
PNG / JPEG / WebP	幻灯片、文档、网站和打印
SVG	README、博客、Figma、Illustrator 以及无损缩放

栅格导出以最高安全分辨率本地渲染，最高可达 4 倍。过大的图表会自动降级以保持在浏览器画布限制内。

导出的 SVG 包含深色/浅色变量以及 prefers-color-scheme，因此单个 SVG 可跟随读者的系统主题。

有用的 URL 参数：

• ?theme=light 或 ?theme=dark — 强制设定起始主题。
• ?openExport=1 — 加载时打开导出菜单。

WebP 和剪贴板支持取决于浏览器能力。当无法加载外部字体时，HTML 会使用本地字体回退。

提示模式

仓库概览

绘制此仓库的运行时架构，核心组件不超过 12 个。
显示主要请求路径、外部系统和信任边界。将实现细节移至卡片中。

CI/CD 工作流

绘制 CI/CD 工作流：pull request -> 测试 -> 审批 -> 构建镜像 -> 预发布 ->
冒烟测试 -> 生产环境。将回滚显示为次要失败路径。

数据血缘

从 Web 和移动端事件出发，经过 Consent Gate、Kafka、数据仓库、特征存储，
最终到达仪表板和 ML 消费者，绘制数据流图。标记 PII 边界。

参考

语义标签指导颜色和分组：

示例	分类
react, nextjs, ios, browser	前端
node, go-service, python-worker, api-gateway	后端
postgres, redis, s3, bigquery, snowflake	数据和存储
aws.lambda, gcp.pubsub, azure.functions, kubernetes	云和基础设施
auth0, oauth, vault, security-group	安全
kafka, rabbitmq, sqs, nats	消息
stripe, github-actions, openai, slack	外部系统

请参阅 schema 参考 了解渲染器输入，以及 CHANGELOG.md 了解发布历史。

当前状态和路线图

Archify 2.10 已经在所有五种基于渲染器的模式中使用了类型化 JSON IR。当前工作重点是稳定本地编辑、改进布局诊断，并确保生成的产物易于检查和共享。

请参阅 ROADMAP.md 了解计划中的工作和设计边界。自动 Mermaid 解析、通用自动布局、托管共享服务以及所见即所得编辑器目前不是目标。

归属

Archify 是 Cocoon-AI/architecture-diagram-generator v1.0 的一个分支和重写版本，原作者为 Cocoon AI。

原始视觉语言仍归功于那个项目。Archify 2.x 增加了主题、导出工具、类型化渲染器、验证、可访问性以及统一的 CLI。两个项目均使用 MIT 许可证。

许可证

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

贡献

欢迎提交 Issue、Pull Request 和共享图表。在报告生成输出问题时，请尽可能包含提示词、图表类型和 Archify 版本。