简介

gws (Google Workspace CLI) 是一个统一命令行工具，用于访问和管理所有 Google Workspace API 服务。该项目采用 Rust 语言编写，支持 Drive、Gmail、Calendar、Docs、Sheets、Chat 等 Workspace API，并内置 40+ AI Agent 技能。 资料来源：README.md:1

gws 的核心设计理念是动态发现驱动（Discovery-Driven）：命令行界面并非静态定义，而是在运行时从 Google Discovery Service 动态读取 API 描述文档自动生成。这意味着当 Google 发布新的 API 端点或方法时，gws 能够立即支持，无需手动更新。 资料来源：README.md:27

[!NOTE]

这是一个开源项目，不是 Google 官方支持的产品。

项目架构

整体架构

gws 采用双 crate 结构设计：

graph TD
    subgraph "用户层"
        A[用户终端 / AI Agent]
    end
    
    subgraph "npm 包装层"
        B[@googleworkspace/cli]
    end
    
    subgraph "Rust CLI 核心"
        C[google-workspace-cli]
        D[google-workspace 核心库]
    end
    
    subgraph "Google 服务"
        E[Discovery Service]
        F[Workspace APIs]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

资料来源：crates/google-workspace-cli/README.md:1

核心库模块

google-workspace 核心库包含以下主要模块： 资料来源：crates/google-workspace/README.md:13

技术特性

动态命令生成

gws 不维护静态命令列表，而是从 Google Discovery Service 实时读取 API 描述。每次执行命令时，CLI 会：

1. 解析用户输入的服务名和 API 方法
2. 获取对应的 Discovery 文档（带 24 小时缓存）
3. 动态生成 HTTP 请求
4. 返回结构化 JSON 输出 资料来源：crates/google-workspace/src/discovery.rs:58

sequenceDiagram
    participant U as 用户
    participant C as gws CLI
    participant D as Discovery Service
    participant A as Workspace API
    
    U->>C: gws drive files list
    C->>D: GET discovery.googleapis.com/...
    D-->>C: Discovery Document
    C->>C: 解析命令参数
    C->>A: POST drive.googleapis.com/...
    A-->>C: JSON Response
    C-->>U: 结构化输出

辅助命令系统

除了 Discovery 生成的 API 方法，gws 还提供 + 前缀的辅助命令，用于复杂工作流： 资料来源：README.md:58

辅助命令的设计遵循特定原则，仅在 Discovery 方法无法直接实现时才添加。 资料来源：crates/google-workspace-cli/src/helpers/README.md:1

错误处理

GwsError 枚举定义了完整的错误类型体系，每种错误都有对应的退出码和 JSON 序列化格式： 资料来源：crates/google-workspace/src/error.rs:1

输入验证

项目实现了多层次的安全验证机制： 资料来源：crates/google-workspace/src/validate.rs:1

• 路径安全检查：防止路径遍历攻击
• 资源名称验证：拒绝包含特殊字符的输入
• 控制字符检测：拒绝 C0/C1 控制字符和危险 Unicode 字符
• API 标识符验证：确保服务名和版本号只包含安全字符

安装与分发

多平台支持

gws 支持以下平台和架构： 资料来源：npm/package.json:18

安装方式

# NPM 全局安装
npm install -g @googleworkspace/cli

# Cargo 安装
cargo install google-workspace-cli

# Nix 安装
nix run github:googleworkspace/cli

# 直接下载
curl -sLO https://github.com/googleworkspace/cli/releases/download/v0.22.5/...

资料来源：crates/google-workspace-cli/README.md:9

认证机制

认证优先级

gws 支持多种认证方式，按优先级顺序如下： 资料来源：README.md:112

已知问题

社区反馈了以下认证相关问题：

• Token 缓存失效：重新认证获取新作用域后，API 调用仍使用旧的缓存访问令牌 资料来源：社区上下文 - Issue #764
• 多账户切换：切换到不同账户后，token_cache.json 未正确更新 资料来源：社区上下文 - Issue #780
• Keyring 密钥写入：加密密钥每次调用都写入磁盘 资料来源：社区上下文 - Issue #791
• 非 TTY 环境阻塞：auth login 在非 TTY 环境下无限等待 资料来源：社区上下文 - Issue #781

AI Agent 集成

Gemini CLI 扩展

gws 可作为 Gemini CLI 的扩展安装，为 AI Agent 提供 Google Workspace 操作能力： 资料来源：README.md:43

gws auth setup
gemini extensions install https://github.com/googleworkspace/cli

Agent Skills

项目提供 100+ Agent Skills（SKILL.md 文件），支持：

• Gmail 邮件处理（搜索、发送、回复、转发）
• Drive 文件管理（上传、下载、分享）
• Calendar 日程管理（创建事件、查询日程）
• Sheets 电子表格操作（读取、追加、更新）
• Docs 文档操作（写入、读取）
• 工作流自动化（standup 报告、会议准备等）

社区热点功能需求

多账户支持

多账户支持是社区呼声最高的功能请求，多个 Issue 均反映了这一需求： 资料来源：社区上下文 - Issue #439

当前版本仅支持单一账户登录，社区希望能够：

• 同时维护多个 Google 账户凭证
• 通过 --account 标志切换账户
• 在同一工作流中使用不同账户

其他功能请求

• Gmail URL 解析：将 Gmail Web UI 的 sync ID（FMfcgz...）转换为 API thread ID 资料来源：社区上下文 - Issue #790
• Drive 评论锚点：修复评论锚点导致的"Original content deleted"问题 资料来源：社区上下文 - Issue #169

版本历史

资料来源：社区上下文 - Release Notes

环境变量

资料来源：README.md:137

项目信息

资料来源：npm/package.json:4

快速开始

# 安装后执行认证
gws auth login

# 列出 Drive 文件
gws drive files list --params '{"pageSize": 5}'

# 列出 Gmail 邮件
gws gmail users.messages list --params '{"maxResults": 3}'

# 查看服务帮助
gws gmail --help

资料来源：crates/google-workspace-cli/README.md:16

概述

gws（Google Workspace CLI）是一个采用动态Discovery驱动架构的CLI工具，旨在为人类用户和AI代理提供统一的Google Workspace API访问接口。该项目的核心设计理念是零维护命令表面——不硬编码任何Google API端点，而是通过运行时读取Google的Discovery Service自动构建整个命令体系。

资料来源：README.md

架构分层

gws 采用双crate架构，职责分离清晰：

graph TB
    subgraph "用户交互层"
        CLI["gws CLI 命令行工具"]
        Skills["Agent Skills (100+)"]
    end
    
    subgraph "google-workspace-cli"
        Commands["命令解析 & 路由"]
        Helpers["Helper Commands (+verb)"]
        Auth["认证管理"]
    end
    
    subgraph "google-workspace 核心库"
        Discovery["Discovery Service"]
        Services["服务注册表"]
        Client["HTTP客户端 & 重试"]
        Validate["输入验证"]
        Error["错误处理"]
    end
    
    subgraph "外部依赖"
        GoogleAPI["Google APIs"]
        Keyring["OS Keyring"]
    end
    
    CLI --> Commands
    CLI --> Helpers
    CLI --> Auth
    Commands --> Discovery
    Commands --> Client
    Helpers --> Auth
    Auth --> Keyring
    Discovery --> Services
    Client --> GoogleAPI

资料来源：crates/google-workspace/README.md

核心库 (`google-workspace`)

核心Rust库提供基础的Google Workspace API交互能力，包含以下模块：

资料来源：crates/google-workspace/src/lib.rs

CLI工具层 (`google-workspace-cli`)

基于核心库构建，负责命令行参数解析、命令路由和用户体验优化。

Discovery驱动机制

工作原理

gws的核心创新在于其动态命令生成机制：

sequenceDiagram
    participant User as 用户
    participant CLI as gws CLI
    participant Discovery as Discovery Service
    participant Cache as 磁盘缓存
    participant GoogleAPI as Google APIs

    User->>CLI: gws drive files list
    CLI->>Discovery: 请求 Discovery Document
    alt 缓存命中 (24h TTL)
        Discovery->>Cache: 读取缓存
        Cache->>CLI: 返回文档
    else 缓存未命中
        Discovery->>GoogleAPI: 获取最新文档
        GoogleAPI->>Discovery: 返回 REST描述
        Discovery->>Cache: 写入缓存
        Cache->>CLI: 返回文档
    end
    CLI->>CLI: 动态构建命令树
    CLI->>GoogleAPI: 执行API请求
    GoogleAPI->>User: 返回JSON响应

Discovery文档处理

Discovery文档定义了每个API的完整结构：

pub struct RestDescription {
    pub name: String,           // API名称（如 "drive"）
    pub version: String,         // 版本（如 "v3"）
    pub resources: HashMap<String, RestResource>,
    // ...
}

