dsh-calendar 0.2.1 → 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
@@ -101,7 +126,10 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 输入输出统一 ISO 8601。定时事件输出为 UTC（如 `2025-01-15T01:00:00Z`），全天事件输出 `YYYY-MM-DD`。输入可带时区偏移（如 `2025-01-15T09:00:00+08:00`），插件内部转 UTC 存储。
 
-## 已知限制
+## 已知限制
+
+- **国内网络**：Google 与 iCloud 的 CalDAV 端点在中国大陆不可直连；可用 `proxyUrl` 走本机梯子/特殊代理，或改用国内可直连的 CalDAV 端点（自建 Nextcloud/Radicale）。
+
 
 - 重复事件展开：calendar_list 默认用 ICAL.RecurExpansion 展开 RRULE（`expand=true`），受 `maxOccurrences` 封顶；calendar_search 仍返回原始系列（不展开）。
 - 不支持单次实例的改/删：calendar_update / calendar_delete 针对整个重复系列（按 uid 操作），无法只修改或删除某一次发生（不支持 RECURRENCE-ID 实例级操作）。

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/ical.d.ts

@@ -41,6 +41,8 @@ export interface EventFields {
     description?: string;
     location?: string;
     allDay?: boolean;
+    /** 重复规则（RFC 5545 RRULE 语法），如 FREQ=WEEKLY;COUNT=4。 */
+    rrule?: string;
     /** iCal UID；创建时缺省则自动生成，更新时用于保留原 UID。 */
     icalUid?: string;
 }

package/lib/ical.js

@@ -216,6 +216,18 @@ export function buildICalString(fields) {
     if (fields.location !== undefined && fields.location !== '') {
         vevent.addPropertyWithValue('location', fields.location);
     }
+    if (fields.rrule !== undefined && fields.rrule !== '') {
+        const rule = fields.rrule.trim();
+        if (!/^FREQ=/i.test(rule)) {
+            throw new Error('rrule 格式无效：' + fields.rrule + '（应为 RFC 5545 RRULE，如 FREQ=WEEKLY;COUNT=4）');
+        }
+        try {
+            vevent.addPropertyWithValue('rrule', ICAL.Recur.fromString(rule));
+        }
+        catch (error) {
+            throw new Error('rrule 格式无效：' + fields.rrule);
+        }
+    }
     vcal.addSubcomponent(vevent);
     return vcal.toString();
 }

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/lib/tools.js

@@ -115,7 +115,7 @@ export function buildCalendarTools(config) {
     };
     const create = {
         name: 'calendar_create',
-        description: '新建一个日历事件。summary 与 start、end（ISO 8601，含时区偏移）为必填；description、location、allDay 可选。全天事件 start/end 用 YYYY-MM-DD 或设置 allDay=true。成功返回新事件的稳定标识 uid。',
+        description: '新建一个日历事件。summary 与 start、end（ISO 8601，含时区偏移）为必填；description、location、allDay、rrule 可选。全天事件 start/end 用 YYYY-MM-DD 或设置 allDay=true。成功返回新事件的稳定标识 uid。',
         parameters: compileParameters({
             summary: { type: 'string', required: true, description: '事件标题（必填）。' },
             start: { type: 'string', required: true, description: '开始时间（ISO 8601，含时区偏移，必填）。' },
@@ -123,6 +123,7 @@ export function buildCalendarTools(config) {
             description: { type: 'string', description: '事件描述（可选）。' },
             location: { type: 'string', description: '地点（可选）。' },
             allDay: { type: 'boolean', description: '是否全天事件（可选，默认 false）。' },
+            rrule: { type: 'string', description: '重复规则（可选，RFC 5545 RRULE 语法），如 FREQ=WEEKLY;COUNT=4；calendar_list 会按该规则展开实例。' },
         }),
         output: {
             schema: {
@@ -150,6 +151,7 @@ export function buildCalendarTools(config) {
                 ...(optionalString(input, 'description') !== undefined ? { description: optionalString(input, 'description') } : {}),
                 ...(optionalString(input, 'location') !== undefined ? { location: optionalString(input, 'location') } : {}),
                 ...(optionalBoolean(input, 'allDay') !== undefined ? { allDay: optionalBoolean(input, 'allDay') } : {}),
+                ...(optionalString(input, 'rrule') !== undefined ? { rrule: optionalString(input, 'rrule') } : {}),
             };
             const created = await service().create(fields);
             return { created };
@@ -167,6 +169,7 @@ export function buildCalendarTools(config) {
             description: { type: 'string', description: '新描述（可选）。' },
             location: { type: 'string', description: '新地点（可选）。' },
             allDay: { type: 'boolean', description: '是否全天事件（可选）。' },
+            rrule: { type: 'string', description: '新的重复规则（可选）。' },
         }),
         output: {
             schema: {
@@ -206,6 +209,9 @@ export function buildCalendarTools(config) {
             const allDay = optionalBoolean(input, 'allDay');
             if (allDay !== undefined)
                 changes.allDay = allDay;
+            const rrule = optionalString(input, 'rrule');
+            if (rrule !== undefined)
+                changes.rrule = rrule;
             const updated = await service().update(uid, changes);
             return { updated };
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.2.1",
+  "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",