google-workspace

Google Workspace CLI (gws)

一个 CLI，即可使用所有 Google Workspace 功能。运行时读取 Google 的 Discovery Service，因此新的 API 端点会自动可用。

前提条件

• $PATH 中有 gws 二进制文件（安装：pnpm add -g @googleworkspace/cli）
• 已完成身份验证：gws auth login（通过浏览器使用 OAuth）
• 查看身份验证状态：gws auth status

参考资料

所有 gws 技能文件均通过符号链接从上游 Gemini 扩展获取，位于： ./gws-skills/

主要参考资料：

• ./gws-skills/gws-shared/SKILL.md - 身份验证、全局标志、安全规则
• ./gws-skills/gws-drive/SKILL.md - Drive 文件/文件夹操作
• ./gws-skills/gws-docs/SKILL.md - Google Docs 读取/写入
• ./gws-skills/gws-docs-write/SKILL.md - 向文档追加文本
• ./gws-skills/gws-sheets/SKILL.md - Sheets 操作
• ./gws-skills/gws-gmail/SKILL.md - Gmail 操作
• ./gws-skills/gws-calendar/SKILL.md - Calendar 操作
• ./CONTEXT.md - 核心语法和使用模式

执行之前未用过的命令前，请先阅读相关技能文件。

核心语法

gws <service> <resource> [sub-resource] <method> [flags]

常用标志

标志	说明
--params '<JSON>'	URL/查询参数
--json '<JSON>'	请求正文（POST/PUT/PATCH）
--fields '<MASK>'	限制响应字段（对上下文窗口至关重要）
--page-all	自动分页（NDJSON 输出）
--upload <PATH>	用于分段上传的文件
--output <PATH>	保存二进制下载内容
--dry-run	验证但不调用 API

架构发现

如果不知道载荷结构，请先查看架构：

gws schema <service>.<resource>.<method>
# Example: gws schema drive.files.list
# Example: gws schema docs.documents.batchUpdate

常见模式

Drive - 列出/搜索文件

gws drive files list --params '{"q": "name contains \"Report\"", "pageSize": 10}' --fields "files(id,name,mimeType)"

Drive - 创建文件夹

gws drive files create --json '{"name": "My Folder", "mimeType": "application/vnd.google-apps.folder"}'

Drive - 将文件移至文件夹

gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID"}'

Drive - 将 Google Doc 导出为纯文本

gws drive files export --params '{"fileId": "DOC_ID", "mimeType": "text/plain"}' --output /tmp/doc.txt

Docs - 读取文档

gws docs documents get --params '{"documentId": "DOC_ID", "fields": "title,body"}'

Docs - 写入文档（batchUpdate）

插入/替换文本时，请构建 JSON 载荷文件，以避免 shell 转义问题：

import json
payload = {
    "requests": [
        {"insertText": {"location": {"index": 1}, "text": "Hello world"}}
    ]
}
with open('/tmp/payload.json', 'w') as f:
    json.dump(payload, f)

gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json "$(cat /tmp/payload.json)"

Docs - 追加文本（辅助工具）

gws docs +write --document DOC_ID --text 'Text to append'

Sheets - 读取单元格

gws sheets spreadsheets values get --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'

Gmail - 搜索邮件

gws gmail users messages list --params '{"userId": "me", "q": "from:[email protected]"}'

Agentic 工作流与 Vibe Coding

• 迭代执行 API： 不要指望复杂的 Workspace API 载荷能一次成功。先起草载荷，使用 --dry-run 标志运行，检查预期变更，定位各项架构错误，每次修复一个字段，并反复测试，直到载荷有效后再执行实际变更。
• Vibe Coding： 对 Drive 或 Docs 执行不可逆的批量操作前，请将复杂的 JSON 载荷或脚本序列保存到本地文件并提交。

规则

• 保护上下文窗口： 在 list/get 操作中始终使用 --fields，避免返回巨大的 JSON 响应
• 先试运行： 执行破坏性操作前使用 --dry-run
• 确认写入操作： 执行写入/删除命令前询问用户
• Shell 转义： 对包含 ! 的 Sheets 范围使用单引号，以防止 bash 历史记录展开
• 大型载荷： 将 JSON 写入临时文件，并使用 $(cat /tmp/file.json)，不要直接内联