GWS 技能

统一的 Google Workspace 管理员与调查工具。所有脚本均位于相对于本文档的 scripts/ 目录下。

安全性

• 严禁记录、回显或输出凭据 — 服务账号密钥及令牌仅保留在内存中
• 严禁未经提示将原始邮件正文内容发送至聊天界面 — 除非明确要求获取完整内容，否则始终返回摘要
• 代入操作会被记录 — 每次 DWD 调用均明确指定被代入的账号
• 仅限只读访问 — 不授予任何写入权限；无法发送邮件、创建日程事件或修改文件
• 凭据存储 — 服务账号密钥存放于 ~/.config/gws/service-account.json（权限设为 chmod 600，且不得置于任何代码仓库内）
• 代码中不包含密钥 — 密钥路径通过环境变量 GWS_SERVICE_ACCOUNT_PATH 加载，若未设置则使用默认路径

认证

所有脚本均调用 scripts/auth.py — 加载服务账号密钥，并通过全域委派（domain-wide delegation）代入用户身份。

• 默认管理员：通过环境变量 GWS_ADMIN_EMAIL 配置
• 域名：通过环境变量 GWS_DOMAIN 配置
• 代入其他用户：通过 --user 参数传入其邮箱地址

脚本

vault.py — 邮件调查（组织范围内容搜索）

搜索任意用户的邮件内容。自动创建临时保管箱（matter）→ 执行查询 → 返回结果 → 自动删除该保管箱。

python3 scripts/vault.py --accounts user@domain.com --terms "from:vendor@acme.com" --start "2026-03-01T00:00:00Z" --end "2026-03-26T23:59:59Z"
python3 scripts/vault.py --org-unit  --terms "subject:confidential"
python3 scripts/vault.py --accounts user@domain.com --terms "from:vendor@acme.com" --export

搜索条件支持 Gmail 操作符：from:、to:、subject:、has:attachment、filename:、newer_than:、older_than: 等。

gmail.py — 读取任意用户的收件箱

# 元数据摘要
python3 scripts/gmail.py --user user@domain.com --query "from:acme.com newer_than:7d" --max 10 --mode summary
# 完整邮件正文
python3 scripts/gmail.py --user user@domain.com --query "from:acme.com" --max 5 --mode full
# 根据消息 ID 读取单条消息
python3 scripts/gmail.py --user user@domain.com --query "" --mode read --message-id 

调查工作流：Vault 统计数量 → Gmail 摘要 → Gmail 完整内容。

directory.py — 用户、群组、组织单位（OUs）

python3 scripts/directory.py users [--query "name:Jared"] [--max 100]
python3 scripts/directory.py user user@domain.com
python3 scripts/directory.py groups
python3 scripts/directory.py members group@domain.com
python3 scripts/directory.py orgunits

reports.py — 审计日志与活动记录

python3 scripts/reports.py login [--user user@domain.com] [--event login_failure] [--start ISO] [--end ISO]
python3 scripts/reports.py admin [--max 25]
python3 scripts/reports.py drive [--user user@domain.com]
python3 scripts/reports.py token [--user user@domain.com]
python3 scripts/reports.py gmail [--user user@domain.com]

drive.py — 搜索与读取文件

python3 scripts/drive.py search --user user@domain.com --query "name contains 'invoice'"
python3 scripts/drive.py recent --user user@domain.com
python3 scripts/drive.py file --user user@domain.com --id 
python3 scripts/drive.py shared --user user@domain.com
python3 scripts/drive.py type --user user@domain.com --type sheet

gcalendar.py — 读取日历

python3 scripts/gcalendar.py today --user user@domain.com
python3 scripts/gcalendar.py tomorrow --user user@domain.com
python3 scripts/gcalendar.py events --user user@domain.com --start ISO --end ISO [--query "meeting"]
python3 scripts/gcalendar.py calendars --user user@domain.com

sheets.py — 读取电子表格

python3 scripts/sheets.py metadata --user user@domain.com --id 
python3 scripts/sheets.py get --user user@domain.com --id  --range "Sheet1!A1:D10"
python3 scripts/sheets.py batch --user user@domain.com --id  --ranges "Sheet1!A1:B5" "Sheet2!A1:C3"

docs.py — 读取文档

python3 scripts/docs.py get --user user@domain.com --id 
python3 scripts/docs.py text --user user@domain.com --id 

people.py — 联系人与组织通讯录

python3 scripts/people.py contacts --user user@domain.com
python3 scripts/people.py search --user user@domain.com --query "John"
python3 scripts/people.py directory --user user@domain.com --query "manager"

配置

请参阅 references/setup-checklist.md 获取一次性 GCP + Google Admin 配置步骤。