mocode-ai 1.1.7 → 1.1.8

package/dist/runtime/browser-manager.js

@@ -0,0 +1,299 @@
+// Playwright 浏览器会话管理器。
+//
+// 设计要点:
+//  - 会话跨工具调用存活(Browser 单例 + 每会话独立 BrowserContext/Page),这样 agent 可以
+//    navigate → click → screenshot 连续操作同一个页面,而不是每次重开浏览器丢状态。
+//  - playwright 用动态 import:启动 mocode 不该为一个可选能力付加载成本,缺浏览器二进制时
+//    也能给出明确的 `npx playwright install chromium` 指引而不是崩在模块加载期。
+//  - 默认只允许回环地址。agent 能驱动真浏览器意味着它能发任意请求,若放开就等于给了
+//    SSRF / 内网扫描能力。放开需用户显式设 MOCODE_BROWSER_ALLOW_REMOTE=true。
+//  - 采集 console / pageerror / requestfailed 到有界 ring buffer:前端问题往往只在控制台可见,
+//    截图看不出来。
+import { randomBytes } from 'node:crypto';
+export class BrowserManagerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BrowserManagerError';
+    }
+}
+const sessions = new Map();
+const DIAGNOSTIC_LIMIT = 200;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_TIMEOUT_MS = 60_000;
+const DEFAULT_VIEWPORT = { width: 1280, height: 800 };
+let browserPromise = null;
+let launchedHeaded = false;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function resolveTimeout(input) {
+    const value = Number(input ?? DEFAULT_TIMEOUT_MS);
+    if (!Number.isFinite(value))
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(Math.max(value, 500), MAX_TIMEOUT_MS);
+}
+function remoteAllowed() {
+    return process.env.MOCODE_BROWSER_ALLOW_REMOTE === 'true';
+}
+/** 默认只放行 http/https 回环地址;拒绝 file:/data:/javascript: 等本地读取与脚本注入面。 */
+export function validateNavigationUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new BrowserManagerError('INVALID_ARGUMENTS', `Invalid url: ${input}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new BrowserManagerError('SANDBOX_DENIED', `Only http and https URLs are allowed (received ${url.protocol}).`);
+    }
+    if (url.username || url.password) {
+        throw new BrowserManagerError('SANDBOX_DENIED', 'URLs with embedded credentials are not allowed.');
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const loopback = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (!loopback && !remoteAllowed()) {
+        throw new BrowserManagerError('SANDBOX_DENIED', `Only localhost, 127.0.0.1, and ::1 are allowed by default (received ${url.hostname}). ` +
+            'Set MOCODE_BROWSER_ALLOW_REMOTE=true to permit remote navigation.');
+    }
+    return url;
+}
+async function launchBrowser(headed) {
+    let playwright;
+    try {
+        playwright = await import('playwright');
+    }
+    catch (error) {
+        throw new BrowserManagerError('EXECUTION_ERROR', `Playwright is not available: ${errorMessage(error)}. Run "npm install" first.`);
+    }
+    try {
+        return await playwright.chromium.launch({ headless: !headed });
+    }
+    catch (error) {
+        throw new BrowserManagerError('EXECUTION_ERROR', `Unable to launch Chromium: ${errorMessage(error)}. If the browser binary is missing, run "npx playwright install chromium".`);
+    }
+}
+async function getBrowser(headed) {
+    const existing = browserPromise ? await browserPromise.catch(() => null) : null;
+    // headless 与 headed 是不同的进程模式;请求切换时重开,避免默默给出与请求不符的模式。
+    if (existing?.isConnected() && launchedHeaded === headed)
+        return existing;
+    if (existing?.isConnected())
+        await existing.close().catch(() => { });
+    launchedHeaded = headed;
+    browserPromise = launchBrowser(headed);
+    try {
+        return await browserPromise;
+    }
+    catch (error) {
+        browserPromise = null;
+        throw error;
+    }
+}
+function record(session, bucket, line) {
+    const target = session[bucket];
+    target.push(line);
+    if (target.length > DIAGNOSTIC_LIMIT)
+        target.splice(0, target.length - DIAGNOSTIC_LIMIT);
+}
+export async function openSession(opts = {}) {
+    const headed = opts.headed === true;
+    const browser = await getBrowser(headed);
+    const context = await browser.newContext({ viewport: DEFAULT_VIEWPORT });
+    const page = await context.newPage();
+    page.setDefaultTimeout(DEFAULT_TIMEOUT_MS);
+    const session = {
+        sessionId: `page-${randomBytes(3).toString('hex')}`,
+        context,
+        page,
+        headed,
+        console: [],
+        pageErrors: [],
+        failedRequests: [],
+    };
+    page.on('console', (message) => {
+        record(session, 'console', `[${message.type()}] ${message.text()}`);
+    });
+    page.on('pageerror', (error) => record(session, 'pageErrors', errorMessage(error)));
+    page.on('requestfailed', (request) => {
+        record(session, 'failedRequests', `${request.method()} ${request.url()} — ${request.failure()?.errorText ?? 'failed'}`);
+    });
+    sessions.set(session.sessionId, session);
+    return describe(session);
+}
+function requireSession(sessionId) {
+    if (sessionId) {
+        const session = sessions.get(sessionId);
+        if (!session) {
+            const known = [...sessions.keys()];
+            throw new BrowserManagerError('INVALID_ARGUMENTS', known.length
+                ? `Unknown browser sessionId "${sessionId}". Known sessions: ${known.join(', ')}.`
+                : `Unknown browser sessionId "${sessionId}". Call action=open first.`);
+        }
+        return session;
+    }
+    // 只有一个会话时允许省略 sessionId,减少模型出错面;多会话必须显式指定。
+    const all = [...sessions.values()];
+    if (all.length === 1)
+        return all[0];
+    if (all.length === 0) {
+        throw new BrowserManagerError('INVALID_ARGUMENTS', 'No browser session is open. Call action=open first.');
+    }
+    throw new BrowserManagerError('INVALID_ARGUMENTS', `Multiple browser sessions are open; specify sessionId. Known sessions: ${all.map((s) => s.sessionId).join(', ')}.`);
+}
+function describe(session) {
+    const viewport = session.page.viewportSize() ?? DEFAULT_VIEWPORT;
+    return {
+        sessionId: session.sessionId,
+        url: session.page.url(),
+        title: '',
+        headed: session.headed,
+        viewport,
+    };
+}
+async function describeAsync(session) {
+    const base = describe(session);
+    return { ...base, title: await session.page.title().catch(() => '') };
+}
+/** Playwright 的超时错误统一映射成结构化 TIMEOUT,便于 agent 区分「选择器没出现」与真故障。 */
+function wrapActionError(error) {
+    if (error instanceof BrowserManagerError)
+        throw error;
+    const message = errorMessage(error);
+    if (/Timeout .* exceeded|waiting for/i.test(message)) {
+        throw new BrowserManagerError('TIMEOUT', message);
+    }
+    throw new BrowserManagerError('EXECUTION_ERROR', message);
+}
+function diagnostics(session) {
+    return {
+        console: session.console.slice(-20),
+        pageErrors: session.pageErrors.slice(-20),
+        failedRequests: session.failedRequests.slice(-20),
+    };
+}
+async function finish(session, action) {
+    return { action, ...(await describeAsync(session)), diagnostics: diagnostics(session) };
+}
+export async function navigate(opts) {
+    const session = requireSession(opts.sessionId);
+    const url = validateNavigationUrl(opts.url);
+    try {
+        const response = await session.page.goto(url.toString(), {
+            timeout: resolveTimeout(opts.timeoutMs),
+            waitUntil: 'domcontentloaded',
+        });
+        if (response && !response.ok()) {
+            record(session, 'failedRequests', `GET ${url.toString()} — HTTP ${response.status()}`);
+        }
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    return finish(session, 'navigate');
+}
+export async function click(opts) {
+    const session = requireSession(opts.sessionId);
+    try {
+        await session.page.click(opts.selector, { timeout: resolveTimeout(opts.timeoutMs) });
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    return finish(session, 'click');
+}
+export async function fill(opts) {
+    const session = requireSession(opts.sessionId);
+    try {
+        await session.page.fill(opts.selector, opts.value, { timeout: resolveTimeout(opts.timeoutMs) });
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    return finish(session, 'fill');
+}
+export async function press(opts) {
+    const session = requireSession(opts.sessionId);
+    const timeout = resolveTimeout(opts.timeoutMs);
+    try {
+        if (opts.selector)
+            await session.page.press(opts.selector, opts.key, { timeout });
+        else
+            await session.page.keyboard.press(opts.key);
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    return finish(session, 'press');
+}
+export async function waitFor(opts) {
+    const session = requireSession(opts.sessionId);
+    try {
+        await session.page.waitForSelector(opts.selector, { timeout: resolveTimeout(opts.timeoutMs) });
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    return finish(session, 'wait_for');
+}
+export async function readText(opts) {
+    const session = requireSession(opts.sessionId);
+    const limit = Math.min(Math.max(Number(opts.limit ?? 4_000), 100), 32_000);
+    let text;
+    try {
+        text = opts.selector
+            ? (await session.page.textContent(opts.selector, { timeout: DEFAULT_TIMEOUT_MS })) ?? ''
+            : await session.page.innerText('body');
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    const normalized = text.replace(/\n{3,}/g, '\n\n').trim();
+    return {
+        ...(await finish(session, 'text')),
+        text: normalized.length > limit ? `${normalized.slice(0, limit)}\n… (truncated)` : normalized,
+    };
+}
+export async function screenshot(opts) {
+    const session = requireSession(opts.sessionId);
+    const timeout = resolveTimeout(opts.timeoutMs);
+    let buffer;
+    try {
+        buffer = opts.selector
+            ? await session.page.locator(opts.selector).screenshot({ timeout, type: 'png' })
+            : await session.page.screenshot({ timeout, type: 'png', fullPage: opts.fullPage === true });
+    }
+    catch (error) {
+        wrapActionError(error);
+    }
+    return { ...(await finish(session, 'screenshot')), buffer };
+}
+export function listSessions() {
+    return [...sessions.values()].map(describe);
+}
+export async function closeSession(sessionId) {
+    const session = requireSession(sessionId);
+    sessions.delete(session.sessionId);
+    await session.context.close().catch(() => { });
+    if (sessions.size === 0 && browserPromise) {
+        const browser = await browserPromise.catch(() => null);
+        browserPromise = null;
+        await browser?.close().catch(() => { });
+    }
+    return { sessionId: session.sessionId, closed: true };
+}
+/** 全局退出清理:关闭所有页面与浏览器进程。幂等。 */
+export async function closeAllBrowsers() {
+    for (const session of [...sessions.values()]) {
+        sessions.delete(session.sessionId);
+        await session.context.close().catch(() => { });
+    }
+    const pending = browserPromise;
+    browserPromise = null;
+    if (!pending)
+        return;
+    const browser = await pending.catch(() => null);
+    await browser?.close().catch(() => { });
+}

package/dist/runtime/dev-server-manager.js

@@ -0,0 +1,354 @@
+// 常驻后台进程管理器(dev server 等)。
+//
+// 与 run_command 的关键区别:run_command 是前台命令,超时或本轮 abort 即 killTree;
+// 这里的进程必须**跨工具调用存活**,所以生命周期只由显式 stop 或进程退出 / 全局 shutdown 决定。
+// 传入的 signal 只用于取消「启动 + 就绪等待」,绝不用于杀已就绪的服务 —— 否则用户下一次
+// Ctrl+C 会顺手把 dev server 干掉。
+//
+// 非安全边界:命令仍是任意 shell 命令(与 run_command 同级风险),故工具层声明 dangerous 风险,
+// 由权限系统在执行前向用户确认。
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, openSync, writeSync } from 'node:fs';
+import { mkdir, open, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { filterEnv, getSandboxRoot, isCommandDenied, jailResolve } from '../sandbox/index.js';
+export class DevServerManagerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DevServerManagerError';
+    }
+}
+const servers = new Map();
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const MAX_READY_TIMEOUT_MS = 180_000;
+const READY_POLL_INTERVAL_MS = 250;
+const PROBE_TIMEOUT_MS = 2_000;
+const STOP_GRACE_MS = 1_500;
+const DEFAULT_LOG_BYTES = 8_000;
+const MAX_LOG_BYTES = 64_000;
+const RECENT_LOG_CHARS = 4_000;
+const IS_WINDOWS = process.platform === 'win32';
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** 进程是否仍存活;EPERM 说明 pid 存在但不属于当前用户。 */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function snapshot(record) {
+    return {
+        id: record.id,
+        pid: record.pid,
+        state: record.state,
+        exitCode: record.exitCode,
+        signal: record.signal,
+        command: record.command,
+        cwd: record.cwd,
+        logPath: record.logPath,
+        startedAt: record.startedAt,
+    };
+}
+function requireRecord(id) {
+    const record = servers.get(id);
+    if (!record) {
+        const known = [...servers.keys()];
+        throw new DevServerManagerError('INVALID_ARGUMENTS', known.length
+            ? `Unknown dev server id "${id}". Known ids: ${known.join(', ')}.`
+            : `Unknown dev server id "${id}". No dev server has been started in this session.`);
+    }
+    return record;
+}
+/** 只允许回环地址:防止 agent 借就绪探测去扫内网 / 打外网。 */
+function validateReadyUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new DevServerManagerError('INVALID_ARGUMENTS', `Invalid readyUrl: ${input}`);
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const loopback = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new DevServerManagerError('INVALID_ARGUMENTS', 'readyUrl must use http or https.');
+    }
+    if (!loopback || url.username || url.password) {
+        throw new DevServerManagerError('INVALID_ARGUMENTS', 'readyUrl must target localhost, 127.0.0.1, or ::1 without credentials.');
+    }
+    return url;
+}
+function compileReadyPattern(input) {
+    try {
+        return new RegExp(input, 'i');
+    }
+    catch (error) {
+        throw new DevServerManagerError('INVALID_ARGUMENTS', `Invalid readyPattern: ${errorMessage(error)}`);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(new DevServerManagerError('ABORTED', 'Dev server startup wait was aborted.'));
+        };
+        if (signal?.aborted) {
+            abort();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+/** 任意 HTTP 响应都算就绪:dev server 常在 / 返回 404 但端口已可用。 */
+async function probeReady(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        await fetch(url, { signal: controller.signal, redirect: 'manual' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function killTree(pid) {
+    try {
+        if (IS_WINDOWS) {
+            spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        else {
+            process.kill(pid, 'SIGTERM');
+        }
+    }
+    catch {
+        // 已退出或无权限:best-effort。
+    }
+}
+function finalizeExit(record, code, signalCode) {
+    record.state = record.stopRequested ? 'stopped' : 'exited';
+    record.exitCode = code;
+    record.signal = signalCode;
+    if (record.logFd !== null) {
+        try {
+            closeSync(record.logFd);
+        }
+        catch {
+            // 忽略:进程收尾期文件句柄可能已失效。
+        }
+        record.logFd = null;
+    }
+}
+/** 进程可能在事件回调之外被外部杀掉,读状态时顺带对账。 */
+function reconcile(record) {
+    if (record.state === 'running' && !isAlive(record.pid)) {
+        finalizeExit(record, record.child.exitCode, record.child.signalCode);
+    }
+    return record;
+}
+export async function startDevServer(opts) {
+    const command = opts.command.trim();
+    if (!command) {
+        throw new DevServerManagerError('INVALID_ARGUMENTS', 'command is required to start a dev server.');
+    }
+    const denied = isCommandDenied(command);
+    if (denied) {
+        throw new DevServerManagerError('SANDBOX_DENIED', denied);
+    }
+    const root = getSandboxRoot() ?? process.cwd();
+    let cwd = root;
+    if (opts.cwd) {
+        try {
+            cwd = jailResolve(opts.cwd);
+        }
+        catch (error) {
+            throw new DevServerManagerError('SANDBOX_DENIED', errorMessage(error));
+        }
+    }
+    const readyUrl = opts.readyUrl ? validateReadyUrl(opts.readyUrl) : null;
+    const readyPattern = opts.readyPattern ? compileReadyPattern(opts.readyPattern) : null;
+    const timeoutMs = Math.min(Math.max(Number(opts.timeoutMs ?? DEFAULT_READY_TIMEOUT_MS), 1_000), MAX_READY_TIMEOUT_MS);
+    const id = `srv-${randomBytes(3).toString('hex')}`;
+    const logPath = jailResolve(join('.mocode', 'dev-servers', `${id}.log`));
+    await mkdir(dirname(logPath), { recursive: true });
+    let logFd;
+    try {
+        logFd = openSync(logPath, 'a');
+    }
+    catch (error) {
+        throw new DevServerManagerError('EXECUTION_ERROR', `Unable to open log file: ${errorMessage(error)}`);
+    }
+    let child;
+    try {
+        child = spawn(IS_WINDOWS ? 'cmd.exe' : 'bash', IS_WINDOWS ? ['/d', '/s', '/c', command] : ['-c', command], {
+            cwd,
+            env: filterEnv(process.env),
+            windowsVerbatimArguments: IS_WINDOWS,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        closeSync(logFd);
+        throw new DevServerManagerError('EXECUTION_ERROR', `Unable to spawn dev server: ${errorMessage(error)}`);
+    }
+    if (child.pid === undefined) {
+        closeSync(logFd);
+        throw new DevServerManagerError('EXECUTION_ERROR', 'Dev server process did not report a pid.');
+    }
+    const record = {
+        id,
+        pid: child.pid,
+        state: 'running',
+        exitCode: null,
+        signal: null,
+        command,
+        cwd,
+        logPath,
+        startedAt: new Date().toISOString(),
+        child,
+        logFd,
+        stopRequested: false,
+        recentLog: '',
+    };
+    servers.set(id, record);
+    const onChunk = (chunk) => {
+        const text = chunk.toString('utf8');
+        record.recentLog = (record.recentLog + text).slice(-RECENT_LOG_CHARS);
+        if (record.logFd === null)
+            return;
+        try {
+            writeSync(record.logFd, text);
+        }
+        catch {
+            // 日志写失败不影响进程本身。
+        }
+    };
+    child.stdout?.on('data', onChunk);
+    child.stderr?.on('data', onChunk);
+    child.on('error', (error) => onChunk(Buffer.from(`\n[spawn error] ${error.message}\n`)));
+    child.on('close', (code, signalCode) => finalizeExit(record, code, signalCode));
+    const deadline = Date.now() + timeoutMs;
+    const wantsReadySignal = Boolean(readyUrl || readyPattern);
+    let ready = false;
+    try {
+        while (wantsReadySignal && Date.now() < deadline) {
+            if (record.state !== 'running') {
+                throw new DevServerManagerError('PROCESS_FAILED', `Dev server exited before becoming ready (exitCode=${record.exitCode ?? 'null'}). Recent output:\n${record.recentLog.trim() || '(no output)'}`);
+            }
+            if (readyPattern?.test(record.recentLog)) {
+                ready = true;
+                break;
+            }
+            if (readyUrl && await probeReady(readyUrl)) {
+                ready = true;
+                break;
+            }
+            await sleep(READY_POLL_INTERVAL_MS, opts.signal);
+        }
+    }
+    catch (error) {
+        // 启动失败 / 被中断:不留孤儿进程。
+        record.stopRequested = true;
+        killTree(record.pid);
+        finalizeExit(record, record.child.exitCode, record.child.signalCode);
+        throw error;
+    }
+    if (wantsReadySignal && !ready) {
+        record.stopRequested = true;
+        killTree(record.pid);
+        finalizeExit(record, record.child.exitCode, record.child.signalCode);
+        throw new DevServerManagerError('TIMEOUT', `Dev server did not become ready within ${timeoutMs}ms and was stopped. Recent output:\n${record.recentLog.trim() || '(no output)'}`);
+    }
+    return {
+        ...snapshot(reconcile(record)),
+        ready,
+        ...(opts.readyUrl ? { readyUrl: opts.readyUrl } : {}),
+        ...(opts.readyPattern ? { readyPattern: opts.readyPattern } : {}),
+        ...(record.recentLog.trim() ? { logTail: record.recentLog.trim().slice(-1_000) } : {}),
+    };
+}
+export function listDevServers() {
+    return [...servers.values()].map((record) => snapshot(reconcile(record)));
+}
+export function getDevServerStatus(id) {
+    if (!id)
+        return listDevServers();
+    return [snapshot(reconcile(requireRecord(id)))];
+}
+export async function readDevServerLogs(id, opts = {}) {
+    const record = reconcile(requireRecord(id));
+    const size = (await stat(record.logPath).catch(() => null))?.size ?? 0;
+    const limit = Math.min(Math.max(Number(opts.limit ?? DEFAULT_LOG_BYTES), 1), MAX_LOG_BYTES);
+    // 缺省读尾部(最新输出);显式 offset 支持增量轮询。
+    const requested = opts.offset === undefined ? Math.max(0, size - limit) : Math.max(0, Number(opts.offset));
+    const start = Math.min(requested, size);
+    const length = Math.min(limit, size - start);
+    let content = '';
+    if (length > 0) {
+        const handle = await open(record.logPath, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            await handle.read(buffer, 0, length, start);
+            content = buffer.toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return {
+        id: record.id,
+        state: record.state,
+        offset: start,
+        nextOffset: start + length,
+        size,
+        hasMore: start + length < size,
+        content,
+    };
+}
+export async function stopDevServer(id) {
+    const record = reconcile(requireRecord(id));
+    if (record.state !== 'running') {
+        return { ...snapshot(record), alreadyStopped: true };
+    }
+    record.stopRequested = true;
+    killTree(record.pid);
+    const deadline = Date.now() + STOP_GRACE_MS;
+    while (Date.now() < deadline && isAlive(record.pid)) {
+        await sleep(50);
+    }
+    if (isAlive(record.pid) && !IS_WINDOWS) {
+        try {
+            process.kill(record.pid, 'SIGKILL');
+        }
+        catch {
+            // 已退出。
+        }
+    }
+    finalizeExit(record, record.child.exitCode, record.child.signalCode);
+    return { ...snapshot(record), alreadyStopped: false };
+}
+/** 全局退出清理:同步树杀所有仍存活的后台进程。可重复调用。 */
+export function stopAllDevServersSync() {
+    for (const record of servers.values()) {
+        if (record.state !== 'running')
+            continue;
+        record.stopRequested = true;
+        killTree(record.pid);
+        finalizeExit(record, record.child.exitCode, record.child.signalCode);
+    }
+}

package/dist/runtime/shutdown.js

@@ -0,0 +1,26 @@
+// 常驻资源的统一退出清理。
+//
+// 后台 dev server 是我们自己 spawn 的子进程,进程退出不会自动带走(Windows 尤其),必须显式树杀;
+// Playwright 浏览器进程在正常路径 await close(),硬退出路径依赖 Playwright 自身的 exit 处理。
+// 两个入口都必须幂等:normal exit / SIGINT / uncaughtException 可能重复触发。
+import { stopAllDevServersSync } from './dev-server-manager.js';
+let asyncDone = false;
+/** 正常退出路径:可 await,尽量优雅关闭。 */
+export async function shutdownRuntime() {
+    if (asyncDone)
+        return;
+    asyncDone = true;
+    stopAllDevServersSync();
+    try {
+        // 动态 import:未用过 browser 工具时不该把 playwright 拉进进程。
+        const { closeAllBrowsers } = await import('./browser-manager.js');
+        await closeAllBrowsers();
+    }
+    catch {
+        // 浏览器从未启动或已崩溃:忽略。
+    }
+}
+/** 同步兜底(process exit / 信号 / 未捕获异常):只做同步树杀,不留孤儿 dev server。 */
+export function shutdownRuntimeSync() {
+    stopAllDevServersSync();
+}