pub struct RestResource {
    pub methods: HashMap<String, RestMethod>,
}

pub struct RestMethod {
    pub http_method: String,
    pub rest_path: String,
    pub parameters: HashMap<String, JsonSchemaProperty>,
    pub request: Option<JsonSchemaProperty>,
    pub response: Option<JsonSchemaProperty>,
}

资料来源：crates/google-workspace/src/discovery.rs

缓存机制

Discovery文档默认缓存24小时，通过cache_dir参数控制：

pub async fn fetch_discovery_document(
    service: &str,
    version: &str,
    cache_dir: Option<&std::path::Path>,  // 24小时TTL缓存
) -> anyhow::Result<RestDescription>

资料来源：crates/google-workspace/src/discovery.rs

服务注册与别名

services模块维护了一个服务别名映射表：

graph LR
    A["drive"] --> B["drive:v3"]
    A1["gmail"] --> B1["gmail:v1"]
    A2["calendar"] --> B2["calendar:v3"]
    A3["sheets"] --> B3["sheets:v4"]
    A4["docs"] --> B4["docs:v1"]
    A5["chat"] --> B5["chat:v1"]

用户可使用简短别名而非完整API标识符，简化命令行使用。

认证系统

认证优先级

认证流程

graph TD
    A[启动 gws] --> B{检查环境变量}
    B -->|有 TOKEN| F[直接使用令牌]
    B -->|无 TOKEN| C{检查凭证文件}
    C -->|有凭证文件| G[加载凭证]
    C -->|无凭证文件| D{检查加密凭证}
    D -->|有加密凭证| H[从Keyring解密]
    D -->|无加密凭证| E{检查明文凭证}
    E -->|有明文凭证| I[使用明文]
    E -->|无凭证| J[需要认证]

凭证存储安全

v0.22.3引入了严格的OS Keychain集成：

• macOS使用Keychain Services
• Windows使用DPAPI
• Linux优先使用系统keyring后端

资料来源：crates/google-workspace/src/client.rs

HTTP客户端与错误处理

客户端架构

graph LR
    A[请求] --> B[验证层]
    B --> C[重试逻辑]
    C -->|失败| D[指数退避]
    C -->|成功| E[发送请求]
    E --> F{响应验证}
    F -->|错误| G[错误处理]
    F -->|成功| H[返回结果]

错误分类

GwsError枚举定义了所有可能的错误类型：

资料来源：crates/google-workspace/src/error.rs

错误JSON格式

所有错误以统一JSON格式输出，便于AI代理解析：

{
  "error": {
    "code": 404,
    "message": "Not Found",
    "reason": "notFound"
  }
}

输入验证层

验证策略

graph TD
    A[用户输入] --> B[路径安全检查]
    B --> C{包含../?}
    C -->|是| D[拒绝]
    C -->|否| E[字符验证]
    E --> F{控制字符?}
    F -->|是| D
    F -->|否| G[危险Unicode?]
    G -->|是| D
    G -->|否| H[资源名称格式]
    H -->|有效| I[放行]
    H -->|无效| D

验证规则

资料来源：crates/google-workspace/src/validate.rs

Helper命令系统

设计原则

Helper命令（以+前缀标识）仅在以下场景使用：

反模式：单一API调用包装、参数暴露已有响应字段、重复Discovery参数。

资料来源：crates/google-workspace-cli/src/helpers/README.md

内置Helper命令

数据流架构

典型命令执行流程

sequenceDiagram
    participant User as 用户
    participant CLI as gws CLI
    participant Validate as 验证层
    participant Discovery as Discovery
    participant Auth as 认证模块
    participant Client as HTTP Client
    participant Google as Google API

    User->>CLI: gws gmail messages.list --params '{...}'
    CLI->>Discovery: 获取/加载 Discovery 文档
    Discovery-->>CLI: RestDescription
    CLI->>Validate: 验证参数
    Validate-->>CLI: 验证通过
    CLI->>Auth: 获取访问令牌
    Auth-->>CLI: Bearer Token
    CLI->>Client: 构建HTTP请求
    Client->>Google: 发送请求
    Google-->>Client: JSON响应
    Client-->>CLI: 结构化数据
    CLI-->>User: JSON输出

配置目录结构

~/.config/gws/
├── credentials.enc      # 加密的OAuth凭证
├── token_cache.json      # 访问令牌缓存
├── discovery_cache/      # Discovery文档缓存
└── .encryption_key       # 加密密钥（回退方案）

已知架构相关问题

根据社区反馈，以下架构层面的问题值得关注：

资料来源：GitHub Issues

技术栈总结

这种架构设计使gws能够自动跟随Google API演进，无需手动更新命令定义，同时为AI代理提供稳定、机器可读的JSON输出格式。

概述

gws (Google Workspace CLI) 的认证系统负责管理与 Google Workspace API 的身份验证交互。该系统支持多种认证方式，包括交互式 OAuth 流程、基于环境变量的预获取令牌、服务账号凭证等。认证模块是整个 CLI 的核心基础设施，所有 API 调用都必须经过认证层才能访问 Google Workspace 资源。

认证系统的设计目标包括：

• 多后端支持：集成操作系统原生 Keychain (macOS、Windows) 和 keyring 后端实现安全的密钥存储
• 透明缓存：自动管理 OAuth 访问令牌和刷新令牌的缓存生命周期
• 环境变量优先级：支持通过环境变量注入凭证，实现自动化和 CI/CD 场景
• 动态发现驱动：基于 Google Discovery Service 动态构建命令，同时保持认证逻辑的稳定性

认证方式与优先级

gws 支持多种认证方式，系统按固定优先级顺序尝试获取有效凭证：

资料来源：README.md

认证方式详解

#### OAuth 桌面应用流程 (gws auth login)

交互式登录使用 OAuth 2.0 桌面应用流程：

gws auth login

该命令启动浏览器进行 Google 账号授权，完成后自动保存加密凭证到本地存储。凭证使用 AES-256-GCM 加密，密钥通过 Keychain/keyring 安全存储。

#### 自动发现认证 (gws auth setup)

如果系统已安装 gcloud 且已认证，CLI 可以直接复用现有凭证：

gws auth setup

这是最快的方式，无需重新输入凭据。

#### 服务账号认证

对于服务器端应用，使用服务账号凭证文件：

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service_account.json

服务账号使用 JWT 签名进行认证，不依赖交互式浏览器流程。

#### 预获取令牌

适用于已有令牌管理基础设施的场景：

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

凭证存储架构

存储组件

认证系统包含两个核心存储组件：

credential_store 负责管理 OAuth 凭证的持久化存储。凭证以加密形式保存在 ~/.config/gws/credentials.enc，密钥安全存储在系统 Keychain 或 keyring 中。

token_storage 负责管理访问令牌和刷新令牌的缓存。令牌缓存文件位于 ~/.config/gws/token_cache.json。

graph TD
    A[用户认证请求] --> B{认证方式判断}
    
    B -->|环境变量 TOKEN| C[直接使用预获取令牌]
    B -->|环境变量 CREDENTIALS_FILE| D[加载凭证文件]
    B -->|OAuth 登录| E[执行 OAuth 流程]
    B -->|gcloud 凭证| F[从 gcloud 读取]
    
    E --> G[保存加密凭证]
    G --> H[Keychain / keyring 存储密钥]
    G --> I[credentials.enc 存储加密数据]
    
    F --> J[令牌缓存]
    C --> J
    I --> J
    
    J --> K[API 调用]
    D --> K

加密机制

凭证加密使用以下安全措施：

1. 加密算法：AES-256-GCM 对称加密
2. 密钥存储：加密密钥存储在操作系统原生 Keychain (macOS/Windows) 或 keyring 后端 (Linux)
3. 密钥派生：使用密钥派生函数从用户密码生成加密密钥

注意：v0.22.3 版本引入了严格的操作系统 Keychain 集成，CLI 不再写入回退的 .encryption_key 文件到磁盘。资料来源：v0.22.3 Release Notes

配置目录结构

认证相关的配置文件位于 ~/.config/gws/ 目录：

环境变量配置

所有认证相关配置都可通过环境变量覆盖：

# 令牌配置
GOOGLE_WORKSPACE_CLI_TOKEN=ya29.xxx          # 预获取的访问令牌
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=./creds.json  # OAuth 凭证文件路径

# OAuth 客户端配置
GOOGLE_WORKSPACE_CLI_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET=xxx

# 配置目录覆盖
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/custom/path

# Model Armor 集成
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE=projects/P/locations/L/templates/T
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=warn  # 或 block

资料来源：.env.example

认证子命令

gws auth 命令组提供完整的认证管理功能：

作用域管理

OAuth 认证支持精细化的作用域控制：

# 使用默认作用域
gws auth login

# 指定作用域模式
gws auth login --scopes read-only
gws auth login --scopes minimal
gws auth login --scopes full

