飞熊写技术文档最烦的两件事——画架构图 + 适配深浅色主题,archify 用一个 Skill 同时干掉。给 Claude Code/Codex CLI/Opencode 一句 ” 用 archify 画 …”, 直接出 5 种图, 自带 dark/light 切换 + 4× 高清导出。
写在前面
写技术文档时, 你会反复撞到同一道墙:“ 我得画个架构图 ”。
打开 draw.io/Mermaid/Excalidraw, 折腾半小时, 出来一张静态 PNG——发到深色背景的 Notion 上发现看不清; 再导出浅色版本发到 GitHub README; 再做一个 2× retina 版本给 Mac 用户; 再做一个 SVG 给前端同事嵌入网页……
archify 是给 ”Agent 用 ” 的设计 ——你只描述系统(英文 / 中文都行),Agent 调 skill 出一个 自包含 HTML(零依赖、单文件、能直接发、能扔 GitHub Pages): 一个开关切深浅、点导出就有 PNG/JPEG/WebP/SVG, 最大 4 倍原生分辨率,带 prefers-color-scheme 的 SVG 跟读者系统主题联动。
它不是另一个 Mermaid 替代品, 而是 Mermaid + 主题切换 + 4× 渲染 + Agent Skill 自动迭代 的一站合体。
一、它解决什么问题
| 痛点 | archify 的解法 |
|---|---|
| 画架构图要学工具 | 描述自然语言(“React → Node API → Postgres/Redis → AWS CloudFront”) |
| 深浅背景发哪都不合适 | HTML 自带一键切换 + SVG 带 @media (prefers-color-scheme)——GitHub README 自动跟读者主题 |
| PNG 模糊,doc 给高清屏就糊 | 原生 4× 渲染(不是 upsampling),PNG/JPEG/WebP/SVG 都给 |
| 截图还得开图床 | 一键复制 PNG 到剪贴板, 直接粘 Slack/Notion/GitHub |
| 改需求来回返工 | 对话迭代——” 加 Redis”” 移 auth 到左边 ”” 改 emerald 色 ” |
| 自己画的图分不清 aws.lambda vs postgres | 语义标签 自动归类(无需图标库) |
| 文档发出去要能纯本地看 | 自包含 HTML, 零依赖——一个文件 200KB, 可直接分享 |
二、项目基本信息
| 字段 | 值 |
|---|---|
| GitHub | tt-a1i/archify |
| 官网 / 预览 | tt-a1i.github.io/archify |
| 一句话定位 | Any agent Skill: 描述系统 → 5 种图(架构 / 工作流 / 序列 / 数据流 / 状态生命周期)+ 主题切换 + 4× 高清导出 |
| 作者 | tt-a1i(GitHub user id 53142663), 作者另有 agent-inspect(12 commits)、tokenfolio、chat_edit(290 commits Vue 3.5) 等 AI 玩具 |
| Stars | 3,830 |
| Forks | 376 |
| Watchers | 3,830 |
| Open Issues | 13(相当稳定) |
| License | MIT ✅ |
| 主语言 | JavaScript(7.3 MB) |
| 首次 commit | 2026-04-15 |
| 最近 commit | 2026-07-09(3 个月成熟,3 天前还在迭代) |
| 当前版本 | v2.10.0 |
| Topics | anthropic, architecture-diagram, claude-skill, dark-mode, developer-tools, diagram-as-code, html-diagram, mermaid-alternative, svg, system-design |
| 支持 Agent | Claude / Codex CLI / opencode(一键 npx skills add) |
社区热度 :3.8k+ star 但只有 13 个 open issues——这是非常健康的比例(star/issue ≈ 295:1, 说明文档清晰、bug 少)。“Anomaly”v2.10.0 是个平稳迭代的成熟项目, 不是 hype 速生品。
三、五种图 + 一个 toggle, 覆盖 90% 技术文档场景
3.1 五种 Diagram 类型
| 类型 | 适用场景 | 怎么问 Agent |
|---|---|---|
| Architecture | 系统组件、云资源、数据库、缓存、服务、边界、安全组 | “Draw architecture for [system]” |
| Workflow | 请求生命周期、审批流、tool calls、CI/CD、runbook、事故响应 | “Draw workflow for [process]” |
| Sequence | API 调用链、请求生命周期、cache fallback、auth 检查、async trace | “Draw sequence for [call chain]” |
| Data Flow | 数据管道、ETL/ELT、分析事件、PII 隔离、仓库同步、lineage | “Draw dataflow for [pipeline]” |
| Lifecycle | 状态机、order/task/deployment/agent-run 生命周期、等待态、重试 | “Draw lifecycle for [object]” |
最大亮点 :lifecycle-agent-run(Agent Run 状态机) 是写“ 我的 OpenClaw Agent 怎么从 Queued→Planning→Executing→Reviewing 然后可能 Paused/Blocked/Failed/Cancelled/Completed” 这种 AI 工具文档的完美帮手。
3.2 一键导出菜单:Copy PNG + 4 种格式 + 4× 分辨率
| 能力 | 细节 |
|---|---|
| 复制 PNG 到剪贴板 | 一点就 paste 到 Slack/Notion/GitHub |
| PNG / JPEG / WebP | 原生 4× 渲染(不是 upsampling)——3840×2160 Retina 直接给 |
| SVG | 真矢量,带 prefers-color-scheme 媒体查询 ——同一 SVG 在深色 GitHub 自动暗, 在浅色 Notion 自动亮, 一文件对双主题 |
| HTML 自包含 | 零依赖,200KB, 可发邮件, 可丢 S3, 可挂 GitHub Pages, 不需要 CDN |
Mermaid 没这个能力——Mermaid 出 PNG 要靠 mermaid-cli 跑 puppeteer, 导出 2× retina 还要额外配置,SVG 没 prefers-color-scheme, 深浅 GitHub READMe 你得维护两份 PNG。
3.3 主题切换:Dark/Light 一键 + 持久化
- 一个按钮在 dark/light 之间切换
- 状态持久化(localStorage 跨刷新)
- SVG 跟系统主题——
@media (prefers-color-scheme: dark)让同一 SVG 文件自动适配读者设备 - URL hash 控制:
?theme=light强制浅色,?theme=dark强制深色——确定性截图(CI/CD 文档图稳定)
3.4 校验循环: 不是 ” 画完就完 ”, 有 4 步自检
archify 输出的图不是直接渲染, 而是走完这条流水线:
自然语言描述
↓
Skill prompt → JSON IR(中间表示)
↓
JSON Schema 校验
↓
Layout 检查
↓
HTML/SVG artifact 校验
↓
渲染输出 → 用户
↓
不通过就迭代修正
这是 Agent Skill 模式 ——不是 ”Mermaid 调一次玩玩 ”, 而是 有自检有迭代的工业级输出。同样适合放进 CI 文档生成流水线。
四、跟四个主流方案的差异化对比
| 维度 | archify | Mermaid | draw.io / diagrams.net | Excalidraw | PlantUML |
|---|---|---|---|---|---|
| 类型 | Agent Skill(JS) | JS 库 /CLI | Web/ 桌面 GUI | 手绘风白板 | Java CLI/GUI |
| 输入 | 自然语言 | Mermaid DSL | 鼠标拖拽 | 鼠标手绘 | PlantUML DSL |
| 主题切换 | ✅一键 + SVG 跟随系统 | ❌ 要重新 render | ⚠️ 自带但导出不联动 | ❌ | ⚠️ 需 skinparam |
| 4× 高清导出 | ✅ 原生 4× 渲染 | ❌ 只到 2× | ⚠️ 需手动设 | ❌ | ⚠️ 取决于工具链 |
| SVG + 媒体查询 | ✅ prefers-color-scheme |
❌ | ⚠️ 不跟主题 | ❌ | ❌ |
| 复制 PNG 剪贴板 | ✅ 一键 | ❌ | ⚠️ 需手动 | ⚠️ 需手动 | ❌ |
| 自包含 HTML | ✅ 200KB 零依赖 | ❌ Mermaid 在线渲染要 JS | ❌ | ❌ | ❌ |
| Agent Skill 集成 | ✅ npx skills add |
⚠️ 自己写 wrapper | ❌ | ❌ | ⚠️ |
| 5 种图类型 | 架构 / 工作流 / 序列 / 数据流 / 生命周期 | 流程 / 序列 / 类 / 状态 /ER/Gantt | 通用(取决于用户) | 通用 | 类 / 序列 / 用例 / 活动 / 组件 |
| 迭代修改 | ✅ 对话改图(“ 加 Redis”” 移左 ”) | ❌ 改代码重 render | ✅ 拖拽 | ✅ 拖拽 | ❌ 改文本重 render |
| 学习成本 | 0(描述就行) | 中(学 DSL) | 中(学 GUI) | 中(学手绘) | 中(学 DSL) |
| License | MIT ✅ | MIT | Apache-2.0 | MIT | MIT/GPL/ 双协议 |
| Stars | 3.8K | 80K+(mermaid-js/mermaid) | — | 95K+ | 11K+ |
archify 的独特定位 : 专门为 Agent 设计的 diagram 工具, 而 Mermaid/draw.io 是为人设计的。Agent 工作流的 ” 自然语言描述 → 图 ” 是关键差异——你说 ”React → Node API → Postgres/Redis → CloudFront”, 它出图;Mermaid 这套你要写:
graph LR
A[React] --> B[Node API]
B --> C[(Postgres)]
B --> D[(Redis)]
E[CloudFront] --> A
一句话总结 :Mermaid 是 ”DSL 描述图 ”,archify 是 ” 自然语言描述 出图, 并自带主题切换 + 4× 导出 ”。
五、3 步跑通实战
5.1 安装(60 秒)
# 1. 给 Claude / Codex CLI / Opencode 装 Skill
npx skills add tt-a1i/archify -g
# 2. (可选)直接在 CLI Agent 里加 skill, 重启加载
# Claude: paste 到 ~/.claude/skills/
# Codex: ~/.codex/skills/
# 3. 调一下就行 —— 不需要单独命令,Agent 集成
或者 : 打开 tt-a1i.github.io/archify, 直接在线试(5 种图都有 example HTML)。
5.2 实战 1 — 画 Otto Robot 架构图
给 Claude Code 的 prompt:
Use archify to draw the architecture of Otto Robot:
A Python voice agent running on Raspberry Pi that listens via a USB microphone array,
wakes on keyword, sends audio to an OpenAI Whisper endpoint for STT, runs an LLM agent
for command parsing (Claude Haiku), returns control signals to a hardware board over GPIO,
and a Python TTS module (Piper) that streams audio back via a USB DAC.
Persistence: SQLite for wake-word config and chat history.
Edge fallback: rule-based command parser if LLM times out.
输出示例(架构):
[USB Mic Array] → [Wake Word (Porcupine)]
│
keyword hit
↓
[Audio Buffer]
↓
[Whisper STT] ──→ [Transcript]
│
↓
[Claude Haiku Agent]
│ ↑
timeout ↓ │ │ result
[Rule-based Parser] │
↓ │
[GPIO Control → PWM/Motor Drivers]
│
[Piper TTS] ←─ [Response Text]
↓
[USB DAC → Speaker]
[SQLite] ←─→ [Wake word config / chat history]
自己看: 这就是 archify 的输入——一段自然语言, 出 HTML(点开有主题切换 + 4× 导出)。
5.3 实战 2 — 写 OpenClaw Agent 生命周期文档
Use archify to draw the lifecycle of an Agent Run:
- Starts at Queued
- Moves through Planning, Executing, Reviewing
- Can pause at Needs Approval
- Waits at Blocked
- Retries after Failed (max 3)
- Ends at Cancelled or Expired (TTL 5 min)
- Finishes at Completed
输出五状态 + 转移线 + 重试路径 + 终态——lifecycle 图模板自带。
直接给你成品 lifecycle-agent-run.html, 附代码:
# 下载示例
open https://tt-a1i.github.io/archify/examples/lifecycle-agent-run.html
5.4 实战 3 — 改图(对话迭代)
# 改颜色
"Make the auth component pink, the API blue"
# 加组件
"Add Redis between Node API and Postgres for session cache"
# 移位置
"Move the API gateway to the top-left"
# 改布局
"Switch to grid layout, 3 columns"
# 加连接
"Add an arrow from analytics to Postgres labeled 'daily sync'"
Agent 会自动改 HTML/JSON IR, 重新走校验循环, 出新版 ——这是 Agent Skill 模式独有的“ 对话改图 ” 能力,Mermaid/draw.io 都没有。
六、5 大特殊能力(超出画图本身)
6.1 SVG 自动适应 GitHub dark/light theme
这是个杀招——archify 导出的 SVG 内嵌 @media (prefers-color-scheme: dark) {...}, 意味着:
<!-- 单文件 SVG, 同时适应深浅主题 -->
<svg viewBox="..." xmlns="...">
<style>
rect {fill: #F0F3F7;}
@media (prefers-color-scheme: dark) {rect { fill: #0d1117;}
}
</style>
...
</svg>
同一个 SVG 文件:
– 在 GitHub 浅色主题显示浅色版
– 在 GitHub dark mode 自动切换深色版
– 在 Notion / Obsidian / 网页里自动跟读者设备
Mermaid 的 SVG 没这个能力 ——你得维护 architecture.svg + architecture-dark.svg 两份, 然后用 <picture> 标签包起来。archify 一个文件搞定。
6.2 4× 原生渲染, 不是简单 upsample
| 工具 | 4× 实现 | 锐度 |
|---|---|---|
| archify | 原生高分辨率画布渲染 | 真 Retina 锐利 |
| Mermaid CLI | 需配 --scale 2×, 无内建 4× |
边缘略糊 |
| draw.io | 导出 PNG @2× | 字号小就糊 |
| Excalidraw | 导出 @2× | 同样 |
| PlantUML | 取决于输出格式 | 看工具链 |
对 4K 显示器用户 / 打印 PDF 文档 / 营销物料:archify 的 4× 一次性干完。
6.3 语义标签自动归类(无需图标库)
"Postgres" → 数据库样式
"Redis" → 缓存样式
"aws.lambda" → AWS 服务样式
"github-actions" → CI/CD 样式
"openai" → AI 服务样式
"kubernetes" → 容器编排样式
不需要你拖图标——描述时用语义词,archify 知道它该长啥样。
6.4 ?theme=dark URL hash 控制, 适合 CI/CD
# 截图工具用
https://...examples/web-app.html?theme=light&openExport=1
https://...examples/web-app.html?theme=dark&openExport=1
适合放进 CI/CD 文档流水线——每次 release 跑一遍, 自动抓 dark + light 两份图, 确保文档与代码同步。
6.5 自包含 HTML, 可邮件发 /S3 上传 /GitHub Pages
| 场景 | 怎么做 |
|---|---|
| Slack/ 微信发同事 | 直接拖 HTML, 双击浏览器看,200KB |
| 个人 repo GitHub Pages | 推 docs/ 目录, 设 Pages source,3 分钟有网站 |
| 内网 Wiki | 拖到 Confluence/Notion/ 语雀附件 |
| PDF 论文插图 | 导出 SVG,Inkscape/Illustrator 编辑 |
Mermaid 这种 JS 库做不到——必须有 mermaid-cli 渲染环境, 要网络加载 mermaid.js, 要 SVG 容器。
七、风险与坑
- Agent Skill 安装——
npx skills add依赖 Agent 平台对 Skill 的原生支持。Claude Code/Codex CLI/Opencode 都 OK, 但自己写的 Agent 框架要先集成 Skill 加载机制 - 自然语言模糊性 ——描述不精确时 Agent 可能猜错组件位置 / 连接方向, 需要二次对话修正(但还好, 对话改图 是 archify 的核心能力)
- 图标精度 ——语义标签(w/aws.lambda) 不是完整图标库, 跟 Lucide/Heroicons 那种全家桶比 图标细节简单, 适合 ” 块状架构图 ” 不适合 ” 细颗粒度 UI 设计 ”
- 3.8k star 但 13 issues ——健康但偏小众,Star 跟 mermaid 80K / Excalidraw 95K 有量级差距, 生态还在建立
- 作者 tt-a1i 是个人作者(非公司 / 组织),GitHub 上多个 AI 玩具 project(agent-inspect/tokenfolio/chat_edit), 核心维护依赖单人精力
- JavaScript 单文件 7.3MB ——生成的 HTML 200KB 还能接受, 但 npm install 后端磁盘占用还好, 生产环境没压力
- 不是 Mermaid 直接替代 ——archify 不支持类图 /ER 图 /Gantt 等 所有 UML 图; 只覆盖 5 种——架构 / 工作流 / 序列 / 数据流 / 生命周期
- 没有动画 ——lifecycle 图是静态状态机, 不能像 draw.io 那样演示状态转换动画
八、总结
三个最值得装的理由
- Agent 友好 ——
npx skills add一键,Claude/Codex/Opencode 直接 describe → diagram, 不用写 Mermaid DSL, 不用开 GUI, 是 AI 原生时代的画图工具 - 双主题真省事 ——一个 HTML 文件 + 一个 SVG 文件, 自动跟读者设备主题, 告别 ” 两份 PNG +
<picture>“ 的维护噩梦 - 4× + 复制 PNG——原生高分辨率渲染 + 一键剪贴板,Mac/4K 屏 / 营销物料都清晰, 粘 Slack/Notion 一步到位
一句话 ” 先试一周 ”
给 Claude Code 装 archify, 接下来一周每次要画技术架构图都让它出——你会发现 写文档的 ” 画图环节 ” 从 30 分钟缩到 30 秒, 双主题 /Retina 适配全自动。
什么时候 不用 archify
| 场景 | 用 |
|---|---|
| 类图 /ER 图 /Gantt/UI wireframe | Mermaid(archify 不支持) |
| 手绘风团队白板讨论 | Excalidraw |
| 跟客户 PPT 配高保真插图 | Figma + 自己的设计 |
| CI/CD 自动文档图(企业级稳定性) | 暂不建议, 等 archify 出 v3+ 稳定再考虑 |
| 离线 / 内网无 Claude Code | Mermaid CLI / PlantUML(本地 DSL) |
参考
- tt-a1i/archify GitHub | Archify 官网 / 预览 | 中文 README
- Topics:
architecture-diagram,claude-skill,dark-mode,diagram-as-code,mermaid-alternative,system-design - 同作者: agent-inspect / tokenfolio / chat_edit
- 对比方案: Mermaid / draw.io / Excalidraw / PlantUML
- 实战 archify 命令:
npx skills add tt-a1i/archify -g - 本站兄弟调研:OpenClaw 调研系列 (lifecycle/Agent Run 实际用法)