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

package/opencode-extension/skills/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/opencode-extension/skills/local-browser-test/lib/html-reporter.js

@@ -0,0 +1,425 @@
+/**
+ * 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: "🅰️"
+};
+
+/** 归一化单条运行结果（兼容新旧格式） */
+function normalizeRunResult(r) {
+  const s = r.summary ?? r.stats ?? {};
+  return {
+    ...r,
+    startedAt: r.startTime ?? r.startedAt,
+    durationMs: parseInt(r.duration ?? "0", 10) || r.durationMs || 0,
+    stats: {
+      total: parseInt(s.total ?? "0", 10),
+      passed: parseInt(s.passed ?? "0", 10),
+      failed: parseInt(s.failed ?? "0", 10),
+      skipped: parseInt(s.skipped ?? "0", 10),
+    },
+    cases: r.steps?.map((step, i) => ({
+      name: step.step ?? `步骤 ${i+1}`,
+      status: step.status === "PASS" ? "passed" : "failed",
+      duration: parseInt(step.duration ?? "0", 10),
+      durationMs: parseInt(step.duration ?? "0", 10),
+      error: step.error || (step.status !== "PASS" ? JSON.stringify(step) : undefined),
+      screenshot: step.filepath,
+      step,
+    })) ?? r.cases ?? [],
+    executor: r.browserInfo ? {
+      version: r.executor?.version ?? "-",
+      browserVersion: `${r.browserInfo.browserName ?? ""} ${r.browserInfo.browserVersion ?? ""}`.trim() || "-",
+    } : r.executor,
+  };
+}
+
+const STYLE = `
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  background: #f0f2f5; color: #1d1d1f; padding: 0;
+}
+.page { max-width: 1100px; margin: 0 auto; padding: 32px 24px; }
+h1 { font-size: 24px; font-weight: 700; color: #1d1d1f; margin-bottom: 24px; display: flex; align-items: center; gap: 10px; }
+h2 { font-size: 18px; font-weight: 600; color: #1d1d1f; margin: 28px 0 16px; }
+.card {
+  background: #fff; border-radius: 12px; box-shadow: 0 1px 3px rgba(0,0,0,.08), 0 1px 2px rgba(0,0,0,.06);
+  padding: 20px 24px; margin-bottom: 16px;
+}
+.badge {
+  display: inline-flex; align-items: center; gap: 4px;
+  padding: 2px 10px; border-radius: 100px; font-size: 13px; font-weight: 600;
+}
+.badge-pass { background: #e6f7e6; color: #1a7d1a; }
+.badge-fail { background: #fce8e8; color: #c41d1d; }
+table {
+  width: 100%; border-collapse: collapse; font-size: 14px;
+}
+th {
+  text-align: left; padding: 10px 12px; font-weight: 600; color: #6b7280;
+  border-bottom: 1px solid #e5e7eb; font-size: 13px; text-transform: uppercase; letter-spacing: .03em;
+}
+td { padding: 10px 12px; border-bottom: 1px solid #f3f4f6; }
+tr:last-child td { border-bottom: none; }
+tr:hover td { background: #f9fafb; }
+a { color: #2563eb; text-decoration: none; }
+a:hover { text-decoration: underline; }
+.stat-group { display: flex; gap: 32px; }
+.stat-item { text-align: center; }
+.stat-num { font-size: 28px; font-weight: 700; line-height: 1.2; }
+.stat-label { font-size: 13px; color: #9ca3af; margin-top: 2px; }
+#trend-chart { width: 100%; height: 240px; }
+.filter-bar {
+  display: flex; gap: 12px; align-items: center; flex-wrap: wrap;
+}
+.filter-bar select, .filter-bar input {
+  padding: 6px 12px; border: 1px solid #d1d5db; border-radius: 8px; font-size: 14px;
+  background: #fff; outline: none;
+}
+.filter-bar select:focus, .filter-bar input:focus { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37,99,235,.15); }
+.row-hidden { display: none !important; }
+.back-link { display: inline-flex; align-items: center; gap: 4px; color: #6b7280; font-size: 14px; margin-top: 24px; }
+.back-link:hover { color: #2563eb; }
+.step-table td:first-child { color: #9ca3af; font-size: 13px; }
+.detail-row { cursor: pointer; }
+.detail-row td:last-child { text-align: right; color: #2563eb; font-size: 13px; }
+.detail-expanded { background: #f9fafb; }
+.detail-expanded td { padding: 0; }
+.detail-expanded pre {
+  margin: 0; padding: 12px 16px; font-size: 13px; line-height: 1.6;
+  background: #1d1d1f; color: #e5e7eb; border-radius: 0 0 8px 8px; overflow-x: auto;
+  max-height: 300px;
+}
+.screenshot-link { display: inline-block; margin-top: 8px; }
+.screenshot-link img { max-width: 100%; border-radius: 8px; border: 1px solid #e5e7eb; }
+`;
+
+function renderStat(num, label, cls = "") {
+  return `<div class="stat-item"><div class="stat-num ${cls}">${num}</div><div class="stat-label">${label}</div></div>`;
+}
+
+/** 收集 runs 中去重的字段值，生成 <option> HTML */
+function collectOpts(runs, field) {
+  const set = new Set();
+  for (const r of runs) {
+    const v = r[field];
+    if (v && v !== "-") set.add(v);
+  }
+  return Array.from(set).sort().map(v => `<option value="${v.replace(/"/g, "&quot;")}">${v}</option>`).join("\n");
+}
+
+/**
+ * 重新生成入口 index.html（读取所有 runs/ 重建）
+ * @param {string} reportsDir
+ */
+export function initIndexHtml(reportsDir) {
+  const indexPath = path.join(reportsDir, "index.html");
+  const runsDir = path.join(reportsDir, "runs");
+
+  let allRuns = [];
+  if (fs.existsSync(runsDir)) {
+    allRuns = fs.readdirSync(runsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => {
+        const resultPath = path.join(runsDir, d.name, "result.json");
+        try {
+          const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8"));
+          return normalizeRunResult(raw);
+        }
+        catch { return null; }
+      })
+      .filter(Boolean)
+      .sort((a, b) => (b.startedAt ?? "").localeCompare(a.startedAt ?? ""))
+      .slice(0, 20);
+  }
+
+  const passed = allRuns.filter(r => (r.stats?.failed ?? 0) === 0).length;
+  const failed = allRuns.filter(r => (r.stats?.failed ?? 0) > 0).length;
+  const rows = allRuns.map(r => renderRunCard(r)).join("\n");
+
+  const html = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>szcd local-browser-test 报告</title>
+  <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
+  <style>${STYLE}</style>
+</head>
+<body>
+  <div class="page">
+    <h1>
+      <span style="background:linear-gradient(135deg,#2563eb,#7c3aed);width:32px;height:32px;border-radius:8px;display:inline-flex;align-items:center;justify-content:center;color:#fff;font-size:18px">🧪</span>
+      测试报告
+    </h1>
+
+    <div class="card">
+      <h2>趋势</h2>
+      <div id="trend-chart"></div>
+    </div>
+
+    <div class="card">
+      <div class="stat-group">
+        ${renderStat(allRuns.length, "总运行")}
+        ${renderStat(passed, "通过", "pass")}
+        ${renderStat(failed, "失败", "fail")}
+      </div>
+    </div>
+
+    <div class="card">
+      <div class="filter-bar">
+        <select id="filter-status"><option value="">所有状态</option><option value="pass">通过</option><option value="fail">失败</option></select>
+        <select id="filter-tag"><option value="">所有 tag</option>${collectOpts(allRuns, 'tag')}</select>
+        <select id="filter-project"><option value="">所有 project</option>${collectOpts(allRuns, 'project')}</select>
+        <select id="filter-branch"><option value="">所有 branch</option>${collectOpts(allRuns, 'branch')}</select>
+        <input id="filter-text" type="search" placeholder="搜索计划名…">
+        <span id="filter-count" style="color:#9ca3af;font-size:14px;margin-left:auto"></span>
+      </div>
+    </div>
+
+    <div class="card" style="padding:0 24px">
+      <table>
+        <thead><tr>
+          <th style="width:160px">时间</th>
+          <th>计划</th>
+          <th style="width:100px">结果</th>
+          <th style="width:80px">耗时</th>
+          <th style="width:60px"></th>
+        </tr></thead>
+        <tbody id="runs-tbody">
+${rows}
+        </tbody>
+      </table>
+    </div>
+
+    <div style="margin-top:24px;font-size:12px;color:#9ca3af;text-align:center">
+      保留最近 30 次 / 7 天 · 失败永久保留
+    </div>
+  </div>
+
+  <script>
+  const trendData = ${JSON.stringify(allRuns.map(r => ({
+    date: (r.startedAt ?? "").slice(0, 10),
+    passed: r.stats?.passed ?? 0,
+    failed: r.stats?.failed ?? 0,
+    total: r.stats?.total ?? 0,
+  })).reverse())};
+
+  function renderTrend() {
+    if (typeof echarts === "undefined") return;
+    const byDate = {};
+    for (const d of trendData) {
+      if (!d.date) continue;
+      if (!byDate[d.date]) byDate[d.date] = { passed: 0, failed: 0 };
+      byDate[d.date].passed += d.passed;
+      byDate[d.date].failed += d.failed;
+    }
+    const dates = Object.keys(byDate).sort().slice(-7);
+    const chart = echarts.init(document.getElementById("trend-chart"));
+    chart.setOption({
+      tooltip: { trigger: "axis", axisPointer: { type: "shadow" } },
+      grid: { left: "3%", right: "4%", bottom: "3%", top: "5%", containLabel: true },
+      xAxis: { type: "category", data: dates, axisLabel: { fontSize: 12 } },
+      yAxis: { type: "value", min: 0, splitLine: { lineStyle: { color: "#f3f4f6" } } },
+      series: [
+        { name: "通过", type: "bar", stack: "total", color: "#22c55e", barWidth: "40%",
+          itemStyle: { borderRadius: [4, 4, 0, 0] },
+          data: dates.map(d => byDate[d].passed) },
+        { name: "失败", type: "bar", stack: "total", color: "#ef4444",
+          itemStyle: { borderRadius: [4, 4, 0, 0] },
+          data: dates.map(d => byDate[d].failed) }
+      ]
+    });
+    window.addEventListener("resize", () => chart.resize());
+  }
+  renderTrend();
+
+  function doFilter() {
+    const status = document.getElementById("filter-status").value;
+    const tag = document.getElementById("filter-tag").value;
+    const project = document.getElementById("filter-project").value;
+    const branch = document.getElementById("filter-branch").value;
+    const text = document.getElementById("filter-text").value.toLowerCase();
+    let visible = 0, totalPassed = 0, totalFailed = 0;
+    document.querySelectorAll("#runs-tbody tr").forEach(tr => {
+      const s = tr.dataset.status || "";
+      const desc = (tr.dataset.desc || "").toLowerCase();
+      const show =
+        (!status || s === status) &&
+        (!tag || tr.dataset.tag === tag) &&
+        (!project || tr.dataset.project === project) &&
+        (!branch || tr.dataset.branch === branch) &&
+        (!text || desc.includes(text));
+      tr.classList.toggle("row-hidden", !show);
+      if (show) {
+        visible++;
+        if (s === "pass") totalPassed++;
+        else if (s === "fail") totalFailed++;
+      }
+    });
+    document.getElementById("filter-count").textContent = visible + " / " + document.querySelectorAll("#runs-tbody tr").length;
+  }
+  document.getElementById("filter-status").addEventListener("change", doFilter);
+  document.getElementById("filter-tag").addEventListener("change", doFilter);
+  document.getElementById("filter-project").addEventListener("change", doFilter);
+  document.getElementById("filter-branch").addEventListener("change", doFilter);
+  document.getElementById("filter-text").addEventListener("input", doFilter);
+  doFilter();
+  </script>
+</body>
+</html>`;
+  fs.writeFileSync(indexPath, html);
+}
+
+/**
+ * 在入口 index.html 表格里追加一行（按时间倒序：最新在最上面）
+ * @param {object} result
+ * @param {string} indexPath
+ */
+export function appendRunCardToIndex(_result, indexPath) {
+  // 重建整个入口（从 runs/ 读取所有历史）
+  initIndexHtml(path.dirname(indexPath));
+}
+
+function renderRunCard(result) {
+  const s = result.stats ?? {};
+  const failed = (s.failed ?? 0) > 0;
+  const cls = failed ? "fail" : "pass";
+  const badgeCls = failed ? "badge-fail" : "badge-pass";
+  const badgeText = failed ? "失败" : "通过";
+  const time = (result.startedAt ?? "").slice(0, 19).replace("T", " ");
+  const dur = ((result.durationMs ?? 0) / 1000).toFixed(1);
+  const desc = result.description || result.planId || "ui";
+  const esc = (v) => (v ?? "").replace(/"/g, "&quot;");
+  return `    <tr data-status="${cls}" data-desc="${esc(desc + " " + (result.planId ?? ""))}"
+        data-tag="${esc(result.tag)}" data-project="${esc(result.project)}" data-branch="${esc(result.branch)}">
+      <td style="white-space:nowrap;color:#6b7280">${time || "-"}</td>
+      <td style="font-weight:500">${desc}</td>
+      <td><span class="badge ${badgeCls}">${badgeText} ${s.passed ?? 0}/${s.total ?? 0}</span></td>
+      <td style="color:#6b7280">${dur}s</td>
+      <td><a href="runs/${result.runId}/index.html" style="font-size:13px">详情 →</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 (let i = 0; i < result.cases.length; i++) {
+      const c = result.cases[i];
+      if (c.screenshot && fs.existsSync(c.screenshot)) {
+        fs.mkdirSync(shotsDir, { recursive: true });
+        const base = (c.name ?? "unknown").replace(/[^a-z0-9_-]/gi, "-");
+        const safeName = `${String(i + 1).padStart(2, "0")}-${base}`;
+        fs.copyFileSync(c.screenshot, path.join(shotsDir, `${safeName}.png`));
+      }
+    }
+  }
+}
+
+function renderRunDetail(result) {
+  const cases = result.cases ?? [];
+  const s = result.stats ?? {};
+  const failedCases = cases.filter((c) => c.status === "failed");
+  const title = `Run${result.planId ? " " + result.planId : ""} @ ${(result.startedAt ?? "").slice(0, 19).replace("T", " ")}`;
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title}</title>
+  <style>${STYLE}
+.detail-expanded pre { display: none; }
+.detail-expanded.open pre { display: block; }
+.detail-expanded td { padding: 0; }
+.detail-expanded .expander { padding: 10px 12px; display: flex; justify-content: space-between; align-items: center; cursor: pointer; }
+.detail-expanded .expander:hover { background: #f3f4f6; }
+.detail-expanded .arrow { transition: transform .2s; font-size: 12px; color: #9ca3af; }
+.detail-expanded.open .arrow { transform: rotate(90deg); }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <a href="../../index.html" class="back-link">← 返回列表</a>
+
+    <h1 style="margin-top:16px">${result.description || result.planId || "运行详情"}</h1>
+
+    <p style="color:#6b7280;font-size:14px;margin-bottom:20px">
+      ${result.runId ? `<code style="background:#f3f4f6;padding:2px 6px;border-radius:4px;font-size:12px">${result.runId}</code>` : ""}
+      ${result.startedAt ? ` &middot; ${result.startedAt.slice(0, 19).replace("T", " ")}` : ""}
+      ${result.mode ? ` &middot; ${result.mode}` : ""}
+      ${result.browserInfo?.currentUrl ? ` &middot; <a href="${result.browserInfo.currentUrl}" target="_blank">${result.browserInfo.currentUrl}</a>` : ""}
+    </p>
+
+    <div class="card">
+      <div class="stat-group">
+        ${renderStat(s.total ?? 0, "总步骤")}
+        ${renderStat(s.passed ?? 0, "通过", "pass")}
+        ${renderStat(s.failed ?? 0, "失败", "fail")}
+        ${renderStat(((result.durationMs ?? 0) / 1000).toFixed(1) + "s", "耗时")}
+      </div>
+    </div>
+
+    <div class="card" style="padding:0 24px">
+      <table class="step-table">
+        <thead><tr>
+          <th style="width:40px">#</th>
+          <th>步骤</th>
+          <th style="width:100px">状态</th>
+          <th style="width:80px">耗时</th>
+          <th style="width:auto">结果</th>
+        </tr></thead>
+        <tbody>
+          ${cases.map((c, i) => {
+            const isFailed = c.status === "failed";
+            const badgeCls = isFailed ? "badge-fail" : "badge-pass";
+            const badgeText = isFailed ? "✗ 失败" : "✓ 通过";
+            const hasDetail = c.error || c.screenshot;
+            return `<tr class="${hasDetail ? "detail-row" : ""}" onclick="${hasDetail ? `this.nextElementSibling.classList.toggle('open')` : ""}">
+              <td>${i + 1}</td>
+              <td style="font-weight:500">${c.name}</td>
+              <td><span class="badge ${badgeCls}">${badgeText}</span></td>
+              <td style="color:#6b7280">${c.durationMs ?? c.duration ?? 0}ms</td>
+              <td style="color:#6b7280;font-size:13px;max-width:350px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${c.result ?? ""}</td>
+            </tr>
+            ${hasDetail ? `<tr class="detail-expanded${isFailed ? " open" : ""}">
+              <td colspan="5">
+                <div class="expander" onclick="this.parentElement.classList.toggle('open');event.stopPropagation()">
+                  <span style="font-weight:500;font-size:13px">${isFailed ? "❌ 错误详情" : "📎 详情"}</span>
+                  <span class="arrow">▶</span>
+                </div>
+                <pre>${(c.error || "").slice(0, 3000)}</pre>
+                ${c.screenshot ? (() => { const base = (c.name ?? "unknown").replace(/[^a-z0-9_-]/gi, "-"); const sn = `${String(i + 1).padStart(2, "0")}-${base}`; return `<div style="padding:0 16px 12px"><a href="screenshots/${sn}.png" target="_blank" class="screenshot-link"><img src="screenshots/${sn}.png" alt="screenshot"></a></div>`; })() : ""}
+              </td>
+            </tr>` : ""}`;
+          }).join("\n")}
+        </tbody>
+      </table>
+    </div>
+
+    <p class="back-link" style="margin-top:32px"><a href="../../index.html">← 返回列表</a></p>
+  </div>
+</body>
+</html>`;
+}

package/opencode-extension/skills/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/opencode-extension/skills/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'
+  };
+}