# 指定自定义作用域
gws auth login --scopes custom https://www.googleapis.com/auth/gmail.readonly

v0.19.0 引入了基于 clap 的参数解析重构，所有 gws auth 子命令现在使用结构化的 clap::Command 定义，并引入 ScopeMode 枚举实现类型安全的作用域选择。资料来源：v0.19.0 Release Notes

认证流程时序图

sequenceDiagram
    participant U as 用户
    participant CLI as gws CLI
    participant Auth as 认证模块
    participant Cache as 令牌缓存
    participant Keychain as Keychain/keyring
    participant Google as Google OAuth

    U->>CLI: gws drive files list
    CLI->>Auth: 获取有效凭证
    Auth->>Cache: 检查 token_cache.json
    Cache-->>Auth: 返回缓存令牌
    
    alt 令牌有效
        Auth-->>CLI: 返回凭证
        CLI->>Google: API 请求
    else 令牌过期
        Auth->>Google: 刷新令牌
        Google-->>Auth: 新访问令牌
        Auth->>Cache: 更新缓存
        Auth-->>CLI: 返回凭证
    else 无有效令牌
        Auth->>U: 提示认证
        U->>CLI: gws auth login
        CLI->>Google: 启动 OAuth 流程
        Google->>U: 浏览器授权
        U->>Google: 授权确认
        Google-->>CLI: 授权码
        CLI->>Google: 交换令牌
        Google-->>CLI: 访问令牌 + 刷新令牌
        CLI->>Keychain: 存储加密密钥
        CLI->>Auth: 保存凭证
        Auth->>Cache: 写入 token_cache.json
    end
    
    CLI->>Google: API 请求
    Google-->>CLI: API 响应
    CLI-->>U: 返回结果

已知问题与限制

社区反馈的认证问题

#### Token 缓存未失效 (#780, #764)

问题描述：当用户使用 gws auth login 登录到不同账号时，credentials.enc 会正确更新，但 token_cache.json 仍保留旧账号的令牌缓存。

影响：API 调用可能使用错误的账号身份。

临时解决：手动删除 ~/.config/gws/token_cache.json 后重新认证。

#### 非 TTY 环境阻塞 (#781)

问题描述：gws auth login 在 stdout/stdin 不是 TTY 的环境中（如 CI runner、cron、非交互式 SSH）会无限阻塞，提示不可见。

影响：自动化脚本和 CI/CD 流程无法正常完成认证。

建议：在自动化场景中使用环境变量注入预获取令牌，而非交互式登录。

#### --help 标志被忽略 (#782)

问题描述：gws auth login --help 和 gws auth login -h 不会显示帮助信息，而是直接启动 OAuth 流程。

影响：用户无法快速查看认证命令的用法。

#### macOS Keychain 存储问题 (#360)

问题描述：macOS 环境下，加密密钥可能未能正确存储到 OS Keychain，导致后续命令因解密失败而认证失败。

错误信息：Authentication failed: Failed to decrypt credentials: Decryption failed. Credentials may have been created on a different machine.

解决：v0.22.3 已引入严格 OS Keychain 集成修复此问题。资料来源：v0.22.3 Release Notes

#### Keyring 密钥磁盘写入 (#791)

问题描述：keyring 后端在每次调用时都会将加密密钥写入磁盘 (~/.config/gws/.encryption_key)。

影响：密钥以文件形式存在于磁盘，降低了安全性。

状态：此问题仍在跟踪中，v0.22.3 的修复仅限于 macOS 和 Windows，Linux 仍使用 keyring 后端。

多账号支持缺失

社区长期请求多账号支持（#78、#293、#439），但当前版本仅支持单一账号认证。用户报告在管理个人、工作、客户端等多个 Google Workspace 账号时需要频繁切换认证状态。

安全最佳实践

1. 保护配置文件权限：确保 ~/.config/gws/ 目录权限限制为仅当前用户可访问
2. CI/CD 环境使用最小权限令牌：仅请求必要的 OAuth 作用域
3. 定期轮换服务账号密钥：服务账号场景下定期更新 credentials.json
4. 避免明文凭证存储：优先使用 credentials.enc 而非 credentials.json
5. 清理敏感缓存：在多账号切换场景下，删除 token_cache.json 强制刷新

相关资源

• 认证系统源码 (auth.rs)
• 认证命令 (auth_commands.rs)
• 凭证存储 (credential_store.rs)
• 令牌存储 (token_storage.rs)
• OAuth 配置 (oauth_config.rs)
• GitHub Issues: 认证相关

概述

gws（Google Workspace CLI）的令牌管理模块负责处理 OAuth2 认证令牌的获取、存储、缓存和刷新。该模块确保 CLI 能够安全地访问 Google Workspace API，同时支持多种认证方式以适应不同的使用场景。

令牌管理的核心职责包括：

• 令牌获取：通过 OAuth2 流程获取访问令牌（Access Token）和刷新令牌（Refresh Token）
• 安全存储：使用系统密钥链（Keychain）或文件加密方式安全存储凭证
• 令牌缓存：维护令牌缓存以减少重复认证请求
• 自动刷新：在访问令牌过期时自动使用刷新令牌获取新令牌
• 加密密钥管理：管理用于加密本地存储凭证的对称密钥

资料来源：README.md

认证优先级

gws 支持多种认证方式，系统按以下优先级依次尝试：

资料来源：README.md - Authentication

令牌存储架构

存储位置

gws 将认证数据存储在配置目录中，默认为 ~/.config/gws/：

密钥链集成

从 v0.22.3 版本开始，gws 在 macOS 和 Windows 上使用严格的操作系统密钥链集成：

graph TD
    A[用户执行 gws 命令] --> B{平台检测}
    B -->|macOS| C[使用 Keychain]
    B -->|Windows| D[使用 DPAPI/Credential Manager]
    B -->|Linux| E[使用 keyring 后端]
    
    C --> F{Keychain 状态}
    D --> F
    E --> F
    
    F -->|成功| G[从密钥链获取加密密钥]
    F -->|失败| H[回退到 .encryption_key 文件]
    
    G --> I[解密 credentials.enc]
    H --> I

资料来源：0.22.3 Release Notes

已知问题：密钥链密钥磁盘写入

社区反馈表明，使用 keyring 后端时，加密密钥会在每次调用时写入磁盘（~/.config/gws/.encryption_key），这是一个安全性和性能问题。

资料来源：GitHub Issue #791

令牌缓存机制

缓存文件格式

token_cache.json 存储最近使用的访问令牌，格式如下：

{
  "access_token": "ya29.xxx",
  "refresh_token": "1//xxx",
  "expiry": "2026-04-01T12:00:00Z",
  "scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
  "client_id": "xxx.apps.googleusercontent.com"
}

缓存失效问题

社区报告了令牌缓存失效相关的多个问题：

资料来源：GitHub Issue #764 | GitHub Issue #780

认证命令

gws 提供以下认证相关命令：

auth login

启动 OAuth2 登录流程，交互式获取用户授权。

gws auth login

行为：

1. 启动本地 HTTP 服务器监听回调
2. 打开浏览器进行 Google 授权
3. 接收回调并交换授权码为令牌
4. 加密存储凭证到 credentials.enc

注意：在非 TTY 环境下（如 CI、脚本、cron），此命令会无限阻塞且无可见输出。

资料来源：GitHub Issue #781

auth setup

使用已存在的 gcloud 凭据快速配置认证。

gws auth setup

这是最快的本地开发环境配置方式，前提是系统已安装并配置好 gcloud。

auth status

检查当前认证状态和已授权的令牌信息。

gws auth status

auth export

导出当前凭证用于备份或迁移。

gws auth export --format json

--help 标志处理

社区反馈指出 gws auth login --help 不会显示帮助信息，而是直接执行登录流程，这可能造成意外操作。

资料来源：GitHub Issue #782

环境变量配置

这些变量也可放置在项目根目录的 .env 文件中。

资料来源：README.md - Environment Variables

令牌验证与错误处理

验证模块

gws 在 crates/google-workspace/src/validate.rs 中实现了严格的输入验证，防止令牌相关的安全攻击：

graph LR
    A[令牌/凭证输入] --> B{格式验证}
    B -->|控制字符| C[拒绝]
    B -->|URL 特殊字符| D[拒绝]
    B -->|路径遍历| E[拒绝]
    B -->|合法字符| F[通过验证]
    
    C --> G[Validation Error: 400]
    D --> G
    E --> G

验证规则包括：

• 禁止控制字符（C0、C1、DEL）
• 禁止危险 Unicode 字符（零宽字符、BIDI 覆盖符）
• 禁止 ? 和 # 字符（防止 URL 注入）
• 禁止 % 字符（防止 URL 编码绕过）
• 禁止 .. 路径遍历模式

