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

package/src/proxy/ProxySessionController.ts

@@ -17,11 +17,15 @@ import {
   CardRenderer,
   type CardSection,
   type ExecutionSettingsTab,
+  type HelpCardSection,
+  type ResetHistoryCardEntry,
   type TaskListCardAction,
+  type TaskListCardEntry,
 } from "../feishu/CardRenderer.js";
 import { generateGroupAvatarPng, resolveGroupAvatarProjectName } from "../feishu/GroupAvatarGenerator.js";
 import type { OutboundRouter } from "../presentation/OutboundRouter.js";
 import type { TurnActivity, TurnViewState } from "../presentation/turnViewTypes.js";
+import { buildTurnGraphRows } from "../presentation/turnGraph.js";
 import type { AgentRuntimeRegistry } from "../runtime/AgentRuntimeRegistry.js";
 import type {
   AgentRuntime,
@@ -61,8 +65,126 @@ 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:";
 
+interface HelpCommandDefinition {
+  command: string;
+  usage?: string;
+  description: string;
+  requiresArgument?: boolean;
+}
+
+const HELP_COMMAND_SECTIONS: Array<{
+  title: string;
+  commands: HelpCommandDefinition[];
+}> = [
+  {
+    title: "任务管理",
+    commands: [
+      {
+        command: "/new",
+        usage: "[title] [--dir &#60;cwd&#62; | --nodir]",
+        description: "使用默认 Agent 创建任务；--nodir 创建 Projectless 任务",
+      },
+      {
+        command: "/newgroup",
+        usage: "[title] [--dir &#60;cwd&#62; | --nodir]",
+        description: "创建飞书群和新任务",
+      },
+      {
+        command: "/forkgroup",
+        usage: "[title]",
+        description: "从当前任务最近完成轮次创建分支群",
+      },
+      {
+        command: "/fork",
+        usage: "[序号或任务 ID]",
+        description: "从当前或指定任务最近完成轮次创建分支",
+      },
+      { command: "/turns", description: "浏览历史轮次，并可 Reset 对话上下文" },
+      {
+        command: "/title",
+        usage: "&#60;新标题&#62;",
+        description: "修改当前任务标题",
+        requiresArgument: true,
+      },
+      { command: "/sessions", usage: "[关键词]", description: "查找本机任务" },
+      {
+        command: "/switch",
+        usage: "[序号或任务 ID]",
+        description: "切换任务；不填参数切回上一个任务",
+      },
+    ],
+  },
+  {
+    title: "执行设置",
+    commands: [
+      {
+        command: "!",
+        usage: "&#60;命令&#62;",
+        description: "在当前任务目录执行本地命令",
+        requiresArgument: true,
+      },
+      { command: "/stop", description: "停止当前执行" },
+      {
+        command: "/queue",
+        usage: "&#60;prompt&#62;",
+        description: "将 Prompt 排队为后续轮次",
+        requiresArgument: true,
+      },
+      {
+        command: "/nosteer",
+        usage: "&#60;prompt&#62;",
+        description: "与 /queue 相同",
+        requiresArgument: true,
+      },
+      {
+        command: "/goal",
+        usage: "&#60;目标或操作&#62;",
+        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),
+);
+
 interface AgentRemoteSession {
   agentName: string;
   runtime: AgentRuntime;
@@ -77,7 +199,7 @@ interface AgentRemoteSessionSummary {
 interface SessionsCardOptions {
   updateMessageId?: string;
   forceSwitchTaskId?: string;
-  visibleCount?: number;
+  page?: number;
 }
 
 interface StatusCardOptions {
@@ -85,6 +207,12 @@ interface StatusCardOptions {
   forceSwitchTaskId?: string;
 }
 
+interface ResetHistoryCardOptions {
+  expectedSessionId?: string;
+  updateMessageId?: string;
+  page?: number;
+}
+
 interface ModelCardOptions {
   sessionId?: string;
   updateMessageId?: string;
@@ -167,8 +295,9 @@ export interface ControlTaskGroupResult {
 
 export interface ProxyLifecycle {
   supervised?: boolean;
-  restart(contextKey: string, force: boolean): Promise<void>;
+  restart(contextKey: string, force: boolean, replyTarget?: MessageReplyTarget): Promise<void>;
   cancelSafeRestart?(scheduleId: number): Promise<boolean>;
+  rememberFeishuUserOpenId?(userOpenId: string): Promise<void> | void;
 }
 
 export type ShellCommandExecutor = (command: string, cwd: string) => Promise<ShellCommandResult>;
@@ -181,6 +310,7 @@ export class ProxySessionController {
   private readonly queuedPromptStarts = new Map<string, Promise<void>>();
   private readonly queuedPromptCards = new Map<string, Map<string, string>>();
   private readonly queuedPromptCardWrites = new Map<string, Promise<void>>();
+  private readonly sessionResets = new Map<string, Promise<void>>();
   private readonly lastSessionListings = new Map<string, string[]>();
   private readonly threadInitializations = new Map<string, Promise<void>>();
   private readonly unsubscribe: Array<() => void> = [];
@@ -240,8 +370,20 @@ export class ProxySessionController {
         "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 as const }
@@ -252,9 +394,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: string[] | undefined;
     if (imageCount > 0) {
       try {
@@ -284,17 +423,6 @@ export class ProxySessionController {
       );
       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 () => {
@@ -355,7 +483,9 @@ 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") {
           const requestedPage = String(scopedAction.value.page ?? "0");
@@ -369,6 +499,26 @@ export class ProxySessionController {
         } else if (kind === "turn_cancel") {
           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);
         } else if (kind === "safe_restart_cancel") {
@@ -383,17 +533,17 @@ export class ProxySessionController {
           if (!cancelled) {
             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 ?? "");
           await this.switchSession(contextKey, sessionId);
           if (scopedAction.value.cardView === "status") await this.refreshStatusCardFromAction(scopedAction);
-          else await this.refreshSessionsCardFromAction(scopedAction);
+          else 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 ?? "");
           await this.forkSessionReferenceToFeishuGroup(contextKey, sessionId, scopedAction.userId);
@@ -401,7 +551,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 ?? "");
           await this.createFeishuGroupFromReference(contextKey, sessionId, scopedAction.userId);
@@ -410,7 +560,7 @@ export class ProxySessionController {
           const sessionId = String(scopedAction.value.sessionId ?? "");
           await this.stopSessionReference(contextKey, sessionId);
           if (scopedAction.value.cardView === "status") await this.refreshStatusCardFromAction(scopedAction, sessionId);
-          else await this.refreshSessionsCardFromAction(scopedAction, sessionId);
+          else await this.refreshSessionsCardFromAction(scopedAction, { forceSwitchTaskId: sessionId });
         } else if (kind === "session_status") {
           await this.status(contextKey, String(scopedAction.value.sessionId ?? ""));
         } else if (kind === "session_status_refresh") {
@@ -541,6 +691,7 @@ export class ProxySessionController {
     this.lastSessionListings.clear();
     this.queuedPromptCards.clear();
     this.queuedPromptCardWrites.clear();
+    this.sessionResets.clear();
   }
 
   async controlStopTask(localSessionId: string): Promise<string> {
@@ -831,7 +982,10 @@ export class ProxySessionController {
         return;
       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");
@@ -2063,6 +2217,24 @@ export class ProxySessionController {
   }
 
   private async handleRuntimeEvent(event: RuntimeEvent): Promise<void> {
+    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);
@@ -2157,6 +2329,13 @@ export class ProxySessionController {
     }
   }
 
+  private completedParentTurnId(source: SessionRecord | undefined): string | undefined {
+    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;
+  }
+
   private async finalizeStandaloneMessageReaction(
     messageId: string,
     status: "completed" | "failed" | "cancelled",
@@ -2271,6 +2450,111 @@ export class ProxySessionController {
     await loaded.runtime.cancelTurn(record.localSessionId, turnId);
   }
 
+  private async resetCurrentSessionToTurn(
+    contextKey: string,
+    sessionId: string,
+    turnId: string,
+  ): Promise<void> {
+    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);
+    }
+  }
+
+  private async performCurrentSessionReset(
+    contextKey: string,
+    sessionId: string,
+    turnId: string,
+  ): Promise<void> {
+    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"),
+    );
+  }
+
   private async resolveApproval(action: CardAction): Promise<void> {
     const sessionId = String(action.value.sessionId ?? "");
     const requestId = String(action.value.requestId ?? "");
@@ -2824,6 +3108,92 @@ export class ProxySessionController {
     await this.outbound.sendText(contextKey, mode === "auto" ? "已切换为自动执行模式。" : "已切换为执行前确认模式。");
   }
 
+  private async openResetHistory(
+    contextKey: string,
+    options: ResetHistoryCardOptions = {},
+  ): Promise<void> {
+    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: ResetHistoryCardEntry[] = 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: TaskListCardAction[] = [
+      ...(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);
+    }
+  }
+
   private async listSessions(
     contextKey: string,
     searchTerm?: string,
@@ -2831,7 +3201,8 @@ export class ProxySessionController {
   ): Promise<void> {
     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),
     );
@@ -2841,9 +3212,9 @@ export class ProxySessionController {
     await Promise.all(this.runtimes.entries("codex").map(async ([agentName, runtime]) => {
       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.");
         remoteErrors.push(`${agentName}: ${error instanceof Error ? error.message : String(error)}`);
@@ -2861,9 +3232,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 === "外部执行中"
@@ -2876,7 +3251,7 @@ export class ProxySessionController {
           action: showStop ? "session_stop" : "session_switch",
           sessionId: entry.reference,
           ...(searchTerm ? { searchTerm } : {}),
-          visibleCount: String(visibleCount),
+          page: String(page),
           contextKey,
         },
       }];
@@ -2886,7 +3261,7 @@ export class ProxySessionController {
           action: "session_new",
           sessionId: entry.reference,
           ...(searchTerm ? { searchTerm } : {}),
-          visibleCount: String(visibleCount),
+          page: String(page),
           contextKey,
         },
       });
@@ -2896,7 +3271,7 @@ export class ProxySessionController {
           action: "session_new_group",
           sessionId: entry.reference,
           ...(searchTerm ? { searchTerm } : {}),
-          visibleCount: String(visibleCount),
+          page: String(page),
           contextKey,
         },
       });
@@ -2906,7 +3281,7 @@ export class ProxySessionController {
           action: "session_fork",
           sessionId: entry.reference,
           ...(searchTerm ? { searchTerm } : {}),
-          visibleCount: String(visibleCount),
+          page: String(page),
           contextKey,
         },
       });
@@ -2916,7 +3291,7 @@ export class ProxySessionController {
           action: "session_fork_group",
           sessionId: entry.reference,
           ...(searchTerm ? { searchTerm } : {}),
-          visibleCount: String(visibleCount),
+          page: String(page),
           contextKey,
         },
       });
@@ -2930,7 +3305,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,
@@ -2942,22 +3317,31 @@ export class ProxySessionController {
       cardEntries,
       [
         ...(remoteHint ? [remoteHint] : []),
-        "点击 **New** 在对应任务的项目中创建新任务；点击 **Switch** 快速切换；点击 **Fork** 从任务最新已完成轮次创建分支；外部正在运行的任务显示 **Stop**，点击后发送 Interrupt 并变为 **Switch**。",
-        "点击 **NewGroup** 在对应任务的项目中创建新群和新任务；点击 **ForkGroup** 从对应任务最新已完成轮次创建分支群。",
-        "也可发送 **/switch [序号或任务 ID]**；不带参数切回上一个任务。外部正在执行的回合不会被接管。",
-        "发送 **/fork [序号或任务 ID]**，可从当前或指定任务创建分支；任务运行中时使用最近已完成轮次。",
-        "点击 **Status**，或发送 **/status [序号或任务 ID]**，查看当前或指定任务状态。",
+        `第 ${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,
+          },
+        }] : []),
       ],
-      hasMore ? {
-        text: "More",
-        type: "primary",
-        value: {
-          action: "session_more",
-          ...(searchTerm ? { searchTerm } : {}),
-          visibleCount: String(visibleCount),
-          contextKey,
-        },
-      } : undefined,
     );
     if (options.updateMessageId) {
       await this.outbound.updateInteractiveCard(contextKey, options.updateMessageId, card);
@@ -2968,18 +3352,16 @@ export class ProxySessionController {
 
   private async refreshSessionsCardFromAction(
     action: CardAction,
-    forceSwitchTaskId?: string,
-    loadMore = false,
+    options: { forceSwitchTaskId?: string; page?: number } = {},
   ): Promise<void> {
     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),
     });
   }
 
@@ -3400,58 +3782,61 @@ export class ProxySessionController {
     else await this.outbound.sendInteractiveCard(contextKey, card);
   }
 
+  private async executeHelpCommandAction(
+    action: CardAction,
+    contextKey: string,
+    replyTarget?: MessageReplyTarget,
+  ): Promise<void> {
+    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,
+    );
+  }
+
   private async help(contextKey: string): Promise<void> {
-    const sections: CardSection[] = [
-      {
-        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: HelpCardSection[] = 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,
+    ));
   }
 
   private ensureAgent(agentName: string) {
@@ -3825,6 +4210,10 @@ function formatStatusTime(value: string): string {
   }).format(date);
 }
 
+function formatResetTurnTime(value?: number): string {
+  return value === undefined ? "完成时间未知" : formatStatusTime(new Date(value).toISOString());
+}
+
 function cardText(value: string): string {
   return value.replaceAll("&", "&amp;").replaceAll("`", "&#96;").replaceAll("<", "&#60;").replaceAll(">", "&#62;");
 }
@@ -3843,9 +4232,15 @@ function executionSettingsTabValue(value: unknown): ExecutionSettingsTab {
   throw new Error("设置卡片的 tab 无效，请重新发送设置命令。");
 }
 
+function resetHistoryPageValue(value: unknown): number {
+  const page = Number(value);
+  if (!Number.isSafeInteger(page) || page < 0) throw new Error("历史轮次卡片页码无效，请重新发送 /turns。");
+  return page;
+}
+
 function requiredCardMessageId(value: string | undefined): string {
   if (value) return value;
-  throw new Error("无法更新设置卡片，请重新发送设置命令。");
+  throw new Error("无法更新卡片，请重新发送对应命令。");
 }
 
 function remoteSessionStatusLabel(status: RemoteSessionSummary["status"]): string {
@@ -3947,9 +4342,9 @@ function isQueueIndependentCommand(command: Command): boolean {
   return false;
 }
 
-function parseSessionVisibleCount(value: unknown): number {
+function parseSessionPage(value: unknown): number {
   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: Command): boolean {