@keyou007/agent-bot 0.1.2 → 0.1.3

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,6 +62,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 +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 文本。
+
 ## 飞书应用要求
 
 基础消息能力依赖以下核心配置：
@@ -107,6 +113,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 +138,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 +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 不支持图片输入时会明确报错。
 
@@ -214,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. 活动任务完成
@@ -224,6 +240,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.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@keyou007/agent-bot",
-      "version": "0.1.2",
+      "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.2",
+  "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,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:
@@ -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

@@ -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,6 +120,7 @@ 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("飞书凭据写入后校验失败。");
     }

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("agent-bot server 已启动，但未能连接飞书机器人。请检查日志。");
+    }
+    return { status: "started" };
+  }
+
+  dependencies.spawnSupervisor(config);
+  const running = await dependencies.waitUntilRunning(endpoint, SERVER_START_TIMEOUT_MS);
+  if (!running) {
+    throw new Error("已启动 Supervisor，但 server 未在 45 秒内连接飞书机器人。请检查日志。");
+  }
+  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/help.ts

@@ -25,7 +25,7 @@ function renderChineseHelp(version: string): string {
   agent-bot [选项] <命令>
 
 常用命令：
-  init                              初始化配置、数据目录和飞书应用
+  init                              初始化配置和飞书应用，并启动服务
   console                           打开本地 Console
   server start                      在后台启动 Agent Bot
   server status                     查看服务和安全重启状态
@@ -41,6 +41,7 @@ function renderChineseHelp(version: string): string {
   skills install                    安装内置 Skill
 
 选项：
+  --profile <directory>             使用指定目录中的独立 Profile
   --config <path>                   使用指定配置文件
   --json                            在支持的命令中输出 JSON
   -h, --help                        显示帮助
@@ -48,6 +49,7 @@ function renderChineseHelp(version: string): string {
 
 示例：
   agent-bot init
+  agent-bot --profile ~/.agent-bot-rescue init
   agent-bot server start
   agent-bot server status
   agent-bot task list
@@ -63,7 +65,7 @@ Usage:
   agent-bot [options] <command>
 
 Common commands:
-  init                              Initialize config, data directories, and the Lark app
+  init                              Initialize the Lark app and start the service
   console                           Open the local console
   server start                      Start Agent Bot in the background
   server status                     Show server and safe-restart status
@@ -79,6 +81,7 @@ Common commands:
   skills install                    Install the built-in Skill
 
 Options:
+  --profile <directory>             Use an isolated profile directory
   --config <path>                   Use a specific config file
   --json                            Print JSON when supported
   -h, --help                        Show help
@@ -86,6 +89,7 @@ Options:
 
 Examples:
   agent-bot init
+  agent-bot --profile ~/.agent-bot-rescue init
   agent-bot server start
   agent-bot server status
   agent-bot task list

package/src/cli/profile.ts

@@ -0,0 +1,59 @@
+import path from "node:path";
+import {
+  AGENT_BOT_EXPLICIT_PROFILE_ENV,
+  AGENT_BOT_HOME_ENV,
+  DEFAULT_CONFIG_FILE,
+  resolveUserPath,
+} from "../config/paths.js";
+
+export interface ParsedGlobalOptions {
+  args: string[];
+  configPath?: string;
+  profilePath?: string;
+}
+
+export interface AppliedProfile {
+  homePath: string;
+  configPath: string;
+}
+
+export function parseGlobalOptions(input: string[]): ParsedGlobalOptions {
+  const args = [...input];
+  const configPath = removeOption(args, "--config");
+  const profilePath = removeOption(args, "--profile");
+  if (configPath && profilePath) {
+    throw new Error("--profile 和 --config 不能同时使用。Profile 固定使用其目录下的 config.yaml。");
+  }
+  return {
+    args,
+    ...(configPath ? { configPath } : {}),
+    ...(profilePath ? { profilePath } : {}),
+  };
+}
+
+export function applyExplicitProfile(
+  profilePath: string,
+  env: NodeJS.ProcessEnv = process.env,
+  baseDirectory = process.cwd(),
+): AppliedProfile {
+  const homePath = resolveUserPath(profilePath, baseDirectory);
+  const configPath = path.join(homePath, DEFAULT_CONFIG_FILE);
+  env[AGENT_BOT_HOME_ENV] = homePath;
+  env.AGENT_BOT_CONFIG = configPath;
+  env[AGENT_BOT_EXPLICIT_PROFILE_ENV] = "1";
+  delete env.FEISHU_APP_ID;
+  delete env.FEISHU_APP_SECRET;
+  delete env.FEISHU_USER_OPEN_ID;
+  return { homePath, configPath };
+}
+
+function removeOption(args: string[], option: string): string | undefined {
+  const indexes = args.flatMap((value, index) => value === option ? [index] : []);
+  if (indexes.length > 1) throw new Error(`${option} 只能指定一次。`);
+  const index = indexes[0];
+  if (index === undefined) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${option} 需要目录或文件路径。`);
+  args.splice(index, 2);
+  return value;
+}