@keyou007/agent-bot 0.1.0 → 0.1.2

package/src/cli/help.ts

@@ -0,0 +1,99 @@
+export type CliLanguage = "en" | "zh";
+
+export function resolveCliLanguage(
+  env: NodeJS.ProcessEnv = process.env,
+  systemLocale = Intl.DateTimeFormat().resolvedOptions().locale,
+): CliLanguage {
+  const configuredLocale = [
+    env.LC_ALL,
+    env.LC_MESSAGES,
+    env.LANGUAGE,
+    env.LANG,
+  ].find((value) => value?.trim());
+  return isChineseLocale(configuredLocale ?? systemLocale) ? "zh" : "en";
+}
+
+export function renderCliHelp(version: string, language = resolveCliLanguage()): string {
+  return language === "zh" ? renderChineseHelp(version) : renderEnglishHelp(version);
+}
+
+function renderChineseHelp(version: string): string {
+  return `Agent Bot ${version}
+通过飞书/Lark 使用本机 Codex 与 ACP Agent。
+
+用法：
+  agent-bot [选项] <命令>
+
+常用命令：
+  init                              初始化配置、数据目录和飞书应用
+  console                           打开本地 Console
+  server start                      在后台启动 Agent Bot
+  server status                     查看服务和安全重启状态
+  server restart                    安排安全重启
+  server stop                       停止 Agent Bot
+  task list                         列出任务
+  task status <task>                查看任务状态
+  task chat <task>                  查看任务绑定的飞书会话
+  task prompt <task> <prompt>       向指定任务发送 Prompt
+  task stop <task>                  停止指定任务
+  task title <task> <title>         修改任务标题
+  skills status                     查看内置 Skill 状态
+  skills install                    安装内置 Skill
+
+选项：
+  --config <path>                   使用指定配置文件
+  --json                            在支持的命令中输出 JSON
+  -h, --help                        显示帮助
+  -v, --version                     显示版本
+
+示例：
+  agent-bot init
+  agent-bot server start
+  agent-bot server status
+  agent-bot task list
+  agent-bot server restart --reason "升级 Agent Bot"
+`;
+}
+
+function renderEnglishHelp(version: string): string {
+  return `Agent Bot ${version}
+Use local Codex and ACP agents from Lark/Feishu.
+
+Usage:
+  agent-bot [options] <command>
+
+Common commands:
+  init                              Initialize config, data directories, and the Lark app
+  console                           Open the local console
+  server start                      Start Agent Bot in the background
+  server status                     Show server and safe-restart status
+  server restart                    Schedule a safe restart
+  server stop                       Stop Agent Bot
+  task list                         List tasks
+  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
+  task stop <task>                  Stop a task
+  task title <task> <title>         Rename a task
+  skills status                     Show the built-in Skill status
+  skills install                    Install the built-in Skill
+
+Options:
+  --config <path>                   Use a specific config file
+  --json                            Print JSON when supported
+  -h, --help                        Show help
+  -v, --version                     Show version
+
+Examples:
+  agent-bot init
+  agent-bot server start
+  agent-bot server status
+  agent-bot task list
+  agent-bot server restart --reason "Update Agent Bot"
+`;
+}
+
+function isChineseLocale(value: string): boolean {
+  const locale = value.trim().split(":")[0]?.split(/[.@]/)[0]?.replaceAll("_", "-").toLowerCase();
+  return locale === "zh" || Boolean(locale?.startsWith("zh-"));
+}

package/src/cli/packageVersion.ts

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function readPackageVersion(
+  packageJsonUrl = new URL("../../package.json", import.meta.url),
+): string {
+  const metadata = JSON.parse(
+    fs.readFileSync(fileURLToPath(packageJsonUrl), "utf8"),
+  ) as { version?: unknown };
+  if (typeof metadata.version !== "string" || !metadata.version.trim()) {
+    throw new Error("package.json 中缺少有效的 version。");
+  }
+  return metadata.version;
+}

package/src/cli.ts

@@ -3,15 +3,18 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import qrcode from "qrcode-terminal";
 import { loadConfig } from "./config/loadConfig.js";
