@xmanrui/dsh-im 4.18.1 → 4.19.0

package/src/channels/feishu/bridge.mjs

@@ -28,6 +28,12 @@ import {
   validHarnessQuestion,
 } from '../shared/harness-question.mjs';
 import { HarnessApprovalQueue } from '../shared/harness-approval.mjs';
+import { textFromHarnessContent } from '../shared/harness-client.mjs';
+import { hasActiveHarnessInteractionOwner } from '../shared/harness-client.mjs';
+import {
+  claimSessionSyncMirror,
+  releaseSessionSyncMirror,
+} from '../shared/session-sync-registry.mjs';
 import {
   BatchInputManager,
   batchInputBusyMessage,
@@ -96,6 +102,7 @@ import {
   steerCard,
   watchListCard,
   workspaceListCard,
+  stepStatusText,
 } from './feishu-cards.mjs';
 import { t } from '../shared/i18n.mjs';
 import { MAX_WATCHES_PER_KEY } from './state-store.mjs';
@@ -188,6 +195,8 @@ const STEP_PUSH_POST_CHUNK_MAX_BYTES = 24_000;
 /** Streaming-card mode coalesces card renders behind one PATCH per interval —
  *  patching the same message is far more rate sensitive than posting. */
 const STEP_STREAM_PATCH_MIN_INTERVAL_MS = 1_000;
+/** Mux doesn't forward turn/end; this idle gap seals the mirror card. */
+const MIRROR_IDLE_SEAL_MS = 90_000;
 /** One answer chunk inside the streaming card: small enough that the block
  *  splitter can always distribute blocks across sealed/live cards. */
 const STEP_STREAM_ANSWER_CHUNK_MAX_BYTES = 18_000;
@@ -633,6 +642,19 @@ export class FeishuHarnessBridge {
   #observedCompletionEvents = new Map();
   /** Earliest completion that still needs delivery for each watch. */
   #failedWatchSeqs = new Map();
+  /** Host resolver: sessionId -> synced DM targets [{ openId, botId }]. */
+  #sessionSyncTargetsFor = null;
+  /** sessionId -> openId for live session-sync mirrors. */
+  #sessionSyncTargets = new Map();
+  /** In-flight adopt lookups, deduped per session. */
+  #sessionSyncAdopting = new Set();
+  /** Latest interim assistant text per mirrored session (folded on tool). */
+  #sessionSyncPendingStep = new Map();
+  /** Idle-seal timers: no events for a while = the turn ended (mux may
+   * not forward turn/end), so seal the mirror card with what it has. */
+  #sessionSyncIdleTimers = new Map();
+  /** Conversation keys with an IM ask in flight (set BEFORE the turn starts). */
+  #imTurnKeys = new Set();
   #cardDataTimeoutMs;
   /** When true, approval/question interactions render as Feishu cards (buttons). */
   #interactionCards = true;
@@ -660,6 +682,7 @@ export class FeishuHarnessBridge {
     cardDataTimeoutMs = CARD_DATA_TIMEOUT_MS,
     replyTimeoutMs = 600_000,
     interactionCards = true,
+    sessionSyncTargetsFor = null,
     logger = console,
     signal,
   }) {
@@ -709,6 +732,9 @@ export class FeishuHarnessBridge {
     this.#cardDataTimeoutMs = cardDataTimeoutMs;
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#interactionCards = interactionCards === true;
+    this.#sessionSyncTargetsFor = typeof sessionSyncTargetsFor === 'function'
+      ? sessionSyncTargetsFor
+      : null;
     this.#logger = logger;
     this.#approvals = new HarnessApprovalQueue({ label: 'Feishu', logger });
     this.#signal = signal;
@@ -722,10 +748,85 @@ export class FeishuHarnessBridge {
     if (typeof this.#harness?.watchHarnessEvents === 'function') {
       queueMicrotask(() => {
         this.#ensureEventWatcher();
+        // Delay the recovery: a restart lands while healthy turns may still
+        // be streaming; sealing them at t=0 would wipe live cards. 90s gives
+        // the turn's own events a window to re-adopt and finish normally.
+        setTimeout(() => { void this.#sealOrphanMirrors(); }, 90_000);
       });
     }
   }
 
+  /**
+   * Seal mirrors left running by a previous process: a restart kills the
+   * turn without a turn/end event, so the persisted card would stay
+   * "running" forever. Mark each orphan sealed (stopped) on delivery.
+   */
+  async #sealOrphanMirrors() {
+    const entries = typeof this.#state.mirrorEntries === 'function'
+      ? this.#state.mirrorEntries()
+      : [];
+    // Only claim cards older than the threshold: a restart lands while a
+    // healthy turn may still be streaming, and sealing it would wipe the
+    // live card. Anything older than a turn could plausibly run is orphaned.
+    const ORPHAN_AFTER_MS = 3 * 60_000;
+    for (const [sessionId, entry] of entries) {
+      if (!entry?.chatId || !Array.isArray(entry.cardIds)) continue;
+      if (typeof entry.claimedAt === 'number' && Date.now() - entry.claimedAt < ORPHAN_AFTER_MS) {
+        this.#logger.warn?.('[dsh-feishu] mirror entry too fresh to be orphaned; leaving untouched:', sessionId);
+        continue;
+      }
+      // The live card's last delivered content is persisted with the mirror:
+      // re-patch the live card with a stopped status line, keeping every
+      // panel intact. Sealed earlier chunks already carry no status line and
+      // keep their original content untouched.
+      let sealContent = null;
+      if (typeof entry.lastContent === 'string' && entry.lastContent) {
+        try {
+          const parsed = JSON.parse(entry.lastContent);
+          const elements = parsed?.body?.elements;
+          if (Array.isArray(elements) && elements.length > 0) {
+            const last = elements[elements.length - 1];
+            if (last?.tag === 'markdown' && typeof last.content === 'string'
+              && last.content.startsWith('_') && last.content.endsWith('_')) {
+              last.content = `_${stepStatusText('stopped')}_`;
+            } else {
+              elements.push({ tag: 'markdown', content: `_${stepStatusText('stopped')}_` });
+            }
+            sealContent = parsed;
+          }
+        } catch { /* fall through to an empty stopped card */ }
+      }
+      for (let index = 0; index < entry.cardIds.length; index += 1) {
+        const content = index === entry.cardIds.length - 1 && sealContent
+          ? JSON.stringify(sealContent)
+          : null;
+        if (content === null) continue;
+        await this.#patchStepCard(entry.cardIds[index], content)
+          .catch((error) => {
+            this.#logger.warn?.('[dsh-feishu] orphan mirror seal failed:', error?.message ?? error);
+          });
+      }
+      for (let index = 0; index < entry.cardIds.length; index += 1) {
+        const isLive = index === entry.cardIds.length - 1;
+        const content = isLive
+          ? (sealContent
+            ? JSON.stringify({ ...sealContent, data: JSON.stringify({
+              ...(JSON.parse(entry.lastContent).data ? JSON.parse(entry.lastContent).data : {}),
+            }) })
+            : stepStreamCard([], { status: 'stopped' }))
+          : stepStreamCard([], { status: 'stopped' });
+        await this.#patchStepCard(entry.cardIds[index], content)
+          .catch((error) => {
+            this.#logger.warn?.('[dsh-feishu] orphan mirror seal failed:', error?.message ?? error);
+          });
+      }
+      await this.#state.clearMirror?.(sessionId);
+      this.#logger.warn?.(
+        `[dsh-feishu] sealed ${entry.cardIds.length} orphan mirror card(s) for ${sessionId}`,
+      );
+    }
+  }
+
   setGroupResponseMode(value) {
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(value);
   }
@@ -2704,6 +2805,25 @@ export class FeishuHarnessBridge {
     const updateMessageId = nonEmptyString(options.updateMessageId);
     const replyTo = nonEmptyString(options.replyTo);
 
+    // Session-sync cards target the user's openId (the synced DM is a user,
+    // not a chat), delivered fresh without topic/thread handling.
+    if (options.receiveIdType === 'open_id') {
+      const response = await this.#client.im.v1.message.create({
+        params: { receive_id_type: 'open_id' },
+        data: {
+          receive_id: chatId,
+          msg_type: 'interactive',
+          content: cardJson,
+        },
+      });
+      if (response?.code && response.code !== 0) {
+        throw new Error(`Feishu card send failed: ${response.msg || response.code}`);
+      }
+      const sentId = nonEmptyString(response?.data?.message_id);
+      if (!sentId) throw new Error('Feishu card send returned no message_id');
+      return sentId;
+    }
+
     if (updateMessageId) {
       try {
         const response = await this.#client.im.v1.message.patch({
@@ -3224,13 +3344,19 @@ export class FeishuHarnessBridge {
 
   #ensureEventWatcher() {
     if (this.#eventWatcher) return;
-    if (typeof this.#harness?.watchHarnessEvents !== 'function') return;
+    if (typeof this.#harness?.watchHarnessEvents !== 'function') {
+      this.#logger.warn?.('[dsh-feishu] harness lacks watchHarnessEvents; session-sync mirror disabled');
+      return;
+    }
     if (this.#signal?.aborted) return;
     const signal = this.#signal ?? new AbortController().signal;
     try {
       this.#eventWatcher = this.#harness.watchHarnessEvents({
         signal,
-        onSessionEvent: (payload) => this.#onHarnessEvent(payload),
+        onSessionEvent: (payload) => {
+          console.error('[ss-final] mux:', payload?.sessionId?.slice(-12), payload?.event?.type);
+          this.#onHarnessEvent(payload);
+        },
         onReconnect: () => {
           void this.#compensateMissedEvents();
           void this.#deferred.resume();
@@ -3573,13 +3699,206 @@ export class FeishuHarnessBridge {
   }
 
   /** Queue live turn completions behind any reconnect compensation. */
+  /**
+   * Mirror one Harness session event into the session-sync process card for
+   * this session (a Web/CLI-initiated turn with a synced DM target). Events
+   * are translated into the same update shapes the ask callbacks produce, so
+   * the regular #stepCards ladder renders them identically: tool/call ->
+   * tool block, assistant/message -> live answer draft, turn/end -> sealed
+   * terminal card with the final answer.
+   */
+  /** True when this session's running turn was opened by one of OUR asks. */
+  #isImTurn(sessionId) {
+    for (const imKey of this.#imTurnKeys) {
+      if (this.#state.sessionFor?.(imKey) === sessionId) return true;
+    }
+    return false;
+  }
+
+  #beginImTurn(key) {
+    this.#imTurnKeys.add(key);
+  }
+
+  #endImTurn(key) {
+    this.#imTurnKeys.delete(key);
+  }
+
+  /**
+   * The session-event mux forwards surfaced events (user/tool/assistant) but
+   * NOT turn/start|turn/end, so the mirror cannot observe the turn boundary
+   * directly. Instead, arm an idle timer on every event: when no event
+   * arrives for MIRROR_IDLE_SEAL_MS, the turn is over — seal the card with
+   * its current content (answer draft included) as completed.
+   */
+  #armSessionSyncIdleTimer(sessionId, key, openId) {
+    const previous = this.#sessionSyncIdleTimers.get(sessionId);
+    if (previous) clearTimeout(previous);
+    const timer = setTimeout(() => {
+      this.#sessionSyncIdleTimers.delete(sessionId);
+      const card = this.#stepCards.get(key);
+      if (!card || card.broken) return;
+      void this.#finishStepCard(key, { stopped: false, answerText: null })
+        .then(() => this.#state.clearMirror?.(sessionId))
+        .catch((error) => {
+          console.error('[ss-final] idle seal failed:', error?.message ?? error);
+        });
+    }, MIRROR_IDLE_SEAL_MS);
+    this.#sessionSyncIdleTimers.set(sessionId, timer);
+  }
+
+  async #feedSessionSyncTurn(sessionId, event) {
+    if (this.#signal?.aborted) return;
+    const key = `session-sync\0${sessionId}`;
+    const type = event?.type;
+    const target = this.#sessionSyncTargets.get(sessionId);
+    const openId = typeof target === 'string' ? target : target?.openId;
+    this.#armSessionSyncIdleTimer(sessionId, key, openId);
+
+    if (type === 'turn/start') {
+      if (this.#stepCards.has(key)) {
+        return;
+      }
+      if (this.#isImTurn(sessionId)) {
+        return;
+      }
+      const targets = await this.#sessionSyncTargetsFor?.(sessionId);
+      const owned = (Array.isArray(targets) ? targets : [])
+        .find((target) => target.botId === this.#botId);
+      if (!owned?.openId) {
+        return;
+      }
+      this.#sessionSyncTargets.set(sessionId, owned);
+      // chatId carries the openId; #sendCard branches on the delivery marker.
+      this.#ensureStepCard(key, owned.openId, null);
+      this.#stepCards.get(key).deliveryViaOpenId = true;
+      this.#stepCards.get(key).sessionSyncSessionId = sessionId;
+      this.#stepCards.get(key).sessionSyncTargetId = owned.targetId ?? '';
+      // Persist the mirror so a restart can seal an orphaned running card.
+      await this.#state.setMirror?.(sessionId, { chatId: owned.openId, targetId: owned.targetId ?? '', cardIds: [], claimedAt: Date.now() });
+      // Claim only THIS target: the coordinator suppresses its plain text for
+      // the mirrored target while other synced targets keep their delivery.
+      claimSessionSyncMirror(sessionId, owned.targetId ?? '');
+      return;
+    }
+
+    const card = this.#stepCards.get(key);
+    if (!card) {
+      // The bridge (re)started mid-turn: adopt the running turn on its first
+      // visible event so the mirror still renders from here on.
+      if ((type === 'assistant/message' || type === 'tool/call')
+        && !this.#sessionSyncAdopting.has(sessionId)
+        && !this.#isImTurn(sessionId)) {
+        this.#sessionSyncAdopting.add(sessionId);
+        Promise.resolve()
+          .then(() => this.#sessionSyncTargetsFor?.(sessionId))
+          .then((targets) => {
+            const owned = (Array.isArray(targets) ? targets : [])
+              .find((target) => target.botId === this.#botId);
+            if (!owned?.openId) return null;
+            this.#sessionSyncTargets.set(sessionId, owned);
+            // Adopt = open the mirror card NOW, then handle this event.
+            this.#ensureStepCard(key, owned.openId, null);
+            this.#stepCards.get(key).deliveryViaOpenId = true;
+            this.#stepCards.get(key).sessionSyncSessionId = sessionId;
+            this.#stepCards.get(key).sessionSyncTargetId = owned.targetId ?? '';
+            void this.#state.setMirror?.(sessionId, { chatId: owned.openId, targetId: owned.targetId ?? '', cardIds: [], claimedAt: Date.now() });
+            claimSessionSyncMirror(sessionId, owned.targetId ?? '');
+            return this.#feedSessionSyncTurn(sessionId, event);
+          })
+          .catch((error) => {
+            this.#logger.warn?.('[dsh-feishu] session-sync adopt failed:', error?.message ?? error);
+          })
+          .finally(() => this.#sessionSyncAdopting.delete(sessionId));
+      }
+      return;
+    }
+    // A broken card must not swallow the turn boundary: turn/end still needs
+    // to release the mirror claim and clear the state so later turns and the
+    // plain-text fallback work again.
+    if (card.broken && type !== 'turn/end') return;
+
+    if (type === 'user/message' && event?.surfaceOp === 'append') {
+      // The coordinator's plain-text user echo is suppressed for mirrored
+      // turns, so the card carries the question itself: a quoted block at
+      // the top keeps the DM self-contained and readable in history.
+      const text = textFromHarnessContent(event?.data?.content);
+      if (text.trim()) {
+        const excerpt = text.length > 400 ? `${text.slice(0, 399)}…` : text;
+        await this.#appendStepCardUpdate(
+          key, openId, null,
+          { kind: 'message', text: `> 👤 **我问：**${excerpt.replaceAll('\n', '\n> ')}` },
+          { billable: false },
+        );
+      }
+      return;
+    }
+    if (type === 'tool/call') {
+      // Align with the ask-callback semantics: a draft proven interim by a
+      // tool call folds into the thinking panel instead of being overwritten
+      // by the next draft.
+      if (this.#sessionSyncPendingStep.has(sessionId)) {
+        this.#morphStepCardAnswerToNote(key, this.#sessionSyncPendingStep.get(sessionId));
+        this.#sessionSyncPendingStep.delete(sessionId);
+      }
+      await this.#appendStepCardUpdate(
+        key, openId, null,
+        this.#stepCardToolBlock({
+          name: event?.data?.name ?? '',
+          arguments: typeof event?.data?.arguments === 'string' ? event.data.arguments : '',
+        }),
+        { billable: false },
+      );
+      return;
+    }
+    if (type === 'assistant/message') {
+      const text = textFromHarnessContent(event?.data?.message?.content);
+      if (text.trim()) {
+        this.#sessionSyncPendingStep.set(sessionId, text);
+        this.#streamStepCardAnswer(key, openId, null, text);
+      }
+      return;
+    }
+    if (type === 'turn/end') {
+      this.#sessionSyncTargets.delete(sessionId);
+      this.#sessionSyncPendingStep.delete(sessionId);
+      releaseSessionSyncMirror(sessionId, card?.sessionSyncTargetId ?? '');
+      await this.#finishStepCard(key, {
+        stopped: event?.data?.reason?.kind === 'aborted',
+        answerText: null,
+      });
+      // Clear AFTER the seal: the render chain may still write mirror state
+      // while it finishes, so clearing earlier would be resurrected by the
+      // trailing setMirror from the last successful render.
+      await this.#state.clearMirror?.(sessionId);
+      return;
+    }
+  }
+
   #onHarnessEvent({ sessionId, event }) {
     if (this.#signal?.aborted
       || !sessionId
       || !event
       || typeof event !== 'object'
-      || event.type !== 'turn/end'
       || !validEventSeq(event.seq)) return;
+
+    // Session-sync mirror: turns opened OUTSIDE the IM (DSH Web / CLI) are
+    // rendered into the synced DM with the same #stepCards ladder as IM
+    // turns. The mirror consumes EVERY event type (turn/start opens the
+    // card, tool/call and assistant/message feed it, turn/end seals it);
+    // IM-opened turns are skipped — they already own their card via the ask
+    // callbacks. turn/end ALSO continues below for watch completions.
+    if (this.#sessionSyncTargetsFor) {
+      if (event.type === 'turn/end') {
+        console.error('[ss-final] turn/end reached dispatcher:', sessionId);
+      }
+      void this.#queueEventTask(`session-sync\0${sessionId}`, async () => {
+        await this.#feedSessionSyncTurn(sessionId, event);
+      }).catch((error) => {
+        console.error('[ss-final] mirror task failed:', event?.type, error?.message ?? error);
+      });
+      if (event.type !== 'turn/end') return;
+    }
+    if (event.type !== 'turn/end') return;
     // Record before consulting state: /watch may still be resolving its target
     // or waiting for setWatch persistence and therefore have no visible entry.
     this.#recordObservedCompletion(sessionId, event);
@@ -4045,6 +4364,23 @@ export class FeishuHarnessBridge {
       });
   }
 
+  /**
+   * Persist the mirror state for a session-sync card after a successful
+   * render. Plain IM cards (no sessionSyncSessionId) are never recorded —
+   * their lifecycle is owned by the ask path, not the mirror recovery.
+   * lastContent keeps stepStreamCard's raw JSON string (single-encoded).
+   */
+  #persistMirrorState(card, liveBlocks, status) {
+    const sessionId = card.sessionSyncSessionId;
+    if (!sessionId || typeof this.#state.setMirror !== 'function') return;
+    void this.#state.setMirror(sessionId, {
+      chatId: card.chatId,
+      cardIds: card.cardIds,
+      claimedAt: Date.now(),
+      lastContent: stepStreamCard(liveBlocks, { status }),
+    });
+  }
+
   async #renderStepCardNow(chatId, card) {
     if (card.broken) return;
     const chunks = splitStepStreamCardBlocks(card.blocks);
