archify

English · 简体中文

Archify

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

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

• 打开即可展示 —— 五种图表类型、四套预设、深色/浅色主题、内置品牌标识，以及有界（finite）动效
• 合并前审查架构变更 —— 将两个验证过的快照以 Before / Delta / After（变更前 / 变更差异 / 变更后）对比，精确呈现新增、移除、修改、移动和改道的事实
• 每次交互都脚踏实地 —— 可搜索节点，可选地打开经过修订校验的源码，追溯上游/下游作者定义的影响范围和精确路由，对比角色，播放引导式故事，而不会臆造拓扑
• 单文件，可信可分享 —— 类型化 JSON IR 和确定性检查生成自包含 HTML，以及 PNG、SVG、WebM 和 1200×630 分享卡片

当前开发版本： v2.16.0-dev.0。参见 Changelog（变更日志）。

项目页面 · 场景指南 · Proof Lab（验证实验室）

npx skills add tt-a1i/archify -g

使用 Cursor？打开 面向 agent 的快速开始 获取精确的全局和项目命令。

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

❤️ 赞助商

APINEBULA	APINEBULA 赞助 Archify，通过一个 API 即可接入 Claude、GPT、Gemini 等模型。通过 Archify 注册，使用 Archify 可享 9 折优惠。
EverMind · Raven	EverMind 赞助 Archify，并为 agent 构建记忆基础设施。其 Raven harness 支持将 Archify 作为 Skill，生成经过验证的交互式系统地图。

想赞助 Archify？邮件联系我们

看看 Archify 的实际效果

以下是 Archify 生成的实际产物，而非产品原型。点击任一帧打开其可交互、可分享的线上版本。

三个真实生成的产物。 Signal Flow · Blueprint · Classic · 打开交互式 Proof Lab ↗

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

Proof Lab 包含全部 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

DSH 社区可选集成：dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0

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 主题。它将技术意图转化为沟通产物。

工作原理

步骤	流程
生成	agent 从你的描述中创建类型化 JSON IR。
校验	内置校验器和布局规则检查源；失败会通过机器可读 JSON 精确定位局部修复。
预览（可选）	仅回环的桌面会话监视一个源，只重新加载已校验的修订；失败时保留上一个良好产物。
交付	在同目录下渲染并检查候选；只有通过的产物才会原子替换目标，然后可选的 --open 启动该精确文件。
迭代	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 停止。添加 --no-open 用于测试或当你自己打开打印的本地 URL 时。它不会向生成的 HTML 添加任何运行时。

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

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

设置：

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

meta.locale=en|zh-CN 会使页面标题、图例、状态/错误、辅助功能、HTML/SVG lang 本地化——从不影响作者定义的内容。否则请省略；保留所请求语言的文案；披露英语回退。静态模式省略 animation；默认使用 classic。

探索并分享输出

操作	控制
打开事实型图表指南	?
查找并聚焦语义节点	/
追溯上游/下游作者定义的影响范围	聚焦节点 → 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	在 Settings → Capabilities → Skills 下上传 archify.zip	取决于沙箱中的 Node.js 访问权限
Project Knowledge	将 archify.zip 上传到项目	基于提示词的架构回退

DeepSeek Harness： 社区集成，非 DeepSeek 官方产品；开发者预览版 @deepseek-ai/dsh@0.1.0-rc.6，Node ^22.19.0 || >=24.0.0。安装：dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0；调用：Use the archify skill to map this repository's runtime architecture.；卸载：dsh plugin --profile web remove @tt-a1i/archify-dsh。无遥测。Shell 文件需要精确的工作区路径，而非 Web Produced Files（Web 生产文件）。详情。

参考和范围

• Schema 参考 · Skill · 示例 · Agent 创作手册
• Changelog（变更日志）
• Roadmap（路线图）
• 生成的 Proof Lab

自动 Mermaid 解析、通用自动布局、托管分享和所见即所得编辑有意排除在现行范围之外。

许可证

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

贡献

欢迎提交 Issue、拉取请求和真实场景图。从贡献指南开始，使用可复现的 bug 表单报告失败，或通过社区展示表单提交已验证的图表。