tt-help-cli-ycl 1.4.177 → 1.4.179

package/src/cli/protocol-bridge.js

@@ -0,0 +1,274 @@
+/**
+ * handleProtocolBridge — 协议桥：tt-help:// 自定义协议（网页 /login-pool 一键拉起本机命令）
+ *
+ * 用法:
+ *   tt-help protocol register      注册本机协议处理器（幂等，可重复执行）
+ *   tt-help protocol unregister    注销协议处理器
+ *   tt-help protocol handle <URL>  内部入口：处理器被系统拉起时回调（勿手动执行）
+ *
+ * 链路（2026-10-29 设计定稿，macOS 路线已经真机 POC）:
+ *   页面按钮 → tt-help://login-pool/<add|relogin>?server=…&username=…
+ *     → OS 协议处理器
+ *       ├─ Windows: HKCU\Software\Classes\tt-help → 包内 scripts/protocol-bridge.cmd（新控制台窗+pause）
+ *       └─ macOS:   ~/Applications/tt-help.app（osacompile AppleScript applet，open location 收 URL
+ *                    —— shell 型 .app 收 argv 已实测不通：LS 只发 AppleEvent，argc=0）
+ *     → tt-help protocol handle <URL> → 白名单校验 → 进程内直调 handleLoginPool（全程不过 shell）
+ *
+ * 安全: action 白名单只认 login-pool/add、login-pool/relogin；参数只透传
+ *       server(origin)/username(字符集白名单)/note(去控制符限长)；proxy/dir/timeout 不开放。
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { homedir, platform, tmpdir } from "os";
+import { join } from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { handleLoginPool } from "./login-pool.js";
+
+const SCHEME = "tt-help";
+const ALLOWED_ACTIONS = new Set(["login-pool/add", "login-pool/relogin"]);
+const MAC_APP_DIR = join(homedir(), "Applications");
+const MAC_APP = join(MAC_APP_DIR, "tt-help.app");
+const BUNDLE_ID = "com.ycl.tt-help";
+const WIN_REG_KEY = `HKCU\\Software\\Classes\\${SCHEME}`;
+
+function log(t) {
+  console.error(`[协议桥] ${t}`);
+}
+
+/** POSIX 单引号转义（用于 .command / do shell script 中的路径与 URL） */
+function shQ(s) {
+  return `'${String(s).replace(/'/g, "'\\''")}'`;
+}
+
+/** package 根目录（本文件位于 <pkg>/src/cli/） */
+function pkgRoot() {
+  return fileURLToPath(new URL("../..", import.meta.url));
+}
+
+// ────────────────────────── URL 解析（handle 入口） ──────────────────────────
+
+/**
+ * 解析并校验协议 URL → { action, serverUrl, username?, note? }
+ * 注意: 非特殊 scheme 的 URL.hostname 不自动小写，必须显式 normalize（实测 LOGIN-POOL 原样保留）
+ */
+export function parseProtocolUrl(raw) {
+  if (!raw) throw new Error("缺少 URL 参数");
+  let u;
+  try {
+    u = new URL(String(raw).trim());
+  } catch {
+    throw new Error(`URL 无法解析: ${String(raw).slice(0, 120)}`);
+  }
+  if (u.protocol !== `${SCHEME}:`) throw new Error(`不支持的协议: ${u.protocol}（只认 ${SCHEME}://）`);
+  const action = `${u.hostname}${u.pathname.replace(/\/+$/, "")}`.toLowerCase();
+  if (!ALLOWED_ACTIONS.has(action)) {
+    throw new Error(`不支持的 action: ${action}（白名单: ${[...ALLOWED_ACTIONS].join(", ")}）`);
+  }
+  const server = u.searchParams.get("server") || "";
+  let s;
+  try {
+    s = new URL(server);
+  } catch {
+    throw new Error("server 参数缺失或非法（需完整 http(s) URL）");
+  }
+  if (s.protocol !== "http:" && s.protocol !== "https:") throw new Error("server 仅支持 http/https");
+  const out = { action, serverUrl: s.origin };
+  if (action === "login-pool/relogin") {
+    const username = u.searchParams.get("username") || "";
+    if (!/^[A-Za-z0-9._]{1,64}$/.test(username)) throw new Error(`username 参数缺失或含非法字符: "${username.slice(0, 40)}"`);
+    out.username = username;
+  }
+  const note = (u.searchParams.get("note") || "").replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200);
+  if (note) out.note = note;
+  return out;
+}
+
+/** handle 入口：解析 URL → 进程内直调 handleLoginPool（不经过任何 shell） */
+async function cmdHandle(rawUrl) {
+  let p;
+  try {
+    p = parseProtocolUrl(rawUrl);
+  } catch (e) {
+    log(`✗ ${e.message}`);
+    throw e;
+  }
+  log(`收到 ${p.action}（server=${p.serverUrl}${p.username ? `，@${p.username}` : ""}）`);
+  const parsed = {
+    subcommand: "login-pool",
+    action: p.action.split("/")[1],
+    username: p.username || null,
+    serverUrl: p.serverUrl,
+    proxy: null, // 走本机 ~/.tt-help.json 默认（与命令行行为一致）
+    noProxy: false,
+    note: p.note || null,
+    dir: null,
+    timeoutSec: 300,
+    ids: null,
+    json: false,
+    showHelp: false,
+  };
+  await handleLoginPool(parsed);
+}
+
+// ────────────────────────── macOS: osacompile applet ──────────────────────────
+
+/** 生成 .applescript 源：open location → 建 .command（烧录绝对路径）→ open -a Terminal */
+export function buildAppleScript({ nodePath, cliPath }) {
+  const asStr = (s) => `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  // .command 内容: #!/bin/bash + 跑 node（不 exec，退出码非 0 时窗口必留）+ 按键保持
+  const shellP1 =
+    "t=$(mktemp ${TMPDIR:-/tmp}/tt-help-bridge.XXXXXX); f=\"$t.command\"; mv \"$t\" \"$f\"; " + // mktemp 要求 X 结尾，先随机后 mv 补 .command 后缀（实测：直接带后缀会退化成固定名，并发互踩）
+    "printf '#!/bin/bash\\n%s %s protocol-handle %s\\nst=$?\\necho\\nrm -f \"$0\"\\nread -n 1 -s -r -p \"完成（退出码 $st）——按任意键关闭…\"\\nexit $st\\n' " +
+    `${shQ(nodePath)} ${shQ(cliPath)} `;
+  const shellP2 = ' > "$f"; chmod +x "$f"; /usr/bin/open -a Terminal "$f"';
+  return (
+    "on open location theURL\n" +
+    "  do shell script " + asStr(shellP1) + " & quoted form of theURL & " + asStr(shellP2) + "\n" +
+    "end open location\n"
+  );
+}
+
+const MAC_LSREG =
+  "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+const MAC_PLISTBUDDY = "/usr/libexec/PlistBuddy";
+
+function macRun(cmd, args, { check = true } = {}) {
+  const r = spawnSync(cmd, args, { encoding: "utf-8" });
+  if (check && r.status !== 0) {
+    throw new Error(`${cmd} 失败（退出码 ${r.status}）: ${(r.stderr || r.stdout || "").slice(0, 300)}`);
+  }
+  return r;
+}
+
+/** PlistBuddy 设值：存在则 Set，不存在则 Add */
+function plistSet(plist, key, type, value) {
+  let r = macRun(MAC_PLISTBUDDY, ["-c", `Set :${key} ${value}`, plist], { check: false });
+  if (r.status !== 0) {
+    r = macRun(MAC_PLISTBUDDY, ["-c", `Add :${key} ${type} ${value}`, plist], { check: false });
+    if (r.status !== 0) throw new Error(`PlistBuddy 写入 ${key} 失败: ${(r.stderr || "").slice(0, 200)}`);
+  }
+}
+
+function registerDarwin() {
+  const osacompile = "/usr/bin/osacompile";
+  if (!existsSync(osacompile)) throw new Error("找不到 /usr/bin/osacompile（macOS 系统自带，异常情况）");
+  const nodePath = process.execPath;
+  const cliPath = join(pkgRoot(), "cli.js");
+  if (!existsSync(cliPath)) throw new Error(`找不到 cli.js: ${cliPath}`);
+
+  mkdirSync(MAC_APP_DIR, { recursive: true });
+  const src = join(mkdtempSync(join(tmpdir(), "tt-help-reg-")), "tt-help.applescript");
+  writeFileSync(src, buildAppleScript({ nodePath, cliPath }));
+
+  log(`编译 applet（node=${nodePath}）…`);
+  rmSync(MAC_APP, { recursive: true, force: true });
+  macRun(osacompile, ["-o", MAC_APP, src]);
+
+  const plist = join(MAC_APP, "Contents", "Info.plist"); // PlistBuddy 只认 plist 文件，不认 .app 目录
+  plistSet(plist, "CFBundleIdentifier", "string", BUNDLE_ID);
+  plistSet(plist, "CFBundleName", "string", "tt-help");
+  plistSet(plist, "LSUIElement", "bool", "true"); // 不占 Dock
+  // URL scheme 声明（POC 验证过的 PlistBuddy 注入路径）
+  macRun(MAC_PLISTBUDDY, ["-c", "Add :CFBundleURLTypes array", plist], { check: false });
+  macRun(MAC_PLISTBUDDY, ["-c", "Add :CFBundleURLTypes:0 dict", plist], { check: false });
+  plistSet(plist, "CFBundleURLTypes:0:CFBundleURLName", "string", BUNDLE_ID);
+  macRun(MAC_PLISTBUDDY, ["-c", "Add :CFBundleURLTypes:0:CFBundleURLSchemes array", plist], { check: false });
+  macRun(MAC_PLISTBUDDY, ["-c", `Add :CFBundleURLTypes:0:CFBundleURLSchemes:0 string ${SCHEME}`, plist], { check: false });
+  macRun("/usr/bin/codesign", ["--force", "--deep", "-s", "-", MAC_APP], { check: false }); // ad-hoc 重签，尽力而为
+
+  macRun(MAC_LSREG, ["-f", MAC_APP]);
+  rmSync(src, { force: true });
+  rmSync(join(src, ".."), { recursive: true, force: true });
+  log(`✓ 已注册 ${SCHEME}:// 协议处理器: ${MAC_APP}`);
+  log("  验证: 浏览器打开 /login-pool 页面点「新增账号」即可一键拉起；或执行:");
+  log(`  open "${SCHEME}://login-pool/add?server=http%3A%2F%2F127.0.0.1%3A3001"`);
+}
+
+function unregisterDarwin() {
+  if (!existsSync(MAC_APP)) {
+    log(`未发现已注册的处理器（${MAC_APP} 不存在），无需注销`);
+    return;
+  }
+  macRun(MAC_LSREG, ["-u", MAC_APP], { check: false });
+  rmSync(MAC_APP, { recursive: true, force: true });
+  log(`✓ 已注销并删除 ${MAC_APP}`);
+}
+
+// ────────────────────────── Windows: HKCU + 包内包装 cmd ──────────────────────────
+
+/**
+ * 生成包装 cmd 内容（register 时写进包 scripts/ 目录，npm 升级原地覆盖，注册表路径永不变）
+ * %1 恒由注册表带引号传入 + URL 参数百分号编码 = 无注入面；pause 保证最终结果不闪退
+ */
+export function buildWindowsCmd({ nodePath, cliPath }) {
+  return [
+    "@echo off",
+    "title tt-help 登录池",
+    `"${nodePath}" "${cliPath}" protocol-handle %1`,
+    "set RC=%ERRORLEVEL%",
+    "echo.",
+    `pause`,
+    "exit /b %RC%",
+    "",
+  ].join("\r\n");
+}
+
+function registerWindows() {
+  const nodePath = process.execPath;
+  const cliPath = join(pkgRoot(), "cli.js");
+  const wrapperPath = join(pkgRoot(), "scripts", "protocol-bridge.cmd");
+  writeFileSync(wrapperPath, buildWindowsCmd({ nodePath, cliPath }), "utf-8");
+
+  const regAdd = (args) => macRun("reg", ["add", ...args]);
+  regAdd([WIN_REG_KEY, "/ve", "/d", `URL:${SCHEME}`, "/f"]);
+  regAdd([WIN_REG_KEY, "/v", "URL Protocol", "/d", "", "/f"]);
+  regAdd([`${WIN_REG_KEY}\\shell\\open\\command`, "/ve", "/d", `"${wrapperPath}" "%1"`, "/f"]);
+  log(`✓ 已注册 ${SCHEME}:// 协议处理器（HKCU，免管理员）: ${wrapperPath}`);
+  log("  验证: 浏览器打开 /login-pool 页面点「新增账号」；首次系统会弹「打开 tt-help?」确认框");
+}
+
+function unregisterWindows() {
+  const r = macRun("reg", ["delete", WIN_REG_KEY, "/f"], { check: false });
+  if (r.status !== 0) {
+    log(`未发现已注册的处理器（注册表 ${WIN_REG_KEY} 不存在），无需注销`);
+    return;
+  }
+  log(`✓ 已注销注册表项 ${WIN_REG_KEY}（包装 cmd 随包升级/卸载自然消失）`);
+}
+
+// ────────────────────────── 入口 ──────────────────────────
+
+/**
+ * @param {object} parsed parseProtocolBridgeArgs 结果 { action, url, showHelp }
+ */
+export async function handleProtocolBridge(parsed) {
+  const { action, url, showHelp } = parsed;
+  if (showHelp || !action) {
+    console.error(
+      [
+        "用法:",
+        `  tt-help protocol register              注册 ${SCHEME}:// 协议处理器（幂等）`,
+        `  tt-help protocol unregister            注销协议处理器`,
+        `  tt-help protocol handle <URL>          内部命令：处理器回调入口（勿手动执行）`,
+        "",
+        "  协议桥 = 网页 /login-pool「新增账号/重登录」按钮一键拉起本机 tt-help 命令。",
+        "  注册一次后，页面按钮直接弹出登录窗口（Windows/macOS；Linux 后置）。",
+      ].join("\n"),
+    );
+    return;
+  }
+  if (action === "handle") return cmdHandle(url);
+  if (action === "register") {
+    if (platform() === "darwin") return registerDarwin();
+    if (platform() === "win32") return registerWindows();
+    log("Linux 平台暂不支持（后置）。协议桥面向操作员桌面机（Windows/macOS）。");
+    return;
+  }
+  if (action === "unregister") {
+    if (platform() === "darwin") return unregisterDarwin();
+    if (platform() === "win32") return unregisterWindows();
+    log("Linux 平台暂不支持（后置）。");
+    return;
+  }
+  throw new Error(`未知子命令: ${action}（支持 register / unregister / handle）`);
+}

