@xmanrui/dsh-im 4.2.0 → 4.3.0

package/src/channels/feishu/bridge.mjs

@@ -686,7 +686,7 @@ export class FeishuHarnessBridge {
         ? pending.queue
         : null,
       isQuestionPending: () => this.#pendingInteractions.has(key),
-      send: (text) => this.#send(event.message.chat_id, text),
+      send: (text) => this.#send(event.message.chat_id, text, { replyTo: event.message.message_id }),
     });
     if (approvalReply) {
       const processing = approvalReply.process(async () => {
@@ -851,7 +851,7 @@ export class FeishuHarnessBridge {
     if (error?.code === 'turn-stopped') {
       await this.#removeProcessingReaction(messageId, processingReaction);
       if (error?.batchInputMessage) {
-        await this.#send(event.message.chat_id, error.batchInputMessage).catch(() => undefined);
+        await this.#send(event.message.chat_id, error.batchInputMessage, { replyTo: event.message.message_id }).catch(() => undefined);
       }
       return;
     }
@@ -940,7 +940,7 @@ export class FeishuHarnessBridge {
       ]);
     }
     for (const reply of result?.messages ?? [result?.message]) {
-      if (reply) await this.#send(event.message.chat_id, reply);
+      if (reply) await this.#send(event.message.chat_id, reply, { replyTo: event.message.message_id });
     }
     this.#status.lastError = null;
   }
@@ -964,7 +964,7 @@ export class FeishuHarnessBridge {
     // accept() 侧已用 nonEmptyString(content) 判定，两侧保持一致。
     const commandText = !hasImages && !hasFiles && text ? text.trim() : null;
     if (!text && !hasImages && !hasFiles) {
-      await this.#send(event.message.chat_id, t('目前支持文字、图片和文件消息。'));
+      await this.#send(event.message.chat_id, t('目前支持文字、图片和文件消息。'), { replyTo: event.message.message_id });
       return;
     }
 
@@ -973,11 +973,11 @@ export class FeishuHarnessBridge {
       return;
     }
     if (commandText === '/help') {
-      await this.#send(event.message.chat_id, menuHelpText());
+      await this.#send(event.message.chat_id, menuHelpText(), { replyTo: event.message.message_id });
       return;
     }
     if (MENU_COMMAND.test(commandText)) {
-      await this.#sendMenuCard(key, event.message.chat_id);
+      await this.#sendMenuCard(key, event.message.chat_id, { replyTo: event.message.message_id });
       return;
     }
     if (commandText === '/new') {
@@ -985,53 +985,54 @@ export class FeishuHarnessBridge {
         await this.#send(
           event.message.chat_id,
           t('当前任务仍在运行，请先停止任务或等待任务完成后再开启新会话。'),
+          { replyTo: event.message.message_id },
         );
         return;
       }
       await this.#state.clearSession(key);
-      await this.#send(event.message.chat_id, t('已开启全新 Harness 会话。'));
-      await this.#sendMenuCard(key, event.message.chat_id);
+      await this.#send(event.message.chat_id, t('已开启全新 Harness 会话。'), { replyTo: event.message.message_id });
+      await this.#sendMenuCard(key, event.message.chat_id, { replyTo: event.message.message_id });
       return;
     }
     if (commandText === '/status') {
-      await this.#showStatusText(key, event.message.chat_id);
+      await this.#showStatusText(key, event.message.chat_id, event.message.message_id);
       return;
     }
     if (commandText === '/compact') {
       const compactCommand = await runCompactCommand(commandText, this.#harness, this.#state, key, { signal: this.#signal });
       if (compactCommand) {
-        await this.#send(event.message.chat_id, compactCommand.message);
+        await this.#send(event.message.chat_id, compactCommand.message, { replyTo: event.message.message_id });
       }
       return;
     }
     if (SESSION_LIST_PREFIX.test(commandText)) {
       const selector = commandText.replace(/^\/(?:sessionlist|sessions)/i, '').trim() || null;
-      await this.#showSessions({ chatId: event.message.chat_id, key }, selector, 0);
+      await this.#showSessions({ chatId: event.message.chat_id, key, replyTo: event.message.message_id }, selector, 0);
       return;
     }
     if (WORKSPACE_LIST_COMMAND.test(commandText)) {
-      await this.#showWorkspaces({ chatId: event.message.chat_id, key });
+      await this.#showWorkspaces({ chatId: event.message.chat_id, key, replyTo: event.message.message_id });
       return;
     }
     if (WATCH_COMMAND.test(commandText)) {
       const target = (WATCH_COMMAND.exec(commandText)?.[1] ?? '').trim() || null;
-      await this.#runWatch(key, event.message.chat_id, target);
+      await this.#runWatch(key, event.message.chat_id, target, { replyTo: event.message.message_id });
       return;
     }
     if (UNWATCH_COMMAND.test(commandText)) {
       const target = (UNWATCH_COMMAND.exec(commandText)?.[1] ?? '').trim() || null;
-      await this.#runUnwatch(key, event.message.chat_id, target);
+      await this.#runUnwatch(key, event.message.chat_id, target, { replyTo: event.message.message_id });
       return;
     }
     if (WATCHLIST_COMMAND.test(commandText)) {
-      await this.#showWatchList(key, event.message.chat_id);
+      await this.#showWatchList(key, event.message.chat_id, { replyTo: event.message.message_id });
       return;
     }
     if (ARCHIVED_COMMAND.test(commandText)) {
       const match = ARCHIVED_COMMAND.exec(commandText);
       const value = match[1]?.toLowerCase();
       if (value !== 'on' && value !== 'off') {
-        await this.#send(event.message.chat_id, t('用法：/archived on（包含归档会话）或 /archived off（隐藏归档会话）'));
+        await this.#send(event.message.chat_id, t('用法：/archived on（包含归档会话）或 /archived off（隐藏归档会话）'), { replyTo: event.message.message_id });
         return;
       }
       if (typeof this.#state?.setIncludeArchivedSessions === 'function') {
@@ -1040,6 +1041,7 @@ export class FeishuHarnessBridge {
       await this.#send(
         event.message.chat_id,
         value === 'on' ? t('已开启：会话列表包含归档会话。') : t('已关闭：会话列表隐藏归档会话。'),
+        { replyTo: event.message.message_id },
       );
       return;
     }
@@ -1059,7 +1061,7 @@ export class FeishuHarnessBridge {
       : await runWorkspaceCommand(text, this.#harness, key);
     if (workspaceCommand) {
       for (const reply of workspaceCommand.messages ?? [workspaceCommand.message]) {
-        await this.#send(event.message.chat_id, reply);
+        await this.#send(event.message.chat_id, reply, { replyTo: event.message.message_id });
       }
       return;
     }
@@ -1073,7 +1075,7 @@ export class FeishuHarnessBridge {
           { signal: this.#signal },
         );
     if (compactCommand) {
-      await this.#send(event.message.chat_id, compactCommand.message);
+      await this.#send(event.message.chat_id, compactCommand.message, { replyTo: event.message.message_id });
       return;
     }
 
@@ -2030,7 +2032,7 @@ export class FeishuHarnessBridge {
   }
 
   async #showSessions(
-    { chatId, key },
+    { chatId, key, replyTo = null },
     selector,
     page = 0,
     { updateMessageId = null } = {},
@@ -2039,14 +2041,14 @@ export class FeishuHarnessBridge {
       const signal = this.#cardDataSignal();
       const resolved = await resolveSessionListWorkspace(selector ?? '', this.#harness, { signal });
       if (resolved.error) {
-        await this.#send(chatId, resolved.error);
+        await this.#send(chatId, resolved.error, { replyTo });
         return;
       }
       const listed = await this.#harness.listWorkspaceSessions(resolved.workspace, { signal });
       const sessions = this.#visibleSessions(Array.isArray(listed?.sessions) ? listed.sessions : []);
       const workspace = listed?.workspace ?? resolved.workspace;
       if (sessions.length === 0) {
-        await this.#send(chatId, t('工作区：{workspace}\n该工作区暂无会话。', { workspace }));
+        await this.#send(chatId, t('工作区：{workspace}\n该工作区暂无会话。', { workspace }), { replyTo });
         return;
       }
       const pageCount = Math.ceil(sessions.length / MENU_PAGE_SIZE);
@@ -2065,6 +2067,7 @@ export class FeishuHarnessBridge {
         {
           key,
           updateMessageId,
+          replyTo,
           // Keep the canonical selector result for later page callbacks. The
           // list response's workspace is display data and is not authoritative.
           sessionWorkspace: resolved.workspace,
@@ -2076,7 +2079,7 @@ export class FeishuHarnessBridge {
     }
   }
 
-  async #showWorkspaces({ chatId, key }, { updateMessageId = null } = {}) {
+  async #showWorkspaces({ chatId, key, replyTo = null }, { updateMessageId = null } = {}) {
     try {
       const { current, paths } = await workspacePathSnapshot(
         this.#harness,
@@ -2086,7 +2089,7 @@ export class FeishuHarnessBridge {
       await this.#sendCard(
         chatId,
         workspaceListCard(paths, current),
-        { key, updateMessageId },
+        { key, updateMessageId, replyTo },
       );
     } catch (error) {
       await this.#sendFailure(chatId, error, { logLabel: 'workspace list' });
@@ -2144,6 +2147,7 @@ export class FeishuHarnessBridge {
 
   async #sendCard(chatId, cardJson, options = {}) {
     const updateMessageId = nonEmptyString(options.updateMessageId);
+    const replyTo = nonEmptyString(options.replyTo);
 
     if (updateMessageId) {
       try {
@@ -2161,6 +2165,28 @@ export class FeishuHarnessBridge {
       }
     }
 
+    // A brand-new card triggered by an inbound message is delivered as a
+    // threaded reply so it lands inside the same Feishu topic. Falls back to
+    // a plain chat message when the referenced message is gone.
+    const content = cardJson;
+    if (replyTo) {
+      try {
+        const response = await this.#client.im.v1.message.reply({
+          path: { message_id: replyTo },
+          data: { msg_type: 'interactive', content },
+        });
+        if (response?.code && response.code !== 0) {
+          throw new Error(`Feishu card reply failed: ${response.msg || response.code}`);
+        }
+        const repliedMessageId = nonEmptyString(response?.data?.message_id);
+        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));
+      }
+    }
     const response = await this.#client.im.v1.message.create({
       params: { receive_id_type: 'chat_id' },
       data: { receive_id: chatId, msg_type: 'interactive', content: cardJson },
@@ -2173,7 +2199,7 @@ export class FeishuHarnessBridge {
     return messageId;
   }
 
-  async #sendMenuCard(key, chatId, { updateMessageId = null } = {}) {
+  async #sendMenuCard(key, chatId, { updateMessageId = null, replyTo = null } = {}) {
     let currentSessionId = null;
     let directSessionTitle = null;
     try {
@@ -2268,7 +2294,7 @@ export class FeishuHarnessBridge {
         currentSession: currentSessionId ? { id: currentSessionId, title: currentSessionTitle } : null,
         sessions, archiveVisible, presetCatalog, modelCatalog,
       }),
-      { key, updateMessageId },
+      { key, updateMessageId, replyTo },
     );
   }
 
@@ -2350,7 +2376,7 @@ export class FeishuHarnessBridge {
   /**
    * Gather system status and show the status card.
    */
-  async #showStatusText(key, chatId) {
+  async #showStatusText(key, chatId, replyTo = null) {
     try {
       await this.#harness.ensureRunning({ signal: this.#signal });
       const lines = [t('连接正常')];
@@ -2369,7 +2395,7 @@ export class FeishuHarnessBridge {
             : (settings.agentPreset || t('跟随默认')),
         }));
       }
-      await this.#send(chatId, lines.join('\n'));
+      await this.#send(chatId, lines.join('\n'), { replyTo });
     } catch (error) {
       await this.#sendFailure(chatId, error, { logLabel: 'status text' });
     }
@@ -2787,11 +2813,12 @@ export class FeishuHarnessBridge {
     notify = true,
     validatedTarget = null,
     workspaceHint = null,
+    replyTo = null,
   } = {}) {
     const watchRequestedAt = Date.now();
     const reply = async (message) => {
       if (!notify) return;
-      await this.#send(chatId, message).catch((error) => {
+      await this.#send(chatId, message, { replyTo }).catch((error) => {
         this.#logger.warn?.('[dsh-feishu] watch notification failed:', error.message);
       });
     };
@@ -2854,10 +2881,10 @@ export class FeishuHarnessBridge {
     return { ok: true, changed: !existingEntry, entry: this.#state.watchEntry?.(key, resolved.sessionId) };
   }
 
-  async #runUnwatch(key, chatId, target, { notify = true } = {}) {
+  async #runUnwatch(key, chatId, target, { notify = true, replyTo = null } = {}) {
     const reply = async (message) => {
       if (!notify) return;
-      await this.#send(chatId, message).catch((error) => {
+      await this.#send(chatId, message, { replyTo }).catch((error) => {
         this.#logger.warn?.('[dsh-feishu] unwatch notification failed:', error.message);
       });
     };
@@ -2883,7 +2910,7 @@ export class FeishuHarnessBridge {
     return { ok: true, changed: true, entry };
   }
 
-  async #showWatchList(key, chatId, { updateMessageId = null } = {}) {
+  async #showWatchList(key, chatId, { updateMessageId = null, replyTo = null } = {}) {
     const entries = this.#state.watchEntries?.(key) ?? [];
     // 收集可选会话（用于「添加关注」多选下拉）；失败则传空数组 → 只渲染移除/列表。
     let availableSessions = [];
@@ -2913,6 +2940,7 @@ export class FeishuHarnessBridge {
       {
         key,
         updateMessageId,
+        replyTo,
         sessionWorkspace: currentWorkspace,
       },
     );
@@ -3068,17 +3096,18 @@ export class FeishuHarnessBridge {
         actor: senderOpenId(event),
         chatId: event.message.chat_id,
         requiresMention: event.message.chat_type !== 'p2p',
+        replyToMessageId: event.message.message_id,
       }),
       onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
       files,
     };
   }
 
