@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/productivity/airtable/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: airtable
+description: 通过 curl 使用 Airtable REST API。包含记录的 CRUD、过滤和 upsert 操作。
+version: 1.1.0
+author: community
+license: MIT
+platforms: [linux, macos, windows]
+prerequisites:
+  env_vars: [AIRTABLE_API_KEY]
+  commands: [curl]
+metadata:
+  hermes:
+    tags: [Airtable, Productivity, Database, API]
+    homepage: https://airtable.com/developers/web/api/introduction
+---
+
+# Airtable — Bases, Tables & Records
+
+使用 `terminal` 工具，通过 `curl` 直接操作 Airtable 的 REST API。无需 MCP 服务器，无需 OAuth 流程，也无需 Python SDK —— 只需要 `curl` 和一个个人访问令牌。
+
+## 前置条件
+
+1. 在 https://airtable.com/create/tokens 创建一个**个人访问令牌 (PAT)**（令牌以 `pat...` 开头）。
+2. 授予以下权限范围（最低要求）：
+   - `data.records:read` — 读取行
+   - `data.records:write` — 创建 / 更新 / 删除行
+   - `schema.bases:read` — 列出 bases 和 tables
+3. **重要提示：** 在同一个令牌界面中，将你想要访问的每个 base 添加到令牌的 **Access** 列表中。PAT 是按 base 划分作用域的 —— 错误 base 上的有效令牌会返回 `403`。
+4. 将令牌存储在 `${HERMES_HOME:-~/.hermes}/.env` 中（或通过 `hermes setup` 设置）：
+   ```
+   AIRTABLE_API_KEY=pat_your_token_here
+   ```
+
+> 注意：旧版 `key...` API 密钥已于 2024 年 2 月弃用。目前仅支持 PAT 和 OAuth 令牌。
+
+## API 基础
+
+- **Endpoint:** `https://api.airtable.com/v0`
+- **Auth header:** `Authorization: Bearer $AIRTABLE_API_KEY`
+- **所有请求**均使用 JSON（任何 POST/PATCH/PUT 请求体均需 `Content-Type: application/json`）。
+- **对象 ID：** bases 为 `app...`，tables 为 `tbl...`，records 为 `rec...`，fields 为 `fld...`。ID 永不改变，而名称可以更改。在自动化操作中首选使用 ID。
+- **速率限制：** 每个 base 5 次请求/秒。遇到 `429` → 退避重试。单个 base 上的突发请求将被限流。
+
+基础的 curl 模式：
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+`-s` 会抑制 curl 的进度条 —— 在每次调用时保持此设置，以便为 Hermes 保持工具输出的整洁。通过管道传递给 `python3 -m json.tool`（始终可用）或 `jq`（如果已安装）以获得可读性更好的 JSON。
+
+## Field Types (request body shapes)
+
+| Field type | Write shape |
+| --- | --- |
+| Single line text | `"Name": "hello"` |
+| Long text | `"Notes": "multi\nline"` |
+| Number | `"Score": 42` |
+| Checkbox | `"Done": true` |
+| Single select | `"Status": "Todo"` (除非设置了 `typecast: true`，否则名称必须已存在) |
+| Multi-select | `"Tags": ["urgent", "bug"]` |
+| Date | `"Due": "2026-04-01"` |
+| DateTime (UTC) | `"At": "2026-04-01T14:30:00.000Z"` |
+| URL / Email / Phone | `"Link": "https://…"` |
+| Attachment | `"Files": [{"url": "https://…"}]` (Airtable 会获取并重新托管) |
+| Linked record | `"Owner": ["recXXXXXXXXXXXXXX"]` (记录 ID 数组) |
+| User | `"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}` |
+
+在创建/更新请求体的顶层传入 `"typecast": true`，可让 Airtable 自动强制转换值（例如：动态创建新的下拉选项，或将 `"42"` 转换为 `42`）。
+
+## Common Queries
+
+### 列出令牌可见的 bases
+```bash
+curl -s "https://api.airtable.com/v0/meta/bases" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### 列出 base 中的 tables 和 schema
+```bash
+curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+在进行修改之前使用此命令 —— 它可以确认准确的字段名称和 ID，显示选择字段下的 `options.choices`，并展示 primary-field 的名称。
+
+### 列出记录（前 10 条）
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### 获取单个记录
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### 过滤记录
+Airtable 公式必须经过 URL 编码。让 Python 标准库来完成这项工作 —— 永远不要手动编码：
+```bash
+FORMULA="{Status}='Todo'"
+ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+常用的公式模式：
+- 精确匹配：`{Email}='user@example.com'`
+- 包含：`FIND('bug', LOWER({Title}))`
+- 多条件：`AND({Status}='Todo', {Priority}='High')`
+- 或：`OR({Owner}='alice', {Owner}='bob')`
+- 非空：`NOT({Assignee}='')`
+- 日期比较：`IS_AFTER({Due}, TODAY())`
+
+### 排序 + 选择特定字段
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+查询参数中的方括号必须进行 URL 编码（`%5B` / `%5D`）。
+
+### 使用命名视图
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+视图会在服务端应用其保存的过滤和排序规则。
+
+## Common Mutations
+
+### 创建记录
+```bash
+curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool
+```
+
+### 单次调用最多创建 10 条记录
+```bash
+curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "typecast": true,
+    "records": [
+      {"fields": {"Name": "Task A", "Status": "Todo"}},
+      {"fields": {"Name": "Task B", "Status": "In progress"}}
+    ]
+  }' | python3 -m json.tool
+```
+批量接口的上限是**每次请求 10 条记录**。如果需要插入更多数据，请分批进行（每批 10 条），并在中间稍作停顿，以遵守 5 次请求/秒/base 的速率限制。
+
+### 更新 a record (PATCH — merges, preserves unchanged fields)
+```bash
+curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool
+```
+
+### 通过合并字段进行 Upsert (无需 ID)
+```bash
+curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "performUpsert": {"fieldsToMergeOn": ["Email"]},
+    "records": [
+      {"fields": {"Email": "user@example.com", "Status": "Active"}}
+    ]
+  }' | python3 -m json.tool
+```
+对于合并字段值为新的记录，`performUpsert` 会创建它们；对于合并字段值已存在的记录，则会进行修补。非常适合用于幂等同步。
+
+### 删除记录
+```bash
+curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### 单次调用最多删除 10 条记录
+```bash
+curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+## Pagination
+
+列表接口每页最多返回 **100 条记录**。如果响应包含 `"offset": "..."`，请在下一次调用时将其传回。循环操作直到该字段不存在为止：
+
+```bash
+OFFSET=""
+while :; do
+  URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"
+  [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"
+  RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")
+  echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'
+  OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')
+  [ -z "$OFFSET" ] && break
+done
+```
+
+## Typical Hermes Workflow
+
+1. **验证授权。** `curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY"` — 预期返回 `200`。
+2. **查找 base。** 列出 bases（见上述步骤），或者如果令牌缺少 `schema.bases:read` 权限，直接向用户询问 `app...` ID。
+3. **检查 schema。** `GET /v0/meta/bases/$BASE_ID/tables` — 在进行任何修改操作之前，在本地会话中缓存准确的字段名称和 primary-field 名称。
+4. **先读后写。** 对于“在满足 Y 条件时更新 X”的需求，首先使用 `filterByFormula` 解析出 `rec...` ID，然后再使用 `PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID`。切勿猜测记录 ID。
+5. **批量写入。** 将相关的创建操作合并为一个包含 10 条记录的 POST 请求，以保持在 5 次请求/秒的预算范围内。
+6. **破坏性操作。** 删除操作无法通过 API撤销。如果用户说“删除所有 X”，请先回显过滤条件和记录数量，并在确认后再执行。
+
+## Pitfalls
+
+- **`filterByFormula` 必须进行 URL 编码。** 包含空格或非 ASCII 字符的字段名也需要编码（`{My Field}` → `%7BMy%20Field%7D`）。请使用 Python 标准库（如上方的模式）—— 切勿手动转义。
+- **响应中会省略空字段。** 缺少 `"Assignee"` 键并不意味着该字段不存在 —— 而是表示该记录的值为空。在断定字段缺失之前，请检查 schema（步骤 3）。
+- **PATCH 与 PUT 的区别。** `PATCH` 会将提供的字段合并到记录中。`PUT` 会完全替换记录，并清除任何未包含的字段。默认使用 `PATCH`。
+- **Single-select 选项必须存在。** 如果 `Shipping` 不在字段的选项列表中，写入 `"Status": "Shipping"` 时除非你传入了 `"typecast": true`（它会自动创建该选项），否则会报 `INVALID_MULTIPLE_CHOICE_OPTIONS` 错误。
+- **令牌作用域是按 base 划分的。** 如果在一个 base 上遇到 `403` 错误，而另一个 base 却能正常工作，这意味着令牌的 Access 列表未包含该 base —— 这不是作用域或授权问题。请引导用户前往 https://airtable.com/create/tokens 进行授权。
+- **速率限制是针对每个 base 的，而不是每个令牌。** 在 `baseA` 上 5 次请求/秒，且在 `baseB` 上 5 次请求/秒是没问题的；但仅在 `baseA` 上达到 6 次请求/秒就会触发限流。请监控 `429` 响应中的 `Retry-After` 标头。
+
+## Important Notes for Hermes
+
+- **始终通过 `terminal` 工具使用 `curl`。** 切勿使用 `web_extract`（无法发送 auth 标头）或 `browser_navigate`（需要 UI 授权且速度慢）。
+- **当此技能加载时，`AIRTABLE_API_KEY` 会从 `${HERMES_HOME:-~/.hermes}/.env` 自动流入子进程** —— 无需在每次 `curl` 调用前重新导出它。
+- **小心转义公式中的花括号。** 在 heredoc 请求体中，`{Status}` 是字面量。在 shell 参数中，只要不处于 `{...}` 花括号扩展上下文中，`{Status}` 就是安全的 —— 但在将动态字符串拼接到 URL 之前，请务必通过 `python3 urllib.parse.quote` 进行处理。
+- **使用 `python3 -m json.tool` 进行格式化美化输出**（始终可用），而不是 `jq`（可选）。只有在你需要进行过滤/投影时才使用 `jq`。
+- **分页是针对当前页的，而非全局的。** Airtable 的 100 条记录上限是硬性限制；没有办法提高它。请使用 `offset` 循环直到该字段消失。
+- **在非 2xx 响应中阅读 `errors` 数组** —— Airtable 会返回结构化的错误代码，如 `AUTHENTICATION_REQUIRED`、`INVALID_PERMISSIONS`、`MODEL_ID_NOT_FOUND`、`INVALID_MULTIPLE_CHOICE_OPTIONS`，它们能准确告诉你问题所在。

package/extensions/skills/builtin/productivity/google-workspace/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: google-workspace
+description: "通过 gws CLI 或 Python 使用 Gmail、Calendar、Drive、Docs、Sheets。"
+version: 1.1.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+required_credential_files:
+  - path: google_token.json
+    description: Google OAuth2 token（由设置脚本创建）
+  - path: google_client_secret.json
+    description: Google OAuth2 客户端凭证（从 Google Cloud Console 下载）
+metadata:
+  hermes:
+    tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]
+    homepage: https://github.com/NousResearch/hermes-agent
+    related_skills: [himalaya]
+---
+
+# Google Workspace
+
+Gmail、Calendar、Drive、Contacts、Sheets 和 Docs —— 通过 Hermes 管理的 OAuth 和一个轻量级的 CLI 封装实现。当安装了 `gws` 时，该 skill 会将其作为执行后端，以覆盖更广泛的 Google Workspace 功能；否则，它将回退到内置的 Python 客户端实现。
+
+## 参考资源
+
+- `references/gmail-search-syntax.md` — Gmail 搜索操作符（is:unread, from:, newer_than: 等）
+
+## 脚本
+
+- `scripts/setup.py` — OAuth2 设置（运行一次以进行授权）
+- `scripts/google_api.py` — 兼容性封装 CLI。在可用时，它会优先使用 `gws` 进行操作，同时保持 Hermes 现有的 JSON 输出契约。
+
+## 首次配置
+
+设置过程完全无需交互——你逐步引导它，使其可以在 CLI、Telegram、Discord 或任何平台上运行。
+
+首先定义一个简写：
+
+```bash
+GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
+```
+
+### 第 0 步：检查是否已设置
+
+```bash
+$GSETUP --check
+```
+
+如果输出 `AUTHENTICATED`，请直接跳转到 用法 —— 设置已完成。
+
+### 第 1 步：评估 —— 询问用户的需求
+
+在开始 OAuth 设置之前，向用户提出两个问题：
+
+**问题 1：“你需要哪些 Google 服务？只需要电子邮件，还是也需要 Calendar/Drive/Sheets/Docs？”**
+
+- **仅需电子邮件** → 他们根本不需要这个 skill。请改用 `himalaya` skill —— 它可以使用 Gmail App Password（Settings → 安全 → App Passwords）工作，只需 2 分钟即可完成设置。不需要 Google Cloud 项目。加载 himalaya skill 并按照其设置说明进行操作。
+
+- **电子邮件 + Calendar** → 继续使用此 skill，但在授权期间请使用 `--services email,calendar`，以便同意屏幕仅请求他们实际需要的 scope。
+
+- **仅 Calendar/Drive/Sheets/Docs** → 继续使用此 skill，并使用更窄的 `--services` 集合，例如 `calendar,drive,sheets,docs`。
+
+- **完整的 Workspace 访问权限** → 继续使用此 skill，并使用默认的 `all` 服务集。
+
+**问题 2：“你的 Google 账户是否使用了高级保护（登录时需要硬件安全密钥）？如果你不确定，那你很可能没有使用——这是你需要显式注册的服务。”**
+
+- **否 / 不确定** → 正常设置。在下面继续。
+- **是** → 他们的 Workspace 管理员必须先将 OAuth client ID 添加到组织的允许应用列表中，第 4 步才能正常工作。请提前告知他们这一点。
+
+### 第 2 步：创建 OAuth 凭证（一次性，约 5 分钟）
+
+告诉用户：
+
+> 你需要一个 Google Cloud OAuth client。这是一次性设置：
+>
+> 1. 创建或选择一个项目：
+>    https://console.cloud.google.com/projectselector2/home/dashboard
+> 2. 从 API Library 启用所需的 API：
+>    https://console.cloud.google.com/apis/library
+>    启用：Gmail API、Google Calendar API、Google Drive API、
+>    Google Sheets API、Google Docs API、People API
+> 3. 在此处创建 OAuth client：
+>    https://console.cloud.google.com/apis/credentials
+>    Credentials → Create Credentials → OAuth 2.0 Client ID
+> 4. Application type: "Desktop app" → Create
+> 5. 如果应用仍处于 Testing 状态，请在此处将用户的 Google 账户添加为 test user：
+>    https://console.cloud.google.com/auth/audience
+>    Audience → Test users → Add users
+> 6. 下载 JSON 文件并告诉我文件路径
+>
+> 重要的 Hermes CLI 注意事项：如果文件路径以 `/` 开头，请不要在 CLI 中仅将纯路径作为单独的消息发送，因为它可能会被误认为是斜杠命令。请将其放在句子中发送，例如：
+> `The JSON file path is: /home/user/Downloads/client_secret_....json`
+
+一旦他们提供了路径：
+
+```bash
+$GSETUP --client-secret /path/to/client_secret.json
+```
+
+如果他们粘贴的是原始的 client ID / client secret 值，而不是文件路径，
+请你自己为他们编写一个有效的 Desktop OAuth JSON 文件，将其保存到一个明确的位置（例如 `~/Downloads/hermes-google-client-secret.json`），然后对该文件运行 `--client-secret`。
+
+### 第 3 步：获取授权 URL
+
+使用在第 1 步中选择的服务集。示例：
+
+```bash
+$GSETUP --auth-url --services email,calendar --format json
+$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
+$GSETUP --auth-url --services all --format json
+```
+
+这会返回包含 `auth_url` 字段的 JSON，并将确切的 URL 保存到 `~/.hermes/google_oauth_last_url.txt`。
+
+此步骤的 Agent 规则：
+- 提取 `auth_url` 字段，并将该确切的 URL 作为单行发送给用户。
+- 告诉用户浏览器在批准后可能会在 `http://localhost:1` 上失败，这是预期行为。
+- 告诉他们从浏览器地址栏中复制整个重定向后的 URL。
+- 如果用户收到 `Error 403: access_denied`，请直接将他们引导至 `https://console.cloud.google.com/auth/audience`，将自己添加为 test user。
+
+### 第 4 步：交换 code
+
+用户将粘贴回一个类似 `http://localhost:1/?code=4/0A...&scope=...` 的 URL，或者仅仅是 code 字符串。两者都可以。`--auth-url` 步骤会在本地存储一个临时的待处理 OAuth 会话，因此 `--auth-code` 稍后可以完成 PKCE 交换，即使在无头系统上也是如此：
+
+```bash
+$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
+```
+
+如果 `--auth-code` 因为 code 过期、已被使用或来自旧的浏览器选项卡而失败，它现在会返回一个新的 `fresh_auth_url`。在这种情况下，请立即将新的 URL 发送给用户，并让他们仅使用最新的浏览器重定向重试。
+
+### 第 5 步：验证
+
+```bash
+$GSETUP --check
+```
+
+应该输出 `AUTHENTICATED`。配置已完成 —— 从现在起 token 会自动刷新。
+
+### 说明
+
+- Token 存储在 `~/.hermes/google_token.json` 中并自动刷新。
+- 待处理的 OAuth 会话状态/验证器会临时存储在 `~/.hermes/google_oauth_pending.json` 中，直到交换完成。
+- 如果安装了 `gws`，`google_api.py` 会将其指向同一个 `~/.hermes/google_token.json` 凭证文件。用户不需要运行单独的 `gws auth login` 流程。
+- 要撤销访问权限：`$GSETUP --revoke`
+
+## 用法
+
+所有命令都通过 API 脚本执行。将 `GAPI` 设置为简写：
+
+```bash
+GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
+```
+
+### Gmail
+
+```bash
+# 搜索（返回包含 id, from, subject, date, snippet 的 JSON 数组）
+$GAPI gmail search "is:unread" --max 10
+$GAPI gmail search "from:boss@company.com newer_than:1d"
+$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
+
+# 读取完整邮件（返回包含正文文本的 JSON）
+$GAPI gmail get MESSAGE_ID
+
+# 发送
+$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
+$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
+$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"
+
+# 回复（自动加入会话并设置 In-Reply-To）
+$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
+$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"
+
+# 标签
+$GAPI gmail labels
+$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
+$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
+```
+
+### Calendar
+
+```bash
+# 列出事件（默认为未来 7 天）
+$GAPI calendar list
+$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
+
+# 创建事件（要求使用带时区的 ISO 8601 格式）
+$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
+$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
+$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"
+
+# 删除事件
+$GAPI calendar delete EVENT_ID
+```
+
+### Drive
+
+```bash
+# 搜索现有文件
+$GAPI drive search "quarterly report" --max 10
+$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
+
+# 获取单个文件的元数据
+$GAPI drive get FILE_ID
+
+# 上传本地文件（自动检测 MIME 类型）
+$GAPI drive upload /path/to/report.pdf
+$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID
+
+# 下载（二进制文件按原样下载；Google 原生文件导出为
+# 合理的默认格式 —— Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png）
+$GAPI drive download FILE_ID
+$GAPI drive download DOC_ID --output ~/doc.pdf
+$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt
+
+# 创建文件夹
+$GAPI drive create-folder "Reports"
+$GAPI drive create-folder "Q4" --parent FOLDER_ID
+
+# 共享
+$GAPI drive share FILE_ID --email alice@example.com --role reader
+$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
+$GAPI drive share FILE_ID --type anyone --role reader        # 拥有链接的任何人
+$GAPI drive share FILE_ID --type domain --domain example.com --role reader
+
+# 删除 —— 默认移至回收站（可逆）。使用 --permanent 跳过回收站。
+$GAPI drive delete FILE_ID
+$GAPI drive delete FILE_ID --permanent
+```
+
+### Contacts
+
+```bash
+$GAPI contacts list --max 20
+```
+
+### Sheets
+
+```bash
+# 创建新电子表格
+$GAPI sheets create --title "Q4 Budget"
+$GAPI sheets create --title "Inventory" --sheet-name "Stock"
+
+# 读取
+$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
+
+# 写入
+$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
+
+# 追加行
+$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
+```
+
+### Docs
+
+```bash
+# 读取
+$GAPI docs get DOC_ID
+
+# 创建新 Doc（可选择使用正文文本作为初始内容）
+$GAPI docs create --title "Meeting Notes"
+$GAPI docs create --title "Draft" --body "First paragraph..."
+
+# 将文本追加到现有 Doc 的末尾
+$GAPI docs append DOC_ID --text "Additional content to append"
+```
+
+## 输出格式
+
+所有命令均返回 JSON。请使用 `jq` 解析或直接读取。关键字段：
+
+- **Gmail search**: `[{id, threadId, from, to, subject, date, snippet, labels}]`
+- **Gmail get**: `{id, threadId, from, to, subject, date, labels, body}`
+- **Gmail send/reply**: `{status: "sent", id, threadId}`
+- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
+- **Calendar create**: `{status: "created", id, summary, htmlLink}`
+- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
+- **Drive get**: `{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}`
+- **Drive upload**: `{status: "uploaded", id, name, mimeType, webViewLink}`
+- **Drive download**: `{status: "downloaded", id, name, path, mimeType}`
+- **Drive create-folder**: `{status: "created", id, name, webViewLink}`
+- **Drive share**: `{status: "shared", permissionId, fileId, role, type}`
+- **Drive delete**: `{status: "trashed" | "deleted", fileId, permanent}`
+- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
+- **Sheets get**: `[[cell, cell, ...], ...]`
+- **Sheets create**: `{status: "created", spreadsheetId, title, spreadsheetUrl}`
+- **Docs create**: `{status: "created", documentId, title, url}`
+- **Docs append**: `{status: "appended", documentId, inserted_at, characters}`
+
+## 规则
+
+1. **未经用户事先确认，绝不发送电子邮件、创建/删除日历事件、删除 Drive 文件、共享文件或修改 Docs/Sheets。** 展示将要执行的操作（收件人、文件 ID、内容、共享角色）并请求批准。对于 `drive delete`，优先使用默认的回收站（可逆）而不是 `--permanent`。
+2. **首次使用前检查授权** —— 运行 `setup.py --check`。如果失败，请引导用户完成设置。
+3. **对于复杂查询，请使用 Gmail 搜索语法参考** —— 使用 `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")` 加载它。
+4. **Calendar 时间必须包含时区** —— 始终使用带偏移量的 ISO 8601（例如，`2026-03-01T10:00:00-06:00`）或 UTC（`Z`）。
+5. **遵守速率限制** —— 避免快速连续的 API 调用。尽可能进行批量读取。
+
+## 故障排查
+
+| 问题 | 解决方法 |
+|---------|-----|
+| `NOT_AUTHENTICATED` | 运行上述设置的第 2-5 步 |
+| `REFRESH_FAILED` | Token 已撤销或过期 —— 重新执行第 3-5 步 |
+| `HttpError 403: Insufficient Permission` | 缺少 API scope —— `$GSETUP --revoke` 然后重新执行第 3-5 步 |
+| `AUTHENTICATED (partial)` 或 "Token missing scopes" | 新的写入功能（Drive 写入/删除、Docs 创建/编辑）需要重新授权。`$GSETUP --revoke` 然后重新执行第 3-5 步以授予升级后的 scope。 |
+| `HttpError 403: Access Not Configured` | API 未启用 —— 用户需要在 Google Cloud Console 中启用它 |
+| `ModuleNotFoundError` | 运行 `$GSETUP --install-deps` |
+| 高级保护阻止授权 | Workspace 管理员必须将 OAuth client ID 加入白名单 |
+
+## 撤销访问权限
+
+```bash
+$GSETUP --revoke
+```

