dsh-calendar 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# dsh-calendar
+
+DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），支持 Google / iCloud / Nextcloud 及任意 CalDAV 服务器。本轮为 node 半身，不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-calendar
+```
+
+安装后重启 dsh。插件会向 profile 插入一行 id 为 `calendar` 的配置行（见本包的 cordis.patch.yml）。默认 provider 为 custom 且未填任何凭证，此时插件照常加载，但工具在调用时会抛出中文指引错误，提示你补全配置。
+
+## 配置
+
+所有配置都在你的 profile 的 cordis.patch.yml 里，按 id 覆盖 `calendar` 行（覆盖整行的 config）。通用字段：
+
+- `provider`：google | icloud | nextcloud | custom
+- `caldavUrl`：完整日历集合 URL（custom / icloud 必填；google / nextcloud 也可手填覆盖预设）
+- `username`：CalDAV 账号（Google / iCloud 为账号邮箱）
+- `password`：密码；Google / iCloud 请用应用专用密码。推荐用环境变量 `DSH_CALENDAR_PASSWORD`，避免明文入库。
+- `calendarId`：google 专用，日历 ID（通常是你的邮箱）
+- `host` / `user` / `calendar`：nextcloud 专用
+
+### Google 示例
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: google
+    username: you@gmail.com
+    calendarId: you@gmail.com
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+Google 的 CalDAV 集合 URL 由插件拼成：`https://apidata.googleusercontent.com/caldav/v2/<calendarId>/events`。
+
+### iCloud 示例
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: icloud
+    username: you@icloud.com
+    caldavUrl: https://caldav.icloud.com/123456789/calendars/<日历ID>/
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+iCloud 需要完整日历集合 URL（含你的用户 ID 与日历 ID），在 icloud.com 的日历 CalDAV 设置里可找到具体日历地址。
+
+### Nextcloud 示例
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: nextcloud
+    username: alice
+    host: https://cloud.example.com
+    user: alice
+    calendar: personal
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+插件会拼成：`https://cloud.example.com/remote.php/dav/calendars/alice/personal/`。
+
+### 自定义 CalDAV 示例
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: custom
+    caldavUrl: https://dav.example.com/calendars/me/work/
+    username: me
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+## 应用专用密码指引
+
+Google：登录 myaccount.google.com → 安全 → 两步验证（需先开启）→ 应用专用密码，选择「其他」生成 16 位密码，填到 `password` 或 `DSH_CALENDAR_PASSWORD`。不能用你的 Google 登录密码。
+
+iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生成后填到 `password` 或 `DSH_CALENDAR_PASSWORD`。不能用你的 Apple ID 密码。
+
+若调用报 401/403，多半是密码不对（用了登录密码而非应用专用密码），插件会返回中文提示。
+
+## 工具清单
+
+- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）
+- `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay 可选）
+- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay 可选，未提供保留原值）
+- `calendar_delete`：按 uid 删事件
+- `calendar_search`：按关键词搜事件（客户端过滤标题/描述/地点/UID，不区分大小写）
+
+事件稳定标识 `uid` 为 CalDAV href（完整对象 URL），`calendar_update` / `calendar_delete` 使用它。
+
+## 时间与时区
+
+输入输出统一 ISO 8601。定时事件输出为 UTC（如 `2025-01-15T01:00:00Z`），全天事件输出 `YYYY-MM-DD`。输入可带时区偏移（如 `2025-01-15T09:00:00+08:00`），插件内部转 UTC 存储。
+
+## 已知限制
+
+- 重复事件（RRULE）不展开：calendar_list / calendar_search 返回的是原始事件时间与 `rrule` 字段，重复实例需要模型自行按 rrule 计算。
+- 不做 OAuth：仅支持 Basic 认证（应用专用密码），不支持 Google / iCloud 的 OAuth 登录流程。
+- 时区规则：带 TZID（命名时区）的事件输出会转成 UTC（Z）；全天边界、夏令时等复杂时区规则不做精细化处理。
+- 无设置页 UI：本轮为 node 半身，配置只走 cordis.patch.yml，不提供 Web 设置页。
+- 日历发现：iCloud 需手动填完整日历集合 URL；不做 principal 自动发现与多日历选择。
+- 取消/超时：工具依赖 timeoutMs（60 秒）做整体超时，不在单次网络请求上透传 AbortSignal。
+
+## 开发
+
+```bash
+pnpm install
+pnpm test   # 构建 + node --test
+```
+
+构建产物在 `lib/`，测试在 `test/*.test.mjs`（不依赖真实账号）。

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# dsh-calendar 组合包补丁：把日历工具插件行插入 profile。
+# 本补丁按 id 覆盖；用户应在自己 profile 的 cordis.patch.yml 里覆盖本行的整个
+# config（见 README 的配置示例）。配置缺失时插件仍会加载，但每个工具在调用时
+# 会抛出带中文指引的错误，提示补全配置后重启。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: calendar
+#     name: 'dsh-calendar'
+#     config:
+#       provider: google              # google | icloud | nextcloud | custom
+#       username: you@gmail.com       # CalDAV 账号（Google/iCloud 用账号邮箱）
+#       calendarId: you@gmail.com     # google：日历 ID（通常是你的邮箱地址）
+#       # password: xxxx              # 应用专用密码；推荐改用环境变量 DSH_CALENDAR_PASSWORD
+#
+- insert:
+    - id: calendar
+      name: 'dsh-calendar'
+      config:
+        provider: custom

package/lib/caldav.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CalDAV 访问层：用 tsdav 客户端对单个日历集合做 查询/新建/更新/删除。
+ * 直接用集合 URL 操作（createDAVClient 不带 defaultAccountType，跳过服务发现）。
+ *
+ * @module dsh-calendar/caldav
+ */
+import type { ResolvedConfig } from './config.js';
+import { type CalendarEvent, type EventFields } from './ical.js';
+/** CalDAV 操作错误：带中文指引。 */
+export declare class CalDAVError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** 对单个日历集合的封装。 */
+export declare class CalendarService {
+    private readonly config;
+    private readonly collectionUrl;
+    private clientPromise?;
+    constructor(config: ResolvedConfig);
+    private client;
+    private calendar;
+    /** 列出某时间段内的事件（不展开 RRULE）。 */
+    list(startIso: string, endIso: string): Promise<CalendarEvent[]>;
+    /** 列出全部事件（客户端过滤用）。 */
+    all(): Promise<CalendarEvent[]>;
+    private toEvents;
+    /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
+    private findObject;
+    /** 新建事件，返回带 href/uid 的事件。 */
+    create(fields: EventFields): Promise<CalendarEvent>;
+    /** 按 uid 更新事件；未提供的字段保留原值。 */
+    update(uid: string, changes: Partial<EventFields>): Promise<CalendarEvent>;
+    /** 按 uid 删除事件。 */
+    delete(uid: string): Promise<{
+        uid: string;
+        href: string;
+    }>;
+}

