Antigravity 迁移指南：10 月 5 日前升级本地任务

先弄清：这次变更影响什么

本文讨论的是 Gemini API 中的 Antigravity 托管智能体，不是安装在电脑上的 Antigravity IDE 更新。

两款产品共用部分运行时基础，因此名称相同。此次真正变化的是应用发送给 Google Interactions API 的智能体 ID；对部分集成而言，还包括应用自行处理的内置工具调用。升级 IDE 并不会替你更新这套 API 契约。

新版智能体是 antigravity-preview-09-2026，默认推理模型为 Gemini 3.8 Flash。不过，Antigravity Agent 指南也说明了如何通过 agent_config 选择其他受支持模型。此前的 Gemini 托管智能体详解介绍了托管工作区、后台任务和工具循环；本次迁移则更靠近底层：它决定任务还能否启动，以及工具调用能否继续执行。

Google 在 9 月 17 日的发布说明中给出了两条迁移路径：

• 在远程沙箱运行、且只读取 output_text 或 model_output 的任务，只需更换智能体字符串。
• 使用 local_environment 或解析 function_call 步骤的任务，还必须更新工具适配器。

判断标准就这一条。所谓适配器，是一小段应用代码：接收工具名称与参数，完成校验，执行本地操作，再返回结果。

Antigravity 迁移的核心：本地工具契约有 5 处变化

旧版智能体大多用宽泛的读、写操作处理文件。9 月版把文件操作拆成名称和参数都更明确的工具，同时将参数键从 snake_case 改为 PascalCase。

文件与搜索共有 5 类能力发生了变化，表中另有 2 个内置工具保持不变。这也解释了为什么即使智能体 ID 已更新，围绕 write_file 编写的兜底处理器仍可能失效。

新的编辑契约也更精细：智能体不再为一次小改动回传整份文件，而是给出行范围、预期原文和替换内容。如果 TargetContent 已经与文件不符，适配器就应拒绝执行。否则，延迟到达的任务可能覆盖人类刚完成的新修改。

哪些任务必须真正改造

个人开发者的远程报告任务

假设一个夜间任务让 Antigravity 在 Google 沙箱中收集数据、保存报告，最后只返回正文；应用读取 output_text，从不查看底层步骤。

这属于最轻量的迁移：把 antigravity-preview-05-2026 换成 antigravity-preview-09-2026，让一个有代表性的报告与旧任务并行跑一次，对比最终产物，再迁移调度计划。既然没有本地工具分发器，就没必要额外造一个。

在自有机器运行工具的平台团队

再看另一种场景：仓库任务的工具调用都在团队自己的 runner 中执行。它会读取文件、搜索代码、编辑配置，再把工具结果送回 interaction。

这类团队面对的是完整迁移。分发器必须识别新工具名、校验 PascalCase 参数、执行路径与命令策略、安全应用行范围修改，并按 interaction 预期的格式返回结果。做好这些，代码审查、报告生成和维护任务才能在 5 月版端点消失后继续运行。

消费每一步数据的可观测性团队

有些应用虽然全部在远程运行，却仍会把 function_call 步骤复制到审计日志、进度界面、审批队列或成本看板。这类系统并不属于“只看最终输出”。

即使内置文件系统操作由 Google 执行，解析器仍可能只认识 write_file、path 和 content。需要同步更新允许列表与测试夹具，避免看板把一次真实编辑标成未知操作、丢弃参数，或送入错误的审批策略。

管理无人值守触发器的运维负责人

定时触发器的风险最高，因为调用发生时没有人盯着。一个触发器会绑定智能体、环境、提示词和 cron 调度；如果已保存的 interaction 仍指向 5 月版智能体，调度本身可能显示健康，但 5 月版关闭后，背后的执行会失败。

因此，要盘点每个触发器定义中的智能体 ID，而不只是主应用 SDK 调用里的 ID。随后，按不同工具模式各做一次影子运行。报告任务和仓库修复任务即使都使用 Antigravity，也不能共用同一个迁移测试来代替验证。

用最小文件编辑测试验证适配器

