@sidleo3/dsh-chat 0.0.4

package/client/version-panel.js

@@ -0,0 +1,97 @@
+/**
+ * 「版本与更新」面板：hub / 契约 / 各渠道包版本 + 连接状态 + 更新做法。
+ *
+ * 数据来自 hub 控制端点的 `channel.list`（`{ hubVersion, hubPackage, contractVersion,
+ * dataDir, logDir, channels }`）——版本一律由 host 侧给，浏览器不猜。
+ * 放在设置页底部：一眼能看到"现在跑的是哪个版本、有没有渠道启动失败、怎么升级"。
+ *
+ * @module dsh-chat/client/version-panel
+ */
+
+import * as React from 'react';
+
+const h = React.createElement;
+
+/** 升级命令里的包名（本地 link 安装时指向仓库路径）。 */
+const CHANNEL_PACKAGE_HINTS = Object.freeze({
+  feishu: 'dsh-chat-feishu',
+  weixin: 'dsh-chat-weixin',
+});
+
+/**
+ * 版本与更新面板。
+ *
+ * @param props - { connection, chatUi, translate, t }。
+ * @returns React 元素。
+ */
+export function VersionPanel(props) {
+  const { connection, chatUi, translate, t: frameworkT } = props;
+  const t = typeof translate === 'function' ? translate
+    : (typeof frameworkT === 'function' ? frameworkT : (key) => key);
+  const [state, setState] = React.useState({ loading: true, error: null, info: null });
+
+  const load = React.useCallback(() => {
+    setState((current) => ({ ...current, loading: true, error: null }));
+    chatUi.callControlRpc(connection, 'channel.list', {})
+      .then((result) => {
+        setState({ loading: false, error: null, info: chatUi.unwrapRpc(result) });
+      })
+      .catch((error) => {
+        setState({ loading: false, error: error?.message ?? String(error), info: null });
+      });
+  }, [chatUi, connection]);
+
+  React.useEffect(() => {
+    load();
+  }, [load]);
+
+  const Panel = chatUi.components.Panel;
+  const StatusPill = chatUi.components.StatusPill;
+  const info = state.info;
+
+  return h(Panel, {
+    title: t('版本与更新'),
+    description: t('升级插件后需要重启 dsh；只改设置页代码则刷新页面即可。'),
+    actions: h('button', {
+      type: 'button',
+      className: 'dchat-button',
+      onClick: load,
+      disabled: state.loading,
+    }, state.loading ? t('读取中…') : t('重新读取')),
+  },
+  state.error
+    ? h('p', { className: 'dchat-error' }, `${t('读取失败')}：${state.error}`)
+    : null,
+  h('ul', { className: 'dchat-list' },
+    h('li', { className: 'dchat-listItem' },
+      h('span', null, t('Chat机器人内核')),
+      h('code', { className: 'dchat-code' },
+        `${info?.hubPackage ?? 'dsh-chat'} ${info?.hubVersion ?? '…'}`)),
+    h('li', { className: 'dchat-listItem' },
+      h('span', null, t('渠道契约版本')),
+      h('code', { className: 'dchat-code' }, `v${info?.contractVersion ?? '…'}`)),
+    ...(info?.channels ?? []).map((channel) => h('li', {
+      key: channel.id, className: 'dchat-listItem',
+    },
+    h('span', null, `${channel.label} · ${CHANNEL_PACKAGE_HINTS[channel.id] ?? channel.id}`),
+    h('span', { className: 'dchat-versionMeta' },
+      h('code', { className: 'dchat-code' }, channel.version ?? '—'),
+      h(StatusPill, {
+        status: channel.status,
+        label: channel.status === 'running' ? t('渠道已就绪') : (channel.error ? t('渠道启动失败') : t('渠道正在启动')),
+      }))))),
+  info?.dataDir
+    ? h('ul', { className: 'dchat-list' },
+      h('li', { className: 'dchat-listItem' },
+        h('span', null, t('数据目录')),
+        h('code', { className: 'dchat-code' }, info.dataDir)),
+      h('li', { className: 'dchat-listItem' },
+        h('span', null, t('日志目录')),
+        h('code', { className: 'dchat-code' }, info.logDir)))
+    : null,
+  h('div', { className: 'dchat-updateHint' },
+    h('p', { className: 'dchat-cardDescription' }, t('更新方式：在仓库里拉取新代码后重新打包，再让 DSH 重新加载插件。')),
+    h('code', { className: 'dchat-code dchat-codeBlock' }, 'npm run check'),
+    h('code', { className: 'dchat-code dchat-codeBlock' },
+      'dsh plugin --profile web add <本仓库 packages/dsh-chat 的绝对路径>')));
+}

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# 这一行把插件挂进 DSH profile 的插件树。
+# name 必须是**包名**（作用域包要带引号，YAML 里 @ 是保留字符）；id 只用于定向补丁。
+- insert:
+    - id: dsh-chat
+      name: '@sidleo3/dsh-chat'

