lark-remote 0.1.3 → 0.1.5

package/dist/router/index.js

@@ -11,6 +11,7 @@ import { activeRunUsage, formatUsageStats } from './utils.js';
 import { markdownDiv, sessionEventPanel } from './card-helpers.js';
 import { MAX_FILE_UPLOAD_SIZE } from '../connector/file-limits.js';
 import { atomicWrite } from '../persistence/atomic-write.js';
+import { checkLatestVersion as defaultCheckLatestVersion, isNewer as defaultIsNewer, runInstallLatest as defaultRunInstallLatest, } from '../update/index.js';
 /** Config card builder - delegates to per-agent builders */
 import { getConfigBuilder, listRegisteredAgents } from './config/index.js';
 import { probeAllAgents, getCachedAvailability } from '../runner/probe.js';
@@ -23,8 +24,19 @@ const AUTO_RESUME_MAX_EVENTS = 5;
 const RESUME_PAGE_SIZE = 5;
 /** /active 卡片每页显示的最大条目数（agent run + bash run 合计）。 */
 const ACTIVE_PAGE_SIZE = 20;
-/** /order 列表页大小；指令超过此数量时显示分页导航栏。 */
-const ORDER_PAGE_SIZE = 20;
+/**
+ * /order 列表页大小；指令超过此数量时显示分页导航栏。
+ * 2026-08-13 实测：每行 2 个元素（div + column_set，行间 hr），20 行 + 分页栏
+ * = 61 个 body 元素，触发飞书 ErrCode 11310 "element exceeds the limit"
+ * （21+ 条指令时第 1 页必炸）。改为 15 行：3*15 - 1 + 2 = 46 个元素，留足余量。
+ */
+const ORDER_PAGE_SIZE = 15;
+/**
+ * /ws 列表页大小。从 15 降为 5：头部 2 + 5 行 × 3（div + column_set + hr）+
+ * 底栏排序 1 + 分页栏 2 ≈ 20 个 body 元素，远低于单卡 60 元素上限（ErrCode 11310），
+ * 留足余量。
+ */
+const WS_PAGE_SIZE = 5;
 /** /resume 列表页内全量预取（readSessionContent）的行数上限；其余行用轻量 summary 兜底。 */
 const RESUME_CONTENT_PREFETCH = 5;
 /**
@@ -39,6 +51,7 @@ import { newSessionButton, agentDisplayName } from '../card/card-shared.js';
  * These bypass the serial queue and execute immediately.
  *
  * ws.use   — /ws list card "使用 <name>"
+ * ws.page  — /ws list card "上一页/下一页"
  * queue.immediate — queue card "立即执行" button (§9.6)
  * queue.cancel    — queue card "撤销" button
  * queue.diagnose  — queue card "诊断" button
@@ -47,6 +60,7 @@ import { newSessionButton, agentDisplayName } from '../card/card-shared.js';
  * new-session — clear sessionId only
  * stop        — interrupt current run
  * ls.file     — send file only
+ * ws.page     — paginate /ws list only
  * ws.remove   — delete workspace alias only
  * resume.use  — set sessionId + agent for correct reader routing
  * help.*      — read-only help commands
@@ -67,7 +81,9 @@ export function isImmediateAction(cmd) {
         cmd === 'ls.page' ||
         cmd === 'resume.page' || // control operation: paginate only, never spawns claude
         cmd === 'active.page' || // control operation: paginate active card
+        cmd === 'ws.page' || // control operation: paginate /ws list only
         cmd === 'ws.remove' ||
+        cmd === 'ws.sort' || // control operation: toggle sort mode only
         cmd === 'resume.use' ||
         cmd === 'ws.use' ||
         cmd === 'queue.immediate' ||
@@ -99,6 +115,12 @@ export class CommandRouter {
      */
     restartSpawner;
     idleTimeoutMs;
+    /** Dev mode flag: --dev means the bridge was started from source (bun src/index.ts). */
+    devMode;
+    /** Cache file for version checks (<configDir>/update-cache.json). */
+    updateCachePath;
+    /** Injected update functions (for testability; defaults to real implementation). */
+    updateFns;
     pendingConfig = null; // /config 卡片编辑暂存区
     /**
      * Monotonic counter minting unique internal keys for order.exec enqueue
@@ -108,6 +130,11 @@ export class CommandRouter {
      * millisecond); the counter guarantees uniqueness regardless of timing.
      */
     orderExecKeyCounter = 0;