资料来源：crates/google-workspace/src/validate.rs

错误类型

令牌相关的错误通过 GwsError 枚举统一处理：

资料来源：crates/google-workspace/src/error.rs

认证流程图

sequenceDiagram
    participant U as 用户
    participant CLI as gws
    participant Google as Google OAuth
    participant Keychain as 系统密钥链
    participant Disk as 磁盘存储

    U->>CLI: gws auth login
    CLI->>Google: 发起 OAuth 授权请求
    Google->>U: 显示授权页面
    U->>Google: 授权访问
    Google->>CLI: 返回授权码
    CLI->>Google: 交换授权码为令牌
    Google->>CLI: 返回 access_token, refresh_token
    CLI->>Keychain: 存储加密密钥
    CLI->>Disk: 加密并存储 credentials.enc
    CLI->>Disk: 缓存 token_cache.json
    
    Note over CLI,U: 后续 API 调用
    
    U->>CLI: gws drive files list
    CLI->>Keychain: 获取加密密钥
    Keychain->>CLI: 返回密钥
    CLI->>Disk: 解密 credentials.enc
    CLI->>CLI: 检查令牌是否过期
    alt 令牌未过期
        CLI->>Google: 直接使用缓存令牌
    else 令牌已过期
        CLI->>Google: 使用 refresh_token 刷新
        Google->>CLI: 返回新 access_token
        CLI->>Disk: 更新 token_cache.json
    end

最佳实践

生产环境

1. 使用环境变量：在 CI/CD 环境中使用 GOOGLE_WORKSPACE_CLI_TOKEN 预获取令牌
2. 最小化令牌暴露：避免将令牌写入日志或错误消息
3. 定期轮换：周期性执行 gws auth login 更新令牌

开发环境

1. gcloud 集成：开发时使用 gws auth setup 复用现有 gcloud 认证
2. 检查状态：使用 gws auth status 确认当前认证状态
3. 调试模式：使用 --dry-run 预览 API 调用而不实际发起请求

安全建议

1. 保护配置目录：确保 ~/.config/gws/ 权限设置为仅当前用户可访问
2. 慎用明文凭证：避免使用 credentials.json，优先使用加密的 credentials.enc
3. 监控系统密钥链：在 macOS/Windows 上确保 Keychain 访问控制正确配置

相关命令参考

常见问题

macOS 上凭证解密失败

症状：gws auth login 成功但后续命令失败，提示"Decryption failed"。

原因：macOS Keychain 未正确存储加密密钥，或密钥链项损坏。

解决：参考 Issue #360，确保 Keychain 访问控制正确配置。

资料来源：GitHub Issue #360

非 TTY 环境阻塞

症状：在脚本或 CI 中运行 gws auth login 时命令无限等待。

原因：OAuth 回调需要本地 HTTP 服务器接收，在重定向环境下提示不可见。

解决：使用 GOOGLE_WORKSPACE_CLI_TOKEN 环境变量而非交互式登录。

资料来源：GitHub Issue #781

概述

多账户支持（Multi-account Support）是 gws CLI 工具的一个用户请求功能，旨在允许用户在同一台机器上同时管理多个 Google Workspace 账户（个人、工作、客户端等），并通过命令行参数或配置在账户之间灵活切换。

截至当前版本（v0.22.5），gws CLI 尚未实现多账户支持。根据版本发布说明，该功能在 v0.7.0 版本中被移除：

Release 0.7.0 says that multiple accounts were removed. With no reason why.

资料来源：Community Issue #439

当前实现仅支持单个账户认证，所有凭证和令牌缓存都存储在统一的配置目录中。

当前认证架构

配置目录结构

gws 将所有认证数据存储在单一的配置目录中（默认路径：~/.config/gws）：

~/.config/gws/
├── credentials.enc      # 加密的 OAuth 凭证
├── token_cache.json     # 访问令牌缓存
├── .encryption_key      # 加密密钥（keyring 后端）
└── discovery_cache/     # Discovery 文档缓存

凭证优先级

gws 使用以下优先级顺序来确定认证方式：

资料来源：README.md

核心认证组件

#### 1. credential_store.rs - 凭证存储管理

credential_store.rs 负责管理 OAuth 凭证的加密存储和检索：

• 密钥存储：使用系统 keyring（macOS Keychain、Windows Credential Manager、Linux secret-service）存储加密密钥
• 凭证加密：使用 ring 或 aes-gcm 密码库对 OAuth 凭证进行加密
• 令牌缓存：维护 token_cache.json 以避免频繁刷新令牌

关键存储路径：

• macOS: ~/Library/Keychains/login.keychain-db
• Windows: Windows Credentials (凭据管理器)
• Linux: org.freedesktop.secrets (GNOME Keyring/KWallet)

#### 2. auth_commands.rs - 认证命令处理

auth_commands.rs 定义了所有认证子命令：

pub enum AuthCommand {
    Login(LoginOptions),
    Logout,
    Status,
    Setup,
    Export,
}

主要认证流程：

graph TD
    A[gws auth login] --> B{是否有 --token 参数}
    B -->|是| C[使用预获取的令牌]
    B -->|否| D{是否配置 CREDENTIALS_FILE}
    D -->|是| E[加载凭证文件]
    D -->|否| F{是否有 credentials.enc}
    F -->|是| G[从 keyring 获取密钥并解密]
    F -->|否| H[启动交互式 OAuth 流程]
    H --> I[获取授权码]
    I --> J[交换访问令牌]
    J --> K[加密并存储凭证]
    K --> L[写入 ~/.config/gws/credentials.enc]

已知问题

Token 缓存未失效（Issue #780）

当用户使用 gws auth login 登录到不同账户时，会出现以下问题：

1. ~/.config/gws/credentials.enc 正确更新为新账户凭证
2. ~/.config/gws/token_cache.json 仍保留旧账户的访问令牌

这导致 API 调用可能继续使用旧账户的令牌。

资料来源：Issue #780

凭证解密失败（Issue #360）

在 macOS 上，由于 OS Keychain 未正确存储加密密钥，凭证解密会始终失败：

Authentication failed: Failed to decrypt credentials: 
Decryption failed. Credentials may have been created on a different machine.

资料来源：Issue #360

keyring 密钥写入问题（Issue #791）

每次调用 gws 命令时，keyring 后端会将加密密钥写入磁盘 (~/.config/gws/.encryption_key)，这存在安全隐患。

资料来源：Issue #791

用户需求与社区反馈

热门 Issue 摘要

典型使用场景

用户需要多账户支持的典型场景包括：

1. 工作与个人分离

• 工作邮箱（组织域名）
• 个人 Gmail 账户

1. 多客户管理

• 为不同客户维护独立的认证会话
• 在不同项目间快速切换身份

1. AI 代理集成

• AI 代理需要在同一工作流中使用不同账户访问不同 API
• 需要通过命令行参数指定账户，而非重新认证

期望的 API 设计

社区期望的账户切换方式类似于 gog 工具：

# 使用工作账户
gws gmail search "newer_than:1d" --account [email protected]

# 使用个人账户
gws drive files list --account [email protected]

# 列出所有已配置的账户
gws auth list

# 添加新账户
gws auth add --account [email protected]

资料来源：Issue #78

多账户支持的设计考量

基于当前代码架构，实现多账户支持需要考虑以下方面：

1. 目录结构变更

~/.config/gws/
├── accounts/
│   ├── [email protected]/
│   │   ├── credentials.enc
│   │   └── token_cache.json
│   └── [email protected]/
│       ├── credentials.enc
│       └── token_cache.json
├── .active_account          # 当前激活的账户标识
└── .encryption_key          # 主加密密钥

2. 认证流程变更

需要修改 auth_commands.rs 和 credential_store.rs 以支持：

• 按账户名称隔离凭证存储
• 新增 --account 参数选择认证账户
• 默认使用上次激活的账户

3. 错误处理增强

error.rs 中需要新增多账户相关的错误类型：

资料来源：crates/google-workspace/src/error.rs

4. 验证逻辑

validate.rs 中需要扩展验证函数以支持账户名称验证：

pub fn validate_account_name(s: &str) -> Result<&str, GwsError> {
    // 允许字母、数字、@ 符号、点号和连字符
    // 禁止路径遍历字符
}

资料来源：crates/google-workspace/src/validate.rs

当前工作区统计

总结

gws CLI 当前版本不支持多账户功能，这是社区呼声最高的特性请求之一。实现此功能需要对凭证存储架构、认证命令处理和环境变量管理进行重大修改。建议关注官方 Release Notes 和 GitHub Issues 以获取后续开发进展。

概述

gws (Google Workspace CLI) 的命令系统是一个运行时动态生成的架构。与传统的 CLI 工具不同，gws 不包含硬编码的命令列表，而是在启动时从 Google Discovery Service 获取 API 规范，自动构建完整的命令表面。这种设计确保当 Google Workspace 新增或更新 API 端点时，gws 能够自动获取，无需版本更新。

