用代码地图减少 Agent 重复扫描

一句话结论

这篇帖子记录了作者在 Antigravity 2.0 中使用 Gemini 3.8 Flash 时，模型反复读取相同文件、消耗大量配额并破坏代码的经历。评论给出一种可复用的缓解工作流：先维护小型代码知识库，再按代码地图定位到相关功能和实现文件，避免每个提示词都重新扫描整个仓库。

适用场景

• 适合的任务：中大型代码仓库的定位、增量修改、测试前检查，以及需要控制上下文读取量的编码 Agent。

• 前置条件：Agent 具备读取/写入仓库和运行测试的权限；知识库文件应与代码一起维护。

• 不适合的任务：没有测试或回滚能力的生产环境直接修改；也不应把社区评论当作 Gemini 3.8 Flash 的官方行为保证。

• 适用的模型与客户端：原帖使用 Antigravity 2.0 中的 Gemini 3.8 Flash；没有公开 API 模型 ID、thinking level、温度、上下文配置或完整 system prompt。

可直接使用的内容

1. 代码知识库工作流（评论原文整理，保留约束）

评论者 GrillePainVert 描述的做法如下；这是评论者分享的工作流，不是原帖作者已验证的官方方案：

让 Agent 为代码建立一个知识库，知识库文件每个最多 200 行。

知识库应包含：
- 代码地图（code map）
- 架构文件
- 功能文件
- 功能与实际实现它的代码文件之间的链接

始终先从知识库开始搜索。

工作过程中持续构建或更新知识库。

每次新的讨论先分析代码地图，再分析代码地图指向的功能文件，最后只分析实际相关代码文件中的相关部分。

它对应的最小执行顺序是：

代码地图 → 相关功能摘要 → 相关实现片段 → 修改与测试 → 回写知识库

2. JSON 返回约束输入（评论原文）

另一位评论者 Chemical_Hawk_6307 给出的实际输入是：

Do not search, list directories, write, or request sandbox bypass.

该评论说明这段指令用于一个“让 Gemini 3.8 Flash 在沙箱中返回 JSON”的简单任务；原评论没有公开 JSON schema 或完整用户输入，因此不能补写成更完整的 API 提示词。

输入—输出案例

案例 A：知识库工作流

• 输入：一个需要定位和修改功能的中大型代码仓库，以及上述代码地图、架构摘要和功能摘要。

• 预期流程：先检索知识库，按链接只读取相关实现，再修改、测试并更新知识库。

• 评论者声称的效果：可减少重复扫描和 token 消耗；原评论没有给出节省比例、仓库规模、测试日志或独立复测。

案例 B：严格 JSON 沙箱任务

• 输入：要求模型返回 JSON，同时明确要求不要搜索、列目录、写文件或请求沙箱权限绕过。

• 原评论记录的结果：模型没有直接返回 JSON，而是开始搜索，反复运行 pwd/尝试列目录。

• 可见问题：约束未被遵守；评论没有展示模型的完整输出、JSON schema、运行环境或请求日志。

原帖中的编码任务结果

原帖作者称自己在 Antigravity 2.0 中测试 Gemini 3.8 Flash：

1. Windows 显示控制应用：要求审计 bug、修复并测试；作者称模型找到了一些问题，但部分修复失败，测试不充分，应用仍会静默崩溃。

2. Three.js 游戏：要求使用现有素材增加一组简单功能并再次测试；功能大体加上了，但作者认为代码质量差、没有抽取可复用部分，并很快发现游戏 bug。

3. 部署/迁移工具：先让模型提出增强点，再选择要实施的项目；模型实施后开始测试，但作者很快在日志中看到异常。

作者还称，单次任务曾消耗 Google AI Pro 五小时用量的约 93%，随后切回 Gemini 3.7 Flash，认为后者在同样尝试中更快且结果可用。以上是单个用户的主观报告，不是受控基准。

测试/工作流步骤

1. 在可回滚的分支或沙箱中建立 code-map、架构和功能摘要，控制每个知识库文件不超过 200 行。

2. 为每个功能摘要链接实际实现文件、测试文件和关键入口；链接失效时及时更新。

3. 给 Agent 新任务时，先要求读取代码地图和相关功能摘要，再打开必要的实现片段。

4. 对修改类任务明确写出测试命令、通过条件和停止条件；不要只写“请测试”。

5. 发现 Agent 重复读同一文件、持续运行命令或偏离目标时，停止当前会话并从知识库摘要重新开始，避免继续消耗配额。

6. 测试通过后，把新增结构和决策回写知识库；保留 diff、日志和失败记录，便于下一次定位。

适用边界与核验说明

• “代码知识库能节省大量 token”是评论者的经验性判断，没有公开前后 token 计量，不能外推为固定收益。

• 原帖只描述了 Antigravity 2.0 的客户端体验，没有公开 Gemini 3.8 Flash 的 API 调用参数、快照、完整系统提示、工具 schema 或重试策略。

• 原帖作者报告的“93% 用量”“静默崩溃”“重复读取”和“切回 3.7 后成功”均来自单个会话的主观记录；没有仓库、日志或独立复现材料，不能据此宣称模型普遍失效。

• JSON 案例只公开了短约束和失败现象，没有公开完整输入、期望 schema、原始响应或沙箱权限配置；复现时必须自行补齐这些信息。

• 只在有权访问的仓库和测试环境中使用；知识库可能包含内部架构、路径或安全信息，分享前应脱敏。不要把 API Key、token、用户数据或生产凭据写入知识库。

• 代码地图不是事实核验机制，也不能替代测试、代码审查、回滚和人工批准；这与已收录的 agy_help 四层事实核验 Agent 属于不同用途。

来源摘录或观察（合规短引）

评论者将工作流概括为：先分析 code map，再分析其中的 feature 文件，最后只分析相关代码文件中的相关部分。该顺序的价值在于限制读取范围；但它是否改善 Gemini 3.8 Flash 的实际成功率，原帖没有给出可重复实验。