lark-remote 0.1.13 → 0.2.1

package/dist/router/card-helpers.d.ts

@@ -28,13 +28,40 @@ type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
  */
 export declare function sessionEventPanel(ev: AgentSessionContentEvent, index: number, totalEvents: number, tailExpandedCount?: number, agentKind?: string): object;
 export { markdownDiv };
+/** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
+export declare const PAGE_JUMP_INPUT_NAME = "pageInput";
+/** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
+export declare const PAGE_JUMP_INVALID_HINT = "\u8BF7\u8F93\u5165\u6709\u6548\u7684\u9875\u7801\uFF08\u6B63\u6574\u6570\uFF09";
 /**
- * Build a CardKit 2.0 pagination bar (prev-button / page-label / next-button
- * columns). Shared by /ls, /ws, /resume, /active, /order.
+ * 解析分页卡「跳转页码」输入框的提交值。
  *
- * Returns the `column_set` element (plus caller appends an `hr`). Each caller
- * supplies its own callback cmd + extra value fields and label text (semantic
- * differences are preserved, not silently unified).
+ * 三态返回：
+ * - `undefined` — 未输入（空串/非字符串），调用方应回退到 `offset`（上一页/下一页）
+ * - `null`      — 输入非法（非正整数），调用方应回错误 toast 且不刷新卡片
+ * - `number`    — 页码换算出的 offset（页码从 1 开始）
+ */
+export declare function parseJumpOffset(inputValue: unknown, pageSize: number): number | null | undefined;
+/**
+ * Build the CardKit 2.0 pagination block shared by /ls, /ws, /resume, /active,
+ * /order.
+ *
+ * 第一性原理（2026-09-10 窄屏重设计）：分页栏要同时承载「页码信息」和「翻页
+ * 控件」两类需求。旧布局把两者塞进同一行 `column_set`（文案 weighted 4 : 输入
+ * weighted 2），手机窄屏下 auto 按钮先占走固有宽度，剩余宽度按 4:2 切分后文案
+ * 列只有百来像素、输入框只有几十像素——文案折行、输入框窄到没法点。
+ * 拆成两行后每一类都有足够的横向空间：
+ *
+ *   1. 页码文案独占整行（顶层 `div`），窄屏不折行；
+ *   2. 控件行 `column_set` = [上一页 auto] [跳转页码 input weighted] [下一页 auto]，
+ *      input 吃掉 auto 按钮之外的剩余宽度（窄屏约百来像素，桌面端更宽）。
+ *
+ * Returns an array of body elements: `[page-label div, controls column_set]`；
+ * 调用方展开进 `body.elements`（+ 自己的 `hr`）。input 仍留在控件 column_set
+ * 内部，不用 form 容器（form 触发 300123 / 200621 整卡不可用）。CardKit 2.0
+ * input 自带 ✓ 提交图标，提交值经 raw `action.input_value` 回传，见 connector
+ * includeRawEvent + router/card-action-payload.ts。
+ *
+ * 每个调用方自带 callback cmd / extra value / 文案（语义差异保留，不强行统一）。
  *
  * @param opts.cmd       The pagination callback command (e.g. 'ls.page').
  * @param opts.offset    Current page offset.
@@ -53,7 +80,7 @@ export declare function paginationBar(opts: {
     label: string;
     prevText?: string;
     nextText?: string;
-}): object;
+}): object[];
 /**
  * Build a session-history resume card (shared by auto-restore, /resume <id>,
  * config-switch resume, and run-completion notification).

package/dist/router/card-helpers.js

@@ -63,13 +63,51 @@ function eventLabel(ev, agentKind) {
     }
 }
 export { markdownDiv };
+/** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
+export const PAGE_JUMP_INPUT_NAME = 'pageInput';
+/** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
+export const PAGE_JUMP_INVALID_HINT = '请输入有效的页码（正整数）';
 /**
- * Build a CardKit 2.0 pagination bar (prev-button / page-label / next-button
- * columns). Shared by /ls, /ws, /resume, /active, /order.
+ * 解析分页卡「跳转页码」输入框的提交值。
  *
- * Returns the `column_set` element (plus caller appends an `hr`). Each caller
- * supplies its own callback cmd + extra value fields and label text (semantic
- * differences are preserved, not silently unified).
+ * 三态返回：
+ * - `undefined` — 未输入（空串/非字符串），调用方应回退到 `offset`（上一页/下一页）
+ * - `null`      — 输入非法（非正整数），调用方应回错误 toast 且不刷新卡片
+ * - `number`    — 页码换算出的 offset（页码从 1 开始）
+ */
+export function parseJumpOffset(inputValue, pageSize) {
+    if (typeof inputValue !== 'string' || inputValue.trim() === '')
+        return undefined;
+    const raw = inputValue.trim();
+    if (!/^[0-9]+$/.test(raw))
+        return null;
+    const page = Number(raw);
+    if (!Number.isFinite(page) || page < 1)
+        return null;
+    const size = Number.isFinite(pageSize) && pageSize > 0 ? Math.trunc(pageSize) : 1;
+    return (page - 1) * size;
+}
+/**
+ * Build the CardKit 2.0 pagination block shared by /ls, /ws, /resume, /active,
+ * /order.
+ *
+ * 第一性原理（2026-09-10 窄屏重设计）：分页栏要同时承载「页码信息」和「翻页
+ * 控件」两类需求。旧布局把两者塞进同一行 `column_set`（文案 weighted 4 : 输入
+ * weighted 2），手机窄屏下 auto 按钮先占走固有宽度，剩余宽度按 4:2 切分后文案
+ * 列只有百来像素、输入框只有几十像素——文案折行、输入框窄到没法点。
+ * 拆成两行后每一类都有足够的横向空间：
+ *
+ *   1. 页码文案独占整行（顶层 `div`），窄屏不折行；
+ *   2. 控件行 `column_set` = [上一页 auto] [跳转页码 input weighted] [下一页 auto]，
+ *      input 吃掉 auto 按钮之外的剩余宽度（窄屏约百来像素，桌面端更宽）。
+ *
+ * Returns an array of body elements: `[page-label div, controls column_set]`；
+ * 调用方展开进 `body.elements`（+ 自己的 `hr`）。input 仍留在控件 column_set
+ * 内部，不用 form 容器（form 触发 300123 / 200621 整卡不可用）。CardKit 2.0
+ * input 自带 ✓ 提交图标，提交值经 raw `action.input_value` 回传，见 connector
+ * includeRawEvent + router/card-action-payload.ts。
+ *
+ * 每个调用方自带 callback cmd / extra value / 文案（语义差异保留，不强行统一）。
  *
  * @param opts.cmd       The pagination callback command (e.g. 'ls.page').
  * @param opts.offset    Current page offset.
@@ -84,9 +122,9 @@ export function paginationBar(opts) {
     const hasNext = opts.offset + opts.pageSize < opts.total;
     const prevText = opts.prevText ?? '⬅ 上一页';
     const nextText = opts.nextText ?? '下一页 ➡';
-    const pageColumns = [];
+    const controls = [];
     if (hasPrev) {
-        pageColumns.push({
+        controls.push({
             tag: 'column',
             width: 'auto',
             vertical_align: 'center',
@@ -106,15 +144,30 @@ export function paginationBar(opts) {
             ],
         });
     }
-    pageColumns.push({
+    // 跳转页码输入：占满 auto 按钮之外的剩余宽度（窄屏可点、桌面不局促）。
+    // 提交后值经 raw.action.input_value 回传，见 connector includeRawEvent +
+    // router/card-action-payload.ts。
+    controls.push({
         tag: 'column',
         width: 'weighted',
         weight: 1,
         vertical_align: 'center',
-        elements: [{ tag: 'div', text: { tag: 'lark_md', content: opts.label } }],
+        elements: [
+            {
+                tag: 'input',
+                name: PAGE_JUMP_INPUT_NAME,
+                placeholder: { tag: 'plain_text', content: '跳转页码' },
+                behaviors: [
+                    {
+                        type: 'callback',
+                        value: { cmd: opts.cmd, pageSize: opts.pageSize, ...opts.extra },
+                    },
+                ],
+            },
+        ],
     });
     if (hasNext) {
-        pageColumns.push({
+        controls.push({
             tag: 'column',
             width: 'auto',
             vertical_align: 'center',
@@ -134,7 +187,10 @@ export function paginationBar(opts) {
             ],
         });
     }
-    return { tag: 'column_set', columns: pageColumns };
+    return [
+        { tag: 'div', text: { tag: 'lark_md', content: opts.label } },
+        { tag: 'column_set', columns: controls },
+    ];
 }
 /**
  * Build a session-history resume card (shared by auto-restore, /resume <id>,

package/dist/router/config/common/render.d.ts

@@ -2,7 +2,7 @@
  * Shared config card rendering logic.
  *
  * Builds CardKit 2.0 elements for config fields (boolean toggle, select dropdown, input).
- * Used by all agent config builders and the shared tabs (idle, output, logging).
+ * Used by all agent config builders and the shared tabs (idle, logging).
  */
 import { type AppConfig } from '../../../config/index.js';
 import type { ConfigField } from '../types.js';