package/extensions/skills/builtin/productivity/google-workspace/references/gmail-search-syntax.md

@@ -0,0 +1,63 @@
+# Gmail 搜索语法
+
+标准的 Gmail 搜索运算符可在 `query` 参数中使用。
+
+## 常用运算符
+
+| 运算符 | 示例 | 说明 |
+| ---------- | --------- | ------------- |
+| `is:unread` | `is:unread` | 未读邮件 |
+| `is:starred` | `is:starred` | 已加星标邮件 |
+| `is:important` | `is:important` | 重要邮件 |
+| `in:inbox` | `in:inbox` | 仅限收件箱 |
+| `in:sent` | `in:sent` | 已发送文件夹 |
+| `in:drafts` | `in:drafts` | 草稿 |
+| `in:trash` | `in:trash` | 已删除邮件 |
+| `in:anywhere` | `in:anywhere` | 所有邮件（包括垃圾邮件/已删除邮件） |
+| `from:` | `from:alice@example.com` | 发件人 |
+| `to:` | `to:bob@example.com` | 收件人 |
+| `cc:` | `cc:team@example.com` | 抄送收件人 |
+| `subject:` | `subject:invoice` | 主题包含 |
+| `label:` | `label:work` | 具有标签 |
+| `has:attachment` | `has:attachment` | 包含附件 |
+| `filename:` | `filename:pdf` | 附件文件名/类型 |
+| `larger:` | `larger:5M` | 大于指定大小 |
+| `smaller:` | `smaller:1M` | 小于指定大小 |
+
+## 日期运算符
+
+| 运算符 | 示例 | 说明 |
+| ---------- | --------- | ------------- |
+| `newer_than:` | `newer_than:7d` | 最近 N 天 (d)、月 (m) 或年 (y) 内 |
+| `older_than:` | `older_than:30d` | 超过 N 天/月/年 |
+| `after:` | `after:2026/02/01` | 指定日期之后 (YYYY/MM/DD) |
+| `before:` | `before:2026/03/01` | 指定日期之前 |
+
+## 组合搜索
+
+| 语法 | 示例 | 说明 |
+| -------- | --------- | ------------- |
+| 空格 | `from:alice subject:meeting` | 与（隐式） |
+| `OR` | `from:alice OR from:bob` | 或 |
+| `-` | `-from:noreply@` | 非（排除） |
+| `()` | `(from:alice OR from:bob) subject:meeting` | 分组 |
+| `""` | `"exact phrase"` | 精确短语匹配 |
+
+## 常用模式
+
+```
+# Unread emails from the last day
+is:unread newer_than:1d
+
+# Emails with PDF attachments from a specific sender
+from:accounting@company.com has:attachment filename:pdf
+
+# Important unread emails (not promotions/social)
+is:unread -category:promotions -category:social
+
+# Emails in a thread about a topic
+subject:"Q4 budget" newer_than:30d
+
+# Large attachments to clean up
+has:attachment larger:10M older_than:90d
+```

