@keyou007/agent-bot 0.1.1 → 0.1.2

package/docs/technical-reference.zh.md

@@ -60,10 +60,12 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 - 进程环境变量优先于 `~/.agent-bot/.env`
 - `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须同时存在
 - 除非使用 `--reconfigure-feishu`，完整凭据不会被替换
-- 凭据只有一项时会直接报错，不会静默覆盖
-- 新创建的凭据以原子方式写入 `.env`
+- 缺少凭据或只有一项时会重新创建应用
+- 新创建的凭据经过 fsync、原子替换写入 `.env`，并在配置权限前读回校验
 
-缺少凭据时，初始化会启动飞书一键创建流程，并以文本和二维码显示验证链接。无论凭据是新创建还是已存在，之后都会检查应用当前已发布版本。
+初始化期间会持有 `~/.agent-bot/init.lock`，避免使用不同配置路径的并发命令重复创建应用。进程异常退出遗留的锁会在下次运行时恢复，凭据写入中断留下的临时文件也会被清理。
+
+没有完整凭据时，初始化会启动飞书一键创建流程，并以文本和二维码显示验证链接。注册中的设备码不会恢复：如果进程在完整凭据持久化前退出，下次会重新创建应用。凭据持久化后会检查应用当前已发布版本；这一权限审计阶段中断后可以安全继续。
 
 缺失配置分两阶段处理：
 
@@ -103,10 +105,8 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 ```yaml
 feishu:
-  transport: "auto"
   appId: "${FEISHU_APP_ID}"
   appSecret: "${FEISHU_APP_SECRET}"
-  useConsoleWhenMissingCredentials: true
 
 console:
   enabled: true
@@ -131,11 +131,7 @@ logging:
   path: "./logs/agent-bot.log"
 ```
 
-`feishu.transport` 支持：
-
-- `auto`：存在凭据时使用 SDK，否则按 `useConsoleWhenMissingCredentials` 决定是否回退 Console
-- `sdk`：要求飞书凭据并启动长连接客户端
-- `console`：禁用飞书传输
+`agent-bot server start` 要求同时配置飞书 `appId` 和 `appSecret`。命令会等待 SDK 的 WebSocket 长连接建立后才报告 Server 就绪；缺少凭据时启动失败并提示先初始化。`agent-bot console` 是明确的纯本地入口，不需要飞书凭据。
 
 必须至少配置一个 Agent，`defaults.agent` 必须指向已配置的 Agent。
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@keyou007/agent-bot",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "license": "GPL-3.0-only",
       "dependencies": {
         "@agentclientprotocol/sdk": "1.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Using Codex in Lark/Feishu feels just like using native Codex.",
   "license": "GPL-3.0-only",

package/skills/agent-bot/SKILL.md

@@ -50,7 +50,7 @@ Initialization creates the Agent Bot home, `config.yaml`, `.env`, `data/`, and `
 
 When running `init` on the user's behalf, relay every exact authorization or incremental-configuration URL and let the user complete it in their own browser. The command waits only for core message receipt and delivery capabilities. Optional capabilities such as group creation, group-title synchronization, reactions, images, and card actions do not block initialization; relay the final affected-feature warnings when they remain unavailable. Neither URL contains the app secret, and the secret itself is never printed.
 
-Existing complete Feishu credentials are preserved but still audited and repaired when needed. Use `agent-bot init --skip-feishu` only for console-only initialization because it skips both registration and configuration auditing. Use `agent-bot init --reconfigure-feishu` only when the user explicitly wants to replace existing credentials. The command respects `AGENT_BOT_HOME`, `AGENT_BOT_CONFIG`, and `--config <path>`. Use `agent-bot init --json` when structured final output helps.
+Existing complete Feishu credentials are preserved but still audited and repaired when needed. Missing or incomplete credentials mean app creation did not complete, so a later `init` starts a new registration instead of resuming the previous device code. Once both credentials are durably saved, an interrupted permission audit resumes against the same remote app. `init` also holds a local lock to prevent concurrent registrations. Use `agent-bot init --skip-feishu` only for console-only initialization because it skips both registration and configuration auditing. Use `agent-bot init --reconfigure-feishu` only when the user explicitly wants to replace existing complete credentials. The command respects `AGENT_BOT_HOME`, `AGENT_BOT_CONFIG`, and `--config <path>`. Use `agent-bot init --json` when structured final output helps.
 
 ## Start with inspection
 

package/src/cli/Initializer.ts

@@ -1,4 +1,6 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseDotEnv } from "dotenv";
@@ -44,8 +46,15 @@ export interface FeishuCredentials {
   appSecret: string;
 }
 
