dsh-calendar 0.3.2 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -1,7 +1,15 @@
 # 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.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
 
 ```bash
@@ -10,6 +18,15 @@ dsh plugin --profile web add dsh-calendar
 
 After installing, restart dsh. The plugin inserts a `calendar` config line into the profile (see this package's cordis.patch.yml). The default provider is custom with no credentials filled in; the plugin still loads, but tools throw a Chinese guidance error when called, prompting you to complete the configuration.
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-calendar
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 All configuration lives in your profile's cordis.patch.yml; override the `calendar` line by id (overriding replaces that line's config wholesale). Common fields:
@@ -92,11 +109,11 @@ If your CalDAV server is not directly reachable from your network (some regional
 
 ## 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`
-- `calendar_create`: create an event (summary/start/end required; description/location/allDay optional)
-- `calendar_update`: edit an event by uid (summary/start/end/description/location/allDay optional; omitted fields keep their original values)
+- `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`. Results are stably sorted by start time.
+- `calendar_create`: create an event (summary/start/end required; description/location/allDay/rrule optional). Validates real calendar dates and `end >= start`.
+- `calendar_update`: edit an event by uid (summary/start/end/description/location/allDay/rrule optional; omitted fields keep their original values, including the recurrence rule).
 - `calendar_delete`: delete an event by uid
-- `calendar_search`: search events by keyword (client-side filter over title/description/location/UID, case-insensitive)
+- `calendar_search`: search events by keyword (client-side filter over title/description/location/UID, case-insensitive; `limit` defaults to 50, clamped to 1-200, and results are sorted by start time).
 
 The stable event identifier `uid` is the CalDAV href (full object URL); `calendar_update` / `calendar_delete` use it.
 
@@ -104,6 +121,16 @@ 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.
 
+
+## Changelog
+
+- **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
 
 - Recurring event expansion: calendar_list expands RRULE by default via ICAL.RecurExpansion (`expand=true`), capped by `maxOccurrences`; calendar_search still returns the original series (not expanded).

package/README.md

