gmail

Gmail 搜索技能

通过 Gmail API 搜索和获取邮件，支持灵活的查询选项和输出格式。

前提条件

必须在 ~/.gmail_credentials/ 中配置凭据。运行 setup 检查状态：

python3 scripts/gmail_search.py setup

获取 Gmail API 凭据

1. 创建 Google Cloud 项目

1. 前往 console.cloud.google.com
2. 点击项目下拉菜单 ->“新建项目”
3. 为项目命名（例如，“Gmail Agent Skill”）-> 创建

2. 启用 Gmail API

1. 前往“API 和服务” ->“库”
2. 搜索“Gmail API”
3. 点击该项并按“启用”

3. 配置 OAuth 同意屏幕

1. 前往“Oauth 同意屏幕”（左侧边栏）
2. 选择“外部”用户类型
3. 填写必填字段：
   • 应用名称：Gmail Agent Skill
   • 用户支持邮箱：你的邮箱
   • 开发者邮箱：你的邮箱
4. 点击“保存并继续”，跳过 Scopes
5. 在“测试用户”页面添加你的 Gmail 地址
6. 完成所有步骤

4. 发布测试应用

**重要：**不执行此步骤会导致出现“Error 403: access_denied”。

1. 返回“Oauth 同意屏幕”
2. 在“发布状态”下，点击“发布应用”
3. 确认对话框

这样应用仍处于测试模式（而非正式环境），但测试用户可以进行身份验证。登录时会看到“未经验证的应用”警告——点击“高级” ->“前往 Gmail Agent Skill（不安全）”继续。

**注意：**测试令牌会在 7 天后过期。正式环境需要通过 Google 验证。

5. 创建 OAuth 凭据

1. 前往“凭据”（左侧边栏）
2. 点击“创建凭据” ->“OAuth 客户端 ID”
3. 选择“桌面应用”作为应用类型
4. 为其命名（例如，“Gmail Agent Client”）
5. 点击“创建”

6. 获取凭据

1. 页面会显示客户端 ID——复制它
2. 客户端密钥：点击下载图标或查看详情以获取密钥

7. 保存凭据

创建 ~/.gmail_credentials/credentials.json：

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

8. 进行身份验证

python3 scripts/gmail_search.py auth

这会打开浏览器。点击“未经验证的应用”警告中的选项（“高级” ->“前往 Gmail Agent Skill”），批准访问，即可开始使用。

快速开始

# Check setup status
python3 scripts/gmail_search.py setup

# Authenticate (opens browser)
python3 scripts/gmail_search.py auth

# Search emails
python3 scripts/gmail_search.py search "meeting notes"

# Search with filters
python3 scripts/gmail_search.py search --from "[email protected]" --unread

命令

设置

检查配置状态：

python3 scripts/gmail_search.py setup
python3 scripts/gmail_search.py setup --json

身份验证

通过 Gmail 进行身份验证（会打开浏览器进行 OAuth）：

python3 scripts/gmail_search.py auth

权限范围

查看或更改 API 权限范围：

# View current scope
python3 scripts/gmail_search.py scope

# Change scope (requires re-auth)
python3 scripts/gmail_search.py scope --set readonly
python3 scripts/gmail_search.py scope --set modify
python3 scripts/gmail_search.py scope --set full

可用范围：

• readonly - 仅阅读邮件（默认，推荐）
• modify - 阅读并修改标签、标记已读/未读
• full - 完全访问权限，包括删除

搜索

使用自由文本查询或筛选条件搜索邮件：

# Free-text search (uses Gmail search syntax)
python3 scripts/gmail_search.py search "project deadline"
python3 scripts/gmail_search.py search "from:[email protected] subject:invoice"

# Using helper flags
python3 scripts/gmail_search.py search --from "[email protected]"
python3 scripts/gmail_search.py search --to "[email protected]"
python3 scripts/gmail_search.py search --subject "Weekly Report"
python3 scripts/gmail_search.py search --label "INBOX"
python3 scripts/gmail_search.py search --label "work"