+    /**
+     * Per-user sort preference for /ws list (memory-only, not persisted).
+     * Default 'recent' (most recently used first), can toggle to 'alpha'.
+     */
+    wsSortPreference = new Map();
     /**
      * Session reader registry for multi-agent path. Resolves the right
      * reader by `config.defaultAgent` (and per-agent override params).
@@ -141,6 +168,13 @@ export class CommandRouter {
             this.bridge.setIdleTimeout(this.idleTimeoutMs);
         }
         this.sessionReaderRegistry = opts.sessionReaderRegistry;
+        this.devMode = opts.devMode ?? false;
+        this.updateCachePath = opts.updateCachePath;
+        this.updateFns = {
+            checkLatestVersion: opts.updateFns?.checkLatestVersion ?? defaultCheckLatestVersion,
+            isNewer: opts.updateFns?.isNewer ?? defaultIsNewer,
+            runInstallLatest: opts.updateFns?.runInstallLatest ?? defaultRunInstallLatest,
+        };
     }
     /**
      * Resolve the active session reader for the current defaultAgent.
@@ -204,8 +238,11 @@ export class CommandRouter {
             case 'ls.page':
                 return this.handleLsPage(value, ctx);
             case 'ws.use':
-                await this.bridge.sendResult(this.cmdWs(['use', value.name ?? ''], ctx), ctx);
-                return;
+                return await this.handleWsUse(value, ctx);
+            case 'ws.sort':
+                return await this.handleWsSort(value, ctx);
+            case 'ws.page':
+                return await this.handleWsPage(value, ctx);
             case 'ws.remove':
                 return await this.handleWsRemove(value, ctx);
             case 'resume.use': {
@@ -299,7 +336,7 @@ export class CommandRouter {
                     }
                     return;
                 }
-                // AGENTS.md red-line: miss paths must reply via bridge.sendResult —
+                // Design constraint: miss paths must reply via bridge.sendResult —
                 // don't silently swallow unknown card actions.
                 getLogger().warn(`[router] unknown card action: ${value.cmd}`);
                 await this.bridge.sendResult({ text: `⚠️ 未知的卡片操作: ${value.cmd}` }, ctx);
@@ -932,6 +969,39 @@ export class CommandRouter {
         await this.bridge.updateCardInPlace(result.card, ctx);
         return { toast: { type: 'success', content: '' } };
     }
+    /**
+     * Handle ws.use card action: switch to the workspace, then refresh the /ws
+     * list card in place so "recent" sort order is immediately visible.
+     *
+     * Unlike the command-line `/ws use` (which returns text), the card action
+     * uses toast + inplace refresh for a cleaner UX (matching ws.remove/ws.sort).
+     * If auto-resume produces a card, it is sent as a separate reply.
+     */
+    async handleWsUse(value, ctx) {
+        const name = value.name ?? '';
+        const useResult = this.cmdWs(['use', name], ctx);
+        // Error cases (workspace not found, path invalid, etc.): relay as error toast
+        if (useResult.text && !useResult.text.includes('已切换')) {
+            return { toast: { type: 'error', content: useResult.text } };
+        }
+        // Success: if auto-resume produced a card, send it as a reply
+        if (useResult.card) {
+            await this.bridge.sendResult(useResult, ctx);
+        }
+        // Refresh the /ws list card in place so "recent" sort is immediately visible
+        const currentOffset = Math.max(0, Math.trunc(Number(value.offset) || 0));
+        const refreshed = this.cmdWs([], ctx, currentOffset);
+        if (refreshed.card) {
+            await this.bridge.updateCardInPlace(refreshed.card, ctx);
+        }
+        // Toast feedback (suppress text when auto-resume card was already sent)
+        return {
+            toast: {
+                type: 'success',
+                content: useResult.card ? '' : (useResult.text ?? `已切换到 workspace "${name}"`),
+            },
+        };
+    }
     /**
      * Handle ws.remove: remove the workspace alias and refresh the /ws list card
      * in place (mirrors handleOrderDelete). Without this the stale alias would
@@ -945,11 +1015,40 @@ export class CommandRouter {
         // Execute the removal (consumes the write-side effect; the returned text
         // is discarded — feedback flows through the toast + refreshed card).
         this.cmdWs(['remove', name], ctx);
-        // Rebuild the /ws list card and update it in place.
-        const refreshed = this.cmdWs([], ctx);
+        // Rebuild the /ws list card and update it in place, preserving the page
+        // the user was on when they clicked 删除.
+        const currentOffset = Math.max(0, Math.trunc(Number(value.offset) || 0));
+        const refreshed = this.cmdWs([], ctx, currentOffset);
         await this.bridge.updateCardInPlace(refreshed.card, ctx);
         return { toast: { type: 'success', content: `已删除 workspace "${name}"` } };
     }
+    /**
+     * Handle ws.page: paginate the /ws list in place.
+     * Mirrors handleOrderPage — updates the same card, never sends a new one.
+     */
+    async handleWsPage(value, ctx) {
+        const offset = Math.max(0, Math.trunc(Number(value.offset) || 0));
+        // cmdWs internally clamps stale/out-of-range offsets
+        const result = this.cmdWs([], ctx, offset);
+        await this.bridge.updateCardInPlace(result.card, ctx);
+        return { toast: { type: 'success', content: '' } };
+    }
+    /**
+     * Handle ws.sort: toggle sort preference and refresh the /ws list card.
+     * Sort preference is memory-only (not persisted); restart resets to 'recent'.
+     */
+    async handleWsSort(value, ctx) {
+        const userId = ctx.userId;
+        const current = this.wsSortPreference.get(userId) ?? 'recent';
+        const next = current === 'recent' ? 'alpha' : 'recent';
+        this.wsSortPreference.set(userId, next);
+        const result = this.cmdWs([], ctx, 0);
+        await this.bridge.updateCardInPlace(result.card, ctx);
+        const nextLabel = next === 'recent' ? '🕐 最近使用' : '🔤 字母顺序';
+        return {
+            toast: { type: 'success', content: `已切换为 ${nextLabel}` },
+        };
+    }
     /**
      * `ls.file` card button: send file to Feishu, rejecting if > 30MB.
      */
