covgate 0.2.3 → 0.3.1

package/README.md

@@ -2,7 +2,39 @@
 
 > 面向 AI 编码工作流的覆盖率门禁：**客户端必须 100%，服务端至少 95%；无法覆盖的代码必须写明原因才能豁免。**
 
-CovGate 是一个零依赖的 Node.js CLI。它不产生覆盖率，而是把测试、覆盖率报告、源码范围、豁免说明和阈值合成一道**可机器执行、可审计、可进 CI 的门禁**。
+CovGate 是一个零依赖的 Node.js 工具。它不产生覆盖率，而是把测试、覆盖率报告、源码范围、豁免说明和阈值合成一道**可机器执行、可审计、可进 CI 的门禁**；同时提供本地可视化工作台和 HTML 覆盖率查看页。
+
+## 可视化工作台
+
+在项目根目录运行：
+
+```bash
+npx --no-install covgate ui
+```
+
+默认打开 `http://127.0.0.1:4318`，也可以指定项目、端口或关闭自动打开浏览器：
+
+```bash
+npx --no-install covgate ui --root D:/Projects/my-app --port 4319 --no-open
+```
+
+![CovGate 可视化工作台](docs/ui-viewer.png)
+
+运行后在工具内直接查看报告：
+
+![CovGate 工作台内嵌覆盖率报告](docs/ui-result.png)
+
+工作台支持：
+
+- 指定客户端、服务端源码路径，路径有自动检测的建议列表；
+- 从项目 `package.json` 脚本中**下拉选择测试命令**，不需要手敲；
+- 单独指定客户端/服务端命令，自动生成临时配置并运行；
+- 工具内嵌覆盖率报告：左侧文件列表，中间源码，绿色已覆盖、白色未覆盖；
+- 运行前检查测试文件；没有测试时禁用运行，并提供可复制的 **AI 补测任务**，避免生成空报告；
+- 测试命令失败或没有生成报告时，直接显示日志和原因，不展示空结果页；
+- 不覆盖项目已有的 `covgate.config.json`，运行结果仍写入 `.covgate/`。
+
+`covgate ui` 只监听本机回环地址，适合本地使用；CI 和 Agent 仍用 `covgate run`。
 
 ## 为什么需要它
 
@@ -48,7 +80,7 @@ covgate run
 
 ### 从 npm registry 安装（推荐）
 
-包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.2.3**。
+包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.3.1**。
 
 ```bash
 npm install --save-dev covgate
@@ -245,6 +277,10 @@ npx --no-install covgate validate
 | `covgate run` | 执行测试命令，然后检查覆盖率。默认命令。 |
 | `covgate check` | 不执行测试，只检查已有报告。 |
 | `covgate validate` | 只校验配置和排除说明。 |
+| `covgate ui` | 启动本地可视化覆盖率工作台。 |
+| `--root <dir>` | `ui` 的项目根目录，默认当前目录。 |
+| `--port <port>` | `ui` 的本地端口，默认 4318。 |
+| `--no-open` | `ui` 启动后不自动打开浏览器。 |
 | `--config <path>` | 指定配置文件。 |
 | `--scope <name>` | 只检查指定 scope，可重复或逗号分隔。 |
 | `--json` | stdout 只输出 JSON；过程日志走 stderr。 |
@@ -473,7 +509,7 @@ macOS 用 `open .covgate/report.html`，Linux 用 `xdg-open .covgate/report.html
 文本输出示例：
 
 ```text
-CovGate · 覆盖率门禁 v0.2.3
+CovGate · 覆盖率门禁 v0.3.1
 模式 执行测试并检查 · 配置 covgate.config.json · 用时 12.4s
 
 ✗ 客户端 [client/client] 未通过

package/docs/setup.md

@@ -9,7 +9,7 @@ npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.2.3**。
+包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.3.1**。
 
 > `0.0.0-stage` 是 npm 暂存发布产生的占位版本，不会被 `npm install covgate` 选中，可以忽略。
 
@@ -38,7 +38,7 @@ npm 11.19+ 默认不执行依赖的 `postinstall`，会显示类似：
 
 ```text
 npm warn install-scripts 1 package has install scripts not yet covered by allowScripts
