dsh-plugin-t-expert 0.2.16 → 0.3.6

package/lib/schedule.js

@@ -0,0 +1,423 @@
+// @ts-check
+/**
+ * T专家 定时事项引擎：按 cron 表达式把提示词交给一个**全新的** agent 会话执行。
+ *
+ * 为什么自建而不是直接依赖 `@weibaohui/dsh-tasks`：用户明确要求两个插件可以同时安装、
+ * 同时可用。所以这里与它**零共享**——
+ *   · 数据不落它的 `dsh_tasks` 存储域，而是 T专家 自己的数据目录（`<root 同级>/schedule.json`）；
+ *   · 服务名 `tTeamSchedule`、错误码前缀 `tTeam/schedule-*`、消息来源 `plugin: dsh-plugin-t-expert`
+ *     全部独立，两个插件的任务互不可见、互不干扰。
+ *
+ * 三件事在这里闭环：
+ *   1. 持久化：一个 JSON 文件，原子写（与 `teams.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专家 数据根下，与 teams.json 同级）。 */
+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;
+  return { title, prompt, cron, enabled, ...(workspaceId === undefined ? {} : { workspaceId }) };
+}
+
+/**
+ * 创建定时事项引擎。
+ *
+ * @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 {(text: string) => Promise<string>} [options.expandPrompt] - 提交前的提示词改写
+ *   （提示词里挑中的  由它落成召唤指令）。缺省就是原文。
+ */
+export function createScheduleEngine(options) {
+  const { ctx, file, logger, t, defaultCwd } = options;
+  /** 提交前的提示词改写：没有注入就原样提交（定时任务本身不依赖它）。 */
+  const expandPrompt = typeof options.expandPrompt === "function"
+    ? options.expandPrompt
+    : async (text) => text;
+  /** @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 } : {}),
+          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"));
+      }
+      const workspace = item.workspaceId === undefined
+        ? undefined
+        : ctx.get("workspaceRegistry")?.get?.(item.workspaceId);
+      if (item.workspaceId !== undefined && workspace === undefined) {
+        throw new Error(t("schedule.workspaceMissing", { id: item.workspaceId }));
+      }
+      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 {
+        /* 标题没钉上也照样执行 */
+      }
+      // 提示词里可能带 `@专家名`（面板里挑中的那位）：交给注入的改写器落成召唤指令。
+      // 改写失败不致命 —— 退回原文提交，任务照跑，只在日志里留一句可查的线索。
+      let promptText = item.prompt;
+      try {
+        promptText = await expandPrompt(item.prompt);
+      } catch (error) {
+        logger?.warn?.(`[t-team] 定时任务「${item.title}」的提示词改写失败，按原文提交：${error instanceof Error ? error.message : String(error)}`);
+      }
+      handle.agent.followup({
+        id: randomUUID(),
+        role: "user",
+        content: [{ type: "text", text: promptText }],
+        source: { kind: "plugin", plugin: PLUGIN_ID },
+      });
+      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 ?? ""),
+      })).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,
+    };
+    const fields = normalizeInput(merged, t);
+    const next = { ...current, ...fields, updatedAt: new Date().toISOString() };
+    // 展开旧记录会把旧的 workspaceId 一起带过来：用户把绑定改回「不绑定」时
+    // fields 里没有这个键，必须显式删掉，否则界面上看着解绑了、执行时还挂在旧工作区。
+    if (fields.workspaceId === undefined) delete next.workspaceId;
+    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 };
+  }
+
+  /** 卸载：停掉全部定时器（数据留着，下次启动重建）。 */
+  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) }),
+    setArmed,
+    isArmed: () => armed,
+    /** 当前真正挂着定时器的事项 id（自检与诊断用：能看出"任务在、但没排定"这种失效）。 */
+    scheduledIds: () => [...jobs.keys()],
+    dispose,
+    /** 开关变化后重建调度（settings 回调里用）。 */
+    rescheduleAll,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-t-expert",
-  "version": "0.2.16",
+  "version": "0.3.6",
   "type": "module",
   "description": "T Expert — a 316-expert, 22-division roster with full Chinese translations, as a standalone DeepSeek Harness plugin, with a built-in multi-agent team engine (T Team).",
   "license": "MIT",
@@ -172,6 +172,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "croner": "^9.1.0",
     "zod": "^4.4.3"
   }
 }

package/skills/t-expert-manager/SKILL.md

@@ -103,9 +103,15 @@ bash "{{TZ}}" install           # 装到 profile（默认 desktop）；可先 --
 
 ```bash
 bash "{{TZ}}" publish-dry       # 预演：只跑预检与打包预览
-bash "{{TZ}}" publish           # 默认 patch；也可 --minor / --major / --version X.Y.Z
+bash "{{TZ}}" publish --current # 直接发布 package.json 里的当前版本（不升版）—— 版本号在开发期就写好了
+bash "{{TZ}}" publish           # 交互选版本（菜单里选项 1 就是"发布当前版本"）；也可 --patch / --minor / --major / --version X.Y.Z
 ```
 
+> 版本号的单一来源是 `package.json`：菜单 15 会把**当前版本号自动读出来**并作为首选，
+> 客户端构建版本（`CLIENT_BUILD_VERSION`）与它必须一致（verify 有断言盯着），所以通常不需要在发布时再 bump。
+> 回车＝取消（发布不可逆，没有"回车即发"的默认）。
+> 选「发布当前版本」不跑 `npm version`，但会**给该版本补一个 tag** —— 发出去的版本要能对应到具体提交，失败后也才能用 `--retry` 重试。
+
 **发布前必须**：(a) 得到用户明确同意；(b) `experts check` 与 `verify` 全绿；(c) 工作区没有未提交的意外改动。
 
 ## 汇报约定

package/vendor/third-party-licenses/croner.LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Hexagon <github.com/Hexagon>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+