企业官网建设流程全解析

把 Archify 装进 Cursor 和 Claude Code：Skill 插件接入实操

【免费下载链接】archifyTurn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.项目地址: https://gitcode.com/GitHub_Trending/arch/archify

Archify 最近频繁出现在 GitHub Trending 周榜榜首，从"画架构图的 Agent 项目"变成了开发者社区的讨论焦点：社区截图显示它曾以 2.8 万星重返第一，skills.sh 上的安装量已超过 13 万。但很多人把它误读成"又一个 Mermaid 替代品"，忽略了它真正的产品形态——一个以 Agent Skill 为核心分发包、附带确定性渲染与校验管线的开源工具。这带来一个非常实际的问题：它既不是npm install就能用的普通 CLI，也不是开箱即用的桌面软件，而是需要"装进"你的 Cursor、Claude Code 等 AI 编程工具的插件。

本文直接基于仓库源码，回答三个问题：为什么 Archify 选择 Skill 而不是普通 CLI 的形态、在 Cursor 与 Claude Code 两套环境里各自怎么接入、装好之后如何用自然语言生成并持续迭代架构图。

一、Skill 插件机制：为什么是 Skill 而不是普通 CLI

先看一个容易忽略的事实：archify/package.json里声明了bin入口（package.json），同时整个技能包又是以archify/SKILL.md为核心的。普通 CLI 和 Skill 的本质区别在于谁来使用它：CLI 是给"人"用的，人要先想清楚命令再执行；Skill 是给"Agent"用的，它把完成一项工作的方法论（触发条件、生成步骤、校验契约、失败修复路径）完整交给 Agent，让 Agent 在合适的时机自主调用。

这个设计的核心证据就在archify/SKILL.md的 frontmatter 里：

name: archify description: "Create polished, validated architecture, workflow, sequence,>node bin/archify.mjs finalize <type> <candidate.json> <output.html> --quality showcase --json

finalize一次运行会依次通过 schema 校验、布局规则校验、HTML/SVG 成品检查、以及真实浏览器渲染检查四道闸门（SKILL.md）。失败时返回的不是一段 Node 堆栈，而是带规则码、具体对象和supportedFixes的机器可读修复回执。从archify/bin/archify.mjs的命令分发可以看出完整的子命令面（bin/archify.mjs）：render、validate、deliver、finalize、preview、compare、check、visual-check、browser-check、guide、doctor、demo等。这套管线回答了一个被反复追问的问题："AI 画的架构图凭什么信？"——因为图不是 AI 直接输出的像素，而是 AI 产出结构化数据、确定性程序渲染并逐项核验的结果。

二、Cursor 与 Claude Code 两套接入步骤对比

2.1 通用安装：一条命令

仓库 README 给出的最简安装方式只有一条命令（README.md）：

npx skills add tt-a1i/archify -g

-g表示全局安装。装完后向 Agent 发送一段自然语言描述即可开始出图，不需要任何额外配置。仓库同时提供了一个零依赖的验证入口：archify/bin/archify.mjs doctor返回Archify is ready.即表示环境就绪。

2.2 Cursor：显式参数安装

Cursor 的接入需要把目标 Agent 显式写在命令里。仓库 README 专门给出非交互式安装命令：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

这条命令的每个参数都有含义：--skill archify指定包内的技能名，--agent cursor指定安装目标，--global安装到用户级目录，--copy与--yes让过程无需交互。安装后 Skill 落在 Cursor 可识别的 Agent skills 路径（~/.agents/skills/archify/）下，与该路径下的bin/archify.mjs一起组成完整的渲染器与校验管线。

仓库里的archify/test/cursor-onboarding.test.mjs直接证明了这个过程是可验证的：测试将archify.zip解压到.agents/skills/目录，运行doctor确认就绪，然后对 architecture、workflow、sequence、dataflow、lifecycle 五类示例逐一执行validate，全部返回receipt.ok === true。同一份 Skill 包、同一条 CLI 入口，在不同 Agent 目录下行为完全一致——这就是 Skill 生态"一次编写、多端接入"的典型形态。

2.3 Claude Code：目录级安装

Claude Code 的接入路径在仓库的安装方式表中写明（README.md）：Skill 可以安装到用户级目录~/.claude/skills/，也可以安装到项目级目录.claude/skills/。两者差别在于作用域：项目级安装让团队共享同一份图定义和校验契约，用户级安装则对所有项目生效。安装完成后同样通过npx skills add tt-a1i/archify -g的通用方式即可。

