企业官网建设流程全解析

gws CLI 实战：用 Google Workspace 命令行一键创建 Gmail 自动过滤器（标签、星标与分类）

【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli

在gws（Google Workspace CLI）中，Gmail 的标签与过滤器操作被封装为动态生成的gws gmail users ...命令，无需手写任何 REST 请求即可完成"自动给入站邮件打标签、标星、归档"的完整工作流。本文将围绕官方 recipe recipe-create-gmail-filter 的四个核心步骤展开，结合仓库源码讲解--params/--json的用法、criteria与action字段的语义，以及命令底层"Discovery 动态构建 + Schema 本地校验"的实现原理。读完本文，你可以用纯命令行（或交给 AI Agent）在几十秒内创建一条可用的 Gmail 过滤规则。

前置准备：认证、gws 与技能加载

创建 Gmail 过滤器属于写操作，会修改收件箱行为，因此执行前需要完成两件事：

1. 安装并认证 gws：参考项目 README.md 安装二进制，然后执行gws auth setup（自动化创建 Cloud 项目并启用 API）或gws auth login（浏览器 OAuth 登录）。服务账号场景下设置GOOGLE_APPLICATION_CREDENTIALS环境变量即可（见 gws-shared 技能）。
2. 加载 gws-gmail 技能：本 recipe 在元数据中声明了前置依赖（requires.skills: gws-gmail）。该技能定义了 gmail 服务下的全部资源与命令面，详见 gws-gmail/SKILL.md；通用认证、全局标志与安全规则见 gws-shared/SKILL.md。

全流程速览

Shell 提示：--params与--json的值必须用单引号包裹，避免 shell 解析内层双引号（gws-shared/SKILL.md 明确给出了这一约定）。

步骤 1：列出已有标签，确定 LABEL_ID

gws gmail users labels list --params '{"userId": "me"}' --format table

• userId是 Gmail API 的路径参数，me表示当前认证用户；它是该方法的必需参数，缺失时命令会在本地直接报错（见下文"Schema 校验"部分）。
• --format table将返回的 JSON 数组渲染为对齐的文本表格。从源码看，formatter.rs 会从典型 Google API 列表响应{ "labels": [...] }中提取数组，并把嵌套对象扁平化为点号.路径形式的列名（flatten_object），因此你能直观看到每个标签的id与name。

这一步的核心产出是目标标签的id。Gmail 内置标准标签使用固定 ID（如INBOX、STARRED、TRASH、SPAM、IMPORTANT、CATEGORY_PERSONAL等），而用户自定义标签则由 API 分配形如Label_1234567890的 ID，这就是步骤 3 中LABEL_ID的取值来源。

步骤 2：创建新标签（可选但推荐）

如果已有标签满足需求可跳过本步，否则创建一个专用标签让过滤器"有处可归"：

gws gmail users labels create --params '{"userId": "me"}' --json '{"name": "Receipts"}'

• --json指定请求体，{"name": "Receipts"}是 GmailLabel资源的必填字段。
• 创建成功后，响应会返回该标签的id（即步骤 3 所需的LABEL_ID）与labelListVisibility/messageListVisibility等默认属性。
• 注意标签名需在账户内唯一；若重名，Gmail API 会返回冲突错误，此时直接复用步骤 1 查询到的既有标签 ID 即可。

步骤 3：创建过滤器——criteria 与 action 详解

这是本 recipe 的核心命令：

gws gmail users settings filters create --params '{"userId": "me"}' --json '{"criteria": {"from": "receipts@example.com"}, "action": {"addLabelIds": ["LABEL_ID"], "removeLabelIds": ["INBOX"]}}'

请求体由criteria（匹配条件）与action（触发动作）两部分组成，它们对应 Gmail APIFilter资源的定义（可用gws schema gmail.users.settings.filters查看当前 Discovery 文档中的完整字段清单）：

一个更"自动化"的变体：若想"打标签 + 标星"而不归档，可将 action 改为{"addLabelIds": ["LABEL_ID", "STARRED"]}；若想彻底归档（移出收件箱），保留"removeLabelIds": ["INBOX"]。注意LABEL_ID必须替换为步骤 1/2 得到的真实标签 ID，否则请求会被 Gmail API 拒绝。

步骤 4：验证过滤器是否生效

gws gmail users settings filters list --params '{"userId": "me"}' --format table

• 该命令列出当前账户全部过滤器，可确认新过滤器及其criteria/action已正确落库。
• 如需查看单条过滤器详情，可使用gws gmail users settings filters get --params '{"userId": "me", "id": "FILTER_ID"}'（FILTER_ID在 create 与 list 的响应中均可获得）。
• 验证行为是否符合预期，可配合gws gmail users messages list --params '{"userId": "me", "q": "from:receipts@example.com"}' --format table检查匹配到的邮件是否已被打上目标标签。

命令背后的实现原理

这四个命令并非硬编码，而是由gws在运行时动态构建的，理解这一点有助于排查问题：

1. Discovery 动态建面：gws不维护静态命令清单，而是从 Google Discovery Service 拉取 Gmail 的 REST 描述文档（RestDescription/RestMethod），在运行时生成users labels list、users settings filters create等完整命令面（见 README.md 与 schema.rs）。Google 侧新增方法后，gws会自动感知。
2. Schema 本地校验：在 executor.rs 的parse_and_validate_inputs中，--params与--json会被解析为 JSON，并对照 Discovery 文档做双重检查：必需参数缺失（如userId）立即报Validation错误；请求体还会validate_body_against_schema校验字段类型，做到"错误在发请求前暴露"。
3. 请求执行与鉴权：通过build_http_request附加 OAuth2 Bearer Token 与x-goog-user-project配额头，POST携带application/json请求体后发出。Gmail 模块的底层 HTTP 调用模式（带重试的send_with_retry、错误响应解析为GwsError::Api）可参考 helpers/gmail/mod.rs。
4. 输出格式化：响应经 formatter.rs 按--format（json默认、table、yaml、csv）渲染；列表型响应自动提取数据数组，因此--format table可以直接看到标签/过滤器的摘要。

进阶技巧与常见问题

• 用gws schema自查字段：动手前执行gws schema gmail.users.settings.filters.create可查看该方法的必需参数、请求体结构与默认值（gws-gmail/SKILL.md 推荐先 inspect 再调用）；gws gmail --help浏览全部资源。
• --dry-run预演：写操作前可加--dry-run在本地校验参数与请求体，不发真实 API 请求，避免误改线上配置（gws-shared/SKILL.md 的安全规则也建议破坏性操作优先 dry-run）。
• zsh 引号陷阱：若 JSON 中混入!等字符（如搜索查询），zsh 会将其当作历史展开，此时应改用双引号包裹并转义内层引号。
• AI Agent 场景：本 recipe 同时注册在 recipes.toml 的create-gmail-filter条目中（services = ["gmail"]），LLM 可读取该 recipe 后按步骤执行；仓库中另有 recipe-label-and-archive-emails 提供"搜索→打标→归档"的姊妹工作流，可组合使用。
• 清理过滤器：确认规则不再需要时，用gws gmail users settings filters delete --params '{"userId": "me", "id": "FILTER_ID"}'删除，并记得用--dry-run先行确认。

通过以上四步，你已经能用gws完成 Gmail 入站邮件的自动标签、标星与归档；结合gws schema的字段自查能力，还能轻松扩展到转发、取反查询等更复杂的过滤规则。

【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli