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

package/src/cli.ts

@@ -56,6 +56,13 @@ import {
 import { formatServerStatus, withConfiguredFeishuAppId } from "./cli/serverStatus.js";
 import { resolveSystemSkillsRoot, SkillRegistry, type SkillRegistrationStatus } from "./cli/SkillRegistry.js";
 import { readPackageVersion } from "./cli/packageVersion.js";
+import {
+  readInitializationReceipt,
+  resolveInitializationWelcomeKind,
+  sendInitializationWelcome,
+  writeInitializationReceipt,
+  type InitializationWelcomeResult,
+} from "./cli/InitializationWelcome.js";
 import { applyExplicitProfile, parseGlobalOptions } from "./cli/profile.js";
 import { printVerificationQrAndLink } from "./cli/VerificationOutput.js";
 import {
@@ -65,6 +72,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 {
@@ -141,6 +154,7 @@ interface InitCommandResult extends InitializationResult {
     configuration?: EnsureFeishuAppConfigurationResult;
   };
   server: InitializationServerResult;
+  welcome: InitializationWelcomeResult;
 }
 
 interface InitializedAgent extends SupportedAgentInspection {
@@ -156,11 +170,13 @@ async function initCommand(
   explicitProfile: boolean,
 ): Promise<void> {
   const options = parseInitCommandOptions(input, explicitProfile);
+  const version = readPackageVersion();
+  const previousInitialization = readInitializationReceipt(agentBotHome());
   let initializationLock = options.reset
     ? acquireInitializationLock(agentBotHome())
     : undefined;
   let paths: InitializationResult;
-  let initialized: Omit<InitCommandResult, "server">;
+  let initialized: Omit<InitCommandResult, "server" | "welcome">;
   try {
     if (options.reset) await assertResetProfileServerStopped(configPath);
     paths = initializeAgentBot({ configPath, reset: options.reset });
@@ -183,9 +199,46 @@ async function initCommand(
     process.stdout.write(cliText("\nStarting Agent Bot server...\n", "\n正在启动 Agent Bot 服务...\n"));
   }
   const server = await startInitializedServer({ skipFeishu: options.skipFeishu, configPath });
-  const result: InitCommandResult = { ...initialized, server };
+  const welcomeKind = resolveInitializationWelcomeKind({
+    firstInitialization: paths.config.status === "created",
+    previousVersion: previousInitialization?.version,
+    currentVersion: version,
+  });
+  let welcome: InitializationWelcomeResult;
+  if (options.skipFeishu) {
+    welcome = { status: "skipped", kind: welcomeKind, reason: "feishu-skipped" };
+  } else {
+    try {
+      welcome = await sendInitializationWelcome({
+        configPath,
+        language: cliLanguage,
+        version,
+        previousVersion: previousInitialization?.version,
+        kind: welcomeKind,
+        activationPending: server.status === "restart-scheduled",
+      });
+    } catch (error) {
+      welcome = {
+        status: "failed",
+        kind: welcomeKind,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+  try {
+    writeInitializationReceipt(paths.home.path, version);
+  } catch (error) {
+    process.stderr.write(`${cliText(
+      "Warning: Could not save initialization version metadata: ",
+      "警告：无法保存初始化版本信息：",
+    )}${error instanceof Error ? error.message : String(error)}\n`);
+  }
+  const result: InitCommandResult = { ...initialized, server, welcome };
   if (options.json) printJson(result);
-  else printInitializationServerResult(server);
+  else {
+    printInitializationServerResult(server);
+    printInitializationWelcomeResult(welcome);
+  }
 }
 
 async function initializeSupportedAgents(json: boolean): Promise<InitializedAgent[]> {
@@ -724,6 +777,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 +872,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 +904,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 +985,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`);
@@ -967,7 +1049,7 @@ function printInitializationPaths(result: InitializationResult): void {
   process.stdout.write(`${cliText("Log directory: ", "日志目录：")}${result.logs.path} (${initializationStatusLabel(result.logs.status)})\n`);
 }
 
-function printInitializationResult(result: Omit<InitCommandResult, "server">): void {
+function printInitializationResult(result: Omit<InitCommandResult, "server" | "welcome">): void {
   process.stdout.write(cliText(
     "\nAgent Bot initialization completed.\n",
     "\nAgent Bot 初始化完成。\n",
@@ -1044,6 +1126,29 @@ function printInitializationServerResult(result: InitCommandResult["server"]): v
   printServerStartResult(result);
 }
 
+function printInitializationWelcomeResult(result: InitializationWelcomeResult): void {
+  if (result.status === "sent") {
+    process.stdout.write(cliText(
+      "Welcome card: sent to your Lark private chat.\n",
+      "欢迎卡片：已发送到你的飞书私聊。\n",
+    ));
+    return;
+  }
+  if (result.status === "failed") {
+    process.stderr.write(cliText(
+      `Warning: The private welcome card could not be sent: ${result.message}\n`,
+      `警告：无法发送私聊欢迎卡片：${result.message}\n`,
+    ));
+    return;
+  }
+  if (result.reason === "missing-user-open-id") {
+    process.stderr.write(cliText(
+      "Warning: The private welcome card was skipped because FEISHU_USER_OPEN_ID is not available. Send the bot a private message, then run agentbot init again.\n",
+      "警告：尚未获得 FEISHU_USER_OPEN_ID，无法发送私聊欢迎卡片。请先私聊机器人，再次运行 agentbot init。\n",
+    ));
+  }
+}
+
 function printServerStartResult(result: ServerStartResult): void {
   process.stdout.write(
     result.status === "already-running"
@@ -1201,26 +1306,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

@@ -35,6 +35,27 @@ export interface StartupStatusView {
   };
 }
 
+export type InitializationWelcomeKind = "first" | "upgrade" | "refresh";
+
+export interface InitializationWelcomeFeature {
+  icon: string;
+  title: string;
+  description: string;
+}
+
+export interface InitializationWelcomeView {
+  kind: InitializationWelcomeKind;
+  language: "en" | "zh";
+  version: string;
+  previousVersion?: string;
+  activationPending?: boolean;
+  defaultAgentName: string;
+  defaultAgentTitle: string;
+  availableAgents: string[];
+  logoPath: string;
+  features: InitializationWelcomeFeature[];
+}
+
 export interface SafeRestartStatusView {
   scheduleId: number;
   reason: string;
@@ -139,6 +160,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[];
@@ -667,6 +700,128 @@ export class CardRenderer {
     return sectionCard("Agent Bot 已启动", [markdown(lines.join("\n"))], "green");
   }
 
+  renderInitializationWelcome(view: InitializationWelcomeView): Record<string, unknown> {
+    const chinese = view.language === "zh";
+    const title = view.kind === "first"
+      ? (chinese ? "欢迎使用 Agent Bot" : "Welcome to Agent Bot")
+      : view.kind === "upgrade"
+        ? (chinese ? "Agent Bot 已更新" : "Agent Bot is updated")
+        : (chinese ? "Agent Bot 已准备就绪" : "Agent Bot is ready");
+    const subtitle = view.activationPending
+      ? (chinese ? "配置已完成，安全重启后生效" : "Configured and pending a safe restart")
+      : view.kind === "first"
+      ? (chinese ? "本地 Agent 已接入飞书" : "Your local Agents are now available in Lark")
+      : view.kind === "upgrade"
+        ? (chinese ? `新版本 ${view.version} 已生效` : `Version ${view.version} is now active`)
+        : (chinese ? "初始化配置已刷新" : "Initialization settings were refreshed");
+    const activationNote = view.activationPending
+      ? (chinese ? "当前任务完成并安全重启后生效。" : "It will take effect after active work finishes and the safe restart completes.")
+      : undefined;
+    const intro = view.kind === "first"
+      ? (chinese
+          ? "**初始化完成**\n从现在起，你可以直接在飞书里把任务交给本机 Agent，并随时查看进度、切换任务或创建分支。"
+          : "**Setup complete**\nYou can now work with local Agents from Lark, follow progress, switch tasks, and branch conversations.")
+      : view.kind === "upgrade"
+        ? (chinese
+            ? `**升级完成**\n${view.previousVersion ? `${inlineCode(view.previousVersion)} → ` : ""}${inlineCode(view.version)} 已准备好。${activationNote ?? "下面是本版值得关注的能力。"}`
+            : `**Upgrade complete**\n${view.previousVersion ? `${inlineCode(view.previousVersion)} → ` : ""}${inlineCode(view.version)} is ready. ${activationNote ?? "Here is what is new."}`)
+        : (chinese
+            ? `**配置刷新完成**\n${inlineCode(view.version)} 已重新检查配置、Agent 和飞书连接。${activationNote ?? ""}`
+            : `**Configuration refreshed**\n${inlineCode(view.version)} rechecked your configuration, Agents, and Lark connection. ${activationNote ?? ""}`);
+    const logo = {
+      ...localCardImage(view.logoPath, "Agent Bot logo"),
+      preview: false,
+    };
+    const featureColumns = view.features.slice(0, 4).map((feature) => ({
+      tag: "column",
+      width: "weighted",
+      weight: 1,
+      vertical_align: "top",
+      elements: [markdown([
+        `${feature.icon} **${feature.title}**`,
+        `<font color='grey'>${feature.description}</font>`,
+      ].join("\n"))],
+    }));
+    const featureRows = [0, 2].flatMap((start) => {
+      const columns = featureColumns.slice(start, start + 2);
+      return columns.length > 0
+        ? [{
+            tag: "column_set",
+            flex_mode: "none",
+            horizontal_spacing: "16px",
+            vertical_align: "top",
+            columns,
+          }]
+        : [];
+    });
+    const availableAgents = view.availableAgents.length > 0
+      ? view.availableAgents.map((agent) => inlineCode(agent)).join(" · ")
+      : inlineCode(view.defaultAgentName);
+    return {
+      schema: "2.0",
+      config: {
+        update_multi: true,
+        width_mode: "fill",
+      },
+      header: {
+        template: view.kind === "first" ? "turquoise" : view.kind === "upgrade" ? "blue" : "green",
+        title: { tag: "plain_text", content: title },
+        subtitle: { tag: "plain_text", content: subtitle },
+        padding: "12px 12px 12px 12px",
+      },
+      body: {
+        direction: "vertical",
+        vertical_spacing: "12px",
+        padding: "12px 12px 12px 12px",
+        elements: [
+          {
+            tag: "column_set",
+            flex_mode: "none",
+            horizontal_spacing: "16px",
+            vertical_align: "center",
+            columns: [
+              {
+                tag: "column",
+                width: "weighted",
+                weight: 1,
+                vertical_align: "center",
+                elements: [logo],
+              },
+              {
+                tag: "column",
+                width: "weighted",
+                weight: 3,
+                vertical_align: "center",
+                elements: [markdown(intro)],
+              },
+            ],
+          },
+          { tag: "hr" },
+          markdown(chinese
+            ? `**${view.kind === "upgrade" ? "本版亮点" : "你可以这样使用"}**`
+            : `**${view.kind === "upgrade" ? "What's new" : "What you can do"}**`),
+          ...featureRows,
+          { tag: "hr" },
+          markdown(chinese
+            ? "> 直接发送消息即可开始；发送 `/new` 创建新任务；发送 `/help` 查看全部命令。"
+            : "> Send a message to begin, `/new` for a new task, or `/help` for all commands."),
+          {
+            ...markdown(chinese
+              ? `**版本** ${inlineCode(view.version)}　·　**默认 Agent** ${inlineCode(view.defaultAgentTitle)}　·　**可用 Agent** ${availableAgents}`
+              : `**Version** ${inlineCode(view.version)}　·　**Default Agent** ${inlineCode(view.defaultAgentTitle)}　·　**Available** ${availableAgents}`),
+            text_size: "notation",
+          },
+          {
+            ...markdown(chinese
+              ? "📋 [查看更新日志](https://github.com/keyou/agent-bot/blob/master/CHANGELOG.md)"
+              : "📋 [View Changelog](https://github.com/keyou/agent-bot/blob/master/CHANGELOG.md)"),
+            text_size: "notation",
+          },
+        ],
+      },
+    };
+  }
+
   renderTurn(state: TurnViewState): Record<string, unknown> {
     const elements = renderTurnElements(state, "hidden");
     if (isTurnStoppable(state.status)) {
@@ -794,6 +949,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 +981,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 +1758,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 {