lark-remote 0.1.5 → 0.1.7

package/dist/router/index.js

@@ -2,18 +2,20 @@ 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, assertSafeKeyPart, } from '../config/index.js';
+import { getConfigDir, getConfigValue, setConfigValue, setConfigValues, mapAgentKey, assertSafeKeyPart, walkNestedContainer, } from '../config/index.js';
 import { syncAgentChoices } from '../runner/index.js';
 import { WorkspaceStore } from '../workspace/index.js';
 import { OrderStore } from '../order/index.js';
+import { AliasStore } from '../order/alias-store.js';
+import { resolveAlias } from '../order/alias-resolve.js';
 import { getLogger } from '../logger/index.js';
-import { activeRunUsage, formatUsageStats } from './utils.js';
-import { markdownDiv, sessionEventPanel } from './card-helpers.js';
+import { activeRunUsage, clampInt } from './utils.js';
+import { markdownDiv, buildSessionHistoryCard, paginationBar } 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 { getConfigBuilder, listRegisteredAgents, sortAgentsForDisplay } from './config/index.js';
 import { probeAllAgents, getCachedAvailability } from '../runner/probe.js';
 import { buildConfigCardFromTabs } from './config/common/render.js';
 /** Max events to read for auto-resume and /resume cards.
@@ -37,6 +39,21 @@ const ORDER_PAGE_SIZE = 15;
  * 留足余量。
  */
 const WS_PAGE_SIZE = 5;
+/**
+ * 归一化卡片分页参数：clamp pageSize 到 [1,maxPageSize]，offset 归整为
+ * 非负整数并对齐到页边界。非数字 payload（如 'abc'）不得产生 NaN slice。
+ *
+ * resume.page / active.page 共用，避免两处重复实现分页归一化。
+ */
+function normalizePageArgs(value, maxPageSize) {
+    const rawPageSize = Number(value.pageSize);
+    const pageSize = Number.isFinite(rawPageSize)
+        ? clampInt(Math.trunc(rawPageSize), 1, maxPageSize)
+        : maxPageSize;
+    const rawOffset = Number(value.offset);
+    const offset = Number.isFinite(rawOffset) ? Math.max(0, Math.trunc(rawOffset)) : 0;
+    return { pageSize, alignedOffset: Math.floor(offset / pageSize) * pageSize };
+}
 /** /resume 列表页内全量预取（readSessionContent）的行数上限；其余行用轻量 summary 兜底。 */
 const RESUME_CONTENT_PREFETCH = 5;
 /**
@@ -45,7 +62,7 @@ const RESUME_CONTENT_PREFETCH = 5;
  * `New Session`、空串），都不是真实输入，不得渲染成行标题。
  */
 const RESUME_SUMMARY_PLACEHOLDERS = new Set(['', '(no user message)', '(无摘要)', 'New Session']);
-import { newSessionButton, agentDisplayName } from '../card/card-shared.js';
+import { newSessionButton, resumeCompactButton, agentDisplayName } from '../card/card-shared.js';
 /**
  * Card-action commands that must run with enqueue({ immediate: true }).
  * These bypass the serial queue and execute immediately.
@@ -96,17 +113,29 @@ export function isImmediateAction(cmd) {
         cmd === 'config.toggle' ||
         cmd === 'config.set' ||
         cmd === 'config.input' ||
-        cmd === 'config.save');
+        cmd === 'config.save' ||
+        // 审批响应/权限切换必须即时触达在途 run（同 stop 类控制动作）。若走串行
+        // 队列会排在等待审批的 run 之后形成死锁：run 不结束审批不执行，run 结束
+        // coordinator 已删响应空转（线上复现：approval.respond 排队卡、审批永不生效）。
+        cmd === 'approval.respond' ||
+        cmd === 'approval.toggle' ||
+        cmd === 'approval.answer' ||
+        cmd === 'approval.answerSubmit' ||
+        cmd === 'approval.answerCustom');
 }
 export class CommandRouter {
     /** Valid agent kinds — single source of truth for resume.use / resume.page / cmdResume. */
     static VALID_AGENTS = ['claude', 'codex', 'opencode', 'pi', 'kimi'];
     sessionStore;
+    /** 飞书桥接实例（public：测试直接访问断言，替代 as unknown as）。 */
     bridge;
+    /** 当前配置（public：测试直接读取断言，替代 as unknown as）。 */
     config;
+    /** 配置文件的绝对路径（public：/config 保存链路与测试共用）。 */
     configPath;
     workspaceStore;
     orderStore;
+    aliasStore;
     exitHandler;
     pendingExit = false;
     /**
@@ -121,7 +150,8 @@ export class CommandRouter {
     updateCachePath;
     /** Injected update functions (for testability; defaults to real implementation). */
     updateFns;
-    pendingConfig = null; // /config 卡片编辑暂存区
+    /** /config 卡片编辑暂存区（public：测试直接读取断言，替代 as unknown as）。 */
+    pendingConfig = null;
     /**
      * Monotonic counter minting unique internal keys for order.exec enqueue
      * actions. One order card can be clicked many times, so the Feishu card
@@ -142,6 +172,7 @@ export class CommandRouter {
      * it uses `listRegisteredAgents()` from `router/config/index.ts` (the
      * config-builder registry), which mirrors the agents with a config card.
      */
