lark-remote 0.5.12 → 0.5.14

package/dist/router/index.js

@@ -1,20 +1,19 @@
-import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import YAML from 'yaml';
-import { getConfigDir, getConfigValue, setConfigValue, setConfigValues, mapAgentKey, getAgentConfig, } from '../config/index.js';
+import { getConfigDir, setConfigValue, setConfigValues, mapAgentKey, getAgentConfig, } from '../config/index.js';
 import { syncAgentChoices } from '../runner/index.js';
-import { resolveDshCredentialsFile } from '../runner/dsh/auth.js';
+import { resolveDshCredentialsFile } from '../dsh/auth.js';
 import { WorkspaceStore } from '../workspace/index.js';
 import { OrderStore, ORDER_NOT_FOUND_TEXT } from '../order/index.js';
 import { resolveAlias } from '../order/alias-resolve.js';
 import { diffConfig, setNestedValue } from './config-diff.js';
-import { AGENT_KINDS } from '../runner/types.js';
+import { AGENT_KINDS, resolveAgentKind } from '../agent-kinds.js';
 import { getLogger } from '../logger/index.js';
 import { stripPlaceholders } from '../inbound/placeholder.js';
 import { clampInt } from '../common/clamp.js';
-import { activeRunUsage } from './usage-format.js';
-import { markdownDiv, buildSessionHistoryCard, paginationBar, searchBar, parseJumpOffset, SEARCH_INPUT_NAME, PAGE_JUMP_INVALID_HINT, } from './card-helpers.js';
+import { activeRunUsage } from './active-run-usage.js';
+import { markdownDiv, buildSessionHistoryCard, paginationBar, parseJumpOffset, SEARCH_INPUT_NAME, PAGE_JUMP_INVALID_HINT, } from '../card/card-helpers.js';
 import { MAX_FILE_UPLOAD_SIZE } from '../connector/file-limits.js';
 import { cardButton, newSessionButton, resumeCompactButton, agentDisplayName, } from '../card/card-shared.js';
 import { displayName } from '../platform/path.js';