-  async #sendAnswerText(chatId, answer, { deliveryId, presentation }) {
+  async #sendAnswerText(chatId, answer, { deliveryId, presentation, replyTo = null }) {
     const providerMessageIds = [];
     for (const chunk of splitText(answer)) {
       this.#signal?.throwIfAborted();
-      const messageId = await this.#send(chatId, chunk);
+      const messageId = await this.#send(chatId, chunk, { replyTo });
       if (messageId) providerMessageIds.push(messageId);
     }
     return createDeliveryReceipt({
@@ -3182,6 +3211,7 @@ export class FeishuHarnessBridge {
           {
             deliveryId: messageId,
             presentation: 'feishu-text',
+            replyTo: messageId,
           },
         );
       } catch (error) {
@@ -3252,6 +3282,7 @@ export class FeishuHarnessBridge {
             {
               deliveryId: messageId,
               presentation: 'feishu-text-fallback',
+              replyTo: messageId,
             },
           );
         } catch (fallbackError) {
@@ -3302,6 +3333,7 @@ export class FeishuHarnessBridge {
           {
             deliveryId: messageId,
             presentation: 'feishu-text-fallback',
+            replyTo: messageId,
           },
         );
       } catch (fallbackError) {
@@ -3368,11 +3400,11 @@ export class FeishuHarnessBridge {
     const pending = this.#pendingInteractions.get(key);
     if (!pending || pending !== expected || pending.submitting) {
       if (this.#isResolvedQuestionReply(event, key)) {
-        await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT()).catch(() => undefined);
+        await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT(), { replyTo: event.message.message_id }).catch(() => undefined);
         return;
       }
       if (claimed && (!pending || pending !== expected)) {
-        await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT());
+        await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT(), { replyTo: event.message.message_id });
         return;
       }
       return this.#enqueueMessage(event, messageId, key, processingReaction, {
