@zxh126/pi-qqbot 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 本文件记录 pi-qqbot 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [2.0.0] - 2026-10-25
+
+### Added
+
+- **多 QQ bot（一份配置、一台机器、多个 pi 进程）**：配置里用 `qqbots: [...]` 写多组
+  `appId` / `appSecret`，支持 `name`、以及逐账号覆盖 `sandbox` / `allowlist` / `queue` /
+  `progress` / `approve` / `commands`（未写的继承全局默认值，逐键合并）。
+- **自动抢占**：每个 pi 进程启动时（`session_start`）按配置顺序找第一个**未上线**的 bot 接入；
+  抢不到的进程不接入 QQ、但每 5 秒重扫，别人退出后接管。一进程一把锁，绝不并发多接。
+- **「不抢别人 reload 中临时释放的 bot」**：会话重建（`/reload`、`/new`、`/fork`、`/resume`）时，
+  释放锁**之前**写 20 秒预约窗口，其他进程跳过该 bot；抢锁后还会二次读预约记录，
+  撞上就让出（关掉竞态窗口）。新 runtime 用同一 pid 认回自己的 bot，静默不打扰。
+- **身份可见**：接入日志带 bot 名称 / appId / cwd / pid；QQ 首条回执前加「（已接入 qqbot「work」）」；
+  `/status` 首行显示 `bot: work (…0143) · cwd: …`。
+- **换进程接管提示**：`~/.pi/agent/pi-qqbot-<appId>.owner.json` 记录上一位持有者的 pid 与工作目录，
+  换进程时日志写新旧 pid/cwd，QQ 首条回执带「（qqbot「work」已由新实例接管 · 当前工作目录 …）」。
+- `PI_QQBOT_ACCOUNT=<name|appId>` 钉选账号（调试/固定目录用），名字不存在则不接入并写日志。
+- **抢占后先验凭据**：抢到锁立即换一次 `access_token`，失败就**放锁**并跳过该 bot（继续试下一个），
+  避免「凭据写错的 bot 占着锁位但永远连不上」；全部不可用时不空转重扫。
+- **修复** `AuthManager`：QQ 平台对无效凭据返回 HTTP 200 + `code 100016`，以前只拿空 token 去连网关，
+  现在直接抛错（带 code/message），并在抢占阶段被发现。
+- 新增文档 [docs/accounts.md](docs/accounts.md)；新增测试 `test/config.test.mjs`（9）、
+  `test/lock.test.mjs`（8，真子进程 + 真 lockfile，含「同一工作目录也能各接一个」）、
+  `test/accounts.test.mjs`（9，端到端抢占/提示/凭据无效降级）、`test/auth.test.mjs`（3）。
+
+### Changed
+
+- 日志按账号分文件：`~/.pi/agent/pi-qqbot-<name>.log`（同机多进程不再交错）；
+  单 bot 旧格式仍写 `pi-qqbot.log`。
+- `/status` 增加 bot 身份与工作目录行；`/help` 增加多 bot 说明。
+- 配置加载改为 `loadAccounts()`（返回按顺序排好的账号列表），`loadConfig()` 保留为兼容包装。
+
+### Compatibility
+
+- **旧的单 bot 配置零改动可用**（等价于名为 `default` 的账号，行为与 1.5.0 一致）；
+  `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 仍只用于单 bot 场景。
+- 同时写顶层 `appId` 与 `qqbots` → 报错不接入（歧义不猜）；单个账号凭据缺失/`appId` 重复/`name`
+  重复 → 跳过该条并写日志，其余照常。
+- **bot 与工作目录无绑定**：分配只看配置顺序与在线状态，与 cwd 无关——同一目录开多个 pi
+  也照样一人接一个 bot。cwd 仅用于日志、接管提示与 `/status` 展示。
+- 升级后建议重启（或 `/reload`）一次：新版本启动时才会按账号分文件写日志。
+
 ## [1.5.0] - 2026-10-25
 
 ### Added

package/README.md

@@ -19,6 +19,7 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | **Slash-command routing** | QQ messages starting with `/` are routed: pi extension commands, prompt templates and `/skill:name` are dispatched to pi; a set of pi built-ins (`/reload`, `/new`, `/compact`, `/session`, `/name`, `/model`, `/thinking`, `/quit`) is taken over; host-only commands are answered instead of being fed to the model. |
 | **Progress reports** | While a run is in progress the bot posts a short progress summary (turns, tool calls, the tool currently running, tokens) every `progress.intervalMs` (default **15 s**). Ask at any time with `/progress` (aliases `/p`, 「进度」). `/progress off` pauses the automatic reports for the rest of the session, `/progress on` brings them back. If a report cannot be delivered the automatic reports stay quiet until you ask again. |
 | **Secret redaction** | Anything leaving the machine is scrubbed first — progress reports, approval prompts, queue previews and the log file: `Authorization` headers (incl. QQ bot tokens), `sk-…` / `ghp_…` / `npm_…` / `AKIA…` / JWTs / PEM blocks, `token=` / `password=` / `--api-key` values, URL `user:pass@`, and long high-entropy strings. |
+| **Multi-bot on one machine** | Put several QQ bots in one config (`qqbots: [...]`, see [docs/accounts.md](./docs/accounts.md)). Each pi process, in config order, claims the first bot that is not online yet and then verifies its credentials (a wrong secret releases the lock instead of squatting the slot); a process that finds every bot taken stays idle and rescans every 5 s, taking over as soon as one goes offline. A bot whose owner is merely reloading is never snatched (a 20 s reservation is left behind). The bot name is logged, shown in `/status` and prepended to the first QQ reply; taking over from another process also tells you the new working directory. |
 | **Built-in commands** | `/status`, `/queue`, `/progress` (+ `/progress off` / `on`), `/reset`, `/cancel`, `/help`. |
 
 ## Install
@@ -68,7 +69,24 @@ Then create `~/.pi/agent/pi-qqbot.json`:
 | `queue.max` | `20` | How many messages may wait while a task runs; `0` disables queueing (busy messages are refused as before) |
 | `queue.ack` | `true` | Reply to QQ when a queued [message](#queueing-while-busy) starts (the "queued" ack is always sent) |
 
-Credentials can also come from the `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` environment variables.
+Credentials can also come from the `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` environment variables (single-bot setup only).
+
+### Several bots (2.0)
+
+```jsonc
+{
+  "qqbots": [
+    { "name": "work", "appId": "1903340143", "appSecret": "…", "sandbox": true },
+    { "name": "home", "appId": "1020123456", "appSecret": "…" }
+  ],
+  "queue": { "max": 20, "ack": true }   // still the global defaults, per-bot overrides allowed
+}
+```
+
+Every pi process claims the first bot (in config order) that is not online; spare processes stand by and rescan
+every 5 s. After claiming, the credentials are verified by fetching an `access_token`: a bot with a wrong
+`appId`/`appSecret` releases its lock and is skipped instead of squatting the slot. `PI_QQBOT_ACCOUNT=<name|appId>`
+pins one bot instead of auto-claiming. Full details: [docs/accounts.md](./docs/accounts.md).
 
 ## Usage
 
@@ -77,7 +95,7 @@ Start pi, then message the bot in QQ; pi handles it and replies.
 | Command | Description |
 |---|---|
 | `/reset` | Clear the reply buffer, approval memory and session-wide auto-approve (**does not** switch sessions — send `/new` for that) |
-| `/status` | Show busy/idle state, queue length, auto-approve state, pending approval count and the progress-report mode |
+| `/status` | Show the bot this process serves (name + working directory), busy/idle state, queue length, auto-approve state, pending approval count and the progress-report mode |
 | `/queue` | Show the queue (aliases: `/q`); `/queue clear` empties it, `/queue drop <id>` removes one entry |
 | `/progress` | **Show the current progress summary immediately** (aliases: `/p`, 「进度」, 「当前进度」, 「进展」; plain-text questions like 「到哪了」「怎么样了」 work while busy). While you paused reports yourself it only replies once — use `/progress on` to resume; while reports are merely quota-quiet, asking resumes them |
 | `/progress off` | **Pause automatic progress reports for the rest of the session** (aliases: `pause`, `stop`, `暂停`, 「暂停汇报」, 「关闭汇报」). Manual `/progress` still works, it just no longer resumes the timer |
@@ -259,8 +277,10 @@ Semantics:
 The QQ gateway keeps only one active connection per bot. The extension uses a `proper-lockfile` lock at `~/.pi/agent/pi-qqbot-<appId>.lock`:
 
 - the process that acquires the lock becomes the host and connects to QQ;
-- other processes stand by and retry every 5 seconds;
-- when the host exits or crashes (30 second heartbeat timeout), a standby process takes over.
+- other processes stand by, retry every 5 seconds, and claim **any** bot of the list that is free;
+- when the host exits or crashes (30 second heartbeat timeout), a standby process takes over;
+- a host that is only rebuilding its session (`/reload`, `/new`, `/fork`, `/resume`) writes a 20 second reservation next to the lock, so nobody else grabs its bot in the gap;
+- the last owner (pid + working directory) is kept in `~/.pi/agent/pi-qqbot-<appId>.owner.json` and is used to tell you that a **new process** took over, and from which directory.
 
 ## Prerequisites
 
@@ -270,12 +290,12 @@ The QQ gateway keeps only one active connection per bot. The extension uses a `p
 
 ## Logs
 