@@ -6,9 +6,15 @@
 
 ![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)
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 
 DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），支持 Google / iCloud / Nextcloud 及任意 CalDAV 服务器。本轮为 node 半身，不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
 
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
 ## 安装
 
 ```bash
@@ -29,6 +35,15 @@ dsh plugin --profile web add dsh-calendar
 - `calendarId`：google 专用，日历 ID（通常是你的邮箱）
 - `host` / `user` / `calendar`：nextcloud 专用
 
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-calendar
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
+
 ## 中国用户：特殊代理配置（Google / iCloud）
 
 Google 与 iCloud 的 CalDAV 端点在中国大陆**不可直连**，需要配合你常用的梯子/特殊代理使用。插件内置 `proxyUrl` 配置：把 CalDAV 请求路由到**你本机代理客户端的端口**，不影响其他插件，也无需改任何系统设置。
@@ -119,11 +134,11 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 ## 工具清单
 
-- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`
-- `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay 可选）
-- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay 可选，未提供保留原值）
+- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`。结果按开始时间稳定排序
+- `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay/rrule 可选）。严格校验真实日历日期与 `end >= start`
+- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay/rrule 可选，未提供保留原值，重复规则不再丢失）
 - `calendar_delete`：按 uid 删事件
-- `calendar_search`：按关键词搜事件（客户端过滤标题/描述/地点/UID，不区分大小写）
+- `calendar_search`：按关键词搜事件（客户端过滤标题/描述/地点/UID，不区分大小写；`limit` 默认 50、clamp 1-200，结果按开始时间排序）
 
 事件稳定标识 `uid` 为 CalDAV href（完整对象 URL），`calendar_update` / `calendar_delete` 使用它。
 
@@ -131,6 +146,16 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 输入输出统一 ISO 8601。定时事件输出为 UTC（如 `2025-01-15T01:00:00Z`），全天事件输出 `YYYY-MM-DD`。输入可带时区偏移（如 `2025-01-15T09:00:00+08:00`），插件内部转 UTC 存储。
 
+## 版本记录
+
+- **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。
+
+
 ## 已知限制
 
 - **国内网络**：Google 与 iCloud 的 CalDAV 端点在中国大陆不可直连；可用 `proxyUrl` 走本机梯子/特殊代理，或改用国内可直连的 CalDAV 端点（自建 Nextcloud/Radicale）。
@@ -157,5 +182,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) — 钉钉群通知（零依赖）
-
+- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）

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/ical.js

@@ -179,7 +179,12 @@ export function expandEventFromICal(data, href, etag, rangeStart, rangeEnd, maxO
     const rangeEndMs = isoToEpochMs(rangeEnd);
     const occurrences = [];
     try {
+        const totalIterationCap = Math.max(100000, maxOccurrences * 1000);
+        let iterations = 0;
         while (occurrences.length < maxOccurrences) {
+            iterations += 1;
+            if (iterations > totalIterationCap)
+                break;
             const next = expansion.next();
             if (next === null || next === undefined)
                 break;

package/lib/index.d.ts

@@ -10,6 +10,7 @@
 import { type CalendarConfig } from './config.js';
 import { type CalendarToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明注入，否则宿主会抛 cannot get property without inject。 */
+export declare const name = "calendar";
 export declare const inject: string[];
 /** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
 export interface CalendarPluginContext {

package/lib/index.js

@@ -10,6 +10,7 @@
 import { resolveConfig } from './config.js';
 import { buildCalendarTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明注入，否则宿主会抛 cannot get property without inject。 */
+export const name = 'calendar';
 export const inject = ['tools'];
 /**
  * 插件入口：惰性解析配置并注册五个日历工具。

package/lib/tools.d.ts

@@ -26,5 +26,5 @@ export interface CalendarToolDefinition {
     execute(args: unknown, exec: unknown): Promise<unknown>;
     timeoutMs?: number;
 }
-/** 构建五个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export declare function buildCalendarTools(config: CalendarConfig | undefined): CalendarToolDefinition[];
+/** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
+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;
@@ -96,9 +102,9 @@ function buildSearchFilter(query) {
         return haystack.includes(needle);
     };
 }
-/** 构建五个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export function buildCalendarTools(config) {
-    const service = () => new CalendarService(resolveConfig(config));
+/** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
+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,15 +315,70 @@ 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 };
         },
         timeoutMs: TIMEOUT_MS,
     };
-    return [list, create, update, remove, search];
+    const health = {
+        name: 'calendar_health',
+        description: 'dsh-calendar 自检：检查 CalDAV 配置完整性（服务商/日历地址/账号/密码），不发起网络连接。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const rec = (value ?? {});
+                const rawChecks = Array.isArray(rec.checks) ? rec.checks : [];
+                const lines = ['dsh-calendar 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const item of rawChecks) {
+                    const c = (item ?? {});
+                    lines.push('- ' + String(c.name) + '：' + (c.ok === true ? '✅ ' + String(c.detail ?? '') : '❌ ' + String(c.detail ?? '')));
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(_args, exec) {
+            executionSignal(exec)?.throwIfAborted();
+            const checks = [];
+            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);
+            }
+            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 为账号邮箱）' });
+            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,
+    };
+    return [list, create, update, remove, search, health];
 }

package/package.json

@@ -1,61 +1,63 @@
-{
-  "name": "dsh-calendar",
-  "version": "0.3.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"
-  ],
-  "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\""
-  }
-}
+{
+  "name": "dsh-calendar",
+  "version": "0.4.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"
+  ],
+  "scripts": {
+    "build": "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": ">=22"
+  },
+  "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": "git+https://github.com/STARDUSTLC666/dsh-calendar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-calendar/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-calendar#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}