dsh-plugin-google

本机专属配置写在哪里

bundle 层只放通用默认值，不要把自己的账号、时区、他人日历 ID 写进去 —— 那样发布出去会污染别人的配置。本机设置请写到 profile 自己的覆盖层 $DSH_HOME/profiles/ /cordis.patch.yml：

## 3. 配置 Google Cloud（一次性）

> 这一步必须在 Google Cloud 控制台完成，因为 OAuth 客户端凭据属于你自己的账号。
> 下面这套流程已在本机用 BrowserSkill 实际走过一遍，路径与注意事项都是实测结果。

1. **创建项目**：打开 ，新建一个项目（例如 `dsh-google`）。
   项目 ID 会自动生成（形如 `swift-area-510708-v1`），无需手动指定。
2. **启用两个 API**（务必确认控制台顶部已切到新项目）：
   -  → 「启用此 API」
   -  → 「启用此 API」

   右上角通知里出现「启用服务：calendar-json.googleapis.com」「启用服务：tasks.googleapis.com」即成功。
3. **配置 OAuth 权限请求页面**（ → 「开始」，共 4 步）：
   - 应用名称 + 用户支持邮箱；
   - 受众群体选 **外部 / External**（个人 Gmail 账号下「内部」是灰的，不可选）；
   - 联系邮箱；
   - 勾选同意《Google API 服务：用户数据政策》，再点「创建」。

   ⚠️ **应用名称里不能包含 "Google"**，否则最后一步会报
   「请求失败，因为"应用名称"不符合 Google 的要求」，而且此时前面的填写不会被保存，需要从头再来一次。
   （实测：`DSH Google 日历与任务` 被拒；`DSH 日历与任务` 通过。）
4. **添加测试用户**（ → 「测试用户」→「添加用户」）：
   加入你自己的 Gmail 地址。发布状态为「测试」时，**只有测试用户能授权**，漏掉这一步会在授权时报
   `access_denied`。权限范围**不需要**在这里手动添加，授权时由插件动态请求。
5. **创建 OAuth 客户端**（ → 「创建客户端」）：
   - 应用类型必须选 **桌面应用 / Desktop app**（这类客户端允许任意回环端口，插件才能自动完成授权）；
   - 名称随意（只用于控制台内识别，不展示给用户）；
   - 点「创建」后**立刻点「下载 JSON」**——对话框明确提示：关闭后客户端密钥将无法再次查看；
   - 把下载到的 JSON 放到（Windows 下即 `%USERPROFILE%\.dsh\google-oauth-client.json`）：

     ```
     $DSH_HOME/google-oauth-client.json
     ```

     > 实测提示：若用浏览器自动化下载，文件可能保留为 `Downloads/.tmp`，
     > 内容其实是完整的客户端 JSON，直接改名复制即可。

6. **（可选但强烈建议）把发布状态改为「正式 / In production」**：否则 refresh token 每 7 天失效一次。
   把发布状态从「测试」改为「正式」需要先在**品牌塑造**页填好「应用首页」与「应用隐私权政策链接」，
   再把网址域名加进「已获授权的网域」。个人使用无需通过 Google 验证，
   授权页会出现「此应用未经 Google 验证」提示，点「高级」→「转至…（不安全）」即可继续。

   > 实测：用个人博客地址（`https://alex007.blog.csdn.net/`）作为首页与隐私政策链接即可通过，
   > 且 `csdn.net` 作为已授权网域**不需要**先在 Search Console 完成所有权验证，保存后即可发布。

令牌文件由插件自动写入 `$DSH_HOME/google-oauth-token.json`，不需要手工创建。

### 中国大陆网络

Google API 通常无法直连。请设置代理（二选一）：

- 在插件配置里显式指定：`proxy: 'http://127.0.0.1:7890'`
- 或让 DSH 进程继承环境变量 `HTTPS_PROXY`（Clash / V2Ray 等混合端口即可）

插件支持 HTTP `CONNECT` 隧道；`127.0.0.1` 等回环地址永不经过代理。

---

## 6. 配置项

在 profile 的 `cordis.patch.yml` 里修改（安装后已有默认值）：

| 字段 | 默认值 | 说明 |
|---|---|---|
| `clientSecretFile` | — | Google Cloud 下载的 OAuth 客户端 JSON 路径 |
| `clientId` / `clientSecret` | — | 也可直接给出凭据（不建议写进配置） |
| `credentialRef` | `GOOGLE_OAUTH_CLIENT` | 交给 DSH 凭据服务解析的引用名 |
| `tokenFile` | — | refresh token 的存放路径 |
| `oauthRedirectPort` | `0` | 本地回调端口，0 为自动分配 |
| `oauthRedirectUri` | — | 使用「Web 应用」类型客户端时填写已登记的固定地址 |
| `oauthFlowTimeoutMs` | `900000` | 授权链接有效期 |
| `timeZone` | `Asia/Shanghai` | 解释与展示时间所用时区 |
| `defaultCalendarId` | `primary` | 默认日历 |
| `defaultTaskList` | `@default` | 默认任务列表 |
| `defaultEventMinutes` | `60` | 只给 `start` 时的默认时长 |
| `otherCalendarIds` | `[]` | 「他人日程」日历：照常展示但不参与 `google_agenda` 的冲突判定（例如学生的课表） |
| `scopes` | calendar + tasks | OAuth 权限范围 |
| `proxy` | — | HTTP(S) 代理；留空则读 `HTTPS_PROXY` |
| `rejectUnauthorized` | `true` | 是否校验 TLS 证书 |
| `requestTimeoutMs` | `30000` | 单次请求超时 |
| `readOnly` | `false` | 全局只读 |
| `requireConfirmForWrites` | `false` | 所有写入都要求 `confirm: true` |
| `oauthAuthUrl` / `oauthTokenUrl` / `oauthRevokeUrl` / `calendarApiBase` / `tasksApiBase` | 官方地址 | 端点覆盖（自建代理或测试用） |

---