package/host/bot-model.mjs

@@ -0,0 +1,53 @@
+/**
+ * 机器人级默认模型（每机器人设置里的 `model` 字段）。
+ *
+ * **为什么需要这一层**：DSH 的模型选择是**会话级**的——
+ * `session/selectModel` 必须带 `sessionId`，而 `session/create` 的参数里没有模型
+ * （`{ workspaceId?, cwd?, sessionId?, agentPreset? }`）。会话又是"用户发第一条消息"时才建的，
+ * 所以"还没有会话时想先挑好模型"原本无处可写，只能让用户先随便发一条消息。
+ *
+ * 于是把它存成**机器人默认模型**，由 `sessions.ensure()` 在新建会话后立刻 `selectModel` 应用
+ * ——与 Agent 预设、工作区同一条口径：**只对新会话生效**。
+ *
+ * 形状统一为 `{ provider, model, reasoningEffort }`；兼容旧 dsh-im `models.json` 的
+ * `{ providerId, modelId }`（历史上被原样导入到 `record.model`，从来没被读过）。
+ */
+
+/** @returns `{ provider, model, reasoningEffort }` 或 null（残缺的旧数据一律当作没配）。 */
+export function normalizeBotModel(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const pick = (...values) => {
+    for (const value of values) {
+      if (typeof value === 'string' && value.trim()) return value.trim();
+    }
+    return null;
+  };
+  const provider = pick(raw.provider, raw.providerId);
+  const model = pick(raw.model, raw.modelId);
+  // 两者缺一不可：只有一半的历史配置用起来只会在建会话时炸，按"没配"处理更保守。
+  if (!provider || !model) return null;
+  return { provider, model, reasoningEffort: pick(raw.reasoningEffort, raw.effort) };
+}
+
+/**
+ * 把一次模型选择写成机器人默认。
+ *
+ * 同一个模型时保留原来的推理等级（改模型不该顺手把等级清掉）；换模型时重置为"模型默认"，
+ * 因为等级是模型自己的能力，跨模型沿用会给出一个当前模型不支持的等级。
+ */
+export function botModelForSelection(previous, { provider, model, reasoningEffort = null }) {
+  const same = previous?.provider === provider && previous?.model === model;
+  return {
+    provider,
+    model,
+    reasoningEffort: same ? (previous?.reasoningEffort ?? null) : (reasoningEffort ?? null),
+  };
+}
+
+/** 给用户看的一行描述（`P/M` 或 `P/M · 推理 x`）。 */
+export function describeBotModel(value) {
+  const normalized = normalizeBotModel(value);
+  if (!normalized) return null;
+  return `${normalized.provider}/${normalized.model}`
+    + `${normalized.reasoningEffort ? ` · 推理 ${normalized.reasoningEffort}` : ''}`;
+}

package/host/bot-settings.mjs