@@ -1106,7 +1205,7 @@ export class CommandRouter {
                     this.config = setConfigValues(this.configPath, this.config, updates);
                     // P1-6：运行时传播（idleTimeout / clearRunners / syncAgentChoices /
                     // defaultAgent 切换的 session 处理）抽到共享方法，与文本直写路径共用。
-                    const switchNotice = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
+                    const switchResult = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
                     this.pendingConfig = null;
                     // 原地更新卡片：保存后卡片刷新为已保存状态（2026-07-04）
                     // 2026-08-03: 卡片刷新失败不吞切换通知——保存已成功，仅记录日志，
@@ -1117,14 +1216,15 @@ export class CommandRouter {
                     catch (refreshErr) {
                         getLogger().warn(`[router] config.save 卡片刷新失败（保存已成功）: ${refreshErr.message}`);
                     }
-                    // 2026-08-03: agent 切换时发送持久化消息通知用户（toast 不持久化，
-                    // 聊天记录不可回溯）；发送失败（resolve false，不 throw）时兜底回退
-                    // toast 即时反馈，复用同一个切换文案。
-                    if (switchNotice) {
-                        const sent = await this.bridge.sendResult({ text: switchNotice }, ctx);
+                    // 2026-08-13: agent 切换时发送 Resume 卡片（替代纯文本通知），
+                    // 让用户直观看到新 agent 的会话状态和历史。
+                    // 发送失败（resolve false）时兜底回退 toast 即时反馈。
+                    if (switchResult.notice) {
+                        const switchCard = this.buildConfigSwitchCard(switchResult, ctx);
+                        const sent = await this.bridge.sendResult(switchCard, ctx);
                         if (!sent) {
                             return {
-                                toast: { type: 'info', content: switchNotice },
+                                toast: { type: 'info', content: switchResult.notice },
                             };
                         }
                     }
@@ -1226,7 +1326,7 @@ export class CommandRouter {
      *
      * @param updates 以 config 路径形式给出的变更 key（卡片路径来自 diffConfig；
      *   直写路径传 mapAgentKey(key)，保证 pi./codex./opencode./kimi. 命中 agents.*）。
-     * @returns defaultAgent 切换时的通知文案（未切换返回 undefined）
+     * @returns 结构化切换结果（含 notice 文案 + 新 agent/sessionId 信息）
      */
     propagateConfigSave(oldDefaultAgent, updates, ctx) {
         this.bridge.setConfig(this.config);
@@ -1251,13 +1351,12 @@ export class CommandRouter {
         // 同时清除新 agent 的 sessionId（等效于 /new 命令），
         // 并支持 session 恢复 - 切换回来时如果条件满足则恢复之前的 session。
         let switchNotice;
+        let switchNewAgent;
+        let switchSessionId;
         if (hasDefaultAgentChange) {
             const newAgent = this.config.defaultAgent;
+            switchNewAgent = newAgent;
             // Step 0: 在清空 old 之前计算「用户活动」基线差（arrival 基线）：
-            // arrivalSessions[old] 是用户最近一次经 config.save 切换「到达」该 agent
-            // 时被赋予的 session id（清空到达 = ''）。当前 session 与到达基线不一致
-            // ⇒ 用户在 oldAgent 上产生过用户活动（发消息 /resume /new /cd 等，均
-            // 不更新 arrival），离开时恢复必须被阻断。
             const oldSessionId = this.sessionStore.getSessionId(ctx.userId, oldDefaultAgent);
             const oldArrivalSessionId = this.sessionStore.getArrivalSessionId(ctx.userId, oldDefaultAgent);
             const userChangedOld = (oldSessionId ?? '') !== (oldArrivalSessionId ?? '');
@@ -1267,48 +1366,36 @@ export class CommandRouter {
             }
             // Step 2: 清除旧 agent 的 session（保存后清除，为新会话腾出空间）
             this.sessionStore.clearSessionId(ctx.userId, oldDefaultAgent);
-            // Step 2.5: 显式选择判定——sessions[new] 非空且不等于到达基线 ⇒ 用户经 /resume
-            // 显式改选了 new 的 session（/resume 不更新 arrival），切换时必须让选择存活。
-            // 优先级：显式选择 > 停车恢复 > 清空；newSessionId 为空（防御）不触发本分支。
+            // Step 2.5: 显式选择判定
             const newSessionId = this.sessionStore.getSessionId(ctx.userId, newAgent);
             const newArrivalSessionId = this.sessionStore.getArrivalSessionId(ctx.userId, newAgent);
             const userSelectedNew = !!newSessionId && (newSessionId ?? '') !== (newArrivalSessionId ?? '');
-            // Step 3: 恢复判定——previousSessions[newAgent] 存在 且 用户在 oldAgent 上
-            // 没有用户活动（session 未变于到达基线）。判断方法：arrival 基线差
-            // userChangedOld 为 false 时，oldAgent 的 session 只可能是 config.save
-            // 自动恢复/清空得到的，不构成用户活动，恢复不被阻断。
+            // Step 3: 恢复判定
             const previousSessionId = this.sessionStore.getPreviousSessionId(ctx.userId, newAgent);
             const canRestore = !!previousSessionId && !userChangedOld;
             if (userSelectedNew) {
-                // 显式选择优先于停车恢复与用户活动阻断：保留 sessions[new]（不动），更新
-                // arrival 基线为所选 session；prev[new] 停车位原样保留（下次离开时会被
-                // sessions[new] 覆盖停车）。
                 this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, newSessionId);
                 const newAgentName = agentDisplayName(newAgent);
                 switchNotice = `已切换到 ${newAgentName}，已使用所选 session，sessionId: ${newSessionId}`;
+                switchSessionId = newSessionId;
             }
             else if (canRestore) {
-                // 可以恢复之前的 session
                 this.sessionStore.setSessionId(ctx.userId, newAgent, previousSessionId);
-                // 恢复分支消费 previousSessions，并记录新的到达基线（自动恢复的 session
-                // 不构成用户活动，后续离开时 userChangedOld 仍为 false）
                 this.sessionStore.clearPreviousSessionId(ctx.userId, newAgent);
                 this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, previousSessionId);
                 const newAgentName = agentDisplayName(newAgent);
                 switchNotice = `已切换到 ${newAgentName}，将继续之前的 session，sessionId: ${previousSessionId}`;
+                switchSessionId = previousSessionId;
             }
             else {
-                // Step 4: 清除新 agent 的 session（等效于 /new）
                 this.sessionStore.clearSessionId(ctx.userId, newAgent, { clearSessionCwd: true });
-                // 清空分支不清除 previousSessions[newAgent]（停车语义：被拒绝的恢复
-                // 机会保留，未来无用户活动的返回仍可恢复）；记录清空到达基线
                 this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, '');
                 const newAgentName = agentDisplayName(newAgent);
                 switchNotice = `已切换到 ${newAgentName}，session 已清空，下次消息将启动新对话`;
+                switchSessionId = '';
             }
         }
         // 2026-07-13: 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
-        // 检测是否有当前 agent 的配置变更
         const currentAgent = this.config.defaultAgent;
         const currentAgentConfigKey = `agents.${currentAgent}`;
         const hasCurrentAgentUpdate = Object.keys(updates).some((k) => k === currentAgentConfigKey || k.startsWith(`${currentAgentConfigKey}.`));
@@ -1319,11 +1406,10 @@ export class CommandRouter {
             this.bridge.setConfig(this.config);
         }
         // 2026-07-13: 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
-        // 否则 runner 仍使用旧配置值
         if (hasDefaultAgentChange || hasAgentConfigChange) {
             this.bridge.clearRunners();
         }
-        return switchNotice;
+        return { notice: switchNotice, newAgent: switchNewAgent, sessionId: switchSessionId };
     }
     async executeCommand(message, ctx) {
         const parts = message.slice(1).split(/\s+/);
@@ -1368,6 +1454,9 @@ export class CommandRouter {
             case 'order':
             case 'o':
                 return this.cmdOrder(args, ctx);
+            case 'update':
+            case 'u':
+                return await this.cmdUpdate(args, ctx);
             default:
                 return { text: `未知命令 /${cmd}，输入 /help 查看可用命令` };
         }
@@ -1387,6 +1476,7 @@ export class CommandRouter {
             { cmd: 'active', label: '/active', desc: '查看所有正在进行中的 session' },
             { cmd: 'exit', label: '/exit /e', desc: '退出 bridge' },
             { cmd: 'restart', label: '/restart', desc: '重启 bridge（新进程，config 不变）' },
+            { cmd: 'update', label: '/update /u', desc: '检查并升级到最新版本' },
             { cmd: 'status', label: '/status /s', desc: '显示当前状态' },
             { cmd: 'reconnect', label: '/reconnect', desc: '重连飞书' },
         ].sort((a, b) => a.label.length - b.label.length || a.cmd.localeCompare(b.cmd));
@@ -1573,6 +1663,61 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             return { text: `重启失败：${err.message}，旧进程仍在运行` };
         }
     }
+    /**
+     * /update: check for newer version and upgrade if available.
+     * /update check: only check, don't upgrade.
+     *
+     * Flow: check version → if newer, install → spawn replacement bridge → exit.
+     * Reuses /restart's restartSpawner + pendingExit mechanism.
+     */
+    async cmdUpdate(args, ctx) {
+        const checkOnly = args[0] === 'check';
+        // 1. Version query（/update check 始终绕过缓存，/update 用 TTL 缓存）
+        let current;
+        let latest;
+        try {
+            const result = await this.updateFns.checkLatestVersion({
+                cachePath: this.updateCachePath,
+                bypassCache: checkOnly,
+            });
+            current = result.current;
+            latest = result.latest;
+        }
+        catch (err) {
+            return { text: `❌ 版本检查失败: ${err.message}` };
+        }
+        if (!this.updateFns.isNewer(current, latest)) {
+            return { text: `✅ 已是最新版本 ${current}` };
+        }
+        if (checkOnly) {
+            return { text: `📦 有新版本 ${latest} 可用（当前 ${current}），发送 /update 升级` };
+        }
+        // 2. Dev mode guard
+        if (this.devMode) {
+            return { text: '⚠️ 开发模式不支持自更新，请 git pull 后重新构建' };
+        }
+        // 3. Install (send intermediate status before the blocking operation)
+        await this.bridge.sendResult({ text: `⬆️ 正在升级 ${current} → ${latest} ...` }, ctx);
+        const installResult = await this.updateFns.runInstallLatest();
+        if (!installResult.success) {
+            return { text: `❌ 升级失败: ${installResult.error}` };
+        }
+        // 4. Restart (reuse /restart's restartSpawner + pendingExit)
+        if (!this.restartSpawner) {
+            return { text: `✅ 已升级到 ${latest}，请手动 /restart 重启 bridge` };
+        }
+        try {
+            const pid = this.restartSpawner();
+            this.pendingExit = true;
+            return { text: `✅ 升级成功 (${current} → ${latest})，正在重启（新进程 pid ${pid}）…` };
+        }
+        catch (err) {
+            getLogger().error('[router] update restart spawn failed:', err);
+            return {
+                text: `✅ 已升级到 ${latest}，但重启失败：${err.message}，请手动 /restart`,
+            };
+        }
+    }
     cmdNew(ctx) {
         // 只清 sessionId 保留 cwd — 否则 /new 之后 /resume 会提示"请先 /cd
         // 设置工作目录"，但用户的 workspace 还在。2026-06-21 复盘：用户
@@ -1755,6 +1900,136 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         };
         return { card };
     }
