dsh-plugin-t-expert 0.3.90 → 0.3.92

package/lib/schedule.js

@@ -1,509 +0,0 @@
-// @ts-check
-/**
- * T专家 定时事项引擎：按 cron 表达式把提示词交给一个**全新的** agent 会话执行。
- *
- * 为什么自建而不是直接依赖 `@weibaohui/dsh-tasks`：用户明确要求两个插件可以同时安装、
- * 同时可用。所以这里与它**零共享**——
- *   · 数据不落它的 `dsh_tasks` 存储域，而是 T专家 自己的数据目录（`<root 同级>/schedule.json`）；
- *   · 服务名 `tTeamSchedule`、错误码前缀 `tTeam/schedule-*` 全部独立，两个插件的任务互不可见、互不干扰。
- *     提交给会话的提示词用 `source.kind: "user"`（聊天右侧才渲染用户气泡；`plugin` 源会被收成 inject）。
- *
- * 三件事在这里闭环：
- *   1. 持久化：一个 JSON 文件，原子写（与名册数据同风格）；
- *   2. 调度：每个启用项一个 croner job，宿主启动时全量重建，卸载时全部 stop；
- *   3. 执行：新建 agent 会话 → 挂部署默认 preset（不挂就没有工具）→ 提交提示词。
- *
- * 开关语义（用户口径）：`setArmed(false)` = 定时事项功能整体停用——**停止全部定时触发**
- * 且拒绝手动执行；任务与执行记录完整保留，重新 armed 后自动恢复调度。
- */
-import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { Cron } from "croner";
-import { writeFileAtomic } from "./catalog.js";
-
-/** 定时事项服务名（remote 侧的服务访问器用它）。 */
-export const SCHEDULE_SERVICE = "tTeamSchedule";
-/** 数据文件名（落在 T专家 数据根下）。 */
-export const SCHEDULE_FILE_NAME = "schedule.json";
-/** 每条事项保留的执行记录条数（最旧的先丢）。 */
-export const MAX_RUNS = 20;
-/** 事项条数上限（防止一次误操作把设置文件写成天文数字）。 */
-export const MAX_ITEMS = 200;
-/** 标题 / 提示词的字符上限。 */
-export const MAX_TITLE_CHARS = 200;
-export const MAX_PROMPT_CHARS = 20000;
-/** 写进会话消息来源的插件名（与 dsh-tasks 区分开，两个插件的任务是两回事）。 */
-export const PLUGIN_ID = "dsh-plugin-t-expert";
-
-/**
- * cron 表达式校验：构造一个 `paused` 的探测 job（只解析、不真的挂定时器），
- * 随即 stop 掉，保证探测本身不会让事件循环多活一秒。
- * @param {unknown} expression - 待校验的表达式。
- * @param {(key: string, params?: Record<string, unknown>) => string} t - host 侧文案函数。
- */
-export function validateCron(expression, t) {
-  const text = typeof expression === "string" ? expression.trim() : "";
-  if (text === "") throw new Error(t("schedule.cronEmpty"));
-  try {
-    const probe = new Cron(text, { paused: true }, () => undefined);
-    probe.stop();
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(t("schedule.invalidCron", { detail }));
-  }
-  return text;
-}
-
-/** 该表达式接下来的若干次触发时间（ISO 串），供面板在保存前预览。 */
-export function previewRuns(expression, t, count = 5) {
-  const text = validateCron(expression, t);
-  const probe = new Cron(text, { paused: true });
-  try {
-    return probe.nextRuns(count).map((date) => date.toISOString());
-  } finally {
-    probe.stop();
-  }
-}
-
-/** 短本地时间戳（`MM-DD HH:mm`）：同一个事项的多次运行在侧栏里要能区分开。 */
-export function runStamp(iso) {
-  const date = new Date(iso);
-  const pad = (value) => String(value).padStart(2, "0");
-  return `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
-}
-
-/** 追加一条执行记录（超过上限丢最旧的），并刷新最近一次执行摘要字段。 */
-export function withRun(item, entry) {
-  const runs = [...(Array.isArray(item.runs) ? item.runs : []), entry].slice(-MAX_RUNS);
-  const next = { ...item, runs, lastRunAt: entry.at };
-  // 成功时**删掉**失败字段而不是置 undefined：线上（remote 严格 schema）与 JSON 都不需要
-  // 一个"值为 undefined 的键"，留着只会让序列化前后形状不一致。
-  if (entry.ok === true) delete next.lastRunError;
-  else next.lastRunError = entry.error || "failed";
-  return next;
-}
-
-/** 校验一条事项的入参（面板提交的形状）；返回规范化后的字段。 */
-export function normalizeInput(input, t) {
-  if (input === null || typeof input !== "object") throw new Error(t("schedule.inputInvalid"));
-  const raw = /** @type {Record<string, unknown>} */ (input);
-  const title = typeof raw.title === "string" ? raw.title.trim() : "";
-  const prompt = typeof raw.prompt === "string" ? raw.prompt : "";
-  if (title === "") throw new Error(t("schedule.titleEmpty"));
-  if (title.length > MAX_TITLE_CHARS) throw new Error(t("schedule.titleTooLong", { limit: MAX_TITLE_CHARS }));
-  if (prompt.trim() === "") throw new Error(t("schedule.promptEmpty"));
-  if (prompt.length > MAX_PROMPT_CHARS) throw new Error(t("schedule.promptTooLong", { limit: MAX_PROMPT_CHARS }));
-  const cron = validateCron(raw.cron, t);
-  const enabled = raw.enabled !== false;
-  const workspaceId = typeof raw.workspaceId === "string" && raw.workspaceId !== "" ? raw.workspaceId : undefined;
-  const workspacePath = typeof raw.workspacePath === "string" && raw.workspacePath !== "" ? raw.workspacePath : undefined;
-  return {
-    title, prompt, cron, enabled,
-    ...(workspaceId === undefined ? {} : { workspaceId }),
-    ...(workspacePath === undefined ? {} : { workspacePath }),
-  };
-}
-
-/**
- * 创建定时事项引擎。
- *
- * @param {object} options
- * @param {any} options.ctx - 插件上下文（用 `ctx.get(...)` 懒查可选服务）。
- * @param {string} options.file - 数据文件绝对路径。
- * @param {any} options.logger - cordis logger（可缺省）。
- * @param {(key: string, params?: Record<string, unknown>) => string} options.t - host 文案函数。
- * @param {string} options.defaultCwd - 不绑定工作区时的会话工作目录。
- * @param {boolean} [options.armed] - 初始是否启用调度（= 界面开关的当前值）。
- * @param {(path: string, title?: string) => Promise<{ id: string, title: string, path: string }>} [options.ensureWorkspace]
- *   - 准备定时任务的工作区（默认「定时任务」工作区，或面板里填的自定义目录）。缺省则面板该项不可用。
- */
-export function createScheduleEngine(options) {
-  const { ctx, file, logger, t, defaultCwd } = options;
-  /** 工作区准备（默认「定时任务」工作区 / 自定义目录），由 host 注入。 */
-  const ensureWorkspace = typeof options.ensureWorkspace === "function" ? options.ensureWorkspace : undefined;
-  /** @type {Map<string, any>} id → 事项 */
-  const items = new Map();
-  /** @type {Map<string, any>} id → croner job */
-  const jobs = new Map();
-  /** 正在执行中的事项 id：同一事项不并发跑两次。 */
-  const running = new Set();
-  let armed = options.armed !== false;
-  /** 写盘串行链：并发变更不能交错写同一个文件。 */
-  let writeChain = Promise.resolve();
-
-  /** 读盘（同步，apply 期就要拿到数据）。读不动时**出声**并按空列表继续。 */
-  function load() {
-    let text;
-    try {
-      text = readFileSync(file, "utf8");
-    } catch (error) {
-      const code = /** @type {any} */ (error)?.code;
-      if (code !== "ENOENT") {
-        logger?.warn?.(`[t-team] 定时事项数据文件读取失败（按空列表继续）：${file}：${error instanceof Error ? error.message : String(error)}`);
-      }
-      return;
-    }
-    try {
-      const parsed = JSON.parse(text);
-      const list = Array.isArray(parsed?.items) ? parsed.items : [];
-      for (const entry of list) {
-        if (entry === null || typeof entry !== "object") continue;
-        if (typeof entry.id !== "string" || typeof entry.cron !== "string") continue;
-        items.set(entry.id, {
-          id: entry.id,
-          title: typeof entry.title === "string" ? entry.title : "",
-          prompt: typeof entry.prompt === "string" ? entry.prompt : "",
-          cron: entry.cron,
-          enabled: entry.enabled !== false,
-          ...(typeof entry.workspaceId === "string" && entry.workspaceId !== "" ? { workspaceId: entry.workspaceId } : {}),
-          // 绑定时同步记下当时的工作区目录：工作区被删后用它「重建」回到原路径，避免要用户重填。
-          ...(typeof entry.workspacePath === "string" && entry.workspacePath !== "" ? { workspacePath: entry.workspacePath } : {}),
-          createdAt: typeof entry.createdAt === "string" ? entry.createdAt : new Date().toISOString(),
-          updatedAt: typeof entry.updatedAt === "string" ? entry.updatedAt : new Date().toISOString(),
-          ...(typeof entry.lastRunAt === "string" ? { lastRunAt: entry.lastRunAt } : {}),
-          ...(typeof entry.lastRunError === "string" ? { lastRunError: entry.lastRunError } : {}),
-          runs: Array.isArray(entry.runs) ? entry.runs.slice(-MAX_RUNS) : [],
-        });
-      }
-    } catch (error) {
-      logger?.warn?.(`[t-team] 定时事项数据文件解析失败（按空列表继续）：${file}：${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /** 落盘：串行 + 原子写（临时文件 + rename），失败只告警不打断内存态。 */
-  function persist() {
-    const payload = `${JSON.stringify({ version: 1, items: [...items.values()] }, null, 2)}\n`;
-    writeChain = writeChain
-      .then(() => writeFileAtomic(file, payload))
-      .catch((error) => {
-        logger?.warn?.(`[t-team] 定时事项写盘失败：${file}：${error instanceof Error ? error.message : String(error)}`);
-      });
-    return writeChain;
-  }
-
-  /** 停掉一个 job（幂等）。 */
-  function stopJob(id) {
-    const job = jobs.get(id);
-    if (job === undefined) return;
-    try {
-      job.stop();
-    } catch {
-      /* 已经停掉的 job 再 stop 无所谓 */
-    }
-    jobs.delete(id);
-  }
-
-  /** 按当前 armed 状态与 enabled 标记给一条事项挂/摘定时器。 */
-  function scheduleOne(item) {
-    stopJob(item.id);
-    if (!armed || item.enabled !== true) return;
-    try {
-      // `unref: true`：不让定时器把宿主进程的事件循环钉住（进程想退出就能退出）。
-      // 它是 croner 的**构造选项**，不是 job 上的方法（写成 job.unref() 会静默无效）。
-      const job = new Cron(item.cron, { unref: true }, () => {
-        void runScheduled(item.id);
-      });
-      jobs.set(item.id, job);
-    } catch (error) {
-      // 表达式在写入时已校验过，这里失败只可能是运行期异常（例如 croner 版本差异）：
-      // 记一条 warn 并保持该事项不调度，别让一个坏 job 拖垮整张表。
-      logger?.warn?.(`[t-team] 定时事项「${item.title}」调度失败（该事项不会自动触发）：${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /** 全量重建调度表（启动、开关切换、批量变更后调用）。 */
-  function rescheduleAll() {
-    for (const id of [...jobs.keys()]) stopJob(id);
-    if (!armed) return;
-    for (const item of items.values()) scheduleOne(item);
-  }
-
-  /** 定时触发的入口：跑完更新记录并落盘。 */
-  async function runScheduled(id) {
-    const current = items.get(id);
-    if (current === undefined || !armed) return;
-    if (running.has(id)) return; // 上一轮还没跑完，这一轮跳过（不排队、不叠加）
-    const updated = await execute(current);
-    items.set(id, updated);
-    await persist();
-  }
-
-  /**
-   * 执行一条事项：新建会话 + 提交提示词，把结果记进 runs。
-   * 失败**不抛**（定时路径没人接异常），而是把原因写进 `lastRunError`。
-   */
-  async function execute(item) {
-    const startedAt = new Date().toISOString();
-    running.add(item.id);
-    try {
-      const agents = ctx.get("agents");
-      if (agents === undefined || typeof agents.create !== "function") {
-        throw new Error(t("schedule.agentsMissing"));
-      }
-      // 工作区解析：绑过 → 查 registry；查不到 → 按 task 记的路径自动 mkdir + create。
-      // 这是用户口径"工作区目录没了就自动新建"的实现点。recover 已经在内部把 workspaceId 写回 items。
-      let workspace = item.workspaceId === undefined
-        ? undefined
-        : ctx.get("workspaceRegistry")?.get?.(item.workspaceId);
-      if (item.workspaceId !== undefined && workspace === undefined) {
-        const recovered = await tryAutoRecoverWorkspace(item);
-        if (recovered === null || recovered === undefined) {
-          // 实在没路径可恢复（老数据迁移后没记路径）：给个明确报错让面板呈现。
-          const hint = typeof item.workspacePath === "string" && item.workspacePath !== ""
-            ? t("schedule.workspaceMissingWithPath", { id: item.workspaceId, path: item.workspacePath })
-            : t("schedule.workspaceMissing", { id: item.workspaceId });
-          throw new Error(hint);
-        }
-        workspace = recovered;
-      }
-      const selection = ctx.get("agentDefaultModel")?.currentSelection?.() ?? {};
-      const sessionId = `session-${randomUUID()}`;
-      const handle = await agents.create({
-        sessionId,
-        meta: { cwd: workspace ? workspace.path : defaultCwd },
-        ...(typeof selection.provider === "string" && typeof selection.model === "string"
-          ? { agentOptions: { provider: selection.provider, model: selection.model } }
-          : {}),
-        // 没有 preset 挂载的新会话**没有任何工具**（模型只能空口回答），所以这里按 web 网关
-        // 建会话的同款做法解析并挂上部署的默认 preset。
-        setup: async (agentCtx) => {
-          const presets = ctx.get("agentPresets");
-          if (!presets || typeof presets.resolve !== "function" || typeof presets.mount !== "function") return;
-          const resolved = await presets.resolve(undefined);
-          if (resolved && resolved.id) await presets.mount(agentCtx, resolved.id);
-        },
-      });
-      if (workspace !== undefined && typeof workspace.attachSession === "function") {
-        await workspace.attachSession(sessionId);
-      }
-      // 标题钉成「事项标题 · 时间」：同一事项的多次运行在侧栏里能一一区分。
-      // 以 `user` 来源直接写日志，避免自动标题生成把它覆盖掉（失败不致命）。
-      try {
-        handle.agent.session.append("session/title", {
-          title: `${item.title} · ${runStamp(startedAt)}`,
-          messageSeqs: [],
-          source: { kind: "user" },
-        });
-      } catch {
-        /* 标题没钉上也照样执行 */
-      }
-      // 提示词**原样提交**：定时任务开的新会话与手动会话挂同一份 system prompt，里面已经写着
-      // 「看到 `@专家名` 就 summon_t_expert FIRST」。这里再做一次改写只会让同一个任务在定时任务
-      // 里显示成一长段模板、在手动对话里却只是 `@名字`，两条入口观感不一致（用户实测反馈）。
-      const promptText = item.prompt;
-      // 必须用 source.kind: "user"：DSH 聊天把非 user 的 user/message 收成左侧
-      // inject/context（plugin 源只显示插件名，正文不进右侧气泡）。定时任务的指令
-      // 本身就是用户写的提示词，应当像手打那条一样出现在对话右侧。
-      handle.agent.followup({
-        id: randomUUID(),
-        role: "user",
-        content: [{ type: "text", text: promptText }],
-        source: { kind: "user" },
-      });
-      return withRun(item, { at: startedAt, ok: true, sessionId });
-    } catch (error) {
-      return withRun(item, {
-        at: startedAt,
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    } finally {
-      running.delete(item.id);
-    }
-  }
-
-  load();
-  // 读盘之后必须**立刻**按当前开关挂上定时器：少了这一句，插件每次启动都是"任务在、但永远不触发"，
-  // 直到用户碰一下开关或增删一条才恢复 —— 那种"看着正常、其实没在跑"的失效最难发现，所以这里
-  // 也有对应自检（verify [20c] 的「重启后 enabled 的任务自动进入调度」）。
-  rescheduleAll();
-
-  /** 面板要的全部数据：事项 + 开关状态 + 可选工作区（一次调用拿全，省一次往返）。 */
-  function snapshot() {
-    const registry = ctx.get("workspaceRegistry") ?? ctx.get("workspace");
-    const list = typeof registry?.list === "function" ? registry.list() : [];
-    return {
-      items: [...items.values()],
-      armed,
-      file,
-      running: [...running],
-      capabilities: {
-        agents: typeof ctx.get("agents")?.create === "function",
-        presets: typeof ctx.get("agentPresets")?.mount === "function",
-      },
-      workspaces: list.map((workspace) => ({
-        id: String(workspace.id ?? ""),
-        title: String(workspace.title ?? workspace.path ?? ""),
-        // 目录：面板把它显示在表单里，用户能看清这条任务落在哪个文件夹。
-        path: typeof workspace.path === "string" ? workspace.path : "",
-      })).filter((workspace) => workspace.id !== ""),
-    };
-  }
-
-  /** 新建一条事项。 */
-  async function create(input) {
-    if (items.size >= MAX_ITEMS) throw new Error(t("schedule.tooManyItems", { limit: MAX_ITEMS }));
-    const fields = normalizeInput(input, t);
-    const now = new Date().toISOString();
-    const item = {
-      id: `item-${randomUUID()}`,
-      ...fields,
-      createdAt: now,
-      updatedAt: now,
-      runs: [],
-    };
-    items.set(item.id, item);
-    scheduleOne(item);
-    await persist();
-    return item;
-  }
-
-  /** 改一条事项（只覆盖传进来的字段）。 */
-  async function update(id, patch) {
-    const current = items.get(id);
-    if (current === undefined) throw new Error(t("schedule.itemMissing", { id }));
-    const source = patch === null || typeof patch !== "object" ? {} : patch;
-    const merged = {
-      title: source.title === undefined ? current.title : source.title,
-      prompt: source.prompt === undefined ? current.prompt : source.prompt,
-      cron: source.cron === undefined ? current.cron : source.cron,
-      enabled: source.enabled === undefined ? current.enabled : source.enabled,
-      workspaceId: source.workspaceId === undefined ? current.workspaceId : source.workspaceId,
-      // workspacePath 与 workspaceId 一同从表单过来；老数据没有也不补（创建时记的是绑定那一刻的目录）。
-      workspacePath: source.workspacePath === undefined ? current.workspacePath : source.workspacePath,
-    };
-    const fields = normalizeInput(merged, t);
-    const next = { ...current, ...fields, updatedAt: new Date().toISOString() };
-    // 展开旧记录会把旧的 workspaceId 一起带过来：用户把绑定改回「不绑定」时
-    // fields 里没有这个键，必须显式删掉，否则界面上看着解绑了、执行时还挂在旧工作区。
-    if (fields.workspaceId === undefined) delete next.workspaceId;
-    if (fields.workspacePath === undefined) delete next.workspacePath;
-    items.set(id, next);
-    scheduleOne(next);
-    await persist();
-    return next;
-  }
-
-  /** 删一条事项（顺带摘掉它的定时器）。 */
-  async function remove(id) {
-    if (!items.has(id)) throw new Error(t("schedule.itemMissing", { id }));
-    stopJob(id);
-    items.delete(id);
-    await persist();
-    return { removed: true };
-  }
-
-  /** 立即执行一条事项（面板上的「立即执行」）。 */
-  async function runNow(id) {
-    if (!armed) throw new Error(t("schedule.disabled"));
-    const current = items.get(id);
-    if (current === undefined) throw new Error(t("schedule.itemMissing", { id }));
-    if (running.has(id)) return current; // 正在跑就原样返回，面板保持「执行中…」
-    const updated = await execute(current);
-    items.set(id, updated);
-    await persist();
-    return updated;
-  }
-
-  /**
-   * 开关联动：关掉 = 停止全部定时触发并拒绝手动执行；打开 = 按 stored enabled 全量重建。
-   * 只改运行态，不写数据文件（开关本身是界面偏好，存在宿主设置里）。
-   */
-  function setArmed(next) {
-    const value = next !== false;
-    if (value === armed) return { armed };
-    armed = value;
-    rescheduleAll();
-    return { armed };
-  }
-
-  /**
-   * 自动恢复：执行路径发现工作区不见了，但任务里记着目录 → 顺着把工作区建回来。
-   * 这是用户口径"工作区目录没了就自动新建"的实现点：
-   *   - execute 拿到 registry.get 拿不到的 workspace 时，先看 item.workspacePath：
-   *     · 路径已记录：按这个路径 ensureWorkspace（**会顺带 mkdir 目录**，宿主 createCanonical 内部对同路径幂等复用）。
-   *     · 没路径：只能抛错让用户去左侧手动建一次工作区（之后 schedule.json 里的 workspaceId 会被自动建回。
-   *       老数据迁移后第一次失败就属于这种情况）。
-   *   - 恢复成功后顺便把 workspaceId 刷回去（**mutate 传入的 item + items.set 同步**：
-   *     execute 自身就是单飞序列，传入的 item 是 Map 里的那条引用；mutate 后 withRun 能
-   *     拿到最新字段，items.set + persist 保证落盘，调度下次直接命中 registry）。
-   *
-   * @returns 恢复出来的 workspace（已经是 registry 里的实体）；返回 null 表示不可恢复。
-   */
-  async function tryAutoRecoverWorkspace(item) {
-    const finalPath = resolveRebuildPath(item, undefined);
-    if (finalPath === "") return null;
-    try {
-      const workspace = await ensureOrFail(finalPath);
-      // 1) mutate 传入的 item：execute 后面的 withRun(item, ...) 直接看到新 workspaceId/Path。
-      item.workspaceId = workspace.id;
-      item.workspacePath = workspace.path;
-      item.updatedAt = new Date().toISOString();
-      delete item.lastRunError;
-      // 2) items.set 触发 Map 引用更新（与 mutate 实际指向同一对象，但保持语义一致）；
-      //    persist 把这条新字段落到磁盘。
-      items.set(item.id, item);
-      await persist();
-      logger?.info?.(`[t-team] 定时事项「${item.title}」绑定的工作区不存在，已按原路径 ${finalPath} 自动重建（id=${workspace.id}）。`);
-      return workspace;
-    } catch (error) {
-      logger?.warn?.(`[t-team] 定时事项「${item.title}」自动恢复工作区失败：${error instanceof Error ? error.message : String(error)}`);
-      return null;
-    }
-  }
-
-  /** 抽取"用哪条 path"的判定：外部传入优先，否则用 task 记的。两边都没有就返回空串。 */
-  function resolveRebuildPath(item, override) {
-    if (typeof override === "string" && override.trim() !== "") return override.trim();
-    if (typeof item?.workspacePath === "string" && item.workspacePath.trim() !== "") return item.workspacePath.trim();
-    return "";
-  }
-
-  /**
-   * 调宿主的工作区准备能力拿实体。宿主若未注入（理论上不会发生，scheduleEngine 必然随插件注入）
-   * 就在这里抛错，调用方自己决定是抛还是降级。
-   */
-  function ensureOrFail(path) {
-    if (ensureWorkspace === undefined) {
-      return Promise.reject(new Error("宿主没有提供工作区准备能力（ensureWorkspace）。"));
-    }
-    return ensureWorkspace(path, undefined);
-  }
-
-  /** 卸载：停掉全部定时器（数据留着，下次启动重建）。 */
-  function dispose() {
-    for (const id of [...jobs.keys()]) stopJob(id);
-  }
-
-  return {
-    file,
-    snapshot,
-    list: () => [...items.values()],
-    create,
-    update,
-    remove,
-    runNow,
-    preview: (cron) => ({ fires: previewRuns(cron, t) }),
-    /**
-     * 给面板用：确保定时任务的默认工作区（或自定义目录）存在，返回精简 { id, title, path }。
-     *
-     * 注意：这里不直接转发 host 注入的 ensureWorkspace，因为后者现在透的是完整 entity
-     * （含 attachSession 等方法引用），不能塞进 remote 的 zod 严格 schema；面板用不上那些方法，
-     * 拿 id/title/path 就够了。
-     */
-    ensureWorkspace: async (path, title) => {
-      if (ensureWorkspace === undefined) {
-        throw new Error("宿主没有提供工作区准备能力（ensureWorkspace）。");
-      }
-      const entity = await ensureWorkspace(path, title);
-      return { id: String(entity.id), title: String(entity.title ?? ""), path: String(entity.path ?? "") };
-    },
-    setArmed,
-    isArmed: () => armed,
-    /** 当前真正挂着定时器的事项 id（自检与诊断用：能看出"任务在、但没排定"这种失效）。 */
-    scheduledIds: () => [...jobs.keys()],
-    dispose,
-    /** 开关变化后重建调度（settings 回调里用）。 */
-    rescheduleAll,
-  };
-}