@@ -3430,7 +3462,7 @@ export class FeishuHarnessBridge {
       if (error?.code === 'interaction-not-pending') {
         this.#rememberResolvedInteraction(key, pending);
         this.#clearPendingInteraction(key, pending.interactionId);
-        await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT()).catch(() => undefined);
+        await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT(), { replyTo: event.message.message_id }).catch(() => undefined);
         return;
       }
       pending.submitting = false;
@@ -3448,12 +3480,13 @@ export class FeishuHarnessBridge {
     actor,
     chatId,
     requiresMention,
+    replyToMessageId,
   }) {
     if (await this.#approvals.handleRequested(interaction, {
       key,
       actor,
       requiresMention,
-      send: (text) => this.#send(chatId, text),
+      send: (text) => this.#send(chatId, text, { replyTo: replyToMessageId }),
     })) return;
 
     // Approval requests return above; the existing question state machine stays unchanged.
@@ -3484,6 +3517,7 @@ export class FeishuHarnessBridge {
       await this.#send(
         chatId,
         t('检测到这个 Session 中遗留的待回答问题，已安全取消并继续处理你刚才的消息。'),
+        { replyTo: replyToMessageId },
       ).catch(() => undefined);
       return;
     }
@@ -3519,6 +3553,7 @@ export class FeishuHarnessBridge {
       answers: [],
       index: 0,
       chatId,
+      replyToMessageId,
       queue: null,
       claimedReplyMessageId: null,
       submitting: false,
@@ -3553,6 +3588,9 @@ export class FeishuHarnessBridge {
         pending.questions.length,
         { requiresMention: pending.requiresMention },
       ),
+      // Reply to the message that started the turn so the question lands in
+      // the same Feishu thread/topic instead of the group's default area.
+      { replyTo: pending.replyToMessageId },
     );
     if (messageId) {
       pending.questionMessageIds.add(messageId);
@@ -3585,7 +3623,7 @@ export class FeishuHarnessBridge {
     await this.#state.markSeen(messageId);
     this.#status.lastMessageAt = new Date().toISOString();
     this.#status.messagesReceived += 1;
-    await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT()).catch(() => undefined);
+    await this.#send(event.message.chat_id, INTERACTION_RESOLVED_TEXT(), { replyTo: event.message.message_id }).catch(() => undefined);
   }
 
   #takePendingInteraction(key, interactionId) {
