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在gwsGoogle Workspace CLI中Gmail 的标签与过滤器操作被封装为动态生成的gws gmail users ...命令无需手写任何 REST 请求即可完成自动给入站邮件打标签、标星、归档的完整工作流。本文将围绕官方 recipe recipe-create-gmail-filter 的四个核心步骤展开结合仓库源码讲解--params/--json的用法、criteria与action字段的语义以及命令底层Discovery 动态构建 Schema 本地校验的实现原理。读完本文你可以用纯命令行或交给 AI Agent在几十秒内创建一条可用的 Gmail 过滤规则。前置准备认证、gws 与技能加载创建 Gmail 过滤器属于写操作会修改收件箱行为因此执行前需要完成两件事安装并认证 gws参考项目 README.md 安装二进制然后执行gws auth setup自动化创建 Cloud 项目并启用 API或gws auth login浏览器 OAuth 登录。服务账号场景下设置GOOGLE_APPLICATION_CREDENTIALS环境变量即可见 gws-shared 技能。加载 gws-gmail 技能本 recipe 在元数据中声明了前置依赖requires.skills: gws-gmail。该技能定义了 gmail 服务下的全部资源与命令面详见 gws-gmail/SKILL.md通用认证、全局标志与安全规则见 gws-shared/SKILL.md。全流程速览步骤目的命令1列出已有标签gws gmail users labels list --params {userId: me} --format table2新建标签gws gmail users labels create --params {userId: me} --json {name: Receipts}3创建过滤器gws gmail users settings filters create --params {userId: me} --json {criteria: {from: receiptsexample.com}, action: {addLabelIds: [LABEL_ID], removeLabelIds: [INBOX]}}4验证过滤器gws gmail users settings filters list --params {userId: me} --format tableShell 提示--params与--json的值必须用单引号包裹避免 shell 解析内层双引号gws-shared/SKILL.md 明确给出了这一约定。步骤 1列出已有标签确定 LABEL_IDgws gmail users labels list --params {userId: me} --format tableuserId是 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: receiptsexample.com}, action: {addLabelIds: [LABEL_ID], removeLabelIds: [INBOX]}}请求体由criteria匹配条件与action触发动作两部分组成它们对应 Gmail APIFilter资源的定义可用gws schema gmail.users.settings.filters查看当前 Discovery 文档中的完整字段清单字段示例值说明criteria.fromreceiptsexample.com发件人地址匹配criteria.tomeexample.com收件人地址匹配criteria.subjectInvoice主题包含匹配criteria.queryhas:attachment与 Gmail 搜索语法一致的查询表达式criteria.negatedQuery-from:newsletter取反查询表达式action.addLabelIds[Label_123]命中后添加的标签 ID 列表可同时使用标准标签如STARRED实现自动标星action.removeLabelIds[INBOX]命中后移除的标签 ID 列表[INBOX]即归档/移出收件箱action.forwardforwardexample.com转发到指定地址需先配置转发地址action.startrue标星开关一个更自动化的变体若想打标签 标星而不归档可将 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:receiptsexample.com} --format table检查匹配到的邮件是否已被打上目标标签。命令背后的实现原理这四个命令并非硬编码而是由gws在运行时动态构建的理解这一点有助于排查问题Discovery 动态建面gws不维护静态命令清单而是从 Google Discovery Service 拉取 Gmail 的 REST 描述文档RestDescription/RestMethod在运行时生成users labels list、users settings filters create等完整命令面见 README.md 与 schema.rs。Google 侧新增方法后gws会自动感知。Schema 本地校验在 executor.rs 的parse_and_validate_inputs中--params与--json会被解析为 JSON并对照 Discovery 文档做双重检查必需参数缺失如userId立即报Validation错误请求体还会validate_body_against_schema校验字段类型做到错误在发请求前暴露。请求执行与鉴权通过build_http_request附加 OAuth2 Bearer Token 与x-goog-user-project配额头POST携带application/json请求体后发出。Gmail 模块的底层 HTTP 调用模式带重试的send_with_retry、错误响应解析为GwsError::Api可参考 helpers/gmail/mod.rs。输出格式化响应经 formatter.rs 按--formatjson默认、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gws CLI 实战：用 Google Workspace 命令行一键创建 Gmail 自动过滤器（标签、星标与分类）
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在gwsGoogle Workspace CLI中Gmail 的标签与过滤器操作被封装为动态生成的gws gmail users ...命令无需手写任何 REST 请求即可完成自动给入站邮件打标签、标星、归档的完整工作流。本文将围绕官方 recipe recipe-create-gmail-filter 的四个核心步骤展开结合仓库源码讲解--params/--json的用法、criteria与action字段的语义以及命令底层Discovery 动态构建 Schema 本地校验的实现原理。读完本文你可以用纯命令行或交给 AI Agent在几十秒内创建一条可用的 Gmail 过滤规则。前置准备认证、gws 与技能加载创建 Gmail 过滤器属于写操作会修改收件箱行为因此执行前需要完成两件事安装并认证 gws参考项目 README.md 安装二进制然后执行gws auth setup自动化创建 Cloud 项目并启用 API或gws auth login浏览器 OAuth 登录。服务账号场景下设置GOOGLE_APPLICATION_CREDENTIALS环境变量即可见 gws-shared 技能。加载 gws-gmail 技能本 recipe 在元数据中声明了前置依赖requires.skills: gws-gmail。该技能定义了 gmail 服务下的全部资源与命令面详见 gws-gmail/SKILL.md通用认证、全局标志与安全规则见 gws-shared/SKILL.md。全流程速览步骤目的命令1列出已有标签gws gmail users labels list --params {userId: me} --format table2新建标签gws gmail users labels create --params {userId: me} --json {name: Receipts}3创建过滤器gws gmail users settings filters create --params {userId: me} --json {criteria: {from: receiptsexample.com}, action: {addLabelIds: [LABEL_ID], removeLabelIds: [INBOX]}}4验证过滤器gws gmail users settings filters list --params {userId: me} --format tableShell 提示--params与--json的值必须用单引号包裹避免 shell 解析内层双引号gws-shared/SKILL.md 明确给出了这一约定。步骤 1列出已有标签确定 LABEL_IDgws gmail users labels list --params {userId: me} --format tableuserId是 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: receiptsexample.com}, action: {addLabelIds: [LABEL_ID], removeLabelIds: [INBOX]}}请求体由criteria匹配条件与action触发动作两部分组成它们对应 Gmail APIFilter资源的定义可用gws schema gmail.users.settings.filters查看当前 Discovery 文档中的完整字段清单字段示例值说明criteria.fromreceiptsexample.com发件人地址匹配criteria.tomeexample.com收件人地址匹配criteria.subjectInvoice主题包含匹配criteria.queryhas:attachment与 Gmail 搜索语法一致的查询表达式criteria.negatedQuery-from:newsletter取反查询表达式action.addLabelIds[Label_123]命中后添加的标签 ID 列表可同时使用标准标签如STARRED实现自动标星action.removeLabelIds[INBOX]命中后移除的标签 ID 列表[INBOX]即归档/移出收件箱action.forwardforwardexample.com转发到指定地址需先配置转发地址action.startrue标星开关一个更自动化的变体若想打标签 标星而不归档可将 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:receiptsexample.com} --format table检查匹配到的邮件是否已被打上目标标签。命令背后的实现原理这四个命令并非硬编码而是由gws在运行时动态构建的理解这一点有助于排查问题Discovery 动态建面gws不维护静态命令清单而是从 Google Discovery Service 拉取 Gmail 的 REST 描述文档RestDescription/RestMethod在运行时生成users labels list、users settings filters create等完整命令面见 README.md 与 schema.rs。Google 侧新增方法后gws会自动感知。Schema 本地校验在 executor.rs 的parse_and_validate_inputs中--params与--json会被解析为 JSON并对照 Discovery 文档做双重检查必需参数缺失如userId立即报Validation错误请求体还会validate_body_against_schema校验字段类型做到错误在发请求前暴露。请求执行与鉴权通过build_http_request附加 OAuth2 Bearer Token 与x-goog-user-project配额头POST携带application/json请求体后发出。Gmail 模块的底层 HTTP 调用模式带重试的send_with_retry、错误响应解析为GwsError::Api可参考 helpers/gmail/mod.rs。输出格式化响应经 formatter.rs 按--formatjson默认、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考