最安全的第一项测试不需要生产凭证。给适配器传入一个保存下来的调用形状夹具，让它修改一次性文件，并断言只有目标行发生了变化。

下面这段代码由我用 Node 运行过，采用 Google 已公布的 replace_file_content 名称和 PascalCase 字段。它测试的是本地适配器，并未实时调用 Gemini API。

import assert from "node:assert/strict";
import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

function applyReplaceFileContent(call) {
  assert.equal(call.name, "replace_file_content");

  const {
    TargetFile,
    StartLine,
    EndLine,
    TargetContent,
    ReplacementContent,
  } = call.arguments;

  const lines = readFileSync(TargetFile, "utf8").split("\n");
  const current = lines.slice(StartLine - 1, EndLine).join("\n");
  assert.equal(current, TargetContent, "line window no longer matches");

  lines.splice(
    StartLine - 1,
    EndLine - StartLine + 1,
    ...ReplacementContent.split("\n"),
  );
  writeFileSync(TargetFile, lines.join("\n"));
}

const dir = mkdtempSync(join(tmpdir(), "antigravity-adapter-"));
const file = join(dir, "scheduled-job.env");
writeFileSync(file, "owner=ops\nstatus=old\nmode=scheduled\n");

applyReplaceFileContent({
  name: "replace_file_content",
  arguments: {
    TargetFile: file,
    StartLine: 2,
    EndLine: 2,
    TargetContent: "status=old",
    ReplacementContent: "status=ready",
  },
});

assert.equal(
  readFileSync(file, "utf8"),
  "owner=ops\nstatus=ready\nmode=scheduled\n",
);
console.log("PASS: line 2 changed from status=old to status=ready");

测试顺利通过。更关键的是，只要改动夹具中的 TargetContent，测试就会停止，而不会继续修改已经过期的内容。

商业账怎么算：迁移人力与任务停摆

Google 并未随本次智能体迁移宣布新的按 token 计费价格。真正变化的预算项，是工程与运维时间。

用两个简单公式即可：

对于只消费输出的远程任务，工程投入可能只是修改智能体字符串，再做一次影子运行。对于本地工具集成，则应为 5 类已变更能力、解析器夹具、安全测试，以及每种不同工作流形态的一次完整运行预留预算。

不要编造一个适用于所有团队的工时估算。功能单一的报告生成器与本地编码智能体，工具覆盖、审批逻辑和故障成本截然不同。把自己的综合工程费率和单次运行的业务价值代入公式，财务团队得到的才是可用决策依据，而不是一张供应商功能清单。

必须说清的限制

上面的本地测试只能证明夹具与适配器彼此一致，无法证明真实智能体面对每一种提示词时都会输出什么。本次运行没有 Gemini API 凭证，所以我没有假装执行过托管智能体。最后一道发布门槛，仍应是在一次性环境中捕获到的 9 月版智能体真实调用。

这次事件也不意味着所有 Antigravity 用户都要做同样的改造：

• 本周就行动：生产任务仍使用 antigravity-preview-05-2026，调用 local_environment、解析 function_call 步骤，或通过调度无人值守运行。
• 走轻量路径：任务在远程沙箱中运行，且只消费 output_text 或 model_output。更换 ID，再做影子运行即可。
• 新项目直接使用新 ID：仍在评估 API，且生产环境中没有 5 月版智能体任务。
• 无需参与本次迁移：只使用 Antigravity IDE，没有通过 Gemini API 调用托管智能体。

周一先做什么

先指定 1 位负责人统一盘点。在已部署配置、触发器定义、环境变量、看板和测试夹具中搜索 5 月版智能体 ID 与旧工具名。任何人动手改代码前，先把结果分成“只需更新输出链路”和“必须更新适配器”两张清单。

随后，从两张清单中各迁移 1 个有代表性的任务。检查 9 月版运行结果期间，保留但暂停旧调度；确认无误后，再按工作流类型迁移其余任务，并持续为未知工具调用设置告警，直至 10 月 5 日。周一要交付的不是幻灯片，而是一份写明负责人的清单、一次通过的影子运行，以及每个剩余任务的完成日期。

如需继续获取会真正影响工作流的变化解读，欢迎订阅邮件通讯。