graph TD
    A[gws 启动] --> B[从 Discovery Service 获取 API 规范]
    B --> C[解析 Discovery Document]
    C --> D[动态构建命令树]
    D --> E[注册到 clap 命令解析器]
    E --> F[等待用户输入]
    F --> G{命令类型}
    G -->|Discovery 命令| H[构建 HTTP 请求]
    G -->|Helper 命令| I[执行编排逻辑]
    H --> J[发送请求到 Google API]
    I --> J
    J --> K[返回 JSON 响应]

命令类型

gws 的命令系统包含两类命令：

Discovery 命令

Discovery 命令遵循 <服务> <资源> <方法> 的三级结构：

# 服务: drive
# 资源: files
# 方法: list
gws drive files list --params '{"pageSize": 10}'

# 服务: gmail
# 资源: users.messages
# 方法: get
gws gmail users.messages get --params '{"id": "MESSAGE_ID"}'

# 服务: sheets
# 资源: spreadsheets.values
# 方法: append
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1"}' \
  --json '{"values": [["A", "B"]]}'

Helper 命令

Helper 命令使用 + 前缀标识，提供 Discovery 命令无法实现的功能：

gws gmail +send --to [email protected] --subject "Hello" --body "Hi"
gws gmail +reply --message-id MSG_ID --body "Thanks!"
gws calendar +agenda --today
gws drive +upload ./report.pdf --name "Q1 Report"
gws workflow +standup-report

命令解析架构

分层结构

graph LR
    A[用户输入] --> B[clap 全局解析器]
    B --> C[服务选择]
    C --> D[子命令解析]
    D --> E{命令类型}
    E -->|Discovery| F[参数验证]
    E -->|Helper| G[编排执行]
    F --> H[请求构建]
    G --> H
    H --> I[HTTP 客户端]
    I --> J[响应格式化]

命令定义来源

Discovery 命令的完整定义存储在 Google Discovery Document 中，包含以下关键结构：

{
  "name": "drive.files.list",
  "restPath": "/drive/v3/files",
  "httpMethod": "GET",
  "parameters": {
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of files to return"
    },
    "fields": {
      "type": "string",
      "description": "Selector specifying which fields to include"
    }
  },
  "request": { "$ref": "FileList" },
  "response": { "$ref": "FileList" }
}

Helper 命令设计原则

Helper 命令的存在有严格的设计标准。核心原则是：Helper 必须提供 Discovery 命令无法实现的价值。

合理场景

反对模式

判断标准：如果用户可以通过 gws <service> <resource> <method> --params '{...}' 实现相同结果，则不应添加 Helper 命令。

参数传递机制

`--params` 参数

用于传递 API 特定的查询参数和路径参数：

gws drive files list --params '{"pageSize": 10, "orderBy": "createdTime desc"}'

`--json` 参数

用于传递 API 请求体（POST/PUT/PATCH 方法）：

gws gmail users.messages send \
  --params '{"userId": "me"}' \
  --json '{"raw": "Base64编码的邮件内容"}'

分页控制

# 读取所有文件，输出 NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all

# 限制最多 5 页
gws gmail users.messages list --params '{"maxResults": 50}' --page-limit 5

输入验证层

gws 在命令执行前进行多层验证：

graph TD
    A[用户输入解析] --> B[字符安全检查]
    B --> C{包含危险字符?}
    C -->|是| D[拒绝并报错]
    C -->|否| E[路径安全检查]
    E --> F{路径遍历?}
    F -->|是| D
    F -->|否| G[资源名称验证]
    G --> H{名称格式正确?}
    H -->|是| I[执行命令]
    H -->|否| D

验证规则

资源名称验证 (validate_resource_name)：

• 拒绝 .. 路径遍历
• 拒绝 URL 特殊字符 ? 和 #
• 拒绝 % (防止 URL 编码绕过)
• 拒绝控制字符 (C0: U+0000-U+001F, C1: U+0080-U+009F, DEL: U+007F)
• 拒绝危险 Unicode 字符

API 标识符验证 (validate_api_identifier)：

• 仅允许字母数字、-、_、.
• 防止路径遍历和注入攻击

已知问题

`--help` 标志被忽略

问题：gws auth login --help 不会打印帮助信息，而是直接启动 OAuth 流程。

影响：在脚本或 CI 环境中运行可能产生意外行为。

相关 Issue：#782

TTY 检测问题

问题：当 stdout/stdin 不是 TTY 时（如脚本、CI runner、cron），gws auth login 会无限阻塞且无可见输出。

相关 Issue：#781

服务别名与版本

gws 支持服务别名，便于记忆：

# 完整写法
gws drive v3 files list

# 别名写法（自动解析版本）
gws drive files list

常见服务别名映射：

环境变量配置

命令行为可通过以下环境变量影响：

扩展命令系统

自定义 Helper

添加新的 Helper 命令需要满足以下条件：

1. 多步骤编排或 Discovery 无法实现的逻辑
2. Flag 控制编排逻辑，而非 API 参数
3. 不重复 Discovery 已暴露的功能

Gemini CLI 扩展

gws 可作为 Gemini CLI 扩展安装，为 AI Agent 提供 Google Workspace 操作能力：

gemini extensions install https://github.com/googleworkspace/cli

扩展安装后，Agent 可直接使用所有 gws 命令和 Workspace 技能。

设计原则

gws 的核心设计基于 Schema 驱动：命令在运行时从 Google Discovery Documents 动态生成。这种设计避免了维护硬编码的无限参数表面。助手命令必须作为这种设计的补充，而非重复。

何时添加助手命令

决策检查清单

1. 此标志是否控制要调用哪个 API 或如何编排多个调用？→ ✅ 添加
2. 此标志是否控制输出中出现什么数据？→ ❌ 使用 --format/jq
3. 此标志是否重复 Discovery 参数？→ ❌ 使用 --params
4. 用户能否用 gws <service> <resource> <method> --params '{...}' 实现相同结果？→ ❌ 不添加助手命令

资料来源：crates/google-workspace-cli/src/helpers/README.md

命令前缀约定

所有助手命令统一使用 + 前缀，与 Discovery 生成的方法名区分开来。这一设计确保：

• 视觉上清晰区分两类命令
• 永远不会与 Discovery 方法名冲突
• 运行 gws <service> --help 时可同时查看两类命令

gws gmail --help      # 显示 +send, +reply, +reply-all, +forward, +triage, +watch 等
gws calendar --help   # 显示 +insert, +agenda 等
gws drive --help       # 显示 +upload 等

资料来源：crates/google-workspace-cli/README.md

Gmail 助手命令

Gmail 服务提供最丰富的助手命令集，涵盖邮件发送、回复、转发和收件箱管理。

邮件发送（+send）

+send 命令处理 RFC 2822 MIME 构建，自动处理以下复杂性：

• 设置 From 头时从 send-as 设置中自动填充显示名称
• 正确处理线程关联
• 管理附件编码

gws gmail +send --to [email protected] --subject "Hello" --body "Hi there"

关键特性：

• 自动从用户 send-as 配置丰富 --from 邮箱地址
• 支持 --cc、--bcc 多收件人
• 附件支持通过 --attachment 标志

资料来源：crates/google-workspace-cli/src/helpers/gmail/send.rs

邮件回复（+reply / +reply-all）

回复命令自动处理线程机制，根据原始消息构建正确的 In-Reply-To 和 References 头：

# 回复单封邮件
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# 回复所有人
gws gmail +reply-all --message-id MESSAGE_ID --body "Got it, thanks everyone!"

这些命令从原始消息中提取线程 ID，并在构建 MIME 时自动设置必要的邮件头。

资料来源：crates/google-workspace-cli/src/helpers/gmail/reply.rs

邮件转发（+forward）

gws gmail +forward --message-id MESSAGE_ID --to [email protected]

收件箱分类（+triage）

显示未读收件箱摘要（发件人、主题、日期），用于快速浏览新邮件：

gws gmail +triage

实时监控（+watch）

监视新邮件并以 NDJSON 格式流式传输：

gws gmail +watch

Calendar 助手命令

日程插入（+insert）

创建新日历事件，支持自动时区处理：

gws calendar +insert --title "会议" --start "2024-01-15T10:00:00" --end "2024-01-15T11:00:00"

日程议程（+agenda）

显示即将到来的事件，自动使用 Google 账户时区：

# 显示今天日程
gws calendar +agenda

# 指定时区
gws calendar +agenda --timezone America/New_York

# 仅显示今天
gws calendar +agenda --today

时间感知助手（+agenda、+standup-report、+weekly-digest、+meeting-prep）自动使用 Google 账户时区，可通过 --timezone/--tz 标志覆盖。

