dsh-calendar 0.2.2 → 0.3.1

package/README.en.md

@@ -20,6 +20,7 @@ All configuration lives in your profile's cordis.patch.yml; override the `calend
 - `password`: password; for Google / iCloud use an app-specific password. Recommended to use the `DSH_CALENDAR_PASSWORD` env var to avoid storing it in plaintext.
 - `calendarId`: google-specific, the calendar ID (usually your email)
 - `host` / `user` / `calendar`: nextcloud-specific
+- `proxyUrl`: optional HTTP proxy (e.g. `http://127.0.0.1:7890`); routes only this plugin's CalDAV requests through it
 
 ### Google example
 
@@ -85,6 +86,10 @@ iCloud: sign in to appleid.apple.com → Sign-In and Security → App-Specific P
 
 If a call returns 401/403, it's usually the wrong password (login password used instead of an app-specific password); the plugin returns a Chinese hint.
 
+## Proxy
+
+If your CalDAV server is not directly reachable from your network (some regional or corporate networks block it), set `proxyUrl` in the plugin config, e.g. `http://127.0.0.1:7890`, and restart. The proxy only routes this plugin's CalDAV requests; it does not affect other plugins in the same process.
+
 ## Tool reference
 
 - `calendar_list`: list events in a time range (start/end, ISO 8601; defaults to the next 7 days). Recurring events are expanded by default (`expand` defaults to true, `maxOccurrences` defaults to 30, clamped to 1-200): each occurrence is a separate row with `isOccurrence: true` and `seriesStart`; non-recurring events keep `isOccurrence: false`. With `expand=false`, recurring events are returned as a single original entry with `rrule`

package/README.md

@@ -2,6 +2,11 @@
 
 # dsh-calendar
 