package/dist/router/config/common/render.js

@@ -2,7 +2,7 @@
  * Shared config card rendering logic.
  *
  * Builds CardKit 2.0 elements for config fields (boolean toggle, select dropdown, input).
- * Used by all agent config builders and the shared tabs (idle, output, logging).
+ * Used by all agent config builders and the shared tabs (idle, logging).
  */
 import { getConfigValue } from '../../../config/index.js';
 /** Build CardKit 2.0 elements for a list of config fields. */

package/dist/router/config-diff.d.ts

@@ -0,0 +1,4 @@
+import type { AppConfig } from '../config/index.js';
+/** 对比原始 config 与 pendingConfig，返回变化的 key→string 映射 */
+export declare function diffConfig(original: AppConfig, pending: AppConfig): Record<string, string | undefined>;
+export declare function setNestedValue(target: AppConfig, key: string, value: unknown): void;

package/dist/router/config-diff.js

@@ -0,0 +1,70 @@
+/**
+ * Config diff / nested-value helpers extracted from CommandRouter
+ * (2026-09 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';
+/** 对比原始 config 与 pendingConfig，返回变化的 key→string 映射 */
+export function diffConfig(original, pending) {
+    const updates = {};
+    collectDiff('', original, pending, updates);
+    return updates;
+}
+/** 递归收集差异 */
+function collectDiff(prefix, original, pending, result) {
+    if (original === pending)
+        return;
+    // 如果 pending 是对象（非 null）但 original 不是对象，
+    // 把 original 当作空对象递归进入 pending 内部，
+    // 避免把整个对象转成 "[object Object]" 字符串
+    if (typeof pending === 'object' &&
+        pending !== null &&
+        (typeof original !== 'object' || original === null)) {
+        const pendObj = pending;
+        for (const k of Object.keys(pendObj)) {
+            const newKey = prefix ? `${prefix}.${k}` : k;
+            collectDiff(newKey, undefined, pendObj[k], result);
+        }
+        return;
+    }
+    if (typeof original !== 'object' ||
+        typeof pending !== 'object' ||
+        original === null ||
+        pending === null) {
+        // 叶子节点，记录差异
+        const key = prefix || 'root';
+        // pending 为 undefined 表示键被删除，必须保留 undefined 语义，
+        // 不能 String(pending) 成 "undefined"
+        result[key] = pending === undefined ? undefined : String(pending);
+        return;
+    }
+    // 两者都是对象，递归比较
+    const origObj = original;
+    const pendObj = pending;
+    const allKeys = new Set([...Object.keys(origObj), ...Object.keys(pendObj)]);
+    for (const k of allKeys) {
+        const newKey = prefix ? `${prefix}.${k}` : k;
+        collectDiff(newKey, origObj[k], pendObj[k], result);
+    }
+}
+export function 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('.');
+    // 复用 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 container[lastPart];
+    }
+    else {
+        container[lastPart] = value;
+    }
+}
+//# sourceMappingURL=config-diff.js.map

