企业官网建设流程全解析

CI 里跑架构校验：Archify 接入流水线的三种姿势

【免费下载链接】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

当 AI 编码助手开始批量改代码，架构图成了最先失真的文档——PR 里悄悄加了一个服务、拆了一条依赖、挪了一层边界，没人会记得回头更新那张 PPT。社区里对 Archify 的讨论几乎都绕不开同一个词："可核验"：CSDN 多篇实测把它定位为"架构图与代码自动对账"、"CI 级自动校验"，本周 GitHub 热榜上它再度登顶，靠的不是画图好看，而是把"架构"从文档变成了可以被机器裁决的输入。Archify 的核验内核足够硬，才有资格进流水线：AI 生成结构化 JSON，确定性程序渲染与校验，schema、布局、HTML/SVG、路由、标签避让逐项 fail-closed，失败时给出机器可读的稳定诊断码，而不是一段 Node 堆栈。

这篇文章不评价它画得美不美，只回答一个问题：把 Archify 的校验装进 CI，有哪几种接法，各自解决什么问题？以下内容全部基于仓库源码与真实命令，你可以直接复制到自己的流水线里。

漂移为什么必须"失败即停"

架构校验进 CI 的第一原则是：校验器必须比审阅者更严格，且失败必须中断流程。Archify 的交付契约（delivery-contract.md）把这条写成了代码级约定：

• 机器回执而非人类话术。validate --json、deliver --json输出单一 JSON 对象，按arguments / input / prepare / render / check / receipt / commit阶段归类失败，携带稳定 rule code、具体对象、测量证据与supportedFixes；参数错误固定 exit status 2，非零退出永远不算成功。CI 脚本可以精确 grep 诊断码来给 PR 打注释，而不是解析自然语言。
• 原子交付。deliver把输入的 specification 字节快照写入同目录私有候选，渲染该快照，跑完整 artifact 检查，全部通过后才原子替换目标文件；任何失败都删除候选并逐字节保留旧 artifact。回执同时给出 specification 与 artifact 的 SHA-256 与字节数——"这次 PR 改了什么"有了可对账的哈希。
• Provenance 可追溯。check <output.html> --require-provenance把没有交付边车（.delivery.json、journal、lock）的产物直接判为失败，防止 CI 里出现"来路不明"的 HTML。

头条那篇"交图前过五道校验"说的就是finalize的一键链路：内嵌校验 → 原子交付 → 严格 provenance 检查 → 真实浏览器检查，四道门串成一条 fail-closed 管线，中途任何一道失败即停，输出<stem>.finalize-summary.json供修复使用。

姿势一：命令行直接接入，当最严格的 lint

Archify 的 CLI（archify/bin/archify.mjs）零依赖、Node >= 18，意味着 CI runner 上不需要npm install，checkout 下来直接能跑。五个 JSON Schema 在构建期被编译成提交进仓库的独立 ESM 校验器（见 generate-validators.mjs 与 CHANGELOG.md），无node_modules、无网络也能完成完整 schema 校验——这是它适合进流水线的关键设计。

把校验挂在 PR 上的最小 GitHub Actions 片段：

- uses: actions/checkout@v5 - uses: actions/setup-node@v5 with: node-version: 22 - name: 校验架构源文件 run: node archify/bin/archify.mjs validate architecture docs/architecture.json --quality showcase --json - name: 渲染并原子交付 run: node archify/bin/archify.mjs deliver architecture docs/architecture.json docs/architecture.html --quality showcase --json

--quality showcase意味着走严格档：回执要求九项 artifact 检查全过、零组合错误、零警告，而不是"能画出来就行"。交付成功后生成的 HTML 还可被下游browser-check用真实浏览器再验一轮渲染稳定性。

值得强调的是，Archify 对自己的 CI 就是按这个标准 dogfooding 的（.github/workflows/ci.yml）：Node 18/20/22/24 矩阵跑 golden file 与 schema 测试；重建archify.zip并逐字节 diff，陈旧直接报错；用真实 Chrome 解码 WebM 动画产物拒绝静态帧；校验稳定版清单必须与已发布的 Release 字节一致。一个画图工具把发布物、更新清单、跨平台路径契约全部纳入 CI，恰好示范了"校验进流水线"能做到多深。

