@xmanrui/dsh-im 4.19.0 → 4.19.2

package/src/channels/shared/i18n.mjs

@@ -10,17 +10,60 @@ import { EN } from './i18n-en.mjs';
 
 let language = 'zh';
 
+const listeners = new Set();
+
 // Accepts 'en', 'en-US', 'english' (any case) as English; anything else
-// (including undefined and unrecognized values) selects Chinese.
-export function setImHostLanguage(lang) {
+// (including undefined and unrecognized values) selects Chinese. Pure: use it
+// to judge a candidate tag without switching the active language.
+export function normalizeImHostLanguage(lang) {
   const normalized = typeof lang === 'string' ? lang.trim().toLowerCase() : '';
-  language = normalized === 'english' || /^en(?:[-_].*)?$/u.test(normalized) ? 'en' : 'zh';
+  return normalized === 'english' || /^en(?:[-_].*)?$/u.test(normalized) ? 'en' : 'zh';
+}
+
+/**
+ * Select the language of every host-side message. Subscribers registered
+ * through onImHostLanguageChange are notified only when the resolved language
+ * actually changes, so re-applying the same selection in a different spelling
+ * (or an unrecognized tag that keeps falling back to Chinese) is free.
+ */
+export function setImHostLanguage(lang) {
+  const next = normalizeImHostLanguage(lang);
+  if (next === language) return language;
+  const previous = language;
+  language = next;
+  // Snapshot first: a subscriber may unsubscribe (or subscribe) while running.
+  for (const listener of [...listeners]) {
+    if (!listeners.has(listener)) continue;
+    try {
+      listener(next, previous);
+    } catch {
+      // Each subscriber owns its own diagnostics; one that fails must not
+      // strand the rest, nor abandon a language switch that already happened.
+    }
+  }
+  return language;
 }
 
 export function getImHostLanguage() {
   return language;
 }
 
+/**
+ * Observe committed changes to the host message language. Platform-side
+ * surfaces that were localized once at connect time (the Telegram command
+ * menu, for example) re-synchronize from here instead of waiting for a
+ * reconnect. Subscribers must not throw; the disposer is idempotent.
+ */
+export function onImHostLanguageChange(listener) {
+  if (typeof listener !== 'function') {
+    throw new TypeError('onImHostLanguageChange requires a listener function');
+  }
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
 // Translate a user-facing Chinese literal. In zh mode (the default) this is
 // the identity function. Optional `params` fills `{name}` placeholders in
 // both the Chinese key and its translation, e.g.

package/src/channels/shared/interface-language-store.mjs

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+import { normalizeInterfaceLanguageTag } from './interface-language.mjs';
+
+const DOCUMENT_VERSION = 1;
+
+function invalidTagError() {
+  const error = new Error('Invalid DSH interface language tag.');
+  error.code = 'interface-language-invalid';
+  return error;
+}
+
+// Mirrors the atomic settings writes of the inbound attachment TTL store and
+// the update service: create a private temporary file, then rename it in.
+async function writeSettingsDocument(path, document) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}
+
+/**
+ * Durable mirror of the DSH interface language, so bot messages keep following
+ * it across Host restarts and before any browser has connected. Only the
+ * lowest resolution layer lives here (see ./interface-language.mjs): an
+ * unreadable document resolves to "nothing mirrored" rather than pinning a
+ * language nobody chose.
+ */
+export class InterfaceLanguageStore {
+  #path;
+  #tag = null;
+  // Whether the document on disk is known to already say what #tag says. False
+  // for a missing or unreadable document, so the next report repairs it.
+  #stored = false;
+
+  constructor(path) {
+    if (typeof path !== 'string' || !path) {
+      throw new TypeError('interface language store path is required');
+    }
+    this.#path = path;
+  }
+
+  async load() {
+    let raw;
+    try {
+      raw = await readFile(this.#path, 'utf8');
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      this.#tag = null;
+      this.#stored = false;
+      await this.#removeStaleTemporaries();
+      return this;
+    }
+    const read = this.#readTag(raw);
+    this.#tag = read === undefined ? null : read;
+    this.#stored = read !== undefined;
+    await this.#removeStaleTemporaries();
+    return this;
+  }
+
+  // Crash leftovers from an interrupted atomic write are unreferenced by
+  // anyone; remove them so the settings directory stays clean.
+  async #removeStaleTemporaries() {
+    const directory = dirname(this.#path);
+    const prefix = `${basename(this.#path)}.`;
+    try {
+      const entries = await readdir(directory);
+      await Promise.all(entries
+        .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
+        .map((name) => unlink(join(directory, name)).catch(() => {})));
+    } catch {
+      // A missing directory or concurrent removal is fine; cleanup is best-effort.
+    }
+  }
+
+  // Returns the mirrored tag (null when the document mirrors nothing), or
+  // undefined when the document is damaged or from an unknown future version.
+  #readTag(raw) {
+    let document;
+    try {
+      document = JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+    if (!document || typeof document !== 'object' || Array.isArray(document)) return undefined;
+    if (document.version !== DOCUMENT_VERSION) return undefined;
+    if (document.interfaceLanguage === undefined) return null;
+    return normalizeInterfaceLanguageTag(document.interfaceLanguage) ?? undefined;
+  }
+
+  getLanguageTag() {
+    return this.#tag;
+  }
+
+  /**
+   * Record the interface language reported by the settings UI. Passing null
+   * clears the mirror, returning resolution to the layers above it. The
+   * settings page reports its locale on every mount, so an unchanged value is
+   * accepted without rewriting the document.
+   */
+  async setLanguageTag(value) {
+    const tag = value === null || value === undefined
+      ? null
+      : normalizeInterfaceLanguageTag(value);
+    if (tag === null && value !== null && value !== undefined) throw invalidTagError();
+    if (tag === this.#tag && this.#stored) return tag;
+    await writeSettingsDocument(this.#path, {
+      version: DOCUMENT_VERSION,
+      ...(tag === null ? {} : { interfaceLanguage: tag }),
+    });
+    this.#tag = tag;
+    this.#stored = true;
+    return tag;
+  }
+}

package/src/channels/shared/interface-language.mjs

@@ -0,0 +1,51 @@
+// Resolution policy for the DSH interface language that dsh-im's bot messages
+// follow.
+//
+// The host message language (./i18n.mjs) is a two-value switch: English, or
+// Chinese as the always-available fallback. The DSH interface language is a
+// BCP 47-style tag that a language pack may extend beyond the shipped zh/en
+// pair, so a tag is carried verbatim through resolution and persistence and is
+// collapsed to a dictionary language only where it reaches setImHostLanguage().
+
+/** Tag shape accepted by DSH's own locale preference (@deepseek-ai/dsh-client-locale). */
+const LANGUAGE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
+
+/**
+ * Resolution layers, highest precedence first.
+ *
+ * - `config`: the plugin's own `language` option (or `DSH_IM_LANGUAGE`). An
+ *   operator who pinned a language in the Host composition keeps it, whatever
+ *   any individual browser reads the interface in.
+ * - `settings`: the explicit selection in DSH's Language row, read from the
+ *   Host user-settings document. This is the setting users mean by "DSH is set
+ *   to English".
+ * - `mirror`: the last effective interface locale reported by the settings UI.
+ *   DSH stores nothing when the interface language came from the browser's
+ *   language list, so without this layer a reader who never opened the
+ *   Language row would still be answered in Chinese.
+ */
+export const HOST_LANGUAGE_SOURCES = Object.freeze(['config', 'settings', 'mirror']);
+
+/**
+ * Normalize one interface-language tag. Surrounding whitespace is trimmed;
+ * anything that is not a BCP 47-style tag returns null so a malformed layer is
+ * skipped rather than silently overriding the layers below it.
+ */
+export function normalizeInterfaceLanguageTag(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return LANGUAGE_TAG.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Pick the winning interface-language tag across the layers, in
+ * HOST_LANGUAGE_SOURCES order. Returns `{ tag: null, source: 'default' }` when
+ * no layer names a usable tag, which keeps Chinese as the shipped default.
+ */
+export function resolveHostLanguageTag(layers = {}) {
+  for (const source of HOST_LANGUAGE_SOURCES) {
+    const tag = normalizeInterfaceLanguageTag(layers[source]);
+    if (tag !== null) return { tag, source };
+  }
+  return { tag: null, source: 'default' };
+}

package/src/channels/shared/session-sync-registry.mjs

@@ -1,34 +1,22 @@
-/**
- * Session-sync ownership registry: records which delivery targets of a
- * session are being mirrored as process cards by their owning bridge.
- *
- * The plain-text session-sync coordinator and the per-bridge card mirror
- * observe the same global session events. When a bridge mirrors a turn to a
- * specific target, the coordinator must suppress the plain-text delivery for
- * THAT target only — other targets (same or other channels) still receive
- * their normal text. Both sides live in the same Host process, so a
- * module-level registry is the whole contract: the mirror claims a target
- * when it opens the mirror card and releases it when the turn ends.
- */
-const claimed = new Map();
+/** Optional per-bot card delivery. A registration is not a delivery receipt:
+ * the coordinator must await the renderer before suppressing final text. */
+const renderers = new Map();
 
-function keyOf(sessionId, targetId) {
-  return `${sessionId}\0${targetId ?? ''}`;
+function botKey({ channel, botId }) {
+  return JSON.stringify([channel, botId]);
 }
 
-export function claimSessionSyncMirror(sessionId, targetId = '', turn = null) {
-  if (typeof sessionId !== 'string' || !sessionId) return;
-  claimed.set(keyOf(sessionId, targetId), { turn, claimedAt: Date.now() });
+export function registerSessionSyncMirror(target, render) {
+  const key = botKey(target);
+  const entry = { render };
+  renderers.set(key, entry);
+  return () => {
+    if (renderers.get(key) === entry) renderers.delete(key);
+  };
 }
 
-export function releaseSessionSyncMirror(sessionId, targetId = '') {
-  claimed.delete(keyOf(sessionId, targetId));
-}
-
-/** True when a live mirror claim covers this session and target. */
-export function isSessionSyncMirrored(sessionId, targetId = '', turn = null) {
-  const claim = claimed.get(keyOf(sessionId, targetId));
-  if (!claim) return false;
-  if (turn !== null && claim.turn !== null && claim.turn !== turn) return false;
-  return true;
+export async function deliverSessionSyncMirror(target, sessionId, turn, text) {
+  const entry = renderers.get(botKey(target));
+  if (!entry) return false;
+  return await entry.render({ target, sessionId, turn, text }) === true;
 }

package/src/channels/shared/token-bot-controller.mjs

@@ -324,6 +324,32 @@ export class TokenBotController {
     };
   }
 
+  /**
+   * Re-synchronize the platform-side command menu of every connected bot.
+   *
+   * Called when the host message language changes: a menu the platform stored
+   * at connect time would otherwise keep the previous language until the bot
+   * reconnected. Runtimes of channels without a platform-side menu expose no
+   * refresh hook and are skipped, and one bot's failure never hides the rest.
+   * @returns the number of bots that accepted a refreshed menu.
+   */
+  async refreshCommandMenus() {
+    if (this.#closed) return 0;
+    const refreshed = await Promise.all([...this.#runtimes].map(async ([botId, runtime]) => {
+      if (typeof runtime?.refreshCommandMenu !== 'function') return false;
+      try {
+        return await runtime.refreshCommandMenu() === true;
+      } catch (error) {
+        this.#logger.warn?.(
+          `[dsh-im:${this.#descriptor.key}] bot ${botId} command menu refresh failed:`,
+          error,
+        );
+        return false;
+      }
+    }));
+    return refreshed.filter(Boolean).length;
+  }
+
   async close() {
     if (this.#closed) return;
     this.#closed = true;

package/src/channels/telegram/telegram-runtime.mjs

@@ -524,10 +524,10 @@ export class TelegramBotClient {
 
         const fallback = await this.#sendPlain(target, text);
         const terminalText = fallback.deliveryOutcome === 'sent'
-          ? '回复已发送。'
+          ? t('回复已发送。')
           : fallback.deliveryOutcome === 'unknown'
-            ? '回复发送结果未能确认。'
-            : '消息发送失败，请稍后重试。';
+            ? t('回复发送结果未能确认。')
+            : t('消息发送失败，请稍后重试。');
         try {
           await this.#api.editMessageText({
             chatId: target.chatId,
@@ -717,13 +717,13 @@ export class TelegramBotClient {
         keepalive: true,
         logger: this.#logger,
       });
-      await stream.update(createTextDeliveryBlock('正在处理…', 'plain'));
+      await stream.update(createTextDeliveryBlock(t('正在处理…'), 'plain'));
       return stream;
     }
 
     const placeholder = await this.#api.sendMessage({
       chatId: target.chatId,
-      text: '正在处理…',
+      text: t('正在处理…'),
       replyToMessageId: target.replyToMessageId,
       messageThreadId: target.messageThreadId,
       signal: this.#signal,
@@ -824,6 +824,14 @@ export class TelegramRuntime {
   #abortController = null;
   #pollTask = null;
   #starting = null;
+  // True only while #start() is between "started connecting" and "ready",
+  // which is the one window a skipped refresh must be reconciled. A refresh on
+  // a never-started or already-stopped runtime stays a no-op.
+  #connecting = false;
+  // True when a language switch arrived while the runtime was connecting, so a
+  // refreshCommandMenu() had nothing to push. Reconciled once startup
+  // completes, so the platform always ends up with the latest language.
+  #menuDirty = false;
 
   constructor({
     config,
@@ -902,6 +910,7 @@ export class TelegramRuntime {
 
   async #start() {
     await this.stop();
+    this.#connecting = true;
     this.#status.startedAt = new Date().toISOString();
     this.#status.connectionState = 'connecting';
     this.#status.lastError = null;
@@ -930,14 +939,7 @@ export class TelegramRuntime {
         throw error;
       }
       try {
-        const commands = telegramCommandMenu(this.#commandCatalog);
-        // Both operations use the existing default scope and language. Sending
-        // the full list replaces old entries; an empty catalog clears that list.
-        if (commands.length > 0) {
-          await api.setMyCommands({ commands, signal: controller.signal });
-        } else {
-          await api.deleteMyCommands({ signal: controller.signal });
-        }
+        await this.#sendCommandMenu(api, controller.signal);
         await api.setChatMenuButton({ menuButton: COMMANDS_MENU_BUTTON, signal: controller.signal });
       } catch (error) {
         this.#logger.warn?.(
@@ -973,6 +975,21 @@ export class TelegramRuntime {
       this.#status.connectionState = 'connected';
       this.#status.lastCheckedAt = now;
       this.#status.lastConnectedAt = now;
+      // A language switch that landed while we were connecting was skipped by
+      // refreshCommandMenu(); re-send the menu now that the API is usable, so
+      // the platform ends with the latest language instead of the one that was
+      // current when #sendCommandMenu first ran.
+      if (this.#menuDirty) {
+        this.#menuDirty = false;
+        try {
+          await this.#sendCommandMenu(api, controller.signal);
+        } catch (error) {
+          this.#logger.warn?.(
+            `[dsh-im:telegram] bot ${this.#config.botId} command menu catch-up failed:`,
+            error,
+          );
+        }
+      }
       this.#pollTask = this.#poll(cursor, controller.signal);
       this.#pollTask.catch((error) => {
         if (controller.signal.aborted) return;
@@ -988,6 +1005,51 @@ export class TelegramRuntime {
       this.#status.lastError = error?.message ?? String(error);
       await this.stop();
       throw error;
+    } finally {
+      // Whether the bot is now ready or the attempt failed, the connecting
+      // window is over. A failed attempt also drops any unreconciled dirty
+      // flag: a later retry re-sends the menu from scratch in the current
+      // language anyway.
+      this.#connecting = false;
+      this.#menuDirty = false;
+    }
+  }
+
+  // Both operations use the existing default scope and language. Sending the
+  // full list replaces old entries; an empty catalog clears that list.
+  async #sendCommandMenu(api, signal) {
+    const commands = telegramCommandMenu(this.#commandCatalog);
+    if (commands.length > 0) await api.setMyCommands({ commands, signal });
+    else await api.deleteMyCommands({ signal });
+  }
+
+  /**
+   * Re-send the command menu in the current host message language.
+   *
+   * The menu Telegram shows is registered once per connection, so a language
+   * change would otherwise stay invisible until the bot reconnected. This
+   * replaces the text only: the chat menu button is owned by connect.
+   * @returns whether a connected bot accepted the refreshed menu.
+   */
+  async refreshCommandMenu() {
+    const api = this.#api;
+    const signal = this.#abortController?.signal;
+    if (!this.#status.ready || !api || !signal || signal.aborted) {
+      // A refresh during an in-progress connection must not be lost: mark the
+      // menu dirty so #start() reconciles it the moment the bot is ready. A
+      // never-started or stopped runtime stays a no-op, as before.
+      if (this.#connecting) this.#menuDirty = true;
+      return false;
+    }
+    try {
+      await this.#sendCommandMenu(api, signal);
+      return true;
+    } catch (error) {
+      this.#logger.warn?.(
+        `[dsh-im:telegram] bot ${this.#config.botId} command menu refresh failed:`,
+        error,
+      );
+      return false;
     }
   }