把 Google Workspace 變成可組合的 Agent 工具：深入解析 gws 的 Discovery 驅動 CLI

如果要讓 AI Agent 操作 Google Workspace，最常見的做法是另外撰寫一層整合程式：處理 OAuth、拼接 REST API URL、維護每個服務的參數結構，再把回應轉成模型容易理解的格式。這條路可以走，但維護成本很快會跟著 Google Workspace API 的服務數量一起上升。

googleworkspace/cli 選擇了另一條路：把 Google Workspace API 變成一個可探索、可組合、輸出一致的命令列介面。它的可執行檔名稱是 gws，以 Rust 實作，能從 Google Discovery Service 在執行期間建立命令面，並以結構化 JSON 回應結果。對人類使用者而言，它減少了手寫 curl 的工作；對 Agent 而言，它則提供一個比客製 MCP wrapper 更接近 Unix 工具的介面。

本文根據 GitHub repository、README、原始碼結構、release 與近期 commit 查證，說明 gws 的設計取捨、實際使用方式，以及它為什麼值得成為 AI 工程團隊的 Workspace 自動化基礎。

先說結論：gws 解決的是「介面漂移」

Google Workspace 並不是單一 API，而是一組服務集合，包含 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等。若把每個 endpoint 都手工包成 CLI 或 Agent tool，整合層通常會遇到三個問題：

命令與 API 規格同步困難：新增方法、欄位或服務時，要同步更新程式碼與說明。
輸出格式不一致：不同 wrapper 可能回傳不同 JSON 結構，讓 shell script 與 Agent prompt 都要額外適配。
人類與 Agent 需要兩套介面：人類需要 --help、dry run 與可讀錯誤；Agent 需要可預測參數、結構化輸出和 schema 探索。

gws 的核心策略是不要把整份命令清單硬編碼在 CLI 裡，而是在執行時讀取 Google 的 Discovery 文件，依服務、資源和方法建立命令樹。這讓 API 介面的更新可以較自然地反映到 CLI，也把「如何呼叫 API」轉成可以由命令列逐層探索的結構。

需要先釐清的是，README 明確聲明它不是 Google 官方支援的產品。它使用 googleworkspace 組織名稱與 Google Workspace API，但使用者仍應把它視為獨立的開源工具，而不是 Google 的產品保證或官方支援管道。

核心架構：兩階段解析加上 Discovery 驅動

README 對執行流程的描述可以濃縮成以下五步：

先讀取第一個參數，辨識服務，例如 drive。
取得該服務的 Discovery Document，並快取 24 小時。
依文件中的 resources 和 methods 建立 clap 命令樹。
重新解析剩餘參數。
完成驗證、認證、HTTP request 建立與執行。

這種兩階段解析很適合 Google API 的階層式命名。使用者可以先執行 gws drive --help，再一路縮小到 gws drive files list --help；Agent 也可以把同樣的 help 與 schema 當成工具探索入口。從程式碼結構來看，discovery.rs、commands.rs、schema.rs、executor.rs 和 formatter.rs 分別承擔 Discovery、命令建構、schema 查詢、請求執行與輸出格式化等責任，並由 crates/google-workspace-cli 組合成 CLI。

這個設計的優點不只在於「少寫一些 wrapper」。更重要的是，命令面與上游 API 規格之間建立了明確的生成關係：Google 新增方法後，工具理論上不必等待另一個手工 wrapper 發版才能開始探索。代價則是執行時需要取得 Discovery 文件，第一次執行某項服務時也會比完全靜態的 CLI 多一個網路依賴。

讓輸出同時適合 shell 和 Agent

gws 的另一個關鍵選擇是把輸出標準化為結構化 JSON。這讓同一個命令可以被三種工作流重用：

人類在終端機中直接檢查結果。
Shell 以 jq 篩選欄位。
AI Agent 讀取 JSON，接續下一個 Workspace 操作。

例如，README 示範以 --params 傳入 Google API 參數，再使用 --page-all 把分頁結果以 NDJSON 逐頁串流：

gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

--page-all、--page-limit 與 --page-delay 把分頁控制明確化，對批次工作尤其重要。Agent 不必一次把所有資料塞進 context，也能用 page limit 控制成本與風險。gws schema drive.files.list 則提供方法的 request／response schema 探索，降低 Agent 產生錯誤參數的機率。

另外，CLI 也提供 --dry-run。在會傳送郵件、建立事件、修改文件或上傳檔案的流程中，先預覽請求再執行，是比單純依賴 prompt 提醒更可靠的操作邊界。

從 OAuth 到伺服器部署：認證是設計的一部分

Workspace 自動化最容易被低估的不是 API 呼叫，而是憑證生命週期。gws 提供多種流程，涵蓋互動式桌面、headless／CI、service account，以及外部工具已經取得 access token 的情境。

互動式登入可透過：

gws auth setup
gws auth login

README 說明，桌面流程的憑證會使用 AES-256-GCM 加密，金鑰儲存在作業系統 keyring；在 Linux 上則可依設定使用檔案後端。對 headless 環境，可以在有瀏覽器的機器完成登入後，用 gws auth export --unmasked 匯出，再以 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 指向憑證檔案。也可以使用 GOOGLE_WORKSPACE_CLI_TOKEN 傳入既有 access token。

這些模式讓同一套命令能從個人電腦延伸到 CI 或伺服器，但不代表可以忽略權限治理。Google OAuth testing mode 有 scope 數量限制，README 特別提醒 recommended preset 包含 85 個以上 scope，未驗證應用程式可能超過限制；實務上應依工作所需選取服務範圍，而不是一開始授予所有權限。

