tt-help-cli-ycl 1.4.183 → 1.4.184

package/package.json

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

package/scripts/test-crash-circuit-breaker.mjs

@@ -0,0 +1,250 @@
+/**
+ * 崩溃熔断三件套单测（F16 实录驱动，2026-11-04）
+ *
+ * 覆盖：
+ *   1. P1 崩溃签名分类 — isBrowserClosedError 命中 Target crashed / Page crashed
+ *      （F16 三种实测形态），Target closed 等旧签名回归不受影响，账号级原因不误判
+ *   2. P3 恢复重试 — isRetryableRestoreFailure（net::ERR_* / 超时 / 崩溃 → true，
+ *      身份不符 / 会话过期 → false）；retryRestoreOnNavFailure 3 次全败才弃号、
+ *      账号级不重试、中途成功即返、shouldAbort 中断
+ *   3. P2 熔断退避 — crashBackoffMs base / 2 倍递增 / max 钳制 / 清零（0 / 负数 / 非法）
+ *   4. P5 内存阈值 — resolveMemoryThreshold 默认回退 / 钳制 [0.5, 0.98] / HealthChecker 构造生效
+ *
+ * 跑法: node scripts/test-crash-circuit-breaker.mjs
+ */
+import assert from "assert";
+import {
+  isBrowserClosedError,
+  isRetryableRestoreFailure,
+} from "../src/lib/browser/page.js";
+import {
+  crashBackoffMs,
+  retryRestoreOnNavFailure,
+  CRASH_BACKOFF_BASE_MS,
+  CRASH_BACKOFF_MAX_MS,
+  RESTORE_RETRY_MAX_RETRIES,
+  RESTORE_RETRY_DELAY_MS,
+} from "../src/lib/login-pool-client.js";
+import {
+  HealthChecker,
+  MEMORY_THRESHOLD,
+  MEMORY_THRESHOLD_MIN,
+  MEMORY_THRESHOLD_MAX,
+  resolveMemoryThreshold,
+} from "../src/lib/browser/health-checker.js";
+
+let pass = 0;
+let fail = 0;
+function check(name, actual, expected) {
+  try {
+    assert.strictEqual(actual, expected);
+    pass++;
+    console.log(`  ✓ ${name}`);
+  } catch (e) {
+    fail++;
+    console.error(`  ✗ ${name}\n    期望: ${expected}\n    实际: ${actual}`);
+  }
+}
+
+// ── 1. P1 崩溃签名分类 ──
+console.log("\n规则 1：崩溃签名分类（isBrowserClosedError）");
+// F16 实录三种实测形态必须命中
+check(
+  "page.goto: Page crashed",
+  isBrowserClosedError(new Error("page.goto: Page crashed")),
+  true,
+);
+check(
+  "page.addInitScript: Target crashed",
+  isBrowserClosedError(new Error("page.addInitScript: Target crashed")),
+  true,
+);
+check(
+  "page.evaluate: Target crashed",
+  isBrowserClosedError(new Error("page.evaluate: Target crashed")),
+  true,
+);
+// 旧签名回归不受影响
+check(
+  "Target page, context or browser has been closed（旧）",
+  isBrowserClosedError(new Error("Target page, context or browser has been closed")),
+  true,
+);
+check("Target closed（旧）", isBrowserClosedError(new Error("Target closed")), true);
+check(
+  "net::ERR_CONNECTION_REFUSED（旧）",
+  isBrowserClosedError(new Error("page.goto: net::ERR_CONNECTION_REFUSED at https://www.tiktok.com/")),
+  true,
+);
+// 账号级/瞬态原因不得误判为浏览器级
+check(
+  "身份不符（账号级）",
+  isBrowserClosedError(new Error("身份不符（期望 @a，实际 @b）")),
+  false,
+);
+check("会话过期（账号级）", isBrowserClosedError(new Error("会话过期")), false);
+check(
+  "Timeout 30000ms exceeded（瞬态）",
+  isBrowserClosedError(new Error("Timeout 30000ms exceeded")),
+  false,
+);
+check("null/undefined", isBrowserClosedError(null) || isBrowserClosedError(undefined), false);
+
+// ── 2. P3 恢复重试 ──
+console.log("\n规则 2：恢复失败可重试分类（isRetryableRestoreFailure）");
+// F16 实录：一次即弃号的恢复失败签名
+check(
+  "net::ERR_HTTP_RESPONSE_CODE_FAILURE（F16 弃号签名）",
+  isRetryableRestoreFailure(
+    "导航失败: page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE at https://www.tiktok.com/",
+  ),
+  true,
+);
+check(
+  "net::ERR_TIMED_OUT",
+  isRetryableRestoreFailure("导航失败: page.goto: net::ERR_TIMED_OUT"),
+  true,
+);
+check(
+  "Timeout 45000ms exceeded",
+  isRetryableRestoreFailure("导航失败: page.goto: Timeout 45000ms exceeded"),
+  true,
+);
+check(
+  "Target crashed（恢复途中崩溃）",
+  isRetryableRestoreFailure("page.evaluate: Target crashed"),
+  true,
+);
+check("身份不符（账号级不重试）", isRetryableRestoreFailure("身份不符（期望 @a，实际 @b）"), false);
+check("会话过期（账号级不重试）", isRetryableRestoreFailure("会话过期"), false);
+check("无账号数据（账号级不重试）", isRetryableRestoreFailure("无账号数据"), false);
+check("空/空串", isRetryableRestoreFailure(null) || isRetryableRestoreFailure("") || isRetryableRestoreFailure(undefined), false);
+
+console.log("\n规则 2b：恢复重试驱动（retryRestoreOnNavFailure）");
+const NAV_FAIL = "导航失败: page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE";
+const ACCT_FAIL = "身份不符（期望 @a，实际 @b）";
+async function drive(script, firstFailure, opts = {}) {
+  let calls = 0;
+  let sleeps = 0;
+  const r = await retryRestoreOnNavFailure(
+    () => {
+      calls++;
+      const step = script[Math.min(calls - 1, script.length - 1)];
+      return typeof step === "string" ? { ok: false, reason: step } : step;
+    },
+    firstFailure,
+    {
+      isRetryable: isRetryableRestoreFailure,
+      sleep: async () => {
+        sleeps++;
+      },
+      ...opts,
+    },
+  );
+  return { r, calls, sleeps };
+}
+
+{
+  const { r, calls, sleeps } = await drive([NAV_FAIL, NAV_FAIL, NAV_FAIL], NAV_FAIL);
+  check("3 次全败 → ok:false", r.ok, false);
+  check("3 次全败 → attempts=3", r.attempts, 3);
+  check("3 次全败 → attemptFn 调 2 次（首败不重调）", calls, 2);
+  check("3 次全败 → sleep 2 次（maxRetries=2）", sleeps, RESTORE_RETRY_MAX_RETRIES);
+}
+{
+  const { r, calls, sleeps } = await drive([], ACCT_FAIL);
+  check("账号级首败 → 不重试 attempts=1", r.attempts, 1);
+  check("账号级首败 → attemptFn 0 次", calls, 0);
+  check("账号级首败 → sleep 0 次", sleeps, 0);
+  check("账号级首败 → 原因透传", r.reason, ACCT_FAIL);
+}
+{
+  const { r, calls } = await drive([{ ok: true, username: "@ok" }], NAV_FAIL);
+  check("第 2 次成功 → ok:true", r.ok, true);
+  check("第 2 次成功 → attempts=2", r.attempts, 2);
+  check("第 2 次成功 → attemptFn 调 1 次", calls, 1);
+}
+{
+  // 第 2 次转账号级失败 → 停止重试
+  const { r, attempts2 } = await drive([ACCT_FAIL], NAV_FAIL);
+  check("中途转账号级 → 停止", r.ok, false);
+  check("中途转账号级 → attempts=2", r.attempts, 2);
+  check("中途转账号级 → 原因为账号级", r.reason, ACCT_FAIL);
+}
+{
+  let abortChecked = false;
+  const r = await retryRestoreOnNavFailure(() => ({ ok: false, reason: NAV_FAIL }), NAV_FAIL, {
+    isRetryable: isRetryableRestoreFailure,
+    sleep: async () => {},
+    shouldAbort: () => {
+      abortChecked = true;
+      return true;
+    },
+  });
+  check("shouldAbort 中断 → aborted:true", r.aborted, true);
+  check("shouldAbort 中断 → 不再尝试", abortChecked, true);
+}
+check(
+  "重试常量：maxRetries=2 / delay=10s",
+  RESTORE_RETRY_MAX_RETRIES === 2 && RESTORE_RETRY_DELAY_MS === 10000,
+  true,
+);
+
+// ── 3. P2 熔断退避轮转 ──
+console.log("\n规则 3：崩溃熔断退避（crashBackoffMs）");
+check("BASE=60s", CRASH_BACKOFF_BASE_MS, 60000);
+check("MAX=15min", CRASH_BACKOFF_MAX_MS, 900000);
+check("第 0 轮 → 0（未熔断）", crashBackoffMs(0), 0);
+check("第 1 轮 → 60s", crashBackoffMs(1), 60000);
+check("第 2 轮 → 120s", crashBackoffMs(2), 120000);
+check("第 3 轮 → 240s（2 倍递增）", crashBackoffMs(3), 240000);
+check("第 4 轮 → 480s", crashBackoffMs(4), 480000);
+check("第 5 轮 → 960s → 钳到 MAX 900s", crashBackoffMs(5), 900000);
+check("第 100 轮 → MAX", crashBackoffMs(100), CRASH_BACKOFF_MAX_MS);
+check("负数 → 0", crashBackoffMs(-1), 0);
+check("非整数 → 0", crashBackoffMs(1.5), 0);
+check("自定义 base/max", crashBackoffMs(2, 1000, 2500), 2000);
+check("清零语义：轮数 0 → 0（成功后重算）", crashBackoffMs(0), 0);
+
+// ── 4. P5 内存阈值可配置 ──
+console.log("\n规则 4：内存阈值解析（resolveMemoryThreshold）");
+check("缺省 → 默认 0.95", resolveMemoryThreshold(undefined), 0.95);
+check("null → 默认 0.95", resolveMemoryThreshold(null), 0.95);
+check("空串 → 默认 0.95", resolveMemoryThreshold(""), 0.95);
+check("非数值 → 默认 0.95", resolveMemoryThreshold("abc"), 0.95);
+check("默认常量 MEMORY_THRESHOLD=0.95", MEMORY_THRESHOLD, 0.95);
+check("0.9 原样通过", resolveMemoryThreshold(0.9), 0.9);
+check("0.3 → 下限 0.5", resolveMemoryThreshold(0.3), MEMORY_THRESHOLD_MIN);
+check("0.99 → 上限 0.98", resolveMemoryThreshold(0.99), MEMORY_THRESHOLD_MAX);
+check("1.5 → 上限 0.98", resolveMemoryThreshold(1.5), 0.98);
+check("0.5 → 边界原样", resolveMemoryThreshold(0.5), 0.5);
+check("0.98 → 边界原样", resolveMemoryThreshold(0.98), 0.98);
+check("字符串数值 '0.9' 可解析", resolveMemoryThreshold("0.9"), 0.9);
+check(
+  "钳制边界常量 0.5/0.98",
+  MEMORY_THRESHOLD_MIN === 0.5 && MEMORY_THRESHOLD_MAX === 0.98,
+  true,
+);
+check(
+  "HealthChecker 构造生效（0.9）",
+  new HealthChecker({ memoryThreshold: 0.9 }).memoryThreshold,
+  0.9,
+);
+check(
+  "HealthChecker 构造缺省 → 0.95",
+  new HealthChecker({}).memoryThreshold,
+  0.95,
+);
+check(
+  "HealthChecker 构造非法 → 0.95",
+  new HealthChecker({ memoryThreshold: "junk" }).memoryThreshold,
+  0.95,
+);
+check(
+  "HealthChecker 构造越界 → 钳制",
+  new HealthChecker({ memoryThreshold: 0.2 }).memoryThreshold,
+  0.5,
+);
+
+console.log(`\n═══ 结果: ${pass} 通过, ${fail} 失败 ═══`);
+process.exit(fail > 0 ? 1 : 0);

