@keyou007/agent-bot 0.1.2 → 0.1.4

package/docs/technical-reference.zh.md

@@ -33,6 +33,10 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 默认用户数据根目录为 `~/.agent-bot`，可通过 `AGENT_BOT_HOME` 整体替换。
 
+CLI 还支持显式指定目录的 Profile。不使用 `--profile` 时，命令使用主 Profile 以及原有的环境变量路径规则。`--profile <目录>` 会为当前命令及其启动的 Supervisor、Worker 固定 `AGENT_BOT_HOME` 和 `AGENT_BOT_CONFIG`，配置文件固定为 `<目录>/config.yaml`。它还会先清除继承的飞书凭据环境变量，再加载所选 Profile 的 `.env`，避免从主 Agent Bot 进程树中启动辅助实例时误用主机器人的凭据。`--profile` 不能和 `--config` 同时使用。其他 Profile 必须在每次命令中显式选择；Agent Bot 不维护按名称注册的 Profile。
+
+CLI 界面文本不受系统语言影响，统一使用英文。系统生成的重启原因仍使用中文，因为它会显示在中文 Lark 状态卡中；显式传入的 `--reason` 保持原样。`agent-bot server status` 会报告运行中 Worker 的 Lark App ID，JSON 字段名为 `feishuAppId`；服务停止或旧版健康协议尚未提供该字段时，CLI 会回退到当前 Profile 配置的 App ID。
+
 | 默认路径                             | 内容                 |
 | ------------------------------------ | -------------------- |
 | `~/.agent-bot/config.yaml`           | YAML 主配置          |
@@ -43,9 +47,10 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 配置文件优先级：
 
-1. CLI `--config <路径>`
-2. `AGENT_BOT_CONFIG`
-3. `~/.agent-bot/config.yaml`
+1. CLI `--profile <目录>` 选择 `<目录>/config.yaml`
+2. CLI `--config <路径>`
+3. `AGENT_BOT_CONFIG`
+4. `<AGENT_BOT_HOME>/config.yaml`，默认为 `~/.agent-bot/config.yaml`
 
 默认 `.env` 始终从 Agent Bot 用户目录加载。加载 `.env` 后，YAML 中的 `${NAME}` 会使用进程环境变量展开。
 
@@ -59,6 +64,7 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 - 进程环境变量优先于 `~/.agent-bot/.env`
 - `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须同时存在
+- 一键注册还会把授权用户的 `open_id` 保存为 `FEISHU_USER_OPEN_ID`
 - 除非使用 `--reconfigure-feishu`，完整凭据不会被替换
 - 缺少凭据或只有一项时会重新创建应用
 - 新创建的凭据经过 fsync、原子替换写入 `.env`，并在配置权限前读回校验
@@ -74,6 +80,8 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 生成的授权链接不包含 App Secret。
 
+飞书初始化成功后，CLI 会先释放初始化锁，再通过与 `agent-bot server start` 相同的就绪检查流程启动后台 Supervisor，并等待最多 45 秒，直到 Worker 连接飞书并进入就绪状态。如果当前 Profile 的服务已经运行，不会创建第二个 Supervisor。`--skip-feishu` 会跳过自动启动；`--json` 会把结果写入 `server.status`，不会混入非 JSON 文本。
+
 ## 飞书应用要求
 
 基础消息能力依赖以下核心配置：
@@ -107,6 +115,7 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 feishu:
   appId: "${FEISHU_APP_ID}"
   appSecret: "${FEISHU_APP_SECRET}"
+  userOpenId: "${FEISHU_USER_OPEN_ID}"
 
 console:
   enabled: true
@@ -131,7 +140,7 @@ logging:
   path: "./logs/agent-bot.log"
 ```
 
