@keyou007/agent-bot 0.1.13-alpha.0 → 0.1.13-alpha.2

package/dist/proxy/ProxySessionController.js

@@ -6,6 +6,7 @@ import { CommandRouter } from "../commands/CommandRouter.js";
 import { baseChatContextKey, isThreadContextKey } from "../feishu/contextKey.js";
 import { CardRenderer, } from "../feishu/CardRenderer.js";
 import { generateGroupAvatarPng, resolveGroupAvatarProjectName } from "../feishu/GroupAvatarGenerator.js";
+import { buildTurnGraphRows } from "../presentation/turnGraph.js";
 import { createId } from "../utils/id.js";
 import { asInlineCode, codeBlock, truncateMiddle, truncateText } from "../utils/markdown.js";
 import { normalizeTaskTitle } from "../utils/taskTitle.js";
@@ -15,7 +16,111 @@ const MESSAGE_COMPLETED_REACTION = "DONE";
 const MESSAGE_FAILED_REACTION = "ERROR";
 const MESSAGE_CANCELLED_REACTION = "CrossMark";
 const SESSION_PAGE_SIZE = 5;
+const RESET_HISTORY_PAGE_SIZE = 10;
 const REMOTE_SESSION_REFERENCE_PREFIX = "agent-runtime:";
