tt-help-cli-ycl 1.4.179 → 1.4.182

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

@@ -157,7 +157,7 @@ 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:not([disabled])", (bs) => bs.some((b) => b.textContent.includes("重登录"))));
+check("独立页检测按钮已点亮（重登录已改名）", await page.$$eval("#content button:not([disabled])", (bs) => bs.some((b) => b.textContent.trim() === "检测")));
 check("独立页含新增账号/批量检测按钮", await page.$$eval(".bar button", (bs) => {
   const t = bs.map((b) => b.textContent).join();
   return t.includes("新增账号") && t.includes("批量检测");

package/scripts/test-protocol-bridge.mjs

@@ -1,15 +1,17 @@
 /**
- * 协议桥单元测试 — parseProtocolUrl 白名单/参数校验 + 双平台模板生成
+ * 协议桥单元测试 — parseProtocolUrl 白名单/参数校验 + 双平台模板生成 + 单 token 别名路由
  *
  * 覆盖:
  *   [1] URL 解析：合法样例（大小写 normalize / origin 归一 / 尾斜杠 / note 清洗）
  *   [2] URL 拒绝：白名单外 action / 缺参 / 非 http server / username 非法 / scheme 不对
  *   [3] 模板生成：AppleScript（osacompile 源）与 Windows 包装 cmd 的结构断言
+ *   [4] 别名路由：protocol-handle 单 token（OS 拉起链路兼容；parseArgs 无参签名读 process.argv）
  *
  * 运行: node scripts/test-protocol-bridge.mjs
  */
 import { strict as assert } from "assert";
 import { parseProtocolUrl, buildAppleScript, buildWindowsCmd } from "../src/cli/protocol-bridge.js";
+import { parseArgs } from "../src/lib/args.js";
 
 let pass = 0;
 let fail = 0;
@@ -101,31 +103,60 @@ 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), "拼接式必须完整闭合");
+  assert.ok(src.includes('protocol handle \\"%s\\"'), "URL 槽必须引号化（quoted form 引号会被生成侧 shell 消费）");
 });
 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 用 protocol handle 两 token（对齐路由）", () => {
+  const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
+  assert.ok(src.includes('protocol handle \\"%s\\"'), "必须 protocol handle 且 URL 槽引号化");
+  assert.ok(!src.includes("protocol-handle"), "不得残留单 token 旧形态");
 });
