@jsonstudio/rcc 0.89.2202 → 0.90.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstudio/rcc",
-  "version": "0.89.2202",
+  "version": "0.90.001",
   "description": "Multi-provider OpenAI proxy server with anthropic/responses/chat support (release)",
   "type": "module",
   "main": "dist/index.js",
@@ -29,9 +29,11 @@
     "node": ">=20 <26"
   },
   "scripts": {
-    "build": "npm run llmswitch:ensure && node scripts/build-core.mjs && node scripts/vendor-core.mjs && npm run clean && node scripts/gen-build-info.mjs && tsc && node scripts/copy-compat-assets.mjs && node scripts/copy-modules-config.mjs && npm run fix:cli-permission",
-    "build:dev": "bash -lc 'export BUILD_MODE=dev; npm run build && npm run fix:cli-permission && npm run test:unified-hub-shadow && npm run verify:e2e-toolcall && npm run verify:apply-patch && npm run verify:apply-patch-regressions && npm run verify:exec-command && npm run test:routing-instructions && npm run test:cli && npm run install:global && npm run mock:regressions && npm run test:blackbox-antigravity-parity && npm run verify:errorsamples && npm run verify:e2e-gemini-followup-sample'",
-    "build:min": "npm run llmswitch:ensure && node scripts/build-core.mjs && node scripts/vendor-core.mjs && npm run clean && node scripts/gen-build-info.mjs && tsc && node scripts/copy-compat-assets.mjs && node scripts/copy-modules-config.mjs && npm run fix:cli-permission",
+    "build": "npm run llmswitch:ensure && node scripts/build-core.mjs && node scripts/vendor-core.mjs && npm run clean && node scripts/gen-build-info.mjs && tsc && npm run build:webui && node scripts/copy-compat-assets.mjs && node scripts/copy-modules-config.mjs && npm run fix:cli-permission",
+    "build:dev": "bash -lc 'export BUILD_MODE=dev ROUTECODEX_BUILD_RESTART_ONLY=1; npm run build && npm run fix:cli-permission && npm run install:global'",
+    "build:dev:full": "bash -lc 'export BUILD_MODE=dev ROUTECODEX_BUILD_RESTART_ONLY=1; npm run cleanup:stale-server-pids || true; trap \"npm run cleanup:stale-server-pids >/dev/null 2>&1 || true\" EXIT; npm run build && npm run fix:cli-permission && npm run test:unified-hub-shadow && npm run verify:e2e-toolcall && npm run verify:apply-patch && npm run verify:apply-patch-regressions && npm run verify:exec-command && npm run test:routing-instructions && npm run test:cli && npm run install:global && npm run mock:regressions && npm run test:blackbox-antigravity-parity && npm run verify:errorsamples && npm run verify:e2e-gemini-followup-sample'",
+    "build:min": "npm run llmswitch:ensure && node scripts/build-core.mjs && node scripts/vendor-core.mjs && npm run clean && node scripts/gen-build-info.mjs && tsc && npm run build:webui && node scripts/copy-compat-assets.mjs && node scripts/copy-modules-config.mjs && npm run fix:cli-permission",
+    "build:webui": "vite build --config webui/vite.config.ts",
     "prepack": "echo skip-prepack",
     "postbuild": "node scripts/ensure-cli-executable.mjs",
     "build:watch": "tsc --watch",
@@ -39,6 +41,7 @@
     "dev": "tsx watch src/index.ts",
     "jest:run": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
     "test": "npm run test:routing-instructions && npm run mock:regressions",
+    "test:regressions": "npm run test:unified-hub-shadow && npm run mock:regressions && npm run test:blackbox-antigravity-parity && npm run verify:errorsamples",
     "test:blackbox-antigravity-parity": "node scripts/tests/blackbox-rcc-vs-routecodex-antigravity.mjs",
     "test:ci:jest": "node scripts/tests/ci-jest.mjs",
     "test:ci:jest:coverage": "node scripts/tests/ci-jest.mjs --coverage",
@@ -53,6 +56,8 @@
     "test:coverage": "npm run jest:run -- --coverage",
     "test:integration": "npm run jest:run -- --testPathPattern=integration",
     "test:e2e": "npm run jest:run -- --testPathPattern=e2e",
+    "test:webui": "npm run jest:run -- --runTestsByPath tests/frontend/webui-app.utils.spec.ts tests/frontend/webui-app.render.spec.tsx tests/frontend/webui-app.integration.spec.tsx tests/frontend/webui-app.pages.spec.tsx tests/frontend/webui-app.edge.spec.tsx",
+    "test:webui:coverage": "npm run jest:run -- --runTestsByPath tests/frontend/webui-app.utils.spec.ts tests/frontend/webui-app.render.spec.tsx tests/frontend/webui-app.integration.spec.tsx tests/frontend/webui-app.pages.spec.tsx tests/frontend/webui-app.edge.spec.tsx --coverage --collectCoverageFrom=webui/src/App.tsx",
     "test:performance": "npm run jest:run -- --testPathPattern=performance",
     "test:protocol": "npm run jest:run -- --testPathPattern=protocol-tools-e2e.spec.ts --runInBand --detectOpenHandles --forceExit",
     "test:dry-run": "node tests/basic-dry-run.mjs",
@@ -63,6 +68,7 @@
     "lint:fix": "ESLINT_USE_FLAT_CONFIG=1 eslint \"src/**/*.ts\" --fix --no-cache",
     "lint:strict": "ESLINT_USE_FLAT_CONFIG=1 eslint \"src/**/*.ts\" --max-warnings 0 --no-cache",
     "clean": "rm -rf dist coverage",
+    "cleanup:stale-server-pids": "node scripts/cleanup-stale-server-pids.mjs --quiet",
     "prebuild": "npm run verify:repo-sanity && echo skip-lint",
     "prepare": "",
     "postinstall": "node scripts/ensure-cli-executable.mjs",
@@ -70,6 +76,7 @@
     "verify:apply-patch-regressions": "node scripts/verify-apply-patch-regressions.mjs",
     "verify:exec-command": "node scripts/tests/exec-command-loop.mjs",
     "verify:errorsamples": "node scripts/verify-codex-error-samples.mjs",
+    "triage:errorsamples": "node scripts/triage-errorsamples.mjs",
     "verify:e2e-gemini-followup-sample": "node scripts/verify-e2e-gemini-followup-sample.mjs",
     "install:global": "./scripts/install-global.sh",
     "install:release": "./scripts/install-release.sh",
@@ -150,7 +157,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.65.0",
-    "@jsonstudio/llms": "^0.6.2125",
+    "@jsonstudio/llms": "^0.6.2172",
     "@lmstudio/sdk": "^1.5.0",
     "@radix-ui/react-switch": "^1.2.6",
     "@types/socket.io": "^3.0.1",
@@ -187,28 +194,38 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.1.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/cors": "^2.8.13",
     "@types/express": "^4.17.17",
     "@types/jest": "^29.5.5",
     "@types/node": "^20.19.25",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
     "@typescript-eslint/eslint-plugin": "^6.7.4",
     "@typescript-eslint/parser": "^6.7.4",
     "@typescript-eslint/typescript-estree": "^6.7.4",
+    "@vitejs/plugin-react": "^5.1.0",
     "complexity-report": "^2.0.0-alpha",
     "depcheck": "^1.4.7",
     "eslint": "^8.50.0",
     "eslint-plugin-complexity": "^1.0.2",
     "husky": "^9.0.0",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^30.2.0",
     "jscpd": "^4.0.5",
     "lint-staged": "^15.0.0",
     "npm-check-updates": "^18.3.0",
     "package-json-validator": "^0.30.0",
     "prettier": "^3.6.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.2",
     "tsx": "^4.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vite": "^7.1.12"
   },
   "bundleDependencies": []
 }

