dsh-calendar 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+> 完整历史（含详细改动说明）。README 只保留最近几个版本的一句话摘要。
+
+## 中文版
+
+- **0.5.4（2026-09-18）**：**修复**：①`calendar_update` 重建 VEVENT 会静默丢掉原事件的 ATTENDEE / ORGANIZER / EXDATE / STATUS / CATEGORIES / VALARM（改一次标题就删掉邀请人和提醒），现在改为在原始 VCALENDAR 上做字段级覆盖，并补齐 RFC 5545 必需的 VERSION / PRODID / UID / DTSTAMP；②RECURRENCE-ID 覆盖实例被忽略（被单独改期的实例按原时间+旧标题返回，或被 EXDATE 排掉后整条消失），现在建覆盖映射并在展开时替换对应实例；③`calendar_create` 返回本地拼的 uid 而忽略服务器 `Location`，导致 create 后 update 找不到事件（现在优先取 Location，缺失时回读确认），且 create 的 PUT body 补上 VERSION / PRODID / DTSTAMP。**优化**：重复事件展开预算耗尽时不再静默返回 0 条（DTSTART 在 2010 的每小时系列实测 680ms 且返回空），改为显式报错并提示缩小时间范围或补 COUNT/UNTIL；`calendar_search` 支持 `start` / `end` 并走 timeRange 查询（缺省用有界窗口），不再先整本下载再过滤。测试 68 → 79 项。
+- **0.5.3（2026-09-11）**：复验官方 Harness 0.1.5-rc.1，更新整套同载与真实服务验证记录；运行时代码未变。
+- **0.5.2（2026-09-08）**：补充官方 Harness 0.1.3-alpha.2 的安装、加载与真实 Google 工具调用验证，更新兼容性和 Node 版本要求；运行时代码与 0.5.0 相同。
+- **0.5.1（2026-09-08）**：补充真实 Google OAuth/CalDAV 读取验证、`calendar.readonly` 与 `calendar` 范围对比及 Testing 刷新令牌到期说明；运行时代码与 0.5.0 相同。
+- **0.5.0（2026-09-07）**：修复 Google CalDAV #2：新增 OAuth 凭据与环境变量配置、请求时刷新、取消与代理透传；健康检查区分 Basic/OAuth，修正误导的应用专用密码说明。保留其他服务的 Basic 认证。
+- **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。
+
+## English
+
+- **0.5.4 (2026-09-18)**: **Fixes**: (1) `calendar_update` rebuilt the VEVENT and silently dropped ATTENDEE / ORGANIZER / EXDATE / STATUS / CATEGORIES / VALARM — renaming an event deleted its guests and reminders; the update now does field-level replacement on the original VCALENDAR and fills in the RFC 5545 essentials (VERSION / PRODID / UID / DTSTAMP). (2) RECURRENCE-ID overrides were ignored: a moved instance came back with its old time and title, or disappeared entirely when an EXDATE removed the original slot; overrides are now mapped and substituted during expansion. (3) `calendar_create` returned a locally invented uid instead of the server `Location`, so a follow-up update could not find the event (Location is now preferred, with a read-back check when absent), and the create body now carries VERSION / PRODID / DTSTAMP. **Improvements**: an exhausted expansion budget no longer returns an empty result silently (an hourly series starting in 2010 took 680ms and returned nothing) but raises a clear error suggesting a narrower range or COUNT/UNTIL; `calendar_search` accepts `start`/`end` and queries by timeRange instead of downloading the whole calendar first. Tests 68 → 79.
+- **0.5.3 (2026-09-11)**: revalidate official Harness 0.1.5-rc.1 and refresh suite co-load and live-service evidence; runtime code is unchanged.
+- **0.5.2 (2026-09-08)**: document installation, loading and real Google tool execution in official Harness 0.1.3-alpha.2; update compatibility and Node requirements. Runtime code is unchanged from 0.5.0.
+- **0.5.1 (2026-09-08)**: document live Google OAuth/CalDAV read validation, the `calendar.readonly` versus `calendar` scope results and Testing refresh-token expiration. Runtime code is unchanged from 0.5.0.
+- **0.5.0 (2026-09-07)**: fix Google CalDAV #2 with OAuth configuration/environment credentials, request-time refresh, cancellation and proxy forwarding. Make health checks and error guidance authentication-aware; retain Basic authentication for other servers.
+- **0.4.0**: new `calendar_health` self-check (offline endpoint and credential configuration checks, not a connection test).
+- **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.

package/README.en.md

