@steerable/agent-shell 0.6.15

package/dist/server/http-server.js

@@ -0,0 +1,361 @@
+/**
+ * BS 模式 HTTP server：把 CS（Electron）模式下挂在 IPC 后面的同一组服务
+ * 暴露成真正的 HTTP 接口，并托管 apps/web/dist 静态产物。
+ *
+ * 路由分三层：
+ *   - `/api/v2/*`        → LocalBackendRouter（chat / 设置 / 技能 / MCP …），
+ *                          与 Electron 下 `local-backend:request` 同一入口；
+ *                          流式路径（chats/:id/run|send|agent、…/regenerate）
+ *                          走 handleStream，响应即标准 SSE。
+ *   - `GET /api/v2/events` → SseBus 事件总线（替代 webContents.send 广播）。
+ *   - `/host/*`          → preload 里 direct-IPC 能力的 HTTP 等价物
+ *                          （terminal / local / approval 为宿主自带；
+ *                          场景包路由经 host/http-routes 注册表匹配）。
+ *
+ * 安全约定：默认绑定 127.0.0.1、无认证——本机自用定位（与 Electron 版相同
+ * 的信任模型：能到端口 = 本机用户）。不要绑到非回环地址，那会把 shell /
+ * 文件读写 / 场景包工具控制暴露给整个网络。
+ */
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import log from 'electron-log';
+import { getActiveCoreLoopStreamId } from '../local-backend/coreloop-stream.js';
+import { getSidecarSupervisor } from '../llm/index.js';
+import { localStore } from '../storage/index.js';
+import { matchPackHttpRoute } from '../host/http-routes.js';
+import { getBrand } from '../brand.js';
+import { saveAttachmentFiles } from '../attachments.js';
+/** 与 router.handleStream 内部的路由正则保持一致——只有这些路径是流式。 */
+const STREAM_PATH_PATTERNS = [
+    /^\/api\/v2\/chats\/[^/]+\/(send|run|agent)$/,
+    /^\/api\/v2\/chats\/[^/]+\/messages\/[^/]+\/regenerate$/,
+];
+const MAX_BODY_BYTES = 25 * 1024 * 1024;
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.txt': 'text/plain; charset=utf-8',
+};
+function sendJson(res, status, data) {
+    const body = JSON.stringify(data ?? null);
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+    });
+    res.end(body);
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('request body too large');
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+function asRecord(body) {
+    return body && typeof body === 'object' ? body : {};
+}
+export function createBsServer(deps) {
+    const { localBackendRouter, localExecutor, localScriptRegistry, terminalManager, approvalBridge, askUserBridge, maybeExecInTerminal, bus, webDistDir, } = deps;
+    async function handleApi(req, res, pathname) {
+        const isStream = req.method === 'POST' && STREAM_PATH_PATTERNS.some((p) => p.test(pathname));
+        const body = req.method === 'POST' || req.method === 'PATCH' || req.method === 'PUT'
+            ? await readJsonBody(req)
+            : undefined;
+        const search = new URL(req.url ?? '/', 'http://bs.local').search;
+        const request = { method: req.method ?? 'GET', path: `${pathname}${search}`, body };
+        if (isStream) {
+            const controller = new AbortController();
+            // 浏览器关页/取消 fetch → 中止 agent 循环（对齐 Electron 的 cancelStream）。
+            req.on('close', () => controller.abort());
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream; charset=utf-8',
+                'Cache-Control': 'no-cache, no-transform',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no',
+            });
+            try {
+                const result = await localBackendRouter.handleStream(request, (chunk) => res.write(chunk), { signal: controller.signal });
+                log.info(`[bs] stream ${request.method} ${pathname} -> ${result.status}`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                log.error(`[bs] stream ${request.method} ${pathname} threw`, err);
+                try {
+                    res.write(`event: error\ndata: ${JSON.stringify({ message })}\n\n`);
+                }
+                catch { /* client gone */ }
+            }
+            finally {
+                res.end();
+            }
+            return;
+        }
+        try {
+            const response = await localBackendRouter.handle(request);
+            log.info(`[bs] ${request.method} ${pathname} -> ${response.status}`);
+            sendJson(res, response.status, response.data);
+        }
+        catch (err) {
+            log.error(`[bs] ${request.method} ${pathname} threw`, err);
+            sendJson(res, 500, { detail: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    /** `/host/*`：preload direct-IPC 的 HTTP 等价物。全部 POST JSON，除标记 GET 的。 */
+    async function handleHost(req, res, pathname) {
+        const body = asRecord(await readJsonBody(req));
+        const method = req.method ?? 'GET';
+        if (method === 'GET' && pathname === '/host/info') {
+            const brand = getBrand();
+            sendJson(res, 200, {
+                runtime: 'bs',
+                platform: process.platform,
+                flavor: brand.flavor,
+                brandName: brand.displayName,
+            });
+            return;
+        }
+        // ─── terminal（对齐 main.ts 的 terminal:* IPC） ───
+        if (method === 'GET' && pathname === '/host/terminal/list') {
+            sendJson(res, 200, terminalManager.list());
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/terminal/spawn') {
+            sendJson(res, 200, terminalManager.spawn(body));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/terminal/ensure') {
+            const session = terminalManager.ensurePrimary(body);
+            // 对齐 Electron ensure：附带 attach 前的 replay buffer，前端补写一次。
+            const replay = terminalManager.getReplayBuffer(session.id);
+            sendJson(res, 200, { session, replay: replay ?? '' });
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/terminal/write') {
+            sendJson(res, 200, terminalManager.write(String(body.id ?? ''), String(body.data ?? '')));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/terminal/resize') {
+            sendJson(res, 200, terminalManager.resize(String(body.id ?? ''), Number(body.cols ?? 80), Number(body.rows ?? 24)));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/terminal/kill') {
+            sendJson(res, 200, terminalManager.kill(String(body.id ?? '')));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/terminal/exec') {
+            let id = typeof body.id === 'string' ? body.id : undefined;
+            if (!id)
+                id = terminalManager.ensurePrimary().id;
+            try {
+                const result = await terminalManager.exec(id, String(body.command ?? ''), body.timeoutMs);
+                sendJson(res, 200, result);
+            }
+            catch (err) {
+                sendJson(res, 200, {
+                    success: false,
+                    exitCode: -1,
+                    stdout: '',
+                    stderr: err instanceof Error ? err.message : String(err),
+                    truncated: false,
+                    durationMs: 0,
+                });
+            }
+            return;
+        }
+        // ─── 轮中转向（对齐 local-backend:steer IPC；不走 router） ───
+        if (method === 'POST' && pathname === '/host/steer') {
+            const chatId = typeof body.chatId === 'string' ? body.chatId : '';
+            const content = typeof body.content === 'string' ? body.content : '';
+            if (!chatId || !content.trim()) {
+                sendJson(res, 200, { ok: false, reason: 'invalid_params' });
+                return;
+            }
+            const streamId = getActiveCoreLoopStreamId(chatId);
+            const supervisor = getSidecarSupervisor();
+            if (!streamId || !supervisor) {
+                sendJson(res, 200, { ok: false, reason: 'no_active_coreloop_turn' });
+                return;
+            }
+            const ok = await supervisor.steerChat(streamId, content);
+            // 与 main.ts 同理：接受即落库，重开对话能看到这条注入的用户消息。
+            if (ok)
+                localStore.addMessage(chatId, 'user', content);
+            sendJson(res, 200, { ok, ...(ok ? {} : { reason: 'stream_not_active' }) });
+            return;
+        }
+        // ─── approval（对齐 approval:decide IPC） ───
+        if (method === 'POST' && pathname === '/host/approval/decide') {
+            sendJson(res, 200, await approvalBridge.decide(body));
+            return;
+        }
+        // ─── ask_user（对齐 ask-user:answer IPC） ───
+        if (method === 'POST' && pathname === '/host/ask-user/answer') {
+            sendJson(res, 200, askUserBridge.answer(body));
+            return;
+        }
+        // ─── local（对齐 local:* IPC） ───
+        if (method === 'POST' && pathname === '/host/local/exec-shell') {
+            const request = body;
+            const viaTerminal = await maybeExecInTerminal(request);
+            sendJson(res, 200, viaTerminal ?? (await localExecutor.executeShell(request)));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/read-file') {
+            sendJson(res, 200, await localExecutor.readLocalFile(body));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/write-file') {
+            sendJson(res, 200, await localExecutor.writeLocalFile(body));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/open-path') {
+            sendJson(res, 200, await localExecutor.openLocalTarget(body));
+            return;
+        }
+        if (method === 'GET' && pathname === '/host/local/scripts') {
+            sendJson(res, 200, localScriptRegistry.list());
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/scripts/add') {
+            sendJson(res, 200, localScriptRegistry.create(body));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/scripts/update') {
+            sendJson(res, 200, localScriptRegistry.update(String(body.id ?? ''), (body.updates ?? {})));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/scripts/delete') {
+            localScriptRegistry.delete(String(body.id ?? ''));
+            sendJson(res, 200, { success: true });
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/scripts/run') {
+            const script = localScriptRegistry.getById(String(body.id ?? ''));
+            if (!script) {
+                sendJson(res, 200, { success: false, error: `Script not found: ${String(body.id ?? '')}` });
+                return;
+            }
+            sendJson(res, 200, await localExecutor.executeShell({
+                command: script.command,
+                cwd: script.cwd,
+                timeout: script.timeout,
+            }));
+            return;
+        }
+        if (method === 'POST' && pathname === '/host/local/update-safety-config') {
+            localExecutor.updateSafetyConfig(body);
+            sendJson(res, 200, { success: true });
+            return;
+        }
+        // ─── 场景包路由（0.4：/host/<pack>/* 由包经 host/http-routes 注册表
+        // 贡献；在宿主自带路由之后、404 之前统一匹配，包不能遮蔽宿主路由）。
+        // host 端点目前不用 query string，query 先传空表。 ───
+        const packMatch = matchPackHttpRoute(method, pathname);
+        if (packMatch) {
+            sendJson(res, 200, await packMatch.route.handler({
+                params: packMatch.params,
+                query: {},
+                body,
+            }));
+            return;
+        }
+        // ─── 会话附件（对齐 attachments:save IPC；BS 用 base64 字节） ───
+        if (method === 'POST' && pathname === '/host/attachments/save') {
+            const chatId = typeof body.chatId === 'string' ? body.chatId : '';
+            const files = Array.isArray(body.files)
+                ? body.files.filter((f) => f && (typeof f.path === 'string' || typeof f.data === 'string'))
+                : [];
+            sendJson(res, 200, await saveAttachmentFiles(chatId, files));
+            return;
+        }
+        sendJson(res, 404, { detail: `Unknown host endpoint: ${method} ${pathname}` });
+    }
+    /** 静态托管 + index.html 注入 BS 标记（前端据此切换 http-bridge）。 */
+    async function serveStatic(req, res, pathname) {
+        const rel = pathname === '/' ? '/index.html' : pathname;
+        const filePath = path.join(webDistDir, path.normalize(rel).replace(/^([/\\])+/, ''));
+        if (!filePath.startsWith(webDistDir)) {
+            sendJson(res, 403, { detail: 'forbidden' });
+            return;
+        }
+        const target = existsSync(filePath) && !filePath.endsWith(path.sep) ? filePath : path.join(webDistDir, 'index.html');
+        try {
+            let content = await readFile(target);
+            const ext = path.extname(target).toLowerCase();
+            if (ext === '.html') {
+                // 注入 BS 引导信息：platform 是 preload 里的同步字段，http-bridge
+                // 需要同步可见；brand 让 <title>/favicon 在 bridge 就绪前就正确。
+                const brand = getBrand();
+                const bootstrap = `<script>window.__DEEPPATH_BS__=${JSON.stringify({
+                    platform: process.platform,
+                    flavor: brand.flavor,
+                    brandName: brand.displayName,
+                })};</script>`;
+                content = content.toString('utf8').replace('<head>', `<head>${bootstrap}`);
+            }
+            res.writeHead(200, {
+                'Content-Type': MIME[ext] ?? 'application/octet-stream',
+                'Cache-Control': ext === '.html' ? 'no-cache' : 'public, max-age=3600',
+            });
+            res.end(content);
+        }
+        catch (err) {
+            log.warn('[bs] static read failed', { target, err });
+            sendJson(res, 404, { detail: 'not found' });
+        }
+    }
+    return createServer((req, res) => {
+        void (async () => {
+            const url = new URL(req.url ?? '/', 'http://bs.local');
+            const pathname = url.pathname;
+            if (pathname === '/api/v2/events' && req.method === 'GET') {
+                bus.attach(res);
+                return;
+            }
+            if (pathname.startsWith('/api/v2/')) {
+                await handleApi(req, res, pathname);
+                return;
+            }
+            if (pathname.startsWith('/host/')) {
+                await handleHost(req, res, pathname);
+                return;
+            }
+            if (req.method === 'GET' || req.method === 'HEAD') {
+                await serveStatic(req, res, pathname);
+                return;
+            }
+            sendJson(res, 404, { detail: 'not found' });
+        })().catch((err) => {
+            log.error('[bs] unhandled request error', err);
+            if (!res.headersSent)
+                sendJson(res, 500, { detail: 'internal error' });
+            else
+                res.end();
+        });
+    });
+}

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/index.js

@@ -0,0 +1,107 @@
+/**
+ * BS 模式入口：`node dist/server/index.js`。
+ *
+ * 装配与 Electron 主进程（main.ts）相同的一组服务——同一份装配住在
+ * src/host/runtime.ts（HostRuntime），这里只保留 BS 特有的部分：SSE
+ * 总线广播、HTTP 出口（http-server.ts）、SIGINT/SIGTERM 生命周期。
+ * 数据目录、sidecar、工具链、审批流全部共用；两种模式因此操作同一份
+ * SQLite / JSON 配置（不要同时启动两个宿主——write-lease 会拒绝第二个写者）。
+ *
+ * 默认绑定 127.0.0.1:4787（DEEPPATH_BS_HOST / DEEPPATH_BS_PORT 可改）。
+ * 无认证：与桌面版同一信任模型，不要暴露到非回环地址。
+ */
+// 产品组装根必须是第一个 import：包迁移注册要先于 storage 单例构造（0.3b）。
+// 产品组装根（products/<id>/server.ts 或 devtools/dev-server.ts）必须先于
+// 本模块完成 import：包迁移注册要先于 storage 单例构造（0.3b / 2.3）。
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import log from 'electron-log';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// 与 main.ts 相同的 .env 加载顺序（.env.local 优先；已有环境变量胜出）。
+(function loadDotenvFiles() {
+    const repoRoot = path.resolve(__dirname, '..', '..');
+    for (const file of ['.env.local', '.env']) {
+        const fullPath = path.join(repoRoot, file);
+        if (existsSync(fullPath))
+            dotenv.config({ path: fullPath, override: false });
+    }
+})();
+import { getBrand } from '../brand.js';
+import { getUserDataDir } from '../runtime.js';
+import { createHostRuntime } from '../host/runtime.js';
+import { registerPackHttpRoutes } from '../host/http-routes.js';
+import { SseBus } from './sse-bus.js';
+import { createBsServer } from './http-server.js';
+// BS 模式没有 Electron 的 userData 概念，electron-log 默认会写
+// ~/.config/<name>/logs；在 HOME 只读（容器/只读环境）或用户显式指定
+// DEEPPATH_USER_DATA_DIR 时，日志应跟随应用数据目录走。
+log.transports.file.resolvePathFn = () => path.join(getUserDataDir(), 'logs', 'main.log');
+async function main() {
+    const brand = getBrand();
+    const bus = new SseBus();
+    const broadcast = (channel, payload) => bus.broadcast(channel, payload);
+    // 与 CS 同一份服务装配；BS 的差异只有广播（SSE 总线）与"有浏览器连着
+    // 事件总线 = 有人能应答审批/提问"的 hasWindow 判定。
+    const runtime = createHostRuntime({
+        broadcast,
+        hasWindow: () => bus.size > 0,
+        onLog: (line) => log.info('[sidecar]', line),
+        taskSweepReason: '服务重启，任务流已中断',
+    });
+    const { localExecutor, localScriptRegistry, terminalManager, packHandles, localBackendRouter, approvalBridge, askUserBridge, maybeExecInTerminal, } = runtime;
+    // 2.3 起 web 产物按产品构建：产品入口注入 DEEPPATH_WEB_DIST
+    //（products/<id>/web/dist）；缺省回退到 shell 包自带的 web/dist
+    //（packages/agent-shell/web/dist），仅用于给出可读的报错。
+    const webDistDir = process.env.DEEPPATH_WEB_DIST ??
+        path.join(__dirname, '..', '..', 'web', 'dist');
+    if (!existsSync(path.join(webDistDir, 'index.html'))) {
+        console.error(`[bs] web build not found at ${webDistDir} — run \`pnpm build\` first.`);
+        process.exit(1);
+    }
+    // 场景包 HTTP 路由（/host/<packId>/*）由装配产物给出，宿主循环注册
+    //（2.3；路由路径命名空间由 registerPackHttpRoutes 校验）。
+    for (const [packId, handle] of packHandles) {
+        const routes = handle.httpRoutes?.();
+        if (routes)
+            registerPackHttpRoutes(packId, routes);
+    }
+    const server = createBsServer({
+        localBackendRouter,
+        localExecutor,
+        localScriptRegistry,
+        terminalManager,
+        approvalBridge,
+        askUserBridge,
+        maybeExecInTerminal,
+        bus,
+        webDistDir,
+    });
+    const host = process.env.DEEPPATH_BS_HOST || '127.0.0.1';
+    const port = Number(process.env.DEEPPATH_BS_PORT || 4787);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    console.log(`[bs] ${brand.displayName} server listening at http://${host}:${port}  (flavor=${brand.flavor})`);
+    // 任务清扫 / mock 广播 / sidecar 启动 / MCP 刷新 / 终端预热。不阻塞
+    // HTTP 就绪；竞速的回合由 router 回退处理（同 main.ts）。
+    runtime.start();
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log('[bs] shutting down…');
+        void runtime.shutdown().finally(() => process.exit(0));
+        // 兜底：sidecar 卡住也不拖住退出。
+        setTimeout(() => process.exit(0), 5_000).unref();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    console.error('[bs] failed to start:', err);
+    process.exit(1);
+});

package/dist/server/sse-bus.d.ts

@@ -0,0 +1,14 @@
+/**
+ * BS 模式的 SSE 事件总线：替代 Electron 的 `webContents.send(channel, payload)`
+ * 广播。所有宿主事件（terminal:data、approval:request、chat-title-updated、
+ * 场景包事件……）经这一条 `GET /api/v2/events` 长连接推给浏览器，
+ * channel 名与 IPC 通道保持一致，前端 http-bridge 按名分发。
+ */
+import type { ServerResponse } from 'node:http';
+export declare class SseBus {
+    private readonly clients;
+    /** 已连接浏览器数；approval 桥用它判断"有没有人能应答"（对齐 hasWindow）。 */
+    get size(): number;
+    attach(res: ServerResponse): void;
+    broadcast(channel: string, payload: unknown): void;
+}

package/dist/server/sse-bus.js

@@ -0,0 +1,31 @@
+export class SseBus {
+    clients = new Set();
+    /** 已连接浏览器数；approval 桥用它判断"有没有人能应答"（对齐 hasWindow）。 */
+    get size() {
+        return this.clients.size;
+    }
+    attach(res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        res.write(': connected\n\n');
+        this.clients.add(res);
+        res.on('close', () => this.clients.delete(res));
+    }
+    broadcast(channel, payload) {
+        if (this.clients.size === 0)
+            return;
+        const frame = `event: ${channel}\ndata: ${JSON.stringify(payload ?? null)}\n\n`;
+        for (const res of this.clients) {
+            try {
+                res.write(frame);
+            }
+            catch {
+                this.clients.delete(res);
+            }
+        }
+    }
+}

package/dist/shell-adapt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cross-dialect command adaptation for Windows PowerShell 5.1.
+ *
+ * LLM 生成的命令经常混用 cmd / bash 语法（`&&`、`||`、`%VAR%`），而我们在
+ * Windows 上默认用 `powershell.exe`（= Windows PowerShell 5.1，**不支持**
+ * Bash 风格的 `&&` / `||` 链接符，也不认识 `%VAR%` 环境变量语法）。
+ * 与其指望模型每次都写对方言，不如在执行前做一次确定性转换：
+ *
+ *   - `%VAR%`        → `$env:VAR`
+ *   - `A && B`       → `A; if ($?) { B }`
+ *   - `A || B`       → `A; if (-not $?) { B }`
+ *   - `A && B && C`  → `A; if ($?) { B; if ($?) { C } }`（从右往左嵌套）
+ *
+ * 引号内的 `&&` / `||` / `%VAR%` 不会被改写（按单双引号做词法扫描）。
+ * 转换是幂等的：已经是纯 PowerShell 语法的命令原样返回。
+ */
+/**
+ * 把混用 cmd / bash 语法的命令转换成 Windows PowerShell 5.1 可执行的形式。
+ * 对已经合法的 PowerShell 命令是 no-op。
+ */
+export declare function adaptCommandForPowerShell(command: string): string;

package/dist/shell-adapt.js

@@ -0,0 +1,104 @@
+/**
+ * Cross-dialect command adaptation for Windows PowerShell 5.1.
+ *
+ * LLM 生成的命令经常混用 cmd / bash 语法（`&&`、`||`、`%VAR%`），而我们在
+ * Windows 上默认用 `powershell.exe`（= Windows PowerShell 5.1，**不支持**
+ * Bash 风格的 `&&` / `||` 链接符，也不认识 `%VAR%` 环境变量语法）。
+ * 与其指望模型每次都写对方言，不如在执行前做一次确定性转换：
+ *
+ *   - `%VAR%`        → `$env:VAR`
+ *   - `A && B`       → `A; if ($?) { B }`
+ *   - `A || B`       → `A; if (-not $?) { B }`
+ *   - `A && B && C`  → `A; if ($?) { B; if ($?) { C } }`（从右往左嵌套）
+ *
+ * 引号内的 `&&` / `||` / `%VAR%` 不会被改写（按单双引号做词法扫描）。
+ * 转换是幂等的：已经是纯 PowerShell 语法的命令原样返回。
+ */
+/** 把 cmd 风格的 `%VAR%` 环境变量替换成 PowerShell 的 `$env:VAR`。 */
+function replaceCmdEnvVars(command) {
+    let out = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            out += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === '%') {
+            const m = command.slice(i).match(/^%([A-Za-z_][A-Za-z0-9_]*)%/);
+            if (m) {
+                out += `$env:${m[1]}`;
+                i += m[0].length - 1;
+                continue;
+            }
+        }
+        out += ch;
+    }
+    return out;
+}
+/** 按引号感知拆分顶层 `&&` / `||` 链。没有链接符时返回 null。 */
+function splitChain(command) {
+    const parts = [];
+    const ops = [];
+    let current = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        const two = command.slice(i, i + 2);
+        if (two === '&&' || two === '||') {
+            parts.push(current);
+            ops.push(two);
+            current = '';
+            i++;
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    if (ops.length === 0)
+        return null;
+    const trimmed = parts.map(p => p.trim());
+    // 任一段为空（如 "foo &&" 结尾）说明命令本身畸形，不做改写。
+    if (trimmed.some(p => p.length === 0))
+        return null;
+    return { parts: trimmed, ops };
+}
+/**
+ * 把混用 cmd / bash 语法的命令转换成 Windows PowerShell 5.1 可执行的形式。
+ * 对已经合法的 PowerShell 命令是 no-op。
+ */
+export function adaptCommandForPowerShell(command) {
+    if (!command)
+        return command;
+    let out = replaceCmdEnvVars(command);
+    const chain = splitChain(out);
+    if (chain) {
+        const { parts, ops } = chain;
+        // 从右往左嵌套构造，保持 && / || 的短路语义。
+        let acc = parts[parts.length - 1];
+        for (let i = ops.length - 1; i >= 0; i--) {
+            const cond = ops[i] === '&&' ? '$?' : '-not $?';
+            acc = `${parts[i]}; if (${cond}) { ${acc} }`;
+        }
+        out = acc;
+    }
+    return out;
+}