tt-help-cli-ycl 1.4.182 → 1.4.184

package/scripts/test-login-pool-faceban-e2e.mjs

@@ -0,0 +1,131 @@
+/**
+ * faceBans HTTP E2E — 真实 watch 服务（不起浏览器；页面用 HTML 字符串断言 + 内嵌 JS 语法编译）
+ *
+ * 覆盖:
+ *   1. POST /api/login-pool/face 标挂/恢复（probe/manual source、by 落库）→ GET /api/login-pool 透出
+ *   2. 参数校验走 HTTP 400（非法 face / source / 缺 ban / 未知账号）
+ *   3. acquire HTTP 全链路：explore 取号跳过 ban 号、search 面照发、池空文案带面维度
+ *   4. /login-pool 页面（登录门禁后）含面标注列/标挂恢复按钮/faceDlg 函数；内嵌 JS 可编译
+ *   5. 服务端 FACE 日志行格式（仿 UPDATE 行风格）
+ *
+ * 跑法: node scripts/test-login-pool-faceban-e2e.mjs（自行起停服务，临时 HOME 零污染）
+ */
+import { spawn } from "child_process";
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const HOME = mkdtempSync(join(tmpdir(), "faceban-e2e-"));
+const PORT = 3913;
+const BASE = `http://127.0.0.1:${PORT}`;
+
+let pass = 0, fail = 0;
+const check = (name, cond, extra = "") => {
+  cond ? (pass++, console.log(`  ✓ ${name}`)) : (fail++, console.log(`  ✗ ${name} ${extra}`));
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const post = async (p, body, cookie) => {
+  const r = await fetch(BASE + p, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...(cookie ? { Cookie: cookie } : {}) },
+    body: JSON.stringify(body),
+  });
+  return { status: r.status, json: await r.json().catch(() => ({})), setCookie: r.headers.get("set-cookie") };
+};
+
+// ── 起 watch ──
+const srvErr = [];
+const srv = spawn("node", [join(root, "src", "main.js"), "watch", "-o", join(HOME, "t.db"), "-p", String(PORT)], {
+  cwd: root, env: { ...process.env, HOME }, stdio: ["ignore", "ignore", "pipe"],
+});
+srv.stderr.on("data", (d) => srvErr.push(String(d)));
+let ready = false;
+for (let i = 0; i < 40 && !ready; i++) {
+  try { await fetch(BASE + "/api/stats"); ready = true; } catch { await sleep(500); }
+}
+check("watch 就绪(3913)", ready);
+try {
+  const pad = (n) => String(n).padStart(2, "0");
+  const d = new Date();
+  const pwd = `tt@${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`;
+  const login = await post("/api/login", { password: pwd });
+  const cookie = (login.setCookie || "").split(";")[0];
+  check("页面门禁登录", login.status === 200 && cookie.startsWith("watch_token="), JSON.stringify(login.json).slice(0, 100));
+
+  // ── 入池三号 ──
+  const mk = (sid, uid) => [
+    { name: "sessionid", value: sid, domain: ".tiktok.com", expires: Date.now() / 1000 + 86400 },
+    { name: "unique_id", value: uid, domain: ".tiktok.com" },
+  ];
+  const a1 = await post("/api/login-pool/add", { username: "e2e-good", cookies: mk("1", "e2e-good") });
+  const a2 = await post("/api/login-pool/add", { username: "e2e-expban", cookies: mk("2", "e2e-expban") });
+  const a3 = await post("/api/login-pool/add", { username: "e2e-seaban", cookies: mk("3", "e2e-seaban") });
+  check("入池 3 号", a1.json.ok && a2.json.ok && a3.json.ok);
+
+  // ── face 标注 API ──
+  const f1 = await post("/api/login-pool/face", { username: "e2e-expban", face: "explore", ban: true, source: "probe", by: "2026-11-02排查" }, cookie);
+  check("face 标挂（probe）", f1.status === 200 && f1.json.account.faceBans.explore.ban === true && f1.json.account.faceBans.explore.source === "probe");
+  const f2 = await post("/api/login-pool/face", { id: a3.json.account.id, face: "search", ban: true, source: "manual", by: "page" }, cookie);
+  check("face 标挂（manual, id 定位）", f2.status === 200 && f2.json.account.faceBans.search.ban === true);
+  const view = await (await fetch(BASE + "/api/login-pool")).json();
+  const vu = view.accounts.find((x) => x.username === "e2e-expban");
+  check("GET /api/login-pool 透出 faceBans", vu && vu.faceBans && vu.faceBans.explore && vu.faceBans.explore.ban === true && vu.faceBans.search === null);
+  check("history 落痕 faceBan", (vu.history || []).some((h) => h.event === "faceBan" && /explore=禁用/.test(h.detail)));
+
+  // ── 校验走 HTTP 400 ──
+  const bad1 = await post("/api/login-pool/face", { username: "e2e-good", face: "video", ban: true }, cookie);
+  const bad2 = await post("/api/login-pool/face", { username: "e2e-good", face: "explore", ban: true, source: "auto" }, cookie);
+  const bad3 = await post("/api/login-pool/face", { username: "nobody", face: "explore", ban: true }, cookie);
+  check("非法 face → 400", bad1.status === 400 && /非法 face/.test(bad1.json.error || ""));
+  check("非法 source → 400", bad2.status === 400 && /非法 source/.test(bad2.json.error || ""));
+  check("未知账号 → 400", bad3.status === 400 && /账号不存在/.test(bad3.json.error || ""));
+
+  // ── acquire 全链路 ──
+  const acq = async (appName) => {
+    const r = await post("/api/login-pool/acquire", { userId: "E2E-" + Math.random().toString(36).slice(2, 6), appName });
+    return r;
+  };
+  const w1 = await acq("explore");
+  check("explore 取号跳过 ban 号", w1.json.account && w1.json.account.username === "e2e-good", JSON.stringify(w1.json).slice(0, 120));
+  const rel = await post("/api/login-pool/release", { id: w1.json.account.id }, cookie);
+  check("release 还号", rel.json.ok);
+  const w2 = await acq("search");
+  check("search 取号照发 explore-ban 号（面独立）", w2.json.account && w2.json.account.username === "e2e-expban", JSON.stringify(w2.json).slice(0, 120));
+  await post("/api/login-pool/release", { id: w2.json.account.id }, cookie);
+  // 池空文案：search-ban 的 e2e-seaban 仍在池；explore-ban 的也回池了；只禁 search 面后 explore 仍可发
+  // 构造 search 面池空：把 good 与 expban 都禁 search
+  await post("/api/login-pool/face", { username: "e2e-good", face: "search", ban: true, source: "manual" }, cookie);
+  await post("/api/login-pool/face", { username: "e2e-expban", face: "search", ban: true, source: "manual" }, cookie);
+  const w3 = await acq("search");
+  check("search 池空文案带面维度", w3.status === 400 && /池中暂无 search 面可用账号（共3 个，面禁用 3 个，租约中 0 个）/.test(w3.json.error || ""), w3.json.error);
+  const w4 = await acq("explore");
+  check("explore 同池不空（面独立，K1 发从未用过的 seaban）",
+    w4.json.account && w4.json.account.username === "e2e-seaban" && !(w4.json.account.faceBans.explore && w4.json.account.faceBans.explore.ban),
+    JSON.stringify(w4.json).slice(0, 120));
+  await post("/api/login-pool/release", { id: w4.json.account.id }, cookie);
+
+  // ── 页面 ──
+  const page = await (await fetch(BASE + "/login-pool", { headers: { Cookie: cookie } })).text();
+  check("页面含 explore/search 列头", page.includes(">explore</th>") && page.includes(">search</th>"));
+  check("页面含标挂/恢复按钮 + faceDlg", page.includes("&gt;标挂&lt;") === false && page.includes(">标挂</button>") && page.includes(">恢复</button>") && page.includes("async function faceDlg("));
+  check("页面调 face API", page.includes("'/api/login-pool/face'"));
+  check("页面含面标注图例", page.includes("面标注图例"));
+  // 内嵌 JS 语法可编译（提取 <script> 块 new Function 编译，不执行）
+  const m = page.match(/<script>([\s\S]*?)<\/script>/);
+  let compiled = false;
+  try { new Function(m[1]); compiled = true; } catch (e) { console.log("    编译错误:", e.message); }
+  check("页面内嵌 JS 语法编译通过", compiled);
+  check("页面无 faceBans 明文泄漏风险（无 cookies 字段渲染）", !page.includes("acc.cookies"));
+
+  // ── FACE 日志行 ──
+  await sleep(300);
+  const logs = srvErr.join("");
+  check("服务端 FACE 日志行（仿 UPDATE 风格）", /\[登录池 .+\] FACE: e2e-expban explore=禁用 \(probe · 2026-11-02排查\)/.test(logs), logs.split("\n").filter((l) => l.includes("FACE")).join(" | ").slice(0, 200));
+} finally {
+  srv.kill("SIGTERM");
+  await sleep(500);
+}
+console.log(`\n═══ faceBans E2E: ${pass} passed, ${fail} failed ═══`);
+process.exit(fail > 0 ? 1 : 0);

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

