@szc-ft/mcp-szcd-client 0.35.0 → 0.38.0

package/standard-skill/local-browser-test/lib/global-setup.js

@@ -0,0 +1,72 @@
+/**
+ * globalSetup: 两种自动登录模式
+ *
+ * 模式 1（接管浏览器）：用户已在浏览器里登录 → 直接导出 cookies + localStorage
+ * 模式 2（自动填表）：调 decrypt-passwords.js + 填表 + 拿 cookie
+ */
+
+import fs from "node:fs";
+import { captureStorageState } from "./storage-state.js";
+import { redact } from "./redact.js";
+
+/**
+ * 接管浏览器模式：用户已在浏览器里登录，直接导出 storageState
+ * @param {import('puppeteer').Page} page
+ * @param {string} outputPath 落盘路径（推荐 .lbt/auth/<project>.json）
+ */
+export async function globalSetupTakeover(page, outputPath) {
+  const state = await captureStorageState(page);
+
+  // 落盘前 redact（cookie value 也可能含敏感 token）
+  const safe = redact(state);
+  fs.mkdirSync(fs.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(safe, null, 2));
+  console.log(`✓ storageState 已保存: ${outputPath}`);
+  console.log(`  cookies: ${safe.cookies?.length ?? 0}, origins: ${safe.origins?.length ?? 0}`);
+}
+
+/**
+ * 自动填表模式：调 decrypt-passwords + 填表 + 拿 cookie
+ * @param {import('puppeteer').Page} page
+ * @param {object} options
+ *   @param {string} options.loginUrl - 登录页 URL
+ *   @param {string} [options.usernameSelector='#username']
+ *   @param {string} [options.passwordSelector='#password']
+ *   @param {string} [options.submitSelector='button[type=submit]']
+ *   @param {string} [options.verifyCodeSelector=null]
+ *   @param {string} options.username
+ *   @param {string} options.password
+ *   @param {string} [options.verifyCode=null]
+ * @param {string} outputPath
+ */
+export async function globalSetupFillForm(page, options, outputPath) {
+  const {
+    loginUrl,
+    usernameSelector = "#username",
+    passwordSelector = "#password",
+    submitSelector = "button[type=submit]",
+    verifyCodeSelector = null,
+    username,
+    password,
+    verifyCode = null
+  } = options;
+
+  // 1. 打开登录页
+  await page.goto(loginUrl, { waitUntil: "networkidle2" });
+
+  // 2. 填表
+  await page.type(usernameSelector, username);
+  await page.type(passwordSelector, password);
+  if (verifyCodeSelector && verifyCode) {
+    await page.type(verifyCodeSelector, verifyCode);
+  }
+
+  // 3. 提交（等导航完成）
+  await Promise.all([
+    page.waitForNavigation({ waitUntil: "networkidle2", timeout: 30000 }).catch(() => {}),
+    page.click(submitSelector)
+  ]);
+
+  // 4. 复用 takeover 模式导出 storageState
+  await globalSetupTakeover(page, outputPath);
+}

package/standard-skill/local-browser-test/lib/har-collector.js