-`agent-bot server start` 要求同时配置飞书 `appId` 和 `appSecret`。命令会等待 SDK 的 WebSocket 长连接建立后才报告 Server 就绪；缺少凭据时启动失败并提示先初始化。`agent-bot console` 是明确的纯本地入口，不需要飞书凭据。
+`agent-bot server start` 要求同时配置飞书 `appId` 和 `appSecret`。Worker 启动 SDK 长连接时不读取 SDK 日志或私有连接状态，随后通过发送启动状态卡片检查出站能力。通知通常发往已知私聊和最近活跃的群聊；数据库里尚无已知会话时，改用 `feishu.userOpenId`，按 `open_id` 私聊发送。存在通知目标时，至少一张卡片发送成功后 Server 才报告就绪，单个目标发送失败仍相互隔离。如果既没有已知会话，也没有 `feishu.userOpenId`，启动会跳过出站检查并继续。缺少凭据时仍会启动失败并提示先初始化。`agent-bot console` 是明确的纯本地入口，不需要飞书凭据。
 
 必须至少配置一个 Agent，`defaults.agent` 必须指向已配置的 Agent。
 
@@ -175,7 +184,7 @@ AGENT_BOT=1
 
 每个 turn 只有一张进度卡。普通更新最多每两秒一次，关键更新最短间隔 500 毫秒。完成时先把进度卡更新为终态，再单独发送 Markdown 最终回答。
 
-消息去重后，Agent Bot 会尝试添加 `OnIt` 表情。Turn 成功、失败或取消时分别替换为 `DONE`、`ERROR` 或 `CrossMark`。表情操作失败不会阻塞任务。
+完成持久化消息去重占位后，Agent Bot 会等待 `OnIt` 表情添加成功，再进行聊天信息持久化、图片下载、队列等待、命令执行或 Runtime 调用。Turn 成功、失败或取消时分别替换为 `DONE`、`ERROR` 或 `CrossMark`。表情操作失败会记录日志，但不会阻塞任务。
 
 富文本图片会下载到输入图片缓存，并以 `localImage` 传给 Codex。纯图片消息使用默认 Prompt `请分析这张图片。`。ACP Runtime 不支持图片输入时会明确报错。
 
@@ -214,6 +223,15 @@ SQLite 保存：
 
 `agent-bot server start` 启动后台 supervisor。Worker 意外退出后会自动拉起；连续崩溃时使用 1 到 30 秒的指数退避。
 
+Supervisor 的崩溃诊断文件按当前 Profile 隔离：
+
+- `logs/supervisor.log` 持久记录 Worker PID、退出码、运行时长、重启延迟和诊断文件路径
+- `logs/worker.stderr.log` 保存后台进程原本会丢失的 Node/V8 fatal 输出；两类诊断日志达到 10 MiB 时轮转，保留三个备份
+- `data/last-crash.json` 指向最近一次 Worker 异常退出，带时间戳的 `data/crash-reports/crash-*.json` 保留历史记录
+- Node 能生成报告时，写入 `data/crash-reports/report.*.json`
+
+Supervisor、Worker、替换 Supervisor 和 Console Worker 默认启用 Node fatal error 与未捕获异常报告。Node 版本支持时还会排除环境变量和网络接口，避免凭据进入报告。主动重启退出码 `75` 和停止退出码 `76` 不会创建崩溃清单。
+
 安全重启会等待：
 
 1. 活动任务完成
@@ -224,6 +242,8 @@ SQLite 保存：
 
 首次安全重启状态卡会延迟 3 秒发送，让任务最终回答尽可能先到达；延迟期间的状态变化会合并到首张卡片。该延迟不阻塞调度器轮询，真正关闭前会立即 flush 尚未发送的卡片。
 
+等待中的安全重启状态卡底部带有 `Cancel` 操作。回调会携带调度器单调递增的计划 ID，因此旧卡片不会取消较新的重启。取消成功后，所有已发送的状态卡都会原地更新并移除按钮；调度器进入不可逆的正在重启阶段后也不再显示该按钮。
+
 本地控制服务负责修改任务和请求服务重启；只读任务查询直接访问 SQLite。
 
 ## 权限模式

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@keyou007/agent-bot",
-      "version": "0.1.2",
+      "version": "0.1.4",
       "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.2",
+  "version": "0.1.4",
   "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