+    /** Session reader 注册中心（public：测试注入/读取，替代 as unknown as）。 */
     sessionReaderRegistry;
     /**
      * 串行化 config.* 卡片回调（2026-07-04）。
@@ -159,6 +190,7 @@ export class CommandRouter {
         this.configPath = opts.configPath;
         this.workspaceStore = new WorkspaceStore(opts.workspacePath);
         this.orderStore = new OrderStore(opts.ordersPath);
+        this.aliasStore = new AliasStore(opts.aliasesPath);
         this.exitHandler = opts.exitHandler ?? (() => process.exit(0));
         this.restartSpawner = opts.restartSpawner;
         // idle watchdog 窗口从 config.idle.watchdogMinutes 读取
@@ -197,6 +229,8 @@ export class CommandRouter {
                 await this.bridge.sendResult(result, ctx);
             }
             if (this.pendingExit) {
+                // 干净退出前冲刷待合批的媒体保存提示，避免 500ms 窗口内的提示丢失。
+                await this.bridge.flushAllMediaNotifications();
                 this.exitHandler();
             }
             return result;
@@ -217,6 +251,13 @@ export class CommandRouter {
         await this.bridge.forwardToClaude(trimmed, ctx, opts);
         return null;
     }
+    /**
+     * 一次别名展开：bridge 收到用户消息后、命令分发前调用。
+     * 仅 `$name` 开头的消息可能被展开；未知别名 / 非 `$` 消息原样返回。
+     */
+    expandAliasMessage(message) {
+        return resolveAlias(message, this.aliasStore.list()) ?? message;
+    }
     /**
      * Handle a CardKit card button click (§6.2).
      * Validates payload and dispatches to the corresponding command.
@@ -237,12 +278,12 @@ export class CommandRouter {
                 return;
             case 'ls.page':
                 return this.handleLsPage(value, ctx);
+            case 'ws.page':
+                return this.handleWsPage(value, ctx);
             case 'ws.use':
                 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': {
@@ -319,6 +360,18 @@ export class CommandRouter {
                 // 调 updateCardInPlace → Feishu API 乱序到达导致 toggle 卡死。
                 // 2026-07-18: 返回 enqueueConfigAction 的结果以支持 toast 响应
                 return this.enqueueConfigAction(value, ctx);
+            case 'approval.respond':
+            case 'approval.toggle':
+            case 'approval.answer':
+            case 'approval.answerSubmit':
+            case 'approval.answerCustom':
+                return this.handleApprovalAction(value, ctx);
+            case 'codex.compact':
+                await this.bridge.handleCodexCompact(value, ctx);
+                return;
+            case 'resume.compact':
+                await this.bridge.handleResumeCompact(value, ctx);
+                return;
             default: {
                 // Help card buttons: help.<cmd> → execute /<cmd>
                 if (value.cmd.startsWith('help.')) {
@@ -332,6 +385,7 @@ export class CommandRouter {
                     // 必须同样消费，否则点击 /restart 按钮 spawn 成功后旧进程不退出，
                     // 新进程撞单例锁退出 → 重启两头落空（2026-08-01 红绿 anchor 锁定）。
                     if (this.pendingExit) {
+                        await this.bridge.flushAllMediaNotifications();
                         this.exitHandler();
                     }
                     return;
@@ -344,6 +398,119 @@ export class CommandRouter {
             }
         }
     }
+    /**
+     * Handle approval-related card actions.
+     * Routes to the appropriate bridge method based on value.cmd.
+     * Returns a toast response for immediate user feedback.
+     */
+    async handleApprovalAction(value, _ctx) {
+        const { runId, requestId, decision, nonce, permId } = value;
+        if (value.cmd === 'approval.respond') {
+            if (!runId || requestId === undefined || !decision || !nonce) {
+                return { toast: { type: 'error', content: '缺少审批响应参数' } };
+            }
+            try {
+                await this.bridge.handleApprovalRespond({
+                    runId,
+                    requestId,
+                    decision,
+                    nonce,
+                });
+                return { toast: { type: 'success', content: '审批已提交' } };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // 审批已过期：给用户明确反馈，不静默不误导（2026-08-12 事故：点了允许无任何反馈）。
+                const content = /state=expired/.test(msg)
+                    ? '⏰ 审批已过期，无法响应'
+                    : `审批响应失败：${msg}`;
+                return { toast: { type: 'error', content } };
+            }
+        }
+        if (value.cmd === 'approval.toggle') {
+            if (!runId || requestId === undefined || !permId) {
+                return { toast: { type: 'error', content: '缺少权限切换参数' } };
+            }
+            try {
+                await this.bridge.handleApprovalToggle({
+                    runId,
+                    requestId,
+                    permId,
+                    selected: value.selected ?? true,
+                });
+                return { toast: { type: 'info', content: '已切换' } };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { toast: { type: 'error', content: `权限切换失败：${msg}` } };
+            }
+        }
+        if (value.cmd === 'approval.answer') {
+            if (!runId ||
+                requestId === undefined ||
+                value.questionIndex === undefined ||
+                !value.option ||
+                !nonce) {
+                return { toast: { type: 'error', content: '缺少问题答案参数' } };
+            }
+            try {
+                await this.bridge.handleApprovalAnswer({
+                    runId,
+                    requestId,
+                    questionIndex: value.questionIndex,
+                    option: value.option,
+                    nonce,
+                });
+                return { toast: { type: 'success', content: '已选择' } };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { toast: { type: 'error', content: `答案提交失败：${msg}` } };
+            }
+        }
+        if (value.cmd === 'approval.answerSubmit') {
+            if (!runId || requestId === undefined || value.questionIndex === undefined || !nonce) {
+                return { toast: { type: 'error', content: '缺少提交参数' } };
+            }
+            try {
+                await this.bridge.handleApprovalAnswerSubmit({
+                    runId,
+                    requestId,
+                    questionIndex: value.questionIndex,
+                    nonce,
+                });
+                return { toast: { type: 'success', content: '答案已提交' } };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { toast: { type: 'error', content: `答案提交失败：${msg}` } };
+            }
+        }
+        if (value.cmd === 'approval.answerCustom') {
+            if (!runId ||
+                requestId === undefined ||
+                value.questionIndex === undefined ||
+                !nonce ||
+                !value.inputValue) {
+                return { toast: { type: 'error', content: '缺少答案文本参数' } };
+            }
+            try {
+                await this.bridge.handleApprovalAnswerCustom({
+                    runId,
+                    requestId,
+                    questionIndex: value.questionIndex,
+                    text: value.inputValue,
+                    nonce,
+                });
+                return { toast: { type: 'success', content: '答案已提交' } };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { toast: { type: 'error', content: `答案提交失败：${msg}` } };
+            }
+        }
+        return { toast: { type: 'error', content: '未知的审批操作' } };
+    }
     /**
      * Handle queue.cancel: remove this message from the queue.
      */
