better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,81 +0,0 @@
----
-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

@@ -1,243 +0,0 @@
----
-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

@@ -1,325 +0,0 @@
----
-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
-```