@@ -48,10 +48,21 @@ agent-bot init
 
 Initialization creates the Agent Bot home, `config.yaml`, `.env`, `data/`, and `logs/` from the bundled examples. If Feishu credentials are absent, it starts Feishu one-click app registration, prints an authorization URL and QR code, waits for the user to approve the request, and stores the returned app ID and secret in `.env`. It then audits the app's currently published tenant permissions, event subscriptions, and callbacks. Core and optional missing items produce separate incremental-configuration URLs so optional approval cannot block core setup.
 
+After Feishu initialization succeeds, `init` releases its initialization lock and automatically starts the selected profile's server, waiting until it is ready. It does not create another supervisor when that profile is already running. `init --skip-feishu` is the exception: it prepares Console-only files and does not start the server. With `--json`, inspect `server.status` for `started`, `already-running`, or `skipped`.
+
 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. 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.
 
+For an isolated secondary bot, pass its profile directory explicitly on every command:
+
+```powershell
+agent-bot --profile ~/.agent-bot-rescue init
+agent-bot --profile ~/.agent-bot-rescue server status
+```
+
+No `--profile` selects the main profile at `~/.agent-bot` by default. `--profile <directory>` selects that directory's `config.yaml`, `.env`, data, logs, and local control endpoint and propagates the selection to the supervisor and worker. Alternative profiles are not registered by name. Do not combine `--profile` with `--config`.
+
 ## Start with inspection
 
 Verify the CLI and current service state before changing anything:
@@ -63,11 +74,11 @@ agent-bot server status
 agent-bot task list
 ```
 
-`agent-bot --help` uses Chinese when the system locale is Chinese and English otherwise.
+All Agent Bot CLI interface text is English regardless of system locale. `agent-bot server status` also reports the running profile's Lark App ID; with `--json`, read it from `feishuAppId`.
 
 Add `--json` to status and list commands when machine-readable output helps. If `agent-bot` is unavailable, report that the CLI is not installed or linked instead of guessing process state.
 
-By default Agent Bot stores user-owned configuration and runtime state in `~/.agent-bot`: config at `~/.agent-bot/config.yaml`, environment variables at `~/.agent-bot/.env`, SQLite state at `~/.agent-bot/data/agent-bot.sqlite`, logs at `~/.agent-bot/logs/agent-bot.log`, and inbound image cache next to the SQLite database. `AGENT_BOT_HOME` changes this root. Use `--config <path>` only when controlling a non-default configuration.
+By default Agent Bot stores user-owned configuration and runtime state in `~/.agent-bot`: config at `~/.agent-bot/config.yaml`, environment variables at `~/.agent-bot/.env`, SQLite state at `~/.agent-bot/data/agent-bot.sqlite`, logs at `~/.agent-bot/logs/agent-bot.log`, and inbound image cache next to the SQLite database. `AGENT_BOT_HOME` changes this root. Prefer `--profile <directory>` when controlling a complete isolated instance; use `--config <path>` only when selecting a non-default configuration without changing the whole profile.
 
 ## Manage the service
 
@@ -80,12 +91,21 @@ agent-bot server restart --reason "reason for restart"
 agent-bot server stop
 ```
 
-Treat `server restart` as the normal restart path. It schedules a safe restart and waits for active tasks, pending final-message delivery, and a quiet inbound-message window. The first safe-restart status card is delayed by three seconds so the active task's final response can usually be delivered first; this presentation delay does not postpone scheduler polling.
+Treat `server restart` as the normal restart path. It schedules a safe restart and waits for active tasks, pending final-message delivery, and a quiet inbound-message window. The first safe-restart status card is delayed by three seconds so the active task's final response can usually be delivered first; this presentation delay does not postpone scheduler polling. While the restart is pending, its status card has a bottom `Cancel` button that conditionally cancels that exact schedule and updates the card in place.
 
 Use `agent-bot server restart --immediate` only when the user explicitly requests an immediate restart or accepts interruption. Never use `taskkill`, `Stop-Process`, or equivalent commands for routine Agent Bot restart management.
 
 `agent-bot console` opens the console UI only when the service is stopped. Do not use `--force` while the service is live unless the user explicitly accepts concurrent state access.
 