@@ -3651,13 +3689,33 @@ export class FeishuHarnessBridge {
     else processingReaction.success();
   }
 
-  async #send(chatId, text) {
+  async #send(chatId, text, { replyTo } = {}) {
+    const content = JSON.stringify({ text });
+    if (replyTo) {
+      try {
+        const response = await this.#client.im.v1.message.reply({
+          path: { message_id: replyTo },
+          data: { msg_type: 'text', content },
+        });
+        if (response?.code && response.code !== 0) {
+          throw new Error(`Feishu reply failed: ${response.msg || response.code}`);
+        }
+        return nonEmptyString(response?.data?.message_id);
+      } catch (error) {
+        // The referenced message may be gone (recalled/deleted); keep the
+        // delivery promise by falling back to a plain chat message.
+        this.#logger.warn?.(
+          '[dsh-feishu] threaded reply failed; falling back to a plain message:',
+          error?.message ?? String(error),
+        );
+      }
+    }
     const response = await this.#client.im.v1.message.create({
       params: { receive_id_type: 'chat_id' },
       data: {
         receive_id: chatId,
         msg_type: 'text',
-        content: JSON.stringify({ text }),
+        content,
       },
     });
     if (response?.code && response.code !== 0) {

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

@@ -16,6 +16,11 @@ export function conversationKey(event) {
   }
   const chatId = event?.message?.chat_id;
   if (!chatId) throw new Error('Feishu group event has no chat id');
+  // Topic groups: every message belongs to a thread, so key the session per
+  // thread to keep each topic's Harness conversation isolated. Regular group
+  // chats carry no thread_id and keep the single shared `group:<chat_id>` key.
+  const threadId = event?.message?.thread_id;
+  if (typeof threadId === 'string' && threadId.trim()) return `group:${chatId}:thread:${threadId}`;
   return `group:${chatId}`;
 }
 

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

