企业官网建设流程全解析

老仓库直接跑不动？Archify 落地大型项目前要避开的 5 个坑

【免费下载链接】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 上拿下周榜第一的核心卖点。它的思路很朴素却极其严谨：AI Agent 负责把仓库读成一份带类型约束的 JSON，再由确定性程序完成渲染与逐项校验，杜绝 AI 编造结构。但越是严谨的流水线，越会在"真实的大型单体仓库"上暴露边界条件——老仓库动辄十几万行代码、几十年的历史包袱、混杂的依赖关系，直接丢给 Agent 往往不是"秒出图"，而是一连串finalize失败与修复死循环。

本文不堆概念，直接打开 Archify 仓库源码，把落地大型项目时最容易踩的 5 个坑逐个拆开：每个坑对应哪个校验规则、报什么诊断码、源码里怎么拦的、正确的姿势是什么。

坑一：把"当前工作区"当成唯一真相

很多人在大型仓库里让 Agent "读一下当前代码"，结果 Agent 顺手把本地还没提交的改动、甚至node_modules里的临时文件当作架构依据画进了图里。Archify 对此的态度非常明确：证据只认钉死的提交，不认工作区。

在 repository-authoring.md 的第一节，作者用近乎苛刻的措辞规定了"冻结身份"：

1. 记录git rev-parse HEAD、git remote get-url origin、git status --short；
2. 对 origin 做脱敏（去掉用户名、密码、token），保留传输协议、端口、路径与.git后缀，不允许把内网 SSH origin 改写成 HTTPS；
3. 在meta.repository里钉死 40 位完整 revision 与脱敏后的 URL；
4. 若工作区是脏的，必须记录变更路径——证据只针对该 revision 下的已提交字节（committed bytes），绝不针对工作区编辑（working-tree edits）；对任何被引用的变更路径，都要回到该 revision 的干净检出里核实。

换句话说：大型仓库里最常见的"我本地刚改完还没提交，你按这个画"的诉求，从契约层面就是不被接受的。落地建议很直接——画图前先git stash或切到干净分支，并让 Agent 从git status --short的输出开始，而不是从你的口头描述开始。

坑二：仓库身份没冻结：短 SHA、本地路径、非顶层目录

这是大型仓库上失败率最高的一个坑，也是诊断码最密集的一块。Archify 的证据校验集中在 repository-evidence.mjs，每一个错误都有明确的规则码和supportedFixes：

const FULL_SHA_RE = /^[a-f0-9]{40}$/i; // ... if (!FULL_SHA_RE.test(repository.revision || '')) { evidenceFailure('repository-evidence/revision-invalid', '/meta/repository/revision must be a full 40-character commit SHA.', ...); }

四件事缺一不可：

• Revision 必须是完整 40 位 SHA。8f3a2b1这种短 SHA 直接报revision-invalid，不会"自动补全"——大型仓库历史深、引用多，短 SHA 有歧义风险，校验器选择 fail closed。
• meta.repository.url必须是 credential-free 的远程地址。源码里专门抓了"把本地文件系统路径填进 URL"这个高频错误，给出提示："the expected value is the remote origin address"。
• 本地 checkout 的 origin 必须与声明一致，否则报origin-mismatch。
• --repo-root必须是 Git 顶层目录。很多人图省事把--repo-root指到子目录或 monorepo 的某个 package，源码用git rev-parse --show-toplevel实测后报root-not-top-level，并直接把正确路径写进supportedFixes。

这四道关卡合起来回答一个根本问题：你声称画的"这个仓库"，到底是不是物理上存在、可验证的"那个仓库"。老仓库常见的多个 fork、镜像、改名历史，都会在这里暴露。

坑三：地图炮式全仓扫描——耗时与 token 双双失控

大型单体仓库最容易犯的错误，是让 Agent "通读一遍再画"。十几万行代码进上下文，token 先爆炸，生成耗时就失控。Archify 的探索契约恰恰反着来：按需切片，小步溯源。

repository-authoring.md 的"Explore on demand"一节写得很具体：

Read a small connected slice instead of scanning the repository for a convenient label. … Batch independent relevant files when known. Each additional read should answer an unresolved question that can change the diagram.

翻译成落地话术：从入口点、配置文件、注册清单出发，顺着 import 和调用点一路追到实际的输入/输出/副作用，而不是把仓库当字典翻。每多读一个文件，都必须能回答一个"会改变图"的未决问题。对老仓库里那些"导出了但从没人调用"的遗留模块，契约明确判为"可选能力，不是必需运行时边"——这直接帮你过滤掉历史遗留代码对依赖解析的干扰。

性能层面也不是没兜底。同样是 repository-evidence.mjs，证据读取做了批量优化，而不是逐条 spawn git 进程：

const result = spawnSync('git', ['--no-replace-objects', '-C', repoRoot, 'cat-file', mode], { input: objects.join('\n') + '\n', maxBuffer: 64 * 1024 * 1024, });

