dsh-calendar 0.4.0 → 0.4.1

package/README.en.md

@@ -1,12 +1,14 @@
 # dsh-calendar
 
+![npm](https://img.shields.io/npm/v/dsh-calendar) ![downloads](https://img.shields.io/npm/dm/dsh-calendar) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-calendar) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-calendar?style=social)
+
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 DSH community plugin: read/write calendar events via CalDAV. Provides 5 model-facing tools (calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search), supporting Google / iCloud / Nextcloud and any CalDAV server. This round is a node half-body with no settings-page UI; all configuration goes through the profile's cordis.patch.yml.
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified against `@deepseek-ai/dsh@0.1.2-alpha.2` on 2026-08-31. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -120,12 +122,14 @@ The stable event identifier `uid` is the CalDAV href (full object URL); `calenda
 Input and output are uniformly ISO 8601. Timed events are output in UTC (e.g. `2025-01-15T01:00:00Z`); all-day events output `YYYY-MM-DD`. Input may carry a timezone offset (e.g. `2025-01-15T09:00:00+08:00`); the plugin converts to UTC internally for storage.
 
 
-## v0.3.2 improvements
+## Changelog
 
-- Fix `calendar_update` dropping `rrule` while updating other fields.
-- Validate `end >= start` and reject impossible dates such as `2025-02-30`.
-- Sort `calendar_list` / `calendar_search` output by start time and clamp search `limit` to 1-200.
-- Reset the cached CalDAV client after creation failure so the next tool call can retry.
+- **0.4.0**: new `calendar_health` self-check (one-call CalDAV config health: endpoint/username/password/connection).
+- **0.3.2**:
+  - Fix `calendar_update` dropping `rrule` while updating other fields.
+  - Validate `end >= start` and reject impossible dates such as `2025-02-30`.
+  - Sort `calendar_list` / `calendar_search` output by start time and clamp search `limit` to 1-200.
+  - Reset the cached CalDAV client after creation failure so the next tool call can retry.
 
 ## Known limitations
 
@@ -144,4 +148,4 @@ pnpm install
 pnpm test   # 构建 + node --test
 ```
 
-Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).
+Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).

package/README.md

@@ -13,7 +13,7 @@ DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -146,12 +146,14 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 输入输出统一 ISO 8601。定时事件输出为 UTC（如 `2025-01-15T01:00:00Z`），全天事件输出 `YYYY-MM-DD`。输入可带时区偏移（如 `2025-01-15T09:00:00+08:00`），插件内部转 UTC 存储。
 
-## v0.3.2 优化
+## 版本记录
 
-- 修复 `calendar_update` 更新其他字段时丢失 `rrule` 的问题。
-- 更新与新建都会校验 `end >= start`，并拒绝 `2025-02-30` 这类不存在的日期。
-- `calendar_list` / `calendar_search` 输出按开始时间稳定排序；搜索 `limit` clamp 到 1-200。
-- CalDAV 客户端创建失败后清空缓存，下一次调用可自动重试，不再永久复用 rejected promise。
+- **0.4.0**：新增 `calendar_health` 自检（CalDAV 配置完整性一键体检：端点/账号/密码/连接）。
+- **0.3.2**：
+  - 修复 `calendar_update` 更新其他字段时丢失 `rrule` 的问题。
+  - 更新与新建都会校验 `end >= start`，并拒绝 `2025-02-30` 这类不存在的日期。
+  - `calendar_list` / `calendar_search` 输出按开始时间稳定排序；搜索 `limit` clamp 到 1-200。
+  - CalDAV 客户端创建失败后清空缓存，下一次调用可自动重试，不再永久复用 rejected promise。
 
 
 ## 已知限制

package/lib/caldav.d.ts

