{"id":49541036,"url":"https://github.com/tt-a1i/archify","last_synced_at":"2026-05-02T15:07:00.996Z","repository":{"id":351475262,"uuid":"1211139949","full_name":"tt-a1i/archify","owner":"tt-a1i","description":"Claude Skill: generate beautiful architecture diagrams with dark/light theme toggle and PNG/JPEG/WebP/SVG export","archived":false,"fork":false,"pushed_at":"2026-04-24T03:33:40.000Z","size":4711,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T04:30:16.983Z","etag":null,"topics":["anthropic","architecture-diagram","claude-skill","dark-mode","developer-tools","diagram-as-code","html-diagram","mermaid-alternative","svg","system-design"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tt-a1i.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T05:27:37.000Z","updated_at":"2026-04-24T03:33:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tt-a1i/archify","commit_stats":null,"previous_names":["tt-a1i/archify"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/tt-a1i/archify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tt-a1i%2Farchify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tt-a1i%2Farchify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tt-a1i%2Farchify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tt-a1i%2Farchify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tt-a1i","download_url":"https://codeload.github.com/tt-a1i/archify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tt-a1i%2Farchify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32538314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","architecture-diagram","claude-skill","dark-mode","developer-tools","diagram-as-code","html-diagram","mermaid-alternative","svg","system-design"],"created_at":"2026-05-02T15:06:59.444Z","updated_at":"2026-05-02T15:07:00.979Z","avatar_url":"https://github.com/tt-a1i.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Archify 主视觉](examples/images/archify-readme-hero.png)\n\n# Archify\n\n**聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切。导出 4× 清晰 PNG / JPEG / WebP / SVG，或直接复制到剪贴板。**\n\nArchify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude)：你用大白话描述自己的系统或流程，它就把你的描述变成一张做工精细的技术图 —— 一个单文件 HTML，在浏览器里打开就能切主题、复制到剪贴板、导出成各种图片格式。\n\n- **不需要会画图** —— 把组件和连接关系说给 Claude 就行\n- **支持 workflow / sequence / data flow / lifecycle** —— 技术流程、审批链、工具调用、CI/CD、请求调用链、数据管线、PII 边界、状态机都可以画\n- **内置主题切换** —— 深色 / 浅色一键切，浏览器记住偏好\n- **一键复制到剪贴板** —— 直接贴到 Slack、飞书、微信、Notion、GitHub issue\n- **导出图片超清晰** —— PNG / JPEG / WebP 全部由浏览器在 4× 源分辨率下**原生光栅化**（不是位图放大，没有糊），或导出 SVG 做真矢量\n- **SVG 自动跟系统深浅色** —— 导出的 SVG 内嵌两套变量 + `@media (prefers-color-scheme)`，贴到 GitHub README 里，读者切深浅色图跟着切（不用两张 PNG + `\u003cpicture\u003e` 包起来）\n- **单文件 HTML** —— 零依赖，发一个文件就能分享\n- **聊天迭代** —— \"把 Redis 挪到左边\"、\"鉴权服务换成玫红\"、\"加个 Kafka\"\n\n![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)\n![Claude](https://img.shields.io/badge/Claude-Skill-7C3AED?style=flat-square)\n![Version](https://img.shields.io/badge/version-2.4.0-0891b2?style=flat-square)\n\n\u003cp align=\"right\"\u003e\u003ca href=\"./README_EN.md\"\u003eEnglish\u003c/a\u003e\u003c/p\u003e\n\n## 预览\n\n同一张图，两套主题，一键切换：\n\n| 深色 | 浅色 |\n|---|---|\n| ![深色主题](examples/images/archify-dark.png) | ![浅色主题](examples/images/archify-light.png) |\n\nExport 菜单 —— 复制到剪贴板 + 四种格式下载：\n\n![导出菜单](examples/images/archify-menu.png)\n\n\n想亲自玩一下：克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html)，按 \u003ckbd\u003eT\u003c/kbd\u003e 切主题，\u003ckbd\u003eE\u003c/kbd\u003e 打开导出菜单。给 URL 加上 `?theme=light` 或 `?openExport=1` 可以强制初始状态。\n\n## 图表类型\n\nArchify 现在有五种主要输出：\n\n| 类型 | 适合画什么 | 怎么用 |\n|---|---|---|\n| **Architecture** | 系统组件、云资源、数据库、缓存、服务边界、安全组 | 直接描述系统结构 |\n| **Workflow** | 请求生命周期、审批流程、工具调用、CI/CD、运维 runbook、事故响应 | 说明参与方、步骤顺序、关键分支 |\n| **Sequence** | API 调用链、请求生命周期、缓存回源、鉴权、异步 trace、服务交互 | 说明谁调用谁、先后顺序、返回路径 |\n| **Data Flow** | 数据管线、ETL/ELT、埋点、PII 隔离、仓库同步、数据血缘、下游消费 | 说明数据来源、处理阶段、存储位置、敏感边界和消费方 |\n| **Lifecycle** | 状态机、订单/任务/部署/Agent run 生命周期、等待态、重试、取消、超时、终态 | 说明对象有哪些状态、哪些事件触发转移、哪些状态是终态 |\n\nWorkflow 不是通用流程图的替代品，它更偏“技术沟通图”：有泳道、有语义颜色、有主路径和异步/审批/观测路径。比如：\n\n```\n用 archify 画一个 workflow：\n用户提交请求 -\u003e Agent 规划 -\u003e 需要审批时进入 Approval Gate -\u003e 调工具 -\u003e 记录 trace -\u003e 返回结果\n```\n\n本仓库里有一个可打开的示例：[`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html)。\n\nSequence 用来解释更细的交互顺序，比如：\n\n```\n用 archify 画一个 sequence diagram：\n用户打开页面，前端请求 API，API 校验 JWT，读取 Redis，缓存未命中则查 Postgres，返回结果并写入 trace。\n```\n\n示例：[`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html)。\n\n![Sequence 示例](examples/images/archify-sequence.png)\n\nData Flow 适合解释“数据资产怎么走”，比如：\n\n```\n用 archify 画一个 data flow：\nWeb 和 Mobile 上报埋点，Edge API 收集事件，Consent Gate 过滤 PII，Kafka 承接事件流，\nWarehouse 存分析表，Feature Store 做每日特征，Dashboard 和 ML Model 消费下游数据。\n```\n\n示例：[`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html)。\n\n![Data Flow 示例](examples/images/archify-dataflow.png)\n\nLifecycle 用来解释“对象状态怎么变”，比如：\n\n```\n用 archify 画一个 lifecycle diagram：\nAgent Run 从 Queued 进入 Planning，再进入 Executing 和 Reviewing。需要人工确认时进入\nNeeds Approval，缺少输入时进入 Blocked；工具失败可以 Failed 后重试，用户取消进入 Cancelled，\n超时进入 Expired，成功则进入 Completed。\n```\n\n示例：[`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html)。\n\n![Lifecycle 示例](examples/images/archify-lifecycle.png)\n\n## 版本演进\n\nArchify 基于 [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 里，读者切深浅色图会自己跟着切。\n\n| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 |\n|---|---|---|---|---|---|---|\n| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + \u003ckbd\u003eT\u003c/kbd\u003e 快捷键 | 同 |\n| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器（仍是放大）| 同 | **4× 原生光栅化，不糊** | 同 |\n| SVG 下载 | — | 矢量 + 内联样式（单主题）| 同 | 同 | 同 | **双主题自持**（`@media prefers-color-scheme`）|\n| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同（始终 4×）| 同 |\n| 键盘快捷键 | — | — | \u003ckbd\u003eT\u003c/kbd\u003e/\u003ckbd\u003eE\u003c/kbd\u003e + 菜单导航 | 同 | 同 | 同 |\n| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 |\n| 打印样式表 | — | — | — | ✓ | ✓（+ 横向 + 2 列卡片）| 同 |\n| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 |\n| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 |\n\n## 快速上手\n\n### 1. 安装 skill\n\n\u003e 需要 Claude Pro / Max / Team / Enterprise 套餐，或 Claude Code。\n\n**Claude.ai：**\n1. 下载 [`archify.zip`](archify.zip)\n2. 进入 **Settings → Capabilities → Skills**\n3. 点 **+ Add**，上传 zip\n4. 打开开关\n\n**Claude Code CLI：**\n```bash\n# 全局（所有项目可用）\nunzip archify.zip -d ~/.claude/skills/\n\n# 或者仅当前项目\nunzip archify.zip -d ./.claude/skills/\n```\n\n**Claude.ai Projects：**\n把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。\n\n### 2. 准备系统描述\n\n下面几种都可以：\n\n**让 AI 分析你的代码仓库：**\n```\n分析这个代码仓库，描述系统架构。包括所有主要组件、它们之间怎么连接、\n用了什么技术栈，以及任何云服务或第三方集成。用列表格式，方便画图。\n```\n\n**自己写一段：**\n```\n- React 前端调 Node.js API\n- PostgreSQL 数据库\n- Redis 做缓存\n- 部署在 AWS 上，用 CloudFront 做 CDN\n```\n\n**或者让 Claude 给个典型架构：**\n```\n一个典型的 SaaS 应用架构是什么样的？\n```\n\n### 3. 让 Claude 调用 skill\n\n```\n用 archify skill 帮我生成一张架构图：\n\n[粘贴你上面准备的描述]\n```\n\n完事。Claude 会生成一个 HTML 文件，浏览器打开就能看。想改就接着聊：「加个 Redis」、「把 Postgres 换成 MySQL」、「鉴权那条路径高亮一下」。\n\n## 用生成的 HTML\n\n浏览器打开文件，右上角会有两个按钮：\n\n- **主题按钮**（Dark / Light）—— 一键切换，持久化保存。快捷键 \u003ckbd\u003eT\u003c/kbd\u003e。\n- **Export 菜单** —— 五个操作：复制到剪贴板 + 4 种格式下载。快捷键 \u003ckbd\u003eE\u003c/kbd\u003e。\n\n### Export 菜单\n\n| 操作 | 做什么 |\n|---|---|\n| **Copy to clipboard** | 当前图以 PNG 格式直接进系统剪贴板，粘贴到 Slack / Notion / 飞书 / GitHub / Figma |\n| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充（无透明）；PNG 保留透明度 |\n| **Download SVG** | 矢量导出，所有样式内联，**双主题自持**。内嵌了 dark + light 两套 CSS 变量 + `@media (prefers-color-scheme)` 规则 —— 同一个 `.svg` 贴到 GitHub README / 博客，读者切深浅色图自己跟着切。可以在 Figma / Illustrator 里继续编辑。无损缩放 |\n\n所有光栅导出（复制 + PNG/JPEG/WebP）都由浏览器在 **4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小，浏览器直接在该分辨率下光栅化矢量，canvas 按自然大小绘制（没有位图升采样）。结果是视网膜屏、演示幻灯、打印输出都真正清晰。\n\n没有倍数选择器 —— 永远最高清晰度，默认也是唯一选项。如果偶尔需要小图，用下面的 URL 参数。\n\n### 键盘快捷键\n\n- 任何位置按 \u003ckbd\u003eT\u003c/kbd\u003e —— 切换主题\n- 任何位置按 \u003ckbd\u003eE\u003c/kbd\u003e —— 打开 Export 菜单\n- 菜单里 \u003ckbd\u003e↑\u003c/kbd\u003e \u003ckbd\u003e↓\u003c/kbd\u003e —— 上下选项\n- \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e —— 跳到第一 / 最后一项\n- \u003ckbd\u003eEnter\u003c/kbd\u003e / \u003ckbd\u003eSpace\u003c/kbd\u003e —— 触发当前项\n- \u003ckbd\u003eEsc\u003c/kbd\u003e —— 关闭菜单\n\n### URL 参数\n\n- `?theme=light` 或 `?theme=dark` —— 强制启动主题（确定性截图、分享链接、文档嵌入场景）\n- `?openExport=1` —— 页面加载时自动展开 Export 菜单（演示 / 文档截图）\n\n### 注意事项\n\n- **WebP 兼容性**：依赖浏览器的 canvas 编码器。老版 Safari 不支持时，菜单项会变灰不可选。PNG 和 JPEG 通用。\n- **剪贴板支持**：图片复制需要 `ClipboardItem` + `navigator.clipboard.write`（Chromium、Firefox 127+、Safari 16+）。不支持时 Copy 选项变灰。\n- **导出字体**：光栅图会使用系统等宽字体回退（`ui-monospace` / Menlo / Consolas），因为沙箱图像渲染上下文拿不到 Google Fonts。本机装了 JetBrains Mono 会自动用上，完全像素级一致。\n\n## 常用 prompt\n\n**Web 应用：**\n```\n用 archify 画一张架构图：\n- React 前端\n- Node.js/Express API\n- PostgreSQL 数据库\n- Redis 缓存\n- JWT 鉴权\n```\n\n**AWS Serverless：**\n```\n用 archify 画：\n- CloudFront CDN\n- API Gateway\n- Lambda（Node.js）\n- DynamoDB\n- S3 存静态资源\n- Cognito 做鉴权\n```\n\n**微服务：**\n```\n用 archify 画一张微服务架构图：\n- React Web + 移动端\n- Kong API Gateway\n- 用户服务（Go）、订单服务（Java）、商品服务（Python）\n- PostgreSQL、MongoDB、Elasticsearch\n- Kafka 做事件流\n- K8s 做编排\n```\n\n**数据流 / 埋点分析：**\n```\n用 archify 画一个 data flow：\n- Web App 和 Mobile SDK 产生 clickstream events\n- Edge API 收集事件\n- Consent Gate 过滤身份信息和 PII\n- Kafka/Event Stream 承接 accepted events\n- Warehouse 存 normalized facts\n- Feature Store 每日生成 feature vectors\n- Dashboards 和 ML Model 消费下游数据\n```\n\n**状态机 / 生命周期：**\n```\n用 archify 画一个 lifecycle diagram：\n- 任务从 Queued 开始\n- Planning 生成计划\n- Executing 调用工具\n- Reviewing 做质量检查\n- Needs Approval 和 Blocked 是等待态\n- Failed 可重试，Cancelled / Expired / Completed 是终态\n```\n\n## 语义配色\n\n| 类型 | 颜色 | 用途 |\n|---|---|---|\n| Frontend | 青色 | 客户端 / UI / 终端设备 |\n| Backend | 翠绿 | 服务 / API / 后台进程 |\n| Database | 紫色 | 数据库 / 存储 / AI/ML |\n| Cloud / AWS | 琥珀 | 托管云服务 / 基础设施 |\n| Security | 玫红 | 鉴权 / 安全组 / 加密 |\n| Message Bus | 橙色 | Kafka / RabbitMQ / SNS / 事件总线 |\n| External | 灰色 | 第三方 / 通用外部系统 |\n\n每种颜色在深色 / 浅色主题下都有配套取值，切主题会同步切换。\n\n## 实现细节\n\n- **样式模型**：`:root` + `[data-theme=\"light\"]` 上的 CSS 变量；SVG 元素引用语义 class（`c-frontend`、`t-muted`、`a-emphasis` 等）。切换 `\u003chtml\u003e` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。\n- **导出流水线**：克隆 SVG，内联 host `\u003cstyle\u003e`，解析当前主题变量并写入 clone 的 `:root` 规则，然后用 `XMLSerializer` 序列化。光栅格式下，clone 的 `width`/`height` 被设为 `4 × viewBox`，浏览器按目标分辨率原生光栅化矢量；canvas 尺寸对齐 clone 后按自然大小绘制（无位图升采样），`toBlob(mime)` 生成文件。JPEG 会显式补背景色（无 alpha）。如果目标分辨率超过浏览器 canvas 上限，自动降到 3× 或 2×。\n- **单文件**：一个 HTML，一个 Google Fonts `\u003clink\u003e`，内联 SVG，约 3 KB 嵌入 JS。无构建步骤、无 JS 框架、无服务端。\n- **浏览器支持**：任何主流浏览器（Chrome、Safari、Firefox、Edge）。WebP 导出需要 canvas 支持 `image/webp`。\n\n## 致谢\n\nArchify 是 [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator)（MIT，v1.0）的 fork 重写，原作者 [Cocoon AI](mailto:hello@cocoon-ai.com)。原版精致的视觉语言 —— 配色、网格背景、摘要卡片布局、JetBrains Mono 字体 —— 完整保留。视觉设计功劳归属原作者。\n\nArchify 2.x 贡献：\n\n- 模板重构为 CSS 变量主题系统（深色 + 浅色）\n- 主题切换 + `localStorage` 持久化 + `prefers-color-scheme` 默认\n- 内置 PNG / JPEG / WebP / SVG 导出菜单 + 复制到剪贴板\n- 4× 原生光栅化（修复升采样导致的模糊）\n- SVG 导出双主题自持（单文件跟随宿主 `prefers-color-scheme`）\n- 键盘导航 + 可访问性语义\n- 打印样式表 + 本地字体回退\n- 更新后的 `SKILL.md` 引导 Claude 使用 class 化、可主题化的画图方式\n\n两个项目都是 MIT 协议。\n\n## 路线图\n\n详见 [ROADMAP.md](ROADMAP.md)。\n\n下一站是 **v3.0 — JSON IR 稳定迭代**：引入极简 `diagram.json` 中间格式，让 Claude 做局部坐标修改时不会漂移无关组件，同时支持 `git diff` 友好和 theme/palette 不重渲染。\n\n\u003e **关于 Mermaid 导入：** 经实验验证（auto-layout + archify CSS 并不比原生 Mermaid 好看多少），Mermaid 自动解析器路线已砍掉。archify 的美学核心是 Claude 的布局判断，不是 CSS。用户仍可贴 Mermaid 代码让 Claude 从零布局出 archify 风格图 —— 只是走 prompt 而不是走 parser。\n\u003e\n\u003e 原 v2.4 / v2.5 计划（`?exportScale=N`、色盲调色板、分享链接）也已砍掉。理由见 [ROADMAP「Not planned」段落](ROADMAP.md#not-planned)。\n\n## License\n\n[MIT](LICENSE) —— 自由使用、修改、再分发。\n\n## 参与贡献\n\n欢迎 issue、PR、分享你画的图。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftt-a1i%2Farchify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftt-a1i%2Farchify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftt-a1i%2Farchify/lists"}