dsh-calendar 0.5.4 → 0.7.0

package/lib/index.d.ts

@@ -9,6 +9,7 @@
  */
 import { type CalendarConfig } from './config.js';
 import { type CalendarToolDefinition } from './tools.js';
+import { type CalendarSettingsFace } from './web.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明注入，否则宿主会抛 cannot get property without inject。 */
 export declare const name = "calendar";
 export declare const inject: string[];
@@ -18,7 +19,31 @@ export interface CalendarPluginContext {
         register(definition: CalendarToolDefinition): () => void;
     };
     on?(event: string, listener: () => void): () => void;
+    /** 设置页面板需要挂路由；隔离环境（测试/headless）可以没有。 */
+    inject?(services: string[], callback: (ctx: any) => void): void;
 }
+/**
+ * 同步注册 settings 命名空间并返回读写面。
+ *
+ * 时机是关键：宿主的 register 内部会 `ctx.effect(...)`，必须在插件加载的**同步阶段**调用 ——
+ * 在请求处理里注册会失败，而失败一旦被吞掉，就会在保存时才暴露成「namespace is not registered」。
+ * 拿不到服务 / 注册失败都只 warn：面板退化为只读，配置仍可写在 cordis.patch.yml。
+ */
+/** 兜底：把连接配置存进插件自己的文件（宿主 settings 不可用/注册失败时）。 */
+export declare function fileSettingsFace(file?: string): CalendarSettingsFace;
+/**
+ * 接上配置存储：首选宿主 settings 命名空间，不行就退到插件自己的文件。
+ *
+ * 三步走，每一步失败都往下退而不是抛：
+ *   1. 拿到 settings 服务 → 在**插件加载阶段**同步注册命名空间（宿主的 register 要活动作用域）；
+ *   2. 注册失败但 describe() 里已有我们这个命名空间 → 搭既有注册的车（重复 apply 的第二个实例）；
+ *   3. 服务不在、或注册失败且没人注册过 → 用兜底文件。
+ * 返回 reason 是为了让面板说清「为什么不是宿主设置」，而不是笼统一句「不可用」。
+ */
+export declare function attachSettings(ctx: CalendarPluginContext, cfg: CalendarConfig): {
+    face: CalendarSettingsFace;
+    reason?: string;
+};
 /**
  * 插件入口：惰性解析配置并注册五个日历工具。
  * @param ctx - 宿主上下文（至少含 tools.register）。
@@ -30,3 +55,6 @@ export * from './config.js';
 export * from './ical.js';
 export * from './caldav.js';
 export * from './tools.js';
+export * from './web.js';
+export * from './settings.js';
+export * from './store.js';

package/lib/index.js

@@ -9,9 +9,88 @@
  */
 import { resolveConfig } from './config.js';
 import { buildCalendarTools } from './tools.js';
+import { CalendarSettingsSchema, SETTINGS_NAMESPACE, toCalendarConfig, toSettingsBase, validateSettingsValue } from './settings.js';
+import { CalendarSettingsBackend, installCalendarSettingsWeb, settingsFaceOf } from './web.js';
+import { connectionFile, readConnectionFile, writeConnectionFile } from './store.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明注入，否则宿主会抛 cannot get property without inject。 */
 export const name = 'calendar';
 export const inject = ['tools'];