@@ -134,9 +134,9 @@ If your CalDAV server is not directly reachable from your network (some regional
 - `calendar_health`: offline provider, endpoint and Basic/OAuth credential-completeness checks; never displays secrets or connects to the server.
 - `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_update`: edit an event by uid (summary/start/end/description/location/allDay/rrule optional; omitted fields keep their original values, including the recurrence rule and original properties such as ATTENDEE / ORGANIZER / VALARM).
 - `calendar_delete`: delete an event by uid
-- `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).
+- `calendar_search`: search events by keyword within the `start`~`end` window (defaults to one year before/after now; 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.
 
@@ -147,21 +147,14 @@ Input and output are uniformly ISO 8601. Timed events are output in UTC (e.g. `2
 
 ## Changelog
 
-- **0.5.3 (2026-09-11)**: revalidate official Harness 0.1.5-rc.1 and refresh suite co-load and live-service evidence; runtime code is unchanged.
-- **0.5.2 (2026-09-08)**: document installation, loading and real Google tool execution in official Harness 0.1.3-alpha.2; update compatibility and Node requirements. Runtime code is unchanged from 0.5.0.
-- **0.5.1 (2026-09-08)**: document live Google OAuth/CalDAV read validation, the `calendar.readonly` versus `calendar` scope results and Testing refresh-token expiration. Runtime code is unchanged from 0.5.0.
-- **0.5.0 (2026-09-07)**: fix Google CalDAV #2 with OAuth configuration/environment credentials, request-time refresh, cancellation and proxy forwarding. Make health checks and error guidance authentication-aware; retain Basic authentication for other servers.
-- **0.4.0**: new `calendar_health` self-check (offline endpoint and credential configuration checks, not a connection test).
-- **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.
+- **0.5.4 (2026-09-18)**: fixes for `calendar_update` dropping ATTENDEE/VALARM and other original properties, ignored RECURRENCE-ID overrides, `calendar_create` inventing a uid instead of using the server Location, and silent empty expansion results; `calendar_search` gained a time range. 79 tests.
+- **0.5.3 (2026-09-11)**: revalidated against official Harness 0.1.5-rc.1 and refreshed co-load / live-service verification; runtime code unchanged.
+- **0.5.2 and earlier**: see [CHANGELOG.md](CHANGELOG.md).
 
 ## 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).
-- No single-instance edit/delete: calendar_update / calendar_delete operate on the whole recurring series (by uid); you cannot modify or delete just one occurrence (no RECURRENCE-ID instance-level operations).
+- Recurring event expansion: calendar_list expands RRULE by default via ICAL.RecurExpansion (`expand=true`), capped by `maxOccurrences`, and raises an explicit error when the iteration budget is exhausted; calendar_search only queries the `start`~`end` window (default one year before/after now) and still returns the original series (not expanded).
+- Single-instance reads vs edit/delete: calendar_list honors RECURRENCE-ID overrides when expanding (an occurrence separately rescheduled/retitled is returned with the override time and fields, including when the original instant is EXDATE-excluded); calendar_update / calendar_delete still operate on the whole recurring series (by uid) and cannot modify or delete just one occurrence.
 - OAuth credentials must be obtained beforehand: refresh-token authentication is supported, but there is no browser login UI / login CLI and runtime tokens are not written back to configuration.
 - Timezone rules: events with TZID (named timezone) are output converted to UTC (Z); all-day boundaries, DST, and other complex timezone rules are not handled finely.
 - No settings-page UI: this round is a node half-body; config only via cordis.patch.yml, no Web settings page.

package/README.md

@@ -158,9 +158,9 @@ Nextcloud / 自定义 Basic 服务：检查账号、密码或服务要求的应
 - `calendar_health`：离线检查服务商、日历集合地址与 Basic/OAuth 凭据完整性，不回显密钥、不发起网络连接。
 - `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_update`：按 uid 改事件（summary/start/end/description/location/allDay/rrule 可选，未提供保留原值；ATTENDEE、ORGANIZER、VALARM 等原始属性一并保留，重复规则不再丢失）
 - `calendar_delete`：按 uid 删事件
-- `calendar_search`：按关键词搜事件（客户端过滤标题/描述/地点/UID，不区分大小写；`limit` 默认 50、clamp 1-200，结果按开始时间排序）
+- `calendar_search`：按关键词搜事件（只查询 start~end 窗口内的事件，缺省为当前时间前后各 1 年；客户端过滤标题/描述/地点/UID，不区分大小写；`limit` 默认 50、clamp 1-200，结果按开始时间排序）
 
 事件稳定标识 `uid` 为 CalDAV href（完整对象 URL），`calendar_update` / `calendar_delete` 使用它。
 
@@ -170,25 +170,17 @@ Nextcloud / 自定义 Basic 服务：检查账号、密码或服务要求的应
 
 ## 版本记录
 
-- **0.5.3（2026-09-11）**：复验官方 Harness 0.1.5-rc.1，更新整套同载与真实服务验证记录；运行时代码未变。
-- **0.5.2（2026-09-08）**：补充官方 Harness 0.1.3-alpha.2 的安装、加载与真实 Google 工具调用验证，更新兼容性和 Node 版本要求；运行时代码与 0.5.0 相同。
-- **0.5.1（2026-09-08）**：补充真实 Google OAuth/CalDAV 读取验证、`calendar.readonly` 与 `calendar` 范围对比及 Testing 刷新令牌到期说明；运行时代码与 0.5.0 相同。
-- **0.5.0（2026-09-07）**：修复 Google CalDAV #2：新增 OAuth 凭据与环境变量配置、请求时刷新、取消与代理透传；健康检查区分 Basic/OAuth，修正误导的应用专用密码说明。保留其他服务的 Basic 认证。
-- **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。
-
+- **0.5.4（2026-09-18）**：修复 `calendar_update` 丢 ATTENDEE/VALARM 等原始属性、RECURRENCE-ID 覆盖实例被忽略、`calendar_create` 的 uid 不用服务器 Location、展开超限静默返回空；`calendar_search` 支持时间窗。测试 79 项。
+- **0.5.3（2026-09-11）**：复验官方 Harness 0.1.5-rc.1，更新同载与真实服务验证记录；运行时代码未变。
+- **0.5.2 及更早**：见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 已知限制
 
 - **网络可达性**：若无法直连，可用 `proxyUrl` 指定本机 HTTP 代理，或改用可直连的 CalDAV 端点。
 
 
-- 重复事件展开：calendar_list 默认用 ICAL.RecurExpansion 展开 RRULE（`expand=true`），受 `maxOccurrences` 封顶；calendar_search 仍返回原始系列（不展开）。
-- 不支持单次实例的改/删：calendar_update / calendar_delete 针对整个重复系列（按 uid 操作），无法只修改或删除某一次发生（不支持 RECURRENCE-ID 实例级操作）。
+- 重复事件展开：calendar_list 默认用 ICAL.RecurExpansion 展开 RRULE（`expand=true`），受 `maxOccurrences` 封顶，展开超出迭代预算时显式报错；calendar_search 只查 start~end 窗口（默认当前前后各 1 年），仍返回原始系列（不展开）。
+- 单次实例的读取与改/删：calendar_list 展开时识别 RECURRENCE-ID 覆盖实例（单独改期/改标题的实例按覆盖后的时间与字段返回，被 EXDATE 排除原时间的覆盖实例仍会返回）；calendar_update / calendar_delete 仍针对整个重复系列（按 uid 操作），无法只修改或删除某一次发生。
 - OAuth 凭据需要事先取得：支持刷新令牌认证，但不提供浏览器登录 UI / 登录 CLI，也不把运行时令牌写回配置文件。
 - 时区规则：带 TZID（命名时区）的事件输出会转成 UTC（Z）；全天边界、夏令时等复杂时区规则不做精细化处理。
 - 无设置页 UI：本轮为 node 半身，配置只走 cordis.patch.yml，不提供 Web 设置页。

package/lib/caldav.d.ts

@@ -24,8 +24,11 @@ export declare class CalendarService {
         expand?: boolean;
         maxOccurrences?: number;
     }, signal?: AbortSignal): Promise<CalendarEvent[]>;
