lark-remote 0.5.19 → 0.5.21

package/dist/router/commands/ws.js

@@ -2,188 +2,233 @@ import { cardButton } from '../../card/card-shared.js';
 import { paginationBar, searchBar } from '../../card/card-helpers.js';
 import { pageSlice } from '../paging.js';
 import { resolveDirectory } from '../path-validation.js';
+import { withQuery } from './ls.js';
 export const WS_PAGE_SIZE = 5;
-export function buildWsCommand(args, ctx, offset, q, deps) {
-    const sub = args[0]?.toLowerCase();
-    switch (sub) {
-        case 'save': {
-            const name = args[1];
-            if (!name)
-                return { text: '用法: /ws save <name>' };
-            const cwd = deps.getCwd(ctx.userId);
-            if (!cwd)
-                return { text: '请先 /cd 设置工作目录' };
-            deps.saveWorkspace(name, cwd);
-            return { text: `已保存 workspace "${name}" -> ${cwd}` };
-        }
-        case 'use': {
-            const name = args[1];
-            if (!name)
-                return { text: '用法: /ws use <name>' };
-            const wsPath = deps.getWorkspace(name);
-            if (!wsPath)
-                return { text: `workspace "${name}" 不存在` };
-            const resolution = resolveDirectory(wsPath);
-            if (!resolution.ok) {
-                if (resolution.reason === 'missing')
-                    return { text: `路径不存在: ${wsPath}` };
-                if (resolution.reason === 'not_directory')
-                    return { text: `不是目录: ${wsPath}` };
-                return { text: `路径无效: ${wsPath}` };
-            }
-            deps.touchWorkspace(name);
-            return deps.switchCwd(ctx.userId, resolution.canonical, ctx);
-        }
-        case 'remove': {
-            const name = args[1];
-            if (!name)
-                return { text: '用法: /ws remove <name>' };
-            if (!deps.hasWorkspace(name))
-                return { text: `workspace "${name}" 不存在` };
-            deps.removeWorkspace(name);
-            return { text: `已删除 workspace "${name}"` };
-        }
-        case 'list':
-        default: {
-            const filter = q?.trim() || undefined;
-            const entries = deps.listWorkspaces();
-            const currentCwd = deps.getCwd(ctx.userId);
-            const sortMode = deps.getSortMode(ctx.userId);
-            if (sortMode === 'recent') {
-                entries.sort((a, b) => {
-                    if (b.lastUsedAt !== a.lastUsedAt)
-                        return b.lastUsedAt - a.lastUsedAt;
-                    return a.name.localeCompare(b.name);
-                });
-            }
-            else {
-                entries.sort((a, b) => a.name.localeCompare(b.name));
-            }
-            const ql = filter?.toLowerCase();
-            const visible = ql
-                ? entries.filter((entry) => entry.name.toLowerCase().includes(ql) || entry.path.toLowerCase().includes(ql))
-                : entries;
-            const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(visible, offset, WS_PAGE_SIZE);
-            const bodyElements = [
+// ── 模块级命名原语 ─────────────────────────────────────────────────────────
+// crapper 把函数内部定义的箭头函数/闭包的决策点也算进外层函数：比较器、过滤
+// 谓词、payload 三元一律抽成模块顶层命名函数，显式传参（见 common/tool-summary.ts）。
+// `withQuery`（q 恒为最后一个字段，钉住卡片 payload 顺序）从 ls.ts 复用，
+// ls / ws 共用同一实现，避免跨文件同形函数。
+/** 筛选命中：名称或路径（大小写不敏感子串）。 */
+function wsMatchesQuery(entry, ql) {
+    return entry.name.toLowerCase().includes(ql) || entry.path.toLowerCase().includes(ql);
+}
+function wsFilterEntries(entries, ql) {
+    const visible = [];
+    for (const entry of entries) {
+        if (wsMatchesQuery(entry, ql))
+            visible.push(entry);
+    }
+    return visible;
+}
+function wsCompareRecent(a, b) {
+    if (b.lastUsedAt !== a.lastUsedAt)
+        return b.lastUsedAt - a.lastUsedAt;
+    return a.name.localeCompare(b.name);
+}
+function wsCompareName(a, b) {
+    return a.name.localeCompare(b.name);
+}
+function wsSortLabels(sortMode) {
+    return sortMode === 'recent'
+        ? { currentLabel: '🕐 最近使用', switchLabel: '🔤 字母顺序' }
+        : { currentLabel: '🔤 字母顺序', switchLabel: '🕐 最近使用' };
+}
+/** 单个 workspace 行的 3 个元素（div + column_set + hr）。 */
+function wsEntryElements(entry, safeOffset, filter) {
+    return [
+        {
+            tag: 'div',
+            text: { tag: 'lark_md', content: `**${entry.name}** → \`${entry.path}\`` },
+        },
+        {
+            tag: 'column_set',
+            columns: [
                 {
-                    tag: 'div',
-                    text: {
-                        tag: 'lark_md',
-                        content: `📂 当前工作目录：\`${currentCwd ?? '(未设置)'}\``,
-                    },
+                    tag: 'column',
+                    width: 'auto',
+                    elements: [
+                        cardButton('切换', withQuery({ cmd: 'ws.use', name: entry.name, offset: safeOffset }, filter), { type: 'primary', size: 'small' }),
+                    ],
                 },
-                { tag: 'hr' },
-                searchBar({
-                    cmd: 'ws.filter',
-                    placeholder: '搜索名称或路径，输完回车',
-                    currentQuery: filter,
-                }),
-            ];
-            if (filter) {
-                bodyElements.push({
-                    tag: 'div',
-                    text: {
-                        tag: 'lark_md',
-                        content: `🔍 筛选："${filter}" · 命中 ${totalCount} 个 workspace（点「清除筛选」取消）`,
-                    },
-                });
-            }
-            if (entries.length === 0 && !filter) {
-                bodyElements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: '没有保存的 workspace' },
-                });
-            }
-            else if (filter && visible.length === 0) {
-                bodyElements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `🔍 无匹配条目（关键词："${filter}"）` },
-                });
-            }
-            else {
-                const currentLabel = sortMode === 'recent' ? '🕐 最近使用' : '🔤 字母顺序';
-                const switchLabel = sortMode === 'recent' ? '🔤 字母顺序' : '🕐 最近使用';
-                bodyElements.push({ tag: 'hr' }, {
-                    tag: 'column_set',
-                    columns: [
-                        {
-                            tag: 'column',
-                            width: 'weighted',
-                            weight: 1,
-                            vertical_align: 'center',
-                            elements: [
-                                {
-                                    tag: 'div',
-                                    text: { tag: 'lark_md', content: `排序：${currentLabel}` },
-                                },
-                            ],
-                        },
+                {
+                    tag: 'column',
+                    width: 'auto',
+                    elements: [
+                        cardButton('删除', withQuery({ cmd: 'ws.remove', name: entry.name, offset: safeOffset }, filter), { type: 'danger', size: 'small' }),
+                    ],
+                },
+            ],
+        },
+        { tag: 'hr' },
+    ];
+}
+/** 排序栏 + 所有行；末尾多余 hr 由调用方 pop（与原实现完全一致）。 */
+function wsListRows(pageEntries, sortMode, safeOffset, filter) {
+    const { currentLabel, switchLabel } = wsSortLabels(sortMode);
+    const rows = [
+        { tag: 'hr' },
+        {
+            tag: 'column_set',
+            columns: [
+                {
+                    tag: 'column',
+                    width: 'weighted',
+                    weight: 1,
+                    vertical_align: 'center',
+                    elements: [
                         {
-                            tag: 'column',
-                            width: 'auto',
-                            elements: [
-                                cardButton(`切换为 ${switchLabel}`, { cmd: 'ws.sort', ...(filter ? { q: filter } : {}) }, { type: 'default', size: 'small' }),
-                            ],
+                            tag: 'div',
+                            text: { tag: 'lark_md', content: `排序：${currentLabel}` },
                         },
                     ],
-                }, { tag: 'hr' });
-                for (const entry of pageEntries) {
-                    bodyElements.push({
-                        tag: 'div',
-                        text: { tag: 'lark_md', content: `**${entry.name}** → \`${entry.path}\`` },
-                    }, {
-                        tag: 'column_set',
-                        columns: [
-                            {
-                                tag: 'column',
-                                width: 'auto',
-                                elements: [
-                                    cardButton('切换', {
-                                        cmd: 'ws.use',
-                                        name: entry.name,
-                                        offset: safeOffset,
-                                        ...(filter ? { q: filter } : {}),
-                                    }, { type: 'primary', size: 'small' }),
-                                ],
-                            },
-                            {
-                                tag: 'column',
-                                width: 'auto',
-                                elements: [
-                                    cardButton('删除', {
-                                        cmd: 'ws.remove',
-                                        name: entry.name,
-                                        offset: safeOffset,
-                                        ...(filter ? { q: filter } : {}),
-                                    }, { type: 'danger', size: 'small' }),
-                                ],
-                            },
-                        ],
-                    }, { tag: 'hr' });
-                }
-                bodyElements.pop();
-                if (hasPagination) {
-                    bodyElements.push({ tag: 'hr' }, ...paginationBar({
-                        cmd: 'ws.page',
-                        offset: safeOffset,
-                        pageSize: WS_PAGE_SIZE,
-                        total: totalCount,
-                        extra: filter ? { q: filter } : {},
-                        label: `**${currentPage}/${totalPages}**（${totalCount}）`,
-                        prevText: '⬅',
-                        nextText: '➡',
-                    }));
-                }
-            }
-            return {
-                card: {
-                    schema: '2.0',
-                    config: { wide_screen_mode: true, update_multi: true },
-                    header: { title: { tag: 'plain_text', content: 'Workspaces' } },
-                    body: { elements: bodyElements },
                 },
-            };
+                {
+                    tag: 'column',
+                    width: 'auto',
+                    elements: [
+                        cardButton(`切换为 ${switchLabel}`, withQuery({ cmd: 'ws.sort' }, filter), {
+                            type: 'default',
+                            size: 'small',
+                        }),
+                    ],
+                },
+            ],
+        },
+        { tag: 'hr' },
+    ];
+    for (const entry of pageEntries)
+        rows.push(...wsEntryElements(entry, safeOffset, filter));
+    return rows;
+}
+function wsPagination(totalCount, totalPages, safeOffset, currentPage, filter) {
+    return [
+        { tag: 'hr' },
+        ...paginationBar({
+            cmd: 'ws.page',
+            offset: safeOffset,
+            pageSize: WS_PAGE_SIZE,
+            total: totalCount,
+            extra: withQuery({}, filter),
+            label: `**${currentPage}/${totalPages}**（${totalCount}）`,
+            prevText: '⬅',
+            nextText: '➡',
+        }),
+    ];
+}
+function wsSave(args, ctx, _offset, _q, deps) {
+    const name = args[1];
+    if (!name)
+        return { text: '用法: /ws save <name>' };
+    const cwd = deps.getCwd(ctx.userId);
+    if (!cwd)
+        return { text: '请先 /cd 设置工作目录' };
+    deps.saveWorkspace(name, cwd);
+    return { text: `已保存 workspace "${name}" -> ${cwd}` };
+}
+function wsUse(args, ctx, _offset, _q, deps) {
+    const name = args[1];
+    if (!name)
+        return { text: '用法: /ws use <name>' };
+    const wsPath = deps.getWorkspace(name);
+    if (!wsPath)
+        return { text: `workspace "${name}" 不存在` };
+    const resolution = resolveDirectory(wsPath);
+    if (!resolution.ok) {
+        if (resolution.reason === 'missing')
+            return { text: `路径不存在: ${wsPath}` };
+        if (resolution.reason === 'not_directory')
+            return { text: `不是目录: ${wsPath}` };
+        return { text: `路径无效: ${wsPath}` };
+    }
+    deps.touchWorkspace(name);
+    return deps.switchCwd(ctx.userId, resolution.canonical, ctx);
+}
+function wsRemove(args, _ctx, _offset, _q, deps) {
+    const name = args[1];
+    if (!name)
+        return { text: '用法: /ws remove <name>' };
+    if (!deps.hasWorkspace(name))
+        return { text: `workspace "${name}" 不存在` };
+    deps.removeWorkspace(name);
+    return { text: `已删除 workspace "${name}"` };
+}
+function wsList(_args, ctx, offset, q, deps) {
+    const filter = q?.trim() || undefined;
+    const entries = deps.listWorkspaces();
+    const currentCwd = deps.getCwd(ctx.userId);
+    const sortMode = deps.getSortMode(ctx.userId);
+    if (sortMode === 'recent') {
+        entries.sort(wsCompareRecent);
+    }
+    else {
+        entries.sort(wsCompareName);
+    }
+    const ql = filter?.toLowerCase();
+    const visible = ql ? wsFilterEntries(entries, ql) : entries;
+    const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(visible, offset, WS_PAGE_SIZE);
+    const bodyElements = [
+        {
+            tag: 'div',
+            text: {
+                tag: 'lark_md',
+                content: `📂 当前工作目录：\`${currentCwd ?? '(未设置)'}\``,
+            },
+        },
+        { tag: 'hr' },
+        searchBar({
+            cmd: 'ws.filter',
+            placeholder: '搜索名称或路径，输完回车',
+            currentQuery: filter,
+        }),
+    ];
+    if (filter) {
+        bodyElements.push({
+            tag: 'div',
+            text: {
+                tag: 'lark_md',
+                content: `🔍 筛选："${filter}" · 命中 ${totalCount} 个 workspace（点「清除筛选」取消）`,
+            },
+        });
+    }
+    if (entries.length === 0 && !filter) {
+        bodyElements.push({
+            tag: 'div',
+            text: { tag: 'lark_md', content: '没有保存的 workspace' },
+        });
+    }
+    else if (filter && visible.length === 0) {
+        bodyElements.push({
+            tag: 'div',
+            text: { tag: 'lark_md', content: `🔍 无匹配条目（关键词："${filter}"）` },
+        });
+    }
+    else {
+        bodyElements.push(...wsListRows(pageEntries, sortMode, safeOffset, filter));
+        bodyElements.pop();
+        if (hasPagination) {
+            bodyElements.push(...wsPagination(totalCount, totalPages, safeOffset, currentPage, filter));
         }
     }
+    return {
+        card: {
+            schema: '2.0',
+            config: { wide_screen_mode: true, update_multi: true },
+            header: { title: { tag: 'plain_text', content: 'Workspaces' } },
+            body: { elements: bodyElements },
+        },
+    };
+}
+/** 子命令 → handler。用 Map 而非对象字面量：`constructor`/`toString` 这类键会命中 Object.prototype。 */
+const WS_SUB_HANDLERS = new Map([
+    ['save', wsSave],
+    ['use', wsUse],
+    ['remove', wsRemove],
+    ['list', wsList],
+]);
+export function buildWsCommand(args, ctx, offset, q, deps) {
+    const sub = args[0]?.toLowerCase();
+    const handler = sub === undefined ? undefined : WS_SUB_HANDLERS.get(sub);
+    return handler ? handler(args, ctx, offset, q, deps) : wsList(args, ctx, offset, q, deps);
 }
 //# sourceMappingURL=ws.js.map