@@ -823,17 +990,7 @@ export class CommandRouter {
         const resolvedAgent = validAgents.includes(resumeAgent)
             ? resumeAgent
             : this.config.defaultAgent;
-        const rawPageSize = Number(value.pageSize);
-        const pageSize = Number.isFinite(rawPageSize)
-            ? Math.min(Math.max(Math.trunc(rawPageSize), 1), RESUME_PAGE_SIZE)
-            : RESUME_PAGE_SIZE;
-        // Normalize the callback offset to a finite non-negative integer, then
-        // align it to a page boundary so prev/next always step by pageSize.
-        // Non-numeric payloads (e.g. 'abc') must not produce NaN slices that look
-        // like an empty directory.
-        const rawOffset = Number(value.offset);
-        const offset = Number.isFinite(rawOffset) ? Math.max(0, Math.trunc(rawOffset)) : 0;
-        const alignedOffset = Math.floor(offset / pageSize) * pageSize;
+        const { pageSize, alignedOffset } = normalizePageArgs(value, RESUME_PAGE_SIZE);
         const entry = this.sessionStore.get(ctx.userId);
         const cwd = entry?.cwd;
         if (!cwd) {
@@ -860,9 +1017,7 @@ export class CommandRouter {
      * Mirrors handleResumePage — updates the same card, never sends a new one.
      */
     async handleActivePage(value, ctx) {
-        const rawOffset = Number(value.offset);
-        const offset = Number.isFinite(rawOffset) ? Math.max(0, Math.trunc(rawOffset)) : 0;
-        const alignedOffset = Math.floor(offset / ACTIVE_PAGE_SIZE) * ACTIVE_PAGE_SIZE;
+        const { alignedOffset } = normalizePageArgs(value, ACTIVE_PAGE_SIZE);
         const result = this.cmdActive([], ctx, alignedOffset);
         if (!result.card) {
             return { toast: { type: 'error', content: '当前没有正在进行中的任务' } };
@@ -984,9 +1139,19 @@ export class CommandRouter {
         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);
+        // Success: send auto-resume card, or a persistent text confirmation when
+        // there is no history session. Toast alone is insufficient: for this
+        // immediate action the callback response is swallowed by enqueueImmediate
+        // (fire-and-forget), and even if delivered it is transient — the user gets
+        // no perceivable feedback on the switch. Same rationale as config.save
+        // agent-switch notice (74e99f0): persistent message first, toast only as a
+        // fallback if sendResult fails.
+        let fallbackToast;
+        if (useResult.card || useResult.text) {
+            const sent = await this.bridge.sendResult(useResult, ctx);
+            if (!sent && useResult.text) {
+                fallbackToast = useResult.text;
+            }
         }
         // Refresh the /ws list card in place so "recent" sort is immediately visible
         const currentOffset = Math.max(0, Math.trunc(Number(value.offset) || 0));
@@ -994,11 +1159,11 @@ export class CommandRouter {
         if (refreshed.card) {
             await this.bridge.updateCardInPlace(refreshed.card, ctx);
         }
-        // Toast feedback (suppress text when auto-resume card was already sent)
+        // Toast feedback (suppress text when a persistent message was already sent)
         return {
             toast: {
                 type: 'success',
-                content: useResult.card ? '' : (useResult.text ?? `已切换到 workspace "${name}"`),
+                content: fallbackToast ?? '',
             },
         };
     }
@@ -1111,6 +1276,7 @@ export class CommandRouter {
         return next;
     }
     /** 实际的 config.* 分发逻辑（在串行队列内执行） */
+    /** config.* 卡片动作分发（public：测试直接调用，替代 as unknown as）。 */
     async dispatchConfigAction(value, ctx) {
         switch (value.cmd) {
             case 'config.toggle': {
@@ -1239,37 +1405,29 @@ export class CommandRouter {
         }
     }
     /** 设置嵌套属性值（仅修改内存对象，不写盘） */
+    /** 在 pendingConfig 上按 dot-separated key 设置嵌套值（config 卡片编辑用）。 */
     setNestedValue(target, key, value) {
         // Path mapping 共用 config 模块的 mapAgentKey（G11 Inconsistency 修复）：
         // pi.xxx/codex.xxx/opencode.xxx → agents.xxx，claude.xxx 保持顶层
         const mappedKey = mapAgentKey(key);
         const parts = mappedKey.split('.');
-        let current = target;
-        for (let i = 0; i < parts.length - 1; i++) {
-            // §P1-4：卡片 config.set/config.input 的 key 来自卡片 action，
-            // 必须与 config 模块的 setNestedValue/deleteNestedValue/getConfigValue 同等
-            // 守卫 __proto__/prototype/constructor 段——否则伪造 key 经
-            // `current['__proto__']` 污染 Object.prototype（文本直写路径已守卫，
-            // 卡片路径是同一威胁模型的另一入口）。
-            assertSafeKeyPart(parts[i]);
-            const next = current[parts[i]];
-            if (next == null || typeof next !== 'object') {
-                current[parts[i]] = {};
-            }
-            current = current[parts[i]];
-        }
-        assertSafeKeyPart(parts[parts.length - 1]);
+        // 复用 config 模块的 walkNestedContainer（含 __proto__/prototype/constructor
+        // 守卫与中间段补 {}），router 只保留 value=undefined → delete 分支。
+        const container = walkNestedContainer(target, parts, true);
+        const lastPart = parts[parts.length - 1];
+        assertSafeKeyPart(lastPart);
         if (value === undefined) {
             // value=undefined 表示"删除键"（如清空 reasoningEffort），
             // 不能写成 undefined 值——diffConfig 会把 undefined 转成字面量 "undefined"
             // 写入 config.yaml 并透传给 codex（ReasoningEffort::Custom("undefined")）。
-            delete current[parts[parts.length - 1]];
+            delete container[lastPart];
         }
         else {
-            current[parts[parts.length - 1]] = value;
+            container[lastPart] = value;
         }
     }
     /** 对比原始 config 与 pendingConfig，返回变化的 key→string 映射 */
+    /** config diff（public：测试直接调用，替代 as unknown as）。 */
     diffConfig(original, pending) {
         const updates = {};
         this.collectDiff('', original, pending, updates);
@@ -1405,6 +1563,27 @@ export class CommandRouter {
             atomicWrite(this.configPath, YAML.stringify(this.config));
             this.bridge.setConfig(this.config);
         }
+        // P1-6 + live approval settings (§P5): active workspace-lifetime runners
+        // are not evicted by clearRunners() (would orphan the live subprocess).
+        // Push the new approval-mode settings to those runners via the unified
+        // 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.'));
+        if (hasApprovalConfigChange) {
+            this.bridge.syncActiveApprovalModes();
+        }
         // 2026-07-13: 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
         if (hasDefaultAgentChange || hasAgentConfigChange) {
             this.bridge.clearRunners();
@@ -1485,7 +1664,11 @@ export class CommandRouter {
             { cmd: 'cd', label: '/cd <path>', desc: '切换工作目录' },
             { cmd: 'ls', label: '/ls [dir]', desc: '列出当前目录，可指定子目录' },
             { cmd: 'resume', label: '/resume /r [agent] [list|id|N]', desc: '列出或切换 Agent session' },
-            { cmd: 'order', label: '/order /o save|list', desc: '保存或列出常用指令（/order 默认列出）' },
+            {
+                cmd: 'order',
+                label: '/order /o save|list',
+                desc: '收藏指令 /order save，快捷别名 /order alias',
+            },
         ];
         const bodyElements = [];
         // 按钮组 — CardKit 2.0: column_set + column + button with behaviors
@@ -1566,6 +1749,7 @@ export class CommandRouter {
             },
         };
     }
+    /** /status 实现（public：测试直接调用，替代 as any）。 */
     cmdStatus(ctx) {
         const entry = this.sessionStore.get(ctx.userId);
         const cwd = entry?.cwd ?? '(未设置)';
@@ -1667,8 +1851,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      * /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.
+     * Flow: check version → if newer, install → report success (no auto-restart).
      */
     async cmdUpdate(args, ctx) {
         const checkOnly = args[0] === 'check';
@@ -1702,21 +1885,8 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         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`,
-            };
-        }
+        // 4. Report success (no auto-restart — user decides when to /restart)
+        return { text: `✅ 升级成功 (${current} → ${latest})，发送 /restart 重启后生效` };
     }
     cmdNew(ctx) {
         // 只清 sessionId 保留 cwd — 否则 /new 之后 /resume 会提示"请先 /cd
@@ -1825,79 +1995,30 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     buildAutoResumeCard(cwd, session, _ctx) {
         const agentName = agentDisplayName(this.config.defaultAgent);
         const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(session.sessionId, cwd, { maxEvents: AUTO_RESUME_MAX_EVENTS });
-        // Build header with displayTitle (aiTitle or last user message) and recap
-        let header = `📂 \`${cwd}\`\n已恢复最近会话: **${session.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' }];
-        // Fold session history into collapsible panels: the last 2 events stay
-        // expanded so the user sees the most recent context without clicking;
-        // older events are collapsed to keep the card compact.
-        content.forEach((ev, i) => {
-            elements.push(sessionEventPanel(ev, i, content.length, 2, this.config.defaultAgent));
+        const actions = this.buildResumeActionButtons({
+            isActive,
+            activeRunRunId,
+            cwd,
+            compact: this.canCompactSession(this.config.defaultAgent, cwd)
+                ? { sessionId: session.sessionId, agentKind: this.config.defaultAgent }
+                : undefined,
+            newSession: true,
         });
-        // Add usage/stats at the end
-        if (usage) {
-            const usageStr = formatUsageStats(usage, { showResult: true, result: 'success' });
-            elements.push({
-                tag: 'div',
-                text: { tag: 'lark_md', content: usageStr },
-            });
-        }
-        // Remove trailing hr and add action buttons
-        if (elements.length > 0 && elements[elements.length - 1].tag === 'hr') {
-            elements.pop();
-        }
-        const actions = [];
-        // Stop button for active sessions (isActive = in-memory activeRun is
-        // non-terminal, which guarantees activeRunRunId is set). Bind the REAL
-        // activeRun.runId (UUID) so bridge.interruptCurrentRun can match and
-        // stop a live run.
-        if (isActive) {
-            actions.push({
-                tag: 'button',
-                text: { tag: 'plain_text', content: '⏹ 终止' },
-                type: 'danger',
-                behaviors: [
-                    {
-                        type: 'callback',
-                        value: { cmd: 'stop', runId: activeRunRunId, cwd },
-                    },
-                ],
-            });
-        }
-        // New session button always shown (use shared function for consistency)
-        actions.push(newSessionButton());
-        // Use column_set+column for 2.0 (action tag not supported in 2.0)
-        elements.push({
-            tag: 'column_set',
-            columns: actions.map((btn) => ({
-                tag: 'column',
-                width: 'auto',
-                elements: [btn],
-            })),
+        const card = buildSessionHistoryCard({
+            sessionId: session.sessionId,
+            cwd,
+            displayTitle,
+            aiTitle,
+            recap,
+            events: content,
+            usage,
+        }, {
+            agentKind: this.config.defaultAgent,
+            headerText: `📂 \`${cwd}\`\n已恢复最近会话: **${session.sessionId}**`,
+            title: `${isActive ? '⏳ 自动恢复会话（完成中）' : '🔁 自动恢复会话'} · ${agentName}`,
+            usageResult: 'success',
+            actions,
         });
-        const card = {
-            schema: '2.0',
-            config: { wide_screen_mode: true },
-            header: {
-                title: {
-                    tag: 'plain_text',
-                    content: `${isActive ? '⏳ 自动恢复会话（完成中）' : '🔁 自动恢复会话'} · ${agentName}`,
-                },
-            },
-            body: { elements },
-        };
         return { card };
     }
     /**
@@ -1911,20 +2032,11 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         const agentName = agentDisplayName(newAgent);
         const cwd = this.sessionStore.getCwd(ctx.userId);
         const sessionId = switchResult.sessionId;
-        // No cwd or no session → compact notice card
+        // No cwd or no session → compact notice card (no new-session button: the
+        // next message already starts a fresh session, a button would mislead
+        // users into thinking a click is required)
         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',
@@ -1968,69 +2080,79 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             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
+        // Action buttons: stop (active) + new session
+        const actions = this.buildResumeActionButtons({
+            isActive,
+            activeRunRunId,
+            cwd,
+            newSession: true,
+        });
+        const card = buildSessionHistoryCard({
+            sessionId,
+            cwd,
+            displayTitle,
+            aiTitle,
+            recap,
+            events: content,
+            usage,
+        }, {
+            agentKind: newAgent,
+            headerText: `📂 \`${cwd}\`\n已恢复会话: **${sessionId}**`,
+            title: `${isActive ? '⏳ 切换 Agent（完成中）' : '🔀 切换 Agent'} · ${agentName}`,
+            usageResult: 'success',
+            emptyPlaceholder: '_该会话暂无新消息可显示（最后一条为用户输入）_',
+            actions,
+        });
+        return { card };
+    }
+    /**
+     * Whether a session of the given agent kind can be compacted from a resume
+     * card. Design doc §6.2-2: duck-typing — check if the runner has `runCompact`
+     * (codex app-server, kimi acp), instead of hardcoding agentKind === 'codex'.
+     */
+    canCompactSession(agentKind, cwd) {
+        if (!cwd)
+            return false;
+        return this.bridge.hasRunCompact(cwd, agentKind);
+    }
+    /**
+     * Assemble the action buttons for a resume / session-history card.
+     * Shared by buildAutoResumeCard, buildConfigSwitchCard, and cmdResume so the
+     * button set (stop / compact / new-session) follows one contract instead of
+     * drifting per call site.
+     *
+     * - stop: only when the session has an in-memory active run (isActive), bound
+     *   to the real activeRun.runId so bridge.interruptCurrentRun can match.
+     * - compact: only when a compact-capable runner applies and the session is
+     *   not running (a live run would occupy the runner, so compaction would
+     *   fail). The caller passes `compact` only when canCompactSession holds.
+     * - new-session: when requested (always shown on resume cards).
+     */
+    buildResumeActionButtons(opts) {
         const actions = [];
-        if (isActive) {
+        if (opts.isActive) {
             actions.push({
                 tag: 'button',
                 text: { tag: 'plain_text', content: '⏹ 终止' },
                 type: 'danger',
-                behaviors: [{ type: 'callback', value: { cmd: 'stop', runId: activeRunRunId, cwd } }],
+                behaviors: [
+                    {
+                        type: 'callback',
+                        value: { cmd: 'stop', runId: opts.activeRunRunId, cwd: opts.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 },
-            },
-        };
+        if (opts.compact && !opts.isActive) {
+            actions.push(resumeCompactButton(opts.compact.sessionId, opts.compact.agentKind));
+        }
+        if (opts.newSession) {
+            actions.push(newSessionButton());
+        }
+        return actions;
     }
     static LS_PAGE_SIZE = 30;
+    /** /ls 实现（public：测试直接调用，替代 as unknown as）。 */
     cmdLs(args, ctx, offset = 0) {
         const cwd = this.sessionStore.getCwd(ctx.userId);
         if (!cwd) {
@@ -2214,78 +2336,16 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             }
             // Pagination bar (only shown when there are more items than PAGE_SIZE)
             if (hasPagination) {
-                const hasPrev = offset > 0;
-                const hasNext = offset + CommandRouter.LS_PAGE_SIZE < totalCount;
-                // Build columns dynamically — Feishu rejects empty elements[] in a column
-                // (ErrCode 200621: "no tag specified"). Only include columns that have content.
-                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: 'ls.page',
-                                            path: targetDir,
-                                            offset: offset - CommandRouter.LS_PAGE_SIZE,
-                                        },
-                                    },
-                                ],
-                            },
-                        ],
-                    });
-                }
-                pageColumns.push({
-                    tag: 'column',
-                    width: 'weighted',
-                    weight: 1,
-                    vertical_align: 'center',
-                    elements: [
-                        {
-                            tag: 'div',
-                            text: {
-                                tag: 'lark_md',
-                                content: `**第 ${currentPage}/${totalPages} 页**（共 ${totalCount} 项）`,
-                            },
-                        },
-                    ],
+                const bar = paginationBar({
+                    cmd: 'ls.page',
+                    offset,
+                    pageSize: CommandRouter.LS_PAGE_SIZE,
+                    total: totalCount,
+                    extra: { path: targetDir },
+                    label: `**第 ${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: 'ls.page',
-                                            path: targetDir,
-                                            offset: offset + CommandRouter.LS_PAGE_SIZE,
-                                        },
-                                    },
-                                ],
-                            },
-                        ],
-                    });
-                }
                 elements.push({ tag: 'hr' });
-                elements.push({ tag: 'column_set', columns: pageColumns });
+                elements.push(bar);
             }
             return {
                 card: {
@@ -2375,7 +2435,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 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 safeOffset = clampInt(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;
@@ -2485,73 +2545,22 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     // 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}）`,
-                                    },
-                                },
-                            ],
+                        const bar = paginationBar({
+                            cmd: 'ws.page',
+                            offset: safeOffset,
+                            pageSize: WS_PAGE_SIZE,
+                            total: totalCount,
+                            label: `**${currentPage}/${totalPages}**（${totalCount}）`,
+                            prevText: '⬅',
+                            nextText: '➡',
                         });
-                        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 });
+                        bodyElements.push(bar);
                     }
                 }
                 const card = {
                     schema: '2.0',
-                    config: { wide_screen_mode: true },
+                    config: { wide_screen_mode: true, update_multi: true },
                     header: { title: { tag: 'plain_text', content: 'Workspaces' } },
                     body: { elements: bodyElements },
                 };
@@ -2566,6 +2575,10 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      * misleading "未找到". Reuses the same card-builder helpers (markdownDiv) as
      * the normal resume card; enforceCardBudget still applies at send time.
      */
+    /**
+     * /resume 核心实现（public：handleResumePage / handle / resume.use 共用，
+     * 也是测试的直接 seam，避免测试用 @ts-expect-error 摸私有方法）。
+     */
     cmdResume(args, ctx, offset = 0) {
         const entry = this.sessionStore.get(ctx.userId);
         const cwd = entry?.cwd;
@@ -2618,82 +2631,39 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 agentKind,
                 maxEvents: AUTO_RESUME_MAX_EVENTS,
             });