+/**
+ * 同步注册 settings 命名空间并返回读写面。
+ *
+ * 时机是关键：宿主的 register 内部会 `ctx.effect(...)`，必须在插件加载的**同步阶段**调用 ——
+ * 在请求处理里注册会失败，而失败一旦被吞掉，就会在保存时才暴露成「namespace is not registered」。
+ * 拿不到服务 / 注册失败都只 warn：面板退化为只读，配置仍可写在 cordis.patch.yml。
+ */
+/** 兜底：把连接配置存进插件自己的文件（宿主 settings 不可用/注册失败时）。 */
+export function fileSettingsFace(file = connectionFile()) {
+    return {
+        kind: 'file',
+        read: () => readConnectionFile(file).value,
+        descriptor: () => ({ revision: readConnectionFile(file).revision }),
+        replace: async (value) => {
+            const current = readConnectionFile(file);
+            writeConnectionFile({ revision: current.revision + 1, value }, file);
+        },
+    };
+}
+/**
+ * 接上配置存储：首选宿主 settings 命名空间，不行就退到插件自己的文件。
+ *
+ * 三步走，每一步失败都往下退而不是抛：
+ *   1. 拿到 settings 服务 → 在**插件加载阶段**同步注册命名空间（宿主的 register 要活动作用域）；
+ *   2. 注册失败但 describe() 里已有我们这个命名空间 → 搭既有注册的车（重复 apply 的第二个实例）；
+ *   3. 服务不在、或注册失败且没人注册过 → 用兜底文件。
+ * 返回 reason 是为了让面板说清「为什么不是宿主设置」，而不是笼统一句「不可用」。
+ */
+export function attachSettings(ctx, cfg) {
+    let provider;
+    try {
+        provider = typeof ctx.get === 'function' ? ctx.get('settings') : undefined;
+    }
+    catch (error) {
+        provider = undefined;
+    }
+    if (provider === undefined || provider === null) {
+        try {
+            provider = ctx.settings;
+        }
+        catch (error) {
+            provider = undefined;
+        }
+    }
+    const usable = provider !== undefined && provider !== null && typeof provider.register === 'function' && typeof provider.replace === 'function';
+    if (usable !== true) {
+        const reason = '插件未注入宿主 settings 服务';
+        console.warn('dsh-calendar: ' + reason + '，连接配置改存插件自己的文件：' + connectionFile());
+        return { face: fileSettingsFace(), reason };
+    }
+    let scope;
+    let failure;
+    try {
+        scope = provider.register(SETTINGS_NAMESPACE, CalendarSettingsSchema, {
+            base: toSettingsBase(cfg),
+            applies: 'live',
+            validate: (value) => validateSettingsValue(value),
+        });
+    }
+    catch (error) {
+        failure = error instanceof Error ? error.message : String(error);
+    }
+    const known = (typeof provider.describe === 'function' ? provider.describe() ?? [] : []).some((row) => row !== undefined && row !== null && row.ns === SETTINGS_NAMESPACE);
+    if (failure !== undefined && known === true) {
+        // 已被注册（重复 apply 的第二个实例）：不注册，搭既有注册的车。
+        console.warn('dsh-calendar: settings 命名空间注册失败（' + failure + '），改为搭既有注册');
+        return { face: settingsFaceOf(provider, undefined) };
+    }
+    if (failure !== undefined) {
+        // 注册失败且没人注册过：写进去也会报 namespace is not registered，直接换兜底文件。
+        const reason = 'settings 命名空间注册失败：' + failure;
+        console.warn('dsh-calendar: ' + reason + '，连接配置改存插件自己的文件：' + connectionFile());
+        return { face: fileSettingsFace(), reason };
+    }
+    return { face: settingsFaceOf(provider, scope) };
+}
 /**
  * 插件入口：惰性解析配置并注册五个日历工具。
  * @param ctx - 宿主上下文（至少含 tools.register）。
@@ -25,10 +104,29 @@ export function apply(ctx, config) {
     catch (error) {
         console.warn('dsh-calendar: ' + (error instanceof Error ? error.message : String(error)));
     }
+    // 面板把连接配置写进 settings 之后，工具的下一次调用就该用新配置 —— 所以工具与面板
+    // 拿到的是一个 getter，而不是启动时那一份静态对象。
+    const attached = attachSettings(ctx, cfg);
+    const configOf = () => ({ ...cfg, ...toCalendarConfig(attached.face.read(), null) });
     const disposers = [];
-    for (const definition of buildCalendarTools(cfg)) {
+    for (const definition of buildCalendarTools(configOf)) {
         disposers.push(ctx.tools.register(definition));
     }
+    // 面板路由挂上即用：settings 服务由 backend 在第一个请求上懒接入（见 web.ts 的
+    // ensureSettings），所以这里不依赖任何子 fiber 的时序，也不会因为重复 apply 而失效。
+    const backend = new CalendarSettingsBackend({
+        config: configOf,
+        ctx,
+        settings: attached.face,
+        settingsBase: toSettingsBase(cfg),
+        ...(attached.reason !== undefined ? { settingsReason: attached.reason } : {}),
+    });
+    try {
+        installCalendarSettingsWeb(ctx, backend);
+    }
+    catch (error) {
+        console.warn('dsh-calendar: 面板路由未挂载：' + (error instanceof Error ? error.message : String(error)));
+    }
     if (typeof ctx.on === 'function') {
         ctx.on('dispose', () => {
             for (const dispose of disposers)
@@ -41,3 +139,6 @@ export * from './config.js';
 export * from './ical.js';
 export * from './caldav.js';
 export * from './tools.js';
+export * from './web.js';
+export * from './settings.js';
+export * from './store.js';

package/lib/settings.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 面板里的「连接设置」写进哪儿：宿主的 settings 命名空间（settings.yaml）。
+ *
+ * 与 dsh-email 同一套契约，理由也相同：
+ *   - 面板是唯一的常规入口，用户不该为了填四个格子去编辑 cordis.patch.yml；
+ *   - 但 cordis.patch.yml 仍是基座：settings 里没碰过的字段由它兜底，所以老用户的
+ *     YAML 配置不会因为装上这个面板就失效（toCalendarConfig 只投影「用户真的设过」
+ *     的字段，schema 默认值绝不覆盖 YAML 与预设）；
+ *   - 密码走 role(secret)，与邮箱授权码同等对待：不进日志、不进导出、不进诊断。
+ */
+import z from 'schemastery';
+import { type CalendarAuthMethod, type CalendarConfig, type CalendarProvider } from './config.js';
+/** 本插件独占的 settings 命名空间。 */
+export declare const SETTINGS_NAMESPACE = "dsh-calendar";
+/**
+ * 面板表单的形状。空串一律表示「没设置」：一行 patch 里的 YAML 配置与面板写下的值
+ * 因此可以共存 —— 谁设过谁说了算。
+ */
+export declare const CalendarSettingsSchema: z<Schemastery.ObjectS<{
+    provider: z<string, string>;
+    caldavUrl: z<string, string>;
+    username: z<string, string>;
+    password: z<string, string>;
+    host: z<string, string>;
+    user: z<string, string>;
+    calendar: z<string, string>;
+    calendarId: z<string, string>;
+    authMethod: z<string, string>;
+    clientId: z<string, string>;
+    clientSecret: z<string, string>;
+    refreshToken: z<string, string>;
+    tokenUrl: z<string, string>;
+    proxyUrl: z<string, string>;
+}>, Schemastery.ObjectT<{
+    provider: z<string, string>;
+    caldavUrl: z<string, string>;
+    username: z<string, string>;
+    password: z<string, string>;
+    host: z<string, string>;
+    user: z<string, string>;
+    calendar: z<string, string>;
+    calendarId: z<string, string>;
+    authMethod: z<string, string>;
+    clientId: z<string, string>;
+    clientSecret: z<string, string>;
+    refreshToken: z<string, string>;
+    tokenUrl: z<string, string>;
+    proxyUrl: z<string, string>;
+}>>;
+export interface CalendarSettingsValue {
+    provider: string;
+    caldavUrl: string;
+    username: string;
+    password: string;
+    host: string;
+    user: string;
+    calendar: string;
+    calendarId: string;
+    authMethod: string;
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    tokenUrl: string;
+    proxyUrl: string;
+}
+/** 把一行 cordis.patch.yml 的配置投影成 schema 的 base（只带有值的字段）。 */
+export declare function toSettingsBase(config: CalendarConfig | undefined): Partial<CalendarSettingsValue>;
+/**
+ * settings 值 → CalendarConfig。
+ *
+ * user 是「用户真的改过哪些键」的投影：只有它列出的字段才会被投影出去，因此 schema
+ * 的默认值（空串）不会擦掉 cordis.patch.yml 里的配置。传 null 表示按草稿全量投影
+ * （保存与测试连接的路径）。
+ */
+export declare function toCalendarConfig(value: Partial<CalendarSettingsValue> | undefined, user?: Partial<CalendarSettingsValue> | null): CalendarConfig;
+/** 连接测试用的「拟议配置」：草稿全量投影，不经过已存值。 */
+export declare function draftToConfig(draft: Partial<CalendarSettingsValue> | undefined): CalendarConfig;
+/**
+ * 写入前的温和校验：结构错误立刻报（中文，面板直接显示），不完整的配置放行 ——
+ * 具体地址拼装留给 resolveConfig，它会在工具调用时给出带指引的错误。
+ */
+export declare function validateSettingsValue(value: Partial<CalendarSettingsValue> | undefined): void;
+export type { CalendarAuthMethod, CalendarProvider };

