@keyou007/agent-bot 0.1.1 → 0.1.3

package/docs/technical-reference.md

@@ -33,6 +33,8 @@ Relevant source areas:
 
 The default user-data root is `~/.agent-bot`. `AGENT_BOT_HOME` replaces that root.
 
+The CLI also supports explicit directory-based profiles. Without `--profile`, commands use the main profile and the normal environment-based path rules. `--profile <directory>` pins both `AGENT_BOT_HOME` and `AGENT_BOT_CONFIG` for the command and every spawned supervisor or worker, with the configuration fixed at `<directory>/config.yaml`. It also clears inherited Feishu credential variables before loading the selected profile's `.env`, which prevents a secondary service launched from inside the primary Agent Bot process tree from accidentally reusing the primary bot. It cannot be combined with `--config`. Alternative profiles must be selected explicitly on every command; Agent Bot does not maintain a named-profile registry.
+
 | Default path                         | Contents                           |
 | ------------------------------------ | ---------------------------------- |
 | `~/.agent-bot/config.yaml`           | Main YAML configuration            |
@@ -43,9 +45,10 @@ The default user-data root is `~/.agent-bot`. `AGENT_BOT_HOME` replaces that roo
 
 Configuration path precedence:
 
-1. CLI `--config <path>`
-2. `AGENT_BOT_CONFIG`
-3. `~/.agent-bot/config.yaml`
+1. CLI `--profile <directory>` selects `<directory>/config.yaml`
+2. CLI `--config <path>`
+3. `AGENT_BOT_CONFIG`
+4. `<AGENT_BOT_HOME>/config.yaml`, defaulting to `~/.agent-bot/config.yaml`
 
 The default `.env` is always loaded from the Agent Bot home. YAML values in the form `${NAME}` are expanded from the process environment after `.env` loading.
 
@@ -59,11 +62,14 @@ Credential behavior:
 
 - Environment values take precedence over values in `~/.agent-bot/.env`.
 - Both `FEISHU_APP_ID` and `FEISHU_APP_SECRET` are required.
+- One-click registration also stores the authorizing user's `open_id` as `FEISHU_USER_OPEN_ID`.
 - Complete credentials are preserved unless `--reconfigure-feishu` is used.
-- An incomplete credential pair is rejected instead of being silently replaced.
-- Newly registered credentials are written atomically to `.env`.
+- Missing or incomplete credentials cause a new app registration.
+- Newly registered credentials are fsynced, atomically replaced in `.env`, and read back before configuration begins.
+
+Initialization holds `~/.agent-bot/init.lock` so concurrent commands cannot create multiple apps, including commands that use different config paths. A lock left by a dead process is recovered on the next run, and credential temporary files left by an interrupted write are removed.
 
-When credentials are absent, initialization uses Feishu one-click registration and reports its verification URL as text and a QR code. After registration, or when complete credentials already exist, it audits the currently published app version.
+When complete credentials are absent, initialization uses Feishu one-click registration and reports its verification URL as text and a QR code. In-progress registration codes are not resumed: if the process exits before the complete credential pair is persisted, the next run starts a new app registration. After credentials are persisted, initialization audits the currently published app version and can safely resume that audit after interruption.
 
 Missing app configuration is handled in two stages:
 
@@ -72,6 +78,8 @@ Missing app configuration is handled in two stages:
 
 The generated authorization links do not contain the app secret.
 
+After Feishu initialization succeeds, the CLI releases the initialization lock and starts the detached supervisor through the same readiness path as `agent-bot server start`. It waits up to 45 seconds for the worker to connect to Feishu and become ready. If the selected profile is already running, no second supervisor is created. `--skip-feishu` skips automatic server startup, and `--json` includes the resulting `server.status` without adding non-JSON output.
+
 ## Feishu App Requirements
 
 Core configuration required for basic messaging:
@@ -103,10 +111,9 @@ The complete example is [config.example.yaml](../config.example.yaml). The main
 
 ```yaml
 feishu:
-  transport: "auto"
   appId: "${FEISHU_APP_ID}"
   appSecret: "${FEISHU_APP_SECRET}"
-  useConsoleWhenMissingCredentials: true
+  userOpenId: "${FEISHU_USER_OPEN_ID}"
 
 console:
   enabled: true
@@ -131,11 +138,7 @@ logging:
   path: "./logs/agent-bot.log"
 ```
 
