botmux 2.9.0 → 2.9.2

package/dist/im/lark/event-dispatcher.js

@@ -6,16 +6,18 @@
 import * as Lark from '@larksuiteoapi/node-sdk';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { getBot, getAllBots, findOncallChat } from '../../bot-registry.js';
+import { getBot, getAllBots, isChatOncallBoundForAnyBot } from '../../bot-registry.js';
 import { config } from '../../config.js';
-import { getChatInfo, listChatBotMembers, replyMessage } from './client.js';
+import { getChatInfo, getChatMode, replyMessage, sendUserMessage } from './client.js';
 import { logger } from '../../utils/logger.js';
+import { parseForceTopicInvocation } from '../../core/command-handler.js';
+import { stripLeadingMentions } from './message-parser.js';
 // ─── Bot identity ─────────────────────────────────────────────────────────
 /** Set the bot's open_id. Callers should also call writeBotInfoFile() to persist. */
 export function setBotOpenId(larkAppId, id) {
     getBot(larkAppId).botOpenId = id;
 }
-/** Persist bot registry info to disk for MCP subprocesses to read.
+/** Persist bot registry info to disk for agent-facing CLI subcommands to read.
  *  Merges current process's bot(s) into the existing file so that
  *  multiple daemon processes (one per bot) don't overwrite each other. */
 export function writeBotInfoFile(dataDir) {
@@ -82,40 +84,143 @@ export async function probeBotOpenId(larkAppId) {
         throw new Error('No open_id in bot info response');
     }
 }