@@ -1,4 +1,4 @@
-import { QQBot, typingIndicator } from '@tencent-connect/qqbot-nodejs';
+import { QQBot, contentSanitizer, typingIndicator } from '@tencent-connect/qqbot-nodejs';
 
 import {
   connectionTestTarget,
@@ -171,6 +171,10 @@ export class QqRuntime {
       replyTimeoutMs: this.#replyTimeoutMs,
       signal: controller.signal,
     });
+    // QQ delivers emoji/face messages as opaque `<faceType=..,faceId="..",ext="..">`
+    // tags. Parse them into readable text so the Harness sees what the sender
+    // actually meant instead of an unusable markup fragment.
+    bot.use(contentSanitizer({ parseFaceTags: true }));
     bot.use?.(this.#typingMiddleware({
       keepAlive: true,
       predicate: (ctx) => this.#config.ownerUserOpenid === '*'

package/src/channels/shared/context-enhancement.mjs

@@ -4,6 +4,12 @@ export const CONTEXT_ENHANCEMENT_FIELDS = Object.freeze([
 ]);
 
 export const CONTEXT_ENHANCEMENT_GUIDANCE_MAX_LENGTH = 8_000;
+export const CONTEXT_GROUP_GUIDANCE_EXAMPLE = `仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
+当前消息来自群聊，请使用严肃、克制、简洁的表达方式。`;
+export const CONTEXT_DIRECT_GUIDANCE_EXAMPLE = `仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
+当前消息来自私聊，可以使用更轻松、幽默、详细的表达方式。`;
+
+// Kept for integrations that imported the original combined example.
 export const CONTEXT_GUIDANCE_EXAMPLE = `仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
 conversationType是群聊时回复严肃一点，conversationType是私聊时回复一定要幽默搞笑，像周星驰的电影一样搞笑`;
 
@@ -11,13 +17,21 @@ conversationType是群聊时回复严肃一点，conversationType是私聊时回
 export const DEFAULT_CONTEXT_GUIDANCE = CONTEXT_GUIDANCE_EXAMPLE;
 
 export const DEFAULT_CONTEXT_ENHANCEMENT_CONFIG = Object.freeze({
-  groupEnabled: false,
-  directEnabled: false,
-  fields: Object.freeze(['senderId']),
-  guidance: '',
+  group: Object.freeze({
+    enabled: false,
+    fields: Object.freeze(['senderId']),
+    guidance: '',
+  }),
+  direct: Object.freeze({
+    enabled: false,
+    fields: Object.freeze(['senderId']),
+    guidance: '',
+  }),
 });
 
-const CONFIG_KEYS = ['groupEnabled', 'directEnabled', 'fields', 'guidance'];
+const CONFIG_KEYS = ['group', 'direct'];
+const SCOPE_KEYS = ['enabled', 'fields', 'guidance'];
+const LEGACY_CONFIG_KEYS = ['groupEnabled', 'directEnabled', 'fields', 'guidance'];
 const CHANNELS = new Set([
   'wecom', 'weixin', 'feishu', 'dingtalk', 'qq',
   'slack', 'telegram', 'discord', 'whatsapp',
@@ -31,16 +45,19 @@ function invalidConfig(message) {
   return error;
 }
 
-/** Validate the complete atomic save, preserving explicit empty selections/text. */
-export function validateContextEnhancementConfig(input) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)
-    || ![Object.prototype, null].includes(Object.getPrototypeOf(input))
-    || Reflect.ownKeys(input).length !== CONFIG_KEYS.length
-    || !CONFIG_KEYS.every((key) => Object.hasOwn(input, key))) {
+function hasExactKeys(input, keys) {
+  return input && typeof input === 'object' && !Array.isArray(input)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(input))
+    && Reflect.ownKeys(input).length === keys.length
+    && keys.every((key) => Object.hasOwn(input, key));
+}
+
+function validateContextEnhancementScope(input) {
+  if (!hasExactKeys(input, SCOPE_KEYS)) {
     throw invalidConfig('请提交完整的上下文增强设置。');
   }
-  const { groupEnabled, directEnabled, fields, guidance } = input;
-  if (typeof groupEnabled !== 'boolean' || typeof directEnabled !== 'boolean') {
+  const { enabled, fields, guidance } = input;
+  if (typeof enabled !== 'boolean') {
     throw invalidConfig('群聊和私聊开关必须是布尔值。');
   }
   if (!Array.isArray(fields) || ![...fields].every((field) => CONTEXT_ENHANCEMENT_FIELDS.includes(field))) {
@@ -50,19 +67,51 @@ export function validateContextEnhancementConfig(input) {
     throw invalidConfig(`增强提示词不得超过 ${CONTEXT_ENHANCEMENT_GUIDANCE_MAX_LENGTH} 个字符。`);
   }
   return Object.freeze({
-    groupEnabled,
-    directEnabled,
+    enabled,
     fields: Object.freeze(CONTEXT_ENHANCEMENT_FIELDS.filter((field) => fields.includes(field))),
     guidance: guidance.trim() ? guidance : '',
   });
 }
 
+/** Validate the complete atomic save, preserving explicit empty selections/text. */
+export function validateContextEnhancementConfig(input) {
+  if (!hasExactKeys(input, CONFIG_KEYS)) {
+    throw invalidConfig('请提交完整的上下文增强设置。');
+  }
+  return Object.freeze({
+    group: validateContextEnhancementScope(input.group),
+    direct: validateContextEnhancementScope(input.direct),
+  });
+}
+
+function migrateLegacyContextEnhancementConfig(input) {
+  if (!hasExactKeys(input, LEGACY_CONFIG_KEYS)) {
+    throw invalidConfig('请提交完整的上下文增强设置。');
+  }
+  return validateContextEnhancementConfig({
+    group: {
+      enabled: input.groupEnabled,
+      fields: input.fields,
+      guidance: input.guidance,
+    },
+    direct: {
+      enabled: input.directEnabled,
+      fields: input.fields,
+      guidance: input.guidance,
+    },
+  });
+}
+
 /** Missing or damaged enhancement settings must never break an existing bot. */
 export function normalizeContextEnhancementConfig(input) {
   try {
     return validateContextEnhancementConfig(input);
   } catch {
-    return DEFAULT_CONTEXT_ENHANCEMENT_CONFIG;
+    try {
+      return migrateLegacyContextEnhancementConfig(input);
+    } catch {
+      return DEFAULT_CONTEXT_ENHANCEMENT_CONFIG;
+    }
   }
 }
 
@@ -71,11 +120,15 @@ export function captureContextEnhancement(provider, conversationType) {
   if (conversationType !== 'group' && conversationType !== 'direct') return null;
   try {
     const settings = provider?.getSettings?.();
-    const enabledKey = conversationType === 'group' ? 'groupEnabled' : 'directEnabled';
-    if (settings?.[enabledKey] !== true) return null;
+    const legacyEnabledKey = conversationType === 'group' ? 'groupEnabled' : 'directEnabled';
+    const enabled = Object.hasOwn(settings ?? {}, conversationType)
+      ? settings?.[conversationType]?.enabled
+      : settings?.[legacyEnabledKey];
+    if (enabled !== true) return null;
     const config = normalizeContextEnhancementConfig(settings);
-    if (config[enabledKey] !== true) return null;
-    return Object.freeze({ config, botId: provider.botId, conversationType });
+    const scope = config[conversationType];
+    if (scope.enabled !== true) return null;
+    return Object.freeze({ config: scope, botId: provider.botId, conversationType });
   } catch {
     return null;
   }

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

@@ -105,19 +105,23 @@ export const COMMANDS_MENU_BUTTON = Object.freeze({ type: 'commands' });
 export class TelegramApi {
   #token;
   #fetch;
+  #FormDataImpl;
   #baseUrl;
   #fileUploadTimeoutMs;
 
   constructor({
     token,
     fetchImpl = fetch,
+    FormDataImpl = globalThis.FormData,
     baseUrl = DEFAULT_BASE_URL,
     fileUploadTimeoutMs = DEFAULT_FILE_UPLOAD_TIMEOUT_MS,
   }) {
     if (!validTelegramToken(token)) throw new TypeError('Telegram Bot Token is invalid');
     if (typeof fetchImpl !== 'function') throw new TypeError('TelegramApi requires fetch');
+    if (typeof FormDataImpl !== 'function') throw new TypeError('TelegramApi requires FormData');
     this.#token = token.trim();
     this.#fetch = fetchImpl;
+    this.#FormDataImpl = FormDataImpl;
     this.#baseUrl = new URL(baseUrl);
     this.#fileUploadTimeoutMs = positiveTimeout(fileUploadTimeoutMs, 'fileUploadTimeoutMs');
   }
@@ -273,7 +277,7 @@ export class TelegramApi {
       || !Buffer.isBuffer(file.bytes)) {
       throw new TypeError(`A Telegram ${mediaLabel} is required`);
     }
-    const payload = new FormData();
+    const payload = new this.#FormDataImpl();
     payload.append('chat_id', String(chatId));
     payload.append(
       fieldName,