+> **agent 从此会排期**：CalDAV 读写日历，重复日程自动展开。
+
+![npm version](https://img.shields.io/npm/v/dsh-calendar?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-calendar) ![license](https://img.shields.io/npm/l/dsh-calendar) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-calendar?style=social)
+
+
 DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），支持 Google / iCloud / Nextcloud 及任意 CalDAV 服务器。本轮为 node 半身，不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
 
 ## 安装
@@ -20,9 +25,34 @@ dsh plugin --profile web add dsh-calendar
 - `caldavUrl`：完整日历集合 URL（custom / icloud 必填；google / nextcloud 也可手填覆盖预设）
 - `username`：CalDAV 账号（Google / iCloud 为账号邮箱）
 - `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,9 +131,9 @@ 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（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 仍返回原始系列（不展开）。
@@ -128,3 +158,4 @@ pnpm test   # 构建 + node --test
 - [dsh-calendar](https://github.com/STARDUSTLC666/dsh-calendar) — CalDAV 日历五件套
 - [dsh-slack](https://github.com/STARDUSTLC666/dsh-slack) — Slack 通知/收件箱
 - [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）
+

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 {
@@ -43,12 +44,19 @@ export class CalendarService {
         this.collectionUrl = ensureTrailingSlash(config.caldavUrl);
     }
     client() {
-        this.clientPromise ??= createDAVClient({
-            serverUrl: this.config.caldavUrl,
-            credentials: { username: this.config.username, password: this.config.password },
-            authMethod: 'Basic',
+        if (this.clientPromise === undefined) {
+            this.clientPromise = createDAVClient({
+                serverUrl: this.config.caldavUrl,
+                credentials: { username: this.config.username, password: this.config.password },
+                authMethod: 'Basic',
+                ...(this.config.proxyUrl !== '' ? { fetch: createProxyFetch(this.config.proxyUrl) } : {}),
+            });
+        }
+        // 创建失败时清掉缓存，让下一次工具调用有机会重试，而不是永久复用 rejected promise。
+        return this.clientPromise.catch((error) => {
+            this.clientPromise = undefined;
+            throw error;
         });
-        return this.clientPromise;
     }
     calendar() {
         return { url: this.collectionUrl };
@@ -156,6 +164,11 @@ export class CalendarService {
         if (start === undefined || end === undefined) {
             throw new CalDAVError('无法确定事件的开始/结束时间：请同时提供 start 与 end。');
         }
+        const startMs = new Date(start).getTime();
+        const endMs = new Date(end).getTime();
+        if (!Number.isNaN(startMs) && !Number.isNaN(endMs) && endMs < startMs) {
+            throw new CalDAVError('更新时间范围无效：end 不能早于 start（' + end + ' < ' + start + '）。');
+        }
         const merged = {
             summary: changes.summary ?? existing?.summary ?? '',
             start,
@@ -163,6 +176,7 @@ export class CalendarService {
             ...(changes.description !== undefined ? { description: changes.description } : existing?.description !== undefined ? { description: existing.description } : {}),
             ...(changes.location !== undefined ? { location: changes.location } : existing?.location !== undefined ? { location: existing.location } : {}),
             allDay: changes.allDay ?? existing?.allDay,
+            ...(changes.rrule !== undefined ? { rrule: changes.rrule } : existing?.rrule !== undefined ? { rrule: existing.rrule } : {}),
             ...(existing?.icalUid !== undefined ? { icalUid: existing.icalUid } : {}),
         };
         const iCalString = buildICalString(merged);

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

@@ -42,16 +42,46 @@ function clampedInteger(args, key, fallback, min, max) {
         return fallback;
     return Math.min(max, Math.max(min, value));
 }
+const DATE_ONLY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
 function assertIsoTime(value, label) {
-    if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+    const dateOnly = DATE_ONLY_PATTERN.exec(value);
+    if (dateOnly !== null) {
+        const year = Number(dateOnly[1]);
+        const month = Number(dateOnly[2]);
+        const day = Number(dateOnly[3]);
+        const date = new Date(Date.UTC(year, month - 1, day));
+        if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+            throw new Error(label + ' 不是合法的日期：' + value + '（YYYY-MM-DD 必须是真实存在的日期）。');
+        }
         return;
+    }
     if (Number.isNaN(new Date(value).getTime())) {
         throw new Error(label + ' 不是合法的 ISO 8601 时间，例如 2025-01-01T09:00:00+08:00 或 2025-01-01T09:00:00Z。');
     }
 }
+/** 日期/时间统一转 epoch 毫秒（date-only 按 UTC 零点），用于范围比较。 */
+function toEpochMs(value) {
+    const dateOnly = DATE_ONLY_PATTERN.exec(value);
+    if (dateOnly !== null) {
+        return Date.UTC(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]));
+    }
+    return new Date(value).getTime();
+}
+function assertTimeRange(start, end) {
+    if (toEpochMs(start) > toEpochMs(end)) {
+        throw new Error('end 不能早于 start：' + end + ' < ' + start + '。请确认起止时间顺序。');
+    }
+}
 function isoNoMillis(value) {
     return value.replace(/\.\d{3}Z$/, 'Z');
 }
+/** 按开始时间升序稳定排序（CalDAV 服务端返回顺序不保证稳定）。 */
+function sortEvents(events) {
+    return events
+        .map((event, index) => ({ event, index, startMs: toEpochMs(event.start) }))
+        .sort((a, b) => a.startMs - b.startMs || a.index - b.index)
+        .map(({ event }) => event);
+}
 function formatEvent(event) {
     const range = event.allDay ? event.start + '（全天）' : event.start + ' ~ ' + event.end;
     const extra = [event.location ? '地点：' + event.location : '', event.rrule ? '重复：' + event.rrule : '']
@@ -106,9 +136,10 @@ export function buildCalendarTools(config) {
             const end = optionalString(input, 'end') ?? isoNoMillis(defaultEnd.toISOString());
             assertIsoTime(start, 'start');
             assertIsoTime(end, 'end');
+            assertTimeRange(start, end);
             const expand = booleanWithDefault(input, 'expand', true);
             const maxOccurrences = clampedInteger(input, 'maxOccurrences', 30, 1, 200);
-            const events = await service().list(start, end, { expand, maxOccurrences });
+            const events = sortEvents(await service().list(start, end, { expand, maxOccurrences }));
             return { count: events.length, start, end, events };
         },
         timeoutMs: TIMEOUT_MS,
@@ -144,14 +175,19 @@ export function buildCalendarTools(config) {
             const end = requiredString(input, 'end', '结束时间');
             assertIsoTime(start, 'start');
             assertIsoTime(end, 'end');
+            assertTimeRange(start, end);
+            const description = optionalString(input, 'description');
+            const location = optionalString(input, 'location');
+            const allDay = optionalBoolean(input, 'allDay');
+            const rrule = optionalString(input, 'rrule');
             const fields = {
                 summary,
                 start,
                 end,
-                ...(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') } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(location !== undefined ? { location } : {}),
+                ...(allDay !== undefined ? { allDay } : {}),
+                ...(rrule !== undefined ? { rrule } : {}),
             };
             const created = await service().create(fields);
             return { created };
@@ -160,7 +196,7 @@ export function buildCalendarTools(config) {
     };
     const update = {
         name: 'calendar_update',
-        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay 均可选，未提供的字段保留原值。',
+        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay、rrule 均可选，未提供的字段保留原值。',
         parameters: compileParameters({
             uid: { type: 'string', required: true, description: '事件稳定标识（来自 calendar_list / calendar_search 的 uid，必填）。' },
             summary: { type: 'string', description: '新标题（可选）。' },
@@ -252,7 +288,7 @@ export function buildCalendarTools(config) {
         description: '按关键词搜索日历事件（客户端过滤：匹配标题、描述、地点与 iCal UID，不区分大小写）。query 必填，limit 可选（默认 50）。返回每个事件的稳定标识 uid。',
         parameters: compileParameters({
             query: { type: 'string', required: true, description: '搜索关键词（必填）。' },
-            limit: { type: 'integer', description: '最多返回条数（可选，默认 50）。' },
+            limit: { type: 'integer', description: '最多返回条数（可选，默认 50，自动 clamp 到 1-200）。' },
         }),
         output: {
             schema: {
@@ -276,9 +312,9 @@ export function buildCalendarTools(config) {
         async execute(args) {
             const input = asRecord(args);
             const query = requiredString(input, 'query', '搜索关键词');
-            const limit = optionalInteger(input, 'limit') ?? 50;
+            const limit = clampedInteger(input, 'limit', 50, 1, 200);
             const all = await service().all();
-            const matched = all.filter(buildSearchFilter(query)).slice(0, limit);
+            const matched = sortEvents(all).filter(buildSearchFilter(query)).slice(0, limit);
             return { query, count: matched.length, events: matched };
         },
         timeoutMs: TIMEOUT_MS,

package/package.json

@@ -1,63 +1,61 @@
-{
-  "name": "dsh-calendar",
-  "version": "0.2.2",
-  "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepare": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
-    "prepublishOnly": "pnpm run build"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "calendar",
-    "caldav",
-    "ical"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "ical.js": "^2.1.0",
-    "tsdav": "^2.3.1"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.6.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/STARDUSTLC666/dsh-calendar"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-calendar/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-calendar#readme",
-  "author": "stardustlc",
-  "packageManager": "pnpm@11.7.0"
-}
+{
+  "name": "dsh-calendar",
+  "version": "0.3.1",
+  "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "calendar",
+    "caldav",
+    "ical"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ical.js": "^2.1.0",
+    "tsdav": "^2.3.1",
+    "undici": "^8.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/STARDUSTLC666/dsh-calendar"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-calendar/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-calendar#readme",
+  "author": "stardustlc",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\""
+  }
+}