一次git cat-file --batch-check摸清所有被引用对象的存在性与类型，再按需用--batch拉内容；同时设有单文件 16MB 上限（MAX_SOURCE_BYTES = 16 * 1024 * 1024），超限文件自动降级为按路径引用、不加载内容。这套"批量预取 + 上限兜底"的设计，就是为"仓库很大但图要快"准备的。

正确姿势是：让 Agent 带上--repo-root走完整finalize，由校验器来决定哪些证据成立，而不是人肉引导它全仓扫一遍。

坑四：引用幽灵文件与越界行号

图上每个带SRC n标记的节点，背后都必须是一组真实存在、范围精确的源码引用。Archify 的路径校验严格到近乎强迫症：

if (segments.some((segment) => !segment || segment === '.' || segment === '..') || segments[0] === '.git') { evidenceFailure('repository-evidence/path-escape', `${where} must stay inside the repository and may not address .git.`, ...); }

仓库相对 POSIX 路径、禁止./../空段/.git/反斜杠/控制字符——所有规则都写在verifiedSourcePath里，一条条拦。后续还有三道实弹校验：

• file-missing：<revision>:<path>在git cat-file -t下不是 blob，直接判定"该文件在该提交下不存在"；
• line-out-of-range：引用行号超过文件实际行数（先取 blob 内容按行数精确比对，不是近似估算）；
• end_line < line这类区间倒挂也会被单独拦截。

老仓库的"幽灵引用"重灾区：删过的文件路径、重构后行号漂移、从旧分支拷贝来的引用。最有效的预防手段是让 Agent边读边记——读到的真实路径和行区间立刻写入sources，而不是画完图再回头补引用。画完后，validate --json会一次性把全部幽灵引用以稳定规则码报出来，配合supportedFixes定点修复，而不是给你一段 Node 堆栈让你猜。

坑五：把修复当无限重试，以及绕不开的输出路径契约

前四个坑都会把finalize变成非零退出。此时最大的陷阱是"无脑重试"。Archify 的交付契约把修复回合数写死成了硬上限：

If an issue survives two focused repairs, inspect measured geometry or the relevant contract; after one evidence-based retry, report the concrete gap.

配合 SKILL.md 与 delivery-contract.md 里的规则，三条铁律务必记住：

1. 非零退出永远不是成功，不允许跳过校验或"手动补一个 HTML 就算过"；
2. 修复回合上限correction_rounds: 2，两轮聚焦修复后还没过，就该回到几何/契约层面找根因，而不是继续撞运气；
3. 禁止删证据、藏 overflow 来"骗过"检查——契约明确写着 "Do not hide overflow, clip content, introduce an internal diagram scroller…"，也不允许删掉已有证据来让重试通过。

另一个大型团队常栽的坑是输出路径。meta.output被规定为便携 POSIX 相对路径（如reports/diagram.html）：禁止绝对路径、禁止反斜杠、禁止 Windows 8.3 短名（PROGRA~1这类）、禁止.git段、组件长度不得超过 255 字节；CLI 参数则按宿主系统原生语法解析。在 Windows 上拉一个 Linux 团队写的仓库，第一轮finalize十有八九会撞output/meta-absolute或output/meta-path-syntax。别改契约，改路径。

最后是"与既有文档/图谱工具共存"的边界感，仓库里写得比想象中克制。SKILL.md 的 Mermaid 输入契约是"读取拓扑与含义，然后重新编写 Archify JSON，不机械渲染 Mermaid 样式"；workflow 渲染器对 schema v1 的老文件承诺"逐字节保留、绝不静默重解释为 v2"（renderers/workflow/README.md）；README 更直接把 Automatic Mermaid parsing、通用自动布局、托管分享、WYSIWYG 编辑列为明确不做的范围。同时，每次新请求都独占.archify/<type>-<slug>-<时间戳>/目录，老版本天然保留——这保证了在大型仓库里反复迭代时，上一版成功的产物不会被下一版覆盖。看懂这条边界，就知道 Archify 的定位是"把你的技术意图变成可核验的沟通产物"，而不是取代你现有的文档体系。

把"跑不动"拆成可验证的门

回头看，这 5 个坑其实指向同一个方法论：Archify 把所有模糊环节都变成了可验证的门——身份门（40 位 SHA + origin 匹配）、范围门（切片探索 + 批量读取）、证据门（文件存在 + 行号精确）、修复门（两轮上限）、路径门（便携 POSIX）。老仓库跑不动，从来不是因为"仓库太大"，而是因为这些门在进场前就被绕过了。

落地清单一句话总结：画图前冻结干净提交、填对 40 位 SHA 与脱敏 origin、让 Agent 从入口点切片溯源而不是全仓扫描、边读边记引用、修复最多两轮。做到这五条，几十万行的老仓库也能稳定产出那张"敢拿出去对齐"的架构图——就像仓库里那份真实溯源产物 docs/cases/mco-runtime.architecture.json 展示的那样，每个节点都钉在具体的文件与行号上，经得起任何人打开源码逐条对账。

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