信息卡

一句话定位

它不是一个独立应用，而是装进编码代理的能力：对 Raven、Cursor、Claude Code、Codex CLI 与 OpenCode 说一句话，就能把代码库或口头描述的系统变成带搜索、路径追踪与镜头切换的交互式系统地图，输出单个自包含 HTML 文件，且每一版都经过类型化验证门禁才允许交付。当前开发版为 v2.16.0-dev.0。

趋势解读：为什么火

架构图是工程协作里最痛的老问题之一：手绘的 Mermaid 迅速过时，AI 生成的图又常凭空编拓扑。archify 同时解决两个痛点——由 Agent 基于真实代码库生成保证新鲜度，再靠"验证门禁 + 不发明拓扑"承诺保证可信度。在 SKILL.md 生态爆发的 8 月，这种垂直深耕型工具拿下了增速榜第十四名。

核心功能拆解

• 五种图式覆盖全域表达：Architecture 讲组件与边界、Workflow 讲 CI 审批与工具调用、Sequence 讲 API 缓存与鉴权时序、Data Flow 讲管道血缘与 PII 流向、Lifecycle 讲状态重试与终局。
• 四种视觉预设配明暗主题与有限动效，兼顾演示美感与打印还原度。
• Before/Delta/After 对比模式：合并前精确标出哪些事实变更了，让评审直接对着差异说话。
• Grounded 交互：节点搜索、路由探测、上下游可达性与角色镜头全部锚定在已声明的组件上，不会临时虚构拓扑。
• 导出矩阵丰富：单文件自包含 HTML 外加 PNG、SVG、WebM 动画和 1200×630 社交分享卡。
• 校验门禁交付：任何一环不过关，坏候选永不替换上一张好图。

架构与技术栈浅析

主体是 Node.js 编写的零依赖 CLI（bin/archify.mjs），内部以类型化 JSON IR 作为唯一事实源，原子化校验分五道关卡：schema 合法性、布局可行性、HTML/SVG 渲染、路由有效性与标签避让。失败时返回稳定规则码、证据以及仅有的合法修复控件。可选 deployment-ownership 档案会在缺少归属或边界事实时直接 fail closed。预览服务器只绑定 127.0.0.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`。落盘位置因宿主而异：Claude Code 为 ~/.claude/skills/ 或项目 .claude/skills/，Codex 与 opencode 为 .agents/skills/，Raven 需手动解压 ZIP 到 ~/.raven/workspace/skills。

快速上手示例

自然语言入口示例："Use archify to map this repository's runtime architecture."。CLI 直接使用如下：

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 bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json
cd archify && node bin/archify.mjs doctor

doctor 用于体检环境，demo 一键生成示例站。

进阶使用要点

• 键盘即效率：问号呼出指南、斜杠搜索、R 探路由、L 比较镜头、M 雷达图、P 故事线、F 演示模式、S/T/E 切风格主题导出。
• 深链状态可分享复现：#focus=定位节点、#route=展示两节点间路径、#lens=叠加角色视角、#view=恢复视图。
• meta 里 locale 支持 en 与 zh-CN 但仅作用于界面文案，永远不会翻译你的业务内容。
• 迭代纪律是每轮最多两次聚焦修正，跟着诊断修点不要整图推倒重来。

典型应用场景

• PR 评审前对 base 与 head 各跑一份架构图，用 compare 输出 delta 网页逐项核对变更影响面。
• 新成员入职用 "map this repository" 摸清服务边界与数据流向，减少口口相传成本。
• 故障复盘时生成缓存未命中或死信队列时序图，邮件附件即单个 HTML 文件。
• 文档站嵌入导出的 SVG/PNG 保证版本一致。

同类生态位对比

Mermaid 与 draw.io 依赖手工维护且无正确性校验，Backstage 类目录偏静态资产登记；archify 主打"Agent 生成加类型化验证"防幻觉组合拳，并明确拒绝 Mermaid 解析、通用自动布局、托管分享与所见即所得编辑四件事来保持锋利。

资源导航

仓库主页见 github.com/tt-a1i/archify，许可证 MIT；CLI 子命令与安装变体见 README 使用章节；示例输入在 examples/ 目录；DeepSeek Harness 社区适配包为 dsh plugin 安装的 @tt-a1i/archify-dsh；明确不做的范围在 License & Scope 小节声明。