-            // Build card header with displayTitle (aiTitle or last user message) and recap
-            let header = `📂 \`${cwd}\`\n会话: **${sessionIdArg}**`;
-            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');
-            }
-            // Build card with session history
-            const elements = [markdownDiv(header), { tag: 'hr' }];
-            // Fold session history into collapsible panels: the last 2 events stay
-            // expanded so the user sees the most recent context without clicking;
-            // older events are collapsed to keep the card compact.
-            if (content.length === 0) {
-                elements.push(markdownDiv('_该会话暂无新消息可显示（最后一条为用户输入）_'));
-            }
-            else {
-                content.forEach((ev, i) => {
-                    elements.push(sessionEventPanel(ev, i, content.length, 2, this.config.defaultAgent));
-                });
-            }
-            // Add usage stats at the end
-            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();
-            }
-            // Add action buttons - use column_set+column for 2.0
-            const buttons = [];
-            // Stop button for active sessions.
-            // isActive is only true when an in-memory activeRun exists, so
-            // activeRunRunId is always set here. See buildAutoResumeCard for details.
-            if (isActive) {
-                buttons.push({
-                    tag: 'button',
-                    text: { tag: 'plain_text', content: '⏹ 终止' },
-                    type: 'danger',
-                    behaviors: [{ type: 'callback', value: { cmd: 'stop', runId: activeRunRunId, cwd } }],
-                });
-            }
-            if (buttons.length > 0) {
-                elements.push({
-                    tag: 'column_set',
-                    columns: buttons.map((btn) => ({
-                        tag: 'column',
-                        width: 'auto',
-                        elements: [btn],
-                    })),
-                });
-            }
-            const card = {
-                schema: '2.0',
-                config: { wide_screen_mode: true },
-                header: {
-                    title: {
-                        tag: 'plain_text',
-                        content: `${isActive ? '⏳ 恢复会话（完成中）' : '🔁 恢复会话'} · ${agentDisplayName(agentKind)}`,
-                    },
-                },
-                body: { elements },
-            };
+            // 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 = Math.min(Math.max(limit ?? RESUME_PAGE_SIZE, 1), RESUME_PAGE_SIZE);
+        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) {
@@ -2713,7 +2683,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             // 这样越界 offset clamp 后 prev/next 仍按 pageSize 步长移动，不会错位。
             const maxOffset = Math.max(0, Math.ceil(pageResult.total / pageSize) - 1) * pageSize;
             if (pageOffset < 0 || pageOffset > maxOffset) {
-                pageOffset = Math.min(Math.max(pageOffset, 0), maxOffset);
+                pageOffset = clampInt(pageOffset, 0, maxOffset);
                 pageResult = reader.listSessions(cwd, { limit: pageSize, offset: pageOffset });
             }
         }