+    /**
+     * Build card for config.save agent switch.
+     * When the new agent has a restored session, renders a Resume card (mirrors
+     * buildAutoResumeCard) with session history + stop/new buttons.
+     * When the session was cleared, renders a compact notice card instead.
+     */
+    buildConfigSwitchCard(switchResult, ctx) {
+        const newAgent = switchResult.newAgent;
+        const agentName = agentDisplayName(newAgent);
+        const cwd = this.sessionStore.getCwd(ctx.userId);
+        const sessionId = switchResult.sessionId;
+        // No cwd or no session → compact notice card
+        if (!cwd || !sessionId) {
+            const elements = [markdownDiv(switchResult.notice)];
+            // New session button
+            elements.push({
+                tag: 'column_set',
+                columns: [
+                    {
+                        tag: 'column',
+                        width: 'auto',
+                        elements: [newSessionButton()],
+                    },
+                ],
+            });
+            return {
+                card: {
+                    schema: '2.0',
+                    config: { wide_screen_mode: true },
+                    header: {
+                        title: { tag: 'plain_text', content: `🔀 切换到 ${agentName}` },
+                    },
+                    body: { elements },
+                },
+            };
+        }
+        // Has session → Resume card (mirrors buildAutoResumeCard)
+        // Guard: if the session reader for the new agent is not available (e.g. agent
+        // not registered), fall back to compact notice card to avoid NPE.
+        const readerForNewAgent = newAgent === this.config.defaultAgent
+            ? this.sessionReader
+            : this.sessionReaderRegistry.get(newAgent);
+        if (!readerForNewAgent) {
+            // Fallback: compact notice card with the notice text
+            const elements = [markdownDiv(switchResult.notice)];
+            elements.push({
+                tag: 'column_set',
+                columns: [
+                    {
+                        tag: 'column',
+                        width: 'auto',
+                        elements: [newSessionButton()],
+                    },
+                ],
+            });
+            return {
+                card: {
+                    schema: '2.0',
+                    config: { wide_screen_mode: true },
+                    header: { title: { tag: 'plain_text', content: `🔀 切换到 ${agentName}` } },
+                    body: { elements },
+                },
+            };
+        }
+        const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(sessionId, cwd, {
+            agentKind: newAgent,
+            maxEvents: AUTO_RESUME_MAX_EVENTS,
+        });
+        let header = `📂 \`${cwd}\`\n已恢复会话: **${sessionId}**`;
+        const sections = [];
+        if (displayTitle) {
+            const label = aiTitle ? 'AI 标题' : '最近输入';
+            sections.push(`🏷️ **${label}**\n${displayTitle}`);
+        }
+        if (recap) {
+            const recapPreview = recap.length > 200 ? recap.slice(0, 197) + '...' : recap;
+            sections.push(`📝 **Recap**\n${recapPreview}`);
+        }
+        if (sections.length > 0) {
+            header += '\n\n' + sections.join('\n\n──\n\n');
+        }
+        const elements = [markdownDiv(header), { tag: 'hr' }];
+        if (content.length === 0) {
+            elements.push(markdownDiv('_该会话暂无新消息可显示（最后一条为用户输入）_'));
+        }
+        else {
+            content.forEach((ev, i) => {
+                elements.push(sessionEventPanel(ev, i, content.length, 2, newAgent));
+            });
+        }
+        if (usage) {
+            const usageStr = formatUsageStats(usage, { showResult: true, result: 'success' });
+            elements.push(markdownDiv(usageStr));
+        }
+        if (elements.length > 0 && elements[elements.length - 1].tag === 'hr') {
+            elements.pop();
+        }
+        // Action buttons
+        const actions = [];
+        if (isActive) {
+            actions.push({
+                tag: 'button',
+                text: { tag: 'plain_text', content: '⏹ 终止' },
+                type: 'danger',
+                behaviors: [{ type: 'callback', value: { cmd: 'stop', runId: activeRunRunId, cwd } }],
+            });
+        }
+        actions.push(newSessionButton());
+        elements.push({
+            tag: 'column_set',
+            columns: actions.map((btn) => ({
+                tag: 'column',
+                width: 'auto',
+                elements: [btn],
+            })),
+        });
+        return {
+            card: {
+                schema: '2.0',
+                config: { wide_screen_mode: true },
+                header: {
+                    title: {
+                        tag: 'plain_text',
+                        content: `${isActive ? '⏳ 切换 Agent（完成中）' : '🔀 切换 Agent'} · ${agentName}`,
+                    },
+                },
+                body: { elements },
+            },
+        };
+    }
     static LS_PAGE_SIZE = 30;
     cmdLs(args, ctx, offset = 0) {
         const cwd = this.sessionStore.getCwd(ctx.userId);
@@ -2030,7 +2305,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             return { text: `读取目录失败: ${err.message}` };
         }
     }