@@ -4061,12 +4397,15 @@ export class FeishuHarnessBridge {
           const id = await this.#sendCard(
             chatId,
             stepStreamCard(chunks[index], { status: isLive ? 'running' : 'sealed' }),
-            { replyTo: card.replyToMessageId },
+            card.deliveryViaOpenId
+              ? { receiveIdType: 'open_id' }
+              : { replyTo: card.replyToMessageId },
           );
           card.cardIds.push(id);
           if (isLive) card.messageId = id;
         }
         card.chunkCount = chunks.length;
+        this.#persistMirrorState(card, live, 'running');
         card.lastRenderAt = this.#stepPushClock.now();
         card.renderedAnswerVersion = card.answerVersion ?? 0;
         return;
@@ -4084,12 +4423,15 @@ export class FeishuHarnessBridge {
           const id = await this.#sendCard(
             chatId,
             stepStreamCard(chunks[index], { status: isLive ? 'running' : 'sealed' }),
-            { replyTo: card.replyToMessageId },
+            card.deliveryViaOpenId
+              ? { receiveIdType: 'open_id' }
+              : { replyTo: card.replyToMessageId },
           );
           card.cardIds.push(id);
           if (isLive) card.messageId = id;
         }
         card.chunkCount = chunks.length;
+        this.#persistMirrorState(card, live, 'running');
       } else {
         await this.#patchStepCard(card.messageId, stepStreamCard(live, { status: 'running' }));
       }
