Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Make English README the default

tt-a1i88db70f03a99
diff --git a/README.md b/README.md
index 9e89c01b..ff3dadfd 100644
--- a/README.md
+++ b/README.md
@@ -1,343 +1,337 @@
-![Archify 主视觉](docs/assets/archify-readme-hero.png)
+![Archify product preview](docs/assets/archify-readme-hero.png)
# Archify
-**聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切。导出最高 4× 清晰 PNG / JPEG / WebP / SVG,或直接复制到剪贴板。**
+**Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat. Switch dark / light. Copy to clipboard or export crisp up-to-4× PNG / JPEG / WebP / SVG.**
-Archify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude):你用大白话描述自己的系统或流程,它就把你的描述变成一张做工精细的技术图 —— 一个单文件 HTML,在浏览器里打开就能切主题、复制到剪贴板、导出成各种图片格式。
+Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude) that turns a plain-English description of your system or process into a polished, self-contained technical diagram — a single HTML file you can open, toggle themes on, copy to the clipboard, and export at maximum resolution.
-- **不需要会画图** —— 把组件和连接关系说给 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>` 包起来)
-- **单文件 HTML** —— 生成的 HTML 零运行时依赖,发一个文件就能分享
-- **聊天迭代** —— "把 Redis 挪到左边"、"鉴权服务换成玫红"、"加个 Kafka"
+- **No design skills needed** — describe your architecture in English, get a diagram
+- **Workflow, sequence, data-flow, and lifecycle diagrams too** — technical flows, approvals, tool calls, CI/CD, runbooks, request call chains, data pipelines, PII boundaries, and state machines can be drawn
+- **Built-in theme toggle** — one click between dark and light, persists across sessions
+- **Copy PNG to clipboard** — one click, paste straight into Slack / Notion / GitHub
+- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at up to 4× source resolution (no upsampling blur), or SVG for true vector
+- **SVG follows system dark/light** — exported SVGs ship with both variable sets + `@media (prefers-color-scheme)`, so dropping one into a GitHub README makes it follow the reader's color preference (no more two PNGs wrapped in `<picture>`)
+- **Self-contained HTML** — the generated file has zero dependencies, share by sending it
+- **Iterate by chat** — "add Redis", "move auth to the left", "use emerald for the API"
![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)
![Claude](https://img.shields.io/badge/Claude-Skill-7C3AED?style=flat-square)
![Version](https://img.shields.io/badge/version-2.6.0-0891b2?style=flat-square)
-**[在线落地页 → tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)**
+**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)
-<p align="right"><a href="./README_EN.md">English</a></p>
+<p align="right"><a href="./README_ZH.md">中文</a></p>
-## 预览
+## Preview
-同一张图,两套主题,一键切换:
+Same diagram, two themes, one click to switch:
-| 深色 | 浅色 |
+| Dark | Light |
|---|---|
-| ![深色主题](docs/assets/archify-dark.png) | ![浅色主题](docs/assets/archify-light.png) |
+| ![Dark theme](docs/assets/archify-dark.png) | ![Light theme](docs/assets/archify-light.png) |
-Export 菜单 —— 复制到剪贴板 + 四种格式下载:
+The Export menu — Copy PNG to clipboard plus 4 download formats (all raster exports at up to 4× source resolution):
-![导出菜单](docs/assets/archify-menu.png)
+![Export menu](docs/assets/archify-menu.png)
+Live example: [`examples/web-app.html`](examples/web-app.html) — open in a browser, press <kbd>T</kbd> to toggle theme, <kbd>E</kbd> to open Export. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.
-想亲自玩一下:克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html),按 <kbd>T</kbd> 切主题,<kbd>E</kbd> 打开导出菜单。给 URL 加上 `?theme=light` 或 `?openExport=1` 可以强制初始状态。
+## Diagram types
-## 图表类型
+Archify now has five primary outputs:
-Archify 现在有五种主要输出:
-
-| 类型 | 适合画什么 | 怎么用 |
+| Type | Good for | How to ask |
|---|---|---|
-| **Architecture** | 系统组件、云资源、数据库、缓存、服务边界、安全组 | 直接描述系统结构 |
-| **Workflow** | 请求生命周期、审批流程、工具调用、CI/CD、运维 runbook、事故响应 | 说明参与方、步骤顺序、关键分支 |
-| **Sequence** | API 调用链、请求生命周期、缓存回源、鉴权、异步 trace、服务交互 | 说明谁调用谁、先后顺序、返回路径 |
-| **Data Flow** | 数据管线、ETL/ELT、埋点、PII 隔离、仓库同步、数据血缘、下游消费 | 说明数据来源、处理阶段、存储位置、敏感边界和消费方 |
-| **Lifecycle** | 状态机、订单/任务/部署/Agent run 生命周期、等待态、重试、取消、超时、终态 | 说明对象有哪些状态、哪些事件触发转移、哪些状态是终态 |
+| **Architecture** | System components, cloud resources, databases, caches, services, boundaries, security groups | Describe the system structure |
+| **Workflow** | Request lifecycles, approval flows, tool calls, CI/CD, runbooks, incident response | Describe participants, step order, and key branches |
+| **Sequence** | API call chains, request lifecycles, cache fallback, auth checks, async trace, service interactions | Describe who calls whom, in what order, and what returns |
+| **Data Flow** | Data pipelines, ETL/ELT, analytics events, PII isolation, warehouse sync, lineage, downstream consumers | Describe sources, processing stages, storage, sensitivity boundaries, and consumers |
+| **Lifecycle** | State machines, order/task/deployment/agent-run lifecycles, wait states, retries, cancellation, timeout, terminal states | Describe states, transition events, retry paths, and terminal outcomes |
-Workflow 不是通用流程图的替代品,它更偏“技术沟通图”:有泳道、有语义颜色、有主路径和异步/审批/观测路径。比如:
+Workflow is not trying to replace every general-purpose flowchart. It is a technical communication diagram: swimlanes, semantic colors, a clear happy path, and secondary async / approval / trace paths.
-```
-用 archify 画一个 workflow:
-用户提交请求 -> Agent 规划 -> 需要审批时进入 Approval Gate -> 调工具 -> 记录 trace -> 返回结果
+```text
+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)。
+Open the example here: [`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html).
-![Workflow 示例](docs/assets/archify-workflow.png)
+![Workflow example](docs/assets/archify-workflow.png)
-Sequence 用来解释更细的交互顺序,比如:
+Sequence diagrams explain a narrower interaction over time:
-```
-用 archify 画一个 sequence diagram:
-用户打开页面,前端请求 API,API 校验 JWT,读取 Redis,缓存未命中则查 Postgres,返回结果并写入 trace。
+```text
+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)。
+Open the example here: [`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html).
-![Sequence 示例](docs/assets/archify-sequence.png)
+![Sequence example](docs/assets/archify-sequence.png)
-Data Flow 适合解释“数据资产怎么走”,比如:
+Data Flow diagrams explain how data assets move and change:
-```
-用 archify 画一个 data flow:
-Web 和 Mobile 上报埋点,Edge API 收集事件,Consent Gate 过滤 PII,Kafka 承接事件流,
-Warehouse 存分析表,Feature Store 做每日特征,Dashboard 和 ML Model 消费下游数据。
+```text
+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)。
+Open the example here: [`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html).
-![Data Flow 示例](docs/assets/archify-dataflow.png)
+![Data Flow example](docs/assets/archify-dataflow.png)
-Lifecycle 用来解释“对象状态怎么变”,比如:
+Lifecycle diagrams explain how an object changes state:
-```
-用 archify 画一个 lifecycle diagram:
-Agent Run 从 Queued 进入 Planning,再进入 Executing 和 Reviewing。需要人工确认时进入
-Needs Approval,缺少输入时进入 Blocked;工具失败可以 Failed 后重试,用户取消进入 Cancelled,
-超时进入 Expired,成功则进入 Completed。
+```text
+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)。
+Open the example here: [`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html).
-![Lifecycle 示例](docs/assets/archify-lifecycle.png)
+![Lifecycle example](docs/assets/archify-lifecycle.png)
-## 版本演进
+## What's new
-Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了一个存在已久的位图升采样 bug,所有光栅导出改为 4× 原生渲染(同时移除了 v2.1 引入的 1×/2×/4× 选择器 —— 那个选择器只是在诱导用户选出更糊的图)。**2.4** SVG 导出升级成双主题自持版 —— 同一个 `.svg` 文件贴在 GitHub README 里,读者切深浅色图会自己跟着切。**2.5** 集中修复类型化渲染器的 bug 并强化 LLM 工程学(校验错误信息带数值阈值和修复建议),SKILL.md 新增 Mermaid 输入指引,字体栈加入 CJK 回退,修复浅色导出泳道配色和 Safari 剪贴板复制,并补齐 golden 测试与 CI。
+Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed a long-standing upsampling bug and made every raster export genuinely sharp at 4× source resolution (the 1× / 2× / 4× selector introduced in 2.1 was removed at the same time — it only encouraged picking a soft-looking scale). **2.4** upgraded the SVG export to a dual-theme self-contained file — drop the same `.svg` into a GitHub README and it follows the reader's dark/light preference automatically. **2.5** is a hardening release: a batch of verified renderer and validation bug fixes (template slot corruption, cross-lane lifecycle overlap detection, light-theme lane colors in PNG/SVG exports, Safari clipboard copy), LLM-ergonomic validation errors with numeric thresholds and fix suggestions, Mermaid accepted as an input dialect (mapped through `SKILL.md` prompts, not a parser), CJK-aware text measurement plus CJK font fallbacks, and a golden-file test suite with CI.
-| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |
+| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |
|---|---|---|---|---|---|---|---|
-| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 | 同 |
-| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 | **浅色导出泳道配色修复** |
-| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)| 同(泳道配色修复)|
-| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(最高 4×)| 同 | **Safari 修复** |
-| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 | 同 |
-| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 | 同(+ 菜单 a11y 修复)|
-| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 | 同 |
-| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 | **+ CJK 字体回退** |
-| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 | 同 |
-| 类型化渲染器 + schema 校验 | — | — | — | — | — | — | **✓(含测试与 CI)** |
-
-## 快速上手
-
-### 1. 安装 skill
-
-> 需要 Claude Pro / Max / Team / Enterprise 套餐,或 Claude Code。
-
-**Claude.ai:**
-1. 下载 [`archify.zip`](archify.zip)
-2. 进入 **Settings → Capabilities → Skills**
-3. 点 **+ Add**,上传 zip
-4. 打开开关
-
-![Claude Skills 设置页](docs/assets/claude-skills-settings.png)
-
-**Claude Code CLI:**
+| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same |
+| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** |
+| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) |
+| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** |
+| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same |
+| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) |
+| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same |
+| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** |
+| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same |
+| Typed renderers + schema validation | — | — | — | — | — | — | **Yes (with tests & CI)** |
+
+## Quick start
+
+### 1. Install the skill
+
+> Requires Claude Pro, Max, Team, or Enterprise plan (or Claude Code).
+
+**Claude.ai:**
+1. Download [`archify.zip`](archify.zip)
+2. Go to **Settings** -> **Capabilities** -> **Skills**
+3. Click **+ Add** and upload the zip file
+4. Toggle the skill on
+
+**Claude Code CLI:**
```bash
-# 全局(所有项目可用)
+# Global (all projects)
unzip archify.zip -d ~/.claude/skills/
-# 或者仅当前项目
+# Or project-local
unzip archify.zip -d ./.claude/skills/
```
-类型化渲染器(workflow / sequence / dataflow / lifecycle)依赖 ajv 做 schema 校验,需要在 skill 目录执行一次 `npm install`。首次使用时 Claude 会按 `SKILL.md` 的 Setup 指引自动安装;也可以自己先装好:
+The typed renderers (workflow / sequence / dataflow / lifecycle) rely on ajv for schema validation, which takes a one-time `npm install` in the skill directory. Claude installs it automatically on first use, following the Setup instructions in `SKILL.md` — or run it yourself:
```bash
cd ~/.claude/skills/archify && npm install
```
-没装依赖时渲染器会跳过 schema 校验(布局检查仍然运行)。
+Without the dependency the renderers skip schema validation (layout checks still run).
-**Claude.ai Projects:**
-把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。
+**Claude.ai Projects (alternative):**
+Upload [`archify.zip`](archify.zip) to your Project Knowledge.
-三种安装方式的能力差异:
+What each install surface can do:
-| 安装方式 | 能力 |
+| Install surface | Capability |
|---|---|
-| **Claude Code** | 完整 —— 可运行类型化渲染器 + schema 校验 |
-| **Claude.ai 上传 zip** | 通常可用 —— 取决于沙箱能否 `npm install`,一般可以 |
-| **Project Knowledge** | 仅架构模式 —— 不执行代码,纯 prompt 驱动 |
+| **Claude Code** | Full — runs the typed renderers + schema validation |
+| **Claude.ai (zip upload)** | Usually full — depends on whether the sandbox can `npm install`, which it typically can |
+| **Project Knowledge** | Architecture mode only — no code execution, purely prompt-driven |
-### 2. 准备系统描述
+### 2. Describe your system
-下面几种都可以:
+Any of these work:
-**让 AI 分析你的代码仓库:**
+**Have AI analyze your codebase:**
```
-分析这个代码仓库,描述系统架构。包括所有主要组件、它们之间怎么连接、
-用了什么技术栈,以及任何云服务或第三方集成。用列表格式,方便画图。
+Analyze this codebase and describe the architecture. Include all major
+components, how they connect, what technologies they use, and any cloud
+services or integrations. Format as a list for an architecture diagram.
```
-**自己写一段:**
+**Write it yourself:**
```
-- React 前端调 Node.js API
-- PostgreSQL 数据库
-- Redis 做缓存
-- 部署在 AWS 上,用 CloudFront 做 CDN
+- React frontend talking to a Node.js API
+- PostgreSQL database
+- Redis for caching
+- Hosted on AWS with CloudFront CDN
```
-**或者让 Claude 给个典型架构:**
+**Or ask for a typical architecture:**
```
-一个典型的 SaaS 应用架构是什么样的?
+What's a typical architecture for a SaaS application?
```
-### 3. 让 Claude 调用 skill
+### 3. Ask Claude to use the skill
```
-用 archify skill 帮我生成一张架构图:
+Use your archify skill to create an architecture diagram from this description:
-[粘贴你上面准备的描述]
+[PASTE YOUR ARCHITECTURE DESCRIPTION HERE]
```
-完事。Claude 会生成一个 HTML 文件,浏览器打开就能看。想改就接着聊:「加个 Redis」、「把 Postgres 换成 MySQL」、「鉴权那条路径高亮一下」。
+That's it. Claude generates an HTML file you can open in any browser. Iterate by chat: "add Redis", "swap Postgres for MySQL", "highlight the auth path".
-## 用生成的 HTML
+## Using the output
-浏览器打开文件,右上角会有两个按钮:
+Open the generated HTML in any browser. Top-right you'll see two buttons:
-- **主题按钮**(Dark / Light)—— 一键切换,持久化保存。快捷键 <kbd>T</kbd>。
-- **Export 菜单** —— 五个操作:复制到剪贴板 + 4 种格式下载。快捷键 <kbd>E</kbd>。
+- **Theme button** (Dark / Light) — one click flip, persisted across sessions. Shortcut: <kbd>T</kbd>.
+- **Export menu** — opens a dropdown with five actions (Copy PNG + download PNG / JPEG / WebP / SVG). Shortcut: <kbd>E</kbd>.
-### Export 菜单
+### Export menu
-| 操作 | 做什么 |
+| Action | What it does |
|---|---|
-| **Copy to clipboard** | 当前图以 PNG 格式直接进系统剪贴板,粘贴到 Slack / Notion / 飞书 / GitHub / Figma |
-| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充(无透明);PNG 保留透明度 |
-| **Download SVG** | 矢量导出,所有样式内联,**双主题自持**。内嵌了 dark + light 两套 CSS 变量 + `@media (prefers-color-scheme)` 规则 —— 同一个 `.svg` 贴到 GitHub README / 博客,读者切深浅色图自己跟着切。可以在 Figma / Illustrator 里继续编辑。无损缩放 |
+| **Copy PNG** | Puts a PNG of the current diagram straight on your clipboard. Paste into Slack, Notion, GitHub, Figma. |
+| **Download PNG / JPEG / WebP** | Saves a raster image. JPEG/WebP are painted over the current theme's background (no alpha); PNG keeps transparency. |
+| **Download SVG** | Vector export with all styles inlined, **dual-theme self-contained**. The file ships with both dark and light CSS variable sets plus a `@media (prefers-color-scheme)` rule — drop the same `.svg` into a GitHub README or blog and it follows the reader's preference automatically. Still editable in Figma / Illustrator. Scales losslessly. |
-所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在**最高 4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。
+Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **up to 4× the diagram's intrinsic resolution** (oversized diagrams step down to 3×/2× to stay within browser canvas limits) — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum safe sharpness is always chosen automatically.
-没有倍数选择器 —— 永远最高清晰度,默认也是唯一选项。如果偶尔需要小图,用下面的 URL 参数。
+### Keyboard
-### 键盘快捷键
+- <kbd>T</kbd> anywhere — toggle theme
+- <kbd>E</kbd> anywhere — open the Export menu
+- <kbd>↑</kbd> <kbd>↓</kbd> inside the menu — navigate actions
+- <kbd>Home</kbd> / <kbd>End</kbd> — jump to first / last action
+- <kbd>Enter</kbd> / <kbd>Space</kbd> — activate
+- <kbd>Esc</kbd> — close menu
-- 任何位置按 <kbd>T</kbd> —— 切换主题
-- 任何位置按 <kbd>E</kbd> —— 打开 Export 菜单
-- 菜单里 <kbd>↑</kbd> <kbd>↓</kbd> —— 上下选项
-- <kbd>Home</kbd> / <kbd>End</kbd> —— 跳到第一 / 最后一项
-- <kbd>Enter</kbd> / <kbd>Space</kbd> —— 触发当前项
-- <kbd>Esc</kbd> —— 关闭菜单
+### URL parameters
-### URL 参数
+- `?theme=light` or `?theme=dark` — force a starting theme (deterministic screenshots, share links, embeds)
+- `?openExport=1` — auto-open the Export menu on load (demo / docs screenshots)
-- `?theme=light` 或 `?theme=dark` —— 强制启动主题(确定性截图、分享链接、文档嵌入场景)
-- `?openExport=1` —— 页面加载时自动展开 Export 菜单(演示 / 文档截图)
+### Notes
-### 注意事项
+- **WebP support** depends on your browser's canvas encoder. If unavailable (older Safari), the menu item is dimmed and disabled. PNG and JPEG are universal.
+- **Clipboard support** for images requires `ClipboardItem` + `navigator.clipboard.write` (Chromium, Firefox 127+, Safari 16+). If unavailable, Copy PNG is dimmed.
+- **Fonts in exports**: raster images use the system monospace fallback (`ui-monospace` / Menlo / Consolas) because the sandboxed image-rendering context can't fetch Google Fonts. Install JetBrains Mono locally for pixel-perfect rendering.
-- **WebP 兼容性**:依赖浏览器的 canvas 编码器。老版 Safari 不支持时,菜单项会变灰不可选。PNG 和 JPEG 通用。
-- **剪贴板支持**:图片复制需要 `ClipboardItem` + `navigator.clipboard.write`(Chromium、Firefox 127+、Safari 16+)。不支持时 Copy 选项变灰。
-- **导出字体**:光栅图会使用系统等宽字体回退(`ui-monospace` / Menlo / Consolas),因为沙箱图像渲染上下文拿不到 Google Fonts。本机装了 JetBrains Mono 会自动用上,完全像素级一致。
+## Example prompts
-## 常用 prompt
-
-**Web 应用:**
+**Web app:**
```
-用 archify 画一张架构图:
-- React 前端
+Create an architecture diagram for a web application with:
+- React frontend
- Node.js/Express API
-- PostgreSQL 数据库
-- Redis 缓存
-- JWT 鉴权
+- PostgreSQL database
+- Redis cache
+- JWT authentication
```
-**AWS Serverless:**
+**AWS serverless:**
```
-用 archify 画:
+Create an architecture diagram showing:
- CloudFront CDN
- API Gateway
-- Lambda(Node.js)
+- Lambda functions (Node.js)
- DynamoDB
-- S3 存静态资源
-- Cognito 做鉴权
+- S3 for static assets
+- Cognito for auth
```
-**微服务:**
+**Microservices:**
```
-用 archify 画一张微服务架构图:
-- React Web + 移动端
+Create an architecture diagram for a microservices system with:
+- React web app and mobile clients
- Kong API Gateway
-- 用户服务(Go)、订单服务(Java)、商品服务(Python)
-- PostgreSQL、MongoDB、Elasticsearch
-- Kafka 做事件流
-- K8s 做编排
+- User Service (Go), Order Service (Java), Product Service (Python)
+- PostgreSQL, MongoDB, and Elasticsearch databases
+- Kafka for event streaming
+- Kubernetes orchestration
```
-**数据流 / 埋点分析:**
+**Data flow / product analytics:**
```
-用 archify 画一个 data flow:
-- Web App 和 Mobile SDK 产生 clickstream events
-- Edge API 收集事件
-- Consent Gate 过滤身份信息和 PII
-- Kafka/Event Stream 承接 accepted events
-- Warehouse 存 normalized facts
-- Feature Store 每日生成 feature vectors
-- Dashboards 和 ML Model 消费下游数据
+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:**
```
-用 archify 画一个 lifecycle diagram:
-- 任务从 Queued 开始
-- Planning 生成计划
-- Executing 调用工具
-- Reviewing 做质量检查
-- Needs Approval 和 Blocked 是等待态
-- Failed 可重试,Cancelled / Expired / Completed 是终态
+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
```
-## 语义配色
-
-| 类型 | 颜色 | 用途 |
-|---|---|---|
-| Frontend | 青色 | 客户端 / UI / 终端设备 |
-| Backend | 翠绿 | 服务 / API / 后台进程 |
-| Database | 紫色 | 数据库 / 存储 / AI/ML |
-| Cloud / AWS | 琥珀 | 托管云服务 / 基础设施 |
-| Security | 玫红 | 鉴权 / 安全组 / 加密 |
-| Message Bus | 橙色 | Kafka / RabbitMQ / SNS / 事件总线 |
-| External | 灰色 | 第三方 / 通用外部系统 |
+## Color palette
-每种颜色在深色 / 浅色主题下都有配套取值,切主题会同步切换。
+| Component Type | Color | Use for |
+| -------------- | ------- | --------------------------------- |
+| Frontend | Cyan | Client apps, UI, edge devices |
+| Backend | Emerald | Servers, APIs, services |
+| Database | Violet | Databases, storage, AI/ML |
+| Cloud / AWS | Amber | Cloud services, infrastructure |
+| Security | Rose | Auth, security groups, encryption |
+| Message Bus | Orange | Kafka, RabbitMQ, SNS, event buses |
+| External | Slate | Generic, external systems |
-## 实现细节
+Each color has coordinated dark-mode and light-mode variants that switch together via the theme toggle.
-- **样式模型**:`:root` + `[data-theme="light"]` 上的 CSS 变量;SVG 元素引用语义 class(`c-frontend`、`t-muted`、`a-emphasis` 等)。切换 `<html>` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。
-- **导出流水线**:克隆 SVG,内联 host `<style>`,解析当前主题变量并写入 clone 的 `:root` 规则,然后用 `XMLSerializer` 序列化。光栅格式下,clone 的 `width`/`height` 被设为 `4 × viewBox`,浏览器按目标分辨率原生光栅化矢量;canvas 尺寸对齐 clone 后按自然大小绘制(无位图升采样),`toBlob(mime)` 生成文件。JPEG 会显式补背景色(无 alpha)。如果目标分辨率超过浏览器 canvas 上限,自动降到 3× 或 2×。
-- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 19 KB 嵌入 JS。生成的 HTML 零运行时依赖 —— 无构建步骤、无 JS 框架、无服务端(渲染器本身需要 `npm install`,见安装章节)。
-- **浏览器支持**:任何主流浏览器(Chrome、Safari、Firefox、Edge)。WebP 导出需要 canvas 支持 `image/webp`。
+## Technical details
-## 致谢
+- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.
+- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.
+- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~19 KB of embedded JS. No build step, no JS framework, no server — the generated HTML itself has zero dependencies (the typed renderers need `npm install` for ajv, see [Install](#1-install-the-skill)).
+- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.
-Archify 是 [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator)(MIT,v1.0)的 fork 重写,原作者 [Cocoon AI](mailto:[email protected])。原版精致的视觉语言 —— 配色、网格背景、摘要卡片布局、JetBrains Mono 字体 —— 完整保留。视觉设计功劳归属原作者。
+## Attribution
-Archify 2.x 贡献:
+Archify is a fork / rewrite of [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT, v1.0) by [Cocoon AI](mailto:[email protected]). The original's clean visual design — color palette, grid background, summary-card layout, JetBrains Mono typography — is preserved. All credit for the original aesthetic belongs to them.
-- 模板重构为 CSS 变量主题系统(深色 + 浅色)
-- 主题切换 + `localStorage` 持久化 + `prefers-color-scheme` 默认
-- 内置 PNG / JPEG / WebP / SVG 导出菜单 + 复制到剪贴板
-- 4× 原生光栅化(修复升采样导致的模糊)
-- SVG 导出双主题自持(单文件跟随宿主 `prefers-color-scheme`)
-- 键盘导航 + 可访问性语义
-- 打印样式表 + 本地字体回退
-- 更新后的 `SKILL.md` 引导 Claude 使用 class 化、可主题化的画图方式
+Archify 2.x contributes:
+- Refactor of the template to a CSS-variable theme system (dark + light)
+- Theme toggle + `localStorage` persistence + `prefers-color-scheme` default
+- Built-in PNG / JPEG / WebP / SVG export menu + copy to clipboard
+- 4× native rasterization (fixes upsampling blur)
+- Dual-theme self-contained SVG export (single file follows the host's `prefers-color-scheme`)
+- Keyboard navigation + accessibility semantics
+- Print stylesheet + local-font fallback
+- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams
-两个项目都是 MIT 协议。
+Both projects are MIT-licensed.
-## 路线图
+## Roadmap
-详见 [ROADMAP.md](ROADMAP.md)。
+See [ROADMAP.md](ROADMAP.md).
-下一站是 **v3.0 — JSON IR 稳定迭代**:引入极简 `diagram.json` 中间格式,让 Claude 做局部坐标修改时不会漂移无关组件,同时支持 `git diff` 友好和 theme/palette 不重渲染。
+Next up is **v3.0 — JSON IR stabilization**: a minimal `diagram.json` intermediate format so Claude can make local coordinate edits without drifting unrelated components, with `git diff`-friendly output and theme/palette swaps that don't require re-rendering.
-> **关于 Mermaid 输入:** 已实现 —— `SKILL.md` 现在有专门的「Mermaid as an Input Dialect」章节,把 flowchart / sequenceDiagram / stateDiagram 映射到 workflow / sequence / lifecycle。注意走的是 prompt 而不是 parser:经实验验证(auto-layout + archify CSS 并不比原生 Mermaid 好看多少),自动解析器路线已砍掉。archify 的美学核心是 Claude 的布局判断,不是 CSS —— 贴 Mermaid 代码,Claude 从零布局出 archify 风格图。
+> **About Mermaid import:** the automatic Mermaid parser route was cut after an experiment showed that auto-layout + archify CSS doesn't look meaningfully better than native Mermaid ([experiments/v3-mermaid-validation/RESULT.md](experiments/v3-mermaid-validation/RESULT.md)). Archify's aesthetic core is Claude's layout judgment, not the CSS. You can still paste Mermaid code and have Claude lay out an archify-style diagram from scratch — it goes through the `SKILL.md` prompts, not a parser.
>
-> 原 v2.4 / v2.5 计划(`?exportScale=N`、色盲调色板、分享链接)也已砍掉。理由见 [ROADMAP「Not planned」段落](ROADMAP.md#not-planned)。
+> The former v2.4 / v2.5 plans (`?exportScale=N`, color-blind palettes, share links) were also dropped. See the [ROADMAP "Not planned" section](ROADMAP.md#not-planned) for the rationale.
## License
-[MIT](LICENSE) —— 自由使用、修改、再分发。
+[MIT](LICENSE) — free to use, modify, and distribute.
-## 参与贡献
+## Contributing
-欢迎 issue、PR、分享你画的图。
+Issues, PRs, and shared diagrams welcome.
diff --git a/README_EN.md b/README_EN.md
index 25072bca..ff3dadfd 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -21,7 +21,7 @@ Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-usin
**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)
-<p align="right"><a href="./README.md">中文</a></p>
+<p align="right"><a href="./README_ZH.md">中文</a></p>
## Preview
diff --git a/README_ZH.md b/README_ZH.md
new file mode 100644
index 00000000..92b09b96
--- /dev/null
+++ b/README_ZH.md
@@ -0,0 +1,343 @@
+![Archify 主视觉](docs/assets/archify-readme-hero.png)
+
+# Archify
+
+**聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切。导出最高 4× 清晰 PNG / JPEG / WebP / SVG,或直接复制到剪贴板。**
+
+Archify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude):你用大白话描述自己的系统或流程,它就把你的描述变成一张做工精细的技术图 —— 一个单文件 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>` 包起来)
+- **单文件 HTML** —— 生成的 HTML 零运行时依赖,发一个文件就能分享
+- **聊天迭代** —— "把 Redis 挪到左边"、"鉴权服务换成玫红"、"加个 Kafka"
+
+![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)
+![Claude](https://img.shields.io/badge/Claude-Skill-7C3AED?style=flat-square)
+![Version](https://img.shields.io/badge/version-2.6.0-0891b2?style=flat-square)
+
+**[在线落地页 → tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)**
+
+<p align="right"><a href="./README.md">English</a></p>
+
+## 预览
+
+同一张图,两套主题,一键切换:
+
+| 深色 | 浅色 |
+|---|---|
+| ![深色主题](docs/assets/archify-dark.png) | ![浅色主题](docs/assets/archify-light.png) |
+
+Export 菜单 —— 复制到剪贴板 + 四种格式下载:
+
+![导出菜单](docs/assets/archify-menu.png)
+
+
+想亲自玩一下:克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html),按 <kbd>T</kbd> 切主题,<kbd>E</kbd> 打开导出菜单。给 URL 加上 `?theme=light` 或 `?openExport=1` 可以强制初始状态。
+
+## 图表类型
+
+Archify 现在有五种主要输出:
+
+| 类型 | 适合画什么 | 怎么用 |
+|---|---|---|
+| **Architecture** | 系统组件、云资源、数据库、缓存、服务边界、安全组 | 直接描述系统结构 |
+| **Workflow** | 请求生命周期、审批流程、工具调用、CI/CD、运维 runbook、事故响应 | 说明参与方、步骤顺序、关键分支 |
+| **Sequence** | API 调用链、请求生命周期、缓存回源、鉴权、异步 trace、服务交互 | 说明谁调用谁、先后顺序、返回路径 |
+| **Data Flow** | 数据管线、ETL/ELT、埋点、PII 隔离、仓库同步、数据血缘、下游消费 | 说明数据来源、处理阶段、存储位置、敏感边界和消费方 |
+| **Lifecycle** | 状态机、订单/任务/部署/Agent run 生命周期、等待态、重试、取消、超时、终态 | 说明对象有哪些状态、哪些事件触发转移、哪些状态是终态 |
+
+Workflow 不是通用流程图的替代品,它更偏“技术沟通图”:有泳道、有语义颜色、有主路径和异步/审批/观测路径。比如:
+
+```
+用 archify 画一个 workflow:
+用户提交请求 -> Agent 规划 -> 需要审批时进入 Approval Gate -> 调工具 -> 记录 trace -> 返回结果
+```
+
+本仓库里有一个可打开的示例:[`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html)。
+
+![Workflow 示例](docs/assets/archify-workflow.png)
+
+Sequence 用来解释更细的交互顺序,比如:
+
+```
+用 archify 画一个 sequence diagram:
+用户打开页面,前端请求 API,API 校验 JWT,读取 Redis,缓存未命中则查 Postgres,返回结果并写入 trace。
+```
+
+示例:[`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html)。
+
+![Sequence 示例](docs/assets/archify-sequence.png)
+
+Data Flow 适合解释“数据资产怎么走”,比如:
+
+```
+用 archify 画一个 data flow:
+Web 和 Mobile 上报埋点,Edge API 收集事件,Consent Gate 过滤 PII,Kafka 承接事件流,
+Warehouse 存分析表,Feature Store 做每日特征,Dashboard 和 ML Model 消费下游数据。
+```
+
+示例:[`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html)。
+
+![Data Flow 示例](docs/assets/archify-dataflow.png)
+
+Lifecycle 用来解释“对象状态怎么变”,比如:
+
+```
+用 archify 画一个 lifecycle diagram:
+Agent Run 从 Queued 进入 Planning,再进入 Executing 和 Reviewing。需要人工确认时进入
+Needs Approval,缺少输入时进入 Blocked;工具失败可以 Failed 后重试,用户取消进入 Cancelled,
+超时进入 Expired,成功则进入 Completed。
+```
+
+示例:[`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html)。
+
+![Lifecycle 示例](docs/assets/archify-lifecycle.png)
+
+## 版本演进
+
+Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了一个存在已久的位图升采样 bug,所有光栅导出改为 4× 原生渲染(同时移除了 v2.1 引入的 1×/2×/4× 选择器 —— 那个选择器只是在诱导用户选出更糊的图)。**2.4** SVG 导出升级成双主题自持版 —— 同一个 `.svg` 文件贴在 GitHub README 里,读者切深浅色图会自己跟着切。**2.5** 集中修复类型化渲染器的 bug 并强化 LLM 工程学(校验错误信息带数值阈值和修复建议),SKILL.md 新增 Mermaid 输入指引,字体栈加入 CJK 回退,修复浅色导出泳道配色和 Safari 剪贴板复制,并补齐 golden 测试与 CI。
+
+| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |
+|---|---|---|---|---|---|---|---|
+| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 | 同 |
+| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 | **浅色导出泳道配色修复** |
+| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)| 同(泳道配色修复)|
+| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(最高 4×)| 同 | **Safari 修复** |
+| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 | 同 |
+| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 | 同(+ 菜单 a11y 修复)|
+| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 | 同 |
+| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 | **+ CJK 字体回退** |
+| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 | 同 |
+| 类型化渲染器 + schema 校验 | — | — | — | — | — | — | **✓(含测试与 CI)** |
+
+## 快速上手
+
+### 1. 安装 skill
+
+> 需要 Claude Pro / Max / Team / Enterprise 套餐,或 Claude Code。
+
+**Claude.ai:**
+1. 下载 [`archify.zip`](archify.zip)
+2. 进入 **Settings → Capabilities → Skills**
+3. 点 **+ Add**,上传 zip
+4. 打开开关
+
+![Claude Skills 设置页](docs/assets/claude-skills-settings.png)
+
+**Claude Code CLI:**
+```bash
+# 全局(所有项目可用)
+unzip archify.zip -d ~/.claude/skills/
+
+# 或者仅当前项目
+unzip archify.zip -d ./.claude/skills/
+```
+
+类型化渲染器(workflow / sequence / dataflow / lifecycle)依赖 ajv 做 schema 校验,需要在 skill 目录执行一次 `npm install`。首次使用时 Claude 会按 `SKILL.md` 的 Setup 指引自动安装;也可以自己先装好:
+
+```bash
+cd ~/.claude/skills/archify && npm install
+```
+
+没装依赖时渲染器会跳过 schema 校验(布局检查仍然运行)。
+
+**Claude.ai Projects:**
+把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。
+
+三种安装方式的能力差异:
+
+| 安装方式 | 能力 |
+|---|---|
+| **Claude Code** | 完整 —— 可运行类型化渲染器 + schema 校验 |
+| **Claude.ai 上传 zip** | 通常可用 —— 取决于沙箱能否 `npm install`,一般可以 |
+| **Project Knowledge** | 仅架构模式 —— 不执行代码,纯 prompt 驱动 |
+
+### 2. 准备系统描述
+
+下面几种都可以:
+
+**让 AI 分析你的代码仓库:**
+```
+分析这个代码仓库,描述系统架构。包括所有主要组件、它们之间怎么连接、
+用了什么技术栈,以及任何云服务或第三方集成。用列表格式,方便画图。
+```
+
+**自己写一段:**
+```
+- React 前端调 Node.js API
+- PostgreSQL 数据库
+- Redis 做缓存
+- 部署在 AWS 上,用 CloudFront 做 CDN
+```
+
+**或者让 Claude 给个典型架构:**
+```
+一个典型的 SaaS 应用架构是什么样的?
+```
+
+### 3. 让 Claude 调用 skill
+
+```
+用 archify skill 帮我生成一张架构图:
+
+[粘贴你上面准备的描述]
+```
+
+完事。Claude 会生成一个 HTML 文件,浏览器打开就能看。想改就接着聊:「加个 Redis」、「把 Postgres 换成 MySQL」、「鉴权那条路径高亮一下」。
+
+## 用生成的 HTML
+
+浏览器打开文件,右上角会有两个按钮:
+
+- **主题按钮**(Dark / Light)—— 一键切换,持久化保存。快捷键 <kbd>T</kbd>。
+- **Export 菜单** —— 五个操作:复制到剪贴板 + 4 种格式下载。快捷键 <kbd>E</kbd>。
+
+### Export 菜单
+
+| 操作 | 做什么 |
+|---|---|
+| **Copy to clipboard** | 当前图以 PNG 格式直接进系统剪贴板,粘贴到 Slack / Notion / 飞书 / GitHub / Figma |
+| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充(无透明);PNG 保留透明度 |
+| **Download SVG** | 矢量导出,所有样式内联,**双主题自持**。内嵌了 dark + light 两套 CSS 变量 + `@media (prefers-color-scheme)` 规则 —— 同一个 `.svg` 贴到 GitHub README / 博客,读者切深浅色图自己跟着切。可以在 Figma / Illustrator 里继续编辑。无损缩放 |
+
+所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在**最高 4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。
+
+没有倍数选择器 —— 永远最高清晰度,默认也是唯一选项。如果偶尔需要小图,用下面的 URL 参数。
+
+### 键盘快捷键
+
+- 任何位置按 <kbd>T</kbd> —— 切换主题
+- 任何位置按 <kbd>E</kbd> —— 打开 Export 菜单
+- 菜单里 <kbd>↑</kbd> <kbd>↓</kbd> —— 上下选项
+- <kbd>Home</kbd> / <kbd>End</kbd> —— 跳到第一 / 最后一项
+- <kbd>Enter</kbd> / <kbd>Space</kbd> —— 触发当前项
+- <kbd>Esc</kbd> —— 关闭菜单
+
+### URL 参数
+
+- `?theme=light` 或 `?theme=dark` —— 强制启动主题(确定性截图、分享链接、文档嵌入场景)
+- `?openExport=1` —— 页面加载时自动展开 Export 菜单(演示 / 文档截图)
+
+### 注意事项
+
+- **WebP 兼容性**:依赖浏览器的 canvas 编码器。老版 Safari 不支持时,菜单项会变灰不可选。PNG 和 JPEG 通用。
+- **剪贴板支持**:图片复制需要 `ClipboardItem` + `navigator.clipboard.write`(Chromium、Firefox 127+、Safari 16+)。不支持时 Copy 选项变灰。
+- **导出字体**:光栅图会使用系统等宽字体回退(`ui-monospace` / Menlo / Consolas),因为沙箱图像渲染上下文拿不到 Google Fonts。本机装了 JetBrains Mono 会自动用上,完全像素级一致。
+
+## 常用 prompt
+
+**Web 应用:**
+```
+用 archify 画一张架构图:
+- React 前端
+- Node.js/Express API
+- PostgreSQL 数据库
+- Redis 缓存
+- JWT 鉴权
+```
+
+**AWS Serverless:**
+```
+用 archify 画:
+- CloudFront CDN
+- API Gateway
+- Lambda(Node.js)
+- DynamoDB
+- S3 存静态资源
+- Cognito 做鉴权
+```
+
+**微服务:**
+```
+用 archify 画一张微服务架构图:
+- React Web + 移动端
+- Kong API Gateway
+- 用户服务(Go)、订单服务(Java)、商品服务(Python)
+- PostgreSQL、MongoDB、Elasticsearch
+- Kafka 做事件流
+- K8s 做编排
+```
+
+**数据流 / 埋点分析:**
+```
+用 archify 画一个 data flow:
+- Web App 和 Mobile SDK 产生 clickstream events
+- Edge API 收集事件
+- Consent Gate 过滤身份信息和 PII
+- Kafka/Event Stream 承接 accepted events
+- Warehouse 存 normalized facts
+- Feature Store 每日生成 feature vectors
+- Dashboards 和 ML Model 消费下游数据
+```
+
+**状态机 / 生命周期:**
+```
+用 archify 画一个 lifecycle diagram:
+- 任务从 Queued 开始
+- Planning 生成计划
+- Executing 调用工具
+- Reviewing 做质量检查
+- Needs Approval 和 Blocked 是等待态
+- Failed 可重试,Cancelled / Expired / Completed 是终态
+```
+
+## 语义配色
+
+| 类型 | 颜色 | 用途 |
+|---|---|---|
+| Frontend | 青色 | 客户端 / UI / 终端设备 |
+| Backend | 翠绿 | 服务 / API / 后台进程 |
+| Database | 紫色 | 数据库 / 存储 / AI/ML |
+| Cloud / AWS | 琥珀 | 托管云服务 / 基础设施 |
+| Security | 玫红 | 鉴权 / 安全组 / 加密 |
+| Message Bus | 橙色 | Kafka / RabbitMQ / SNS / 事件总线 |
+| External | 灰色 | 第三方 / 通用外部系统 |
+
+每种颜色在深色 / 浅色主题下都有配套取值,切主题会同步切换。
+
+## 实现细节
+
+- **样式模型**:`:root` + `[data-theme="light"]` 上的 CSS 变量;SVG 元素引用语义 class(`c-frontend`、`t-muted`、`a-emphasis` 等)。切换 `<html>` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。
+- **导出流水线**:克隆 SVG,内联 host `<style>`,解析当前主题变量并写入 clone 的 `:root` 规则,然后用 `XMLSerializer` 序列化。光栅格式下,clone 的 `width`/`height` 被设为 `4 × viewBox`,浏览器按目标分辨率原生光栅化矢量;canvas 尺寸对齐 clone 后按自然大小绘制(无位图升采样),`toBlob(mime)` 生成文件。JPEG 会显式补背景色(无 alpha)。如果目标分辨率超过浏览器 canvas 上限,自动降到 3× 或 2×。
+- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 19 KB 嵌入 JS。生成的 HTML 零运行时依赖 —— 无构建步骤、无 JS 框架、无服务端(渲染器本身需要 `npm install`,见安装章节)。
+- **浏览器支持**:任何主流浏览器(Chrome、Safari、Firefox、Edge)。WebP 导出需要 canvas 支持 `image/webp`。
+
+## 致谢
+
+Archify 是 [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator)(MIT,v1.0)的 fork 重写,原作者 [Cocoon AI](mailto:[email protected])。原版精致的视觉语言 —— 配色、网格背景、摘要卡片布局、JetBrains Mono 字体 —— 完整保留。视觉设计功劳归属原作者。
+
+Archify 2.x 贡献:
+
+- 模板重构为 CSS 变量主题系统(深色 + 浅色)
+- 主题切换 + `localStorage` 持久化 + `prefers-color-scheme` 默认
+- 内置 PNG / JPEG / WebP / SVG 导出菜单 + 复制到剪贴板
+- 4× 原生光栅化(修复升采样导致的模糊)
+- SVG 导出双主题自持(单文件跟随宿主 `prefers-color-scheme`)
+- 键盘导航 + 可访问性语义
+- 打印样式表 + 本地字体回退
+- 更新后的 `SKILL.md` 引导 Claude 使用 class 化、可主题化的画图方式
+
+两个项目都是 MIT 协议。
+
+## 路线图
+
+详见 [ROADMAP.md](ROADMAP.md)。
+
+下一站是 **v3.0 — JSON IR 稳定迭代**:引入极简 `diagram.json` 中间格式,让 Claude 做局部坐标修改时不会漂移无关组件,同时支持 `git diff` 友好和 theme/palette 不重渲染。
+
+> **关于 Mermaid 输入:** 已实现 —— `SKILL.md` 现在有专门的「Mermaid as an Input Dialect」章节,把 flowchart / sequenceDiagram / stateDiagram 映射到 workflow / sequence / lifecycle。注意走的是 prompt 而不是 parser:经实验验证(auto-layout + archify CSS 并不比原生 Mermaid 好看多少),自动解析器路线已砍掉。archify 的美学核心是 Claude 的布局判断,不是 CSS —— 贴 Mermaid 代码,Claude 从零布局出 archify 风格图。
+>
+> 原 v2.4 / v2.5 计划(`?exportScale=N`、色盲调色板、分享链接)也已砍掉。理由见 [ROADMAP「Not planned」段落](ROADMAP.md#not-planned)。
+
+## License
+
+[MIT](LICENSE) —— 自由使用、修改、再分发。
+
+## 参与贡献
+
+欢迎 issue、PR、分享你画的图。