-    cmdWs(args, ctx) {
+    cmdWs(args, ctx, offset = 0) {
         const sub = args[0]?.toLowerCase();
         switch (sub) {
             case 'save': {
@@ -2063,6 +2338,8 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 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);
             }
@@ -2079,6 +2356,29 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             default: {
                 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));
+                }
+                // Pagination calculations (mirror cmdOrder): clamp stale/out-of-range
+                // offsets so prev/next always step by WS_PAGE_SIZE.
+                const totalCount = entries.length;
+                const totalPages = Math.max(1, Math.ceil(totalCount / WS_PAGE_SIZE));
+                const maxOffset = Math.max(0, (totalPages - 1) * WS_PAGE_SIZE);
+                const safeOffset = Math.min(Math.max(offset, 0), maxOffset);
+                const currentPage = Math.floor(safeOffset / WS_PAGE_SIZE) + 1;
+                const pageEntries = entries.slice(safeOffset, safeOffset + WS_PAGE_SIZE);
+                const hasPagination = totalCount > WS_PAGE_SIZE;
                 // Build body elements: current cwd + workspace list with dividers
                 const bodyElements = [];
                 // Current working directory section
@@ -2086,18 +2386,56 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     tag: 'div',
                     text: { tag: 'lark_md', content: `📂 当前工作目录：\`${currentCwd ?? '(未设置)'}\`` },
                 });
