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

package/src/acp/AcpProcessManager.ts

@@ -3,7 +3,10 @@ import readline from "node:readline";
 import type { Logger } from "pino";
 import type { AgentConfig } from "../config/schema.js";
 import { AcpJsonRpcConnection } from "./AcpJsonRpcConnection.js";
-import { agentBotEnvironment } from "../runtime/agentEnvironment.js";
+import {
+  agentBotEnvironment,
+  type AgentEnvironmentContext,
+} from "../runtime/agentEnvironment.js";
 import { spawnStdioCommand } from "../utils/spawnCommand.js";
 
 export interface ManagedAcpProcess {
@@ -16,14 +19,24 @@ export interface ManagedAcpProcess {
 export class AcpProcessManager {
   private readonly processes = new Map<string, ManagedAcpProcess>();
 
-  constructor(private readonly logger: Logger) {}
+  constructor(
+    private readonly logger: Logger,
+    private readonly environmentContext: () => AgentEnvironmentContext = () => ({}),
+  ) {}
 
   start(processKey: string, agentName: string, agent: AgentConfig): ManagedAcpProcess {
     if (this.processes.has(processKey)) {
       throw new Error(`ACP process already exists: ${processKey}`);
     }
 
-    const child = spawnStdioCommand(agent.command, agent.args, agentBotEnvironment(process.env, agent.env));
+    const child = spawnStdioCommand(
+      agent.command,
+      agent.args,
+      agentBotEnvironment(process.env, agent.env, {
+        ...this.environmentContext(),
+        agentName,
+      }),
+    );
 
     const childLogger = this.logger.child({ processKey, agentName });
     const connection = new AcpJsonRpcConnection(child, childLogger);

package/src/acp/AcpSessionManager.ts

@@ -40,6 +40,7 @@ export class AcpSessionManager {
   private readonly sessions = new Map<string, RuntimeSession>();
   private readonly sessionsByAcpId = new Map<string, RuntimeSession>();
   private processStart?: Promise<ManagedAcpProcess>;
+  private processVersion?: string;
 
   constructor(
     private readonly agentName: string,
@@ -52,6 +53,15 @@ export class AcpSessionManager {
     return this.sessions.get(localSessionId);
   }
 
+  getProcessInfo(): { pid?: number; version?: string } {
+    const pid = this.processManager.get(this.agentName)?.child.pid;
+    if (!pid) return {};
+    return {
+      pid,
+      ...(this.processVersion ? { version: this.processVersion } : {}),
+    };
+  }
+
   async create(input: CreateRuntimeSessionInput): Promise<RuntimeSession> {
     if (input.agentName !== this.agentName) throw new Error(`Unexpected agent: ${input.agentName}`);
 
@@ -133,6 +143,7 @@ export class AcpSessionManager {
     this.sessions.clear();
     this.sessionsByAcpId.clear();
     this.processStart = undefined;
+    this.processVersion = undefined;
     this.processManager.stopAll();
   }
 
@@ -181,6 +192,7 @@ export class AcpSessionManager {
   }
 
   private async startProcess(): Promise<ManagedAcpProcess> {
+    this.processVersion = undefined;
     const managed = this.processManager.start(this.agentName, this.agentName, this.agent);
     try {
       const connection = managed.connection;
@@ -210,6 +222,8 @@ export class AcpSessionManager {
           version: "0.1.0",
         },
       });
+      const version = initializeResult.agentInfo?.version?.trim();
+      if (version) this.processVersion = version;
       if (initializeResult.authMethods?.length) {
         const method = initializeResult.authMethods[0];
         this.logger.info({ methodId: method.id }, "Authenticating ACP agent with first advertised method.");

package/src/cli/help.ts

@@ -13,10 +13,11 @@ export function renderCliHelp(version: string, language: CliLanguage = cliLangua
   init --reset                      重置并重新配置显式指定的 Profile
   console                           打开本地控制台
   server start                      在后台启动 Agent Bot
-  server status                     显示服务、飞书 App ID 和安全重启状态
+  server status                     显示服务、飞书 App ID、Agent 进程和安全重启状态
   server restart [--task <任务>]    安排安全重启并将状态发回指定任务会话
   server stop                       停止 Agent Bot
   task list                         列出任务
+  task current [--json]             显示当前调用任务的详情
   task status <任务>                显示任务状态
   task chat <任务>                  显示任务绑定的飞书会话
   task prompt <任务> <提示词>       向任务发送提示词
@@ -66,10 +67,11 @@ Common commands:
   init --reset                      Reset and reconfigure an explicit profile
   console                           Open the local console
   server start                      Start Agent Bot in the background
-  server status                     Show the server, Lark App ID, and safe-restart status
+  server status                     Show the server, Lark App ID, Agent processes, and safe-restart status
   server restart [--task <task>]    Schedule a safe restart and return status to the task's conversation
   server stop                       Stop Agent Bot
   task list                         List tasks
+  task current [--json]             Show details for the task invoking the CLI
   task status <task>                Show task status
   task chat <task>                  Show the task's Lark chat binding
   task prompt <task> <prompt>       Send a Prompt to a task

package/src/cli/serverStatus.ts

@@ -29,16 +29,44 @@ export function formatServerStatus(data: unknown, language: CliLanguage = cliLan
         language,
       )
     : cliText("not scheduled", "未计划", language);
+  const agents = formatAgentProcesses(value.agents, language);
   return [
     `${cliText("Agent Bot server: ", "Agent Bot 服务：", language)}${state}`,
     `${cliText("Lark App ID: ", "飞书 App ID：", language)}${value.feishuAppId ?? cliText("not configured", "未配置", language)}`,
     `${cliText("PID: ", "PID：", language)}${value.pid ?? "-"}`,
     `${cliText("Started at: ", "启动时间：", language)}${value.startedAt ?? "-"}`,
     `${cliText("Supervisor: ", "Supervisor：", language)}${value.supervised ? cliText("enabled", "已启用", language) : cliText("disabled", "未启用", language)}`,
+    ...agents,
     `${cliText("Running tasks: ", "运行中任务：", language)}${activity.runningSessions ?? 0}`,
     `${cliText("Pending final deliveries: ", "待发送最终结果：", language)}${activity.pendingFinalDeliveries ?? 0}`,
     `${cliText("Safe restart: ", "安全重启：", language)}${safeRestart}`,
     "",
   ].join("\n");
 }
+
+function formatAgentProcesses(value: unknown, language: CliLanguage): string[] {
+  const agents = Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object")
+    : [];
+  if (agents.length === 0) {
+    return [`${cliText("Agents: ", "Agent 进程：", language)}-`];
+  }
+  return [
+    cliText("Agents:", "Agent 进程：", language),
+    ...agents.map((agent) => {
+      const name = typeof agent.name === "string" && agent.name.trim() ? agent.name.trim() : "-";
+      const title = typeof agent.title === "string" && agent.title.trim() ? agent.title.trim() : undefined;
+      const label = title && title !== name ? `${name} (${title})` : name;
+      const pid = typeof agent.pid === "number" && Number.isInteger(agent.pid) && agent.pid > 0
+        ? String(agent.pid)
+        : "-";
+      const version = typeof agent.version === "string" && agent.version.trim()
+        ? agent.version.trim()
+        : "-";
+      return language === "zh"
+        ? `  ${label}：PID ${pid}，版本 ${version}`
+        : `  ${label}: PID ${pid}, version ${version}`;
+    }),
+  ];
+}
 import { cliLanguage, cliText, type CliLanguage } from "./i18n.js";

package/src/cli/taskListOutput.ts

@@ -0,0 +1,91 @@
+import type { SessionRecord } from "../state/StateStore.js";
+import { cliLanguage, cliText, type CliLanguage } from "./i18n.js";
+
+export type CurrentTaskResolution =
+  | { status: "found"; session: SessionRecord }
+  | { status: "missing-thread-id" }
+  | { status: "not-found"; threadIds: string[] }
+  | { status: "ambiguous"; sessions: SessionRecord[]; threadIds: string[] };
+
+export function formatTaskList(
+  sessions: SessionRecord[],
+  language: CliLanguage = cliLanguage,
+  currentThreadIds: readonly string[] = [],
+): string {
+  if (sessions.length === 0) return cliText("No tasks.\n", "没有任务。\n", language);
+
+  const current = resolveCurrentTask(sessions, currentThreadIds);
+  const currentLocalSessionId = current.status === "found" ? current.session.localSessionId : undefined;
+  return sessions.map((session, index) => {
+    const title = session.title ?? cliText("Untitled task", "未命名任务", language);
+    const current = session.localSessionId === currentLocalSessionId
+      ? ` [${cliText("Current", "当前任务", language)}]`
+      : "";
+    const nativeId = nativeTaskIdLabel(session, language);
+    return [
+      `${index + 1}.${current} [${taskStateLabel(session.status, language)}/${taskStateLabel(session.lastTurnStatus, language)}] ${title}`,
+      `   ${cliText("Agent: ", "Agent：", language)}${session.agentName} · ${cliText("AgentBot task ID: ", "AgentBot 任务 ID：", language)}${session.localSessionId}`,
+      `   ${nativeId ? `${nativeId} · ` : ""}${session.contextKey} · ${session.updatedAt}`,
+    ].join("\n");
+  }).join("\n") + "\n";
+}
+
+export function currentAppServerThreadIds(env: NodeJS.ProcessEnv): string[] {
+  return [...new Set([
+    env.CODEX_THREAD_ID?.trim(),
+    env.TRAECLI_THREAD_ID?.trim(),
+  ].filter((value): value is string => Boolean(value)))];
+}
+
+export function resolveCurrentTask(
+  sessions: SessionRecord[],
+  currentThreadIds: readonly string[],
+): CurrentTaskResolution {
+  const threadIds = [...new Set(currentThreadIds.map((value) => value.trim()).filter(Boolean))];
+  if (threadIds.length === 0) return { status: "missing-thread-id" };
+
+  const candidates = new Set(threadIds);
+  const matches = sessions.filter((session) => session.remoteSessionId && candidates.has(session.remoteSessionId));
+  if (matches.length === 0) return { status: "not-found", threadIds };
+  if (matches.length === 1) return { status: "found", session: matches[0]! };
+
+  const running = matches.filter((session) =>
+    session.status === "running" || session.lastTurnStatus === "running");
+  if (running.length === 1) return { status: "found", session: running[0]! };
+  return { status: "ambiguous", sessions: matches, threadIds };
+}
+
+export function taskStateLabel(
+  status: string | undefined,
+  language: CliLanguage = cliLanguage,
+): string {
+  if (!status) return "-";
+  const chinese: Record<string, string> = {
+    starting: "启动中",
+    ready: "就绪",
+    running: "运行中",
+    closed: "已关闭",
+    failed: "失败",
+    completed: "已完成",
+    cancelled: "已取消",
+    interrupted: "已中断",
+    inProgress: "进行中",
+    active: "活动中",
+    idle: "空闲",
+    not_loaded: "未加载",
+    error: "错误",
+  };
+  return language === "zh" ? chinese[status] ?? status : status;
+}
+
+function nativeTaskIdLabel(session: SessionRecord, language: CliLanguage): string | undefined {
+  if (session.runtimeKind === "acp" || session.acpSessionId) {
+    const sessionId = session.acpSessionId ?? session.remoteSessionId;
+    return sessionId
+      ? `${cliText("ACP session ID: ", "ACP Session ID：", language)}${sessionId}`
+      : undefined;
+  }
+  return session.remoteSessionId
+    ? `${cliText("App Server thread ID: ", "App Server 原生任务 ID（Thread ID）：", language)}${session.remoteSessionId}`
+    : undefined;
+}

package/src/cli.ts

@@ -65,6 +65,12 @@ import {
   type ServerStartResult,
 } from "./cli/ServerStarter.js";
 import { taskChatRoute } from "./cli/taskChatRoute.js";
+import {
+  currentAppServerThreadIds,
+  formatTaskList,
+  resolveCurrentTask,
+  taskStateLabel,
+} from "./cli/taskListOutput.js";
 import { isThreadContextKey } from "./feishu/contextKey.js";
 import { refreshedSystemEnvironment } from "./supervision/systemEnvironment.js";
 import {
@@ -724,6 +730,16 @@ async function taskCommand(input: string[]): Promise<void> {
   const store = new StateStore(config.storage.sqlitePath);
   try {
     const allSessions = store.listAllSessions();
+    if (action === "current") {
+      const unsupported = rest.filter((value) => value !== "--json");
+      if (unsupported.length > 0) throw new Error(cliText(
+        `task current does not accept arguments: ${unsupported.join(" ")}`,
+        `task current 不接受这些参数：${unsupported.join(" ")}`,
+      ));
+      const session = resolveCurrentTaskFromEnvironment(allSessions);
+      await outputTaskStatus(config.storage.sqlitePath, store, session, rest.includes("--json"));
+      return;
+    }
     if (action === "prompt" || action === "send") {
       const [reference, ...promptParts] = rest;
       if (!reference) throw new Error(cliText(
@@ -809,28 +825,7 @@ async function taskCommand(input: string[]): Promise<void> {
       return;
     }
     if (action === "status") {
-      const endpoint = controlEndpoint(config.storage.sqlitePath);
-      let live: TaskStatusControlData | undefined;
-      let response: ControlResponse | undefined;
-      try {
-        response = await sendControlRequest(endpoint, {
-          action: "task_status",
-          localSessionId: session.localSessionId,
-        });
-      } catch {
-        // The server can be stopped or still run an older control protocol
-        // while a safe restart is pending. Preserve the local read-only fallback.
-      }
-      if (response) {
-        ensureOk(response);
-        live = response.data as TaskStatusControlData;
-      }
-      const statusSession = live?.session ?? session;
-      const snapshot = live?.snapshot
-        ?? (statusSession.lastTurnId ? store.getTurnSnapshot(statusSession.lastTurnId) : undefined);
-      const result = { ...statusSession, snapshot, ...(live?.remote ? { remote: live.remote } : {}) };
-      if (rest.includes("--json")) printJson(result);
-      else printTaskStatus(statusSession, snapshot, live?.remote);
+      await outputTaskStatus(config.storage.sqlitePath, store, session, rest.includes("--json"));
       return;
     }
     const endpoint = controlEndpoint(config.storage.sqlitePath);
@@ -862,6 +857,53 @@ async function taskCommand(input: string[]): Promise<void> {
   }
 }
 
+function resolveCurrentTaskFromEnvironment(sessions: SessionRecord[]): SessionRecord {
+  const resolution = resolveCurrentTask(sessions, currentAppServerThreadIds(process.env));
+  if (resolution.status === "found") return resolution.session;
+  if (resolution.status === "missing-thread-id") throw new Error(cliText(
+    "The current task cannot be detected because neither CODEX_THREAD_ID nor TRAECLI_THREAD_ID is set. Run this command from a Codex or TraeX task.",
+    "无法检测当前任务：CODEX_THREAD_ID 和 TRAECLI_THREAD_ID 均未设置。请从 Codex 或 TraeX 任务中运行此命令。",
+  ));
+  if (resolution.status === "not-found") throw new Error(cliText(
+    `No AgentBot task matches the current App Server Thread ID (${resolution.threadIds.join(", ")}). Check that the correct Profile is selected.`,
+    `没有 AgentBot 任务匹配当前 App Server Thread ID（${resolution.threadIds.join("，")}）。请检查是否选择了正确的 Profile。`,
+  ));
+  throw new Error(cliText(
+    "The current task is ambiguous because multiple injected Thread IDs match AgentBot tasks. Use task status <task> with an explicit AgentBot task ID.",
+    "当前任务存在歧义：多个注入的 Thread ID 匹配到了 AgentBot 任务。请使用明确的 AgentBot 任务 ID 执行 task status <任务>。",
+  ));
+}
+
+async function outputTaskStatus(
+  sqlitePath: string,
+  store: StateStore,
+  session: SessionRecord,
+  json: boolean,
+): Promise<void> {
+  const endpoint = controlEndpoint(sqlitePath);
+  let live: TaskStatusControlData | undefined;
+  let response: ControlResponse | undefined;
+  try {
+    response = await sendControlRequest(endpoint, {
+      action: "task_status",
+      localSessionId: session.localSessionId,
+    });
+  } catch {
+    // The server can be stopped or still run an older control protocol
+    // while a safe restart is pending. Preserve the local read-only fallback.
+  }
+  if (response) {
+    ensureOk(response);
+    live = response.data as TaskStatusControlData;
+  }
+  const statusSession = live?.session ?? session;
+  const snapshot = live?.snapshot
+    ?? (statusSession.lastTurnId ? store.getTurnSnapshot(statusSession.lastTurnId) : undefined);
+  const result = { ...statusSession, snapshot, ...(live?.remote ? { remote: live.remote } : {}) };
+  if (json) printJson(result);
+  else printTaskStatus(statusSession, snapshot, live?.remote);
+}
+
 function filterSessions(sessions: SessionRecord[], args: string[]): SessionRecord[] {
   const context = optionValue(args, "--context");
   const status = optionValue(args, "--status");
@@ -896,19 +938,12 @@ function resolveTask(sessions: SessionRecord[], reference: string): SessionRecor
 }
 
 function printTaskList(sessions: SessionRecord[]): void {
-  if (sessions.length === 0) {
-    process.stdout.write(cliText("No tasks.\n", "没有任务。\n"));
-    return;
-  }
-  for (const [index, session] of sessions.entries()) {
-    const id = session.remoteSessionId ?? session.acpSessionId ?? session.localSessionId;
-    process.stdout.write(`${index + 1}. [${taskStateLabel(session.status)}/${taskStateLabel(session.lastTurnStatus)}] ${session.title ?? cliText("Untitled task", "未命名任务")}\n`);
-    process.stdout.write(`   ${id} · ${session.contextKey} · ${session.updatedAt}\n`);
-  }
+  process.stdout.write(formatTaskList(sessions, cliLanguage, currentAppServerThreadIds(process.env)));
 }
 
 function printTaskStatus(session: SessionRecord, snapshot: unknown, remote?: TaskStatusControlData["remote"]): void {
   process.stdout.write(`${cliText("Title: ", "标题：")}${session.title ?? cliText("Untitled task", "未命名任务")}\n`);
+  process.stdout.write(`${cliText("Agent: ", "Agent：")}${session.agentName}\n`);
   process.stdout.write(`${cliText("Task ID: ", "任务 ID：")}${session.remoteSessionId ?? session.acpSessionId ?? session.localSessionId}\n`);
   process.stdout.write(`${cliText("Local ID: ", "本地 ID：")}${session.localSessionId}\n`);
   process.stdout.write(`${cliText("Context: ", "上下文：")}${session.contextKey}\n`);
@@ -1201,26 +1236,6 @@ function initializationStatusLabel(status: InitializationStatus): string {
   return cliText("already exists; unchanged", "已存在，未修改");
 }
 
-function taskStateLabel(status: string | undefined): string {
-  if (!status) return "-";
-  const chinese: Record<string, string> = {
-    starting: "启动中",
-    ready: "就绪",
-    running: "运行中",
-    closed: "已关闭",
-    failed: "失败",
-    completed: "已完成",
-    cancelled: "已取消",
-    interrupted: "已中断",
-    inProgress: "进行中",
-    active: "活动中",
-    idle: "空闲",
-    not_loaded: "未加载",
-    error: "错误",
-  };
-  return cliLanguage === "zh" ? chinese[status] ?? status : status;
-}
-
 function ensureOk(response: ControlResponse): void {
   if (response.ok) return;
   const message = response.message?.trim();

package/src/codex/CodexProcessManager.ts

@@ -5,12 +5,17 @@ import readline from "node:readline";
 import type { Logger } from "pino";
 import { AppServerConnection } from "./AppServerConnection.js";
 import type { AppServerClient, AppServerClientProvider } from "./CodexRuntime.js";
-import { agentBotEnvironment } from "../runtime/agentEnvironment.js";
+import {
+  agentBotEnvironment,
+  type AgentEnvironmentContext,
+} from "../runtime/agentEnvironment.js";
+import type { AgentProcessInfo } from "../runtime/types.js";
 import { spawnStdioCommand } from "../utils/spawnCommand.js";
 
 export class CodexProcessManager implements AppServerClientProvider {
   private client?: AppServerConnection;
   private child?: ChildProcessWithoutNullStreams;
+  private version?: string;
   private readonly disconnectListeners = new Set<(error: Error) => void>();
 
   constructor(
@@ -18,11 +23,17 @@ export class CodexProcessManager implements AppServerClientProvider {
     private readonly args: string[],
     private readonly env: Record<string, string>,
     private readonly logger: Logger,
+    private readonly environmentContext: () => AgentEnvironmentContext = () => ({}),
   ) {}
 
   async getClient(): Promise<AppServerClient> {
     if (this.client) return this.client;
-    const child = spawnStdioCommand(this.command, this.args, agentBotEnvironment(process.env, this.env));
+    this.version = undefined;
+    const child = spawnStdioCommand(
+      this.command,
+      this.args,
+      agentBotEnvironment(process.env, this.env, this.environmentContext()),
+    );
     this.child = child;
     const client = new AppServerConnection(child, this.logger.child({ component: "codex-app-server" }));
     this.client = client;
@@ -38,14 +49,24 @@ export class CodexProcessManager implements AppServerClientProvider {
       const error = new Error(`App Server exited (code=${code ?? "null"}, signal=${signal ?? "null"}).`);
       for (const listener of this.disconnectListeners) listener(error);
     });
-    await client.request("initialize", {
+    const initializeResult = await client.request("initialize", {
       clientInfo: { name: "agent-bot", title: "Agent Bot", version: "0.1.0" },
       capabilities: { experimentalApi: true },
     });
+    this.version = initializedAgentVersion(initializeResult);
     client.notify("initialized", {});
     return client;
   }
 
+  getProcessInfo(): AgentProcessInfo {
+    const pid = this.child?.pid;
+    if (!pid) return {};
+    return {
+      pid,
+      ...(this.version ? { version: this.version } : {}),
+    };
+  }
+
   getCodexHome(): string {
     return this.env.CODEX_HOME ?? process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
   }
@@ -62,3 +83,17 @@ export class CodexProcessManager implements AppServerClientProvider {
     return () => this.disconnectListeners.delete(listener);
   }
 }
+
+function initializedAgentVersion(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const result = value as Record<string, unknown>;
+  const serverInfo = result.serverInfo && typeof result.serverInfo === "object"
+    ? result.serverInfo as Record<string, unknown>
+    : undefined;
+  for (const candidate of [serverInfo?.version, result.version, result.userAgent]) {
+    if (typeof candidate !== "string") continue;
+    const match = /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\b/u.exec(candidate);
+    if (match?.[1]) return match[1];
+  }
+  return undefined;
+}

package/src/codex/CodexRuntime.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "pino";
 import type {
   AgentRuntime,
+  AgentProcessInfo,
   ApprovalDecision,
   CreateRuntimeSessionInput,
   ForkRuntimeSessionInput,
@@ -55,6 +56,7 @@ export interface AppServerClient {
 
 export interface AppServerClientProvider {
   getClient(): Promise<AppServerClient>;
+  getProcessInfo?(): AgentProcessInfo;
   getCodexHome?(): string;
   onDisconnect?(listener: (error: Error) => void): () => void;
   close(): void;
@@ -100,6 +102,10 @@ export class CodexRuntime implements AgentRuntime {
     return this.sessions.get(localSessionId);
   }
 
+  getProcessInfo(): AgentProcessInfo {
+    return this.provider.getProcessInfo?.() ?? {};
+  }
+
   async createSession(input: CreateRuntimeSessionInput): Promise<RuntimeSession> {
     const client = await this.client();
     const response = await client.request<ThreadResponse>("thread/start", {

package/src/feishu/CardRenderer.ts

@@ -139,6 +139,18 @@ export interface TaskListCardAction {
   value: Record<string, string>;
 }
 
+export interface HelpCardCommand {
+  text: string;
+  action?: TaskListCardAction;
+  usage?: string;
+  description: string;
+}
+
+export interface HelpCardSection {
+  title: string;
+  commands: HelpCardCommand[];
+}
+
 export interface TaskListCardEntry {
   lines: string[];
   actions?: TaskListCardAction[];
@@ -794,6 +806,19 @@ export class CardRenderer {
     return sectionCard(title, elements);
   }
 
+  renderHelpCard(
+    title: string,
+    introLines: string[],
+    sections: HelpCardSection[],
+  ): Record<string, unknown> {
+    const elements: Record<string, unknown>[] = [markdown(introLines.join("\n"))];
+    for (const section of sections) {
+      elements.push({ tag: "hr" }, markdown(`**${section.title}**`));
+      elements.push(...section.commands.map(helpCommandRow));
+    }
+    return sectionCard(title, elements);
+  }
+
   renderTaskListCard(
     title: string,
     sectionTitle: string,
@@ -813,10 +838,12 @@ export class CardRenderer {
         if (index < entries.length - 1) elements.push({ tag: "hr" });
       });
     }
+    if (footerActions.length > 0) {
+      elements.push({ tag: "hr" }, taskActionRow(footerActions));
+    }
     if (footerLines.length > 0) {
       elements.push({ tag: "hr" }, markdown(footerLines.join("\n")));
     }
-    if (footerActions.length > 0) elements.push(taskActionRow(footerActions));
     return {
       schema: "2.0",
       config: {
@@ -1588,6 +1615,39 @@ function taskActionElement(action: TaskListCardAction): Record<string, unknown>
   };
 }
 
+function helpCommandRow(command: HelpCardCommand): Record<string, unknown> {
+  const details = [
+    command.usage ? `**${command.usage}**` : undefined,
+    command.description,
+  ].filter((line): line is string => Boolean(line)).join("　");
+  return {
+    tag: "column_set",
+    flex_mode: "none",
+    horizontal_spacing: "12px",
+    vertical_align: "top",
+    margin: "2px 0 0 0",
+    columns: [
+      {
+        tag: "column",
+        width: "auto",
+        vertical_align: "top",
+        elements: [
+          command.action
+            ? taskActionElement(command.action)
+            : markdown(`**${escapeCardHtml(command.text)}**`),
+        ],
+      },
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        vertical_align: "top",
+        elements: [markdown(details)],
+      },
+    ],
+  };
+}
+
 function turnCard(
   title: string,
   template: string,

package/src/feishu/FeishuConnector.ts

@@ -5,6 +5,7 @@ import { resolveFeishuBotOpenId } from "./FeishuBotIdentity.js";
 import type { ChatUpdatedEvent, FeishuEventHandler, IncomingMessage } from "./types.js";
 
 type BotOpenIdResolver = (appId: string, appSecret: string) => Promise<string>;
+type BotOpenIdListener = (botOpenId: string) => void;
 
 export class FeishuConnector {
   constructor(
@@ -12,6 +13,7 @@ export class FeishuConnector {
     private readonly handler: FeishuEventHandler,
     private readonly logger: Logger,
     private readonly botOpenIdResolver: BotOpenIdResolver = resolveFeishuBotOpenId,
+    private readonly onBotOpenId?: BotOpenIdListener,
   ) {}
 
   async start(): Promise<void> {
@@ -21,10 +23,17 @@ export class FeishuConnector {
     }
 
     const respondToAllGroupMessages = this.config.feishu.respondToAllGroupMessages !== false;
-    const botOpenId = respondToAllGroupMessages
-      ? undefined
-      : await this.botOpenIdResolver(appId, appSecret);
-    await this.startFeishuWs(appId, appSecret, botOpenId);
+    let botOpenId: string | undefined;
+    if (!respondToAllGroupMessages || this.onBotOpenId) {
+      try {
+        botOpenId = await this.botOpenIdResolver(appId, appSecret);
+        this.onBotOpenId?.(botOpenId);
+      } catch (error) {
+        if (!respondToAllGroupMessages) throw error;
+        this.logger.warn({ error }, "Failed to resolve the Lark bot Open ID for the Agent environment.");
+      }
+    }
+    await this.startFeishuWs(appId, appSecret, respondToAllGroupMessages ? undefined : botOpenId);
   }
 
   stop(): void {