tt-help-cli-ycl 1.4.178 → 1.4.181

package/package.json

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

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

@@ -157,13 +157,24 @@ 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("批量检测");
 }));
 const barSrc = await page.content();
-check("页面含命令化文案（协议桥后置，先复制命令）", barSrc.includes("tt-help login-pool"));
+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));

package/scripts/test-protocol-bridge.mjs

@@ -0,0 +1,162 @@
+/**
+ * 协议桥单元测试 — 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;
+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), "拼接式必须完整闭合");
+  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: .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 退出码保持 + 按键防闪退 + 自清理", () => {
+  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: 绝对路径 + 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"'), "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/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

@@ -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: 600,
+    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

@@ -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") {
@@ -1232,6 +1232,18 @@ function parseLoginPoolArgs(args) {
   };
 }
 
+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;
@@ -1790,6 +1802,15 @@ export function parseArgs() {
     return parseLoginPoolArgs(args.slice(1));
   }
 
+  if (args.length > 0 && args[0] === "protocol") {
+    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",
@@ -308,6 +308,13 @@ const HELP_TEXT = [
   "          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

@@ -28,6 +28,7 @@ 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();
@@ -83,6 +84,8 @@ async function main() {
       return handleLoginCheck(parsed);
     case "login-pool":
       return handleLoginPool(parsed);
+    case "protocol":
+      return handleProtocolBridge(parsed);
   }
 
   const {

package/src/npm-main.js

@@ -24,6 +24,7 @@ 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(
@@ -82,6 +83,8 @@ async function main() {
       return handleLoginCheck(parsed);
     case "login-pool":
       return handleLoginPool(parsed);
+    case "protocol":
+      return handleProtocolBridge(parsed);
   }
 
   const {

package/src/watch/server.js

@@ -686,7 +686,7 @@ function serveLoginPoolPage(res) {
 <div class="sub">登录态统一存放与租借：业务取号注入 / 节点启动导入 / 巡检与重登录</div>
 <div class="bar">
   <button onclick="load()">刷新</button>
-  <button onclick="addCmdDlg()" title="生成一条命令，在任意装有 tt-help 的机器执行：弹出 Edge 人工登录 TikTok 后自动入池">新增账号</button>
+  <button onclick="addCmdDlg()" title="一键拉起本机 tt-help：弹出 Edge 登录 TikTok 后自动入池（本机需已安装 tt-help 并执行过 tt-help protocol register；未注册时自动回退为复制命令）">新增账号</button>
   <button id="btn-check" class="primary" onclick="checkNow()" title="逐号 HTTP 探测登录态（空闲+疑似），死号自动标疑似">批量检测</button>
   <span id="msg"></span>
   <span class="chips" id="stats"></span>
@@ -758,7 +758,7 @@ async function load() {
           (a.status === 'retired' ? '<button onclick="enable(\\'' + a.id + '\\',\\'' + esc(a.username) + '\\',false)">启用</button> ' : '') +
           (a.status !== 'retired' ? '<button onclick="disable(\\'' + a.id + '\\',\\'' + esc(a.username) + '\\',' + (a.status === 'leased') + ')">停用</button> ' : '') +
           (a.status === 'retired' ? '<button onclick="del(\\'' + a.id + '\\')">删除</button> ' : '') +
-          '<button onclick="reloginDlg(\\'' + esc(a.username) + '\\')" title="生成重登录命令：本机执行后旧登录态自动复活（或人工登录），验证身份后覆盖刷新池内 cookies">重登录</button>' +
+          '<button onclick="reloginDlg(\\'' + esc(a.username) + '\\')" title="一键拉起本机 tt-help 检测：窗口打开账号当前登录态，可退出重登或保持，回终端按回车提交更新池内 cookies">检测</button>' +
         '</td>' +
         '<td><details data-acc="' + esc(a.id) + '" ' + (openHist.has(a.id) ? 'open' : '') + ' ontoggle="onHistToggle(this)"><summary class="muted">' + (a.history ? a.history.length : 0) + ' 条</summary>' +
           (a.history || []).slice(0, 8).map(h => '<div class="muted">' + fmt(h.at) + ' ' + esc(h.event) + ' ' + esc(h.detail) + '</div>').join('') + '</details></td>' +
@@ -776,20 +776,40 @@ async function load() {
       '<span class="chip">已停用 <b>' + nRet + '</b></span>';
     document.getElementById('content').innerHTML =
       '<table><tr><th>#</th><th>账号</th><th>状态</th><th>使用者</th><th>最近使用</th><th>次数</th><th>有效期</th><th>检测</th><th>操作</th><th>历史</th></tr>' + rows + '</table>' +
-      '<div style="padding: 10px 14px;"><p class="muted" style="margin:0">排序：使用中 → 空闲 → 疑似 → 已停用 · 每 15 秒自动刷新 · 有效期 = sessionid cookie 承诺寿命 · 检测 = 登录态探测（真实判据 = 业务出活）· cookies 明文不出服务端</p></div>';
+      '<div style="padding: 10px 14px;"><p class="muted" style="margin:0">排序：使用中 → 空闲 → 疑似 → 已停用 · 每 15 秒自动刷新 · 有效期 = sessionid cookie 承诺寿命 · 检测 = 登录态探测（真实判据 = 业务出活）· cookies 明文不出服务端 · 「新增账号/重登录」一键拉起需本机装 tt-help 并执行过 <b>tt-help protocol register</b></p></div>';
   } catch (e) { msg('加载失败: ' + e.message, true); }
 }
 function copyCmd(cmd) {
   if (navigator.clipboard) navigator.clipboard.writeText(cmd).catch(() => {});
   prompt('复制命令（在装有 tt-help 的机器上执行）:', cmd);
 }
+function protoHref(action, params) {
+  const q = [];
+  for (const k in params) q.push(k + '=' + encodeURIComponent(params[k]));
+  return 'tt-help://' + action + '?' + q.join('&');
+}
+let protoBlurred = false;
+window.addEventListener('blur', () => { protoBlurred = true; });
+function launchProto(url, fallbackCmd, okMsg) {
+  protoBlurred = false;
+  location.href = url;
+  setProgress('已发起一键拉起 tt-help…');
+  setTimeout(() => {
+    if (protoBlurred) { msg(okMsg); return; }
+    const el = document.getElementById('msg');
+    el.style.color = '#d97706';
+    el.innerHTML = '未检测到协议处理器（或已在弹窗取消）。<button onclick="copyCmd(\\'' + fallbackCmd + '\\')">复制命令</button> <span class="muted">或本机执行 <b>tt-help protocol register</b> 注册后即可一键拉起</span>';
+  }, 2500);
+}
 function addCmdDlg() {
-  copyCmd('tt-help login-pool add --server ' + location.origin);
-  msg('命令已生成：执行成功后点刷新查看新号');
+  launchProto(protoHref('login-pool/add', { server: location.origin }),
+    'tt-help login-pool add --server ' + location.origin,
+    '已拉起 tt-help：请在弹出的窗口登录 TikTok，完成后回来点刷新');
 }
 function reloginDlg(name) {
-  copyCmd('tt-help login-pool relogin ' + name + ' --server ' + location.origin);
-  msg('重登录命令已生成（' + name + '）：执行成功后点刷新');
+  launchProto(protoHref('login-pool/relogin', { server: location.origin, username: name }),
+    'tt-help login-pool relogin ' + name + ' --server ' + location.origin,
+    '已拉起 tt-help 检测 @' + name + '：窗口中核对/退出重登，完成后回终端按回车提交，然后回来点刷新');
 }
 function setProgress(t) {
   const el = document.getElementById('msg');