English · 简体中文

Archify

将代码库或系统描述转化为精美的交互式系统地图——直接在聊天中完成。

Archify 是 Raven、Cursor、Claude Code、Codex CLI 和 OpenCode 的代理技能。只需提供系统描述或仓库，即可获得一个可交互、可分享的技术地图。

• 打开即可展示——五种技术图类型、四种视觉预设、暗色/亮色主题，以及可选的有限动效
• 合并前审查架构变更——比较两个已验证的快照，提供 Before / Delta / After 视图，精确显示新增、删除、修改、移动和重新路由的事实
• 每次交互都基于事实——搜索节点，可选打开经过修订验证的源码，追踪上游/下游的编写关系和精确路由，比较角色，并播放引导式故事，无需虚构拓扑
• 单一文件，值得信任与分享——类型化的 JSON IR 和确定性校验生成自包含 HTML，以及 PNG、SVG、WebM 和 1200×630 分享卡片

当前开发版本： v2.13.0-dev.0（未发布；最新稳定版：v2.12.0）。参见 Unreleased。

项目页面 · 使用场景指南 · 证明实验室

npx skills add tt-a1i/archify -g

使用 Cursor？打开 agent-aware 快速开始 获取准确的全局和项目命令。

然后向你的代理提问：Use archify to map this repository's runtime architecture.

❤️ 赞助商

由 EverMind 赞助，该公司为代理构建记忆基础设施。其记忆优先、自我进化的代理框架 Raven 将 Archify 作为技能支持，将经过验证的交互式系统地图带入 Raven 工作流。

查看 Archify 的实际效果

这些是生成的 Archify 制品，而非产品模型。点击任一帧可打开其在线、可分享的状态。

_{三个真实生成的制品。 Signal Flow · Blueprint · Classic · 打开交互式证明实验室 ↗}

引导式故事	路由探测	语义透镜
播放一个有限命名的章节。	检查最短的编写有向路径。	比较语义角色之间的真实流量。

证明实验室 包含所有 11 个检入的场景、其 JSON 源、命名视图和验证收据。

一个真实的仓库，从源码映射而来

Archify 在 9f1a1cf 提交处追踪了 mco-org/mco 并生成了这个经过验证的地图。打开它 ↗ · 追踪可达性 ↗ · 类型化源文件

预览

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

暗色	亮色

导出菜单将 PNG 复制到剪贴板，并下载静态或动效格式：

当你想为 README、发布版本或社交媒体帖子获取一个标准的 1200×630 图片时，使用 Copy Share Card。

追踪路由后，Export → Route Share Card 将该编写路径下载为 1200×630 的 PNG，并保留完整图表作为上下文。

追踪编写后的 Upstream 或 Downstream 可达性后，Export → Reach Share Card 捕获该精确读取结果，而不声称运行时影响。

在本地打开 examples/web-app.html 以尝试完整的查看器。

快速开始

1. 安装

npx skills add tt-a1i/archify -g

对于显式、非交互的 Cursor 安装：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

若要尝试无需永久安装的方式：

npx skills use tt-a1i/archify@archify --agent codex

Agent 切换器 支持 cursor、codex、claude-code 和 opencode。对于 Raven 的手动 ZIP 安装，将 archify.zip 解压到 ~/.raven/workspace/skills 目录；解压后得到 ~/.raven/workspace/skills/archify。Raven 不是切换器的目标。

2. 请求一个受限视图

Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

对于聚焦流程：

Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->
Redis session lookup -> PostgreSQL fallback. Keep the cache-miss path secondary.

3. 在聊天中优化

继续提出针对性请求，例如 add Redis、move auth to the left 或 highlight the rollback path。Archify 会保持类型化源文件可用，以便进行有针对性的迭代。

选择正确的图表类型

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

对于生产部署评审，架构图可以选择启用 deployment-ownership 工程配置文件。当缺少所有者、单区域部署、私有数据库范围或已命名的边界穿越时，它会安全失败。该配置绝不会静默启用，并且验证的是编写的事实，而非实时基础设施。请参阅已检查的部署证明。

对于设计或 PR 评审，架构差异图会对比经过验证的 Before / Delta / After 快照，并附带机器收据。选择一个精确的编写变更，或播放一个有限的评审（仅查看，无影响、无风险、无合并安全推断）。

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

不确定哪种适合？使用交互式场景指南，或咨询零依赖的 CLI：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

工作流图在多个泳道中保持快乐路径清晰：

时序图解释一次交互随时间的变化：

数据流图使数据流动和敏感边界显式化：

生命周期图区分进度、等待、重试和最终结果：

架构图示例：web-app · Archify pipeline · grid placement · desktop agent

为什么选择 Archify