+When a startup card says the Worker exited and the supervisor restarted it, inspect the selected profile's persisted crash evidence before guessing at a cause:
+
+- `data/last-crash.json` for PID, exit code, uptime, restart delay, and linked report paths
+- `logs/supervisor.log` for the restart timeline
+- `logs/worker.stderr.log` for Node/V8 fatal output
+- `data/crash-reports/report.*.json` for Node diagnostic reports
+
+Normal safe restarts and explicit stops do not overwrite the latest crash record. Every explicit profile keeps its own diagnostic files; use the same `--profile <directory>` selection when correlating service status with those paths.
+
 ## Manage tasks
 
 List tasks before resolving a numeric reference because task numbers follow the current list order:
@@ -131,7 +151,7 @@ Messages whose trimmed text starts with `/` are always parsed as Agent Bot comma
 
 When a group body has a current task, renaming the Feishu group to `[agent-name] new title` also renames that current task if the prefix matches the task's configured agent. Malformed names, agent mismatches, empty groups, and thread-specific tasks are ignored.
 
-Use `--context <key>` or `--status <status>` to narrow `task list`. Use `--config <path>` before the command when controlling a non-default Agent Bot configuration.
+Use `--context <key>` or `--status <status>` to narrow `task list`. Use `--profile <directory>` before the command when controlling an isolated Agent Bot instance, or `--config <path>` for only a non-default configuration.
 
 ## Apply code changes safely
 

package/src/cli/FeishuAppConfiguration.ts

@@ -178,8 +178,8 @@ export async function ensureFeishuAppConfiguration(
     }
   }
 
-  const detail = lastError instanceof Error ? ` 最后一次检查失败：${lastError.message}` : "";
-  throw new Error(`等待飞书核心权限和消息事件配置生效超时，请重新运行 agent-bot init。${detail}`);
+  const detail = lastError instanceof Error ? ` Last check failed: ${lastError.message}` : "";
+  throw new Error(`Timed out waiting for the core Lark scopes and message event. Run agent-bot init again.${detail}`);
 }
 
 async function requestMissingFeishuConfiguration(
@@ -248,14 +248,14 @@ async function readFeishuAppConfiguration(
       `${FEISHU_OPEN_BASE_URL}${APPLICATION_PATH_PREFIX}/${appId}?lang=zh_cn`,
       { headers },
       signal,
-      "查询飞书应用配置",
+      "Read Lark app configuration",
     ),
     fetchJson(
       fetchImpl,
       `${FEISHU_OPEN_BASE_URL}${APPLICATION_PATH_PREFIX}/${appId}/app_versions?lang=zh_cn&page_size=2`,
       { headers },
       signal,
-      "查询飞书应用版本",
+      "Read Lark app versions",
     ),
   ]);
 
@@ -303,10 +303,10 @@ async function getTenantAccessToken(
       }),
     },
     signal,
-    "获取飞书 tenant_access_token",
+    "Get the Lark tenant_access_token",
   );
   const token = readString(payload, "tenant_access_token");
-  if (!token) throw new Error("飞书 tenant_access_token 响应缺少访问凭证。");
+  if (!token) throw new Error("The Lark tenant_access_token response is missing the access token.");
   return token;
 }
 