-// ─── Group user count cache ───────────────────────────────────────────────
-const chatUserCountCache = new Map();
-export const CHAT_CACHE_TTL = 5 * 60_000; // 5 minutes
-export async function getGroupUserCount(larkAppId, chatId) {
-    const cacheKey = `${larkAppId}:${chatId}`;
-    const cached = chatUserCountCache.get(cacheKey);
-    if (cached && Date.now() - cached.fetchedAt < CHAT_CACHE_TTL) {
-        return cached.count;
+// ─── Required-scope check ───────────────────────────────────────────────────
+//
+// Bot-to-bot @mention 投递依赖 "获取群组中其他机器人和用户@当前机器人的消息"
+// 权限（scope: im:message.group_at_msg.include_bot:readonly）。该权限关闭
+// 后飞书不会把跨 bot 的事件推到 WSClient，botmux 的 handleThreadReply 收
+// 不到，看上去就是"另一个 bot @ 我没反应"——而 botmux 已经把本地 signal-file
+// 转发删了，不再有兜底。启动时主动校验一下，缺了就向 allowedUsers[0] 私信
+// 提示。
+//
+// 校验通过飞书 "Get application info" API（应用身份）：
+//   GET /open-apis/application/v6/applications/{app_id}?lang=zh_cn
+// 返回的 data.app.scopes 是个 {scope, description, ...} 数组，遍历找
+// scope 字段是否包含目标 key。
+//
+// 鸡生蛋约束：调这个 API 自身需要 admin:app.info:readonly 或
+// application:application:self_manage 中任一权限。后者免审批，是
+// 推荐路径——拿不到 app info 时（飞书返回 99991672）我们就主动私信
+// admin 提示开通 self_manage，下次重启就能自检。
+const REQUIRED_BOT_AT_SCOPE = 'im:message.group_at_msg.include_bot:readonly';
+const SELF_MANAGE_SCOPE = 'application:application:self_manage';
+function getAdminOpenId(bot) {
+    return bot.resolvedAllowedUsers.find(u => u.startsWith('ou_'));
+}
+async function dmAdmin(larkAppId, adminOpenId, content, contextTag) {
+    try {
+        await sendUserMessage(larkAppId, adminOpenId, content, 'text');
+        logger.info(`[${larkAppId}] notified admin ${adminOpenId.substring(0, 12)} about ${contextTag}`);
+    }
+    catch (err) {
+        logger.warn(`[${larkAppId}] failed to DM admin about ${contextTag}: ${err?.message ?? err}`);
     }
+}
+export async function checkRequiredScopes(larkAppId) {
+    const bot = getBot(larkAppId);
     try {
-        const info = await getChatInfo(larkAppId, chatId);
-        chatUserCountCache.set(cacheKey, { count: info.userCount, fetchedAt: Date.now() });
-        return info.userCount;
+        const tokenRes = await fetch('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ app_id: bot.config.larkAppId, app_secret: bot.config.larkAppSecret }),
+        });
+        const tokenData = await tokenRes.json();
+        if (tokenData.code !== 0) {
+            logger.debug(`[${larkAppId}] scope check skipped: tenant_access_token failed (${tokenData.msg})`);
+            return;
+        }
+        const infoRes = await fetch(`https://open.feishu.cn/open-apis/application/v6/applications/${bot.config.larkAppId}?lang=zh_cn`, { headers: { Authorization: `Bearer ${tokenData.tenant_access_token}` } });
+        const infoData = await infoRes.json();
+        // 99991672 = 应用身份缺权限。最常见就是 admin:app.info:readonly /
+        // application:application:self_manage 都没拿到，导致根本查不到自己的
+        // scope 列表。这种"鸡生蛋"情况单独提示：让 admin 开通免审批的
+        // self_manage 后下次重启就能自检了。
+        if (infoData.code === 99991672) {
+            const selfManageAuthUrl = `https://open.feishu.cn/app/${bot.config.larkAppId}/auth?q=${encodeURIComponent(SELF_MANAGE_SCOPE)}&op_from=openapi&token_type=tenant`;
+            const targetAuthUrl = `https://open.feishu.cn/app/${bot.config.larkAppId}/auth?q=${encodeURIComponent(REQUIRED_BOT_AT_SCOPE)}&op_from=openapi&token_type=tenant`;
+            logger.warn(`[${larkAppId}] scope 自检 API 被拒（99991672）：应用缺少 ${SELF_MANAGE_SCOPE}（免审批）。` +
+                `开通后下次 daemon 重启即可自动核验跨 bot @ 必需权限 ${REQUIRED_BOT_AT_SCOPE}。申请链接：${selfManageAuthUrl}`);
+            const adminOpenId = getAdminOpenId(bot);
+            if (!adminOpenId) {
+                logger.warn(`[${larkAppId}] 没有 resolved 的 admin open_id，self_manage 提示仅出现在 daemon 日志`);
+                return;
+            }
+            const dm = `⚠️ botmux 想自动核验机器人 "${bot.botName ?? larkAppId}" 是否开通了跨 bot @ 必需权限，但发现应用自身缺少一个**免审批**的辅助权限，因此查不到 scope 列表。\n\n` +
+                `**操作步骤（点链接 → 申请开通 → 重启 daemon）**：\n` +
+                `1. 开通 ${SELF_MANAGE_SCOPE}（免审批，自动通过）：\n   ${selfManageAuthUrl}\n\n` +
+                `2. 顺便确认/开通真正的目标权限 ${REQUIRED_BOT_AT_SCOPE}（"获取群组中其他机器人和用户@当前机器人的消息"，免审批，自动通过）：\n   ${targetAuthUrl}\n\n` +
+                `3. \`botmux restart\`，启动后 botmux 会自动复核，结果会再次发到这里。\n\n` +
+                `**为什么需要**：botmux 多机器人协作（A 机器人 @ B 机器人）依赖目标权限把跨 bot 事件推送过来；不开通则跨 bot @ 完全失效。`;
+            await dmAdmin(larkAppId, adminOpenId, dm, 'self_manage scope (auto-approved) missing');
+            return;
+        }
+        if (infoData.code !== 0) {
+            logger.debug(`[${larkAppId}] scope check skipped: app info failed (code=${infoData.code} msg=${infoData.msg ?? ''})`);
+            return;
+        }
+        // Lark 文档示例把 scopes 放在 data.app.scopes；为防响应结构变化，
+        // 同时兜底 data.scopes / data.application.scopes，取到的第一个非空数组为准。
+        const scopesRaw = infoData.data?.app?.scopes
+            ?? infoData.data?.application?.scopes
+            ?? infoData.data?.scopes
+            ?? [];
+        if (!Array.isArray(scopesRaw) || scopesRaw.length === 0) {
+            logger.debug(`[${larkAppId}] scope check inconclusive: scopes array empty or shape unexpected — skipping`);
+            return;
+        }
+        const grantedScopes = scopesRaw.map(s => typeof s === 'string' ? s : s?.scope).filter(Boolean);
+        if (grantedScopes.includes(REQUIRED_BOT_AT_SCOPE)) {
+            logger.info(`[${larkAppId}] required scope present: ${REQUIRED_BOT_AT_SCOPE}`);
+            return;
+        }
+        // Missing — log + DM
+        logger.error(`[${larkAppId}] 缺少必需权限 ${REQUIRED_BOT_AT_SCOPE}（"获取群组中其他机器人和用户@当前机器人的消息"）。` +
+            `跨 bot @ 消息无法到达本 bot，多 bot 协作会失效。请到飞书开放平台 → 应用 → 权限管理里申请该权限，开通后 \`botmux restart\`。`);
+        const adminOpenId = getAdminOpenId(bot);
+        if (!adminOpenId) {
+            logger.warn(`[${larkAppId}] no resolved admin open_id in allowedUsers; missing-scope warning visible only in daemon log`);
+            return;
+        }
+        const authUrl = `https://open.feishu.cn/app/${bot.config.larkAppId}/auth?q=${encodeURIComponent(REQUIRED_BOT_AT_SCOPE)}&op_from=openapi&token_type=tenant`;
+        const dm = `⚠️ botmux 启动检查发现机器人 "${bot.botName ?? larkAppId}" 缺少必需权限\n\n` +
+            `权限名：获取群组中其他机器人和用户@当前机器人的消息\n` +
+            `scope: ${REQUIRED_BOT_AT_SCOPE}\n\n` +
+            `没开通的话，跨机器人 @ 收不到事件，botmux 多机器人协作的整套场景都失效。\n\n` +
+            `**操作步骤**：\n` +
+            `1. 点链接申请权限（免审批，自动通过）：${authUrl}\n` +
+            `2. \`botmux restart\``;
+        await dmAdmin(larkAppId, adminOpenId, dm, 'required scope missing');
     }
     catch (err) {
-        logger.debug(`Failed to get chat user count for ${chatId}: ${err}`);
-        return cached?.count ?? 999; // fallback: assume multi-person
+        logger.debug(`[${larkAppId}] scope check errored: ${err?.message ?? err}`);
     }
 }
-const chatBotCountCache = new Map();
-export async function getGroupBotCount(larkAppId, chatId) {
+// ─── Group chat stats cache ───────────────────────────────────────────────
+//
+// chat.get returns both user_count (real users only) and bot_count (bots).
+// One API call, one cache — used to gate auto-replies in multi-bot/multi-user
+// groups (oncall chats often have 3rd-party oncall/form/AI-search bots).
+export const CHAT_CACHE_TTL = 5 * 60_000; // 5 minutes
+const chatStatsCache = new Map();
+export async function getGroupStats(larkAppId, chatId) {
     const cacheKey = `${larkAppId}:${chatId}`;
-    const cached = chatBotCountCache.get(cacheKey);
+    const cached = chatStatsCache.get(cacheKey);
     if (cached && Date.now() - cached.fetchedAt < CHAT_CACHE_TTL) {
-        return cached.count;
+        return { userCount: cached.userCount, botCount: cached.botCount };
     }
     try {
-        const bots = await listChatBotMembers(larkAppId, chatId);
-        chatBotCountCache.set(cacheKey, { count: bots.length, fetchedAt: Date.now() });
-        return bots.length;
+        const info = await getChatInfo(larkAppId, chatId);
+        chatStatsCache.set(cacheKey, { userCount: info.userCount, botCount: info.botCount, fetchedAt: Date.now() });
+        return info;
     }
     catch (err) {
-        logger.warn(`Failed to get chat bot count for ${chatId}: ${err}`);
-        return cached?.count ?? 999; // fallback: assume multiple bots → require @mention
+        // Soft failure — the fallback below assumes worst case (multi-user,
+        // multi-bot → require @mention). No user-visible regression, so debug.
+        logger.debug(`Failed to get chat stats for ${chatId}, using safe fallback: ${err}`);
+        if (cached)
+            return { userCount: cached.userCount, botCount: cached.botCount };
+        // Fallback: assume multi-person, multi-bot → require @mention to be safe.
+        return { userCount: 999, botCount: 999 };
     }
 }
 // ─── Cross-bot open_id mapping ──────────────────────────────────────────
@@ -143,6 +248,17 @@ export function readBotOpenIdCrossRef(dataDir, larkAppId) {
     catch { /* ignore */ }
     return map;
 }
+/** Is `senderOpenId` a registered botmux peer (from larkAppId's cross-ref)?
+ *  Used to gate chat-scope foreign-bot @mention spawning to vetted peers. */
+export function isKnownPeerBot(dataDir, larkAppId, senderOpenId) {
+    if (!senderOpenId)
+        return false;
+    for (const openId of readBotOpenIdCrossRef(dataDir, larkAppId).values()) {
+        if (openId === senderOpenId)
+            return true;
+    }
+    return false;
+}
 /** Update the per-bot cross-reference from @mention data in an event.
  *  mentionsList comes from Lark event message.mentions array. */
 export function updateBotOpenIdCrossRef(dataDir, larkAppId, mentionsList) {
@@ -202,7 +318,10 @@ export function updateBotOpenIdCrossRef(dataDir, larkAppId, mentionsList) {
 export function isBotMentioned(larkAppId, message, _senderOpenId) {
     const botOpenId = getBot(larkAppId).botOpenId;
     if (!botOpenId) {
-        logger.warn('Bot open_id unknown, cannot check @mentions');
+        // Startup race: events can arrive before probeBotOpenId() resolves the
+        // per-bot open_id. Subsequent events succeed once the probe completes,
+        // so this is not a real warning — drop to debug to keep error.log clean.
+        logger.debug(`[${larkAppId}] Bot open_id not yet known, skipping @mention check`);
         return false;
     }
     // 1. Check message.mentions array (populated for user-sent text messages)
@@ -231,27 +350,30 @@ export function isBotMentioned(larkAppId, message, _senderOpenId) {
 }
 // ─── Permission gates ────────────────────────────────────────────────────
 //
-// Two separate gates for oncall support:
+// Two gates:
 //   canTalk    — may address the bot in this chat (prompts, thread replies)
 //   canOperate — may trigger state-changing actions (card buttons, daemon
 //                slash commands like /cd /restart /close /oncall)
 //
-// Non-oncall chats: both fall back to the bot's allowedUsers. Oncall-bound
-// chats: talking is open to everyone; operating is restricted to the entry's
-// `owners` list (initial binder + anyone they later add).
+// Non-oncall chats: both fall back to the bot's allowedUsers.
+// Oncall-bound chats: talking is open to everyone in the group; operating
+// still requires allowedUsers (single source of truth — no per-chat owners).
+//
+// Oncall is a chat-level concept: `isChatOncallBoundForAnyBot` returns true
+// when ANY bot (this one or a sibling in another daemon) has the chat bound,
+// so an unbound sibling doesn't fall back to allowedUsers and reply
+// "⚠️ 无操作权限" when @-mentioned in a shared oncall workspace.
 export function canTalk(larkAppId, chatId, senderOpenId) {
-    const oncall = chatId ? findOncallChat(larkAppId, chatId) : undefined;
-    if (oncall)
+    if (chatId && isChatOncallBoundForAnyBot(chatId))
+        return true;
+    if (isKnownPeerBot(config.session.dataDir, larkAppId, senderOpenId))
         return true;
     const allowedUsers = getBot(larkAppId).resolvedAllowedUsers;
     if (allowedUsers.length === 0)
         return true;
     return !!senderOpenId && allowedUsers.includes(senderOpenId);
 }
-export function canOperate(larkAppId, chatId, senderOpenId) {
-    const oncall = chatId ? findOncallChat(larkAppId, chatId) : undefined;
-    if (oncall)
-        return !!senderOpenId && oncall.owners.includes(senderOpenId);
+export function canOperate(larkAppId, _chatId, senderOpenId) {
     const allowedUsers = getBot(larkAppId).resolvedAllowedUsers;
     if (allowedUsers.length === 0)
         return true;
@@ -274,13 +396,8 @@ export async function checkGroupMessageAccess(larkAppId, message, chatId, sender
     // No @mention — only allow if sender is the sole human in the group
     // AND this is the only bot in the chat. With multiple bots, require @mention
     // to disambiguate.
-    // Note: each daemon registers only 1 bot, so getAllBots().length is always 1.
-    // Use getGroupBotCount (API query) to get the real count of bots in the chat.
     if (isAllowed) {
-        const [userCount, botCount] = await Promise.all([
-            getGroupUserCount(larkAppId, chatId),
-            getGroupBotCount(larkAppId, chatId),
-        ]);
+        const { userCount, botCount } = await getGroupStats(larkAppId, chatId);
         logger.debug(`Group user count: ${userCount}, bot count: ${botCount}`);
         if (userCount <= 1 && botCount <= 1) {
             return 'allowed';
@@ -288,6 +405,123 @@ export async function checkGroupMessageAccess(larkAppId, message, chatId, sender
     }
     return 'ignore';
 }
+/**
+ * Best-effort plain-text extraction from a Lark message for routing-level
+ * decisions (currently: `/t` / `/topic` detection). Handles the two common
+ * shapes — `text` (`{"text": "..."}`) and `post` (zh_cn/en_us nested
+ * paragraphs of `text` / `at` nodes). Other types (image, file, sticker,
+ * interactive, …) return null so the caller falls through to the default
+ * routing path.
+ *
+ * Kept deliberately tiny rather than reusing parseEventMessage: the dispatcher
+ * runs on every inbound event and we only need a quick text peek before the
+ * permission gates / scope override; full parseEventMessage still runs once
+ * inside the chosen handler.
+ */
+export function extractMessageTextForRouting(message) {
+    if (!message?.content)
+        return null;
+    try {
+        const obj = JSON.parse(message.content);
+        // text shape: {"text":"..."}. Lark stuffs placeholder keys like "@_user_1"
+        // into obj.text; the human name only lives in message.mentions[].name. We
+        // must resolve keys → @${name} so stripLeadingMentions can strip them
+        // before parseForceTopicInvocation sees the content. Mirrors the
+        // resolveMentions logic in parseEventMessage.
+        if (typeof obj?.text === 'string') {
+            let text = obj.text;
+            const mentions = message?.mentions;
+            if (Array.isArray(mentions)) {
+                for (const m of mentions) {
+                    if (m?.key && m?.name) {
+                        text = text.split(m.key).join(`@${m.name}`);
+                    }
+                }
+            }
+            return text;
+        }
+        // post shape: {"zh_cn":{"content":[[{tag:"text",text:"..."},{tag:"at",...}]]}}
+        // Post messages keep @mentions as separate `at` nodes (not embedded in
+        // text), so the joined text-node content is already clean of placeholders.
+        const inner = obj?.zh_cn ?? obj?.en_us ?? obj;
+        if (Array.isArray(inner?.content)) {
+            const parts = [];
+            for (const para of inner.content) {
+                if (!Array.isArray(para))
+                    continue;
+                for (const node of para) {
+                    if (node?.tag === 'text' && typeof node.text === 'string') {
+                        parts.push(node.text);
+                    }
+                }
+            }
+            return parts.length > 0 ? parts.join('') : null;
+        }
+    }
+    catch { /* malformed content — skip */ }
+    return null;
+}
+/**
+ * If the inbound message starts with `/t` / `/topic` AND the routing
+ * currently lands on chat-scope, override to thread-scope anchored at
+ * the inbound message_id. This makes "force topic mode" work even when
+ * the bot already owns a chat-scope session in the chat — the dispatcher
+ * routes to handleNewTopic at a fresh anchor instead of falling into
+ * handleThreadReply on the chat-scope owner.
+ *
+ * Already-thread messages (real Lark 话题, p2p, 话题群) are left alone:
+ * the prefix is still stripped downstream by handleNewTopic.
+ */
+export function maybeApplyForceTopicOverride(routing, message, messageId) {
+    if (routing.scope !== 'chat')
+        return false;
+    const rawText = extractMessageTextForRouting(message);
+    if (!rawText)
+        return false;
+    const stripped = stripLeadingMentions(rawText.trim(), message?.mentions ?? []);
+    if (!parseForceTopicInvocation(stripped))
+        return false;
+    routing.scope = 'thread';
+    routing.anchor = messageId;
+    return true;
+}
+/** Compute the scope + anchor for an inbound message:
+ *   - root_id + thread_id     → thread-scope, anchor = root_id (real Lark 话题)
+ *   - 话题群 + no real thread → thread-scope, anchor = message_id (thread seed)
+ *   - p2p + no real thread    → thread-scope, anchor = message_id (each DM
+ *                               top-level message starts a fresh topic; a
+ *                               reply inside an existing thread carries
+ *                               root_id+thread_id and threads into its session)
+ *   - 普通群 + no real thread  → chat-scope, anchor = chat_id (entire group
+ *                               is one session)
+ *
+ *  Why we gate on thread_id (not root_id alone): Lark 客户端的引用气泡 / 快速
+ *  回复 UI 有时会给"用户视角的顶层消息"塞 root_id 但**不会**塞 thread_id。
+ *  飞书官方文档：root_id/parent_id "仅在回复消息场景会有返回值"；thread_id
+ *  "不返回说明该消息非话题消息"。所以 thread_id 才是"是否真的处于话题里"的
+ *  权威信号。只看 root_id 会把 quote-bubble 错认为话题回复，把用户从 chat-scope
+ *  会话里拽走、又起一个孤立的 thread session。
+ *  Exported for unit tests. */
+export async function decideRouting(larkAppId, message) {
+    const rootId = message.root_id;
+    const threadId = message.thread_id;
+    if (rootId && threadId)
+        return { scope: 'thread', anchor: rootId };
+    const chatType = message.chat_type ?? 'group';
+    const messageId = message.message_id;
+    const chatId = message.chat_id;
+    // 私聊：每条 top-level DM 都视为新话题 — 跟话题群同款，匹配 Lark DM 的话题
+    // 化默认行为，避免无限把 1:1 对话塞进同一个 CLI 进程里。
+    if (chatType === 'p2p') {
+        return { scope: 'thread', anchor: messageId };
+    }
+    // Group chat — fetch chat_mode (cached) to disambiguate 话题群 from 普通群.
+    const mode = await getChatMode(larkAppId, chatId);
+    if (mode === 'topic') {
+        return { scope: 'thread', anchor: messageId };
+    }
+    return { scope: 'chat', anchor: chatId };
+}
 /**
  * Create and start the Lark WSClient with event dispatching.
  * Returns the WSClient instance for lifecycle management.
@@ -318,15 +552,26 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers) {
                 if (message.mentions?.length > 0) {
                     updateBotOpenIdCrossRef(config.session.dataDir, larkAppId, message.mentions);
                 }
-                // Bot-originated messages
-                if (sender?.sender_type === 'app') {
+                const chatId = message.chat_id;
+                const chatType = (message.chat_type === 'p2p' ? 'p2p' : 'group');
+                const messageId = message.message_id;
+                // Bot-originated messages — bots historically only post inside threads
+                // (their own thread replies). With chat-scope sessions a bot can also
+                // post top-level (its first reply in a chat-scope group), so we still
+                // route them through `decideRouting` rather than gating on root_id.
+                //
+                // 飞书在跨 bot 卡片消息场景实测会把发送方标成 sender_type='bot'（不是
+                // 文档里写的 'app'），所以这里两个值都接受，否则那条路径会落到下面的
+                // user-message 通用分支，绕开 /close self-message 特判、foreign-bot
+                // chat-scope gate（isKnownPeerBot）和"Bot-to-bot @mention detected"
+                // 日志。
+                const senderType = sender?.sender_type;
+                const isBotSenderType = senderType === 'app' || senderType === 'bot';
+                if (isBotSenderType) {
                     const senderOpenId = sender.sender_id?.open_id;
-                    const rootId = message.root_id;
-                    if (!rootId)
-                        return; // ignore bot messages outside threads
                     const isSelfMessage = senderOpenId === getBot(larkAppId).botOpenId;
+                    // Self messages: only echoed `/close` commands matter.
                     if (isSelfMessage) {
-                        // Own messages: only process /close commands
                         try {
                             const body = JSON.parse(message.content ?? '{}');
                             if (body.text?.trim() !== '/close')
@@ -335,69 +580,142 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers) {
                         catch {
                             return;
                         }
-                        handlers.handleThreadReply(data, rootId, larkAppId).catch(err => logger.error(`Error handling message event: ${err}`));
+                        const ctx = await decideRouting(larkAppId, message);
+                        handlers.handleThreadReply(data, { ...ctx, chatId, messageId, chatType, larkAppId })
+                            .catch(err => logger.error(`Error handling message event: ${err}`));
                         return;
                     }
-                    // Message from another bot: check if it @mentions this bot
-                    if (isBotMentioned(larkAppId, message, undefined)) {
-                        logger.info(`Bot-to-bot @mention detected: routing to handleThreadReply`);
-                        handlers.handleThreadReply(data, rootId, larkAppId).catch(err => logger.error(`Error handling bot @mention: ${err}`));
+                    // Foreign bot: only route on @mention of us.
+                    if (!isBotMentioned(larkAppId, message, undefined))
+                        return;
+                    const ctx = await decideRouting(larkAppId, message);
+                    // Chat-scope foreign-bot @mention without an existing session: gate to
+                    // vetted botmux peers (registered in our bot-openids cross-ref). This
+                    // keeps random Lark bots from silently spawning chat-scope sessions
+                    // in 普通群/p2p, while letting Bot A → Bot B handoffs in 普通群 work
+                    // (handleThreadReply auto-create + chat-scope inheritance below).
+                    if (ctx.scope === 'chat') {
+                        const ownsSession = handlers.isSessionOwner?.(ctx.anchor, larkAppId) ?? false;
+                        if (!ownsSession && !isKnownPeerBot(config.session.dataDir, larkAppId, senderOpenId)) {
+                            return;
+                        }
                     }
+                    logger.info(`Bot-to-bot @mention detected (scope=${ctx.scope}): routing to handleThreadReply`);
+                    handlers.handleThreadReply(data, { ...ctx, chatId, messageId, chatType, larkAppId })
+                        .catch(err => logger.error(`Error handling bot @mention: ${err}`));
                     return;
                 }
-                const rootId = message.root_id;
-                const chatId = message.chat_id;
-                const chatType = message.chat_type; // 'group' or 'p2p'
-                const messageId = message.message_id;
                 const senderOpenId = sender?.sender_id?.open_id;
                 const isAllowed = canTalk(larkAppId, chatId, senderOpenId);
                 logger.debug('Received message:', message);
-                // Group new topics (no rootId): check @mention + permissions
-                if (chatType === 'group' && !rootId) {
-                    const access = await checkGroupMessageAccess(larkAppId, message, chatId, senderOpenId);
-                    logger.debug('Group message access check:', access);
-                    if (access === 'not_allowed') {
-                        replyMessage(larkAppId, messageId, JSON.stringify({ text: '⚠️ 无操作权限' }))
-                            .catch(err => logger.debug(`Failed to send permission denied: ${err}`));
-                        return;
-                    }
-                    if (access === 'ignore') {
-                        logger.debug(`Ignoring group message not addressed to bot: ${messageId}`);
-                        return;
+                // Diagnostic: record the Lark quote-bubble UI quirk where root_id
+                // appears without thread_id. decideRouting now treats this as
+                // "no thread" (chat-scope / topic / new-topic depending on context),
+                // which is the authoritative behavior. Logging it here so we can spot
+                // any future surprise in the wild.
+                if (message.root_id && !message.thread_id) {
+                    logger.info(`[routing] root_id w/o thread_id (Lark UI quirk, treating as top-level): ` +
+                        `msg=${messageId.substring(0, 12)} chat=${chatId.substring(0, 12)} ` +
+                        `type=${chatType} root=${String(message.root_id).substring(0, 12)} ` +
+                        `parent=${String(message.parent_id ?? '').substring(0, 12)}`);
+                }
+                const routing = await decideRouting(larkAppId, message);
+                // 话题群 → 普通群 (reverse conversion). Symmetric to the forward check
+                // below: when decideRouting lands on thread-scope purely because the
+                // *cached* chat_mode said 'topic' (no real thread_id on the message
+                // either — i.e. this would seed a brand-new thread), our 5-min cache
+                // may be stale from before a flip-back to 普通群. Re-verify with
+                // forceRefresh; if Lark now reports 'group', flatten to chat-scope so
+                // the bot doesn't keep wrapping every top-level reply in a fresh
+                // Lark topic via reply_in_thread.
+                //
+                // Skip when there's a real thread_id (authoritative thread signal,
+                // can't be cache-stale) or when chatType is p2p (DMs always thread).
+                // Runs BEFORE /t override so a `@bot /t …` in a now-flat 普通群 still
+                // gets the explicit topic seed it asked for.
+                if (routing.scope === 'thread' &&
+                    routing.anchor === messageId &&
+                    !message.thread_id &&
+                    chatType === 'group') {
+                    const freshMode = await getChatMode(larkAppId, chatId, { forceRefresh: true });
+                    if (freshMode === 'group') {
+                        logger.info(`[chat-mode-converted] ${chatId.substring(0, 12)} chat_mode flipped 'topic' → 'group'; ` +
+                            `rerouting msg=${messageId.substring(0, 12)} as chat-scope`);
+                        routing.scope = 'chat';
+                        routing.anchor = chatId;
                     }
                 }
-                else if (chatType === 'group' && rootId) {
-                    // Group thread replies:
-                    // - Sole bot in chat + owns session → respond without @mention
-                    // - Multiple bots in chat → always require @mention, even for session owners
-                    // - Non-owner bots → require @mention to join/take over
-                    const ownsSession = handlers.isSessionOwner?.(rootId, larkAppId) ?? false;
-                    const botCount = ownsSession ? await getGroupBotCount(larkAppId, chatId) : 0;
-                    if (ownsSession && isAllowed && botCount <= 1) {
-                        // Sole bot in chat + owns session → process without @mention
+                // /t / /topic in 普通群: flip routing to thread-scope so the bot's
+                // first reply seeds a fresh Lark thread, even if a chat-scope session
+                // is currently active in this chat.
+                if (maybeApplyForceTopicOverride(routing, message, messageId)) {
+                    logger.info(`[/t] Force-topic override: msg=${messageId.substring(0, 12)} → thread-scope, anchor=msg`);
+                }
+                let ownsSession = handlers.isSessionOwner?.(routing.anchor, larkAppId) ?? false;
+                // 普通群 → 话题群 conversion detection. Lark group admins can flip
+                // chat_mode at any time; our 30/5-min cache lags. If routing landed on
+                // chat-scope AND we own a session at this chat, the chat-scope session
+                // may be stale from before a conversion. Re-fetch chat_mode with
+                // forceRefresh to confirm. If it's now 'topic', the session is dead:
+                // sendMessage(chatId) at dispatch time would wrap each reply in a new
+                // Lark topic (the user-reported bug). Evict the stale session, then
+                // route this message as if it were a brand-new thread seed so
+                // handleNewTopic spawns a thread-scope session anchored at messageId.
+                // Gate on ownsSession to avoid an API roundtrip on every fresh inbound.
+                if (routing.scope === 'chat' && ownsSession) {
+                    const freshMode = await getChatMode(larkAppId, chatId, { forceRefresh: true });
+                    if (freshMode === 'topic') {
+                        logger.info(`[chat-mode-converted] ${chatId.substring(0, 12)} chat_mode flipped 'group' → 'topic'; ` +
+                            `evicting stale chat-scope session and rerouting msg=${messageId.substring(0, 12)} as thread seed`);
+                        try {
+                            handlers.onChatModeConverted?.(chatId, larkAppId);
+                        }
+                        catch (err) {
+                            logger.warn(`onChatModeConverted handler threw: ${err}`);
+                        }
+                        routing.scope = 'thread';
+                        routing.anchor = messageId;
+                        // ownsSession was true on the stale chatId anchor; the new anchor
+                        // (messageId) is brand-new, so no current session owns it.
+                        ownsSession = false;
                     }
-                    else {
+                }
+                // Permission gating — same shape as before, just keyed on
+                // `ownsSession` (anchor-aware) instead of "rootId presence":
+                //
+                //   ownsSession + 1v1 group → relax (no @mention required)
+                //   ownsSession + multi     → require @mention
+                //   !ownsSession (group)    → require @mention + allowlist
+                //   p2p                     → allowlist only
+                if (chatType === 'group') {
+                    let stats = null;
+                    if (ownsSession)
+                        stats = await getGroupStats(larkAppId, chatId);
+                    const relax = ownsSession && isAllowed && !!stats && stats.userCount <= 1 && stats.botCount <= 1;
+                    if (!relax) {
                         const access = await checkGroupMessageAccess(larkAppId, message, chatId, senderOpenId);
                         if (access === 'not_allowed') {
-                            logger.debug(`Ignoring thread reply from non-allowed user: ${senderOpenId}`);
+                            if (!ownsSession) {
+                                replyMessage(larkAppId, messageId, JSON.stringify({ text: '⚠️ 无操作权限' }))
+                                    .catch(err => logger.debug(`Failed to send permission denied: ${err}`));
+                            }
+                            logger.debug(`Ignoring group message from non-allowed user: ${senderOpenId}`);
                             return;
                         }
                         if (access === 'ignore') {
-                            logger.debug(`Ignoring group thread reply not addressed to bot: ${messageId}`);
+                            logger.debug(`Ignoring group message not addressed to bot: ${messageId}`);
                             return;
                         }
                     }
                 }
                 else if (!isAllowed) {
-                    // P2P thread replies and DMs: still check allowlist
-                    logger.debug(`Ignoring message from non-allowed user: ${senderOpenId}`);
+                    logger.debug(`Ignoring p2p message from non-allowed user: ${senderOpenId}`);
                     return;
                 }
-                // p2p messages without rootId -> create session directly in the DM chat
-                // group messages -> normal flow
-                const promise = !rootId
-                    ? handlers.handleNewTopic(data, chatId, messageId, chatType, larkAppId)
-                    : handlers.handleThreadReply(data, rootId, larkAppId);
+                const ctx = { chatId, messageId, chatType, larkAppId, ...routing };
+                const promise = ownsSession
+                    ? handlers.handleThreadReply(data, ctx)
+                    : handlers.handleNewTopic(data, ctx);
                 promise.catch(err => logger.error(`Error handling message event: ${err}`));
             }
             catch (err) {
@@ -409,7 +727,10 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers) {
     const wsClient = new Lark.WSClient({
         appId: larkAppId,
         appSecret: larkAppSecret,
-        loggerLevel: Lark.LoggerLevel.info,
+        // Default to warn — the SDK is chatty at info ("client ready", reconnect
+        // heartbeats, etc.) and floods pm2 error.log when stderr is the only sink.
+        // DEBUG=1 widens the level back to info for troubleshooting.
+        loggerLevel: process.env.DEBUG ? Lark.LoggerLevel.info : Lark.LoggerLevel.warn,
     });
     wsClient.start({ eventDispatcher });
     logger.info('Daemon WSClient started');