-    /** 列出全部事件（客户端过滤用）。 */
-    all(signal?: AbortSignal): Promise<CalendarEvent[]>;
+    /** 列出全部（或 timeRange 窗口内）事件，供客户端过滤用。 */
+    all(signal?: AbortSignal, timeRange?: {
+        start: string;
+        end: string;
+    }): Promise<CalendarEvent[]>;
     private toEvents;
     /** 列出并展开：每个对象经 expandEventFromICal 展开为若干实例行。 */
     private toExpandedEvents;
@@ -33,6 +36,8 @@ export declare class CalendarService {
     private findObject;
     /** 新建事件，返回带 href/uid 的事件。 */
     create(fields: EventFields, signal?: AbortSignal): Promise<CalendarEvent>;
+    /** 解析 PUT 响应的 Location；取不到时回读一次确认，避免把本地猜测的 href 当成 uid。 */
+    private resolveCreatedHref;
     /** 按 uid 更新事件；未提供的字段保留原值。 */
     update(uid: string, changes: Partial<EventFields>, signal?: AbortSignal): Promise<CalendarEvent>;
     /** 按 uid 删除事件。 */

package/lib/caldav.js

@@ -7,7 +7,7 @@
 import { createDAVClient } from 'tsdav';
 import { createProxyFetch } from './proxy-fetch.js';
 import { createOAuthFetch, OAuthError } from './oauth.js';
-import { buildICalString, expandEventFromICal, generateUid, parseEventFromICal, } from './ical.js';
+import { buildICalString, expandEventFromICal, ExpansionLimitError, generateUid, parseEventFromICal, updateICalString, } from './ical.js';
 /** CalDAV 操作错误：带中文指引。 */
 export class CalDAVError extends Error {
     status;
@@ -34,6 +34,9 @@ function authenticationError(config, status) {
 function translateError(error, action, config) {
     if (error instanceof CalDAVError)
         return error;
+    // 展开超限是可操作的明确提示，不能被下面的 OAuth 通用文案覆盖。
+    if (error instanceof ExpansionLimitError)
+        return new CalDAVError(error.message);
     if (error instanceof OAuthError)
         return new CalDAVError(error.message, error.status);
     const message = error instanceof Error ? error.message : String(error);
@@ -101,14 +104,15 @@ export class CalendarService {
             throw translateError(error, '读取日历', this.config);
         }
     }
-    /** 列出全部事件（客户端过滤用）。 */
-    async all(signal) {
+    /** 列出全部（或 timeRange 窗口内）事件，供客户端过滤用。 */
+    async all(signal, timeRange) {
         signal?.throwIfAborted();
         try {
             const client = await this.client();
             signal?.throwIfAborted();
             const objects = await client.fetchCalendarObjects({
                 calendar: this.calendar(),
+                ...(timeRange !== undefined ? { timeRange } : {}),
                 urlFilter: (url) => typeof url === 'string' && url.length > 0,
                 ...(signal !== undefined ? { fetchOptions: { signal } } : {}),
             });
@@ -157,6 +161,8 @@ export class CalendarService {
         const icalUid = fields.icalUid ?? generateUid();
         const iCalString = buildICalString({ ...fields, icalUid });
         const filename = icalUid + '.ics';
+        // 本地 filename 只是 PUT 目标，服务器可以按自己的规则分配 href；先按本地猜测兜底。
+        let href = new URL(filename, this.collectionUrl).href;
         try {
             const client = await this.client();
             signal?.throwIfAborted();
@@ -168,6 +174,7 @@ export class CalendarService {
             });
             signal?.throwIfAborted();
             assertOk(response, '新建事件', this.config);
+            href = await this.resolveCreatedHref(response, filename, signal);
         }
         catch (error) {
             signal?.throwIfAborted();
@@ -175,12 +182,26 @@ export class CalendarService {
                 throw error;
             throw translateError(error, '新建事件', this.config);
         }
-        const href = new URL(filename, this.collectionUrl).href;
         const event = parseEventFromICal(iCalString, href);
         if (event === null)
             throw new CalDAVError('新建事件失败：生成的 iCal 无法解析');
         return event;
     }
+    /** 解析 PUT 响应的 Location；取不到时回读一次确认，避免把本地猜测的 href 当成 uid。 */
+    async resolveCreatedHref(response, filename, signal) {
+        const location = response.headers.get('location')?.trim();
+        if (location !== undefined && location !== '') {
+            try {
+                return new URL(location, this.collectionUrl).href;
+            }
+            catch {
+                // Location 不是合法 URL 时退回回读确认。
+            }
+        }
+        const guessed = new URL(filename, this.collectionUrl).href;
+        const confirmed = await this.findObject(guessed, signal);
+        return confirmed === undefined ? guessed : confirmed.url;
+    }
     /** 按 uid 更新事件；未提供的字段保留原值。 */
     async update(uid, changes, signal) {
         signal?.throwIfAborted();
@@ -217,7 +238,9 @@ export class CalendarService {
             ...(changes.rrule !== undefined ? { rrule: changes.rrule } : existing?.rrule !== undefined ? { rrule: existing.rrule } : {}),
             ...(existing?.icalUid !== undefined ? { icalUid: existing.icalUid } : {}),
         };
-        const iCalString = buildICalString(merged);
+        // 字段级覆盖：保留原 VCALENDAR/VEVENT 的 ATTENDEE、VALARM 等属性，只改显式给出的字段。
+        // 原 calendar-data 无法解析时回退到整条重建，保持旧的可用行为。
+        const iCalString = updateICalString(String(object.data ?? ''), changes) ?? buildICalString(merged);
         try {
             const client = await this.client();
             signal?.throwIfAborted();

package/lib/ical.d.ts

@@ -33,6 +33,10 @@ export interface CalendarEvent {
     created?: string;
     lastModified?: string;
 }
+/** 展开重复事件超出迭代预算：显式报错，避免把「没走到窗口」静默当成「窗口内没有实例」。 */
+export declare class ExpansionLimitError extends Error {
+    constructor(message: string);
+}
 /** 新建 / 更新事件时需要的字段。 */
 export interface EventFields {
     summary: string;
@@ -57,15 +61,30 @@ export declare function parseEventFromICal(data: string, href: string, etag?: st
  * 解析并（可选）展开一个 VEVENT：非重复事件原样返回（isOccurrence: false）；
  * 重复事件用 ICAL.RecurExpansion 在 [rangeStart, rangeEnd] 内展开，最多返回
  * maxOccurrences 个实例（isOccurrence: true + seriesStart）。
+ *
+ * 同一 VCALENDAR 里带 RECURRENCE-ID 的 VEVENT 是单次实例的覆盖（改期/改标题）：
+ * 展开时用覆盖 VEVENT 替换对应原实例；原实例被 EXDATE 排除或原时间在窗口外时，
+ * 只要覆盖后的实例落在窗口内仍单独返回，避免实例被静默丢弃。
  * @param data - iCal 文本。
  * @param href - CalDAV 对象 href，作为稳定 uid。
  * @param etag - 服务器 ETag。
  * @param rangeStart - 查询窗口起始（ISO 8601）。
  * @param rangeEnd - 查询窗口结束（ISO 8601）。
  * @param maxOccurrences - 每个事件最多展开的实例数（防死循环）。
+ * @throws {ExpansionLimitError} 迭代次数超出预算仍未能到达查询窗口时抛出。
  */
 export declare function expandEventFromICal(data: string, href: string, etag: string | undefined, rangeStart: string, rangeEnd: string, maxOccurrences: number): CalendarEvent[];
 /** 生成随机 iCal UID（带 host 后缀，形如 UUID）。 */
 export declare function generateUid(): string;
 /** 把字段生成一段完整 iCal 文本（单个 VEVENT）。 */
 export declare function buildICalString(fields: EventFields): string;
+/**
+ * 在原 iCal 文本上做字段级覆盖：保留原 VCALENDAR / VEVENT 的全部属性
+ * （ATTENDEE、ORGANIZER、EXDATE、STATUS、CATEGORIES、VALARM 及未知属性等），
+ * 只替换 changes 里显式给出的字段；原文本缺少 RFC 5545 必需属性时补齐
+ * （VCALENDAR 的 VERSION/PRODID，VEVENT 的 UID/DTSTAMP）。
+ * 解析失败或没有 VEVENT 时返回 null，由调用方回退到整条重建。
+ * @param data - 原 iCal 文本（通常来自服务器的 calendar-data）。
+ * @param changes - 需要覆盖的字段；未提供的字段保留原值。
+ */
+export declare function updateICalString(data: string, changes: Partial<EventFields>): string | null;

package/lib/ical.js

@@ -6,6 +6,13 @@
  */
 import { randomUUID } from 'node:crypto';
 import ICAL from 'ical.js';
+/** 展开重复事件超出迭代预算：显式报错，避免把「没走到窗口」静默当成「窗口内没有实例」。 */
+export class ExpansionLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExpansionLimitError';
+    }
+}
 function pad(value) {
     return value < 10 ? '0' + value : String(value);
 }
@@ -61,7 +68,7 @@ export function parseEventFromICal(data, href, etag) {
     catch {
         return null;
     }
-    const vevent = vcal.getFirstSubcomponent('vevent');
+    const vevent = masterVevent(vcal);
     if (vevent === null)
         return null;
     return veventToEvent(vevent, href, etag);
@@ -114,6 +121,15 @@ function veventToEvent(vevent, href, etag) {
     };
     return event;
 }
+/** 挑选系列主 VEVENT：优先不带 RECURRENCE-ID 的那个，避免把单次实例覆盖当成系列本身。 */
+function masterVevent(vcal) {
+    const vevents = vcal.getAllSubcomponents('vevent');
+    return vevents.find((vevent) => !vevent.hasProperty('recurrence-id')) ?? vevents[0] ?? null;
+}
+/** 把实例时间规整成可比较的键：全天按日期，定时按 epoch 秒。 */
+function recurrenceKey(time) {
+    return time.isDate === true ? 'D:' + icalTimeToIso(time) : 'T:' + time.toUnixTime();
+}
 /** 由一次 occurrence 起始时间构造实例行。 */
 function buildOccurrence(base, occurrenceStart, duration) {
     const start = icalTimeToIso(occurrenceStart);
@@ -142,55 +158,123 @@ function buildOccurrence(base, occurrenceStart, duration) {
         ...(base.lastModified !== undefined ? { lastModified: base.lastModified } : {}),
     };
 }
+/**
+ * 用带 RECURRENCE-ID 的覆盖 VEVENT 构造实例行：字段以覆盖 VEVENT 为准，
+ * 稳定标识（uid/href/etag）与 seriesStart 继承系列主 VEVENT。
+ * 覆盖 VEVENT 缺少可用 DTSTART 时用 RECURRENCE-ID 兜底，避免实例被静默丢弃。
+ */
+function buildOverrideEvent(base, vevent) {
+    const parsed = veventToEvent(vevent, base.href, base.etag);
+    if (parsed !== null) {
+        return {
+            ...parsed,
+            uid: base.uid,
+            href: base.href,
+            isOccurrence: true,
+            seriesStart: base.start,
+            ...(parsed.icalUid === undefined && base.icalUid !== undefined ? { icalUid: base.icalUid } : {}),
+        };
+    }
+    const recurrenceId = timePropertyValue(vevent, 'recurrence-id');
+    if (recurrenceId === undefined)
+        return null;
+    return {
+        uid: base.uid,
+        href: base.href,
+        summary: asString(vevent.getFirstPropertyValue('summary')) ?? base.summary,
+        start: icalTimeToIso(recurrenceId),
+        end: icalTimeToIso(recurrenceId),
+        allDay: recurrenceId.isDate === true,
+        isOccurrence: true,
+        seriesStart: base.start,
+        ...(base.icalUid !== undefined ? { icalUid: base.icalUid } : {}),
+        ...(base.etag !== undefined ? { etag: base.etag } : {}),
+        ...(base.description !== undefined ? { description: base.description } : {}),
+        ...(base.location !== undefined ? { location: base.location } : {}),
+    };
+}
 /**
  * 解析并（可选）展开一个 VEVENT：非重复事件原样返回（isOccurrence: false）；
  * 重复事件用 ICAL.RecurExpansion 在 [rangeStart, rangeEnd] 内展开，最多返回
  * maxOccurrences 个实例（isOccurrence: true + seriesStart）。
+ *
+ * 同一 VCALENDAR 里带 RECURRENCE-ID 的 VEVENT 是单次实例的覆盖（改期/改标题）：
+ * 展开时用覆盖 VEVENT 替换对应原实例；原实例被 EXDATE 排除或原时间在窗口外时，
+ * 只要覆盖后的实例落在窗口内仍单独返回，避免实例被静默丢弃。
  * @param data - iCal 文本。
  * @param href - CalDAV 对象 href，作为稳定 uid。
  * @param etag - 服务器 ETag。
  * @param rangeStart - 查询窗口起始（ISO 8601）。
  * @param rangeEnd - 查询窗口结束（ISO 8601）。
  * @param maxOccurrences - 每个事件最多展开的实例数（防死循环）。
+ * @throws {ExpansionLimitError} 迭代次数超出预算仍未能到达查询窗口时抛出。
  */
 export function expandEventFromICal(data, href, etag, rangeStart, rangeEnd, maxOccurrences) {
-    const base = parseEventFromICal(data, href, etag);
-    if (base === null)
-        return [];
     let vcal;
     try {
         vcal = new ICAL.Component(ICAL.parse(data));
     }
     catch {
-        return [{ ...base, isOccurrence: false }];
+        return [];
     }
-    const vevent = vcal.getFirstSubcomponent('vevent');
-    if (vevent === null)
-        return [{ ...base, isOccurrence: false }];
-    if (!vevent.hasProperty('rrule') && !vevent.hasProperty('rdate')) {
+    const master = masterVevent(vcal);
+    if (master === null)
+        return [];
+    const base = veventToEvent(master, href, etag);
+    if (base === null)
+        return [];
+    // 收集 RECURRENCE-ID -> 覆盖 VEVENT，展开时按原实例时间替换。
+    const overrides = new Map();
+    for (const candidate of vcal.getAllSubcomponents('vevent')) {
+        if (candidate === master)
+            continue;
+        const recurrenceId = timePropertyValue(candidate, 'recurrence-id');
+        if (recurrenceId === undefined)
+            continue;
+        overrides.set(recurrenceKey(recurrenceId), candidate);
+    }
+    if (!master.hasProperty('rrule') && !master.hasProperty('rdate')) {
         return [{ ...base, isOccurrence: false }];
     }
-    const dtstart = timePropertyValue(vevent, 'dtstart');
+    const dtstart = timePropertyValue(master, 'dtstart');
     if (dtstart === undefined)
         return [{ ...base, isOccurrence: false }];
-    const duration = veventDuration(vevent, dtstart);
-    const expansion = new ICAL.RecurExpansion({ component: vevent, dtstart });
     const rangeStartMs = isoToEpochMs(rangeStart);
     const rangeEndMs = isoToEpochMs(rangeEnd);
+    const inRange = (event) => {
+        const startMs = isoToEpochMs(event.start);
+        return !Number.isNaN(startMs) && startMs >= rangeStartMs && startMs <= rangeEndMs;
+    };
+    const duration = veventDuration(master, dtstart);
+    const expansion = new ICAL.RecurExpansion({ component: master, dtstart });
     const occurrences = [];
+    const consumedOverrides = new Set();
+    const totalIterationCap = Math.max(100000, maxOccurrences * 1000);
+    let budgetExhausted = false;
     try {
-        const totalIterationCap = Math.max(100000, maxOccurrences * 1000);
         let iterations = 0;
         while (occurrences.length < maxOccurrences) {
             iterations += 1;
-            if (iterations > totalIterationCap)
+            if (iterations > totalIterationCap) {
+                budgetExhausted = true;
                 break;
+            }
             const next = expansion.next();
             if (next === null || next === undefined)
                 break;
             const occMs = next.toUnixTime() * 1000;
             if (occMs > rangeEndMs)
                 break;
+            const key = recurrenceKey(next);
+            const overrideVevent = overrides.get(key);
+            if (overrideVevent !== undefined) {
+                // 该次实例已被单独覆盖：只输出覆盖后的字段与时间（覆盖后移出窗口则不再出现）。
+                consumedOverrides.add(key);
+                const overrideEvent = buildOverrideEvent(base, overrideVevent);
+                if (overrideEvent !== null && inRange(overrideEvent))
+                    occurrences.push(overrideEvent);
+                continue;
+            }
             if (occMs < rangeStartMs)
                 continue;
             occurrences.push(buildOccurrence(base, next, duration));
@@ -199,6 +283,22 @@ export function expandEventFromICal(data, href, etag, rangeStart, rangeEnd, maxO
     catch {
         // 规则无法满足或迭代异常时，返回已成功展开的部分实例。
     }
+    if (budgetExhausted) {
+        throw new ExpansionLimitError('重复事件「' + (base.summary !== '' ? base.summary : (base.icalUid ?? href)) + '」展开超过迭代上限（' +
+            totalIterationCap + ' 次）：该系列从 ' + base.start + ' 开始，未能在预算内到达查询窗口。' +
+            '请缩小 start/end 时间范围，或为该 RRULE 添加 COUNT/UNTIL 限制。');
+    }
+    // EXDATE 已把原时间排除、或原时间在窗口外但覆盖后移入窗口：覆盖实例仍需单独返回。
+    for (const [key, overrideVevent] of overrides) {
+        if (consumedOverrides.has(key))
+            continue;
+        const overrideEvent = buildOverrideEvent(base, overrideVevent);
+        if (overrideEvent === null || !inRange(overrideEvent))
+            continue;
+        if (occurrences.length >= maxOccurrences)
+            break;
+        occurrences.push(overrideEvent);
+    }
     return occurrences;
 }
 /** 生成随机 iCal UID（带 host 后缀，形如 UUID）。 */
@@ -208,8 +308,12 @@ export function generateUid() {
 /** 把字段生成一段完整 iCal 文本（单个 VEVENT）。 */
 export function buildICalString(fields) {
     const vcal = new ICAL.Component('vcalendar');
+    // RFC 5545 必需属性：服务器不一定替我们补，创建路径显式输出。
+    vcal.addPropertyWithValue('version', '2.0');
+    vcal.addPropertyWithValue('prodid', '-//dsh-calendar//EN');
     const vevent = new ICAL.Component('vevent');
     vevent.addPropertyWithValue('uid', fields.icalUid ?? generateUid());
+    vevent.addPropertyWithValue('dtstamp', ICAL.Time.fromJSDate(new Date(), true));
     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));
@@ -236,6 +340,109 @@ export function buildICalString(fields) {
     vcal.addSubcomponent(vevent);
     return vcal.toString();
 }
+/** 把 ICAL.Time 转成全天 DATE 值（保留原年月日）。 */
+function toDateValue(time) {
+    return ICAL.Time.fromDateString(pad(time.year) + '-' + pad(time.month) + '-' + pad(time.day));
+}
+/** 把 ICAL.Time 转成 UTC 零点的定时值（allDay 由 true 改 false 时使用）。 */
+function toMidnightUtc(time) {
+    return ICAL.Time.fromDateTimeString(pad(time.year) + '-' + pad(time.month) + '-' + pad(time.day) + 'T00:00:00Z');
+}
+/** 显式改 allDay 时同步 DTSTART/DTEND 的 DATE / DATE-TIME 表示。 */
+function convertTimeForAllDay(time, allDay) {
+    if (allDay)
+        return time.isDate === true ? time : toDateValue(time);
+    return time.isDate === true ? toMidnightUtc(time) : time;
+}
+/** 在既有 VEVENT 上覆盖开始/结束时间（含 allDay 表示转换），未显式给出的时间不动。 */
+function applyEventTimes(vevent, changes) {
+    const existingStart = timePropertyValue(vevent, 'dtstart');
+    const existingEnd = timePropertyValue(vevent, 'dtend');
+    const allDay = changes.allDay ?? (existingStart?.isDate === true);
+    let start;
+    if (changes.start !== undefined) {
+        start = parseTime(changes.start, allDay || isDateOnly(changes.start));
+    }
+    else if (existingStart !== undefined && changes.allDay !== undefined) {
+        start = convertTimeForAllDay(existingStart, allDay);
+    }
+    if (start !== undefined)
+        vevent.updatePropertyWithValue('dtstart', start);
+    let end;
+    if (changes.end !== undefined) {
+        end = parseTime(changes.end, allDay || isDateOnly(changes.end));
+    }
+    else if (existingEnd !== undefined && changes.allDay !== undefined) {
+        end = convertTimeForAllDay(existingEnd, allDay);
+    }
+    if (end !== undefined) {
+        vevent.updatePropertyWithValue('dtend', end);
+        // DTEND 与 DURATION 互斥；显式给结束时间时移除原 DURATION，避免双份定义。
+        vevent.removeProperty('duration');
+    }
+}
+/**
+ * 在原 iCal 文本上做字段级覆盖：保留原 VCALENDAR / VEVENT 的全部属性
+ * （ATTENDEE、ORGANIZER、EXDATE、STATUS、CATEGORIES、VALARM 及未知属性等），
+ * 只替换 changes 里显式给出的字段；原文本缺少 RFC 5545 必需属性时补齐
+ * （VCALENDAR 的 VERSION/PRODID，VEVENT 的 UID/DTSTAMP）。
+ * 解析失败或没有 VEVENT 时返回 null，由调用方回退到整条重建。
+ * @param data - 原 iCal 文本（通常来自服务器的 calendar-data）。
+ * @param changes - 需要覆盖的字段；未提供的字段保留原值。
+ */
+export function updateICalString(data, changes) {
+    let vcal;
+    try {
+        vcal = new ICAL.Component(ICAL.parse(data));
+    }
+    catch {
+        return null;
+    }
+    const vevent = masterVevent(vcal);
+    if (vevent === null)
+        return null;
+    if (!vcal.hasProperty('version'))
+        vcal.addPropertyWithValue('version', '2.0');
+    if (!vcal.hasProperty('prodid'))
+        vcal.addPropertyWithValue('prodid', '-//dsh-calendar//EN');
+    if (!vevent.hasProperty('uid')) {
+        vevent.addPropertyWithValue('uid', changes.icalUid ?? generateUid());
+    }
+    else if (changes.icalUid !== undefined) {
+        vevent.updatePropertyWithValue('uid', changes.icalUid);
+    }
+    if (!vevent.hasProperty('dtstamp')) {
+        vevent.addPropertyWithValue('dtstamp', ICAL.Time.fromJSDate(new Date(), true));
+    }
+    // 字段级覆盖：updatePropertyWithValue 保留原属性参数（如 ATTENDEE 的 CN/PARTSTAT）。
+    if (changes.summary !== undefined)
+        vevent.updatePropertyWithValue('summary', changes.summary);
+    if (changes.description !== undefined)
+        vevent.updatePropertyWithValue('description', changes.description);
+    if (changes.location !== undefined)
+        vevent.updatePropertyWithValue('location', changes.location);
+    if (changes.rrule !== undefined) {
+        const rule = changes.rrule.trim();
+        if (rule === '') {
+            vevent.removeProperty('rrule');
+        }
+        else {
+            if (!/^FREQ=/i.test(rule)) {
+                throw new Error('rrule 格式无效：' + changes.rrule + '（应为 RFC 5545 RRULE，如 FREQ=WEEKLY;COUNT=4）');
+            }
+            try {
+                vevent.updatePropertyWithValue('rrule', ICAL.Recur.fromString(rule));
+            }
+            catch (error) {
+                throw new Error('rrule 格式无效：' + changes.rrule);
+            }
+        }
+    }
+    if (changes.start !== undefined || changes.end !== undefined || changes.allDay !== undefined) {
+        applyEventTimes(vevent, changes);
+    }
+    return vcal.toString();
+}
 /** 把 ISO 字符串解析成 ICAL.Time（全天 YYYY-MM-DD 或转 UTC 的定时时间）。 */
 function parseTime(value, allDay) {
     if (allDay || isDateOnly(value)) {

package/lib/tools.js

@@ -302,9 +302,11 @@ export function buildCalendarTools(config, env = process.env) {
     };
     const search = {
         name: 'calendar_search',
-        description: '按关键词搜索日历事件（客户端过滤：匹配标题、描述、地点与 iCal UID，不区分大小写）。query 必填，limit 可选（默认 50）。返回每个事件的稳定标识 uid。',
+        description: '按关键词搜索日历事件（客户端过滤：匹配标题、描述、地点与 iCal UID，不区分大小写）。只查询 start~end 窗口内的事件（start/end 缺省为当前时间前后各 1 年），query 必填，limit 可选（默认 50）。返回每个事件的稳定标识 uid。',
         parameters: compileParameters({
             query: { type: 'string', required: true, description: '搜索关键词（必填）。' },
+            start: { type: 'string', description: '查询窗口起始时间（ISO 8601，含时区偏移）。缺省为当前时间前 1 年。' },
+            end: { type: 'string', description: '查询窗口结束时间（ISO 8601，含时区偏移）。缺省为当前时间后 1 年。' },
             limit: { type: 'integer', description: '最多返回条数（可选，默认 50，自动 clamp 到 1-200）。' },
         }),
         output: {
@@ -330,7 +332,14 @@ export function buildCalendarTools(config, env = process.env) {
             const input = asRecord(args);
             const query = requiredString(input, 'query', '搜索关键词');
             const limit = clampedInteger(input, 'limit', 50, 1, 200);
-            const all = await service().all(executionSignal(exec));
+            const now = new Date();
+            const yearMs = 365 * 24 * 3600 * 1000;
+            const start = optionalString(input, 'start') ?? isoNoMillis(new Date(now.getTime() - yearMs).toISOString());
+            const end = optionalString(input, 'end') ?? isoNoMillis(new Date(now.getTime() + yearMs).toISOString());
+            assertIsoTime(start, 'start');
+            assertIsoTime(end, 'end');
+            assertTimeRange(start, end);
+            const all = await service().all(executionSignal(exec), { start, end });
             const matched = sortEvents(all).filter(buildSearchFilter(query)).slice(0, limit);
             return { query, count: matched.length, events: matched };
         },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-calendar",
-  "version": "0.5.3",
-  "description": "DeepSeek Harness 日历插件：CalDAV 日程查询、创建、修改、删除与搜索，支持 Google OAuth 2.0、iCloud、Nextcloud、自定义服务及离线配置自检。",
+  "version": "0.5.4",
+  "description": "DSH 日历插件：CalDAV 日程查询、创建、修改、删除与搜索，支持 Google OAuth2、iCloud、Nextcloud 与自建服务。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -17,7 +17,8 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",