@xmanrui/dsh-im 4.29.1 → 4.31.0

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

@@ -7,9 +7,10 @@ import { normalizeFeishuGroupResponseMode } from './group-response-mode.mjs';
 import { normalizeFeishuStepPushMode } from './step-push-mode.mjs';
 import { createVoice } from './voice.mjs';
 import {
-  registerSlashCommands,
+  syncSlashCommands,
   SLASH_COMMAND_MANIFEST,
 } from './slash-command-registry.mjs';
+import { normalizeSlashPanelConfig } from './slash-command-panel.mjs';
 import {
   connectionTestTargetUnavailable,
   sendRememberedConnectionTest,
@@ -95,6 +96,7 @@ export function createBridgeStatus({ allowedSenderCount = 1 } = {}) {
     slashCommandsRegistered: 0,
     slashCommandsExisting: 0,
     slashCommandsFailed: 0,
+    slashCommandsRemoved: 0,
     slashCommandsError: null,
   };
 }
@@ -113,7 +115,7 @@ export class FeishuRuntime {
   #domain;
   #botOpenId;
   #groupResponseMode;
-  #groupTopicReply;
+  #mentionTopicReply;
   #stepPush;
   #stepPushMode;
   #voice = null;
@@ -139,6 +141,19 @@ export class FeishuRuntime {
   #pendingCardActionProbes = new Map();
   #status;
   #slashCommands = true;
+  /** Which commands the "/" panel should offer, and in which order. */
+  #slashPanel = null;
+  /** HTTP instance kept for panel re-syncs after startup. */
+  #slashHttpInstance = null;
+  /**
+   * Bumped on every panel change: a sync started for an older config stops at
+   * its next checkpoint instead of racing the newer one (last writer wins).
+   */
+  #slashSyncEpoch = 0;
+  /** Cancels the panel sync in flight; it stops before its next request. */
+  #slashSyncCancel = null;
+  /** Panel syncs run one after another, so two plans never interleave. */
+  #slashSyncQueue = Promise.resolve();
 
   constructor({
     lark,
@@ -148,7 +163,7 @@ export class FeishuRuntime {
     domain = 'feishu',
     botOpenId,
     groupResponseMode,
-    groupTopicReply = false,
+    mentionTopicReply = true,
     stepPush = false,
     stepPushMode = 'post',
     voice = null,
@@ -164,6 +179,7 @@ export class FeishuRuntime {
     connectTimeoutMs = 15000,
     requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
     slashCommands = true,
+    slashPanel = null,
     wsAgent,
     logger = console,
   }) {
@@ -188,7 +204,7 @@ export class FeishuRuntime {
     this.#domain = domain;
     this.#botOpenId = nonEmptyString(botOpenId);
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(groupResponseMode);
-    this.#groupTopicReply = groupTopicReply === true;
+    this.#mentionTopicReply = mentionTopicReply !== false;
     this.#stepPush = stepPush === true;
     this.#stepPushMode = normalizeFeishuStepPushMode(stepPushMode);
     // voice 为 { config, secret } 来源;凭据缺失时 createVoice 返回禁用对象,
@@ -209,6 +225,7 @@ export class FeishuRuntime {
     this.#connectTimeoutMs = connectTimeoutMs;
     this.#requestTimeoutMs = requestTimeoutMs;
     this.#slashCommands = Boolean(slashCommands);
+    this.#slashPanel = normalizeSlashPanelConfig(slashPanel);
     this.#wsAgent = wsAgent;
     this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'feishu', logger });
     this.#status = createBridgeStatus({ allowedSenderCount: normalizedOwners.length });
@@ -223,9 +240,9 @@ export class FeishuRuntime {
     this.#bridge?.setGroupResponseMode(this.#groupResponseMode);
   }
 
-  setGroupTopicReply(value) {
-    this.#groupTopicReply = value === true;
-    this.#bridge?.setGroupTopicReply(this.#groupTopicReply);
+  setMentionTopicReply(value) {
+    this.#mentionTopicReply = value !== false;
+    this.#bridge?.setMentionTopicReply(this.#mentionTopicReply);
   }
 
   setStepPush(value) {
@@ -245,6 +262,17 @@ export class FeishuRuntime {
     this.#bridge?.setVoice(this.#voice);
   }
 
+  /**
+   * Record which commands the "/" panel should offer. The panel itself lives on
+   * Feishu's side, so a connected bot re-syncs it in the background; the newer
+   * config wins and any sync still running for the older one stops.
+   */
+  setSlashPanel(value) {
+    this.#slashPanel = normalizeSlashPanelConfig(value);
+    this.#slashSyncEpoch += 1;
+    this.#scheduleSlashPanelSync();
+  }
+
   async start() {
     while (true) {
       while (this.#stopping) await this.#stopping;
@@ -333,7 +361,7 @@ export class FeishuRuntime {
         appId: this.#appId,
         botOpenId: this.#botOpenId,
         groupResponseMode: this.#groupResponseMode,
-        groupTopicReply: this.#groupTopicReply,
+        mentionTopicReply: this.#mentionTopicReply,
         stepPush: this.#stepPush,
         stepPushMode: this.#stepPushMode,
         voice: this.#voice,
@@ -444,9 +472,11 @@ export class FeishuRuntime {
       assertCurrentStart();
       // Register the native Slash Command panel best-effort and asynchronously
       // so it never blocks the long-connection startup. The panel is only a
-      // client-side convenience; failure here must not take the bot down.
+      // client-side convenience; failure here must not take the bot down. The
+      // HTTP instance is kept so a later panel change can re-sync while running.
       if (this.#slashCommands && httpInstance) {
-        void this.#registerSlashCommands(httpInstance, isCurrentStart, signal);
+        this.#slashHttpInstance = httpInstance;
+        this.#scheduleSlashPanelSync();
       }
       return this.status;
     } catch (error) {
@@ -689,28 +719,69 @@ export class FeishuRuntime {
     return { sent: true };
   }
 
-  async #registerSlashCommands(httpInstance, isCurrentStart, signal) {
+  /**
+   * Queue one panel sync for the current config.
+   *
+   * Two saves in a row used to run two syncs concurrently, and the older one
+   * kept deleting and creating commands from a plan nobody wanted anymore. Here
+   * the run in flight is cancelled first — it stops at its next checkpoint while
+   * requests already sent are left to finish — and the new run starts only once
+   * it has settled, so the panel converges to the newest config.
+   */
+  #scheduleSlashPanelSync() {
+    const httpInstance = this.#slashHttpInstance;
+    const connectionSignal = this.#abortController?.signal;
+    if (!this.#slashCommands || !httpInstance || !connectionSignal || connectionSignal.aborted) return;
+    const epoch = this.#slashSyncEpoch;
+    this.#slashSyncCancel?.();
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    const forwardAbort = () => cancel();
+    this.#slashSyncCancel = cancel;
+    connectionSignal.addEventListener('abort', forwardAbort, { once: true });
+    if (connectionSignal.aborted) cancel();
+    const run = this.#slashSyncQueue.then(() => this.#registerSlashCommands(
+      httpInstance,
+      () => !connectionSignal.aborted && this.#abortController?.signal === connectionSignal,
+      controller.signal,
+      epoch,
+    ));
+    const settled = run.then(() => {}, () => {});
+    this.#slashSyncQueue = settled;
+    void settled.then(() => {
+      connectionSignal.removeEventListener('abort', forwardAbort);
+      if (this.#slashSyncCancel === cancel) this.#slashSyncCancel = null;
+    });
+  }
+
+  async #registerSlashCommands(httpInstance, isCurrentStart, signal, epoch = this.#slashSyncEpoch) {
     this.#status.slashCommandRegistration = 'registering';
     this.#status.slashCommandsError = null;
     try {
-      const result = await registerSlashCommands({
+      const result = await syncSlashCommands({
         appId: this.#appId,
         appSecret: this.#appSecret,
         domain: this.#domain,
         httpInstance,
         signal,
         manifest: SLASH_COMMAND_MANIFEST,
+        config: this.#slashPanel,
       });
-      if (!isCurrentStart()) return;
+      // A newer panel config took over while this sync was running: its own run
+      // reports the outcome, so this one only stops.
+      if (!isCurrentStart() || epoch !== this.#slashSyncEpoch || result.superseded === true) return;
       this.#status.slashCommandRegistration = 'done';
       this.#status.slashCommandsRegistered = result.created.length;
       this.#status.slashCommandsExisting = result.existing.length;
       this.#status.slashCommandsFailed = result.failed.length;
+      this.#status.slashCommandsRemoved = result.deleted.length;
       this.#status.slashCommandsError = result.failed.length > 0
         ? result.failed.map((f) => `/${f.command}: ${f.error?.message ?? String(f.error)}`).join('; ')
         : null;
-      if (result.created.length > 0) {
-        this.#logger.info?.(`[dsh-feishu] registered ${result.created.length} slash command(s)`);
+      if (result.created.length > 0 || result.deleted.length > 0) {
+        this.#logger.info?.(
+          `[dsh-feishu] slash panel synced: ${result.created.length} added, ${result.deleted.length} removed`,
+        );
       }
       if (result.failed.length > 0) {
         this.#logger.warn?.(

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);
+}