资料来源：crates/google-workspace-cli/src/helpers/calendar.rs 资料来源：crates/google-workspace-cli/src/timezone.rs

Drive 助手命令

文件上传（+upload）

处理可恢复上传协议，支持自动元数据填充：

# 上传文件
gws drive +upload ./report.pdf --name "Q1 Report"

# 与 JSON 元数据结合
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

该命令处理分块上传协议，显示进度条，并自动设置 MIME 类型。

Sheets 助手命令

追加行（+append）

向电子表格追加行数据：

gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

读取数据（+read）

从电子表格读取值：

gws sheets +read --spreadsheet SPREADSHEET_ID --range "Sheet1!A1:C10"

Shell 转义提示：Sheets 范围使用 !，bash 会将其解释为历史展开。务必用单引号包裹值。

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

Docs 助手命令

写入文档（+write）

将文本追加到文档，执行 Markdown 到 Docs batchUpdate JSON 的格式转换：

gws docs +write --document DOC_ID --content "新段落内容"

Chat 助手命令

发送消息（+send）

向 Chat space 发送消息：

gws chat +send --space SPACES_ID --text "部署完成"

Script 助手命令

推送代码（+push）

用本地文件替换 Apps Script 项目中的所有文件：

gws script +push --project PROJECT_ID ./local/scripts/

Workflow 工作流命令

工作流命令将多个服务调用链接在一起，提供高级自动化场景。

站会报告（+standup-report）

汇总今日会议和未读邮件数：

gws workflow +standup-report

会议准备（+meeting-prep）

为下一场会议做准备：议程、参会者和关联文档：

gws workflow +meeting-prep

邮件转任务（+email-to-task）

将 Gmail 消息转换为 Google Tasks 条目：

gws workflow +email-to-task --message-id MESSAGE_ID

周报摘要（+weekly-digest）

本周会议汇总 + 未读邮件数：

gws workflow +weekly-digest

文件公告（+file-announce）

在 Chat space 中公告 Drive 文件：

gws workflow +file-announce --file FILE_ID --space SPACE_ID

资料来源：crates/google-workspace-cli/src/helpers/workflows.rs

Events 事件订阅命令

订阅（+subscribe）

订阅 Workspace Events 并以 NDJSON 格式流式传输：

gws events +subscribe --target TARGET --project PROJECT_ID

该命令执行多步骤编排：创建 Pub/Sub 主题 → 创建订阅 → 创建 Workspace Events 订阅。

续订（+renew）

续订/重新激活 Workspace Events 订阅：

gws events +renew --subscription SUBSCRIPTION_ID

Model Armor 命令

集成 Google Cloud Model Armor 扫描 API 响应中的提示注入。

提示清理（+sanitize-prompt）

通过 Model Armor 模板清理用户提示：

gws modelarmor +sanitize-prompt --template "projects/P/locations/L/templates/T" --text "用户输入"

响应清理（+sanitize-response）

通过 Model Armor 模板清理模型响应：

gws modelarmor +sanitize-response --template "projects/P/locations/L/templates/T" --response "模型响应"

创建模板（+create-template）

创建新的 Model Armor 模板：

gws modelarmor +create-template --name "我的模板" --rules "规则配置"

助手命令架构图

graph TD
    subgraph 用户命令层
        A["gws <service> +helper"]
    end

    subgraph 助手命令类型
        B["多步骤编排<br/>+subscribe, +renew"]
        C["格式转换<br/>+write, +send"]
        D["多 API 组合<br/>+triage, +standup-report"]
        E["复杂请求体<br/>+reply, +reply-all"]
        F["工作流配方<br/>+meeting-prep"]
    end

    subgraph 底层服务
        G["Discovery API"]
        H["Pub/Sub API"]
        I["Calendar API"]
        J["Gmail API"]
        K["Drive API"]
    end

    A --> B
    A --> C
    A --> D
    A --> E
    A --> F

    B --> H
    B --> I
    C --> J
    D --> J
    E --> J
    F --> I
    F --> J
    F --> K

    G -.->|"动态生成<br/>Discovery 方法"| A

完整命令参考表

资料来源：crates/google-workspace-cli/README.md

标志设计规则

✅ 好的标志（控制编排逻辑）

❌ 坏的标志（暴露 API 响应数据）

常见问题

如何查看所有可用助手命令？

# 按服务查看
gws gmail --help
gws calendar --help
gws drive --help

# 查看所有 Discovery 方法和助手命令
gws <service> --help

助手命令与 Discovery 命令有何区别？

• Discovery 命令：动态生成，运行时从 Google Discovery Service 读取
• 助手命令：以 + 开头的手工编写命令，提供 Discovery 无法实现的增值功能

时区如何处理？

时间感知助手（+agenda、+standup-report、+weekly-digest、+meeting-prep）自动使用 Google 账户时区。首次调用时从 Calendar Settings API 获取并缓存 24 小时。

# 使用账户时区
gws calendar +agenda

# 覆盖时区
gws calendar +agenda --timezone America/New_York

相关文档

• 帮助命令设计指南
• 完整命令参考
• 环境变量配置

概述

AI 代理技能（Agent Skills）是 gws CLI 为 AI 代理提供的结构化工作流定义文件，使大语言模型能够直接调用 Google Workspace API 执行复杂任务。这些技能以 SKILL.md 格式存储，包含触发指令、执行示例和参数说明，AI 代理通过阅读这些技能文档即可理解如何调用 gws 完成特定工作流程。

gws 仓库内置了 100+ 个技能文件，涵盖 Gmail、Drive、Calendar、Docs、Sheets、Chat 等所有支持的 Workspace 服务，并附带 50+ 个精选工作流配方（Recipes）。资料来源：README.md

核心设计理念

gws 的命令表面是通过 Discovery Service 动态生成的，AI 代理技能必须与此设计互补而非重复。技能文件中的 + 前缀命令（如 +send、+triage、+agenda）代表更高层次的编排逻辑，包括多步骤编排、格式转换、多 API 组合和复杂请求体构建。

单一 API 调用的简单包装不应作为技能实现——Discovery 驱动的方式已经暴露了所有底层方法。资料来源：crates/google-workspace-cli/src/helpers/README.md

技能类型与分类

按功能分类

按服务分组

资料来源：docs/skills.md

技能执行机制

命令行助手命令（+命令）

+ 前缀的助手命令是预包装的高层次操作，与 Discovery 动态生成的命令共存于 gws <service> --help 输出中。时区感知型助手（+agenda、+standup-report、+weekly-digest、+meeting-prep）会自动使用 Google 账户配置的时区，该时区从 Calendar Settings API 获取并缓存 24 小时。

# 查看 Gmail 所有可用命令（包括 +命令）
gws gmail --help

# 查看 Calendar 所有可用命令（包括 +命令）
gws calendar --help

助手命令参考表

资料来源：README.md

技能安装与配置

安装所有技能

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

按需安装特定技能

# 仅安装 Drive 技能
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

# 仅安装 Gmail 技能
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

OpenClaw 安装方式

# 符号链接所有技能（与仓库保持同步）
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# 或复制特定技能
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

gws-shared 技能包含 install 块，使 OpenClaw 能够在 gws 不在 PATH 中时自动通过 npm 安装 CLI。

Gemini CLI 扩展集成

``bash gws auth setup ``

1. 首先完成 CLI 认证：

``bash gemini extensions install https://github.com/googleworkspace/cli ``

1. 将扩展安装到 Gemini CLI：

安装此扩展后，Gemini CLI 代理可直接访问所有 gws 命令和 Google Workspace 技能。由于 gws 自行处理身份验证，用户只需在终端认证一次，扩展将自动继承凭证。

配方（Recipes）与角色（Personas）

配方定义

配方是预定义的工作流序列，存储在 crates/google-workspace-cli/registry/recipes.toml 中。每个配方包含：

• 标识符：唯一名称
• 触发器：激活配方的关键词
• 步骤序列：要执行的具体命令和参数
• 描述：配方的用途说明

角色定义

角色（Personas）定义了特定场景下的 AI 代理行为模式，存储在 crates/google-workspace-cli/registry/personas.toml 中。角色与配方的区别在于：

技能开发指南

何时需要新技能

助手命令仅在以下情况正当时才应存在：

检验标准：用户能否通过 gws <service> <resource> <method> --params '{...}' 获得相同结果？如果可以，则不需要添加助手。

标志设计规则

助手标志必须控制编排逻辑，而非 API 参数或输出字段。

✅ 好的标志（控制编排）：

❌ 坏的标志（暴露 API 响应数据）：

开发步骤

1. 在 src/helpers/<service>.rs 中创建助手实现
2. 实现 Helper trait
3. 在 src/helpers/mod.rs 中注册
4. 用 + 前缀命名命令（如 +create）
5. 使用 crate::validate::encode_path_segment() 进行 URL 路径段编码
6. 使用 crate::output::sanitize_for_terminal() 处理错误消息
7. 添加测试：命令注册、必需参数、正常路径
8. 支持需要创建或修改资源的助手的 --dry-run

