项目详情
Archify
在聊天里把代码库变成可验证的交互式架构图——单 HTML 交付
GitHub 地址
MIT
Agent Skill
v2.16.0-dev.0
Node.js 零依赖 CLI
更新于 2026-08-27
← 返回汇总
项目速览
一句话定位
让 Agent 画出「讲真话」的架构图
面向 Raven / Cursor / Claude Code / Codex CLI / OpenCode 的 Agent Skill。输入代码仓库或系统描述，产出带类型化 JSON 中间表示、经过确定性校验的自包含交互式 HTML 架构图。不是 Mermaid 主题皮肤，也不是 WYSIWYG 绘图器——它是「技术意图 → 可信沟通产物」的转换器。
为什么存在
架构沟通的三个痛点
Mermaid 千篇一律
自动布局不读语义：主路径和支线混在一锅，箭头在中点堆成一坨。换主题只是换皮，信息架构没变好。
WYSIWYG 太重
draw.io 类工具的编辑面板本身成了产品。评审者要的是「读懂图」而不是「学一个绘图软件」。
AI 画图会撒谎
LLM 直接生成图时容易发明不存在的连线、暗示没有的运行时流量。评审者无法区分「事实」和「脑补」。
Archify 的答案：类型化 JSON 源 + 确定性校验管线 + 只做「有据可依」的交互——图的每个焦点、每条路径、每次高亮都来自作者声明的拓扑，不发明事实。
核心理念
Truth before Spectacle
设计原则六条，全部围绕「证据优先于表演」：
原则 1
先真后炫
焦点、可达性查询、路由、故事、源码链接必须全部派生自声明或验证过的证据。
原则 2
一条主叙事
先让主路径可读，再揭示次级关系与细节。一条明显的主路，支线从最近的主路节点出发。
原则 3
渐进披露
画布保持主导，不堆面板。悬停、聚焦时才展开卡片和元数据。
原则 4
动画有界
静态语义必须完整，动画有限且由读者控制，导出永远干净。尊重 prefers-reduced-motion。
原则 5
可携带的证明
默认产出单个自包含 HTML，确定性校验，不依赖托管运行时。分享卡明确命名自己的范围。
原则 6
品牌不漂移
内置品牌徽标用 digest 固定，永远不替代节点类型、标签、关系的语义契约。
核心能力
五种图类型，各管一段
| 类型 | 最适场景 | Prompt 里给什么 |
|---|
architecture | 组件、服务、存储、信任边界 | 范围、核心组件、主路径 |
workflow | CI/CD、审批门、工具调用、runbook | 参与者、顺序、分支、异常 |
sequence | API 调用链、缓存回退、认证、异步追踪 | 调用方、被调方、返回、时序 |
dataflow | 管道、血缘、PII、消费者 | 数据源、转换、存储、边界 |
lifecycle | 状态机、重试、等待、终态 | 状态、事件、重试与取消路径 |
拿不准？问零依赖 CLI：node bin/archify.mjs guide "Show an API request with Redis cache miss" --json。SKILL.md 同时接受 Mermaid 输入——但只读拓扑语义，然后重新作者化 JSON，不机械套样式。
架构
工作管线：五步，步步有闸门
Generate 生成→
Validate 校验→
Preview 预览（可选）→
Deliver 交付→
Iterate 迭代
- Generate：Agent 从描述产出 typed JSON IR——每种图类型有独立 schema，节点类型固定七种（frontend / backend / database / cloud / security / messagebus / external）
- Validate：捆绑校验器查 schema、布局、HTML/SVG、路由、标签与路由间隙——showcase 级要求 9 项检查全过、0 错误 0 警告
- Preview：可选桌面回路，只监听 127.0.0.1 随机端口，盯一个 JSON 文件，只有通过全部闸门的版本才刷新；失败时保留上一个验证过的图
- Deliver：先渲染同目录候选件并检查，只有通过才原子替换目标 HTML；报告 SHA-256 与字节数回执
- Iterate：Agent 只改被诊断点名的 subject，无关结构保持稳定
架构
确定性验证：失败给「修复回执」
校验失败时不抛 Node 栈、不靠 LLM 瞎猜重试——validate --json 返回稳定规则码、确切 subject、测量证据、只列受支持的修复动作。
- 原子交付：showcase 产物只有通过全部检查才替换上一个已知良好输出
- 聚焦修复：改且只改诊断点名的对象；连续两轮无改善就停下，如实报告未解决项
- visual-check：交付后在 1440×900 / 1600×1000 / 1920×1080 / 2048×1320 四档测溢出，截明暗双主题截图，出 contact sheet
# 校验一个候选图
node bin/archify.mjs validate workflow \
examples/agent-tool-call.workflow.json \
--quality showcase --json
# 失败时读 diagnostics[]，按 supportedFixes 修
# 交付 = 最终验收，原子替换 + SHA-256 回执
node bin/archify.mjs deliver workflow \
examples/agent-tool-call.workflow.json \
/tmp/workflow.html \
--quality showcase --open --json
核心能力
Architecture Delta：合并前审查架构变更
对两个已验证快照做机器回执对比，输出 Before / Delta / After 三段视图，列出精确的 added、removed、changed、moved、rerouted 事实。
- 设计评审 / PR review 场景：选一条确切变更或播放一段有限 Review 章——仅查看器视图，不做影响、风险或合并安全推断
- deployment-ownership 工程档案：生产部署审查可选启用；缺 owner、单区域放置、私库范围、具名边界穿越时 fail-closed
- 永不静默启用：只验证声明的事实，不验证实际基础设施
node archify/bin/archify.mjs \
compare architecture \
base.json head.json \
architecture-delta.html --json
示例：examples/checkout-platform-delta.html
核心能力
Grounded 交互：每个动作都有出处
- 搜索聚焦：/ 找到语义节点后聚焦；可达性查询只复用声明的节点和关系，不发明拓扑
- 上下游追踪：聚焦节点后按 Upstream / Downstream 展示「作者声明的」影响范围——绝不宣称运行时影响
- 路由探测：R 查两点间最短有向路径，逐步走完整 journey
- 语义透镜：L 对比一两个角色间的真实流量（如 backend vs database）
- 引导故事：P 播放有限命名的章节，叙事有限、读者可控
- 源码证据（可选）：Evidence-backed 节点标
SRC n，打开 Git 验证过的文件与行区间，钉在一个公开 commit 上；普通产物默认无源码
核心能力
键盘即操作台
| 动作 | 按键 |
|---|
| 图表指南 / 搜索节点 / 总览雷达 | ? · / · M |
| 路由探测 / 语义透镜 / 故事 | R · L · P（章节 [ ]） |
| 演示舞台 / 切风格 / 切主题 / 导出 | F · S · T · E |
| 缩放与复位 | + · - · 0 |
稳定深链：#focus=、#route=src~dst、#lens=a~b、#view=——任何图状态都能一键还原成 URL 分享。
技术细节
设计系统：Evidence Console
「自信的技术仪表」：暗色优先、mono 字体贯穿、密度服务于工程评审。饱和色只标语义，从不做装饰。
七色语义词汇
每种颜色绑定一种节点/关系含义，深浅主题与四个视觉预设共享同一词汇表：
frontend · 青色
backend · 绿色
database · 紫色
cloud · 琥珀
security · 玫红
messagebus · 橙
external · 灰蓝
- JetBrains Mono 全栈：标题到标签统一 mono，1.5rem/700 标题、0.625rem/700 标签 + 0.12em 字距
- 状态转换 140–200ms；故事动画可以更长但必须有界且读者控制
- 明暗主题平价：Light / Dark 与 Signal Flow / Blueprint / Classic / Editorial 预设共享同一语义几何
- 反 AI 味清单：拒绝密集仪表盘壳、无限同款卡片网格、装饰性玻璃、渐变文字、无限图标市场
技术细节
导出：一个文件，处处能开
自包含 HTML
默认产物。单文件内联 SVG，零运行时依赖，本地双击即开，主题/缩放/搜索/故事全内置。
静态与动态导出
Export 菜单：PNG 复制到剪贴板、PNG/SVG/JPEG/WebP 下载、WebM 动图。导出永远保留完整图，不带临时查看器状态。
1200×630 分享卡
README / 发布 / 社交用规范卡。追踪路由后有 Route Share Card，追踪上下游后有 Reach Share Card——都明确命名自己的范围。
真实案例：Archify 追踪了 mco-org/mco@9f1a1cf 整个仓库，产出带源码证据的 runtime 架构图——Proof Lab 里 11 个场景全部连同 JSON 源、命名视图、校验回执一起 checked-in。
快速上手
三条命令跑起来
# 1. 安装（全局）
npx skills add tt-a1i/archify -g
# 免安装试用（Codex）
npx skills use tt-a1i/archify@archify \
--agent codex
# 2. 健康检查 + demo
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
# 3. 对 Agent 说一句有边界的话
Use archify to map this repository's
runtime architecture.
# 或聚焦一条流
Use archify to draw this login flow:
Browser -> Web App -> API -> JWT
-> Redis session -> PostgreSQL
fallback. Keep cache-miss secondary.
- 迭代在聊天里完成：「add Redis」「move auth to the left」「highlight the rollback path」——typed 源保持可定点修改
- 安装面：Raven（ZIP 手动）、Claude Code（~/.claude/skills/）、Codex CLI（~/.agents/skills/）、OpenCode、Claude.ai（上传 zip，沙箱内需有 Node）、DeepSeek Harness（社区插件 @tt-a1i/archify-dsh）
在线体验
亲手玩一遍 Grounded 交互
迷你工作台复刻 Archify 核心机制：左边编辑 typed JSON，右边实时渲染分层架构图。点击节点追踪上下游 reach，选两端探测最短路由，验证面板实时跑确定性检查。
单文件 · 零网络依赖 · 深色工作台
质量文化
Ordinary-Model Floor：普通模型也能一次过吗
仓库自带基准套件，只回答一个窄问题：普通编码 Agent 第一次尝试能否产出可用的 Archify 图，无需人工修 JSON？
Gate 1
语义正确
语义要求在场且连接正确。渲染合法但语义错的图 = 失败。
Gate 2
确定性校验
真实 Archify CLI 通过 validate --quality showcase --json。视觉漂亮但校验失败 = 失败。
Gate 3
人工复核
指定评审者检查最终渲染产物、记录 passed、报告无缺陷。缺复核就如实报告，绝不升格为通过。
五任务覆盖全部五种图类型；公平协议要求同 prompt、同 commit、同 skill、同时限、同工具、干净输出路径；候选件冻结后零事后编辑（包括人工）。这不是模型排行榜，是交付闸门。
生态位
出身与对立面
- 出身：SKILL.md 元数据声明 based_on Cocoon-AI/architecture-diagram-generator (MIT, v1.0)——从单一架构图生成器长成五类型全管线工具
- 赞助方：APINEBULA（Claude/GPT/Gemini API 聚合）、EverMind · Raven（Agent 记忆基础设施）
- 规模：178 commits · 1.3k forks · 31 open issues · 主语言 HTML（渲染器 + Node CLI）
README 点名的四类反面对照
- 只换主题不改信息架构的 Mermaid 美化器
- 编辑面板本身成为产品的 WYSIWYG 绘图套件
- 暗示不存在关系的 motion-first 图表演示
- 密集仪表盘壳 / 无限卡片网格 / 渐变文字等 AI 生成套路
明确不做：Mermaid 自动解析、通用自动布局、托管分享、WYSIWYG 编辑。
风险提示
需要警惕
- 开发版版本：v2.16.0-dev.0，迭代极快，API/契约可能变动；生产使用前锁 commit
- 单一主维护者：tt-a1i 个人项目，bus factor 低；社区贡献依赖 contribution guide + showcase 表单流程
- 图质量依赖 Agent 水平：layout judgment 交给 LLM——这正是 Ordinary-Model Floor 基准存在的原因，弱模型可能通不过 showcase 闸门
- 宿主环境要求 Node：Claude.ai 沙箱内依赖 Node.js 访问，能力受限；无 shell 时降级为手放 SVG 进模板
- 评审受众是桌面：窄屏只做安全容器化，不是一等公民产品面
适用场景
适合谁用
- 架构师 / Tech Lead：把仓库证据变成可信、可演示的架构叙事，评审时每个结论都有回执
- PR 作者与评审者：合并前用 Architecture Delta 展示变更事实，替代口头描述「我改了哪几条线」
- AI Agent 开发者：目前最完整的「Agent Skill 工程化」范本——typed IR、确定性闸门、修复回执、交付冻结、基准协议都可直接借鉴
- 文档工程师：给 README / 发布说明生成 1200×630 规范分享卡与自包含交互图
潜力评估
未来空间
4 个月 18.6k stars 说明「可信 AI 生成图」切中真实需求。若 Agent Skill 生态继续标准化，Archify 的 typed IR + 校验回执模式有机会成为 Agent 产物可信化的参考实现——不只是画图工具，更是「AI 产物如何自证清白」的方法论样本。