tt-help-cli-ycl 1.4.177 → 1.4.179

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-help-cli-ycl",
-  "version": "1.4.177",
+  "version": "1.4.179",
   "description": "TikTok user & video data scraper - extract ttSeller, verified, locationCreated from HTML source",
   "type": "module",
   "bin": {

package/scripts/test-login-pool-ui.mjs

@@ -150,14 +150,34 @@ await page.waitForFunction(() => document.querySelector("#content table"), { tim
 const headers = await page.textContent("#content table tr:first-child");
 check(
   "独立页新列齐全",
-  ["账号", "状态", "使用者", "最近使用", "次数", "有效期", "操作", "历史"].every((h) => headers.includes(h)),
+  ["账号", "状态", "使用者", "最近使用", "次数", "有效期", "检测", "操作", "历史"].every((h) => headers.includes(h)),
 );
 const row1 = await page.textContent("#content table tr:nth-child(2)");
 check("状态徽章=使用中", row1.includes("使用中"));
 check("使用者=机器:口", row1.includes("F-11:9222"));
 const poolSrc = await page.content();
 check("独立页无 cookie 明文", !poolSrc.includes("SECRET-SID-XYZ"));
-check("独立页含重登录置灰按钮", await page.$$eval("#content button[disabled]", (bs) => bs.some((b) => b.textContent.includes("重登录"))));
+check("独立页重登录按钮已点亮（不再是置灰占位）", await page.$$eval("#content button:not([disabled])", (bs) => bs.some((b) => b.textContent.includes("重登录"))));
+check("独立页含新增账号/批量检测按钮", await page.$$eval(".bar button", (bs) => {
+  const t = bs.map((b) => b.textContent).join();
+  return t.includes("新增账号") && t.includes("批量检测");
+}));
+const barSrc = await page.content();
+check("页面含协议桥四件套（protoHref/launchProto/blur 探测/降级 copyCmd）",
+  ["function protoHref", "function launchProto", "addEventListener('blur'", "copyCmd("].every((s) => barSrc.includes(s)),
+);
+const protoUrl = await page.evaluate(() => protoHref("login-pool/relogin", { server: location.origin, username: "userA" }));
+check("protoHref 构造协议 URL 正确（参数全编码）",
+  protoUrl === "tt-help://login-pool/relogin?server=" + encodeURIComponent(BASE) + "&username=userA", `got ${protoUrl}`);
+const fallbackHtml = await page.evaluate(async () => {
+  launchProto("tt-help://login-pool/add?server=x", "CMD-FALLBACK-TEST", "ok");
+  await new Promise((r) => setTimeout(r, 2700));
+  return document.getElementById("msg").innerHTML;
+});
+check("未注册降级：2.5s 后出现复制按钮且命令正确嵌入", fallbackHtml.includes("copyCmd('CMD-FALLBACK-TEST')"), fallbackHtml.slice(0, 120));
+check("模拟取号/入池粘cookies按钮已移除", !barSrc.includes("模拟取号") && !barSrc.includes("入池(粘cookies)"));
+check("自动刷新无条件化（无勾选框）", !barSrc.includes('id="auto"'));
+check("统计 chips 存在", await page.$$eval("#stats .chip", (cs) => cs.length >= 5));
 
 // 有效期归一显示：应为 ~90 天后的日期（而非 1970）
 const day90 = new Date(Date.now() + 90 * 86400000).toLocaleDateString("zh-CN");

package/scripts/test-login-pool.mjs

@@ -32,7 +32,13 @@ const {
   importAccount,
   heartbeatLoginPool,
   reapExpiredLeases,
+  reloginAccount,
+  prepareRelogin,
+  healthTargets,
+  recordHealth,
+  _accountsInternal,
 } = await import("../src/watch/login-pool.js");
+const { checkPoolAccounts } = await import("../src/watch/login-health.js");
 
 let pass = 0;
 let fail = 0;
@@ -377,5 +383,108 @@ console.log("\n[8] 登录态导入 import");
   check("缺 cookies 确实抛错", threw);
 }
 
+console.log("\n[9] 重登录 relogin（覆盖刷新 + 守卫）");
+{
+  for (const a of getLoginPoolView().accounts) {
+    try { releaseAccount({ id: a.id }); } catch {}
+    try { updateAccount({ id: a.id, status: "retired" }); } catch {}
+    try { deleteAccount(a.id); } catch {}
+  }
+  const D1 = [
+    { name: "sessionid", value: "sid-d-old", domain: ".tiktok.com", expires: Math.floor(Date.now() / 1000) + 86400 },
+    { name: "unique_id", value: "userD", domain: ".tiktok.com" },
+  ];
+  importAccount({ userId: "F-9", username: "userD", cookies: D1 });
+  const D2 = [
+    { name: "sessionid", value: "sid-d-new", domain: ".tiktok.com", expires: Math.floor(Date.now() / 1000) + 86400 * 2 },
+    { name: "unique_id", value: "userD", domain: ".tiktok.com" },
+    { name: "poc_marker", value: "x", domain: ".tiktok.com" },
+  ];
+
+  let r = reloginAccount({ username: "userD", cookies: D2, userId: "cli", note: "单测" });
+  const after = JSON.parse(JSON.stringify(_accountsInternal().find((a) => a.username === "userD")));
+  check("覆盖刷新（新 cookies 落池）", JSON.stringify(after.cookies).includes("sid-d-new") && JSON.stringify(after.cookies).includes("poc_marker"));
+  check("历史含 relogin 事件", (after.history || []).some((h) => h.event === "relogin"));
+  check("正常刷新不改状态不复活", r.revived === false && r.wasSuspect === false && r.account.status === "pool");
+
+  let threw = false;
+  try { reloginAccount({ username: "ghost", cookies: D2, userId: "cli" }); } catch (e) { threw = /不在池中/.test(e.message); }
+  check("不在池拒绝", threw);
+  threw = false;
+  try { reloginAccount({ username: "userD", cookies: D2 }); } catch (e) { threw = /userId/.test(e.message); }
+  check("缺 userId 拒绝", threw);
+  threw = false;
+  try { reloginAccount({ username: "userD", userId: "cli" }); } catch (e) { threw = /cookies/.test(e.message); }
+  check("缺 cookies 拒绝", threw);
+
+  acquireAccount({ userId: "T1", port: 9400 });
+  threw = false;
+  try { reloginAccount({ username: "userD", cookies: D2, userId: "cli" }); } catch (e) { threw = /使用中/.test(e.message); }
+  check("使用中拒绝重登录", threw);
+  releaseAccount({ id: getLoginPoolView().accounts.find((a) => a.username === "userD").id });
+
+  updateAccount({ id: getLoginPoolView().accounts.find((a) => a.username === "userD").id, status: "suspect" });
+  r = reloginAccount({ username: "userD", cookies: D2, userId: "cli" });
+  check("suspect → 刷新后回 pool", r.wasSuspect === true && r.account.status === "pool");
+
+  updateAccount({ id: getLoginPoolView().accounts.find((a) => a.username === "userD").id, status: "retired" });
+  r = reloginAccount({ username: "userD", cookies: D2, userId: "cli" });
+  check("retired → 重登录复活", r.revived === true && r.account.status === "pool");
+}
+
+console.log("\n[10] 巡检 healthTargets/recordHealth/checkPoolAccounts（注入假探测）");
+{
+  for (const a of getLoginPoolView().accounts) {
+    try { releaseAccount({ id: a.id }); } catch {}
+    try { updateAccount({ id: a.id, status: "retired" }); } catch {}
+    try { deleteAccount(a.id); } catch {}
+  }
+  const mk = (sid) => [
+    { name: "sessionid", value: sid, domain: ".tiktok.com", expires: Math.floor(Date.now() / 1000) + 86400 },
+    { name: "unique_id", value: "u-" + sid, domain: ".tiktok.com" },
+  ];
+  importAccount({ userId: "F-9", username: "u-alive", cookies: mk("alive-1") });
+  importAccount({ userId: "F-9", username: "u-dead", cookies: mk("dead-1") });
+  const retired = importAccount({ userId: "F-9", username: "u-retired", cookies: mk("ret-1") });
+  updateAccount({ id: retired.account.id, status: "retired" });
+
+  const targets = healthTargets();
+  check("巡检目标默认含 pool/suspect 排除 retired", targets.length === 2 && targets.every((t) => t.username !== "u-retired"));
+  check("巡检目标带 cookies/proxyHint", targets.every((t) => Array.isArray(t.cookies) && t.cookies.length > 0));
+
+  // 假探测：u-alive 判活，u-dead 判死（带标记 cookie 验证探测拿到的是池内 cookies）
+  const fakeProbe = async (cookies) => {
+    const isAlive = JSON.stringify(cookies).includes("alive-1");
+    check(isAlive ? "探测[活]拿到的是池内 cookies" : "探测[死]拿到的是池内 cookies", Array.isArray(cookies));
+    return isAlive
+      ? { alive: true, username: "u-alive", expired: false, httpStatus: 200, error: null, ms: 5 }
+      : { alive: false, username: null, expired: true, httpStatus: 200, error: null, ms: 5 };
+  };
+  const sum = await checkPoolAccounts({ probeFn: fakeProbe, pacingMs: 0 });
+  check("巡检计数 alive/dead", sum.checked === 2 && sum.alive === 1 && sum.dead === 1);
+  check("死号自动 pool→suspect", sum.migrated === 1 && sum.results.find((x) => x.username === "u-dead").migrated === true);
+
+  const deadAcc = getLoginPoolView().accounts.find((a) => a.username === "u-dead");
+  check("死号 lastHealth=dead + 时间戳", deadAcc.lastHealth === "dead" && deadAcc.lastHealthAt > 0);
+  check("死号历史含 health 事件", (deadAcc.history || []).some((h) => h.event === "health"));
+  const aliveAcc = getLoginPoolView().accounts.find((a) => a.username === "u-alive");
+  check("活号不写 history（防刷屏）", !(aliveAcc.history || []).some((h) => h.event === "health"));
+
+  acquireAccount({ userId: "T2", port: 9401 }); // 租走最久未用的（u-alive 或 u-dead 中 LRU 者）
+  const leased = getLoginPoolView().accounts.find((a) => a.status === "leased");
+  const rec = recordHealth({ id: leased.id, ok: "dead", detail: "单测" });
+  check("leased 死号仅记录不迁移状态", rec.status === "leased" && leased.username === rec.username);
+
+  const notLeased = getLoginPoolView().accounts.find((a) => a.status !== "leased").username;
+  const prep = prepareRelogin({ username: notLeased });
+  check("prepare 返回明文 cookies", Array.isArray(prep.account.cookies) && prep.account.cookies.length > 0);
+  let threw = false;
+  try { prepareRelogin({ username: leased.username }); } catch (e) { threw = /使用中/.test(e.message); }
+  check("prepare 使用中拒绝", threw);
+  threw = false;
+  try { prepareRelogin({ username: "ghost" }); } catch (e) { threw = /不在池中/.test(e.message); }
+  check("prepare 不在池拒绝", threw);
+}
+
 console.log(`\n═══ 结果: ${pass} 通过, ${fail} 失败 ═══`);
 process.exit(fail > 0 ? 1 : 0);

package/scripts/test-protocol-bridge.mjs

@@ -0,0 +1,131 @@
+/**
+ * 协议桥单元测试 — parseProtocolUrl 白名单/参数校验 + 双平台模板生成
+ *
+ * 覆盖:
+ *   [1] URL 解析：合法样例（大小写 normalize / origin 归一 / 尾斜杠 / note 清洗）
+ *   [2] URL 拒绝：白名单外 action / 缺参 / 非 http server / username 非法 / scheme 不对
+ *   [3] 模板生成：AppleScript（osacompile 源）与 Windows 包装 cmd 的结构断言
+ *
+ * 运行: node scripts/test-protocol-bridge.mjs
+ */
+import { strict as assert } from "assert";
+import { parseProtocolUrl, buildAppleScript, buildWindowsCmd } from "../src/cli/protocol-bridge.js";
+
+let pass = 0;
+let fail = 0;
+const check = (name, fn) => {
+  try {
+    fn();
+    pass++;
+    console.log(`  ✓ ${name}`);
+  } catch (e) {
+    fail++;
+    console.log(`  ✗ ${name}: ${e.message}`);
+  }
+};
+
+// ── [1] 合法样例 ──
+console.log("[1] URL 解析（合法）");
+check("add 最小样例：host/path 解析 + server 取 origin", () => {
+  const p = parseProtocolUrl("tt-help://login-pool/add?server=http%3A%2F%2F172.18.154.201%3A3001");
+  assert.equal(p.action, "login-pool/add");
+  assert.equal(p.serverUrl, "http://172.18.154.201:3001");
+  assert.equal(p.username, undefined);
+});
+check("hostname 大写自动 normalize（非特殊 scheme 不自动小写，实测坑）", () => {
+  const p = parseProtocolUrl("tt-help://LOGIN-POOL/RELOGIN?server=https://x.io&username=u1");
+  assert.equal(p.action, "login-pool/relogin");
+});
+check("pathname 尾斜杠归一", () => {
+  const p = parseProtocolUrl("tt-help://login-pool/add/?server=http://x.io");
+  assert.equal(p.action, "login-pool/add");
+});
+check("server 路径丢弃只留 origin", () => {
+  const p = parseProtocolUrl("tt-help://login-pool/add?server=http%3A%2F%2Fx.io%2Fevil%2Fpath%3Fq%3D1");
+  assert.equal(p.serverUrl, "http://x.io");
+});
+check("username 字符集：字母数字点下划线", () => {
+  const p = parseProtocolUrl("tt-help://login-pool/relogin?server=http://x.io&username=user_1.2");
+  assert.equal(p.username, "user_1.2");
+});
+check("note 控制符清洗 + 200 限长", () => {
+  const long = "a".repeat(500);
+  const p = parseProtocolUrl(
+    "tt-help://login-pool/add?server=http://x.io&note=" +
+      encodeURIComponent("备\n注\x00" + long),
+  );
+  assert.equal(p.note, "备注" + "a".repeat(198));
+  assert.ok(!p.note.includes("\x00"));
+});
+check("未知参数静默忽略", () => {
+  const p = parseProtocolUrl("tt-help://login-pool/add?server=http://x.io&proxy=http://evil&dir=/etc");
+  assert.equal(p.proxy, undefined);
+  assert.equal(p.dir, undefined);
+});
+
+// ── [2] 拒绝样例 ──
+console.log("[2] URL 解析（拒绝）");
+const rejects = [
+  ["白名单外 action（check 不开放）", "tt-help://login-pool/check?server=http://x.io"],
+  ["任意命令形 action（防任意执行入口）", "tt-help://config/set?server=http://x.io"],
+  ["路径注入形 action", "tt-help://../../win.ini?server=http://x.io"],
+  ["scheme 不对", "https://login-pool/add?server=http://x.io"],
+  ["缺 server", "tt-help://login-pool/add"],
+  ["server 非 http(s)", "tt-help://login-pool/add?server=ftp://x.io"],
+  ["server 垃圾串", "tt-help://login-pool/add?server=not-a-url"],
+  ["relogin 缺 username", "tt-help://login-pool/relogin?server=http://x.io"],
+  ["username 空格", "tt-help://login-pool/relogin?server=http://x.io&username=a%20b"],
+  ["username 命令注入字符", "tt-help://login-pool/relogin?server=http://x.io&username=a%3Brm"],
+  ["username 超长", "tt-help://login-pool/relogin?server=http://x.io&username=" + "a".repeat(65)],
+  ["空 URL", ""],
+  ["null", null],
+];
+for (const [why, raw] of rejects) {
+  check(`拒绝: ${why}`, () => {
+    assert.throws(() => parseProtocolUrl(raw), Error);
+  });
+}
+
+// ── [3] 模板生成 ──
+console.log("[3] 双平台模板生成");
+const NODE = "/Users/x/.nvm/versions/node/v24.14.1/bin/node";
+const CLI = "/Users/x/pkg/tt-help-cli-ycl/cli.js";
+check("AppleScript: open location 处理器 + quoted form 拼接", () => {
+  const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
+  assert.ok(src.startsWith("on open location theURL"), "必须有 open location 处理器");
+  assert.ok(src.includes("quoted form of theURL"), "URL 必须经 quoted form 传递");
+  assert.ok(src.includes("open -a Terminal"), "必须拉起 Terminal");
+  assert.ok(src.includes("'#!/bin/bash"), "必须生成 .command（shebang）");
+});
+check("AppleScript: 生成源可通过 osacompile 语法结构（do shell script 成对引号）", () => {
+  const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
+  const m = src.match(/do shell script ("(?:[^"\\]|\\.)*")/);
+  assert.ok(m, "do shell script 后必须是合法 AppleScript 字符串字面量");
+  // 拼接表达式收尾
+  assert.ok(/& quoted form of theURL & "(?:[^"\\]|\\.)*"\s*\nend open location/.test(src), "拼接式必须完整闭合");
+});
+check("AppleScript: node 路径烧录且单引号包裹", () => {
+  const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
+  assert.ok(src.includes(`'${NODE}'`), "node 绝对路径必须烧录");
+  assert.ok(src.includes(`'${CLI}'`), "cli.js 绝对路径必须烧录");
+});
+check("AppleScript: 路径含空格时仍单引号安全", () => {
+  const src = buildAppleScript({ nodePath: "/Users/a b/n/node", cliPath: "/Users/a b/n/cli.js" });
+  assert.ok(src.includes("'/Users/a b/n/node'"), "含空格路径必须在单引号内");
+});
+check("AppleScript: .command 退出码保持 + 按键防闪退", () => {
+  const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
+  assert.ok(src.includes("st=$?"), "必须捕获退出码");
+  assert.ok(src.includes("read -n 1"), "必须按键保持窗口");
+});
+check("Windows cmd: 绝对路径 + %1 引号约定 + pause", () => {
+  const cmd = buildWindowsCmd({ nodePath: "C:\\n\\node.exe", cliPath: "C:\\p\\cli.js" });
+  assert.ok(cmd.startsWith("@echo off"), "必须关回显");
+  assert.ok(cmd.includes('"C:\\n\\node.exe" "C:\\p\\cli.js" protocol-handle %1'), "参数必须是单变量 %1");
+  assert.ok(cmd.includes("pause"), "必须 pause 防闪退");
+  assert.ok(cmd.includes("exit /b %RC%"), "必须透传退出码");
+  assert.ok(cmd.includes("\r\n"), "必须是 CRLF");
+});
+
+console.log(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail ? 1 : 0);

package/src/cli/login-pool.js

@@ -0,0 +1,207 @@
+/**
+ * handleLoginPool — 账号中心一条命令：新登录收号 / 重登录 / 巡检触发
+ *
+ * 用法:
+ *   tt-help login-pool add     [--server URL] [--proxy URL|--no-proxy] [--note S] [--dir D] [--timeout S]
+ *   tt-help login-pool relogin <username> [--server URL] [--proxy URL|--no-proxy] [--dir D] [--timeout S]
+ *   tt-help login-pool check   [--server URL] [--proxy URL] [--ids id1,id2] [--json]
+ *
+ * add:      起独立 Edge（临时目录+代理）→ 人工在窗口里登录 TikTok → 轮询 passport 检出
+ *           → 导出 cookies → POST /api/login-pool/import（幂等，同号跳过）
+ * relogin:  POST /prepare 取池内旧 cookies → 注入本机 Edge 试复活（快路径零操作）
+ *           → 会话已死则提示人工在窗口登录目标账号 → 身份校验 → POST /relogin 覆盖刷新
+ * check:    服务端无浏览器 HTTP 探测各号登录态（默认空闲+疑似），死号自动标疑似
+ *
+ * 协议桥（页面一键拉起本命令）为独立后续项，本命令即其执行端。
+ */
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { chromium } from "playwright";
+import { gotoTiktok, whoAmI } from "../lib/login-pool-client.js";
+import { proxy as configuredProxy } from "../lib/constants.js";
+
+const POLL_INTERVAL_MS = 3000;
+const CDP_FALLBACK_NOTE = "（关掉窗口或 Ctrl+C 可中止）";
+
+function log(t) {
+  console.error(`[登录池] ${t}`);
+}
+
+/** HTTP POST，默认 30s 超时（check 场景调用方自带更长超时） */
+async function post(base, path, body, timeoutMs = 30 * 1000) {
+  const res = await fetch(`${String(base).replace(/\/+$/, "")}/api/login-pool/${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body || {}),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const j = await res.json().catch(() => null);
+  if (!res.ok || !j || j.error) throw new Error((j && j.error) || `HTTP ${res.status}`);
+  return j;
+}
+
+/** 起独立 Edge 会话（launchPersistentContext: 跨平台自动找 Edge；临时目录随用随清） */
+async function openEdgeSession({ proxy, dir } = {}) {
+  const userDataDir = dir || mkdtempSync(join(tmpdir(), "tt-login-pool-"));
+  const context = await chromium.launchPersistentContext(userDataDir, {
+    channel: "msedge",
+    headless: false,
+    ...(proxy ? { proxy: { server: proxy } } : {}),
+    viewport: { width: 1280, height: 900 },
+    args: ["--no-first-run", "--no-default-browser-check", "--disable-sync"],
+  });
+  const page = context.pages()[0] || (await context.newPage());
+  return {
+    context,
+    page,
+    userDataDir,
+    cleanup: async () => {
+      await context.close().catch(() => {}); // persistent context close = 关浏览器
+      if (!dir) rmSync(userDataDir, { recursive: true, force: true });
+    },
+  };
+}
+
+/** 轮询等登录：注入 preCookies（重登录快路径）后循环 passport 检测 */
+async function waitForLogin({ page, preCookies, toPlaywrightCookies, timeoutMs }) {
+  const t0 = Date.now();
+  if (preCookies) {
+    await page.context().addCookies(preCookies);
+  }
+  await gotoTiktok(page);
+  for (;;) {
+    const id = await whoAmI(page);
+    if (id.hasAccount) return id;
+    if (Date.now() - t0 > timeoutMs) {
+      throw new Error(`等待登录超时（${Math.round(timeoutMs / 1000)}s）${CDP_FALLBACK_NOTE}`);
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+}
+
+/** add 子命令 */
+async function cmdAdd(opts) {
+  const { serverUrl, proxy, note, timeoutMs, dir } = opts;
+  log("启动 Edge，请在打开的窗口里登录 TikTok（等待中，随时可关窗口中止）…");
+  const session = await openEdgeSession({ proxy, dir });
+  try {
+    const id = await waitForLogin({ page: session.page, timeoutMs });
+    log(`检测到登录: @${id.username}，导出 cookies 并入池…`);
+    const cookies = await session.context.cookies();
+    const r = await post(serverUrl, "import", {
+      userId: "cli-login-pool",
+      username: id.username,
+      cookies,
+      note: note || "命令行新登录收号",
+    });
+    if (r.dedup) {
+      log(`✓ @${id.username} 已在池，幂等跳过（不覆盖）`);
+    } else {
+      log(`✓ @${id.username} 新入池（空闲），共 ${r.account.cookieCount} 条 cookies`);
+    }
+    log(`完成。服务端: ${serverUrl}`);
+  } finally {
+    await session.cleanup();
+  }
+}
+
+/** relogin 子命令 */
+async function cmdRelogin(opts) {
+  const { serverUrl, proxy, username, timeoutMs, dir } = opts;
+  if (!username) throw new Error("用法: tt-help login-pool relogin <username>");
+  const prep = await post(serverUrl, "prepare", { username });
+  const oldCookies = prep.account.cookies;
+  log(`目标 @${username}（池内 ${oldCookies.length} 条 cookies）。启动 Edge，先试旧登录态复活…`);
+  const toPlaywrightCookies = (cookies) =>
+    (cookies || []).map((c) => ({
+      name: c.name,
+      value: c.value,
+      domain: c.domain || ".tiktok.com",
+      path: c.path || "/",
+      secure: c.secure !== false,
+      httpOnly: c.httpOnly !== false,
+      ...(typeof c.expires === "number" && c.expires > 0 ? { expires: c.expires } : {}),
+    }));
+  const session = await openEdgeSession({ proxy, dir });
+  try {
+    let id = await waitForLogin({ page: session.page, preCookies: toPlaywrightCookies(oldCookies), timeoutMs: 20000 });
+    if (id.hasAccount && id.username === username) {
+      log("✓ 旧登录态仍存活（快路径，零操作）");
+    } else {
+      // 死号分支：清掉死 cookies，提示人工在窗口登录目标账号
+      log(`旧登录态已失效（${id.expired ? "会话过期" : "未登录"}）。请在窗口里登录 @${username}…`);
+      await session.context.clearCookies();
+      await gotoTiktok(session.page);
+      id = await waitForLogin({ page: session.page, timeoutMs });
+    }
+    if (id.username !== username) {
+      throw new Error(`身份不符：窗口登录的是 @${id.username}，目标是 @${username}，已中止（不更新池）`);
+    }
+    const cookies = await session.context.cookies();
+    const r = await post(serverUrl, "relogin", { username, cookies, userId: "cli-login-pool", note: "命令行重登录" });
+    log(
+      `✓ @${username} 重登录完成: cookies 已覆盖刷新（${r.account.cookieCount} 条）${r.revived ? "，已停用账号复活回池" : r.wasSuspect ? "，疑似已清回池" : ""}`,
+    );
+  } finally {
+    await session.cleanup();
+  }
+}
+
+/** check 子命令：触发服务端巡检（探测在服务端做，cookies 不出服务端） */
+async function cmdCheck(opts) {
+  const { serverUrl, proxy, ids, json } = opts;
+  log(`触发服务端巡检${proxy ? `（出口 ${proxy}）` : ""}…`);
+  const r = await post(serverUrl, "check", { ids: ids || undefined, proxy: proxy || undefined }, 15 * 60 * 1000);
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+  log(`巡检完成: 探测 ${r.checked}，活 ${r.alive} / 死 ${r.dead} / 异常 ${r.error}${r.migrated ? `，死号标疑似 ${r.migrated} 个` : ""}`);
+  for (const x of r.results || []) {
+    if (x.health !== "alive") {
+      log(`  ${x.health === "dead" ? "✗" : "?"} @${x.username} → ${x.status}${x.migrated ? "（pool→suspect）" : ""}`);
+    }
+  }
+}
+
+/**
+ * @param {object} parsed parseLoginPoolArgs 结果
+ *   { action, username, serverUrl, proxy(null=用配置默认), noProxy, note, dir, timeoutSec, ids, showHelp, json }
+ */
+export async function handleLoginPool(parsed) {
+  const {
+    action,
+    username,
+    serverUrl,
+    proxy: proxyArg,
+    noProxy,
+    note,
+    dir,
+    timeoutSec = 300,
+    ids,
+    json,
+    showHelp,
+  } = parsed;
+  if (showHelp || !action) {
+    console.error(
+      [
+        "用法:",
+        "  tt-help login-pool add     [--server URL] [--proxy URL|--no-proxy] [--note S] [--dir D] [--timeout S]",
+        "  tt-help login-pool relogin <username> [--server URL] [--proxy URL|--no-proxy] [--dir D] [--timeout S]",
+        "  tt-help login-pool check   [--server URL] [--proxy URL] [--ids id1,id2] [--json]",
+        "",
+        "  add     新登录收号：弹出 Edge 人工登录 TikTok，检出后自动入池（幂等）",
+        "  relogin 重登录：先试旧登录态复活（零操作），死了引导人工登录，身份校验后覆盖刷新",
+        "  check   巡检：服务端 HTTP 探测各号登录态，死号自动标疑似",
+      ].join("\n"),
+    );
+    return;
+  }
+  const proxy = noProxy ? null : proxyArg || configuredProxy || null;
+  const opts = { serverUrl, proxy, note, dir, timeoutMs: timeoutSec * 1000, ids, json };
+  if (action === "add") return cmdAdd(opts);
+  if (action === "relogin") return cmdRelogin({ ...opts, username: username || parsed.username });
+  if (action === "check") return cmdCheck(opts);
+  throw new Error(`未知子命令: ${action}（支持 add / relogin / check）`);
+}