资料来源：crates/google-workspace-cli/src/helpers/README.md

Model Armor 集成

Model Armor 是 Google Cloud 安全产品，用于在 API 响应到达代理之前扫描提示词注入攻击。

配置方式

# 在命令中指定净化模板
gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

环境变量配置

与 AI 代理的协同

为什么为 AI 代理设计

gws 的每个响应都是结构化 JSON，这使得大语言模型能够可靠地解析和利用 API 返回的数据。结合内置的代理技能，LLM 无需自定义工具即可管理 Google Workspace。

# 列出最近的 10 个文件
gws drive files list --params '{"pageSize": 10}'

# 创建电子表格
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# 预览请求（dry-run）
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# 以 NDJSON 格式流式输出分页结果
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

社区关注的集成点

从社区讨论中可见，用户对以下场景的 AI 代理集成高度关注：

• 多账户支持：当前 gws 仅支持单一账户认证，但在 AI 代理场景下，不同代理可能需要使用不同账户（Issue #78、#293、#439）
• Token 缓存失效：切换账户后 token 缓存未正确更新的问题（Issue #780、#764）
• 非 TTY 环境：在 CI runner 或远程 SSH 会话中 auth login 会无限阻塞（Issue #781）

完整技能索引

完整的技能列表和索引文档位于 docs/skills.md，包含每个技能文件的：

• 功能描述
• 触发短语
• 使用示例
• 参数说明
• 与其他技能的关联

索引数据结构

技能索引按服务分组，每个技能包含以下元数据：

名称        → SKILL.md 文件名
服务        → 所属 Workspace 服务
描述       → 功能摘要
触发短语    → LLM 可识别的激活词
依赖项      → 需要的其他技能或 API

相关资源

• 完整 README 文档
• 技能索引文档
• 助手命令开发指南
• Discovery Service 动态命令机制
• Google Workspace API 文档

诊断工具

启用调试输出

使用 --debug 标志获取详细的执行日志：

gws drive files list --debug --params '{"pageSize": 5}'

调试输出包含 HTTP 请求/响应、Discovery 文档获取过程以及加密操作的详细信息。资料来源：crates/google-workspace-cli/README.md

验证认证状态

gws auth status

该命令显示当前配置的凭据、令牌缓存状态以及有效的 OAuth 范围。资料来源：crates/google-workspace-cli/README.md

认证问题

凭据解密失败 (macOS)

症状：执行 gws auth login 成功后，所有后续命令失败并显示：

Authentication failed: Failed to decrypt credentials: Decryption failed. Credentials may have been created on a different machine.

原因：macOS Keychain 未正确存储加密密钥，导致 CLI 无法解密 ~/.config/gws/credentials.enc。这是社区报告的 #360 问题。

解决方案：

1. 检查 Keychain 中是否存在 gws 相关条目：

security find-generic-password -s "gws"

1. 如条目存在但无效，删除后重新认证：

security delete-generic-password -s "gws"
gws auth login

1. 确保系统已启用 Keychain 访问

加密密钥磁盘写入

症状：每次调用 gws 命令时，CLI 向 ~/.config/gws/.encryption_key 写入加密密钥。

原因：这是 keyring 后端的已知行为 (#791)。当 Keychain 后端不可用时，CLI 回退到文件存储。

临时解决：

chmod 600 ~/.config/gws/.encryption_key

令牌缓存失效

症状：重新认证获取新范围后，API 调用仍使用旧的访问令牌。

原因：#764 - 令牌缓存未在凭据更新后失效。

解决方案：手动清除令牌缓存：

rm ~/.config/gws/token_cache.json
gws auth login

切换账户后旧令牌仍生效

症状：使用 gws auth login 登录不同账户后，credentials.enc 已更新但 API 调用仍使用旧账户。

原因：#780 - token_cache.json 在切换账户时未清除。

解决方案：

rm ~/.config/gws/token_cache.json
gws auth status

非 TTY 环境阻塞

症状：在 CI runner、cron 或 SSH 非 PTY 会话中执行 gws auth login 时，命令无限阻塞且无输出。

原因：#781 - OAuth 流程需要终端交互。

替代方案：使用预获取的访问令牌或服务账号凭据：

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

资料来源：README.md - 环境变量配置

--help 标志被忽略

症状：gws auth login --help 启动 OAuth 流程而非显示帮助信息。

原因：#782 - auth 子命令的参数解析问题。

替代方案：使用 gws help auth login 或 gws auth --help。

API 错误

错误响应格式

所有 API 错误以统一 JSON 格式返回：

{
  "error": {
    "code": 404,
    "message": "File not found",
    "reason": "notFound"
  }
}

错误码映射规则：

资料来源：crates/google-workspace/src/error.rs:40-75

验证错误

症状：

Error: Resource name must not contain '?' or '#': spaces/ABC?key=val

原因：输入包含 URL 特殊字符，可能表示注入尝试。资料来源：crates/google-workspace/src/validate.rs:60-65

解决方案：移除查询参数或锚点，仅传递纯资源标识符。

路径遍历防护

症状：

Error: Resource name contains path traversal: spaces/../other

原因：输入包含 .. 或其他路径遍历序列。资料来源：crates/google-workspace/src/validate.rs:50-55

防护措施：

if s.contains("..") {
    return Err(GwsError::Validation(...));
}

资料来源：crates/google-workspace/src/validate.rs:45-48

危险 Unicode 字符拒绝

症状：

Error: Resource name contains invalid Unicode characters

原因：输入包含零宽字符、双向文本覆盖符或段落分隔符。资料来源：crates/google-workspace/src/validate.rs:115-130

被拒绝的字符范围：

控制字符拒绝

症状：

Error: --message-id contains invalid control characters

原因：输入包含 C0/C1 控制字符或 DEL 字符 (U+007F)。资料来源：crates/google-workspace/src/validate.rs:135-145

Discovery 服务问题

文档获取失败

症状：

Error: Failed to fetch discovery document: Connection refused

原因：无法访问 Google Discovery API (https://discovery.googleapis.com/discovery/v1/)。资料来源：crates/google-workspace/src/discovery.rs:80-90

诊断步骤：

curl -I https://discovery.googleapis.com/discovery/v1/apis

缓存策略

Discovery 文档在磁盘缓存，TTL 为 24 小时：

清除缓存：

rm -rf ~/.cache/gws/discovery
gws drive files list

API 标识符验证

症状：

Error: API identifier contains invalid characters (only alphanumeric, '-', '_', '.' allowed): service@name

原因：服务名称包含非法字符。资料来源：crates/google-workspace/src/validate.rs:70-85

多账户支持

当前限制

gws 目前仅支持单账户认证。多账户功能在 #78、#293 和 #439 中被多次请求。

临时方案：使用环境变量切换账户：

# 账户 A
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token [email protected])

# 账户 B  
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token [email protected])

Gmail 同步 ID 解析

问题描述

Gmail 网页界面的 URL 使用同步 ID (如 FMfcgzQgLjNPlfJCVRfnNkPGkLhWClCW)，而非 API 线程 ID。直接传递给 API 会返回 Invalid id value 错误。资料来源：#790

解决方案

使用 Gmail API 列表接口查找对应线程：

gws gmail users.messages list --params '{"labelIds": ["INBOX"]}' | \
  jq '.messages[] | select(.threadId == "THREAD_ID")'

配置目录与权限

默认配置位置

环境变量覆盖

export GOOGLE_WORKSPACE_CLI_CONFIG_DIR="/path/to/custom/config"

权限检查

ls -la ~/.config/gws/
# 应显示 gws 用户拥有读写权限

常见错误速查表

安装方式概览

gws 支持多种安装渠道，适用于不同的使用场景：

资料来源：README.md:1-30

支持的平台

gws 提供预编译二进制文件，覆盖主流操作系统和架构：

平台列表

资料来源：npm/package.json:35-55

从 Release 手动安装

# 1. 下载归档文件及其校验和
curl -sLO https://github.com/googleworkspace/cli/releases/download/v0.22.5/google-workspace-cli-<target>.tar.gz
curl -sLO https://github.com/googleworkspace/cli/releases/download/v0.22.5/google-workspace-cli-<target>.tar.gz.sha256

# 2. 验证完整性
sha256sum -c google-workspace-cli-<target>.tar.gz.sha256

# 3. 解压并安装
tar -xzf google-workspace-cli-<target>.tar.gz
./gws --help

将 <target> 替换为对应平台的标识符，例如 x86_64-unknown-linux-gnu。

资料来源：README.md:Release v0.22.5

环境变量配置

所有环境变量均为可选配置。CLI 会按优先级自动选择认证源：