package/scripts/test-error-auto-reset.mjs

@@ -0,0 +1,103 @@
+/**
+ * 错误任务自动恢复（B 方案）单测：listStaleErrorJobs + resetJob 回流
+ *
+ * 覆盖：
+ *   1. commitJob 错误结果 → 行落 jobs 表（status='error'，updated_at 盖章）
+ *   2. 龄期过滤：新鲜 error 不列出，超龄 error 列出
+ *   3. limit 参数生效
+ *   4. resetJob 回流：行回 task_queue（pending）、jobs 行消失、error 清空
+ *   5. 回流后 listStaleErrorJobs 不再列出
+ *
+ * 运行：node scripts/test-error-auto-reset.mjs
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStore } from "../src/watch/data-store.js";
+
+const MIN = 60 * 1000;
+let pass = 0;
+let fail = 0;
+
+function assert(cond, label) {
+  if (cond) {
+    pass++;
+    console.error(`  ✓ ${label}`);
+  } else {
+    fail++;
+    console.error(`  ✗ ${label}`);
+  }
+}
+
+const tmp = mkdtempSync(join(tmpdir(), "err-auto-reset-"));
+const dbPath = join(tmp, "test.db");
+const store = createStore(dbPath);
+
+try {
+  // 造数：直接向 task_queue 热表插 pending 行（addUser 只写 users/jobs_base 基线，不产热行）
+  const { addJobToDb } = await import("../src/watch/db-crud.js");
+  addJobToDb({
+    uniqueId: "user_a",
+    nickname: "A",
+    status: "pending",
+    sources: ["test"],
+  });
+  const before = store.getUser("user_a");
+  assert(before && before.status === "pending", "task_queue 造数后为 pending");
+
+  const commitRet = store.commitJob("user_a", { error: "测试错误" });
+  assert(commitRet && commitRet.saved === true, "commitJob 提交错误成功");
+  assert(commitRet.status === "error", "提交错误后 status=error");
+
+  const errJob = store.getUser("user_a");
+  assert(errJob.status === "error" && errJob.error, "error 行状态与错误旗标正确（error 列为 0/1 布尔，文本不落库）");
+
+  // ── 2. 龄期过滤 ──
+  const fresh = store.listStaleErrorJobs(10 * MIN, 500);
+  assert(!fresh.includes("user_a"), "新鲜 error（刚盖 updated_at）不被列出");
+
+  const { getDb } = await import("../src/watch/db-schema.js");
+  getDb()
+    .prepare(`UPDATE jobs SET updated_at = ? WHERE unique_id = 'user_a'`)
+    .run(Date.now() - 11 * MIN);
+  const stale = store.listStaleErrorJobs(10 * MIN, 500);
+  assert(stale.includes("user_a"), "超龄 error（11min 前）被列出");
+
+  // ── 3. limit 生效 ──
+  const limited = store.listStaleErrorJobs(10 * MIN, 0);
+  assert(limited.length === 0, "limit=0 不列出任何行");
+
+  // ── 4. resetJob 回流 ──
+  const resetRet = store.resetJob("user_a");
+  assert(resetRet && resetRet.saved === true, "resetJob 回流成功");
+
+  const backJob = store.getUser("user_a");
+  assert(backJob.status === "pending", "回流后 status=pending");
+  assert(!backJob.error, "回流后 error 已清空");
+  const { getUserTable } = await import("../src/watch/db-crud.js");
+  assert(getUserTable("user_a") === "task_queue", "回流行回到 task_queue 热表");
+
+  const jobsRow = getDb()
+    .prepare(`SELECT 1 FROM jobs WHERE unique_id = 'user_a'`)
+    .get();
+  assert(!jobsRow, "jobs 表中该行已迁出");
+
+  // ── 5. 回流后不再列出 ──
+  const after = store.listStaleErrorJobs(10 * MIN, 500);
+  assert(!after.includes("user_a"), "回流后不再被列出");
+
+  // ── 6. 无 DB（JSON 模式）安全退化 ──
+  const { closeDb } = await import("../src/watch/db-schema.js");
+  if (typeof closeDb === "function") {
+    closeDb();
+    const noDb = store.listStaleErrorJobs(10 * MIN, 500);
+    assert(Array.isArray(noDb) && noDb.length === 0, "无 DB 时返回空数组不抛错");
+  }
+} finally {
+  try {
+    rmSync(tmp, { recursive: true, force: true });
+  } catch {}
+}
+
+console.error(`\n结果: ${pass} 通过 / ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);

package/scripts/test-error-report.mjs

@@ -0,0 +1,215 @@
+/**
+ * 客户端错误上报封装（方案甲）单测：
+ *
+ * A. createErrorReporter 字段附加
+ *   1. poolUsername 从 getState 注入（有在手号/无在手号空串）
+ *   2. proxyNode 三级 fallback：端口匹配通道 → 主通道 → 空串
+ *   3. proxyUrl 缺省回退 ~/.tt-help.json 的 proxy（注入式验证 parseProxyPort）
+ *   4. 旧 username 原样透传；userId 单次覆盖（search 每轮标签 clientId 场景）
+ *   5. 缺省字段兜底（errorType 默认 other）
+ * B. 服务端 reportClientError 新字段存列
+ *   6. 首次上报落 poolUsername/proxyNode
+ *   7. 非空才覆盖语义（空串不覆盖旧值）
+ *   8. captcha 分支也不丢新字段
+ *
+ * 运行：node scripts/test-error-report.mjs
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createErrorReporter, parseProxyPort, resolveProxyNode } from "../src/lib/error-report.js";
+import { createStore } from "../src/watch/data-store.js";
+
+let pass = 0;
+let fail = 0;
+
+function assert(cond, label) {
+  if (cond) {
+    pass++;
+    console.error(`  ✓ ${label}`);
+  } else {
+    fail++;
+    console.error(`  ✗ ${label}`);
+  }
+}
+
+// ── A0. parseProxyPort ──
+{
+  console.error("\n[parseProxyPort]");
+  assert(parseProxyPort("http://127.0.0.1:7897") === 7897, "http URL 提取端口");
+  assert(parseProxyPort("socks5://localhost:1080") === 1080, "socks5 URL 提取端口");
+  assert(parseProxyPort("127.0.0.1:7890") === 7890, "非 URL 形态正则兑底");
+  assert(parseProxyPort("") === 0, "空串 → 0");
+  assert(parseProxyPort(null) === 0, "null → 0");
+  assert(parseProxyPort("http://127.0.0.1") === 0, "无端口 → 0");
+}
+
+// ── A1/A2. resolveProxyNode 三级 fallback（deps 注入，不依赖真机文件） ──
+{
+  console.error("\n[resolveProxyNode 三级 fallback]");
+  const channels = [
+    { port: 7897, node: "端口匹配节点", stale: false },
+    { port: 7898, node: "其他通道节点", stale: true }, // stale 通道不参与匹配
+  ];
+  const health = { node: "主通道节点", stale: false };
+
+  assert(
+    resolveProxyNode("http://127.0.0.1:7897", { channels, health }) ===
+      "端口匹配节点",
+    "L1 业务端口匹配非 stale 通道的 node",
+  );
+  assert(
+    resolveProxyNode("http://127.0.0.1:7899", { channels, health }) ===
+      "主通道节点",
+    "L2 端口无匹配 → 主通道 node",
+  );
+  assert(
+    resolveProxyNode("", { channels, health }) === "主通道节点",
+    "无代理地址 → 跳过 L1 直接主通道",
+  );
+  assert(
+    resolveProxyNode("http://127.0.0.1:7899", {
+      channels,
+      health: { node: "主通道节点", stale: true },
+    }) === "",
+    "L3 主通道 stale → 空串",
+  );
+  assert(
+    resolveProxyNode("http://127.0.0.1:7897", {
+      channels: [{ port: 7897, node: "x", stale: true }],
+      health: null,
+    }) === "",
+    "L3 通道仅 stale + 无主通道 → 空串",
+  );
+  assert(
+    resolveProxyNode("http://127.0.0.1:7897", { channels: [], health: null }) ===
+      "",
+    "L3 无 clash（空通道/null health）→ 空串",
+  );
+}
+
+// ── A3~A5. createErrorReporter 字段附加 ──
+{
+  console.error("\n[createErrorReporter 字段附加]");
+  const captured = [];
+  const apiPost = async (url, body) => {
+    captured.push({ url, body });
+    return { ok: true };
+  };
+  let poolUsername = "pool_user_01";
+  const reporter = createErrorReporter({
+    apiPost,
+    serverUrl: "http://127.0.0.1:3001",
+    userId: "machine_user",
+    proxyUrl: "http://127.0.0.1:7897",
+    getState: () => ({ poolUsername }),
+  });
+  const channels = [{ port: 7897, node: "通道节点N1", stale: false }];
+  const health = { node: "主通道节点", stale: false };
+
+  await reporter.report({
+    errorType: "captcha",
+    errorMessage: "页面出现验证码",
+    stage: "video-page",
+    username: "target_user",
+    // deps 注入走 report 内部 resolveProxyNode —— 无法从外部传，
+    // 这里用真文件环境不可控，改为直接校验 resolveProxyNode 已单测；
+    // report 层只断言 poolUsername/userId/透传/兜底
+  });
+  const b1 = captured[0].body;
+  assert(captured[0].url === "http://127.0.0.1:3001/api/error-report", "POST 地址正确");
+  assert(b1.userId === "machine_user", "userId 取工厂注入值");
+  assert(b1.username === "target_user", "旧 username 原样透传");
+  assert(b1.errorType === "captcha" && b1.stage === "video-page", "业务字段透传");
+  assert(typeof b1.poolUsername === "string", "poolUsername 字段存在");
+  assert(typeof b1.proxyNode === "string", "proxyNode 字段存在");
+
+  await reporter.report({ errorType: "network" });
+  const b2 = captured[1].body;
+  assert(b2.userId === "machine_user", "未传 username 时其余字段仍完整");
+
+  await reporter.report({
+    userId: "per-tag-client-id",
+    errorType: "other",
+    username: "search_tag",
+  });
+  assert(
+    captured[2].body.userId === "per-tag-client-id",
+    "userId 单次覆盖（search 每轮标签 clientId 场景）",
+  );
+
+  poolUsername = "";
+  await reporter.report({ errorType: "other" });
+  assert(
+    captured[3].body.poolUsername === "",
+    "无在手号 → poolUsername 空串（不传 unknown）",
+  );
+
+  // getState 未注入也不炸
+  const bare = createErrorReporter({ apiPost, serverUrl: "http://x", userId: "u" });
+  await bare.report({ errorType: "other" });
+  assert(captured[4].body.poolUsername === "", "无 getState → poolUsername 空串兜底");
+
+  let threw = false;
+  try {
+    createErrorReporter({ serverUrl: "http://x", userId: "u" });
+  } catch {
+    threw = true;
+  }
+  assert(threw, "缺 apiPost 抛错（防止静默漏报）");
+}
+
+// ── B. 服务端 reportClientError 存列 ──
+{
+  console.error("\n[reportClientError 新字段存列]");
+  const tmp = mkdtempSync(join(tmpdir(), "err-report-"));
+  const store = createStore(join(tmp, "test.db"));
+  try {
+    store.reportClientError(
+      "node_a", "other", "业务错误", "legacy_user", "process", "stack",
+      "host-a", "F-1@HOST", "pool_user_01", "通道节点N1",
+    );
+    let e = store.getClientErrors().find((c) => c.userId === "node_a");
+    assert(e && e.poolUsername === "pool_user_01", "首次上报落 poolUsername");
+    assert(e && e.proxyNode === "通道节点N1", "首次上报落 proxyNode");
+    assert(e && e.username === "legacy_user", "旧 username 语义不动");
+
+    // 非空才覆盖：空串不冲掉旧值
+    store.reportClientError(
+      "node_a", "network", "超时", "", "process", "",
+      "host-a", "F-1@HOST", "", "",
+    );
+    e = store.getClientErrors().find((c) => c.userId === "node_a");
+    assert(e.poolUsername === "pool_user_01", "空 poolUsername 不覆盖旧值");
+    assert(e.proxyNode === "通道节点N1", "空 proxyNode 不覆盖旧值");
+    assert(e.errorType === "network", "常规字段仍按原语义覆盖");
+
+    // 非空新值覆盖
+    store.reportClientError(
+      "node_a", "network", "超时2", "", "process", "",
+      "host-a", "F-1@HOST", "pool_user_02", "通道节点N2",
+    );
+    e = store.getClientErrors().find((c) => c.userId === "node_a");
+    assert(e.poolUsername === "pool_user_02", "非空 poolUsername 覆盖");
+    assert(e.proxyNode === "通道节点N2", "非空 proxyNode 覆盖");
+
+    // captcha 分支（走计数路径）同样落新字段
+    store.reportClientError(
+      "node_b", "captcha", "验证码", "", "between-tasks", "",
+      "host-b", "F-2@HOST", "pool_user_03", "主通道节点",
+    );
+    const b = store.getClientErrors().find((c) => c.userId === "node_b");
+    assert(b && b.captchaCount === 1 && b.poolUsername === "pool_user_03" && b.proxyNode === "主通道节点",
+      "captcha 分支落新字段且计数路径不受影响");
+
+    // 旧版客户端（不带新字段，undefined 参数）不炸、落空串
+    store.reportClientError("node_c", "other", "旧客户端", "u", "process", "", "h", "c");
+    const c = store.getClientErrors().find((r) => r.userId === "node_c");
+    assert(c && c.poolUsername === "" && c.proxyNode === "", "旧客户端兼容：缺参落空串");
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+console.error(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);