package/extensions/skills/builtin/productivity/google-workspace/scripts/_hermes_home.py

@@ -0,0 +1,42 @@
+"""Resolve HERMES_HOME for standalone skill scripts.
+
+Skill scripts may run outside the Hermes process (e.g. system Python,
+nix env, CI) where ``hermes_constants`` is not importable.  This module
+provides the same ``get_hermes_home()`` and ``display_hermes_home()``
+contracts as ``hermes_constants`` without requiring it on ``sys.path``.
+
+When ``hermes_constants`` IS available it is used directly so that any
+future enhancements (profile resolution, Docker detection, etc.) are
+picked up automatically.  The fallback path replicates the core logic
+from ``hermes_constants.py`` using only the stdlib.
+
+All scripts under ``google-workspace/scripts/`` should import from here
+instead of duplicating the ``HERMES_HOME = Path(os.getenv(...))`` pattern.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+try:
+    from hermes_constants import display_hermes_home as display_hermes_home
+    from hermes_constants import get_hermes_home as get_hermes_home
+except (ModuleNotFoundError, ImportError):
+
+    def get_hermes_home() -> Path:
+        """Return the Hermes home directory (default: ~/.hermes).
+
+        Mirrors ``hermes_constants.get_hermes_home()``."""
+        val = os.environ.get("HERMES_HOME", "").strip()
+        return Path(val) if val else Path.home() / ".hermes"
+
+    def display_hermes_home() -> str:
+        """Return a user-friendly ``~/``-shortened display string.
+
+        Mirrors ``hermes_constants.display_hermes_home()``."""
+        home = get_hermes_home()
+        try:
+            return "~/" + str(home.relative_to(Path.home()))
+        except ValueError:
+            return str(home)