-check("AppleScript: .command 退出码保持 + 按键防闪退", () => {
+check("AppleScript: .command 退出码保持 + 按键防闪退 + 自清理", () => {
   const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
   assert.ok(src.includes("st=$?"), "必须捕获退出码");
   assert.ok(src.includes("read -n 1"), "必须按键保持窗口");
+  assert.ok(src.includes("rm -f"), "必须自清理临时 .command");
 });
-check("Windows cmd: 绝对路径 + %1 引号约定 + pause", () => {
+check("Windows cmd: 绝对路径 + protocol handle %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('"C:\\n\\node.exe" "C:\\p\\cli.js" protocol handle "%~1"'), "URL 槽必须 %~1 再引号化");
+  assert.ok(!cmd.includes("protocol-handle"), "不得残留单 token 旧形态");
   assert.ok(cmd.includes("pause"), "必须 pause 防闪退");
   assert.ok(cmd.includes("exit /b %RC%"), "必须透传退出码");
   assert.ok(cmd.includes("\r\n"), "必须是 CRLF");
 });
 
+// ── [4] 单 token 别名路由 ──
+console.log("[4] 别名路由（parseArgs 无参签名，读 process.argv）");
+check("protocol-handle 单 token → protocol/handle（OS 拉起链路兼容）", () => {
+  const oldArgv = process.argv;
+  process.argv = ["node", "tt-help", "protocol-handle", "tt-help://login-pool/add?server=http://x.io"];
+  try {
+    const p = parseArgs();
+    assert.equal(p.subcommand, "protocol");
+    assert.equal(p.action, "handle");
+    assert.equal(p.url, "tt-help://login-pool/add?server=http://x.io");
+  } finally {
+    process.argv = oldArgv;
+  }
+});
+check("protocol handle 两 token 仍正常", () => {
+  const oldArgv = process.argv;
+  process.argv = ["node", "tt-help", "protocol", "handle", "tt-help://login-pool/add?server=http://x.io"];
+  try {
+    const p = parseArgs();
+    assert.equal(p.subcommand, "protocol");
+    assert.equal(p.action, "handle");
+  } finally {
+    process.argv = oldArgv;
+  }
+});
+
 console.log(`\n结果: ${pass} 通过, ${fail} 失败`);
 process.exit(fail ? 1 : 0);

package/scripts/verify-protocol-quote.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// 验证模板输出的 .command 里 URL 是否带引号（模拟 printf 行为）
+import { buildAppleScript, buildWindowsCmd } from "../src/cli/protocol-bridge.js";
+import { execFileSync } from "child_process";
+import { readFileSync } from "fs";
+import { strict as assert } from "assert";
+
+const NODE = "/Users/x/.nvm/versions/node/v24.14.1/bin/node";
+const CLI = "/Users/x/pkg/cli.js";
+const URL = "tt-help://login-pool/relogin?server=http%3A%2F%2F117.71.53.99%3A17301&username=asset698";
+
+const src = buildAppleScript({ nodePath: NODE, cliPath: CLI });
+
+// 从 AppleScript 源抽取 sh 命令（模拟 AppleScript 字符串求值：\" → "，\\ → \）
+const m = src.match(/do shell script "((?:[^"\\]|\\.)*)" & quoted form of theURL & "((?:[^"\\]|\\.)*)"\n/);
+assert.ok(m, "do shell script 拼接式结构完整");
+const unesc = (s) => s.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+const sh = unesc(m[1]) + "'" + URL + "'" + unesc(m[2]);
+
+// 用 /bin/sh 真实执行 printf（macOS 上等价；这里在 Linux 模拟——printf POSIX 行为一致）
+const out2 = execFileSync("/bin/sh", ["-c", sh.replace("open -a Terminal", "echo OPEN-TARGET:")], { encoding: "utf-8" });
+const target = (out2.match(/OPEN-TARGET: (\S+)/) || [])[1];
+assert.ok(target, "未取得 .command 路径");
+const out = readFileSync(target, "utf-8");
+
+
+// 断言：URL 必须带引号出现在 .command 里
+assert.ok(out.includes(`protocol handle "${URL}"`), "URL 必须被双引号包裹");
+assert.ok(out.includes(`"${NODE}"`), "node 路径必须被双引号包裹");
+assert.ok(out.includes(`"${CLI}"`), "cli 路径必须被双引号包裹");
+console.log("✓ macOS：URL/路径均已引号化（& 不再截断命令）");
+
+const w = buildWindowsCmd({ nodePath: "C:\\n\\node.exe", cliPath: "C:\\p\\cli.js" });
+assert.ok(w.includes('protocol handle "%~1"'), "Windows 必须用 %~1 再引号化");
+console.log("✓ Windows：protocol handle \"%~1\"（引号恒在）");

package/src/cli/explore.js

@@ -49,6 +49,17 @@ const MAX_REBUILD_ATTEMPTS = 5; // 账户切换后导航恢复：连续重启浏
 const STARTUP_TIKTOK_URL = "https://www.tiktok.com/@ycl5007";
 const PAGE_GOTO_TIMEOUT = 60000; // 页面导航超时 60 秒（账户切换后需要更长时间）
 
+// 换号原因受控 code（2026-10-30 定稿：服务端 switchStats 按账号聚合展示；
+// 只用这组固定值上报，不传自由文本；startup 首次取号不带 reason）
+const SWITCH_REASON = {
+  BANNED: "banned", // 关注/粉丝功能被封、被封累计
+  RECOVER_FAIL: "recover_fail", // 浏览器重启/登录态恢复失败
+  SCHEDULED: "scheduled", // 48min 周期例行换号
+  INJECT_FAIL: "inject_fail", // 候选号注入验证失败后的再取号
+  CAPTCHA: "captcha", // 验证码累计超时未解决
+  NETWORK: "network", // CDN 限流累计（网络侧限流）
+};
+
 async function withRetry(label, fn) {
   let backoff = 1000;
   while (true) {
@@ -349,13 +360,15 @@ export async function handleExplore(options) {
      * 换号（以号为主键）：先取新号（旧号仍在手，无空窗）→ 注入验证 → 还旧号。
      * 候选最多试 5 个（注入失败的释放回池）；池空/服务器不可达 → 保旧号返回 false，
      * 由主循环「无在手账号」补取逻辑兑底。
+     * @param code 受控换号原因（SWITCH_REASON，上报服务端 switchStats；可选）；
+     *             首选按外层 call site 上报，候选注入失败后的再取号 = inject_fail
      */
-    async function switchPoolAccount(reason) {
+    async function switchPoolAccount(reason, code) {
       console.error(`\n[换号] ${reason}，从账号中心取新账号...`);
       for (let attempt = 0; attempt < 5; attempt++) {
         let next = null;
         try {
-          next = await poolClient.acquire();
+          next = await poolClient.acquire(attempt === 0 ? code : SWITCH_REASON.INJECT_FAIL);
         } catch (e) {
           console.error(
             `[换号] 取新号失败（${e.message}）${poolAccount ? `，保留当前账号 @${poolAccount.username}` : "，将在主循环补取"}`,
@@ -419,7 +432,10 @@ export async function handleExplore(options) {
         return true;
       }
       console.error(`[登录池] 登录态恢复失败（${r.reason}），转入换号流程`);
-      return await switchPoolAccount(`浏览器重启后无法恢复 @${poolAccount.username} 的登录态`);
+      return await switchPoolAccount(
+        `浏览器重启后无法恢复 @${poolAccount.username} 的登录态`,
+        SWITCH_REASON.RECOVER_FAIL,
+      );
     }
 
     /** 内存超限：同号重启浏览器（不换号——内存是浏览器进程问题，不是账号问题） */
@@ -434,14 +450,17 @@ export async function handleExplore(options) {
         Object.assign(page, rebuiltPage);
       } catch (e) {
         console.error(`[浏览器] 重启失败: ${e.message}，转入换号流程`);
-        return await switchPoolAccount(`浏览器重启失败（${e.message}）`);
+        return await switchPoolAccount(
+          `浏览器重启失败（${e.message}）`,
+          SWITCH_REASON.RECOVER_FAIL,
+        );
       }
       return await restorePoolLogin();
     }
 
-    async function handleAccountSwitch(reason) {
+    async function handleAccountSwitch(reason, code) {
       if (poolMode) {
-        await switchPoolAccount(reason);
+        await switchPoolAccount(reason, code);
         return;
       }
       console.error(`\n[健康检查] ${reason}，切换到下一个账户...`);
@@ -560,7 +579,7 @@ export async function handleExplore(options) {
             errorStack: result.errorStack || "",
           }),
         ),
-      switchAccount: (reason) => handleAccountSwitch(reason),
+      switchAccount: (reason) => handleAccountSwitch(reason, SWITCH_REASON.NETWORK),
     });
 
     /** 等待人工在浏览器中解决验证码：轮询检测，解决即继续；超时返回 false */
@@ -652,6 +671,7 @@ export async function handleExplore(options) {
           } else if (elapsedMs >= ROTATE_INTERVAL_MS) {
             await handleAccountSwitch(
               `当前账号已运行 ${Math.round(elapsedMs / 60000)} 分钟`,
+              SWITCH_REASON.SCHEDULED,
             );
           } else if (processedCount % 10 === 0) {
             const remainMin = Math.max(
@@ -713,6 +733,7 @@ export async function handleExplore(options) {
             if (captchaCount >= 3) {
               await handleAccountSwitch(
                 `验证码累计 ${captchaCount} 次（超时未解决）`,
+                SWITCH_REASON.CAPTCHA,
               );
               captchaCount = 0;
             }
@@ -729,7 +750,7 @@ export async function handleExplore(options) {
             console.error(
               `\n[封禁检测] 关注/粉丝功能已 ${minutes} 分钟未成功获取，切换到下一个账户...`,
             );
-            await handleAccountSwitch(`关注/粉丝功能被封`);
+            await handleAccountSwitch(`关注/粉丝功能被封`, SWITCH_REASON.BANNED);
           }
         }
 
@@ -914,7 +935,10 @@ export async function handleExplore(options) {
               // 触发代理切换（api-interceptor 已内置 30/40/50s 重试，到这里仍封直接切代理）
               await triggerProxySwitch(`账号被封 @${username}`, proxyPort);
               if (blockedCount >= 3) {
-                await handleAccountSwitch(`账号被封累计 ${blockedCount} 次`);
+                await handleAccountSwitch(
+                  `账号被封累计 ${blockedCount} 次`,
+                  SWITCH_REASON.BANNED,
+                );
                 blockedCount = 0;
               }
               continue;
@@ -952,6 +976,7 @@ export async function handleExplore(options) {
             // 累计3次验证码（均超时未解决），切换账户
             await handleAccountSwitch(
               `验证码累计 ${captchaCount} 次（超时未解决）`,
+              SWITCH_REASON.CAPTCHA,
             );
             captchaCount = 0;
           }

package/src/cli/login-pool.js

@@ -8,13 +8,14 @@
  *
  * add:      起独立 Edge（临时目录+代理）→ 人工在窗口里登录 TikTok → 轮询 passport 检出
  *           → 导出 cookies → POST /api/login-pool/import（幂等，同号跳过）
- * relogin:  POST /prepare 取池内旧 cookies → 注入本机 Edge 试复活（快路径零操作）
- *           → 会话已死则提示人工在窗口登录目标账号 → 身份校验 → POST /relogin 覆盖刷新
+ * relogin:  检测：POST /prepare 取池内旧 cookies → 注入本机 Edge 打开账号当前登录态
+ *           → 人工核对/退出重登（机器不做任何自动判定）→ 回车提交 → 身份校验 → POST /relogin 覆盖刷新
  * check:    服务端无浏览器 HTTP 探测各号登录态（默认空闲+疑似），死号自动标疑似
  *
  * 协议桥（页面一键拉起本命令）为独立后续项，本命令即其执行端。
  */
 import { mkdtempSync, rmSync } from "fs";
+import { createInterface } from "readline";
 import { tmpdir } from "os";
 import { join } from "path";
 import { chromium } from "playwright";
@@ -23,11 +24,37 @@ import { proxy as configuredProxy } from "../lib/constants.js";
 
 const POLL_INTERVAL_MS = 3000;
 const CDP_FALLBACK_NOTE = "（关掉窗口或 Ctrl+C 可中止）";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 function log(t) {
   console.error(`[登录池] ${t}`);
 }
 
+/** 等待回车提交；stdin 关闭或超时则中止（不更新池）。返回 {promise, abort}：失败路径须 abort() 关闭监听，否则进程不退 */
+function waitEnter(timeoutMs) {
+  let finish = null;
+  const promise = new Promise((resolve, reject) => {
+    const rl = createInterface({ input: process.stdin });
+    let done = false;
+    finish = (err) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      rl.close();
+      process.stdin.pause();
+      process.stdin.unref(); // 释放事件循环对 stdin 的引用：提交/中止后进程立即退出
+      err ? reject(err) : resolve();
+    };
+    const timer = setTimeout(
+      () => finish(new Error(`等待回车超时（${Math.round(timeoutMs / 1000)}s），已中止（不更新池）`)),
+      timeoutMs,
+    );
+    rl.once("line", () => finish(null));
+    rl.once("close", () => finish(new Error("stdin 已关闭，已中止（不更新池）")));
+  });
+  return { promise, abort: (msg) => finish && finish(new Error(msg || "已中止")) };
+}
+
 /** HTTP POST，默认 30s 超时（check 场景调用方自带更长超时） */
 async function post(base, path, body, timeoutMs = 30 * 1000) {
   const res = await fetch(`${String(base).replace(/\/+$/, "")}/api/login-pool/${path}`, {
@@ -106,45 +133,66 @@ async function cmdAdd(opts) {
   }
 }
 
-/** relogin 子命令 */
+/** 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 });
+  // 尽早挂回车监听：fd0 在重活（Edge 启动/页面导航）期间可能被环境消费，迟挂会丢事件；
+  // 提前监听则回车随时可达，结果由下方 await 消费
+  const enter = waitEnter(timeoutMs);
+  enter.promise.catch(() => {}); // 防 unhandled rejection（真正消费在下方 await/abort）
+  let session = null;
   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 });
+    const prep = await post(serverUrl, "prepare", { username });
+    const oldCookies = prep.account.cookies;
+    log(`目标 @${username}（池内 ${oldCookies.length} 条 cookies）。在窗口中打开当前登录态…`);
+    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 } : {}),
+      }));
+    session = await openEdgeSession({ proxy, dir });
+    await session.context.addCookies(toPlaywrightCookies(oldCookies));
+    await gotoTiktok(session.page);
+    log(`已在窗口打开 @${username}。可保持不动 / 退出重登 / 直接处理异常（人工操作）`);
+    log(
+      `操作完成后回这里按回车，提交最新登录态（${Math.round(timeoutMs / 1000)}s 无操作自动中止；关窗口=中止）…`,
+    );
+    await enter.promise;
+
+    // 读提交时刻的登录态：页面可能在加载，未检出时短暂重试
+    let id = null;
+    for (let i = 0; i < 3; i++) {
+      id = await whoAmI(session.page);
+      if (id.hasAccount) break;
+      if (i < 2) {
+        log("未检测到登录态，3 秒后重试…");
+        await sleep(3000);
+      }
+    }
+    if (!id || !id.hasAccount) {
+      enter.abort();
+      throw new Error("窗口当前未登录（登出后未重登？），已中止（不更新池）");
     }
     if (id.username !== username) {
+      enter.abort();
       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: "命令行重登录" });
+    const r = await post(serverUrl, "relogin", { username, cookies, userId: "cli-login-pool", note: "命令行检测更新" });
     log(
-      `✓ @${username} 重登录完成: cookies 已覆盖刷新（${r.account.cookieCount} 条）${r.revived ? "，已停用账号复活回池" : r.wasSuspect ? "，疑似已清回池" : ""}`,
+      `✓ @${username} 检测完成: cookies 已覆盖刷新（${r.account.cookieCount} 条）${r.revived ? "，已停用账号复活回池" : r.wasSuspect ? "，疑似已清回池" : ""}`,
     );
+  } catch (e) {
+    enter.abort(); // 失败路径关闭回车监听，否则 readline 持有事件循环、进程不退
+    throw e;
   } finally {
-    await session.cleanup();
+    if (session) await session.cleanup();
   }
 }
 
@@ -192,7 +240,7 @@ export async function handleLoginPool(parsed) {
         "  tt-help login-pool check   [--server URL] [--proxy URL] [--ids id1,id2] [--json]",
         "",
         "  add     新登录收号：弹出 Edge 人工登录 TikTok，检出后自动入池（幂等）",
-        "  relogin 重登录：先试旧登录态复活（零操作），死了引导人工登录，身份校验后覆盖刷新",
+        "  relogin 检测：窗口打开账号当前登录态，人工核对/退出重登后按回车提交，身份校验后覆盖刷新",
         "  check   巡检：服务端 HTTP 探测各号登录态，死号自动标疑似",
       ].join("\n"),
     );

package/src/cli/protocol-bridge.js

@@ -102,7 +102,7 @@ async function cmdHandle(rawUrl) {
     noProxy: false,
     note: p.note || null,
     dir: null,
-    timeoutSec: 300,
+    timeoutSec: 600,
     ids: null,
     json: false,
     showHelp: false,
@@ -118,7 +118,7 @@ export function buildAppleScript({ nodePath, cliPath }) {
   // .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' " +
+    "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 (
@@ -204,7 +204,7 @@ export function buildWindowsCmd({ nodePath, cliPath }) {
   return [
     "@echo off",
     "title tt-help 登录池",
-    `"${nodePath}" "${cliPath}" protocol-handle %1`,
+    `"${nodePath}" "${cliPath}" protocol handle "%~1"`,
     "set RC=%ERRORLEVEL%",
     "echo.",
     `pause`,

package/src/lib/args.js

@@ -1175,7 +1175,7 @@ function parseLoginPoolArgs(args) {
   let noProxy = false;
   let note = null;
   let dir = null;
-  let timeoutSec = 300;
+  let timeoutSec = 600;
   let ids = null;
   let json = false;
   let showHelp = false;
@@ -1193,7 +1193,7 @@ function parseLoginPoolArgs(args) {
     } 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;
+      timeoutSec = parseInt(args[++i], 10) || 600;
     } else if (arg === "--ids" && i + 1 < args.length) {
       ids = args[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--json") {
@@ -1806,6 +1806,11 @@ export function parseArgs() {
     return parseProtocolBridgeArgs(args.slice(1));
   }
 
+  // protocol-handle 单 token 别名：协议处理器拉起链路的历史形态，兼容已注册机器
+  if (args.length > 0 && args[0] === "protocol-handle") {
+    return parseProtocolBridgeArgs(["handle", ...args.slice(1)]);
+  }
+
   if (args.length > 0 && args[0] === "comments") {
     return parseCommentsArgs(args.slice(1));
   }

package/src/lib/constants.js

@@ -294,13 +294,13 @@ const HELP_TEXT = [
   "  tt-help login-pool <add|relogin|check> [选项]",
   "    账号中心：新登录收号 / 重登录 / 巡检（与网页 /login-pool 同一套账号库）",
   "    add     弹出独立 Edge，人工登录 TikTok 后自动导出登录态入池（幂等）",
-  "    relogin <username>  先试旧登录态复活（零操作），失效则引导人工登录，覆盖刷新池内 cookies",
+  "    relogin <username>  检测：窗口打开账号当前登录态，人工核对/退出重登后按回车提交，覆盖刷新池内 cookies",
   "    选项:",
   "      --server <URL>            账号中心地址（watch 服务端）",
   "      --proxy <地址>            Edge/探测代理，默认配置文件 proxy；--no-proxy 直连",
   "      --note <备注>             add 备注信息",
   "      --dir <路径>              自定义 Edge 用户目录（默认临时目录用后即清）",
-  "      --timeout <秒>            等待人工登录上限，默认 300",
+  "      --timeout <秒>            等待人工操作上限，默认 600",
   "      --ids <id1,id2>           check 只探测指定账号",
   "      --json                    check 输出 JSON",
   "    示例: tt-help login-pool add --server http://172.18.154.201:3011",

package/src/lib/login-pool-client.js

@@ -37,9 +37,14 @@ async function poolPost(url, body) {
 export function createLoginPoolClient({ serverUrl, userId, port, appName = "explore" }) {
   const base = `${String(serverUrl).replace(/\/+$/, "")}/api/login-pool`;
   return {
-    /** 取号：挑最久未用的空闲号，响应带明文 cookies。失败抛错（池空/服务器不可达） */
-    async acquire() {
-      const r = await poolPost(`${base}/acquire`, { userId, port, appName });
+    /** 取号：按服务端排序规则（2026-10-30：休息窗+同类/非同类）挑空闲号，响应带明文 cookies。
+     *  失败抛错（池空/服务器不可达）。
+     *  reason 可选：换号原因受控 code（banned/recover_fail/scheduled/inject_fail/captcha/network），
+     *  服务端按账号聚合 switchStats；不带则不计（仅显式上报才计数，旧客户端兼容） */
+    async acquire(reason) {
+      const body = { userId, port, appName };
+      if (reason) body.reason = String(reason);
+      const r = await poolPost(`${base}/acquire`, body);
       return r.account;
     },
     /** 还号：以号为主键，按 id 释放（谁持账号谁还） */