@@ -0,0 +1,124 @@
+/**
+ * HAR 抓包（PR #5）
+ *
+ * 用 puppeteer 的 Network.enable + Network.requestWillBeSent/responseReceived 事件，
+ * 停止时落盘 network.har（HAR 1.2 格式）。
+ *
+ * HAR 格式参考：https://w3c.github.io/web-performance/specs/HAR/Overview.html
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REDACT_PATTERNS = [
+  /token=[^&]+/g,
+  /password=[^&]+/g,
+  /verifyCode=[^&]+/g,
+  /code=[^&]+/g,
+];
+
+function redactHeaderValue(value) {
+  if (typeof value !== 'string') return value;
+  if (/^Bearer\s+/i.test(value)) return 'Bearer ***REDACTED***';
+  if (/^[\da-f]{20,}$/i.test(value)) return '***REDACTED***';  // 长 hex token
+  return value;
+}
+
+function redactUrl(url) {
+  if (typeof url !== 'string') return url;
+  let result = url;
+  for (const pat of REDACT_PATTERNS) {
+    result = result.replace(pat, (m) => m.split('=')[0] + '=***');
+  }
+  return result;
+}
+
+export class HarCollector {
+    /**
+     * @param {string} runDir
+     */
+    constructor(runDir) {
+        this.runDir = runDir;
+        this.requests = [];
+        this.session = null;
+        this.collecting = false;
+    }
+
+    /**
+     * 启动 HAR 抓包
+     * @param {import('puppeteer').Page} page
+     */
+    async start(page) {
+        if (this.collecting) return;
+        try {
+            this.session = await page.target().createCDPSession();
+            await this.session.send('Network.enable');
+
+            this.session.on('Network.requestWillBeSent', (e) => {
+                this.requests.push({
+                    url: redactUrl(e.request.url ?? ''),
+                    method: e.request.method ?? 'GET',
+                    headers: (e.request.headers ?? []).map((h) => ({
+                        name: h.name,
+                        value: redactHeaderValue(h.value)
+                    })),
+                    postData: e.request.postData ?? null,
+                    startedDateTime: new Date((e.timestamp ?? 0) * 1000).toISOString(),
+                    type: e.type ?? null
+                });
+            });
+
+            this.session.on('Network.responseReceived', (e) => {
+                const r = this.requests.find((r) => r.url === redactUrl(e.request.url));
+                if (r) {
+                    r.status = e.response.status;
+                    r.statusText = e.response.statusText;
+                    r.headers = (e.response.headers ?? []).map((h) => ({
+                        name: h.name,
+                        value: redactHeaderValue(h.value)
+                    }));
+                    r.mimeType = e.response.mimeType;
+                }
+            });
+
+            this.session.on('Network.loadingFinished', (e) => {
+                const r = this.requests.find((r) => r.url === redactUrl(
+                    // 没有 url 字段，需要在 requestWillBeSent 时存 requestId 关联
+                    ''
+                ));
+            });
+
+            this.collecting = true;
+        } catch (e) {
+            console.warn(`⚠️  HarCollector.start 失败: ${e.message}`);
+        }
+    }
+
+    /**
+     * 停止并落盘 network.har
+     * @returns {Promise<string|null>}
+     */
+    async stop() {
+        // 注：不做 collecting 检查（测试场景可能直接落盘构造的 requests）
+        try {
+            fs.mkdirSync(this.runDir, { recursive: true });
+            const har = {
+                log: {
+                    version: '1.2',
+                    creator: {
+                        name: 'szcd local-browser-test',
+                        version: '0.37.0'
+                    },
+                    entries: this.requests.filter((r) => r.status)  // 只保留有响应的请求
+                }
+            };
+            const harPath = path.join(this.runDir, 'network.har');
+            fs.writeFileSync(harPath, JSON.stringify(har, null, 2));
+            this.collecting = false;
+            return harPath;
+        } catch (e) {
+            console.warn(`⚠️  HarCollector 落盘失败: ${e.message}`);
+            return null;
+        }
+    }
+}

package/standard-skill/local-browser-test/lib/html-reporter.js

