English · 简体中文
# Archify
**在对话里，把代码仓库或系统描述变成漂亮、可靠、可交互的系统地图。**
Archify 是适用于 Raven、Cursor、Claude Code、Codex CLI 和 OpenCode 的 Agent Skill。给它系统描述或代码仓库，就能得到可交互、可分享的专业技术地图。
- **打开就是成品** —— 五种技术图、四套视觉预设、深浅主题，以及显式启用的有限动态
- **合并前先看清架构变化** —— 把两份已校验快照对比为 Before / Delta / After，准确区分新增、删除、语义变化、移动和重路由
- **每次探索都有依据** —— 搜索节点、按需打开版本校验过的源码、追踪作者定义的上下游可达范围与精确路径、对比角色、播放故事，但不编造拓扑
- **一个文件即可放心交付** —— Typed JSON IR 和确定性校验生成独立 HTML，并支持 PNG、SVG、WebM 与 1200×630 分享卡片
**[在线项目页](https://tt-a1i.github.io/archify/)** · **[场景选图指南](https://tt-a1i.github.io/archify/guide.html)** · **[Proof Lab](https://tt-a1i.github.io/archify/gallery.html)**
```bash
npx skills add tt-a1i/archify -g
```
使用 Cursor？打开[可切换 Agent 的快速开始页](https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture)，即可获得准确的全局或当前仓库安装命令。
然后告诉 Agent：`使用 archify 梳理这个仓库的运行时架构。`
## ❤️ 赞助
本项目由专注 Agent 记忆基础设施的 [**EverMind**](https://github.com/EverMind-AI) 赞助。EverMind 旗下以记忆为核心、可自进化的 Agent Harness [**Raven**](https://github.com/EverMind-AI/Raven) 已支持 Archify Skill，让 Raven 工作流可以直接生成经过验证的交互式系统地图。
## 看看 Archify 能做什么
下面都是真实生成的 Archify 成品，不是产品效果图。点击画面即可打开对应的可分享交互状态。
三个真实生成、校验通过的成品。 Signal Flow · Blueprint · Classic · 打开可交互验证作品集 ↗
| 引导故事 | 路径探查 | 语义角色对比 |
|---|---|---|
| [](https://tt-a1i.github.io/archify/gallery/artifacts/agent-tool-call.workflow.html?theme=dark&present=1&play=1#view=happy-path) | [](https://tt-a1i.github.io/archify/gallery/artifacts/cache-miss.sequence.html?theme=dark&present=1#route=web~db) | [](https://tt-a1i.github.io/archify/gallery/artifacts/production-deployment.architecture.html?theme=dark&present=1#lens=backend~database) |
| 播放一次有限的命名章节。 | 检查最短的作者有向路径。 | 对比语义角色之间的真实流量。 |
[Proof Lab](https://tt-a1i.github.io/archify/gallery.html) 收录全部 11 个仓库内场景、JSON 源、命名视图和校验回执。
### 从真实仓库读出来，不是只靠 Prompt 画出来
[](https://tt-a1i.github.io/archify/cases/mco-runtime.architecture.html?theme=dark&present=1#view=dispatch-path)
Archify 追踪 [`mco-org/mco`](https://github.com/mco-org/mco) 的 `9f1a1cf` 版本并生成这张校验地图。**[打开成品 ↗](https://tt-a1i.github.io/archify/cases/mco-runtime.architecture.html?theme=dark&present=1#view=dispatch-path)** · [追踪下游 ↗](https://tt-a1i.github.io/archify/cases/mco-runtime.architecture.html?theme=dark#focus=router&reach=downstream) · [Typed Source](docs/cases/mco-runtime.architecture.json)
## 预览
同一张图，两套主题，一键切换：
| 深色 | 浅色 |
|---|---|
|  |  |
Export 菜单支持复制 PNG，并下载静态或动态格式：
需要用于 README、Release 或社交平台的标准 1200×630 图片时，使用 **Copy Share Card**。
路径解析后，**Export → Route Share Card** 会把真实路径下载为 1200×630 PNG，并保留完整拓扑上下文。
完成 authored `Upstream` 或 `Downstream` reach 后，**Export → Reach Share Card** 会捕获这次阅读结果，但不冒充运行时影响分析。
在本地打开 [`examples/web-app.html`](examples/web-app.html)，即可体验完整 Viewer。
## 快速开始
### 1. 安装
```bash
npx skills add tt-a1i/archify -g
```
显式、非交互地安装到 Cursor：
```bash
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes
```
如果只想临时体验：
```bash
npx skills use tt-a1i/archify@archify --agent codex
```
同一份 Skill 可用于 `raven`、`cursor`、`codex`、`claude-code` 和 `opencode`；[快速开始页的 Agent 切换器](https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture)会生成准确命令，不维护厂商专属分叉。仓库内的 [`archify.zip`](archify.zip) 也不需要执行 `npm install`；在 Raven 中，将其解压到 `~/.raven/workspace/skills` 即可。
### 2. 先画一个边界清楚的视图
```text
分析这个仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，突出一条主要路径，并标出外部依赖与信任边界。
辅助信息放进说明卡片，不要继续增加连线。
```
如果只想解释一条调用链：
```text
使用 archify 画出这条登录流程：Browser -> Web App -> API -> JWT 校验 ->
Redis Session 查询 -> PostgreSQL 回源。把缓存未命中作为次要路径。
```
### 3. 在对话中细调
继续说：`增加 Redis`、`把鉴权移到左侧`、`突出回滚路径`。Archify 会保留 Typed Source，只修改相关部分。
## 选择合适的图表
| 类型 | 最适合 | Prompt 中应包含 |
|---|---|---|
| **Architecture** | 组件、服务、存储和系统边界 | 范围、核心组件、主要路径 |
| **Workflow** | CI/CD、审批、工具调用、Runbook | 参与者、顺序、分支、异常 |
| **Sequence** | API 调用、缓存回源、鉴权、异步链路 | 调用方、被调用方、返回、时序 |
| **Data Flow** | 数据管线、血缘、PII、下游消费者 | 来源、转换、存储、边界 |
| **Lifecycle** | 状态、重试、等待、终态 | 状态、事件、重试与取消路径 |
做生产部署评审时，Architecture 可以按需启用 `deployment-ownership`
工程画像：负责人、单一区域归属、数据库私有边界或边界穿越机制缺失时会直接阻断。
它不会被静默开启，只校验作者写入的事实，不代表线上基础设施已经核验。可查看
[通过校验的部署证明](https://tt-a1i.github.io/archify/gallery.html#proof-deployment-ownership)。
做设计或 PR 评审时，Architecture Delta 生成已校验的 Before / Delta / After 和机器回执。精确选择任一作者变更，或播放一次有限 Review；全程只读，不推断影响、风险或合并安全。
`node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json`
[](examples/checkout-platform-delta.html)
不知道选哪一种？打开[交互式场景指南](https://tt-a1i.github.io/archify/guide.html)，或直接询问零依赖 CLI：
```bash
node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求"
node archify/bin/archify.mjs guide "梳理 Kafka Topic、消费者组、重放和死信队列" --json
```
Workflow 用泳道保持主路径清晰：
Sequence 解释一次交互随时间如何推进：
Data Flow 突出数据移动和敏感边界：
Lifecycle 区分正常进展、等待、重试和终态：
Architecture 示例：[`Web App`](examples/web-app.html) · [`Archify Pipeline`](examples/archify-repo.html) · [`Grid 布局`](examples/archify-repo-grid.html) · [`桌面 Agent`](examples/maka-architecture.html)
## 为什么用 Archify
- **用布局判断代替通用自动布局** —— Agent 根据故事选择层级、留白、线路和强调关系；共享的自动端点会确定性展开，不再让多支箭头堆在同一个中点。
- **Typed JSON IR** —— 每种 Renderer 模式都有 Schema 和可复现的源文件。
- **原子交付前校验** —— Schema、布局、HTML/SVG、线路和标签到其他路径的净空检查必须全部通过，Showcase 成品才会替换上一份可信结果。
- **失败也有结构化修复回执** —— `validate --json` 和 `deliver --json` 会返回稳定规则码、准确对象、测量证据和真正支持的修复旋钮，不再让 Agent 从 Node 堆栈或自由文本里猜。
- **保留最后好图的实时预览** —— 可选桌面循环只监听一个 JSON；只有最新候选通过全部门禁才刷新，半写入或无效保存时继续显示上一份验证成品。
- **交互不编造拓扑** —— 聚焦、上下游可达范围、精确路径、角色对比和故事都复用作者定义的节点与关系，也不把图上可达误报成真实运行时影响。
- **只在需要时附源码证据** —— 有证据的 Architecture 节点会显示 `SRC n`，并可打开由 Git 校验、固定到公开 commit 的文件与行号；普通成品不携带源码信息。
- **结果默认便携** —— 一个 HTML 文件即可分享；导出永远是完整原图，不携带临时 Viewer 状态。
Archify 不是通用绘图编辑器，也不是 Mermaid 主题；它负责把技术意图变成可交流的成品。
## 工作原理
| 步骤 | 发生什么 |
|---|---|
| **生成** | Agent 根据描述创建 Typed JSON IR。 |
| **校验** | 内置 Validator 和布局规则检查源文件；失败时用机器可读 JSON 指出准确的局部修复。 |
| **预览（可选）** | 仅 loopback 的桌面会话监听一个源文件，只刷新验证版本；失败时保留最后好图。 |
| **交付** | 在目标同目录生成并检查候选；只有通过门禁的结果才原子替换目标文件，随后可选用 `--open` 打开这个确切成品。 |
| **迭代** | Agent 修改源文件，不干扰无关结构。 |
仓库常用命令：
```bash
cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "展示 CI/CD 检查、审批、部署和回滚"
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json
```
`preview` 是显式启用的桌面创作模式，不是默认后台服务：它只在随机端口监听 `127.0.0.1`，只观察指定 JSON，失败时保留上一份验证输出，并通过 Ctrl-C 停止。测试或准备手动打开打印出的本地 URL 时可加 `--no-open`。生成的 HTML 不会携带 Preview Runtime。
`deliver --open` 适合一次性的本地交互交付。它默认关闭，并且只在验证成品原子提交后执行；系统无法打开时，交付仍保持成功，JSON 只写 stdout，stderr 会给出可手动打开的绝对路径。
失败时，`validate --json` 和 `deliver --json` 仍然只输出一个 JSON 对象。读取 `diagnostics[]`，只修改其中 `subject` 指向的对象，并使用 `supportedFixes` 列出的修复方式；不要整图重写，也不要突破 Skill 最多两轮的聚焦修复上限。确定性诊断仍不等于视觉复核。
动态和演示样式需要显式选择：
```json
{
"meta": {
"animation": "trace",
"visual_preset": "signal-flow"
}
}
```
不设置 `animation` 时结果完全静态；`classic` 始终是默认视觉预设。设计评审、发布说明和技术文档可以显式选择 `editorial`，获得暖纸张与深墨色的编辑风格，同时保持几何完全不变。
## 探索与分享
| 操作 | 控制方式 |
|---|---|
| 打开事实型 Diagram Guide | ? |
| 查找并聚焦语义节点 | / |
| 追踪作者定义的上游 / 下游可达范围 | 聚焦节点 → `Upstream` / `Downstream` |
| 探查有向路径并逐站检查 | R 或 `PATH` |
| 对比一种或两种语义角色 | L 或 `LENS` |
| 打开实时全局雷达 | M 或 `MAP` |
| 播放故事 / 切换章节 | P / [ ] |
| 进入 Presentation Stage | F |
| 选择视觉风格（S 循环）/ 切换主题 / 打开 Export | S / T / E |
| 缩放或复位 | + / - / 0 |
稳定链接可以恢复 `#focus=`、`#focus=&reach=upstream|downstream`、`#relation=`、`#route=~`、`#lens=~` 和 `#view=`。读者触发的动态有限运行、遵守 `prefers-reduced-motion`，并且不会进入标准导出。
完整生成与 Viewer 契约请查看 [`archify/SKILL.md`](archify/SKILL.md)。
## 安装方式
| 使用位置 | 安装位置或方法 | 能力 |
|---|---|---|
| **Raven** | `~/.raven/workspace/skills/archify` | 完整 Renderer + Validation 工作流 |
| **Claude Code** | `~/.claude/skills/` 或 `.claude/skills/` | 完整 Renderer + Validation 工作流 |
| **Codex CLI** | `~/.agents/skills/` 或 `.agents/skills/` | 完整 Renderer + Validation 工作流 |
| **opencode** | `~/.config/opencode/skills/`、`.opencode/skills/` 或 `.agents/skills/` | 完整 Renderer + Validation 工作流 |
| **Claude.ai** | Settings → Capabilities → Skills 中上传 `archify.zip` | 取决于沙箱是否提供 Node.js |
| **Project Knowledge** | 把 `archify.zip` 上传到项目 | Prompt 驱动的 Architecture Fallback |
Claude.ai 中的上传入口：
## 参考与边界
- [Schema 说明](archify/schemas/README.md)
- [Skill 与 Renderer 契约](archify/SKILL.md)
- [示例](archify/examples/)
- [版本历史](CHANGELOG.md)
- [路线图](ROADMAP.md)
- [自动生成的 Proof Lab](https://tt-a1i.github.io/archify/gallery.html)
Archify 2.12 已覆盖五种 Typed IR、真实仓库证明、基于精确 ID 的确定性 Architecture Delta 评审、验证后实时预览、作者可达性、可选有限动态、引导视图、语义搜索与关系探索、可分享深链、1200×630 整图与路径卡片、浏览器原生 WebM、显式 `standard` / `showcase` 质量档位，以及按需启用的部署所有权契约。
自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不在产品范围内。
## 致谢
Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 Fork 和重写。原始视觉语言仍归功于 Cocoon AI；Archify 2.x 在此基础上增加主题、导出、Typed Renderer、校验、无障碍、交互和统一 CLI。两个项目都采用 MIT License。
## License
[MIT](LICENSE) —— 可以自由使用、修改和分发。
## 参与贡献
欢迎提交 Issue、Pull Request 和真实场景图。请先阅读[贡献指南](CONTRIBUTING.md)；遇到问题时使用可复现 Bug 表单，也可以通过[社区 Showcase 表单](https://github.com/tt-a1i/archify/issues/new?template=showcase.yml)提交已验证成品。