@@ -0,0 +1,235 @@
+/**
+ * faceBans（账号面标注 + 派号过滤）单元测试 — 模块级直驱（不起 HTTP）
+ *
+ * 覆盖（2026-11-02 任务卡验证要求）:
+ *   1. faceBans 写读：setAccountFace 写入 → publicView 透出 → 池文件持久化（saveNow 立即落盘）
+ *   2. 参数校验：face/source 枚举、ban 必填 boolean、id/username 定位二选一
+ *   3. acquire 按面过滤：explore 禁用号 explore 取号跳过；另一面（search）不受影响照发
+ *   4. 缺失/null = 未验证 = 默认可用；ban=false 恢复后重新可发
+ *   5. 面禁用导致池空：文案带面维度（共X 个，面禁用 Y 个，租约中 Z 个）
+ *   6. 排序回归：K1 从未用过最前 / K2 非同类优先 / K3 lastUsedAt 升序在过滤后不变；
+ *      面禁用号即使排序键最优也不得中签
+ *   7. 与 status 正交：leased 号可标注（租约不动，faceBans 落本体）
+ *
+ * 跑法: HOME=$(mktemp -d) node scripts/test-login-pool-faceban.mjs
+ */
+import assert from "assert";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const HOME = process.env.HOME;
+if (!HOME || HOME === "/") {
+  console.error("请用隔离 HOME 运行: HOME=$(mktemp -d) node scripts/test-login-pool-faceban.mjs");
+  process.exit(1);
+}
+
+const {
+  getLoginPoolView,
+  addAccount,
+  releaseAccount,
+  acquireAccount,
+  setAccountFace,
+  isFaceBanned,
+  faceOfAppName,
+  _accountsInternal,
+} = await import("../src/watch/login-pool.js");
+
+let pass = 0;
+let fail = 0;
+const check = (name, cond, extra = "") => {
+  if (cond) {
+    pass++;
+    console.log(`  ✓ ${name}`);
+  } else {
+    fail++;
+    console.log(`  ✗ ${name} ${extra}`);
+  }
+};
+const POOL_FILE = join(HOME, ".tt-help-watchdog-logins.json");
+const mkCookies = (sid, uid) => [
+  { name: "sessionid", value: sid, domain: ".tiktok.com", expires: Date.now() / 1000 + 86400 },
+  { name: "unique_id", value: uid, domain: ".tiktok.com" },
+];
+const findAcc = (username) => getLoginPoolView().accounts.find((x) => x.username === username);
+// 节间隔离：全部下架（retired 不参与取号/计数为已停用），每节干净开局
+const retireAll = () => {
+  for (const a of _accountsInternal()) {
+    a.status = "retired";
+    a.lease = null;
+  }
+};
+const backdate = (username, msAgo) => {
+  for (const a of _accountsInternal()) {
+    if (a.username === username) a.lastUsedAt = Date.now() - msAgo;
+  }
+};
+
+// ── 1. faceOfAppName 语义 ──
+console.log("\n[1] faceOfAppName：未知 appName 归 explore");
+{
+  check("search → search", faceOfAppName("search") === "search");
+  check("explore → explore", faceOfAppName("explore") === "explore");
+  check("undefined → explore", faceOfAppName(undefined) === "explore");
+  check("未知字符串 → explore", faceOfAppName("comments") === "explore");
+}
+
+// ── 2. 写读 + 持久化 + 校验 ──
+console.log("\n[2] setAccountFace 写读 + saveNow 持久化");
+{
+  retireAll();
+  const a = addAccount({ cookies: mkCookies("s1", "faceA") });
+  const b = addAccount({ cookies: mkCookies("s2", "faceB") });
+
+  const before = findAcc("faceA");
+  check("初始 faceBans 双面均 null（未验证=可用）",
+    before.faceBans && before.faceBans.explore === null && before.faceBans.search === null);
+  check("isFaceBanned 懒判空：无标注=false", isFaceBanned(_accountsInternal()[0], "explore") === false);
+
+  const r1 = setAccountFace({ username: "faceA", face: "explore", ban: true, source: "probe", by: "2026-11-02排查" });
+  check("ban=true 写入（username 定位）", r1.faceBans.explore && r1.faceBans.explore.ban === true);
+  check("source/at/by 落库", r1.faceBans.explore.source === "probe" && typeof r1.faceBans.explore.at === "number" && r1.faceBans.explore.by === "2026-11-02排查");
+  check("另一面仍 null", r1.faceBans.search === null);
+  check("isFaceBanned=true", isFaceBanned(_accountsInternal().find((x) => x.username === "faceA"), "explore") === true);
+  check("search 面不受影响", isFaceBanned(_accountsInternal().find((x) => x.username === "faceA"), "search") === false);
+  check("history 落痕 faceBan", (r1.history || []).some((h) => h.event === "faceBan" && /explore=禁用/.test(h.detail)));
+
+  const r2 = setAccountFace({ id: b.id, face: "search", ban: true, source: "manual", by: "人工" });
+  check("ban=true（id 定位）", r2.faceBans.search && r2.faceBans.search.ban === true && r2.faceBans.search.source === "manual");
+
+  // 恢复（ban=false → ✅ 验证通过记录，不再过滤）
+  const r3 = setAccountFace({ username: "faceA", face: "explore", ban: false, source: "manual", by: "page" });
+  check("ban=false 恢复（isFaceBanned=false）",
+    r3.faceBans.explore && r3.faceBans.explore.ban === false &&
+    isFaceBanned(_accountsInternal().find((x) => x.username === "faceA"), "explore") === false);
+  check("history 落痕 faceRestore", (r3.history || []).some((h) => h.event === "faceRestore" && /explore=恢复/.test(h.detail)));
+
+  // saveNow 立即落盘（不走 3s 防抖）：连续标注（同进程第二次 setAccountFace）也必须落盘
+  const disk = JSON.parse(readFileSync(POOL_FILE, "utf-8"));
+  const diskA = disk.accounts.find((x) => x.username === "faceA");
+  check("池文件持久化 faceBans（连续两次标注均落盘）", diskA && diskA.faceBans && diskA.faceBans.explore && diskA.faceBans.explore.ban === false && diskA.faceBans.search == null,
+    JSON.stringify(diskA && diskA.faceBans));
+
+  // 参数校验
+  const throws = (fn, kw) => {
+    try { fn(); return false; } catch (e) { return e.message.includes(kw); }
+  };
+  check("非法 face 拒绝", throws(() => setAccountFace({ id: "x", face: "video", ban: true }), "非法 face"));
+  check("非法 source 拒绝", throws(() => setAccountFace({ id: "x", face: "explore", ban: true, source: "auto" }), "非法 source"));
+  check("ban 缺失/非 bool 拒绝", throws(() => setAccountFace({ id: "x", face: "explore" }), "ban 必填"));
+  check("账号不存在报错", throws(() => setAccountFace({ username: "nobody", face: "explore", ban: true }), "账号不存在"));
+  check("id/username 均缺拒绝", throws(() => setAccountFace({ face: "explore", ban: true }), "账号不存在"));
+}
+
+// ── 3. acquire 按面过滤（核心） ──
+console.log("\n[3] acquire 面过滤：跳过 ban 号，另一面不受影响");
+{
+  retireAll();
+  const good = addAccount({ cookies: mkCookies("g1", "good1"), username: "good1" });
+  const expBan = addAccount({ cookies: mkCookies("e1", "expBan"), username: "expBan" });
+  const seaBan = addAccount({ cookies: mkCookies("s3", "seaBan"), username: "seaBan" });
+  setAccountFace({ id: expBan.id, face: "explore", ban: true, source: "probe" });
+  setAccountFace({ id: seaBan.id, face: "search", ban: true, source: "probe" });
+
+  // explore 取号：good1 与 expBan 都是从未用过（K1 并列），K3 createdAt 升序 → 无过滤时 expBan（先入池？）
+  // 入池顺序 good→expBan→seaBan；K1 并列时按 lastUsedAt??createdAt 升序，good1 最先 → 中签。
+  // 为证明过滤生效（而非巧合排序），把 expBan 的 createdAt 提前，使无过滤时它必中签：
+  for (const a of _accountsInternal()) if (a.username === "expBan") a.createdAt = Date.now() - 60000;
+
+  const w1 = acquireAccount({ userId: "T-1", appName: "explore" });
+  check("explore 取号跳过 explore 禁用号", w1.username === "good1", `got ${w1.username}`);
+  releaseAccount({ id: w1.id });
+  _accountsInternal().find((x) => x.id === w1.id).lastUsedAt = null; // 还原从未用过
+
+  // 另一面不受影响：search 取号可拿到 explore 禁用号（expBan createdAt 最老 → K3 最前）
+  const w2 = acquireAccount({ userId: "T-2", appName: "search" });
+  check("search 取号照发 explore 禁用号（面独立）", w2.username === "expBan", `got ${w2.username}`);
+  releaseAccount({ id: w2.id });
+  _accountsInternal().find((x) => x.id === w2.id).lastUsedAt = null;
+
+  // search 取号跳过 search 禁用号
+  const w3 = acquireAccount({ userId: "T-3", appName: "search" });
+  check("search 取号跳过 search 禁用号", w3.username === "good1", `got ${w3.username}`);
+  releaseAccount({ id: w3.id });
+  _accountsInternal().find((x) => x.id === w3.id).lastUsedAt = null;
+
+  // 未知 appName 归 explore 面
+  const w4 = acquireAccount({ userId: "T-4" });
+  check("缺省 appName 归 explore 面（跳过 explore 禁用号）", w4.username === "good1", `got ${w4.username}`);
+  releaseAccount({ id: w4.id });
+  _accountsInternal().find((x) => x.id === w4.id).lastUsedAt = null;
+}
+
+// ── 4. 面禁用导致池空：文案带面维度 ──
+console.log("\n[4] 池空文案带面维度");
+{
+  retireAll();
+  const p1 = addAccount({ cookies: mkCookies("p1", "onlyPool"), username: "onlyPool" });
+  const leased = addAccount({ cookies: mkCookies("p2", "busyOne"), username: "busyOne" });
+  setAccountFace({ id: p1.id, face: "explore", ban: true, source: "manual" });
+  const l = acquireAccount({ userId: "T-9", appName: "explore" });
+  check("租约占住 busyOne", l.username === "busyOne");
+  let err = null;
+  try { acquireAccount({ userId: "T-10", appName: "explore" }); } catch (e) { err = e.message; }
+  const total = getLoginPoolView().total;
+  check("文案含面与三类计数", err === `池中暂无 explore 面可用账号（共${total} 个，面禁用 1 个，租约中 1 个）`, `got ${err}`);
+  // search 面同池不空（onlyPool 的 search 面未禁用）——但它 lastUsedAt 刚被 acquire 盖过？
+  // 上一步 search 取号会走 30min 休息窗 eligible 空集 → 全池兑底，仍能发号（语义=有得用总比没用好）
+  const w = acquireAccount({ userId: "T-11", appName: "search" });
+  check("另一面池不空照发（兑底流水线不受面文案影响）", !!w && w.faceBans.search === null);
+}
+
+// ── 5. 排序回归（K1/K2/K3 在过滤后不变） ──
+console.log("\n[5] 排序回归：K1/K2/K3 结果不变");
+{
+  retireAll();
+  const k1a = addAccount({ cookies: mkCookies("k1", "k1never"), username: "k1never" }); // 从未用过
+  const k1b = addAccount({ cookies: mkCookies("k2", "k1used"), username: "k1used" });
+  backdate("k1used", 61 * 60 * 1000); // 用过但已出休息窗（eligible）；61min 与后续 60min 严格分离，免同毫秒 tie
+  for (const a of _accountsInternal()) if (a.username === "k1used") a.lastAppName = "search";
+  // K1: 从未用过最前
+  const w1 = acquireAccount({ userId: "T-K1", appName: "explore" });
+  check("K1 从未用过最前", w1.username === "k1never", `got ${w1.username}`);
+  releaseAccount({ id: w1.id });
+
+  // K2: 非同类优先：k1never 刚被 explore 租过（lastAppName=explore，非同类），
+  // k1used 是 search（同类）→ search 请求优先 k1never；K2 在 K3 之前分出胜负，确定性不受时间戳精度影响
+  backdate("k1never", 60 * 60 * 1000); // 出休息窗，两者都 eligible（K1 并列）
+  const w2 = acquireAccount({ userId: "T-K2", appName: "search" });
+  check("K2 非同类优先", w2.username === "k1never", `got ${w2.username}`);
+  releaseAccount({ id: w2.id });
+
+  // K3: 同类并列 → lastUsedAt 升序（两者都 lastAppName=search；k1used 严格更老 61min vs 60min）
+  for (const a of _accountsInternal()) if (a.username === "k1never") a.lastAppName = "search";
+  backdate("k1never", 60 * 60 * 1000);
+  backdate("k1used", 61 * 60 * 1000);
+  const w3 = acquireAccount({ userId: "T-K3", appName: "search" });
+  check("K3 lastUsedAt 升序", w3.username === "k1used", `got ${w3.username}`);
+  releaseAccount({ id: w3.id });
+
+  // 面禁用即使排序键最优也不中签：把 k1never 还原成从未用过（K1 最优）再 explore 标挂 → 只剩 k1used
+  for (const a of _accountsInternal()) if (a.username === "k1never") a.lastUsedAt = null;
+  setAccountFace({ id: k1a.id, face: "explore", ban: true, source: "probe" });
+  const w4 = acquireAccount({ userId: "T-K4", appName: "explore" });
+  check("面禁用号排序键最优（从未用过）也不中签", w4.username === "k1used", `got ${w4.username}`);
+  releaseAccount({ id: w4.id });
+}
+
+// ── 6. 与 status 正交：leased 号可标注 ──
+console.log("\n[6] leased 号可标注（不动租约，下次派发生效）");
+{
+  retireAll();
+  const a = addAccount({ cookies: mkCookies("L1", "leasedOne"), username: "leasedOne" });
+  const l = acquireAccount({ userId: "T-L", appName: "explore" });
+  check("先取到手", l.username === "leasedOne");
+  const r = setAccountFace({ id: l.id, face: "explore", ban: true, source: "manual", by: "测试" });
+  check("标注后仍 leased 且租约原样", r.status === "leased" && r.lease && r.lease.userId === "T-L");
+  check("faceBans 落本体", r.faceBans.explore && r.faceBans.explore.ban === true);
+  // release 后回池，explore 派号不再发它
+  releaseAccount({ id: a.id });
+  let got = null;
+  try { got = acquireAccount({ userId: "T-L2", appName: "explore" }); } catch (e) { got = e.message; }
+  check("释放后 explore 派发跳过该号", typeof got === "string" && got.includes("面禁用 1 个"), `got ${got}`);
+}
+
+console.log(`\n═══ faceBans 测试: ${pass} passed, ${fail} failed ═══`);
+process.exit(fail > 0 ? 1 : 0);

