English · 简体中文

Archify

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

Archify 是一个用于 Raven、Cursor、Claude Code、Codex CLI 和 OpenCode 的 agent skill。提供系统描述或仓库，即可获得交互式、可共享的技术地图。

• 打开并展示——五种技术图类型、四种视觉预设、深色/浅色主题以及可选有限动画
• 合并前审查架构变更——比较两个经过验证的快照，显示之前/差异/之后，并精确列出添加、删除、更改、移动和重新路由的事实
• 每次交互都基于事实——搜索节点，可选打开经过版本验证的源代码，追溯上游/下游的编写范围和确切路径，比较角色，以及播放引导式故事，而不会凭空捏造拓扑
• 一个文件，即可信任和分享——类型化的 JSON IR 和确定性检查生成自包含的 HTML 以及 PNG、SVG、WebM 和 1200×630 分享卡片

当前稳定版本： v2.13.0。参见 变更日志。

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

npx skills add tt-a1i/archify -g

使用 Cursor？打开 agent感知快速入门 获取精确的全局和项目命令。

然后询问你的 agent：Use archify to map this repository's runtime architecture.

❤️ 赞助者

由 EverMind 赞助，为 agent 构建内存基础设施。其内存优先、自我进化的 agent 框架 Raven 将 Archify 作为 Skill 支持，将经过验证的交互式系统地图引入 Raven 工作流。

查看 Archify 运行示例

这些是生成的 Archify 工件，不是产品模型。单击一个框架即可打开其实时可共享状态。

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

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

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

从源代码映射的真实仓库

Archify 跟踪了 mco-org/mco（提交 9f1a1cf）并生成了这张经过检查的地图。打开它 ↗ · 追溯范围 ↗ · 类型化源文件

预览

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

深色	浅色

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

当你需要为 README、发布或社交媒体帖子准备一张规范的 1200×630 图片时，请使用 复制分享卡片。

追踪路径后，导出 → 路径分享卡片 会将该编写路径下载为 1200×630 PNG，并保留完整图表作为上下文。

跟踪已编写的 Upstream 或 Downstream 范围后，导出 → 范围分享卡片 会捕获该确切读数，而不声称运行时影响。

在本地打开 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 会保留输入的源，以便进行有针对性的迭代。

选择正确的图表

类型	适用场景	提示中应包含的内容
Architecture	组件、服务、存储、边界	范围、核心组件、主要路径
Workflow	CI/CD、审批、工具调用、运行手册	参与者、顺序、分支、异常
Sequence	API 调用、缓存回退、认证、异步追踪	调用方、被调用方、返回、时序
Data Flow	管道、血缘、PII、消费者	数据源、转换、存储、边界
Lifecycle	状态、重试、等待、终态结果	状态、事件、重试和取消路径

对于生产部署评审，Architecture 可以选择启用 deployment-ownership 工程配置。当缺少负责人、单区域部署、私有数据库范围或具名边界跨越时，它会拒绝通过（fail closed）。它绝不会被静默启用，并且验证的是人工编写的事实，而非实时基础设施。参见已检查的部署证明。

对于设计或 PR 评审，Architecture Delta 会将经过验证的 Before / Delta / After 快照与机器凭证进行比较。可以选择一个精确的人工变更，或执行一次有限的 Review——仅查看，不推断影响、风险或合并安全性。

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

Workflow 让各泳道中的正常路径保持清晰：

Sequence 解释一次随时间的交互：

Data Flow 让流转和敏感边界变得明确：

Lifecycle 区分进度、等待、重试和终态结果：

Architecture 示例：web-app · Archify pipeline · grid placement · desktop agent

为什么选择 Archify

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

Archify 不是通用绘图编辑器，也不是 Mermaid 主题。它将技术意图转化为沟通产物。

工作原理

步骤	详情
Generate	根据你的描述创建类型化 JSON IR。
Validate	内置验证器和布局规则检查源；失败时在机器可读的 JSON 中标明确切的局部修复位置。
Preview（可选）	仅限回环的桌面会话监视一个源，并且只加载已通过验证的修订；失败时保留上一次良好产物。
Deliver	在同一目录中渲染并检查候选文件；只有通过验证的产物才会原子地替换目标文件，之后可选的 --open 会启动该确切文件。
Iterate	agent 更新源，同时不相关的结构保持稳定。

有用的仓库命令：

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 停止。在测试或需要自行打开打印的本地 URL 时，添加 --no-open。它不会给生成的 HTML 增加任何运行时。

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

失败时，validate --json 和 deliver --json 仍会发出恰好一个 JSON 对象。读取 diagnostics[] 并使用其 supportedFixes 仅修改命名的主题；不要重写整个图表，也不要超出 Skill 的两轮聚焦修正。确定性诊断与视觉审查保持分离。

可选的动画和呈现样式是显式的：

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

省略 animation 可获得真正静态的图表。classic 仍为默认值；editorial 会添加温暖的出版外观。

探索并分享输出

操作	控制
打开事实性图表指南	?
查找并聚焦语义节点	/
追踪上游/下游的已创作可达范围	聚焦节点 → 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	手动 ZIP 至 ~/.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	在设置 → 功能 → 技能下上传 archify.zip	取决于沙箱中的 Node.js 访问权限
项目知识	将 archify.zip 上传到项目	提示驱动的架构回退

参考与范围

• Schema 参考
• Skill 与渲染器契约
• 示例
• 变更日志
• 路线图
• 生成的验证实验室

Archify 2.13 包含五种模式下的类型化 IR、真实仓库验证、确定性精确 ID 架构 Delta 审查、已验证的实时预览、已创作的可达性、真实的可配置图例、可选的有限动画、引导视图、语义搜索与关系探索、可共享的深度链接、1200×630 的图表和路径卡片、浏览器原生 WebM 录制、显式的 standard / showcase 质量配置文件，以及一个可选的部署所有权契约。

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

许可证

MIT — 可自由使用、修改和分发。

贡献

欢迎提交 Issue、Pull Request 和真实世界图表。请先阅读贡献指南，使用可重现的错误表单报告失败，或通过社区展示表单提交经过验证的图表。