+const HELP_COMMAND_SECTIONS = [
+    {
+        title: "任务管理",
+        commands: [
+            {
+                command: "/new",
+                usage: "[title] [--dir <cwd> | --nodir]",
+                description: "使用默认 Agent 创建任务；--nodir 创建 Projectless 任务",
+            },
+            {
+                command: "/newgroup",
+                usage: "[title] [--dir <cwd> | --nodir]",
+                description: "创建飞书群和新任务",
+            },
+            {
+                command: "/forkgroup",
+                usage: "[title]",
+                description: "从当前任务最近完成轮次创建分支群",
+            },
+            {
+                command: "/fork",
+                usage: "[序号或任务 ID]",
+                description: "从当前或指定任务最近完成轮次创建分支",
+            },
+            { command: "/turns", description: "浏览历史轮次，并可 Reset 对话上下文" },
+            {
+                command: "/title",
+                usage: "<新标题>",
+                description: "修改当前任务标题",
+                requiresArgument: true,
+            },
+            { command: "/sessions", usage: "[关键词]", description: "查找本机任务" },
+            {
+                command: "/switch",
+                usage: "[序号或任务 ID]",
+                description: "切换任务；不填参数切回上一个任务",
+            },
+        ],
+    },
+    {
+        title: "执行设置",
+        commands: [
+            {
+                command: "!",
+                usage: "<命令>",
+                description: "在当前任务目录执行本地命令",
+                requiresArgument: true,
+            },
+            { command: "/stop", description: "停止当前执行" },
+            {
+                command: "/queue",
+                usage: "<prompt>",
+                description: "将 Prompt 排队为后续轮次",
+                requiresArgument: true,
+            },
+            {
+                command: "/nosteer",
+                usage: "<prompt>",
+                description: "与 /queue 相同",
+                requiresArgument: true,
+            },
+            {
+                command: "/goal",
+                usage: "<目标或操作>",
+                description: "查看或创建长任务 Goal；支持 pause、resume、edit、clear",
+                requiresArgument: true,
+            },
+            { command: "/provider", description: "选择 AI 服务提供商" },
+            { command: "/model", description: "选择当前任务使用的模型" },
+            { command: "/thinking", description: "设置模型的思考强度" },
+            { command: "/permissions", description: "设置执行工具前是否需要确认" },
+        ],
+    },
+    {
+        title: "Agent",
+        commands: [
+            {
+                command: "/agent",
+                usage: "[name]",
+                description: "选择新任务使用的默认 Agent",
+            },
+        ],
+    },
+    {
+        title: "系统",
+        commands: [
+            {
+                command: "/status",
+                usage: "[序号或任务 ID]",
+                description: "查看当前或指定任务状态",
+            },
+            {
+                command: "/restart",
+                usage: "[--force]",
+                description: "默认安全重启；--force 立即重启",
+            },
+            { command: "/help", description: "显示本帮助" },
+        ],
+    },
+];
+const HELP_DEFAULT_COMMANDS = new Set(HELP_COMMAND_SECTIONS.flatMap((section) => section.commands)
+    .filter((command) => !command.requiresArgument)
+    .map((command) => command.command));
 export class ProxySessionController {
     config;
     store;
@@ -31,6 +136,7 @@ export class ProxySessionController {
     queuedPromptStarts = new Map();
     queuedPromptCards = new Map();
     queuedPromptCardWrites = new Map();
+    sessionResets = new Map();
     lastSessionListings = new Map();
     threadInitializations = new Map();
     unsubscribe = [];
@@ -75,8 +181,18 @@ export class ProxySessionController {
         catch (error) {
             this.logger.warn({ error, messageId: message.messageId, contextKey: message.contextKey }, "Failed to acknowledge the incoming Feishu message with a reaction.");
         }
+        if (message.chatType === "p2p" && message.userId?.startsWith("ou_")) {
+            try {
+                await this.lifecycle?.rememberFeishuUserOpenId?.(message.userId);
+            }
+            catch (error) {
+                this.logger.warn({ error, messageId: message.messageId }, "Failed to persist the first private-chat Lark user Open ID.");
+            }
+        }
         if (message.chatId && message.chatType) {
-            this.store.recordChatContext(baseChatContextKey(message.contextKey), message.chatType);
+            const chatContextKey = baseChatContextKey(message.contextKey);
+            this.store.recordChatContext(chatContextKey, message.chatType);
+            this.store.markChatActive(chatContextKey);
         }
         const replyTarget = message.replyInThread
             ? { messageId: message.messageId, replyInThread: true }
@@ -87,9 +203,6 @@ export class ProxySessionController {
             text: message.text,
             ...(imageCount > 0 ? { imageCount } : {}),
         });
-        if (imageCount > 0 && message.chatId && message.chatType) {
-            this.store.markChatActive(baseChatContextKey(message.contextKey));
-        }
         let localImagePaths;
         if (imageCount > 0) {
             try {
@@ -112,12 +225,6 @@ export class ProxySessionController {
             await this.outbound.withReplyTarget(message.contextKey, replyTarget, () => this.sendError(message.contextKey, error));
             return;
         }
-        if (message.chatId
-            && message.chatType
-            && (command.type === "shell"
-                || (command.type === "prompt" && !message.text.trimStart().startsWith("/")))) {
-            this.store.markChatActive(baseChatContextKey(message.contextKey));
-        }
         // Operational and read-only commands must remain available even if a prompt operation is slow.
         if (isQueueIndependentCommand(command)) {
             await this.outbound.withReplyTarget(message.contextKey, replyTarget, async () => {
@@ -165,7 +272,10 @@ export class ProxySessionController {
         await this.outbound.withReplyTarget(contextKey, replyTarget, async () => {
             try {
                 const kind = String(scopedAction.value.action ?? "");
-                if (kind === "turn_details") {
+                if (kind === "help_command") {
+                    await this.executeHelpCommandAction(scopedAction, contextKey, replyTarget);
+                }
+                else if (kind === "turn_details") {
                     await this.outbound.showDetails(contextKey, String(scopedAction.value.turnId ?? ""));
                 }
                 else if (kind === "activity_history") {
@@ -177,6 +287,24 @@ export class ProxySessionController {
                     const sessionId = String(scopedAction.value.sessionId ?? "");
                     await this.cancelSession(this.requireSession(contextKey, sessionId));
                 }
+                else if (kind === "turn_reset") {
+                    const sessionId = String(scopedAction.value.sessionId ?? "");
+                    await this.resetCurrentSessionToTurn(contextKey, sessionId, String(scopedAction.value.turnId ?? ""));
+                    if (scopedAction.value.cardView === "reset_history") {
+                        await this.openResetHistory(contextKey, {
+                            expectedSessionId: sessionId,
+                            updateMessageId: requiredCardMessageId(scopedAction.messageId),
+                            page: resetHistoryPageValue(scopedAction.value.page),
+                        });
+                    }
+                }
+                else if (kind === "turn_reset_page") {
+                    await this.openResetHistory(contextKey, {
+                        expectedSessionId: String(scopedAction.value.sessionId ?? ""),
+                        updateMessageId: requiredCardMessageId(scopedAction.messageId),
+                        page: resetHistoryPageValue(scopedAction.value.page),
+                    });
+                }
                 else if (kind === "queued_prompt_cancel") {
                     await this.cancelQueuedPrompt(scopedAction);
                 }
@@ -193,8 +321,8 @@ export class ProxySessionController {
                         await this.outbound.sendText(contextKey, "该安全重启计划已失效，请查看最新状态卡片。");
                     }
                 }
-                else if (kind === "session_more") {
-                    await this.refreshSessionsCardFromAction(scopedAction, undefined, true);
+                else if (kind === "session_page") {
+                    await this.refreshSessionsCardFromAction(scopedAction);
                 }
                 else if (kind === "session_switch") {
                     const sessionId = String(scopedAction.value.sessionId ?? "");
@@ -202,12 +330,12 @@ export class ProxySessionController {
                     if (scopedAction.value.cardView === "status")
                         await this.refreshStatusCardFromAction(scopedAction);
                     else
-                        await this.refreshSessionsCardFromAction(scopedAction);
+                        await this.refreshSessionsCardFromAction(scopedAction, { page: 0 });
                 }
                 else if (kind === "session_fork") {
                     const sessionId = String(scopedAction.value.sessionId ?? "");
                     await this.forkSessionReference(contextKey, sessionId);
-                    await this.refreshSessionsCardFromAction(scopedAction);
+                    await this.refreshSessionsCardFromAction(scopedAction, { page: 0 });
                 }
                 else if (kind === "session_fork_group") {
                     const sessionId = String(scopedAction.value.sessionId ?? "");
@@ -217,7 +345,7 @@ export class ProxySessionController {
                 else if (kind === "session_new") {
                     const sessionId = String(scopedAction.value.sessionId ?? "");
                     await this.createProjectSessionFromReference(contextKey, sessionId);
-                    await this.refreshSessionsCardFromAction(scopedAction);
+                    await this.refreshSessionsCardFromAction(scopedAction, { page: 0 });
                 }
                 else if (kind === "session_new_group") {
                     const sessionId = String(scopedAction.value.sessionId ?? "");
@@ -230,7 +358,7 @@ export class ProxySessionController {
                     if (scopedAction.value.cardView === "status")
                         await this.refreshStatusCardFromAction(scopedAction, sessionId);
                     else
-                        await this.refreshSessionsCardFromAction(scopedAction, sessionId);
+                        await this.refreshSessionsCardFromAction(scopedAction, { forceSwitchTaskId: sessionId });
                 }
                 else if (kind === "session_status") {
                     await this.status(contextKey, String(scopedAction.value.sessionId ?? ""));
@@ -355,6 +483,7 @@ export class ProxySessionController {
         this.lastSessionListings.clear();
         this.queuedPromptCards.clear();
         this.queuedPromptCardWrites.clear();
+        this.sessionResets.clear();
     }
     async controlStopTask(localSessionId) {
         const record = this.store.getSession(localSessionId);
@@ -588,7 +717,10 @@ export class ProxySessionController {
             case "restart":
                 if (!this.lifecycle)
                     throw new Error("当前运行方式不支持自动重启。");
-                await this.lifecycle.restart(contextKey, command.force === true);
+                await this.lifecycle.restart(contextKey, command.force === true, replyTarget);
+                return;
+            case "turns":
+                await this.openResetHistory(contextKey);
                 return;
             case "model":
                 await this.openExecutionSettings(contextKey, "model");
@@ -1532,6 +1664,15 @@ export class ProxySessionController {
         });
     }
     async handleRuntimeEvent(event) {
+        if ("turnId" in event) {
+            const source = this.store.getSession(event.sessionId);
+            if (source?.remoteSessionId && this.isCodexSession(source)) {
+                this.store.saveTurnRuntimeOrigin(event.turnId, source.localSessionId, source.agentName, source.remoteSessionId);
+            }
+            if (event.type === "turn_started") {
+                this.store.saveTurnParent(event.turnId, event.sessionId, this.completedParentTurnId(source));
+            }
+        }
         if (event.type === "session_metadata_updated") {
             this.store.updateRuntimeSession(event.sessionId, { title: event.title });
             this.outbound.updateSessionTitle(event.sessionId, event.title);
@@ -1623,6 +1764,14 @@ export class ProxySessionController {
             }
         }
     }
+    completedParentTurnId(source) {
+        if (!source?.lastTurnId)
+            return undefined;
+        if (source.lastTurnStatus === "completed")
+            return source.lastTurnId;
+        const snapshot = turnViewSnapshot(this.store.getTurnSnapshot(source.lastTurnId));
+        return snapshot?.status === "completed" ? source.lastTurnId : undefined;
+    }
     async finalizeStandaloneMessageReaction(messageId, status) {
         const reaction = this.store.claimMessageReaction(messageId);
         if (reaction)
@@ -1718,6 +1867,88 @@ export class ProxySessionController {
         }
         await loaded.runtime.cancelTurn(record.localSessionId, turnId);
     }
+    async resetCurrentSessionToTurn(contextKey, sessionId, turnId) {
+        if (!sessionId || !turnId)
+            throw new Error("无效的 Reset 请求。请使用最新的思考卡片重试。");
+        const previous = this.sessionResets.get(sessionId) ?? Promise.resolve();
+        const reset = previous.catch(() => undefined).then(() => this.performCurrentSessionReset(contextKey, sessionId, turnId));
+        this.sessionResets.set(sessionId, reset);
+        try {
+            await reset;
+        }
+        finally {
+            if (this.sessionResets.get(sessionId) === reset)
+                this.sessionResets.delete(sessionId);
+        }
+    }
+    async performCurrentSessionReset(contextKey, sessionId, turnId) {
+        const current = this.requireCurrentSession(contextKey);
+        if (current.localSessionId !== sessionId) {
+            throw new Error("这张思考卡片不属于当前任务。请先切换回对应任务，再点击 Reset。");
+        }
+        if (!current.remoteSessionId || !this.isCodexSession(current)) {
+            throw new Error("当前任务不是可 Reset 的 App Server 任务。");
+        }
+        const snapshot = turnViewSnapshot(this.store.getTurnSnapshot(turnId));
+        if (!snapshot || snapshot.sessionId !== sessionId || snapshot.status !== "completed") {
+            throw new Error("只能将当前任务 Reset 到已成功完成的轮次。");
+        }
+        if (current.lastTurnId === turnId && current.lastTurnStatus === "completed") {
+            await this.outbound.sendText(contextKey, "当前任务已经处于本轮完成后的对话状态，无需 Reset。");
+            return;
+        }
+        const runtime = this.runtimes.forAgent(current.agentName);
+        if (runtime.kind !== "codex" || !runtime.forkSession) {
+            throw new Error("当前 App Server Agent 不支持 Reset。");
+        }
+        const loaded = await this.loadSession(current);
+        const activity = await this.assertSessionTurnOwnership(current, runtime);
+        const active = activity?.active
+            ?? Boolean(loaded.session.activeTurnId || current.status === "running" || current.lastTurnStatus === "running");
+        if (active) {
+            throw new Error("当前任务仍在执行。请等待任务完成或先停止任务，再点击 Reset。");
+        }
+        const origin = this.store.getTurnRuntimeOrigin(turnId);
+        if (origin && (origin.localSessionId !== sessionId || origin.agentName !== current.agentName)) {
+            throw new Error("这张思考卡片与当前任务不匹配，已拒绝 Reset。");
+        }
+        const sourceRemoteSessionId = origin?.remoteSessionId ?? current.remoteSessionId;
+        const previousRemoteSessionId = current.remoteSessionId;
+        const forked = await runtime.forkSession({
+            localSessionId: current.localSessionId,
+            remoteSessionId: sourceRemoteSessionId,
+            lastTurnId: turnId,
+            agentName: current.agentName,
+            cwd: current.cwd,
+            title: current.title,
+            modelProvider: current.modelProvider,
+            model: current.model,
+            reasoningEffort: current.reasoningEffort,
+            permissionMode: current.permissionMode ?? "auto",
+        });
+        this.persistRuntimeSession(current, forked, "ready");
+        this.store.updateRuntimeSession(current.localSessionId, {
+            lastTurnId: turnId,
+            lastTurnStatus: "completed",
+        });
+        this.outbound.registerSession(current.localSessionId, contextKey, forked.title ?? current.title, current.cwd, this.agentLabel(current.agentName));
+        this.store.audit(contextKey, "session_reset_to_turn", {
+            localSessionId: current.localSessionId,
+            previousRemoteSessionId,
+            sourceRemoteSessionId,
+            resetTurnId: turnId,
+            forkedRemoteSessionId: forked.remoteSessionId,
+        });
+        const targetSummary = truncateText((snapshot.prompt ?? snapshot.taskTitle ?? "未记录对话内容").replace(/\s+/g, " ").trim(), 100) || "未记录对话内容";
+        const targetTime = snapshot.completedAt ?? snapshot.startedAt;
+        await this.outbound.sendText(contextKey, [
+            "已将当前任务重置到：",
+            targetSummary,
+            `完成时间：${targetTime === undefined ? "未知" : formatResetTurnTime(targetTime)}`,
+            `Turn ID：${turnId}`,
+            "后续对话将从该轮完成后的状态继续；本地文件没有回退。",
+        ].join("\n"));
+    }
     async resolveApproval(action) {
         const sessionId = String(action.value.sessionId ?? "");
         const requestId = String(action.value.requestId ?? "");
@@ -2185,10 +2416,92 @@ export class ProxySessionController {
         }
         await this.outbound.sendText(contextKey, mode === "auto" ? "已切换为自动执行模式。" : "已切换为执行前确认模式。");
     }
+    async openResetHistory(contextKey, options = {}) {
+        const current = this.requireCurrentSession(contextKey);
+        if (options.expectedSessionId && current.localSessionId !== options.expectedSessionId) {
+            throw new Error("这张历史轮次卡片不属于当前任务。请先切换回对应任务，再重新发送 /turns。");
+        }
+        if (!current.remoteSessionId || !this.isCodexSession(current)) {
+            throw new Error("当前任务不是可 Reset 的 App Server 任务。");
+        }
+        const allTurns = this.store.listCompletedTurnGraph(current.localSessionId, contextKey);
+        const graphRows = buildTurnGraphRows(allTurns.map((turn) => ({
+            turnId: turn.turnId,
+            parentTurnId: turn.parentTurnId,
+        })));
+        const total = allTurns.length;
+        const totalPages = Math.max(1, Math.ceil(total / RESET_HISTORY_PAGE_SIZE));
+        const page = Math.max(0, Math.min(Math.trunc(options.page ?? 0), totalPages - 1));
+        const offset = page * RESET_HISTORY_PAGE_SIZE;
+        const turns = allTurns.slice(offset, offset + RESET_HISTORY_PAGE_SIZE);
+        const entries = turns.flatMap((turn, index) => {
+            const snapshot = turnViewSnapshot(turn.snapshot);
+            if (!snapshot)
+                return [];
+            const graph = graphRows[offset + index];
+            const summary = truncateText((snapshot.prompt ?? snapshot.taskTitle ?? "未记录对话内容").replace(/\s+/g, " ").trim(), 100);
+            const isCurrent = current.lastTurnId === turn.turnId && current.lastTurnStatus === "completed";
+            return [{
+                    sequence: graph.sequence,
+                    graphNodeLine: graph.nodeLine,
+                    graphConnectorLine: graph.connectorLine,
+                    lines: [
+                        `**${cardText(summary || "未记录对话内容")}**`,
+                        `${formatResetTurnTime(snapshot.completedAt ?? snapshot.startedAt)} · ${cardCode(turn.turnId)}`,
+                    ],
+                    current: isCurrent,
+                    actions: isCurrent ? undefined : [{
+                            text: "Reset",
+                            value: {
+                                action: "turn_reset",
+                                cardView: "reset_history",
+                                sessionId: current.localSessionId,
+                                turnId: turn.turnId,
+                                contextKey,
+                                page: String(page),
+                            },
+                        }],
+                }];
+        });
+        const pageActions = [
+            ...(page > 0 ? [{
+                    text: "Previous",
+                    value: {
+                        action: "turn_reset_page",
+                        sessionId: current.localSessionId,
+                        contextKey,
+                        page: String(page - 1),
+                    },
+                }] : []),
+            ...(page < totalPages - 1 ? [{
+                    text: "Next",
+                    value: {
+                        action: "turn_reset_page",
+                        sessionId: current.localSessionId,
+                        contextKey,
+                        page: String(page + 1),
+                    },
+                }] : []),
+        ];
+        const card = this.cardRenderer.renderResetHistoryCard({
+            entries,
+            footerLines: [
+                `第 ${page + 1}/${totalPages} 页 · 共 ${total} 个已完成 turn`,
+            ],
+            pageActions,
+        });
+        if (options.updateMessageId) {
+            await this.outbound.updateInteractiveCard(contextKey, options.updateMessageId, card);
+        }
+        else {
+            await this.outbound.sendInteractiveCard(contextKey, card);
+        }
+    }
     async listSessions(contextKey, searchTerm, options = {}) {
         const context = this.store.getOrCreateUserContext(contextKey, this.config.defaults.agent);
         const normalizedSearch = searchTerm?.trim().toLowerCase();
-        const visibleCount = options.visibleCount ?? SESSION_PAGE_SIZE;
+        const requestedPage = Math.max(0, Math.trunc(options.page ?? 0));
+        const fetchLimit = (requestedPage + 1) * SESSION_PAGE_SIZE;
         const localSessions = this.store.listSessions(contextKey).filter((session) => session.status !== "closed" && this.isCodexSession(session));
         const remoteSessions = [];
         const remoteErrors = [];
@@ -2197,9 +2510,9 @@ export class ProxySessionController {
             if (!runtime.listRemoteSessions)
                 return;
             try {
-                const page = await runtime.listRemoteSessions({ searchTerm, limit: visibleCount });
-                remoteSessions.push(...page.sessions.map((session) => ({ agentName, session })));
-                remoteHasMore ||= Boolean(page.nextCursor);
+                const result = await runtime.listRemoteSessions({ searchTerm, limit: fetchLimit });
+                remoteSessions.push(...result.sessions.map((session) => ({ agentName, session })));
+                remoteHasMore ||= Boolean(result.nextCursor);
             }
             catch (error) {
                 this.logger.warn({ error, contextKey, agentName }, "Failed to list App Server sessions for an Agent.");
@@ -2217,9 +2530,13 @@ export class ProxySessionController {
             || Number(right.active) - Number(left.active)
             || right.updatedAt - left.updatedAt);
         const activeCount = entries.filter((entry) => entry.active).length;
-        const visibleEntries = entries.slice(0, visibleCount);
-        const hasMore = remoteHasMore || entries.length > visibleCount;
-        this.lastSessionListings.set(contextKey, visibleEntries.map((entry) => entry.reference));
+        const lastKnownPage = Math.max(0, Math.ceil(entries.length / SESSION_PAGE_SIZE) - 1);
+        const page = remoteHasMore ? requestedPage : Math.min(requestedPage, lastKnownPage);
+        const offset = page * SESSION_PAGE_SIZE;
+        const visibleEntries = entries.slice(offset, offset + SESSION_PAGE_SIZE);
+        const hasPrevious = page > 0;
+        const hasNext = remoteHasMore || entries.length > offset + SESSION_PAGE_SIZE;
+        this.lastSessionListings.set(contextKey, entries.map((entry) => entry.reference));
         const cardEntries = visibleEntries.map((entry, index) => {
             const marker = entry.current ? "✅" : entry.active ? "🟢 **活跃**" : "•";
             const showStop = entry.status === "外部执行中"
@@ -2232,7 +2549,7 @@ export class ProxySessionController {
                         action: showStop ? "session_stop" : "session_switch",
                         sessionId: entry.reference,
                         ...(searchTerm ? { searchTerm } : {}),
-                        visibleCount: String(visibleCount),
+                        page: String(page),
                         contextKey,
                     },
                 }];
@@ -2242,7 +2559,7 @@ export class ProxySessionController {
                     action: "session_new",
                     sessionId: entry.reference,
                     ...(searchTerm ? { searchTerm } : {}),
-                    visibleCount: String(visibleCount),
+                    page: String(page),
                     contextKey,
                 },
             });
@@ -2252,7 +2569,7 @@ export class ProxySessionController {
                     action: "session_new_group",
                     sessionId: entry.reference,
                     ...(searchTerm ? { searchTerm } : {}),
-                    visibleCount: String(visibleCount),
+                    page: String(page),
                     contextKey,
                 },
             });
@@ -2262,7 +2579,7 @@ export class ProxySessionController {
                     action: "session_fork",
                     sessionId: entry.reference,
                     ...(searchTerm ? { searchTerm } : {}),
-                    visibleCount: String(visibleCount),
+                    page: String(page),
                     contextKey,
                 },
             });
@@ -2272,7 +2589,7 @@ export class ProxySessionController {
                     action: "session_fork_group",
                     sessionId: entry.reference,
                     ...(searchTerm ? { searchTerm } : {}),
-                    visibleCount: String(visibleCount),
+                    page: String(page),
                     contextKey,
                 },
             });
@@ -2286,7 +2603,7 @@ export class ProxySessionController {
             });
             return {
                 lines: [
-                    `**${index + 1}.**　${marker}　**${cardText(entry.title)}**　${cardText(entry.id)}`,
+                    `**${offset + index + 1}.**　${marker}　**${cardText(entry.title)}**　${cardText(entry.id)}`,
                     `${entry.status} · ${entry.updatedLabel} · ${cardText(entry.agentName)} · ${cardText(entry.cwd || "目录未知")}`,
                 ],
                 actions,
@@ -2294,21 +2611,30 @@ export class ProxySessionController {
         });
         const card = this.cardRenderer.renderTaskListCard(searchTerm ? `App Server 任务：${searchTerm}` : "App Server 任务", activeCount > 0 ? `任务（${activeCount} 个活跃）` : "任务", cardEntries, [
             ...(remoteHint ? [remoteHint] : []),
-            "点击 **New** 在对应任务的项目中创建新任务；点击 **Switch** 快速切换；点击 **Fork** 从任务最新已完成轮次创建分支；外部正在运行的任务显示 **Stop**，点击后发送 Interrupt 并变为 **Switch**。",
-            "点击 **NewGroup** 在对应任务的项目中创建新群和新任务；点击 **ForkGroup** 从对应任务最新已完成轮次创建分支群。",
-            "也可发送 **/switch [序号或任务 ID]**；不带参数切回上一个任务。外部正在执行的回合不会被接管。",
-            "发送 **/fork [序号或任务 ID]**，可从当前或指定任务创建分支；任务运行中时使用最近已完成轮次。",
-            "点击 **Status**，或发送 **/status [序号或任务 ID]**，查看当前或指定任务状态。",
-        ], hasMore ? {
-            text: "More",
-            type: "primary",
-            value: {
-                action: "session_more",
-                ...(searchTerm ? { searchTerm } : {}),
-                visibleCount: String(visibleCount),
-                contextKey,
-            },
-        } : undefined);
+            `第 ${page + 1} 页 · 每页 ${SESSION_PAGE_SIZE} 个任务${hasNext ? "" : ` · 当前共 ${entries.length} 个任务`}`,
+            "",
+            "> **Switch** 切换任务；**Stop** 停止运行；**Status** 查看状态。",
+            "> **New** / **Fork** 新建 / 分支任务；**NewGroup** / **ForkGroup** 新建 / 分支群。",
+        ], [
+            ...(hasPrevious ? [{
+                    text: "Previous",
+                    value: {
+                        action: "session_page",
+                        ...(searchTerm ? { searchTerm } : {}),
+                        page: String(page - 1),
+                        contextKey,
+                    },
+                }] : []),
+            ...(hasNext ? [{
+                    text: "Next",
+                    value: {
+                        action: "session_page",
+                        ...(searchTerm ? { searchTerm } : {}),
+                        page: String(page + 1),
+                        contextKey,
+                    },
+                }] : []),
+        ]);
         if (options.updateMessageId) {
             await this.outbound.updateInteractiveCard(contextKey, options.updateMessageId, card);
         }
@@ -2316,17 +2642,16 @@ export class ProxySessionController {
             await this.outbound.sendInteractiveCard(contextKey, card);
         }
     }
-    async refreshSessionsCardFromAction(action, forceSwitchTaskId, loadMore = false) {
+    async refreshSessionsCardFromAction(action, options = {}) {
         if (!action.messageId)
             return;
         const searchTerm = typeof action.value.searchTerm === "string" && action.value.searchTerm.trim()
             ? action.value.searchTerm
             : undefined;
-        const currentVisibleCount = parseSessionVisibleCount(action.value.visibleCount);
         await this.listSessions(action.contextKey, searchTerm, {
             updateMessageId: action.messageId,
-            forceSwitchTaskId,
-            visibleCount: currentVisibleCount + (loadMore ? SESSION_PAGE_SIZE : 0),
+            forceSwitchTaskId: options.forceSwitchTaskId,
+            page: options.page ?? parseSessionPage(action.value.page),
         });
     }
     async refreshStatusCardFromAction(action, forceSwitchTaskId) {
@@ -2702,58 +3027,45 @@ export class ProxySessionController {
         else
             await this.outbound.sendInteractiveCard(contextKey, card);
     }
+    async executeHelpCommandAction(action, contextKey, replyTarget) {
+        const commandText = typeof action.value.command === "string"
+            ? action.value.command.trim()
+            : "";
+        if (!HELP_DEFAULT_COMMANDS.has(commandText)) {
+            throw new Error("帮助卡片中的命令无效，请发送 /help 获取最新卡片。");
+        }
+        const command = this.router.parse(commandText);
+        await this.execute(contextKey, command, undefined, replyTarget, undefined, action.userId);
+    }
     async help(contextKey) {
-        const sections = [
-            {
-                lines: [
-                    "直接发送消息即可继续当前任务；执行中发送的新消息会追加到本次任务。",
-                    "> 命令前缀示例：/sess 等同于 /sessions。",
-                    "> 命令缩写示例：/fg 等同于 /forkgroup。",
-                    "前缀或缩写匹配多个命令时，需要输入更长的形式。",
-                    "**[参数]** 可选　**&#60;参数&#62;** 必填",
-                ],
-            },
-            {
-                title: "任务管理",
-                lines: [
-                    "**/new [title] [--dir &#60;cwd&#62; | --nodir]**　使用默认 Agent 创建任务；--nodir 强制创建 Projectless 任务",
-                    "**/newgroup [title] [--dir &#60;cwd&#62; | --nodir]**　创建飞书群和新任务；参数与 /new 相同",
-                    "**/forkgroup [title]**　从当前任务最新已完成轮次创建分支并绑定到新群",
-                    "**/fork [序号或任务 ID]**　从当前或指定任务创建分支；运行中使用最近已完成轮次",
-                    "**/title &#60;新标题&#62;**　修改当前任务的标题",
-                    "**/sessions [关键词]**　查找本机任务",
-                    "**/switch [序号或任务 ID]**　不填参数切回上一个任务",
-                ],
-            },
-            {
-                title: "执行设置",
-                lines: [
-                    "**! &#60;命令&#62;**　在当前任务目录直接执行本地命令",
-                    "**/stop**　停止当前执行",
-                    "**/queue &#60;prompt&#62;**（兼容 **/nosteer**）　不追加到当前轮次，按顺序排队为后续轮次",
-                    "**/goal [目标]**　查看或创建长任务 Goal；支持 pause、resume、edit、clear",
-                    "**/provider**　选择 AI 服务提供商；没有其他候选时仅显示当前 Provider",
-                    "**/model**　选择当前任务使用的模型",
-                    "**/thinking**　设置模型的思考强度",
-                    "**/permissions**　设置执行工具前是否需要确认",
-                ],
-            },
-            {
-                title: "Agent",
-                lines: [
-                    "**/agent [name]**　选择新任务使用的默认 Agent；仅配置一个时直接显示当前 Agent",
-                ],
-            },
-            {
-                title: "系统",
-                lines: [
-                    "**/status [序号或任务 ID]**　查看当前或指定任务的详细状态",
-                    "**/restart [--force]**　默认安全重启；--force 立即重启",
-                    "**/help**　显示本帮助",
-                ],
-            },
-        ];
-        await this.outbound.sendInteractiveCard(contextKey, this.cardRenderer.renderSectionsCard("Agent Bot 使用帮助", sections));
+        const sections = HELP_COMMAND_SECTIONS.map((section) => ({
+            title: section.title,
+            commands: section.commands.map((command) => ({
+                text: command.command,
+                ...(command.requiresArgument
+                    ? {}
+                    : {
+                        action: {
+                            text: command.command,
+                            value: {
+                                action: "help_command",
+                                command: command.command,
+                                contextKey,
+                            },
+                        },
+                    }),
+                ...(command.usage ? { usage: command.usage } : {}),
+                description: command.description,
+            })),
+        }));
+        await this.outbound.sendInteractiveCard(contextKey, this.cardRenderer.renderHelpCard("Agent Bot 使用帮助", [
+            "直接发送消息即可继续当前任务；执行中发送的新消息会追加到本次任务。",
+            "点击命令按钮可执行默认形式；有必填参数的命令需要手动发送。",
+            "> 命令前缀示例：/sess 等同于 /sessions。",
+            "> 命令缩写示例：/fg 等同于 /forkgroup。",
+            "前缀或缩写匹配多个命令时，需要输入更长的形式。",
+            "**[参数]** 可选　**&#60;参数&#62;** 必填",
+        ], sections));
     }
     ensureAgent(agentName) {
         const agent = this.config.agents[agentName];
@@ -3090,6 +3402,9 @@ function formatStatusTime(value) {
         hourCycle: "h23",
     }).format(date);
 }
+function formatResetTurnTime(value) {
+    return value === undefined ? "完成时间未知" : formatStatusTime(new Date(value).toISOString());
+}
 function cardText(value) {
     return value.replaceAll("&", "&amp;").replaceAll("`", "&#96;").replaceAll("<", "&#60;").replaceAll(">", "&#62;");
 }
@@ -3106,10 +3421,16 @@ function executionSettingsTabValue(value) {
         return value;
     throw new Error("设置卡片的 tab 无效，请重新发送设置命令。");
 }
+function resetHistoryPageValue(value) {
+    const page = Number(value);
+    if (!Number.isSafeInteger(page) || page < 0)
+        throw new Error("历史轮次卡片页码无效，请重新发送 /turns。");
+    return page;
+}
 function requiredCardMessageId(value) {
     if (value)
         return value;
-    throw new Error("无法更新设置卡片，请重新发送设置命令。");
+    throw new Error("无法更新卡片，请重新发送对应命令。");
 }
 function remoteSessionStatusLabel(status) {
     const labels = {
@@ -3206,9 +3527,9 @@ function isQueueIndependentCommand(command) {
         return true;
     return false;
 }
-function parseSessionVisibleCount(value) {
+function parseSessionPage(value) {
     const parsed = typeof value === "string" || typeof value === "number" ? Number(value) : Number.NaN;
-    return Number.isSafeInteger(parsed) && parsed >= SESSION_PAGE_SIZE ? parsed : SESSION_PAGE_SIZE;
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0;
 }
 function isPromptCommand(command) {
     return command.type === "prompt" || command.type === "nosteer";