dsh-calendar 0.2.2 → 0.3.0

package/README.md

@@ -19,10 +19,35 @@ dsh plugin --profile web add dsh-calendar
 - `provider`：google | icloud | nextcloud | custom
 - `caldavUrl`：完整日历集合 URL（custom / icloud 必填；google / nextcloud 也可手填覆盖预设）
 - `username`：CalDAV 账号（Google / iCloud 为账号邮箱）
-- `password`：密码；Google / iCloud 请用应用专用密码。推荐用环境变量 `DSH_CALENDAR_PASSWORD`，避免明文入库。
+- `password`：密码；Google / iCloud 请用应用专用密码。推荐用环境变量 `DSH_CALENDAR_PASSWORD`，避免明文入库。
+- `proxyUrl`：本机代理地址（如 http://127.0.0.1:7890）。中国大陆访问 Google / iCloud 必填，详见上文「特殊代理配置」专节；国内可直连的 CalDAV 服务无需填写。
 - `calendarId`：google 专用，日历 ID（通常是你的邮箱）
 - `host` / `user` / `calendar`：nextcloud 专用
 
+## 中国用户：特殊代理配置（Google / iCloud）
+
+Google 与 iCloud 的 CalDAV 端点在中国大陆**不可直连**，需要配合你常用的梯子/特殊代理使用。插件内置 `proxyUrl` 配置：把 CalDAV 请求路由到**你本机代理客户端的端口**，不影响其他插件，也无需改任何系统设置。
+
+```yaml
+- id: calendar
+  config:
+    provider: google
+    username: you@gmail.com
+    calendarId: you@gmail.com
+    password: 你的应用专用密码
+    proxyUrl: http://127.0.0.1:7890   # 改成你代理客户端的本地端口
+```
+
+### 常见代理客户端本地端口
+
+| 客户端 | 本地端口 |
+|---|---|
+| Clash / Clash Verge（HTTP） | 7890 / 7897 |
+| v2rayN（HTTP / SOCKS） | 10808 / 10809 |
+| Shadowsocks | 1080 |
+
+在客户端界面确认你的实际端口，填进 `proxyUrl` 即可。国内可直连的 CalDAV 服务（如自建 Nextcloud）则无需填写。
+
 ### Google 示例
 
 ```yaml
@@ -103,7 +128,7 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 ## 已知限制
 
-- **国内网络**：Google（apidata.googleusercontent.com）与 iCloud（caldav.icloud.com）在中国大陆不可直连；请使用可达的 CalDAV 端点（自建 Nextcloud/Radicale 或代理）。
+- **国内网络**：Google 与 iCloud 的 CalDAV 端点在中国大陆不可直连；可用 `proxyUrl` 走本机梯子/特殊代理，或改用国内可直连的 CalDAV 端点（自建 Nextcloud/Radicale）。
 
 
 - 重复事件展开：calendar_list 默认用 ICAL.RecurExpansion 展开 RRULE（`expand=true`），受 `maxOccurrences` 封顶；calendar_search 仍返回原始系列（不展开）。

package/lib/caldav.js

@@ -5,6 +5,7 @@
  * @module dsh-calendar/caldav
  */
 import { createDAVClient } from 'tsdav';
+import { createProxyFetch } from './proxy-fetch.js';
 import { buildICalString, expandEventFromICal, generateUid, parseEventFromICal, } from './ical.js';
 /** CalDAV 操作错误：带中文指引。 */
 export class CalDAVError extends Error {
@@ -47,6 +48,7 @@ export class CalendarService {
             serverUrl: this.config.caldavUrl,
             credentials: { username: this.config.username, password: this.config.password },
             authMethod: 'Basic',
+            ...(this.config.proxyUrl !== '' ? { fetch: createProxyFetch(this.config.proxyUrl) } : {}),
         });
         return this.clientPromise;
     }

package/lib/config.d.ts

@@ -24,6 +24,12 @@ export interface CalendarConfig {
     user?: string;
     /** nextcloud：日历名。 */
     calendar?: string;
+    /**
+     * HTTP 代理地址，如 http://127.0.0.1:7890。
+     * 中国用户访问 Google / iCloud 需经代理：填你本地代理客户端的端口即可，
+     * 插件会把所有 CalDAV 请求路由到该代理，不影响其他插件。
+     */
+    proxyUrl?: string;
 }
 /** 解析完成、可直接建客户端的配置。 */
 export interface ResolvedConfig {
@@ -31,6 +37,7 @@ export interface ResolvedConfig {
     caldavUrl: string;
     username: string;
     password: string;
+    proxyUrl: string;
 }
 /** 预设端点常量。 */
 export declare const GOOGLE_CALDAV_PREFIX = "https://apidata.googleusercontent.com/caldav/v2/";

package/lib/config.js

@@ -49,7 +49,7 @@ export function resolveConfig(config, env = process.env) {
             '或在 profile 的 cordis.patch.yml 覆盖 calendar 行的 password（Google / iCloud 请用应用专用密码）后重启。');
     }
     const caldavUrl = buildCaldavUrl(config ?? {}, provider);
-    return { provider, caldavUrl, username, password };
+    return { provider, caldavUrl, username, password, proxyUrl: nonEmpty(config?.proxyUrl) ?? '' };
 }
 /** 依据 provider 预设或手填字段拼出日历集合 URL。 */
 export function buildCaldavUrl(config, provider) {

package/lib/proxy-fetch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 构造一个把所有请求路由到 proxyUrl 的 fetch（供 tsdav 的 fetch 注入使用）。
+ * @param proxyUrl - 如 http://127.0.0.1:7890
+ */
+export declare function createProxyFetch(proxyUrl: string): typeof globalThis.fetch;

package/lib/proxy-fetch.js

@@ -0,0 +1,14 @@
+/**
+ * 插件级 HTTP 代理：给 CalDAV 请求一个走指定代理的 fetch，不影响同进程其他插件。
+ */
+import { ProxyAgent, fetch as undiciFetch } from 'undici';
+/**
+ * 构造一个把所有请求路由到 proxyUrl 的 fetch（供 tsdav 的 fetch 注入使用）。
+ * @param proxyUrl - 如 http://127.0.0.1:7890
+ */
+export function createProxyFetch(proxyUrl) {
+    const agent = new ProxyAgent(proxyUrl);
+    // undici 自带类型与全局 fetch 类型不完全一致，桥接处用 any 避免类型摩擦；
+    // 对外契约仍是 typeof globalThis.fetch。
+    return ((input, init) => undiciFetch(input, { ...init, dispatcher: agent }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
   "type": "module",
   "main": "lib/index.js",
@@ -44,7 +44,8 @@
   },
   "dependencies": {
     "ical.js": "^2.1.0",
-    "tsdav": "^2.3.1"
+    "tsdav": "^2.3.1",
+    "undici": "^8.10.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",