• 布局判断优于通用自动布局 — 代理选择层级、间距、路径和重点；共享的自动端点会分散布局，而非将箭头堆积在同一个中点。
• 类型化 JSON IR — 每个基于渲染器的模式都有 schema 和可复现的源文件。
• 交付前的原子化验证 — schema、布局、HTML/SVG、路由以及标签到路由的清除检查必须全部通过，展示制品才会替换上次已知良好的输出。
• 失败时附带修复收据 — validate --json 和 deliver --json 返回稳定的规则代码、精确的主题、测量的证据以及仅支持修复的控制项，而非 Node 堆栈或非结构化的重试猜测。
• 上次良好结果的实时预览 — 可选的桌面循环监视一个 JSON 文件，仅当最新候选通过所有关卡时刷新，并在保存不完整或无效时保持之前已验证的图表可见。
• 真实的交互 — 聚焦、上游/下游可达、精确路径、角色对比和故事会重用已编写的节点和关系，而非虚构拓扑或声称运行时影响。
• 源证据，仅按需请求 — 基于证据的架构节点会标记自身为 SRC n，并打开固定在某个公共提交上的 Git 验证文件和行范围；普通制品保持无源状态。
• 默认可移植 — 输出为一个 HTML 文件；导出内容保持完整图表，且不包含临时查看器状态。

Archify 不是通用绘图编辑器或 Mermaid 主题。它将技术意图转化为沟通制品。

工作原理

步骤	具体操作
生成	代理根据你的描述创建类型化 JSON IR。
验证	内置验证器和布局规则检查源文件；失败时以机器可读的 JSON 形式指出精确的本地修复位置。
预览（可选）	仅回环的桌面会话监视一个源文件，仅在已验证的修订版本加载；失败时保持上次良好制品。
交付	渲染并检查同目录下的候选文件；仅通过验证的制品会原子性地替换目标文件，然后可选的 --open 会打开该文件。
迭代	代理更新源文件，同时无关结构保持稳定。

有用的仓库命令：

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
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 停止。添加 --no-open 用于测试或当你打算自行打开打印的本地 URL 时。它不会在生成的 HTML 中添加运行时。

使用 deliver --open 进行一次性交互式本地交接。默认关闭，仅在已验证的产物提交后运行，并且当操作系统打开器不可用时，绝不会将成功的交付转变为失败；JSON 保持在 stdout，手动打开的绝对路径输出到 stderr。

失败时，validate --json 和 deliver --json 仍然只输出一个 JSON 对象。读取 diagnostics[]，仅使用其 supportedFixes 更改指定的主题；不要重写整个图表或超出 Skill 的两轮针对性修正。确定性诊断与视觉审查保持分离。

可选的运动和演示样式是显式的：

{
  "meta": {
    "animation": "trace",
    "visual_preset": "signal-flow"
  }
}

省略 animation 可获得真正的静态图表。classic 保持默认；editorial 添加温暖的出版物外观。

探索与共享输出

操作	控件
打开事实性 Diagram Guide	?
查找并聚焦语义节点	/
追踪上游/下游作者范围	聚焦节点 → Upstream / Downstream
探测有向路由并检查其路径	R 或 PATH
比较一个或两个语义角色	L 或 LENS
打开实时概览雷达	M 或 MAP
播放引导故事 / 切换章节	P / [ ]
进入演示舞台	F
选择视觉样式（S 循环切换）/ 切换主题 / 打开导出	S / T / E
缩放或重置	+ / - / 0

稳定链接可以恢复 #focus=<id>、#focus=<id>&reach=upstream|downstream、#relation=<id>、#route=<source>~<target>、#lens=<kind>~<kind> 和 #view=<view-id>。读者驱动的运动是有限的，尊重 prefers-reduced-motion，并且永远不会进入规范导出。

完整的生成和查看器合约位于 archify/SKILL.md。

安装选项

平台	安装位置或方法	能力
Raven	手动解压到 ~/.raven/workspace/skills → ~/.raven/workspace/skills/archify	完整渲染器 + 验证工作流
Claude Code	~/.claude/skills/ 或 .claude/skills/	完整渲染器 + 验证工作流
Codex CLI	~/.agents/skills/ 或 .agents/skills/	完整渲染器 + 验证工作流
opencode	~/.config/opencode/skills/、.opencode/skills/ 或 .agents/skills/	完整渲染器 + 验证工作流
Claude.ai	在 Settings → Capabilities → Skills 下上传 archify.zip	取决于沙盒中的 Node.js 访问权限
Project Knowledge	将 archify.zip 上传到项目	提示驱动的架构回退

参考与范围

• Schema reference
• Skill and renderer contract
• Examples
• Changelog
• Roadmap
• Generated Proof Lab

未发布的 v2.13.0-dev.0 包含所有五种模式下的类型化 IR、真实仓库证明、确定性精确 ID 架构差异审查、已验证的实时预览、作者可达性、可选有限运动、引导视图、语义搜索与关系探索、可共享的深度链接、1200×630 的图表与路由卡片、浏览器原生 WebM 录制、显式的 standard / showcase 质量配置文件，以及一个可选的部署所有权合约。

自动 Mermaid 解析、通用自动布局、托管共享和所见即所得编辑有意不在当前范围内。

归属

Archify 是 Cocoon-AI/architecture-diagram-generator v1.0 的一个分支和重写。原始视觉语言仍归功于 Cocoon AI；Archify 2.x 增加了主题、导出、类型化渲染器、验证、可访问性、交互和统一 CLI。两个项目均使用 MIT 许可证。

许可证

MIT — 免费使用、修改和分发。

贡献

欢迎提交 Issues、Pull Requests 和真实世界图表。从贡献指南开始，使用可重现的 bug 表单报告失败，或通过社区展示表单提交已验证的图表。