google-workspace

Google Workspace

在编写代码或粘贴 API 代码片段之前，使用此技能为 Google Workspace 相关工作选择合适的方案。关键通常在于判断应由哪个 Workspace 方案来处理这项工作：

• Apps Script：适用于紧贴 Sheets / Docs / Forms / 触发器 / 菜单的 Workspace 原生自动化
• 直接使用 REST API + 客户端库：适用于后端服务、多系统集成、需要更强部署控制或语言灵活性的场景
• Admin SDK / 仅限管理员的 API：适用于用户、群组、组织部门、目录数据或整个网域的治理任务

何时使用此技能

• 创建或更新 Docs、Sheets、Slides、Drive 文件/文件夹、Gmail 邮件、Calendar 活动、Forms 或 Chat 消息
• 设计 Workspace 自动化流程，例如 Form → Sheet → Gmail / Calendar / Drive
• 在 Apps Script 和直接使用 REST API 之间做出选择
• 选择合适的身份验证模型：OAuth 用户流程、服务账号或全网域委派
• 在实施前审查范围、共享模型、配额/执行风险或安全边界
• 处理普通 Docs/Sheets/Gmail 代码不应承担的 Workspace 管理任务

Instructions

步骤 1：对请求进行分类

在调用任何 API 之前，先明确以下五项：

1. 主要产品方案 — Docs、Sheets、Slides、Drive、Gmail、Calendar、Forms、Chat 或 Admin SDK
2. 操作 — 创建、读取、更新、搜索、共享、发送、安排、导出、批量更新、管理
3. 执行者 / 身份 — 最终用户、服务账号、委派管理员或 Apps Script 所有者
4. 运行位置 — Workspace 界面/运行时、后端服务、cron/批处理工作进程或混合工作流
5. 触发方式 / 频率 — 手动、提交表单、定时、Web 请求、批量迁移、管理事件

如果用户描述了多个 Workspace 应用，首先应将其视为工作流问题，而不是单一 API 问题。

步骤 2：选择执行方案

适用于以下情况时使用 Apps Script

• 工作流围绕 Sheets / Docs / Forms / Gmail 展开，并且应在 Workspace 内运行
• 需要触发器、自定义菜单、侧边栏或其他 Workspace 原生脚本功能
• 使用绑定脚本比单独配置后端更简单
• 在 Workspace 中使用 JavaScript 的便利性比后端部署控制更重要

适用于以下情况时直接使用 REST API

• 工作流运行在后端、集成服务、CLI 或批处理作业中
• 需要更强的部署、测试、重试控制，或使用非 JS 技术栈
• 任务涉及 Workspace 和外部系统，不应依赖绑定脚本运行时
• Apps Script 配额或运行时限制可能成为瓶颈

适用于以下情况时使用 Admin SDK / 管理员 API

• 任务涉及用户、群组、组织部门、角色或网域管理
• 任务需要全网域委派访问权限
• 请求显然超出 Docs/Sheets 编辑等普通内容操作的范围

仅将外部自动化层作为转接方案

• 如果用户确实需要无代码/跨应用编排器，可将 Zapier / Make / n8n 等工具作为替代方案提及。
• 不要将此技能变成通用的无代码平台教程。

第 3 步：选择身份验证模式

身份验证模式	适用场景	典型服务	备注
OAuth 用户流程	操作真实用户的邮箱、日历、云端硬盘、文档或个人内容	Gmail、Calendar、Drive、Docs、Sheets、Slides、Forms、Chat	用户所有数据的最佳默认选择
服务账号	后端自动化拥有数据或操作共享资源	Drive、后端生成的文档/表格、服务工作流	可能需要设计共享云端硬盘/文件访问方式
服务账号 + 域范围委派	管理员或全组织操作需要安全地模拟用户身份	Admin SDK、全组织范围的 Gmail/Calendar/Drive 工作流	安全要求更高；将权限范围控制在最小限度
Apps Script 绑定身份验证	工作流有意在 Workspace 内运行，并与脚本所有者/安装模式绑定	Sheets、Docs、Forms、Gmail、Calendar、Drive	上手快，但仍需考虑运行时和配额

规则：

• 选择满足任务要求的最小权限范围。
• 不要将凭据和令牌放入代码库。
• 如果任务涉及用户的邮箱/日历/文件，请说明使用的是谁的身份。
• 如果需要管理员权限，请将相关操作与常规内容编辑逻辑分开。

第 4 步：将任务路由到合适的 Workspace 产品

产品	适用场景	常见操作	以下情况应改用其他方案
Docs	格式化文本文件	创建文档、替换占位符、插入文本/表格/图片、导出	最终交付物实际是演示文稿或电子表格
Sheets	表格工作流和轻量级运营数据库	追加/更新行、格式设置、公式、筛选、审批、仪表板	用户需要持久化数据库设计或 BI 建模
Slides	生成演示文稿和可更新的幻灯片组	创建幻灯片、替换占位符、缩略图、批量更新	核心工作是演示文稿策略/内容设计，而非 API 执行
Drive	存储、共享、文件夹层级结构、导出/导入	上传文件、创建文件夹、搜索文件、权限、共享云端硬盘	主要问题是信息架构，而非 Drive API 调用
Gmail	邮箱自动化和外发邮件	草稿、发送、标签、搜索、会话操作	主要工作是邮件撰写策略，而非邮箱操作
Calendar	日程安排和活动自动化	创建活动、邀请参与者、同步时间、Meet 链接	核心问题是会议策略或路线图规划
Forms	信息收集、调查问卷、测验、响应流程	创建/更新表单、收集响应、Form → Sheet 工作流	工作重点是调查设计方法，而非实现
Chat	Workspace 消息自动化	发布消息、机器人流程、通知	用户需要更全面的 ChatOps 平台设计
Admin SDK	目录和网域管理	用户、群组、组织部门、许可证、设置	常规内容工作流被过度授予管理员权限

