实用提示：如何利用 Gemini 托管代理与 Google 应用程序结合使用
《实用笔记》操作指南：如何利用 Gemini 托管代理与 Google Apps 搭配使用——为采用该模式的团队提供合同、检查清单以及可直接插入的代码片段。
以下内容为“利用 Gemini 托管代理与 Google Apps Script”提供实用实施路径。重点在于合同规范、检查项以及可直接插入的代码占位符，而非激励性表述。
摘要
在撰写摘要阶段时，首先明确合同规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续代码修改的规范性。 优先选择小型、可测试的代码单元，而非冗长的脚本。当某一步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 每次调用时都要记录请求 ID、模型 ID 以及延迟时间。没有这些记录，间歇性的服务提供商错误就会被视为应用程序故障。
引言
在完成入门阶段时，首先写下契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，并杜绝无声的半完成状态。 每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务端错误就会被视为应用程序的故障。
架构范式：为何选择直接的云对云流传输？
在完成“架构范式：为何直接处理”这一阶段时，首先需列出相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在代码从演示环境转向共享环境时出现意外费用。 每次调用都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务端错误就会被视为应用程序的故障。
通过双向流式传输大幅节省输入令牌
在实施“大幅减少输入令牌消耗”阶段时，首先需记录下合约的详细信息：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会偏离原定方向。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。 每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，偶尔出现的服务端错误就会被误认为是应用程序的故障。
通过共享的持久化沙箱降低处理成本
在分阶段降低流程成本时，首先需明确相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明可追溯。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的功能。 每次调用时都要记录请求编号、模型编号以及响应延迟时间。如果没有这些记录，间歇性的服务错误就会被视为应用程序的缺陷。 在分阶段降低流程成本时，首先需明确相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明可追溯。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，绝不允许出现无声无息的部分完成情况。
工作流程
将工作流阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份优秀的测试用例、一个故障案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解这些成本，就能避免在从演示环境过渡到共享环境时出现意外费用。
仓库
将仓库阶段视为可度量的对象来使用效果最佳。在扩大范围之前，先记录一份完美的测试用例、一个故障案例以及回滚说明。 将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，这样操作人员无需查看整个系统结构即可进行审计。 在讲解循环逻辑之前，先锁定解释器及依赖项的版本。笔记本电脑与持续集成环境之间的差异是导致 API 演示出现故障的最常见原因。
使用方法
在将“使用阶段”视为可度量的对象时，其效果最佳。在扩大范围之前，先记录一个成功的用例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。在讲解循环逻辑之前，先锁定解释器及依赖项的锁文件。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障原因。
1. 获取 Gemini API 密钥
在“1 获取 Gemini API”阶段，将其视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一份成功的示例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 在讲解循环之前，先确定解释器版本及依赖项锁定文件。笔记本电脑与持续集成环境之间的差异是 API 演示中最常见的隐性故障原因。
2. 创建 Google Apps Script 项目
将“创建Google Apps”这一阶段视为可衡量的工作面最为有效。在扩大范围之前，先记录一份最佳实践案例、一个失败案例以及回滚说明。 把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现悄无声息的半完成状态。 在讲解循环逻辑之前，先固定解释器及依赖项的锁定文件。在笔记本电脑与持续集成环境之间切换是API演示中最常见的隐性故障来源。
3. 部署客户端脚本并设置脚本属性
将“部署客户端脚本”这一阶段视为可度量的指标会更为有效。在扩大范围之前，先记录一份理想的运行日志、一个故障案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，就能避免在从演示环境过渡到共享环境时出现意外费用。
4. 所需授权范围
将“4个必需的授权范围”这一环节视为可度量的指标来处理效果最佳。在扩大授权范围之前，先记录一份完美的测试用例、一个失败案例以及回滚说明。 应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 在讲解循环逻辑之前，先锁定解释器及依赖项的版本。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障来源。
云端测试（Google Apps Script）
在 Google Cloud 测试环境中，若将其视为可度量的测试对象，效果会最佳。在扩大测试范围之前，需记录一份理想的测试用例、一个失败案例以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。在开始循环测试之前，先锁定解释器及依赖项的版本文件。笔记本电脑与持续集成环境之间的差异是 API 演示中最常见的隐性故障原因。在 Google Cloud 测试环境中，若将其视为可度量的测试对象，效果会最佳。在扩大测试范围之前，需记录一份理想的测试用例、一个失败案例以及回滚说明。应将此测试阶段视为输入与经过验证的输出之间的契约，为相关文件命名，明确成功标准，杜绝隐性部分完成的情况。
1. 部署统一的 Linux 沙箱环境
在“准备统一阶段”中，需在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境切换到共享环境时出现意外账单。应将客户端构建与消息循环分开，这样即便更换提供方，也无需重写对话状态机。
2. 测试1：用户代理自定义与POSIX套接字验证（runTest1_UserAgentComparison）
在“2次测试1种用户代理”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 将客户端构建与消息处理循环分开，这样在更换提供方时无需重写对话状态机。
3. 第2次测试：ggsrun部署与直接访问验证（runTest2_GgsrunDirectDeployment）
在3 Test 2 ggsrun阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 应将客户端构建部分与消息处理循环分开，这样即便更换服务提供商，也无需重写对话状态机。 在3 Test 2 ggsrun阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与验证后输出结果之间的契约。需为相关产物命名、明确成功判定标准，并杜绝无声的半完成状态。
4. 测试3：使用Playwright无头模式进行抓取并直接上传到驱动器（runTest3_PlaywrightDirectUpload）
在开展测试3的Playwright阶段时，首先明确需求规范：所需输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续代码修改的准确性。 在功能测试结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 每次调用都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务端错误就会被视为应用程序故障。
5. 测试4：使用FFmpeg进行音频合成与转码后直接上传到驱动器（runTest4_FFmpegAudioDirectUpload）
在完成“5个测试4：FFmpeg阶段”时，首先列出相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 每次调用时都要记录请求ID、模型ID以及延迟时间。如果没有这些记录，间歇性的服务错误就会被视为应用程序的故障。
6. 第5个测试：TypeScript AST提取及使用esbuild进行打包以便直接上传（runTest5_TypeScriptASTDirectUpload）
在完成“6 Test 5 TypeScript”阶段时，首先需明确接口规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续的优化工作。 每次调用时都要记录请求ID、模型ID以及响应延迟时间。如果没有这些记录，间歇性的服务错误就会被视为应用程序的缺陷。 在完成“6 Test 5 TypeScript”阶段时，首先需明确接口规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将此阶段视为输入与验证后输出之间的契约。为相关组件命名，定义成功判定标准，并杜绝无声的半完成状态。
7. 测试6：性能基准测试：直接使用ggsrun上传与通过GAS进行Base64编码上传的对比（runTest6_DriveUploadPerformanceComparison）
将测试6的性能测试阶段视为可测量的指标会更为有效。在扩大测试范围之前，需记录一份成功的测试案例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在测试环境从演示模式切换到共享环境时出现意外费用。在讲解循环逻辑之前，需先锁定解释器及依赖项的版本。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障原因。
================================================================================
PERFORMANCE BENCHMARK REPORT: 10,000 BYTES FILE TRANSFER TO GOOGLE DRIVE
================================================================================
| Metric | Approach A: Direct ggsrun Upload | Approach B: Base64 via Gemini API -> GAS |
| :--------------------------- | :------------------------------- | :--------------------------------------- |
| Transfer Method | Direct Sandbox-to-Drive (Go CLI) | Base64 Stream -> GAS -> Drive |
| Drive File Name | benchmark_10kb_ggsrun.bin | benchmark_10kb_gas.bin |
| Verified File Size | 10,000 bytes (9.77 KB) | 10,000 bytes (9.77 KB) |
| API Turns Required | 1 Turn (Direct Offload) | 1 Turn (Base64 Retrieval) |
| Local GAS Processing Time | 0.00 s (Zero CPU overhead) | 1.23 s (Base64 Decode & Blob Creation) |
| Total End-to-End Duration | 16.20 s | 32.13 s |
| Effective Throughput | 0.60 KB/s | 0.30 KB/s |
| Performance Multiplier | 1.98x FASTER | Baseline (Higher Latency & Token Usage) |
================================================================================
在本地工作站上测试（Node.js Stream Runner）
在“本地工作站测试”阶段，若将其视为可度量的对象来处理，效果会最佳。在扩大测试范围之前，先记录一份理想的测试结果、一个故障案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 在讲解循环逻辑之前，先锁定解释器及依赖项的版本。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障原因。
1. 本地流式运行器的目的与优势
“1个目标与优势”阶段若被视为可度量的工作面，效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。在讲解循环逻辑之前，先锁定解释器及依赖项的锁文件。笔记本电脑与持续集成环境之间的差异是API演示中最常见的隐性故障原因。“1个目标与优势”阶段若被视为可度量的工作面，效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。应将此阶段视为输入与经过验证的输出之间的契约，为相关文档命名、明确成功标准，并杜绝隐性部分完成的情况。
2. 本地环境搭建与测试执行
对于本地设置和测试阶段，在修改代码之前需明确输入参数、各步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。应将客户端构建部分与消息循环分离，这样即便更换服务提供商，也无需重写对话状态机。
附录：Gemini Managed Agents API 使用模式
在附录中的 Gemini 托管代理阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置应与应用程序代码分开。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 将客户端构建与消息处理循环分开，这样在更换提供方时无需重写对话状态机。
基础端点
在基础端点阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。 应将客户端构建与消息循环分开，这样在更换提供方时无需重写对话状态机。
POST https://generativelanguage.googleapis.com/v1beta/interactions?key=${API_KEY}
Content-Type: application/json
场景1：在多个客户端之间共享单个持久化沙箱
对于“共享舞台”的场景1，在修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 将客户端构建逻辑与消息循环分开，这样即便更换提供方，也无需重写对话状态机。
{
"agent": "antigravity-preview-05-2026",
"input": "Run task in shared container...",
"environment": "environments/env-12345"
}
场景2：每次执行使用独立的沙箱
对于使用隔离阶段的场景2，在修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定条件，并拒绝默许的半完成状态。 将客户端构建逻辑与消息循环分离，这样即便更换提供方，也无需重写对话状态机。
{
"agent": "antigravity-preview-05-2026",
"input": "Execute client-specific isolated task...",
"environment": {
"type": "remote"
}
}
场景3：保留多轮对话上下文
对于“保留多轮对话”的场景3，在修改代码之前需明确输入内容、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前显示成本可避免在从演示环境切换到共享环境时出现意外费用。应将客户端构建部分与消息循环分离，这样即便更换服务提供商，也无需重写对话状态机。
{
"agent": "antigravity-preview-05-2026",
"input": "Based on the previous output, proceed to step 2...",
"environment": "environments/env-12345",
"previous_interaction_id": "interaction-prev-67890"
}
场景4：使用全新上下文重用沙箱（freshInteraction）
在场景4的重复使用沙箱阶段，应在修改代码之前明确输入参数、该步骤的负责人以及退出标准。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作员无需查看整个系统结构即可进行审计。 将客户端构建逻辑与消息处理循环分开，这样在更换提供方时无需重写对话状态机。
{
"agent": "antigravity-preview-05-2026",
"input": "Execute a completely new task in the existing sandbox...",
"environment": "environments/env-12345"
}
总结矩阵
在摘要矩阵阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续需要补充的功能。 应将客户端构建部分与消息循环分离，这样在更换提供方时无需重写对话状态机。
总结
在总结阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任模块，而非复杂的流程链。应将客户端构建逻辑与消息处理循环分开，这样在更换提供方时无需重写对话状态机。
操作检查清单
在操作检查清单阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。
应优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的处理流程。
将客户端构建逻辑与消息循环分离，这样在更换提供者时无需重写对话状态机。
在耗时的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
锁定依赖项的版本，并记录用于演示的图像摘要。可重复性比经验知识更为重要。
将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放，以便操作员在不需查看整个架构的情况下进行审计。
在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如追求扎实的可靠性。
关于19215ab8c61f的批注：请将提供商密钥移出代码仓库，设定单会话令牌上限，并将日志存储在评估用示例文件旁，以便后续模型更换时仍能保持对比性。