-                bodyElements.push({ tag: 'hr' });
                 if (entries.length === 0) {
+                    bodyElements.push({ tag: 'hr' });
                     bodyElements.push({
                         tag: 'div',
                         text: { tag: 'lark_md', content: '没有保存的 workspace' },
                     });
                 }
                 else {
-                    entries.forEach(([name, p]) => {
+                    // 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: [
+                                    {
+                                        tag: 'button',
+                                        text: { tag: 'plain_text', content: `切换为 ${switchLabel}` },
+                                        type: 'default',
+                                        size: 'small',
+                                        behaviors: [{ type: 'callback', value: { cmd: 'ws.sort' } }],
+                                    },
+                                ],
+                            },
+                        ],
+                    });
+                    bodyElements.push({ tag: 'hr' });
+                    for (const entry of pageEntries) {
                         bodyElements.push({
                             tag: 'div',
-                            text: { tag: 'lark_md', content: `**${name}** → \`${p}\`` },
+                            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({
@@ -2112,7 +2450,12 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                                             text: { tag: 'plain_text', content: '切换' },
                                             type: 'primary',
                                             size: 'small',
-                                            behaviors: [{ type: 'callback', value: { cmd: 'ws.use', name } }],
+                                            behaviors: [
+                                                {
+                                                    type: 'callback',
+                                                    value: { cmd: 'ws.use', name: entry.name, offset: safeOffset },
+                                                },
+                                            ],
                                         },
                                     ],
                                 },
@@ -2125,15 +2468,86 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                                             text: { tag: 'plain_text', content: '删除' },
                                             type: 'danger',
                                             size: 'small',
-                                            behaviors: [{ type: 'callback', value: { cmd: 'ws.remove', name } }],
+                                            behaviors: [
+                                                {
+                                                    type: 'callback',
+                                                    value: { cmd: 'ws.remove', name: entry.name, offset: safeOffset },
+                                                },
+                                            ],
                                         },
                                     ],
                                 },
                             ],
                         });
                         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 hasPrev = safeOffset > 0;
