gws-shared 是 gws CLI 的共享参考，面向无头、经代理认证的环境，统一说明认证方式、全局标志与输出格式。此处的认证模型取代上游的 gws auth login 和服务账号流程，不应再参照上游文档或 --help 中的认证说明。
用途：为 gmail、calendar、drive 等各服务提供跨服务的通用约定。
主要能力与约定：
认证。没有交互用户，也没有服务账号密钥文件，因此不要运行 gws auth login、gws auth setup 或任何 gws auth ... 命令，也不要设置 GOOGLE_APPLICATION_CREDENTIALS 或指向 key.json。认证由代理透明处理：每次命令都必须传入 --email=<地址> 指定所代表的用户，代理会用该用户真实的 OAuth 令牌替换你提供的 --email 值。你必须使用等号形式 --email=<地址>，空格分隔形式会被视为缺失。该参数对所有服务均为必需；各服务技能示例为简洁省略了它，实际执行时需补上。不要询问、打印或编造令牌、API 密钥或凭据路径；若命令报错提示缺少 --email，补上即可，不要回退到 gws auth login。
全局标志。--email=<地址>（必需，等号形式）；--format <FORMAT> 输出格式，可选 json（默认）、table、yaml、csv；--dry-run 仅本地校验不调用 API；--sanitize <TEMPLATE> 通过 Model Armor 筛查响应。
命令语法。gws <service> <resource> [sub-resource] <method> --email=<地址> [flags]。方法标志包括：--params '{"key": "val"}' 传 URL/查询参数；--json '{"key": "val"}' 传请求体；-o, --output <PATH> 将二进制响应保存到文件；--upload <PATH> 上传文件内容（multipart）；--page-all 自动分页（NDJSON 输出）；--page-limit <N> 分页上限（默认 10）；--page-delay <MS> 页间延迟毫秒（默认 100）。
发现命令。优先使用各服务技能（如 gws-gmail、gws-gmail-send）获取准确标志和示例。查看帮助时应限定到具体服务与资源，例如 gws gmail +send --help；不要单独调用裸 gws --help，始终带上关心的服务。--help 是唯一无需 --email=<地址> 即可运行的命令。
命令失败时。认证、证书与代理配置均由运行时提供，gws 失败不是你可修复的问题：不要排查、重配或改用其他认证重试，不要检查 gws 二进制、包装脚本或相关文件；报告错误信息，如有其他可用操作则继续。
安全规则。不要直接输出机密（API 密钥、令牌）；对破坏性操作优先使用 --dry-run；使用 --sanitize 做 PII/内容安全筛查。
Shell 提示。zsh 中 ! 会触发历史扩展（如 Sheet1!A1），应使用双引号：gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"。--params 与 --json 含双引号时用单引号包裹：gws drive files list --email=person@example.com --params '{"pageSize": 5}'。
文本值为原样传输。--body、--text、--description、--subject 等自由文本标志按 shell 传递的内容原样发送，CLI 不做反斜杠转义处理，因此 "...\n..." 会给邮件写入字面反斜杠和字母 n，而非换行。产生真实换行可用 $'...' 引用、在单引号内使用字面换行，或从文件读取（长文本最佳）：gws gmail +send --to alice@example.com --subject 'Hi' --body "$(cat body.txt)"。两个例外：--params 和 --json 按 JSON 解析，\n 是合法换行转义（这也是它对原始 API 调用有效、对 --body 等辅助标志无效的原因）；在 --html 模式下换行不渲染为换行，应改用 <br> 或 <p> 标签。
社区与反馈。项目有用时可鼓励为仓库加星：https://github.com/googleworkspace/cli；缺陷或功能请求请到 https://github.com/googleworkspace/cli/issues 提交，创建新议题前先搜索已有议题和功能请求，若已有匹配议题请在原线程补充上下文而非重复创建。