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

package/opencode-extension/skills/local-browser-test/lib/api-call-executor.js

@@ -0,0 +1,251 @@
+/**
+ * apiCall step 增强执行器（PR #8 v3 走法 P）
+ *
+ * 关键设计：
+ *   - API 步骤走 Node 18+ 内置 fetch（**不通过浏览器**，但自动共享 context.cookies()）
+ *   - UI 步骤走 page（真实浏览器，CDP）
+ *   - 同一 testCase 跑（UI + API 混合），cookie 自动共享
+ *   - 首次 = 回归 = 真实行为（永远一致）
+ *   - 不引入 newman 依赖
+ *   - 不引入 axios 依赖（用 fetch 即可，Node 18+ 内置）
+ *
+ * 6 个新字段：
+ *   - assert: L1 status / L2 header / L3 body path / L4 responseTime
+ *   - captureTrace: HAR-like trace 录制（PR #5 trace-collector 集成）
+ *   - noRetry: 写操作禁重试（PR #6 retry-policy 集成）
+ *   - strategy: plan 显式（newman / browser / auto）
+ *   - headers: 自定义请求头
+ *   - tags: 用例标签（PR #7）
+ */
+
+import { redact } from './redact.js';
+
+/**
+ * apiCall step 增强 schema
+ * @typedef {object} ApiCallStep
+ * @property {'apiCall'} type
+ * @property {string} method
+ * @property {string} url
+ * @property {object} [headers]
+ * @property {object} [body]
+ * @property {object} [assert] - L1-L4 断言
+ * @property {boolean} [captureTrace] - 是否记录 trace
+ * @property {boolean} [noRetry] - 写操作禁重试（默认 true）
+ * @property {string} [strategy] - plan 显式（newman / browser / auto）
+ * @property {string[]} [tags] - 用例标签
+ */
+
+/**
+ * 共享 cookie header（PR #8 关键设计）
+ * @param {Array<{name: string, value: string, domain?: string}>} cookies
+ * @param {string} [targetOrigin]
+ * @returns {string} Cookie 头（空字符串如果无 cookie）
+ */
+export function buildCookieHeader(cookies, targetOrigin) {
+    if (!Array.isArray(cookies) || cookies.length === 0) return '';
+    const filtered = targetOrigin
+        ? cookies.filter((c) => c.domain?.endsWith(targetOrigin.replace(/^https?:\/\//, '')))
+        : cookies;
+    return filtered.map((c) => `${c.name}=${c.value}`).join('; ');
+}
+
+/**
+ * ★ axios interceptor 工厂：记录 timings（PR #5 + PR #8）
+ * @param {object} collector - { timings: Array<{name, url, method, total}> }
+ * @returns {{ request: Function, response: Function, error: Function }}
+ */
+export function createTimingsInterceptor(collector) {
+    return {
+        request(config) {
+            config.metadata = { startTime: process.hrtime.bigint() };
+            return config;
+        },
+        response(response) {
+            const ns = process.hrtime.bigint() - response.config.metadata.startTime;
+            const total = Number(ns / 1000000n);  // ms
+            collector.timings.push({
+                name: response.config.metadata.name ?? '',
+                url: response.config.url,
+                method: response.config.method?.toUpperCase(),
+                total,
+                status: response.status
+            });
+            response.config.metadata.total = total;
+            return response;
+        },
+        error(error) {
+            if (error.config?.metadata) {
+                const ns = process.hrtime.bigint() - error.config.metadata.startTime;
+                error.config.metadata.total = Number(ns / 1000000n);
+            }
+            return Promise.reject(error);
+        }
+    };
+}
+
+/**
+ * L1-L4 断言引擎
+ * @param {object} response - axios response
+ * @param {object} assertSpec - 断言规格
+ * @returns {{passed: boolean, checks: Array<{name: string, level: number, passed: boolean, actual: any, expected: any, error?: string}>}}
+ */
+export function assertApiResponse(response, assertSpec) {
+    const checks = [];
+    let allPassed = true;
+
+    // L1: status code
+    if (assertSpec.status !== undefined) {
+        const actual = response.status;
+        const expected = assertSpec.status;
+        const passed = actual === expected;
+        checks.push({ name: `Status is ${expected}`, level: 1, actual, expected, passed });
+        if (!passed) allPassed = false;
+    }
+
+    // L2: header
+    if (assertSpec.headers) {
+        for (const [key, expected] of Object.entries(assertSpec.headers)) {
+            const actual = response.headers?.[key.toLowerCase()];
+            const passed = actual === expected;
+            checks.push({ name: `Header ${key}=${expected}`, level: 2, actual, expected, passed });
+            if (!passed) allPassed = false;
+        }
+    }
+
+    // L3: body path
+    if (assertSpec.body) {
+        for (const [path, expected] of Object.entries(assertSpec.body)) {
+            const actual = getByPath(response.data, path);
+            const passed = matchValue(actual, expected);
+            checks.push({ name: `Body ${path} = ${JSON.stringify(expected)}`, level: 3, actual, expected, passed });
+            if (!passed) allPassed = false;
+        }
+    }
+
+    // L4: response time
+    if (assertSpec.responseTime !== undefined) {
+        const total = response.config?.metadata?.total ?? 0;
+        const expected = assertSpec.responseTime;
+        const passed = total < expected;
+        checks.push({ name: `Response time < ${expected}ms`, level: 4, actual: total, expected, passed });
+        if (!passed) allPassed = false;
+    }
+
+    return { passed: allPassed, checks };
+}
+
+/**
+ * 路径取值（点号访问嵌套对象）
+ */
+function getByPath(obj, path) {
+    return String(path).split('.').reduce((o, k) => o?.[k], obj);
+}
+
+/**
+ * 操作符匹配
+ * @param {any} actual
+ * @param {any} expected - 可以是值 / { $gt: n } / { $lt: n } / { $contains: 'x' } / { $regex: 'p' }
+ */
+function matchValue(actual, expected) {
+    if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+        if ('$gt' in expected && actual > expected.$gt) return true;
+        if ('$lt' in expected && actual < expected.$lt) return true;
+        if ('$gte' in expected && actual >= expected.$gte) return true;
+        if ('$lte' in expected && actual <= expected.$lte) return true;
+        if ('$contains' in expected && String(actual ?? '').includes(expected.$contains)) return true;
+        if ('$regex' in expected && new RegExp(expected.$regex).test(String(actual ?? ''))) return true;
+        if ('$in' in expected && Array.isArray(expected.$in) && expected.$in.includes(actual)) return true;
+        return false;
+    }
+    return actual === expected;
+}
+
+/**
+ * 执行 apiCall step（v3 走法 P：不通过浏览器，走 axios）
+ * @param {ApiCallStep} step
+ * @param {object} ctx - { baseURL, cookies, traceCollector? }
+ * @returns {Promise<{
+ *   name: string, status: 'passed'|'failed', duration: number,
+ *   request: object, response: object,
+ *   assertions: Array, trace: object|null, error: object|null
+ * }>}
+ */
+export async function executeApiCallStep(step, ctx = {}) {
+    const startTime = Date.now();
+    const method = (step.method || 'POST').toUpperCase();
+    const timings = [];
+    const collector = { timings };
+
+    // 1. 构造 axios request：自动共享 context.cookies()
+    const cookieHeader = buildCookieHeader(ctx.cookies ?? [], ctx.baseURL);
+    const request = axios.create({
+        baseURL: ctx.baseURL,
+        headers: {
+            Cookie: cookieHeader,
+            'Content-Type': 'application/json',
+            ...step.headers
+        },
+        // 让 axios 接受任意状态码（不抛错）
+        validateStatus: () => true
+    });
+
+    // 2. ★ axios interceptor（PR #5 + PR #8）
+    const interceptor = createTimingsInterceptor(collector);
+    request.interceptors.request.use(interceptor.request);
+    request.interceptors.response.use(interceptor.response, interceptor.error);
+
+    // 3. 发请求
+    let response;
+    let error = null;
+    try {
+        response = await request({
+            method,
+            url: step.url,
+            data: step.body
+        });
+    } catch (e) {
+        error = {
+            message: e.message ?? String(e),
+            code: e.code ?? null
+        };
+    }
+
+    const duration = Date.now() - startTime;
+    const status = response?.status ?? 0;
+
+    // 4. ★ 断言（PR #8 L1-L4）
+    let assertionResults = [];
+    let passed = error == null && status >= 200 && status < 300;  // 默认通过 = 2xx
+    if (step.assert && response) {
+        const assertResult = assertApiResponse(response, step.assert);
+        assertionResults = assertResult.checks;
+        if (!assertResult.passed) {
+            passed = false;
+        }
+    }
+
+    // 5. ★ 构造返回值（脱敏 + 统一 schema）
+    const safeResponse = response ? {
+        status: response.status,
+        statusText: response.statusText,
+        duration: response.config?.metadata?.total ?? 0,
+        headers: redact(response.headers ?? {}),
+        body: redact(response.data)
+    } : null;
+
+    return {
+        name: step.name ?? `${method} ${step.url}`,
+        status: passed ? 'passed' : 'failed',
+        duration,
+        request: {
+            method,
+            url: step.url,
+            headers: redact(step.headers ?? {}),
+            body: redact(step.body)
+        },
+        response: safeResponse,
+        assertions: assertionResults,
+        trace: step.captureTrace ? { timings: collector.timings } : null,
+        error
+    };
+}

package/opencode-extension/skills/local-browser-test/lib/browser-engine.js

@@ -16,6 +16,8 @@ import { AntAdapter } from "./ant-adapter.js";
 import { createExpect, locator as expectLocator, validation as expectValidation, url as expectUrl, api as expectApi } from "./expect.js";
 import { getBrowserConfigFromProcess } from "./cdp-browser-config.js";
 import { decryptAllPasswords } from "./decrypt-passwords.js";
+// ★ PR #6 v3: 重试 + flaky + 写操作禁重试
+import { RetryPolicy, retryPolicyFromPlan } from "./retry-policy.js";
 import { existsSync, readFileSync, writeFileSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
@@ -3246,24 +3248,83 @@ export class BrowserEngine {
 
     async _rawScript(step) {
         var target = await this._getTargetFrame(step);
+        // ★ PR #4 v3 修复：抽 helper 便于测试 + 支持 step.codeFile + 静态扫描 Node-only API
+        var resolve = require('./raw-script-helpers.js');
+        var codeResult = resolve.resolveCodeFile(step, process.cwd());
+        if (codeResult.error) {
+            return resolve.buildErrorResult(codeResult.reason);
+        }
+        var code = codeResult.code;
+
+        // 静态扫描：检测常见 Node-only API（浏览器侧不可用）
+        var nodeOnlyHints = resolve.detectNodeOnlyApi(code);
+        if (nodeOnlyHints.length > 0) {
+            return resolve.buildErrorResult(
+                'rawScript 检测到 Node-only API:\n  - ' + nodeOnlyHints.join('\n  - ') +
+                '\n\n  → 修复：改用浏览器侧 API（document.* / localStorage / fetch 等）\n' +
+                '  → 详见 SKILL.md > ## rawScript 可用 API'
+            );
+        }
+
         var fn;
-        try { fn = new Function('page', 'frame', 'params', 'browser', 'return (' + step.code + ')(page, frame, params, browser)'); }
-        catch (e) { return { type: 'rawScript', passed: false, reason: 'script compile error: ' + e.message, status: 'FAIL' }; }
+        try {
+            // rawScript 签名：async (page, frame, params, browser) => { return { passed, ... } }
+            fn = new Function('page', 'frame', 'params', 'browser', 'return (async () => { ' + code + ' })()');
+        } catch (e) {
+            return resolve.buildErrorResult('script compile error: ' + e.message + '\n  → 详见 SKILL.md > ## rawScript 可用 API');
+        }
         try {
             var result = await fn(this.page, target.frame, step.params || {}, this.browser);
             return Object.assign({ type: 'rawScript' }, result);
-        } catch (e) { return { type: 'rawScript', passed: false, reason: 'script execution error: ' + e.message, status: 'FAIL' }; }
+        } catch (e) {
+            return resolve.buildErrorResult('script execution error: ' + e.message + '\n  → 详见 SKILL.md > ## rawScript 可用 API');
+        }
     }
 
     async _apiCall(step) {
-        var method = (step.method || 'POST').toUpperCase();
-        var response = await this.page.evaluate(async function(opts) {
-            var res = await fetch(opts.url, { method: opts.method, headers: Object.assign({ 'Content-Type': 'application/json' }, opts.headers || {}), body: opts.body ? JSON.stringify(opts.body) : undefined });
-            var data = await res.text();
-            try { return { status: res.status, data: JSON.parse(data) }; } catch(e) { return { status: res.status, data: data }; }
-        }, { method: method, url: step.url, body: step.body, headers: step.headers });
-        var passed = response.status >= 200 && response.status < 300;
-        return { type: 'apiCall', status: response.status, data: typeof response.data === 'string' ? response.data.slice(0, 500) : response.data, passed: passed, reason: passed ? null : 'API returned ' + response.status };
+        // ★ PR #8 v3: 走法 P — 增强 apiCall step（不通过浏览器，走 axios）
+        //   自动从 context.cookies() 共享 Cookie
+        //   6 个新字段：assert / captureTrace / noRetry / strategy / headers / tags
+        try {
+            // 从 currentPage 拿 cookies
+            let cookies = [];
+            try {
+                if (this.page && this.page.browserContext) {
+                    cookies = await this.page.browserContext().cookies();
+                }
+            } catch (e) {
+                // 跨域 iframe / about:blank 等忽略
+            }
+
+            // 调新 executor
+            const { executeApiCallStep } = await import('./api-call-executor.js');
+            const baseURL = this._baseURL || (this.page ? (new URL(this.page.url()).origin) : '');
+            const result = await executeApiCallStep(step, {
+                baseURL,
+                cookies
+            });
+
+            return {
+                type: 'apiCall',
+                passed: result.status === 'passed',
+                name: result.name,
+                status: result.response?.status ?? 0,
+                duration: result.duration,
+                request: result.request,
+                response: result.response,
+                assertions: result.assertions,
+                trace: result.trace,
+                error: result.error,
+                reason: result.status === 'passed' ? null : (result.error?.message ?? `API returned ${result.response?.status}`)
+            };
+        } catch (e) {
+            return {
+                type: 'apiCall',
+                passed: false,
+                reason: 'apiCall 执行失败: ' + e.message + '\n  → 详见 SKILL.md > ## apiCall step',
+                status: 'FAIL'
+            };
+        }
     }
 
     async _switchPage(step) {
@@ -3356,21 +3417,34 @@ export class BrowserEngine {
 
                 if (stepResult.status === "FAIL") {
                     allPassed = false;
-                    const recovery = testCase.recovery || {};
-                    const maxRetries = recovery.maxRetriesPerStep ?? 0;
-                    for (let retry = 0; retry < maxRetries; retry++) {
-                        const retryResult = await this.executeStep(step, context);
+                    // ★ PR #6 v3：用 RetryPolicy 替换简单 retry 逻辑
+                    const policy = retryPolicyFromPlan(testCase.recovery);
+                    if (policy.isStepRetryable(step)) {
+                        const maxRetries = policy.maxRetriesPerStep;
+                        for (let retry = 0; retry < maxRetries; retry++) {
+                            const retryResult = await this.executeStep(step, context);
+                            rowResults.push({
+                                ...retryResult,
+                                stepIndex,
+                                dataRowIndex,
+                                retry: retry + 1,
+                            });
+                            results.push(rowResults[rowResults.length - 1]);
+                            if (retryResult.status === "PASS") {
+                                allPassed = true;
+                                break;
+                            }
+                        }
+                    } else {
+                        // 写操作禁重试：标记 step 为 noRetry
                         rowResults.push({
-                            ...retryResult,
+                            ...stepResult,
                             stepIndex,
                             dataRowIndex,
-                            retry: retry + 1,
+                            noRetry: true,
+                            reason: (stepResult.reason ?? 'fail') + ' (写操作禁重试)'
                         });
                         results.push(rowResults[rowResults.length - 1]);
-                        if (retryResult.status === "PASS") {
-                            allPassed = true;
-                            break;
-                        }
                     }
                     if (!allPassed && step.continueOnFail === false) break;
                 }

package/opencode-extension/skills/local-browser-test/lib/config-loader.js

@@ -0,0 +1,104 @@
+/**
+ * YAML 配置加载链
+ *
+ * 加载优先级：
+ *   process.env > --config <path> > --env <name> 隐式加载 .lbt/config.<env>.yaml
+ *   > 内置默认
+ *
+ * 支持 ${ENV_VAR} 占位符（CI 注入凭据用）
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+
+const DEFAULTS = {
+  app: { baseURL: 'http://localhost:3000', timeout: 30000 },
+  auth: { type: 'bearer', storageState: null },
+  projects: [],
+  retry: { maxRetries: 0, maxRetriesPerStep: 2, flakyThreshold: 5, noRetryActions: true },
+  report: { retainRuns: 30, retainDays: 7, retainFailedForever: true }
+};
+
+/**
+ * 加载配置
+ * @param {object} args - 解析后的 CLI args
+ * @returns {object} 完整配置
+ */
+export function loadConfig(args = {}) {
+  // 1. 决定配置文件路径
+  const configPath = resolveConfigPath(args);
+
+  // 2. 加载文件（不存在用默认）
+  let fileConfig = {};
+  if (configPath && fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    fileConfig = YAML.parse(raw) || {};
+  }
+
+  // 3. 合并 + env 覆盖
+  const merged = deepMerge(structuredClone(DEFAULTS), fileConfig);
+  const resolved = processEnvReferences(merged, process.env);
+
+  // 4. 校验
+  validateConfig(resolved);
+
+  return resolved;
+}
+
+function resolveConfigPath(args) {
+  if (args.config) return path.isAbsolute(args.config) ? args.config : path.join(process.cwd(), args.config);
+  if (args.env) {
+    return path.join(process.cwd(), '.lbt', `config.${args.env}.yaml`);
+  }
+  // 默认：cwd/.lbt/config.yaml
+  return path.join(process.cwd(), '.lbt', 'config.yaml');
+}
+
+function deepMerge(target, source) {
+  if (!source || typeof source !== 'object') return target;
+  const out = { ...target };
+  for (const [k, v] of Object.entries(source)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      out[k] = deepMerge(out[k] || {}, v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function processEnvReferences(obj, env) {
+  if (typeof obj === 'string') {
+    return obj.replace(/\$\{(\w+)\}/g, (_, key) => {
+      const val = env[key];
+      if (val === undefined) {
+        // 保留原占位符（让用户知道哪个 env 缺失）
+        return `\${${key}}`;
+      }
+      return val;
+    });
+  }
+  if (Array.isArray(obj)) return obj.map(v => processEnvReferences(v, env));
+  if (obj && typeof obj === 'object') {
+    return Object.fromEntries(
+      Object.entries(obj).map(([k, v]) => [k, processEnvReferences(v, env)])
+    );
+  }
+  return obj;
+}
+
+function validateConfig(config) {
+  if (!config.app?.baseURL) {
+    throw new Error(
+      'config.app.baseURL 缺失\n' +
+      '  → 修复：cp .lbt/config.yaml.example .lbt/config.yaml 并填值'
+    );
+  }
+  if (config.auth?.password && !config.auth.password.includes('${') && !process.env[config.auth.password]) {
+    console.warn(
+      '⚠️  config.auth.password 看起来是明文。' +
+      '建议改用 ${PASSWORD} 走环境变量。'
+    );
+  }
+}

package/opencode-extension/skills/local-browser-test/lib/console-archiver.js

@@ -0,0 +1,100 @@
+/**
+ * console.log/warn/error 自动归档（PR #5）
+ *
+ * 用 puppeteer page.on('console') + page.on('pageerror') 收集浏览器侧所有控制台输出 + 页面错误，
+ * 落盘 console.log（含时间戳 + 类型）。
+ *
+ * 与 PR #1 redact 集成：落盘前 redact 敏感字段（避免 password / token 泄漏到 log）。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REDACT_KEYS = ['password', 'verifyCode', 'token', 'apiKey', 'credentials', 'authorization'];
+
+function redactText(text) {
+  if (typeof text !== 'string') return text;
+  let result = text;
+  // URL query 参数 / 括号内 / 空白分隔
+  // 注：要求 key 后面跟 =value，前缀可有可无（处理 stack trace 中的 (token=xxx)）
+  result = result.replace(/(\?|&|\(|\s|=|^)(token|password|verifyCode|code|apiKey|secret)=([^&\s)]+)/g,
+    (m, p1, p2, p3) => `${p1}${p2}=***`);
+  // Bearer token
+  result = result.replace(/(Bearer\s+)[A-Za-z0-9\-._~+/]+=*/g, '$1***');
+  return result;
+}
+
+export class ConsoleArchiver {
+    /**
+     * @param {string} runDir
+     */
+    constructor(runDir) {
+        this.runDir = runDir;
+        this.messages = [];
+        this.collecting = false;
+    }
+
+    /**
+     * 启动 console 监听
+     * @param {import('puppeteer').Page} page
+     */
+    async start(page) {
+        if (this.collecting) return;
+        try {
+            page.on('console', (msg) => {
+                const text = msg.text();
+                const type = msg.type();
+                this.messages.push({
+                    type,
+                    text: redactText(text),
+                    time: new Date().toISOString(),
+                    location: msg.location() ?? null
+                });
+            });
+            page.on('pageerror', (err) => {
+                this.messages.push({
+                    type: 'error',
+                    text: redactText(err.message ?? String(err)),
+                    time: new Date().toISOString(),
+                    location: null,
+                    stack: redactText(err.stack ?? '')
+                });
+            });
+            this.collecting = true;
+        } catch (e) {
+            console.warn(`⚠️  ConsoleArchiver.start 失败: ${e.message}`);
+        }
+    }
+
+    /**
+     * 停止并落盘 console.log
+     * @returns {Promise<string|null>}
+     */
+    async stop() {
+        // 注：不做 collecting 检查（测试场景可能直接落盘构造的 messages）
+        try {
+            fs.mkdirSync(this.runDir, { recursive: true });
+            const content = this.messages
+                .map((m) => {
+                    const loc = m.location ? ` (${m.location.url ?? '?'}:${m.location.lineNumber ?? '?'})` : '';
+                    // ★ 落盘前 redact（避免 token / Bearer 泄漏到 log）
+                    return `[${m.time}] [${m.type.toUpperCase()}]${loc} ${redactText(m.text)}${m.stack ? '\n' + redactText(m.stack) : ''}`;
+                })
+                .join('\n');
+            const logPath = path.join(this.runDir, 'console.log');
+            fs.writeFileSync(logPath, content);
+            this.collecting = false;
+            return logPath;
+        } catch (e) {
+            console.warn(`⚠️  ConsoleArchiver 落盘失败: ${e.message}`);
+            return null;
+        }
+    }
+
+    /**
+     * 收集的 message 数量（测试用）
+     */
+    get count() {
+        return this.messages.length;
+    }
+}

package/opencode-extension/skills/local-browser-test/lib/global-setup.js

@@ -0,0 +1,73 @@
+/**
+ * globalSetup: 两种自动登录模式
+ *
+ * 模式 1（接管浏览器）：用户已在浏览器里登录 → 直接导出 cookies + localStorage
+ * 模式 2（自动填表）：调 decrypt-passwords.js + 填表 + 拿 cookie
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+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(path.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);
+}