@@ -4101,6 +4443,19 @@ export class FeishuHarnessBridge {
         '[dsh-feishu] step streaming card render failed; the turn continues without it:',
         error?.message ?? String(error),
       );
+      if (card.deliveryViaOpenId) {
+        this.#logger.warn?.('[dsh-feishu] session-sync mirror card render failed:',
+          error?.message ?? String(error));
+        // Release the mirror claim at the FIRST failure so the plain-text
+        // coordinator takes over delivery for the rest of the turn (its
+        // user-echo suppression lifts immediately, and its recipients stay
+        // usable for the final answer fallback).
+        const sessionId = card.sessionSyncSessionId;
+        if (sessionId) {
+          releaseSessionSyncMirror(sessionId, card.sessionSyncTargetId ?? '');
+          void this.#state.clearMirror?.(sessionId);
+        }
+      }
     }
   }
 
@@ -4141,7 +4496,9 @@ export class FeishuHarnessBridge {
           const id = await this.#sendCard(
             card.chatId,
             stepStreamCard(groups[index], { status: isLive ? status : 'sealed' }),
-            { replyTo: card.replyToMessageId },
+            card.deliveryViaOpenId
+              ? { receiveIdType: 'open_id' }
+              : { replyTo: card.replyToMessageId },
           );
           card.cardIds.push(id);
         }
