perf(test): speed up offline command E2E execution

- Run offline validation and dry-run cases in process
- Serialize captures and restore process state after each run
- Preserve subprocess coverage for live, I/O, preload and proxy contracts
- Load only command modules required by topic routes
- Isolate the harness npm update lookup while preserving business fetches
- Add execution parity and isolation tests
- Stabilize preload checks across cache modes
- Document offline E2E execution boundaries

Author: XXPermanentXX

docs/agents/cli-e2e-tests.md

@@ -2,14 +2,14 @@
 
 ## 架构分层
 
-| 层级            | 路径                                                  | 测什么                                                                                  |
-| --------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| **共享基建**    | `packages/e2e`                                        | gating、子进程 runner、registry help 捕获、output、globalSetup（`private`，不发布）     |
-| **命令 E2E**    | `packages/commands/tests/e2e`                         | 进程内 help、子进程缺参/dry-run/live（gated）；每用例最小路由                           |
-| **Journey E2E** | `packages/commands/tests/e2e/knowledge/journeys`      | 用户旅程全链路（跨命令回路 + 标记词召回闭环），全部 live gated；见 `journeys/README.md` |
-| **bl smoke**    | `packages/cli/tests/e2e/registry.smoke.e2e.test.ts`   | 产品 map 全部 path/分组的进程内 help；根 help、鉴权域等代表性子进程冒烟                 |
-| **kscli smoke** | `packages/kscli/tests/e2e/registry.smoke.e2e.test.ts` | map 全部 path/分组的进程内 help；`--version`、`search --help` 等代表性子进程冒烟        |
-| **runtime**     | `packages/runtime/tests`                              | `proxy.e2e`、console 跨域 flag 拒绝                                                     |
+| 层级            | 路径                                                  | 测什么                                                                                       |
+| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **共享基建**    | `packages/e2e`                                        | gating、子进程 / 进程内 runner、registry help 捕获、output、globalSetup（`private`，不发布） |
+| **命令 E2E**    | `packages/commands/tests/e2e`                         | 进程内 help / 离线校验 / dry-run、代表性子进程、live（gated）；每用例最小路由                |
+| **Journey E2E** | `packages/commands/tests/e2e/knowledge/journeys`      | 用户旅程全链路（跨命令回路 + 标记词召回闭环），全部 live gated；见 `journeys/README.md`      |
+| **bl smoke**    | `packages/cli/tests/e2e/registry.smoke.e2e.test.ts`   | 产品 map 全部 path/分组的进程内 help；根 help、鉴权域等代表性子进程冒烟                      |
+| **kscli smoke** | `packages/kscli/tests/e2e/registry.smoke.e2e.test.ts` | map 全部 path/分组的进程内 help；`--version`、`search --help` 等代表性子进程冒烟             |
+| **runtime**     | `packages/runtime/tests`                              | `proxy.e2e`、console 跨域 flag 拒绝                                                          |
 
 **依赖边界**：`e2e` → `core`；`commands/tests` → `e2e` + `commands/src`；产品 tests → `e2e` + 各自 `src` + `runtime` 公共 API。**禁止**产品 import `commands/tests/**`（子进程 spawn harness 路径除外）。
 
@@ -30,7 +30,10 @@
 
 - 路径：`packages/commands/tests/e2e/<kebab-topic>.e2e.test.ts`；knowledge 领域集中在 `packages/commands/tests/e2e/knowledge/` 子目录（新增 knowledge 命令测试放这里）
 - help：`runCommandHelp(routes, [...path, "--help"])` from `./helpers.ts`（当前 Vitest worker 内用真实 command + `CommandRegistry` 渲染，不启动子进程）
-- 子进程：缺参、dry-run、live 使用 `runCommandE2e(routes, args)`（spawn `harness/main.ts`，`routes` 为本 topic 最小 path → export 映射）
+- 离线校验 / dry-run：确认用例不依赖进程初始化、真实请求或持久化后，可显式使用 `runCommandInProcess(routes, args, envOverrides)`；走真实 `createCli`、middleware 和 command，捕获 stdout / stderr / 退出码，执行后恢复进程环境。worker 内串行捕获，禁止与其他操作全局状态的并发用例混用
+- 子进程：`runCommandE2e(routes, args)` 保留给 live、实际写盘、进程隔离及 shell / stdio / env 契约；每个 topic 保留代表性子进程用例。`NODE_OPTIONS` / HTTP(S) 代理配置存在时，`runCommandInProcess` 自动回退子进程
+- 路由加载：harness 按 command 库公开导出名加载 topic 所需模块，不整体求值命令 barrel；新增导出形式需扩展 loader 并保留与公开导出对象一致性的测试
+- 更新检查：未发布的 harness 包 `latest` 查询固定返回本地 404，避免重复访问 npm；只拦截这个精确 URL，业务 fetch 和生产 updater 测试仍走原逻辑
 - fixtures：`packages/commands/tests/e2e/fixtures/`
 - 路由常量：`topic-routes.ts`（按 topic 维护，**非**全量产品 map）
 