@@ -2837,80 +2807,16 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         if (total > pageSize) {
             const totalPages = Math.ceil(total / pageSize);
             const currentPage = Math.floor(pageOffset / pageSize) + 1;
-            const hasPrev = pageOffset > 0;
-            const hasNext = pageOffset + pageSize < total;
-            // Build columns dynamically — Feishu rejects empty elements[] in a column
-            // (ErrCode 200621: "no tag specified"). Only include columns that have content.
-            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: 'resume.page',
-                                        agent: agentKind,
-                                        offset: pageOffset - pageSize,
-                                        pageSize,
-                                    },
-                                },
-                            ],
-                        },
-                    ],
-                });
-            }
-            pageColumns.push({
-                tag: 'column',
-                width: 'weighted',
-                weight: 1,
-                vertical_align: 'center',
-                elements: [
-                    {
-                        tag: 'div',
-                        text: {
-                            tag: 'lark_md',
-                            content: `第 ${currentPage}/${totalPages} 页 · 共 ${total} 个会话`,
-                        },
-                    },
-                ],
+            const bar = paginationBar({
+                cmd: 'resume.page',
+                offset: pageOffset,
+                pageSize,
+                total,
+                extra: { agent: agentKind, pageSize },
+                label: `第 ${currentPage}/${totalPages} 页 · 共 ${total} 个会话`,
             });
-            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: 'resume.page',
-                                        agent: agentKind,
-                                        offset: pageOffset + pageSize,
-                                        pageSize,
-                                    },
-                                },
-                            ],
-                        },
-                    ],
-                });
-            }
             elements.push({ tag: 'hr' });