姿势二：Skill 触发，让 AI 自己过闸

第二种姿势面向"AI 已经在改代码"的现实：让生成架构图的 Agent 自己把校验跑完，再把证明带回来。Archify 本身就是一个 Agent Skill，安装即用：

npx skills add tt-a1i/archify -g

装进 Claude Code 的~/.claude/skills/、Codex CLI 的~/.agents/skills/，或 Cursor、opencode、GitHub Copilot 对应目录后，SKILL.md 就变成了 Agent 的硬性工作流：完整首稿直接finalize，禁止先出临时图；非零退出永不视为成功；失败按回执的supportedFixes修复，且只有两轮修复配额；成功回执必须如实汇报"自动化检查通过"，不得谎称做过视觉审阅。

对 CI 而言，这意味着校验逻辑被前置到了生成现场：Agent 在本地编辑器里改完候选 JSON，先自己跑一遍finalize，通过后再 push。CI 上的validate不是第一道防线，而是对 Agent 自检的复核——同一套诊断码，本地和流水线两侧共享。更新检查（ARCHIFY_UPDATE_CHECK_DISABLED=1可关闭）也是 bounded 的：只提醒、绝不自动安装，离线 runner 不会有任何网络依赖。

姿势三：定时对账，抓"慢性漂移"

PR 门禁挡得住"这次改动"，挡不住"三个月没人碰"的慢性漂移。第三种姿势是把 Archify 的 compare 能力做成 nightly 对账任务，让架构基线自己过期。

compare对比已校验的 Before / Delta / After 快照并输出机器回执（checkout-platform-delta.receipt.json 是仓库内的真实样例）：组件与连接的 added / changed / removed / moved 数量、边界变化、presentation 与 provenance 是否变动，全部结构化。仓库里那张对比示意（）展示了同一架构两个版本间"新增了组件、改了连接、移了边界"的可视化结果。

定时任务只需三行核心逻辑：

schedule: - cron: '0 2 * * *' # 每天凌晨对账 steps: - run: node archify/bin/archify.mjs compare architecture baseline.json current.json delta.html --json

对账的意义不只是"发现漂移"，而是把漂移变成可归因的差异：回执里的rawSha256与semanticSha256双哈希能区分"换了个空格"和"拓扑真变了"；provenanceChanged标记仓库版本、来源链接模式是否被改。凌晨的 job 把 delta 回执写进 issue 或存档，比年底补一张架构图靠谱得多。

与 Codex CLI 串成一条链

三种姿势不是互斥的，它们在"AI 从建议者变成执行者"的工作流里正好串成一条闭环。以 Codex CLI 为例（Archify 官方支持它作为 Skill 宿主，README 的安装表明确给出~/.agents/skills/路径）：

1. 本地生成：开发者在 Codex CLI 里描述系统，Agent 按 Skill 契约生成候选 JSON，--repo-root指向仓库时，每个组件节点都会携带sources（文件路径 + 行范围），并绑定到固定 commit 校验 Git 顶层、origin、blob 与行界——证据不足的节点直接标为未知，绝不脑补（repository-authoring.md）。
2. 提交前自检：Agent 本地finalize过完四道门，回执里带 SHA-256 和浏览器证据。
3. 流水线复验：PR 触发姿势一的validate+deliver，CI 对同一份候选重算哈希与检查，失败即 merge 门禁亮红。
4. 定时对账：合入后，nightly 的compare持续追踪基线漂移；哪天发现sources指向的代码行已经和图上不一致，delta 回执会精确指出是哪个组件、哪条连接变了。

这条链的关键不在工具数量，而在每一环都产出同一格式的机器回执：本地 Agent、CI runner、定时任务共享诊断码与哈希约定，谁都可以验证上一环的结论。对于把 CI/CD 流程本身画成图的需求，Archify 的workflow类型（SKILL.md 的 Type 路由将其定位为"CI/CD、审批门、runbook"）还能把流水线结构可视化——用画 CI 的工具校验架构，再用它把 CI 画出来，闭环就完整了。

架构文档的宿命曾经是"画完即过期"。当校验器能进 PR 门禁、能随 Agent 一起写代码、能在深夜自动对账时，架构图第一次获得了和单元测试同等的地位：不是记录，而是约束。

【免费下载链接】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