# Date filters (YYYY/MM/DD format)
python3 scripts/gmail_search.py search --after 2024/01/01
python3 scripts/gmail_search.py search --before 2024/12/31
python3 scripts/gmail_search.py search --after 2024/01/01 --before 2024/06/30

# Status filters
python3 scripts/gmail_search.py search --unread
python3 scripts/gmail_search.py search --starred
python3 scripts/gmail_search.py search --has-attachment

# Combined filters
python3 scripts/gmail_search.py search "invoice" --from "billing@" --has-attachment --after 2024/01/01

# Limit results
python3 scripts/gmail_search.py search "meeting" --limit 50

# Include full body (default shows snippet only)
python3 scripts/gmail_search.py search "contract" --full

# Include attachment info
python3 scripts/gmail_search.py search --has-attachment --attachments

# JSON output
python3 scripts/gmail_search.py search "project" --json

下载附件

从指定邮件中下载附件：

# Download to default location (~/Downloads/gmail_attachments/)
python3 scripts/gmail_search.py download MESSAGE_ID

# Download to custom directory
python3 scripts/gmail_search.py download MESSAGE_ID --output /path/to/folder

# JSON output
python3 scripts/gmail_search.py download MESSAGE_ID --json

从搜索结果中获取邮件 ID（会显示在输出中）。

标签

列出所有可用的 Gmail 标签：

python3 scripts/gmail_search.py labels
python3 scripts/gmail_search.py labels --json

输出格式

Markdown（默认）

# Gmail Search Results (3 messages)

## Weekly Report
**From:** [email protected]
**To:** [email protected]
**Date:** Mon, 25 Nov 2024 10:00:00 +0000
**ID:** `18abc123def`

> Here's the weekly report summary...

---

JSON

添加 --json 标志以获取结构化输出：

[
  {
    "id": "18abc123def",
    "thread_id": "18abc123def",
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Weekly Report",
    "date": "Mon, 25 Nov 2024 10:00:00 +0000",
    "snippet": "Here's the weekly report summary...",
    "labels": ["INBOX", "UNREAD"]
  }
]

Gmail 搜索语法

此技能支持在自由文本查询中使用 Gmail 原生搜索语法：

运算符	示例	说明
from:	from:[email protected]	来自特定发件人
to:	to:[email protected]	发给特定收件人
subject:	subject:meeting	主题中包含
label:	label:work	带有特定标签
has:attachment	has:attachment	有附件
filename:	filename:pdf	附件文件名
is:unread	is:unread	未读邮件
is:starred	is:starred	已加星标邮件
after:	after:2024/01/01	指定日期之后
before:	before:2024/12/31	指定日期之前
newer_than:	newer_than:7d	最近 N 天内
older_than:	older_than:1m	超过 N 个月
in:	in:inbox	位于指定文件夹中
OR	from:john OR from:jane	满足任一条件
-	-label:spam	排除
""	"exact phrase"	精确匹配

用户请求示例

用户说	命令
“在 Gmail 中搜索会议记录”	search "meeting notes"
“查找 John 发来的邮件”	search --from "john"
“显示未读邮件”	search --unread
“查找上个月关于项目的邮件”	search "project" --after 2024/10/01
“查找带附件的发票”	search "invoice" --has-attachment
“阅读全文中关于合同的邮件”	search "contract" --full --limit 1
“下载那封邮件中的附件”	download MESSAGE_ID
“我有哪些标签？”	labels
“查找老板发来的已加星标邮件”	search --from "boss" --starred
“Gmail 是否已配置？”	setup

依赖项

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

文件

• ~/.gmail_credentials/credentials.json - OAuth 客户端凭据
• ~/.gmail_credentials/token.pickle - 缓存的身份验证令牌
• ~/.gmail_credentials/scope.txt - 当前的作用域设置