老仓库直接跑不动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 的第一节作者用近乎苛刻的措辞规定了冻结身份记录git rev-parse HEAD、git remote get-url origin、git status --short对 origin 做脱敏去掉用户名、密码、token保留传输协议、端口、路径与.git后缀不允许把内网 SSH origin 改写成 HTTPS在meta.repository里钉死 40 位完整 revision 与脱敏后的 URL若工作区是脏的必须记录变更路径——证据只针对该 revision 下的已提交字节committed bytes绝不针对工作区编辑working-tree edits对任何被引用的变更路径都要回到该 revision 的干净检出里核实。换句话说大型仓库里最常见的我本地刚改完还没提交你按这个画的诉求从契约层面就是不被接受的。落地建议很直接——画图前先git stash或切到干净分支并让 Agent 从git status --short的输出开始而不是从你的口头描述开始。坑二仓库身份没冻结短 SHA、本地路径、非顶层目录这是大型仓库上失败率最高的一个坑也是诊断码最密集的一块。Archify 的证据校验集中在 repository-evidence.mjs每一个错误都有明确的规则码和supportedFixesconst 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-missingrevision: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 里的规则三条铁律务必记住非零退出永远不是成功不允许跳过校验或手动补一个 HTML 就算过修复回合上限correction_rounds: 2两轮聚焦修复后还没过就该回到几何/契约层面找根因而不是继续撞运气禁止删证据、藏 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 的老文件承诺逐字节保留、绝不静默重解释为 v2renderers/workflow/README.mdREADME 更直接把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考