better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/note-taking/note-taking-obsidian.md

@@ -0,0 +1,81 @@
+---
+title: "Obsidian — 在 Obsidian 知识库中读取、搜索、创建和编辑笔记"
+sidebar_label: "Obsidian"
+description: "在 Obsidian 知识库中读取、搜索、创建和编辑笔记"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Obsidian
+
+在 Obsidian 知识库中读取、搜索、创建和编辑笔记。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/note-taking/obsidian` |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Obsidian 知识库
+
+将此 skill 用于以文件系统为核心的 Obsidian 知识库操作：读取笔记、列出笔记、搜索笔记文件、创建笔记、追加内容以及添加 wikilink。
+
+## 知识库路径
+
+在调用文件工具之前，先确定已知或已解析的知识库路径。
+
+知识库路径的约定文档为 `OBSIDIAN_VAULT_PATH` 环境变量，例如来自 `~/.hermes/.env`。若未设置，则使用 `~/Documents/Obsidian Vault`。
+
+文件工具不会展开 shell 变量。不要将包含 `$OBSIDIAN_VAULT_PATH` 的路径传递给 `read_file`、`write_file`、`patch` 或 `search_files`；应先解析知识库路径，再传入具体的绝对路径。知识库路径可能包含空格，这也是优先使用文件工具而非 shell 命令的另一个原因。
+
+若知识库路径未知，可使用 `terminal` 解析 `OBSIDIAN_VAULT_PATH` 或检查备用路径是否存在。一旦路径确定，切换回文件工具。
+
+## 读取笔记
+
+使用 `read_file` 并传入笔记的已解析绝对路径。优先使用此方式而非 `cat`，因为它提供行号和分页功能。
+
+## 列出笔记
+
+使用 `search_files`，将 `target` 设为 `"files"` 并传入已解析的知识库路径。优先使用此方式而非 `find` 或 `ls`。
+
+- 若要列出所有 markdown 笔记，在知识库路径下使用 `pattern: "*.md"`。
+- 若要列出子文件夹，在该子文件夹的绝对路径下进行搜索。
+
+## 搜索
+
+使用 `search_files` 进行文件名和内容搜索。优先使用此方式而非 `grep`、`find` 或 `ls`。
+
+- 搜索文件名时，使用 `search_files`，将 `target` 设为 `"files"` 并指定文件名 `pattern`。
+- 搜索笔记内容时，使用 `search_files`，将 `target` 设为 `"content"`，将内容正则表达式作为 `pattern`，并在需要将匹配限制为 markdown 笔记时设置 `file_glob: "*.md"`。
+
+## 创建笔记
+
+使用 `write_file` 并传入已解析的绝对路径和完整 markdown 内容。优先使用此方式而非 shell heredoc 或 `echo`，因为它可避免 shell 引号问题并返回结构化结果。
+
+## 追加内容到笔记
+
+在操作不复杂的情况下，优先使用原生文件工具工作流：
+
+- 使用 `read_file` 读取目标笔记。
+- 当存在稳定的上下文时（例如在现有标题后添加章节或在已知尾部块之前追加），使用 `patch` 进行锚定追加。
+- 当重写整个笔记比构造脆弱的 patch 更清晰时，使用 `write_file`。
+
+使用 `patch` 进行锚定追加时，将锚点替换为锚点加新内容。
+
+若无稳定上下文的简单追加，且 `terminal` 是最清晰安全的选项，则可接受使用 `terminal`。
+
+## 定向编辑
+
+当现有内容提供稳定上下文时，使用 `patch` 进行笔记的局部修改。优先使用此方式而非 shell 文本重写。
+
+## Wikilink
+
+Obsidian 使用 `[[Note Name]]` 语法链接笔记。创建笔记时，使用这种语法链接相关内容。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/productivity/productivity-airtable.md

@@ -0,0 +1,243 @@
+---
+title: "Airtable — 通过 curl 调用 Airtable REST API"
+sidebar_label: "Airtable"
+description: "通过 curl 调用 Airtable REST API"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Airtable
+
+通过 curl 调用 Airtable REST API。支持记录的增删改查、过滤和 upsert 操作。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/productivity/airtable` |
+| 版本 | `1.1.0` |
+| 作者 | community |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Airtable`, `Productivity`, `Database`, `API` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Airtable — Bases、Tables 与 Records
+
+通过 `terminal` 工具，使用 `curl` 直接调用 Airtable 的 REST API。无需 MCP server，无需 OAuth 流程，无需 Python SDK——只需 `curl` 和一个个人访问令牌（PAT）。
+
+## 前置条件
+
+1. 在 https://airtable.com/create/tokens 创建一个**个人访问令牌（PAT）**（令牌以 `pat...` 开头）。
+2. 授予以下权限范围（最低要求）：
+   - `data.records:read` — 读取行
+   - `data.records:write` — 创建 / 更新 / 删除行
+   - `schema.bases:read` — 列出 bases 和 tables
+3. **重要：** 在同一令牌 UI 中，将你需要访问的每个 base 添加到令牌的 **Access** 列表中。PAT 是按 base 划定范围的——有效令牌若未授权对应 base 会返回 `403`。
+4. 将令牌存储在 `~/.hermes/.env` 中（或通过 `hermes setup` 配置）：
+   ```
+   AIRTABLE_API_KEY=pat_your_token_here
+   ```
+
+> 注意：旧版 `key...` API 密钥已于 2024 年 2 月弃用。目前仅支持 PAT 和 OAuth 令牌。
+
+## API 基础
+
+- **端点：** `https://api.airtable.com/v0`
+- **认证头：** `Authorization: Bearer $AIRTABLE_API_KEY`
+- **所有请求** 使用 JSON（POST/PATCH/PUT 请求体需设置 `Content-Type: application/json`）。
+- **对象 ID：** base 为 `app...`，table 为 `tbl...`，record 为 `rec...`，field 为 `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。
+
+## 字段类型（请求体格式）
+
+| 字段类型 | 写入格式 |
+|---|---|
+| 单行文本 | `"Name": "hello"` |
+| 长文本 | `"Notes": "multi\nline"` |
+| 数字 | `"Score": 42` |
+| 复选框 | `"Done": true` |
+| 单选 | `"Status": "Todo"`（选项名必须已存在，除非设置 `typecast: true`） |
+| 多选 | `"Tags": ["urgent", "bug"]` |
+| 日期 | `"Due": "2026-04-01"` |
+| 日期时间（UTC） | `"At": "2026-04-01T14:30:00.000Z"` |
+| URL / 邮箱 / 电话 | `"Link": "https://…"` |
+| 附件 | `"Files": [{"url": "https://…"}]`（Airtable 会抓取并重新托管） |
+| 关联记录 | `"Owner": ["recXXXXXXXXXXXXXX"]`（record ID 数组） |
+| 用户 | `"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}` |
+
+在创建/更新请求体的顶层传入 `"typecast": true`，可让 Airtable 自动强制转换值（例如动态创建新的单选选项，或将 `"42"` 转换为 `42`）。
+
+## 常用查询
+
+### 列出令牌可访问的 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`，并获取主字段名称。
+
+### 列出记录（前 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
+```
+
+### 过滤记录（filterByFormula）
+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
+```
+视图会在服务端应用其保存的过滤条件和排序规则。
+
+## 常用变更操作
+
+### 创建单条记录
+```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 条为一批循环处理，并在每批之间短暂休眠，以遵守每 base 每秒 5 次的速率限制。
+
+### 更新记录（PATCH——合并更新，保留未修改字段）
+```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
+```
+
+## 分页
+
+列表端点每页最多返回 **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
+```
+
+## Hermes 典型工作流
+
+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` — 在执行任何变更操作前，在会话中本地缓存精确的字段名和主字段名。
+4. **写前先读。** 对于"更新满足条件 Y 的 X"类操作，先用 `filterByFormula` 解析出 `rec...` ID，再执行 `PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID`。切勿猜测 record ID。
+5. **批量写入。** 将相关的创建操作合并为一次 10 条记录的 POST 请求，以控制在每秒 5 次的速率预算内。
+6. **破坏性操作。** 删除操作无法通过 API 撤销。若用户要求"删除所有 X"，先回显过滤条件和记录数量，确认后再执行。
+
+## 注意事项
+
+- **`filterByFormula` 必须进行 URL 编码。** 包含空格或非 ASCII 字符的字段名也需要编码（`{My Field}` → `%7BMy%20Field%7D`）。使用 Python 标准库（见上方模式）——切勿手动转义。
+- **空字段不会出现在响应中。** 响应中缺少 `"Assignee"` 键并不意味着该字段不存在——而是表示该记录的值为空。在判断字段缺失之前，请先检查 schema（步骤 3）。
+- **PATCH 与 PUT 的区别。** `PATCH` 将提供的字段合并到记录中。`PUT` 会完全替换记录，并清除所有未包含的字段。默认使用 `PATCH`。
+- **单选选项必须已存在。** 若 `Shipping` 不在字段的选项列表中，写入 `"Status": "Shipping"` 会报错 `INVALID_MULTIPLE_CHOICE_OPTIONS`，除非传入 `"typecast": true`（会自动创建该选项）。
+- **令牌的 base 范围限制。** 某个 base 返回 `403` 而其他 base 正常，说明该 base 未添加到令牌的 Access 列表中——而非权限范围或认证问题。请引导用户前往 https://airtable.com/create/tokens 授权。
+- **速率限制是按 base 计算的，而非按令牌。** `baseA` 每秒 5 次、`baseB` 每秒 5 次是允许的；单独在 `baseA` 上每秒 6 次则会被限流。收到 `429` 时请监控 `Retry-After` 响应头。
+
+## Hermes 重要说明
+
+- **始终使用 `terminal` 工具配合 `curl`。** 不要使用 `web_extract`（无法发送认证头）或 `browser_navigate`（需要 UI 认证且速度慢）。
+- **`AIRTABLE_API_KEY` 会在此 skill 加载时自动从 `~/.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/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/productivity/productivity-google-workspace.md