@@ -327,12 +327,12 @@ async function fetchJson(
     const response = await fetchImpl(url, { ...init, signal: controller.signal });
     const payload = (await response.json().catch(() => undefined)) as unknown;
     if (!isJsonObject(payload)) {
-      throw new Error(`${operation}返回了无法解析的响应（HTTP ${response.status}）。`);
+      throw new Error(`${operation} returned an invalid response (HTTP ${response.status}).`);
     }
     const code = readNumber(payload, "code");
     if (!response.ok || code !== 0) {
       throw new FeishuConfigurationApiError(
-        `${operation}失败：${readString(payload, "msg") || response.statusText || `HTTP ${response.status}`}`,
+        `${operation} failed: ${readString(payload, "msg") || response.statusText || `HTTP ${response.status}`}`,
         code,
         response.status,
       );
@@ -340,7 +340,7 @@ async function fetchJson(
     return payload;
   } catch (error) {
     if (parentSignal?.aborted) throw abortError(parentSignal);
-    if (controller.signal.aborted) throw new Error(`${operation}请求超时。`);
+    if (controller.signal.aborted) throw new Error(`${operation} timed out.`);
     throw error;
   } finally {
     clearTimeout(timeout);
@@ -442,7 +442,7 @@ function positiveInteger(value: number | undefined): number | undefined {
 }
 
 function abortError(signal: AbortSignal): Error {
-  return signal.reason instanceof Error ? signal.reason : new Error("飞书应用配置已取消。");
+  return signal.reason instanceof Error ? signal.reason : new Error("Lark app configuration was cancelled.");
 }
 
 function delay(milliseconds: number): Promise<void> {

package/src/cli/FeishuAppRegistration.ts

@@ -16,6 +16,7 @@ export interface FeishuAppRegistrationChallenge {
 export interface FeishuAppCredentials {
   appId: string;
   appSecret: string;
+  userOpenId?: string;
 }
 
 export interface FeishuAppRegistrationOptions {
@@ -40,12 +41,12 @@ export async function registerFeishuApp(options: FeishuAppRegistrationOptions =
     },
     options.signal,
   );
-  throwRegistrationError(begin, "无法发起飞书应用创建");
+  throwRegistrationError(begin, "Could not start Lark app creation");
 
   const deviceCode = readString(begin, "device_code");
   const userCode = readString(begin, "user_code");
   if (!deviceCode || !userCode) {
-    throw new Error("飞书应用创建响应缺少 device_code 或 user_code。");
+    throw new Error("The Lark app creation response is missing device_code or user_code.");
   }
 
   const expiresIn =
@@ -94,7 +95,14 @@ export async function registerFeishuApp(options: FeishuAppRegistrationOptions =
     if (!errorCode) {
       const appId = readString(payload, "client_id");
       const appSecret = readString(payload, "client_secret");
-      if (appId && appSecret) return { appId, appSecret };
+      if (appId && appSecret) {
+        const userOpenId = readString(readObject(payload, "user_info"), "open_id");
+        return {
+          appId,
+          appSecret,
+          ...(userOpenId ? { userOpenId } : {}),
+        };
+      }
       continue;
     }
 
@@ -105,16 +113,16 @@ export async function registerFeishuApp(options: FeishuAppRegistrationOptions =
         intervalSeconds = Math.min(intervalSeconds + 5, MAX_POLL_INTERVAL_SECONDS);
         continue;
       case "access_denied":
-        throw new Error("你已取消飞书应用创建。");
+        throw new Error("Lark app creation was cancelled.");
       case "expired_token":
       case "invalid_grant":
-        throw new Error("飞书应用创建链接已过期，请重新运行 agent-bot init。");
+        throw new Error("The Lark app creation link expired. Run agent-bot init again.");
       default:
-        throwRegistrationError(payload, "飞书应用创建失败");
+        throwRegistrationError(payload, "Lark app creation failed");
     }
   }
 
-  throw new Error("等待飞书应用创建超时，请重新运行 agent-bot init。");
+  throw new Error("Timed out waiting for Lark app creation. Run agent-bot init again.");
 }
 
 function buildVerificationUrl(userCode: string): string {
@@ -144,7 +152,7 @@ async function postRegistration(
     });
     const payload = (await response.json().catch(() => undefined)) as unknown;
     if (!isRecord(payload)) {
-      throw new Error(`飞书应用注册接口返回了无法解析的响应（HTTP ${response.status}）。`);
+      throw new Error(`The Lark app registration endpoint returned an invalid response (HTTP ${response.status}).`);
     }
     return payload;
   } finally {
@@ -157,7 +165,7 @@ function throwRegistrationError(payload: RegistrationPayload, prefix: string): v
   const code = readString(payload, "error");
   if (!code) return;
   const description = readString(payload, "error_description") || code;
-  throw new Error(`${prefix}：${description}`);
+  throw new Error(`${prefix}: ${description}`);
 }
 
 function readString(value: RegistrationPayload, key: string): string {
@@ -165,6 +173,11 @@ function readString(value: RegistrationPayload, key: string): string {
   return typeof field === "string" ? field.trim() : "";
 }
 
+function readObject(value: RegistrationPayload, key: string): RegistrationPayload {
+  const field = value[key];
+  return isRecord(field) ? field : {};
+}
+
 function readPositiveInteger(value: RegistrationPayload, key: string): number | undefined {
   const field = value[key];
   const parsed = typeof field === "number" ? field : Number(field);
@@ -176,7 +189,7 @@ function isRecord(value: unknown): value is RegistrationPayload {
 }
 
 function abortError(signal: AbortSignal): Error {
-  return signal.reason instanceof Error ? signal.reason : new Error("飞书应用创建已取消。");
+  return signal.reason instanceof Error ? signal.reason : new Error("Lark app creation was cancelled.");
 }
 
 function delay(milliseconds: number): Promise<void> {

package/src/cli/Initializer.ts

@@ -39,11 +39,13 @@ export interface FeishuCredentialState {
   status: FeishuCredentialStatus;
   appId?: string;
   appSecret?: string;
+  userOpenId?: string;
 }
 
 export interface FeishuCredentials {
   appId: string;
   appSecret: string;
+  userOpenId?: string;
 }
 
 export interface InitializationLock {
@@ -85,17 +87,21 @@ export function readFeishuCredentials(envPath: string, env: NodeJS.ProcessEnv =
   const fileValues = fs.existsSync(envPath) ? parseDotEnv(fs.readFileSync(envPath, "utf8")) : {};
   const appId = firstNonBlank(env.FEISHU_APP_ID, fileValues.FEISHU_APP_ID);
   const appSecret = firstNonBlank(env.FEISHU_APP_SECRET, fileValues.FEISHU_APP_SECRET);
-  if (appId && appSecret) return { status: "configured", appId, appSecret };
-  if (appId || appSecret) return { status: "incomplete", appId, appSecret };
-  return { status: "missing" };
+  const userOpenId = firstNonBlank(env.FEISHU_USER_OPEN_ID, fileValues.FEISHU_USER_OPEN_ID);
+  const user = userOpenId ? { userOpenId } : {};
+  if (appId && appSecret) return { status: "configured", appId, appSecret, ...user };
+  if (appId || appSecret) return { status: "incomplete", appId, appSecret, ...user };
+  return { status: "missing", ...user };
 }
 
 export function writeFeishuCredentials(envPath: string, credentials: FeishuCredentials): void {
   assertDotEnvValue("FEISHU_APP_ID", credentials.appId);
   assertDotEnvValue("FEISHU_APP_SECRET", credentials.appSecret);
+  if (credentials.userOpenId) assertDotEnvValue("FEISHU_USER_OPEN_ID", credentials.userOpenId);
   const original = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
   let updated = upsertDotEnvValue(original, "FEISHU_APP_ID", credentials.appId);
   updated = upsertDotEnvValue(updated, "FEISHU_APP_SECRET", credentials.appSecret);
+  updated = upsertDotEnvValue(updated, "FEISHU_USER_OPEN_ID", credentials.userOpenId ?? "");
 
   fs.mkdirSync(path.dirname(envPath), { recursive: true });
   const temporaryPath = `${envPath}.${process.pid}.${Date.now()}.tmp`;
@@ -114,8 +120,9 @@ export function writeFeishuCredentials(envPath: string, credentials: FeishuCrede
       persisted.status !== "configured"
       || persisted.appId !== credentials.appId
       || persisted.appSecret !== credentials.appSecret
+      || persisted.userOpenId !== credentials.userOpenId
     ) {
-      throw new Error("飞书凭据写入后校验失败。");
+      throw new Error("Lark credential verification failed after writing the environment file.");
     }
   } finally {
     if (temporaryFile !== undefined) fs.closeSync(temporaryFile);
@@ -162,13 +169,13 @@ export function acquireInitializationLock(lockDirectory: string): Initialization
       if (created) fs.rmSync(lockPath, { force: true });
       if (!isFileExistsError(error)) throw error;
       if (!isStaleInitializationLock(lockPath)) {
-        throw new Error(`另一个 agent-bot init 正在运行（锁文件：${lockPath}）。`);
+        throw new Error(`Another agent-bot init process is running (lock file: ${lockPath}).`);
       }
       fs.rmSync(lockPath, { force: true });
     }
   }
 
-  throw new Error(`无法获取初始化锁：${lockPath}`);
+  throw new Error(`Could not acquire the initialization lock: ${lockPath}`);
 }
 
 export function cleanupFeishuCredentialTemporaryFiles(envPath: string): number {
@@ -227,7 +234,7 @@ function upsertDotEnvValue(contents: string, key: string, value: string): string
 
 function assertDotEnvValue(key: string, value: string): void {
   if (!value.trim() || /[\r\n]/.test(value)) {
-    throw new Error(`${key} 不是有效的单行环境变量值。`);
+    throw new Error(`${key} is not a valid single-line environment variable value.`);
   }
 }
 

package/src/cli/LocalControlClient.ts

@@ -17,7 +17,7 @@ export async function sendControlRequest(
       socket.destroy();
       operation();
     };
-    const timer = setTimeout(() => finish(() => reject(new Error("连接 Agent Bot 控制端点超时。"))), timeoutMs);
+    const timer = setTimeout(() => finish(() => reject(new Error("Timed out connecting to the Agent Bot control endpoint."))), timeoutMs);
     socket.setEncoding("utf8");
     socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
     socket.on("data", (chunk: string) => {
@@ -33,7 +33,7 @@ export async function sendControlRequest(
     });
     socket.once("error", (error) => finish(() => reject(error)));
     socket.once("end", () => {
-      if (!settled) finish(() => reject(new Error("Agent Bot 控制端点未返回结果。")));
+      if (!settled) finish(() => reject(new Error("The Agent Bot control endpoint returned no response.")));
     });
   });
 }

package/src/cli/LocalControlServer.ts

@@ -61,7 +61,7 @@ export class LocalControlServer {
 function parseRequest(line: string): ControlRequest {
   const value = JSON.parse(line) as unknown;
   if (!value || typeof value !== "object" || !("action" in value) || typeof value.action !== "string") {
-    throw new Error("无效的本地控制请求。");
+    throw new Error("Invalid local control request.");
   }
   return value as ControlRequest;
 }

package/src/cli/ServerStarter.ts

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "../config/loadConfig.js";
+import type { AppConfig } from "../config/schema.js";
+import { requireServerFeishuTransport } from "../feishu/transport.js";
+import {
+  nodeDiagnosticReportArguments,
+  prepareCrashReportDirectory,
+  resolveSupervisorDiagnosticsPaths,
+} from "../supervision/SupervisorDiagnostics.js";
+import { controlEndpoint } from "./controlProtocol.js";
+import { isServerReachable, isServerRunning } from "./LocalControlClient.js";
+
+export interface ServerStartResult {
+  status: "started" | "already-running";
+}
+
+export type InitializationServerResult =
+  | ServerStartResult
+  | { status: "skipped"; reason: "feishu-skipped" };
+
+export interface ServerStarterDependencies {
+  isRunning(endpoint: string): Promise<boolean>;
+  isReachable(endpoint: string): Promise<boolean>;
+  waitUntilRunning(endpoint: string, timeoutMs: number): Promise<boolean>;
+  spawnSupervisor(config: AppConfig): void;
+}
+
+const SERVER_START_TIMEOUT_MS = 45_000;
+
+interface InitializationServerDependencies {
+  loadConfig(configPath?: string): AppConfig;
+  startServer(config: AppConfig): Promise<ServerStartResult>;
+}
+
+export async function startInitializedServer(
+  options: { skipFeishu: boolean; configPath?: string },
+  dependencies: InitializationServerDependencies = defaultInitializationDependencies,
+): Promise<InitializationServerResult> {
+  if (options.skipFeishu) {
+    return { status: "skipped", reason: "feishu-skipped" };
+  }
+  return dependencies.startServer(dependencies.loadConfig(options.configPath));
+}
+
+export async function startServer(
+  config: AppConfig,
+  dependencies: ServerStarterDependencies = defaultDependencies,
+): Promise<ServerStartResult> {
+  requireServerFeishuTransport(config.feishu);
+  const endpoint = controlEndpoint(config.storage.sqlitePath);
+
+  if (await dependencies.isRunning(endpoint)) {
+    return { status: "already-running" };
+  }
+  if (await dependencies.isReachable(endpoint)) {
+    const running = await dependencies.waitUntilRunning(endpoint, SERVER_START_TIMEOUT_MS);
+    if (!running) {
+      throw new Error("The Agent Bot server started but could not connect to Lark. Check the logs.");
+    }
+    return { status: "started" };
+  }
+
+  dependencies.spawnSupervisor(config);
+  const running = await dependencies.waitUntilRunning(endpoint, SERVER_START_TIMEOUT_MS);
+  if (!running) {
+    throw new Error("The Supervisor started, but the server did not connect to Lark within 45 seconds. Check the logs.");
+  }
+  return { status: "started" };
+}
+
+const defaultDependencies: ServerStarterDependencies = {
+  isRunning: isServerRunning,
+  isReachable: isServerReachable,
+  waitUntilRunning: waitForServer,
+  spawnSupervisor: (config) => {
+    const entry = fileURLToPath(new URL("../supervisor.js", import.meta.url));
+    const reportDirectory = resolveSupervisorDiagnosticsPaths(config).crashReportDirectory;
+    prepareCrashReportDirectory(reportDirectory);
+    const child = spawn(process.execPath, [
+      ...nodeDiagnosticReportArguments(reportDirectory),
+      entry,
+    ], {
+      cwd: process.cwd(),
+      detached: true,
+      windowsHide: true,
+      stdio: "ignore",
+      env: { ...process.env, AGENT_BOT_RESTART_REASON: "通过 Agent Bot CLI 启动" },
+    });
+    child.unref();
+  },
+};
+
+const defaultInitializationDependencies: InitializationServerDependencies = {
+  loadConfig,
+  startServer: (config) => startServer(config),
+};
+
+async function waitForServer(endpoint: string, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isServerRunning(endpoint)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return false;
+}

package/src/cli/SkillRegistry.ts

@@ -65,7 +65,7 @@ export class SkillRegistry {
     this.assertValidSource();
     const existing = fs.existsSync(this.targetPath);
     if (existing && this.readMarker()?.managedBy !== "agent-bot") {
-      throw new Error(`目标目录已存在且不由 Agent Bot 管理：${this.targetPath}`);
+      throw new Error(`The target directory exists and is not managed by Agent Bot: ${this.targetPath}`);
     }
 
     const before = existing ? this.status() : undefined;
@@ -93,7 +93,7 @@ export class SkillRegistry {
   uninstall(): boolean {
     if (!fs.existsSync(this.targetPath)) return false;
     if (this.readMarker()?.managedBy !== "agent-bot") {
-      throw new Error(`拒绝删除不由 Agent Bot 管理的目录：${this.targetPath}`);
+      throw new Error(`Refusing to remove a directory that is not managed by Agent Bot: ${this.targetPath}`);
     }
     this.removeManagedTarget();
     return true;
@@ -101,13 +101,13 @@ export class SkillRegistry {
 
   private assertValidSource(): void {
     if (!fs.existsSync(path.join(this.sourcePath, "SKILL.md"))) {
-      throw new Error(`找不到内置 Agent Bot Skill：${this.sourcePath}`);
+      throw new Error(`The built-in Agent Bot Skill was not found: ${this.sourcePath}`);
     }
   }
 
   private assertSafeTarget(): void {
     if (path.dirname(this.targetPath) !== this.skillsRoot || path.basename(this.targetPath) !== SKILL_NAME) {
-      throw new Error(`不安全的 Skill 目标路径：${this.targetPath}`);
+      throw new Error(`Unsafe Skill target path: ${this.targetPath}`);
     }
   }