Agent Skills：把 API 介面提升成工作流介面

repo 內除了 CLI，也提供大量 SKILL.md。這些 skill 覆蓋單一 Workspace 服務，也包含較高階的常見流程與 recipe，例如寄信、讀取 Drive 檔案、建立 Calendar 事件、寫入文件或整理摘要。README 在不同段落以 40+ 與 100+ 描述已包含的 skill／技能範圍；這些數字會隨版本與生成結果改變，因此更重要的訊息是：技能與 CLI 共用同一套命令面，而不是另外維護一組完全不同的 Agent API。

安裝所有 skill 的方式是：

npx skills add https://github.com/googleworkspace/cli

也可以只挑選特定服務，例如 Drive 或 Gmail。這種粒度對團隊治理很有用：需要寄信的 Agent 不必同時載入整個 Workspace 的操作說明，也能降低可用工具過多造成的選擇成本。

對 AI Chain 這類重視可重現工作流的團隊而言，這裡有一個值得注意的模式：skill 負責描述「何時使用」與「如何組合」，gws 負責執行具體 API 呼叫。兩者分工清楚，Agent 的 prompt 不必塞入整套 Google API 文件。

Helper commands 與通用 Discovery 的取捨

完全依賴 Discovery 可以覆蓋廣度，但常見任務仍需要更好用的捷徑。因此 gws 另外提供以 + 開頭的 helper commands，例如：

gws gmail +send、+reply、+forward：處理郵件常見流程。
gws calendar +agenda：取得今日或即將到來的行程，並可指定時區。
gws drive +upload：上傳檔案並處理相關 metadata。
gws workflow +meeting-prep、+weekly-digest：組合多個服務的工作流。
gws events +subscribe：操作 Workspace Events 訂閱。

+ 前綴的意義在於把手工設計的高階體驗與 Discovery 生成的方法區分開來，避免名稱衝突。這是一個務實的折衷：底層 API 保持完整，高頻任務則有更適合人類與 Agent 的介面。

安全邊界：可預覽、可稽核，但仍要正確設定

gws 提供結構化 exit codes，將成功、API error、auth error、validation error、Discovery error 與 internal error 分開。對 CI 來說，這比解析一段自然語言錯誤訊息更容易建立可靠的 retry 或告警規則。

它也支援把 API 回應交給 Google Cloud Model Armor 做 prompt injection 掃描，並可選擇 warn 或 block 模式。這對「Agent 讀取郵件、文件或 Chat 內容後繼續執行」的情境特別有價值，因為外部內容可能含有不應被當成命令的文字。不過，安全掃描功能仍需要自行設定 Model Armor template，不能取代最小權限、dry run、人工核准和輸出驗證。

實際部署時，建議至少採用以下原則：

將 access token 與 credentials file 放在 secret manager 或受限檔案權限中，避免寫入 log。
對寄信、刪除、分享和權限變更等副作用操作先啟用 dry run 或審批閘門。
只授予 Agent 必需的 Workspace scopes，並依任務分開帳號或 service account。
讓腳本檢查 exit code 與 JSON schema，不要只根據終端機文字判斷成功。
若 Agent 會讀取不可信的郵件或文件，評估 Model Armor 與額外的內容隔離策略。

快速上手與適用場景

官方 README 建議優先使用 GitHub Releases 的預建 binary，也提供 npm、Cargo、Nix 與 Homebrew 安裝方式。以 npm 為例：

npm install -g @googleworkspace/cli

完成認證後，可以從低風險的讀取操作開始：

gws drive files list --params '{"pageSize": 5}'
gws calendar +agenda --today

gws 特別適合下列場景：

需要讓 Agent 讀寫多個 Workspace 服務，但不想逐一維護 API wrapper。
已有 shell／CI 自動化，希望以 JSON 與 exit code 接入 Agent。
想把 Workspace 操作拆成可審查、可重用的 skill 與 recipe。
需要在本機、CI 與伺服器之間共用同一套命令。

相對地，如果需求只是單一固定 API、對延遲有極端要求，或組織必須依賴 Google 官方支援產品，則應先評估直接使用官方 client library 或自行維護整合層。

為什麼現在值得關注？

截至本次查證，googleworkspace/cli 在 GitHub 上約有 3.07 萬顆星，採 Apache-2.0 授權，且 repository 仍在近期更新；近期 release 為 v0.22.5。它並不是因為「把所有 API 包成一個命令」就值得注意，而是把三個原本分離的層次接在一起：

Discovery 提供可更新的 API 命令面。
JSON、schema、pagination 與 exit code 提供可組合的執行介面。
Agent Skills 與 helper commands 提供接近實際工作流的高階語意。

這讓 Workspace 自動化從「為每個服務寫一個專案」轉向「用一個可探索的執行核心，加上按需載入的技能」。對正在建立 Agent 平台的團隊而言，這種架構比單純增加另一個 connector 更值得研究。

結語

gws 的價值不在於取代 Google Workspace API，而在於提供一個介於原始 API 與高階 Agent workflow 之間的穩定邊界。它用 Discovery 解決介面同步，用結構化輸出解決組合問題，再以 OAuth、dry run、exit code、helper 和 skills 補足生產環境需要的可操作性。

目前專案仍明確處於 v1.0 前的積極開發階段，README 也提醒可能出現 breaking changes。因此最適合的採用方式不是直接把它當成永遠不變的基礎層，而是鎖定版本、建立自己的 smoke tests，並針對高風險操作加上審批與權限限制。做到這些之後，gws 會是一個很有潛力的 Workspace Agent 執行底座。