@xmanrui/dsh-im 4.29.1 → 4.30.0

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

@@ -14,20 +14,43 @@ 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');
+/**
+ * Managed-topic key: one per Feishu topic the bot auto-rooted at a message.
+ * `scope` is the conversation the topic belongs to (`group:<chat_id>` for a
+ * group, `p2p:<open_id>` for a direct chat).
+ */
+export function managedTopicKey(scope, rootMessageId) {
+  if (!scope) throw new Error('Feishu managed-topic key needs a conversation scope');
   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:')
+  return `${scope}:managed:${rootMessageId}`;
+}
+
+/** Root message id encoded in a managed-topic key, or null for any other key. */
+export function managedTopicRoot(key) {
+  if (typeof key !== 'string') return null;
+  const marker = ':managed:';
+  const at = key.lastIndexOf(marker);
+  if (at <= 0) return null;
+  return key.slice(at + marker.length) || null;
+}
+
+/**
+ * Whether a key denotes a topic-isolated conversation: either a thread the
+ * platform created (a topic group, a topic the reader opened, or the topic the
+ * bot's own reply opened) or a managed topic the bot rooted at one message.
+ */
+export function isTopicKey(key) {
+  return typeof key === 'string'
+    && (key.startsWith('group:') || key.startsWith('p2p:'))
     && (key.includes(':thread:') || key.includes(':managed:'));
 }
 
-export function conversationKey(event) {
+/**
+ * The conversation a message belongs to, without the topic dimension: the
+ * stable identity a managed-topic key is built on. Group events are identified
+ * by chat id; a direct chat is identified by its peer.
+ */
+export function conversationScope(event) {
   const chatType = event?.message?.chat_type;
   if (chatType === 'p2p') {
     const senderId = event?.sender?.sender_id?.open_id || event?.sender?.sender_id?.user_id;
@@ -36,12 +59,25 @@ export function conversationKey(event) {
   }
   const chatId = event?.message?.chat_id;
   if (!chatId) throw new Error('Feishu group event has no chat id');
+  return `group:${chatId}`;
+}
+
+export function conversationKey(event) {
+  const scope = conversationScope(event);
   // 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.
+  //
+  // Direct chats deliberately keep one key per peer: their thread_id must not
+  // split the session, or an answer typed inside a thread would no longer reach
+  // the question the bot asked in the main window. A direct chat only leaves
+  // its main session for a topic the bot itself opened (a managed topic key).
   const threadId = event?.message?.thread_id;
-  if (typeof threadId === 'string' && threadId.trim()) return `group:${chatId}:thread:${threadId}`;
-  return `group:${chatId}`;
+  if (event?.message?.chat_type !== 'p2p'
+    && typeof threadId === 'string' && threadId.trim()) {
+    return `${scope}:thread:${threadId}`;
+  }
+  return scope;
 }
 
 function parsedMessageContent(event) {

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

@@ -22,6 +22,10 @@ import {
   normalizeFeishuStepPushMode,
 } from './step-push-mode.mjs';
 import { normalizeFeishuVoiceConfig } from './voice-config.mjs';
+import {
+  isSlashPanelConfig,
+  normalizeSlashPanelConfig,
+} from './slash-command-panel.mjs';
 
 const ACTIVE_REGISTRATION_STATES = new Set([
   'starting', 'qr_ready', 'polling', 'slow_down', 'domain_switched',
@@ -97,10 +101,11 @@ function configuredBotFingerprint(config) {
     botOpenId: config.botOpenId,
     activated: config.activated,
     groupResponseMode: normalizeFeishuGroupResponseMode(config.groupResponseMode),
-    groupTopicReply: config.groupTopicReply === true,
+    mentionTopicReply: config.mentionTopicReply !== false,
     stepPush: config.stepPush === true,
     stepPushMode: normalizeFeishuStepPushMode(config.stepPushMode),
     voice: config.voice,
+    slashPanel: normalizeSlashPanelConfig(config.slashPanel),
     groupMessagePermissionGranted: config.groupMessagePermissionGranted === true,
     deletionPending: config.deletionPending === true,
     connectedAt: config.connectedAt ?? null,
@@ -605,15 +610,31 @@ export class MultiBotDshFeishuController {
     }));
   }
 
-  async updateGroupTopicReply(botId, groupTopicReply) {
+  async updateMentionTopicReply(botId, mentionTopicReply) {
+    this.#assertOpen();
+    if (typeof mentionTopicReply !== 'boolean') {
+      throw new TypeError('Invalid Feishu mention topic reply flag');
+    }
+    return this.#serializeConfig(() => this.#withBotTransition(botId, async () => {
+      const config = this.#requireBot(botId);
+      const saved = await this.#configStore.saveBot({ ...config, mentionTopicReply });
+      this.#runtimes.get(botId)?.setMentionTopicReply?.(saved.mentionTopicReply);
+      this.#touch();
+      return this.status(botId);
+    }));
+  }
+
+  async updateSlashPanel(botId, slashPanel) {
     this.#assertOpen();
-    if (typeof groupTopicReply !== 'boolean') {
-      throw new TypeError('Invalid Feishu group topic reply flag');
+    if (!isSlashPanelConfig(slashPanel)) {
+      throw new TypeError('Invalid Feishu slash panel config');
     }
     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);
+      const saved = await this.#configStore.saveBot({ ...config, slashPanel });
+      // The panel lives on Feishu's side, so the runtime re-syncs it in the
+      // background; this call only records what the panel should be.
+      this.#runtimes.get(botId)?.setSlashPanel?.(saved.slashPanel);
       this.#touch();
       return this.status(botId);
     }));