package/scripts/test-process-manager-label.mjs

@@ -0,0 +1,145 @@
+/**
+ * watchdog 进程日志前缀标签单测 — deriveDisplayLabel 纯函数直驱
+ *
+ * 覆盖（2026-11-04 定稿规则表全部 5 条分支 + 引号/路径边界）:
+ *   1. --base-port 单端口        → [explore:9223]
+ *   2. --port 单端口（仅浏览器类）→ [refresh-mini:5222]；webserver/watch 的 --port 不吃
+ *   3. --base-port --port-count  → 区间压缩 [explore:9223-9225]
+ *   4. 解析不到端口              → [comments]（不猜默认端口）
+ *   5. 程序名也解析不出          → 兜底 fallbackId（即 cmdDef.name || id）
+ *   边界: 引号形态 "tt-help" "explore" / node+脚本路径取子命令 / 脚本本体即程序 /
+ *         Windows 启动器（.cmd/.exe）/ 值含引号空格不影响端口提取
+ *
+ * 跑法: node scripts/test-process-manager-label.mjs
+ */
+import assert from "assert";
+import { deriveDisplayLabel } from "../src/watchdog/process-manager.js";
+
+let pass = 0;
+let fail = 0;
+function check(name, actual, expected) {
+  try {
+    assert.strictEqual(actual, expected);
+    pass++;
+    console.log(`  ✓ ${name}`);
+  } catch {
+    fail++;
+    console.error(`  ✗ ${name}\n    期望: ${expected}\n    实际: ${actual}`);
+  }
+}
+
+console.log("规则 1：--base-port 单端口");
+check(
+  "explore --base-port 9223",
+  deriveDisplayLabel("tt-help explore --base-port 9223 --server http://127.0.0.1:3001", "1793630915534"),
+  "explore:9223",
+);
+check(
+  "refresh --base-port 8222（无 port-count 默认 1 个端口）",
+  deriveDisplayLabel("tt-help refresh --base-port 8222", "r1"),
+  "refresh:8222",
+);
+
+console.log("规则 2：--port 单端口（仅浏览器类命令提取，防误吃服务端口）");
+check(
+  "refresh-mini --port 5222",
+  deriveDisplayLabel("tt-help refresh-mini --port 5222 --headless", "m1"),
+  "refresh-mini:5222",
+);
+check(
+  "webserver --port 3000 不吃端口（非浏览器类命令）",
+  deriveDisplayLabel("tt-help webserver --port 3000", "w1"),
+  "webserver",
+);
+check(
+  "watch --port 3000 不吃端口（非浏览器类命令）",
+  deriveDisplayLabel("tt-help watch --port 3000 -o data.db", "w2"),
+  "watch",
+);
+
+console.log("规则 3：--base-port + --port-count 区间压缩");
+check(
+  "explore --base-port 9223 --port-count 3 → 9223-9225",
+  deriveDisplayLabel("tt-help explore --base-port 9223 --port-count 3", "e1"),
+  "explore:9223-9225",
+);
+check(
+  "attach --base-port 9222 --port-count 5 → 9222-9226",
+  deriveDisplayLabel("tt-help attach --base-port 9222 --port-count 5", "a1"),
+  "attach:9222-9226",
+);
+
+console.log("规则 4：解析不到端口 → 只显示程序名（不猜默认端口）");
+check("comments 无端口参数", deriveDisplayLabel("tt-help comments --server http://127.0.0.1:3001", "c1"), "comments");
+check("videostats 无端口参数", deriveDisplayLabel("tt-help videostats data/result.db -p 3", "v1"), "videostats");
+check("recheck 无端口参数", deriveDisplayLabel("tt-help recheck", "rc1"), "recheck");
+
+console.log("规则 5：程序名也解析不出 → 兜底 fallbackId");
+check("空命令行", deriveDisplayLabel("", "1793630915534"), "1793630915534");
+check("纯空白", deriveDisplayLabel("   ", "fallback-id"), "fallback-id");
+check("null 命令行", deriveDisplayLabel(null, "fb"), "fb");
+check("裸路径分隔符解析不出程序名", deriveDisplayLabel("/ --base-port 9223", "fb2"), "fb2");
+
+console.log("边界：引号形态");
+check(
+  '"tt-help" "explore" 全引号',
+  deriveDisplayLabel('"tt-help" "explore" --base-port 9223', "q1"),
+  "explore:9223",
+);
+check(
+  "引号值含空格不影响端口提取",
+  deriveDisplayLabel('tt-help explore --name "my explore" --base-port 9223', "q2"),
+  "explore:9223",
+);
+check(
+  "单引号启动器",
+  deriveDisplayLabel("'tt-help' refresh-mini --port 5222", "q3"),
+  "refresh-mini:5222",
+);
+
+console.log("边界：node/路径启动形态");
+check(
+  "node + 脚本路径 → 取子命令 token",
+  deriveDisplayLabel("node /usr/local/lib/cli.js explore --base-port 9223", "p1"),
+  "explore:9223",
+);
+check(
+  "node src/main.js watch → 取子命令 watch（--port 不吃，watch 非浏览器类）",
+  deriveDisplayLabel("node src/main.js watch --port 3000 -o tmp.db", "p2"),
+  "watch",
+);
+check(
+  "node scraper.js --port 9222 → 脚本本体即程序；scraper 不属浏览器类词表，--port 不吃",
+  deriveDisplayLabel("node scraper.js --port 9222", "p3"),
+  "scraper",
+);
+check(
+  "node explore.js --port 9222 → 脚本名属浏览器类词表，吃端口",
+  deriveDisplayLabel("node explore.js --port 9222", "p3b"),
+  "explore:9222",
+);
+check(
+  "node.exe + 相对脚本路径",
+  deriveDisplayLabel("node.exe cli.js refresh-mini --port 5222", "p4"),
+  "refresh-mini:5222",
+);
+check(
+  "Windows 完整路径 tt-help.cmd 启动器",
+  deriveDisplayLabel("C:\\tools\\tt-help.cmd explore --base-port 9223 --port-count 2", "p5"),
+  "explore:9223-9224",
+);
+check(
+  "裸命令（无启动器）直接取 token[0]",
+  deriveDisplayLabel("explore --base-port 9223", "p6"),
+  "explore:9223",
+);
+
+console.log("边界：cmdDef.args 数组形态（startCommand join 后派生）");
+check(
+  "args 数组 join 成命令行后解析",
+  deriveDisplayLabel(["tt-help", "explore", "--base-port", "9223"].join(" "), "ar1"),
+  "explore:9223",
+);
+
+console.log(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);