第 5 步：使用工作流包处理常见的跨服务任务

表单信息收集包

• Forms 收集提交内容
• Sheets 存储/审核响应
• Gmail 或 Chat 发送后续通知
• 需要时，Calendar 安排面试、会议或提醒

审批/运营包

• Sheet 存储队列/状态
• Apps Script 或后端工作进程评估行/状态
• Gmail 或 Chat 发送审批提示/更新
• Drive 存储生成的产物或附件

报告包

• Sheets 保存指标或提取的数据
• Docs / Slides 发布叙述性内容
• Drive 管理共享访问权限和导出
• Calendar / Gmail 处理定期分发

对于多步骤流程，请定义：

• 事实来源系统
• 触发源
• 操作者身份
• 幂等性/重复提交规则
• 失败通知路径

步骤 6：检查配额和运行时风险

在敲定计划前，询问该工作流是否：

• 处理量大或涉及大量编辑
• 由计划任务驱动，触发频繁
• 可能触及 Apps Script 的执行或运行时限制
• 依赖大量遍历 Drive、发送 Gmail 邮件或批量写入电子表格

如果是：

• 在支持的情况下优先采用批量操作
• 如果有一次批量调用可用，就避免逐行执行、频繁调用的循环
• 如果运行时上限成为真正的瓶颈，考虑从 Apps Script 迁移到后端工作进程

步骤 7：生成具体的执行方案

返回一份简洁的计划，包括：

• 选定的 Workspace 操作界面
• 选定的身份验证模式
• 所需的权限范围 / 管理员边界
• 所需的主要对象标识符（docId、spreadsheetId、folderId、用户邮箱、calendarId、formId）
• 实施顺序
• 验证步骤
• 转交路径 / 风险

示例

示例 1：表单 → 表格 → 电子邮件工作流

提示词：“创建一份员工反馈表单，在 Sheets 中收集回复，并发送确认邮件。”

使用此技能：

• 将其归类为多服务工作流
• 根据自动化应运行的位置选择 Apps Script 或轻量级后端
• 将 Forms + Sheets + Gmail 确定为服务组合
• 在实施前明确身份验证、权限范围和触发器行为

示例 2：共享云端硬盘入职资料包

提示词：“为新客户创建共享 Drive 文件夹结构，与三位用户共享，并生成一份启动文档。”

使用此技能：

• 将 Drive 设为主要操作界面，将 Docs 设为次要文档层
• 根据所有权模式选择 OAuth 或服务账号访问
• 编码前列出文件夹 ID、用户邮箱和共享规则

示例 3：Workspace 管理员请求

提示词：“停用一位即将离职的用户，将其移至其他组织部门，并审计其群组成员身份。”

使用此技能：

• 立即转交给 Admin SDK
• 要求在执行方案中明确管理员 / 委派身份
• 将管理员操作与常规 Docs / Drive 编辑逻辑分开

示例 4：以电子表格为核心的审批自动化

提示词：“将此电子表格转换为审批队列，并加入提醒邮件和状态更新。”

使用此技能：

• 判断绑定的 Apps Script 是否足够
• 定义状态列、提醒频率和 Gmail 集成方式
• 在承诺采用触发器密集型方案前检查配额和运行时风险

最佳实践

1. 先选择操作界面，不要先写代码片段。
2. 将内容操作与管理操作分开。
3. 使用 Apps Script 获取 Workspace 原生的便捷体验；如果更看重后端控制或规模，则使用直接 API。
4. 尽量缩小权限范围，并明确说明操作所用的身份。
5. 对于多应用工作流，先定义事实来源和触发来源。
6. 如果 API 支持批处理，优先采用批量更新，而不是频繁调用的逐行 / 逐单元格循环。
7. 如果实际需求是撰写电子邮件、文档、调查问卷、仪表板或演示文稿，则在明确 Workspace 执行方案后，转交给相应的内容技能。

参考资料

• references/auth-and-scope-routing.md — OAuth、服务账号与全网域委派的选择指引
• references/service-selection-matrix.md — Docs / Sheets / Drive / Gmail / Calendar / Forms / Admin SDK 的逐产品选择指引
• references/workflow-patterns-and-quotas.md — 常见跨服务执行方案及配额 / 运行时注意事项
• Google Workspace 开发者文档：https://developers.google.com/workspace
• 身份验证概览：https://developers.google.com/workspace/guides/auth-overview
• Apps Script 示例：https://developers.google.com/apps-script/samples
• Apps Script 配额：https://developers.google.com/apps-script/guides/services/quotas
• Forms REST API 与 Apps Script 对比：https://developers.google.com/workspace/forms/api/guides/compare-rest-apps-script