package/dist/router/config/dsh.d.ts

@@ -17,22 +17,18 @@
  */
 import type { AgentConfigCardBuilder, ConfigField } from './types.js';
 import { type AppConfig } from '../../config/index.js';
+import { type DshCatalogClientFactory } from '../../runner/dsh/catalog-probe.js';
 import type { DshModelCatalogValue, DshPermissionCatalogValue, DshPresetListValue } from '../../dsh/types.js';
-/** DshConfigBuilder 预取只依赖的 client 方法子集。 */
-export interface DshCatalogClient {
-    listModels(): Promise<DshModelCatalogValue>;
-    listPresets(): Promise<DshPresetListValue>;
-    listPermissionPresets(): Promise<DshPermissionCatalogValue>;
-}
+export type { DshCatalogClient } from '../../runner/dsh/catalog-probe.js';
 export declare class DshConfigBuilder implements AgentConfigCardBuilder {
     /** 最近一次预取用的 host；host 变更时缓存失效。 */
     private prefetchHost;
     private modelCatalog;
     private presets;
     private permissionCatalog;
-    /** 可注入 client 工厂（测试用）；默认生产实现。 */
+    /** 可注入 client 工厂（测试用）；默认生产实现在 runner/dsh/catalog-probe。 */
     private readonly clientFactory;
-    constructor(clientFactory?: (baseUrl: string, token?: string, credentialsFile?: string) => DshCatalogClient);
+    constructor(clientFactory?: DshCatalogClientFactory);
     /**
      * 异步预取模型/预设目录。失败/离线静默回退固定兜底清单，卡不依赖 DSH
      * 服务在线。`force` 用于打开 /config 时强制刷新（在 DSH Web UI 新增

package/dist/router/config/dsh.js

@@ -17,7 +17,7 @@
  */
 import { DEFAULT_DSH_HOST } from '../../config/index.js';
 import { pickMiddleValue } from './common/model-patch.js';
-import { DshClient } from '../../runner/dsh/client.js';
+import { createDshCatalogClient, } from '../../runner/dsh/catalog-probe.js';
 import { getLogger } from '../../logger/index.js';
 /** 旧配置没有 provider 时的生效值（与 DshRunner 的兼容规则一致）。 */
 const LEGACY_PROVIDER = 'deepseek-official';
@@ -46,17 +46,10 @@ export class DshConfigBuilder {
     modelCatalog;
     presets;
     permissionCatalog;
-    /** 可注入 client 工厂（测试用）；默认生产实现。 */
+    /** 可注入 client 工厂（测试用）；默认生产实现在 runner/dsh/catalog-probe。 */
     clientFactory;
     constructor(clientFactory) {
-        this.clientFactory =
-            clientFactory ??
-                ((base, token, credentialsFile) => new DshClient(base, {
-                    token,
-                    credentialsFile,
-                    // 卡片预取是交互路径：DSH 卡死时最多等 5 秒后回退固定清单。
-                    requestTimeoutMs: 5_000,
-                }));
+        this.clientFactory = clientFactory ?? createDshCatalogClient;
     }
     /**
      * 异步预取模型/预设目录。失败/离线静默回退固定兜底清单，卡不依赖 DSH

package/dist/router/config/kimi.js

@@ -9,7 +9,7 @@ import { DEFAULT_TURN_IDLE_TIMEOUT_MINUTES } from '../../config/index.js';
 import { pickMiddleValue } from './common/model-patch.js';
 import { turnIdleTimeoutField } from './common/turn-idle.js';
 const PERMISSION_MODE_OPTIONS = [
-    // kimi 0.40.0（2026-09-02）起官方语义：manual=始终询问 / yolo=必要时询问 / auto=完全自动
+    // kimi 0.40.0 起官方语义：manual=始终询问 / yolo=必要时询问 / auto=完全自动
     { text: 'manual（始终询问）', value: 'manual' },
     { text: 'auto（完全自动）', value: 'auto' },
     { text: 'yolo（必要时询问）', value: 'yolo' },

package/dist/router/config/types.d.ts

@@ -21,7 +21,7 @@ export interface ConfigField {
      * select=下拉、input=文本框、note=纯说明行（无回调）。
      *
      * 没有 boolean：卡片曾留着一套「开关」控件（`config.toggle`），但全仓没有
-     * 任何字段声明它，2026-10-27 成套删除。原则是**卡片只放配得了的控件**，
+     * 任何字段声明它，已成套删除。原则是**卡片只放配得了的控件**，
      * 实现细节与未上卡的键走 YAML（见 `buildConfigCard` 的分 tab 注释）。
      */
     type: 'select' | 'input' | 'note';

package/dist/router/config-diff.js

@@ -1,6 +1,6 @@
 /**
  * Config diff / nested-value helpers extracted from CommandRouter
- * (2026-09 round-2 simplification). Pure functions — no router state —
+ * (round-2 simplification). Pure functions — no router state —
  * previously inlined as methods (collectDiff recursed only into itself).
  */
 import { mapAgentKey, walkNestedContainer, assertSafeKeyPart } from '../config/index.js';

package/dist/router/index.d.ts

@@ -121,7 +121,7 @@ export declare const DIRECT_RETURN_CMDS: ReadonlySet<string>;
  * sessionId / cwd / defaultAgent，必须与入站装配器的 700ms 静默窗口定序：
  * 控制层（index.ts）在执行它们之前先 flush 该 user/chat 的装配窗口，保证窗口内
  * 先到的文本消息在本动作之前 commit（绑定动作前的旧状态）。否则窗口内消息会
- * 漂移到动作之后的新状态（2026-10-07 事故：输入「重新构建」后立即点「新会话」，
+ * 漂移到动作之后的新状态（输入「重新构建」后立即点「新会话」，
  * 消息落到新会话）。
  *
  * 文本命令（/new、/cd、/resume、/config）已由 index.ts 命令分支先 flush，
@@ -132,7 +132,7 @@ export declare const SESSION_MUTATING_ACTION_CMDS: ReadonlySet<string>;
  * 会产生压缩工作的卡片动作（单源）。这类条目占用 lane 时必须自报身份：
  * 排队卡写明「正在执行: 🗜 Compact」而不是「前面还有 0 条」，并且期间禁用
  * 「立即执行」——该按钮走 interruptCurrentRun，会连带中断正在跑的压缩
- * （2026-10-09 线上：Compact 占 lane 期间新消息的排队卡自相矛盾，且按钮
+ * （Compact 占 lane 期间新消息的排队卡自相矛盾，且按钮
  * 一点就会杀掉压缩）。同时它们也不允许编辑（预览不是用户文本）。
  */
 export declare const COMPACT_ACTION_CMDS: ReadonlySet<string>;
@@ -174,8 +174,8 @@ export declare class CommandRouter {
      *
      * 草稿（pendingConfig）是全局一份：/config 文本命令重开卡片时沿用同一份草稿
      * （这是既有语义，不改）。但**视图**是每张卡一份 —— 只刷新被点击的那张，其余
-     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容
-     * （2026-10-08 发现的缺陷）。这里记住所有交互过的 config 卡，任何一次编辑/保存
+     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容。
+     * 这里记住所有交互过的 config 卡，任何一次编辑/保存
      * 后把草稿刷到每张卡，保证「看到的就是会保存的」。
      */
     private configCardIds;
@@ -186,7 +186,7 @@ export declare class CommandRouter {
      * 条目的身份必须与「一次入队动作」1:1（queuedTasks 的定位、queueCardMessages
      * 的卡片更新、taskIndex 的取消判据全部按这个 key 做 lookup）。复用卡片 id
      * 会让同 key 的多条任务互相顶替：位置显示命中最早那条兄弟、第一条开始时删掉
-     * 索引导致其余兄弟被判「已撤销」静默丢弃（2026-10-08 线上：连点 Compact
+     * 索引导致其余兄弟被判「已撤销」静默丢弃（连点 Compact
      * 三次 → 三张排队卡都显示「第 1 位」、两张永久停在「等待中」，只压缩一次）。
      *
      * Date.now() 不够（两次同步调用可落在同一毫秒）；计数器与时间无关，恒唯一。
@@ -207,7 +207,7 @@ export declare class CommandRouter {
     /** Session reader 注册中心（public：测试注入/读取，替代 as unknown as）。 */
     sessionReaderRegistry: SessionReaderRegistry;
     /**
-     * 串行化 config.* 卡片回调（2026-07-04）。
+     * 串行化 config.* 卡片回调。
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，**不进串行队列**，
      * 多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
      * `updateCardInPlace` → Feishu API 乱序到达，控件卡死在某个状态。
@@ -257,7 +257,7 @@ export declare class CommandRouter {
     /**
      * Route a message: if it starts with /, handle as command; if it starts with !, execute as bash; otherwise forward to Claude.
      *
-     * 命令识别前置条件（2026-09-15修复，`inbound-unified-input-design.md` §5.6）：
+     * 命令识别前置条件（`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -279,6 +279,29 @@ export declare class CommandRouter {
      * Validates payload and dispatches to the corresponding command.
      */
     handleCardAction(value: CardActionPayload, ctx: CommandContext): Promise<CardActionResponse | void>;
+    /**
+     * resume.use: 从 /resume 列表卡切换到所选会话。
+     */
+    private handleResumeUse;
+    /** new-session: 清空当前会话绑定，下一条消息开始全新对话。 */
+    private handleNewSession;
+    /** compact: 对当前会话发起压缩（bridge 收口）。 */
+    private handleCompact;
+    /** resume.compact: 对 /resume 选中的历史会话发起压缩（bridge 收口）。 */
+    private handleResumeCompact;
+    /**
+     * Help card buttons: help.<cmd> → execute /<cmd>.
+     * /exit、/restart 等命令通过 pendingExit 表达"回复送达后退出"。
+     * handle() 在 sendResult 后消费它；help.* 按钮点击走 handleCardAction，
+     * 必须同样消费，否则点击 /restart 按钮 spawn 成功后旧进程不退出，
+     * 新进程撞单例锁退出 → 重启两头落空（2026-08-01 红绿 anchor 锁定）。
+     */
+    private handleHelpAction;
+    /**
+     * Design constraint: miss paths must reply via bridge.sendResult —
+     * don't silently swallow unknown card actions.
+     */
+    private handleUnknownCardAction;
     /**
      * Handle approval-related card actions.
      * Routes to the appropriate bridge method based on value.cmd.
@@ -553,7 +576,7 @@ export declare class CommandRouter {
      */
     private refreshConfigCards;
     /**
-     * 串行化 config.* 卡片回调（2026-07-04 修复连击卡死 bug）。
+     * 串行化 config.* 卡片回调（修复连击卡死 bug）。
      *
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，不进 bridge 的
      * 串行队列；多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
@@ -621,10 +644,19 @@ export declare class CommandRouter {
     private switchCwdAndNotify;
     /** Build card for auto-resumed session with new session button */
     private buildAutoResumeCard;
+    /**
+     * Shared body of the two "resume-like" cards（cwd 切换后的 auto-resume 与
+     * config.save 换 agent）：两者都是同一序列 readSessionDisplayState →
+     * buildResumeActionButtons → buildSessionHistoryCard，差异仅 4 处——
+     * Compact 按钮（仅 auto-resume，canCompactSession 门控）、标题文案、
+     * headerText 的「已恢复…会话」行与可选尾部行、空会话占位——全部参数化，
+     * 共享序列只留一份（Clean Code DRY）。
+     */
+    private buildResumeLikeCard;
     /**
      * 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 new agent has a restored session, renders a Resume card (shared
+     * body via buildResumeLikeCard) with session history + stop/new buttons.
      * When the session was cleared, renders a compact notice card instead.
      */
     private buildConfigSwitchCard;
@@ -655,7 +687,7 @@ export declare class CommandRouter {
      * @param offset  分页起点（条目数）
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
-     *                丢回 工作目录（用户明确反馈过）。
+     *                丢回 工作目录。
      * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
      *                省略/空 = 无筛选。
      */
@@ -684,6 +716,19 @@ export declare class CommandRouter {
      * Paginates with ACTIVE_PAGE_SIZE (default 20) items per page.
      */
     private buildActiveCardFromMemory;
+    /**
+     * Render one section of the /active（/ps）card — the agent-runs and
+     * bash-runs sections are the same loop (title line → per-entry rows →
+     * stop button → trailing hr) and differ only in the title and the two
+     * per-entry content rows, which the caller supplies via `renderRows`.
+     *
+     * Cross-section offset accounting (caller threads `remaining`/`skipped`
+     * through the returned value): entries rendered decrement `remaining` and
+     * consume the offset (`skipped` → 0, so the next section renders from its
+     * own head); a section the offset/page has moved past deducts its full size
+     * from `skipped` instead, so agent runs eat the offset before bash runs do.
+     */
+    private appendActiveCardSection;
     private cmdConfig;
     /**
      * DSH /config 卡片构建前异步预取模型/预设目录（§4.2 动态清单）。