-import { sendControlRequest, isServerRunning } from "./cli/LocalControlClient.js";
+import { sendControlRequest, isServerReachable, isServerRunning } from "./cli/LocalControlClient.js";
 import {
   controlEndpoint,
   type ControlResponse,
   type TaskStatusControlData,
 } from "./cli/controlProtocol.js";
 import {
+  acquireInitializationLock,
+  cleanupFeishuCredentialTemporaryFiles,
   initializeAgentBot,
   readFeishuCredentials,
+  shouldCreateFeishuApp,
   writeFeishuCredentials,
   type InitializationResult,
   type InitializationStatus,
@@ -26,7 +29,10 @@ import {
   type EnsureFeishuAppConfigurationResult,
   type FeishuConfigurationChallenge,
 } from "./cli/FeishuAppConfiguration.js";
+import { renderCliHelp } from "./cli/help.js";
+import { requireServerFeishuTransport } from "./feishu/transport.js";
 import { resolveSystemSkillsRoot, SkillRegistry, type SkillRegistrationStatus } from "./cli/SkillRegistry.js";
+import { readPackageVersion } from "./cli/packageVersion.js";
 import { taskChatRoute } from "./cli/taskChatRoute.js";
 import { StateStore, type SessionRecord } from "./state/StateStore.js";
 
@@ -45,6 +51,10 @@ async function main(input: string[]): Promise<void> {
     printHelp();
     return;
   }
+  if (command === "--version" || command === "-v") {
+    process.stdout.write(`${readPackageVersion()}\n`);
+    return;
+  }
   if (command === "init") {
     await initCommand(rest, parsed.configPath);
     return;
@@ -91,57 +101,73 @@ async function initCommand(input: string[], configPath?: string): Promise<void>
 
   const paths = initializeAgentBot({ configPath });
   if (!json) printInitializationPaths(paths);
+  const initializationLock = acquireInitializationLock(paths.home.path);
 
+  try {
+    cleanupFeishuCredentialTemporaryFiles(paths.env.path);
+    const feishu = await initializeFeishu(
+      paths,
+      { json, skipFeishu, reconfigureFeishu },
+    );
+    const result: InitCommandResult = { ...paths, feishu };
+    if (json) printJson(result);
+    else printInitializationResult(result);
+  } finally {
+    initializationLock.release();
+  }
+}
+
+async function initializeFeishu(
+  paths: InitializationResult,
+  options: { json: boolean; skipFeishu: boolean; reconfigureFeishu: boolean },
+): Promise<InitCommandResult["feishu"]> {
   const existing = readFeishuCredentials(paths.env.path);
-  let feishu: InitCommandResult["feishu"];
-  if (skipFeishu) {
-    feishu = {
+  if (options.skipFeishu) {
+    return {
       status: "skipped",
       ...(existing.appId ? { appId: existing.appId } : {}),
     };
-  } else {
-    const controller = new AbortController();
-    const onInterrupt = (): void => controller.abort(new Error("已取消初始化。"));
-    process.once("SIGINT", onInterrupt);
-    try {
-      let credentials: FeishuAppCredentials;
-      let status: Exclude<FeishuInitializationStatus, "skipped">;
-      if (existing.status === "configured" && !reconfigureFeishu) {
-        credentials = {
-          appId: existing.appId!,
-          appSecret: existing.appSecret!,
-        };
-        status = "existing";
-      } else {
-        if (existing.status === "incomplete" && !reconfigureFeishu) {
-          throw new Error(`检测到不完整的飞书凭证：请补全 ${paths.env.path}，或使用 --reconfigure-feishu 重新创建应用。`);
-        }
-        credentials = await registerFeishuApp({
-          signal: controller.signal,
-          onVerification: (challenge) => printFeishuVerification(challenge, json),
-        });
-        writeFeishuCredentials(paths.env.path, credentials);
-        status = "created";
-      }
+  }
 
-      if (!json) process.stdout.write("\n正在检查飞书应用权限、事件和回调配置...\n");
-      const configuration = await ensureFeishuAppConfiguration(credentials, {
+  const controller = new AbortController();
+  const onInterrupt = (): void => controller.abort(new Error("已取消初始化。"));
+  process.once("SIGINT", onInterrupt);
+  process.once("SIGTERM", onInterrupt);
+  try {
+    let credentials: FeishuAppCredentials;
+    let status: Exclude<FeishuInitializationStatus, "skipped">;
+    if (!shouldCreateFeishuApp(existing, options.reconfigureFeishu)) {
+      credentials = {
+        appId: existing.appId!,
+        appSecret: existing.appSecret!,
+      };
+      status = "existing";
+    } else {
+      if (existing.status === "incomplete" && !options.json) {
+        process.stdout.write("\n检测到未完整保存的飞书凭据，将重新创建机器人。\n");
+      }
+      credentials = await registerFeishuApp({
         signal: controller.signal,
-        onVerification: (challenge) => printFeishuConfigurationVerification(challenge, json),
+        onVerification: (challenge) => printFeishuVerification(challenge, options.json),
       });
-      feishu = {
-        status,
-        appId: credentials.appId,
-        configuration,
-      };
-    } finally {
-      process.removeListener("SIGINT", onInterrupt);
+      writeFeishuCredentials(paths.env.path, credentials);
+      status = "created";
     }
-  }
 
-  const result: InitCommandResult = { ...paths, feishu };
-  if (json) printJson(result);
-  else printInitializationResult(result);
+    if (!options.json) process.stdout.write("\n正在检查飞书应用权限、事件和回调配置...\n");
+    const configuration = await ensureFeishuAppConfiguration(credentials, {
+      signal: controller.signal,
+      onVerification: (challenge) => printFeishuConfigurationVerification(challenge, options.json),
+    });
+    return {
+      status,
+      appId: credentials.appId,
+      configuration,
+    };
+  } finally {
+    process.removeListener("SIGINT", onInterrupt);
+    process.removeListener("SIGTERM", onInterrupt);
+  }
 }
 
 function skillsCommand(input: string[]): void {
@@ -190,7 +216,7 @@ async function consoleCommand(input: string[]): Promise<void> {
   const config = loadConfig();
   const endpoint = controlEndpoint(config.storage.sqlitePath);
   const force = input.includes("--force");
-  if (!force && await isServerRunning(endpoint)) {
+  if (!force && await isServerReachable(endpoint)) {
     throw new Error("agent-bot server 正在运行。为避免争用同一任务状态，请先停止 server，或明确使用 --force。");
   }
   const entry = fileURLToPath(new URL("./index.js", import.meta.url));
@@ -221,10 +247,17 @@ async function serverCommand(input: string[]): Promise<void> {
     return;
   }
   if (action === "start") {
+    requireServerFeishuTransport(config.feishu);
     if (await isServerRunning(endpoint)) {
       process.stdout.write("agent-bot server 已在运行。\n");
       return;
     }
+    if (await isServerReachable(endpoint)) {
+      const running = await waitForServer(endpoint, 45_000);
+      if (!running) throw new Error("agent-bot server 已启动，但未能连接飞书机器人。请检查日志。");
+      process.stdout.write("agent-bot server 已启动。\n");
+      return;
+    }
     const entry = fileURLToPath(new URL("./supervisor.js", import.meta.url));
     const child = spawn(process.execPath, [entry], {
       cwd: process.cwd(),
@@ -234,8 +267,8 @@ async function serverCommand(input: string[]): Promise<void> {
       env: { ...process.env, AGENT_BOT_RESTART_REASON: "通过 agent-bot CLI 启动" },
     });
     child.unref();
-    const running = await waitForServer(endpoint, 30_000);
-    if (!running) throw new Error("已启动 Supervisor，但 server 未在 30 秒内就绪。请检查日志。");
+    const running = await waitForServer(endpoint, 45_000);
+    if (!running) throw new Error("已启动 Supervisor，但 server 未在 45 秒内连接飞书机器人。请检查日志。");
     process.stdout.write("agent-bot server 已启动。\n");
     return;
   }
@@ -416,7 +449,11 @@ function printServerStatus(data: unknown): void {
   const activity = value.activity && typeof value.activity === "object"
     ? value.activity as Record<string, unknown>
     : {};
-  process.stdout.write("agent-bot server：运行中\n");
+  process.stdout.write(
+    value.ready === false
+      ? "agent-bot server：启动中（正在连接飞书机器人）\n"
+      : "agent-bot server：运行中\n",
+  );
   process.stdout.write(`PID：${value.pid ?? "-"}\n`);
   process.stdout.write(`启动时间：${value.startedAt ?? "-"}\n`);
   process.stdout.write(`Supervisor：${value.supervised ? "已启用" : "未启用"}\n`);
@@ -594,37 +631,5 @@ function printJson(value: unknown): void {
 }
 
 function printHelp(): void {
-  process.stdout.write(`Agent Bot 命令行工具
-
-用法：
-  agent-bot [--config <path>] init [--json] [--skip-feishu | --reconfigure-feishu]
-  agent-bot [--config <path>] console [--force]
-  agent-bot [--config <path>] server status [--json]
-  agent-bot [--config <path>] server start
-  agent-bot [--config <path>] server stop
-  agent-bot [--config <path>] server restart [--safe | --immediate] [--reason <text>]
-  agent-bot [--config <path>] task list [--context <key>] [--status <status>] [--json]
-  agent-bot [--config <path>] task chat <序号|任务ID> [--json]
-  agent-bot [--config <path>] task status <序号|任务ID> [--json]
-  agent-bot [--config <path>] task stop <序号|任务ID>
-  agent-bot [--config <path>] task title <序号|任务ID> <新标题>
-  agent-bot [--config <path>] task prompt <序号|任务ID> <prompt>
-  agent-bot skills status [--json] [--target <skills目录>]
-  agent-bot skills install|register [--json] [--target <skills目录>]
-  agent-bot skills uninstall|unregister [--json] [--target <skills目录>]
-  agent-bot skills path [--json] [--target <skills目录>]
-
-说明：
-  默认用户目录是 ~/.agent-bot；配置为 ~/.agent-bot/config.yaml，环境变量为 ~/.agent-bot/.env。
-  可用 AGENT_BOT_HOME 修改用户目录，或用 --config 指向某个配置文件。
-  init 创建用户目录和运行文件；创建或读取飞书凭证后会审计并补齐已发布的权限、事件和回调。
-  仅核心消息能力缺失会阻塞初始化；非核心配置缺失只提醒受影响功能。
-  --skip-feishu 跳过飞书创建及配置审计并保留 Console 模式；--reconfigure-feishu 明确替换已有飞书凭证。
-  server restart 默认执行安全重启；等待全部任务完成、结果投递完成且连续 15 秒无新消息。
-  --immediate（或 --force）跳过空闲等待并立即重启 worker。
-  task 序号来自 task list 当前排序；任务管理操作通过运行中 server 执行。
-  task chat 从本地任务路由中读取飞书会话 ID；话题任务使用 --json 可同时查看 threadId。
-  task prompt 不切换任务；机器人先在原会话显示 Prompt，再提交任务，响应继续发送到该会话。
-  skills 默认注册到系统通用 ~/.agents/skills 目录；AGENT_BOT_SKILLS_DIR 可修改默认目录。
-`);
+  process.stdout.write(renderCliHelp(readPackageVersion()));
 }

package/src/config/loadConfig.ts

@@ -7,10 +7,8 @@ import { defaultConfigPath, defaultDotEnvPath, resolveUserPath } from "./paths.j
 
 const ENV_PATTERN = /\$\{([A-Z0-9_]+)\}/gi;
 const DEFAULT_CONFIG = `feishu:
-  transport: "auto"
   appId: "\${FEISHU_APP_ID}"
   appSecret: "\${FEISHU_APP_SECRET}"
-  useConsoleWhenMissingCredentials: true
 
 console:
   enabled: true

package/src/config/schema.ts

@@ -21,7 +21,7 @@ export const appConfigSchema = z.object({
     transport: z.enum(["auto", "sdk", "console"]).default("auto"),
     appId: z.string().optional(),
     appSecret: z.string().optional(),
-    useConsoleWhenMissingCredentials: z.boolean().default(true),
+    useConsoleWhenMissingCredentials: z.boolean().default(false),
   }),
   agents: z.record(z.string().min(1), agentConfigSchema).refine(
     (agents) => Object.keys(agents).length > 0,

package/src/feishu/FeishuConnector.ts

@@ -3,11 +3,18 @@ import type { AppConfig } from "../config/schema.js";
 import { threadContextKey } from "./contextKey.js";
 import type { ChatUpdatedEvent, FeishuEventHandler, IncomingMessage } from "./types.js";
 
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+
+interface FeishuConnectorOptions {
+  connectTimeoutMs?: number;
+}
+
 export class FeishuConnector {
   constructor(
     private readonly config: AppConfig,
     private readonly handler: FeishuEventHandler,
     private readonly logger: Logger,
+    private readonly options: FeishuConnectorOptions = {},
   ) {}
 
   async start(): Promise<void> {
@@ -25,7 +32,6 @@ export class FeishuConnector {
 
   private async startFeishuWs(appId: string, appSecret: string): Promise<void> {
     const lark = (await import("@larksuiteoapi/node-sdk")) as Record<string, any>;
-    const wsClient = new lark.WSClient({ appId, appSecret });
     const eventDispatcher = new lark.EventDispatcher({}).register({
       "im.message.receive_v1": async (data: unknown) => {
         const message = toIncomingMessage(data);
@@ -77,21 +83,94 @@ export class FeishuConnector {
         };
       },
     });
+    const connected = createConnectionWaiter(this.logger, this.options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
+    try {
+      const wsClient = new lark.WSClient({
+        appId,
+        appSecret,
+        logger: connected.sdkLogger,
+        loggerLevel: lark.LoggerLevel.debug,
+      });
+      await wsClient.start({ eventDispatcher });
+      await connected.promise;
+      this.logger.info("Feishu WebSocket connector connected.");
+    } finally {
+      connected.dispose();
+    }
+  }
+}
 
-    wsClient.start({ eventDispatcher });
-    this.logger.info("Feishu WebSocket connector started.");
+function createConnectionWaiter(
+  logger: Logger,
+  timeoutMs: number,
+): {
+  promise: Promise<void>;
+  sdkLogger: {
+    error: (...messages: unknown[]) => void;
+    warn: (...messages: unknown[]) => void;
+    info: (...messages: unknown[]) => void;
+    debug: (...messages: unknown[]) => void;
+    trace: (...messages: unknown[]) => void;
+  };
+  dispose: () => void;
+} {
+  let resolveConnected!: () => void;
+  let rejectConnected!: (error: Error) => void;
+  let lastError: string | undefined;
+  let settled = false;
+  const promise = new Promise<void>((resolve, reject) => {
+    resolveConnected = resolve;
+    rejectConnected = reject;
+  });
+  const timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    const detail = lastError ? ` Last SDK error: ${lastError}` : "";
+    rejectConnected(new Error(`Timed out after ${timeoutMs}ms waiting for the Feishu WebSocket connection.${detail}`));
+  }, timeoutMs);
+  const logValues = (messages: unknown[]): string => messages.map(formatSdkLogValue).join(" ");
+  const sdkLogger = {
+    error: (...messages: unknown[]) => {
+      lastError = logValues(messages);
+      logger.error({ component: "feishu-websocket", sdkMessage: lastError }, "Feishu SDK error.");
+    },
+    warn: (...messages: unknown[]) => {
+      logger.warn({ component: "feishu-websocket", sdkMessage: logValues(messages) }, "Feishu SDK warning.");
+    },
+    info: (...messages: unknown[]) => {
+      logger.debug({ component: "feishu-websocket", sdkMessage: logValues(messages) }, "Feishu SDK status.");
+    },
+    debug: (...messages: unknown[]) => {
+      if (!messages.some((message) => message === "ws connect success")) return;
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveConnected();
+    },
+    trace: () => undefined,
+  };
+  return {
+    promise,
+    sdkLogger,
+    dispose: () => clearTimeout(timer),
+  };
+}
+
+function formatSdkLogValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
   }
 }
 
 function toChatUpdatedEvent(data: unknown): ChatUpdatedEvent | undefined {
   const event = getFeishuEvent(data);
   const chatId = typeof event?.chat_id === "string" ? event.chat_id : undefined;
-  const beforeName = typeof event?.before_change?.name === "string"
-    ? event.before_change.name
-    : undefined;
-  const afterName = typeof event?.after_change?.name === "string"
-    ? event.after_change.name
-    : undefined;
+  const beforeName = typeof event?.before_change?.name === "string" ? event.before_change.name : undefined;
+  const afterName = typeof event?.after_change?.name === "string" ? event.after_change.name : undefined;
   if (!chatId || !afterName || beforeName === afterName) return undefined;
   return {
     chatId,
@@ -118,9 +197,7 @@ function toIncomingMessage(data: unknown): IncomingMessage | undefined {
   const parentMessageId = typeof message.parent_id === "string" && message.parent_id ? message.parent_id : undefined;
   const threadContext = Boolean(chatId && threadId);
   const senderId =
-    event.sender?.sender_id?.open_id ??
-    event.sender?.sender_id?.user_id ??
-    event.sender?.sender_id?.union_id;
+    event.sender?.sender_id?.open_id ?? event.sender?.sender_id?.user_id ?? event.sender?.sender_id?.union_id;
 
   if (!chatId && !senderId) {
     return undefined;

package/src/feishu/transport.ts

@@ -1,24 +1,15 @@
 import type { AppConfig } from "../config/schema.js";
 
-export type FeishuTransportMode = "sdk" | "console";
-
 type FeishuTransportConfig = Pick<
   AppConfig["feishu"],
-  "transport" | "appId" | "appSecret" | "useConsoleWhenMissingCredentials"
+  "appId" | "appSecret"
 >;
 
-export function resolveFeishuTransport(config: FeishuTransportConfig): FeishuTransportMode {
-  if (config.transport === "console") {
-    return "console";
-  }
-
-  const hasCredentials = Boolean(config.appId && config.appSecret);
-  if (config.transport === "sdk" || !config.useConsoleWhenMissingCredentials) {
-    if (!hasCredentials) {
-      throw new Error("Feishu appId/appSecret are required.");
-    }
-    return "sdk";
+export function requireServerFeishuTransport(config: FeishuTransportConfig): "sdk" {
+  if (!config.appId || !config.appSecret) {
+    throw new Error(
+      "飞书机器人尚未配置。请先运行 agent-bot init 完成初始化；仅需本地调试时请使用 agent-bot console。",
+    );
   }
-
-  return hasCredentials ? "sdk" : "console";
+  return "sdk";
 }

package/src/index.ts

@@ -15,7 +15,7 @@ import { ConsoleFeishuClient } from "./feishu/ConsoleFeishuClient.js";
 import { FeishuConnector } from "./feishu/FeishuConnector.js";
 import { FeishuMessageClient } from "./feishu/FeishuMessageClient.js";
 import { FeishuTurnPresenter } from "./feishu/FeishuTurnPresenter.js";
-import { resolveFeishuTransport } from "./feishu/transport.js";
+import { requireServerFeishuTransport } from "./feishu/transport.js";
 import { createLogger } from "./logging/logger.js";
 import { OutboundRouter, type OutboundRoute } from "./presentation/OutboundRouter.js";
 import { ProxySessionController } from "./proxy/ProxySessionController.js";
@@ -36,6 +36,7 @@ const startupReason = process.env.AGENT_BOT_RESTART_REASON?.trim()
   || (supervised ? "Supervisor 启动" : "直接启动");
 const consoleOnly = process.env.AGENT_BOT_CONSOLE_ONLY === "1";
 const config = loadConfig();
+const transport = consoleOnly ? "console" : requireServerFeishuTransport(config.feishu);
 const logger = createLogger(config);
 const store = new StateStore(config.storage.sqlitePath);
 
@@ -52,13 +53,13 @@ const codexProcessManager = new CodexProcessManager(
 const codexRuntime = new CodexRuntime(codexProcessManager, logger);
 const runtimes = new AgentRuntimeRegistry({ acp: acpRuntime, codex: codexRuntime });
 
-const transport = consoleOnly ? "console" : resolveFeishuTransport(config.feishu);
 const routes: OutboundRoute[] = [];
 let feishuConnector: FeishuConnector | undefined;
 let consoleConnector: ConsoleConnector | undefined;
 let startupNotifier: StartupNotifier | undefined;
 let safeRestartNotifier: SafeRestartNotifier | undefined;
 let controlServer: LocalControlServer | undefined;
+let serverReady = false;
 
 const feishuOutbound = transport === "sdk" ? new FeishuMessageClient(config, logger) : undefined;
 if (feishuOutbound) {
@@ -123,10 +124,18 @@ const startControlServer = async (): Promise<void> => {
 };
 
 if (feishuConnector && startupNotifier) {
-  await startFeishu(feishuConnector, startupNotifier, processStartedAt, startupReason, startControlServer);
+  await startFeishu(
+    feishuConnector,
+    startupNotifier,
+    processStartedAt,
+    startupReason,
+    startControlServer,
+    () => { serverReady = true; },
+  );
 } else {
   await startControlServer();
   await feishuConnector?.start();
+  serverReady = true;
 }
 consoleConnector?.start();
 
@@ -156,6 +165,8 @@ async function handleControlRequest(request: ControlRequest): Promise<ControlRes
       return {
         ok: true,
         data: {
+          ready: serverReady,
+          phase: serverReady ? "ready" : "connecting_feishu",
           pid: process.pid,
           startedAt: processStartedAt.toISOString(),
           supervised,

package/src/startup/startFeishu.ts

@@ -12,8 +12,10 @@ export async function startFeishu(
   startedAt: Date,
   restartReason: string,
   prepare?: () => Promise<void>,
+  onConnected?: () => void,
 ): Promise<void> {
   await prepare?.();
   await connector.start();
+  onConnected?.();
   await notifier.notify(startedAt, restartReason);
 }

package/src/supervisor.ts

@@ -1,8 +1,9 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { isServerRunning } from "./cli/LocalControlClient.js";
+import { isServerReachable } from "./cli/LocalControlClient.js";
 import { controlEndpoint } from "./cli/controlProtocol.js";
 import { loadConfig } from "./config/loadConfig.js";
+import { requireServerFeishuTransport } from "./feishu/transport.js";
 import {
   crashRestartDelayMs,
   describeRestartReason,
@@ -13,7 +14,9 @@ import {
 } from "./supervision/restartPolicy.js";
 
 const childEntry = fileURLToPath(new URL("./index.js", import.meta.url));
-const sqlitePath = loadConfig().storage.sqlitePath;
+const config = loadConfig();
+requireServerFeishuTransport(config.feishu);
+const sqlitePath = config.storage.sqlitePath;
 const serverEndpoint = controlEndpoint(sqlitePath);
 let child: ChildProcess | undefined;
 let restartTimer: NodeJS.Timeout | undefined;
@@ -23,7 +26,7 @@ let nextStartReason = process.env.AGENT_BOT_RESTART_REASON?.trim() || "Superviso
 
 async function startChild(): Promise<void> {
   if (stopping || child) return;
-  if (await isServerRunning(serverEndpoint)) {
+  if (await isServerReachable(serverEndpoint)) {
     writeSupervisorLog("existing_server_detected", { endpoint: serverEndpoint });
     process.exit(0);
     return;
@@ -64,7 +67,7 @@ async function handleChildExit(
     process.exit(0);
     return;
   }
-  if (await isServerRunning(serverEndpoint)) {
+  if (await isServerReachable(serverEndpoint)) {
     writeSupervisorLog("duplicate_supervisor_stopped", { endpoint: serverEndpoint });
     process.exit(0);
     return;