package/lib/settings.js

@@ -0,0 +1,139 @@
+/**
+ * 面板里的「连接设置」写进哪儿：宿主的 settings 命名空间（settings.yaml）。
+ *
+ * 与 dsh-email 同一套契约，理由也相同：
+ *   - 面板是唯一的常规入口，用户不该为了填四个格子去编辑 cordis.patch.yml；
+ *   - 但 cordis.patch.yml 仍是基座：settings 里没碰过的字段由它兜底，所以老用户的
+ *     YAML 配置不会因为装上这个面板就失效（toCalendarConfig 只投影「用户真的设过」
+ *     的字段，schema 默认值绝不覆盖 YAML 与预设）；
+ *   - 密码走 role(secret)，与邮箱授权码同等对待：不进日志、不进导出、不进诊断。
+ */
+import z from 'schemastery';
+import { CALENDAR_PROVIDERS } from './config.js';
+/** 本插件独占的 settings 命名空间。 */
+export const SETTINGS_NAMESPACE = 'dsh-calendar';
+/**
+ * 面板表单的形状。空串一律表示「没设置」：一行 patch 里的 YAML 配置与面板写下的值
+ * 因此可以共存 —— 谁设过谁说了算。
+ */
+export const CalendarSettingsSchema = z.object({
+    provider: z.string().default(''),
+    caldavUrl: z.string().default(''),
+    username: z.string().default(''),
+    password: z.string().role('secret').default(''),
+    host: z.string().default(''),
+    user: z.string().default(''),
+    calendar: z.string().default(''),
+    calendarId: z.string().default(''),
+    authMethod: z.string().default(''),
+    clientId: z.string().default(''),
+    clientSecret: z.string().role('secret').default(''),
+    refreshToken: z.string().role('secret').default(''),
+    tokenUrl: z.string().default(''),
+    proxyUrl: z.string().default(''),
+});
+const TEXT_KEYS = [
+    'provider', 'caldavUrl', 'username', 'password', 'host', 'user', 'calendar',
+    'calendarId', 'authMethod', 'clientId', 'clientSecret', 'refreshToken', 'tokenUrl', 'proxyUrl',
+];
+/** 把一行 cordis.patch.yml 的配置投影成 schema 的 base（只带有值的字段）。 */
+export function toSettingsBase(config) {
+    const out = {};
+    const cfg = (config ?? {});
+    for (const key of TEXT_KEYS) {
+        const value = cfg[key];
+        if (typeof value === 'string' && value !== '')
+            out[key] = value;
+    }
+    return out;
+}
+function isSet(value) {
+    return value !== undefined && value !== null;
+}
+/**
+ * settings 值 → CalendarConfig。
+ *
+ * user 是「用户真的改过哪些键」的投影：只有它列出的字段才会被投影出去，因此 schema
+ * 的默认值（空串）不会擦掉 cordis.patch.yml 里的配置。传 null 表示按草稿全量投影
+ * （保存与测试连接的路径）。
+ */
+export function toCalendarConfig(value, user) {
+    const draft = (value ?? {});
+    const has = (key) => user === null || (user !== undefined && user[key] !== undefined);
+    const out = {};
+    for (const key of TEXT_KEYS) {
+        if (!has(key))
+            continue;
+        const raw = draft[key];
+        if (!isSet(raw) || raw === '')
+            continue;
+        out[key] = raw;
+    }
+    return out;
+}
+/** 连接测试用的「拟议配置」：草稿全量投影，不经过已存值。 */
+export function draftToConfig(draft) {
+    return toCalendarConfig(draft, null);
+}
+function describe(value) {
+    if (typeof value === 'string')
+        return '"' + value + '"';
+    if (value === undefined)
+        return 'undefined';
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * 写入前的温和校验：结构错误立刻报（中文，面板直接显示），不完整的配置放行 ——
+ * 具体地址拼装留给 resolveConfig，它会在工具调用时给出带指引的错误。
+ */
+export function validateSettingsValue(value) {
+    const draft = (value ?? {});
+    const provider = typeof draft.provider === 'string' ? draft.provider : '';
+    if (provider !== '' && !CALENDAR_PROVIDERS.includes(provider)) {
+        throw new Error('未知的日历服务商 ' + describe(provider) + '，可选：' + CALENDAR_PROVIDERS.join(' / '));
+    }
+    const authMethod = typeof draft.authMethod === 'string' ? draft.authMethod : '';
+    if (authMethod !== '' && authMethod !== 'oauth' && authMethod !== 'basic') {
+        throw new Error('认证方式只能是 oauth 或 basic，收到 ' + describe(authMethod));
+    }
+    if (provider === 'google' && authMethod === 'basic') {
+        throw new Error('Google 不接受 Basic（应用专用密码）：请把认证方式设为 oauth 并填 clientId / clientSecret / refreshToken');
+    }
+    const url = typeof draft.caldavUrl === 'string' ? draft.caldavUrl.trim() : '';
+    if (url !== '' && !/^https?:\/\//i.test(url)) {
+        throw new Error('日历集合 URL 必须以 http:// 或 https:// 开头，收到 ' + describe(url));
+    }
+    const tokenUrl = typeof draft.tokenUrl === 'string' ? draft.tokenUrl.trim() : '';
+    if (tokenUrl !== '' && !/^https?:\/\//i.test(tokenUrl)) {
+        throw new Error('令牌地址必须以 http:// 或 https:// 开头，收到 ' + describe(tokenUrl));
+    }
+    const proxyUrl = typeof draft.proxyUrl === 'string' ? draft.proxyUrl.trim() : '';
+    if (proxyUrl !== '' && !/^https?:\/\//i.test(proxyUrl)) {
+        throw new Error('代理地址必须以 http:// 或 https:// 开头，收到 ' + describe(proxyUrl));
+    }
+    if (provider === 'google') {
+        if ((draft.calendarId ?? '') === '')
+            throw new Error('Google 需要日历 ID（通常是你的邮箱地址）');
+        if ((draft.clientId ?? '') === '')
+            throw new Error('Google 需要 clientId');
+        if ((draft.clientSecret ?? '') === '' || (draft.refreshToken ?? '') === '') {
+            throw new Error('Google 需要 clientSecret 与 refreshToken：两者都由 OAuth 换来，缺一不可');
+        }
+    }
+    if (provider === 'nextcloud') {
+        if ((draft.host ?? '') === '')
+            throw new Error('Nextcloud 需要 host（如 https://cloud.example.com）');
+        if ((draft.user ?? '') === '')
+            throw new Error('Nextcloud 需要 user');
+        if ((draft.calendar ?? '') === '')
+            throw new Error('Nextcloud 需要 calendar（日历名，如 personal）');
+    }
+    if ((provider === 'icloud' || provider === 'custom') && url === '') {
+        throw new Error((provider === 'icloud' ? 'iCloud' : '自建 CalDAV') + '需要完整的日历集合 URL（caldavUrl）');
+    }
+}

package/lib/store.d.ts

@@ -0,0 +1,10 @@
+/** $DSH_HOME/data/dsh-calendar/connection.json（DSH_HOME 缺省 ~/.dsh）。 */
+export declare function connectionFile(env?: NodeJS.ProcessEnv): string;
+export interface StoredConnection {
+    revision: number;
+    value: Record<string, unknown>;
+}
+/** 读兜底文件；不存在、坏了、被改成非对象都当「没有配置」处理（面板会显示引导态）。 */
+export declare function readConnectionFile(file?: string): StoredConnection;
+/** 先写临时文件再改名：中途失败不会留下半份配置。 */
+export declare function writeConnectionFile(stored: StoredConnection, file?: string): void;

package/lib/store.js

@@ -0,0 +1,42 @@
+/**
+ * 连接配置的兜底存放地。
+ *
+ * 首选是宿主的 settings 命名空间（设置页可读、可导出、可诊断）；但社区插件没法保证
+ * 宿主一定提供、也保证不了注册一定成功。所以再加一层：插件自己的 JSON 文件，位置与
+ * dsh-email 的 oauth2-tokens.json 同源（$DSH_HOME/data/<插件>/），写入 0600。
+ * 两条路都只存明文（settings.yaml 本身也是明文），差别只在「谁读得到」。
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** $DSH_HOME/data/dsh-calendar/connection.json（DSH_HOME 缺省 ~/.dsh）。 */
+export function connectionFile(env = process.env) {
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME !== '' ? env.DSH_HOME : join(homedir(), '.dsh');
+    return join(home, 'data', 'dsh-calendar', 'connection.json');
+}
+/** 读兜底文件；不存在、坏了、被改成非对象都当「没有配置」处理（面板会显示引导态）。 */
+export function readConnectionFile(file = connectionFile()) {
+    try {
+        if (!existsSync(file))
+            return { revision: 0, value: {} };
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const raw = parsed.value;
+        const value = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+        const revision = typeof parsed.revision === 'number' && Number.isFinite(parsed.revision) ? Math.trunc(parsed.revision) : 0;
+        return { revision, value };
+    }
+    catch (error) {
+        return { revision: 0, value: {} };
+    }
+}
+/** 先写临时文件再改名：中途失败不会留下半份配置。 */
+export function writeConnectionFile(stored, file = connectionFile()) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = file + '.tmp';
+    writeFileSync(tmp, JSON.stringify({ revision: stored.revision, value: stored.value }, null, 2) + '\n', { mode: 0o600 });
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch (error) { /* Windows 上权限位无效，忽略 */ }
+    renameSync(tmp, file);
+}

