Archify

Archify

将代码库或系统描述转换为可直接在聊天中呈现的、可交互的系统架构图。

Archify 是面向 Raven、Cursor、Claude Code、Codex CLI 与 OpenCode 的代理技能。给定系统描述或仓库，可产出可交互、可分享的技术架构图。

核心特性

• 即时呈现：内置五种技术图类型（架构、工作流、时序、数据流、生命周期）、四种视觉预设、明暗双主题，可选有限动效。
• 合并前评审：对两个已校验快照执行 Before / Delta / After 对比，精确标注新增、删除、变更、移动与改道事实。
• 可追溯的交互：节点搜索、可选打开版本校验后的源代码、上下游作者可达性分析、精确路径追踪、角色对比、按剧本播放；不臆造拓扑，不宣称运行期影响。
• 单一输出文件：类型化 JSON IR 与确定性校验产出独立 HTML，并支持 PNG、SVG、WebM 与 1200×630 分享卡片。

当前稳定版本：v2.14.0。

快速开始

安装

npx skills add tt-a1i/archify -g          # 全局安装技能

无需安装的试用方式：

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

DeepSeek Harness 社区集成（非官方）：

dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0

Raven 需手动解压 archify.zip 至 ~/.raven/workspace/skills，得到 ~/.raven/workspace/skills/archify。

第一张图

向代理发出指令：

分析本仓库，然后使用 archify 创建一张高层运行时架构图。
包含 8 到 12 个核心组件、一条主路径、外部依赖与信任边界。
细节使用卡片呈现，不要增加更多边。

聚焦某一流程：

使用 archify 绘制登录流程：浏览器 -> Web 应用 -> API -> JWT 校验 ->
Redis 会话查询 -> PostgreSQL 回退，将缓存未命中路径作为次要路径。

随后可在聊天中迭代：add Redis、move auth to the left、highlight the rollback path。Archify 保留类型化源码以支持定向修改。

图类型选择

类型	适用场景	提示中需提供
Architecture	组件、服务、存储、边界	范围、核心组件、主路径
Workflow	CI/CD、审批、工具调用、Runbook	参与者、顺序、分支、异常
Sequence	API 调用、缓存回退、鉴权、异步轨迹	调用者、被调用者、返回、时序
Data Flow	管道、谱系、PII、消费者	来源、转换、存储、边界
Lifecycle	状态、重试、等待、终态	状态、事件、重试与取消路径

Architecture 可启用 deployment-ownership 工程配置；缺失负责人、单区域部署、私有数据库范围、命名边界穿越时失败并阻断，永不静默启用，且只校验作者事实，不涉及运行期基础设施。

合并前评审可使用 Architecture Delta：对比两个已校验快照，提供机器可读回执。可选择某一精确变更或播放一段有限的 Review——仅查看器、不推断影响、风险或合并安全性。

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

不确定使用哪种图类型时：

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

技术架构

• 布局判断优先：由代理决定层级、间距、路径与强调方式，共享自动端点以确定性方式分散，避免箭头堆叠。
• 类型化 JSON IR：每个由渲染器支撑的模式都附带模式定义与可复现源。
• 交付前原子校验：模式、布局、HTML/SVG、路径、标签到路径净空检查全部通过后，展示工件才会替换上次已知良好产物。
• 失败附带修复回执：validate --json 与 deliver --json 返回稳定的规则代码、确切主体、实测证据，仅给出受支持的修复选项而非 Node 栈或无结构重试猜测。
• 保留上次良好预览：可选的桌面循环监视单一 JSON 文件，仅在最新候选通过所有关卡后刷新；保存不完整或无效时保留上一次已校验图。
• 真实交互：聚焦、上下游可达、精确路径、角色对比与剧本均复用作者节点与关系，不臆造拓扑，不宣称运行期影响。
• 按需的源证据：基于证据的 Architecture 节点标记为 SRC n，可打开钉在某一公开提交上的、经 Git 校验的文件与行范围；普通工件不附带源码。
• 默认可移植：结果为单一 HTML 文件；导出保留完整图，不含临时查看器状态。

工作流程

阶段	行为
Generate	代理根据描述生成类型化 JSON IR
Validate	内置校验器与布局规则检查源，失败时输出机器可读的本地修复建议
Preview（可选）	仅本地回环的桌面会话监视单一源，仅在通过校验后刷新；失败时保留上次良好工件
Deliver	同目录候选被渲染与检查；仅通过的工件以原子方式替换目标；可选 --open 启动该文件
Iterate	代理更新源，未涉及的结构保持稳定

常用命令：

node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
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 停止；不增加生成 HTML 的运行时开销。deliver --open 是一次性本地交付，通过校验后才会启动，成功交付不会被 OS 打开器不可用转为失败；JSON 输出至 stdout，手动打开的绝对路径输出至 stderr。

动效与演示样式需显式配置：

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

省略 animation 即生成完全静态图。classic 为默认预设；editorial 提供更温暖的刊物风格。

查看与分享操作

操作	控制键
打开图说明	?
查找并聚焦语义节点	/
追踪上下游作者可达性	聚焦节点后选 Upstream / Downstream
探查有向路径	R 或 PATH
对比一至两个语义角色	L 或 LENS
打开实时概览雷达	M 或 MAP
播放剧本 / 变更章节	P / [ ]
进入演示模式	F
切换视觉样式 / 主题 / 打开导出	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，不会进入规范导出。

安装方式

载体	位置或方式	能力
Raven	手动解压 ZIP 至 ~/.raven/workspace/skills	完整渲染器与校验流程
Claude Code	~/.claude/skills/ 或 .claude/skills/	完整渲染器与校验流程
Codex CLI	~/.agents/skills/ 或 .agents/skills/	完整渲染器与校验流程
opencode	~/.config/opencode/skills/ 等	完整渲染器与校验流程
Claude.ai	在设置中上传 archify.zip	依赖沙箱中的 Node.js 能力
Project Knowledge	上传 archify.zip 至项目	由提示驱动的架构回退

不在范围

自动 Mermaid 解析、通用自动布局、托管分享、所见即所得编辑均明确不在当前范围内。

许可

MIT 协议，可自由使用、修改与分发。