@@ -24,36 +23,16 @@ import { checkLatestVersion as defaultCheckLatestVersion, compareVersions as def
 import { getConfigBuilder, listRegisteredAgents, sortAgentsForDisplay } from './config/index.js';
 import { probeAllAgents, getCachedAvailability } from '../runner/probe.js';
 import { buildConfigCardFromTabs } from './config/common/render.js';
+import { isDirectorySafe, resolveDirectory, statPath } from './path-validation.js';
+import { pageInfo } from './paging.js';
+import { buildLsCommand, LS_PAGE_SIZE } from './commands/ls.js';
+import { buildWsCommand, WS_PAGE_SIZE } from './commands/ws.js';
+import { buildOrderCommand, ORDER_PAGE_SIZE } from './commands/order.js';
+import { buildResumeCommand, AUTO_RESUME_MAX_EVENTS, RESUME_PAGE_SIZE } from './commands/resume.js';
 /** Max events to read for auto-resume and /resume cards.
  * Limits events at the read stage so enforceCardBudget rarely needs to truncate.
  * Chosen to be under the 28KB card budget for typical events (~2KB each). */
-const AUTO_RESUME_MAX_EVENTS = 5;
-/** /resume 列表页大小；`/resume [N]` 的 N clamp 到 [1, RESUME_PAGE_SIZE]。 */
-const RESUME_PAGE_SIZE = 5;
 /** /active 卡片每页显示的最大条目数（agent run + bash run 合计）。 */
-/**
- * 分页算术（原先 5 处内联且 clamp 语义漂移：/ls 不 clamp、/active clamp 到
- * totalCount-1 会把过期 offset 泄漏成残页）。统一 clamp 到最后一页边界。
- */
-function pageInfo(totalCount, offset, pageSize) {
-    const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
-    const maxOffset = Math.max(0, (totalPages - 1) * pageSize);
-    const safeOffset = clampInt(offset, 0, maxOffset);
-    const currentPage = Math.floor(safeOffset / pageSize) + 1;
-    return { totalPages, safeOffset, currentPage };
-}
-/** 在 pageInfo 之上切出当前页条目。 */
-function pageSlice(items, offset, pageSize) {
-    const { totalPages, safeOffset, currentPage } = pageInfo(items.length, offset, pageSize);
-    return {
-        totalCount: items.length,
-        totalPages,
-        safeOffset,
-        currentPage,
-        pageItems: items.slice(safeOffset, safeOffset + pageSize),
-        hasPagination: items.length > pageSize,
-    };
-}
 const ACTIVE_PAGE_SIZE = 20;
 /**
  * 飞书会把极短间隔连发的多条消息合并成一条换行分隔的消息：用户侧看是两条消息，
@@ -75,15 +54,6 @@ function findMergedCommandTail(message) {
     return hasSlashLine ? tail : null;
 }
 /** 人类可读字节数（B/KB/MB/GB）；/ls 列表与单文件卡共用。 */
-function formatBytes(bytes) {
-    if (bytes < 1024)
-        return `${bytes}B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)}KB`;
-    if (bytes < 1024 * 1024 * 1024)
-        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
-}
 /**
  * /order 列表页大小；指令超过此数量时显示分页导航栏。
  * 2026-08-13 实测：每行 2 个元素（div + column_set，行间 hr），20 行 + 分页栏
@@ -93,13 +63,11 @@ function formatBytes(bytes) {
  * 从 15 降为 8：3*8 - 1 + 2 = 25 个元素，仍在余量内，同时保证手机窄屏
  * 每条指令的操作控件（执行/别名/删除）不被挤压。
  */
-const ORDER_PAGE_SIZE = 8;
 /**
  * /ws 列表页大小。从 15 降为 5：头部 2 + 5 行 × 3（div + column_set + hr）+
  * 底栏排序 1 + 分页栏 2 ≈ 20 个 body 元素，远低于单卡 60 元素上限（ErrCode 11310），
  * 留足余量。
  */
-const WS_PAGE_SIZE = 5;
 /**
  * 归一化卡片分页参数：clamp pageSize 到 [1,maxPageSize]，offset 归整为
  * 非负整数并对齐到页边界。非数字 payload（如 'abc'）不得产生 NaN slice。
@@ -126,25 +94,17 @@ function normalizePageArgs(value, maxPageSize) {
     return { pageSize, alignedOffset: Math.floor(offset / pageSize) * pageSize };
 }
 /** /resume 列表页内全量预取（readSessionContent）的行数上限；其余行用轻量 summary 兜底。 */
-const RESUME_CONTENT_PREFETCH = 5;
 /**
  * Reader summary 占位符（trim 后匹配）。各 reader 在"无 user 消息"时返回的
  * 兜底文案不同（claude/pi `(无摘要)`、codex `(no user message)`、kimi
  * `New Session`、空串），都不是真实输入，不得渲染成行标题。
  */
-const RESUME_SUMMARY_PLACEHOLDERS = new Set(['', '(no user message)', '(无摘要)', 'New Session']);
-/** 列表卡「最近输入 / 最后输出」单行预览的长度上限（中文按字符，手机约两行）。 */
-const RESUME_PREVIEW_MAX = 60;
 /**
  * 列表卡单行预览：压平空白、去掉反引号，再按字符截断。
  *
  * 为什么去反引号：agent 的输出里 `code` 很常见，截断点落在一对反引号中间时
  * 后半张卡片的 markdown 会被当成代码块渲染（lark_md 不闭合就不回退）。
  */
-function sessionPreviewLine(text, max) {
-    const flat = text.replace(/`/g, '').replace(/\s+/g, ' ').trim();
-    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
-}
 /**
  * Card-action commands that must run with enqueue({ immediate: true }).
  * These bypass the serial queue and execute immediately.
@@ -330,7 +290,6 @@ const IMMEDIATE_ACTION_CMDS = new Set([
     'order.aliasRemove',
     'order.textEdit',
     'order.textInput',
-    'config.toggle',
     'config.set',
     'config.input',
     'config.save',
@@ -369,20 +328,6 @@ export const COMPACT_ACTION_CMDS = new Set(['compact', 'resume.compact']);
 function payloadOffset(value) {
     return Math.max(0, Math.trunc(Number(value.offset) || 0));
 }
-/**
- * existsSync + statSync 的 TOCTOU 安全目录校验：路径在两次 syscalls 之间被删时
- * statSync 会抛错——落进 enqueueImmediate / 队列任务的静默 catch，点击/命令
- * 毫无反馈（违反「点击必有反馈」红线；同族 handleLsRefresh/Page/Filter 均已
- * try/catch 防护）。统一返回 false 走「路径无效」回复。
- */
-function isDirectorySafe(p) {
-    try {
-        return fs.existsSync(p) && fs.statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * 搜索框提交值单源读取：`inputValue` 主路（CardKit 2.0 input 提交（键盘回车/
  * 完成键）经 raw `action.input_value` 回传，SDK normalizer 会丢弃
@@ -403,13 +348,20 @@ const CARD_PAYLOAD_MISSING = '⚠️ 卡片 payload 缺少必要信息';
  * 卡片只有最近一两张，5 张足够覆盖；无上限会让长跑进程的 Set 随卡片数增长。
  */
 const MAX_CONFIG_CARDS = 5;
+/** 本次改动是否落进 `agents.<kind>` 子树。 */
+function touchesAgentsSubtree(keys, kind) {
+    return keys.some((k) => k === `agents.${kind}` || k.startsWith(`agents.${kind}.`));
+}
+/**
+ * 本次改动是否触及某个 agent 的配置——两种键形态都要认：现行 `agents.<kind>[.*]`
+ * 与历史的顶层 `<kind>[.*]`（claude 至今是顶层键）。判定曾抄在三处（agent 变更检测 /
+ * agentChoices 同步 / approval 热推），每加一个 agent 都得记得改三遍，与
+ * AGENT_KINDS 名单漂移是同一种事故，这里收成一处。
+ */
+function touchesAgentConfig(keys, kind) {
+    return (touchesAgentsSubtree(keys, kind) || keys.some((k) => k === kind || k.startsWith(`${kind}.`)));
+}
 export class CommandRouter {
-    /**
-     * Valid agent kinds — single source of truth for resume.use / resume.page /
-     * cmdResume. 名单本体在 `runner/types.ts` 的 AGENT_KINDS（与 AgentKind 类型
-     * 同源），这里只做别名，避免人手抄第二份。
-     */
-    static VALID_AGENTS = AGENT_KINDS;
     sessionStore;
     /** 飞书桥接实例（public：测试直接访问断言，替代 as unknown as）。 */
     bridge;
@@ -482,8 +434,8 @@ export class CommandRouter {
     /**
      * 串行化 config.* 卡片回调（2026-07-04）。
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，**不进串行队列**，
-     * 多次快速点击 toggle/input 会并发读写 `pendingConfig` 并同时调
-     * `updateCardInPlace` → Feishu API 乱序到达，导致 toggle 卡死在某个状态。
+     * 多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
+     * `updateCardInPlace` → Feishu API 乱序到达，控件卡死在某个状态。
      * 此 Promise chain 把所有 config.* 动作串成一个执行链，保证后到的动作
      * 等前一个动作的卡片 patch 完成后再读 `pendingConfig`。
      */
@@ -637,11 +589,7 @@ export class CommandRouter {
             case 'resume.use': {
                 // resume.use carries an agent field from /resume [agent] list cards
                 // (both active and completed cards include the agent field).
-                const resumeAgent = value.agent ?? this.config.defaultAgent;
-                const validAgents = CommandRouter.VALID_AGENTS;
-                const resolvedAgent = validAgents.includes(resumeAgent)
-                    ? resumeAgent
-                    : this.config.defaultAgent;
+                const resolvedAgent = resolveAgentKind(value.agent, this.config.defaultAgent);
                 const entry = this.sessionStore.get(ctx.userId);
                 const cwd = entry?.cwd;
                 if (!cwd) {
@@ -712,13 +660,12 @@ export class CommandRouter {
                 return await this.handleOrderTextEdit(value, ctx);
             case 'order.textInput':
                 return await this.handleOrderTextInput(value, ctx);
-            case 'config.toggle':
             case 'config.set':
             case 'config.input':
             case 'config.save':
                 // 2026-07-04: 串行化所有 config.* 动作。CardKit 2.0 回调经 enqueueImmediate
-                // 不进串行队列，多次快速点击 toggle/input 会并发读写 pendingConfig 并同时
-                // 调 updateCardInPlace → Feishu API 乱序到达导致 toggle 卡死。
+                // 不进串行队列，多次快速点击下拉/文本框会并发读写 pendingConfig 并同时
+                // 调 updateCardInPlace → Feishu API 乱序到达导致控件卡死。
                 // 2026-07-18: 返回 enqueueConfigAction 的结果以支持 toast 响应
                 return this.enqueueConfigAction(value, ctx);
             case 'compact':
@@ -813,6 +760,20 @@ export class CommandRouter {
      * Handle queue.immediate: stop current run, clear queue before this message, execute this message immediately.
      * Instead of asking user to resend, we keep the target task in queue and let it execute.
      */
+    /**
+     * 把「执行编辑后的内容」注册成原队列槽位的一次性 replacement（复用入队时
+     * 捕获的 binding + 恢复 lane cwd，否则编辑后重跑的 run 会丢 cwd 与绑定）。
+     *
+     * 重新入队不行：`enqueue` 只能追加到 promise 链尾部，会把编辑任务甩到
+     * 后来者后面，违背「立即执行 = 下一个就跑」。三个调用点都必须在任何 await
+     * 之前注册——begin 路径消费 replacement 的时机不可预测（见
+     * handleQueueImmediate 步骤 1.5 的竞态说明）。
+     */
+    registerEditedReplacement(cwd, messageId, content, binding, ctx) {
+        this.bridge.setTaskReplacement(cwd, messageId, async () => {
+            await this.handle(content, ctx, { cwdOverride: cwd, binding });
+        });
+    }
     async handleQueueImmediate(value, ctx) {
         const payload = await this.queuePayloadOrReply(value, ctx);
         if (!payload)
@@ -862,15 +823,7 @@ export class CommandRouter {
             // the queue position: enqueue can only append to the promise chain tail,
             // which would put the edited task behind tasks queued after it.
             if (targetTask.editedMessage) {
-                const editedContent = targetTask.editedMessage;
-                ///Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
-                // cwdOverride（lane cwd 同源）。否则编辑后重新执行的 run 会丢 cwd 与绑定。
-                this.bridge.setTaskReplacement(cwd, messageId, async () => {
-                    await this.handle(editedContent, ctx, {
-                        cwdOverride: cwd,
-                        binding: targetTask.binding,
-                    });
-                });
+                this.registerEditedReplacement(cwd, messageId, targetTask.editedMessage, targetTask.binding, ctx);
             }
             // 2. Stop current running process
             // (Note: queue executing count is reset inside Bridge.interruptCurrentRun
@@ -887,29 +840,7 @@ export class CommandRouter {
             const stopUnconfirmed = interrupt.stop?.status === 'unconfirmed';
             getLogger().info(`[router] queue.immediate: stopped=${stopped} unconfirmed=${stopUnconfirmed}`);
             // 3. Remove all tasks BEFORE this one (by position in the current queue).
-            // The target may have begun while interruptCurrentRun was awaiting (the chain
-            // advances concurrently): then it is already out of the snapshot and every
-            // remaining queued task is BEHIND it — clearing must stop, not run off the
-            // end and delete tasks queued after the target.
-            const tasks = this.bridge.getQueuedTasks(cwd);
-            const targetIdx = tasks.findIndex((t) => t.messageId === messageId);
-            let removedCount = 0;
-            // Phase 1: remove synchronously. The queue chain advances on any await
-            // (card PATCH round trips included), so every task before the target must
-            // be removed before yielding to the event loop — otherwise a task the user
-            // asked to clear can begin executing while its cancellation card is still
-            // in flight.
-            for (let i = 0; i < targetIdx; i++) {
-                const task = tasks[i];
-                // 撤销卡片由 removeFromQueue 统一触发（fire-and-forget），保持本循环
-                // 同步推进的既有不变式。
-                if (this.bridge.removeFromQueue(cwd, task.messageId)) {
-                    removedCount++;
-                }
-            }
-            if (targetIdx < 0) {
-                getLogger().debug(`[router] queue.immediate: target no longer queued (began/cancelled), not clearing tasks behind it`);
-            }
+            const removedCount = this.clearTasksAheadOfTarget(cwd, messageId);
             // 4. DO NOT remove the target task - keep it in queue to execute immediately
             // The queue will naturally execute it after the current task (which we just stopped)
             // 4.4. Refresh the replacement with the latest edited content (idempotent:
@@ -918,66 +849,92 @@ export class CommandRouter {
             // the task has begun, because getQueuedTask then returns undefined.
             const latestTask = this.bridge.getQueuedTask(cwd, messageId);
             if (latestTask?.editedMessage) {
-                const editedContent = latestTask.editedMessage;
-                ///Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
-                this.bridge.setTaskReplacement(cwd, messageId, async () => {
-                    await this.handle(editedContent, ctx, {
-                        cwdOverride: cwd,
-                        binding: latestTask.binding,
-                    });
-                });
+                this.registerEditedReplacement(cwd, messageId, latestTask.editedMessage, latestTask.binding, ctx);
             }
-            // 4.5/6. The target must only be marked executing (and the toast may only
-            // promise immediate execution) when it is really the next task after the
-            // stop. While interruptCurrentRun was awaiting, a task ahead of the target
-            // may have begun and now occupy the cwd — the target is still queued
-            // but is NOT next, so its card must stay queued and the toast must say so.
-            const targetStillQueued = this.bridge.getQueuedTask(cwd, messageId) !== undefined;
-            if (!targetStillQueued) {
-                // The target began or was cancelled while earlier awaits were in flight —
-                // a success toast must never promise execution of a task that will not
-                // run. The two missing-reason states get distinct feedback: a target
-                // that began while the interrupt was in flight is already executing, so
-                // the toast must acknowledge that instead of telling the user nothing
-                // was scheduled; only a target that was actually cancelled (never began)
-                // gets the "未安排执行" wording.
-                if (this.bridge.hasTaskBegan(messageId)) {
-                    await this.bridge.sendResult({ text: `ℹ️ 目标消息已开始执行，无需重复操作。已清除 ${removedCount} 条排队消息。` }, ctx);
-                }
-                else {
-                    await this.bridge.sendResult({
-                        text: `⚠️ 目标消息已不在队列中（可能已被撤销），未安排执行。已清除 ${removedCount} 条排队消息。`,
-                    }, ctx);
-                }
-                return;
-            }
-            const workspaceBusy = this.bridge.isBusyFor(cwd);
-            if (stopUnconfirmed) {
-                const name = interrupt.agentKind ? agentDisplayName(interrupt.agentKind) : 'agent';
-                await this.bridge.sendResult({
-                    text: `⚠️ 未能确认 ${name} 的 turn 已停止，它可能仍在后台运行。\n` +
-                        `已清除 ${removedCount} 条排队消息；您的消息已提交，但可能要等该 turn 结束后才开始。`,
-                }, ctx);
+            // 4.5/6. 按「目标此刻真的是下一个吗」给唯一一份用户可见反馈。
+            await this.reportImmediateOutcome({
+                cwd,
+                messageId,
+                ctx,
+                removedCount,
+                stopped,
+                stopUnconfirmed,
+                agentKind: interrupt.agentKind,
+            });
+        }
+        finally {
+            releaseRunStart();
+        }
+    }
+    /**
+     * 清掉排在目标之前的所有排队任务，返回实际清除条数。
+     *
+     * 两条红线：
+     * - 目标可能在 interruptCurrentRun 等待期间已经接跑（链并发前进），那时它已不在
+     *   快照里，剩下的全部排在它**后面**——清除必须在目标位置之前停下，不得越界删掉
+     *   用户没要求清除的任务。
+     * - 移除循环必须整体同步：队列链在任何 await 处都会推进（卡片 PATCH 也算），
+     *   一旦让出事件循环，用户要求清除的任务可能趁撤销卡还在路上就跑起来了。
+     *   撤销卡片由 `removeFromQueue` 统一触发（fire-and-forget）。
+     */
+    clearTasksAheadOfTarget(cwd, messageId) {
+        const tasks = this.bridge.getQueuedTasks(cwd);
+        const targetIdx = tasks.findIndex((t) => t.messageId === messageId);
+        let removedCount = 0;
+        for (let i = 0; i < targetIdx; i++) {
+            if (this.bridge.removeFromQueue(cwd, tasks[i].messageId)) {
+                removedCount++;
             }
-            else if (!workspaceBusy) {
-                // Normal path: nothing new began during the stop, the target is next.
-                // Mark its own card as executing now so buttons grey out immediately.
-                // Done BEFORE any removal so getQueuedTask still returns the task with
-                // its (possibly edited) messagePreview for the card. The queue callback's
-                // later updateQueueCardToExecuting call becomes a no-op (idempotent).
-                await this.bridge.markQueueCardExecuting(cwd, messageId);
-                const stopPrefix = stopped ? '⚡ 已停止当前任务，' : '';
-                await this.bridge.sendResult({ text: `${stopPrefix}清除了 ${removedCount} 条排队消息。您的消息将立即执行。` }, ctx);
+        }
+        if (targetIdx < 0) {
+            getLogger().debug(`[router] queue.immediate: target no longer queued (began/cancelled), not clearing tasks behind it`);
+        }
+        return removedCount;
+    }
+    /**
+     * `queue.immediate` 的终态反馈（唯一出口）。
+     *
+     * 承诺必须与真实调度一致：目标只有确实是停止后的下一个，才可以把它的卡翻成
+     * 「执行中」并说「将立即执行」；在途接跑/被撤销/被抢先/远程停止未确认四种状态
+     * 各给各的文案（把没发生的事说成发生了，比沉默更糟——用户会据文案决定要不要重发）。
+     */
+    async reportImmediateOutcome(opts) {
+        const { cwd, messageId, ctx, removedCount, stopped, stopUnconfirmed, agentKind } = opts;
+        const targetStillQueued = this.bridge.getQueuedTask(cwd, messageId) !== undefined;
+        if (!targetStillQueued) {
+            // 目标在途接跑：已经在执行，说「无需重复操作」；真的被撤销了才说「未安排执行」。
+            if (this.bridge.hasTaskBegan(messageId)) {
+                await this.bridge.sendResult({ text: `ℹ️ 目标消息已开始执行，无需重复操作。已清除 ${removedCount} 条排队消息。` }, ctx);
             }
             else {
                 await this.bridge.sendResult({
-                    text: `⚠️ 排在目标之前的任务已开始执行，目标消息保持排队。已清除 ${removedCount} 条排队消息。`,
+                    text: `⚠️ 目标消息已不在队列中（可能已被撤销），未安排执行。已清除 ${removedCount} 条排队消息。`,
                 }, ctx);
             }
+            return;
         }
-        finally {
-            releaseRunStart();
+        if (stopUnconfirmed) {
+            const name = agentKind ? agentDisplayName(agentKind) : 'agent';
+            await this.bridge.sendResult({
+                text: `⚠️ 未能确认 ${name} 的 turn 已停止，它可能仍在后台运行。\n` +
+                    `已清除 ${removedCount} 条排队消息；您的消息已提交，但可能要等该 turn 结束后才开始。`,
+            }, ctx);
+            return;
         }
+        if (!this.bridge.isBusyFor(cwd)) {
+            // Normal path: nothing new began during the stop, the target is next.
+            // Mark its own card as executing now so buttons grey out immediately.
+            // Done BEFORE any removal so getQueuedTask still returns the task with
+            // its (possibly edited) messagePreview for the card. The queue callback's
+            // later updateQueueCardToExecuting call becomes a no-op (idempotent).
+            await this.bridge.markQueueCardExecuting(cwd, messageId);
+            const stopPrefix = stopped ? '⚡ 已停止当前任务，' : '';
+            await this.bridge.sendResult({ text: `${stopPrefix}清除了 ${removedCount} 条排队消息。您的消息将立即执行。` }, ctx);
+            return;
+        }
+        await this.bridge.sendResult({
+            text: `⚠️ 排在目标之前的任务已开始执行，目标消息保持排队。已清除 ${removedCount} 条排队消息。`,
+        }, ctx);
     }
     /**
      * Handle queue.diagnose: show diagnostic info for why message is queuing.
@@ -1149,8 +1106,6 @@ export class CommandRouter {
         // replacement if the task starts during the subsequent await. Both
         // setTaskReplacement and the begin-path consumption are synchronous, so
         // there is no interleaving window.
-        //
-        ///Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
         const inputTask = this.bridge.getQueuedTask(cwd, messageId);
         if (!inputTask) {
             // Task already left the queue (began or was cancelled) before we could
@@ -1160,9 +1115,7 @@ export class CommandRouter {
             // toast/card field).
             return { toast: { type: 'info', content: '任务已不在队列中（可能已开始执行或被撤销）' } };
         }
-        this.bridge.setTaskReplacement(cwd, messageId, async () => {
-            await this.handle(newMessage, ctx, { cwdOverride: cwd, binding: inputTask.binding });
-        });
+        this.registerEditedReplacement(cwd, messageId, newMessage, inputTask.binding, ctx);
         // Update the message preview (and editedMessage so handleQueueImmediate
         // re-enqueues the edited content instead of the stale original closure),
         // and build the updated queue card. Returning the card in the callback
@@ -1226,26 +1179,17 @@ export class CommandRouter {
         const resolvedTarget = path.resolve(targetPath);
         // 与 ls.browse 对齐：目标只要存在且是目录即可切换（不再做子树/父级限制）。
         // 安全边界由 binder owner 认证兜底，见 docs/zh/architecture/design.md §9.7 更新说明。
-        if (!isDirectorySafe(resolvedTarget)) {
-            await this.bridge.sendResult({ text: `路径无效: ${resolvedTarget}` }, ctx);
-            return;
-        }
-        // Canonicalize via realpath; if the target vanished between stat and
-        // realpath (TOCTOU), reject gracefully instead of throwing.
-        let canonical;
-        try {
-            canonical = fs.realpathSync(resolvedTarget);
-        }
-        catch {
+        const resolution = resolveDirectory(resolvedTarget);
+        if (!resolution.ok) {
             await this.bridge.sendResult({ text: `路径无效: ${resolvedTarget}` }, ctx);
             return;
         }
         // Set cwd + auto-resume + user notification (shared with /cd and /ws use)
-        const notifyResult = this.switchCwdAndNotify(ctx.userId, canonical, ctx);
+        const notifyResult = this.switchCwdAndNotify(ctx.userId, resolution.canonical, ctx);
         // Card channel: refresh ls card in-place (existing behavior preserved)。
         // value.root 是本次 /ls 浏览的起点（绝对路径，不受 cwd 变更影响），透传后
         // 「返回」仍回到用户最初 /ls 的那个目录。
-        const card = this.cmdLs([canonical], ctx, 0, value.root);
+        const card = this.cmdLs([resolution.canonical], ctx, 0, value.root);
         await this.bridge.updateCardInPlace(card.card, ctx);
         // Message channel: send switch confirmation / auto-resume card to chat
         await this.bridge.sendResult(notifyResult, ctx);
@@ -1256,21 +1200,11 @@ export class CommandRouter {
     async handleLsRefresh(value, ctx) {
         const targetPath = value.path;
         const offset = value.offset ?? 0;
-        // TOCTOU guard: existsSync → statSync can race (target
-        // deleted in between), throwing into enqueueImmediate's catch which only
-        // logs — violating the "card button clicks must give visible feedback"
-        // red line. Treat a vanished/non-dir path as "use current cwd" instead of
-        // crashing the refresh.
-        let card;
-        try {
-            card =
-                targetPath && fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory()
-                    ? this.cmdLs([targetPath], ctx, offset, value.root, value.q)
-                    : this.cmdLs([], ctx, offset, value.root, value.q);
-        }
-        catch {
-            card = this.cmdLs([], ctx, offset, value.root, value.q);
-        }
+        // Treat a vanished/non-dir path as "use current cwd" instead of crashing
+        // the refresh. inspectPath closes the former existsSync→statSync race.
+        const card = targetPath && isDirectorySafe(targetPath)
+            ? this.cmdLs([targetPath], ctx, offset, value.root, value.q)
+            : this.cmdLs([], ctx, offset, value.root, value.q);
         await this.bridge.updateCardInPlace(card.card, ctx);
     }
     /**
@@ -1281,22 +1215,12 @@ export class CommandRouter {
         if (!targetPath) {
             return { toast: { type: 'error', content: '卡片 payload 缺少 path' } };
         }
-        const paging = this.pagingOffset(value, CommandRouter.LS_PAGE_SIZE);
+        const paging = this.pagingOffset(value, LS_PAGE_SIZE);
         if ('error' in paging) {
             return { toast: { type: 'error', content: paging.error } };
         }
         const resolvedTarget = path.resolve(targetPath);
-        // TOCTOU guard: existsSync → statSync can race; without the
-        // try/catch the throw lands in enqueueImmediate's silent .catch and the
-        // paginated card never updates (no visible feedback for the click).
-        let isDir;
-        try {
-            isDir = fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isDirectory();
-        }
-        catch {
-            isDir = false;
-        }
-        if (!isDir) {
+        if (!isDirectorySafe(resolvedTarget)) {
             return { toast: { type: 'error', content: `路径无效: ${resolvedTarget}` } };
         }
         const card = this.cmdLs([resolvedTarget], ctx, paging.offset, value.root, value.q);
@@ -1318,14 +1242,7 @@ export class CommandRouter {
         }
         const q = searchQueryFrom(value);
         const resolvedTarget = path.resolve(targetPath);
-        let isDir;
-        try {
-            isDir = fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isDirectory();
-        }
-        catch {
-            isDir = false;
-        }
-        if (!isDir) {
+        if (!isDirectorySafe(resolvedTarget)) {
             return { toast: { type: 'error', content: `路径无效: ${resolvedTarget}` } };
         }
         const card = this.cmdLs([resolvedTarget], ctx, 0, value.root, q);
@@ -1337,11 +1254,7 @@ export class CommandRouter {
      * Mirrors handleLsPage — updates the same card, never sends a new one.
      */
     async handleResumePage(value, ctx) {
-        const resumeAgent = value.agent ?? this.config.defaultAgent;
-        const validAgents = CommandRouter.VALID_AGENTS;
-        const resolvedAgent = validAgents.includes(resumeAgent)
-            ? resumeAgent
-            : this.config.defaultAgent;
+        const resolvedAgent = resolveAgentKind(value.agent, this.config.defaultAgent);
         const { pageSize, alignedOffset, error } = normalizePageArgs(value, RESUME_PAGE_SIZE);
         if (error) {
             return { toast: { type: 'error', content: error } };
@@ -1471,8 +1384,6 @@ export class CommandRouter {
      * Returns null when the order no longer exists; index.ts surfaces the error.
      */
     resolveOrderExecForQueue(orderId) {
-        if (!this.orderStore.has(orderId))
-            return null;
         const order = this.orderStore.get().find((o) => o.id === orderId);
         if (!order)
             return null;
@@ -1856,16 +1767,13 @@ export class CommandRouter {
      * `/download` 与 `ls.file` 卡片按钮共用，避免两处重复 30MB/存在性校验。
      */
     async deliverFileToFeishu(resolved, ctx) {
-        if (!fs.existsSync(resolved)) {
-            return { text: `文件不存在: ${resolved}` };
-        }
-        let stat;
-        try {
-            stat = fs.statSync(resolved);
-        }
-        catch {
+        const resolution = statPath(resolved);
+        if (!resolution.ok) {
+            if (resolution.reason === 'missing')
+                return { text: `文件不存在: ${resolved}` };
             return { text: `无法读取: ${resolved}` };
         }
+        const { stat } = resolution;
         if (stat.isDirectory()) {
             return { text: `这是一个目录，不能作为文件发送: ${resolved}\n用 /ls 查看目录内容` };
         }
@@ -1905,6 +1813,26 @@ export class CommandRouter {
             this.configCardIds.delete(oldest);
         }
     }
+    /**
+     * 把一次字段变更交给当前 agent 的 config builder（处理 provider→model 这类
+     * 依赖关系），逐条写进草稿，再把草稿刷到所有配置卡。
+     * `config.set`（下拉）与 `config.input`（输入框提交）共用同一套应用逻辑。
+     */
+    async applyConfigFieldChange(key, newValue, ctx) {
+        try {
+            this.ensurePendingConfig();
+            const defaultAgent = this.pendingConfig.defaultAgent ?? 'claude';
+            const configBuilder = getConfigBuilder(defaultAgent);
+            const patches = configBuilder.handleFieldChange(key, newValue, this.pendingConfig);
+            for (const patch of patches) {
+                this.setNestedValue(this.pendingConfig, patch.key, patch.value);
+            }
+            await this.refreshConfigCards(ctx);
+        }
+        catch (err) {
+            await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
+        }
+    }
     /**
      * 把当前草稿刷到所有已知 config 卡片上（含本次点击的那张）。
      *
@@ -1928,12 +1856,12 @@ export class CommandRouter {
         }
     }
     /**
-     * 串行化 config.* 卡片回调（2026-07-04 修复 toggle 卡死 bug）。
+     * 串行化 config.* 卡片回调（2026-07-04 修复连击卡死 bug）。
      *
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，不进 bridge 的
-     * 串行队列；多次快速点击 toggle 会并发读写 `pendingConfig` 并同时调
+     * 串行队列；多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
      * `updateCardInPlace` → 两个 patch 请求乱序到达飞书，后到达的 patch（点击 1
-     * 的旧卡片）覆盖先到达的 patch（点击 2 的新卡片），用户看到 toggle 卡死。
+     * 的旧卡片）覆盖先到达的 patch（点击 2 的新卡片），用户看到控件卡死。
      *
      * 此方法把所有 config.* 动作串成一个 Promise chain：每个动作等前一个动作
      * 的 `updateCardInPlace` 完全 settle 后再读 `pendingConfig`。
@@ -1956,28 +1884,6 @@ export class CommandRouter {
     /** config.* 卡片动作分发（public：测试直接调用，替代 as unknown as）。 */
     async dispatchConfigAction(value, ctx) {
         switch (value.cmd) {
-            case 'config.toggle': {
-                // 通用 boolean 翻转：目前无卡片字段使用（output.show* 已移除），
-                // 保留供未来 boolean 配置项复用；configActionQueue 串行化覆盖连击。
-                const key = value.key;
-                if (!key) {
-                    await this.bridge.sendResult({ text: '缺少配置项 key' }, ctx);
-                    return;
-                }
-                this.ensurePendingConfig();
-                const current = getConfigValue(this.pendingConfig, key);
-                // 布尔字段未设置时视为 false，而非报错（如布尔配置项尚未写入 config）
-                const boolVal = typeof current === 'boolean' ? current : false;
-                try {
-                    // 只改暂存区，不写盘；原地更新卡片而非发送新卡（2026-07-04）
-                    this.setNestedValue(this.pendingConfig, key, !boolVal);
-                    await this.refreshConfigCards(ctx);
-                }
-                catch (err) {
-                    await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
-                }
-                return;
-            }
             case 'config.set': {
                 // Set config value from select dropdown (option from CardKit 2.0)
                 const key = value.key;
@@ -1986,20 +1892,7 @@ export class CommandRouter {
                     await this.bridge.sendResult({ text: '缺少参数' }, ctx);
                     return;
                 }
-                try {
-                    this.ensurePendingConfig();
-                    // 使用 agent config builder 处理字段变更（处理依赖关系如 provider→model）
-                    const defaultAgent = this.pendingConfig.defaultAgent ?? 'claude';
-                    const configBuilder = getConfigBuilder(defaultAgent);
-                    const patches = configBuilder.handleFieldChange(key, newValue, this.pendingConfig);
-                    for (const patch of patches) {
-                        this.setNestedValue(this.pendingConfig, patch.key, patch.value);
-                    }
-                    await this.refreshConfigCards(ctx);
-                }
-                catch (err) {
-                    await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
-                }
+                await this.applyConfigFieldChange(key, newValue, ctx);
                 return;
             }
             case 'config.input': {
@@ -2017,20 +1910,7 @@ export class CommandRouter {
                     await this.bridge.sendResult({ text: '缺少输入值' }, ctx);
                     return;
                 }
-                try {
-                    this.ensurePendingConfig();
-                    // 使用 agent config builder 处理字段变更
-                    const defaultAgent = this.pendingConfig.defaultAgent ?? 'claude';
-                    const configBuilder = getConfigBuilder(defaultAgent);
-                    const patches = configBuilder.handleFieldChange(key, newValue, this.pendingConfig);
-                    for (const patch of patches) {
-                        this.setNestedValue(this.pendingConfig, patch.key, patch.value);
-                    }
-                    await this.refreshConfigCards(ctx);
-                }
-                catch (err) {
-                    await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
-                }
+                await this.applyConfigFieldChange(key, newValue, ctx);
                 return;
             }
             case 'config.save': {
@@ -2116,18 +1996,9 @@ export class CommandRouter {
         this.bridge.setIdleTimeout(this.idleTimeoutMs);
         // 2026-07-13: 检测是否有任何 agent 配置变更或 defaultAgent 切换
         const hasDefaultAgentChange = oldDefaultAgent !== this.config.defaultAgent;
-        const hasAgentConfigChange = Object.keys(updates).some((k) => k.startsWith('agents.') ||
-            k.startsWith('claude.') ||
-            k.startsWith('pi.') ||
-            k.startsWith('codex.') ||
-            k.startsWith('opencode.') ||
-            k.startsWith('kimi.') ||
-            k === 'defaultAgent' ||
-            k === 'claude' ||
-            k === 'pi' ||
-            k === 'codex' ||
-            k === 'opencode' ||
-            k === 'kimi');
+        const changedKeys = Object.keys(updates);
+        const hasAgentConfigChange = changedKeys.includes('defaultAgent') ||
+            AGENT_KINDS.some((kind) => touchesAgentConfig(changedKeys, kind));
         // 当 defaultAgent 改变时，清除旧 agent 的 sessionId，
         // 同时清除新 agent 的 sessionId（等效于 /new 命令），
         // 并支持 session 恢复 - 切换回来时如果条件满足则恢复之前的 session。
@@ -2176,43 +2047,30 @@ export class CommandRouter {
                 switchSessionId = '';
             }
         }
-        // DSH preset 变更 = 下次 run 新建 session：
-        // preset 在 session 创建时固定，中途切换会被服务端拒绝（agent-preset-conflict）。
-        // 旧 sessionId 存入 previousSessions 停车位（可手动 /resume，但 /resume 会做
-        // preset 一致性校验），当前 sessionId 清空——下次 run 走 session.create 新建。
-        const hasDshPresetChange = Object.keys(updates).some((k) => k === 'agents.dsh.agentPreset');
-        // 已发生 agent 切换时（switchNotice 已设置）preset 分支跳过，避免覆盖切换 notice；
-        // 切换分支对 dsh 的 session 已做恢复/清空处理。
-        if (hasDshPresetChange && this.config.defaultAgent === 'dsh' && !switchNotice) {
-            const oldSessionId = this.sessionStore.getSessionId(ctx.userId, 'dsh');
-            if (oldSessionId) {
-                this.sessionStore.setPreviousSessionId(ctx.userId, 'dsh', oldSessionId);
-                this.sessionStore.clearSessionId(ctx.userId, 'dsh');
-                switchNotice = `DSH preset 已变更，旧会话已停放到恢复槽（可 /resume 校验后恢复），下次消息将新建会话`;
-            }
-            else {
-                switchNotice = `DSH preset 已变更，下次消息将新建会话`;
-            }
-        }
-        // DSH host 变更 = 换服务：旧 host 的 sessionId 发往新 host 是错的。
-        // 视为 session 边界，仿 preset 分支停车 + 清空当前 sessionId，下次 run 新建会话。
-        const hasDshHostChange = Object.keys(updates).some((k) => k === 'agents.dsh.host');
-        if (hasDshHostChange && this.config.defaultAgent === 'dsh' && !switchNotice) {
+        // DSH 的两个「会话边界」变更共用一套处理：preset 在 session 创建时固定，
+        // 中途切换会被服务端拒绝（agent-preset-conflict）；host 变更等于换服务，
+        // 旧 host 的 sessionId 发往新 host 是错的。两者都把旧 sessionId 停到
+        // previousSessions 恢复槽（可 /resume 校验后恢复）并清空当前值，下次 run
+        // 走 session.create 新建。已发生 agent 切换时（switchNotice 已设置）跳过，
+        // 避免覆盖切换 notice——切换分支对 dsh 的 session 已做恢复/清空处理。
+        const parkDshSessionBoundary = (changed, label) => {
+            if (!changed || this.config.defaultAgent !== 'dsh' || switchNotice)
+                return;
             const oldSessionId = this.sessionStore.getSessionId(ctx.userId, 'dsh');
             if (oldSessionId) {
                 this.sessionStore.setPreviousSessionId(ctx.userId, 'dsh', oldSessionId);
                 this.sessionStore.clearSessionId(ctx.userId, 'dsh');
-                switchNotice = `DSH host 已变更，旧会话已停放到恢复槽（可 /resume 校验后恢复），下次消息将新建会话`;
+                switchNotice = `DSH ${label} 已变更，旧会话已停放到恢复槽（可 /resume 校验后恢复），下次消息将新建会话`;
             }
             else {
-                switchNotice = `DSH host 已变更，下次消息将新建会话`;
+                switchNotice = `DSH ${label} 已变更，下次消息将新建会话`;
             }
-        }
+        };
+        parkDshSessionBoundary(changedKeys.includes('agents.dsh.agentPreset'), 'preset');
+        parkDshSessionBoundary(changedKeys.includes('agents.dsh.host'), 'host');
         // 2026-07-13: 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
         const currentAgent = this.config.defaultAgent;
-        const currentAgentConfigKey = `agents.${currentAgent}`;
-        const hasCurrentAgentUpdate = Object.keys(updates).some((k) => k === currentAgentConfigKey || k.startsWith(`${currentAgentConfigKey}.`));
-        if (hasCurrentAgentUpdate) {
+        if (touchesAgentsSubtree(changedKeys, currentAgent)) {
             this.config = syncAgentChoices(this.config, currentAgent);
             // agentChoices 同步写盘必须走原子写（tmp+rename），禁裸同步写盘
             atomicWrite(this.configPath, YAML.stringify(this.config));
@@ -2224,19 +2082,8 @@ export class CommandRouter {
         // duck method `updateApprovalMode` (codex thread/settings/update,
         // kimi/opencode session/set_mode) so they take effect for subsequent
         // turns without waiting for the runner to be recreated.
-        const hasApprovalConfigChange = Object.keys(updates).some((k) => k === 'agents.codex' ||
-            k.startsWith('agents.codex.') ||
-            k === 'codex' ||
-            k.startsWith('codex.') ||
-            k === 'agents.kimi' ||
-            k.startsWith('agents.kimi.') ||
-            k === 'kimi' ||
-            k.startsWith('kimi.') ||
-            k === 'agents.opencode' ||
-            k.startsWith('agents.opencode.') ||
-            k === 'opencode' ||
-            k.startsWith('opencode.') ||
-            k === 'agents.dsh.permissionPreset');
+        const hasApprovalConfigChange = ['codex', 'kimi', 'opencode'].some((kind) => touchesAgentConfig(changedKeys, kind)) ||
+            changedKeys.includes('agents.dsh.permissionPreset');
         if (hasApprovalConfigChange) {
             this.bridge.syncActiveApprovalModes();
         }
@@ -2449,14 +2296,14 @@ export class CommandRouter {
     cmdStatus(ctx) {
         const entry = this.sessionStore.get(ctx.userId);
         const cwd = entry?.cwd ?? '(未设置)';
-        const sessionId = entry?.sessions?.get(this.config.defaultAgent) ?? '(无)';
+        const sessionId = entry?.sessions.get(this.config.defaultAgent) ?? '(无)';
         // 查 bridge.activeRuns 而不是默认 runner.isRunning —— 因为 per-workspace
         // runner 启动的 run 不会反映到默认 runner 状态。
         const running = cwd !== '(未设置)' && this.bridge.isBusyFor(cwd);
         const logger = getLogger();
         const pid = process.pid;
         const configDir = getConfigDir();
-        const logFile = typeof logger.getCurrentLogFile === 'function' ? logger.getCurrentLogFile() : '';
+        const logFile = logger.getCurrentLogFile();
         // 构建 agent 状态信息
         const agentLines = [];
         if (cwd !== '(未设置)') {
@@ -2629,38 +2476,16 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         const currentCwd = this.sessionStore.getCwd(ctx.userId) ?? process.cwd();
         const expanded = target.startsWith('~') ? path.join(os.homedir(), target.slice(1)) : target;
         const resolved = path.resolve(currentCwd, expanded);
-        if (!fs.existsSync(resolved)) {
-            return { text: `路径不存在: ${resolved}` };
-        }
-        // TOCTOU：existsSync 与 statSync 之间路径被删时 statSync 抛错，会落进队列
-        // 任务的静默 catch（用户无反馈）——按路径无效回复，与下方 realpath 守卫同口径。
-        let stat;
-        try {
-            stat = fs.statSync(resolved);
-        }
-        catch {
-            return { text: `路径无效: ${resolved}` };
-        }
-        if (!stat.isDirectory()) {
-            return { text: `不是目录: ${resolved}` };
-        }
-        // Canonicalize via realpath so it matches the symlink-resolved cwd that
-        // Claude writes into JSONL (e.g. `/tmp` → `/private/tmp` on macOS).
-        // Without this, a hand-typed unresolved path never matches any JSONL's
-        // cwd field and the user's `/cd /tmp/foo` never finds their sessions.
-        // TOCTOU: the directory may vanish between stat and realpath.
-        // Reject gracefully instead of letting realpathSync throw into the queue
-        // task's .catch (which only logs — the user gets no feedback). Mirrors
-        // handleLsSwitch's realpath guard so /cd and ls.switch behave identically.
-        let canonical;
-        try {
-            canonical = fs.realpathSync(resolved);
-        }
-        catch {
+        const resolution = resolveDirectory(resolved);
+        if (!resolution.ok) {
+            if (resolution.reason === 'missing')
+                return { text: `路径不存在: ${resolved}` };
+            if (resolution.reason === 'not_directory')
+                return { text: `不是目录: ${resolved}` };
             return { text: `路径无效: ${resolved}` };
         }
         // Switch cwd with auto-resume and user feedback (shared with /ws use and ls.switch)
-        return this.switchCwdAndNotify(ctx.userId, canonical, ctx);
+        return this.switchCwdAndNotify(ctx.userId, resolution.canonical, ctx);
     }
     readSessionDisplayState(sessionId, cwd, opts) {
         // Use the appropriate session reader based on agentKind
@@ -2871,7 +2696,6 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
         return actions;
     }
-    static LS_PAGE_SIZE = 30;
     /**
      * `/ls` 实现（public：测试直接调用，替代 as unknown as）。
      *
@@ -2884,246 +2708,12 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      *                省略/空 = 无筛选。
      */
     cmdLs(args, ctx, offset = 0, rootDir, q) {
-        const cwd = this.sessionStore.getCwd(ctx.userId);
-        if (!cwd) {
-            return { text: '请先使用 /cd <path> 设置工作目录' };
-        }
-        const filter = q?.trim() || undefined;
-        // args can be:
-        // - [] : list current cwd
-        // - [dirName] : list subdirectory if it exists
-        let targetDir = cwd;
-        if (args[0]) {
-            // Expand tilde to home directory (path.resolve does not handle ~)
-            if (args[0].startsWith('~')) {
-                args[0] = path.join(os.homedir(), args[0].slice(1));
-            }
-            // path.resolve (not path.join) so absolute args[0] is honored as-is
-            // instead of being concatenated onto cwd (which broke /ls card nav).
-            const potentialDir = path.resolve(cwd, args[0]);
-            if (!fs.existsSync(potentialDir)) {
-                return { text: `ls: ${args[0]}: No such file or directory` };
-            }
-            let isDir;
-            try {
-                isDir = fs.statSync(potentialDir).isDirectory();
-            }
-            catch {
-                // TOCTOU：existsSync 与 statSync 之间目标被删
-                return { text: `ls: ${args[0]}: No such file or directory` };
-            }
-            if (!isDir) {
-                // 命中文件：列出该文件本身（用户可能想下载它或确认是否存在），
-                // 不再回 `ls: xxx: Not a directory` 把文件路径当错误。
-                return this.buildFileCard(potentialDir);
-            }
-            targetDir = potentialDir;
-        }
-        // 浏览起点（「返回」按钮的目标）：`/ls <dir>` 的起点就是该目录本身，之后
-        // 进入子目录/翻页/刷新时由卡片 payload 的 root 一路带过来。省略时 = 本次
-        // 列出的目录，因此「返回」永远不会把用户丢回工作目录。
-        const browseRoot = rootDir ? path.resolve(cwd, rootDir) : targetDir;
-        try {
-            const entries = fs.readdirSync(targetDir, { withFileTypes: true });
-            // 逐条目分类。`Dirent.isFile()/isDirectory()` 对符号链接恒 false（旧实现
-            // 因此完全不列链接）；必须 stat 解析目标。单条目 stat 失败（悬空链接、
-            // readdir 与 stat 之间被删、无权限）只让该条目降级为「大小未知」，不能
-            // 让整次列目录失败——一个坏邻居毁掉整张卡是旧实现的第二宗罪。
-            const dirs = [];
-            const files = [];
-            for (const entry of entries) {
-                let isDir = entry.isDirectory();
-                let size;
-                if (!isDir) {
-                    try {
-                        const st = fs.statSync(path.join(targetDir, entry.name));
-                        isDir = st.isDirectory();
-                        if (!isDir)
-                            size = st.size;
-                    }
-                    catch {
-                        // 目标拿不到：按文件列出，size 留空
-                    }
-                }
-                if (isDir)
-                    dirs.push(entry.name);
-                else
-                    files.push({ name: entry.name, size });
-            }
-            dirs.sort((a, b) => a.localeCompare(b));
-            files.sort((a, b) => a.name.localeCompare(b.name));
-            // Merge dirs and files for pagination, preserving type info
-            const allItems = [
-                ...dirs.map((name) => ({ name, isDir: true })),
-                ...files.map((f) => ({ name: f.name, isDir: false, size: f.size })),
-            ];
-            // 关键词筛选：只匹配当前层条目名（不递归子目录）。大小写不敏感的子串包含
-            // ——禁止 new RegExp(q)（用户搜 `foo(` 会直接抛）。插在排序之后、分页之前。
-            const ql = filter?.toLowerCase();
-            const visibleItems = ql
-                ? allItems.filter((i) => i.name.toLowerCase().includes(ql))
-                : allItems;
-            const visibleDirCount = visibleItems.reduce((n, i) => n + (i.isDir ? 1 : 0), 0);
-            const visibleFileCount = visibleItems.length - visibleDirCount;
-            // Pagination calculations（clamp 到最后一页边界，原先不 clamp 会显示空页）
-            const { totalCount, totalPages, safeOffset, currentPage, pageItems, hasPagination } = pageSlice(visibleItems, offset, CommandRouter.LS_PAGE_SIZE);
-            // Check if we need to show parent directory button
-            const parentDir = path.dirname(targetDir);
-            const hasParent = parentDir !== targetDir;
-            // 「切换」相对 cwd（把工作目录切到当前浏览目录）
-            const isSubdir = targetDir !== cwd;
-            // 「返回」相对浏览起点：在 `/ls <dir>` 的起点上不显示（无路可返）
-            const canReturn = targetDir !== browseRoot;
-            // Build header with parent button
-            const headerElements = [];
-            if (hasParent) {
-                headerElements.push(cardButton('上级', { cmd: 'ls.browse', path: parentDir, root: browseRoot }, { type: 'default', size: 'small' }));
-            }
-            // Show "返回" button when browsing away from the /ls root (回到 /ls 指定的目录)
-            if (canReturn) {
-                headerElements.push(cardButton('返回', { cmd: 'ls.browse', path: browseRoot, root: browseRoot }, { type: 'default', size: 'small' }));
-            }
-            headerElements.push(cardButton('刷新', {
-                cmd: 'ls.refresh',
-                path: targetDir,
-                offset: safeOffset,
-                root: browseRoot,
-                ...(filter ? { q: filter } : {}),
-            }, { type: 'default', size: 'small' }));
-            // Show "切换" button when viewing a subdirectory (to switch cwd to this directory)
-            if (isSubdir) {
-                headerElements.push(
-                // 切换只改 cwd，**不重置浏览起点**：root 一路带到切换后的卡片，
-                // 否则「返回」会退化成「回到刚切换到的目录」（用户反馈的缺陷）。
-                cardButton('切换', { cmd: 'ls.switch', path: targetDir, root: browseRoot }, { type: 'primary', size: 'small' }));
-            }
-            // Helper to create directory button - use targetDir
-            const dirButton = (name) => cardButton(`📁 ${name}`, { cmd: 'ls.browse', path: path.join(targetDir, name), root: browseRoot }, { type: 'default' });
-            // Helper to create file button with size - use targetDir
-            const fileButton = (name, size) => {
-                const sizeStr = size !== undefined ? ` (${formatBytes(size)})` : '';
-                return cardButton(`📄 ${name}${sizeStr}`, { cmd: 'ls.file', path: path.join(targetDir, name) }, { type: 'default', size: 'small' });
-            };
-            // Build each section's elements (no tabs - use section headers)
-            // Note: div+elements is not supported in CardKit 2.0, use column_set instead
-            const elements = [];
-            // Status line：只报条目构成；页码/总数交给分页栏文案行（同一信息不重复
-            // 渲染两遍——2026-09-10 分页栏改成整行文案后重复会很明显）。筛选态一律用
-            // 过滤后的计数，否则标题说 12 项、列表只有 3 项，卡片自相矛盾。
-            const status = `\n共 ${visibleDirCount} 目录, ${visibleFileCount} 文件`;
-            // Header info + navigation buttons - show targetDir in header
-            elements.push({ tag: 'div', text: { tag: 'lark_md', content: `\`${targetDir}\`${status}` } });
-            elements.push({
-                tag: 'column_set',
-                columns: headerElements.map((e) => ({ tag: 'column', width: 'auto', elements: [e] })),
-            });
-            elements.push({ tag: 'hr' });
-            // 搜索行：头部导航按钮之下、内容区之上（主导航在上、过滤紧随其后、内容区
-            // 在下）。path/root 必须进 callback value，否则提交后 handler 不知道刷哪。
-            elements.push(searchBar({
-                cmd: 'ls.filter',
-                placeholder: '搜索本层目录/文件名，输完回车',
-                currentQuery: filter,
-                extra: { path: targetDir, root: browseRoot },
-            }));
-            if (filter) {
-                elements.push({
-                    tag: 'div',
-                    text: {
-                        tag: 'lark_md',
-                        content: `🔍 筛选："${filter}" · 命中 ${totalCount} 项（点「清除筛选」取消）`,
-                    },
-                });
-            }
-            // Section 1 + 2: Directories / Files (show only items on current page)
-            const pageDirs = pageItems.filter((i) => i.isDir);
-            const pageFiles = pageItems.filter((i) => !i.isDir);
-            if (filter && visibleItems.length === 0) {
-                // 筛选零命中：两个区标题都不渲染（两行空区标题只是噪音），搜索行仍在，
-                // 用户可直接改词再回车，或点「清除筛选」。
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `🔍 无匹配条目（关键词："${filter}"）` },
-                });
-            }
-            else {
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `**📂 目录 (${visibleDirCount})**` },
-                });
-                if (pageDirs.length > 0) {
-                    for (const d of pageDirs) {
-                        elements.push({
-                            tag: 'column_set',
-                            flex_mode: 'none',
-                            columns: [{ tag: 'column', width: 'auto', elements: [dirButton(d.name)] }],
-                        });
-                    }
-                }
-                else if (visibleDirCount === 0) {
-                    elements.push({ tag: 'div', text: { tag: 'lark_md', content: '无子目录' } });
-                }
-                else {
-                    elements.push({
-                        tag: 'div',
-                        text: { tag: 'lark_md', content: `（第 ${currentPage} 页无目录）` },
-                    });
-                }
-                elements.push({ tag: 'hr' });
-                // Section 2: Files
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `**📄 文件 (${visibleFileCount})**` },
-                });
-                if (pageFiles.length > 0) {
-                    for (const f of pageFiles) {
-                        elements.push({
-                            tag: 'column_set',
-                            flex_mode: 'none',
-                            columns: [{ tag: 'column', width: 'auto', elements: [fileButton(f.name, f.size)] }],
-                        });
-                    }
-                }
-                else if (visibleFileCount === 0) {
-                    elements.push({ tag: 'div', text: { tag: 'lark_md', content: '无文件' } });
-                }
-                else {
-                    elements.push({
-                        tag: 'div',
-                        text: { tag: 'lark_md', content: `（第 ${currentPage} 页无文件）` },
-                    });
-                }
-            }
-            // Pagination bar (only shown when there are more items than PAGE_SIZE)
-            if (hasPagination) {
-                const bar = paginationBar({
-                    cmd: 'ls.page',
-                    offset: safeOffset,
-                    pageSize: CommandRouter.LS_PAGE_SIZE,
-                    total: totalCount,
-                    extra: { path: targetDir, root: browseRoot, ...(filter ? { q: filter } : {}) },
-                    label: `**第 ${currentPage}/${totalPages} 页**（共 ${totalCount} 项）`,
-                });
-                elements.push({ tag: 'hr' });
-                elements.push(...bar);
-            }
-            return {
-                card: {
-                    schema: '2.0',
-                    config: { wide_screen_mode: true, update_multi: true },
-                    header: {
-                        title: { tag: 'plain_text', content: `📁 ${path.basename(targetDir)}` },
-                        template: 'blue',
-                    },
-                    body: {
-                        elements,
-                    },
-                },
-            };
-        }
-        catch (err) {
-            return { text: `读取目录失败: ${err.message}` };
-        }
+        return buildLsCommand(args, ctx, {
+            cwd: this.sessionStore.getCwd(ctx.userId),
+            offset,
+            rootDir,
+            q,
+        });
     }
     /**
      * `/download <path>`（别名 `/d`）：把本地文件直接发送到飞书。
@@ -3149,283 +2739,18 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
         return this.deliverFileToFeishu(path.resolve(input), ctx);
     }
-    /**
-     * 单文件 ls 结果卡：路径 / 大小 / 修改时间 + 「下载」+「上级」。
-     *
-     * `/ls <file>` 命中普通文件时使用——用户可能想下载该文件或确认它是否存在，
-     * 此前直接回 `ls: xxx: Not a directory` 把文件路径当成错误处理。
-     */
-    buildFileCard(filePath) {
-        let stat;
-        try {
-            stat = fs.statSync(filePath);
-        }
-        catch {
-            stat = undefined;
-        }
-        const sizeText = stat ? formatBytes(stat.size) : '未知';
-        const mtimeText = stat ? stat.mtime.toLocaleString('zh-CN', { hour12: false }) : '未知';
-        const parentDir = path.dirname(filePath);
-        const buttons = [
-            cardButton('📎 下载', { cmd: 'ls.file', path: filePath }, { type: 'primary', size: 'small' }),
-        ];
-        if (parentDir !== filePath) {
-            buttons.push(
-            // 浏览起点 = 文件所在目录：进入后「返回」回到这里，不回 工作目录
-            cardButton('上级', { cmd: 'ls.browse', path: parentDir, root: parentDir }, { type: 'default', size: 'small' }));
-        }
-        return {
-            card: {
-                schema: '2.0',
-                config: { wide_screen_mode: true, update_multi: true },
-                header: {
-                    title: { tag: 'plain_text', content: `📄 ${path.basename(filePath)}` },
-                    template: 'blue',
-                },
-                body: {
-                    elements: [
-                        {
-                            tag: 'div',
-                            text: {
-                                tag: 'lark_md',
-                                content: `\`${filePath}\`\n文件 · 大小 ${sizeText} · 修改时间 ${mtimeText}`,
-                            },
-                        },
-                        {
-                            tag: 'column_set',
-                            columns: buttons.map((b) => ({ tag: 'column', width: 'auto', elements: [b] })),
-                        },
-                        { tag: 'hr' },
-                        {
-                            tag: 'div',
-                            text: { tag: 'lark_md', content: '💡 也可用 `/download <path>` 直接下载该文件' },
-                        },
-                    ],
-                },
-            },
-        };
-    }
-    /**
-     * `/ws` 实现（public：测试直接调用，替代 as unknown as，与 cmdLs 同款）。
-     *
-     * @param offset list 分支的分页起点（条目数）
-     * @param q      list 分支的关键词筛选：name 或完整 path 命中即保留，大小写
-     *               不敏感。省略/空 = 无筛选。
-     */
     cmdWs(args, ctx, offset = 0, q) {
-        const sub = args[0]?.toLowerCase();
-        switch (sub) {
-            case 'save': {
-                const name = args[1];
-                if (!name)
-                    return { text: '用法: /ws save <name>' };
-                const cwd = this.sessionStore.getCwd(ctx.userId);
-                if (!cwd)
-                    return { text: '请先 /cd 设置工作目录' };
-                this.workspaceStore.save(name, cwd);
-                return { text: `已保存 workspace "${name}" -> ${cwd}` };
-            }
-            case 'use': {
-                const name = args[1];
-                if (!name)
-                    return { text: '用法: /ws use <name>' };
-                const wsPath = this.workspaceStore.get(name);
-                if (!wsPath)
-                    return { text: `workspace "${name}" 不存在` };
-                if (!fs.existsSync(wsPath))
-                    return { text: `路径不存在: ${wsPath}` };
-                // 目录校验与 /cd、ls.switch 对齐：目录被删后同路径出现同名文件（或
-                // workspace.json 被手改）时 realpath 照样成功——放行会让下一次 run
-                // 以文件为 cwd spawn（ENOTDIR）。
-                if (!isDirectorySafe(wsPath))
-                    return { text: `不是目录: ${wsPath}` };
-                // Canonicalize via realpath so it matches Claude JSONL cwd (2026-06-21).
-                // TOCTOU guard: mirror cmdCd — if the path vanishes
-                // between existsSync and realpath, reply gracefully instead of
-                // throwing into the queue task's silent .catch.
-                let canonical;
-                try {
-                    canonical = fs.realpathSync(wsPath);
-                }
-                catch {
-                    return { text: `路径无效: ${wsPath}` };
-                }
-                // Record usage timestamp AFTER successful path validation
-                this.workspaceStore.touch(name);
-                // Switch cwd with auto-resume and user feedback (shared with /cd and ls.switch)
-                return this.switchCwdAndNotify(ctx.userId, canonical, ctx);
-            }
-            case 'remove': {
-                const name = args[1];
-                if (!name)
-                    return { text: '用法: /ws remove <name>' };
-                if (!this.workspaceStore.has(name))
-                    return { text: `workspace "${name}" 不存在` };
-                this.workspaceStore.remove(name);
-                return { text: `已删除 workspace "${name}"` };
-            }
-            case 'list':
-            default: {
-                const filter = q?.trim() || undefined;
-                const entries = this.workspaceStore.list();
-                const currentCwd = this.sessionStore.getCwd(ctx.userId);
-                const sortMode = this.wsSortPreference.get(ctx.userId) ?? 'recent';
-                // Sort entries by the current preference (view concern, not stored)
-                if (sortMode === 'recent') {
-                    // Most recently used first; same lastUsedAt → alphabetical by name (deterministic)
-                    entries.sort((a, b) => {
-                        if (b.lastUsedAt !== a.lastUsedAt)
-                            return b.lastUsedAt - a.lastUsedAt;
-                        return a.name.localeCompare(b.name);
-                    });
-                }
-                else {
-                    // Alphabetical by alias name
-                    entries.sort((a, b) => a.name.localeCompare(b.name));
-                }
-                // 关键词筛选：alias name 或完整 path 命中即保留，大小写不敏感的子串包含
-                // （禁止 new RegExp(q)——用户搜 `foo(` 会直接抛）。插在排序之后、分页
-                // 之前：先分页再过滤会出现某页只剩 1 条的残页，且翻页时筛选像是丢了。
-                const ql = filter?.toLowerCase();
-                const visible = ql
-                    ? entries.filter((e) => e.name.toLowerCase().includes(ql) || e.path.toLowerCase().includes(ql))
-                    : entries;
-                // Pagination calculations (mirror cmdOrder): clamp stale/out-of-range
-                // offsets so prev/next always step by WS_PAGE_SIZE.
-                const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(visible, offset, WS_PAGE_SIZE);
-                // Build body elements: current cwd + cwd list with dividers
-                const bodyElements = [];
-                // Current working directory section
-                bodyElements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `📂 当前工作目录：\`${currentCwd ?? '(未设置)'}\`` },
-                });
-                bodyElements.push({ tag: 'hr' });
-                // 搜索行：「当前工作目录」之下、排序行之上（与 /ls 同一视觉动线：主信息
-                // 在上、过滤紧随其后、列表在下）
-                bodyElements.push(searchBar({
-                    cmd: 'ws.filter',
-                    placeholder: '搜索名称或路径，输完回车',
-                    currentQuery: filter,
-                }));
-                if (filter) {
-                    bodyElements.push({
-                        tag: 'div',
-                        text: {
-                            tag: 'lark_md',
-                            content: `🔍 筛选："${filter}" · 命中 ${totalCount} 个 workspace（点「清除筛选」取消）`,
-                        },
-                    });
-                }
-                if (entries.length === 0 && !filter) {
-                    bodyElements.push({
-                        tag: 'div',
-                        text: { tag: 'lark_md', content: '没有保存的 workspace' },
-                    });
-                }
-                else if (filter && visible.length === 0) {
-                    bodyElements.push({
-                        tag: 'div',
-                        text: { tag: 'lark_md', content: `🔍 无匹配条目（关键词："${filter}"）` },
-                    });
-                }
-                else {
-                    // Sort mode indicator + toggle button: placed above the list so the user
-                    // sees "current mode" and "switch to X" before scanning entries.
-                    // On narrow (mobile) screens, the label and button must convey both
-                    // what-is-active and what-clicking-does to avoid ambiguity.
-                    const currentLabel = sortMode === 'recent' ? '🕐 最近使用' : '🔤 字母顺序';
-                    const switchLabel = sortMode === 'recent' ? '🔤 字母顺序' : '🕐 最近使用';
-                    bodyElements.push({ tag: 'hr' });
-                    bodyElements.push({
-                        tag: 'column_set',
-                        columns: [
-                            {
-                                tag: 'column',
-                                width: 'weighted',
-                                weight: 1,
-                                vertical_align: 'center',
-                                elements: [
-                                    {
-                                        tag: 'div',
-                                        text: { tag: 'lark_md', content: `排序：${currentLabel}` },
-                                    },
-                                ],
-                            },
-                            {
-                                tag: 'column',
-                                width: 'auto',
-                                elements: [
-                                    cardButton(`切换为 ${switchLabel}`, { cmd: 'ws.sort', ...(filter ? { q: filter } : {}) }, { type: 'default', size: 'small' }),
-                                ],
-                            },
-                        ],
-                    });
-                    bodyElements.push({ tag: 'hr' });
-                    for (const entry of pageEntries) {
-                        bodyElements.push({
-                            tag: 'div',
-                            text: { tag: 'lark_md', content: `**${entry.name}** → \`${entry.path}\`` },
-                        });
-                        // Use column_set+column for 2.0 (action tag not supported in 2.0)
-                        bodyElements.push({
-                            tag: 'column_set',
-                            columns: [
-                                {
-                                    tag: 'column',
-                                    width: 'auto',
-                                    elements: [
-                                        cardButton('切换', {
-                                            cmd: 'ws.use',
-                                            name: entry.name,
-                                            offset: safeOffset,
-                                            ...(filter ? { q: filter } : {}),
-                                        }, { type: 'primary', size: 'small' }),
-                                    ],
-                                },
-                                {
-                                    tag: 'column',
-                                    width: 'auto',
-                                    elements: [
-                                        cardButton('删除', {
-                                            cmd: 'ws.remove',
-                                            name: entry.name,
-                                            offset: safeOffset,
-                                            ...(filter ? { q: filter } : {}),
-                                        }, { type: 'danger', size: 'small' }),
-                                    ],
-                                },
-                            ],
-                        });
-                        bodyElements.push({ tag: 'hr' });
-                    }
-                    bodyElements.pop();
-                    // Pagination bar — separate row below the list (not crowded with sort
-                    // toggle; mobile-friendly vertical layout).
-                    if (hasPagination) {
-                        const bar = paginationBar({
-                            cmd: 'ws.page',
-                            offset: safeOffset,
-                            pageSize: WS_PAGE_SIZE,
-                            total: totalCount,
-                            extra: filter ? { q: filter } : {},
-                            label: `**${currentPage}/${totalPages}**（${totalCount}）`,
-                            prevText: '⬅',
-                            nextText: '➡',
-                        });
-                        bodyElements.push({ tag: 'hr' });
-                        bodyElements.push(...bar);
-                    }
-                }
-                const card = {
-                    schema: '2.0',
-                    config: { wide_screen_mode: true, update_multi: true },
-                    header: { title: { tag: 'plain_text', content: 'Workspaces' } },
-                    body: { elements: bodyElements },
-                };
-                return { card };
-            }
-        }
+        return buildWsCommand(args, ctx, offset, q, {
+            getCwd: (userId) => this.sessionStore.getCwd(userId),
+            saveWorkspace: (name, cwd) => this.workspaceStore.save(name, cwd),
+            getWorkspace: (name) => this.workspaceStore.get(name),
+            hasWorkspace: (name) => this.workspaceStore.has(name),
+            removeWorkspace: (name) => this.workspaceStore.remove(name),
+            touchWorkspace: (name) => this.workspaceStore.touch(name),
+            listWorkspaces: () => this.workspaceStore.list(),
+            getSortMode: (userId) => this.wsSortPreference.get(userId) ?? 'recent',
+            switchCwd: (userId, cwd, actionCtx) => this.switchCwdAndNotify(userId, cwd, actionCtx),
+        });
     }
     /**
      * DSH /resume preset 一致性校验：返回 mismatch 详情，或 undefined（一致/不可判定）。
@@ -3454,286 +2779,17 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         return { sessionPreset, currentPreset };
     }
     cmdResume(args, ctx, offset = 0) {
-        const entry = this.sessionStore.get(ctx.userId);
-        const cwd = entry?.cwd;
-        // Valid agent kinds for the /resume [agent] [N] feature
-        const VALID_AGENTS = CommandRouter.VALID_AGENTS;
-        // Parse arguments: /resume [agent] [N] or /resume [sessionId] or /resume [agent] [sessionId]
-        let agentKind = this.config.defaultAgent;
-        let limit;
-        let sessionIdArg;
-        if (args[0]) {
-            if (VALID_AGENTS.includes(args[0])) {
-                agentKind = args[0];
-                if (args[1]) {
-                    if (/^\d+$/.test(args[1])) {
-                        limit = parseInt(args[1], 10);
-                    }
-                    else {
-                        sessionIdArg = args[1];
-                    }
-                }
-            }
-            else if (/^\d+$/.test(args[0])) {
-                limit = parseInt(args[0], 10);
-            }
-            else {
-                sessionIdArg = args[0];
-            }
-        }
-        // `/resume <sessionId>` — manually set session id (needs an existing cwd to bind to)
-        if (sessionIdArg) {
-            if (!entry || !cwd)
-                return { text: '请先 /cd 设置工作目录' };
-            const reader = agentKind !== this.config.defaultAgent
-                ? this.sessionReaderRegistry.get(agentKind)
-                : this.sessionReader;
-            const verifyContent = reader.readSessionContent(sessionIdArg, cwd);
-            // If session doesn't exist, reject the write
-            if (verifyContent.events.length === 0 &&
-                !verifyContent.usage &&
-                !verifyContent.aiTitle &&
-                !verifyContent.recap &&
-                !verifyContent.displayTitle) {
-                return {
-                    text: `未找到 session ${sessionIdArg}（当前目录: ${cwd}）。请确认该 session 属于此目录，或先 /cd 到正确目录。`,
-                };
-            }
-            // DSH preset 一致性校验（§6 风险 1）：session 的 preset 在创建时固定，
-            // 若与当前配置不符，直接复用会让后续 run 报 agent-preset-conflict。
-            // 不静默复用——明确提示用户，由用户决定是否继续（配置里手动改/清 preset）。
-            if (agentKind === 'dsh' && this.config.defaultAgent === 'dsh') {
-                const presetMismatch = this.dshPresetMismatch(reader, sessionIdArg, cwd);
-                if (presetMismatch) {
-                    return {
-                        text: `⚠️ 该 DSH session 的 preset 是「${presetMismatch.sessionPreset}」，与当前配置「${presetMismatch.currentPreset}」不一致。\n` +
-                            `preset 在 session 创建时固定，无法中途切换（DSH 返回 agent-preset-conflict）。\n` +
-                            `继续恢复将在下次 run 失败。请在 /config 中把预设模式改回「${presetMismatch.sessionPreset}」后重试，或保持当前配置并发新消息新建会话。`,
-                    };
-                }
-            }
-            // 校验通过后才写入
-            this.sessionStore.setSessionId(ctx.userId, agentKind, sessionIdArg, cwd);
-            const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(sessionIdArg, cwd, {
-                agentKind,
-                maxEvents: AUTO_RESUME_MAX_EVENTS,
-            });
-            // Action buttons: stop (active) + compact (capable runner, not running) + new session
-            const actions = this.buildResumeActionButtons({
-                isActive,
-                activeRunRunId,
-                cwd,
-                compact: this.canCompactSession(agentKind, cwd)
-                    ? { sessionId: sessionIdArg, agentKind }
-                    : undefined,
-                newSession: true,
-            });
-            const card = buildSessionHistoryCard({
-                sessionId: sessionIdArg,
-                cwd,
-                displayTitle,
-                aiTitle,
-                recap,
-                events: content,
-                usage,
-            }, {
-                agentKind,
-                headerText: `📂 \`${cwd}\`\n会话: **${sessionIdArg}**`,
-                title: `${isActive ? '⏳ 恢复会话（完成中）' : '🔁 恢复会话'} · ${agentDisplayName(agentKind)}`,
-                usageResult: 'success',
-                emptyPlaceholder: '_该会话暂无新消息可显示（最后一条为用户输入）_',
-                actions,
-            });
-            return { card };
-        }
-        // `/resume` or `/resume list` or `/resume <N>` — list sessions for the current cwd as a card
-        // Use agentKind to select the appropriate sessionReader
-        if (!cwd)
-            return { text: '请先 /cd 设置工作目录' };
-        const pageSize = clampInt(limit ?? RESUME_PAGE_SIZE, 1, RESUME_PAGE_SIZE);
-        let reader;
-        // Use this.sessionReader when agentKind matches default, otherwise get from registry
-        if (agentKind === this.config.defaultAgent) {
-            reader = this.sessionReader;
-        }
-        else {
-            reader = this.sessionReaderRegistry.get(agentKind);
-        }
-        // Fetch the requested page. If the offset is stale (sessions added/removed
-        // since the page was rendered), clamp it to the last valid page start and
-        // re-fetch so the card never shows a misaligned/empty page.
-        let pageOffset = offset;
-        let pageResult;
-        try {
-            pageResult = reader.listSessions(cwd, { limit: pageSize, offset: pageOffset });
-            // 末页起点对齐页边界（(总页数-1)*pageSize，如 25 条/页 20 → offset 20），
-            // 这样越界 offset clamp 后 prev/next 仍按 pageSize 步长移动，不会错位。
-            const maxOffset = Math.max(0, Math.ceil(pageResult.total / pageSize) - 1) * pageSize;
-            if (pageOffset < 0 || pageOffset > maxOffset) {
-                pageOffset = clampInt(pageOffset, 0, maxOffset);
-                pageResult = reader.listSessions(cwd, { limit: pageSize, offset: pageOffset });
-            }
-        }
-        catch (err) {
-            // 读取失败必须给用户可见反馈，而不是误导性的「没有 session 记录」
-            const msg = err instanceof Error ? err.message : String(err);
-            return { text: `读取 ${agentDisplayName(agentKind)} session 列表失败: ${msg}` };
-        }
-        const { sessions: allSessions, total } = pageResult;
-        if (allSessions.length === 0) {
-            const agentName = agentDisplayName(agentKind);
-            const hint = agentKind === this.config.defaultAgent
-                ? `\n提示：可使用 /resume <agent> 切换查看其他 Agent 的 session`
-                : '';
-            return { text: `当前目录没有 ${agentName} session 记录\n${cwd}${hint}` };
-        }
-        // Pre-fetch aiTitle/recap/displayTitle only for the first few rows —
-        // full reads are expensive (whole-file JSONL scan). Remaining rows fall
-        // back to the lightweight summary already returned by listSessions.
-        const sessionMeta = new Map();
-        const prefetchCount = Math.min(RESUME_CONTENT_PREFETCH, allSessions.length);
-        for (const s of allSessions.slice(0, prefetchCount)) {
-            // 行上已经带了服务端投影预览（DSH：title + turnOutline 末条）→ 跳过预取。
-            // DSH 的 readSessionContent 每行走 3 次 unary：`session/list`（cwd 守卫）、
-            // `session/projections`（取 throughSeq）、再 `session/page`（maxMessages=10000，
-            // 拉整段历史）。按前 5 行预取等于 15 次同步 HTTP，而这些信息一次
-            // `session/list` 就已经给全了。
-            if (s.title || s.lastUserMessage || s.lastAssistantMessage)
-                continue;
-            // 优先走轻量摘要（只取标题/用量，不构造 events）——codex 实现了
-            // readSessionSummary，避免对前 N 条各做一次全量 JSONL 解析来构造
-            // 立即被丢弃的 events 数组。其他 agent 无此方法时回退全量读取再取字段。
-            const meta = reader.readSessionSummary
-                ? reader.readSessionSummary(s.sessionId, cwd)
-                : (() => {
-                    const c = reader.readSessionContent(s.sessionId, cwd);
-                    return { aiTitle: c.aiTitle, recap: c.recap, displayTitle: c.displayTitle };
-                })();
-            sessionMeta.set(s.sessionId, {
-                aiTitle: meta.aiTitle,
-                recap: meta.recap,
-                displayTitle: meta.displayTitle,
-            });
-        }
-        const now = Date.now();
-        function formatRelativeTime(mtimeMs) {
-            const diffSec = Math.floor((now - mtimeMs) / 1000);
-            if (diffSec < 60)
-                return '刚刚';
-            if (diffSec < 3600)
-                return `${Math.floor(diffSec / 60)} 分钟前`;
-            if (diffSec < 86400)
-                return `${Math.floor(diffSec / 3600)} 小时前`;
-            if (diffSec < 604800)
-                return `${Math.floor(diffSec / 86400)} 天前`;
-            return new Date(mtimeMs).toLocaleDateString('zh-CN');
-        }
-        const elements = [
-            {
-                tag: 'div',
-                text: { tag: 'lark_md', content: `📂 当前工作目录：\`${cwd}\`` },
-            },
-        ];
-        // Get current sessionId for the agent being listed
-        const currentId = entry?.sessions?.get(agentKind) ?? '';
-        for (const s of allSessions) {
-            // Only mark as current if we're listing the defaultAgent's sessions
-            const isCurrent = agentKind === this.config.defaultAgent && s.sessionId === currentId;
-            const timeStr = formatRelativeTime(s.mtime);
-            const buttonText = isCurrent ? '✓ 当前会话' : '恢复此会话';
-            const meta = sessionMeta.get(s.sessionId);
-            // Title priority:
-            // 1. 行级 title（服务端投影，DSH）→ 「标题」。
-            // 2. Prefetched displayTitle (aiTitle or last user message) keeps its
-            //    original label (AI 标题 / 最近输入).
-            // 3. Otherwise the lightweight summary renders under the neutral
-            //    "会话摘要" label — summary is the first user message, not the
-            //    last input, so "最近输入" would be semantically wrong.
-            // 4. Placeholder summaries (no user message) render no title section
-            //    at all — never leak '(无摘要)'/'(no user message)'/'New Session'.
-            const summaryIsPlaceholder = RESUME_SUMMARY_PLACEHOLDERS.has(s.summary.trim());
-            const prefetchedTitle = meta?.displayTitle;
-            // 行级 title 也过占位符过滤：DSH 对空会话可能给 "New Session"，旧路径
-            // 的 summary 会被挡掉，新路径如果不过滤就会把它当真实标题渲染。
-            const rowTitleRaw = s.title?.trim() ?? '';
-            const rowTitle = rowTitleRaw && !RESUME_SUMMARY_PLACEHOLDERS.has(rowTitleRaw) ? rowTitleRaw : undefined;
-            // aiTitle 不能单独作为"预取标题"键：若 displayTitle 缺失（理论上 opencode
-            // info.title 非空但 export 无 user text），标题兜底是 summary，label 必须
-            // 是中性"会话摘要"而不是"最近输入"（Review 边缘分支）。
-            const titleText = prefetchedTitle ?? rowTitle ?? (summaryIsPlaceholder ? '' : s.summary);
-            const titleLabel = prefetchedTitle
-                ? meta?.aiTitle
-                    ? 'AI 标题'
-                    : '最近输入'
-                : rowTitle
-                    ? '标题'
-                    : summaryIsPlaceholder
-                        ? ''
-                        : '会话摘要';
-            const sections = [];
-            if (titleText) {
-                sections.push(`🏷️ **${titleLabel}**\n${titleText.slice(0, 80)}${titleText.length > 80 ? '...' : ''}`);
-            }
-            if (meta?.recap) {
-                sections.push(`📝 **Recap**\n${meta.recap.slice(0, 60)}${meta.recap.length > 60 ? '...' : ''}`);
-            }
-            // 行级预览（DSH 服务端投影）：最后一句我说了什么 / 最后一句它答了什么。
-            // 只对提供了字段的 reader 渲染，其他 agent 的卡片一个字都不变。
-            if (s.lastUserMessage) {
-                sections.push(`✏️ **最近输入**\n${sessionPreviewLine(s.lastUserMessage, RESUME_PREVIEW_MAX)}`);
-            }
-            if (s.lastAssistantMessage) {
-                sections.push(`📤 **最后输出**\n${sessionPreviewLine(s.lastAssistantMessage, RESUME_PREVIEW_MAX)}`);
-            }
-            const infoStr = sections.length > 0 ? '\n' + sections.join('\n──\n') : '';
-            elements.push({ tag: 'hr' });
-            // Both current and non-current sessions get a button for visual consistency
-            elements.push({
-                tag: 'div',
-                text: {
-                    tag: 'lark_md',
-                    content: `**${s.sessionId}**${infoStr}\n⏱ ${timeStr}${isCurrent ? '  •' : ''}`,
-                },
-            });
-            elements.push({
-                tag: 'column_set',
-                columns: [
-                    {
-                        tag: 'column',
-                        width: 'auto',
-                        elements: [
-                            cardButton(buttonText, { cmd: 'resume.use', sessionId: s.sessionId, agent: agentKind }, { type: isCurrent ? 'default' : 'primary', disabled: isCurrent }),
-                        ],
-                    },
-                ],
-            });
-        }
-        // Pagination bar (only shown when there are more sessions than pageSize)
-        if (total > pageSize) {
-            const { totalPages, currentPage } = pageInfo(total, pageOffset, pageSize);
-            const bar = paginationBar({
-                cmd: 'resume.page',
-                offset: pageOffset,
-                pageSize,
-                total,
-                extra: { agent: agentKind, pageSize },
-                label: `第 ${currentPage}/${totalPages} 页 · 共 ${total} 个会话`,
-            });
-            elements.push({ tag: 'hr' });
-            elements.push(...bar);
-        }
-        const card = {
-            schema: '2.0',
-            config: { wide_screen_mode: true },
-            header: {
-                title: {
-                    tag: 'plain_text',
-                    content: `🔁 恢复历史会话 · ${agentDisplayName(agentKind)}`,
-                },
-            },
-            body: { elements },
-        };
-        return { card };
+        return buildResumeCommand(args, ctx, offset, {
+            defaultAgent: this.config.defaultAgent,
+            getSessionEntry: (userId) => this.sessionStore.get(userId),
+            setSessionId: (userId, agent, sessionId, cwd) => this.sessionStore.setSessionId(userId, agent, sessionId, cwd),
+            defaultReader: () => this.sessionReader,
+            readerFor: (agent) => this.sessionReaderRegistry.get(agent),
+            dshPresetMismatch: (reader, sessionId, cwd) => this.dshPresetMismatch(reader, sessionId, cwd),
+            readDisplay: (sessionId, cwd, opts) => this.readSessionDisplayState(sessionId, cwd, opts),
+            buildActions: (opts) => this.buildResumeActionButtons(opts),
+            canCompact: (agent, cwd) => this.canCompactSession(agent, cwd),
+        });
     }
     cmdActive(_args, _ctx, offset = 0) {
         // List all active runs from lark-remote memory (not from file system scan)
@@ -3957,216 +3013,17 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         // 使用共享渲染模块构建卡片（Agent 选择器作为普通 select 字段参与渲染）
         return { card: buildConfigCardFromTabs(tabs, displayConfig) };
     }
-    /** /order 实现（public：测试直接调用，替代 as unknown as）。 */
-    cmdOrder(args, _ctx, offset = 0) {
-        const sub = args[0]?.toLowerCase();
-        // /order — list orders (CardKit 2.0 with pagination)
-        if (!sub || sub === 'list') {
-            this.orderStore.reload();
-            const allOrders = this.orderStore.get();
-            const elements = [];
-            if (allOrders.length === 0) {
-                elements.push({ tag: 'div', text: { tag: 'lark_md', content: '暂无指令' } });
-            }
-            else {
-                // Pagination calculations
-                const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageOrders, hasPagination, } = pageSlice(allOrders, offset, ORDER_PAGE_SIZE);
-                for (let i = 0; i < pageOrders.length; i++) {
-                    const order = pageOrders[i];
-                    const displayText = order.text.length > 100 ? order.text.slice(0, 97) + '...' : order.text;
-                    // 文字在上方（有别名时用 `$name` 前缀标识触发词）
-                    elements.push({
-                        tag: 'div',
-                        text: {
-                            tag: 'lark_md',
-                            content: order.alias ? `\`$${order.alias}\` ${displayText}` : displayText,
-                        },
-                    });
-                    // 操作行：左侧别名按钮（无别名显示 ＋别名，有别名点击可改），
-                    // 右侧「删除指令」按钮。两列均 weighted 1:1，跨行对齐。
-                    const leftColumn = order.alias
-                        ? [
-                            cardButton(`$${order.alias}`, { cmd: 'order.aliasEdit', orderId: order.id, offset: safeOffset }, { type: 'default', size: 'small' }),
-                            cardButton('✕', {
-                                cmd: 'order.aliasRemove',
-                                orderId: order.id,
-                                aliasName: order.alias,
-                                offset: safeOffset,
-                            }, { type: 'default', size: 'small' }),
-                        ]
-                        : [
-                            cardButton('＋别名', { cmd: 'order.aliasEdit', orderId: order.id, offset: safeOffset }, { type: 'default', size: 'small' }),
-                        ];
-                    elements.push({
-                        tag: 'column_set',
-                        columns: [
-                            {
-                                tag: 'column',
-                                width: 'weighted',
-                                weight: 1,
-                                elements: leftColumn,
-                            },
-                            {
-                                tag: 'column',
-                                width: 'weighted',
-                                weight: 1,
-                                vertical_align: 'center',
-                                elements: [
-                                    {
-                                        tag: 'column_set',
-                                        columns: [
-                                            {
-                                                tag: 'column',
-                                                width: 'auto',
-                                                elements: [
-                                                    cardButton('▶ 执行', { cmd: 'order.exec', orderId: order.id }, { type: 'primary', size: 'small' }),
-                                                ],
-                                            },
-                                            {
-                                                // 编辑：弹蓝色 header 输入卡（CardKit 2.0 input，回车提交），
-                                                // 镜像 order.aliasEdit 流程。order.textEdit 是 control-only action
-                                                // （isImmediateAction 注册），不 spawn agent。
-                                                tag: 'column',
-                                                width: 'auto',
-                                                elements: [
-                                                    cardButton('编辑', { cmd: 'order.textEdit', orderId: order.id, offset: safeOffset }, { type: 'default', size: 'small' }),
-                                                ],
-                                            },
-                                            {
-                                                tag: 'column',
-                                                width: 'auto',
-                                                elements: [
-                                                    cardButton('删除', { cmd: 'order.delete', orderId: order.id, offset: safeOffset }, { type: 'danger', size: 'small' }),
-                                                ],
-                                            },
-                                        ],
-                                    },
-                                ],
-                            },
-                        ],
-                    });
-                    // 非最后一项，添加分隔线
-                    if (i < pageOrders.length - 1) {
-                        elements.push({ tag: 'hr' });
-                    }
-                }
-                // Pagination bar (only shown when there are more items than ORDER_PAGE_SIZE)
-                if (hasPagination) {
-                    const bar = paginationBar({
-                        cmd: 'order.page',
-                        offset: safeOffset,
-                        pageSize: ORDER_PAGE_SIZE,
-                        total: totalCount,
-                        label: `**第 ${currentPage}/${totalPages} 页**（共 ${totalCount} 条）`,
-                    });
-                    elements.push({ tag: 'hr' });
-                    elements.push(...bar);
-                }
-            }
-            return {
-                card: {
-                    schema: '2.0',
-                    config: { wide_screen_mode: true, update_multi: true },
-                    header: { title: { tag: 'plain_text', content: '📋 指令' }, template: 'turquoise' },
-                    body: { elements },
-                },
-            };
-        }
-        // /order alias — CLI 别名管理（卡片是主入口，命令是备选）：
-        //   /order alias add <orderId|N> <name>   — 给某条指令绑定别名
-        //   /order alias rm <orderId|N>           — 移除某条指令的别名
-        //   /order alias list                     — 列出已绑定的别名（并入列表卡片）
-        if (sub === 'alias') {
-            const op = args[1];
-            if (op === 'add') {
-                const target = args[2];
-                const name = args[3];
-                if (!target || !name) {
-                    return { text: '用法: /order alias add <orderId|序号> <别名名>' };
-                }
-                return this.cmdOrderAliasAdd(target, name);
-            }
-            if (op === 'rm') {
-                const target = args[2];
-                if (!target) {
-                    return { text: '用法: /order alias rm <orderId|序号>' };
-                }
-                return this.cmdOrderAliasRemove(target);
-            }
-            if (!op || op === 'list') {
-                // 别名管理列表并入列表卡片
-                return this.cmdOrder([], _ctx, offset);
-            }
-            return {
-                text: '用法: /order alias [add <orderId|序号> <别名名> | rm <orderId|序号> | list]',
-            };
-        }
-        // /order save <text>
-        if (sub === 'save') {
-            const text = args.slice(1).join(' ');
-            if (!text) {
-                return { text: '用法: /order save <指令文本>' };
-            }
-            try {
-                this.orderStore.save(text);
-                return { text: `✅ 已保存指令: ${text.slice(0, 50)}${text.length > 50 ? '...' : ''}` };
-            }
-            catch (err) {
-                return { text: `保存失败: ${err.message}` };
-            }
-        }
-        // /order edit <orderId|序号> <新文本> — CLI 备选路径（卡片是主入口）。
-        // 与 /order save / alias add|rm 对称；复用 resolveOrderTarget。
-        // 与卡片路径（handleOrderTextInput）对齐 trim 语义，避免「卡片 trim、CLI 不 trim」
-        // 两条入口对同一文本存出不同结果。
-        if (sub === 'edit') {
-            const target = args[1];
-            const newText = args.slice(2).join(' ').trim();
-            if (!target || !newText) {
-                return { text: '用法: /order edit <orderId|序号> <新文本>' };
-            }
-            const order = this.resolveOrderTarget(target);
-            if (!order)
-                return { text: `指令不存在: ${target}` };
-            try {
-                this.orderStore.updateText(order.id, newText);
-                const preview = newText.length > 50 ? newText.slice(0, 50) + '...' : newText;
-                return { text: `✅ 已更新指令: ${preview}` };
-            }
-            catch (err) {
-                return { text: `保存失败: ${err.message}` };
-            }
-        }
-        return {
-            text: '用法: /order [list|save <text>|edit <orderId|序号> <新文本>|alias add <orderId|序号> <别名名>|alias rm <orderId|序号>]',
-        };
-    }
-    /** /order alias add：按 orderId 或列表序号（1 基）解析目标指令并绑定别名。 */
-    cmdOrderAliasAdd(target, name) {
-        const order = this.resolveOrderTarget(target);
-        if (!order)
-            return { text: `指令不存在: ${target}` };
-        try {
-            this.orderStore.setAlias(order.id, name);
-            return { text: `✅ 已给指令绑定别名 $${name}` };
-        }
-        catch (err) {
-            return { text: `保存失败: ${err.message}` };
-        }
-    }
-    /** /order alias rm：按 orderId 或列表序号（1 基）移除指令的别名。 */
-    cmdOrderAliasRemove(target) {
-        const order = this.resolveOrderTarget(target);
-        if (!order)
-            return { text: `指令不存在: ${target}` };
-        if (!order.alias)
-            return { text: '该指令没有别名' };
-        // 先读别名名再解绑：setAlias(undefined) 会 delete 同一对象引用上的 alias 字段。
-        const aliasName = order.alias;
-        this.orderStore.setAlias(order.id, undefined);
-        return { text: `✅ 已移除别名 $${aliasName}` };
+    /** /order 实现（public：测试直接调用）。 */
+    cmdOrder(args, ctx, offset = 0) {
+        return buildOrderCommand(args, ctx, offset, {
+            reload: () => this.orderStore.reload(),
+            list: () => this.orderStore.get(),
+            save: (text) => this.orderStore.save(text),
+            updateText: (id, text) => this.orderStore.updateText(id, text),
+            setAlias: (id, alias) => this.orderStore.setAlias(id, alias),
+            resolveTarget: (target) => this.resolveOrderTarget(target),
+        });
     }
-    /** 将 `/order alias add|rm` 的目标解析为 order：优先 orderId 精确匹配，回退列表序号（1 基）。 */
     resolveOrderTarget(target) {
         const all = this.orderStore.get();
         const byId = all.find((o) => o.id === target);