-`feishu.transport` accepts:
-
-- `auto`: use the SDK when credentials exist; otherwise follow `useConsoleWhenMissingCredentials`
-- `sdk`: require Feishu credentials and start the WebSocket client
-- `console`: disable Feishu transport
+`agent-bot server start` requires both Feishu credentials. The worker starts the SDK's persistent connection without inspecting SDK logs or private connection state, then sends startup status cards as an outbound readiness check. It normally targets known private chats and recently active groups. If the database has no known chat yet, it sends the card to `feishu.userOpenId` using an `open_id` private message. When notification targets exist, at least one card must be delivered before the server reports ready; individual target failures remain isolated. If neither a known chat nor `feishu.userOpenId` is available, startup continues without the outbound check. Missing credentials still fail startup with an initialization hint. `agent-bot console` is the explicit local-only path and does not require Feishu credentials.
 
 At least one agent must be configured. `defaults.agent` must name a configured agent.
 
@@ -179,7 +182,7 @@ Starting a Feishu thread from a mapped user message, progress card, or final res
 
 Each turn owns one progress card. Normal updates are throttled to one every two seconds; critical updates have a 500 ms minimum gap. On completion, Agent Bot updates the progress card to a terminal state before sending a separate final Markdown message.
 
-After message deduplication, Agent Bot attempts an `OnIt` reaction. It replaces that reaction with `DONE`, `ERROR`, or `CrossMark` when the turn succeeds, fails, or is canceled. Reaction failures do not block task execution.
+After the durable message-deduplication claim, Agent Bot awaits the `OnIt` reaction before chat persistence, image downloads, queue waits, command execution, or runtime calls. It replaces that reaction with `DONE`, `ERROR`, or `CrossMark` when the turn succeeds, fails, or is canceled. Reaction failures are logged but do not block task execution.
 
 Incoming rich-text images are downloaded into the inbound image cache and passed to Codex as `localImage` inputs. An image-only message uses the default Prompt `请分析这张图片。`. An ACP runtime that cannot accept image input returns an explicit error.
 
@@ -218,6 +221,15 @@ The final-delivery ledger prevents duplicate successful replies. App Server requ
 
 `agent-bot server start` starts a detached supervisor. The supervisor restarts the worker after unexpected exits and applies exponential backoff from one to 30 seconds after repeated crashes.
 
+Supervisor crash diagnostics are isolated to the selected profile:
+
+- `logs/supervisor.log` permanently records worker PIDs, exit codes, uptime, restart delays, and diagnostic artifact paths.
+- `logs/worker.stderr.log` captures Node/V8 fatal output that would otherwise be lost by the detached process. Both diagnostic logs rotate at 10 MiB with three backups.
+- `data/last-crash.json` points to the latest unexpected worker exit, while timestamped `data/crash-reports/crash-*.json` files preserve the history.
+- `data/crash-reports/report.*.json` contains Node diagnostic reports when Node can generate one.
+
+The supervisor, worker, replacement supervisor, and Console worker enable Node reports for fatal runtime errors and uncaught exceptions by default. Supported Node versions also exclude environment variables and network interfaces so credentials are not copied into reports. Intentional restart exit code `75` and stop exit code `76` do not create crash manifests.
+
 A safe restart waits for:
 
 1. Active tasks to finish
@@ -228,6 +240,8 @@ New messages reset the quiet timer. `--immediate` and `--force` skip these check
 
 The first safe-restart status card is delayed by three seconds so a task's final response can usually arrive first. Status changes during that window are coalesced into the initial card. The delay does not block scheduler polling, and shutdown flushes any pending card immediately.
 
+Pending safe-restart cards include a bottom `Cancel` action. The action carries the scheduler's monotonic schedule ID, so an old card cannot cancel a newer restart. A successful cancellation updates every existing status card in place and removes the action; the action is also absent once the scheduler enters the irreversible restarting phase.
+
 The local control server implements task mutations and service restart requests. Read-only task queries access SQLite directly.
 
 ## Permission Modes

package/docs/technical-reference.zh.md

@@ -33,6 +33,8 @@ 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。
+
 | 默认路径                             | 内容                 |
 | ------------------------------------ | -------------------- |
 | `~/.agent-bot/config.yaml`           | YAML 主配置          |