两套环境的差异用一个对比表就能说清：

另外还有两条可选路径值得一提：Claude.ai 网页端支持直接上传archify.zip（Settings → Capabilities → Skills），依赖沙箱内的 Node.js 访问能力；如果完全没有 Shell 访问权限，SKILL.md 还提供了把 SVG 手工嵌入assets/template.html的降级方案。

三、交互式编辑：用自然语言生成并持续改图

3.1 从一句话到一张图

安装完成后，第一张图不需要任何 JSON 知识。README 给出了最小示例：

Use Archify to diagram a web request: Browser calls the API, the API checks Redis, and a cache miss queries PostgreSQL and fills the cache.

Agent 会根据SKILL.md的 Type router 判断这是sequence类型，引用对应 schema 与示例（archify/examples/cache-miss-request.sequence.json），直接产出候选 JSON，再运行finalize完成门禁。五类图的选型由仓库内archify/SKILL.md的类型路由表给出：architecture管组件与服务、workflow管流程与审批、sequence管调用链与异步、dataflow管管线与血缘、lifecycle管状态与重试。

除了自然语言，Agent 还能"读懂"Mermaid：flowchart映射为 workflow 或 architecture，sequenceDiagram保留参与者与消息语义，stateDiagram保留状态与迁移——转换的是拓扑和含义，而不是机械搬运样式。

3.2 关键设计：图背后永远有一份可编辑的 JSON

自然语言编辑之所以可靠，是因为图不是一次性产物，而是"JSON IR → HTML"的持续映射。每次新请求都会在.archify/<type>-<slug>-<时间戳>/目录下生成独立的candidate.json，对话中任何一句"加个节点"或"换条路径"都落在 JSON 上，再走同一套finalize门禁。因此文档里明确承诺：add Redis、move auth to the left、highlight the rollback path这类口语指令都可以连续执行，且无关结构保持稳定——只改被点名的局部，而不是每次重画整张图。

3.3 代码驱动的"真图"：从仓库反向生成

当图必须反映真实代码时，Archify 走的是 repository authoring 路径（repository-authoring.md）：Agent 先阅读仓库取证，生成的 Architecture 节点会标注SRC n证据标记，指向固定在单个公开 commit 上的 Git 校验文件和行范围。仓库中还内置了--repo-root参数把本地仓库路径传给校验器，Archify 会核验远端、commit、blob 与请求的代码行，无法验证的版本绝不添加证据。这条路径把"架构图"从演示文稿升级为可追溯的工程文档，也回应了社区热议的"架构漂移"问题——代码改了，图可以重新取证生成，而不是靠人肉维护。

3.4 交付物与日常迭代体验

最终产物是自包含的单文件 HTML：内联 SVG、暗/亮双主题一键切换、节点聚焦与上下游追踪、定向路径探测（#route=web~db）、可分享的深链。导出菜单支持 PNG/JPEG/WebP/SVG/WebM 与分享卡（1200×630），无需安装任何查看器即可传播。日常迭代还有两个贴心机制：preview模式在127.0.0.1随机端口开启仅回环的桌面预览，只在候选通过全部门禁后才刷新，保存失败时保留上一张已验证的图；更新感知则在交付回执里附带update.noticeRequired提醒——但它永远不会自动安装更新，装不装、何时装完全由你决定（可设ARCHIFY_UPDATE_CHECK_DISABLED=1关闭联网检查）。

小结

Archify 的接入体验揭示了当前 AI 编程工具链的一个清晰趋势：工具不再以"命令清单"交付，而是以"能力契约"交付。SKILL.md 既是 Agent 的触发器和操作手册，也是校验管线的规格书；npx skills add tt-a1i/archify -g之后，Cursor 和 Claude Code 里的 Agent 就同时获得了一套"能生成、能校验、能修复、能溯源"的架构图生产能力。对开发者而言，值得记住的其实只有三点：装的是 Skill 而不是裸 CLI，图背后永远有一份可编辑的 JSON，以及 AI 负责想象、确定性程序负责把关。

【免费下载链接】archifyTurn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.项目地址: https://gitcode.com/GitHub_Trending/arch/archify