@@ -728,10 +749,11 @@ export class MultiBotDshFeishuController {
         connected,
         configured: true,
         groupResponseMode: normalizeFeishuGroupResponseMode(config.groupResponseMode),
-        groupTopicReply: config.groupTopicReply === true,
+        mentionTopicReply: config.mentionTopicReply !== false,
         stepPush: config.stepPush === true,
         stepPushMode: normalizeFeishuStepPushMode(config.stepPushMode),
         voice: normalizeFeishuVoiceConfig(config.voice),
+        slashPanel: normalizeSlashPanelConfig(config.slashPanel),
         groupMessagePermissionGranted: config.groupMessagePermissionGranted === true,
         bot: publicBot(config),
         connection,

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

@@ -4,6 +4,7 @@ import { dirname } from 'node:path';
 import { normalizeFeishuGroupResponseMode } from './group-response-mode.mjs';
 import { normalizeFeishuStepPushMode } from './step-push-mode.mjs';
 import { normalizeFeishuVoiceConfig } from './voice-config.mjs';
+import { normalizeSlashPanelConfig } from './slash-command-panel.mjs';
 
 export const LEGACY_FEISHU_SECRET_REF = 'DSH_FEISHU_APP_SECRET';
 
@@ -47,10 +48,11 @@ function normalizeBot(value, { legacy = false } = {}) {
     botOpenId: cleanString(value.botOpenId),
     activated: value.activated ?? null,
     groupResponseMode: normalizeFeishuGroupResponseMode(value.groupResponseMode),
-    groupTopicReply: value.groupTopicReply === true,
+    mentionTopicReply: value.mentionTopicReply !== false,
     stepPush: value.stepPush === true,
     stepPushMode: normalizeFeishuStepPushMode(value.stepPushMode),
     voice: normalizeFeishuVoiceConfig(value.voice),
+    slashPanel: normalizeSlashPanelConfig(value.slashPanel),
     groupMessagePermissionGranted: value.groupMessagePermissionGranted === true,
     deletionPending: value.deletionPending === true,
     connectedAt: cleanString(value.connectedAt),

package/src/channels/feishu/slash-command-panel.mjs

@@ -0,0 +1,155 @@
+/**
+ * The Feishu "/" command panel of one bot: which commands it offers and in
+ * which order.
+ *
+ * The panel is stored server-side per Feishu app and is NOT pushed by
+ * dsh/Harness, so dsh-im holds a manifest and registers it through
+ * `slash-command-registry.mjs`. This module owns that manifest plus the per-bot
+ * configuration that narrows and orders it.
+ *
+ * Reference (official):
+ *   https://open.feishu.cn/document/mcp_open_tools/agent-best-practices/agent-supports-slash-commands
+ */
+
+/**
+ * Icon keys are the documented values in the Feishu Slash Command doc.
+ */
+export const DEFAULT_SLASH_COMMAND_ICON = 'ai-agent_outlined';
+
+/**
+ * The dsh-im Feishu command manifest. Every entry's `command` is registered
+ * WITHOUT the leading slash; Feishu displays it as "/<command>" in the panel
+ * and sends "/<command>" back as text, which matches the bridge's regexes.
+ *
+ * Descriptions should stay short and match what the command actually does in
+ * bridge.mjs / the shared command modules.
+ */
+export const SLASH_COMMAND_MANIFEST = Object.freeze([
+  { command: 'menu', icon: 'skill_outlined', default: '打开功能菜单', en_us: 'Open the feature menu' },
+  { command: 'new', icon: 'ai-deepthink_outlined', default: '开启全新会话', en_us: 'Start a fresh session' },
+  { command: 'help', icon: 'promptword_outlined', default: '查看帮助', en_us: 'Show help' },
+  { command: 'status', icon: 'ai-functions_outlined', default: '查看机器人状态', en_us: 'Show bot status' },
+  { command: 'compact', icon: 'ai-block_outlined', default: '压缩当前会话上下文', en_us: 'Compact the current session' },
+  { command: 'sessionlist', icon: 'chat-ai_outlined', default: '列出会话', en_us: 'List sessions' },
+  { command: 'workspacelist', icon: 'folder_outlined', default: '列出工作区', en_us: 'List workspaces' },
+  { command: 'workspaces', icon: 'folder_outlined', default: '列出工作区', en_us: 'List workspaces' },
+  { command: 'wsl', icon: 'folder_outlined', default: '列出工作区', en_us: 'List workspaces' },
+  { command: 'ws', icon: 'folder_outlined', default: '切换工作区', en_us: 'Switch workspace' },
+  { command: 'watch', icon: 'flag_outlined', default: '关注一个会话', en_us: 'Watch a session' },
+  { command: 'unwatch', icon: 'clear_outlined', default: '取消关注会话', en_us: 'Unwatch a session' },
+  { command: 'watchlist', icon: 'flag_outlined', default: '查看关注列表', en_us: 'List watched sessions' },
+  { command: 'archived', icon: 'folder_outlined', default: '设置归档会话显隐（on/off）', en_us: 'Show or hide archived sessions (on/off)' },
+  { command: 'history', icon: 'chat-ai_outlined', default: '查看最近历史消息（仅私聊）', en_us: 'Show recent history (private chats only)' },
+  { command: 'workspace', icon: 'folder_outlined', default: '切换工作区', en_us: 'Switch workspace' },
+  { command: 'conv', icon: 'folder_outlined', default: '设置当前对话专属工作区', en_us: 'Set the workspace for this conversation' },
+  { command: 'session', icon: 'chat-ai_outlined', default: '绑定已有会话', en_us: 'Bind an existing session' },
+  { command: 'models', icon: 'ai-functions_outlined', default: '列出可用模型', en_us: 'List available models' },
+  { command: 'model', icon: 'ai-agent_outlined', default: '查看或切换当前模型', en_us: 'Show or switch the current model' },
+  { command: 'reasoninglist', icon: 'ai-deepthink_outlined', default: '列出可用推理等级', en_us: 'List available reasoning efforts' },
+  { command: 'reasoning', icon: 'ai-deepthink_outlined', default: '查看或切换推理等级', en_us: 'Show or switch the reasoning effort' },
+  { command: 'presetlist', icon: 'skill_outlined', default: '列出可用 Agent 预设', en_us: 'List available Agent Presets' },
+  { command: 'preset', icon: 'skill_outlined', default: '查看或切换 Agent 预设', en_us: 'Show or switch the Agent Preset' },
+  { command: 'stop', icon: 'clear_outlined', default: '停止当前任务', en_us: 'Stop the current task' },
+  { command: 'steer', icon: 'promptword_outlined', default: '给当前任务补充指令', en_us: 'Send additional instructions to the current task' },
+  { command: 'batch', icon: 'chat-ai_outlined', default: '开始批量输入（仅私聊）', en_us: 'Start batch input (private chats only)' },
+  { command: 'send', icon: 'chat-ai_outlined', default: '提交当前批次（仅私聊）', en_us: 'Submit the current batch (private chats only)' },
+  { command: 'cancel', icon: 'clear_outlined', default: '取消当前批次（仅私聊）', en_us: 'Cancel the current batch (private chats only)' },
+  { command: 'version', icon: 'ai-functions_outlined', default: '查看插件版本', en_us: 'Show the plugin version' },
+  { command: 'repair', icon: 'ai-functions_outlined', default: '补全飞书权限与卡片回调（仅私聊）', en_us: 'Complete Feishu permissions and card callbacks (private chats only)' },
+]);
+
+/**
+ * How the "/" panel of one bot is built.
+ *
+ * - `default` follows the shipped manifest: every command is registered, in the
+ *   manifest's own order, and nothing already registered is removed. This is
+ *   what every bot did before the panel became configurable.
+ * - `custom` follows `order`: exactly those commands, in that order. Commands
+ *   from the manifest that are not listed are removed from the app, and the
+ *   panel is rebuilt when its order no longer matches — Feishu returns the
+ *   panel in creation order, so holding a chosen order means recreating the
+ *   commands.
+ *
+ * Hidden is not the same as disabled: the panel only decides what the input box
+ * offers, and a command removed from it still works when typed.
+ */
+export const SLASH_PANEL_MODES = Object.freeze({
+  DEFAULT: 'default',
+  CUSTOM: 'custom',
+});
+
+export const DEFAULT_SLASH_PANEL_CONFIG = Object.freeze({
+  mode: SLASH_PANEL_MODES.DEFAULT,
+  order: Object.freeze([]),
+});
+
+/** A bot may pin at most this many commands; the shipped manifest is smaller. */
+export const MAX_SLASH_PANEL_COMMANDS = 100;
+
+/** Command names as the API and the stored config spell them (no leading "/"). */
+function normalizeCommandName(value) {
+  if (typeof value !== 'string') return null;
+  const name = value.trim().replace(/^\//u, '').toLowerCase();
+  return name || null;
+}
+
+function manifestHas(name) {
+  return SLASH_COMMAND_MANIFEST.some((entry) => entry.command === name);
+}
+
+/**
+ * Normalize a stored panel config, dropping anything the code cannot serve: an
+ * unknown name would put a dead command in the panel, and a duplicate would
+ * register twice. Never throws — a damaged value falls back to the default.
+ */
+export function normalizeSlashPanelConfig(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return DEFAULT_SLASH_PANEL_CONFIG;
+  }
+  if (value.mode !== SLASH_PANEL_MODES.CUSTOM) return DEFAULT_SLASH_PANEL_CONFIG;
+  const order = [];
+  const seen = new Set();
+  for (const candidate of Array.isArray(value.order) ? value.order : []) {
+    const name = normalizeCommandName(candidate);
+    if (!name || seen.has(name) || !manifestHas(name)) continue;
+    seen.add(name);
+    order.push(name);
+    if (order.length >= MAX_SLASH_PANEL_COMMANDS) break;
+  }
+  return Object.freeze({ mode: SLASH_PANEL_MODES.CUSTOM, order: Object.freeze(order) });
+}
+
+/**
+ * Strict counterpart of `normalizeSlashPanelConfig` for RPC payloads: a caller
+ * has to send exactly what it means, and damaged input is reported instead of
+ * being silently rewritten into a different panel.
+ */
+export function isSlashPanelConfig(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 2 || !keys.includes('mode') || !keys.includes('order')) return false;
+  if (!Array.isArray(value.order) || value.order.length > MAX_SLASH_PANEL_COMMANDS) return false;
+  // Following the shipped manifest carries no list of its own: the manifest is
+  // the list, and it moves with the plugin version.
+  if (value.mode === SLASH_PANEL_MODES.DEFAULT) return value.order.length === 0;
+  if (value.mode !== SLASH_PANEL_MODES.CUSTOM) return false;
+  if (new Set(value.order).size !== value.order.length) return false;
+  return value.order.every((entry) => normalizeCommandName(entry) === entry
+    && manifestHas(entry));
+}
+
+/** Whether the config asks the panel to be exactly its `order`. */
+export function isCustomSlashPanel(config) {
+  return normalizeSlashPanelConfig(config).mode === SLASH_PANEL_MODES.CUSTOM;
+}
+
+/**
+ * The manifest entries a bot should offer, in panel order. `default` returns the
+ * shipped manifest untouched, so an upgrade never reshapes an existing bot.
+ */
+export function resolveSlashPanelManifest(config, manifest = SLASH_COMMAND_MANIFEST) {
+  const normalized = normalizeSlashPanelConfig(config);
+  if (normalized.mode !== SLASH_PANEL_MODES.CUSTOM) return manifest;
+  const byName = new Map(manifest.map((entry) => [entry.command, entry]));
+  return normalized.order.map((name) => byName.get(name)).filter(Boolean);
+}

package/src/channels/feishu/slash-command-registry.mjs

@@ -16,6 +16,17 @@
  * existing "/xxx" text commands.
  */
 
+import {
+  DEFAULT_SLASH_COMMAND_ICON,
+  SLASH_COMMAND_MANIFEST,
+  isCustomSlashPanel,
+  resolveSlashPanelManifest,
+} from './slash-command-panel.mjs';
+
+// The manifest describes the panel, so it lives with the panel's configuration;
+// re-exported here because this is where callers have always imported it from.
+export { SLASH_COMMAND_MANIFEST };
+
 const SLASH_ENDPOINT = '/open-apis/application/v7/app_slash_commands';
 const MISSING_PERMISSION_CODES = new Set(['99991640', '99991672']);
 
@@ -24,50 +35,15 @@ export const SLASH_COMMAND_TENANT_SCOPES = Object.freeze([
   'application:app_slash_command:write',
 ]);
 
-// Icon keys are the documented values in the Feishu Slash Command doc.
-const DEFAULT_ICON = 'ai-agent_outlined';
+const DEFAULT_ICON = DEFAULT_SLASH_COMMAND_ICON;
 
 /**
- * The dsh-im Feishu command manifest. Every entry's `command` is registered
- * WITHOUT the leading slash; Feishu displays it as "/<command>" in the panel
- * and sends "/<command>" back as text, which matches the bridge's regexes.
- *
- * Descriptions should stay short and match what the command actually does in
- * bridge.mjs / the shared command modules.
+ * Feishu returns the panel in creation order (newest first, time to the
+ * second), so a chosen order is only reachable by creating the commands in
+ * reverse, one per second. Anything faster lands in the same second and the
+ * order degrades to the platform's tie-break.
  */
-export const SLASH_COMMAND_MANIFEST = Object.freeze([
-  { command: 'menu', icon: 'skill_outlined', default: '打开功能菜单', en_us: 'Open the feature menu' },
-  { command: 'new', icon: 'ai-deepthink_outlined', default: '开启全新会话', en_us: 'Start a fresh session' },
-  { command: 'help', icon: 'promptword_outlined', default: '查看帮助', en_us: 'Show help' },
-  { command: 'status', icon: 'ai-functions_outlined', default: '查看机器人状态', en_us: 'Show bot status' },
-  { command: 'compact', icon: 'ai-block_outlined', default: '压缩当前会话上下文', en_us: 'Compact the current session' },
-  { command: 'sessionlist', icon: 'chat-ai_outlined', default: '列出会话', en_us: 'List sessions' },
-  { command: 'workspacelist', icon: 'folder_outlined', default: '列出工作区', en_us: 'List workspaces' },
-  { command: 'workspaces', icon: 'folder_outlined', default: '列出工作区', en_us: 'List workspaces' },
-  { command: 'wsl', icon: 'folder_outlined', default: '列出工作区', en_us: 'List workspaces' },
-  { command: 'ws', icon: 'folder_outlined', default: '切换工作区', en_us: 'Switch workspace' },
-  { command: 'watch', icon: 'flag_outlined', default: '关注一个会话', en_us: 'Watch a session' },
-  { command: 'unwatch', icon: 'clear_outlined', default: '取消关注会话', en_us: 'Unwatch a session' },
-  { command: 'watchlist', icon: 'flag_outlined', default: '查看关注列表', en_us: 'List watched sessions' },
-  { command: 'archived', icon: 'folder_outlined', default: '设置归档会话显隐（on/off）', en_us: 'Show or hide archived sessions (on/off)' },
-  { command: 'history', icon: 'chat-ai_outlined', default: '查看最近历史消息（仅私聊）', en_us: 'Show recent history (private chats only)' },
-  { command: 'workspace', icon: 'folder_outlined', default: '切换工作区', en_us: 'Switch workspace' },
-  { command: 'conv', icon: 'folder_outlined', default: '设置当前对话专属工作区', en_us: 'Set the workspace for this conversation' },
-  { command: 'session', icon: 'chat-ai_outlined', default: '绑定已有会话', en_us: 'Bind an existing session' },
-  { command: 'models', icon: 'ai-functions_outlined', default: '列出可用模型', en_us: 'List available models' },
-  { command: 'model', icon: 'ai-agent_outlined', default: '查看或切换当前模型', en_us: 'Show or switch the current model' },
-  { command: 'reasoninglist', icon: 'ai-deepthink_outlined', default: '列出可用推理等级', en_us: 'List available reasoning efforts' },
-  { command: 'reasoning', icon: 'ai-deepthink_outlined', default: '查看或切换推理等级', en_us: 'Show or switch the reasoning effort' },
-  { command: 'presetlist', icon: 'skill_outlined', default: '列出可用 Agent 预设', en_us: 'List available Agent Presets' },
-  { command: 'preset', icon: 'skill_outlined', default: '查看或切换 Agent 预设', en_us: 'Show or switch the Agent Preset' },
-  { command: 'stop', icon: 'clear_outlined', default: '停止当前任务', en_us: 'Stop the current task' },
-  { command: 'steer', icon: 'promptword_outlined', default: '给当前任务补充指令', en_us: 'Send additional instructions to the current task' },
-  { command: 'batch', icon: 'chat-ai_outlined', default: '开始批量输入（仅私聊）', en_us: 'Start batch input (private chats only)' },
-  { command: 'send', icon: 'chat-ai_outlined', default: '提交当前批次（仅私聊）', en_us: 'Submit the current batch (private chats only)' },
-  { command: 'cancel', icon: 'clear_outlined', default: '取消当前批次（仅私聊）', en_us: 'Cancel the current batch (private chats only)' },
-  { command: 'version', icon: 'ai-functions_outlined', default: '查看插件版本', en_us: 'Show the plugin version' },
-  { command: 'repair', icon: 'ai-functions_outlined', default: '补全飞书权限与卡片回调（仅私聊）', en_us: 'Complete Feishu permissions and card callbacks (private chats only)' },
-]);
+export const SLASH_PANEL_CREATE_INTERVAL_MS = 1_100;
 
 // Commands that require a parameter are registered too, so the user can type
 // "/watch <session ID>" from the panel. A leading placeholder hint is not part of
@@ -276,4 +252,244 @@ export async function registerSlashCommands({
   };
 }
 
+/** Delete one registered command with an already-fetched tenant token. */
+async function deleteSlashCommandWithToken({
+  tenantAccessToken, domain, httpInstance, timeoutMs, signal, commandId,
+}) {
+  await requestJson(httpInstance, {
+    method: 'DELETE',
+    url: endpointFor(domain, `${SLASH_ENDPOINT}/${commandId}`).href,
+    headers: { authorization: `Bearer ${tenantAccessToken}` },
+    signal: requestSignal(signal, timeoutMs),
+    timeout: timeoutMs,
+  }, 'Feishu slash command delete');
+}
+
+/** Plain timer used between creates; tests inject their own. */
+function defaultWait(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}
+
+function commandNameOf(item) {
+  return typeof item?.command === 'string' && item.command ? item.command : null;
+}
+
+/**
+ * The commands of ours in panel order. Feishu returns the list newest-first
+ * with second precision, so `create_time` is the panel order and `command_id`
+ * only breaks ties inside the same second.
+ */
+function orderedOwnedNames(items, owned) {
+  return items
+    .map((item, index) => ({ item, index }))
+    .filter(({ item }) => owned.has(commandNameOf(item)))
+    .sort((a, b) => {
+      const aTime = Number(a.item.create_time);
+      const bTime = Number(b.item.create_time);
+      if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) return bTime - aTime;
+      const aId = Number(a.item.command_id);
+      const bId = Number(b.item.command_id);
+      if (Number.isFinite(aId) && Number.isFinite(bId) && aId !== bId) return bId - aId;
+      return a.index - b.index;
+    })
+    .map(({ item }) => commandNameOf(item))
+    .filter(Boolean);
+}
+
+function slashPanelDescription(entry, command) {
+  return {
+    default_value: entry.default ?? entry.en_us ?? command,
+    i18n: {
+      zh_cn: entry.default ?? command,
+      en_us: entry.en_us ?? entry.default ?? command,
+    },
+  };
+}
+
+/**
+ * Sync one bot's "/" panel with its configured manifest.
+ *
+ * `default` mode is the pre-configurable behaviour: create what is missing and
+ * leave everything else alone. `custom` mode converges the app to the
+ * configured commands *and order*:
+ *
+ *   1. read the registered commands (with command_id and create_time);
+ *   2. stop when the panel already holds exactly that order — Feishu reports the
+ *      panel in creation order, so a matching order needs no calls at all;
+ *   3. otherwise delete our commands and recreate the configured ones
+ *      newest-first, one per `intervalMs`, because the order *is* the creation
+ *      order.
+ *
+ * Commands registered outside the manifest are never deleted: dsh-im does not
+ * own them, and their position is the platform's business.
+ *
+ * @returns {{ created: Array<{command,command_id}>, deleted: string[],
+ *   existing: string[], external: string[], failed: Array<{command,error}>,
+ *   changed: boolean, superseded: boolean }} `superseded` marks a run that
+ *   stopped early because a newer panel config took over; it reports what it
+ *   managed to do, and the newer run converges the panel from there.
+ */
+export async function syncSlashCommands({
+  appId, appSecret, domain = 'feishu', httpInstance, timeoutMs = 15000,
+  signal, manifest = SLASH_COMMAND_MANIFEST, config = null,
+  intervalMs = SLASH_PANEL_CREATE_INTERVAL_MS, wait = defaultWait,
+}) {
+  // A superseded run — the runtime aborts this signal when a newer panel config
+  // arrives — must not send further create/delete calls: the newer run re-reads
+  // the panel and converges it, and letting both write would leave the older
+  // plan's commands behind. Requests already in flight are left to finish.
+  const stopped = () => signal?.aborted === true;
+  const tenantAccessToken = await fetchTenantAccessToken({
+    appId, appSecret, domain, httpInstance, timeoutMs, signal,
+  });
+  const items = await listSlashCommandsWithToken({
+    tenantAccessToken, domain, httpInstance, timeoutMs, signal,
+  });
+  const owned = new Set(manifest.map((entry) => commandNameOf(entry)).filter(Boolean));
+  const external = items
+    .map((item) => commandNameOf(item))
+    .filter((name) => name && !owned.has(name));
+  const registered = new Set(
+    items.map((item) => commandNameOf(item)).filter(Boolean),
+  );
+
+  if (!isCustomSlashPanel(config)) {
+    const created = [];
+    const failed = [];
+    for (const entry of resolveSlashPanelManifest(config, manifest)) {
+      if (stopped()) break;
+      const command = commandNameOf(entry);
+      if (!command || registered.has(command)) continue;
+      try {
+        const commandId = await createSlashCommandWithToken({
+          tenantAccessToken, domain, httpInstance, timeoutMs, signal,
+          command,
+          description: slashPanelDescription(entry, command),
+          icon: entry.icon ?? DEFAULT_ICON,
+        });
+        created.push({ command, command_id: commandId });
+        registered.add(command);
+      } catch (error) {
+        if (stopped()) break;
+        if (error?.code === '40000000' && /already exists/i.test(error?.msg ?? '')) {
+          registered.add(command);
+          continue;
+        }
+        failed.push({ command, error: error?.message ?? String(error) });
+        if (MISSING_PERMISSION_CODES.has(error?.code)
+          || /(?:lacks permission|access denied)/i.test(error?.msg ?? '')) {
+          break;
+        }
+      }
+    }
+    return {
+      created,
+      deleted: [],
+      existing: [...registered].filter(Boolean),
+      external,
+      failed,
+      changed: created.length > 0,
+      superseded: stopped(),
+    };
+  }
+
+  const current = orderedOwnedNames(items, owned);
+  const plannedEntries = resolveSlashPanelManifest(config, manifest)
+    .filter((entry) => commandNameOf(entry));
+  const plannedNames = plannedEntries.map((entry) => commandNameOf(entry));
+  if (current.length === plannedNames.length
+    && plannedNames.every((name, index) => name === current[index])) {
+    return {
+      created: [], deleted: [], existing: current, external, failed: [], changed: false,
+    };
+  }
+
+  // A newer config took over while we were reading the panel: leave the rebuild
+  // to its run rather than deleting commands for a plan nobody wants anymore.
+  if (stopped()) {
+    return {
+      created: [], deleted: [], existing: current, external, failed: [], changed: false, superseded: true,
+    };
+  }
+
+  const byName = new Map(
+    items.map((item) => [commandNameOf(item), item]).filter(([name]) => name && owned.has(name)),
+  );
+  const deleted = [];
+  const failed = [];
+  for (const name of current) {
+    if (stopped()) break;
+    const item = byName.get(name);
+    if (!item?.command_id) {
+      failed.push({ command: name, error: 'the registered command reports no command_id' });
+      continue;
+    }
+    try {
+      await deleteSlashCommandWithToken({
+        tenantAccessToken, domain, httpInstance, timeoutMs, signal, commandId: item.command_id,
+      });
+      deleted.push(name);
+    } catch (error) {
+      if (stopped()) break;
+      failed.push({ command: name, error: error?.message ?? String(error) });
+    }
+  }
+  // A superseded run stops before rebuilding: the newer run owns the panel now.
+  if (stopped()) {
+    return {
+      created: [], deleted, existing: current, external, failed, changed: deleted.length > 0, superseded: true,
+    };
+  }
+  // Deleting only part of the panel would leave it half-converged, and
+  // recreating a name that still exists is rejected as a duplicate. Stop here;
+  // the next sync (config change, reconnect, or a later start) converges.
+  if (failed.length > 0) {
+    return { created: [], deleted, existing: current, external, failed, changed: deleted.length > 0 };
+  }
+
+  const created = [];
+  for (const [index, entry] of [...plannedEntries].reverse().entries()) {
+    if (stopped()) break;
+    const command = commandNameOf(entry);
+    try {
+      if (index > 0) {
+        await wait(intervalMs, signal);
+        // The wait wakes on abort as well, so re-check instead of recording a
+        // superseded run as a failed create.
+        if (stopped()) break;
+      }
+      const commandId = await createSlashCommandWithToken({
+        tenantAccessToken, domain, httpInstance, timeoutMs, signal,
+        command,
+        description: slashPanelDescription(entry, command),
+        icon: entry.icon ?? DEFAULT_ICON,
+      });
+      created.push({ command, command_id: commandId });
+    } catch (error) {
+      if (stopped()) break;
+      failed.push({ command, error: error?.message ?? String(error) });
+      if (MISSING_PERMISSION_CODES.has(error?.code)
+        || /(?:lacks permission|access denied)/i.test(error?.msg ?? '')) {
+        break;
+      }
+    }
+  }
+
+  return {
+    created,
+    deleted,
+    existing: [],
+    external,
+    failed,
+    changed: created.length > 0 || deleted.length > 0,
+    superseded: stopped(),
+  };
+}
+
 export default registerSlashCommands;