dsh-calendar 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.11.2（2026-10-20）
+
+- 修复 #3：更新时间时保留原 TZID 对应的本地钟点和夏令时规则，不再写出 TZID 与 UTC `Z` 混用的属性。
+- 含 EXDATE、RDATE 或单次覆盖的系列，拒绝整体改开始时间、全天类型或重复规则，防止取消场次复活、改期场次重复。
+- 重复系列更新 / 删除必须显式传 `scope:"series"`；面板编辑先读取系列主记录，并提示影响全部场次，删除确认包含视图外场次。
+
 ## 0.11.1（2026-10-20）
 
 - 修复 calendar_update 传入空字符串时无法清空说明、地点或重复规则的问题；省略字段仍保留原值。

package/docs/USAGE.md

@@ -4,6 +4,8 @@
 
 ## 本次改进
 
+重复系列的 `calendar_update` / `calendar_delete` 需先向用户说明影响，确认操作全部场次后传 `scope:"series"`。无法只改或删除某一次。面板编辑读取系列原始日期，删除确认覆盖整个系列。有取消、额外或单独改期场次的系列不能整体改开始时间、全天类型或重复规则，请在原日历客户端处理；描述、地点、标题仍可修改。带 TZID 的时间保留其本地钟点与夏令时语义。
+
 日期使用 YYYY-MM-DD；带时间使用带 Z 或 UTC 偏移的 ISO 格式。错误日期会在创建或更新远端日程前报错，原日程保留。
 
 ## 安装

package/lib/caldav.d.ts

@@ -45,10 +45,12 @@ export declare class CalendarService {
     }>;
     /** Insert one already reviewed UID resource; tsdav uses If-None-Match:* and never overwrites existing objects. */
     importRaw(uid: string, data: string, signal?: AbortSignal): Promise<void>;
+    /** Read the resource master rather than a projected occurrence. */
+    get(uid: string, signal?: AbortSignal): Promise<CalendarEvent>;
     /** 按 uid 更新事件；未提供的字段保留原值。 */
-    update(uid: string, changes: Partial<EventFields>, signal?: AbortSignal): Promise<CalendarEvent>;
+    update(uid: string, changes: Partial<EventFields>, signal?: AbortSignal, scope?: 'series'): Promise<CalendarEvent>;
     /** 按 uid 删除事件。 */