package/lib/caldav.js

@@ -0,0 +1,212 @@
+/**
+ * CalDAV 访问层：用 tsdav 客户端对单个日历集合做 查询/新建/更新/删除。
+ * 直接用集合 URL 操作（createDAVClient 不带 defaultAccountType，跳过服务发现）。
+ *
+ * @module dsh-calendar/caldav
+ */
+import { createDAVClient } from 'tsdav';
+import { buildICalString, generateUid, parseEventFromICal, } from './ical.js';
+/** CalDAV 操作错误：带中文指引。 */
+export class CalDAVError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'CalDAVError';
+        this.status = status;
+    }
+}
+function ensureTrailingSlash(value) {
+    return value.endsWith('/') ? value : value + '/';
+}
+function normalizeUrl(value) {
+    const trimmed = value.trim();
+    return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
+/** 把底层错误翻译成中文指引；识别 401/403 提示应用专用密码。 */
+function translateError(error, action) {
+    const message = error instanceof Error ? error.message : String(error);
+    const status = error?.status;
+    if (status === 401 || status === 403 || /401|403/.test(message)) {
+        return new CalDAVError('账号认证失败（401/403）：请检查应用专用密码是否正确生成——' +
+            'Google 需在账号安全里创建「应用专用密码」，iCloud 需在 appleid.apple.com 创建 app 专用密码，' +
+            '不能用登录密码。请在 profile 的 cordis.patch.yml 覆盖 calendar 行或设置环境变量 DSH_CALENDAR_PASSWORD 后重启。', status ?? (/401/.test(message) ? 401 : 403));
+    }
+    return new CalDAVError(action + ' 失败：' + message, status);
+}
+/** 对单个日历集合的封装。 */
+export class CalendarService {
+    config;
+    collectionUrl;
+    clientPromise;
+    constructor(config) {
+        this.config = config;
+        this.collectionUrl = ensureTrailingSlash(config.caldavUrl);
+    }
+    client() {
+        this.clientPromise ??= createDAVClient({
+            serverUrl: this.config.caldavUrl,
+            credentials: { username: this.config.username, password: this.config.password },
+            authMethod: 'Basic',
+        });
+        return this.clientPromise;
+    }
+    calendar() {
+        return { url: this.collectionUrl };
+    }
+    /** 列出某时间段内的事件（不展开 RRULE）。 */
+    async list(startIso, endIso) {
+        try {
+            const client = await this.client();
+            const objects = await client.fetchCalendarObjects({
+                calendar: this.calendar(),
+                timeRange: { start: startIso, end: endIso },
+                urlFilter: (url) => typeof url === 'string' && url.length > 0,
+            });
+            return this.toEvents(objects);
+        }
+        catch (error) {
+            throw translateError(error, '读取日历');
+        }
+    }
+    /** 列出全部事件（客户端过滤用）。 */
+    async all() {
+        try {
+            const client = await this.client();
+            const objects = await client.fetchCalendarObjects({
+                calendar: this.calendar(),
+                urlFilter: (url) => typeof url === 'string' && url.length > 0,
+            });
+            return this.toEvents(objects);
+        }
+        catch (error) {
+            throw translateError(error, '读取日历');
+        }
+    }
+    toEvents(objects) {
+        const events = [];
+        for (const object of objects) {
+            const event = parseEventFromICal(String(object.data ?? ''), object.url, object.etag);
+            if (event !== null)
+                events.push(event);
+        }
+        return events;
+    }
+    /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
+    async findObject(uid) {
+        const client = await this.client();
+        const target = normalizeUrl(uid);
+        const objects = await client.fetchCalendarObjects({
+            calendar: this.calendar(),
+            urlFilter: (url) => normalizeUrl(url) === target,
+        });
+        return objects.find((object) => normalizeUrl(object.url) === target);
+    }
+    /** 新建事件，返回带 href/uid 的事件。 */
+    async create(fields) {
+        const iCalString = buildICalString(fields);
+        const filename = (fields.icalUid ?? generateUid()) + '.ics';
+        try {
+            const client = await this.client();
+            const response = await client.createCalendarObject({
+                calendar: this.calendar(),
+                iCalString,
+                filename,
+            });
+            assertOk(response, '新建事件');
+        }
+        catch (error) {
+            if (error instanceof CalDAVError)
+                throw error;
+            throw translateError(error, '新建事件');
+        }
+        const href = new URL(filename, this.collectionUrl).href;
+        const event = parseEventFromICal(iCalString, href);
+        if (event === null)
+            throw new CalDAVError('新建事件失败：生成的 iCal 无法解析');
+        return event;
+    }
+    /** 按 uid 更新事件；未提供的字段保留原值。 */
+    async update(uid, changes) {
+        let object;
+        try {
+            object = await this.findObject(uid);
+        }
+        catch (error) {
+            throw translateError(error, '查找事件');
+        }
+        if (object === undefined) {
+            throw new CalDAVError('找不到 uid 对应的事件：请用 calendar_list 或 calendar_search 重新获取最新 uid，' +
+                '该事件可能已被删除或 uid 已过期。');
+        }
+        const existing = parseEventFromICal(String(object.data ?? ''), object.url, object.etag);
+        const start = changes.start ?? existing?.start;
+        const end = changes.end ?? existing?.end;
+        if (start === undefined || end === undefined) {
+            throw new CalDAVError('无法确定事件的开始/结束时间：请同时提供 start 与 end。');
+        }
+        const merged = {
+            summary: changes.summary ?? existing?.summary ?? '',
+            start,
+            end,
+            ...(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,
+            ...(existing?.icalUid !== undefined ? { icalUid: existing.icalUid } : {}),
+        };
+        const iCalString = buildICalString(merged);
+        try {
+            const client = await this.client();
+            const response = await client.updateCalendarObject({
+                calendarObject: { url: object.url, etag: object.etag, data: iCalString },
+            });
+            assertOk(response, '更新事件');
+        }
+        catch (error) {
+            if (error instanceof CalDAVError)
+                throw error;
+            throw translateError(error, '更新事件');
+        }
+        const event = parseEventFromICal(iCalString, object.url, object.etag);
+        if (event === null)
+            throw new CalDAVError('更新事件失败：生成的 iCal 无法解析');
+        return event;
+    }
+    /** 按 uid 删除事件。 */
+    async delete(uid) {
+        let object;
+        try {
+            object = await this.findObject(uid);
+        }
+        catch (error) {
+            throw translateError(error, '查找事件');
+        }
+        if (object === undefined) {
+            throw new CalDAVError('找不到 uid 对应的事件：请用 calendar_list 或 calendar_search 重新获取最新 uid，' +
+                '该事件可能已被删除或 uid 已过期。');
+        }
+        try {
+            const client = await this.client();
+            const response = await client.deleteCalendarObject({
+                calendarObject: { url: object.url, etag: object.etag },
+            });
+            assertOk(response, '删除事件');
+        }
+        catch (error) {
+            if (error instanceof CalDAVError)
+                throw error;
+            throw translateError(error, '删除事件');
+        }
+        return { uid: object.url, href: object.url };
+    }
+}
+/** 校验 HTTP 响应，把 401/403 与其它非 2xx 转成中文错误。 */
+function assertOk(response, action) {
+    if (response.status === 401 || response.status === 403) {
+        throw new CalDAVError('账号认证失败（' + response.status + '）：请检查应用专用密码是否正确生成——' +
+            'Google 需在账号安全里创建「应用专用密码」，iCloud 需在 appleid.apple.com 创建 app 专用密码，' +
+            '不能用登录密码。请在 profile 的 cordis.patch.yml 覆盖 calendar 行或设置环境变量 DSH_CALENDAR_PASSWORD 后重启。', response.status);
+    }
+    if (!response.ok) {
+        throw new CalDAVError(action + ' 失败：服务器返回 ' + response.status + ' ' + response.statusText, response.status);
+    }
+}

package/lib/config.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 日历插件配置解析：provider 预设 + 手填 URL，全部在调用时惰性解析。
+ * 配置缺失绝不阻止插件加载，只在工具 execute 时抛出带中文指引的错误。
+ *
+ * @module dsh-calendar/config
+ */
+/** 支持的 provider 预设。 */
+export type CalendarProvider = 'google' | 'icloud' | 'nextcloud' | 'custom';
+/** 插件配置：可在 profile 的 cordis.patch.yml 覆盖 calendar 行的整个 config。 */
+export interface CalendarConfig {
+    /** provider 预设；默认 custom。 */
+    provider?: CalendarProvider;
+    /** 完整日历集合 URL；custom / icloud 必填，google / nextcloud 可由此手填覆盖预设。 */
+    caldavUrl?: string;
+    /** CalDAV 账号（Google / iCloud 用账号邮箱）。 */
+    username?: string;
+    /** 密码；支持环境变量 DSH_CALENDAR_PASSWORD。Google / iCloud 请用应用专用密码。 */
+    password?: string;
+    /** google：日历 ID（通常是你的邮箱地址）。 */
+    calendarId?: string;
+    /** nextcloud：主机，如 https://cloud.example.com。 */
+    host?: string;
+    /** nextcloud：用户名。 */
+    user?: string;
+    /** nextcloud：日历名。 */
+    calendar?: string;
+}
+/** 解析完成、可直接建客户端的配置。 */
+export interface ResolvedConfig {
+    provider: CalendarProvider;
+    caldavUrl: string;
+    username: string;
+    password: string;
+}
+/** 预设端点常量。 */
+export declare const GOOGLE_CALDAV_PREFIX = "https://apidata.googleusercontent.com/caldav/v2/";
+export declare const ICLOUD_CALDAV_URL = "https://caldav.icloud.com";
+export declare const NEXTCLOUD_PATH = "/remote.php/dav/calendars/";
+/** 配置错误：带中文指引，模型和用户都能读。 */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * 解析配置为可用的 caldavUrl + 凭证。配置缺失抛出 ConfigError（中文指引）。
+ * @param config - 插件 config（可能 undefined）。
+ * @param env - 环境变量来源（测试可注入）。
+ */
+export declare function resolveConfig(config: CalendarConfig | undefined, env?: NodeJS.ProcessEnv): ResolvedConfig;
+/** 依据 provider 预设或手填字段拼出日历集合 URL。 */
+export declare function buildCaldavUrl(config: CalendarConfig, provider: CalendarProvider): string;

package/lib/config.js

@@ -0,0 +1,83 @@
+/**
+ * 日历插件配置解析：provider 预设 + 手填 URL，全部在调用时惰性解析。
+ * 配置缺失绝不阻止插件加载，只在工具 execute 时抛出带中文指引的错误。
+ *
+ * @module dsh-calendar/config
+ */
+/** 预设端点常量。 */
+export const GOOGLE_CALDAV_PREFIX = 'https://apidata.googleusercontent.com/caldav/v2/';
+export const ICLOUD_CALDAV_URL = 'https://caldav.icloud.com';
+export const NEXTCLOUD_PATH = '/remote.php/dav/calendars/';
+/** 配置错误：带中文指引，模型和用户都能读。 */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+const PROVIDERS = ['google', 'icloud', 'nextcloud', 'custom'];
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}
+function normalizeProvider(value) {
+    if (value === undefined || value === null || value === '')
+        return 'custom';
+    if (typeof value === 'string' && PROVIDERS.includes(value)) {
+        return value;
+    }
+    throw new ConfigError('dsh-calendar 的 provider 取值不合法：只支持 google / icloud / nextcloud / custom。' +
+        '请在 profile 的 cordis.patch.yml 覆盖 calendar 行的 provider 并重启。');
+}
+/**
+ * 解析配置为可用的 caldavUrl + 凭证。配置缺失抛出 ConfigError（中文指引）。
+ * @param config - 插件 config（可能 undefined）。
+ * @param env - 环境变量来源（测试可注入）。
+ */
+export function resolveConfig(config, env = process.env) {
+    const provider = normalizeProvider(config?.provider);
+    const username = nonEmpty(config?.username);
+    const password = nonEmpty(config?.password) ?? nonEmpty(env.DSH_CALENDAR_PASSWORD);
+    if (username === undefined) {
+        throw new ConfigError('dsh-calendar 未配置 username：请在 profile 的 cordis.patch.yml 覆盖 calendar 行的 config，' +
+            '填上 CalDAV 账号（Google / iCloud 为账号邮箱）后重启。');
+    }
+    if (password === undefined) {
+        throw new ConfigError('dsh-calendar 未配置密码：请设置环境变量 DSH_CALENDAR_PASSWORD，' +
+            '或在 profile 的 cordis.patch.yml 覆盖 calendar 行的 password（Google / iCloud 请用应用专用密码）后重启。');
+    }
+    const caldavUrl = buildCaldavUrl(config ?? {}, provider);
+    return { provider, caldavUrl, username, password };
+}
+/** 依据 provider 预设或手填字段拼出日历集合 URL。 */
+export function buildCaldavUrl(config, provider) {
+    const explicit = nonEmpty(config.caldavUrl);
+    if (explicit !== undefined)
+        return explicit;
+    if (provider === 'google') {
+        const calendarId = nonEmpty(config.calendarId);
+        if (calendarId === undefined) {
+            throw new ConfigError('dsh-calendar 的 provider=google 需要 calendarId（日历 ID，通常是你的邮箱地址）：' +
+                '请在 profile 的 cordis.patch.yml 覆盖 calendar 行的 calendarId 并重启。');
+        }
+        return GOOGLE_CALDAV_PREFIX + encodeURIComponent(calendarId) + '/events';
+    }
+    if (provider === 'nextcloud') {
+        const host = nonEmpty(config.host);
+        const user = nonEmpty(config.user);
+        const calendar = nonEmpty(config.calendar);
+        if (host === undefined || user === undefined || calendar === undefined) {
+            throw new ConfigError('dsh-calendar 的 provider=nextcloud 需要 host、user、calendar 三个字段：' +
+                '请在 profile 的 cordis.patch.yml 覆盖 calendar 行并重启。');
+        }
+        return trimTrailingSlash(host) + NEXTCLOUD_PATH + encodeURIComponent(user) + '/' + encodeURIComponent(calendar) + '/';
+    }
+    if (provider === 'icloud') {
+        throw new ConfigError('dsh-calendar 的 provider=icloud 需要完整日历集合 URL：请在 icloud.com 的日历设置里找到具体日历的 CalDAV 地址，' +
+            '填入 profile 的 cordis.patch.yml 覆盖 calendar 行的 caldavUrl（形如 ' + ICLOUD_CALDAV_URL + '/<用户ID>/calendars/<日历ID>/）后重启。');
+    }
+    throw new ConfigError('dsh-calendar 未配置 caldavUrl：provider=custom 时需提供完整日历集合 URL，' +
+        '请在 profile 的 cordis.patch.yml 覆盖 calendar 行的 caldavUrl 并重启。');
+}

package/lib/ical.d.ts

@@ -0,0 +1,53 @@
+/**
+ * iCal 解析与生成：用 ical.js 处理 VEVENT 的字段提取与 round-trip 序列化。
+ * 输入输出统一 ISO 8601（含时区偏移）：全天事件用 YYYY-MM-DD，定时事件转 UTC（Z）。
+ *
+ * @module dsh-calendar/ical
+ */
+/** 一个暴露给模型的日历事件。 */
+export interface CalendarEvent {
+    /** 稳定标识（CalDAV href），calendar_update / calendar_delete 用它。 */
+    uid: string;
+    /** 与 uid 相同的完整对象 URL，便于调试。 */
+    href: string;
+    /** iCal 里的 UID 原始值（可能为空）。 */
+    icalUid?: string;
+    /** 服务器 ETag（内部用于并发安全更新）。 */
+    etag?: string;
+    summary: string;
+    description?: string;
+    location?: string;
+    /** 开始时间，ISO 8601（定时事件为 UTC，全天为 YYYY-MM-DD）。 */
+    start: string;
+    /** 结束时间，同上；无 DTEND/DURATION 时等于 start。 */
+    end: string;
+    allDay: boolean;
+    /** 重复规则原样返回，不展开（见 README 已知限制）。 */
+    rrule?: string;
+    status?: string;
+    url?: string;
+    created?: string;
+    lastModified?: string;
+}
+/** 新建 / 更新事件时需要的字段。 */
+export interface EventFields {
+    summary: string;
+    start: string;
+    end: string;
+    description?: string;
+    location?: string;
+    allDay?: boolean;
+    /** iCal UID；创建时缺省则自动生成，更新时用于保留原 UID。 */
+    icalUid?: string;
+}
+/**
+ * 解析一段 iCal 文本中的首个 VEVENT 为 CalendarEvent；解析失败返回 null。
+ * @param data - iCal 文本（通常来自服务器的 calendar-data）。
+ * @param href - CalDAV 对象 href，作为稳定 uid。
+ * @param etag - 服务器 ETag。
+ */
+export declare function parseEventFromICal(data: string, href: string, etag?: string): CalendarEvent | null;
+/** 生成随机 iCal UID（带 host 后缀，形如 UUID）。 */
+export declare function generateUid(): string;
+/** 把字段生成一段完整 iCal 文本（单个 VEVENT）。 */
+export declare function buildICalString(fields: EventFields): string;

package/lib/ical.js

@@ -0,0 +1,135 @@
+/**
+ * iCal 解析与生成：用 ical.js 处理 VEVENT 的字段提取与 round-trip 序列化。
+ * 输入输出统一 ISO 8601（含时区偏移）：全天事件用 YYYY-MM-DD，定时事件转 UTC（Z）。
+ *
+ * @module dsh-calendar/ical
+ */
+import { randomUUID } from 'node:crypto';
+import ICAL from 'ical.js';
+function pad(value) {
+    return value < 10 ? '0' + value : String(value);
+}
+function isDateOnly(value) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value);
+}
+/** 把任意 hydrated 值安全转成字符串。 */
+function asString(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && 'toICALString' in value) {
+        const rendered = value.toICALString();
+        return typeof rendered === 'string' ? rendered : undefined;
+    }
+    return String(value);
+}
+/** ICAL.Time -> ISO 8601：全天 YYYY-MM-DD，定时转 UTC（Z，去毫秒）。 */
+function icalTimeToIso(time) {
+    if (time.isDate) {
+        return pad(time.year) + '-' + pad(time.month) + '-' + pad(time.day);
+    }
+    return time.toJSDate().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+function timePropertyValue(vevent, name) {
+    const value = vevent.getFirstPropertyValue(name);
+    return value instanceof ICAL.Time ? value : undefined;
+}
+/**
+ * 解析一段 iCal 文本中的首个 VEVENT 为 CalendarEvent；解析失败返回 null。
+ * @param data - iCal 文本（通常来自服务器的 calendar-data）。
+ * @param href - CalDAV 对象 href，作为稳定 uid。
+ * @param etag - 服务器 ETag。
+ */
+export function parseEventFromICal(data, href, etag) {
+    let vcal;
+    try {
+        vcal = new ICAL.Component(ICAL.parse(data));
+    }
+    catch {
+        return null;
+    }
+    const vevent = vcal.getFirstSubcomponent('vevent');
+    if (vevent === null)
+        return null;
+    const icalUid = asString(vevent.getFirstPropertyValue('uid'));
+    const summary = asString(vevent.getFirstPropertyValue('summary')) ?? '';
+    const description = asString(vevent.getFirstPropertyValue('description'));
+    const location = asString(vevent.getFirstPropertyValue('location'));
+    const status = asString(vevent.getFirstPropertyValue('status'));
+    const url = asString(vevent.getFirstPropertyValue('url'));
+    const created = timePropertyValue(vevent, 'created');
+    const lastModified = timePropertyValue(vevent, 'last-modified');
+    const dtstartProp = vevent.getFirstProperty('dtstart');
+    const dtstart = dtstartProp === null ? undefined : (dtstartProp.getFirstValue() instanceof ICAL.Time ? dtstartProp.getFirstValue() : undefined);
+    if (dtstart === undefined)
+        return null;
+    const dtendProp = vevent.getFirstProperty('dtend');
+    const dtend = dtendProp === null ? undefined : (dtendProp.getFirstValue() instanceof ICAL.Time ? dtendProp.getFirstValue() : undefined);
+    const duration = vevent.getFirstPropertyValue('duration');
+    const start = icalTimeToIso(dtstart);
+    const allDay = dtstart.isDate === true;
+    let end = dtend === undefined ? undefined : icalTimeToIso(dtend);
+    if (end === undefined && duration instanceof ICAL.Duration) {
+        const endTime = dtstart.clone();
+        endTime.addDuration(duration);
+        end = icalTimeToIso(endTime);
+    }
+    if (end === undefined)
+        end = start;
+    const rruleValue = vevent.getFirstPropertyValue('rrule');
+    const rrule = rruleValue instanceof ICAL.Recur ? rruleValue.toString() : undefined;
+    const event = {
+        uid: href,
+        href,
+        summary,
+        start,
+        end,
+        allDay,
+        ...(icalUid !== undefined ? { icalUid } : {}),
+        ...(etag !== undefined ? { etag } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(location !== undefined ? { location } : {}),
+        ...(rrule !== undefined ? { rrule } : {}),
+        ...(status !== undefined ? { status } : {}),
+        ...(url !== undefined ? { url } : {}),
+        ...(created !== undefined ? { created: icalTimeToIso(created) } : {}),
+        ...(lastModified !== undefined ? { lastModified: icalTimeToIso(lastModified) } : {}),
+    };
+    return event;
+}
+/** 生成随机 iCal UID（带 host 后缀，形如 UUID）。 */
+export function generateUid() {
+    return randomUUID();
+}
+/** 把字段生成一段完整 iCal 文本（单个 VEVENT）。 */
+export function buildICalString(fields) {
+    const vcal = new ICAL.Component('vcalendar');
+    const vevent = new ICAL.Component('vevent');
+    vevent.addPropertyWithValue('uid', fields.icalUid ?? generateUid());
+    vevent.addPropertyWithValue('summary', fields.summary);
+    const start = parseTime(fields.start, fields.allDay === true || isDateOnly(fields.start));
+    const end = parseTime(fields.end, fields.allDay === true || isDateOnly(fields.end));
+    vevent.addPropertyWithValue('dtstart', start);
+    vevent.addPropertyWithValue('dtend', end);
+    if (fields.description !== undefined && fields.description !== '') {
+        vevent.addPropertyWithValue('description', fields.description);
+    }
+    if (fields.location !== undefined && fields.location !== '') {
+        vevent.addPropertyWithValue('location', fields.location);
+    }
+    vcal.addSubcomponent(vevent);
+    return vcal.toString();
+}
+/** 把 ISO 字符串解析成 ICAL.Time（全天 YYYY-MM-DD 或转 UTC 的定时时间）。 */
+function parseTime(value, allDay) {
+    if (allDay || isDateOnly(value)) {
+        return ICAL.Time.fromDateString(value);
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error('时间格式不合法：' + value + '（应为 ISO 8601，含时区偏移，如 2025-01-01T09:00:00+08:00）');
+    }
+    // 用 UTC 瞬间构造，序列化为带 Z 的稳定形式，避免时区歧义。
+    return ICAL.Time.fromJSDate(date, true);
+}

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * dsh-calendar —— CalDAV 日历工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：把五个面向模型的工具（calendar_list / calendar_create /
+ * calendar_update / calendar_delete / calendar_search）注册进宿主进程的工具注册表。
+ * 配置缺失时插件照常加载，工具在 execute 时才抛出带中文指引的错误。
+ *
+ * @module dsh-calendar
+ */
+import { type CalendarConfig } from './config.js';
+import { type CalendarToolDefinition } from './tools.js';
+/** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
+export interface CalendarPluginContext {
+    tools: {
+        register(definition: CalendarToolDefinition): () => void;
+    };
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：惰性解析配置并注册五个日历工具。
+ * @param ctx - 宿主上下文（至少含 tools.register）。
+ * @param config - 插件配置（可缺省）。
+ */
+export declare function apply(ctx: CalendarPluginContext, config?: CalendarConfig | null): void;
+export default apply;
+export * from './parameters.js';
+export * from './config.js';
+export * from './ical.js';
+export * from './caldav.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,41 @@
+/**
+ * dsh-calendar —— CalDAV 日历工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：把五个面向模型的工具（calendar_list / calendar_create /
+ * calendar_update / calendar_delete / calendar_search）注册进宿主进程的工具注册表。
+ * 配置缺失时插件照常加载，工具在 execute 时才抛出带中文指引的错误。
+ *
+ * @module dsh-calendar
+ */
+import { resolveConfig } from './config.js';
+import { buildCalendarTools } from './tools.js';
+/**
+ * 插件入口：惰性解析配置并注册五个日历工具。
+ * @param ctx - 宿主上下文（至少含 tools.register）。
+ * @param config - 插件配置（可缺省）。
+ */
+export function apply(ctx, config) {
+    const cfg = config ?? {};
+    try {
+        resolveConfig(cfg);
+    }
+    catch (error) {
+        console.warn('dsh-calendar: ' + (error instanceof Error ? error.message : String(error)));
+    }
+    const disposers = [];
+    for (const definition of buildCalendarTools(cfg)) {
+        disposers.push(ctx.tools.register(definition));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}
+export default apply;
+export * from './parameters.js';
+export * from './config.js';
+export * from './ical.js';
+export * from './caldav.js';
+export * from './tools.js';

package/lib/parameters.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 工具参数 DSL 编译：把作者友好的参数描述编译成注册所需的【编译好的 JSON Schema】。
+ *
+ * 这是社区插件必须遵守的坑：ctx.tools.register 的 parameters 字段必须是
+ * { type: 'object', properties: {...}, required?: [...] } 形式的 JSON Schema，
+ * 绝不能塞原始 DSL（{ summary: { type: 'string' } } 这种），否则标准模式下 DeepSeek
+ * API 会以 "schema must be a JSON Schema of 'type: object'" 拒绝请求。
+ *
+ * @module dsh-calendar/parameters
+ */
+/** 单个参数属性支持的类型。 */
+export type ParameterType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+/** 单个参数属性的 DSL 描述。 */
+export interface ParameterSpec {
+    type: ParameterType;
+    /** 是否为必填参数；编译进顶层 required 数组。 */
+    required?: boolean;
+    /** 人类可读描述，投影进 JSON Schema 的 description 注解。 */
+    description?: string;
+    /** 可选枚举约束（标量类型）。 */
+    enum?: readonly (string | number | boolean)[];
+    /** 数组元素的类型（type: 'array' 时生效）。 */
+    items?: Exclude<ParameterType, 'array' | 'object'>;
+}
+/** 参数 DSL 映射：键为参数名，值为属性描述。 */
+export type ParameterDsl = Record<string, ParameterSpec>;
+/** 编译后的 JSON Schema（object 根）。 */
+export interface CompiledParameters {
+    type: 'object';
+    properties: Record<string, Record<string, unknown>>;
+    required?: string[];
+}
+/**
+ * 把参数 DSL 编译成注册用的 JSON Schema。
+ * @param dsl - 参数描述映射。
+ * @returns 以 object 为根的编译后 schema。
+ */
+export declare function compileParameters(dsl: ParameterDsl): CompiledParameters;

package/lib/parameters.js

@@ -0,0 +1,36 @@
+/**
+ * 工具参数 DSL 编译：把作者友好的参数描述编译成注册所需的【编译好的 JSON Schema】。
+ *
+ * 这是社区插件必须遵守的坑：ctx.tools.register 的 parameters 字段必须是
+ * { type: 'object', properties: {...}, required?: [...] } 形式的 JSON Schema，
+ * 绝不能塞原始 DSL（{ summary: { type: 'string' } } 这种），否则标准模式下 DeepSeek
+ * API 会以 "schema must be a JSON Schema of 'type: object'" 拒绝请求。
+ *
+ * @module dsh-calendar/parameters
+ */
+/**
+ * 把参数 DSL 编译成注册用的 JSON Schema。
+ * @param dsl - 参数描述映射。
+ * @returns 以 object 为根的编译后 schema。
+ */
+export function compileParameters(dsl) {
+    const properties = {};
+    const required = [];
+    for (const [name, spec] of Object.entries(dsl)) {
+        const property = { type: spec.type };
+        if (spec.enum !== undefined)
+            property.enum = [...spec.enum];
+        if (spec.description !== undefined)
+            property.description = spec.description;
+        if (spec.type === 'array' && spec.items !== undefined) {
+            property.items = { type: spec.items };
+        }
+        properties[name] = property;
+        if (spec.required === true)
+            required.push(name);
+    }
+    const schema = { type: 'object', properties };
+    if (required.length > 0)
+        schema.required = required;
+    return schema;
+}

package/lib/tools.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 五个面向模型的日历工具：list / create / update / delete / search。
+ * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
+ *
+ * @module dsh-calendar/tools
+ */
+import { type CalendarConfig } from './config.js';
+/** 模型可见的内容块。 */
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+/** 注册给 ctx.tools.register 的原始工具定义（parameters 为编译好的 JSON Schema）。 */
+export interface CalendarToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    timeoutMs?: number;
+}
+/** 构建五个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
+export declare function buildCalendarTools(config: CalendarConfig | undefined): CalendarToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,266 @@
+/**
+ * 五个面向模型的日历工具：list / create / update / delete / search。
+ * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
+ *
+ * @module dsh-calendar/tools
+ */
+import { CalendarService } from './caldav.js';
+import { 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 optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined) {
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    }
+    return value;
+}
+function optionalBoolean(args, key) {
+    const value = args[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+function optionalInteger(args, key) {
+    const value = args[key];
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+function assertIsoTime(value, label) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+        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。');
+    }
+}
+function isoNoMillis(value) {
+    return value.replace(/\.\d{3}Z$/, 'Z');
+}
+function formatEvent(event) {
+    const range = event.allDay ? event.start + '（全天）' : event.start + ' ~ ' + event.end;
+    const extra = [event.location ? '地点：' + event.location : '', event.rrule ? '重复：' + event.rrule : '']
+        .filter(Boolean).join('；');
+    return '- ' + event.summary + '（' + range + '）' + (extra ? '，' + extra : '') + '，uid=' + event.uid;
+}
+function buildSearchFilter(query) {
+    const needle = query.toLowerCase();
+    return (event) => {
+        const haystack = [event.summary, event.description ?? '', event.location ?? '', event.icalUid ?? '']
+            .join(' ').toLowerCase();
+        return haystack.includes(needle);
+    };
+}
+/** 构建五个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
+export function buildCalendarTools(config) {
+    const service = () => new CalendarService(resolveConfig(config));
+    const list = {
+        name: 'calendar_list',
+        description: '列出某时间段内的日历事件（默认未来 7 天）。start/end 为 ISO 8601 时间（含时区偏移，如 2025-01-01T09:00:00+08:00），全天事件返回 YYYY-MM-DD。重复事件不展开，原始重复规则见每个事件的 rrule 字段。返回每个事件的稳定标识 uid，供 calendar_update / calendar_delete 使用。',
+        parameters: compileParameters({
+            start: { type: 'string', description: '起始时间（ISO 8601，含时区偏移）。缺省为当前时间（UTC）。' },
+            end: { type: 'string', description: '结束时间（ISO 8601，含时区偏移）。缺省为 start 后 7 天。' },
+        }),
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                    count: { type: 'integer' },
+                    start: { type: 'string' },
+                    end: { type: 'string' },
+                    events: { type: 'array', items: EVENT_SCHEMA },
+                },
+                required: ['count', 'events'],
+            },
+            render: (_args, value) => {
+                const result = value;
+                const lines = ['时间段 ' + result.start + ' ~ ' + result.end + ' 内共 ' + result.count + ' 个事件：'];
+                for (const event of result.events)
+                    lines.push(formatEvent(event));
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(args) {
+            const input = asRecord(args);
+            const now = new Date();
+            const defaultEnd = new Date(now.getTime() + 7 * 24 * 3600 * 1000);
+            const start = optionalString(input, 'start') ?? isoNoMillis(now.toISOString());
+            const end = optionalString(input, 'end') ?? isoNoMillis(defaultEnd.toISOString());
+            assertIsoTime(start, 'start');
+            assertIsoTime(end, 'end');
+            const events = await service().list(start, end);
+            return { count: events.length, start, end, events };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    const create = {
+        name: 'calendar_create',
+        description: '新建一个日历事件。summary 与 start、end（ISO 8601，含时区偏移）为必填；description、location、allDay 可选。全天事件 start/end 用 YYYY-MM-DD 或设置 allDay=true。成功返回新事件的稳定标识 uid。',
+        parameters: compileParameters({
+            summary: { type: 'string', required: true, description: '事件标题（必填）。' },
+            start: { type: 'string', required: true, description: '开始时间（ISO 8601，含时区偏移，必填）。' },
+            end: { type: 'string', required: true, description: '结束时间（ISO 8601，含时区偏移，必填）。' },
+            description: { type: 'string', description: '事件描述（可选）。' },
+            location: { type: 'string', description: '地点（可选）。' },
+            allDay: { type: 'boolean', description: '是否全天事件（可选，默认 false）。' },
+        }),
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+                properties: { created: EVENT_SCHEMA },
+                required: ['created'],
+            },
+            render: (_args, value) => {
+                const event = value.created;
+                return [{ type: 'text', text: '已新建事件：' + formatEvent(event) }];
+            },
+        },
+        async execute(args) {
+            const input = asRecord(args);
+            const summary = requiredString(input, 'summary', '事件标题');
+            const start = requiredString(input, 'start', '开始时间');
+            const end = requiredString(input, 'end', '结束时间');
+            assertIsoTime(start, 'start');
+            assertIsoTime(end, 'end');
+            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') } : {}),
+            };
+            const created = await service().create(fields);
+            return { created };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    const update = {
+        name: 'calendar_update',
+        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay 均可选，未提供的字段保留原值。',
+        parameters: compileParameters({
+            uid: { type: 'string', required: true, description: '事件稳定标识（来自 calendar_list / calendar_search 的 uid，必填）。' },
+            summary: { type: 'string', description: '新标题（可选）。' },
+            start: { type: 'string', description: '新开始时间（ISO 8601，可选）。' },
+            end: { type: 'string', description: '新结束时间（ISO 8601，可选）。' },
+            description: { type: 'string', description: '新描述（可选）。' },
+            location: { type: 'string', description: '新地点（可选）。' },
+            allDay: { type: 'boolean', description: '是否全天事件（可选）。' },
+        }),
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+                properties: { updated: EVENT_SCHEMA },
+                required: ['updated'],
+            },
+            render: (_args, value) => {
+                const event = value.updated;
+                return [{ type: 'text', text: '已更新事件：' + formatEvent(event) }];
+            },
+        },
+        async execute(args) {
+            const input = asRecord(args);
+            const uid = requiredString(input, 'uid', '事件 uid');
+            const changes = {};
+            const summary = optionalString(input, 'summary');
+            if (summary !== undefined)
+                changes.summary = summary;
+            const start = optionalString(input, 'start');
+            if (start !== undefined) {
+                assertIsoTime(start, 'start');
+                changes.start = start;
+            }
+            const end = optionalString(input, 'end');
+            if (end !== undefined) {
+                assertIsoTime(end, 'end');
+                changes.end = end;
+            }
+            const description = optionalString(input, 'description');
+            if (description !== undefined)
+                changes.description = description;
+            const location = optionalString(input, 'location');
+            if (location !== undefined)
+                changes.location = location;
+            const allDay = optionalBoolean(input, 'allDay');
+            if (allDay !== undefined)
+                changes.allDay = allDay;
+            const updated = await service().update(uid, changes);
+            return { updated };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    const remove = {
+        name: 'calendar_delete',
+        description: '按 uid 删除日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。删除不可撤销。',
+        parameters: compileParameters({
+            uid: { type: 'string', required: true, description: '事件稳定标识（来自 calendar_list / calendar_search 的 uid，必填）。' },
+        }),
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                    deleted: { type: 'boolean' },
+                    uid: { type: 'string' },
+                    href: { type: 'string' },
+                },
+                required: ['deleted', 'uid'],
+            },
+            render: (_args, value) => {
+                const result = value;
+                return [{ type: 'text', text: '已删除事件：uid=' + result.uid }];
+            },
+        },
+        async execute(args) {
+            const input = asRecord(args);
+            const uid = requiredString(input, 'uid', '事件 uid');
+            const result = await service().delete(uid);
+            return { deleted: true, uid: result.uid, href: result.href };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    const search = {
+        name: 'calendar_search',
+        description: '按关键词搜索日历事件（客户端过滤：匹配标题、描述、地点与 iCal UID，不区分大小写）。query 必填，limit 可选（默认 50）。返回每个事件的稳定标识 uid。',
+        parameters: compileParameters({
+            query: { type: 'string', required: true, description: '搜索关键词（必填）。' },
+            limit: { type: 'integer', description: '最多返回条数（可选，默认 50）。' },
+        }),
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                    query: { type: 'string' },
+                    count: { type: 'integer' },
+                    events: { type: 'array', items: EVENT_SCHEMA },
+                },
+                required: ['query', 'count', 'events'],
+            },
+            render: (_args, value) => {
+                const result = value;
+                const lines = ['搜索「' + result.query + '」命中 ' + result.count + ' 个事件：'];
+                for (const event of result.events)
+                    lines.push(formatEvent(event));
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(args) {
+            const input = asRecord(args);
+            const query = requiredString(input, 'query', '搜索关键词');
+            const limit = optionalInteger(input, 'limit') ?? 50;
+            const all = await service().all();
+            const matched = all.filter(buildSearchFilter(query)).slice(0, limit);
+            return { query, count: matched.length, events: matched };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    return [list, create, update, remove, search];
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dsh-calendar",
+  "version": "0.1.0",
+  "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"
+}