@@ -44,7 +47,7 @@
 
 ### 共享
 
-- gating / output / runner：`e2e/gating`、`e2e/output`、`e2e/runner`；runner 使用 `node --import tsx` 执行 TypeScript 入口，不启动 tsx CLI IPC server
+- gating / output / runner：`e2e/gating`、`e2e/output`、`e2e/runner`、`e2e/in-process`；runner 使用 `node --import tsx` 执行 TypeScript 入口，不启动 tsx CLI IPC server
 - globalSetup：根 `vite.config.ts` → `packages/e2e/src/global-setup.ts`
 - 解析 JSON stdout：`parseStdoutJson`；输出目录：`makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url))`
 - 长任务：`cliTimeoutPrefix()`；视频用例加 `test(..., 3_600_000)` 等显式超时

packages/commands/tests/e2e/alert.e2e.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vite-plus/test";
-import { parseStdoutJson, runCommandE2e } from "./helpers.ts";
+import { parseStdoutJson, runCommandE2e, runCommandInProcess } from "./helpers.ts";
 import { ALERT_ROUTES } from "./topic-routes.ts";
 
 // 只覆盖 help / 参数校验 / dry-run；真实调用依赖 console 凭证与已开通的 CMS 服务。
@@ -74,7 +74,7 @@ describe("e2e: alert", () => {
   });
 
   test("alert create --dry-run 输出完整通知配置", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+    const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
       "alert",
       "create",
       "--name",
@@ -146,7 +146,7 @@ describe("e2e: alert", () => {
   });
 
   test("alert delete --dry-run 支持多 ID", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+    const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
       "alert",
       "delete",
       "--rule-id",
@@ -187,7 +187,7 @@ describe("e2e: alert", () => {
       ["enable", "zeldaEasy.bailian-telemetry.alertRule.enableAlertRule"],
       ["disable", "zeldaEasy.bailian-telemetry.alertRule.disableAlertRule"],
     ] as const) {
-      const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+      const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
         "alert",
         verb,
         "--rule-id",
@@ -246,7 +246,7 @@ describe("e2e: alert", () => {
   });
 
   test("alert template create --dry-run 输出条件结构", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+    const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
       "alert",
       "template",
       "create",
@@ -295,7 +295,7 @@ describe("e2e: alert", () => {
   });
 
   test("alert template update --dry-run 输出更新请求", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+    const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
       "alert",
       "template",
       "update",
@@ -319,7 +319,7 @@ describe("e2e: alert", () => {
   });
 
   test("alert template delete --dry-run 支持多 ID", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+    const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
       "alert",
       "template",
       "delete",
@@ -362,7 +362,7 @@ describe("e2e: alert", () => {
   });
 
   test("alert history --dry-run 输出时间范围映射", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(ALERT_ROUTES, [
+    const { stdout, stderr, exitCode } = await runCommandInProcess(ALERT_ROUTES, [
       "alert",
       "history",
       "--rule-id",

packages/commands/tests/e2e/command-in-process.test.ts

@@ -0,0 +1,125 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vite-plus/test";
+import { runCommandE2e, runCommandInProcess } from "./helpers.ts";
+import {
+  CONFIG_ROUTES,
+  KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES,
+  QUOTA_ROUTES,
+} from "./topic-routes.ts";
+
+const captureEnvironment = {
+  NODE_OPTIONS: undefined,
+  HTTP_PROXY: undefined,
+  HTTPS_PROXY: undefined,
+  http_proxy: undefined,
+  https_proxy: undefined,
+};
+
+const cases = [
+  { name: "group help", routes: QUOTA_ROUTES, args: ["quota", "--help"] },
+  {
+    name: "supplied flag usage error",
+    routes: QUOTA_ROUTES,
+    args: ["quota", "list", "--unsupported", "--output", "json"],
+  },
+  {
+    name: "required flag usage error",
+    routes: CONFIG_ROUTES,
+    args: ["config", "set", "--quiet", "--output", "json"],
+  },
+  {
+    name: "config dry-run",
+    routes: CONFIG_ROUTES,
+    args: [
+      "config",
+      "set",
+      "--key",
+      "watermark",
+      "--value",
+      "false",
+      "--dry-run",
+      "--output",
+      "json",
+    ],
+  },
+  {
+    name: "command validation",
+    routes: KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES,
+    args: [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "fixture",
+      "--content",
+      "hello",
+      "--field",
+      "column=1",
+      "--workspace-id",
+      "fixture",
+      "--dry-run",
+      "--output",
+      "json",
+    ],
+  },
+];
+
+test.each(cases)(
+  "in-process $name matches the real CLI subprocess exactly",
+  async ({ routes, args }) => {
+    const directory = mkdtempSync(join(tmpdir(), "bl-command-parity-"));
+    try {
+      const environment = {
+        ...captureEnvironment,
+        BAILIAN_CONFIG_DIR: directory,
+        DASHSCOPE_API_KEY: "",
+        BAILIAN_E2E: "0",
+      };
+      const subprocess = await runCommandE2e(routes, args, environment);
+      const inProcess = await runCommandInProcess(routes, args, environment);
+      expect(inProcess).toEqual(subprocess);
+    } finally {
+      rmSync(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+test("profile-language errors match in-process and subprocess output", async () => {
+  const directory = mkdtempSync(join(tmpdir(), "bl-command-locale-parity-"));
+  try {
+    writeFileSync(
+      join(directory, "config.json"),
+      JSON.stringify({ language: "en-US", work: { language: "zh-CN" } }),
+    );
+    const args = ["--config", "work", "quota", "list", "--unsupported", "--output", "json"];
+    const environment = { ...captureEnvironment, BAILIAN_CONFIG_DIR: directory };
+    const result = await runCommandInProcess(QUOTA_ROUTES, args, environment);
+    expect(result).toEqual(await runCommandE2e(QUOTA_ROUTES, args, environment));
+    expect(result.stderr).toContain("未知参数");
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test("Node preloads retain the real subprocess contract", async () => {
+  const directory = mkdtempSync(join(tmpdir(), "bl-command-preload-"));
+  // esbuild workers also inherit NODE_OPTIONS on cache misses; only the CLI main thread marks startup.
+  const preload =
+    'import { isMainThread } from "node:worker_threads"; if (isMainThread) process.stdout.write("preload marker\\n");';
+  try {
+    for (const disableCache of [undefined, "1"]) {
+      const result = await runCommandInProcess(QUOTA_ROUTES, ["quota", "--help"], {
+        BAILIAN_CONFIG_DIR: directory,
+        TSX_DISABLE_CACHE: disableCache,
+        NODE_OPTIONS: `--import=data:text/javascript,${encodeURIComponent(preload)}`,
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toBe("preload marker\n");
+      expect(result.stderr).toContain("Usage: bl quota");
+    }
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});

packages/commands/tests/e2e/command-routes.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "vite-plus/test";
+import { loadRouteCommands } from "./harness/routes.ts";
+import * as topicRoutes from "./topic-routes.ts";
+import * as commandExports from "../../src/index.ts";
+
+const fixtureIndex = new URL("./fixtures/route-loader/index.ts", import.meta.url);
+
+test("loads a declared command without evaluating an unrelated broken export", async () => {
+  const commands = await loadRouteCommands({ "probe run": "probe" }, fixtureIndex);
+  expect(commands["probe run"].description).toBe("fixture probe");
+  expect(await commands["probe run"].run({} as never)).toBe("probe result");
+});
+
+test("aliases retain the same command instance", async () => {
+  const commands = await loadRouteCommands(
+    { "probe run": "probe", "probe alias": "probeAlias" },
+    fixtureIndex,
+  );
+  expect(commands["probe run"]).toBe(commands["probe alias"]);
+});
+
+test("rejects unknown exports and declared non-command defaults", async () => {
+  await expect(loadRouteCommands({ invalid: "missing" }, fixtureIndex)).rejects.toThrow(
+    "Unknown bailian-cli-commands export: missing",
+  );
+  await expect(loadRouteCommands({ invalid: "notACommand" }, fixtureIndex)).rejects.toThrow(
+    "Unknown bailian-cli-commands export: notACommand",
+  );
+});
+
+test("every topic route resolves to the same public command exported by the library", async () => {
+  const library = commandExports as Record<string, unknown>;
+  for (const routes of Object.values(topicRoutes)) {
+    const commands = await loadRouteCommands(routes);
+    for (const [path, exportName] of Object.entries(routes))
+      expect(commands[path]).toBe(library[exportName]);
+  }
+});
+
+test("supports named aliases and preserves route declaration order", async () => {
+  const routes = { "named first": "namedProbe", "default second": "probe" };
+  const commands = await loadRouteCommands(routes, fixtureIndex);
+  expect(Object.keys(commands)).toEqual(Object.keys(routes));
+  expect(await commands["named first"].run({} as never)).toBe("named result");
+});