-            elements.push({ tag: 'column_set', columns: pageColumns });
+            elements.push(bar);
         }
         const card = {
             schema: '2.0',
@@ -3138,7 +3044,9 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         // Direct inline construction (not via ConfigField) so that text (display label)
         // and value (agentKind for config storage) can differ — uninstalled agents get
         // a "⚠️ (未安装)" suffix in the label while the value stays clean.
-        const allAgents = listRegisteredAgents();
+        // 固定展示顺序（Codex → Claude → OpenCode → Pi → Kimi），
+        // 明确未安装的 agent 排到后面（getCachedAvailability === false）。
+        const allAgents = sortAgentsForDisplay(listRegisteredAgents(), getCachedAvailability);
         const agentOptions = allAgents.map((kind) => {
             const available = getCachedAvailability(kind);
             const label = available === false ? `${agentDisplayName(kind)} ⚠️ (未安装)` : agentDisplayName(kind);
@@ -3232,11 +3140,14 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
         return { card };
     }
+    /** /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') {
+        // /order — list orders + aliases (CardKit 2.0 with pagination)
+        // `/order alias`（无参数）也并入列表卡片。
+        if (!sub || sub === 'list' || (sub === 'alias' && !args[1])) {
             this.orderStore.reload();
+            this.aliasStore.reload();
             const allOrders = this.orderStore.get();
             const elements = [];
             if (allOrders.length === 0) {
@@ -3248,7 +3159,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 const totalPages = Math.max(1, Math.ceil(totalCount / ORDER_PAGE_SIZE));
                 // Clamp offset to last page boundary to avoid empty pages
                 const maxOffset = Math.max(0, (totalPages - 1) * ORDER_PAGE_SIZE);
-                const safeOffset = Math.min(Math.max(offset, 0), maxOffset);
+                const safeOffset = clampInt(offset, 0, maxOffset);
                 const currentPage = Math.floor(safeOffset / ORDER_PAGE_SIZE) + 1;
                 const pageOrders = allOrders.slice(safeOffset, safeOffset + ORDER_PAGE_SIZE);
                 const hasPagination = totalCount > ORDER_PAGE_SIZE;
@@ -3303,74 +3214,31 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 }
                 // Pagination bar (only shown when there are more items than ORDER_PAGE_SIZE)
                 if (hasPagination) {
-                    const hasPrev = safeOffset > 0;
-                    const hasNext = safeOffset + ORDER_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: 'order.page',
-                                                offset: safeOffset - ORDER_PAGE_SIZE,
-                                            },
-                                        },
-                                    ],
-                                },
-                            ],
-                        });
-                    }
-                    pageColumns.push({
-                        tag: 'column',
-                        width: 'weighted',
-                        weight: 1,
-                        vertical_align: 'center',
-                        elements: [
-                            {
-                                tag: 'div',
-                                text: {
-                                    tag: 'lark_md',
-                                    content: `**第 ${currentPage}/${totalPages} 页**（共 ${totalCount} 条）`,
-                                },
-                            },
-                        ],
+                    const bar = paginationBar({
+                        cmd: 'order.page',
+                        offset: safeOffset,
+                        pageSize: ORDER_PAGE_SIZE,
+                        total: totalCount,
+                        label: `**第 ${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: 'order.page',
-                                                offset: safeOffset + ORDER_PAGE_SIZE,
-                                            },
-                                        },
-                                    ],
-                                },
-                            ],
-                        });
-                    }
                     elements.push({ tag: 'hr' });
-                    elements.push({ tag: 'column_set', columns: pageColumns });
+                    elements.push(bar);
+                }
+            }
+            // 别名区：并入 /order 卡片（`/order alias` 列出全部）。
+            const aliases = this.aliasStore.list();
+            if (aliases.length > 0) {
+                elements.push({ tag: 'hr' });
+                elements.push({
+                    tag: 'div',
+                    text: { tag: 'lark_md', content: '**⚡ 别名**（输入 $name 触发）' },
+                });
+                for (const alias of aliases) {
+                    const text = alias.text.length > 100 ? alias.text.slice(0, 97) + '...' : alias.text;
+                    elements.push({
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: `$${alias.name} → ${text}` },
+                    });
                 }
             }
             return {
@@ -3382,6 +3250,47 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 },
             };
         }
+        // /order alias <name> <text> — 注册；/order alias <name> — 查看；/order alias remove <name> — 删除
+        if (sub === 'alias') {
+            const name = args[1];
+            if (name === 'remove') {
+                const target = args[2];
+                if (!target) {
+                    return { text: '用法: /order alias remove <name>' };
+                }
+                // remove 是保留子命令，不能作为别名名：后面跟多词文本说明用户想注册
+                // 名为 remove 的别名，明确报错而不是静默删除已存在的 target（P2 review）。
+                if (args.length > 3) {
+                    return { text: '`remove` 是保留子命令，不能作为别名名，请换一个名称' };
+                }
+                const entry = this.aliasStore.get(target);
+                if (!entry) {
+                    return { text: `别名 $${target} 不存在` };
+                }
+                this.aliasStore.remove(target);
+                // 回显原内容：单词场景无法区分「注册 remove」与「删除」，误删后
+                // 用户可直接按回显内容重新注册，消除静默破坏（P3 review）。
+                const preview = entry.text.length > 50 ? entry.text.slice(0, 50) + '...' : entry.text;
+                return { text: `✅ 已删除别名 $${target}（原内容：${preview}）` };
+            }
+            const text = args.slice(2).join(' ');
+            if (!text) {
+                const entry = name ? this.aliasStore.get(name) : undefined;
+                if (!entry) {
+                    return { text: name ? `别名 $${name} 不存在` : '用法: /order alias <name> <text>' };
+                }
+                return { text: `$${entry.name} → ${entry.text}` };
+            }
+            try {
+                const existed = this.aliasStore.has(name);
+                this.aliasStore.set(name, text);
+                const preview = text.length > 50 ? text.slice(0, 50) + '...' : text;
+                return { text: `${existed ? '✅ 已更新别名' : '✅ 已保存别名'} $${name} → ${preview}` };
+            }
+            catch (err) {
+                return { text: `保存失败: ${err.message}` };
+            }
+        }
         // /order save <text>
         if (sub === 'save') {
             const text = args.slice(1).join(' ');
@@ -3396,10 +3305,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 return { text: `保存失败: ${err.message}` };
             }
         }
-        return { text: '用法: /order [list|save <text>]' };
+        return { text: '用法: /order [list|save <text>|alias <name> <text>|alias remove <name>]' };
     }
 }
-// --- Re-exported from ./utils.js (moved for decomposition) ---
-// formatUsageStats is shared by run-renderer and bridge via ../router/index.js.
-export { formatUsageStats } from './utils.js';
 //# sourceMappingURL=index.js.map