-npm warn install-scripts   covgate@0.2.3 (postinstall: node bin/covgate-postinstall.js)
+npm warn install-scripts   covgate@0.3.1 (postinstall: node bin/covgate-postinstall.js)
 ```
 
 因此：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "covgate",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "覆盖率门禁：客户端 100%，服务端至少 95%，安装时自动检测/配置测试框架与 AI 编码代理接入。",
   "type": "module",
   "bin": {

package/src/args.js

@@ -1,6 +1,6 @@
 import { ConfigError } from "./errors.js";
 
-const COMMANDS = new Set(["run", "check", "validate", "setup"]);
+const COMMANDS = new Set(["run", "check", "validate", "setup", "ui"]);
 const NL = String.fromCharCode(10);
 
 export const HELP_TEXT = [
@@ -11,6 +11,7 @@ export const HELP_TEXT = [
   "  covgate run [选项]       执行测试并检查覆盖率（默认命令）",
   "  covgate check [选项]     不执行测试，只检查已有覆盖率报告",
   "  covgate validate [选项]  只校验配置",
+  "  covgate ui [--root <dir>] [--port <port>] 启动可视化覆盖率工作台",
   "",
   "通用选项：",
   "  --config <path>          配置文件路径（默认 ./covgate.config.json）",
@@ -38,6 +39,11 @@ export const HELP_TEXT = [
   "  --force                  覆盖已有配置和 setup 生成的文件",
   "  --dry-run                只打印计划，不写文件、不安装依赖",
   "",
+  "ui 选项：",
+  "  --root <dir>             项目根目录，默认当前目录",
+  "  --port <port>            本地端口，默认 4318",
+  "  --no-open                不自动打开浏览器",
+  "",
   "硬性门槛（配置不可低于）：",
   "  profile=client  行/语句/函数/分支覆盖率必须 100%",
   "  profile=server  行/语句/函数/分支覆盖率必须至少 95%",
@@ -78,7 +84,10 @@ export function parseArgs(argv) {
     profile: undefined,
     source: undefined,
     coverage: undefined,
-    testCommand: undefined
+    testCommand: undefined,
+    root: undefined,
+    port: undefined,
+    noOpen: false
   };
 
   let index = 0;
@@ -92,7 +101,7 @@ export function parseArgs(argv) {
     explicitCommand = true;
     index = 1;
   } else if (argv[0] && !argv[0].startsWith("-")) {
-    throw new ConfigError('未知命令 "' + argv[0] + '"，可用命令：setup、run、check、validate');
+    throw new ConfigError('未知命令 "' + argv[0] + '"，可用命令：setup、run、check、validate、ui');
   }
 
   for (; index < argv.length; index += 1) {
@@ -173,6 +182,15 @@ export function parseArgs(argv) {
       options.coverage = value();
     } else if (key === "--test-command") {
       options.testCommand = value();
+    } else if (key === "--root") {
+      options.root = value();
+    } else if (key === "--port") {
+      options.port = Number(value());
+      if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+        throw new ConfigError("--port 必须是 0 到 65535 之间的整数");
+      }
+    } else if (key === "--no-open") {
+      options.noOpen = true;
     } else if (key === "--help" || key === "-h") {
       options.help = true;
     } else if (key === "--version") {
@@ -186,6 +204,15 @@ export function parseArgs(argv) {
   if (options.command !== "setup" && (options.yes || options.profile || options.source || options.coverage || options.testCommand || options.noAgent || options.noConfig || options.force || options.dryRun || !options.installFramework)) {
     throw new ConfigError("setup 相关选项只能和 covgate setup 一起使用");
   }
+  if (options.command === "ui") {
+    if (options.json || options.configPath || options.scopes.length > 0 || options.noRun || options.noFiles || options.reportDir || options.changed || options.base || options.verbose || options.color !== undefined) {
+      throw new ConfigError("covgate ui 只支持 --root、--port、--no-open 和 --help");
+    }
+    return options;
+  }
+  if (options.root || options.port !== undefined || options.noOpen) {
+    throw new ConfigError("--root、--port、--no-open 只能和 covgate ui 一起使用");
+  }
   if (options.base && !options.changed) {
     throw new ConfigError("--base 必须和 --changed 一起使用");
   }

package/src/cli.js

@@ -24,6 +24,7 @@ import {
 import { printCommandFailure, runScopeCommands } from "./runner.js";
 import { evaluateScope } from "./scope.js";
 import { runSetup } from "./setup/index.js";
+import { openBrowser, startUiServer } from "./ui/server.js";
 import { validateReason } from "./reason.js";
 import {
   formatThreshold,
@@ -124,6 +125,28 @@ async function runSetupCommand(options) {
   }
 }
 
+/**
+ * @param {any} options
+ */
+async function runUiCommand(options) {
+  const root = path.resolve(options.root || process.cwd());
+  try {
+    const ui = await startUiServer({ root, port: options.port ?? 4318 });
+    process.stdout.write("CovGate UI: " + ui.url + String.fromCharCode(10));
+    process.stdout.write("按 Ctrl+C 停止。" + String.fromCharCode(10));
+    if (!options.noOpen) openBrowser(ui.url);
+    const shutdown = async () => {
+      await ui.close().catch(() => {});
+      process.exit(0);
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    return 0;
+  } catch (error) {
+    return printEarlyError(error, false, options.verbose);
+  }
+}
+
 /**
  * @param {any} config
  * @param {any[]} scopes
@@ -487,6 +510,9 @@ export async function main(argv) {
   if (options.command === "setup") {
     return runSetupCommand(options);
   }
+  if (options.command === "ui") {
+    return runUiCommand(options);
+  }
 
   let config;
   let scopes;

package/src/ui/page.html

@@ -0,0 +1,617 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>CovGate 可视化覆盖率工具</title>
+  <style>
+    :root {
+      --bg: #eef3f7;
+      --panel: #ffffff;
+      --ink: #17212b;
+      --muted: #687583;
+      --line: #dfe6ec;
+      --accent: #1473e6;
+      --green: #0f7b44;
+      --green-bg: #e6f7ed;
+      --red: #c53138;
+      --red-bg: #fdeced;
+      --amber: #8a6200;
+      --amber-bg: #fff6d9;
+      --shadow: 0 12px 30px rgba(24, 44, 66, 0.08);
+    }
+    * { box-sizing: border-box; }
+    html, body { margin: 0; height: 100%; }
+    body {
+      font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", sans-serif;
+      background: var(--bg);
+      color: var(--ink);
+    }
+    button, input, select { font: inherit; }
+    button { cursor: pointer; }
+    .topbar {
+      height: 64px;
+      background: #10253a;
+      color: #fff;
+      display: flex;
+      align-items: center;
+      gap: 18px;
+      padding: 0 22px;
+      position: relative;
+      z-index: 2;
+    }
+    .brand { display: flex; align-items: center; gap: 10px; min-width: 210px; }
+    .logo {
+      width: 30px; height: 30px; border-radius: 8px;
+      background: linear-gradient(135deg, #46d39a, #1473e6);
+      display: grid; place-items: center; font-weight: 800; font-size: 13px;
+    }
+    .brand strong { font-size: 15px; letter-spacing: .2px; }
+    .brand span { color: #a9bdce; font-size: 11px; margin-left: 1px; }
+    .project-box { display: flex; align-items: center; gap: 8px; flex: 1; min-width: 0; }
+    .project-box label { color: #9db2c4; font-size: 12px; white-space: nowrap; }
+    .project-box input {
+      min-width: 0; flex: 1; max-width: 660px; height: 34px;
+      border: 1px solid #35506a; border-radius: 7px;
+      background: #19344d; color: #eaf3fb; padding: 0 10px; outline: none;
+      font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 12px;
+    }
+    .project-box input:focus { border-color: #5aa6ff; box-shadow: 0 0 0 3px #1473e633; }
+    .topbar button {
+      height: 34px; border: 1px solid #4a6580; border-radius: 7px;
+      background: #24445f; color: #fff; padding: 0 12px; font-size: 12px;
+    }
+    .topbar button:hover { background: #2d5475; }
+    .layout { display: grid; grid-template-columns: 390px minmax(0, 1fr); height: calc(100vh - 64px); }
+    .panel {
+      overflow: auto; background: #f8fafc; border-right: 1px solid var(--line);
+      padding: 18px;
+    }
+    .panel-intro { margin: 0 0 16px; color: var(--muted); font-size: 12px; line-height: 1.7; }
+    .health {
+      background: #edf6ff; border: 1px solid #cfe3f8; border-radius: 10px;
+      padding: 10px 12px; margin-bottom: 12px; display: grid; gap: 6px; font-size: 11px;
+    }
+    .health-row { display: flex; justify-content: space-between; gap: 10px; color: #4d6b86; }
+    .health-row b { color: #17324a; font-weight: 700; text-align: right; }
+    .health-row b.bad { color: var(--red); }
+    .health-row b.good { color: var(--green); }
+    .health-warn {
+      border: 1px solid #f1d58a; background: #fff8e3; color: #735700;
+      border-radius: 9px; padding: 9px 10px; margin: 0 0 12px; font-size: 11px; line-height: 1.55;
+    }
+    .card {
+      background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
+      padding: 14px; margin-bottom: 12px; box-shadow: 0 2px 5px rgba(24,44,66,.03);
+    }
+    .card-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 12px; }
+    .card-title { display: flex; align-items: center; gap: 8px; font-weight: 700; font-size: 13px; }
+    .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); }
+    .dot.server { background: #8c67d8; }
+    .hint { color: var(--muted); font-size: 11px; }
+    .field { display: flex; flex-direction: column; gap: 5px; margin-bottom: 10px; }
+    .field:last-child { margin-bottom: 0; }
+    .field label { font-size: 11px; color: var(--muted); }
+    .field input, .field select {
+      width: 100%; height: 35px; border: 1px solid var(--line); border-radius: 7px;
+      background: #fff; color: var(--ink); padding: 0 9px; outline: none; font-size: 12px;
+    }
+    .field input:focus, .field select:focus { border-color: var(--accent); box-shadow: 0 0 0 3px #1473e61a; }
+    .field input { font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }
+    .path-grid { display: grid; grid-template-columns: 1fr 94px; gap: 7px; }
+    .config-chip {
+      display: inline-flex; align-items: center; gap: 5px; border-radius: 99px;
+      background: #eef5ff; color: #28639f; padding: 4px 8px; font-size: 10px;
+    }
+    .config-chip.temp { background: var(--amber-bg); color: var(--amber); }
+    .run-button {
+      width: 100%; height: 46px; border: 0; border-radius: 10px;
+      background: linear-gradient(135deg, #1376e8, #0f5dc0); color: #fff;
+      font-weight: 700; font-size: 14px; margin-top: 4px;
+      box-shadow: 0 8px 18px #1473e62e;
+    }
+    .run-button:hover { filter: brightness(1.05); }
+    .run-button:disabled { opacity: .55; cursor: not-allowed; box-shadow: none; }
+    .panel-status { min-height: 18px; margin-top: 10px; font-size: 11px; color: var(--muted); line-height: 1.6; }
+    .panel-status.error { color: var(--red); }
+    .panel-status.ok { color: var(--green); }
+    .workspace { overflow: hidden; display: flex; flex-direction: column; min-width: 0; }
+    .empty {
+      margin: auto; max-width: 540px; text-align: center; padding: 32px;
+    }
+    .empty-mark { width: 64px; height: 64px; margin: 0 auto 18px; border-radius: 18px; background: #dcecfb; color: #1473e6; display: grid; place-items: center; font-size: 26px; }
+    .empty h1 { margin: 0 0 8px; font-size: 22px; letter-spacing: -.3px; }
+    .empty p { color: var(--muted); font-size: 13px; line-height: 1.8; margin: 0; }
+    .empty-actions { display: flex; gap: 8px; justify-content: center; flex-wrap: wrap; margin-top: 16px; }
+    .secondary-btn {
+      height: 38px; border: 1px solid #b9cde2; border-radius: 8px;
+      background: #fff; color: #17324a; padding: 0 14px; font-size: 12px;
+    }
+    .secondary-btn:hover { border-color: var(--accent); color: var(--accent); }
+    .text-btn { border: 0; background: transparent; color: var(--muted); font-size: 11px; padding: 6px; text-decoration: underline; }
+    .text-btn:hover { color: var(--accent); }
+    .run-view { padding: 22px; overflow: auto; flex: 1; }
+    .run-card { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 18px; box-shadow: var(--shadow); }
+    .run-head { display: flex; align-items: center; gap: 12px; margin-bottom: 14px; }
+    .spinner { width: 18px; height: 18px; border: 2px solid #cfe1f5; border-top-color: var(--accent); border-radius: 50%; animation: spin .8s linear infinite; }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .run-head strong { font-size: 14px; }
+    .run-head span { color: var(--muted); font-size: 12px; }
+    .logs {
+      margin: 0; background: #0e1d2c; color: #bfe0f5; border-radius: 9px;
+      padding: 14px; min-height: 160px; max-height: 280px; overflow: auto;
+      font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 11px; line-height: 1.6;
+      white-space: pre-wrap; word-break: break-word;
+    }
+    .result-view { display: flex; flex-direction: column; min-height: 0; flex: 1; }
+    .result-head { background: var(--panel); border-bottom: 1px solid var(--line); padding: 16px 20px; display: flex; align-items: center; gap: 16px; flex-wrap: wrap; }
+    .result-head h2 { margin: 0; font-size: 15px; flex: 1; min-width: 150px; }
+    .status-pill { border-radius: 99px; padding: 5px 10px; font-size: 11px; font-weight: 700; }
+    .status-pill.pass { background: var(--green-bg); color: var(--green); }
+    .status-pill.fail { background: var(--red-bg); color: var(--red); }
+    .status-pill.error { background: var(--amber-bg); color: var(--amber); }
+    .head-link { color: var(--accent); text-decoration: none; font-size: 12px; }
+    .head-link:hover { text-decoration: underline; }
+    .scope-strip { display: flex; gap: 10px; flex-wrap: wrap; padding: 14px 20px; background: #f8fafc; border-bottom: 1px solid var(--line); }
+    .scope-card { background: #fff; border: 1px solid var(--line); border-radius: 9px; padding: 9px 12px; min-width: 180px; }
+    .scope-card .name { display: flex; justify-content: space-between; gap: 12px; font-size: 11px; color: var(--muted); }
+    .scope-card .name b { color: var(--ink); font-size: 12px; }
+    .scope-card .value { margin-top: 5px; font-size: 18px; font-weight: 800; font-variant-numeric: tabular-nums; }
+    .scope-card .value.good { color: var(--green); }
+    .scope-card .value.bad { color: var(--red); }
+    .scope-card .sub { font-size: 10px; color: var(--muted); margin-top: 2px; }
+    .report-frame-wrap { flex: 1; min-height: 0; background: #fff; }
+    .report-frame { width: 100%; height: 100%; border: 0; display: block; }
+    .error-box { background: var(--red-bg); border: 1px solid #f5c2c5; color: #8d1f24; border-radius: 9px; padding: 12px; font-size: 12px; line-height: 1.7; margin-bottom: 12px; white-space: pre-wrap; }
+    .error-box .hint-line { margin-top: 7px; color: #6d3a3d; font-size: 11px; }
+    .toast {
+      position: fixed; left: 50%; bottom: 26px; transform: translateX(-50%);
+      background: #17324a; color: #fff; border-radius: 8px; padding: 9px 14px;
+      font-size: 12px; box-shadow: var(--shadow); z-index: 20;
+    }
+    [hidden] { display: none !important; }
+    @media (max-width: 980px) {
+      .layout { grid-template-columns: 1fr; height: auto; }
+      .panel { border-right: 0; border-bottom: 1px solid var(--line); max-height: none; }
+      .workspace { min-height: 70vh; }
+      .topbar { height: auto; min-height: 64px; flex-wrap: wrap; padding: 10px 14px; gap: 10px; }
+      .brand { min-width: 0; }
+      .project-box { order: 3; flex-basis: 100%; }
+      .project-box input { max-width: none; }
+    }
+  </style>
+</head>
+<body>
+  <header class="topbar">
+    <div class="brand">
+      <div class="logo">CG</div>
+      <div><strong>CovGate</strong> <span>覆盖率工作台</span></div>
+    </div>
+    <div class="project-box">
+      <label for="root">项目</label>
+      <input id="root" spellcheck="false" placeholder="项目根目录">
+      <button id="detectBtn" type="button">检测项目</button>
+    </div>
+  </header>
+
+  <main class="layout">
+    <aside class="panel">
+      <p class="panel-intro">选择客户端、服务端的源码路径和测试命令。运行时会使用临时配置，不会覆盖项目里的 <code>covgate.config.json</code>。</p>
+
+      <div id="healthCard" class="health" hidden>
+        <div class="health-row"><span>测试框架</span><b id="healthFramework">—</b></div>
+        <div class="health-row"><span>测试文件</span><b id="healthTests">—</b></div>
+        <div class="health-row"><span>覆盖率报告</span><b id="healthCoverage">—</b></div>
+      </div>
+      <div id="healthWarn" class="health-warn" hidden>
+        没有检测到测试文件。CovGate 不会生成测试，请先让项目/AI 补真实测试。
+      </div>
+
+      <section class="card">
+        <div class="card-head">
+          <div class="card-title"><span class="dot"></span>客户端</div>
+          <span class="hint">100%</span>
+        </div>
+        <div class="field">
+          <label for="clientPath">源码路径</label>
+          <input id="clientPath" list="sourceDirs" spellcheck="false" placeholder="例如 src">
+        </div>
+        <div class="field">
+          <label for="clientCommand">测试命令</label>
+          <select id="clientCommand"></select>
+        </div>
+      </section>
+
+      <section class="card">
+        <div class="card-head">
+          <div class="card-title"><span class="dot server"></span>服务端</div>
+          <span class="hint">95%</span>
+        </div>
+        <div class="field">
+          <label for="serverPath">源码路径</label>
+          <input id="serverPath" list="sourceDirs" spellcheck="false" placeholder="例如 desktop，留空则不检查">
+        </div>
+        <div class="field">
+          <label for="serverCommand">测试命令</label>
+          <select id="serverCommand"></select>
+        </div>
+      </section>
+
+      <section class="card">
+        <div class="card-head">
+          <div class="card-title"><span class="dot"></span>覆盖率报告</div>
+          <span class="hint">自动检测</span>
+        </div>
+        <div class="field">
+          <label for="coveragePath">报告文件</label>
+          <input id="coveragePath" list="coverageOptions" spellcheck="false" placeholder="coverage/coverage-final.json">
+        </div>
+        <div id="configChip" class="config-chip temp">使用临时配置</div>
+      </section>
+
+      <button id="runBtn" class="run-button" type="button" disabled>运行覆盖率</button>
+      <div id="panelStatus" class="panel-status"></div>
+
+      <datalist id="sourceDirs"></datalist>
+      <datalist id="coverageOptions"></datalist>
+    </aside>
+
+    <section class="workspace">
+      <div id="emptyView" class="empty">
+        <div id="emptyMark" class="empty-mark">⌁</div>
+        <h1 id="emptyTitle">把覆盖率跑起来</h1>
+        <p id="emptyText">在左侧选择源码路径和测试命令，点击“运行覆盖率”。<br>完成后会在这里显示文件列表和逐行覆盖情况。</p>
+        <div id="emptyActions" class="empty-actions" hidden>
+          <button id="copyPromptBtn" class="secondary-btn" type="button">复制 AI 补测任务</button>
+          <button id="allowRunBtn" class="text-btn" type="button">仍然运行一次</button>
+        </div>
+      </div>
+
+      <div id="runView" class="run-view" hidden>
+        <div class="run-card">
+          <div class="run-head"><div class="spinner"></div><strong id="runTitle">正在运行覆盖率…</strong><span id="runMeta"></span></div>
+          <div id="runError" class="error-box" hidden></div>
+          <pre id="logs" class="logs">等待测试命令输出…</pre>
+        </div>
+      </div>
+
+      <div id="resultView" class="result-view" hidden>
+        <div class="result-head">
+          <h2 id="resultTitle">覆盖率结果</h2>
+          <span id="statusPill" class="status-pill"></span>
+          <a id="openReport" class="head-link" href="#" target="_blank" rel="noreferrer">在新标签打开报告</a>
+        </div>
+        <div id="scopeStrip" class="scope-strip"></div>
+        <div class="report-frame-wrap">
+          <iframe id="reportFrame" class="report-frame" title="CovGate 覆盖率报告"></iframe>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <script>
+    (function () {
+      var $ = function (id) { return document.getElementById(id); };
+      var state = null;
+      var activeJob = null;
+      var pollTimer = null;
+      var allowNoTests = false;
+
+      function text(value) { return value === null || value === undefined ? "" : String(value); }
+      function setStatus(message, kind) {
+        var el = $("panelStatus");
+        el.textContent = message || "";
+        el.className = "panel-status" + (kind ? " " + kind : "");
+      }
+      function setRunning(running) {
+        var noTests = Boolean(state && state.testCount === 0 && !allowNoTests);
+        $("runBtn").disabled = running || noTests;
+        $("detectBtn").disabled = running;
+        $("runBtn").title = noTests ? "没有测试文件：先补测试，或使用“仍然运行一次”" : "";
+      }
+      function toast(message) {
+        var el = document.createElement("div");
+        el.className = "toast";
+        el.textContent = message;
+        document.body.appendChild(el);
+        setTimeout(function () { el.remove(); }, 1800);
+      }
+      function buildPrompt() {
+        var root = $("root").value.trim() || (state && state.root) || "";
+        var client = $("clientPath").value.trim() || "（未指定）";
+        var server = $("serverPath").value.trim() || "（未指定）";
+        var clientCommand = $("clientCommand").value || "（未选择）";
+        var serverCommand = $("serverCommand").value || "（未选择）";
+        var coverage = $("coveragePath").value.trim() || "（未指定）";
+        var framework = state && state.frameworkLabel ? state.frameworkLabel : "项目现有测试框架";
+        return [
+          "你正在为以下项目补真实测试，目标是让 CovGate 真正通过。",
+          "",
+          "项目根目录：" + root,
+          "测试框架：" + framework,
+          "客户端源码：" + client + "（目标 100%）",
+          "服务端源码：" + server + "（目标 95%）",
+          "客户端测试命令：" + clientCommand,
+          "服务端测试命令：" + serverCommand,
+          "覆盖率报告：" + coverage,
+          "",
+          "当前测试文件数量：" + ((state && state.testCount) || 0) + "。请先建立/完善测试基础设施，再补真实测试。",
+          "",
+          "硬性规则：",
+          "- 不得使用 ignore、伪造覆盖率、空报告或降低阈值；客户端 100%、服务端 95%。",
+          "- 不得整体排除客户端 UI、主进程或核心模块；只允许对第三方生成物或确实不可达的薄启动层提出窄范围 exclude/waiver，并写 reason/owner/expires，等待人工批准。",
+          "- 先补测试，再考虑配置；不要通过缩小 sources.include 或扩大 exclude 让门禁通过。",
+          "- 每轮至少完成一个可验证的测试里程碑；每轮运行 npx covgate run --json，退出码 0 才算完成。",
+          "- 最终通过后再提交/合并；WIP 请提交到独立分支并明确标注 coverage WIP。",
+          "",
+          "请从测试基础设施和第一批核心模块测试开始，直接修改代码并运行测试，不要只给计划。"
+        ].join(String.fromCharCode(10));
+      }
+      function copyText(value) {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          return navigator.clipboard.writeText(value);
+        }
+        var area = document.createElement("textarea");
+        area.value = value;
+        document.body.appendChild(area);
+        area.select();
+        document.execCommand("copy");
+        area.remove();
+        return Promise.resolve();
+      }
+      function updateHealth(data) {
+        var hasTests = (data.testCount || 0) > 0;
+        $("healthCard").hidden = false;
+        $("healthFramework").textContent = data.frameworkLabel || "未检测到";
+        $("healthFramework").className = data.framework ? "good" : "bad";
+        $("healthTests").textContent = hasTests ? data.testCount + " 个" : "0 个 · 需要补测试";
+        $("healthTests").className = hasTests ? "good" : "bad";
+        $("healthCoverage").textContent = data.coveragePath || "未指定";
+        $("healthWarn").hidden = hasTests;
+        $("emptyMark").textContent = hasTests ? "⌁" : "!";
+        $("emptyTitle").textContent = hasTests ? "把覆盖率跑起来" : "项目还没有测试";
+        $("emptyText").innerHTML = hasTests
+          ? "在左侧选择源码路径和测试命令，点击“运行覆盖率”。<br>完成后会在这里显示文件列表和逐行覆盖情况。"
+          : "CovGate 不会生成测试。先让项目或编码代理补真实测试，再运行覆盖率。<br>可以复制下面的补测任务作为 AI 的输入。";
+        $("emptyActions").hidden = hasTests;
+        setRunning(false);
+      }
+      function showView(name) {
+        $("emptyView").hidden = name !== "empty";
+        $("runView").hidden = name !== "run";
+        $("resultView").hidden = name !== "result";
+      }
+      function fillCommands(select, commands, selected) {
+        select.innerHTML = "";
+        if (!commands.length) {
+          var none = document.createElement("option");
+          none.value = "";
+          none.textContent = "未检测到可用的测试命令";
+          select.appendChild(none);
+          select.disabled = true;
+          return;
+        }
+        select.disabled = false;
+        commands.forEach(function (command) {
+          var option = document.createElement("option");
+          option.value = command.run;
+          option.textContent = command.label;
+          option.title = command.run;
+          select.appendChild(option);
+        });
+        if (selected && !commands.some(function (command) { return command.run === selected; })) {
+          var custom = document.createElement("option");
+          custom.value = selected;
+          custom.textContent = "当前配置命令：" + selected;
+          select.appendChild(custom);
+        }
+        select.value = selected || commands[0].run;
+      }
+      function fillDatalist(id, values) {
+        var list = $(id);
+        list.innerHTML = "";
+        values.forEach(function (value) {
+          var option = document.createElement("option");
+          option.value = value;
+          list.appendChild(option);
+        });
+      }
+      function applyState(data) {
+        state = data;
+        allowNoTests = false;
+        $("root").value = data.root;
+        $("clientPath").value = data.clientPath || "";
+        $("serverPath").value = data.serverPath || "";
+        $("coveragePath").value = data.coveragePath || "coverage/coverage-final.json";
+        fillCommands($("clientCommand"), data.commands || [], data.clientCommand);
+        fillCommands($("serverCommand"), data.commands || [], data.serverCommand);
+        fillDatalist("sourceDirs", data.sourceDirs || []);
+        var coverageOptions = (data.coverageFiles || []).slice();
+        if (data.coveragePath && coverageOptions.indexOf(data.coveragePath) === -1) coverageOptions.unshift(data.coveragePath);
+        fillDatalist("coverageOptions", coverageOptions);
+        var chip = $("configChip");
+        chip.textContent = data.existingConfig ? "已加载现有 covgate.config.json" : "使用临时配置";
+        chip.className = "config-chip" + (data.existingConfig ? "" : " temp");
+        updateHealth(data);
+        setStatus(data.name ? "已检测：" + data.name + " · " + (data.frameworkLabel || "未检测到测试框架") : "已检测项目");
+      }
+      async function api(url, options) {
+        var response = await fetch(url, options);
+        var data = null;
+        try { data = await response.json(); } catch (_) {}
+        if (!response.ok) throw new Error((data && data.error) || ("HTTP " + response.status));
+        return data;
+      }
+      async function detect() {
+        var root = $("root").value.trim();
+        setStatus("正在检测项目…");
+        try {
+          var data = await api("/api/state" + (root ? "?root=" + encodeURIComponent(root) : ""));
+          applyState(data);
+          showView(activeJob ? "run" : "empty");
+        } catch (error) {
+          setStatus(error.message, "error");
+        }
+      }
+      function renderSummary(job) {
+        var report = job.report;
+        if (!report) throw new Error(job.error || "没有报告");
+        var passed = report.status === "pass";
+        $("statusPill").textContent = passed ? "通过" : report.status === "fail" ? "未通过" : "运行失败";
+        $("statusPill").className = "status-pill " + (passed ? "pass" : report.status === "fail" ? "fail" : "error");
+        $("resultTitle").textContent = "覆盖率结果 · " + (report.tool && report.tool.version ? "v" + report.tool.version : "");
+        $("openReport").href = job.htmlUrl || "#";
+        $("openReport").hidden = !job.htmlUrl;
+        var strip = $("scopeStrip");
+        strip.innerHTML = "";
+        (report.scopes || []).forEach(function (scope) {
+          var card = document.createElement("div");
+          card.className = "scope-card";
+          var name = document.createElement("div");
+          name.className = "name";
+          var label = document.createElement("b");
+          label.textContent = scope.label || scope.name;
+          var profile = document.createElement("span");
+          profile.textContent = String(scope.profile || "").toUpperCase();
+          name.appendChild(label);
+          name.appendChild(profile);
+          var value = document.createElement("div");
+          var line = scope.metrics && scope.metrics.lines;
+          var linePercent = line && line.applicable && line.percent !== null ? line.percent : null;
+          value.className = "value " + (scope.skipped || (linePercent !== null && linePercent >= line.threshold) ? "good" : "bad");
+          value.textContent = scope.skipped ? "未涉及" : linePercent === null ? "N/A" : linePercent.toFixed(2) + "%";
+          var sub = document.createElement("div");
+          sub.className = "sub";
+          sub.textContent = scope.skipped ? "本次无变更" : line && line.applicable ? line.covered + "/" + line.total + " 行 · 目标 " + line.threshold + "%" : "无行覆盖率数据";
+          card.appendChild(name);
+          card.appendChild(value);
+          card.appendChild(sub);
+          strip.appendChild(card);
+        });
+        $("reportFrame").src = job.htmlUrl ? job.htmlUrl + "?v=" + Date.now() : "about:blank";
+      }
+      function finishJob(job) {
+        setRunning(false);
+        activeJob = null;
+        pollTimer = null;
+        $("runView").hidden = true;
+        var report = job.report;
+        var emptyReport = !report || report.status === "error" || (report.scopes || []).length === 0;
+        if (job.status === "failed" || emptyReport) {
+          showView("run");
+          $("runTitle").textContent = "运行失败";
+          $("runMeta").textContent = job.exitCode === null ? "" : "退出码 " + job.exitCode;
+          var message = job.error;
+          if (!message && report && report.issues && report.issues.length) message = report.issues[0].message;
+          if (!message) message = "没有生成可用的覆盖率报告。";
+          if (/No test files found|没有测试文件/i.test(job.logs || "")) {
+            message += "\n\n检测到测试命令没有测试文件可执行。请先补真实测试，再重新运行。";
+          }
+          $("runError").hidden = false;
+          $("runError").textContent = message;
+          $("logs").textContent = job.logs || "测试命令没有输出。";
+          setStatus("运行失败", "error");
+          return;
+        }
+        try {
+          renderSummary(job);
+          showView("result");
+          setStatus("覆盖率完成：" + (report.status === "pass" ? "通过" : "未通过"), report.status === "pass" ? "ok" : "error");
+        } catch (error) {
+          showView("run");
+          $("runTitle").textContent = "结果解析失败";
+          $("runError").hidden = false;
+          $("runError").textContent = error.message;
+          setStatus(error.message, "error");
+        }
+      }
+      function pollJob(id) {
+        pollTimer = setTimeout(async function () {
+          try {
+            var job = await api("/api/jobs/" + encodeURIComponent(id));
+            $("logs").textContent = job.logs || "等待测试命令输出…";
+            $("logs").scrollTop = $("logs").scrollHeight;
+            $("runMeta").textContent = job.report ? "正在生成报告…" : "";
+            if (job.status === "running") pollJob(id);
+            else finishJob(job);
+          } catch (error) {
+            setRunning(false);
+            activeJob = null;
+            $("runTitle").textContent = "查询任务失败";
+            $("runError").hidden = false;
+            $("runError").textContent = error.message;
+            setStatus(error.message, "error");
+          }
+        }, 700);
+      }
+      async function run() {
+        if (activeJob) return;
+        if (state && state.testCount === 0 && !allowNoTests) {
+          showView("empty");
+          setStatus("项目没有测试文件。先补测试，或选择“仍然运行一次”。", "error");
+          return;
+        }
+        var clientPath = $("clientPath").value.trim();
+        var serverPath = $("serverPath").value.trim();
+        if (!clientPath && !serverPath) {
+          setStatus("至少填写客户端或服务端源码路径。", "error");
+          return;
+        }
+        var clientCommand = $("clientCommand").value;
+        var serverCommand = $("serverCommand").value;
+        if (clientPath && !clientCommand) { setStatus("请选择客户端测试命令。", "error"); return; }
+        if (serverPath && !serverCommand) { setStatus("请选择服务端测试命令。", "error"); return; }
+        setRunning(true);
+        setStatus("正在运行覆盖率…");
+        showView("run");
+        $("runTitle").textContent = "正在运行覆盖率…";
+        $("runMeta").textContent = "";
+        $("runError").hidden = true;
+        $("logs").textContent = "正在启动测试命令…";
+        try {
+          var job = await api("/api/run", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              root: $("root").value.trim(),
+              clientPath: clientPath,
+              serverPath: serverPath,
+              clientCommand: clientCommand,
+              serverCommand: serverCommand,
+              coveragePath: $("coveragePath").value.trim(),
+              allowNoTests: allowNoTests
+            })
+          });
+          activeJob = job.jobId;
+          pollJob(job.jobId);
+        } catch (error) {
+          setRunning(false);
+          setStatus(error.message, "error");
+          showView("empty");
+          if (/没有检测到测试文件/.test(error.message)) {
+            allowNoTests = false;
+            if (state) updateHealth(state);
+          }
+        }
+      }
+
+      $("detectBtn").addEventListener("click", detect);
+      $("root").addEventListener("keydown", function (event) { if (event.key === "Enter") detect(); });
+      $("runBtn").addEventListener("click", run);
+      $("copyPromptBtn").addEventListener("click", function () {
+        copyText(buildPrompt()).then(function () {
+          toast("补测任务已复制");
+        }).catch(function () {
+          toast("复制失败，请手动选择文本");
+        });
+      });
+      $("allowRunBtn").addEventListener("click", function () {
+        allowNoTests = true;
+        updateHealth(state);
+        run();
+      });
+      detect();
+    })();
+  </script>
+</body>
+</html>

package/src/ui/server.js

@@ -0,0 +1,496 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, stat, unlink, writeFile } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expandFiles, matchGlob } from "../glob.js";
+import { detectFramework, detectPackageManager } from "../setup/project.js";
+
+const BIN = fileURLToPath(new URL("../../bin/covgate.js", import.meta.url));
+const PAGE = fileURLToPath(new URL("./page.html", import.meta.url));
+const SOURCE_EXT = "{js,jsx,ts,tsx,mjs,cjs}";
+const COVERAGE_CANDIDATES = [
+  "coverage/coverage-final.json",
+  "coverage/lcov.info",
+  "coverage/lcov-report/lcov.info"
+];
+const SOURCE_DIR_CANDIDATES = [
+  "src",
+  "desktop",
+  "app",
+  "client",
+  "server",
+  "renderer",
+  "web",
+  "lib"
+];
+const TEST_PATTERNS = [
+  "**/*.{test,spec}.{js,jsx,ts,tsx,mjs,cjs}",
+  "tests/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+  "test/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+  "__tests__/**/*.{js,jsx,ts,tsx,mjs,cjs}"
+];
+const TEST_EXCLUDES = [
+  { pattern: "**/*.test.*", reason: "测试文件，不是产品运行时代码" },
+  { pattern: "**/*.spec.*", reason: "测试文件，不是产品运行时代码" },
+  { pattern: "**/__tests__/**", reason: "测试目录，不是产品运行时代码" }
+];
+const MAX_BODY = 1024 * 1024;
+
+class HttpError extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.status = status;
+    this.code = code || null;
+  }
+}
+
+async function pickTestExcludes(root, sourcePath) {
+  let files = [];
+  try {
+    files = await expandFiles([sourceGlob(sourcePath)], root);
+  } catch {
+    return [];
+  }
+  const relative = files.map((file) => toPosix(path.relative(root, file)));
+  return TEST_EXCLUDES.filter((entry) =>
+    relative.some((file) => matchGlob(file, entry.pattern))
+  );
+}
+
+async function findTestFiles(root) {
+  try {
+    const files = await expandFiles(TEST_PATTERNS, root);
+    return files
+      .map((file) => toPosix(path.relative(root, file)))
+      .filter((file) => !file.startsWith("../"))
+      .sort((left, right) => left.localeCompare(right, "en"));
+  } catch {
+    return [];
+  }
+}
+
+function toPosix(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+function relativeInput(root, value) {
+  const raw = String(value || "").trim().replaceAll("\\", "/");
+  if (!raw) return "";
+  if (path.isAbsolute(raw)) return toPosix(path.relative(root, raw));
+  return raw.replace(/^\.\//, "");
+}
+
+function sourceGlob(value) {
+  const input = String(value || "").trim().replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!input) return "";
+  if (/[*?[\]{}]/.test(input)) return input;
+  if (path.extname(input)) return input;
+  return input.replace(/\/+$/, "") + "/**/*." + SOURCE_EXT;
+}
+
+function pathFromGlob(glob) {
+  const value = String(glob || "").trim();
+  if (!value) return "";
+  return value
+    .replace(/\/\*\*\/\*\..*$/, "")
+    .replace(/\/\*\*.*$/, "")
+    .replace(/\/\*\..*$/, "")
+    .replace(/\/\*.*$/, "");
+}
+
+function scriptCommand(packageManager, name) {
+  if (packageManager === "yarn") return "yarn " + name;
+  if (packageManager === "pnpm") return "pnpm run " + name;
+  if (packageManager === "bun") return "bun run " + name;
+  return "npm run " + name;
+}
+
+function buildCommands(packageManager, pkg) {
+  const scripts = pkg?.scripts || {};
+  const commands = [];
+  const seen = new Set();
+  const add = (label, run, scriptName) => {
+    if (!run || seen.has(run)) return;
+    seen.add(run);
+    commands.push({ label, run, script: scriptName || null });
+  };
+  const names = Object.keys(scripts).filter((name) => {
+    const script = String(scripts[name] || "");
+    if (name === "coverage:gate" || /\bcovgate\b/i.test(script)) return false;
+    return /(^|:)(test|spec|coverage)(:|$)|test|coverage|spec/i.test(name);
+  });
+  names.sort((left, right) => {
+    const score = (name) =>
+      name === "test:coverage" ? 0 : name.includes("coverage") ? 1 : name === "test" ? 2 : 3;
+    return score(left) - score(right) || left.localeCompare(right, "en");
+  });
+  for (const name of names) {
+    const script = String(scripts[name] || "");
+    add(name + " — " + script, scriptCommand(packageManager, name), name);
+  }
+  const framework = detectFramework(pkg);
+  if (framework.id === "vitest") {
+    add("Vitest 覆盖率", "npx vitest run --coverage --coverage.reporter=json --coverage.reporter=lcov");
+  } else if (framework.id === "jest") {
+    add("Jest 覆盖率", "npx jest --coverage --coverageReporters=json --coverageReporters=lcov");
+  }
+  return { commands, framework, defaultCommand: commands[0]?.run || "" };
+}
+
+function existingPath(scopes, name) {
+  const include = scopes?.[name]?.sources?.include;
+  if (!Array.isArray(include) || include.length === 0) return "";
+  return pathFromGlob(include[0]);
+}
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function inspectProject(root) {
+  const projectRoot = path.resolve(root || process.cwd());
+  let info;
+  try {
+    info = await stat(projectRoot);
+  } catch {
+    throw new HttpError(400, "项目目录不存在：" + projectRoot);
+  }
+  if (!info.isDirectory()) throw new HttpError(400, "项目路径不是目录：" + projectRoot);
+
+  const pkg = (await readJson(path.join(projectRoot, "package.json"))) || {};
+  const packageManager = detectPackageManager(projectRoot, pkg);
+  const { commands, framework, defaultCommand } = buildCommands(packageManager, pkg);
+  const existing = (await readJson(path.join(projectRoot, "covgate.config.json"))) || null;
+  const scopes = existing?.scopes || {};
+
+  const sourceDirs = [];
+  for (const candidate of SOURCE_DIR_CANDIDATES) {
+    if (existsSync(path.join(projectRoot, candidate))) sourceDirs.push(candidate);
+  }
+  const coverageFiles = [];
+  for (const candidate of COVERAGE_CANDIDATES) {
+    if (existsSync(path.join(projectRoot, candidate))) coverageFiles.push(candidate);
+  }
+  const configuredCoverage = scopes.client?.coverage?.paths?.[0] || scopes.server?.coverage?.paths?.[0];
+  const coveragePath = configuredCoverage || coverageFiles[0] || COVERAGE_CANDIDATES[0];
+
+  const pickExisting = (names) => names.find((name) => existsSync(path.join(projectRoot, name))) || "";
+  const clientPath =
+    existingPath(scopes, "client") ||
+    pickExisting(["src", "web", "client", "app", "renderer"]);
+  const serverPath =
+    existingPath(scopes, "server") ||
+    pickExisting(["server", "desktop", "api"]);
+  const clientCommand = scopes.client?.commands?.[0]?.run || defaultCommand;
+  const serverCommand = scopes.server?.commands?.[0]?.run || defaultCommand;
+  const testFiles = await findTestFiles(projectRoot);
+
+  return {
+    root: projectRoot,
+    name: pkg.name || path.basename(projectRoot),
+    packageManager,
+    framework: framework.id,
+    frameworkLabel: framework.label,
+    commands,
+    sourceDirs,
+    coverageFiles,
+    coveragePath,
+    clientPath,
+    serverPath,
+    clientCommand,
+    serverCommand,
+    testCount: testFiles.length,
+    testFiles: testFiles.slice(0, 50),
+    existingConfig: Boolean(existing),
+    reportsDir: existing?.reports?.dir || ".covgate"
+  };
+}
+
+async function buildConfig(state, input) {
+  const clientPath = relativeInput(state.root, input.clientPath);
+  const serverPath = relativeInput(state.root, input.serverPath);
+  const coveragePath = relativeInput(state.root, input.coveragePath || state.coveragePath);
+  const existing = state.existing || {};
+  const scopes = {};
+  const makeScope = async (name, profile, label, sourcePath, command) => {
+    if (!sourcePath) return;
+    const old = existing.scopes?.[name] || {};
+    const oldExclude = Array.isArray(old.exclude) ? old.exclude : [];
+    const testExclude = await pickTestExcludes(state.root, sourcePath);
+    const merged = [...oldExclude, ...testExclude];
+    const seen = new Set();
+    const exclude = merged.filter((entry) => {
+      if (!entry || seen.has(entry.pattern)) return false;
+      seen.add(entry.pattern);
+      return true;
+    });
+    scopes[name] = {
+      profile,
+      label,
+      ...(old.thresholds ? { thresholds: old.thresholds } : {}),
+      commands: [
+        {
+          name: label + "测试与覆盖率",
+          run: command || state.defaultCommand,
+          timeoutSeconds: 900
+        }
+      ],
+      coverage: { format: "auto", paths: [coveragePath] },
+      sources: { include: [sourceGlob(sourcePath)] },
+      exclude
+    };
+  };
+  await makeScope("client", "client", "客户端", clientPath, input.clientCommand || state.clientCommand);
+  await makeScope("server", "server", "服务端", serverPath, input.serverCommand || state.serverCommand);
+  if (Object.keys(scopes).length === 0) {
+    throw new HttpError(400, "至少需要指定客户端或服务端源码路径。");
+  }
+  return {
+    version: 1,
+    scopes,
+    waivers: existing.waivers || {
+      minReasonLength: 8,
+      requireOwner: false,
+      stale: "fail",
+      expiry: "fail"
+    },
+    reports: {
+      dir: existing.reports?.dir || ".covgate",
+      formats: ["json", "html"]
+    }
+  };
+}
+
+function parseReport(stdout) {
+  const text = stdout.trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+      try {
+        return JSON.parse(text.slice(start, end + 1));
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+function truncateLog(value, max = 16000) {
+  const text = String(value || "");
+  return text.length > max ? text.slice(text.length - max) : text;
+}
+
+async function readBody(req) {
+  let body = "";
+  for await (const chunk of req) {
+    body += chunk;
+    if (body.length > MAX_BODY) throw new HttpError(413, "请求体过大");
+  }
+  if (!body) return {};
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new HttpError(400, "请求 JSON 无效");
+  }
+}
+
+function send(res, status, body, contentType = "application/json; charset=utf-8") {
+  const payload = typeof body === "string" ? body : JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": contentType,
+    "Cache-Control": "no-store"
+  });
+  res.end(payload);
+}
+
+/**
+ * @param {{ root?: string, port?: number, host?: string }} options
+ */
+export async function startUiServer(options = {}) {
+  const defaultRoot = path.resolve(options.root || process.cwd());
+  const host = options.host || "127.0.0.1";
+  const port = Number(options.port ?? 4318);
+  const page = await readFile(PAGE, "utf8");
+  const jobs = new Map();
+  let activeJob = null;
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url || "/", "http://" + host);
+      if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/index.html")) {
+        send(res, 200, page, "text/html; charset=utf-8");
+        return;
+      }
+      if (req.method === "GET" && url.pathname === "/favicon.ico") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      if (req.method === "GET" && url.pathname === "/api/state") {
+        const root = url.searchParams.get("root") || defaultRoot;
+        const state = await inspectProject(root);
+        send(res, 200, state);
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/api/run") {
+        if (activeJob) throw new HttpError(409, "已有覆盖率任务正在运行，请等待完成。");
+        const body = await readBody(req);
+        const root = path.resolve(body.root || defaultRoot);
+        const state = await inspectProject(root);
+        if (state.testCount === 0 && body.allowNoTests !== true) {
+          throw new HttpError(
+            422,
+            "项目中没有检测到测试文件。请先让项目补真实测试，再运行覆盖率；CovGate 不会生成测试。",
+            "no-tests"
+          );
+        }
+        const existing = (await readJson(path.join(root, "covgate.config.json"))) || null;
+        state.existing = existing || {};
+        state.defaultCommand = state.commands[0]?.run || "";
+        const config = await buildConfig(state, body);
+        const id = randomUUID();
+        const configPath = path.join(root, ".covgate-ui-" + id + ".json");
+        await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+        const job = {
+          id,
+          root,
+          status: "running",
+          logs: "",
+          startedAt: new Date().toISOString(),
+          finishedAt: null,
+          exitCode: null,
+          report: null,
+          error: null,
+          htmlPath: null,
+          spec: {
+            clientPath: body.clientPath || "",
+            serverPath: body.serverPath || "",
+            clientCommand: body.clientCommand || state.clientCommand || "",
+            serverCommand: body.serverCommand || state.serverCommand || "",
+            coveragePath: body.coveragePath || state.coveragePath || ""
+          }
+        };
+        jobs.set(id, job);
+        activeJob = id;
+        const child = spawn(process.execPath, [BIN, "run", "--config", configPath, "--json"], {
+          cwd: root,
+          env: { ...process.env, NO_COLOR: "1" },
+          windowsHide: true,
+          stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+          job.error = "覆盖率任务超过 15 分钟，已终止。";
+          child.kill();
+        }, 15 * 60 * 1000);
+        child.stdout.on("data", (chunk) => {
+          stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+          stderr += chunk.toString();
+          job.logs = truncateLog(stderr);
+        });
+        child.on("error", (error) => {
+          job.error = error.message;
+        });
+        child.on("close", async (code) => {
+          clearTimeout(timer);
+          job.exitCode = code;
+          job.finishedAt = new Date().toISOString();
+          job.status = job.error ? "failed" : "completed";
+          job.report = parseReport(stdout);
+          if (!job.report && !job.error) {
+            job.status = "failed";
+            job.error = "CovGate 没有返回 JSON 报告。" + (stderr ? "\n" + truncateLog(stderr) : "");
+          }
+          if (job.report) {
+            const htmlRelative = job.report.artifacts?.html;
+            if (htmlRelative) {
+              job.htmlPath = path.resolve(root, htmlRelative);
+              if (!existsSync(job.htmlPath)) job.htmlPath = null;
+            }
+          }
+          await unlink(configPath).catch(() => {});
+          activeJob = null;
+        });
+        send(res, 202, { jobId: id });
+        return;
+      }
+      const jobMatch = url.pathname.match(/^\/api\/jobs\/([^/]+)$/);
+      if (req.method === "GET" && jobMatch) {
+        const job = jobs.get(jobMatch[1]);
+        if (!job) throw new HttpError(404, "任务不存在");
+        const { htmlPath, root, ...safe } = job;
+        send(res, 200, { ...safe, htmlUrl: htmlPath ? "/api/jobs/" + job.id + "/report.html" : null });
+        return;
+      }
+      const reportMatch = url.pathname.match(/^\/api\/jobs\/([^/]+)\/report\.html$/);
+      if (req.method === "GET" && reportMatch) {
+        const job = jobs.get(reportMatch[1]);
+        if (!job) throw new HttpError(404, "任务不存在");
+        if (!job.htmlPath) throw new HttpError(404, "HTML 报告尚未生成");
+        const html = await readFile(job.htmlPath, "utf8");
+        send(res, 200, html, "text/html; charset=utf-8");
+        return;
+      }
+      throw new HttpError(404, "Not found");
+    } catch (error) {
+      const status = error instanceof HttpError ? error.status : 500;
+      send(res, status, {
+        error: error.message || String(error),
+        ...(error instanceof HttpError && error.code ? { code: error.code } : {})
+      });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  const actualPort = typeof address === "object" && address ? address.port : port;
+  return {
+    server,
+    port: actualPort,
+    url: "http://" + host + ":" + actualPort,
+    close: () => new Promise((resolve) => server.close(resolve))
+  };
+}
+
+/**
+ * @param {string} url
+ */
+export function openBrowser(url) {
+  let command;
+  let args;
+  if (process.platform === "win32") {
+    command = "cmd";
+    args = ["/c", "start", "", url];
+  } else if (process.platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+  try {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}