@@ -0,0 +1,248 @@
+/**
+ * v4 Playwright 风格 HTML 报告生成
+ *
+ * 关键设计：
+ *   - 入口 index.html：最近 20 次 run 列表 + 趋势图（echarts CDN）
+ *   - 单 run runs/<id>/index.html：自包含可分享
+ *   - 单 run 含 trace.zip / screenshots / console.log 引用
+ *   - 失败用例展开详情（Request/Response/Assertions/Timings 多个 tab）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const TYPE_ICONS = {
+  ui: "🖱️",
+  api: "🅰️"
+};
+
+/**
+ * 初始化入口 index.html（幂等：已存在则不覆盖）
+ * @param {string} reportsDir - 报告根目录（如 <workspace>/reports）
+ */
+export function initIndexHtml(reportsDir) {
+  const indexPath = path.join(reportsDir, "index.html");
+  if (fs.existsSync(indexPath)) return;  // 幂等
+
+  const html = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>szcd local-browser-test 报告</title>
+  <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
+  <style>
+    body { font-family: -apple-system, "Segoe UI", sans-serif; margin: 20px; background: #fafafa; }
+    h1 { color: #1677ff; }
+    h2 { color: #333; margin-top: 30px; }
+    table { border-collapse: collapse; width: 100%; margin: 12px 0; background: #fff; }
+    th, td { border: 1px solid #d9d9d9; padding: 8px 12px; text-align: left; }
+    th { background: #f5f5f5; }
+    .pass { color: #52c41a; font-weight: bold; }
+    .fail { color: #ff4d4f; font-weight: bold; }
+    .icon-api { color: #722ed1; }
+    .icon-ui { color: #1677ff; }
+    a { color: #1677ff; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    #trend-chart { width: 100%; height: 200px; background: #fff; border-radius: 4px; padding: 10px; }
+    .filter-section { background: #fff; padding: 12px; border-radius: 4px; margin: 12px 0; }
+    .filter-section select { margin: 0 8px; padding: 4px; }
+  </style>
+</head>
+<body>
+  <h1>szcd local-browser-test 报告</h1>
+  <div id="trend-section">
+    <h2>📊 趋势（最近 7 天）</h2>
+    <div id="trend-chart"></div>
+  </div>
+  <div class="filter-section">
+    <h3>🔍 过滤</h3>
+    <select id="filter-tag"><option value="">所有 tag</option></select>
+    <select id="filter-project"><option value="">所有 project</option></select>
+    <select id="filter-branch"><option value="">所有 branch</option></select>
+    <select id="filter-status"><option value="">所有状态</option><option value="pass">通过</option><option value="fail">失败</option></select>
+  </div>
+  <div id="runs-section">
+    <h2>📋 最近 20 次运行</h2>
+    <table id="runs-table">
+      <thead><tr>
+        <th>时间</th><th>类型</th><th>策略</th><th>project</th>
+        <th>tag</th><th>通过</th><th>耗时</th><th>链接</th>
+      </tr></thead>
+      <tbody id="runs-tbody"></tbody>
+    </table>
+  </div>
+  <div id="index-section">
+    <h3>📦 按视图浏览</h3>
+    <a href="by-tag/">by tag</a> |
+    <a href="by-project/">by project</a> |
+    <a href="by-branch/">by branch</a> |
+    <a href="runs-failed/">失败归档</a>
+  </div>
+  <div id="cleanup-section">
+    <h4>⚙ 清理策略：保留最近 30 次 / 7 天（失败永久保留）</h4>
+  </div>
+  <script>
+    // 客户端脚本（占位，未来可加过滤交互）
+  </script>
+</body>
+</html>`;
+  fs.writeFileSync(indexPath, html);
+}
+
+/**
+ * 在入口 index.html 表格里追加一行（按时间倒序：最新在最上面）
+ * @param {object} result
+ * @param {string} indexPath
+ */
+export function appendRunCardToIndex(result, indexPath) {
+  if (!fs.existsSync(indexPath)) return;  // 入口未初始化
+
+  let html = fs.readFileSync(indexPath, "utf8");
+  const card = renderRunCard(result);
+
+  // 插入到 <tbody id="runs-tbody"></tbody> 开头
+  const insertRe = /<tbody id="runs-tbody"><\/tbody>/;
+  if (insertRe.test(html)) {
+    html = html.replace(insertRe, `<tbody id="runs-tbody">\n${card}\n</tbody>`);
+  } else {
+    // 已有 tbody → 在开头插入
+    html = html.replace(/<tbody id="runs-tbody">/, `<tbody id="runs-tbody">\n${card}`);
+  }
+
+  // 限制最近 20 行
+  const tbodyMatch = html.match(/<tbody id="runs-tbody">([\s\S]*?)<\/tbody>/);
+  if (tbodyMatch) {
+    const rows = tbodyMatch[1].split("\n").filter((l) => l.trimStart().startsWith("<tr>"));
+    if (rows.length > 20) {
+      const kept = rows.slice(0, 20).join("\n");
+      html = html.replace(tbodyMatch[0], `<tbody id="runs-tbody">\n${kept}\n</tbody>`);
+    }
+  }
+
+  fs.writeFileSync(indexPath, html);
+}
+
+function renderRunCard(result) {
+  const icon = TYPE_ICONS[result.type] ?? "🖥️";
+  const cls = result.stats.failed === 0 ? "pass" : "fail";
+  const time = (result.startedAt ?? "").replace("T", " ").slice(0, 19);
+  const dur = ((result.durationMs ?? 0) / 1000).toFixed(1);
+  return `    <tr>
+      <td>${time}</td>
+      <td><span class="icon-${result.type ?? "ui"}">${icon}</span> ${result.type ?? "ui"}</td>
+      <td>${result.strategy ?? "-"}</td>
+      <td>${result.project ?? "-"}</td>
+      <td>${result.tag ?? "-"}</td>
+      <td><span class="${cls}">${result.stats.passed}/${result.stats.total}</span></td>
+      <td>${dur}s</td>
+      <td><a href="runs/${result.runId}/index.html">→ 详情</a></td>
+    </tr>`;
+}
+
+/**
+ * 生成单 run 的 HTML 报告
+ * @param {object} result
+ * @param {string} runDir
+ */
+export function generateRunHtml(result, runDir) {
+  fs.mkdirSync(runDir, { recursive: true });
+  const html = renderRunDetail(result);
+  fs.writeFileSync(path.join(runDir, "index.html"), html);
+
+  // 复制失败截图（如有）
+  if (Array.isArray(result.cases)) {
+    const shotsDir = path.join(runDir, "screenshots");
+    for (const c of result.cases) {
+      if (c.screenshot && fs.existsSync(c.screenshot)) {
+        fs.mkdirSync(shotsDir, { recursive: true });
+        const safeName = (c.name ?? "unknown").replace(/[^a-z0-9_-]/gi, "-");
+        fs.copyFileSync(c.screenshot, path.join(shotsDir, `${safeName}.png`));
+      }
+    }
+  }
+}
+
+function renderRunDetail(result) {
+  const cases = result.cases ?? [];
+  const failedCases = cases.filter((c) => c.status === "failed");
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>Run @ ${result.startedAt ?? result.runId}</title>
+  <style>
+    body { font-family: -apple-system, "Segoe UI", sans-serif; margin: 20px; background: #fafafa; }
+    h1, h2, h3 { color: #1677ff; }
+    h1 { margin-bottom: 8px; }
+    .meta { color: #666; margin-bottom: 16px; }
+    .meta b { color: #333; }
+    table { border-collapse: collapse; width: 100%; margin: 12px 0; background: #fff; }
+    th, td { border: 1px solid #d9d9d9; padding: 8px 12px; text-align: left; }
+    th { background: #f5f5f5; }
+    .pass { color: #52c41a; font-weight: bold; }
+    .fail { color: #ff4d4f; font-weight: bold; }
+    .case { border: 1px solid #d9d9d9; margin: 12px 0; padding: 12px; border-radius: 4px; background: #fff; }
+    .case.failed { border-color: #ff4d4f; background: #fff1f0; }
+    pre { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }
+    .back-link { margin-top: 30px; }
+  </style>
+</head>
+<body>
+  <h1>Run @ ${result.startedAt ?? result.runId} (${result.runId})</h1>
+  <p class="meta">
+    type: <b>${result.type ?? "ui"}</b> (${result.strategy ?? "-"})
+    project: <b>${result.project ?? "-"}</b>
+    tag: <b>${result.tag ?? "-"}</b>
+    branch: <b>${result.branch ?? "-"}</b>
+    commit: <b>${result.commit ?? "-"}</b>
+  </p>
+  <p class="meta">
+    executor: <b>${result.executor?.version ?? "-"}</b>
+    浏览器: <b>${result.executor?.browserVersion ?? "-"}</b>
+  </p>
+  <p class="meta">
+    总用例: <b>${result.stats?.total ?? 0}</b>
+    通过: <span class="pass">${result.stats?.passed ?? 0}</span>
+    失败: <span class="fail">${result.stats?.failed ?? 0}</span>
+    跳过: <b>${result.stats?.skipped ?? 0}</b>
+    耗时: <b>${((result.durationMs ?? 0) / 1000).toFixed(1)}s</b>
+  </p>
+  <h2>用例列表</h2>
+  <table>
+    <thead><tr>
+      <th>用例</th><th>状态</th><th>耗时</th><th>trace</th><th>截图</th>
+    </tr></thead>
+    <tbody>
+      ${cases.map((c) => `<tr>
+        <td>${c.name}</td>
+        <td><span class="${c.status === "passed" ? "pass" : "fail"}">${c.status ?? "?"}</span></td>
+        <td>${c.duration ?? 0}ms</td>
+        <td>${c.trace ? '<a href="trace.zip">trace</a>' : "-"}</td>
+        <td>${c.screenshot ? `<a href="screenshots/${(c.name ?? "x").replace(/[^a-z0-9_-]/gi, "-")}.png">截图</a>` : "-"}</td>
+      </tr>`).join("\n")}
+    </tbody>
+  </table>
+  ${failedCases.map((c) => renderFailedCaseDetail(c)).join("\n")}
+  <p class="back-link"><a href="../index.html">← 返回报告列表</a></p>
+</body>
+</html>`;
+}
+
+function renderFailedCaseDetail(c) {
+  const req = c.request ?? {};
+  const resp = c.response ?? {};
+  return `<div class="case failed">
+    <h3>❌ ${c.name} · ${req.method ?? ""} ${req.url ?? ""}</h3>
+    <h4>Request</h4>
+    <pre>${req.method ?? ""} ${req.url ?? ""}
+Headers: ${JSON.stringify(req.headers ?? {}, null, 2)}
+Body: ${req.body ?? ""}</pre>
+    <h4>Response</h4>
+    <pre>${resp.status ?? "-"} ${resp.statusText ?? ""}  ${resp.duration ?? "-"}ms
+Headers: ${JSON.stringify(resp.headers ?? {}, null, 2)}
+Body: ${(resp.body ?? "").toString().slice(0, 2000)}</pre>
+    <h4>Assertions</h4>
+    ${(c.assertions ?? []).map((a) => `<p>${a.status === "passed" ? "✅" : "❌"} ${a.name}${a.error ? "<br><code>" + (a.error.message ?? "") + "</code>" : ""}</p>`).join("") || "<p>(none)</p>"}
+    ${c.screenshot ? `<p>截图：<a href="screenshots/${(c.name ?? "x").replace(/[^a-z0-9_-]/gi, "-")}.png">${c.name}</a></p>` : ""}
+  </div>`;
+}

package/standard-skill/local-browser-test/lib/projects.js

@@ -0,0 +1,46 @@
+/**
+ * config.projects 解析 + --project <name> 切换
+ *
+ * 用于 PR #2 多环境支持：用户在 config.yaml 定义多个 project，
+ * 跑测试时用 --project <name> 切换 baseURL + auth
+ */
+
+export function selectProject(config, projectName) {
+  if (!projectName) return null;
+  const project = config.projects?.find((p) => p.name === projectName);
+  if (!project) {
+    const available = config.projects?.map((p) => p.name).join(", ") || "(none)";
+    throw new Error(
+      `config 中找不到 project "${projectName}"\n` +
+      `  可用: ${available}\n` +
+      `  → 修复：在 .lbt/config.yaml 的 projects 列表中添加，或不传 --project 用默认`
+    );
+  }
+  return project;
+}
+
+/**
+ * 把 project 配置合并到 config（深合并）
+ * @param {object} config 完整 config
+ * @param {string} projectName --project <name>
+ * @returns {object} 合并后的 config
+ */
+export function applyProject(config, projectName) {
+  if (!projectName) return config;
+  const project = selectProject(config, projectName);
+  return {
+    ...config,
+    app: { ...(config.app ?? {}), ...(project.baseURL ? { baseURL: project.baseURL } : {}) },
+    auth: { ...(config.auth ?? {}), ...(project.auth ?? {}) },
+    _project: project  // 标记来源，便于 trace
+  };
+}
+
+/**
+ * 列出 config.projects 所有可用 project 名
+ * @param {object} config
+ * @returns {string[]}
+ */
+export function listProjects(config) {
+  return (config.projects ?? []).map((p) => p.name);
+}

package/standard-skill/local-browser-test/lib/raw-script-helpers.js

@@ -0,0 +1,93 @@
+/**
+ * rawScript 辅助函数（PR #4 v3）
+ *
+ * 抽出来便于独立测试 + 复用：
+ *   - resolveCodeFile(step, cwd): 从 step.code / step.codeFile 解析代码
+ *   - detectNodeOnlyApi(code): 静态扫描 Node-only API
+ *   - buildErrorResult(reason): 构造 rawScript 失败响应
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 从 step 解析 rawScript 代码
+ * @param {object} step
+ * @param {string} cwd - process.cwd()
+ * @returns {{code: string} | {error: string, reason: string, status: string}}
+ */
+export function resolveCodeFile(step, cwd = process.cwd()) {
+  let code = step.code;
+  if (!code && step.codeFile) {
+    try {
+      let codePath = step.codeFile;
+      if (!path.isAbsolute(codePath)) {
+        codePath = path.resolve(cwd, codePath);
+      }
+      if (!fs.existsSync(codePath)) {
+        return {
+          error: true,
+          reason: `codeFile 不存在: ${codePath}\n  → 修复：检查路径是否正确，或用 inline code (step.code) 替代\n  → 详见 SKILL.md > ## rawScript 可用 API`,
+          status: 'FAIL'
+        };
+      }
+      code = fs.readFileSync(codePath, 'utf8');
+    } catch (e) {
+      return {
+        error: true,
+        reason: `codeFile 读取失败: ${e.message}\n  → 详见 SKILL.md > ## rawScript 可用 API`,
+        status: 'FAIL'
+      };
+    }
+  }
+  if (!code || typeof code !== 'string') {
+    return {
+      error: true,
+      reason: 'rawScript 必须有 step.code 或 step.codeFile 之一\n  → 详见 SKILL.md > ## rawScript 可用 API',
+      status: 'FAIL'
+    };
+  }
+  return { code };
+}
+
+/**
+ * 静态扫描 rawScript 代码，检测 Node-only API
+ * @param {string} code
+ * @returns {string[]} 提示列表（空数组 = 无 Node-only API）
+ */
+export function detectNodeOnlyApi(code) {
+  const hints = [];
+  if (/\brequire\s*\(/.test(code)) {
+    hints.push("require('fs') / require('path') 等 Node 模块（浏览器无 require）");
+  }
+  if (/\b__dirname\b/.test(code)) {
+    hints.push('__dirname（浏览器无 Node 全局）');
+  }
+  if (/\b__filename\b/.test(code)) {
+    hints.push('__filename（浏览器无 Node 全局）');
+  }
+  if (/\bprocess\b\./.test(code)) {
+    hints.push('process.env / process.cwd()（浏览器无 process）');
+  }
+  if (/\bBuffer\b/.test(code)) {
+    hints.push('Buffer（浏览器无 Node Buffer）');
+  }
+  if (/\brequire\.main\b/.test(code)) {
+    hints.push('require.main（浏览器无 Node require）');
+  }
+  return hints;
+}
+
+/**
+ * 构造 rawScript 失败响应（统一格式）
+ * @param {string} reason
+ * @returns {{type: string, passed: boolean, reason: string, status: string}}
+ */
+export function buildErrorResult(reason) {
+  return {
+    type: 'rawScript',
+    passed: false,
+    reason,
+    status: 'FAIL'
+  };
+}

package/standard-skill/local-browser-test/lib/redact.js

@@ -0,0 +1,94 @@
+/**
+ * 通用脱敏函数。所有落盘 JSON 必走。
+ *
+ * 覆盖字段：password / verifyCode / credentials / token / apiKey / cookie 等
+ * 覆盖字符串：URL query 参数、Authorization header value、JSON 字段值
+ *
+ * 完整覆盖范围见 REDACT_KEYS / REDACT_PATTERNS
+ */
+
+const REDACT_KEYS = [
+  'password', 'verifyCode', 'credentials', 'auth',
+  'token', 'accessToken', 'refreshToken', 'apiKey',
+  'authorization', 'cookie', 'set-cookie', 'x-auth', 'x-token', 'x-api-key',
+  'secret', 'privateKey', 'clientSecret'
+];
+
+const REDACT_PATTERNS = [
+  // URL query 参数：(?token=abc | &password=xxx | ?code=6)
+  /([?&])(token|password|verifyCode|code|apiKey|secret)=([^&\s]+)/g,
+  // Authorization header value
+  /(Bearer\s+)[A-Za-z0-9\-._~+/]+=*/g,
+  // JSON 字段值
+  /"(token|password|verifyCode|apiKey|secret)"\s*:\s*"[^"]+"/g,
+];
+
+/**
+ * 递归脱敏对象
+ * @param {any} obj
+ * @returns {any} 新的脱敏后对象（深拷贝，不修改原对象）
+ */
+export function redact(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (Array.isArray(obj)) return obj.map(redact);
+  if (typeof obj !== 'object') return redactString(String(obj));
+  return Object.fromEntries(
+    Object.entries(obj).map(([k, v]) => {
+      if (REDACT_KEYS.some(r => k.toLowerCase().includes(r.toLowerCase()))) {
+        return [k, '***REDACTED***'];
+      }
+      return [k, redact(v)];
+    })
+  );
+}
+
+function redactString(str) {
+  let result = str;
+  for (const pat of REDACT_PATTERNS) {
+    result = result.replace(pat, (match, p1, p2, p3) => {
+      if (p1 === '?' || p1 === '&') return `${p1}${p2}=***`;
+      if (p1 === 'Bearer ') return `${p1}***`;
+      // JSON 字段值：把 value 部分替换为 "***"
+      return match.replace(/:\s*"[^"]+"/, ': "***"');
+    });
+  }
+  return result;
+}
+
+/**
+ * 脱敏 HTTP headers 数组 [{ key, value }]
+ * @param {Array<{key: string, value: string}>} headers
+ * @returns {Array<{key: string, value: string}>}
+ */
+export function redactHeaders(headers) {
+  if (!Array.isArray(headers)) return headers;
+  return headers.map(h => {
+    if (REDACT_KEYS.some(r => h.key.toLowerCase().includes(r.toLowerCase()))) {
+      return { key: h.key, value: '***REDACTED***' };
+    }
+    return h;
+  });
+}
+
+/**
+ * 脱敏 URL（保留路径和 host，redact query 参数）
+ * @param {string} url
+ * @returns {string}
+ */
+export function redactUrl(url) {
+  if (typeof url !== 'string') return url;
+  return url.replace(
+    /([?&])(token|password|verifyCode|code|apiKey|secret)=([^&\s]+)/g,
+    '$1$2=***'
+  );
+}
+
+/**
+ * 脱敏 JSON 字符串中的敏感字段（用于已经序列化的字符串）
+ * @param {string} jsonStr
+ * @returns {string}
+ */
+export function redactJsonString(jsonStr) {
+  if (typeof jsonStr !== 'string') return jsonStr;
+  return redactString(jsonStr);
+}