@@ -4161,7 +4518,9 @@ export class FeishuHarnessBridge {
           const id = await this.#sendCard(
             card.chatId,
             stepStreamCard(chunks[index], { status: isLast ? status : 'sealed' }),
-            { replyTo: card.replyToMessageId },
+            card.deliveryViaOpenId
+              ? { receiveIdType: 'open_id' }
+              : { replyTo: card.replyToMessageId },
           );
           card.cardIds.push(id);
           if (isLast) card.messageId = id;
@@ -4499,6 +4858,7 @@ export class FeishuHarnessBridge {
    * （工具参数折叠为代码块）；post 失败走既有纯文本降级。
    */
   async #answerWithStepPush(event, key, message, { onAskComplete } = {}) {
+    this.#beginImTurn(key);
     const chatId = event.message.chat_id;
     const messageId = event.message.message_id;
     const text = message.content;
@@ -4506,6 +4866,7 @@ export class FeishuHarnessBridge {
     const markAskComplete = () => {
       if (askCompleted) return;
       askCompleted = true;
+      this.#endImTurn(key);
       onAskComplete?.();
     };
     // 与流式分支一致的提示内容构造：图片与回复引用展开为富提示内容，已接受
@@ -4811,6 +5172,7 @@ export class FeishuHarnessBridge {
   }
 
   async #answerWithStream(event, key, message, { onAskComplete } = {}) {
+    this.#beginImTurn(key);
     const chatId = event.message.chat_id;
     const messageId = event.message.message_id;
     const text = message.content;
@@ -4818,6 +5180,7 @@ export class FeishuHarnessBridge {
     const markAskComplete = () => {
       if (askCompleted) return;
       askCompleted = true;
+      this.#endImTurn(key);
       onAskComplete?.();
     };
     // 分步直推：开关开启且通道支持流式卡时，在构造提示内容之前分流到完整替

package/src/channels/feishu/feishu-cards.mjs

@@ -1003,7 +1003,7 @@ function stepPanel(lines, { title, expanded }) {
   };
 }
 
-function stepStatusText(status) {
+export function stepStatusText(status) {
   if (status === 'completed') return t('已完成');
   if (status === 'stopped') return t('已停止');
   return t('运行中');

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

@@ -114,6 +114,7 @@ export class FeishuRuntime {
   #groupTopicReply;
   #stepPush;
   #stepPushMode;
+  #sessionSyncTargetsFor;
   #ownerOpenIds;
   #harness;
   #state;
@@ -146,6 +147,7 @@ export class FeishuRuntime {
     groupTopicReply = false,
     stepPush = false,
     stepPushMode = 'post',
+    sessionSyncTargetsFor = null,
     ownerOpenId,
     ownerOpenIds,
     harness,
@@ -184,6 +186,9 @@ export class FeishuRuntime {
     this.#groupTopicReply = groupTopicReply === true;
     this.#stepPush = stepPush === true;
     this.#stepPushMode = normalizeFeishuStepPushMode(stepPushMode);
+    this.#sessionSyncTargetsFor = typeof sessionSyncTargetsFor === 'function'
+      ? sessionSyncTargetsFor
+      : null;
     this.#ownerOpenIds = normalizedOwners;
     this.#harness = harness;
     this.#state = state;
@@ -314,6 +319,7 @@ export class FeishuRuntime {
         groupTopicReply: this.#groupTopicReply,
         stepPush: this.#stepPush,
         stepPushMode: this.#stepPushMode,
+        sessionSyncTargetsFor: this.#sessionSyncTargetsFor,
         repair: this.#repair,
         replyTimeoutMs: this.#replyTimeoutMs,
         // Interaction cards (approval/question buttons) are on by default.

package/src/channels/feishu/state-store.mjs

@@ -10,6 +10,7 @@ const EMPTY_STATE = Object.freeze({
   deferred: {},
   includeArchivedSessions: false,
   topics: {},
+  mirrors: {},
 });
 
 /** One conversation key may watch at most this many sessions. */
@@ -46,6 +47,7 @@ export class StateStore {
           ? parsed.includeArchivedSessions
           : false,
         topics: parsed.topics && typeof parsed.topics === 'object' ? parsed.topics : {},
+        mirrors: parsed.mirrors && typeof parsed.mirrors === 'object' ? parsed.mirrors : {},
       };
     } catch (error) {
       if (error?.code !== 'ENOENT') throw error;
@@ -59,6 +61,21 @@ export class StateStore {
   patchDeferred(id, patch) { return this.#deferred.patch(id, patch); }
   removeDeferred(id) { return this.#deferred.remove(id); }
 
+  // ── Mirrors (persisted: open session-sync cards, recovered at startup) ──
+  setMirror(sessionId, entry) {
+    this.#state.mirrors[sessionId] = entry;
+    return this.#persist();
+  }
+
+  clearMirror(sessionId) {
+    delete this.#state.mirrors[sessionId];
+    return this.#persist();
+  }
+
+  mirrorEntries() {
+    return Object.entries(this.#state.mirrors ?? {});
+  }
+
   sessionFor(key) {
     return this.#state.sessions[key] ?? null;
   }

package/src/channels/shared/bot-alias.mjs

@@ -0,0 +1,29 @@
+export const SET_ALIAS_ENDPOINT = 'bot.alias.set';
+export const MAX_BOT_ALIAS_LENGTH = 80;
+
+export function validateBotAlias(value) {
+  if (typeof value !== 'string' || value.trim().length > MAX_BOT_ALIAS_LENGTH
+    || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new TypeError('别名不能包含换行或控制字符，且最多 80 个字符。');
+  }
+  return value.trim();
+}
+
+export function normalizeBotAlias(bot) {
+  try {
+    const alias = validateBotAlias(bot?.alias);
+    return alias && typeof bot.originalName === 'string'
+      ? { alias, originalName: bot.originalName }
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function withBotAlias(bot, alias) {
+  if (!bot) return bot;
+  const { originalName = bot.name, alias: _alias, ...rest } = bot;
+  return alias
+    ? { ...rest, originalName, alias, name: alias }
+    : { ...rest, name: originalName };
+}