lark-remote 0.1.12 → 0.1.13

package/dist/router/index.js

@@ -24,6 +24,29 @@ const AUTO_RESUME_MAX_EVENTS = 5;
 /** /resume 列表页大小；`/resume [N]` 的 N clamp 到 [1, RESUME_PAGE_SIZE]。 */
 const RESUME_PAGE_SIZE = 5;
 /** /active 卡片每页显示的最大条目数（agent run + bash run 合计）。 */
+/**
+ * 分页算术（原先 5 处内联且 clamp 语义漂移：/ls 不 clamp、/active clamp 到
+ * totalCount-1 会把过期 offset 泄漏成残页）。统一 clamp 到最后一页边界。
+ */
+function pageInfo(totalCount, offset, pageSize) {
+    const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
+    const maxOffset = Math.max(0, (totalPages - 1) * pageSize);
+    const safeOffset = clampInt(offset, 0, maxOffset);
+    const currentPage = Math.floor(safeOffset / pageSize) + 1;
+    return { totalPages, safeOffset, currentPage };
+}
+/** 在 pageInfo 之上切出当前页条目。 */
+function pageSlice(items, offset, pageSize) {
+    const { totalPages, safeOffset, currentPage } = pageInfo(items.length, offset, pageSize);
+    return {
+        totalCount: items.length,
+        totalPages,
+        safeOffset,
+        currentPage,
+        pageItems: items.slice(safeOffset, safeOffset + pageSize),
+        hasPagination: items.length > pageSize,
+    };
+}
 const ACTIVE_PAGE_SIZE = 20;
 /**
  * /order 列表页大小；指令超过此数量时显示分页导航栏。
@@ -132,6 +155,109 @@ export function isImmediateAction(cmd) {
         cmd === 'approval.answerNote' ||
         cmd === 'approval.planFeedback');
 }
+const QUESTION_INDEX_PRESENT = (v) => v.questionIndex !== undefined;
+const APPROVAL_ACTION_SPECS = {
+    'approval.respond': {
+        missing: (v) => !v.runId || v.requestId === undefined || !v.decision || !v.nonce,
+        missingToast: '缺少审批响应参数',
+        run: (bridge, v) => bridge.handleApprovalRespond({
+            runId: v.runId,
+            requestId: v.requestId,
+            decision: v.decision,
+            nonce: v.nonce,
+        }),
+        successToast: '审批已提交',
+        failureToast: (msg) => {
+            // 审批已过期：给用户明确反馈，不静默不误导（2026-08-12 事故：点了允许无任何反馈）。
+            const content = /state=expired/.test(msg)
+                ? '⏰ 审批已过期，无法响应'
+                : `审批响应失败：${msg}`;
+            return { toast: { type: 'error', content } };
+        },
+    },
+    'approval.toggle': {
+        missing: (v) => !v.runId || v.requestId === undefined || !v.permId,
+        missingToast: '缺少权限切换参数',
+        run: (bridge, v) => bridge.handleApprovalToggle({
+            runId: v.runId,
+            requestId: v.requestId,
+            permId: v.permId,
+            selected: v.selected ?? true,
+        }),
+        successToast: '已切换',
+        toastType: 'info',
+        failureToast: (msg) => ({ toast: { type: 'error', content: `权限切换失败：${msg}` } }),
+    },
+    'approval.answer': {
+        missing: (v) => !v.runId || v.requestId === undefined || !QUESTION_INDEX_PRESENT(v) || !v.option || !v.nonce,
+        missingToast: '缺少问题答案参数',
+        run: (bridge, v) => bridge.handleApprovalAnswer({
+            runId: v.runId,
+            requestId: v.requestId,
+            questionIndex: v.questionIndex,
+            option: v.option,
+            nonce: v.nonce,
+        }),
+        successToast: '已选择',
+    },
+    'approval.answerSubmit': {
+        missing: (v) => !v.runId || v.requestId === undefined || !QUESTION_INDEX_PRESENT(v) || !v.nonce,
+        missingToast: '缺少提交参数',
+        run: (bridge, v) => bridge.handleApprovalAnswerSubmit({
+            runId: v.runId,
+            requestId: v.requestId,
+            questionIndex: v.questionIndex,
+            nonce: v.nonce,
+        }),
+        successToast: '答案已提交',
+    },
+    'approval.answerCustom': {
+        missing: (v) => !v.runId ||
+            v.requestId === undefined ||
+            !QUESTION_INDEX_PRESENT(v) ||
+            !v.nonce ||
+            !v.inputValue,
+        missingToast: '缺少答案文本参数',
+        run: (bridge, v) => bridge.handleApprovalAnswerCustom({
+            runId: v.runId,
+            requestId: v.requestId,
+            questionIndex: v.questionIndex,
+            text: v.inputValue,
+            nonce: v.nonce,
+        }),
+        successToast: '答案已提交',
+    },
+    'approval.answerNote': {
+        missing: (v) => !v.runId ||
+            v.requestId === undefined ||
+            !QUESTION_INDEX_PRESENT(v) ||
+            !v.nonce ||
+            !v.inputValue,
+        missingToast: '缺少补充说明参数',
+        run: (bridge, v) => bridge.handleApprovalAnswerNote({
+            runId: v.runId,
+            requestId: v.requestId,
+            questionIndex: v.questionIndex,
+            text: v.inputValue,
+            nonce: v.nonce,
+        }),
+        successToast: '补充说明已保存',
+    },
+    'approval.planFeedback': {
+        missing: (v) => !v.runId || v.requestId === undefined || !v.nonce || !v.inputValue,
+        missingToast: '缺少修改意见参数',
+        run: (bridge, v) => bridge.handleApprovalPlanFeedback({
+            runId: v.runId,
+            requestId: v.requestId,
+            text: v.inputValue,
+            nonce: v.nonce,
+        }),
+        successToast: '修改意见已保存',
+        failureToast: (msg) => ({ toast: { type: 'error', content: `修改意见保存失败：${msg}` } }),
+    },
+};
+/** 卡片 cardAction payload 缺字段的统一报错文案（原先 12 处手写且已漂移出两种前缀）。 */
+const CARD_PAYLOAD_MISSING = '⚠️ 卡片 payload 缺少必要信息';
 export class CommandRouter {
     /** Valid agent kinds — single source of truth for resume.use / resume.page / cmdResume. */
     static VALID_AGENTS = ['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh'];
@@ -427,6 +553,14 @@ export class CommandRouter {
      * Routes to the appropriate bridge method based on value.cmd.
      * Returns a toast response for immediate user feedback.
      */
+    /** queue.* 卡片动作通用守卫：workspace/messageId 缺失时回复错误并返回 null。 */
+    async queuePayloadOrReply(value, ctx) {
+        if (!value.workspace || !value.messageId) {
+            await this.bridge.sendResult({ text: CARD_PAYLOAD_MISSING }, ctx);
+            return null;
+        }
+        return { workspace: value.workspace, messageId: value.messageId };
+    }
     /** 答案类操作的统一失败反馈：重复投递（同一 nonce 第二次点击）是已生效的
      *  中性事件，报 error 会误导（首次点击实际已成功）。 */
     answerFailureToast(msg) {
@@ -436,164 +570,30 @@ export class CommandRouter {
         return { toast: { type: 'error', content: `答案提交失败：${msg}` } };
     }
     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 } };
-            }
+        const spec = APPROVAL_ACTION_SPECS[value.cmd];
+        if (!spec) {
+            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 this.answerFailureToast(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 this.answerFailureToast(msg);
-            }
+        if (spec.missing(value)) {
+            return { toast: { type: 'error', content: spec.missingToast } };
         }
-        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 this.answerFailureToast(msg);
-            }
-        }
-        if (value.cmd === 'approval.answerNote') {
-            if (!runId ||
-                requestId === undefined ||
-                value.questionIndex === undefined ||
-                !nonce ||
-                !value.inputValue) {
-                return { toast: { type: 'error', content: '缺少补充说明参数' } };
-            }
-            try {
-                await this.bridge.handleApprovalAnswerNote({
-                    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 this.answerFailureToast(msg);
-            }
+        try {
+            await spec.run(this.bridge, value);
+            return { toast: { type: spec.toastType ?? 'success', content: spec.successToast } };
         }
-        if (value.cmd === 'approval.planFeedback') {
-            if (!runId || requestId === undefined || !nonce || !value.inputValue) {
-                return { toast: { type: 'error', content: '缺少修改意见参数' } };
-            }
-            try {
-                await this.bridge.handleApprovalPlanFeedback({
-                    runId,
-                    requestId,
-                    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}` } };
-            }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return spec.failureToast ? spec.failureToast(msg) : this.answerFailureToast(msg);
         }
-        return { toast: { type: 'error', content: '未知的审批操作' } };
     }
     /**
      * Handle queue.cancel: remove this message from the queue.
      */
     async handleQueueCancel(value, ctx) {
-        const workspace = value.workspace;
-        const messageId = value.messageId;
-        if (!workspace || !messageId) {
-            await this.bridge.sendResult({ text: '⚠️ 卡片 payload 缺少必要信息' }, ctx);
+        const payload = await this.queuePayloadOrReply(value, ctx);
+        if (!payload)
             return;
-        }
+        const { workspace, messageId } = payload;
         const removed = this.bridge.removeFromQueue(workspace, messageId);
         if (removed) {
             // Update the queue card in-place to "cancelled" state
@@ -610,12 +610,10 @@ export class CommandRouter {
      * Instead of asking user to resend, we keep the target task in queue and let it execute.
      */
     async handleQueueImmediate(value, ctx) {
-        const workspace = value.workspace;
-        const messageId = value.messageId;
-        if (!workspace || !messageId) {
-            await this.bridge.sendResult({ text: '卡片 payload 缺少必要信息' }, ctx);
+        const payload = await this.queuePayloadOrReply(value, ctx);
+        if (!payload)
             return;
-        }
+        const { workspace, messageId } = payload;
         // 1. Check target exists BEFORE any await. The queue chain can advance
         // while later awaits (interruptCurrentRun / markQueueCardExecuting's card
         // send) are in flight, so the target must be read synchronously at entry.
@@ -751,13 +749,11 @@ export class CommandRouter {
      * Handle queue.diagnose: show diagnostic info for why message is queuing.
      */
     async handleQueueDiagnose(value, ctx) {
-        const workspace = value.workspace;
-        const messageId = value.messageId;
-        const targetUserId = value.userId ?? ctx.userId;
-        if (!workspace || !messageId) {
-            await this.bridge.sendResult({ text: '卡片 payload 缺少必要信息' }, ctx);
+        const payload = await this.queuePayloadOrReply(value, ctx);
+        if (!payload)
             return;
-        }
+        const { workspace, messageId } = payload;
+        const targetUserId = value.userId ?? ctx.userId;
         const task = this.bridge.getQueuedTask(workspace, messageId);
         const queueInfo = this.bridge.getQueueInfo(workspace);
         const activeRuns = this.bridge.getAllActiveRuns();
@@ -825,12 +821,10 @@ export class CommandRouter {
      * Handle queue.edit: show input field for editing the queued message.
      */
     async handleQueueEdit(value, ctx) {
-        const workspace = value.workspace;
-        const messageId = value.messageId;
-        if (!workspace || !messageId) {
-            await this.bridge.sendResult({ text: '⚠️ 卡片 payload 缺少必要信息' }, ctx);
+        const payload = await this.queuePayloadOrReply(value, ctx);
+        if (!payload)
             return;
-        }
+        const { workspace, messageId } = payload;
         // Get current message preview
         const task = this.bridge.getQueuedTask(workspace, messageId);
         if (!task) {
@@ -896,13 +890,11 @@ export class CommandRouter {
      * when the callback response has no `card` field).
      */
     async handleQueueInput(value, ctx) {
-        const workspace = value.workspace;
-        const messageId = value.messageId;
         const newMessage = value.inputValue ?? value.formValue?.['newMessage'];
-        if (!workspace || !messageId) {
-            await this.bridge.sendResult({ text: '⚠️ 卡片 payload 缺少必要信息' }, ctx);
+        const payload = await this.queuePayloadOrReply(value, ctx);
+        if (!payload)
             return;
-        }
+        const { workspace, messageId } = payload;
         if (!newMessage) {
             await this.bridge.sendResult({ text: '⚠️ 缺少新消息内容' }, ctx);
             return;
@@ -1173,7 +1165,7 @@ export class CommandRouter {
     async handleOrderDelete(value, ctx) {
         const orderId = value.orderId;
         if (!orderId) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
+            return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
         if (!this.orderStore.has(orderId)) {
             return { toast: { type: 'error', content: '指令不存在或已被删除' } };
@@ -1201,17 +1193,22 @@ export class CommandRouter {
      * Handle order.aliasEdit: 展示别名编辑卡（input + ✓ 提交图标）。
      * 有别名时预填；提交 `order.aliasInput` 处理（含校验与唯一性）。
      */
-    async handleOrderAliasEdit(value, ctx) {
+    /**
+     * order 编辑卡公共骨架：payload 校验 → 查指令 → 构造 input 编辑卡 → 原地更新。
+     * handleOrderAliasEdit / handleOrderTextEdit 原先各持一份 ~90% 相同的 4 段结构。
+     */
+    async showOrderEditCard(value, ctx, opts) {
         const orderId = value.orderId;
         const offset = Math.max(0, Math.trunc(Number(value.offset) || 0));
         if (!orderId) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
+            return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
         this.orderStore.reload();
         const order = this.orderStore.get().find((o) => o.id === orderId);
         if (!order) {
             return { toast: { type: 'error', content: '指令不存在或已被删除' } };
         }
+        // 列表卡显示的是截断版（≤100 字符 + ...），编辑卡预览保持一致
         const displayText = order.text.length > 100 ? order.text.slice(0, 97) + '...' : order.text;
         // CardKit 2.0 input 自带 ✓ 提交图标（input_value 经 raw 回传，红线）。
         // 不用 form 容器（触发 300123 无 submit button / 200621 嵌套 column）。
@@ -1220,7 +1217,7 @@ export class CommandRouter {
             config: { wide_screen_mode: true },
             header: {
                 template: 'blue',
-                title: { tag: 'plain_text', content: '✏️ 给指令起别名' },
+                title: { tag: 'plain_text', content: opts.title },
             },
             body: {
                 elements: [
@@ -1231,10 +1228,7 @@ export class CommandRouter {
                     { tag: 'hr' },
                     {
                         tag: 'div',
-                        text: {
-                            tag: 'lark_md',
-                            content: '💡 输入别名名后点击右侧 ✓ 提交；留空提交 = 删除该别名',
-                        },
+                        text: { tag: 'lark_md', content: opts.hint },
                     },
                     {
                         tag: 'column_set',
@@ -1246,13 +1240,14 @@ export class CommandRouter {
                                 elements: [
                                     {
                                         tag: 'input',
-                                        name: 'aliasName',
-                                        placeholder: { tag: 'plain_text', content: '输入 $别名名（如 all）...' },
-                                        default_value: order.alias ?? '',
+                                        name: opts.inputName,
+                                        placeholder: { tag: 'plain_text', content: opts.placeholder },
+                                        default_value: opts.defaultValue,
+                                        ...(opts.maxLength !== undefined ? { max_length: opts.maxLength } : {}),
                                         behaviors: [
                                             {
                                                 type: 'callback',
-                                                value: { cmd: 'order.aliasInput', orderId, offset },
+                                                value: { cmd: opts.inputCmd, orderId, offset },
                                             },
                                         ],
                                     },
@@ -1265,6 +1260,18 @@ export class CommandRouter {
         };
         await this.bridge.updateCardInPlace(editCard, ctx);
     }
+    async handleOrderAliasEdit(value, ctx) {
+        this.orderStore.reload();
+        const order = this.orderStore.get().find((o) => o.id === value.orderId);
+        return this.showOrderEditCard(value, ctx, {
+            title: '✏️ 给指令起别名',
+            hint: '💡 输入别名名后点击右侧 ✓ 提交；留空提交 = 删除该别名',
+            inputName: 'aliasName',
+            placeholder: '输入 $别名名（如 all）...',
+            defaultValue: order?.alias ?? '',
+            inputCmd: 'order.aliasInput',
+        });
+    }
     /**
      * Handle order.aliasInput: 提交别名（绑/改/解绑），随后重渲染 /order 列表卡。
      * 留空 = 解绑；非空按命名规则 + 全局唯一校验，失败仅 toast 不重渲染。
@@ -1274,7 +1281,7 @@ export class CommandRouter {
         const offset = Math.max(0, Math.trunc(Number(value.offset) || 0));
         const name = value.inputValue ?? value.formValue?.['aliasName'];
         if (!orderId) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
+            return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
         this.orderStore.reload();
         const order = this.orderStore.get().find((o) => o.id === orderId);
@@ -1308,7 +1315,7 @@ export class CommandRouter {
         const orderId = value.orderId;
         const offset = Math.max(0, Math.trunc(Number(value.offset) || 0));
         if (!orderId) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
+            return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
         this.orderStore.reload();
         const order = this.orderStore.get().find((o) => o.id === orderId);
@@ -1335,73 +1342,20 @@ export class CommandRouter {
      * updateCardInPlace）。
      */
     async handleOrderTextEdit(value, ctx) {
-        const orderId = value.orderId;
-        const offset = Math.max(0, Math.trunc(Number(value.offset) || 0));
-        if (!orderId) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
-        }
         this.orderStore.reload();
-        const order = this.orderStore.get().find((o) => o.id === orderId);
-        if (!order) {
-            return { toast: { type: 'error', content: '指令不存在或已被删除' } };
-        }
-        // 列表卡显示的是截断版（≤100 字符 + ...），编辑卡预览也保持一致；
-        // input 组件 default_value 预填完整 text（不受截断影响），用户提交后生效完整文本。
-        const displayText = order.text.length > 100 ? order.text.slice(0, 97) + '...' : order.text;
-        // CardKit 2.0 input 自带 ✓ 提交图标（input_value 经 raw 回传，红线）。
-        // 不用 form 容器（触发 300123 无 submit button / 200621 嵌套 column）。
-        const editCard = {
-            schema: '2.0',
-            config: { wide_screen_mode: true },
-            header: {
-                template: 'blue',
-                title: { tag: 'plain_text', content: '✏️ 编辑指令' },
-            },
-            body: {
-                elements: [
-                    {
-                        tag: 'div',
-                        text: { tag: 'lark_md', content: `**当前指令:**\n\`${displayText}\`` },
-                    },
-                    { tag: 'hr' },
-                    {
-                        tag: 'div',
-                        text: {
-                            tag: 'lark_md',
-                            content: '💡 修改后点击右侧 ✓ 提交；空白提交 = 报错；最多 200 字符',
-                        },
-                    },
-                    {
-                        tag: 'column_set',
-                        columns: [
-                            {
-                                tag: 'column',
-                                width: 'weighted',
-                                weight: 3,
-                                elements: [
-                                    {
-                                        tag: 'input',
-                                        name: 'text',
-                                        placeholder: { tag: 'plain_text', content: '输入新的指令文本...' },
-                                        default_value: order.text,
-                                        // max_length 与 MAX_TEXT_LENGTH=200 对齐：超长在输入侧直接截断，
-                                        // 避免提交后才报错（后端 updateText 仍会二次校验，双保险）。
-                                        max_length: 200,
-                                        behaviors: [
-                                            {
-                                                type: 'callback',
-                                                value: { cmd: 'order.textInput', orderId, offset },
-                                            },
-                                        ],
-                                    },
-                                ],
-                            },
-                        ],
-                    },
-                ],
-            },
-        };
-        await this.bridge.updateCardInPlace(editCard, ctx);
+        const order = this.orderStore.get().find((o) => o.id === value.orderId);
+        // input 组件 default_value 预填完整 text（不受截断影响），提交后生效完整文本
+        return this.showOrderEditCard(value, ctx, {
+            title: '✏️ 编辑指令',
+            hint: '💡 修改后点击右侧 ✓ 提交；空白提交 = 报错；最多 200 字符',
+            inputName: 'text',
+            placeholder: '输入新的指令文本...',
+            defaultValue: order?.text ?? '',
+            inputCmd: 'order.textInput',
+            // 与 MAX_TEXT_LENGTH=200 对齐：超长在输入侧直接截断，避免提交后才报错
+            // （后端 updateText 仍会二次校验，双保险）
+            maxLength: 200,
+        });
     }
     /**
      * Handle order.textInput: 提交指令文本编辑。校验 orderId → OrderStore.updateText
@@ -1415,7 +1369,7 @@ export class CommandRouter {
         const offset = Math.max(0, Math.trunc(Number(value.offset) || 0));
         const raw = value.inputValue ?? value.formValue?.['text'];
         if (!orderId) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
+            return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
         this.orderStore.reload();
         const order = this.orderStore.get().find((o) => o.id === orderId);
@@ -1494,7 +1448,7 @@ export class CommandRouter {
     async handleWsRemove(value, ctx) {
         const name = value.name;
         if (!name) {
-            return { toast: { type: 'error', content: '卡片 payload 缺少必要信息' } };
+            return { toast: { type: 'error', content: CARD_PAYLOAD_MISSING } };
         }
         // Execute the removal (consumes the write-side effect; the returned text
         // is discarded — feedback flows through the toast + refreshed card).
@@ -2557,12 +2511,8 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     size: fs.statSync(path.join(targetDir, f.name)).size,
                 })),
             ];
-            // Pagination calculations
-            const totalCount = allItems.length;
-            const totalPages = Math.max(1, Math.ceil(totalCount / CommandRouter.LS_PAGE_SIZE));
-            const currentPage = Math.floor(offset / CommandRouter.LS_PAGE_SIZE) + 1;
-            const pageItems = allItems.slice(offset, offset + CommandRouter.LS_PAGE_SIZE);
-            const hasPagination = totalCount > CommandRouter.LS_PAGE_SIZE;
+            // Pagination calculations（clamp 到最后一页边界，原先不 clamp 会显示空页）
+            const { totalCount, totalPages, safeOffset, currentPage, pageItems, hasPagination } = pageSlice(allItems, offset, CommandRouter.LS_PAGE_SIZE);
             // Check if we need to show parent directory button
             const parentDir = path.dirname(targetDir);
             const hasParent = parentDir !== targetDir;
@@ -2593,7 +2543,9 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 text: { tag: 'plain_text', content: '刷新' },
                 type: 'default',
                 size: 'small',
-                behaviors: [{ type: 'callback', value: { cmd: 'ls.refresh', path: targetDir, offset } }],
+                behaviors: [
+                    { type: 'callback', value: { cmd: 'ls.refresh', path: targetDir, offset: safeOffset } },
+                ],
             });
             // Show "切换" button when viewing a subdirectory (to switch cwd to this directory)
             if (isSubdir) {
@@ -2701,7 +2653,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             if (hasPagination) {
                 const bar = paginationBar({
                     cmd: 'ls.page',
-                    offset,
+                    offset: safeOffset,
                     pageSize: CommandRouter.LS_PAGE_SIZE,
                     total: totalCount,
                     extra: { path: targetDir },
@@ -2795,13 +2747,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 }
                 // Pagination calculations (mirror cmdOrder): clamp stale/out-of-range
                 // offsets so prev/next always step by WS_PAGE_SIZE.
-                const totalCount = entries.length;
-                const totalPages = Math.max(1, Math.ceil(totalCount / WS_PAGE_SIZE));
-                const maxOffset = Math.max(0, (totalPages - 1) * WS_PAGE_SIZE);
-                const safeOffset = 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;
+                const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(entries, offset, WS_PAGE_SIZE);
                 // Build body elements: current cwd + workspace list with dividers
                 const bodyElements = [];
                 // Current working directory section
@@ -3214,8 +3160,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
         // Pagination bar (only shown when there are more sessions than pageSize)
         if (total > pageSize) {
-            const totalPages = Math.ceil(total / pageSize);
-            const currentPage = Math.floor(pageOffset / pageSize) + 1;
+            const { totalPages, currentPage } = pageInfo(total, pageOffset, pageSize);
             const bar = paginationBar({
                 cmd: 'resume.page',
                 offset: pageOffset,
@@ -3259,9 +3204,9 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     buildActiveCardFromMemory(activeRuns, activeBashRuns, offset = 0) {
         const totalCount = activeRuns.length + activeBashRuns.length;
         const pageSize = ACTIVE_PAGE_SIZE;
-        const safeOffset = Math.max(0, Math.min(offset, Math.max(0, totalCount - 1)));
-        const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
-        const currentPage = Math.floor(safeOffset / pageSize) + 1;
+        // 统一 clamp 到最后一页边界（原先 clamp 到 totalCount-1，过期 offset 会
+        // 泄漏成「第 1 页只显示末尾几条」的残页）
+        const { totalPages, safeOffset, currentPage } = pageInfo(totalCount, offset, pageSize);
         // Slice: distribute offset across agent runs first, then bash runs
         const elements = [];
         // Page info
@@ -3576,14 +3521,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             }
             else {
                 // Pagination calculations
-                const totalCount = allOrders.length;
-                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 = 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;
+                const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageOrders, hasPagination, } = pageSlice(allOrders, offset, ORDER_PAGE_SIZE);
                 for (let i = 0; i < pageOrders.length; i++) {
                     const order = pageOrders[i];
                     const displayText = order.text.length > 100 ? order.text.slice(0, 97) + '...' : order.text;