@@ -0,0 +1,325 @@
+---
+title: "Google Workspace — 通过 gws CLI 或 Python 使用 Gmail、Calendar、Drive、Docs、Sheets"
+sidebar_label: "Google Workspace"
+description: "通过 gws CLI 或 Python 使用 Gmail、Calendar、Drive、Docs、Sheets"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Google Workspace
+
+通过 gws CLI 或 Python 使用 Gmail、Calendar、Drive、Docs、Sheets。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/productivity/google-workspace` |
+| 版本 | `1.1.0` |
+| 作者 | Nous Research |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Google`, `Gmail`, `Calendar`, `Drive`, `Sheets`, `Docs`, `Contacts`, `Email`, `OAuth` |
+| 相关 skill | [`himalaya`](/user-guide/skills/bundled/email/email-himalaya) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# 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 应用专用密码（设置 → 安全 → 应用专用密码）工作，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 客户端 ID 添加到组织的允许应用列表，步骤 4 才能成功。请提前告知用户。
+
+### 步骤 2：创建 OAuth 凭据（一次性，约 5 分钟）
+
+告知用户：
+
+> 你需要一个 Google Cloud OAuth 客户端。这是一次性设置：
+>
+> 1. 创建或选择一个项目：
+>    https://console.cloud.google.com/projectselector2/home/dashboard
+> 2. 在 API 库中启用所需 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 客户端：
+>    https://console.cloud.google.com/apis/credentials
+>    凭据 → 创建凭据 → OAuth 2.0 客户端 ID
+> 4. 应用类型选择「桌面应用」→ 创建
+> 5. 若应用仍处于测试状态，在此处将用户的 Google 账号添加为测试用户：
+>    https://console.cloud.google.com/auth/audience
+>    受众群体 → 测试用户 → 添加用户
+> 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
+```
+
+若用户粘贴的是原始客户端 ID / 客户端密钥值而非文件路径，请自行为其编写一个有效的桌面 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` 以添加自己为测试用户。
+
+### 步骤 4：交换授权码
+
+用户将粘贴回形如 `http://localhost:1/?code=4/0A...&scope=...` 的 URL 或仅粘贴授权码字符串，两者均可。`--auth-url` 步骤会在本地存储一个临时待处理的 OAuth 会话，以便 `--auth-code` 稍后完成 PKCE 交换，即使在无头系统上也可正常工作：
+
+```bash
+$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
+```
+
+若 `--auth-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
+
+# 创建新文档（可选择以正文文本初始化）
+$GAPI docs create --title "Meeting Notes"
+$GAPI docs create --title "Draft" --body "First paragraph..."
+
+# 在现有文档末尾追加文本
+$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 客户端 ID 加入白名单 |
+
+## 撤销访问权限
+
+```bash
+$GSETUP --revoke
+```