package/lib/tools.d.ts

@@ -5,6 +5,7 @@
  * @module dsh-calendar/tools
  */
 import { type CalendarConfig } from './config.js';
+import { type CalendarEvent } from './ical.js';
 /** 模型可见的内容块。 */
 export interface ContentBlock {
     type: 'text';
@@ -26,5 +27,14 @@ export interface CalendarToolDefinition {
     execute(args: unknown, exec: unknown): Promise<unknown>;
     timeoutMs?: number;
 }
+export declare function asRecord(args: unknown): Record<string, unknown>;
+export declare function optionalString(args: Record<string, unknown>, key: string): string | undefined;
+export declare function assertIsoTime(value: string, label: string): void;
+export declare function assertTimeRange(start: string, end: string): void;
+export declare function isoNoMillis(value: string): string;
+/** 按开始时间升序稳定排序（CalDAV 服务端返回顺序不保证稳定）。 */
+export declare function sortEvents(events: CalendarEvent[]): CalendarEvent[];
 /** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
-export declare function buildCalendarTools(config: CalendarConfig | undefined, env?: NodeJS.ProcessEnv): CalendarToolDefinition[];
+/** 配置来源：静态对象，或一个 getter（面板把新配置写进 settings 后，工具下一次调用就该用新的）。 */
+export type CalendarConfigSource = CalendarConfig | undefined | (() => CalendarConfig | undefined);
+export declare function buildCalendarTools(config: CalendarConfigSource, env?: NodeJS.ProcessEnv): CalendarToolDefinition[];

package/lib/tools.js

@@ -9,7 +9,7 @@ import { CALENDAR_PROVIDERS, buildCaldavUrl, resolveAuthMethod, resolveConfig, r
 import { compileParameters } from './parameters.js';
 const EVENT_SCHEMA = { type: 'object', additionalProperties: true };
 const TIMEOUT_MS = 60000;
-function asRecord(args) {
+export function asRecord(args) {
     return typeof args === 'object' && args !== null ? args : {};
 }
 function executionSignal(exec) {
@@ -18,7 +18,7 @@ function executionSignal(exec) {
     const signal = exec.signal;
     return signal instanceof AbortSignal ? signal : undefined;
 }
-function optionalString(args, key) {
+export function optionalString(args, key) {
     const value = args[key];
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 }
@@ -49,7 +49,7 @@ function clampedInteger(args, key, fallback, min, max) {
     return Math.min(max, Math.max(min, value));
 }
 const DATE_ONLY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
-function assertIsoTime(value, label) {
+export function assertIsoTime(value, label) {
     const dateOnly = DATE_ONLY_PATTERN.exec(value);
     if (dateOnly !== null) {
         const year = Number(dateOnly[1]);
@@ -73,16 +73,16 @@ function toEpochMs(value) {
     }
     return new Date(value).getTime();
 }
-function assertTimeRange(start, end) {
+export function assertTimeRange(start, end) {
     if (toEpochMs(start) > toEpochMs(end)) {
         throw new Error('end 不能早于 start：' + end + ' < ' + start + '。请确认起止时间顺序。');
     }
 }
-function isoNoMillis(value) {
+export function isoNoMillis(value) {
     return value.replace(/\.\d{3}Z$/, 'Z');
 }
 /** 按开始时间升序稳定排序（CalDAV 服务端返回顺序不保证稳定）。 */
-function sortEvents(events) {
+export function sortEvents(events) {
     return events
         .map((event, index) => ({ event, index, startMs: toEpochMs(event.start) }))
         .sort((a, b) => a.startMs - b.startMs || a.index - b.index)
@@ -102,12 +102,12 @@ function buildSearchFilter(query) {
         return haystack.includes(needle);
     };
 }
-/** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
 export function buildCalendarTools(config, env = process.env) {
+    const configOf = () => (typeof config === 'function' ? config() : config);
     let cachedKey;
     let cachedService;
     const service = () => {
-        const resolved = resolveConfig(config, env);
+        const resolved = resolveConfig(configOf(), env);
         // 闭包内比较，不写日志或磁盘；凭据/端点变化时不复用旧 token。
         const key = JSON.stringify(resolved);
         if (cachedService === undefined || cachedKey !== key) {
@@ -365,13 +365,15 @@ export function buildCalendarTools(config, env = process.env) {
         async execute(_args, exec) {
             executionSignal(exec)?.throwIfAborted();
             const checks = [];
-            const rawProvider = config?.provider;
+            // 每次自检都重新取配置：面板刚保存的地址应当立刻反映在这里。
+            const current = configOf();
+            const rawProvider = current?.provider;
             const provider = rawProvider === undefined || rawProvider === null || rawProvider === '' ? 'custom' : String(rawProvider);
             const providerOk = CALENDAR_PROVIDERS.includes(provider);
             checks.push({ name: '服务商', ok: providerOk, detail: providerOk ? provider : '不支持 ' + provider + '；只支持 ' + CALENDAR_PROVIDERS.join(' / ') });
             try {
-                const endpoint = buildCaldavUrl(config ?? {}, provider);
-                if (resolveAuthMethod(config) === 'oauth')
+                const endpoint = buildCaldavUrl(current ?? {}, provider);
+                if (resolveAuthMethod(current) === 'oauth')
                     validateOAuthUrl(endpoint, 'caldavUrl');
                 checks.push({ name: '日历地址', ok: true, detail: '已解析为 ' + endpoint });
             }
@@ -379,11 +381,11 @@ export function buildCalendarTools(config, env = process.env) {
                 checks.push({ name: '日历地址', ok: false, detail: error instanceof Error ? error.message : String(error) });
             }
             try {
-                if (resolveAuthMethod(config) === 'oauth') {
+                if (resolveAuthMethod(current) === 'oauth') {
                     checks.push({ name: '认证方式', ok: true, detail: 'OAuth 2.0（无需 username/password）' });
                 }
                 else {
-                    const hasUser = typeof config?.username === 'string' && config.username.trim() !== '';
+                    const hasUser = typeof current?.username === 'string' && current.username.trim() !== '';
                     checks.push({ name: '账号', ok: hasUser, detail: hasUser ? '已配置 Basic 账号' : '未配置：请填 username（iCloud 为账号邮箱）' });
                 }
             }
@@ -391,7 +393,7 @@ export function buildCalendarTools(config, env = process.env) {
                 checks.push({ name: '认证方式', ok: false, detail: error instanceof Error ? error.message : String(error) });
             }
             try {
-                const credentials = resolveCredentials(config, env);
+                const credentials = resolveCredentials(current, env);
                 checks.push({ name: '认证凭据', ok: true, detail: credentials.oauth === undefined
                         ? '已配置 Basic 凭据；仅检查配置，未联网验证'
                         : '已配置 clientId、clientSecret、refreshToken 与 tokenUrl；仅检查配置，未联网验证' });