@@ -43,9 +45,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,11 +62,14 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 - 进程环境变量优先于 `~/.agent-bot/.env`
 - `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须同时存在
+- 一键注册还会把授权用户的 `open_id` 保存为 `FEISHU_USER_OPEN_ID`
 - 除非使用 `--reconfigure-feishu`，完整凭据不会被替换
-- 凭据只有一项时会直接报错，不会静默覆盖
-- 新创建的凭据以原子方式写入 `.env`
+- 缺少凭据或只有一项时会重新创建应用
+- 新创建的凭据经过 fsync、原子替换写入 `.env`，并在配置权限前读回校验
+
+初始化期间会持有 `~/.agent-bot/init.lock`，避免使用不同配置路径的并发命令重复创建应用。进程异常退出遗留的锁会在下次运行时恢复，凭据写入中断留下的临时文件也会被清理。
 
-缺少凭据时，初始化会启动飞书一键创建流程，并以文本和二维码显示验证链接。无论凭据是新创建还是已存在，之后都会检查应用当前已发布版本。
+没有完整凭据时，初始化会启动飞书一键创建流程，并以文本和二维码显示验证链接。注册中的设备码不会恢复：如果进程在完整凭据持久化前退出，下次会重新创建应用。凭据持久化后会检查应用当前已发布版本；这一权限审计阶段中断后可以安全继续。
 
 缺失配置分两阶段处理：
 
@@ -72,6 +78,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 文本。
+
 ## 飞书应用要求
 
 基础消息能力依赖以下核心配置：
@@ -103,10 +111,9 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 ```yaml
 feishu:
-  transport: "auto"
   appId: "${FEISHU_APP_ID}"
   appSecret: "${FEISHU_APP_SECRET}"
-  useConsoleWhenMissingCredentials: true
+  userOpenId: "${FEISHU_USER_OPEN_ID}"
 
 console:
   enabled: true
@@ -131,11 +138,7 @@ logging:
   path: "./logs/agent-bot.log"
 ```
 
-`feishu.transport` 支持：
-
-- `auto`：存在凭据时使用 SDK，否则按 `useConsoleWhenMissingCredentials` 决定是否回退 Console
-- `sdk`：要求飞书凭据并启动长连接客户端
-- `console`：禁用飞书传输
+`agent-bot server start` 要求同时配置飞书 `appId` 和 `appSecret`。Worker 启动 SDK 长连接时不读取 SDK 日志或私有连接状态，随后通过发送启动状态卡片检查出站能力。通知通常发往已知私聊和最近活跃的群聊；数据库里尚无已知会话时，改用 `feishu.userOpenId`，按 `open_id` 私聊发送。存在通知目标时，至少一张卡片发送成功后 Server 才报告就绪，单个目标发送失败仍相互隔离。如果既没有已知会话，也没有 `feishu.userOpenId`，启动会跳过出站检查并继续。缺少凭据时仍会启动失败并提示先初始化。`agent-bot console` 是明确的纯本地入口，不需要飞书凭据。
 
 必须至少配置一个 Agent，`defaults.agent` 必须指向已配置的 Agent。
 
@@ -179,7 +182,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 不支持图片输入时会明确报错。
 
@@ -218,6 +221,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. 活动任务完成
@@ -228,6 +240,8 @@ SQLite 保存：
 
 首次安全重启状态卡会延迟 3 秒发送，让任务最终回答尽可能先到达；延迟期间的状态变化会合并到首张卡片。该延迟不阻塞调度器轮询，真正关闭前会立即 flush 尚未发送的卡片。
 
+等待中的安全重启状态卡底部带有 `Cancel` 操作。回调会携带调度器单调递增的计划 ID，因此旧卡片不会取消较新的重启。取消成功后，所有已发送的状态卡都会原地更新并移除按钮；调度器进入不可逆的正在重启阶段后也不再显示该按钮。
+
 本地控制服务负责修改任务和请求服务重启；只读任务查询直接访问 SQLite。
 
 ## 权限模式

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@keyou007/agent-bot",
-      "version": "0.1.1",
+      "version": "0.1.3",
       "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.3",
   "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,9 +48,20 @@ 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. 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.
+
+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
 
@@ -67,7 +78,7 @@ agent-bot task list
 
 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/FeishuAppRegistration.ts

@@ -16,6 +16,7 @@ export interface FeishuAppRegistrationChallenge {
 export interface FeishuAppCredentials {
   appId: string;
   appSecret: string;
+  userOpenId?: string;
 }
 
 export interface FeishuAppRegistrationOptions {
@@ -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;
     }
 
@@ -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);

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";
@@ -37,15 +39,24 @@ export interface FeishuCredentialState {
   status: FeishuCredentialStatus;
   appId?: string;
   appSecret?: string;
+  userOpenId?: string;
 }
 
 export interface FeishuCredentials {
   appId: string;
   appSecret: string;
+  userOpenId?: 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 +74,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"));
@@ -83,29 +87,112 @@ 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`;
+  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
+      || persisted.userOpenId !== credentials.userOpenId
+    ) {
+      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 +208,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 +246,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;
   }