+export interface InitializationLock {
+  path: string;
+  release(): void;
+}
+
 const DEFAULT_CONFIG_TEMPLATE = fileURLToPath(new URL("../../config.example.yaml", import.meta.url));
 const DEFAULT_ENV_TEMPLATE = fileURLToPath(new URL("../../.env.example", import.meta.url));
+const INITIALIZATION_LOCK_NAME = "init.lock";
+const MAX_INITIALIZATION_LOCK_AGE_MS = 30 * 60_000;
 
 export function initializeAgentBot(options: InitializationOptions = {}): InitializationResult {
   const env = options.env ?? process.env;
@@ -63,14 +72,7 @@ export function initializeAgentBot(options: InitializationOptions = {}): Initial
   const home = ensureDirectory(homePath);
   fs.mkdirSync(configDirectory, { recursive: true });
 
-  let config: InitializedPath;
-  if (fs.existsSync(configPath)) {
-    config = { path: configPath, status: "existing" };
-  } else {
-    fs.copyFileSync(configTemplatePath, configPath, fs.constants.COPYFILE_EXCL);
-    config = { path: configPath, status: "created" };
-  }
-
+  const config = copyIfMissing(configTemplatePath, configPath);
   const envFile = copyIfMissing(envTemplatePath, envPath);
   restrictFilePermissions(envFile.path);
   const data = ensureDirectory(path.join(configDirectory, "data"));
@@ -97,15 +99,93 @@ export function writeFeishuCredentials(envPath: string, credentials: FeishuCrede
 
   fs.mkdirSync(path.dirname(envPath), { recursive: true });
   const temporaryPath = `${envPath}.${process.pid}.${Date.now()}.tmp`;
+  let temporaryFile: number | undefined;
   try {
-    fs.writeFileSync(temporaryPath, updated, { encoding: "utf8", mode: 0o600 });
+    temporaryFile = fs.openSync(temporaryPath, "wx", 0o600);
+    fs.writeFileSync(temporaryFile, updated, "utf8");
+    fs.fsyncSync(temporaryFile);
+    fs.closeSync(temporaryFile);
+    temporaryFile = undefined;
     fs.renameSync(temporaryPath, envPath);
+    syncDirectory(path.dirname(envPath));
     restrictFilePermissions(envPath);
+    const persisted = readFeishuCredentials(envPath, {});
+    if (
+      persisted.status !== "configured"
+      || persisted.appId !== credentials.appId
+      || persisted.appSecret !== credentials.appSecret
+    ) {
+      throw new Error("飞书凭据写入后校验失败。");
+    }
   } finally {
+    if (temporaryFile !== undefined) fs.closeSync(temporaryFile);
     fs.rmSync(temporaryPath, { force: true });
   }
 }
 
+export function shouldCreateFeishuApp(
+  credentials: FeishuCredentialState,
+  reconfigureFeishu: boolean,
+): boolean {
+  return reconfigureFeishu || credentials.status !== "configured";
+}
+
+export function acquireInitializationLock(lockDirectory: string): InitializationLock {
+  fs.mkdirSync(lockDirectory, { recursive: true });
+  const lockPath = path.join(lockDirectory, INITIALIZATION_LOCK_NAME);
+  const owner = {
+    token: randomUUID(),
+    pid: process.pid,
+    hostname: os.hostname(),
+    startedAt: new Date().toISOString(),
+  };
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    let lockFile: number | undefined;
+    let created = false;
+    try {
+      lockFile = fs.openSync(lockPath, "wx", 0o600);
+      created = true;
+      fs.writeFileSync(lockFile, `${JSON.stringify(owner)}\n`, "utf8");
+      fs.fsyncSync(lockFile);
+      fs.closeSync(lockFile);
+      lockFile = undefined;
+      return {
+        path: lockPath,
+        release: () => {
+          const current = readInitializationLock(lockPath);
+          if (current?.token === owner.token) fs.rmSync(lockPath, { force: true });
+        },
+      };
+    } catch (error) {
+      if (lockFile !== undefined) fs.closeSync(lockFile);
+      if (created) fs.rmSync(lockPath, { force: true });
+      if (!isFileExistsError(error)) throw error;
+      if (!isStaleInitializationLock(lockPath)) {
+        throw new Error(`另一个 agent-bot init 正在运行（锁文件：${lockPath}）。`);
+      }
+      fs.rmSync(lockPath, { force: true });
+    }
+  }
+
+  throw new Error(`无法获取初始化锁：${lockPath}`);
+}
+
+export function cleanupFeishuCredentialTemporaryFiles(envPath: string): number {
+  const directory = path.dirname(envPath);
+  if (!fs.existsSync(directory)) return 0;
+  const prefix = `${path.basename(envPath)}.`;
+  let removed = 0;
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith(".tmp")) continue;
+    const middle = entry.name.slice(prefix.length, -".tmp".length);
+    if (!/^\d+\.\d+$/.test(middle)) continue;
+    fs.rmSync(path.join(directory, entry.name), { force: true });
+    removed += 1;
+  }
+  return removed;
+}
+
 function assertTemplate(templatePath: string): void {
   if (!fs.statSync(templatePath, { throwIfNoEntry: false })?.isFile()) {
     throw new Error(`Initialization template does not exist: ${templatePath}`);
@@ -121,8 +201,13 @@ function ensureDirectory(directoryPath: string): InitializedPath {
 function copyIfMissing(sourcePath: string, targetPath: string): InitializedPath {
   if (fs.existsSync(targetPath)) return { path: targetPath, status: "existing" };
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-  fs.copyFileSync(sourcePath, targetPath, fs.constants.COPYFILE_EXCL);
-  return { path: targetPath, status: "created" };
+  try {
+    fs.copyFileSync(sourcePath, targetPath, fs.constants.COPYFILE_EXCL);
+    return { path: targetPath, status: "created" };
+  } catch (error) {
+    if (isFileExistsError(error)) return { path: targetPath, status: "existing" };
+    throw error;
+  }
 }
 
 function upsertDotEnvValue(contents: string, key: string, value: string): string {
@@ -154,6 +239,74 @@ function restrictFilePermissions(filePath: string): void {
   }
 }
 
+function syncDirectory(directoryPath: string): void {
+  let directory: number | undefined;
+  try {
+    directory = fs.openSync(directoryPath, "r");
+    fs.fsyncSync(directory);
+  } catch {
+    // Directory fsync is not supported on every Windows or mounted filesystem.
+  } finally {
+    if (directory !== undefined) fs.closeSync(directory);
+  }
+}
+
+interface InitializationLockOwner {
+  token: string;
+  pid: number;
+  hostname: string;
+  startedAt: string;
+}
+
+function readInitializationLock(lockPath: string): InitializationLockOwner | undefined {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object") return undefined;
+    const value = parsed as Record<string, unknown>;
+    if (
+      typeof value.token !== "string"
+      || typeof value.pid !== "number"
+      || typeof value.hostname !== "string"
+      || typeof value.startedAt !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      token: value.token,
+      pid: value.pid,
+      hostname: value.hostname,
+      startedAt: value.startedAt,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function isStaleInitializationLock(lockPath: string): boolean {
+  const owner = readInitializationLock(lockPath);
+  const modifiedAt = fs.statSync(lockPath, { throwIfNoEntry: false })?.mtimeMs ?? Date.now();
+  const ageMs = Date.now() - modifiedAt;
+  if (!owner) return ageMs >= 5_000;
+  if (owner.hostname === os.hostname()) return !isProcessRunning(owner.pid);
+  const startedAt = Date.parse(owner.startedAt);
+  const ownerAgeMs = Number.isFinite(startedAt) ? Date.now() - startedAt : ageMs;
+  return ownerAgeMs >= MAX_INITIALIZATION_LOCK_AGE_MS;
+}
+
+function isProcessRunning(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function isFileExistsError(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException)?.code === "EEXIST";
+}
+
 function firstNonBlank(...values: Array<string | undefined>): string | undefined {
   return values.find((value) => value !== undefined && value.trim().length > 0);
 }

package/src/cli/LocalControlClient.ts

@@ -41,7 +41,18 @@ export async function sendControlRequest(
 export async function isServerRunning(endpoint: string): Promise<boolean> {
   try {
     const response = await sendControlRequest(endpoint, { action: "health" }, 1_000);
-    return response.ok;
+    if (!response.ok) return false;
+    if (!response.data || typeof response.data !== "object") return true;
+    return (response.data as Record<string, unknown>).ready !== false;
+  } catch {
+    return false;
+  }
+}
+
+export async function isServerReachable(endpoint: string): Promise<boolean> {
+  try {
+    await sendControlRequest(endpoint, { action: "health" }, 1_000);
+    return true;
   } catch {
     return false;
   }

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,
@@ -27,6 +30,7 @@ import {
   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";
@@ -97,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 {
@@ -196,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));
@@ -227,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(),
@@ -240,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;
   }
@@ -422,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`);

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;