package/scripts/build-core.mjs

@@ -10,6 +10,7 @@ const buildMode = buildModeRaw === 'dev' ? 'dev' : 'release';
 const tsc = path.join(root, 'node_modules', 'typescript', 'bin', 'tsc');
 const proj = path.join(root, 'sharedmodule', 'llmswitch-core', 'tsconfig.json');
 const coreRoot = path.join(root, 'sharedmodule', 'llmswitch-core');
+const nativeBuildScript = path.join(coreRoot, 'scripts', 'build-native-hotpath.mjs');
 const outDir = path.join(coreRoot, 'dist');
 const requiredOutputs = [
   path.join(outDir, 'bridge', 'routecodex-adapter.js'),
@@ -75,6 +76,16 @@ function shouldSkipBuild() {
   return distMtime >= srcMtime;
 }
 
+function runNativeBuild() {
+  if (!fs.existsSync(nativeBuildScript)) {
+    fail(`native build script missing: ${nativeBuildScript}`);
+  }
+  const res = spawnSync(process.execPath, [nativeBuildScript], { stdio: 'inherit', cwd: coreRoot });
+  if ((res.status ?? 0) !== 0) {
+    fail('native build failed for llmswitch-core');
+  }
+}
+
 if (!fs.existsSync(tsc)) fail('TypeScript not installed in root node_modules. Run npm i.');
 if (!fs.existsSync(proj)) {
   console.log('[build-core] llmswitch-core source not found under sharedmodule; skip local core build (依赖包将用于运行/打包)');
@@ -92,6 +103,7 @@ if (skip === '1' || skip === 'true' || skip === 'yes') {
   console.log('[build-core] skip requested by env (ROUTECODEX_SKIP_CORE_BUILD/SKIP_CORE_BUILD)');
   process.exit(0);
 }
+runNativeBuild();
 if (shouldSkipBuild()) {
   console.log('[build-core] dist up-to-date; skip rebuild:', outDir);
   process.exit(0);

package/scripts/camoufox/launch-auth.mjs

@@ -13,6 +13,30 @@ function isTruthy(value) {
   return v === '1' || v === 'true' || v === 'yes' || v === 'on';
 }
 
+function isFalsy(value) {
+  if (!value) return false;
+  const v = String(value).trim().toLowerCase();
+  return v === '0' || v === 'false' || v === 'no' || v === 'off';
+}
+
+function resolveIflowHeadlessMode(devMode) {
+  if (devMode) {
+    return false;
+  }
+  const raw = String(
+    process.env.ROUTECODEX_CAMOUFOX_IFLOW_HEADLESS ||
+    process.env.RCC_CAMOUFOX_IFLOW_HEADLESS ||
+    ''
+  ).trim();
+  if (!raw) {
+    return false;
+  }
+  if (isFalsy(raw)) {
+    return false;
+  }
+  return isTruthy(raw);
+}
+
 function parseArgs(argv) {
   const args = { profile: 'default', url: '', autoMode: '', devMode: false };
   const list = argv.slice(2);
@@ -260,13 +284,44 @@ function cleanupExistingCamoufox(profileDir) {
   if (!profileDir) {
     return;
   }
-  console.log('[camoufox-launch-auth] Ensuring Camoufox profile is clean before launch...');
-  const pkillArgs = ['-f', profileDir];
+  // 清理已知进程，不使用 pkill 普杀
+  // 使用 pgrep 查找匹配的进程，然后逐个验证后终止
   try {
-    spawnSync('pkill', pkillArgs, { stdio: 'ignore' });
+    const probe = spawnSync('pgrep', ['-f', profileDir], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    
+    if (probe.status === 0 && probe.stdout) {
+      const selfPid = process.pid;
+      const lines = String(probe.stdout).split(/\r?\n/).filter(Boolean);
+      
+      for (const line of lines) {
+        const pid = Number.parseInt(line.trim(), 10);
+        if (!Number.isFinite(pid) || pid <= 0 || pid === selfPid) {
+          continue;
+        }
+        // 验证进程命令包含 camoufox
+        try {
+          const cmdProbe = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+          const cmd = String(cmdProbe.stdout || '').toLowerCase();
+          if (cmd.includes('camoufox')) {
+            console.log(`[camoufox-launch-auth] Stopping known Camoufox process PID ${pid}`);
+            try {
+              process.kill(pid, 'SIGTERM');
+            } catch {
+              // 忽略终止失败
+            }
+          }
+        } catch {
+          // 忽略 ps 查询失败
+        }
+      }
+    }
   } catch {
-    // pkill may not exist; ignore
+    // pgrep 可能不存在，忽略
   }
+  console.log('[camoufox-launch-auth] Ensuring Camoufox profile is clean before launch...');
   const lockNames = ['.parentlock', 'parent.lock', 'lock'];
   for (const name of lockNames) {
     const target = path.join(profileDir, name);
@@ -754,7 +809,9 @@ async function runIflowAutoFlow({ url, profileDir, profileId, camoufoxBinary, de
     );
   }
 
-  const headless = !devMode;
+  // iFlow OAuth has poor reliability under headless mode (often returns anti-bot/garbled pages).
+  // Keep default headed to match camo CLI behavior; allow opt-in headless via env.
+  const headless = resolveIflowHeadlessMode(devMode);
   const timeoutMs = Number(process.env.ROUTECODEX_CAMOUFOX_IFLOW_TIMEOUT_MS || 300_000);
   console.log(`[camoufox-launch-auth] Launching Camoufox in ${headless ? 'headless' : 'headed'} mode...`);
   cleanupExistingCamoufox(profileDir);
@@ -1172,6 +1229,8 @@ async function runQwenAutoFlow({ url, profileDir, camoufoxBinary, devMode }) {
   }
 
   const timeoutMs = Number(process.env.ROUTECODEX_CAMOUFOX_QWEN_TIMEOUT_MS || 120_000);
+  const accountPreference = (process.env.ROUTECODEX_CAMOUFOX_ACCOUNT_TEXT || '').trim();
+  const accountWaitMs = Number(process.env.ROUTECODEX_CAMOUFOX_QWEN_ACCOUNT_TIMEOUT_MS || 15_000);
   cleanupExistingCamoufox(profileDir);
   const context = await firefox.launchPersistentContext(profileDir, {
     executablePath: camoufoxBinary,
@@ -1231,6 +1290,54 @@ async function runQwenAutoFlow({ url, profileDir, camoufoxBinary, devMode }) {
       await authPage.waitForLoadState('domcontentloaded', { timeout: pageLoadTimeoutMs }).catch(() => {});
     }
 
+    const qwenAccountSelectors = [
+      'div.yAlK0b[jsname="bQIQze"]',
+      'div.pGzURd[jsname="V1ur5d"]',
+      'span.accountName--ZKlffRBc',
+      'span[class^="accountName--"]',
+      'span[class*="accountName--"]',
+      '.account-item',
+      '[class*="account-item"]',
+      '[class*="accountItem"]',
+      '[data-testid*="account"]',
+      '[data-test*="account"]'
+    ];
+    const accountResult = await waitForAnyElementInPages(context, qwenAccountSelectors, accountWaitMs);
+    if (accountResult) {
+      let targetAccount = accountResult.locator.first();
+      if (accountPreference) {
+        const preferred = accountResult.locator.filter({ hasText: accountPreference });
+        if (await preferred.count()) {
+          console.log(`[camoufox-launch-auth] Qwen selecting account matching preference "${accountPreference}"`);
+          targetAccount = preferred.first();
+        } else {
+          console.warn(
+            `[camoufox-launch-auth] Qwen preferred account text "${accountPreference}" not found; falling back to first account`
+          );
+        }
+      }
+      await targetAccount.scrollIntoViewIfNeeded().catch(() => {});
+      await targetAccount.hover({ force: true }).catch(() => {});
+      const handle = await targetAccount.elementHandle();
+      const accountText = await targetAccount.innerText().catch(() => '');
+      if (handle) {
+        console.log(
+          `[camoufox-launch-auth] Qwen account element detected (${accountText || 'unknown label'}), clicking...`
+        );
+        await accountResult.page.evaluate((el) => {
+          const events = ['mouseenter', 'mouseover', 'mousemove', 'mousedown', 'mouseup', 'click'];
+          for (const type of events) {
+            el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window }));
+          }
+        }, handle);
+      } else {
+        await targetAccount.click({ timeout: Math.min(timeoutMs, 10_000) }).catch(() => {});
+      }
+      await accountResult.page.waitForLoadState('domcontentloaded', { timeout: Math.min(timeoutMs, 15_000) }).catch(() => {});
+    } else {
+      console.log('[camoufox-launch-auth] Qwen account selector not detected; proceeding to confirm step...');
+    }
+
     console.log('[camoufox-launch-auth] Qwen authorize page loaded, waiting for confirm button...');
     const confirmSelector = 'button.qwen-confirm-btn';
     const confirmResult = await waitForElementInPages(context, confirmSelector, timeoutMs);

package/scripts/ci/repo-sanity.mjs

@@ -91,6 +91,7 @@ function checkRootLayout() {
     'task.md',
     'tests',
     'tmp',
+    'tsconfig.jest.json',
     'tsconfig.json',
     'vendor',
   ]);

package/scripts/cleanup-stale-server-pids.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+const quiet = process.argv.includes('--quiet');
+const routeCodexHome = path.join(os.homedir(), '.routecodex');
+
+function log(message) {
+  if (!quiet) {
+    console.log(`[cleanup:server-pids] ${message}`);
+  }
+}
+
+function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readProcessCommand(pid) {
+  if (process.platform === 'win32') {
+    return '';
+  }
+  try {
+    const result = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+    if (result.error || Number(result.status ?? 0) !== 0) {
+      return '';
+    }
+    return String(result.stdout || '').trim().toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+function isTrustedRouteCodexCommand(command) {
+  const normalized = String(command || '').trim().toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  if (normalized.includes('routecodex/dist/index.js')) {
+    return true;
+  }
+  if (normalized.includes('routecodex/dist/cli.js')) {
+    return true;
+  }
+  if (normalized.includes('@jsonstudio/rcc') && normalized.includes('/dist/index.js')) {
+    return true;
+  }
+  if (normalized.includes('jsonstudio-rcc') && normalized.includes('/dist/index.js')) {
+    return true;
+  }
+  return false;
+}
+
+function isPidListeningOnPort(pid, port) {
+  if (process.platform === 'win32') {
+    return true;
+  }
+  try {
+    const result = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], { encoding: 'utf8' });
+    if (result.error) {
+      return true;
+    }
+    if (Number(result.status ?? 0) !== 0) {
+      return false;
+    }
+    const pids = String(result.stdout || '')
+      .split(/\r?\n/)
+      .map((entry) => Number.parseInt(entry.trim(), 10))
+      .filter((entry) => Number.isFinite(entry) && entry > 0);
+    return pids.includes(pid);
+  } catch {
+    return true;
+  }
+}
+
+function cleanupPidFile(filePath) {
+  const fileName = path.basename(filePath);
+  const match = fileName.match(/^server-(\d+)\.pid$/i);
+  const filePort = match ? Number.parseInt(match[1], 10) : null;
+  let raw = '';
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { removed: false, reason: 'unreadable' };
+  }
+  const pid = Number.parseInt(String(raw || '').trim(), 10);
+  if (!Number.isFinite(pid) || pid <= 0) {
+    fs.rmSync(filePath, { force: true });
+    return { removed: true, reason: 'invalid_pid' };
+  }
+  if (!isPidAlive(pid)) {
+    fs.rmSync(filePath, { force: true });
+    return { removed: true, reason: 'pid_not_alive' };
+  }
+
+  const command = readProcessCommand(pid);
+  if (command && !isTrustedRouteCodexCommand(command)) {
+    fs.rmSync(filePath, { force: true });
+    return { removed: true, reason: 'pid_not_routecodex' };
+  }
+  if (Number.isFinite(filePort) && filePort > 0 && !isPidListeningOnPort(pid, filePort)) {
+    fs.rmSync(filePath, { force: true });
+    return { removed: true, reason: 'pid_not_listening_on_port' };
+  }
+
+  return { removed: false, reason: `kept:${fileName}:${pid}` };
+}
+
+function main() {
+  if (!fs.existsSync(routeCodexHome)) {
+    return;
+  }
+  const entries = fs.readdirSync(routeCodexHome);
+  const candidates = entries
+    .filter((name) => /^server-\d+\.pid$/i.test(name) || name === 'server.cli.pid')
+    .map((name) => path.join(routeCodexHome, name));
+
+  let removed = 0;
+  let kept = 0;
+  for (const filePath of candidates) {
+    const result = cleanupPidFile(filePath);
+    if (result.removed) {
+      removed += 1;
+      log(`removed ${path.basename(filePath)} (${result.reason})`);
+    } else {
+      kept += 1;
+      log(`kept ${path.basename(filePath)} (${result.reason})`);
+    }
+  }
+  log(`done removed=${removed} kept=${kept}`);
+}
+
+main();

package/scripts/install-global.sh

@@ -196,6 +196,12 @@ verify_install() {
 }
 
 verify_server_health() {
+    if [ "${ROUTECODEX_INSTALL_SKIP_E2E:-0}" = "1" ]; then
+        echo ""
+        echo "⏭️  已跳过全局 CLI 端到端检查（ROUTECODEX_INSTALL_SKIP_E2E=1）"
+        return
+    fi
+
     local HEALTH_LOG="/tmp/routecodex-install-health-$(date +%s).log"
     echo ""
     echo "🩺 执行服务器健康&端到端检查 (chat + anthropic SSE)..."
@@ -244,11 +250,13 @@ cleanup_old_install() {
 main() {
     check_node
     cleanup_old_install
+    node scripts/cleanup-stale-server-pids.mjs --quiet || true
     build_project
     global_install
     link_global_llms_dev
     verify_install
     verify_server_health
+    node scripts/cleanup-stale-server-pids.mjs --quiet || true
 
     echo ""
     echo "🎉 全局安装完成!"

package/scripts/install-verify.mjs

@@ -25,6 +25,7 @@ const state = {
   logStream: null,
   logPath: '',
   baseUrl: '',
+  ownsServer: false,
 };
 let shuttingDown = false;
 let responsesSseParser = null;
@@ -791,9 +792,12 @@ async function verifyChatStreaming(baseUrl, model, timeoutMs, samplePayload, cha
 async function stopServer() {
   const proc = state.serverProc;
   const baseUrl = state.baseUrl;
-  if (baseUrl) {
+  if (state.ownsServer && baseUrl) {
     try { await fetch(`${baseUrl}/shutdown`, { method: 'POST' }).catch(() => {}); } catch { /* ignore */ }
   }
+  if (!state.ownsServer) {
+    return;
+  }
   if (!proc) {
     if (state.logStream) {
       try { state.logStream.end(); } catch { /* ignore */ }
@@ -903,18 +907,23 @@ async function main() {
 
   const model = resolveModel(config);
   console.log(`🔁 模型: ${model}, 端口: ${port}`);
+  const buildRestartOnly = (() => {
+    const raw = String(process.env.ROUTECODEX_BUILD_RESTART_ONLY ?? process.env.RCC_BUILD_RESTART_ONLY ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+  })();
 
   const listeners = detectPortPids(port);
-  if (listeners.length) {
+  const reuseExistingServer = buildRestartOnly && listeners.length > 0;
+  if (listeners.length && !reuseExistingServer) {
     throw new Error(`端口 ${port} 已被使用 (PID: ${listeners.join(', ')}). 请先停止正在运行的 RouteCodex 实例再重试。`);
   }
+  if (reuseExistingServer) {
+    console.log(`ℹ build-restart-only: 检测到已运行服务 (PID: ${listeners.join(', ')})，复用现有实例进行验证。`);
+  }
 
   console.log('🛠️ 动态生成最新的 pipeline 配置...');
   regeneratePipelineConfig({ port, configPath });
 
-  state.logPath = path.join(os.tmpdir(), `routecodex-install-verify-${Date.now()}.log`);
-  const logStream = fs.createWriteStream(state.logPath, { flags: 'a' });
-
   let command;
   let commandArgs;
   const env = { ...process.env };
@@ -933,17 +942,25 @@ async function main() {
     env.RCC_PORT = String(port);
   }
 
-  console.log(`🚀 启动 RouteCodex server... (launcher=${launcher === 'cli' ? command : 'node dist/index.js'})`);
-  const serverProc = spawn(command, commandArgs, {
-    cwd,
-    env,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: false,
-  });
-  serverProc.stdout.pipe(logStream, { end: false });
-  serverProc.stderr.pipe(logStream, { end: false });
-  state.serverProc = serverProc;
-  state.logStream = logStream;
+  if (!reuseExistingServer) {
+    state.logPath = path.join(os.tmpdir(), `routecodex-install-verify-${Date.now()}.log`);
+    const logStream = fs.createWriteStream(state.logPath, { flags: 'a' });
+    state.ownsServer = true;
+    console.log(`🚀 启动 RouteCodex server... (launcher=${launcher === 'cli' ? command : 'node dist/index.js'})`);
+    const serverProc = spawn(command, commandArgs, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: false,
+    });
+    serverProc.stdout.pipe(logStream, { end: false });
+    serverProc.stderr.pipe(logStream, { end: false });
+    state.serverProc = serverProc;
+    state.logStream = logStream;
+  } else {
+    state.ownsServer = false;
+    state.serverProc = null;
+  }
 
   await waitForHealth(baseUrl, 90000);
   console.log('✅ server 健康检查通过');