@@ -0,0 +1,247 @@
+/**
+ * 每机器人共享设置的持久化（hub 所有）。
+ *
+ * 渠道无关的那些设置——工作区、模型、思考强度、Agent Preset、上下文增强、访问策略、
+ * 投递目标——由 hub 统一持有，文件为 `<dataDir>/bots.json`。渠道自己的协议配置
+ * （凭据、机器人列表、会话状态、过程展示等平台概念）留在渠道包自己的目录里。
+ *
+ * 写盘纪律（原子写、首次覆盖备份、串行队列）由 `json-store` 提供。
+ *
+ * @module dsh-chat/host/bot-settings
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { normalizeContextConfig } from '../shared/context-enhancement.mjs';
+import { normalizePanelSections } from '../shared/panel-sections.mjs';
+import { createJsonStore } from './json-store.mjs';
+
+const DOCUMENT_VERSION = 1;
+
+/** 一个机器人记录的默认值。 */
+const EMPTY_RECORD = Object.freeze({
+  workspace: null,
+  model: null,
+  agentPreset: null,
+  contextEnhancement: null,
+  accessPolicy: null,
+  deliveryTargets: null,
+  /**
+   * 控制面板卡片的显示项（私聊/群聊各一份）：`{ direct: { model: true, … }, group: {…} }`。
+   * `null` = 全显示（见 `shared/panel-sections.mjs`）。
+   */
+  panelSections: null,
+});
+
+const RECORD_KEYS = Object.freeze(Object.keys(EMPTY_RECORD));
+
+/** 旧 workspaces.json 里与每机器人设置对应的键。 */
+const LEGACY_SOURCES = Object.freeze({
+  workspaces: 'workspace',
+  models: 'model',
+  agentPresets: 'agentPreset',
+  contextEnhancement: 'contextEnhancement',
+  accessPolicies: 'accessPolicy',
+  deliveryTargets: 'deliveryTargets',
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneRecord(record) {
+  return {
+    ...EMPTY_RECORD,
+    ...(isPlainObject(record) ? record : {}),
+  };
+}
+
+function normalizeDocument(value) {
+  const source = isPlainObject(value) && value.version === DOCUMENT_VERSION ? value : {};
+  const imports = isPlainObject(source.imports) ? { ...source.imports } : {};
+  const channels = {};
+  if (isPlainObject(source.channels)) {
+    for (const [channelId, bots] of Object.entries(source.channels)) {
+      if (!isPlainObject(bots)) continue;
+      const entries = {};
+      for (const [botId, record] of Object.entries(bots)) {
+        if (!isPlainObject(record)) continue;
+        entries[botId] = cloneRecord(record);
+      }
+      channels[channelId] = entries;
+    }
+  }
+  return { version: DOCUMENT_VERSION, imports, channels };
+}
+
+/**
+ * 创建每机器人共享设置存储。
+ *
+ * @param options - { dataDir, logger }。
+ * @returns 存储：ready / read / write / list / subscribe / importLegacy / imports / path。
+ */
+export function createBotSettingsStore({ dataDir, logger = console } = {}) {
+  if (typeof dataDir !== 'string' || !dataDir.trim()) {
+    throw new TypeError('bot settings 需要 dataDir。');
+  }
+  const store = createJsonStore({
+    path: join(dataDir, 'bots.json'),
+    normalize: normalizeDocument,
+    empty: () => ({ version: DOCUMENT_VERSION, imports: {}, channels: {} }),
+    logger,
+    label: '每机器人设置',
+  });
+
+  function readRecord(channelId, botId) {
+    const stored = store.snapshot().channels?.[channelId]?.[botId];
+    const record = cloneRecord(stored);
+    // 未配置（undefined）与显式清空（null）都表示"没有上下文增强"。
+    record.contextEnhancement = stored?.contextEnhancement === undefined
+      || stored?.contextEnhancement === null
+      ? null
+      : normalizeContextConfig(stored.contextEnhancement);
+    // 显示项：残缺/写错的配置按"显示"补齐（把卡片变空是最难查的那类静默失效）。
+    record.panelSections = stored?.panelSections === undefined || stored?.panelSections === null
+      ? null
+      : normalizePanelSections(stored.panelSections);
+    return Object.freeze(record);
+  }
+
+  return {
+    path: store.path,
+
+    /** 等待磁盘文档就绪；渠道读取设置前应 await 它。 */
+    ready: () => store.ready(),
+
+    /** @returns 冻结的机器人记录（缺失时为默认值）。 */
+    read: readRecord,
+
+    /** 合并写入若干字段（未知键一律拒绝）。 */
+    async write(channelId, botId, patch) {
+      if (typeof channelId !== 'string' || !channelId) throw new TypeError('channelId 必填。');
+      if (typeof botId !== 'string' || !botId) throw new TypeError('botId 必填。');
+      if (!isPlainObject(patch)) throw new TypeError('patch 必须是对象。');
+      const unknown = Object.keys(patch).filter((key) => !RECORD_KEYS.includes(key));
+      if (unknown.length > 0) throw new TypeError(`未知的设置字段：${unknown.join('、')}`);
+      const withContext = Object.hasOwn(patch, 'contextEnhancement') && patch.contextEnhancement !== null
+        ? { ...patch, contextEnhancement: normalizeContextConfig(patch.contextEnhancement) }
+        : patch;
+      const normalized = Object.hasOwn(withContext, 'panelSections') && withContext.panelSections !== null
+        ? { ...withContext, panelSections: normalizePanelSections(withContext.panelSections) }
+        : withContext;
+      await store.update((current) => {
+        const channels = { ...current.channels };
+        const bots = { ...(channels[channelId] ?? {}) };
+        bots[botId] = { ...cloneRecord(bots[botId]), ...normalized };
+        channels[channelId] = bots;
+        return { ...current, channels };
+      });
+      return readRecord(channelId, botId);
+    },
+
+    /** @returns 该渠道下的全部记录（含 botId）。 */
+    list(channelId) {
+      const bots = store.snapshot().channels?.[channelId] ?? {};
+      return Object.freeze(Object.keys(bots).map((botId) => Object.freeze({
+        botId,
+        ...readRecord(channelId, botId),
+      })));
+    },
+
+    /** 订阅变更。 */
+    subscribe: (listener) => store.subscribe(listener),
+
+    /**
+     * 一次性把旧渠道的 `workspaces.json` 导入为每机器人设置。
+     *
+     * 只读旧文件，绝不改写；导入过后记 `imports[channelId]`，因此用户在 dsh-chat 里
+     * 清空某条设置后不会在下次启动被"复活"。`force: true` 时忽略标记并以旧文件为准刷新。
+     *
+     * @param channelId - 渠道 id。
+     * @param legacyDir - 旧数据目录（绝对路径）。
+     * @param options - { force }。
+     * @returns { imported, bots } 或 { skipped }。
+     */
+    async importLegacy(channelId, legacyDir, { force = false } = {}) {
+      if (!force) {
+        await store.ready();
+        if (store.snapshot().imports[channelId]) {
+          return { skipped: '已导入过', imported: 0, bots: [] };
+        }
+      }
+      const source = join(legacyDir, 'workspaces.json');
+      let legacy = null;
+      try {
+        legacy = JSON.parse(await readFile(source, 'utf8'));
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          // 没有旧文件：记为已导入，避免每次启动都去探测。
+          await store.update((current) => ({
+            ...current,
+            imports: {
+              ...current.imports,
+              [channelId]: { path: source, importedAt: new Date().toISOString(), bots: [] },
+            },
+          }));
+          return { imported: 0, bots: [] };
+        }
+        // 读得到但解析失败：不记导入，保留下次启动重试的机会。
+        logger.warn?.(`[dsh-chat] 旧设置 ${source} 无法解析，稍后重试：${error?.message ?? error}`);
+        return { skipped: '旧设置无法解析', imported: 0, bots: [] };
+      }
+
+      const perBot = new Map();
+      for (const [legacyKey, recordKey] of Object.entries(LEGACY_SOURCES)) {
+        const table = legacy?.[legacyKey];
+        if (!isPlainObject(table)) continue;
+        for (const [botId, value] of Object.entries(table)) {
+          if (value === null || value === undefined) continue;
+          const entry = perBot.get(botId) ?? {};
+          entry[recordKey] = recordKey === 'contextEnhancement'
+            ? normalizeContextConfig(value)
+            : value;
+          perBot.set(botId, entry);
+        }
+      }
+
+      await store.update((current) => {
+        const channels = { ...current.channels };
+        if (perBot.size > 0) {
+          const bots = { ...(channels[channelId] ?? {}) };
+          for (const [botId, patch] of perBot) {
+            // 首次导入只补空缺；force 重跑则以旧文件为准刷新。
+            const merged = cloneRecord(bots[botId]);
+            for (const [key, value] of Object.entries(patch)) {
+              if (force || merged[key] === null) merged[key] = value;
+            }
+            bots[botId] = merged;
+          }
+          channels[channelId] = bots;
+        }
+        return {
+          ...current,
+          imports: {
+            ...current.imports,
+            [channelId]: {
+              path: source,
+              importedAt: new Date().toISOString(),
+              bots: [...perBot.keys()],
+            },
+          },
+          channels,
+        };
+      });
+
+      if (perBot.size > 0) {
+        logger.info?.(`[dsh-chat] 已从 ${source} 导入 ${perBot.size} 个机器人的设置`);
+      }
+      return { imported: perBot.size, bots: [...perBot.keys()] };
+    },
+
+    /** @returns 已导入来源的快照（调试与测试用）。 */
+    imports() {
+      return Object.freeze({ ...store.snapshot().imports });
+    },
+  };
+}

package/host/channel-registry.mjs

@@ -0,0 +1,237 @@
+/**
+ * 渠道注册表（host 侧）：渠道包提交定义，hub 负责创建实例、挂 RPC、跟踪状态。
+ *
+ * 生命周期要点：
+ * - `register()` 同步返回注销函数（Cordis `ctx.effect` 需要同步 disposer），
+ *   实例创建与启动在后台进行，失败记入状态而不是抛出；
+ * - RPC 路由在实例就绪前就已挂上，因此设置页在"启动中/启动失败"时也能读到状态；
+ * - 注销后先摘路由、再停实例，重复注销是幂等的。
+ *
+ * @module dsh-chat/host/channel-registry
+ */
+
+import { channelLabel, validateChannelDefinition } from '../shared/contract.mjs';
+import { fail } from './rpc.mjs';
+
+const STATUSES = new Set(['starting', 'running', 'failed', 'stopped']);
+
+function describeError(error) {
+  if (!error) return null;
+  return Object.freeze({
+    code: typeof error.code === 'string' ? error.code : 'chat/channel-error',
+    message: typeof error.message === 'string' && error.message ? error.message : String(error),
+  });
+}
+
+/**
+ * 创建渠道注册表。
+ *
+ * @param options - { logger, rpc, createDeps, onRegistered }。
+ *   `createDeps(channelId, definition)` 返回交给渠道 `createChannel(deps)` 的依赖包；
+ *   `onRegistered(channelId, legacy)` 在定义通过校验后同步调用一次（用于旧设置导入），
+ *   其异常不会影响渠道注册。
+ * @returns { register, list, get, subscribe, handleRpc, disposeAll }。
+ */
+export function createChannelRegistry({
+  logger = console,
+  rpc,
+  createDeps,
+  onRegistered,
+  onDelivery,
+}) {
+  if (typeof rpc?.register !== 'function') throw new TypeError('渠道注册表需要 rpc 载体。');
+  if (typeof createDeps !== 'function') throw new TypeError('渠道注册表需要 createDeps。');
+
+  /** @type {Map<string, object>} */
+  const channels = new Map();
+  const listeners = new Set();
+  let snapshot = Object.freeze([]);
+
+  function publish() {
+    snapshot = Object.freeze([...channels.values()].map((record) => Object.freeze({
+      id: record.definition.id,
+      label: channelLabel(record.definition),
+      order: record.definition.order,
+      version: record.definition.version ?? null,
+      status: record.status,
+      error: record.error,
+      startedAt: record.startedAt,
+    })).sort((left, right) => (
+      left.order === right.order ? left.id.localeCompare(right.id) : left.order - right.order
+    )));
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch {
+        // 单个订阅者出错不影响其他订阅者。
+      }
+    }
+  }
+
+  function setStatus(record, status, error = null) {
+    if (!STATUSES.has(status)) throw new TypeError(`未知渠道状态：${status}`);
+    record.status = status;
+    record.error = describeError(error);
+    publish();
+  }
+
+  async function start(record) {
+    const { definition } = record;
+    try {
+      const instance = await definition.createChannel(record.deps);
+      if (record.disposed) {
+        await instance?.stop?.();
+        return;
+      }
+      if (instance === null || typeof instance !== 'object') {
+        throw new TypeError(`渠道 ${definition.id} 的 createChannel 必须返回实例对象。`);
+      }
+      if (instance.endpoints !== undefined && (typeof instance.endpoints !== 'object'
+        || instance.endpoints === null || Array.isArray(instance.endpoints))) {
+        throw new TypeError(`渠道 ${definition.id} 的 endpoints 必须是方法表。`);
+      }
+      record.instance = instance;
+      // 渠道声明了投递能力就挂到 hub 的投递服务上（注销时自动摘掉）。
+      if (instance.delivery !== undefined && typeof onDelivery === 'function') {
+        record.releaseDelivery = onDelivery(definition.id, instance.delivery);
+      }
+      await instance.start?.();
+      if (record.disposed) {
+        await instance.stop?.();
+        record.releaseDelivery?.();
+        return;
+      }
+      if (record.status === 'starting') setStatus(record, 'running');
+    } catch (error) {
+      setStatus(record, 'failed', error);
+      logger.error?.(`[dsh-chat] 渠道 ${definition.id} 启动失败：${error?.message ?? error}`);
+    }
+  }
+
+  async function stop(record) {
+    record.disposed = true;
+    record.releaseRoutes?.();
+    record.releaseRoutes = null;
+    record.releaseDelivery?.();
+    record.releaseDelivery = null;
+    try {
+      await record.instance?.stop?.();
+    } catch (error) {
+      logger.warn?.(`[dsh-chat] 渠道 ${record.definition.id} 停止时报错：${error?.message ?? error}`);
+    }
+    record.instance = null;
+    record.status = 'stopped';
+  }
+
+  /**
+   * 注册一个渠道。
+   *
+   * @param definition - 渠道定义（见 CONTRACT.md）。
+   * @returns 同步注销函数。
+   */
+  function register(definition) {
+    const validated = validateChannelDefinition(definition);
+    if (channels.has(validated.id)) {
+      throw new Error(`渠道 ${validated.id} 已注册，不能重复注册。`);
+    }
+    const record = {
+      definition: validated,
+      deps: null,
+      instance: null,
+      status: 'starting',
+      error: null,
+      startedAt: new Date().toISOString(),
+      disposed: false,
+      releaseRoutes: null,
+    };
+    record.deps = Object.freeze({
+      ...createDeps(validated.id, validated),
+      reportStatus: (status, error) => {
+        if (record.disposed) return;
+        setStatus(record, status, error);
+      },
+    });
+    channels.set(validated.id, record);
+    // 旧设置导入等"注册后动作"不能影响渠道本身。
+    if (typeof onRegistered === 'function') {
+      try {
+        onRegistered(validated.id, validated.legacy);
+      } catch (error) {
+        logger.warn?.(`[dsh-chat] 渠道 ${validated.id} 注册后动作失败：${error?.message ?? error}`);
+      }
+    }
+    // 路由先挂上：状态页在渠道启动完成前就能读到 starting / failed。
+    record.releaseRoutes = rpc.register(validated.id, (method, payload, signal) => (
+      handleRpc(validated.id, method, payload, signal)
+    ));
+    publish();
+    void start(record);
+
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      if (!channels.delete(validated.id)) return;
+      void stop(record);
+      publish();
+    };
+  }
+
+  /** @returns 渠道状态快照（按 order 排序）。 */
+  function list() {
+    return snapshot;
+  }
+
+  /**
+   * @param id - 渠道 id。
+   * @returns 渠道状态记录，未注册时为 undefined。
+   */
+  function get(id) {
+    return snapshot.find((entry) => entry.id === id);
+  }
+
+  /**
+   * 订阅渠道状态变化。
+   *
+   * @param listener - 无参回调。
+   * @returns 取消订阅函数。
+   */
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  /**
+   * 把一次 RPC 调用分派给渠道实例的 endpoints。
+   *
+   * @param channelId - 渠道 id。
+   * @param method - 渠道自定义方法名。
+   * @param payload - 载荷。
+   * @param signal - AbortSignal。
+   * @returns RPC 结果对象。
+   */
+  async function handleRpc(channelId, method, payload, signal) {
+    const record = channels.get(channelId);
+    if (!record) return fail('chat/unknown-channel', `渠道 ${channelId} 未安装。`);
+    if (record.status === 'failed') {
+      return fail('chat/channel-failed', record.error?.message ?? `渠道 ${channelId} 启动失败。`,
+        record.error?.code ? { channelCode: record.error.code } : {});
+    }
+    const endpoint = record.instance?.endpoints?.[method];
+    if (typeof endpoint !== 'function') {
+      return fail('chat/unknown-method', `渠道 ${channelId} 不支持 ${method}。`);
+    }
+    return endpoint(payload, { signal, channelId });
+  }
+
+  /** 注销全部渠道（插件卸载时）。 */
+  function disposeAll() {
+    for (const [id, record] of [...channels.entries()]) {
+      channels.delete(id);
+      void stop(record);
+    }
+    publish();
+  }
+
+  return { register, list, get, subscribe, handleRpc, disposeAll };
+}