@sidleo3/dsh-chat 0.0.4

package/host/deferred.mjs

@@ -0,0 +1,291 @@
+/**
+ * 延迟交付：**超时放手之后，继续有界地盯着这一轮的终态，拿到结果就补发**。
+ *
+ * 为什么需要它：`ask()` 的超时兜底只防"流断了/回合卡死"，不是长任务。可一旦判定超时，
+ * 我们就把 follow 流收掉、渠道只回一句「回合未正常结束（timeout）」——如果那一轮其实之后
+ * 跑完了，**最终答案谁也拿不到**（"回合跑完但用户没收到"这条故障线本仓库栽过两次）。
+ *
+ * 做法（照上游 dsh-im 的 deferred-delivery 收窄）：
+ * - 超时时只**登记一条待交付记录**（会话路由 + sessionId + turn + 超时原因），不重问、不重跑；
+ * - 之后**有界复查**：先等 `firstCheckMs`，再每 `intervalMs` 一次，最多盯 `maxAgeMs`；
+ *   每次用调用方给的 `probe` 问一句"这个会话还在跑吗、最后一条助手正文是什么"；
+ * - 会话空闲且拿到非空正文 → 交给渠道注册的 `deliver` 补发，然后删记录；
+ * - 会话没了 / 一直空闲但没有正文 / 盯满时限 → 删记录并留日志（不静默）。
+ *
+ * 语义边界（与上游一致）：平台侧没有消息事务，**不承诺恰好一次**——补发过但删记录前崩溃、
+ * 或同一 chat 里紧接着又有一轮很快结束，都可能重复补发一次。宁可能重复，也不丢。
+ *
+ * 记录落盘（`deferred.json`）：进程重启后由渠道在重新建桥时 `register`，届时重新起盯；
+ * 盯不到就按上面的规则清掉。
+ *
+ * @module dsh-chat/host/deferred
+ */
+
+import { join } from 'node:path';
+
+import { createJsonStore } from './json-store.mjs';
+
+/** 超时后第一次复查的等待：给它一点时间自己跑完（真机上"刚好差一点"是最常见的情况）。 */
+const FIRST_CHECK_MS = 60_000;
+/** 之后每次复查的间隔。 */
+const INTERVAL_MS = 30_000;
+/** 最多盯多久：超过就认了（记录删掉、日志留痕）。 */
+const MAX_AGE_MS = 30 * 60_000;
+/** 同一个会话键最多留几条：多了说明这个 chat 一直在超时，留最新的就够。 */
+const MAX_PER_KEY = 2;
+/** 正文长度上限：与最终答案同一个量级，防一条记录把状态文件撑爆。 */
+const MAX_TEXT = 8_000;
+
+/**
+ * 创建延迟交付服务。
+ *
+ * @param options - {
+ *   dataDir, logger, probe, firstCheckMs?, intervalMs?, maxAgeMs?,
+ * }。
+ *   `probe({ record })` 由 hub 提供：返回 `{ exists, running, text }`（会话在不在、是否还在跑、
+ *   最后一条助手正文）。这样这个模块不碰 DSH 的细节，只负责"盯 + 补发"。
+ * @returns 服务：ready / register / schedule / checkNow / list / forgetKey / stop。
+ */
+export function createDeferredDelivery({
+  dataDir,
+  logger = console,
+  probe,
+  firstCheckMs = FIRST_CHECK_MS,
+  intervalMs = INTERVAL_MS,
+  maxAgeMs = MAX_AGE_MS,
+} = {}) {
+  if (typeof dataDir !== 'string' || !dataDir.trim()) {
+    throw new TypeError('延迟交付需要 dataDir。');
+  }
+  if (typeof probe !== 'function') throw new TypeError('延迟交付需要 probe。');
+
+  const store = createJsonStore({
+    path: join(dataDir, 'deferred.json'),
+    empty: () => ({ version: 1, records: [] }),
+    normalize: (value) => {
+      const source = value && typeof value === 'object' && Array.isArray(value.records) ? value : { records: [] };
+      return {
+        version: 1,
+        records: source.records.filter((row) => row && typeof row === 'object'
+          && typeof row.id === 'string' && typeof row.sessionId === 'string'
+          && typeof row.channelId === 'string' && typeof row.botId === 'string'
+          && typeof row.key === 'string').map((row) => ({
+          id: row.id,
+          channelId: row.channelId,
+          botId: row.botId,
+          key: row.key,
+          sessionId: row.sessionId,
+          turn: Number.isInteger(row.turn) ? row.turn : null,
+          startedAt: Number.isFinite(row.startedAt) ? row.startedAt : null,
+          timedOutAt: Number.isFinite(row.timedOutAt) ? row.timedOutAt : Date.now(),
+          reason: typeof row.reason === 'string' ? row.reason : 'timeout',
+          attempts: Number.isInteger(row.attempts) ? row.attempts : 0,
+          lastError: typeof row.lastError === 'string' ? row.lastError : null,
+        })),
+      };
+    },
+    logger,
+    label: '延迟交付记录',
+  });
+
+  /** `${channelId}:${botId}` → 渠道注册的补发函数（渠道建桥时注册）。 */
+  const deliverers = new Map();
+  /** id → 定时器（unref，不拖住进程退出）。 */
+  const timers = new Map();
+  let stopped = false;
+  let seq = 0;
+
+  const keyOf = (row) => `${row.channelId}:${row.botId}`;
+  const find = (id) => store.snapshot().records.find((row) => row.id === id) ?? null;
+
+  function clearTimer(id) {
+    const timer = timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timers.delete(id);
+    }
+  }
+
+  /** 记一条：落盘 + 起盯。 */
+  async function persist(records) {
+    await store.update(() => ({ version: 1, records }));
+  }
+
+  async function drop(id, why) {
+    clearTimer(id);
+    const row = find(id);
+    if (!row) return;
+    await persist(store.snapshot().records.filter((item) => item.id !== id));
+    logger.info?.(`[dsh-chat] 延迟交付记录已清理（${why}）：${row.channelId}/${row.botId} ${row.key}`
+      + ` 会话=${row.sessionId}`);
+  }
+
+  /** 一次复查：还在跑就继续等，空闲且有正文就补发。 */
+  async function check(id) {
+    if (stopped) return;
+    const row = find(id);
+    if (!row) {
+      clearTimer(id);
+      return;
+    }
+    const age = Date.now() - (row.timedOutAt ?? Date.now());
+    let state = null;
+    try {
+      state = await probe({ record: row });
+    } catch (error) {
+      // 读不到不算"跑完了"：记下来继续盯（失败必须可见）。
+      logger.warn?.(`[dsh-chat] 延迟交付复查失败（${row.key}）：${error?.message ?? error}`);
+      await bump(id, { lastError: error?.message ?? String(error) });
+    }
+    if (state?.exists === false) {
+      await drop(id, '会话已不存在');
+      return;
+    }
+    if (state?.rebound === true) {
+      // 这个聊天已经换到别的会话了：旧结果发过去是错的，直接作废。
+      await drop(id, '聊天已换绑到别的会话');
+      return;
+    }
+    if (state && state.running !== true) {
+      const text = typeof state.text === 'string' ? state.text.trim() : '';
+      if (text) {
+        const deliver = deliverers.get(keyOf(row));
+        if (typeof deliver !== 'function') {
+          // 渠道还没注册（例如重启后先读到了记录）：再等等，别丢。
+          logger.warn?.(`[dsh-chat] 延迟交付还没有可用的发送器（${keyOf(row)}），继续等待`);
+          await bump(id, {});
+        } else {
+          try {
+            await deliver({ key: row.key, text: text.slice(0, MAX_TEXT), record: row });
+            logger.info?.(`[dsh-chat] 延迟交付已补发：${row.channelId}/${row.botId} ${row.key}`
+              + ` ${text.length} 字（超时后 ${Math.round(age / 1000)} 秒）`);
+            await drop(id, '已补发');
+            return;
+          } catch (error) {
+            logger.warn?.(`[dsh-chat] 延迟交付补发失败（${row.key}）：${error?.message ?? error}`);
+            await bump(id, { lastError: error?.message ?? String(error) });
+          }
+        }
+      } else {
+        await bump(id, {});
+      }
+    } else {
+      await bump(id, {});
+    }
+    if (Date.now() - (row.timedOutAt ?? Date.now()) >= maxAgeMs) {
+      await drop(id, '超过盯守时限');
+      return;
+    }
+    arm(id, intervalMs);
+  }
+
+  async function bump(id, patch) {
+    const records = store.snapshot().records.map((row) => (row.id === id
+      ? { ...row, attempts: (row.attempts ?? 0) + 1, ...patch }
+      : row));
+    await persist(records);
+  }
+
+  function arm(id, delay) {
+    clearTimer(id);
+    if (stopped) return;
+    /**
+     * 定时复查是**后台**跑的：它自己抛错没人接——一次落盘失败就会变成
+     * unhandledRejection（进程可能因此退出）。这里必须自己收口并留日志。
+     */
+    const timer = setTimeout(() => {
+      void check(id).catch((error) => {
+        logger.warn?.(`[dsh-chat] 延迟交付复查异常（${id}）：${error?.message ?? error}`);
+      });
+    }, delay);
+    timer.unref?.();
+    timers.set(id, timer);
+  }
+
+  return {
+    path: store.path,
+
+    /** 等磁盘文档就绪（与其它 store 一致）。 */
+    ready: () => store.ready(),
+
+    /**
+     * 渠道注册"怎么把补发内容发回这个会话"。同一 channel/bot 后注册的覆盖先前的。
+     * 注册时顺手把该 bot 的既有记录重新盯起来（重启后的续盯）。
+     */
+    register({ channelId, botId, deliver }) {
+      if (typeof channelId !== 'string' || !channelId) throw new TypeError('register 需要 channelId。');
+      if (typeof botId !== 'string' || !botId) throw new TypeError('register 需要 botId。');
+      if (typeof deliver !== 'function') throw new TypeError('register 需要 deliver 函数。');
+      deliverers.set(`${channelId}:${botId}`, deliver);
+      for (const row of store.snapshot().records) {
+        if (row.channelId === channelId && row.botId === botId && !timers.has(row.id)) {
+          arm(row.id, firstCheckMs);
+        }
+      }
+    },
+
+    registerCount: () => deliverers.size,
+
+    /**
+     * 登记一条待交付记录（超时那一刻调用）。
+     *
+     * @param record - `{ channelId, botId, key, sessionId, turn?, startedAt?, reason? }`。
+     * @returns 记录 id。
+     */
+    async schedule({ channelId, botId, key, sessionId, turn = null, startedAt = null, reason = 'timeout' }) {
+      await store.ready();
+      seq += 1;
+      const id = `df-${Date.now().toString(36)}-${seq}`;
+      const row = {
+        id,
+        channelId,
+        botId,
+        key,
+        sessionId,
+        turn,
+        startedAt,
+        timedOutAt: Date.now(),
+        reason,
+        attempts: 0,
+        lastError: null,
+      };
+      const records = store.snapshot().records;
+      const sameKey = (item) => item.channelId === channelId && item.botId === botId && item.key === key;
+      const mine = records.filter(sameKey);
+      // 同一个会话键最多留 MAX_PER_KEY 条：超出丢最旧的（连同它的定时器一起清）。
+      const kept = [...mine, row].slice(-MAX_PER_KEY);
+      for (const dropped of mine) {
+        if (!kept.includes(dropped)) clearTimer(dropped.id);
+      }
+      await persist([...records.filter((item) => !sameKey(item)), ...kept]);
+      logger.info?.(`[dsh-chat] 这一轮超时了，登记待交付：${channelId}/${botId} ${key}`
+        + ` 会话=${sessionId} turn=${turn ?? '?'}（${reason}），${Math.round(firstCheckMs / 1000)} 秒后开始复查`);
+      arm(id, firstCheckMs);
+      return id;
+    },
+
+    /** 立刻复查一条（测试与排查用）。 */
+    checkNow: check,
+
+    /** 还没交付完的记录（设置页/诊断用）。 */
+    list: () => store.snapshot().records.map((row) => ({ ...row })),
+
+    /** 某个会话键的待交付记录作废（`/stop`、解绑、换绑时调用）。 */
+    async forgetKey({ channelId, botId, key, reason = '用户停止' }) {
+      const records = store.snapshot().records;
+      const doomed = records.filter((row) => row.channelId === channelId
+        && row.botId === botId && row.key === key);
+      if (doomed.length === 0) return 0;
+      for (const row of doomed) clearTimer(row.id);
+      await persist(records.filter((row) => !doomed.includes(row)));
+      logger.info?.(`[dsh-chat] 作废 ${doomed.length} 条待交付记录（${reason}）：${channelId}/${botId} ${key}`);
+      return doomed.length;
+    },
+
+    /** 停止所有定时器（进程收摊/测试用）；记录保留在磁盘上。 */
+    stop() {
+      stopped = true;
+      for (const id of [...timers.keys()]) clearTimer(id);
+    },
+  };
+}