package/dist/router/index.d.ts

@@ -51,6 +51,11 @@ export interface CardActionPayload {
     key?: string;
     /** /ls 与 /resume 列表分页起点（条目数）。 */
     offset?: number;
+    /**
+     * `/ls` 浏览起点（本次 `/ls <dir>` 指定的目录；省略时 = cwd）。
+     * 卡片上的「返回」按钮回到这里，而不是回到 workspace cwd。
+     */
+    root?: string;
     /** /resume 列表的 agent 类型。 */
     agent?: string;
     /** /resume 列表页大小覆盖。 */
@@ -89,6 +94,13 @@ interface CardActionResponse {
     };
     [key: string]: unknown;
 }
+/** 审批命令名清单（APPROVAL_ACTION_SPECS keys，handleCardAction 分发共用）。 */
+export declare const APPROVAL_ACTION_CMDS: readonly string[];
+/**
+ * 直返命令：点击后同步返回 toast 给飞书回调，不经队列。
+ * index.ts 控制层直返清单的唯一来源（勿在别处复制名单）。
+ */
+export declare const DIRECT_RETURN_CMDS: ReadonlySet<string>;
 export declare class CommandRouter {
     /** Valid agent kinds — single source of truth for resume.use / resume.page / cmdResume. */
     static readonly VALID_AGENTS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
@@ -235,6 +247,12 @@ export declare class CommandRouter {
      * when the callback response has no `card` field).
      */
     private handleQueueInput;
+    /**
+     * 分页卡动作的 offset 解析：优先读取「跳转页码」输入框（paginationBar 内置
+     * 的 CardKit 2.0 input），未输入则回退 `payload.offset`（上一页/下一页按钮）。
+     * 非法页码返回 `{ error }`，调用方应回错误 toast 且不刷新卡片。
+     */
+    private pagingOffset;
     /**
      * Handle ls.switch: switch cwd to target directory after path validation.
      */
@@ -289,6 +307,23 @@ export declare class CommandRouter {
         orderText: string;
         internalKey: string;
     } | null;
+    /**
+     * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     */
+    private rebuildListCard;
+    /**
+     * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
+     * 翻页/移除/排序动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
+     */
+    private refreshListCard;
+    /**
+     * W2.8 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
+     * 的公共骨架——校验 orderId → reload+find → mutate → 成功后 toast + raw 卡。
+     * mutate 返回 error 时仅回 error toast，不重渲染。
+     * 注意：本 helper 只服务「toast + card 进响应体」语义（飞书需用响应体原地
+     * 替换 pre-click 编辑卡）；updateCardInPlace 原地刷新走 refreshListCard。
+     */
+    private mutateOrderAndRefreshCard;
     /**
      * Handle order.delete: remove the order and update card in place.
      */
@@ -360,6 +395,13 @@ export declare class CommandRouter {
      * `ls.file` card button: send file to Feishu, rejecting if > 30MB.
      */
     private cardLsFile;
+    /**
+     * 校验并发送本地文件到飞书（≤30MB）。成功返回 null（文件已发出），失败返回
+     * 错误 CommandResult 由调用方展示。
+     *
+     * `/download` 与 `ls.file` 卡片按钮共用，避免两处重复 30MB/存在性校验。
+     */
+    private deliverFileToFeishu;
     /** 确保 pendingConfig 已初始化（从当前 config 克隆） */
     ensurePendingConfig(): void;
     /**
@@ -380,11 +422,7 @@ export declare class CommandRouter {
     /** 设置嵌套属性值（仅修改内存对象，不写盘） */
     /** 在 pendingConfig 上按 dot-separated key 设置嵌套值（config 卡片编辑用）。 */
     setNestedValue(target: AppConfig, key: string, value: unknown): void;
-    /** 对比原始 config 与 pendingConfig，返回变化的 key→string 映射 */
-    /** config diff（public：测试直接调用，替代 as unknown as）。 */
     diffConfig(original: AppConfig, pending: AppConfig): Record<string, string | undefined>;
-    /** 递归收集差异 */
-    private collectDiff;
     /**
      * config 写盘后的运行时传播（P1-6：自 config.save 卡片路径抽出，卡片保存与
      * `/config <key> <value>` 文本直写两条路径共用）。
@@ -458,8 +496,30 @@ export declare class CommandRouter {
      */
     private buildResumeActionButtons;
     private static readonly LS_PAGE_SIZE;
-    /** /ls 实现（public：测试直接调用，替代 as unknown as）。 */
-    cmdLs(args: string[], ctx: CommandContext, offset?: number): CommandResult;
+    /**
+     * `/ls` 实现（public：测试直接调用，替代 as unknown as）。
+     *
+     * @param args    [] 列出 cwd；[path] 列出指定目录（或文件）
+     * @param offset  分页起点（条目数）
+     * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
+     *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
+     *                丢回 workspace cwd（用户明确反馈过）。
+     */
+    cmdLs(args: string[], ctx: CommandContext, offset?: number, rootDir?: string): CommandResult;
+    /**
+     * `/download <path>`（别名 `/d`）：把本地文件直接发送到飞书。
+     *
+     * 路径解析与 `/ls` 一致：`~` 展开到 home；相对路径基于当前 cwd（无 cwd 时
+     * 必须给绝对路径）。成功时文件本身即回复，返回 null（不额外发文本）。
+     */
+    cmdDownload(args: string[], ctx: CommandContext): Promise<CommandResult | null>;
+    /**
+     * 单文件 ls 结果卡：路径 / 大小 / 修改时间 + 「下载」+「上级」。
+     *
+     * `/ls <file>` 命中普通文件时使用——用户可能想下载该文件或确认它是否存在，
+     * 此前直接回 `ls: xxx: Not a directory` 把文件路径当成错误处理。
+     */
+    private buildFileCard;
     private cmdWs;
     /**
      * L3: degraded card when a session's export is non-empty but unparseable