tt-help-cli-ycl 1.4.178 → 1.4.179

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-help-cli-ycl",
-  "version": "1.4.178",
+  "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

@@ -163,7 +163,18 @@ check("独立页含新增账号/批量检测按钮", await page.$$eval(".bar but
   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,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/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

@@ -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,10 @@ export function parseArgs() {
     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

@@ -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');