认证优先级

配置变量

环境变量可写入 .env 文件，CLI 会自动加载。

资料来源：README.md:环境变量章节

配置目录结构

gws 的配置存储在 ~/.config/gws 目录下（可通过 GOOGLE_WORKSPACE_CLI_CONFIG_DIR 覆盖）：

graph TD
    A[~/.config/gws] --> B[credentials.enc]
    A --> C[token_cache.json]
    A --> D[.encryption_key]
    A --> E[credentials.json]
    A --> F[discovery_cache/]
    
    B --> G[加密的 OAuth 凭据]
    C --> H[缓存的 Access Token]
    D --> I[Keyring 后端加密密钥]
    F --> J[Discovery Document 缓存]

关键文件说明

已知问题：在某些环境下，密钥环后端会频繁写入 .encryption_key 文件。参见 Issue #791。

资料来源：crates/google-workspace/src/discovery.rs 资料来源：社区 Issue #791

认证配置

交互式本地桌面认证（推荐）

使用已登录的 gcloud 凭证：

gws auth setup

这是最快的本地开发认证方式，CLI 会自动使用 gcloud 的应用默认凭证。

手动 OAuth 设置

1. 在 Google Cloud Console 创建 OAuth 2.0 Client ID（类型：Desktop app）
2. 下载 JSON 文件
3. 设置环境变量或放置在指定位置：

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="/path/to/client_secret.json"
gws auth login

使用预获取的 Access Token

适用于已由其他工具（如 gcloud）管理 Token 的环境：

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
gws drive files list

CI/CD 环境认证

注意：gws auth login 在非 TTY 环境下会无限阻塞。参见 Issue #781。

资料来源：README.md:Authentication 章节 资料来源：社区 Issue #781

Token 缓存行为

缓存失效机制

Token 缓存在 ~/.config/gws/token_cache.json 中存储。当凭据更新后，缓存可能不会自动失效：

已知问题：切换账号后 token_cache.json 不会自动清除。参见 Issue #780 和 Issue #764。

临时解决方案

# 手动清除 Token 缓存
rm ~/.config/gws/token_cache.json

# 或清除所有认证数据
rm -rf ~/.config/gws/credentials.enc ~/.config/gws/token_cache.json

资料来源：社区 Issue #780 资料来源：社区 Issue #764

Model Armor 集成

gws 支持集成 Google Cloud Model Armor，对 API 响应进行提示注入扫描：

gws gmail users messages get --params '{...}' \
  --sanitize "projects/P/locations/L/templates/T"

配置选项

资料来源：README.md:Model Armor 章节

Agent Skills 安装

gws 包含 100+ Agent Skills，可用于 Gemini CLI 等 AI Agent：

安装所有 Skills

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

安装特定 Skills

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

OpenClaw 集成

# 符号链接所有 Skills（与仓库保持同步）
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# 或复制特定 Skills
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

资料来源：README.md:AI Agent Skills 章节

快速验证

安装完成后，验证 CLI 是否正常工作：

# 检查版本
gws --version

# 验证认证状态
gws auth status

# 测试 API 调用
gws drive files list --params '{"pageSize": 5}'
gws gmail users.messages list --params '{"maxResults": 3}'

故障排除

相关文档

• 认证配置
• 环境变量完整列表
• Skills 索引
• GitHub Issues

Pitfall Log / 踩坑日志

项目：googleworkspace/cli

摘要：发现 18 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Multiple commands return exit 0 with empty stdout when output serialization fails, silently swallowing successful API r…。

1. 安全/权限坑 · 来源证据：Multiple commands return exit 0 with empty stdout when output serialization fails, silently swallowing successful API r…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Multiple commands return exit 0 with empty stdout when output serialization fails, silently swallowing successful API responses
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_93db91c5a08e4daba58b5f0ff2e829ec | https://github.com/googleworkspace/cli/issues/740 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：Please restore multiple accounts being able to be used

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Please restore multiple accounts being able to be used
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a857d186b1b74ede965ea415f911322a | https://github.com/googleworkspace/cli/issues/439 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...

• 严重度：medium
• 证据强度：source_linked
• 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...

4. 能力坑 · 社区讨论暴露的待验证问题：I built Muninn, an open-source proxy for AI coding agents like Claude ...

• 严重度：medium
• 证据强度：source_linked
• 发现：I built Muninn, an open-source proxy for AI coding agents like Claude ... 12 Jan 2026 · We built an open-source coding agent CLI that can be run locally ... Turn 10,000 API endpoints into one CLI tool instead of MCP, Skills and tools ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_6102ff6da0284536abb5e26f2533abed | https://www.reddit.com/r/LocalLLaMA/comments/1qai4ul/i_built_muninn_an_opensource_proxy_for_ai_coding/ | I built Muninn, an open-source proxy for AI coding agents like Claude ...

5. 能力坑 · 社区讨论暴露的待验证问题：Open Source Claude Coder alternative? : r/LocalLLaMA - Reddit

• 严重度：medium
• 证据强度：source_linked
• 发现：Open Source Claude Coder alternative? : r/LocalLLaMA - Reddit 11 Jul 2025 · https://github.com/google-gemini/gemini-cli · https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/ · Dentuam.
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_c4981b55cfdd415d980deff32dcc52a8 | https://www.reddit.com/r/LocalLLaMA/comments/1lww2w9/open_source_claude_coder_alternative/ | Open Source Claude Coder alternative? : r/LocalLLaMA - Reddit

6. 能力坑 · 社区讨论暴露的待验证问题：The best open source general AI agent is on !

• 严重度：medium
• 证据强度：source_linked
• 发现：The best open source general AI agent is on ! Excited to share our new project OWL - an open-source alternative to Manus AI with 6K+ stars and climbing… OWL: github.com/camel-ai/owl
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:x | ssig_9705a4152aac4e7db1ec2472633ef681 | https://x.com/CamelAIOrg/status/1899069486587593176 | The best open source general AI agent is on !

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_5acca765122c4bdb92a82f7a086f8c02 | https://github.com/googleworkspace/cli#readme | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：Posted in error by Automation tool

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Posted in error by Automation tool
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8d9bcef5bfdd494cb3f6cf54c76e16a1 | https://github.com/googleworkspace/cli/issues/768 | 来源类型 github_issue 暴露的待验证使用条件。

9. 运行坑 · 社区讨论暴露的待验证问题：I Open Sourced My Unified A.I. Agent Memory Solution : r/selfhosted

• 严重度：medium
• 证据强度：source_linked
• 发现：I Open Sourced My Unified A.I. Agent Memory Solution : r/selfhosted 6 Mar 2026 · I read this: Each zip contains the desktop app, CLI, MCP server, and ONNX runtime. ... Looking for open-source knowledge management tool with AI ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_63d78212c6ab427285fa30b9fd047945 | https://www.reddit.com/r/selfhosted/comments/1rmu2yt/i_open_sourced_my_unified_ai_agent_memory_solution/ | I Open Sourced My Unified A.I. Agent Memory Solution : r/selfhosted

10. 运行坑 · 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit

• 严重度：medium
• 证据强度：source_linked
• 发现：why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit

11. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_5acca765122c4bdb92a82f7a086f8c02 | https://github.com/googleworkspace/cli#readme | last_activity_observed missing

12. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_5acca765122c4bdb92a82f7a086f8c02 | https://github.com/googleworkspace/cli#readme | no_demo; severity=medium

13. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_5acca765122c4bdb92a82f7a086f8c02 | https://github.com/googleworkspace/cli#readme | no_demo; severity=medium

14. 安全/权限坑 · 来源证据：Regression: `gws auth login -s chat` requests no Chat scope in v0.22.5 (dynamic Discovery fallback from #236/#352 not f…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Regression: gws auth login -s chat requests no Chat scope in v0.22.5 (dynamic Discovery fallback from #236/#352 not firing)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8c2b4459afc34b9192af3bb9c9ba3619 | https://github.com/googleworkspace/cli/issues/822 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：Support `--port` and `--no-browser` flags for `gws auth login` on remote/headless machines

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support --port and --no-browser flags for gws auth login on remote/headless machines
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_02a20e9aaaf44fd7b1b7ba66edf337e4 | https://github.com/googleworkspace/cli/issues/210 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：gws 0.6.0: drafts.create rejects valid --params with 'expected a map'; works in 0.15.0+

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：gws 0.6.0: drafts.create rejects valid --params with 'expected a map'; works in 0.15.0+
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_48b12ba60f1d4d7ab9e84e450c386a3b | https://github.com/googleworkspace/cli/issues/821 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_5acca765122c4bdb92a82f7a086f8c02 | https://github.com/googleworkspace/cli#readme | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_5acca765122c4bdb92a82f7a086f8c02 | https://github.com/googleworkspace/cli#readme | release_recency=unknown