+                        const hasNext = safeOffset + WS_PAGE_SIZE < totalCount;
+                        const pageColumns = [];
+                        if (hasPrev) {
+                            pageColumns.push({
+                                tag: 'column',
+                                width: 'auto',
+                                vertical_align: 'center',
+                                elements: [
+                                    {
+                                        tag: 'button',
+                                        text: { tag: 'plain_text', content: '⬅' },
+                                        type: 'default',
+                                        size: 'small',
+                                        behaviors: [
+                                            {
+                                                type: 'callback',
+                                                value: { cmd: 'ws.page', offset: safeOffset - WS_PAGE_SIZE },
+                                            },
+                                        ],
+                                    },
+                                ],
+                            });
+                        }
+                        pageColumns.push({
+                            tag: 'column',
+                            width: 'weighted',
+                            weight: 1,
+                            vertical_align: 'center',
+                            elements: [
+                                {
+                                    tag: 'div',
+                                    text: {
+                                        tag: 'lark_md',
+                                        content: `**${currentPage}/${totalPages}**（${totalCount}）`,
+                                    },
+                                },
+                            ],
+                        });
+                        if (hasNext) {
+                            pageColumns.push({
+                                tag: 'column',
+                                width: 'auto',
+                                vertical_align: 'center',
+                                elements: [
+                                    {
+                                        tag: 'button',
+                                        text: { tag: 'plain_text', content: '➡' },
+                                        type: 'default',
+                                        size: 'small',
+                                        behaviors: [
+                                            {
+                                                type: 'callback',
+                                                value: { cmd: 'ws.page', offset: safeOffset + WS_PAGE_SIZE },
+                                            },
+                                        ],
+                                    },
+                                ],
+                            });
+                        }
+                        bodyElements.push({ tag: 'hr' });
+                        bodyElements.push({ tag: 'column_set', columns: pageColumns });
+                    }
                 }
                 const card = {
                     schema: '2.0',
@@ -2682,8 +3096,14 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 // clearRunners / syncAgentChoices / defaultAgent 切换）。key 经 mapAgentKey
                 // 归一化，pi./codex./opencode./kimi. 命中 agents.* 判定；claude. 与
                 // defaultAgent 不再漏判。
-                this.propagateConfigSave(oldDefaultAgent, { [mapAgentKey(key)]: value }, ctx);
+                const switchResult = this.propagateConfigSave(oldDefaultAgent, { [mapAgentKey(key)]: value }, ctx);
                 this.pendingConfig = null; // 命令式写盘后清空暂存，避免不一致
+                // 2026-08-13: agent 切换时额外发送 Resume 卡片
+                if (switchResult.notice) {
+                    const switchCard = this.buildConfigSwitchCard(switchResult, ctx);
+                    // 文本路径返回 config card，Resume card 通过 bridge 异步发送
+                    void this.bridge.sendResult(switchCard, ctx);
+                }
                 const card = this.buildConfigCard();
                 if (discarded > 0 && card.card && typeof card.card === 'object') {
                     const body = card.card.body;