package/host/delivery.mjs

@@ -0,0 +1,377 @@
+/**
+ * 主动投递（hub 所有）：把一段文本推给指定渠道的指定会话。
+ *
+ * 分工：
+ * - hub 持有"目标清单"（存在每机器人设置的 `deliveryTargets`，沿用上游结构）
+ *   与调度逻辑；
+ * - 渠道提供两件事：`send({ target, text })`（怎么发）与 `discover(botId)`
+ *   （从自己的会话记录里发现可投递对象）。
+ *
+ * 这样定时任务/脚本只需要 `dshChat.delivery.send({ channelId, botId, targetId, text })`，
+ * 不必知道任何平台细节；新增渠道也只要实现这两个方法。
+ *
+ * @module dsh-chat/host/delivery
+ */
+
+import { stat } from 'node:fs/promises';
+import { basename, isAbsolute, resolve } from 'node:path';
+
+/** 目标 id 语法（与渠道 id 同款安全字符集）。 */
+const TARGET_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** 出站文件上限：飞书 im/v1/files 的硬限制就是 30MB，超过它没有任何渠道能发出去。 */
+const MAX_FILE_BYTES = 30 * 1024 * 1024;
+const FILE_NAME_MAX = 120;
+/** 按图片发出去会得到预览与缩略图，比当附件更好用（渠道按 kind 自己决定消息类型）。 */
+const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp']);
+const TARGET_NAME_MAX = 80;
+const ROUTE_MAX_KEYS = 8;
+const ROUTE_VALUE_MAX = 256;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g;
+const CONTROL_CHARACTER_TEST = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function deliveryError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/** route 里只允许"短标量"：不存 Secret、不存嵌套结构。 */
+function normalizeRoute(route) {
+  if (!isPlainObject(route)) throw deliveryError('chat/bad-target', '投递目标的 route 必须是对象。');
+  const keys = Object.keys(route);
+  if (keys.length === 0 || keys.length > ROUTE_MAX_KEYS) {
+    throw deliveryError('chat/bad-target', `投递目标的 route 需要 1–${ROUTE_MAX_KEYS} 个字段。`);
+  }
+  const normalized = {};
+  for (const key of keys) {
+    const value = route[key];
+    if (!/^[A-Za-z][A-Za-z0-9]{0,31}$/u.test(key)) {
+      throw deliveryError('chat/bad-target', `route 字段名不合法：${key}`);
+    }
+    if (typeof value !== 'string' || !value.trim() || value.length > ROUTE_VALUE_MAX
+      || CONTROL_CHARACTER_TEST.test(value)) {
+      throw deliveryError('chat/bad-target', `route.${key} 必须是非空短字符串。`);
+    }
+    normalized[key] = value.replace(CONTROL_CHARACTERS, '').trim();
+  }
+  return Object.freeze(normalized);
+}
+
+/**
+ * 校验一个投递目标。
+ *
+ * `renamed` 标记"这个名字是用户自己起的"：渠道补名字（`decorateTargets`）时不许覆盖它
+ * ——否则用户刚改完的名字，下一次打开设置页就被平台群名顶回去了。
+ *
+ * @param input - { id, name?, kind, route, renamed? }。
+ * @returns 冻结后的目标。
+ */
+export function normalizeTarget(input) {
+  if (!isPlainObject(input)) throw deliveryError('chat/bad-target', '投递目标必须是对象。');
+  const { id, name, kind, route, renamed } = input;
+  if (typeof id !== 'string' || !TARGET_ID.test(id)) {
+    throw deliveryError('chat/bad-target', '投递目标 id 只能是 1–64 位字母/数字/下划线/连字符。');
+  }
+  if (kind !== 'direct' && kind !== 'group') {
+    throw deliveryError('chat/bad-target', '投递目标 kind 只能是 direct 或 group。');
+  }
+  const label = typeof name === 'string' ? name.replace(CONTROL_CHARACTERS, '').trim() : '';
+  if (label.length > TARGET_NAME_MAX) {
+    throw deliveryError('chat/bad-target', `投递目标名称不得超过 ${TARGET_NAME_MAX} 个字符。`);
+  }
+  return Object.freeze({
+    id,
+    name: label,
+    kind,
+    route: normalizeRoute(route),
+    // 空名字等于"取消自定义"，这时渠道给什么名字就用什么。
+    renamed: renamed === true && label.length > 0,
+  });
+}
+
+/**
+ * 把一次"要发的文件"归一化：解析路径、校验存在与大小、收敛文件名。
+ *
+ * 相对路径按**该机器人的工作区**解析——agent 生成报表时用的就是会话工作目录，
+ * 让它写 `报表.xlsx` 而不是绝对路径才是顺手的。
+ *
+ * @param options - { path, name, workspace }。
+ * @returns 冻结的 { path, name, size }。
+ */
+async function resolveOutboundFile({ path: inputPath, name, workspace }) {
+  const raw = typeof inputPath === 'string' ? inputPath.trim() : '';
+  if (!raw) throw deliveryError('chat/bad-file', '发送文件需要 path。');
+  const absolute = isAbsolute(raw) ? raw : resolve(workspace ?? process.cwd(), raw);
+  let stats;
+  try {
+    stats = await stat(absolute);
+  } catch {
+    throw deliveryError('chat/file-not-found', `找不到文件：${absolute}`);
+  }
+  if (!stats.isFile()) throw deliveryError('chat/bad-file', `不是普通文件：${absolute}`);
+  if (stats.size === 0) throw deliveryError('chat/bad-file', `文件是空的，无法发送：${absolute}`);
+  if (stats.size > MAX_FILE_BYTES) {
+    const mb = (stats.size / 1024 / 1024).toFixed(1);
+    throw deliveryError('chat/file-too-large',
+      `文件 ${mb}MB 超过 ${MAX_FILE_BYTES / 1024 / 1024}MB 上限：${absolute}`);
+  }
+  const label = typeof name === 'string' ? name.replace(CONTROL_CHARACTERS, '').trim() : '';
+  const finalName = (label || basename(absolute)).slice(0, FILE_NAME_MAX);
+  const ext = finalName.split('.').pop()?.toLowerCase() ?? '';
+  const kind = IMAGE_EXTENSIONS.has(ext) ? 'image' : 'file';
+  return Object.freeze({ path: absolute, name: finalName, size: stats.size, kind });
+}
+
+/**
+ * 会话身份键：同一会话可能以不同 id 出现（旧数据 `tgt_xxx` vs 渠道派生的 `group_xxx`），
+ * 因此判重按"类型 + 路由"而不是 id。
+ *
+ * @param target - 归一化后的目标。
+ * @returns 稳定的字符串键。
+ */
+function routeKey(target) {
+  const route = Object.entries(target.route)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `${key}=${value}`)
+    .join('\u0001');
+  return `${target.kind}\u0000${route}`;
+}
+
+/** 容错归一化（读取历史数据用）：坏条目丢弃而不是让整表读不出来。 */
+function normalizeStoredTargets(value) {  if (!isPlainObject(value)) return {};
+  const targets = {};
+  for (const [id, target] of Object.entries(value)) {
+    try {
+      targets[id] = normalizeTarget({ ...target, id });
+    } catch {
+      // 丢弃坏条目：一条脏数据不该让该机器人所有投递目标失效。
+    }
+  }
+  return targets;
+}
+
+/**
+ * 创建投递服务。
+ *
+ * @param options - { settings, logger }。
+ * @returns 投递服务。
+ */
+/**
+ * 创建投递服务。
+ *
+ * @param options - { settings, sessionStore?, logger? }。
+ *   `sessionStore` 用来把该机器人**真实聊过的会话**补成候选（见 list 里的说明），
+ *   缺席时只依赖渠道的 `discover()`。
+ * @returns 投递服务。
+ */
+export function createDeliveryService({ settings, sessionStore = null, logger = console }) {
+  if (!settings?.read) throw new TypeError('投递服务需要每机器人设置存储。');
+  /** @type {Map<string, object>} channelId → 渠道投递实现 */
+  const providers = new Map();
+
+  return Object.freeze({
+    /**
+     * 渠道注册投递实现（实例创建时由注册表调用，注销时释放）。
+     *
+     * @param channelId - 渠道 id。
+     * @param provider - `{ send({ botId, target, text }), discover?({ botId }) }`。
+     * @returns 注销函数。
+     */
+    attach(channelId, provider) {
+      if (typeof provider?.send !== 'function') {
+        throw new TypeError(`渠道 ${channelId} 的投递实现缺少 send。`);
+      }
+      providers.set(channelId, provider);
+      return () => {
+        if (providers.get(channelId) === provider) providers.delete(channelId);
+      };
+    },
+
+    /** @returns 该渠道是否支持发送文件（`sendFile` 可选，能力缺席要能被查出来）。 */
+    supportsFile: (channelId) => typeof providers.get(channelId)?.sendFile === 'function',
+
+    /** @returns 该渠道是否具备主动投递能力。 */
+    supports: (channelId) => providers.has(channelId),
+
+    /** @returns 已保存的投递目标（含渠道发现的候选，候选不落盘）。 */
+    async list({ channelId, botId }) {
+      const saved = normalizeStoredTargets(settings.read(channelId, botId).deliveryTargets);
+      const provider = providers.get(channelId);
+      const discovered = [];
+      if (typeof provider?.discover === 'function') {
+        try {
+          discovered.push(...(await provider.discover({ botId })) ?? []);
+        } catch (error) {
+          logger.warn?.(`[dsh-chat] 渠道 ${channelId} 发现投递目标失败：${error?.message ?? error}`);
+        }
+      }
+      /**
+       * 候选的第二个来源：hub 自己的**持久**会话绑定表。
+       *
+       * 只靠 `discover()`（渠道运行时状态）的话，重启后运行时是空的，设置页就一个候选都没有
+       * ——用户会说"看不到添加的入口"。而绑定表里的会话本来就是这个机器人真实聊过的，
+       * 由渠道用 `targetFromKey` 把会话键翻译成目标（平台概念只在渠道里）。
+       */
+      if (typeof provider?.targetFromKey === 'function' && sessionStore) {
+        try {
+          await sessionStore.ready?.();
+          for (const key of Object.keys(sessionStore.entries(channelId, botId))) {
+            try {
+              const target = provider.targetFromKey(key);
+              if (target) discovered.push(target);
+            } catch {
+              // 单个键翻译失败不该毁掉整份清单
+            }
+          }
+        } catch (error) {
+          logger.warn?.(`[dsh-chat] 读取会话绑定失败：${error?.message ?? error}`);
+        }
+      }
+      const savedList = Object.values(saved);
+      // 同一个会话可能有两套 id（旧设置里的 tgt_xxx 与渠道派生的 group_xxx），
+      // 因此除了 id，还要按"类型 + 路由"判重，否则设置页和 agent 会看到重复条目。
+      const known = new Set(savedList.map(routeKey));
+      const candidates = [];
+      for (const candidate of discovered) {
+        try {
+          const target = normalizeTarget(candidate);
+          const key = routeKey(target);
+          if (saved[target.id] || known.has(key)) continue;
+          known.add(key);
+          candidates.push(Object.freeze({ ...target, discovered: true }));
+        } catch {
+          // 忽略无法识别的候选
+        }
+      }
+      /**
+       * 让人认得出：渠道把 `oc_xxx` / `ou_xxx` 换成群名 / 人名（只有渠道认识平台概念）。
+       * 已保存目标也要补——它们当年保存时存下来的常常就是掩码 id。
+       * 渠道没实现、或某个名字拿不到，就保持原名称，绝不因此少列目标。
+       */
+      let listed = [...savedList, ...candidates];
+      if (typeof provider?.decorateTargets === 'function' && listed.length > 0) {
+        try {
+          const decorated = await provider.decorateTargets({
+            botId,
+            targets: listed.map((target) => ({ ...target })),
+          });
+          if (Array.isArray(decorated) && decorated.length === listed.length) {
+            listed = listed.map((target, index) => {
+              // 用户自己起过名字的，平台名字不许顶掉它（真机上会表现为"改完又变回去"）。
+              if (target.renamed) return target;
+              const name = decorated[index]?.name;
+              return typeof name === 'string' && name ? { ...target, name } : target;
+            });
+          }
+        } catch (error) {
+          logger.warn?.(`[dsh-chat] 渠道 ${channelId} 补充目标名称失败：${error?.message ?? error}`);
+        }
+      }
+      return Object.freeze({
+        targets: Object.freeze(listed),
+        canSend: providers.has(channelId),
+      });
+    },
+
+    /**
+     * 保存（或覆盖）一个投递目标。
+     *
+     * @param options - { channelId, botId, target }。
+     */
+    async save({ channelId, botId, target }) {
+      const normalized = normalizeTarget(target);
+      const current = normalizeStoredTargets(settings.read(channelId, botId).deliveryTargets);
+      await settings.write(channelId, botId, {
+        deliveryTargets: { ...current, [normalized.id]: normalized },
+      });
+      return normalized;
+    },
+
+    /**
+     * 给一个**已保存**的目标改名字（用户自定义名）。
+     *
+     * 为什么需要：目标名字来自平台（群名/人名），但微信拿不到昵称、飞书缺权限时只有
+     * `oc_xxx` / `ou_xxx`——设置页里一排掩码 id，人认不出哪个是哪个。
+     * 传空名字 = 取消自定义，回到渠道给的名字。
+     */
+    async rename({ channelId, botId, targetId, name }) {
+      const current = normalizeStoredTargets(settings.read(channelId, botId).deliveryTargets);
+      const target = current[targetId];
+      if (!target) {
+        throw deliveryError('chat/unknown-target',
+          `找不到投递目标 ${targetId}（先保存为投递目标，再改名）。`);
+      }
+      const label = typeof name === 'string' ? name.trim() : '';
+      const renamed = normalizeTarget({ ...target, name: label, renamed: label.length > 0 });
+      await settings.write(channelId, botId, {
+        deliveryTargets: { ...current, [targetId]: renamed },
+      });
+      return renamed;
+    },
+
+    /** 删除一个投递目标。 */
+    async remove({ channelId, botId, targetId }) {
+      const current = normalizeStoredTargets(settings.read(channelId, botId).deliveryTargets);
+      if (!Object.hasOwn(current, targetId)) return false;
+      const next = { ...current };
+      delete next[targetId];
+      await settings.write(channelId, botId, { deliveryTargets: next });
+      return true;
+    },
+
+    /**
+     * 发一条文本。
+     *
+     * @param options - { channelId, botId, targetId, text }。
+     * @returns 渠道返回的发送结果。
+     */
+    async send({ channelId, botId, targetId, text }) {
+      const provider = providers.get(channelId);
+      if (!provider) {
+        throw deliveryError('chat/delivery-unavailable', `渠道 ${channelId} 不支持主动投递。`);
+      }
+      const content = typeof text === 'string' ? text.trim() : '';
+      if (!content) throw deliveryError('chat/empty-text', '投递内容不能为空。');
+      const saved = normalizeStoredTargets(settings.read(channelId, botId).deliveryTargets);
+      const target = saved[targetId];
+      if (!target) {
+        throw deliveryError('chat/unknown-target', `找不到投递目标 ${targetId}（先在设置页保存或改用候选目标）。`);
+      }
+      return provider.send({ botId, target, text: content });
+    },
+
+    /**
+     * 发一个文件。
+     *
+     * 与文本同样的安全边界：**只能发给已保存的目标**；文件本身必须是存在、非空、
+     * 不超过上限的普通文件。
+     *
+     * @param options - { channelId, botId, targetId, path, name? }。
+     * @returns 渠道返回的发送结果。
+     */
+    async sendFile({ channelId, botId, targetId, path, name }) {
+      const provider = providers.get(channelId);
+      if (!provider) {
+        throw deliveryError('chat/delivery-unavailable', `渠道 ${channelId} 不支持主动投递。`);
+      }
+      if (typeof provider.sendFile !== 'function') {
+        throw deliveryError('chat/delivery-unsupported', `渠道 ${channelId} 暂不支持发送文件。`);
+      }
+      const saved = normalizeStoredTargets(settings.read(channelId, botId).deliveryTargets);
+      const target = saved[targetId];
+      if (!target) {
+        throw deliveryError('chat/unknown-target', `找不到投递目标 ${targetId}（先在设置页保存或改用候选目标）。`);
+      }
+      const file = await resolveOutboundFile({
+        path,
+        name,
+        workspace: settings.read(channelId, botId).workspace,
+      });
+      return provider.sendFile({ botId, target, file });
+    },
+  });
+}