-    delete(uid: string, signal?: AbortSignal): Promise<{
+    delete(uid: string, signal?: AbortSignal, scope?: 'series'): Promise<{
         uid: string;
         href: string;
     }>;

package/lib/caldav.js

@@ -9,7 +9,7 @@ import { createHash } from 'node:crypto';
 import ICAL from 'ical.js';
 import { createProxyFetch } from './proxy-fetch.js';
 import { createOAuthFetch, OAuthError } from './oauth.js';
-import { buildICalString, expandEventFromICal, ExpansionLimitError, generateUid, parseEventFromICal, updateICalString, } from './ical.js';
+import { buildICalString, expandEventFromICal, ExpansionLimitError, generateUid, parseEventFromICal, updateICalString, isRecurringResource, } from './ical.js';
 /** CalDAV 操作错误：带中文指引。 */
 export class CalDAVError extends Error {
     status;
@@ -279,8 +279,22 @@ export class CalendarService {
             throw translateError(error, '导入日程', this.config);
         }
     }
+    /** Read the resource master rather than a projected occurrence. */
+    async get(uid, signal) {
+        try {
+            const object = await this.findObject(uid, signal);
+            const event = object && parseEventFromICal(String(object.data ?? ''), object.url, object.etag);
+            if (!event)
+                throw new CalDAVError('找不到或无法解析日程，请刷新日历后重试。');
+            return event;
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            throw translateError(error, '读取系列事件', this.config);
+        }
+    }
     /** 按 uid 更新事件；未提供的字段保留原值。 */
-    async update(uid, changes, signal) {
+    async update(uid, changes, signal, scope) {
         signal?.throwIfAborted();
         let object;
         try {
@@ -295,6 +309,10 @@ export class CalendarService {
                 '该事件可能已被删除或 uid 已过期。');
         }
         const existing = parseEventFromICal(String(object.data ?? ''), object.url, object.etag);
+        if (!existing)
+            throw new CalDAVError('无法解析原日程，更新已取消；请在原日历客户端检查。');
+        if (isRecurringResource(String(object.data ?? '')) && scope !== 'series')
+            throw new CalDAVError('这是整个重复系列。请先向用户说明影响，确认后显式传 scope="series"；当前不支持只改某一次。');
         const start = changes.start ?? existing?.start;
         const end = changes.end ?? existing?.end;
         if (start === undefined || end === undefined) {
@@ -340,7 +358,7 @@ export class CalendarService {
         return event;
     }
     /** 按 uid 删除事件。 */
-    async delete(uid, signal) {
+    async delete(uid, signal, scope) {
         signal?.throwIfAborted();
         let object;
         try {
@@ -354,6 +372,8 @@ export class CalendarService {
             throw new CalDAVError('找不到 uid 对应的事件：请用 calendar_list 或 calendar_search 重新获取最新 uid，' +
                 '该事件可能已被删除或 uid 已过期。');
         }
+        if (isRecurringResource(String(object.data ?? '')) && scope !== 'series')
+            throw new CalDAVError('这是整个重复系列。请先向用户说明影响，确认后显式传 scope="series"；当前不支持只删某一次。');
         try {
             const client = await this.client();
             signal?.throwIfAborted();

package/lib/client.js

@@ -240,6 +240,8 @@ const UI = {
     "conflict.title": "这个时段已有 {n} 个日程，会重叠：", "conflict.hint": "仍然保存？",
     "error.title": "操作失败", "error.load": "读取日历失败",
     "confirm.delete": "删除「{name}」？这个操作会同步到你的日历服务器。",
+    "confirm.deleteSeries": "将删除「{name}」整个重复系列的所有场次，包含当前视图外的场次。无法撤销。",
+    "form.series": "正在编辑整个重复系列，所有场次都会受影响。含取消或单独改期场次时，请到原日历客户端调整时间和规则。",
     "form.newTitle": "新建日程", "form.editTitle": "编辑日程",
     "form.required": "标题和时间都要填。",
     "day.today": "今天", "day.tomorrow": "明天", "day.yesterday": "昨天",
@@ -336,6 +338,8 @@ const UI = {
     "conflict.title": "This slot already has {n} event(s); they overlap:", "conflict.hint": "Save anyway?",
     "error.title": "Something failed", "error.load": "Could not load the calendar",
     "confirm.delete": "Delete「{name}」? This is pushed to your calendar server.",
+    "confirm.deleteSeries": "Delete every occurrence of {name}, including dates outside this view? This cannot be undone.",
+    "form.series": "Editing the entire recurring series. All occurrences are affected. If it has cancelled or rescheduled occurrences, change times and rules in your original calendar app.",
     "form.newTitle": "New event", "form.editTitle": "Edit event",
     "form.required": "A title and a time range are required.",
     "day.today": "Today", "day.tomorrow": "Tomorrow", "day.yesterday": "Yesterday",
@@ -417,6 +421,11 @@ var activeLocaleService = null;
 
 // Backend guidance is localized separately from event titles and source content.
 const BACKEND_EN = {
+  '系列含已取消、额外或单独改期的场次，不能整体改开始时间、全天类型或重复规则；请在原日历客户端编辑，现有日程未改动。': 'This series has cancelled, extra or rescheduled occurrences. Change its start time, all-day type or recurrence rule in the original calendar app. No event was changed.',
+  '这是整个重复系列。请先向用户说明影响，确认后显式传 scope="series"；当前不支持只改某一次。': 'This action changes the entire recurring series. Explain its impact, then use scope="series" after confirmation. Editing just one occurrence is unsupported.',
+  '这是整个重复系列。请先向用户说明影响，确认后显式传 scope="series"；当前不支持只删某一次。': 'This action deletes the entire recurring series. Explain its impact, then use scope="series" after confirmation. Deleting just one occurrence is unsupported.',
+  '找不到或无法解析日程，请刷新日历后重试。': 'The event is missing or could not be parsed. Refresh the calendar and try again.',
+  '无法解析原日程，更新已取消；请在原日历客户端检查。': 'The original event could not be parsed. No update was made. Check it in the original calendar app.',
   "日期格式不合法": "Invalid date format.",
   "日程包含不存在的日期或时间": "This event contains an invalid date or time.",
   "请先选择或粘贴 ICS 文件内容": "Choose an ICS file or paste its content first.",
@@ -1310,6 +1319,7 @@ function draftOfEvent(event) {
   const e = allDay ? addDays(rawEnd, -1) : rawEnd;
   return {
     uid: event.uid,
+    isSeries: isRecurring(event),
     summary: event.summary || "",
     date: dayKey(s),
     startTime: pad2(s.getHours()) + ":" + pad2(s.getMinutes()),
@@ -1364,7 +1374,7 @@ function rruleForRepeat(repeat) {
 
 /** 草稿 → 后端字段（全天走 DATE，定时走本地时间换算出的 UTC 秒级 ISO）。 */
 function fieldsOfDraft(draft) {
-  const fields = { summary: draft.summary.trim(), location: draft.location.trim(), description: draft.description.trim() };
+  const fields = { summary: draft.summary.trim(), location: draft.location.trim(), description: draft.description.trim(), ...(draft.isSeries ? { scope: "series" } : {}) };
   if (draft.allDay === true) {
     fields.start = draft.date;
     fields.end = dayKey(addDays(new Date(draft.date + "T00:00:00"), 1));
@@ -1400,6 +1410,7 @@ function EventForm(props) {
   const canSave = form.summary.trim() !== "" && (form.allDay === true || form.startTime <= form.endTime);
 
   const body = h("div", null, [
+    draft.isSeries ? h("div", { className: "dshc-alert" }, t("form.series")) : null,
     error ? h("div", { className: "dshc-alert error" }, error) : null,
     h("div", { className: "dshc-field" }, [
       h("label", { htmlFor: formId + "-summary" }, t("field.summary")),
@@ -1491,7 +1502,7 @@ function EventDrawer(props) {
           : h(Btn, { key: "delete", variant: "danger", onClick: () => setConfirmDelete(true), disabled: busy === true || readOnly === true }, t("action.delete")),
         h(Btn, { key: "edit", variant: "outline", onClick: () => onEdit(event), disabled: busy === true || readOnly === true }, t("action.edit"))
       ]),
-      confirmDelete ? h("div", { className: "dshc-sub", style: { textAlign: "right", marginTop: "6px" } }, t("confirm.delete", { name: event.summary })) : null
+      confirmDelete ? h("div", { className: "dshc-sub", style: { textAlign: "right", marginTop: "6px" } }, t(isRecurring(event) ? "confirm.deleteSeries" : "confirm.delete", { name: event.summary })) : null
     ])
   ]);
 }
@@ -2076,7 +2087,7 @@ function CalendarPanel(props) {
     if (demo === true) { notify(t("demo.banner")); return; }
     setBusy(true);
     try {
-      await api("delete", { uid: event.uid });
+      await api("delete", { uid: event.uid, ...(isRecurring(event) ? { scope: "series" } : {}) });
       setSelected(null);
       setConfirmDelete(false);
       reload();
@@ -2167,7 +2178,13 @@ function CalendarPanel(props) {
           confirmDelete,
           setConfirmDelete,
           onClose: () => { setSelected(null); setConfirmDelete(false); },
-          onEdit: (event) => { setSelected(null); setDraft(draftOfEvent(event)); },
+          onEdit: async (event) => {
+            if (!isRecurring(event) || demo) { setSelected(null); setDraft(draftOfEvent(event)); return; }
+            setBusy(true);
+            try { const value = await api("event", { uid: event.uid }); setSelected(null); setDraft({ ...draftOfEvent(value.event), isSeries: true }); }
+            catch (error) { setBanner(backendMessage(error)); }
+            finally { setBusy(false); }
+          },
           onDelete: remove
         })
       : null,

package/lib/ical.d.ts

@@ -4,6 +4,7 @@
  *
  * @module dsh-calendar/ical
  */
+export declare function isRecurringResource(data: string): boolean;
 /** 一个暴露给模型的日历事件（或重复系列的一个展开实例）。 */
 export interface CalendarEvent {
     /** 稳定标识（CalDAV href），calendar_update / calendar_delete 用它。 */

package/lib/ical.js

@@ -6,7 +6,30 @@
  */
 import { randomUUID } from 'node:crypto';
 import ICAL from 'ical.js';
+import { tzlib_get_ical_block, tzlib_get_timezones } from 'timezones-ical-library';
 import { assertIsoTime } from './time.js';
+const supportedZones = new Set(tzlib_get_timezones());
+/** Install missing IANA definitions in this resource before hydrating any dates. */
+function prepareTimezones(calendar) {
+    const defined = new Set(calendar.getAllSubcomponents('vtimezone').map(zone => String(zone.getFirstPropertyValue('tzid'))));
+    for (const event of calendar.getAllSubcomponents('vevent'))
+        for (const property of event.getAllProperties()) {
+            const tzid = property.getParameter('tzid');
+            if (typeof tzid !== 'string' || tzid === 'UTC' || defined.has(tzid))
+                continue;
+            if (!supportedZones.has(tzid))
+                throw new Error('无法识别日程时区 ' + tzid + '，请从原日历重新导出完整的 VTIMEZONE');
+            const block = tzlib_get_ical_block(tzid)[0];
+            if (!block)
+                throw new Error('缺少日程时区定义：' + tzid);
+            calendar.addSubcomponent(new ICAL.Component(ICAL.parse(block)));
+            defined.add(tzid);
+        }
+}
+export function isRecurringResource(data) {
+    const calendar = new ICAL.Component(ICAL.parse(data));
+    return calendar.getAllSubcomponents('vevent').some(event => ['rrule', 'rdate', 'exdate', 'recurrence-id'].some(name => event.hasProperty(name)));
+}
 /** 展开重复事件超出迭代预算：显式报错，避免把「没走到窗口」静默当成「窗口内没有实例」。 */
 export class ExpansionLimitError extends Error {
     constructor(message) {
@@ -69,6 +92,7 @@ export function parseEventFromICal(data, href, etag) {
     catch {
         return null;
     }
+    prepareTimezones(vcal);
     const vevent = masterVevent(vcal);
     if (vevent === null)
         return null;
@@ -218,6 +242,7 @@ export function expandEventFromICal(data, href, etag, rangeStart, rangeEnd, maxO
     catch {
         return [];
     }
+    prepareTimezones(vcal);
     const master = masterVevent(vcal);
     if (master === null)
         return [];
@@ -360,6 +385,22 @@ function applyEventTimes(vevent, changes) {
     const existingStart = timePropertyValue(vevent, 'dtstart');
     const existingEnd = timePropertyValue(vevent, 'dtend');
     const allDay = changes.allDay ?? (existingStart?.isDate === true);
+    const originalZone = vevent.getFirstProperty('dtstart')?.getParameter('tzid');
+    const writeTime = (name, time) => {
+        const tzid = vevent.getFirstProperty(name)?.getParameter('tzid') ?? originalZone;
+        if (!time.isDate && typeof tzid === 'string') {
+            const zone = vevent.parent?.getTimeZoneByID(tzid);
+            if (!zone)
+                throw new Error('无法保留日程时区：' + tzid);
+            time = time.convertToZone(zone);
+        }
+        vevent.updatePropertyWithValue(name, time);
+        const property = vevent.getFirstProperty(name);
+        if (!time.isDate && typeof tzid === 'string')
+            property.setParameter('tzid', tzid);
+        else
+            property.removeParameter('tzid');
+    };
     let start;
     if (changes.start !== undefined) {
         start = parseTime(changes.start, allDay || isDateOnly(changes.start));
@@ -368,7 +409,7 @@ function applyEventTimes(vevent, changes) {
         start = convertTimeForAllDay(existingStart, allDay);
     }
     if (start !== undefined)
-        vevent.updatePropertyWithValue('dtstart', start);
+        writeTime('dtstart', start);
     let end;
     if (changes.end !== undefined) {
         end = parseTime(changes.end, allDay || isDateOnly(changes.end));
@@ -377,7 +418,7 @@ function applyEventTimes(vevent, changes) {
         end = convertTimeForAllDay(existingEnd, allDay);
     }
     if (end !== undefined) {
-        vevent.updatePropertyWithValue('dtend', end);
+        writeTime('dtend', end);
         // DTEND 与 DURATION 互斥；显式给结束时间时移除原 DURATION，避免双份定义。
         vevent.removeProperty('duration');
     }
@@ -399,9 +440,19 @@ export function updateICalString(data, changes) {
     catch {
         return null;
     }
+    prepareTimezones(vcal);
     const vevent = masterVevent(vcal);
     if (vevent === null)
         return null;
+    const originalStart = timePropertyValue(vevent, 'dtstart');
+    const timeMoves = changes.start !== undefined && originalStart !== undefined &&
+        parseTime(changes.start, changes.allDay ?? originalStart.isDate).toUnixTime() !== originalStart.toUnixTime();
+    const typeChanges = changes.allDay !== undefined && changes.allDay !== originalStart?.isDate;
+    const ruleChanges = changes.rrule !== undefined && changes.rrule.trim() !== String(vevent.getFirstPropertyValue('rrule') ?? '');
+    const hasExceptions = vevent.hasProperty('exdate') || vevent.hasProperty('rdate') || vcal.getAllSubcomponents('vevent').some(event => event.hasProperty('recurrence-id'));
+    if (hasExceptions && (timeMoves || typeChanges || ruleChanges)) {
+        throw new Error('系列含已取消、额外或单独改期的场次，不能整体改开始时间、全天类型或重复规则；请在原日历客户端编辑，现有日程未改动。');
+    }
     if (!vcal.hasProperty('version'))
         vcal.addPropertyWithValue('version', '2.0');
     if (!vcal.hasProperty('prodid'))

package/lib/tools.js

@@ -203,9 +203,10 @@ export function buildCalendarTools(config, env = process.env) {
     };
     const update = {
         name: 'calendar_update',
-        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay、rrule 均可选，未提供的字段保留原值。description、location、rrule 显式传空字符串可分别清空说明、地点或停止重复。',
+        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay、rrule 均可选，未提供的字段保留原值。description、location、rrule 显式传空字符串可分别清空说明、地点或停止重复。重复日程的 uid 指整个系列；先向用户说明，确认后传 scope="series"，不能只改某一次。有例外场次的系列不允许整体改开始时间、全天类型或重复规则。',
         parameters: compileParameters({
             uid: { type: 'string', required: true, description: '事件稳定标识（来自 calendar_list / calendar_search 的 uid，必填）。' },
+            scope: { type: 'string', enum: ['series'], description: '重复日程必须先向用户说明影响；确认操作整个系列后传 series。不能只改或删除某一次。' },
             summary: { type: 'string', description: '新标题（可选）。' },
             start: { type: 'string', description: '新开始时间（ISO 8601，可选）。' },
             end: { type: 'string', description: '新结束时间（ISO 8601，可选）。' },
@@ -255,16 +256,17 @@ export function buildCalendarTools(config, env = process.env) {
             const rrule = optionalPatchString(input, 'rrule');
             if (rrule !== undefined)
                 changes.rrule = rrule;
-            const updated = await service().update(uid, changes, executionSignal(exec));
+            const updated = await service().update(uid, changes, executionSignal(exec), input.scope === 'series' ? 'series' : undefined);
             return { updated };
         },
         timeoutMs: TIMEOUT_MS,
     };
     const remove = {
         name: 'calendar_delete',
-        description: '按 uid 删除日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。删除不可撤销。',
+        description: '按 uid 删除日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。删除不可撤销。重复日程的 uid 指向整个系列，不能只删某一次；必须先向用户说明将删除所有场次，确认后传 scope="series"，否则拒绝。',
         parameters: compileParameters({
             uid: { type: 'string', required: true, description: '事件稳定标识（来自 calendar_list / calendar_search 的 uid，必填）。' },
+            scope: { type: 'string', enum: ['series'], description: '重复日程必须先向用户说明影响；确认操作整个系列后传 series。不能只改或删除某一次。' },
         }),
         output: {
             schema: {
@@ -285,7 +287,7 @@ export function buildCalendarTools(config, env = process.env) {
         async execute(args, exec) {
             const input = asRecord(args);
             const uid = requiredString(input, 'uid', '事件 uid');
-            const result = await service().delete(uid, executionSignal(exec));
+            const result = await service().delete(uid, executionSignal(exec), input.scope === 'series' ? 'series' : undefined);
             return { deleted: true, uid: result.uid, href: result.href };
         },
         timeoutMs: TIMEOUT_MS,

package/lib/web.d.ts

@@ -27,10 +27,11 @@ export declare function postVerdict(headers: Record<string, unknown>): {
 } | undefined;
 /** 面板需要的服务面；测试里可以塞假的进来。 */
 export interface CalendarServiceLike {
+    get?(uid: string, signal?: AbortSignal): Promise<CalendarEvent>;
     list(start: string, end: string, options?: unknown, signal?: AbortSignal): Promise<CalendarEvent[]>;
     create(fields: unknown, signal?: AbortSignal): Promise<CalendarEvent>;
-    update(uid: string, changes: unknown, signal?: AbortSignal): Promise<CalendarEvent>;
-    delete(uid: string, signal?: AbortSignal): Promise<{
+    update(uid: string, changes: unknown, signal?: AbortSignal, scope?: 'series'): Promise<CalendarEvent>;
+    delete(uid: string, signal?: AbortSignal, scope?: 'series'): Promise<{
         uid: string;
         href: string;
     }>;

package/lib/web.js

@@ -388,13 +388,19 @@ export class CalendarSettingsBackend {
             const fields = eventFields(body, true);
             return { event: await this.service().create(fields) };
         }
+        if (action === 'event') {
+            const service = this.service();
+            if (!service.get)
+                throw new Error('当前日历连接不支持读取系列原始事件');
+            return { event: await service.get(requireString(body, 'uid', '缺少事件 uid')) };
+        }
         if (action === 'update') {
             const uid = requireString(body, 'uid', '缺少要修改的事件 uid');
-            return { event: await this.service().update(uid, eventFields(body, false)) };
+            return { event: await this.service().update(uid, eventFields(body, false), undefined, body.scope === 'series' ? 'series' : undefined) };
         }
         if (action === 'delete') {
             const uid = requireString(body, 'uid', '缺少要删除的事件 uid');
-            return await this.service().delete(uid);
+            return await this.service().delete(uid, undefined, body.scope === 'series' ? 'series' : undefined);
         }
         throw new Error('未知动作：' + (action === '' ? '(空)' : action));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "连接 CalDAV 日历，在 DSH 中查看、创建和调整日程。",
   "type": "module",
   "main": "lib/index.js",