package/src/lib/args.js

@@ -1167,6 +1167,83 @@ function parseLoginCheckArgs(args) {
   };
 }
 
+function parseLoginPoolArgs(args) {
+  let action = null;
+  let username = null;
+  let serverUrl = defaultServer;
+  let proxy = null;
+  let noProxy = false;
+  let note = null;
+  let dir = null;
+  let timeoutSec = 300;
+  let ids = null;
+  let json = false;
+  let showHelp = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--server" && i + 1 < args.length) {
+      serverUrl = args[++i];
+    } else if (arg === "--proxy" && i + 1 < args.length) {
+      proxy = args[++i];
+    } else if (arg === "--no-proxy") {
+      noProxy = true;
+    } else if (arg === "--note" && i + 1 < args.length) {
+      note = args[++i];
+    } else if (arg === "--dir" && i + 1 < args.length) {
+      dir = args[++i];
+    } else if (arg === "--timeout" && i + 1 < args.length) {
+      timeoutSec = parseInt(args[++i], 10) || 300;
+    } else if (arg === "--ids" && i + 1 < args.length) {
+      ids = args[++i].split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (arg === "--json") {
+      json = true;
+    } else if (arg === "-h" || arg === "--help") {
+      showHelp = true;
+    } else if (!arg.startsWith("-")) {
+      if (!action) action = arg;
+      else if (!username) username = arg;
+    }
+  }
+
+  return {
+    subcommand: "login-pool",
+    action,
+    username,
+    serverUrl,
+    proxy,
+    noProxy,
+    note,
+    dir,
+    timeoutSec,
+    ids,
+    json,
+    showHelp,
+    urls: [],
+    outputFormat: "json",
+    exploreCount: 0,
+    showConfig: false,
+    showVersion: false,
+    customProxy: null,
+    configAction: null,
+    configValue: null,
+    pipeMode: false,
+    filterStr: null,
+  };
+}
+
+function parseProtocolBridgeArgs(args) {
+  let action = null;
+  let url = null;
+  let showHelp = false;
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") showHelp = true;
+    else if (!action) action = arg;
+    else if (!url) url = arg;
+  }
+  return { subcommand: "protocol", action, url, showHelp };
+}
+
 function parseOpenArgs(args) {
   let openPort = null;
   let openList = false;
@@ -1721,6 +1798,14 @@ export function parseArgs() {
     return parseLoginCheckArgs(args.slice(1));
   }
 
+  if (args.length > 0 && args[0] === "login-pool") {
+    return parseLoginPoolArgs(args.slice(1));
+  }
+
+  if (args.length > 0 && args[0] === "protocol") {
+    return parseProtocolBridgeArgs(args.slice(1));
+  }
+
   if (args.length > 0 && args[0] === "comments") {
     return parseCommentsArgs(args.slice(1));
   }

package/src/lib/constants.js

@@ -291,12 +291,30 @@ const HELP_TEXT = [
   "    示例: tt-help login-check 9222,9223,9224 --proxy http://127.0.0.1:7897",
   "          tt-help login-check --json",
   "",
-  "  videostats  <db路径> -p <并发数>",
-  "    批量刷新视频统计数据（playCount, diggCount, commentCount, shareCount, collectCount）",
-  "    直接读取并更新 SQLite videos 表",
-  "    -p, --parallel <N>       并发数（默认: 3）",
+  "  tt-help login-pool <add|relogin|check> [选项]",
+  "    账号中心：新登录收号 / 重登录 / 巡检（与网页 /login-pool 同一套账号库）",
+  "    add     弹出独立 Edge，人工登录 TikTok 后自动导出登录态入池（幂等）",
+  "    relogin <username>  先试旧登录态复活（零操作），失效则引导人工登录，覆盖刷新池内 cookies",
+  "    选项:",
+  "      --server <URL>            账号中心地址（watch 服务端）",
+  "      --proxy <地址>            Edge/探测代理，默认配置文件 proxy；--no-proxy 直连",
+  "      --note <备注>             add 备注信息",
+  "      --dir <路径>              自定义 Edge 用户目录（默认临时目录用后即清）",
+  "      --timeout <秒>            等待人工登录上限，默认 300",
+  "      --ids <id1,id2>           check 只探测指定账号",
+  "      --json                    check 输出 JSON",
+  "    示例: tt-help login-pool add --server http://172.18.154.201:3011",
+  "          tt-help login-pool relogin user8868337530661 --server http://172.18.154.201:3011",
+  "          tt-help login-pool check --server http://172.18.154.201:3011 --proxy http://127.0.0.1:7897",
   "    示例: tt-help videostats data/result.db -p 3",
   "",
+  "  tt-help protocol <register|unregister|handle> [URL]",
+  "    协议桥：注册 tt-help:// 协议处理器，网页 /login-pool 按钮一键拉起本机命令（Windows/macOS）",
+  "    register     注册处理器（幂等；Windows 写 HKCU，macOS 生成 ~/Applications/tt-help.app）",
+  "    unregister   注销处理器",
+  "    handle <URL> 内部命令：处理器回调入口（系统拉起时调用，勿手动执行）",
+  "    示例: tt-help protocol register",
+  "",
   "  db-import  --db <db路径> [--users users.json] [--done done.json] [--videos videos.json]",
   "    将 legacy JSON 显式导入 SQLite；运行期不再自动读取 result*.json",
   "    示例: tt-help db-import --db data/result.db --users data/result.json --done data/result-done.json --videos data/result-videos.json",

package/src/main.js

@@ -27,6 +27,8 @@ import { handleSearch } from "./cli/search.js";
 import { handleWatchdog } from "./cli/watchdog.js";
 import { handleClashDaemon } from "./cli/clash-daemon.js";
 import { handleLoginCheck } from "./cli/login-check.js";
+import { handleLoginPool } from "./cli/login-pool.js";
+import { handleProtocolBridge } from "./cli/protocol-bridge.js";
 
 async function main() {
   const parsed = parseArgs();
@@ -80,6 +82,10 @@ async function main() {
       return handleClashDaemon(parsed);
     case "login-check":
       return handleLoginCheck(parsed);
+    case "login-pool":
+      return handleLoginPool(parsed);
+    case "protocol":
+      return handleProtocolBridge(parsed);
   }
 
   const {

package/src/npm-main.js

@@ -23,6 +23,8 @@ import { handleRawSync } from "./cli/raw-sync.js";
 import { handleSearch } from "./cli/search.js";
 import { handleWatchdog } from "./cli/watchdog.js";
 import { handleLoginCheck } from "./cli/login-check.js";
+import { handleLoginPool } from "./cli/login-pool.js";
+import { handleProtocolBridge } from "./cli/protocol-bridge.js";
 
 function exitUnsupportedCommand(command) {
   console.error(
@@ -79,6 +81,10 @@ async function main() {
       return handleWatchdog(parsed);
     case "login-check":
       return handleLoginCheck(parsed);
+    case "login-pool":
+      return handleLoginPool(parsed);
+    case "protocol":
+      return handleProtocolBridge(parsed);
   }
 
   const {

package/src/watch/login-health.js

@@ -0,0 +1,108 @@
+/**
+ * 登录态批量巡检（账号中心）— 服务端无浏览器纯 HTTP 探测
+ *
+ * 原理（POC 实证 2026-10-28，见知识库 worklog）：
+ *   undici + Cookie 头 + 真实 UA + 代理出口，直探 passport/web/account/info/。
+ *   浏览器里必须页面上下文 fetch（CORS），服务端无此限制。阳性对照（真实 cookies）
+ *   判活 / 阴性对照（垃圾 sessionid）判死均已验证，单次 ~700ms。
+ *
+ * 判据边界：探测只回答「登录态还活着吗」，不回答「号还能不能干活」——
+ *   风控限流/影子封禁只有真实业务出活能暴露。
+ */
+import { request, ProxyAgent } from "undici";
+import { healthTargets, recordHealth } from "./login-pool.js";
+
+const ACCOUNT_INFO_URL = "https://www.tiktok.com/passport/web/account/info/";
+const UA =
+  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36 Edg/155.0.0.0";
+const DEFAULT_TIMEOUT_MS = 20 * 1000;
+const DEFAULT_PACING_MS = 250;
+
+/** proxyHint 归一化：纯数字 → http://127.0.0.1:<port>；http(s):// 开头 → 原样；其余忽略 */
+function normalizeProxy(hint) {
+  const s = String(hint || "").trim();
+  if (!s) return null;
+  if (/^\d{2,5}$/.test(s)) return `http://127.0.0.1:${s}`;
+  if (/^https?:\/\//.test(s)) return s;
+  return null;
+}
+
+/**
+ * 无浏览器探测单个账号登录态
+ * @param {Array} cookies 池内 cookies 数组 [{name,value,domain?...}]
+ * @param {object} opts { proxy?: string|null, timeoutMs?: number }
+ * @returns {Promise<{alive: boolean, username: ?string, expired: boolean, httpStatus: number, error: ?string, ms: number}>}
+ */
+export async function probeLogin(cookies, { proxy = null, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const cookieHeader = (cookies || [])
+    .filter((c) => c && c.name && c.value != null)
+    .filter((c) => !c.domain || String(c.domain).includes("tiktok"))
+    .map((c) => `${c.name}=${c.value}`)
+    .join("; ");
+  const t0 = Date.now();
+  try {
+    const res = await request(ACCOUNT_INFO_URL, {
+      method: "GET",
+      headers: {
+        cookie: cookieHeader,
+        "user-agent": UA,
+        accept: "application/json",
+        "accept-language": "en-US,en;q=0.9",
+      },
+      ...(proxy ? { dispatcher: new ProxyAgent(proxy) } : {}),
+      headersTimeout: timeoutMs,
+      bodyTimeout: timeoutMs,
+    });
+    const body = await res.body.json().catch(() => null);
+    const ms = Date.now() - t0;
+    const d = (body && body.data) || null;
+    return {
+      httpStatus: res.status,
+      alive: !!d && !!(d.username || d.user_id || d.sec_user_id),
+      username: (d && d.username) || null,
+      expired: (d && d.name === "session_expired") || (body && body.error_code === 13),
+      error: body && !d ? JSON.stringify(body).slice(0, 120) : null,
+      ms,
+    };
+  } catch (e) {
+    return { httpStatus: 0, alive: false, username: null, expired: false, error: String(e).slice(0, 120), ms: Date.now() - t0 };
+  }
+}
+
+/**
+ * 批量巡检：默认探 pool+suspect（leased 由消费方验证兜底、retired 不探测），指定 ids 精确取。
+ * 结果逐号 recordHealth 落账（dead 且在池 → suspect）；串行 + pacing，对 TikTok 友好。
+ * @param {object} opts { ids?: string[], proxy?: string|null(缺省用各号 proxyHint), pacingMs?, probeFn?(测试注入) }
+ * @returns {Promise<{checked: number, alive: number, dead: number, error: number, migrated: number, results: Array}>}
+ */
+export async function checkPoolAccounts(opts = {}) {
+  const { ids, proxy = null, pacingMs = DEFAULT_PACING_MS, probeFn = probeLogin } = opts;
+  const targets = healthTargets({ ids });
+  const summary = { checked: 0, alive: 0, dead: 0, error: 0, migrated: 0, results: [] };
+  for (let i = 0; i < targets.length; i++) {
+    const t = targets[i];
+    const exit = proxy || normalizeProxy(t.proxyHint);
+    const r = await probeFn(t.cookies, { proxy: exit });
+    const ok = r.error ? "error" : r.alive ? "alive" : "dead";
+    let rec = { username: t.username, health: ok, status: t.status, ms: r.ms };
+    try {
+      const applied = recordHealth({
+        id: t.id,
+        ok,
+        detail: r.error ? `探测异常 ${r.error}` : r.alive ? "" : r.expired ? "会话过期" : "未登录",
+      });
+      rec.status = applied.status;
+      if (applied.migrated) rec.migrated = true;
+    } catch (e) {
+      rec.error = e.message;
+    }
+    summary[ok]++;
+    summary.checked++;
+    if (rec.migrated) summary.migrated++;
+    summary.results.push(rec);
+    if (i < targets.length - 1 && pacingMs > 0) {
+      await new Promise((res) => setTimeout(res, pacingMs));
+    }
+  }
+  return summary;
+}

package/src/watch/login-pool.js

@@ -229,6 +229,7 @@ function publicView(acc) {
     lastImportFrom: acc.lastImportFrom || null,
     // 最近使用镜像（脱离 lease 独立存在，释放/回收后仍可见）
     lastHealthAt: acc.lastHealthAt || null,
+    lastHealth: acc.lastHealth || null,
     lastBusinessOkAt: acc.lastBusinessOkAt || null,
     lastUsedAt: acc.lastUsedAt || null,
     lease,
@@ -754,6 +755,108 @@ export function importAccount({ userId, port, username, cookies, note, proxyHint
 /** 来源元数据（供节点热路径跳过 + 账号中心展示），非租约；新入池与幂等补写共用此定义 */
 const importMeta = (userId, portNum, at) => ({ userId, port: portNum, at });
 
+/**
+ * 重登录：按 username 覆盖刷新 cookies（区别于 import 的「已在池即幂等跳过」）。
+ * 守卫：目标必须已在池（新号走 import/add）；使用中（leased）拒绝——先等节点换号/手动释放；
+ *   retired 重登录=复活回 pool；suspect 刷新后回 pool；空闲则原地刷新。
+ * username 必须来自 passport 活体验证（调用方已验，且须与目标一致——身份不符由调用方拦截），
+ * cookies 必须非空。
+ */
+export function reloginAccount({ username, cookies, userId, note } = {}) {
+  ensureLoaded();
+  reapExpiredLeases();
+  if (!username) throw new Error("username 必填（重登录目标）");
+  if (!userId) throw new Error("userId 必填（操作来源）");
+  const norm = normalizeCookies(cookies);
+  if (!norm) throw new Error("cookies 必须是非空数组，且每项含 name/value");
+  const acc = _accounts.find((a) => a.username === username);
+  if (!acc) throw new Error(`账号 ${username} 不在池中（重登录仅针对已有账号，新号走 import/add）`);
+  if (acc.status === "leased") {
+    const w = acc.lease;
+    throw new Error(
+      `账号 ${username} 使用中（${w?.userId || "?"}${w?.port ? ":" + w.port : ""}），先释放再重登录`,
+    );
+  }
+  const revived = acc.status === "retired";
+  const wasSuspect = acc.status === "suspect";
+  acc.cookies = norm;
+  acc.status = "pool";
+  acc.updatedAt = now();
+  pushHistory(
+    acc,
+    "relogin",
+    `${revived ? "重登录复活（已停用→池）" : wasSuspect ? "重登录（疑似→池）" : "重登录刷新"} · ${userId}${note ? ` · ${String(note).slice(0, 80)}` : ""}`,
+  );
+  scheduleSave();
+  return { account: publicView(acc), revived, wasSuspect };
+}
+
+/**
+ * 巡检目标：默认取 pool+suspect（leased 由消费方验证兜底、retired 不探测）；
+ * 指定 ids 时按 id 精确取（仍排除 retired）。返回含明文 cookies，仅限服务端进程内使用。
+ */
+export function healthTargets({ ids } = {}) {
+  ensureLoaded();
+  reapExpiredLeases();
+  const idSet = Array.isArray(ids) && ids.length ? new Set(ids) : null;
+  return _accounts
+    .filter((a) => a.status !== "retired")
+    .filter((a) => (idSet ? idSet.has(a.id) : a.status === "pool" || a.status === "suspect"))
+    .map((a) => ({
+      id: a.id,
+      username: a.username,
+      status: a.status,
+      proxyHint: a.proxyHint || "",
+      cookies: a.cookies,
+    }));
+}
+
+/**
+ * 巡检结果落账：lastHealthAt + lastHealth('alive'|'dead'|'error')。
+ * dead 且在池 → 迁移 suspect（业务不再自动取到死号）；alive 不写 history（避免刷屏，
+ * HISTORY_MAX 只有 20 条）；dead/error 才记 history。leased/retired 仅记录不迁移状态。
+ */
+export function recordHealth({ id, ok, detail } = {}) {
+  ensureLoaded();
+  const acc = _accounts.find((x) => x.id === id);
+  if (!acc) throw new Error(`账号不存在: ${id}`);
+  acc.lastHealthAt = now();
+  acc.lastHealth = ok; // 'alive' | 'dead' | 'error'
+  let migrated = false;
+  if (ok === "dead" && acc.status === "pool") {
+    acc.status = "suspect";
+    migrated = true;
+  }
+  if (ok !== "alive" || migrated) {
+    pushHistory(
+      acc,
+      "health",
+      `${ok}${detail ? ` · ${String(detail).slice(0, 80)}` : ""}${migrated ? " · pool→suspect" : ""}`,
+    );
+  }
+  scheduleSave();
+  return { username: acc.username, status: acc.status, migrated };
+}
+
+/**
+ * 重登录预备：返回目标账号明文 cookies（relogin 命令注入旧登录态用）。
+ * 守卫与 reloginAccount 一致：必须在池、使用中拒绝。
+ */
+export function prepareRelogin({ username } = {}) {
+  ensureLoaded();
+  reapExpiredLeases();
+  if (!username) throw new Error("username 必填");
+  const acc = _accounts.find((a) => a.username === username);
+  if (!acc) throw new Error(`账号 ${username} 不在池中`);
+  if (acc.status === "leased") {
+    const w = acc.lease;
+    throw new Error(
+      `账号 ${username} 使用中（${w?.userId || "?"}${w?.port ? ":" + w.port : ""}），先释放再重登录`,
+    );
+  }
+  return { account: fullView(acc) };
+}
+
 /** 内部：注入账号（测试/迁移工具用，跳过命令队列直接改状态） */
 export function _accountsInternal() {
   ensureLoaded();