tt-help-cli-ycl 1.4.172 → 1.4.175

package/src/watch/login-pool.js

@@ -0,0 +1,755 @@
+/**
+ * 共享登录池 — TikTok 账号登录态集中存储 + 独占租约分配 + 心跳下发
+ *
+ * Phase 0（本期）: 纯服务端能力，节点行为零改动
+ *   - 账号登录态 CRUD（~/.tt-help-watchdog-logins.json，cookies 明文落盘，接口输出一律脱敏）
+ *   - 独占租约: 同一账号全局只允许一个 active lease（防同账号双机并行劣化——10-25 实证坑）
+ *   - 指派 = 排队 applyLogin/clearLogin 命令，随目标节点心跳一次性取走（复用 loginRecheck 模式）
+ *   - 直接取号 = POST /api/login-pool/acquire（Phase 2，explore 等业务进程自取自注入，
+ *     幂等续租 + force 原子换号，响应带明文 cookies，不经命令队列）
+ *   - 续租/回收: 持有节点每次心跳自动续租；节点掉线超过租约 TTL 自动回收回池
+ *   - 健康采集: 心跳 body.loginPool.ports 被动入库（Phase 1 agent 开始上报；判据=业务出活，
+ *     不做接口探测——裸 fetch item_list 假阴性，10-25 教训）
+ *
+ * 与订阅中心同构的约定:
+ *   - watch 主进程收心跳（唯一写入热路径），standalone 复用同一路由做展示/CRUD
+ *   - 文件原子写（tmp + rename），mtime 变化时自动重读（跨进程可见）
+ *   - 安全: cookies 等同账号密码。日志只打 username/计数；所有 API 输出脱敏
+ *     （仅 cookieCount/hasSessionid/sessionExpiresAt）；命令队列 10 分钟未被取走即作废并回收租约
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  existsSync,
+  unlinkSync,
+  statSync,
+} from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const homeDir = homedir() || process.env.HOME || process.env.USERPROFILE || "";
+const POOL_FILE = join(homeDir, ".tt-help-watchdog-logins.json");
+
+// ── 常量 ──
+const SAVE_DEBOUNCE_MS = 3 * 1000;
+const LEASE_TTL_MS = 12 * 60 * 60 * 1000; // 租约时长：持有节点心跳自动续，掉线超时回收
+const CMD_TTL_MS = 10 * 60 * 1000; // 下发命令 10 分钟未被取走作废（节点离线），租约自动回收
+const HISTORY_MAX = 20; // 每账号保留最近 20 条分配历史
+const POOL_MAX = 256; // 池容量上限
+const VALID_STATUS = ["pool", "leased", "suspect", "retired"];
+
+// ── 内存状态 ──
+let _accounts = []; // 账号注册表（含明文 cookies，仅服务端内存/文件持有）
+let _loaded = false;
+let _fileMtime = 0;
+let _saveTimer = null;
+
+// 下发命令队列：跨进程共享（关键！201 拓扑 assign/take 在 watch(3011)，心跳取走在 standalone(17302)，
+// 进程内存队列互相看不见）→ 队列随池文件持久化（原子写+mtime 重载），双进程/单进程部署通吃
+let _queue = []; // [{ userId, action, accountId, port, username, cookies?, proxyHint?, queuedAt }]
+let _lastFileWriteAt = 0;
+let _dirty = false; // 内存有未落盘变更；无变更不写文件（双进程下冗余写会踩掉对方的写入窗口）
+
+// ── 工具 ──
+
+function now() {
+  return Date.now();
+}
+
+function newId() {
+  return "acc-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8);
+}
+
+function pushHistory(acc, event, detail = "") {
+  acc.history = acc.history || [];
+  acc.history.unshift({ at: now(), event, detail: String(detail).slice(0, 200) });
+  if (acc.history.length > HISTORY_MAX) acc.history.length = HISTORY_MAX;
+}
+
+/** 从 cookies 数组提取账号名（无显式 username 时的兜底） */
+export function deriveUsername(cookies) {
+  for (const c of Array.isArray(cookies) ? cookies : []) {
+    if (c && (c.name === "unique_id" || c.name === "uniqueId") && c.value) return c.value;
+  }
+  return "";
+}
+
+function findSessionid(cookies) {
+  for (const c of Array.isArray(cookies) ? cookies : []) {
+    if (c && c.name === "sessionid") return c;
+  }
+  return null;
+}
+
+/** 校验 cookies 形参：必须是 [{name, value, domain?, ...}] 非空数组 */
+function normalizeCookies(input) {
+  if (!Array.isArray(input)) return null;
+  const out = [];
+  for (const c of input) {
+    if (!c || typeof c.name !== "string" || typeof c.value !== "string") return null;
+    out.push({
+      name: c.name,
+      value: c.value,
+      domain: typeof c.domain === "string" ? c.domain : ".tiktok.com",
+      path: typeof c.path === "string" ? c.path : "/",
+      secure: c.secure !== false,
+      httpOnly: c.httpOnly !== false,
+      expires: typeof c.expires === "number" ? c.expires : undefined,
+    });
+  }
+  return out.length > 0 ? out : null;
+}
+
+// ── 文件读写（与订阅中心同模式：mtime 缓存 + 原子替换） ──
+
+function ensureLoaded() {
+  let mtime = 0;
+  try {
+    mtime = statSync(POOL_FILE).mtimeMs;
+  } catch {}
+  if (_loaded && mtime === _fileMtime) return;
+  _loaded = true;
+  _fileMtime = mtime;
+  try {
+    if (existsSync(POOL_FILE)) {
+      const data = JSON.parse(readFileSync(POOL_FILE, "utf-8"));
+      _accounts = Array.isArray(data.accounts) ? data.accounts : [];
+      _queue = Array.isArray(data.queue) ? data.queue : [];
+      // useCount 迁移：老账号无该字段时按历史回填一次（assigned/acquired 各计一次使用；
+      // history 上限 20 条，回填值为下限估计）
+      for (const a of _accounts) {
+        if (a.useCount === undefined) {
+          a.useCount = (a.history || []).filter(
+            (h) => h.event === "assigned" || h.event === "acquired",
+          ).length;
+        }
+      }
+      if (mtime)
+        console.error(
+          `[登录池] 已加载: ${_accounts.length} 个账号, 待发命令 ${_queue.length} 条 (${POOL_FILE})`,
+        );
+    }
+  } catch (e) {
+    console.error(`[登录池] 文件加载失败（忽略，按空池启动）: ${e.message}`);
+    _accounts = [];
+  }
+}
+
+function saveNow() {
+  if (_saveTimer) {
+    clearTimeout(_saveTimer);
+    _saveTimer = null;
+  }
+  if (!_dirty) return; // 无变更不写
+  // 双进程写冲突规避（watch 3011 与 standalone 17302 共享此文件）：
+  // 磁盘已被对方更新且我们没见过那份 → 重载磁盘状态、放弃本次写。
+  // 操作性变更（入池/指派/取号）都在 ensureLoaded→mutate→save 毫秒级窗口内完成，
+  // 可能被丢的只有低价值状态（如续租时间戳），下一轮心跳会重新写回。
+  try {
+    const m = statSync(POOL_FILE).mtimeMs;
+    if (_fileMtime && m !== _fileMtime) {
+      _loaded = false;
+      _dirty = false; // 磁盘为准，放弃本次未落盘变更（操作性变更窗口在毫秒级，低价值状态下轮心跳重写）
+      ensureLoaded();
+      console.error("[登录池] 检测到跨进程更新，已重载磁盘状态（放弃本次写）");
+      return;
+    }
+  } catch {}
+  // 内容比对去重：序列化后与磁盘一致 → 只清脏标记不动文件（mtime 不变 = 不抢对方的写入窗口）
+  const json = JSON.stringify({ accounts: _accounts, queue: _queue }, null, 2);
+  try {
+    if (readFileSync(POOL_FILE, "utf-8") === json) {
+      _dirty = false;
+      return;
+    }
+  } catch {}
+  const tmp = POOL_FILE + ".tmp";
+  try {
+    writeFileSync(tmp, json, "utf-8");
+    renameSync(tmp, POOL_FILE); // 原子替换，防并发读撕裂
+    _lastFileWriteAt = now();
+    _dirty = false;
+    try {
+      _fileMtime = statSync(POOL_FILE).mtimeMs;
+    } catch {}
+  } catch (e) {
+    try {
+      unlinkSync(tmp);
+    } catch {}
+    console.error(`[登录池] 保存失败: ${e.message}`);
+  }
+}
+
+function scheduleSave() {
+  _dirty = true; // 无变更不写：双进程下冗余写会踩掉对方的写入窗口
+  if (_saveTimer) return;
+  _saveTimer = setTimeout(saveNow, SAVE_DEBOUNCE_MS);
+  if (_saveTimer.unref) _saveTimer.unref();
+}
+
+// ── 脱敏视图（所有 API 输出唯一形态；明文 cookies 永不出服务端内存/心跳下发通道） ──
+
+function sessionExpiresAt(acc) {
+  const s = findSessionid(acc.cookies);
+  if (!s || typeof s.expires !== "number" || s.expires <= 0) return null;
+  // cookie 规范的 expires 是秒；归一化为毫秒，前端 new Date() 直接可用
+  return s.expires < 1e12 ? Math.round(s.expires * 1000) : s.expires;
+}
+
+function publicView(acc) {
+  const lease = acc.lease
+    ? {
+        userId: acc.lease.userId,
+        port: acc.lease.port,
+        assignedAt: acc.lease.assignedAt,
+        expireAt: acc.lease.expireAt,
+        lastHealthAt: acc.lease.lastHealthAt || null,
+        lastBusinessOkAt: acc.lease.lastBusinessOkAt || null,
+        emptyStreak: acc.lease.emptyStreak || 0,
+        lastAppliedAt: acc.lease.lastAppliedAt || null,
+        lastAppliedOk: acc.lease.lastAppliedOk != null ? acc.lease.lastAppliedOk : null,
+        persisted: acc.lease.persisted != null ? acc.lease.persisted : null,
+        appliedUsername: acc.lease.appliedUsername || null,
+        appName: acc.lease.appName || null,
+        pendingDelivery: hasPendingCommand(acc.id),
+      }
+    : null;
+  return {
+    id: acc.id,
+    username: acc.username,
+    note: acc.note || "",
+    proxyHint: acc.proxyHint || "",
+    status: acc.status,
+    cookieCount: Array.isArray(acc.cookies) ? acc.cookies.length : 0,
+    hasSessionid: !!findSessionid(acc.cookies),
+    sessionExpiresAt: sessionExpiresAt(acc),
+    useCount: acc.useCount || 0,
+    lastImportFrom: acc.lastImportFrom || null,
+    // 最近使用镜像（脱离 lease 独立存在，释放/回收后仍可见）
+    lastHealthAt: acc.lastHealthAt || null,
+    lastBusinessOkAt: acc.lastBusinessOkAt || null,
+    lastUsedAt: acc.lastUsedAt || null,
+    lease,
+    history: acc.history || [],
+    createdAt: acc.createdAt,
+    updatedAt: acc.updatedAt,
+  };
+}
+
+// ── 命令队列（随池文件跨进程共享；心跳取走即清空） ──
+
+function hasPendingCommand(accountId) {
+  return _queue.some((c) => c.accountId === accountId);
+}
+
+/** 清除某账号的所有待发命令（租约终止/状态迁移时调用，防止旧命令把登录态下发到已不持有租约的节点） */
+function purgeCommandsFor(accountId) {
+  const kept = _queue.filter((c) => c.accountId !== accountId);
+  if (kept.length !== _queue.length) {
+    _queue = kept;
+    scheduleSave();
+  }
+}
+
+function enqueueCommand(userId, cmd) {
+  // 同账号同端口幂等：替换未取走的旧命令
+  const idx = _queue.findIndex(
+    (c) => c.userId === userId && c.accountId === cmd.accountId && c.port === cmd.port,
+  );
+  if (idx >= 0) _queue.splice(idx, 1);
+  cmd.queuedAt = now();
+  cmd.userId = userId;
+  _queue.push(cmd);
+  _dirty = true;
+  saveNow(); // 立即落盘（不走 3s 防抖）：命令是跨进程投递的关键载荷
+}
+
+function dropStaleCommands() {
+  const t = now();
+  const kept = [];
+  let expired = false;
+  for (const cmd of _queue) {
+    if (t - cmd.queuedAt > CMD_TTL_MS) {
+      expired = true;
+      // 节点离线未取走：回收租约回池，避免账号被"幽灵租约"占死
+      const acc = _accounts.find((a) => a.id === cmd.accountId);
+      if (acc && acc.status === "leased" && acc.lease) {
+        pushHistory(acc, "deliveryExpired", `命令未被 ${acc.lease.userId} 取走，租约回收`);
+        acc.status = "pool";
+        acc.lastUsedAt = t;
+        acc.lease = null;
+        acc.updatedAt = t;
+        scheduleSave();
+      }
+    } else {
+      kept.push(cmd);
+    }
+  }
+  if (expired || kept.length !== _queue.length) {
+    _queue = kept;
+    scheduleSave();
+  }
+}
+
+// ── 租约维护 ──
+
+/** 回收过期租约（节点掉线 > TTL）。返回回收数量。 */
+export function reapExpiredLeases() {
+  ensureLoaded();
+  dropStaleCommands();
+  const t = now();
+  let reaped = 0;
+  for (const acc of _accounts) {
+    if (acc.status === "leased" && acc.lease && t - (acc.lease.lastHealthAt || acc.lease.assignedAt) > LEASE_TTL_MS) {
+      pushHistory(acc, "leaseExpired", `${acc.lease.userId} 掉线超时，自动回收`);
+      acc.status = "pool";
+      acc.lastUsedAt = t;
+      acc.lease = null;
+      acc.updatedAt = t;
+      purgeCommandsFor(acc.id);
+      reaped++;
+    }
+  }
+  if (reaped > 0) scheduleSave();
+  return reaped;
+}
+
+// ── 心跳集成（watch 主进程心跳热路径调用） ──
+
+/**
+ * 心跳处理：续租 + 采集健康数据 + 返回待下发命令。
+ * @param userId 节点 userId（body.config.userId）
+ * @param body 心跳 body（可含 loginPool: { ports: { "9222": { username, lastBusinessOkAt, emptyStreak } } }）
+ * @returns loginPoolCommands（无则 undefined）
+ */
+export function heartbeatLoginPool(userId, body) {
+  ensureLoaded();
+  const t = now();
+  const poolBody = body && body.loginPool;
+  const report = poolBody && poolBody.ports;
+
+  // 0) 节点执行回报（applyLogin/clearLogin 结果）：写回租约与历史
+  if (Array.isArray(poolBody && poolBody.applied)) {
+    for (const r of poolBody.applied) {
+      const acc = _accounts.find((a) => a.id === r.accountId);
+      if (!acc) continue;
+      if (r.action === "applyLogin") {
+        if (acc.lease && acc.lease.userId === userId) {
+          acc.lease.lastAppliedAt = r.at || t;
+          acc.lease.lastAppliedOk = !!r.ok;
+          acc.lease.persisted = !!r.persisted;
+          if (r.ok && r.username) acc.lease.appliedUsername = r.username;
+        }
+        pushHistory(
+          acc,
+          r.ok ? (r.persisted ? "applied" : "appliedVolatile") : "applyFailed",
+          `${userId}:${r.port}${r.ok ? " @" + (r.username || "") : " " + (r.error || "")}`,
+        );
+      } else {
+        pushHistory(acc, "cleared", `${userId}:${r.port}`);
+      }
+    }
+    scheduleSave();
+  }
+
+  // 1) 续租该节点持有的所有租约 + 采集健康数据
+  for (const acc of _accounts) {
+    if (acc.status === "leased" && acc.lease && acc.lease.userId === userId) {
+      acc.lease.lastHealthAt = t;
+      acc.lastHealthAt = t; // 镜像到账号本体，释放后仍可查
+      acc.lastUsedAt = t;
+      _dirty = true; // 续租也是变更：配合下方低频持久化落盘
+      if (report && report[acc.lease.port]) {
+        const h = report[acc.lease.port];
+        if (typeof h.lastBusinessOkAt === "number") {
+          acc.lease.lastBusinessOkAt = h.lastBusinessOkAt;
+          acc.lastBusinessOkAt = h.lastBusinessOkAt; // 镜像：最近一次业务出活
+        }
+        if (typeof h.emptyStreak === "number") acc.lease.emptyStreak = h.emptyStreak;
+        if (h.username && !acc.username) acc.username = h.username;
+      }
+    }
+  }
+
+  // 1.5) 心跳续租的低频持久化：只在我们真的持有账号状态时才写，且每 5 分钟最多一次
+  //      （冷启动空状态下绝不落盘，防盖掉对方刚写的数据；TTL 12h，5min 漂移可忽略）
+  if (_loaded && _accounts.length > 0 && t - _lastFileWriteAt > 300000) scheduleSave();
+
+  // 2) 取走待下发命令（一次性；跨进程：命令由 watch 进程经池文件投递）
+  const list = _queue.filter((c) => c.userId === userId);
+  let commands;
+  if (list.length > 0) {
+    _queue = _queue.filter((c) => c.userId !== userId);
+    commands = list.map((c) => ({
+      action: c.action,
+      accountId: c.accountId,
+      port: c.port,
+      username: c.username,
+      cookies: c.cookies, // 仅在心跳响应通道下发，不经任何 GET API
+      proxyHint: c.proxyHint || "",
+    }));
+    for (const c of list) {
+      const acc = _accounts.find((a) => a.id === c.accountId);
+      if (acc)
+        pushHistory(
+          acc,
+          c.action === "applyLogin" ? "delivered" : "clearDelivered",
+          `${userId}:${c.port}`,
+        );
+    }
+    scheduleSave();
+  }
+
+  // 3) 低频回收（每次心跳顺带检查，成本低）
+  reapExpiredLeases();
+
+  return commands && commands.length > 0 ? { commands } : undefined;
+}
+
+// ── CRUD / 分配 API ──
+
+/** 取号响应视图：publicView + 明文 cookies（仅 POST /api/login-pool/acquire 返回，属下发通道同级） */
+function fullView(acc) {
+  return { ...publicView(acc), cookies: acc.cookies };
+}
+
+/** 池视图（脱敏） */
+export function getLoginPoolView() {
+  ensureLoaded();
+  reapExpiredLeases();
+  return {
+    accounts: _accounts.map(publicView),
+    total: _accounts.length,
+  };
+}
+
+/** 入池：{ username, cookies, note?, proxyHint? } */
+export function addAccount({ username, cookies, note, proxyHint } = {}) {
+  ensureLoaded();
+  const norm = normalizeCookies(cookies);
+  if (!norm) throw new Error("cookies 必须是非空数组，且每项含 name/value");
+  if (_accounts.length >= POOL_MAX) throw new Error(`池已满（上限 ${POOL_MAX}）`);
+  const derived = deriveUsername(norm);
+  const name = (username || derived || "").trim();
+  if (!name) throw new Error("无法确定账号名：请传 username（或 cookies 含 unique_id）");
+  const dup = _accounts.find((a) => a.username === name && a.status !== "retired");
+  if (dup) throw new Error(`账号 ${name} 已在池中（id=${dup.id}, status=${dup.status}）`);
+  const acc = {
+    id: newId(),
+    username: name,
+    note: (note || "").slice(0, 200),
+    proxyHint: (proxyHint || "").slice(0, 100),
+    cookies: norm,
+    status: "pool",
+    lease: null,
+    useCount: 0,
+    history: [],
+    createdAt: now(),
+    updatedAt: now(),
+  };
+  pushHistory(acc, "added", `入池 ${norm.length} 条 cookies`);
+  _accounts.push(acc);
+  scheduleSave();
+  return publicView(acc);
+}
+
+/** 更新元数据/状态：{ id, note?, proxyHint?, status? }；status 仅允许 leased→suspect/retired/pool 的服务端安全迁移 */
+export function updateAccount({ id, note, proxyHint, status } = {}) {
+  ensureLoaded();
+  const acc = _accounts.find((a) => a.id === id);
+  if (!acc) throw new Error(`账号不存在: ${id}`);
+  if (note !== undefined) acc.note = String(note).slice(0, 200);
+  if (proxyHint !== undefined) acc.proxyHint = String(proxyHint).slice(0, 100);
+  if (status !== undefined) {
+    if (!VALID_STATUS.includes(status)) throw new Error(`非法 status: ${status}`);
+    if (acc.status === "leased" && status === "pool") {
+      pushHistory(acc, "released", "手动释放");
+      acc.lease = null;
+      purgeCommandsFor(acc.id);
+    } else if (acc.status === "leased" && status !== "pool") {
+      pushHistory(acc, "force" + status[0].toUpperCase() + status.slice(1), "从 leased 强制迁移");
+      acc.lease = null;
+      purgeCommandsFor(acc.id);
+    }
+    pushHistory(acc, "status", `${acc.status} → ${status}`);
+    acc.status = status;
+  }
+  acc.updatedAt = now();
+  scheduleSave();
+  return publicView(acc);
+}
+
+/** 删除（retired 才可删；其余先 retired） */
+export function deleteAccount(id) {
+  ensureLoaded();
+  const idx = _accounts.findIndex((a) => a.id === id);
+  if (idx < 0) throw new Error(`账号不存在: ${id}`);
+  const acc = _accounts[idx];
+  if (acc.status === "leased") throw new Error("账号在租约中，先 release 再删除");
+  _accounts.splice(idx, 1);
+  scheduleSave();
+  return { id, username: acc.username };
+}
+
+/**
+ * 指派：{ id, userId, port }
+ * 独占约束：① 账号必须 status=pool（suspect 需 force）② 该账号不得已有 lease ③ 目标 (userId,port) 不得持有其他账号
+ */
+export function assignAccount({ id, userId, port, force } = {}) {
+  ensureLoaded();
+  const acc = _accounts.find((a) => a.id === id);
+  if (!acc) throw new Error(`账号不存在: ${id}`);
+  if (!userId || !port) throw new Error("userId 和 port 必填");
+  port = Number(port);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error(`非法端口: ${port}`);
+  if (acc.status === "leased" && acc.lease) throw new Error(`账号已租给 ${acc.lease.userId}:${acc.lease.port}，先 release`);
+  if (acc.status === "retired") throw new Error("账号已下架（retired），不可指派");
+  if (acc.status === "suspect" && !force) throw new Error("账号为 suspect 状态，确认可用请带 force=true");
+
+  // 目标端口独占检查
+  const occupant = _accounts.find(
+    (a) => a.status === "leased" && a.lease && a.lease.userId === userId && a.lease.port === port,
+  );
+  if (occupant) {
+    if (!force) throw new Error(`${userId}:${port} 已持有 ${occupant.username}（id=${occupant.id}），替换请带 force=true`);
+    // 自动替换：旧账号回收（清其遗留命令）+ 节点下发 clearLogin
+    purgeCommandsFor(occupant.id);
+    enqueueCommand(userId, {
+      action: "clearLogin",
+      accountId: occupant.id,
+      port,
+      username: occupant.username,
+    });
+    pushHistory(occupant, "evicted", `被 ${acc.username} 替换下机`);
+    occupant.status = "pool";
+    occupant.lastUsedAt = now();
+    occupant.lease = null;
+    occupant.updatedAt = now();
+  }
+
+  const t = now();
+  acc.status = "leased";
+  acc.useCount = (acc.useCount || 0) + 1;
+  acc.lease = {
+    userId,
+    port,
+    assignedAt: t,
+    expireAt: t + LEASE_TTL_MS,
+    lastHealthAt: t,
+    lastBusinessOkAt: null,
+    emptyStreak: null,
+  };
+  acc.updatedAt = t;
+  pushHistory(acc, "assigned", `${userId}:${port}${force ? " (force)" : ""}`);
+  enqueueCommand(userId, {
+    action: "applyLogin",
+    accountId: acc.id,
+    port,
+    username: acc.username,
+    cookies: acc.cookies,
+    proxyHint: acc.proxyHint || "",
+  });
+  scheduleSave();
+  return publicView(acc);
+}
+
+/**
+ * 释放：{ id, clearOnNode? }
+ * clearOnNode=true 时同时下发 clearLogin（清理节点端口上的登录态，默认 false —— 换机不清理，
+ * 便于回滚；真要下机清理时显式传）
+ */
+export function releaseAccount({ id, clearOnNode } = {}) {
+  ensureLoaded();
+  const acc = _accounts.find((a) => a.id === id);
+  if (!acc) throw new Error(`账号不存在: ${id}`);
+  if (acc.status !== "leased" || !acc.lease) throw new Error("账号不在租约中");
+  const { userId, port } = acc.lease;
+  acc.status = "pool";
+  acc.lastUsedAt = now();
+  acc.lease = null;
+  acc.updatedAt = now();
+  pushHistory(acc, "released", `${userId}:${port}${clearOnNode ? " (清理节点)" : ""}`);
+  purgeCommandsFor(acc.id); // 先清该账号遗留命令，再按需下发 clearLogin
+  if (clearOnNode) {
+    enqueueCommand(userId, {
+      action: "clearLogin",
+      accountId: acc.id,
+      port,
+      username: acc.username,
+    });
+  }
+  scheduleSave();
+  return publicView(acc);
+}
+
+/**
+ * 自动取号（客户端拉取）：节点程序需要账号时按 API 自取。
+ * { userId, port, username?, force? } — 传 username 优先指派该账号，否则按入池先后取首个 pool 态账号。
+ * 复用 assignAccount 的独占约束与命令下发，账号从 pool → leased。
+ */
+export function takeAccount({ userId, port, username, force } = {}) {
+  ensureLoaded();
+  reapExpiredLeases();
+  if (!userId || !port) throw new Error("userId 和 port 必填");
+  let acc;
+  if (username) {
+    acc = _accounts.find((a) => a.username === username);
+    if (!acc) throw new Error(`池中无此账号: ${username}`);
+  } else {
+    acc = _accounts.find((a) => a.status === "pool");
+    if (!acc) {
+      const leased = _accounts.filter((a) => a.status === "leased").length;
+      throw new Error(`池中暂无空闲账号（共 ${_accounts.length} 个，其中 ${leased} 个在租约中）`);
+    }
+  }
+  return assignAccount({ id: acc.id, userId, port, force });
+}
+
+/**
+ * 直接取号（Phase 2，以号为主键）：业务进程自取账号，拿到明文 cookies 后
+ * 在自有浏览器实例上原地注入，不经心跳命令队列、不依赖节点 watchdog。
+ *
+ * 语义（2026-10-26 用户定稿：以号为主键，无幂等/无端口键）:
+ *   - 取号 = 挑最久未用的空闲号 → 标 leased → 响应带明文 cookies
+ *   - 独占由池状态机保证（take 即 leased，同号不双机并行）；
+ *     切换 = 先取新号、验证通过后再还旧号（无空窗，池空保旧）
+ *   - 崩溃/异常未还号的租约由 TTL 兑底回收（或账号中心手动释放），不做幂等恢复
+ *   - port 可选：仅作展示元数据（浏览器口），不参与任何键/约束
+ *   - appName: 租约元数据仅记录展示（explore/search...），不参与分配
+ */
+export function acquireAccount({ userId, port, appName } = {}) {
+  ensureLoaded();
+  reapExpiredLeases();
+  if (!userId) throw new Error("userId 必填");
+  let portNum = null;
+  if (port !== undefined && port !== null && port !== "") {
+    portNum = Number(port);
+    if (!Number.isInteger(portNum) || portNum < 1024 || portNum > 65535) {
+      throw new Error(`非法端口: ${port}`);
+    }
+  }
+  const t = now();
+
+  // ⑥ 双键排序：先用次数少的优先（永不用过的最优先），同次数再按最近使用时间升序
+  const pool = _accounts.filter((a) => a.status === "pool");
+  const sortFn =
+    (a, b) =>
+      (a.useCount || 0) - (b.useCount || 0) ||
+      (a.lastUsedAt || a.createdAt) - (b.lastUsedAt || b.createdAt);
+  // ⑥ 错峰冷却：刚归还的号（lastUsedAt 在冷却窗内）先排除，避免同号被连续调用；
+  //   全部在冷却时退化为全池排序（有得用总比没用好）。从未用过的号无 lastUsedAt，不受冷却影响
+  const COOLDOWN_MS = 10 * 60 * 1000;
+  const cooled = pool
+    .filter((a) => !a.lastUsedAt || a.lastUsedAt <= t - COOLDOWN_MS)
+    .sort(sortFn);
+  const acc = cooled[0] || pool.slice().sort(sortFn)[0];
+  if (!acc) {
+    const leased = _accounts.filter((a) => a.status === "leased").length;
+    throw new Error(`池中暂无空闲账号（共 ${_accounts.length} 个，其中 ${leased} 个在租约中）`);
+  }
+
+  acc.status = "leased";
+  acc.useCount = (acc.useCount || 0) + 1;
+  acc.lastUsedAt = t; // 最近使用时间（取号即「开始使用」）
+  acc.lease = {
+    userId,
+    port: portNum,
+    appName: appName ? String(appName).slice(0, 50) : null,
+    assignedAt: t,
+    expireAt: t + LEASE_TTL_MS,
+    lastHealthAt: t,
+    lastBusinessOkAt: null,
+    emptyStreak: null,
+  };
+  acc.updatedAt = t;
+  pushHistory(acc, "acquired", `${userId}${portNum ? ":" + portNum : ""} 直接取号`);
+
+  // ③ 一程序实例恒持一号：自动释放该使用者名下的其他旧租约
+  //   （换号 = 取新+还旧一步完成；崩溃重启后的首次取号自愈清僵尸租约；
+  //    旧号释放后 lastUsedAt=now 垫底，不会被下一个消费者立刻拿走）
+  const releasedOthers = [];
+  for (const other of _accounts) {
+    if (
+      other.id !== acc.id &&
+      other.status === "leased" &&
+      other.lease &&
+      other.lease.userId === userId
+    ) {
+      pushHistory(other, "released", `自动释放（${userId} 取新号）`);
+      other.status = "pool";
+      other.lastUsedAt = t;
+      other.lease = null;
+      other.updatedAt = t;
+      purgeCommandsFor(other.id);
+      releasedOthers.push(other.username);
+    }
+  }
+  if (releasedOthers.length > 0) {
+    pushHistory(
+      acc,
+      "autoRelease",
+      `已自动释放同使用者旧号: ${releasedOthers.join(", ")}`,
+    );
+  }
+  scheduleSave();
+  return fullView(acc);
+}
+
+/**
+ * 导入登录态（节点 → 账号中心）：
+ * 看门狗启动同步调用。按 username 去重：
+ *   - 已在池 → 幂等返回现状（不覆盖 cookies、不动租约）
+ *   - 新号 → 入池为【空闲】（不自动租——导入只是登记，租约只由真实消费产生；
+ *     pool 模式消费方启动时自会 acquire，那时才变「使用中」）
+ * username 必须来自 passport 活体验证（调用方已验），cookies 必须非空。
+ */
+export function importAccount({ userId, port, username, cookies, note, proxyHint } = {}) {
+  ensureLoaded();
+  reapExpiredLeases();
+  if (!userId) throw new Error("userId 必填");
+  if (!username) throw new Error("username 必填（须为 passport 验证过的登录号）");
+  const norm = normalizeCookies(cookies);
+  if (!norm) throw new Error("cookies 必须是非空数组，且每项含 name/value");
+  let portNum = null;
+  if (port !== undefined && port !== null && port !== "") {
+    portNum = Number(port);
+    if (!Number.isInteger(portNum) || portNum < 1024 || portNum > 65535) {
+      throw new Error(`非法端口: ${port}`);
+    }
+  }
+  const t = now();
+
+  const dup = _accounts.find((a) => a.username === username && a.status !== "retired");
+  if (dup) {
+    // 幂等：不覆盖 cookies、不动租约
+    return { account: publicView(dup), dedup: true };
+  }
+  if (_accounts.length >= POOL_MAX) throw new Error(`池已满（上限 ${POOL_MAX}）`);
+
+  const acc = {
+    id: newId(),
+    username,
+    note: (note || "").slice(0, 200),
+    proxyHint: (proxyHint || "").slice(0, 100),
+    cookies: norm,
+    status: "pool",
+    lease: null,
+    useCount: 0, // 导入是登记不是消费；次数只在 acquire/assign 时 +1
+    lastImportFrom: { userId, port: portNum, at: t }, // 来源元数据（供节点热路径跳过 + 账号中心展示），非租约
+    history: [],
+    createdAt: t,
+    updatedAt: t,
+  };
+  pushHistory(acc, "imported", `${userId} 节点同步导入`);
+  _accounts.push(acc);
+  scheduleSave();
+  return { account: fullView(acc), dedup: false };
+}
+
+/** 内部：注入账号（测试/迁移工具用，跳过命令队列直接改状态） */
+export function _accountsInternal() {
+  ensureLoaded();
+  return _accounts;
+}