@xmanrui/dsh-im 4.9.1 → 4.11.0

package/src/channels/feishu/bridge.mjs

@@ -5,6 +5,8 @@ import {
   extractText,
   isAllowedSender,
   isBotSender,
+  isTopicGroupKey,
+  managedGroupKey,
   splitText,
 } from './message-utils.mjs';
 import {
@@ -101,6 +103,10 @@ import {
 // Lazily evaluated: t() must run after setImHostLanguage, not at import time.
 const INTERACTION_RESOLVED_TEXT = () => t('这个问题已在其他客户端处理，无需再次回答。');
 const RESOLVED_REPLY_TTL_MS = 30 * 60_000;
+/** Managed-topic root candidates expire without a returned thread_id. */
+const ROOT_CANDIDATE_TTL_MS = 30 * 60_000;
+/** Bound main-feed roots awaiting a topic so silent drops cannot grow them. */
+const MAX_ROOT_CANDIDATES = 512;
 
 const MENU_COMMAND = /^\/m(?:enu)?$/i;
 const REPAIR_COMMAND_PREFIX = /^\/repair(?:\s|$)/i;
@@ -480,6 +486,14 @@ export class FeishuHarnessBridge {
   #appId;
   #botOpenId;
   #groupResponseMode;
+  /** When true, group replies that belong to a Feishu topic ask reply_in_thread. */
+  #groupTopicReply = false;
+  /** Group chats this bot has seen; only these may use topic replies. */
+  #groupChatIds = new Set();
+  /** Anchor message id → whether its replies should stay in a Feishu topic. */
+  #anchorTopicReply = new Map();
+  /** Main-feed roots this bot intends to auto-open as topics, awaiting thread_id. */
+  #rootCandidates = new Map();
   #repair;
   #repairAttempt = null;
   #repairMonitorVersion = 0;
@@ -516,6 +530,7 @@ export class FeishuHarnessBridge {
     appId,
     botOpenId,
     groupResponseMode = FEISHU_GROUP_RESPONSE_MODES.ALL,
+    groupTopicReply = false,
     repair,
     repairPollIntervalMs = REPAIR_POLL_INTERVAL_MS,
     repairLinkWaitMs = REPAIR_LINK_WAIT_MS,
@@ -555,6 +570,7 @@ export class FeishuHarnessBridge {
     this.#appId = nonEmptyString(appId);
     this.#botOpenId = nonEmptyString(botOpenId);
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(groupResponseMode);
+    this.#groupTopicReply = groupTopicReply === true;
     this.#repair = repair ?? null;
     this.#repairPollIntervalMs = repairPollIntervalMs;
     this.#repairLinkWaitMs = repairLinkWaitMs;
@@ -576,6 +592,10 @@ export class FeishuHarnessBridge {
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(value);
   }
 
+  setGroupTopicReply(value) {
+    this.#groupTopicReply = value === true;
+  }
+
   #isAddressed(event) {
     if (event?.message?.chat_type === 'p2p') return true;
     const mentions = Array.isArray(event?.message?.mentions) ? event.message.mentions : [];
@@ -584,6 +604,106 @@ export class FeishuHarnessBridge {
       || mention?.open_id === this.#botOpenId);
   }
 
+  /**
+   * Conversation key for one inbound event. When group-topic replies are on,
+   * a main-feed question addressed to the bot opens a fresh managed topic
+   * session instead of joining the shared group session, and messages inside
+   * a topic we already opened resolve back to that same managed session.
+   */
+  #resolveKey(event) {
+    const chatType = event?.message?.chat_type;
+    const chatId = nonEmptyString(event?.message?.chat_id);
+    if (chatType !== 'group') return conversationKey(event);
+    const messageId = nonEmptyString(event?.message?.message_id);
+    const threadId = nonEmptyString(event?.message?.thread_id);
+    if (threadId) {
+      const root = this.#state?.topicRootFor?.(threadId) ?? null;
+      return root && chatId
+        ? managedGroupKey(chatId, root.rootMessageId)
+        : `group:${chatId}:thread:${threadId}`;
+    }
+    if (this.#groupTopicReply && chatId && messageId && this.#isAddressed(event)) {
+      return managedGroupKey(chatId, messageId);
+    }
+    return `group:${chatId}`;
+  }
+
+  /**
+   * Record whether replies anchored on `messageId` should stay in a topic.
+   * `asRoot` marks a main-feed question this bot will auto-open as a topic.
+   */
+  #rememberTopicReply(messageId, key) {
+    if (!nonEmptyString(messageId)) return;
+    this.#anchorTopicReply.set(messageId, this.#groupTopicReply && isTopicGroupKey(key));
+    if (this.#anchorTopicReply.size > 2048) {
+      const oldest = this.#anchorTopicReply.keys().next().value;
+      if (oldest !== undefined) this.#anchorTopicReply.delete(oldest);
+    }
+    if (typeof key === 'string' && key.startsWith('group:')) {
+      const chatId = key.split(':')[1];
+      if (chatId) this.#groupChatIds.add(chatId);
+    }
+  }
+
+  /** Whether a reply anchored on `replyTo` must ask Feishu to keep it in a topic. */
+  #replyInThreadFor(replyTo) {
+    return this.#groupTopicReply
+      && nonEmptyString(replyTo)
+      && this.#anchorTopicReply.get(replyTo) === true;
+  }
+
+  /** Drop expired root candidates so a silently dropped reply cannot leak memory. */
+  #pruneRootCandidates(now = Date.now()) {
+    for (const [messageId, expiresAt] of this.#rootCandidates) {
+      if (expiresAt <= now) this.#rootCandidates.delete(messageId);
+    }
+  }
+
+  /** Track a main-feed root this bot will auto-open as a topic, bounded + TTL'd. */
+  #rememberTopicRoot(messageId) {
+    if (!nonEmptyString(messageId)) return;
+    const now = Date.now();
+    this.#pruneRootCandidates(now);
+    this.#rootCandidates.delete(messageId);
+    this.#rootCandidates.set(messageId, now + ROOT_CANDIDATE_TTL_MS);
+    while (this.#rootCandidates.size > MAX_ROOT_CANDIDATES) {
+      const oldest = this.#rootCandidates.keys().next().value;
+      if (oldest === undefined) break;
+      this.#rootCandidates.delete(oldest);
+    }
+  }
+
+  /** Forget a root candidate once its topic opened or the reply degraded. */
+  #forgetTopicRoot(messageId) {
+    if (!nonEmptyString(messageId)) return;
+    this.#rootCandidates.delete(messageId);
+  }
+
+  /** Persist thread_id once Feishu auto-opened a topic from a managed root. */
+  async #registerTopicFromReply(replyTo, chatId, response) {
+    const threadId = nonEmptyString(response?.data?.thread_id);
+    if (threadId) {
+      await this.#registerTopicThreadId(threadId, replyTo, chatId);
+    } else {
+      // No thread_id means the topic did not open; drop the candidate so a
+      // later addressed question opens a fresh session, not a stale slot.
+      this.#forgetTopicRoot(replyTo);
+    }
+  }
+
+  /** Persist thread_id when the reply anchor is a root this bot auto-opened. */
+  async #registerTopicThreadId(threadId, rootMessageId, chatId) {
+    this.#pruneRootCandidates();
+    if (!threadId || !this.#rootCandidates.has(rootMessageId)) return;
+    this.#rootCandidates.delete(rootMessageId);
+    if (!chatId || typeof this.#state?.setTopic !== 'function') return;
+    try {
+      await this.#state.setTopic(threadId, { rootMessageId, chatId });
+    } catch (error) {
+      this.#logger.warn?.('[dsh-feishu] failed to record managed topic:', error?.message ?? String(error));
+    }
+  }
+
   accept(event) {
     if (this.#signal?.aborted) return Promise.resolve();
     const messageId = nonEmptyString(event?.message?.message_id);
@@ -606,12 +726,13 @@ export class FeishuHarnessBridge {
 
     let key;
     try {
-      key = conversationKey(event);
+      key = this.#resolveKey(event);
     } catch {
       this.#status.messagesRejected += 1;
       this.#status.lastRejectedAt = new Date().toISOString();
       return Promise.resolve();
     }
+    this.#rememberTopicReply(messageId, key);
 
     const commandMessage = extractInboundMessage(event, this.#client);
     const commandText = nonEmptyString(commandMessage.content) ?? '';
@@ -635,6 +756,15 @@ export class FeishuHarnessBridge {
       this.#acceptedMessageIds.set(messageId, null);
       return this.#finishAccessDecision(event, messageId, access);
     }
+    // Register a managed-topic root only after access is allowed, so a
+    // rejected or ignored question never reserves a candidate slot.
+    if (this.#groupTopicReply
+      && event?.message?.chat_type === 'group'
+      && !nonEmptyString(event?.message?.thread_id)
+      && isTopicGroupKey(key)
+      && key.includes(':managed:')) {
+      this.#rememberTopicRoot(messageId);
+    }
     if (event.message.chat_type === 'p2p') {
       const chatId = nonEmptyString(event.message.chat_id);
       if (chatId) rememberConnectionTestTarget(this.#state, { chatId });
@@ -1910,6 +2040,7 @@ export class FeishuHarnessBridge {
   }) {
     // Confirmations triggered by a card interaction stay anchored to the
     // card's message so they land inside the same Feishu topic.
+    this.#rememberTopicReply(messageId, key);
     const reply = (text) => this.#send(chatId, text, { replyTo: messageId });
     // Approval card buttons: approve:<approvalId> / reject:<approvalId>
     if (action.startsWith('approve:') || action.startsWith('reject:')) {
@@ -2383,18 +2514,25 @@ export class FeishuHarnessBridge {
       try {
         const response = await this.#client.im.v1.message.reply({
           path: { message_id: replyTo },
-          data: { msg_type: 'interactive', content },
+          data: {
+            msg_type: 'interactive',
+            content,
+            ...(this.#replyInThreadFor(replyTo) ? { reply_in_thread: true } : {}),
+          },
         });
         if (response?.code && response.code !== 0) {
           throw new Error(`Feishu card reply failed: ${response.msg || response.code}`);
         }
         const repliedMessageId = nonEmptyString(response?.data?.message_id);
+        await this.#registerTopicFromReply(replyTo, chatId, response);
         if (repliedMessageId) {
           this.#rememberCardRoute(repliedMessageId, chatId, options);
           return repliedMessageId;
         }
       } catch (error) {
         this.#logger.warn?.('[dsh-feishu] threaded card reply failed; sending a plain card:', error?.message ?? String(error));
+        // The topic never opened; a managed root candidate must not linger.
+        this.#forgetTopicRoot(replyTo);
       }
     }
     const response = await this.#client.im.v1.message.create({
@@ -3206,6 +3344,10 @@ export class FeishuHarnessBridge {
         || (validLastSeq(entry.lastSeq) && entry.lastSeq >= event.seq)
         || (validEventSeq(failedSeq) && event.seq > failedSeq)) continue;
       try {
+        // Re-derive topic intent at delivery time: the push may outlive the
+        // bounded in-memory anchor cache, but the conversation key still tells
+        // us whether the completion belongs to a Feishu topic.
+        this.#rememberTopicReply(entry.replyToMessageId ?? null, key);
         await this.#sendCard(
           entry.chatId,
           completionCard(sessionId, entry.title, reason),
@@ -3346,12 +3488,18 @@ export class FeishuHarnessBridge {
         ? (file) => this.#channel.sendImage(chatId, file, {
             replyTo,
             signal: this.#signal,
+            ...(this.#replyInThreadFor(replyTo)
+              ? { replyInThread: true, onReplyThreadId: async (threadId) => this.#registerTopicThreadId(threadId, replyTo, chatId) }
+              : {}),
           })
         : undefined,
       sendFile: typeof this.#channel?.sendFile === 'function'
         ? (file) => this.#channel.sendFile(chatId, file, {
             replyTo,
             signal: this.#signal,
+            ...(this.#replyInThreadFor(replyTo)
+              ? { replyInThread: true, onReplyThreadId: async (threadId) => this.#registerTopicThreadId(threadId, replyTo, chatId) }
+              : {}),
           })
         : undefined,
       onFailure: (artifact, error) => setLastMessageFailure(this.#status, error, {
@@ -3499,7 +3647,12 @@ export class FeishuHarnessBridge {
           completedArtifacts = completed.artifacts ?? [];
           await controller.setContent(answerTextForDelivery(completedAnswer, completedArtifacts));
         },
-      }, { replyTo: messageId });
+      }, {
+        replyTo: messageId,
+        ...(this.#replyInThreadFor(messageId)
+          ? { replyInThread: true, onReplyThreadId: async (threadId) => this.#registerTopicThreadId(threadId, messageId, chatId) }
+          : {}),
+      });
     } catch (error) {
       this.#status.streamErrors = (this.#status.streamErrors ?? 0) + 1;
       if (completedAnswer || completedArtifacts.length > 0) {
@@ -4007,11 +4160,16 @@ export class FeishuHarnessBridge {
       try {
         const response = await this.#client.im.v1.message.reply({
           path: { message_id: replyTo },
-          data: { msg_type: 'text', content },
+          data: {
+            msg_type: 'text',
+            content,
+            ...(this.#replyInThreadFor(replyTo) ? { reply_in_thread: true } : {}),
+          },
         });
         if (response?.code && response.code !== 0) {
           throw new Error(`Feishu reply failed: ${response.msg || response.code}`);
         }
+        await this.#registerTopicFromReply(replyTo, chatId, response);
         return nonEmptyString(response?.data?.message_id);
       } catch (error) {
         // The referenced message may be gone (recalled/deleted); keep the
@@ -4020,6 +4178,8 @@ export class FeishuHarnessBridge {
           '[dsh-feishu] threaded reply failed; falling back to a plain message:',
           error?.message ?? String(error),
         );
+        // The topic never opened; a managed root candidate must not linger.
+        this.#forgetTopicRoot(replyTo);
       }
     }
     const response = await this.#client.im.v1.message.create({

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

@@ -208,7 +208,7 @@ export class VerifiedFeishuChannel {
     let activeCard = null;
     let rotating = false;
     try {
-      activeCard = await this.#createStreamCard(chatId, options.replyTo);
+      activeCard = await this.#createStreamCard(chatId, options);
       cards.push(activeCard);
       let lastContent = this.#initialText;
       // issue #86：独立交互消息（提问/审批）落在占位卡下方后，最终答案不得
@@ -217,7 +217,7 @@ export class VerifiedFeishuChannel {
       // 交互消息之后。旧卡纳入 cards，参与 recall 与 providerMessageIds。
       const ensureActiveCard = async () => {
         if (!rotating) return activeCard;
-        activeCard = await this.#createStreamCard(chatId, options.replyTo);
+        activeCard = await this.#createStreamCard(chatId, options);
         cards.push(activeCard);
         rotating = false;
         return activeCard;
@@ -255,7 +255,7 @@ export class VerifiedFeishuChannel {
       for (const [index, chunk] of chunks.entries()) {
         const card = index === 0
           ? await ensureActiveCard()
-          : await this.#createStreamCard(chatId, options.replyTo);
+          : await this.#createStreamCard(chatId, options);
         if (index > 0) cards.push(card);
         await this.#updateStreamCard(card, chunk);
         await this.#finishStreamCard(card);
@@ -272,19 +272,33 @@ export class VerifiedFeishuChannel {
     }
   }
 
-  async sendFile(chatId, file, { replyTo, signal } = {}) {
+  async sendFile(chatId, file, {
+    replyTo,
+    signal,
+    replyInThread = false,
+    onReplyThreadId,
+  } = {}) {
     return this.#sendArtifact(chatId, file, {
       replyTo,
       signal,
+      replyInThread,
+      onReplyThreadId,
       messageType: 'file',
       presentation: 'feishu-file',
     });
   }
 
-  async sendImage(chatId, file, { replyTo, signal } = {}) {
+  async sendImage(chatId, file, {
+    replyTo,
+    signal,
+    replyInThread = false,
+    onReplyThreadId,
+  } = {}) {
     return this.#sendArtifact(chatId, file, {
       replyTo,
       signal,
+      replyInThread,
+      onReplyThreadId,
       messageType: 'image',
       presentation: 'feishu-image',
     });
@@ -293,6 +307,8 @@ export class VerifiedFeishuChannel {
   async #sendArtifact(chatId, file, {
     replyTo,
     signal,
+    replyInThread = false,
+    onReplyThreadId,
     messageType,
     presentation,
   }) {
@@ -349,7 +365,12 @@ export class VerifiedFeishuChannel {
     const request = replyTo
       ? {
           path: { message_id: replyTo },
-          data: { msg_type: messageType, content, uuid },
+          data: {
+            msg_type: messageType,
+            content,
+            uuid,
+            ...(replyInThread === true ? { reply_in_thread: true } : {}),
+          },
         }
       : {
           params: { receive_id_type: 'chat_id' },
@@ -399,6 +420,10 @@ export class VerifiedFeishuChannel {
     if (typeof messageId !== 'string' || !messageId) {
       throw fileDeliveryError('message send', undefined, undefined, { uncertain: true });
     }
+    if (replyTo && typeof onReplyThreadId === 'function') {
+      const threadId = response?.data?.thread_id;
+      if (typeof threadId === 'string' && threadId) await onReplyThreadId(threadId);
+    }
     return createDeliveryReceipt({
       deliveryId: file.deliveryKey,
       presentation,
@@ -410,7 +435,7 @@ export class VerifiedFeishuChannel {
     });
   }
 
-  async #createStreamCard(chatId, replyTo) {
+  async #createStreamCard(chatId, options = {}) {
     const content = streamPreview(this.#initialText);
     const response = assertApiSuccess('Feishu card.create', await this.#client.cardkit.v1.card.create({
       data: {
@@ -420,7 +445,7 @@ export class VerifiedFeishuChannel {
     }));
     const cardId = response?.data?.card_id;
     if (!cardId) throw new Error('Feishu card.create returned no card_id');
-    const messageId = await this.#sendCard(chatId, cardId, replyTo);
+    const messageId = await this.#sendCard(chatId, cardId, options);
     return { cardId, messageId, content, sequence: 0 };
   }
 
@@ -455,12 +480,18 @@ export class VerifiedFeishuChannel {
     assertApiSuccess('Feishu card.settings', response);
   }
 
-  async #sendCard(chatId, cardId, replyTo) {
+  async #sendCard(chatId, cardId, options = {}) {
+    const replyTo = options.replyTo;
+    const replyInThread = options.replyInThread === true;
     const content = JSON.stringify({ type: 'card', data: { card_id: cardId } });
     const response = replyTo
       ? await this.#client.im.v1.message.reply({
         path: { message_id: replyTo },
-        data: { msg_type: 'interactive', content },
+        data: {
+          msg_type: 'interactive',
+          content,
+          ...(replyInThread ? { reply_in_thread: true } : {}),
+        },
       })
       : await this.#client.im.v1.message.create({
         params: { receive_id_type: 'chat_id' },
@@ -469,6 +500,10 @@ export class VerifiedFeishuChannel {
     assertApiSuccess('Feishu message send', response);
     const messageId = response?.data?.message_id;
     if (!messageId) throw new Error('Feishu message send returned no message_id');
+    if (replyTo && typeof options.onReplyThreadId === 'function') {
+      const threadId = response?.data?.thread_id;
+      if (typeof threadId === 'string' && threadId) await options.onReplyThreadId(threadId);
+    }
     return messageId;
   }
 

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

@@ -110,6 +110,7 @@ export class FeishuRuntime {
   #domain;
   #botOpenId;
   #groupResponseMode;
+  #groupTopicReply;
   #ownerOpenIds;
   #harness;
   #state;
@@ -139,6 +140,7 @@ export class FeishuRuntime {
     domain = 'feishu',
     botOpenId,
     groupResponseMode,
+    groupTopicReply = false,
     ownerOpenId,
     ownerOpenIds,
     harness,
@@ -174,6 +176,7 @@ export class FeishuRuntime {
     this.#domain = domain;
     this.#botOpenId = nonEmptyString(botOpenId);
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(groupResponseMode);
+    this.#groupTopicReply = groupTopicReply === true;
     this.#ownerOpenIds = normalizedOwners;
     this.#harness = harness;
     this.#state = state;
@@ -198,6 +201,11 @@ export class FeishuRuntime {
     this.#bridge?.setGroupResponseMode(this.#groupResponseMode);
   }
 
+  setGroupTopicReply(value) {
+    this.#groupTopicReply = value === true;
+    this.#bridge?.setGroupTopicReply(this.#groupTopicReply);
+  }
+
   async start() {
     while (true) {
       while (this.#stopping) await this.#stopping;
@@ -286,6 +294,7 @@ export class FeishuRuntime {
         appId: this.#appId,
         botOpenId: this.#botOpenId,
         groupResponseMode: this.#groupResponseMode,
+        groupTopicReply: this.#groupTopicReply,
         repair: this.#repair,
         replyTimeoutMs: this.#replyTimeoutMs,
         // Interaction cards (approval/question buttons) are on by default.

package/src/channels/feishu/message-utils.mjs

@@ -13,6 +13,19 @@ const FEISHU_CARD_UNAVAILABLE_TEXTS = new Set([
 const FEISHU_IMAGE_PERMISSION_MESSAGE =
   '飞书机器人缺少图片读取权限 im:message:readonly（飞书显示为“获取单聊、群组消息”）。请私聊机器人执行 /repair 命令，或者在「IM机器人」设置页点击“补全权限”按钮并扫码。按飞书提示发布新版本、完成必要审批后，再重新发送图片。';
 
+/** Managed-topic group key: one per Feishu topic auto-rooted at a message. */
+export function managedGroupKey(chatId, rootMessageId) {
+  if (!chatId) throw new Error('Feishu managed-topic key needs a chat_id');
+  if (!rootMessageId) throw new Error('Feishu managed-topic key needs a root message id');
+  return `group:${chatId}:managed:${rootMessageId}`;
+}
+
+/** Whether a key denotes a topic-isolated group conversation (thread or managed). */
+export function isTopicGroupKey(key) {
+  return typeof key === 'string' && key.startsWith('group:')
+    && (key.includes(':thread:') || key.includes(':managed:'));
+}
+
 export function conversationKey(event) {
   const chatType = event?.message?.chat_type;
   if (chatType === 'p2p') {

package/src/channels/feishu/multi-bot-controller.mjs

@@ -90,6 +90,7 @@ function configuredBotFingerprint(config) {
     botOpenId: config.botOpenId,
     activated: config.activated,
     groupResponseMode: normalizeFeishuGroupResponseMode(config.groupResponseMode),
+    groupTopicReply: config.groupTopicReply === true,
     groupMessagePermissionGranted: config.groupMessagePermissionGranted === true,
     deletionPending: config.deletionPending === true,
     connectedAt: config.connectedAt ?? null,
@@ -584,6 +585,20 @@ export class MultiBotDshFeishuController {
     }));
   }
 
+  async updateGroupTopicReply(botId, groupTopicReply) {
+    this.#assertOpen();
+    if (typeof groupTopicReply !== 'boolean') {
+      throw new TypeError('Invalid Feishu group topic reply flag');
+    }
+    return this.#serializeConfig(() => this.#withBotTransition(botId, async () => {
+      const config = this.#requireBot(botId);
+      const saved = await this.#configStore.saveBot({ ...config, groupTopicReply });
+      this.#runtimes.get(botId)?.setGroupTopicReply?.(saved.groupTopicReply);
+      this.#touch();
+      return this.status(botId);
+    }));
+  }
+
   async deleteBot(botId) {
     this.#assertOpen();
     return this.#serializeConfig(() => this.#withBotTransition(botId, async () => {
@@ -646,6 +661,7 @@ export class MultiBotDshFeishuController {
         connected,
         configured: true,
         groupResponseMode: normalizeFeishuGroupResponseMode(config.groupResponseMode),
+        groupTopicReply: config.groupTopicReply === true,
         groupMessagePermissionGranted: config.groupMessagePermissionGranted === true,
         bot: publicBot(config),
         connection,

package/src/channels/feishu/plugin-config-store.mjs

@@ -45,6 +45,7 @@ function normalizeBot(value, { legacy = false } = {}) {
     botOpenId: cleanString(value.botOpenId),
     activated: value.activated ?? null,
     groupResponseMode: normalizeFeishuGroupResponseMode(value.groupResponseMode),
+    groupTopicReply: value.groupTopicReply === true,
     groupMessagePermissionGranted: value.groupMessagePermissionGranted === true,
     deletionPending: value.deletionPending === true,
     connectedAt: cleanString(value.connectedAt),

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

@@ -7,6 +7,7 @@ const EMPTY_STATE = Object.freeze({
   seenMessageIds: [],
   watches: {},
   includeArchivedSessions: false,
+  topics: {},
 });
 
 /** One conversation key may watch at most this many sessions. */
@@ -40,6 +41,7 @@ export class StateStore {
         includeArchivedSessions: typeof parsed.includeArchivedSessions === 'boolean'
           ? parsed.includeArchivedSessions
           : false,
+        topics: parsed.topics && typeof parsed.topics === 'object' ? parsed.topics : {},
       };
     } catch (error) {
       if (error?.code !== 'ENOENT') throw error;
@@ -136,6 +138,29 @@ export class StateStore {
     return [...ids];
   }
 
+  // ── Managed Feishu topics (thread_id → root message, persisted) ────────
+
+  topicRootFor(threadId) {
+    const entry = this.#state.topics[threadId];
+    return entry && typeof entry === 'object'
+      && typeof entry.rootMessageId === 'string' && entry.rootMessageId.length > 0
+      && typeof entry.chatId === 'string' && entry.chatId.length > 0
+      ? { rootMessageId: entry.rootMessageId, chatId: entry.chatId }
+      : null;
+  }
+
+  async setTopic(threadId, root) {
+    const validRoot = root && typeof root === 'object'
+      && typeof root.rootMessageId === 'string' && root.rootMessageId.length > 0
+      && typeof root.chatId === 'string' && root.chatId.length > 0;
+    if (!validRoot) throw new TypeError('Invalid Feishu topic root');
+    this.#state.topics[threadId] = {
+      rootMessageId: root.rootMessageId,
+      chatId: root.chatId,
+    };
+    await this.#persist();
+  }
+
   // ── Session-list archived policy (per bot) ───────────────────
 
   includesArchivedSessions() {