-Debug logs are written to `~/.pi/agent/pi-qqbot.log`. Each line starts with a **local** timestamp that carries the UTC offset, e.g. `[2026-10-24T07:39:09.762+08:00]`, so it lines up with file mtimes and process start times without mental arithmetic.
+Debug logs are written to `~/.pi/agent/pi-qqbot-<name>.log` (one file per bot, so several pi processes on the same machine never interleave). A single-bot v1 config keeps writing `pi-qqbot.log`. Each line starts with a **local** timestamp that carries the UTC offset, e.g. `[2026-10-24T07:39:09.762+08:00]`, so it lines up with file mtimes and process start times without mental arithmetic.
 
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) — every release with what changed and why. The progress-report
-pause/resume (`/progress off` / `on`) landed in **1.5.0**.
+pause/resume (`/progress off` / `on`) landed in **1.5.0**; multi-bot auto-claiming in **2.0.0**.
 
 ## License
 

package/config.ts

@@ -41,41 +41,178 @@ export interface QQBotConfig {
   progress: ProgressConfig;
 }
 
-export function loadConfig(): QQBotConfig | null {
-  let file: any = {};
+/**
+ * 配置里的一个 QQ bot。
+ *
+ * 除凭据外，所有字段都是「对全局默认值的逐键覆盖」——没写的就继承顶层
+ * `queue` / `progress` / `approve` / `commands` / `sandbox` / `allowlist`。
+ */
+export interface QQBotsEntry {
+  /** 展示名（日志、/status、抢占提示都用它）；缺省 = `bot-<appId 后 6 位>` */
+  name?: string;
+  appId: string;
+  appSecret: string;
+  sandbox?: boolean;
+  allowlist?: string[];
+  markdownReply?: boolean;
+  streaming?: boolean;
+  toolProgress?: boolean;
+  approve?: Partial<ApproveConfig>;
+  commands?: Partial<CommandConfig>;
+  queue?: Partial<QueueConfig>;
+  progress?: Partial<ProgressConfig>;
+}
+
+/** 校验并归一化后的账号（凭据 + 合并好的完整配置） */
+export interface QQBotAccount {
+  name: string;
+  appId: string;
+  /** 该账号最终生效的配置：全局 defaults + 本账号覆盖 */
+  config: QQBotConfig;
+}
+
+export interface LoadAccountsResult {
+  accounts: QQBotAccount[];
+  /** 配置错误：有错误时**不启动网关**，避免「机器人没反应又不知道为什么」 */
+  errors: string[];
+}
+
+const DEFAULT_PROGRESS_MS = 15000;
+
+const asObject = (value: unknown): any =>
+  value && typeof value === "object" && !Array.isArray(value) ? value : {};
+
+function readFile(): any {
   try {
-    file = JSON.parse(fs.readFileSync(CONFIG_PATH(), "utf8"));
+    return asObject(JSON.parse(fs.readFileSync(CONFIG_PATH(), "utf8")));
   } catch {
     /* 文件不存在或非法不致命，凭据可完全来自环境变量 */
+    return {};
   }
-  const appId = process.env.QQ_BOT_APPID ?? file.appId;
-  const appSecret = process.env.QQ_BOT_APPSECRET ?? file.appSecret;
-  if (!appId || !appSecret) return null;
+}
+
+/** 缺省名字：`bot-<appId 后 6 位>`，方便在多 bot 场景里一眼分辨 */
+export function defaultAccountName(appId: string): string {
+  const tail = appId.replace(/[^0-9a-zA-Z]/g, "").slice(-6);
+  return tail ? `bot-${tail}` : "default";
+}
+
+/** 全局 defaults（顶层字段）与账号覆盖合并成一份可直接用的配置 */
+export function resolveConfig(
+  file: any,
+  entry: QQBotsEntry,
+  fallback?: { appId: string; appSecret: string },
+): QQBotConfig {
+  const appId = entry.appId ?? fallback?.appId ?? "";
+  const appSecret = entry.appSecret ?? fallback?.appSecret ?? "";
+  const envInterval = process.env.PI_QQBOT_PROGRESS_MS;
   return {
     appId,
     appSecret,
-    sandbox: file.sandbox ?? false,
-    allowlist: file.allowlist ?? [],
-    markdownReply: file.markdownReply ?? false,
-    streaming: file.streaming ?? false,
-    toolProgress: file.toolProgress ?? false,
+    sandbox: entry.sandbox ?? file.sandbox ?? false,
+    allowlist: entry.allowlist ?? file.allowlist ?? [],
+    markdownReply: entry.markdownReply ?? file.markdownReply ?? false,
+    streaming: entry.streaming ?? file.streaming ?? false,
+    toolProgress: entry.toolProgress ?? file.toolProgress ?? false,
     approve: {
-      tools: file.approve?.tools ?? ["bash", "powershell", "write", "edit"],
-      remember: file.approve?.remember ?? true,
+      tools: entry.approve?.tools ?? file.approve?.tools ?? ["bash", "powershell", "write", "edit"],
+      remember: entry.approve?.remember ?? file.approve?.remember ?? true,
     },
     commands: {
-      passthrough: file.commands?.passthrough ?? DEFAULT_COMMANDS.passthrough,
-      allowReload: file.commands?.allowReload ?? DEFAULT_COMMANDS.allowReload,
-      allowQuit: file.commands?.allowQuit ?? DEFAULT_COMMANDS.allowQuit,
-      allowSession: file.commands?.allowSession ?? DEFAULT_COMMANDS.allowSession,
+      passthrough: entry.commands?.passthrough ?? file.commands?.passthrough ?? DEFAULT_COMMANDS.passthrough,
+      allowReload: entry.commands?.allowReload ?? file.commands?.allowReload ?? DEFAULT_COMMANDS.allowReload,
+      allowQuit: entry.commands?.allowQuit ?? file.commands?.allowQuit ?? DEFAULT_COMMANDS.allowQuit,
+      allowSession: entry.commands?.allowSession ?? file.commands?.allowSession ?? DEFAULT_COMMANDS.allowSession,
     },
     queue: {
-      max: file.queue?.max ?? DEFAULT_QUEUE_MAX,
-      ack: file.queue?.ack ?? true,
+      max: entry.queue?.max ?? file.queue?.max ?? DEFAULT_QUEUE_MAX,
+      ack: entry.queue?.ack ?? file.queue?.ack ?? true,
     },
     progress: {
-      enabled: file.progress?.enabled ?? true,
-      intervalMs: Number(process.env.PI_QQBOT_PROGRESS_MS ?? file.progress?.intervalMs ?? 15000),
+      enabled: entry.progress?.enabled ?? file.progress?.enabled ?? true,
+      intervalMs: Number(
+        envInterval ?? entry.progress?.intervalMs ?? file.progress?.intervalMs ?? DEFAULT_PROGRESS_MS,
+      ),
     },
   };
 }
+
+/**
+ * 读配置，返回**按配置顺序**排好的账号列表。
+ *
+ * 支持两种格式：
+ * - v2 多 bot：`{ "qqbots": [ { "name": "work", "appId": … }, … ], "queue": {…}, … }`
+ * - v1 单 bot：`{ "appId": …, "appSecret": …, … }`（或全部来自 `QQ_BOT_APPID/SECRET`），
+ *   等价于只有一个名叫 `default` 的账号，行为与 1.x 完全一致。
+ */
+export function loadAccounts(): LoadAccountsResult {
+  const file = readFile();
+  const errors: string[] = [];
+  const envAppId = process.env.QQ_BOT_APPID;
+  const envAppSecret = process.env.QQ_BOT_APPSECRET;
+
+  let entries: QQBotsEntry[];
+  if (Array.isArray(file.qqbots)) {
+    if (file.appId) {
+      errors.push("配置里同时出现顶层 appId 和 qqbots 数组：请只保留一种格式（多 bot 请写进 qqbots）");
+      return { accounts: [], errors };
+    }
+    entries = file.qqbots.map((item: any) => asObject(item));
+    if (entries.length === 0) {
+      errors.push("qqbots 是空数组：至少配置一个 bot，否则插件不会接入 QQ");
+      return { accounts: [], errors };
+    }
+  } else if (file.appId || envAppId) {
+    entries = [
+      {
+        name: "default",
+        appId: envAppId ?? file.appId,
+        appSecret: envAppSecret ?? file.appSecret,
+      },
+    ];
+  } else {
+    return { accounts: [], errors };
+  }
+
+  const accounts: QQBotAccount[] = [];
+  const seenNames = new Set<string>();
+  const seenAppIds = new Set<string>();
+
+  for (let index = 0; index < entries.length; index += 1) {
+    const raw = asObject(entries[index]);
+    const appId = String(raw.appId ?? "").trim();
+    const appSecret = String(raw.appSecret ?? "").trim();
+    const label = `qqbots[${index}]${raw.name ? `(name=${raw.name})` : ""}`;
+    if (!appId || !appSecret) {
+      // 单个账号缺凭据只跳过它，别让整个插件都起不来
+      errors.push(`${label} 缺少 appId 或 appSecret，已跳过`);
+      continue;
+    }
+    if (seenAppIds.has(appId)) {
+      errors.push(`${label} 的 appId ${appId} 重复，已跳过（否则会双连接被平台踢）`);
+      continue;
+    }
+    const name = String(raw.name ?? defaultAccountName(appId)).trim() || defaultAccountName(appId);
+    if (seenNames.has(name)) {
+      errors.push(`${label} 的 name "${name}" 与其他 bot 重复，已跳过（改名后重试）`);
+      continue;
+    }
+    seenAppIds.add(appId);
+    seenNames.add(name);
+    accounts.push({ name, appId, config: resolveConfig(file, raw) });
+  }
+
+  return { accounts, errors };
+}
+
+/** 兼容旧调用：只取第一个账号的配置（1.x 单 bot 语义） */
+export function loadConfig(): QQBotConfig | null {
+  const { accounts } = loadAccounts();
+  return accounts[0]?.config ?? null;
+}
+
+/** 环境变量指定的账号名（调试/测试用：钉住某个 bot，不参与自动抢占） */
+export function pinnedAccountName(): string | null {
+  const name = process.env.PI_QQBOT_ACCOUNT?.trim();
+  return name ? name : null;
+}

package/constants.ts

@@ -20,3 +20,8 @@ const PI_DIR = path.join(os.homedir(), ".pi", "agent");
 export const PI_AGENT_DIR = PI_DIR;
 export const CONFIG_PATH = () => path.join(PI_DIR, "pi-qqbot.json");
 export const LOCK_PATH = (appId: string) => path.join(PI_DIR, `pi-qqbot-${appId}.lock`);
+/** 记录「谁占着这个 bot」：pid/cwd/账号名 + 临时释放的预约窗口（换进程时用来生成提示） */
+export const OWNER_PATH = (appId: string) => path.join(PI_DIR, `pi-qqbot-${appId}.owner.json`);
+/** 日志文件（按账号分文件：多进程同机时不交错） */
+export const LOG_PATH = (account: string, legacy = false) =>
+  path.join(PI_DIR, legacy ? "pi-qqbot.log" : `pi-qqbot-${account}.log`);

package/docs/README.zh-CN.md

@@ -19,6 +19,7 @@
 | **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
 | **进度汇报** | 任务运行期间按 `progress.intervalMs`（默认 **15 秒**）推一条进度摘要（轮次、工具调用、正在跑的工具、token 用量）。随时发 `/progress`（别名 `/p`、「进度」）可立即获取；`/progress off` 在本会话内暂停自动汇报，`/progress on` 恢复。推送失败后自动推送静默，直到你再次问询。 |
 | **敏感信息脱敏** | 离开本机的文本先脱敏——进度摘要、审批提示、队列预览、日志文件：`Authorization` 头（含 QQ bot token）、`sk-…`/`ghp_…`/`npm_…`/`AKIA…`/JWT/PEM、`token=`/`password=`/`--api-key` 的值、URL 里的 `user:pass@`，以及超长高熵串。 |
+| **多 bot 同机** | 一份配置里写多个 QQ bot（`qqbots: [...]`，详见 [accounts.md](./accounts.md)），同一台机器上每个 pi 进程按配置顺序接入第一个未上线的 bot；全部在线则待命、每 5 秒重扫，有人退出就接管。别人只是 `/reload` 临时释放的 bot 不会被抢（留 20 秒预约窗口）。接入/接管时会告知当前 bot 名称与工作目录。 |
 | **内置指令** | `/status`、`/queue`、`/progress`、`/reset`、`/cancel`、`/help`。 |
 
 ## 安装
@@ -68,7 +69,22 @@ pi install ./pi-qqbot
 | `progress.enabled` | `true` | 任务运行期间是否定期推送进度摘要（会话启动时读取，改完需 `/new` 或重启；运行时用 `/progress off`） |
 | `progress.intervalMs` | `15000` | 推送间隔（可用环境变量 `PI_QQBOT_PROGRESS_MS` 覆盖，便于测试） |
 
-也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
+也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据（仅单 bot 场景）。
+
+### 多个 bot（2.0）
+
+```jsonc
+{
+  "qqbots": [
+    { "name": "work", "appId": "1903340143", "appSecret": "…", "sandbox": true },
+    { "name": "home", "appId": "1020123456", "appSecret": "…" }
+  ],
+  "queue": { "max": 20, "ack": true }   // 这里仍是全局默认，qqbots 内可逐键覆盖
+}
+```
+
+多个 pi 进程按配置顺序各自接入一个未上线的 bot，抢不到的待命并每 5 秒重扫；
+`PI_QQBOT_ACCOUNT=<name|appId>` 可以钉住某个 bot，不走自动抢占。细节见 [accounts.md](./accounts.md)。
 
 ## 使用
 
@@ -77,7 +93,7 @@ pi install ./pi-qqbot
 | 指令 | 说明 |
 |---|---|
 | `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
-| `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量、自动汇报模式 |
+| `/status` | 查看本进程服务的 bot（名称 + 工作目录）、忙闲状态、队列长度、自动同意状态、待审批数量、自动汇报模式 |
 | `/queue` | 查看队列（别名 `/q`）；`/queue clear` 清空，`/queue drop <编号>` 删一条 |
 | `/progress` | **立即获取当前进度摘要**（别名 `/p`、「进度」「当前进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效）。手动暂停期间**问一次只回一次**，要重新打开定时汇报需发 `/progress on` 或「恢复汇报」；若只是配额静默，问一次即恢复 |
 | `/progress off` | **在本会话内暂停自动进度汇报**（别名：`pause`、`stop`、`暂停`、「暂停汇报」、「关闭汇报」）。手动 `/progress` 仍可看一次，但不再解除暂停 |
@@ -245,8 +261,10 @@ pi 的会话一次只跑一轮 agent run，所以串行调度由 bot 自己做
 QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile` 文件锁（`~/.pi/agent/pi-qqbot-<appId>.lock`）：
 
 - 抢到锁的进程 = 宿主，连接 QQ；
-- 其余进程待命，每 5 秒重试；
-- 宿主退出或崩溃（30 秒心跳超时）后，待命进程自动接管。
+- 其余进程待命，每 5 秒重扫，**列表里任何一个空闲的 bot** 都能抢；
+- 宿主退出或崩溃（30 秒心跳超时）后，待命进程自动接管；
+- 只是重建会话（`/reload`、`/new`、`/fork`、`/resume`）的宿主会在锁旁留 20 秒预约，别人不会趁空抢走；
+- 上一位持有者的 pid 与工作目录记在 `~/.pi/agent/pi-qqbot-<appId>.owner.json`，用来提示「换进程接管」以及新实例的工作目录。
 
 ## 前置条件
 
@@ -256,11 +274,11 @@ QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile`
 
 ## 日志
 
-调试日志写入 `~/.pi/agent/pi-qqbot.log`。每行开头是**本地时间 + 时区偏移**（如 `[2026-10-24T07:39:09.762+08:00]`），和文件 mtime、进程启动时间直接对得上，不需要再拿 UTC 换算。
+调试日志写入 `~/.pi/agent/pi-qqbot-<name>.log`（按 bot 分文件，同机多进程不交错）；单 bot 旧格式仍写 `pi-qqbot.log`。每行开头是**本地时间 + 时区偏移**（如 `[2026-10-24T07:39:09.762+08:00]`），和文件 mtime、进程启动时间直接对得上，不需要再拿 UTC 换算。
 
 ## 变更日志
 
-见 [CHANGELOG.md](../CHANGELOG.md)：每个版本改了什么、为什么改。进度汇报的暂停/恢复（`/progress off` / `on`）在 **1.5.0** 加入。
+见 [CHANGELOG.md](../CHANGELOG.md)：每个版本改了什么、为什么改。进度汇报的暂停/恢复（`/progress off` / `on`）在 **1.5.0** 加入；多 bot 自动抢占在 **2.0.0**。
 
 ## License
 

package/docs/accounts.md

@@ -0,0 +1,88 @@
+# 多 QQ bot（2.0）
+
+一份配置里可以写多个 QQ bot；同一台机器上每个 pi 进程启动时，按配置顺序找**第一个没上线的**
+bot 接入，抢不到的进程待命并每 5 秒重扫。进程退出（或崩溃导致的锁心跳超时）后，该 bot 下线，
+待命进程接管。
+
+## 配置
+
+### 多 bot（v2）
+
+```jsonc
+// ~/.pi/agent/pi-qqbot.json
+{
+  "qqbots": [
+    { "name": "work", "appId": "1903340143", "appSecret": "……", "sandbox": true },
+    { "name": "home", "appId": "1020123456", "appSecret": "……", "sandbox": false }
+  ],
+
+  // 以下是全局默认值，qqbots 里可以逐键覆盖
+  "queue": { "max": 20, "ack": true },
+  "progress": { "enabled": true, "intervalMs": 15000 }
+}
+```
+
+- **顺序就是抢占顺序**：先起的进程拿 `work`，第二个进程拿 `home`，第三个进程抢不到就待命。
+- `name` 缺省为 `bot-<appId 后 6 位>`；日志、`/status`、接管提示都用它。
+- `name` 或 `appId` 重复、凭据缺失 → 该条被跳过并写日志，其余照常可用（不会双连接同一个 bot）。
+- 同时写顶层 `appId` 和 `qqbots` → 报错，插件不接入（歧义不猜）。
+
+### 单 bot（v1，原格式，无需改动）
+
+```json
+{ "appId": "1903340143", "appSecret": "……", "sandbox": true }
+```
+
+等价于只有一个名叫 `default` 的 bot，行为与 1.x 完全一致。凭据也仍可来自
+`QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 环境变量（只用于单 bot 场景）。
+
+## 实例身份
+
+| 场景 | 表现 |
+|---|---|
+| 首次接入 | 日志 `[lock] 接入 qqbot "work" (1903340143) · cwd=E:\Projects\foo · pid=1234`；QQ 首条回执前加「（已接入 qqbot「work」）」；`/status` 显示 `bot: work (…0143) · cwd: …` |
+| 换进程接管 | 日志记录新旧 pid 与新旧 cwd；QQ 首条回执前加「（qqbot「work」已由新实例接管 · 当前工作目录 E:\Projects\foo）」 |
+| 全部在线 | 日志 `[lock] 无可接入的 qqbot（…），本进程待命，5s 后重扫`；本进程不连 QQ，pi 本身照常用 |
+| 会话重建（`/reload`、`/new`、`/fork`、`/resume`） | 释放锁**之前**先写 20 秒预约窗口，其他进程不会趁机抢走；新 runtime 用自己的 pid 认回同一个 bot，静默不打扰 |
+| 凭据无效 | 抢到锁后先换一次 `access_token`；失败就**放锁跳过该 bot**（不占槽位），继续试下一个。日志：`[lock] qqbot "x" 凭据不可用：code=100016 invalid appid or secret → 已放锁并跳过该 bot`。全部不可用时不空转重扫 |
+
+`/status` 一眼确认：
+
+```
+bot: work (…0143) · cwd: E:\Projects\foo
+状态: 空闲
+```
+
+> **工作目录与 bot 无绑定。** 分配只看「配置顺序 + 谁在线」，跟 cwd 无关：
+> 同一台机器上可以在不同的项目目录各开一个 pi，也可以在一个大工作区（里面好几个项目）里
+> 同时开几个 pi——后者照样一人接一个 bot，互不干扰。cwd 只用于日志、接管提示和 `/status` 展示，
+> 让你能分辨「现在是哪个实例在管这个 bot」。
+
+## 可选：钉住某个 bot
+
+自动抢占是默认行为。调试或需要「这个目录固定用某个 bot」时，用环境变量钉住：
+
+```powershell
+$env:PI_QQBOT_ACCOUNT = "work"; pi
+```
+
+钉选时只尝试该账号（可写 name 或 appId）；名字不存在则**不接入**并写日志（不会乱接别的 bot）。
+
+## 能/不能
+
+- **能**：同一台机器上开 N 个 pi，各接一个 bot，互不串话；目录随意（同一目录开多个也成立，目录只是 pi 的工作区）；某个 pi 退出后由待命进程接管。
+- **能**：一个 bot 同一时刻只有一个进程连着（锁 + 心跳 + 30 秒僵尸锁回收）。
+- **不能**：一个 pi 进程同时服务多个 bot（扩展的 session 是单租户模型）。要多路并行就多开 pi 进程。
+
+## 日志
+
+多 bot 场景下日志按账号分文件：`~/.pi/agent/pi-qqbot-<name>.log`（单 bot 旧格式仍写
+`pi-qqbot.log`）。身份记录与锁在 `~/.pi/agent/pi-qqbot-<appId>.lock` / `…owner.json`。
+
+## 排查：某个 bot 一直不上线
+
+1. 看日志：`凭据不可用：code=100016 invalid appid or secret` → appId/secret 写错了
+   （可用 `POST https://api.bot.qq.com/app/getAppAccessToken` 自己验一下）；
+2. 看日志：`本轮无可接入的 qqbot（x:在线）` → 这个 bot 已被别的 pi 进程连着；
+3. 看日志：`被 pid 1234 重载中` → 对方正在 `/reload`，等几秒即可；
+4. 什么都没打 → 确认配置能解析（`loadAccounts()` 报错会写 `[setup] 配置问题:`）。

package/index.ts

@@ -1,17 +1,16 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { loadConfig, QQBotConfig } from "./config";
+import { loadAccounts, pinnedAccountName, type QQBotAccount, type QQBotConfig } from "./config";
 import {
   REST_BASE_PROD,
   REST_BASE_SANDBOX,
   INTENT_GROUP_AND_C2C,
   PASSIVE_WINDOW_MS,
   APPROVAL_TIMEOUT_MS,
-  LOCK_PATH,
   DISPATCH_RETRY_MS,
   CANCEL_SETTLE_GRACE_MS,
 } from "./constants";
-import { log } from "./logger";
-import { tryAcquireLock, startLockRetry } from "./lock";
+import { log, configureLog } from "./logger";
+import { claimAny, startClaimRetry, reserveBeforeRelease, readOwner, type Claim } from "./lock";
 import { AuthManager } from "./qq/auth";
 import { QQApi } from "./qq/api";
 import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
@@ -25,6 +24,12 @@ import { splitText } from "./util/chunk";
 
 interface State {
   cfg: QQBotConfig | null;
+  /** 本进程当前服务的 QQ bot（自动抢占的结果）；未接入则为 null */
+  account: { name: string; appId: string } | null;
+  /** 本进程的候选 bot（按配置顺序），待命时用它重扫 */
+  candidates: { name: string; appId: string }[];
+  /** 首条回执前缀（接入成功 / 换进程接管时告知用户当前 bot 与工作目录） */
+  claimNote: string | null;
   api: QQApi | null;
   approver: Approver;
   gateway: QQGateway | null;
@@ -94,13 +99,22 @@ export function createInitialState(): State {
     progressPaused: false,
     progressMuted: false,
     undelivered: null,
+    account: null,
+    candidates: [],
+    claimNote: null,
   };
 }
 
 export default function (
   pi: ExtensionAPI,
   /** 仅测试用：注入状态，让事件处理器与 handleMessage 共享同一份状态 */
-  options?: { state?: State },
+  options?: {
+    state?: State;
+    /** 仅测试用：不真连 QQ 网关（避免单测打网络），其余流程（抢锁/身份/提示）照常 */
+    disableGateway?: boolean;
+    /** 仅测试用：替换「抢到锁后验凭据」的实现（默认真的去换 access_token） */
+    verifyCredentials?: (account: QQBotAccount) => Promise<AuthManager>;
+  },
 ) {
   const state: State = options?.state ?? createInitialState();
 
@@ -235,69 +249,205 @@ export default function (
     return { block: true, reason: `QQ 用户拒绝了 ${summary}` };
   });
 
-  // ---- 事件：session_start 抢锁 + 启动网关 ----
-  pi.on("session_start", async () => {
-    const cfg = loadConfig();
-    if (!cfg) {
-      log("[setup] 缺少 QQ_BOT_APPID/QQ_BOT_APPSECRET 或配置，插件未启用");
+  // ---- 事件：session_start 选/抢 qqbot + 启动网关 ----
+  pi.on("session_start", async (event) => {
+    const { accounts, errors } = loadAccounts();
+    for (const message of errors) log("[setup] 配置问题:", message);
+    if (accounts.length === 0) {
+      log("[setup] 未配置 QQ bot（或配置不可用），插件未启用");
       return;
     }
-    state.cfg = cfg;
+
+    // 会话重建（/reload、/new…）时优先沿用自己的 bot：上一轮释放前写了 owner 记录
+    const pin = pinnedAccountName();
+    const pool: QQBotAccount[] = pin
+      ? accounts.filter((a) => a.name === pin || a.appId === pin)
+      : accounts;
+    if (pool.length === 0) {
+      log("[setup] PI_QQBOT_ACCOUNT=", pin, "不在配置里（可选:", accounts.map((a) => a.name).join(", "), "），插件未启用");
+      return;
+    }
+    state.candidates = pool.map((a) => ({ name: a.name, appId: a.appId }));
+
+    const ownPid = process.pid;
+    const preferredAppId = state.candidates
+      .map((c) => readOwner(c.appId))
+      .find((owner) => owner?.pid === ownPid)?.appId;
+
     // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
     state.approver.reset();
     // 手动暂停的自动汇报同样只在本会话有效
     state.progressMuted = false;
     state.progressPaused = false;
-    // 队列上限来自配置；新会话不继承上一个会话遗留的待执行任务
-    state.queue.setLimit(cfg.queue.max);
     state.queue.clear();
-    log("[setup] 配置已加载 sandbox=", cfg.sandbox, "queue.max=", cfg.queue.max);
 
-    const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
-    const auth = new AuthManager(cfg.appId, cfg.appSecret);
-    const api = new QQApi({ restBase, getToken: () => auth.getToken() });
-    state.api = api;
+    // 凭据不可用的 bot 在本次会话内不再尝试（配置在 session_start 读取，改完 /reload 才生效）
+    const unusable = new Set<string>();
+    const verifyAccount =
+      options?.verifyCredentials ??
+      (async (account: QQBotAccount) => {
+        const auth = new AuthManager(account.appId, account.config.appSecret);
+        await auth.getToken(); // 抢到锁之后先验凭据，失败就不占着这个槽位
+        return auth;
+      });
+
+    const applyClaim = (claim: Claim, account: QQBotAccount, auth: AuthManager) => {
+      const cfg = account.config;
+      state.cfg = cfg;
+      state.account = { name: account.name, appId: account.appId };
+      state.releaseLock = claim.release;
+      // 只有一个 bot（含 v1 旧配置）→ 继续写旧文件名，升级后日志不断线
+      configureLog(accounts.length === 1 ? null : account.name);
+      state.queue.setLimit(cfg.queue.max);
+      log(
+        "[setup] 配置已加载 bot=",
+        `"${account.name}"`,
+        "appId=",
+        account.appId,
+        "sandbox=",
+        cfg.sandbox,
+        "queue.max=",
+        cfg.queue.max,
+        "reason=",
+        (event as any)?.reason ?? "startup",
+      );
 
-    const startGateway = () => {
+      // 提示：接入成功 / 换进程接管（后者一定要带工作目录）
+      const cwd = process.cwd();
+      if (claim.takeover && claim.previous) {
+        log(
+          "[lock] qqbot",
+          `"${account.name}"`,
+          "换进程接管: pid",
+          claim.previous.pid,
+          "→",
+          process.pid,
+          "· cwd",
+          claim.previous.cwd || "?",
+          "→",
+          cwd,
+        );
+        state.claimNote = `（qqbot「${account.name}」已由新实例接管 · 当前工作目录 ${cwd}）`;
+      } else if (claim.reclaimed) {
+        log("[lock] 重新接入自己的 qqbot（同进程会话重建）");
+      } else {
+        log("[lock] 接入 qqbot", `"${account.name}"`, `(${account.appId})`, "· cwd=", cwd, "· pid=", process.pid);
+        state.claimNote = `（已接入 qqbot「${account.name}」）`;
+      }
+
+      const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
+      const api = new QQApi({ restBase, getToken: () => auth.getToken() });
+      state.api = api;
+
+      if (options?.disableGateway) {
+        log("[setup] 测试模式：跳过 QQ 网关");
+        return;
+      }
       const gateway = new QQGateway({
         getGatewayUrl: createGatewayUrlFetcher(restBase, () => auth.getToken()),
         getToken: () => auth.getToken(),
         intents: INTENT_GROUP_AND_C2C,
         connected: () => {},
         disconnected: () => {},
-        message: (msg) => handleMessage(pi, state, api, cfg, msg),
+        message: (msg) => handleMessage(pi, state, api, state.cfg ?? cfg, msg),
       });
       state.gateway = gateway;
       log("[lock] 启动 QQ 网关");
       gateway.start();
     };
 
-    // 单实例锁：只有抢到锁的实例连接 QQ
-    const lockPath = LOCK_PATH(cfg.appId);
-    const release = await tryAcquireLock(lockPath);
-    if (release) {
-      state.releaseLock = release;
-      log("[lock] 抢锁成功，本实例为 QQ bot 宿主");
-      startGateway();
-    } else {
-      log("[lock] 锁被占用，本实例进入待命");
-      state.stopRetry = startLockRetry(lockPath, (r) => {
-        state.releaseLock = r;
-        log("[lock] 抢锁成功，接管 QQ bot");
-        startGateway();
-      });
-    }
+    // 抢一个、验一下凭据、验不过就放锁换下一个
+    const tryClaimOnce = async (): Promise<boolean> => {
+      const remaining = state.candidates.filter((c) => !unusable.has(c.appId));
+      if (remaining.length === 0) return false;
+      const result = await claimAny(remaining, { preferredAppId });
+      if (!result.claim) {
+        const detail = result.skipped
+          .map(
+            (s) =>
+              `${s.name}:${s.reason === "online" ? "在线" : s.reason === "reserved" ? `被 pid ${s.owner?.pid} 重载中` : "刚被抢走"}`,
+          )
+          .join(", ");
+        log("[lock] 本轮无可接入的 qqbot（", detail, "）");
+        return false;
+      }
+      const claim = result.claim;
+      const account = pool.find((a) => a.appId === claim.appId);
+      if (!account) {
+        await claim.release().catch(() => {});
+        unusable.add(claim.appId);
+        return tryClaimOnce();
+      }
+      try {
+        const auth = await verifyAccount(account);
+        applyClaim(claim, account, auth);
+        return true;
+      } catch (e) {
+        await claim.release().catch(() => {});
+        unusable.add(account.appId);
+        log(
+          "[lock] qqbot",
+          `"${account.name}"`,
+          "凭据不可用：",
+          String(e).slice(0, 160),
+          "→ 已放锁并跳过该 bot（改好配置后 /reload 再试）",
+        );
+        return tryClaimOnce();
+      }
+    };
+
+    // 待命：还有「可能变可用」的候选就 5s 重扫——否则别人退出后没人接管
+    const enterStandby = () => {
+      if (!state.candidates.some((c) => !unusable.has(c.appId))) {
+        log("[lock] 没有可接入的 qqbot（其余在线或凭据不可用），本进程不接入 QQ");
+        return;
+      }
+      log("[lock] 本进程待命，5s 后重扫");
+      state.stopRetry = startClaimRetry(
+        () => state.candidates.filter((c) => !unusable.has(c.appId)),
+        (claim) => {
+          state.stopRetry = null;
+          void (async () => {
+            const account = pool.find((a) => a.appId === claim.appId);
+            if (!account || state.gateway) {
+              await claim.release().catch(() => {});
+              enterStandby();
+              return;
+            }
+            try {
+              const auth = await verifyAccount(account);
+              applyClaim(claim, account, auth);
+            } catch (e) {
+              await claim.release().catch(() => {});
+              unusable.add(account.appId);
+              log("[lock] qqbot", `"${account.name}"`, "凭据不可用：", String(e).slice(0, 160), "→ 放锁继续待命");
+              enterStandby();
+            }
+          })();
+        },
+        { preferredAppId },
+      );
+    };
+
+    if (await tryClaimOnce()) return;
+    enterStandby();
   });
 
   // ---- 事件：session_shutdown 清理 ----
-  pi.on("session_shutdown", async () => {
-    log("[shutdown] 清理资源");
+  pi.on("session_shutdown", async (event) => {
+    const reason = String((event as any)?.reason ?? "quit");
+    log("[shutdown] 清理资源 reason=", reason);
     clearCancelTimer(state);
     stopProgressTimer(state);
     const dropped = state.queue.clear();
     if (dropped.length > 0) log("[shutdown] 丢弃队列任务", dropped.length, "条");
     if (state.stopRetry) state.stopRetry();
     state.gateway?.stop();
+    // reload/new/fork/resume 只是「本进程换会话」，马上会重新接入：先贴预约，别让别人抢走
+    if (state.account && state.releaseLock && reason !== "quit") {
+      reserveBeforeRelease(state.account, reason);
+      log("[lock] qqbot", `"${state.account.name}"`, "临时释放（reason=", reason, "），已留预约窗口");
+    }
     if (state.releaseLock) {
       try {
         await state.releaseLock();
@@ -308,6 +458,7 @@ export default function (
     state.releaseLock = null;
     state.gateway = null;
     state.api = null;
+    state.account = null;
   });
 
   // ---- /qq：QQ 侧命令的桥接入口 ----
@@ -726,13 +877,14 @@ export async function handleMessage(
         [
           "pi-qqbot 指令:",
           "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
-          "/status — 查看状态（忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
+          "/status — 查看状态（当前 qqbot / 忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
           "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
           "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
           "/cancel（或「取消」「停止」）— 中断正在运行的任务并清空队列",
           "/help — 帮助",
           "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
           "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
+          "多 bot：配置了多个 qqbot 时，多个 pi 进程会按列表顺序各自接入一个，抢不到的待命重扫。",
           "其余文本交给 pi 当作对话处理。",
         ].join("\n"),
       );
@@ -740,6 +892,7 @@ export async function handleMessage(
     }
     if (cmd?.name === "status") {
       const lines = [
+        `bot: ${state.account ? `${state.account.name} (…${state.account.appId.slice(-4)})` : "未接入"} · cwd: ${process.cwd()}`,
         `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
         `队列: ${state.queue.size} 条待执行${state.queue.size > 0 ? "（发 /queue 查看）" : ""}`,
         `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
@@ -848,6 +1001,12 @@ async function replyTo(
   text: string,
   format: "text" | "markdown" = "text",
 ): Promise<boolean> {
+  // 本进程刚接入 / 刚接管这个 qqbot：第一条回执带上身份与工作目录
+  if (state.claimNote) {
+    const note = state.claimNote;
+    state.claimNote = null;
+    text = `${note}\n${text}`;
+  }
   const ref = state.passiveRefs.get(openid);
   let delivered = true;
   for (const chunk of splitText(text)) {

package/lock.ts

@@ -1,11 +1,63 @@
+import fs from "node:fs";
 import lockfile from "proper-lockfile";
+import { LOCK_PATH, OWNER_PATH } from "./constants";
 
 const LOCK_RETRY_MS = 5000; // 待命实例抢锁间隔
 const LOCK_STALE_MS = 30000; // 锁文件超过 30 秒无心跳视为僵尸锁
 const LOCK_UPDATE_MS = 10000; // 宿主每 10 秒心跳刷新锁
+/**
+ * 「临时释放」的预约窗口：本进程 `/reload`、`/new` 这类会话重建时，锁会先释放再重新抢。
+ * 这段时间内别的进程不许来抢，否则同一台机器上的另一个 pi 会把 bot 抢走。
+ */
+export const DEFAULT_RESERVE_MS = 20000;
 
 type Release = () => Promise<void>;
 
+/** 一个 bot 当前/最后一位持有者的记录（放在锁旁边，进程退出后不删） */
+export interface LockOwner {
+  account: string;
+  appId: string;
+  pid: number;
+  /** 持有者启动时的工作目录（换进程提示要用） */
+  cwd: string;
+  claimedAt: string;
+  /** 仅「临时释放」时写：谁在重载 */
+  releasedAt?: string;
+  /** 临时释放的原因（reload/new/fork/resume） */
+  releaseReason?: string;
+  /** 预约到期时间（epoch ms）：到点前其他进程不得抢占 */
+  reservedUntil?: number;
+}
+
+export interface ClaimCandidate {
+  name: string;
+  appId: string;
+}
+
+export interface Claim {
+  name: string;
+  appId: string;
+  release: Release;
+  /** 抢到之前的持有者记录（没有则 null） */
+  previous: LockOwner | null;
+  /** 是否「换进程接管」（previous.pid 存在且不是自己） */
+  takeover: boolean;
+  /** 是否是「自己临时释放后又拿回来」（/reload 场景，静默） */
+  reclaimed: boolean;
+}
+
+export interface ClaimSkip {
+  name: string;
+  reason: "online" | "reserved" | "raced";
+  /** reserved 时用于日志：谁在重载 */
+  owner?: LockOwner;
+}
+
+export interface ClaimResult {
+  claim?: Claim;
+  skipped: ClaimSkip[];
+}
+
 /** 抢文件锁：成功返回 release 函数；被占/异常返回 null */
 export async function tryAcquireLock(lockPath: string): Promise<Release | null> {
   try {
@@ -21,6 +73,7 @@ export async function tryAcquireLock(lockPath: string): Promise<Release | null>
   }
 }
 
+/** 抢锁+心跳刷新的组合：保持旧导出名，供单 bot 场景与测试使用 */
 export function startLockRetry(lockPath: string, onAcquired: (release: Release) => void): () => void {
   const timer = setInterval(async () => {
     const release = await tryAcquireLock(lockPath);
@@ -31,3 +84,154 @@ export function startLockRetry(lockPath: string, onAcquired: (release: Release)
   }, LOCK_RETRY_MS);
   return () => clearInterval(timer);
 }
+
+export function readOwner(appId: string): LockOwner | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(OWNER_PATH(appId), "utf8"));
+    if (!raw || typeof raw !== "object") return null;
+    return {
+      account: String(raw.account ?? ""),
+      appId: String(raw.appId ?? appId),
+      pid: Number(raw.pid ?? 0),
+      cwd: String(raw.cwd ?? ""),
+      claimedAt: String(raw.claimedAt ?? ""),
+      releasedAt: raw.releasedAt ? String(raw.releasedAt) : undefined,
+      releaseReason: raw.releaseReason ? String(raw.releaseReason) : undefined,
+      reservedUntil: Number.isFinite(raw.reservedUntil) ? Number(raw.reservedUntil) : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeOwner(appId: string, owner: LockOwner): void {
+  try {
+    fs.writeFileSync(OWNER_PATH(appId), JSON.stringify(owner, null, 2), "utf8");
+  } catch {
+    /* owner 记录只是观测量，写不进去不能影响接入 */
+  }
+}
+
+/** 接入成功后落盘身份（同时清掉上一次的临时释放预约） */
+export function recordClaim(input: { name: string; appId: string }, now = Date.now()): LockOwner {
+  const owner: LockOwner = {
+    account: input.name,
+    appId: input.appId,
+    pid: process.pid,
+    cwd: process.cwd(),
+    claimedAt: new Date(now).toISOString(),
+  };
+  writeOwner(input.appId, owner);
+  return owner;
+}
+
+/**
+ * 「我要暂时放开，别来抢」：给其他进程留下预约窗口。
+ * 只在会话重建（reload/new/fork/resume）时调用；真正退出（quit/崩溃）什么都不写，
+ * 让别人立刻能接管。
+ */
+export function reserveBeforeRelease(
+  input: { name: string; appId: string },
+  reason: string,
+  now = Date.now(),
+  reserveMs = DEFAULT_RESERVE_MS,
+): LockOwner | null {
+  const prev = readOwner(input.appId);
+  const owner: LockOwner = {
+    account: input.name,
+    appId: input.appId,
+    pid: process.pid,
+    cwd: process.cwd(),
+    claimedAt: prev?.claimedAt ?? new Date(now).toISOString(),
+    releasedAt: new Date(now).toISOString(),
+    releaseReason: reason,
+    reservedUntil: now + reserveMs,
+  };
+  writeOwner(input.appId, owner);
+  return owner;
+}
+
+/** 该 bot 此刻是否被别人预约着（临时释放窗口内） */
+function reservedByOther(owner: LockOwner | null, now: number): boolean {
+  if (!owner?.reservedUntil) return false;
+  if (owner.pid === process.pid) return false; // 自己 reload：拿回来即可，不算抢占
+  return owner.reservedUntil > now;
+}
+
+/**
+ * 按顺序抢占：跳过「别人正在重载」和「已在线」的 bot，抢到第一个可用就返回。
+ *
+ * 抢到之后会再读一次 owner 记录——如果刚好在抢锁瞬间别人贴了预约，
+ * 立刻把锁放掉（关掉竞态窗口），换下一个候选。
+ */
+export async function claimAny(
+  candidates: ClaimCandidate[],
+  options: { preferredAppId?: string | null; now?: number } = {},
+): Promise<ClaimResult> {
+  const skipped: ClaimSkip[] = [];
+  const ordered = [...candidates];
+  if (options.preferredAppId) {
+    const index = ordered.findIndex((c) => c.appId === options.preferredAppId);
+    if (index > 0) ordered.unshift(...ordered.splice(index, 1));
+  }
+
+  for (const candidate of ordered) {
+    const now = options.now ?? Date.now();
+    const before = readOwner(candidate.appId);
+    if (reservedByOther(before, now)) {
+      skipped.push({ name: candidate.name, reason: "reserved", owner: before ?? undefined });
+      continue;
+    }
+    const release = await tryAcquireLock(LOCK_PATH(candidate.appId));
+    if (!release) {
+      skipped.push({ name: candidate.name, reason: "online" });
+      continue;
+    }
+    const raced = readOwner(candidate.appId);
+    if (reservedByOther(raced, options.now ?? Date.now())) {
+      // 抢锁和别人的「临时释放」撞在一起了：让出去，别抢别人 reload 中的 bot
+      await release().catch(() => {});
+      skipped.push({ name: candidate.name, reason: "raced", owner: raced ?? undefined });
+      continue;
+    }
+    recordClaim({ name: candidate.name, appId: candidate.appId }, now);
+    const previous = before;
+    const takeover = !!previous && previous.pid !== process.pid && previous.pid !== 0;
+    const reclaimed = !!previous && previous.pid === process.pid;
+    return {
+      claim: { name: candidate.name, appId: candidate.appId, release, previous, takeover, reclaimed },
+      skipped,
+    };
+  }
+  return { skipped };
+}
+
+/**
+ * 待命：每 5 秒重扫一遍候选。
+ *
+ * 注意「全上线了就忽略」= 本进程不接入、但持续重扫——否则别人退出后没人接管，
+ * 「同账号换进程要提示」这条需求永远触发不到。
+ */
+export function startClaimRetry(
+  getCandidates: () => ClaimCandidate[],
+  onClaim: (claim: Claim) => void,
+  options: { preferredAppId?: string | null; intervalMs?: number; maxAttempts?: number } = {},
+): () => void {
+  let attempts = 0;
+  let stopped = false;
+  const timer = setInterval(async () => {
+    if (stopped) return;
+    attempts += 1;
+    const result = await claimAny(getCandidates(), { preferredAppId: options.preferredAppId });
+    if (result.claim) {
+      clearInterval(timer);
+      onClaim(result.claim);
+      return;
+    }
+    if (options.maxAttempts !== undefined && attempts >= options.maxAttempts) clearInterval(timer);
+  }, options.intervalMs ?? LOCK_RETRY_MS);
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+}

package/logger.ts

@@ -2,8 +2,29 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { redactSecrets } from "./redact";
+import { LOG_PATH as ACCOUNT_LOG_PATH } from "./constants";
 
-const LOG_PATH = path.join(os.homedir(), ".pi", "agent", "pi-qqbot.log");
+/**
+ * 日志文件。默认仍写旧的单文件 `pi-qqbot.log`（1.x 行为、旧测试与旧排查习惯都靠它），
+ * 一旦 `configureLog(账号名)` 被调用（多 bot 场景）就改成 `pi-qqbot-<账号>.log`：
+ * 同一台机器跑多个 pi 进程时，各账号的日志不交织。
+ */
+let currentPath: string | null = null;
+const legacyPath = () => path.join(os.homedir(), ".pi", "agent", "pi-qqbot.log");
+const logPath = () => currentPath ?? legacyPath();
+
+/**
+ * 指定本进程的账号：之后所有日志写进该账号的日志文件。
+ * `null` = 单 bot 场景，继续写旧的 `pi-qqbot.log`（v1 配置升级后日志位置不变）。
+ */
+export function configureLog(account: string | null): void {
+  currentPath = account ? ACCOUNT_LOG_PATH(account) : legacyPath();
+}
+
+/** 当前日志文件路径（诊断用） */
+export function currentLogPath(): string {
+  return logPath();
+}
 
 const pad = (value: number, width = 2): string =>
   String(Math.trunc(Math.abs(value))).padStart(width, "0");
@@ -30,7 +51,7 @@ export function log(...args: unknown[]) {
   // 日志会留在磁盘上：落盘前统一脱敏（Authorization、token=、URL userinfo、私钥块等）
   const line = `[${timestamp()}] ${redactSecrets(body)}\n`;
   try {
-    fs.appendFileSync(LOG_PATH, line, "utf8");
+    fs.appendFileSync(logPath(), line, "utf8");
   } catch {
     /* ignore */
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -27,7 +27,7 @@
     ]
   },
   "scripts": {
-    "test": "node test/queue.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs"
+    "test": "node test/queue.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs"
   },
   "files": [
     "*.ts",

package/qq/auth.ts

@@ -20,8 +20,16 @@ export class AuthManager {
     });
     if (!res.ok) throw new Error(`getAppAccessToken failed: HTTP ${res.status}`);
     const data = (await res.json()) as any;
-    this.token = String(data.access_token ?? "");
-    this.expireAt = Date.now() + Number(data.expires_in) * 1000;
+    const token = String(data.access_token ?? "");
+    // QQ 平台对无效凭据返回 HTTP 200 + code 100016，以前只在后面拿空 token 去连网关，
+    // 表现为「锁抢到了但永远连不上」；这里直接抛，抢占阶段就能发现。
+    if (!token) {
+      const code = data?.code ?? "-";
+      const message = data?.message ?? data?.msg ?? "未返回 access_token";
+      throw new Error(`getAppAccessToken 被拒: code=${code} ${message}`);
+    }
+    this.token = token;
+    this.expireAt = Date.now() + Number(data.expires_in ?? 0) * 1000;
     return this.token;
   }
 }