30秒速览
- 把五万文件塞进 Gemini 1.5 Pro 之前，光是清洗压缩就花了三天，但模型确实能生成出人意料的结构化索引
- 分阶段提问比一句“架构怎么样”有效百倍——先建心智地图，再追依赖和反模式，模型就能给你实打实的证据
- 别信模型输出的代码引用，它经常把名字相同的函数跨服务胡乱配对，得用符号表和静态工具交叉验证
光是准备“饲料”就花了三天——代码仓库不是想塞就能塞的
说实话，我第一次听到“百万 token 上下文”的时候，脑子里蹦出来的场景就是把整个微服务仓库扔进去，然后翘着腿等模型给我生成一份完美的架构文档。事实证明我太天真了。我们的仓库里有大概5万个文件，包括了13个微服务，每个服务都有各自的 source、test、config、proto，还有一堆让人头皮发麻的 node_modules 和生成的代码。直接全塞是不可能全塞的，必须先做清洗。我先用一把简单粗暴的过滤器：只保留 .ts、.js、.proto、.json（仅限 package.json 和 tsconfig.json）、.yaml，并把 node_modules、dist、coverage 目录整棵砍掉。这一刀下去，5万个文件就剩不到1万8了，大小也从1.2GB降到不到180MB。但即便是180MB的纯文本，也远超过Gemini 2.5 Pro当时标注的1M token上下文窗口——按平均4字符一个token算，差不多700万字符，得压缩到150万字符以内才安全。
我当时的做法是，把每个文件前面加上一个很短的路径标记，然后用 “`ts 包裹起来，再在后头留两个空行。这样做的目的是让模型既能区分文件边界，又能把代码上下文串成一个巨大的流式文本。我写了个Python脚本，边遍历文件边按需截断一些巨大的JSON schema和自动生成的protobuf定义，把代码部分保留完整，最后生成的文本大概有140万字符。我用tiktoken库粗略估了一下，差不多是95万 token，刚好卡在1M window以下，还能留出一点空间给系统提示和回答。但问题是 Vertex AI 的 gemini-2.5-pro 虽然支持1M上下文，却对单次请求有输入长度限制，默认好像是20万字符？我没记住确切数字，反正我第一次用那个拼接好的大文本直接调用 generate_content，API 直接回了一个 400 错误，说 payload 太大。
我后来才发现，Vertex AI 在调用 Gemini 2.5 Pro 时，如果上下文超长，是需要用文件上传的方式来走非流式传输的。我当时没找到特别清晰的文档，反复试错之后才摸到门道：先把整个文本保存成一个 .txt 文件，上传到 Cloud Storage，然后通过 Part.from_uri 来引用。但这也意味着不能在一个 prompt 里同时放文件和一个巨大的文本字符串。所以我干脆把整个仓库文本分成两个部分：第一部分是前80%的核心业务代码（差不多按字母序排的服务），第二部分是剩下的通用库和基础设施代码，分别上传两个文件。然后在 prompt 里这样写：
from vertexai.generative_models import GenerativeModel, Part
model = GenerativeModel("gemini-2.5-pro")
core_code = Part.from_uri("gs://my-bucket/repo-core.txt", mime_type="text/plain")
infra_code = Part.from_uri("gs://my-bucket/repo-infra.txt", mime_type="text/plain")
prompt = """
你是一个精通TypeScript微服务架构的专家。下面有两个文件，是同一个代码仓库的核心业务代码和基础设施代码。
请先仔细阅读全部内容，然后生成一份包含所有微服务模块的全局索引。
"""
response = model.generate_content([core_code, infra_code, prompt])
这样就能一次性让模型读完整个仓库，而且响应也很顺畅。但 Vertex AI 的速率限制又给了我当头一棒。长上下文请求消耗的配额极高，我一开始没注意看 Quota，直接连续发了好几个 prompt，很快就被限流了，返回 429。后来我加了一个简单的指数退避，并且在每次 generate_content 后故意等20秒，才把整条链路跑顺。那几天光是把“饲料”准备好，就磨掉了我无数耐心。
直接问“架构怎么样”跟对墙说话没区别——我用三段式提问逼出模型的结构化思考
模型能读完整个仓库只是第一步，怎么问才是真正见功力的地方。我最早是图省事，直接一个 prompt：“请分析这个仓库的架构，列出所有服务、模块依赖关系、可能存在的问题。” 结果模型给我的回复是一段笼统的描述，大致是“这是一个基于微服务的电商平台，服务之间通过REST和消息队列通信，看起来组织良好”。我当时差点把笔记本合上——这跟 ChatGPT 3.5 时代说“你的代码看起来不错”有啥区别？后来我才慢慢摸索出一套心法：不能一下丢出太开放的问题，你得帮模型建立“心智地图”，也就是先让它对全局有一个结构化的认知，然后才去探究具体问题。
我设计的第一个 prompt 就是生成全局索引。这个 prompt 的要求非常具体——不要求分析，只要求提取事实：每个服务的主目录、主要职责、暴露的API端点（从代码里推断，不是从文档）、用到的数据库或外部系统、关键入口文件。这相当于让模型把整个仓库从一团乱线梳理成一个结构化的 JSON 输出。我指定了输出格式，大致是{“services”:[{“name”:””,”responsibility”:””,”apiEndpoints”:[],”database”:””,”keyEntry”:”src/server.ts”}]}。结果模型真的输出了一份非常详尽的 JSON，13个服务一个不落，而且职责描述准确得吓人，比如“payment-service 负责处理支付请求、与Stripe集成、并发布 PaymentProcessed 事件到Kafka”，连具体的 topic 名都给出来了。我拿着这份索引去跟同事核对，他们看了都说“比我们 Confluence 上的架构文档还全”。
第二个阶段是识别模块边界。这时我给了模型一个新的 prompt，把第一步生成的 JSON 作为上下文的一部分，再附上原始代码文件，要求：“基于上述全局索引，对于每对微服务，找出代码中实际存在的依赖关系。请关注 import 语句、HTTP 客户端调用、数据库共享表名、消息 topic 的订阅发布、共享库的引用。区分直接调用和间接消息依赖。以表格形式输出，每行包含源服务、目标服务、依赖方式、依赖强度（高、中、低）。” 这个 prompt 比第一个更聚焦，模型输出了一个非常干净的 Markdown 表格。我把它导出成 CSV，用 Python 简单画了个图，发现 payment 和 order 之间存在强双向依赖，shipping 和 inventory 之间也有一条通过消息队列的间接依赖，而静态工具根本没抓到。
第三个阶段是发现反模式。这时候模型已经对整个仓库有了“心智地图”，我直接把前两步的结果和原始代码一起喂进去，要求：“已知上述依赖关系图，请识别至少 5 个架构反模式，例如循环依赖、共享内核滥用、服务边界过于模糊、API 版本不一致、数据库跨服务直接访问等。为每个反模式提供具体证据（文件路径和代码片段），并评估风险级别。” 这次模型不仅找到了 21 个循环依赖（其中 4 个是真正的直接循环调用，其他是通过消息队列的异步循环），还指出了 3 个服务共享了同一个数据库表的直接写操作，这在我们团队当时根本没意识到。这种分阶段提问的方式，就像是你先带模型逛一遍仓库，指给它看每个房间的布局，再问“你觉得厨房和厕所为什么连在一起？”——它立马就能给出具体判断。
它生成的diff比实习生写的还工整，但我不敢直接合并——流水线里的“三振出局”策略救了我
架构诊断只能算前半场，让我真正心动的是能不能让模型直接动手重构。我当时选了 inventory 和 shipping 之间那个通过 Kafka 事件触发的循环依赖作为试点。具体来说，inventory-service 在扣减库存后会发送 InventoryReserved 事件，而 shipping-service 订阅了这个事件后创建发货单，成功后又向 Kafka 发送 ShipmentCreated，inventory-service 又订阅了这个事件去更新订单状态。这一来一回虽然消息解耦了，但本质上形成了一个事件循环，而且如果 shipping 失败，inventory 的状态会不一致。
我的想法是让模型生成一个重构方案，拆解这个循环。我给它的 prompt 里明确要求：“不要只给建议，直接生成代码 diff。对涉及的文件，输出 unified diff 格式，注明旧代码和新代码。改动必须保持现有测试全部通过。” 并且我特意把测试文件也放在了上下文里，让模型能预判影响。模型花了一分多钟处理，最后返回的 diff 让我有点意外——它没有简单粗暴地删掉一个订阅，而是引入了领域事件存储表，让 shipping-service 改读这个表而不是直接发事件给 inventory，然后 inventory 通过定时任务去查询未处理的发货结果。换句话说，模型自己设计了一个“请求-响应”风格的补偿机制，而不是继续在异步事件里打转。
但我还是不信。我把那个 diff 存成文件，写了个小脚本自动应用到本地分支，然后跑测试。第一轮就跑挂了：一个关于库存补偿的集成测试直接报空指针，因为模型改了一处 service 方法，却漏掉了对 mock 的重置。我把报错信息连同原始 diff 重新喂给模型：“你的重构导致了这个测试失败，请修复。” 它又生成了第二版 diff，这次只多改了一行测试代码。再次跑，仍然失败，但这次只是因为订单状态 assert 的 expected 值还用的是旧逻辑。第三次重新生成之后，测试全绿了。我定了个规矩：最多三次修复机会，如果还跑不通，就直接丢弃该重构建议。这种方式被我称为“三振出局”，虽然有点粗暴，但能快速滤掉那些模型很难彻底修好的复杂改动。
跑通测试只是第一步，我还在流水线里加了一道静态分析过滤。每次模型生成 diff 后，我除了跑现有的 Jest 测试，还会用 eslint 和 TypeScript 编译器做检查，确保没有引入新的类型错误。同时，我用了一个叫 dependency-cruiser 的工具生成依赖图，把模型中建议删除的依赖与新生成的代码依赖做对比，看看是否真的解耦了。有一次模型声称解决了循环依赖，但 dependency-cruiser 发现它只是把循环从直接的函数调用变成了通过 Redux store 的间接依赖，本质没变。这种交叉验证虽然繁琐，但让我敢于把一部分模型建议真的合并到主干。那次仓库重构，我们最后采纳了 19 个 diff 里的 11 个，成功率超过 50%，对于一个完全由 AI 驱动生成的提案来说，我觉得已经相当可观了。而且整个重构建议的生成时间，比我手写这些改动要快至少两倍，尤其是那些需要横跨多个服务的修改，人工搞起来简直要扒层皮。
模型一口咬定PaymentService依赖OrderService的一个私有方法，我翻遍代码都没找到
一致性问题是长上下文模型最大的软肋，尤其当它试图引用跨文件的代码片段时，很容易出现“幻觉引用”——看起来有模有样，实际压根不存在。有一次我让模型解释某个循环依赖链的具体调用路径，它给出的回答里有一条是：“payment-service 在 src/handlers/checkout.ts 中直接调用了 order-service/src/services/OrderValidator.ts 的 validateOrder 私有方法”。我看到这个描述时第一反应是这不可能，因为我们的代码规范不允许跨服务直接调用内部方法，更何况是私有方法。我马上打开这两个文件，搜索了半天，根本没有任何这种调用。但我又有点心虚——万一模型看到的是一种更隐晦的调用，比如通过内部 NPM 包？我又全局搜索了 validateOrder，结果只在 order-service 自己的文件里找到，其他服务根本没有引用。
这件事让我意识到，你绝对不能把模型的代码引用当作事实。它就像一个记忆力超群但偶尔胡说的同事，能背出几百行代码，但有时候会把两个完全不相关的概念揉在一起。为了系统性地解决这个问题，我写了一个交叉验证脚本，专门用来检查模型输出中提到的文件路径、方法和类是否真实存在。基本逻辑是用 TypeScript 的 compiler API 构建一个全局符号表，从所有 .ts 文件里提取 export 出来的类、函数、方法签名，然后对模型输出的每一条“A 调用 B”的引用去这个表里查 B 是否真的存在，并且是否从 A 文件中被 import。我还考虑了别名导入和 barrel exports 的情况，虽然不能覆盖全部场景，但足以过滤掉大多数编造的引用。
import * as ts from "typescript";
import * as fs from "fs";
function buildSymbolTable(filePaths: string[]): Map {
const table = new Map();
for (const file of filePaths) {
const source = fs.readFileSync(file, "utf8");
const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
const functions: string[] = [];
ts.forEachChild(sourceFile, (node) => {
if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isClassDeclaration(node)) {
const name = (node as any).name?.text;
if (name) functions.push(name);
}
});
table.set(file, functions);
}
return table;
}
// 然后用这个 table 去匹配模型提到的调用
我把这个验证过程做成一个 GitHub Action，每次模型生成架构报告后自动跑，发现无效引用就直接给报告打上“含幻觉内容”的标记，并且附上验证失败的条目。刚开始的时候，差不多有 15% 的引用是假的，后来我发现如果在 prompt 里明确要求“只引用你确定存在的文件路径和方法，并用 `filePath#method` 格式给出”，然后再用 few-shot 示例给它看正确和错误的例子，幻觉率能降到 5% 以下。不过代价是 prompt 会变长，上下文消耗更多。我现在还会搭配 Madge 这种静态依赖分析工具，把模型输出的依赖图跟 Madge 生成的纯 import 依赖图做 diff，如果模型声称的某条依赖在静态图里完全不可见，我就会特别小心地去人工确认。
最可笑的一次是，模型把 order-service 内部的 OrderValidator 和 payment 服务里一个叫 validateOrder 的私有辅助函数搞混了，因为名字一样，它就脑补出了跨服务调用。这件事让我彻底明白：长上下文模型虽然能一次性理解全仓库，但它没有一个真实的执行环境来验证跨模块引用。你必须自己搭建一个验证管道，把它的输出当作“高度可疑但值得参考”的草案，而不是最终诊断。说到底，百万 token 上下文更像是一张巨大的工作台，让你把所有零件铺开，但真正组装的时候，你的眼睛和静态分析工具一个都不能偷懒。