@@ -23,20 +23,20 @@ export declare class CalendarService {
     list(startIso: string, endIso: string, options?: {
         expand?: boolean;
         maxOccurrences?: number;
-    }): Promise<CalendarEvent[]>;
+    }, signal?: AbortSignal): Promise<CalendarEvent[]>;
     /** 列出全部事件（客户端过滤用）。 */
-    all(): Promise<CalendarEvent[]>;
+    all(signal?: AbortSignal): Promise<CalendarEvent[]>;
     private toEvents;
     /** 列出并展开：每个对象经 expandEventFromICal 展开为若干实例行。 */
     private toExpandedEvents;
     /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
     private findObject;
     /** 新建事件，返回带 href/uid 的事件。 */
-    create(fields: EventFields): Promise<CalendarEvent>;
+    create(fields: EventFields, signal?: AbortSignal): Promise<CalendarEvent>;
     /** 按 uid 更新事件；未提供的字段保留原值。 */
-    update(uid: string, changes: Partial<EventFields>): Promise<CalendarEvent>;
+    update(uid: string, changes: Partial<EventFields>, signal?: AbortSignal): Promise<CalendarEvent>;
     /** 按 uid 删除事件。 */
-    delete(uid: string): Promise<{
+    delete(uid: string, signal?: AbortSignal): Promise<{
         uid: string;
         href: string;
     }>;

package/lib/caldav.js

@@ -62,35 +62,45 @@ export class CalendarService {
         return { url: this.collectionUrl };
     }
     /** 列出某时间段内的事件；expand 为 true 时在窗口内展开 RRULE。 */
-    async list(startIso, endIso, options) {
+    async list(startIso, endIso, options, signal) {
         const expand = options?.expand !== false;
         const maxOccurrences = options?.maxOccurrences ?? 30;
+        signal?.throwIfAborted();
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const objects = await client.fetchCalendarObjects({
                 calendar: this.calendar(),
                 timeRange: { start: startIso, end: endIso },
                 urlFilter: (url) => typeof url === 'string' && url.length > 0,
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             return expand
                 ? this.toExpandedEvents(objects, startIso, endIso, maxOccurrences)
                 : this.toEvents(objects);
         }
         catch (error) {
+            signal?.throwIfAborted();
             throw translateError(error, '读取日历');
         }
     }
     /** 列出全部事件（客户端过滤用）。 */
-    async all() {
+    async all(signal) {
+        signal?.throwIfAborted();
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const objects = await client.fetchCalendarObjects({
                 calendar: this.calendar(),
                 urlFilter: (url) => typeof url === 'string' && url.length > 0,
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             return this.toEvents(objects);
         }
         catch (error) {
+            signal?.throwIfAborted();
             throw translateError(error, '读取日历');
         }
     }
@@ -112,29 +122,39 @@ export class CalendarService {
         return events;
     }
     /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
-    async findObject(uid) {
+    async findObject(uid, signal) {
+        signal?.throwIfAborted();
         const client = await this.client();
+        signal?.throwIfAborted();
         const target = normalizeUrl(uid);
         const objects = await client.fetchCalendarObjects({
             calendar: this.calendar(),
             urlFilter: (url) => normalizeUrl(url) === target,
+            ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
         });
+        signal?.throwIfAborted();
         return objects.find((object) => normalizeUrl(object.url) === target);
     }
     /** 新建事件，返回带 href/uid 的事件。 */
-    async create(fields) {
-        const iCalString = buildICalString(fields);
-        const filename = (fields.icalUid ?? generateUid()) + '.ics';
+    async create(fields, signal) {
+        signal?.throwIfAborted();
+        const icalUid = fields.icalUid ?? generateUid();
+        const iCalString = buildICalString({ ...fields, icalUid });
+        const filename = icalUid + '.ics';
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const response = await client.createCalendarObject({
                 calendar: this.calendar(),
                 iCalString,
                 filename,
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             assertOk(response, '新建事件');
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (error instanceof CalDAVError)
                 throw error;
             throw translateError(error, '新建事件');
@@ -146,12 +166,14 @@ export class CalendarService {
         return event;
     }
     /** 按 uid 更新事件；未提供的字段保留原值。 */
-    async update(uid, changes) {
+    async update(uid, changes, signal) {
+        signal?.throwIfAborted();
         let object;
         try {
-            object = await this.findObject(uid);
+            object = await this.findObject(uid, signal);
         }
         catch (error) {
+            signal?.throwIfAborted();
             throw translateError(error, '查找事件');
         }
         if (object === undefined) {
@@ -182,12 +204,16 @@ export class CalendarService {
         const iCalString = buildICalString(merged);
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const response = await client.updateCalendarObject({
                 calendarObject: { url: object.url, etag: object.etag, data: iCalString },
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             assertOk(response, '更新事件');
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (error instanceof CalDAVError)
                 throw error;
             throw translateError(error, '更新事件');
@@ -198,12 +224,14 @@ export class CalendarService {
         return event;
     }
     /** 按 uid 删除事件。 */
-    async delete(uid) {
+    async delete(uid, signal) {
+        signal?.throwIfAborted();
         let object;
         try {
-            object = await this.findObject(uid);
+            object = await this.findObject(uid, signal);
         }
         catch (error) {
+            signal?.throwIfAborted();
             throw translateError(error, '查找事件');
         }
         if (object === undefined) {
@@ -212,12 +240,16 @@ export class CalendarService {
         }
         try {
             const client = await this.client();
+            signal?.throwIfAborted();
             const response = await client.deleteCalendarObject({
                 calendarObject: { url: object.url, etag: object.etag },
+                ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
+            signal?.throwIfAborted();
             assertOk(response, '删除事件');
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (error instanceof CalDAVError)
                 throw error;
             throw translateError(error, '删除事件');

package/lib/config.d.ts

@@ -47,6 +47,7 @@ export declare const NEXTCLOUD_PATH = "/remote.php/dav/calendars/";
 export declare class ConfigError extends Error {
     constructor(message: string);
 }
+export declare const CALENDAR_PROVIDERS: readonly CalendarProvider[];
 /**
  * 解析配置为可用的 caldavUrl + 凭证。配置缺失抛出 ConfigError（中文指引）。
  * @param config - 插件 config（可能 undefined）。

package/lib/config.js

@@ -15,7 +15,7 @@ export class ConfigError extends Error {
         this.name = 'ConfigError';
     }
 }
-const PROVIDERS = ['google', 'icloud', 'nextcloud', 'custom'];
+export const CALENDAR_PROVIDERS = ['google', 'icloud', 'nextcloud', 'custom'];
 function nonEmpty(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
@@ -25,7 +25,7 @@ function trimTrailingSlash(value) {
 function normalizeProvider(value) {
     if (value === undefined || value === null || value === '')
         return 'custom';
-    if (typeof value === 'string' && PROVIDERS.includes(value)) {
+    if (typeof value === 'string' && CALENDAR_PROVIDERS.includes(value)) {
         return value;
     }
     throw new ConfigError('dsh-calendar 的 provider 取值不合法：只支持 google / icloud / nextcloud / custom。' +

package/lib/tools.d.ts

@@ -27,4 +27,4 @@ export interface CalendarToolDefinition {
     timeoutMs?: number;
 }
 /** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export declare function buildCalendarTools(config: CalendarConfig | undefined): CalendarToolDefinition[];
+export declare function buildCalendarTools(config: CalendarConfig | undefined, env?: NodeJS.ProcessEnv): CalendarToolDefinition[];

package/lib/tools.js

@@ -5,13 +5,19 @@
  * @module dsh-calendar/tools
  */
 import { CalendarService } from './caldav.js';
-import { resolveConfig } from './config.js';
+import { CALENDAR_PROVIDERS, resolveConfig } from './config.js';
 import { compileParameters } from './parameters.js';
 const EVENT_SCHEMA = { type: 'object', additionalProperties: true };
 const TIMEOUT_MS = 60000;
 function asRecord(args) {
     return typeof args === 'object' && args !== null ? args : {};
 }
+function executionSignal(exec) {
+    if (typeof exec !== 'object' || exec === null)
+        return undefined;
+    const signal = exec.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}
 function optionalString(args, key) {
     const value = args[key];
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
@@ -97,8 +103,8 @@ function buildSearchFilter(query) {
     };
 }
 /** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export function buildCalendarTools(config) {
-    const service = () => new CalendarService(resolveConfig(config));
+export function buildCalendarTools(config, env = process.env) {
+    const service = () => new CalendarService(resolveConfig(config, env));
     const list = {
         name: 'calendar_list',
         description: '列出某时间段内的日历事件（默认未来 7 天）。start/end 为 ISO 8601 时间（含时区偏移，如 2025-01-01T09:00:00+08:00），全天事件返回 YYYY-MM-DD。默认展开重复事件（RRULE）：每个实例作为独立行返回，start/end 为该次发生时间，并带 isOccurrence=true 与 seriesStart（系列原开始时间）；非重复事件保持单行且 isOccurrence=false。expand=false 时重复事件按原始单条返回并带 rrule 字段。maxOccurrences 为每个重复事件的展开次数上限。返回每个事件的稳定标识 uid，供 calendar_update / calendar_delete 使用。',
@@ -128,7 +134,7 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const now = new Date();
             const defaultEnd = new Date(now.getTime() + 7 * 24 * 3600 * 1000);
@@ -139,7 +145,7 @@ export function buildCalendarTools(config) {
             assertTimeRange(start, end);
             const expand = booleanWithDefault(input, 'expand', true);
             const maxOccurrences = clampedInteger(input, 'maxOccurrences', 30, 1, 200);
-            const events = sortEvents(await service().list(start, end, { expand, maxOccurrences }));
+            const events = sortEvents(await service().list(start, end, { expand, maxOccurrences }, executionSignal(exec)));
             return { count: events.length, start, end, events };
         },
         timeoutMs: TIMEOUT_MS,
@@ -168,7 +174,7 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: '已新建事件：' + formatEvent(event) }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const summary = requiredString(input, 'summary', '事件标题');
             const start = requiredString(input, 'start', '开始时间');
@@ -189,7 +195,7 @@ export function buildCalendarTools(config) {
                 ...(allDay !== undefined ? { allDay } : {}),
                 ...(rrule !== undefined ? { rrule } : {}),
             };
-            const created = await service().create(fields);
+            const created = await service().create(fields, executionSignal(exec));
             return { created };
         },
         timeoutMs: TIMEOUT_MS,
@@ -219,7 +225,7 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: '已更新事件：' + formatEvent(event) }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const uid = requiredString(input, 'uid', '事件 uid');
             const changes = {};
@@ -248,7 +254,7 @@ export function buildCalendarTools(config) {
             const rrule = optionalString(input, 'rrule');
             if (rrule !== undefined)
                 changes.rrule = rrule;
-            const updated = await service().update(uid, changes);
+            const updated = await service().update(uid, changes, executionSignal(exec));
             return { updated };
         },
         timeoutMs: TIMEOUT_MS,
@@ -275,10 +281,10 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: '已删除事件：uid=' + result.uid }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const uid = requiredString(input, 'uid', '事件 uid');
-            const result = await service().delete(uid);
+            const result = await service().delete(uid, executionSignal(exec));
             return { deleted: true, uid: result.uid, href: result.href };
         },
         timeoutMs: TIMEOUT_MS,
@@ -309,11 +315,11 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(args) {
+        async execute(args, exec) {
             const input = asRecord(args);
             const query = requiredString(input, 'query', '搜索关键词');
             const limit = clampedInteger(input, 'limit', 50, 1, 200);
-            const all = await service().all();
+            const all = await service().all(executionSignal(exec));
             const matched = sortEvents(all).filter(buildSearchFilter(query)).slice(0, limit);
             return { query, count: matched.length, events: matched };
         },
@@ -336,29 +342,41 @@ export function buildCalendarTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute() {
+        async execute(_args, exec) {
+            executionSignal(exec)?.throwIfAborted();
             const checks = [];
-            let ok = true;
-            const provider = (config?.provider ?? 'custom');
-            checks.push({ name: '服务商', ok: true, detail: provider });
-            const hasUrl = typeof config?.caldavUrl === 'string' && config.caldavUrl.trim() !== '';
-            const derivable = provider === 'google' || provider === 'nextcloud' || provider === 'icloud';
-            if (hasUrl || derivable) {
-                checks.push({ name: '日历地址', ok: true, detail: hasUrl ? '已配置 caldavUrl' : provider + ' 预设可推导' });
+            const rawProvider = config?.provider;
+            const provider = rawProvider === undefined || rawProvider === null || rawProvider === '' ? 'custom' : String(rawProvider);
+            const providerOk = CALENDAR_PROVIDERS.includes(provider);
+            checks.push({ name: '服务商', ok: providerOk, detail: providerOk ? provider : '不支持 ' + provider + '；只支持 ' + CALENDAR_PROVIDERS.join(' / ') });
+            let resolved;
+            try {
+                resolved = resolveConfig(config, env);
             }
-            else {
-                ok = false;
-                checks.push({ name: '日历地址', ok: false, detail: '未配置：请在 profile 的 cordis.patch.yml 里给 calendar 行填 caldavUrl' });
+            catch {
+                // Each individual check below provides the actionable detail.
             }
             const hasUser = typeof config?.username === 'string' && config.username.trim() !== '';
+            const configuredPassword = typeof config?.password === 'string' && config.password.trim() !== '';
+            const envPassword = typeof env.DSH_CALENDAR_PASSWORD === 'string' && env.DSH_CALENDAR_PASSWORD.trim() !== '';
+            try {
+                const endpoint = resolved ?? resolveConfig({
+                    ...config,
+                    username: hasUser ? config.username : '__health_check__',
+                    password: configuredPassword ? config.password : (envPassword ? env.DSH_CALENDAR_PASSWORD : '__health_check__'),
+                }, env);
+                checks.push({ name: '日历地址', ok: true, detail: '已解析为 ' + endpoint.caldavUrl });
+            }
+            catch (error) {
+                checks.push({ name: '日历地址', ok: false, detail: error instanceof Error ? error.message : String(error) });
+            }
             checks.push({ name: '账号', ok: hasUser, detail: hasUser ? '已配置' : '未配置：请填 username（Google/iCloud 为账号邮箱）' });
-            if (!hasUser)
-                ok = false;
-            const hasPass = typeof config?.password === 'string' && config.password.trim() !== '';
-            checks.push({ name: '密码', ok: hasPass, detail: hasPass ? '已配置' : '未配置：请填 password 或环境变量 DSH_CALENDAR_PASSWORD（Google/iCloud 用应用专用密码）' });
-            if (!hasPass)
-                ok = false;
-            return { ok, plugin: 'dsh-calendar', checks };
+            checks.push({
+                name: '密码',
+                ok: configuredPassword || envPassword,
+                detail: configuredPassword ? '已在插件配置中提供' : envPassword ? '已通过环境变量 DSH_CALENDAR_PASSWORD 提供' : '未配置：请填 password 或环境变量 DSH_CALENDAR_PASSWORD（Google/iCloud 用应用专用密码）',
+            });
+            return { ok: resolved !== undefined, plugin: 'dsh-calendar', checks };
         },
         timeoutMs: TIMEOUT_MS,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
   "type": "module",
   "main": "lib/index.js",