gws Google Workspace 命令行
用一个动态生成的命令行界面调用 Google Workspace API，并为自动化与智能体提供结构化 JSON 输出。
按维度查看评分与理由
证据显示：README 描述了 OAuth 流程、凭据加密（AES-256-GCM）、作用域选择、--dry-run 预览、环境变量优先级、安全报告渠道（SECURITY.md）和依赖审计工作流（audit.yml）。扣分：未提供代码级验证，未明确最小权限原则，用户确认机制仅体现在 OAuth 同意和 --dry-run，数据流透明度有限，未提及回滚机制，发布者身份未验证。
证据显示：README 提供退出码、故障排除、结构化 JSON 输出，架构描述清晰。扣分：未提供测试结果或执行验证，依赖可用性仅通过 CI 工作流暗示，失败消息仅部分示例。
证据显示：README 面向人类和 AI 代理，提供多种安装方式、环境变量、使用场景（如 CI、无头）。扣分：能力边界未明确列出，触发精度依赖动态发现，环境适配未覆盖所有平台。
证据显示：README 结构清晰，提供安装说明、示例、故障排除、许可证（Apache-2.0）、版本号（0.22.5）。扣分：命名稳定性未保证（预发布），变更日志未提供，维护责任未明确（未验证发布者）。
证据显示：README 强调结构化 JSON 输出、自动分页、动态命令表面，提供多种安装方式。扣分：未提供性能基准或成本分析，边际价值基于断言。
证据显示：README 声明动态构建、AI 技能等，但未提供可追溯的测试或独立验证。扣分：声明与证据分离不明确，交叉来源有限。
- 发布者身份未验证，需谨慎对待供应链风险。
- 项目处于预发布阶段，存在破坏性变更风险。
- 动态命令表面可能引入意外行为，需在隔离环境中测试。
- 凭据处理虽加密，但需确保密钥管理安全。
这个 Agent 能做什么，适合哪些场景？
gws 是一个面向人类和 AI 智能体的 Google Workspace 命令行工具，覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat 及更多 Workspace API。它在运行时读取 Google Discovery Service，为目标服务动态生成命令、资源和方法，而非维护静态命令清单。命令执行后输出结构化 JSON，分页模式可输出 NDJSON，适合脚本和自动化流程消费。项目还提供 100 多个 SKILL.md Agent Skills、常用工作流配方，以及 Gemini CLI 扩展安装路径。它是本地 CLI，不是托管服务；调用 Workspace 数据需要 Google Cloud OAuth 或其他已配置的凭据。该项目仍在积极开发中，并明确提示 v1.0 前可能存在破坏性变更。
用户先通过 gws auth setup、gws auth login、GOOGLE_WORKSPACE_CLI_TOKEN 或 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 配置身份验证。执行例如 gws drive files list --params '{"pageSize": 5}' 时，gws 先从 argv[1] 识别 drive，获取并缓存该服务的 Discovery Document，然后据此构建 clap::Command 命令树并重新解析参数。随后它完成认证、构造 HTTP 请求、调用相应 Google API，并把成功结果、错误和下载元数据作为 JSON 输出；--page-all 会逐页输出 NDJSON。除 Discovery 生成的方法外，gws 还提供带 + 前缀的助手命令，例如 gmail +send、drive +upload、calendar +agenda、workflow +standup-report 和 events +subscribe。它支持通过 --sanitize 配合 Google Cloud Model Armor 模板扫描 API 响应中的提示注入风险。
- 需要从终端列出最近 Drive 文件、上传报告或读取 Google Workspace API 数据的运维人员。
- 需要以 JSON 调用 Gmail、Calendar、Sheets、Docs 或 Chat 的自动化脚本作者。
- 希望让已安装 Gemini CLI 扩展的智能体使用已认证 gws 命令和仓库内技能的团队。
- 需要通过 calendar +agenda、workflow +meeting-prep 或 +weekly-digest 汇总个人工作安排的 Workspace 用户。
- 需要在 CI 或无头服务器上导出凭据并以 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 调用 Workspace API 的工程团队。
- 需要用 Model Armor 模板在智能体消费 Gmail 或其他 API 响应前进行提示注入检查的开发者。
这个 Agent 有哪些优点和局限？
- 运行时使用 Google Discovery Service 构建命令面，Google Workspace 新增 API 端点或方法时可被自动纳入。
- 所有成功、错误和下载元数据均为结构化 JSON，并支持 --page-all 的 NDJSON，便于脚本和智能体处理。
- 同时提供 Discovery 方法与明确标识的 + 助手命令，覆盖发邮件、上传文件、日程摘要和跨服务工作流。
- 认证覆盖交互式 OAuth、凭据文件、服务账号和预先获取的访问令牌，适用于桌面、CI 和服务器场景。
- 仓库提供 100 多个 Agent Skills，并有 Gemini CLI 扩展安装方式。
- 核心用途依赖 Google Workspace、Google Cloud 项目和 Google OAuth 或服务账号凭据，无法作为通用 SaaS CLI 使用。
- 未验证且处于测试模式的 OAuth 应用约受约 25 个 scope 限制；recommended 预设的 85+ scopes 可能登录失败。
- gws auth setup 依赖 gcloud；没有 gcloud 时需要手动在 Google Cloud Console 配置 Desktop app OAuth 客户端和测试用户。
- 项目仍在积极开发，文档明确提示 v1.0 前预计会有破坏性变更。
- 运行时需要获取 Discovery Document；获取失败会以退出码 4 终止命令。
如何安装或部署这个 Agent？
前提是拥有可访问 Google Workspace 的 Google 账号和 Google Cloud 项目。推荐从 GitHub Releases 下载与操作系统和架构匹配的预构建二进制，将 gws 放入 PATH；也可执行 npm install -g @googleworkspace/cli（需要 Node.js 18+）、cargo install --git https://github.com/googleworkspace/cli --locked、nix run github:googleworkspace/cli，或在 macOS/Linux 上执行 brew install googleworkspace-cli。首次本地认证可运行 gws auth setup，然后运行 gws auth login；若没有 gcloud，可在 Google Cloud Console 创建 Desktop app OAuth 客户端，将客户端 JSON 保存为 ~/.config/gws/client_secret.json，再运行 gws auth login。
如何使用这个 Agent？
完成认证后，可运行：gws drive files list --params '{"pageSize": 5}'。创建表格可运行：gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'。查看命令的请求与响应模式可运行 gws schema drive.files.list；自动翻页并逐页输出 NDJSON 可使用 gws drive files list --params '{"pageSize": 100}' --page-all。无头环境可先在有浏览器的机器上执行 gws auth export --unmasked > credentials.json，再设置 export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json。
这个 Agent 与同类方案有什么区别？
相较于直接按 REST 文档编写 curl 调用，gws 提供由 Discovery Service 动态生成的命令、内置帮助、--dry-run、自动分页和结构化 JSON 输出。