@xiaoqiong0v0/opencode-ssh-tool 0.7.0 → 0.7.2

package/dist/precheck.js

@@ -1,7 +1,12 @@
 // 发送前语法预检（term_exec / web run-exec 共用）：
 // 只解析、绝不执行；命中语法错误即拦下并返回文案，模块自身异常一律放行。
+// - 本地会话：走 parse-check（本机/容器的校验器：pwsh 解析侧车 / `bash -n`、`zsh -n`）。
+// - SSH 远程：走会话提供的 `precheckSyntax`（独立 exec channel：bash/zsh 跑 `-n`，
+//   pwsh 启动解析侧车；不占 PTY）；两者互不复用，远程通道异常/超时一律 fail-open。
+//   CMD 没有安全的 parse-only 通道，明确跳过（只查 shell 语法，不查 Python/Node 等程序代码）。
 // 单独成文件是为了让 index（工具入口）与 agent（web 执行入口）共用，避免 index↔agent 循环依赖。
 import { stripCommandTail } from "./base-session.js";
+import { REMOTE_PRECHECK_TIMEOUT_MS } from "./constants.js";
 import { validateCommand } from "./parse-check.js";
 import log from "./log.js";
 import { getToolLang, tr } from "./i18n.js";
@@ -9,6 +14,8 @@ import { getToolLang, tr } from "./i18n.js";
 const SYNTAX_REJECT_MAX_ERRORS = 5;
 /** 拦截消息里出错片段的展示长度上限（超长截断，保留可定位性） */
 const SYNTAX_ISSUE_TEXT_MAX = 60;
+/** 远程预检提取出错片段的长度上限（字符）：避免把超长命令整行塞进拦截文案 */
+const REMOTE_SYNTAX_FRAGMENT_MAX = 200;
 /**
  * 适配器名 → parse-check 的 shell 标识（shell-adapter 的 `name` 与 classifyShell 兼容）。
  * 未列出的适配器（cmd 等）不校验、直接放行；bash/zsh 各自走 `bash -n`/`zsh -n`，
@@ -72,20 +79,36 @@ export function formatSyntaxRejection(command, errors, lang) {
     const more = errors.length > shown.length ? `${sep}${fillTemplate(tr("precheck_more", lang), { n: errors.length })}` : "";
     return `${tr("precheck_failed", lang)}${lang === "zh" ? "：" : ": "}${body}${more}`;
 }
+/**
+ * 远程预检的出错片段：优先取命令中出错行的原文，取不到再退回解析器输出首行。
+ * 结果压成单行并限制长度，避免把整条超长命令回显进拦截文案。
+ * @param command 待发送的命令文本
+ * @param line 解析出的错误行号（1 起；0/非法时只看 fallback）
+ * @param fallback 解析器 stderr（用于取首行）
+ * @returns 单行片段（可能为空串）
+ */
+export function pickSyntaxErrorText(command, line, fallback) {
+    const fromCommand = line > 0 ? (command.split(/\r?\n/)[line - 1] ?? "") : "";
+    const source = fromCommand.trim() ? fromCommand : (fallback.split(/\r?\n/)[0] ?? "");
+    const flat = source.replace(/\s+/g, " ").trim();
+    return flat.length > REMOTE_SYNTAX_FRAGMENT_MAX ? `${flat.slice(0, REMOTE_SYNTAX_FRAGMENT_MAX)}…` : flat;
+}
 /**
  * 发送前语法预检（只解析、绝不执行）：命中语法错误即拦下并返回文案，放行返回 null。
- * - 只对本地会话生效：SSH 远程需会话内往返且涉及 `$?` 污染，本步不接。
- * - shell 映射：pwsh/bash/zsh → 对应校验器；cmd 等 → 跳过。
+ * - 本地会话：parse-check（pwsh/bash/zsh；cmd 等跳过）。
+ * - SSH 远程：仅当会话提供 `precheckSyntax` 时调用（SshSession 对 bash/zsh/pwsh 启用，
+ *   CMD 无安全 parse-only 通道故跳过），与本地 parse-check 完全分离；未提供/抛异常/超时一律 fail-open。
  * - 校验模块异常一律放行，绝不因预检故障阻塞命令。
- * @param session 已解析的会话（需提供 shellName/isLocal）
+ * @param session 已解析的会话（需提供 shellName/isLocal，远程另需 precheckSyntax）
  * @param command 待发送的命令文本
- * @param validate 校验函数（默认 validateCommand；仅供单测注入异常实现）
+ * @param validate 本地校验函数（默认 validateCommand；仅供单测注入异常实现）
  * @param lang 文案语言（默认取当前工具语言）
+ * @param remoteTimeoutMs 远程预检等待上限（毫秒；默认 REMOTE_PRECHECK_TIMEOUT_MS，仅供单测缩短）
  * @returns null=放行；非 null=拦截文案（调用方直接返回，不写终端）
  */
-export async function precheckBeforeExec(session, command, validate = validateCommand, lang = getToolLang()) {
+export async function precheckBeforeExec(session, command, validate = validateCommand, lang = getToolLang(), remoteTimeoutMs = REMOTE_PRECHECK_TIMEOUT_MS) {
     if (!session.isLocal)
-        return null;
+        return precheckRemote(session, command, lang, remoteTimeoutMs);
     const shell = CHECK_SHELL_BY_ADAPTER[session.shellName ?? ""];
     if (!shell)
         return null; // cmd 等不支持的 shell：跳过校验
@@ -102,4 +125,56 @@ export async function precheckBeforeExec(session, command, validate = validateCo
         return null; // 预检故障绝不阻塞命令
     }
 }
+/**
+ * 远程会话的发送前预检：调用会话自带的 `precheckSyntax`（独立 exec channel）。
+ * 未实现、调用异常、超时、返回结构异常一律放行（fail-open），绝不误拦或阻塞主命令。
+ * @param session 已解析的远程会话
+ * @param command 待发送的命令文本
+ * @param lang 文案语言
+ * @param timeoutMs 等待上限（毫秒）
+ * @returns null=放行；非 null=拦截文案
+ */
+async function precheckRemote(session, command, lang, timeoutMs) {
+    const precheckSyntax = session.precheckSyntax;
+    if (typeof precheckSyntax !== "function")
+        return null;
+    try {
+        // 与本地一致：校验实际会发送的命令体（剥掉尾注释/尾运算符，避免把合法命令误判）
+        const target = stripCommandTail(command, session.shellName ?? "");
+        if (!target)
+            return null;
+        const result = await withTimeout(precheckSyntax.call(session, target), timeoutMs);
+        if (!result || result.ok !== false)
+            return null;
+        const errors = Array.isArray(result.errors) ? result.errors : [];
+        if (errors.length === 0)
+            return null;
+        return formatSyntaxRejection(target, errors, lang);
+    }
+    catch (e) {
+        log.error("远程发送前语法校验异常，放行命令", e instanceof Error ? e : String(e));
+        return null; // 预检故障绝不阻塞命令
+    }
+}
+/**
+ * 给远程预检加超时：到点返回 null（调用方按 fail-open 处理）。
+ * 原 Promise 后续的 rejection 也在此处消费，避免未捕获拒绝。
+ * @param task 远程预检 Promise
+ * @param timeoutMs 等待上限（毫秒，最小 1）
+ * @returns 预检结果；超时为 null
+ */
+function withTimeout(task, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(null), Math.max(1, timeoutMs));
+        task.then((value) => finish(value), () => finish(null));
+    });
+}
 //# sourceMappingURL=precheck.js.map

package/dist/precheck.js.map

@@ -1 +1 @@
-{"version":3,"file":"precheck.js","sourceRoot":"","sources":["../src/precheck.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"precheck.js","sourceRoot":"","sources":["../src/precheck.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import { type DownloadOptions, type TransferResult, type UploadOptions } from "./transfer.js";
 import type { ExecResult } from "./base-session.js";
 import { BaseSession } from "./base-session.js";
+import { type ParseCheckResult } from "./parse-check.js";
 export interface SessionStatus {
     connected: boolean;
     busy: boolean;
@@ -54,6 +55,17 @@ export declare class SshSession extends BaseSession {
      * @returns 传输结果（路径/实际字节/耗时，不含内容）
      */
     downloadFile(opts: Omit<DownloadOptions, "sftp">): Promise<TransferResult>;
+    /**
+     * SSH 远程发送前语法预检（bash/zsh/pwsh）：独立 exec channel，只解析不执行。
+     * - bash/zsh：跑 `<shell> -n`，命令经 stdin 写入；
+     * - pwsh：启动 PowerShell 解析侧车（与本地 parse-check 同一脚本/协议），命令以 base64 写入 stdin；
+     * - 不占 PTY、不写 history、不翻转 busy、不修改 `_connected`；
+     * - 其他 shell（sh/dash/cmd/未知）或未连接时直接放行；cmd 无安全 parse-only 通道，明确跳过；
+     * - 通道异常、超时、拿不到响应、非语法失败一律 `{ok:true}`（绝不误拦）。
+     * @param command 待校验的命令文本（调用方已剥掉尾注释/尾运算符）
+     * @returns 通过或无法判定为 `{ok:true}`；确认语法错误为 `{ok:false,errors}`（含行号/片段）
+     */
+    precheckSyntax(command: string): Promise<ParseCheckResult>;
     /**
      * 串行化文件传输：前一个任务成功或失败后都继续执行下一个（失败不阻塞队列）。
      * @param job 传输任务
@@ -74,6 +86,44 @@ export declare class SshSession extends BaseSession {
      * @returns 任务结果
      */
     private _withSftp;
+    /**
+     * 用独立 SSH exec channel 跑 `<shell> -n`：命令文本经 stdin 写入（末尾补换行）后 EOF。
+     * 只解析不执行；通道结束/错误/超时都只结算本次预检，不触碰 PTY、busy、history 或连接状态。
+     * @param client 当前 SSH 客户端（调用方已确认非 null 且已连接）
+     * @param shell bash 或 zsh
+     * @param command 待校验命令文本
+     * @returns 确认语法错误 `{ok:false,errors}`；其余情况一律 `{ok:true}`（fail-open）
+     */
+    private _execSyntaxCheck;
+    /**
+     * 用独立 SSH exec channel 启动 PowerShell 解析侧车（只解析不执行）：
+     * 复用本地 parse-check 的侧车脚本/响应协议，命令以 base64(UTF-8) 写入 stdin，
+     * 随后写 `!QUIT` 让侧车自行退出；只读 stdout 的 `ERRCOUNT=` 行，不触碰 PTY/连接状态。
+     * 命令超长或编码失败直接放行（fail-open）。
+     * @param client 当前 SSH 客户端（调用方已确认非 null 且已连接）
+     * @param command 待校验命令文本
+     * @returns 确认语法错误 `{ok:false,errors}`；其余情况一律 `{ok:true}`
+     */
+    private _execPwshSyntaxCheck;
+    /**
+     * 按候选顺序（pwsh → powershell → powershell.exe）启动侧车，共享总超时预算。
+     * 只有"候选不可用"（找不到解释器/启动失败）才换下一个；拿到协议结果或通道异常/超时即结算，
+     * 除确认语法错误外一律返回 `{ok:true}`。
+     * @param client 当前 SSH 客户端
+     * @param payload base64(UTF-8 命令文本)
+     * @returns 预检结果（fail-open）
+     */
+    private _runPwshCandidates;
+    /**
+     * 单个候选解释器的一次预检：打开独立 exec channel、写入请求与 `!QUIT`、收集 stdout/stderr。
+     * 结算时清定时器/销毁通道；通道错误与"命令不存在"都只影响本次预检。
+     * @param client 当前 SSH 客户端
+     * @param bin 候选解释器名（pwsh / powershell / powershell.exe）
+     * @param payload base64(UTF-8 命令文本)
+     * @param timeoutMs 本次候选的剩余预算（毫秒）
+     * @returns 候选结果（result/unavailable/error/timeout）
+     */
+    private _runPwshCandidate;
     getStatus(): SessionStatus;
 }
 /** runSshTransfer 参数 */

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAkE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7J,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,qBAAa,UAAW,SAAQ,WAAW;IACzC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,OAAO,CAA4C;IAC3D,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;IAClB;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAsC;IAE5D,SAAS,KAAK,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC,CAAgC;IAEjF,SAAS,CAAC,MAAM,IAAI,OAAO,CAE1B;IAED,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnC;IAED,SAAS,CAAC,eAAe,IAAI,IAAI,CAIhC;IAEK,OAAO,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAiH5G;IAED;;;;;OAKG;IACG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ3E;IAED;;;;;OAKG;IACG,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ/E;IAED;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAiIjB,SAAS,IAAI,aAAa,CAYzB;CACF;AAED,wBAAwB;AACxB,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,iBAAiB;IACjB,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUnF"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -2,11 +2,61 @@
 // 完成标记法：每条命令后追加一条标记命令，完成后输出 <SSH_DONE:nonce:seq:退出码>（不依赖 PROMPT_COMMAND/PS1 钩子）
 import { Client } from "ssh2";
 import log, { isDebugEnabled, ssh2Trace } from "./log.js";
-import { INJECT_TIMEOUT_MS, PTY_COLS, PTY_ROWS, READY_TIMEOUT_MS, SSH_KEEPALIVE_COUNT_MAX, SSH_KEEPALIVE_INTERVAL_MS, TRANSFER_JOB_SETTLE_TIMEOUT_MS, TRANSFER_TIMEOUT_MS, } from "./constants.js";
+import { INJECT_TIMEOUT_MS, PTY_COLS, PTY_ROWS, READY_TIMEOUT_MS, REMOTE_PRECHECK_COMMAND_MAX, REMOTE_PRECHECK_OUTPUT_MAX, REMOTE_PRECHECK_TIMEOUT_MS, SSH_KEEPALIVE_COUNT_MAX, SSH_KEEPALIVE_INTERVAL_MS, TRANSFER_JOB_SETTLE_TIMEOUT_MS, TRANSFER_TIMEOUT_MS, } from "./constants.js";
 import { tr } from "./i18n.js";
 import { resolveAuth, resolvePassword } from "./ssh-auth.js";
 import { assertTransferCapable, downloadFile, uploadFile, TransferError } from "./transfer.js";
 import { BaseSession } from "./base-session.js";
+import { encodePwshSidecarPayload, looksLikePosixSyntaxError, parsePosixSyntaxLine, parsePwshSidecarResponse, PS_SIDECAR_ENCODED_COMMAND, } from "./parse-check.js";
+import { pickSyntaxErrorText } from "./precheck.js";
+/** 远程预检放行结果（共享单例） */
+const PRECHECK_PASS = { ok: true };
+/** 远程 pwsh 侧车候选解释器（按序尝试；任一不可用/超时即 fail-open） */
+const REMOTE_PWSH_CANDIDATES = ["pwsh", "powershell", "powershell.exe"];
+/** 侧车启动参数（脚本经 UTF-16LE base64 传入，纯 ASCII，规避远端代码页/引号问题） */
+const PS_SIDECAR_ARGV = `-NoProfile -NonInteractive -NoLogo -EncodedCommand ${PS_SIDECAR_ENCODED_COMMAND}`;
+/** 侧车协议响应行前缀 */
+const PWSH_RESPONSE_PREFIX = "ERRCOUNT=";
+const PWSH_ERROR_PREFIX = "ERROR=";
+/**
+ * 从侧车 stdout 取出协议响应行（容忍 CRLF、UTF-8 BOM 与前置 READY 行）。
+ * @param stdout 侧车标准输出
+ * @returns `ERRCOUNT=...` / `ERROR=...` 行；无响应返回 null
+ */
+function findPwshResponseLine(stdout) {
+    for (const raw of stdout.split(/\r?\n/)) {
+        const line = raw.replace(/^\uFEFF/, "");
+        if (line.startsWith(PWSH_RESPONSE_PREFIX) || line.startsWith(PWSH_ERROR_PREFIX))
+            return line;
+    }
+    return null;
+}
+/** 远端"解释器不存在/无法启动"的典型文案（仅在拿不到协议响应时用于决定是否换候选） */
+const PWSH_UNAVAILABLE_RE = /command not found|not found|not recognized|不是内部或外部命令|无法将.*识别|未找到命令|找不到命令/i;
+/**
+ * 追加输出并保留尾部上限，避免异常输出撑爆内存。
+ * @param current 已收集文本
+ * @param chunk 新到片段
+ * @returns 截尾后的文本（上限 REMOTE_PRECHECK_OUTPUT_MAX）
+ */
+function appendBounded(current, chunk) {
+    const next = current + chunk;
+    return next.length > REMOTE_PRECHECK_OUTPUT_MAX ? next.slice(-REMOTE_PRECHECK_OUTPUT_MAX) : next;
+}
+/**
+ * 候选解释器是否明显"没跑起来"（不存在/启动失败）。
+ * 只在没有协议响应时判定：非语法失败必须放行，绝不误拦。
+ * @param exitCode 远端退出码（null=未收到）
+ * @param stderr 远端标准错误输出
+ * @returns 可换下一候选时为 true
+ */
+function isPwshCandidateUnavailable(exitCode, stderr) {
+    if (exitCode === null)
+        return true;
+    if (exitCode === 0)
+        return false;
+    return exitCode === 127 || exitCode === 9009 || PWSH_UNAVAILABLE_RE.test(stderr);
+}
 export class SshSession extends BaseSession {
     _client = null;
     _stream = null;
@@ -167,6 +217,26 @@ export class SshSession extends BaseSession {
         const timeoutMs = opts.timeoutMs ?? TRANSFER_TIMEOUT_MS;
         return this._enqueueTransfer(() => this._withSftp(timeoutMs, (sftp, remainingMs, abortSignal) => downloadFile({ ...opts, sftp, timeoutMs: remainingMs, abortSignal })));
     }
+    /**
+     * SSH 远程发送前语法预检（bash/zsh/pwsh）：独立 exec channel，只解析不执行。
+     * - bash/zsh：跑 `<shell> -n`，命令经 stdin 写入；
+     * - pwsh：启动 PowerShell 解析侧车（与本地 parse-check 同一脚本/协议），命令以 base64 写入 stdin；
+     * - 不占 PTY、不写 history、不翻转 busy、不修改 `_connected`；
+     * - 其他 shell（sh/dash/cmd/未知）或未连接时直接放行；cmd 无安全 parse-only 通道，明确跳过；
+     * - 通道异常、超时、拿不到响应、非语法失败一律 `{ok:true}`（绝不误拦）。
+     * @param command 待校验的命令文本（调用方已剥掉尾注释/尾运算符）
+     * @returns 通过或无法判定为 `{ok:true}`；确认语法错误为 `{ok:false,errors}`（含行号/片段）
+     */
+    async precheckSyntax(command) {
+        const shell = this._adapter?.name;
+        if (shell !== "bash" && shell !== "zsh" && shell !== "pwsh")
+            return PRECHECK_PASS;
+        if (!command || !this._connected || this._client === null)
+            return PRECHECK_PASS;
+        if (shell === "pwsh")
+            return this._execPwshSyntaxCheck(this._client, command);
+        return this._execSyntaxCheck(this._client, shell, command);
+    }
     /**
      * 串行化文件传输：前一个任务成功或失败后都继续执行下一个（失败不阻塞队列）。
      * @param job 传输任务
@@ -332,6 +402,260 @@ export class SshSession extends BaseSession {
             }
         });
     }
+    /**
+     * 用独立 SSH exec channel 跑 `<shell> -n`：命令文本经 stdin 写入（末尾补换行）后 EOF。
+     * 只解析不执行；通道结束/错误/超时都只结算本次预检，不触碰 PTY、busy、history 或连接状态。
+     * @param client 当前 SSH 客户端（调用方已确认非 null 且已连接）
+     * @param shell bash 或 zsh
+     * @param command 待校验命令文本
+     * @returns 确认语法错误 `{ok:false,errors}`；其余情况一律 `{ok:true}`（fail-open）
+     */
+    _execSyntaxCheck(client, shell, command) {
+        return new Promise((resolve) => {
+            let settled = false;
+            /** 远端退出码；未收到 exit 事件时为 null（按"无法判定"放行） */
+            let exitCode = null;
+            let stderr = "";
+            let stdout = "";
+            let stream = null;
+            let timer = null;
+            /** 单次结算：清定时器；abort=true 时销毁预检通道（超时/错误路径） */
+            const settle = (result, abort = false) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== null) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                if (abort && stream !== null) {
+                    try {
+                        stream.destroy();
+                    }
+                    catch {
+                        /* 通道可能已关闭 */
+                    }
+                }
+                resolve(result);
+            };
+            /** 通道关闭：只有"非 0 退出码 + stderr 确实像语法错误"才拦截，其余放行 */
+            const finish = () => {
+                if (settled)
+                    return;
+                if (exitCode === null || exitCode === 0 || !looksLikePosixSyntaxError(stderr)) {
+                    settle(PRECHECK_PASS);
+                    return;
+                }
+                const line = parsePosixSyntaxLine(stderr);
+                const detail = stderr.trim() ? stderr : stdout;
+                settle({
+                    ok: false,
+                    errors: [{ errorId: `${shell}-syntax`, line, col: 1, text: pickSyntaxErrorText(command, line, detail) }],
+                });
+            };
+            timer = setTimeout(() => {
+                log.info(`远程语法预检超时，放行命令 (session ${this.sessionID}, term ${this.name})`);
+                settle(PRECHECK_PASS, true);
+            }, REMOTE_PRECHECK_TIMEOUT_MS);
+            try {
+                client.exec(`${shell} -n`, { pty: false }, (err, channel) => {
+                    // 超时/错误之后才建好的通道：直接销毁，避免泄漏
+                    if (settled) {
+                        try {
+                            channel?.destroy();
+                        }
+                        catch {
+                            /* 已关闭 */
+                        }
+                        return;
+                    }
+                    if (err || !channel) {
+                        log.info(`远程语法预检通道不可用，放行命令 (session ${this.sessionID}, term ${this.name})`);
+                        settle(PRECHECK_PASS);
+                        return;
+                    }
+                    stream = channel;
+                    channel.on("error", (e) => {
+                        if (settled)
+                            return;
+                        log.info(`远程语法预检通道错误，放行命令 (session ${this.sessionID}, term ${this.name}): ${e.message}`);
+                        settle(PRECHECK_PASS, true);
+                    });
+                    channel.stderr.on("error", () => settle(PRECHECK_PASS, true));
+                    channel.stderr.setEncoding("utf8");
+                    channel.stderr.on("data", (chunk) => { stderr = appendBounded(stderr, chunk); });
+                    channel.setEncoding("utf8");
+                    channel.on("data", (chunk) => { stdout = appendBounded(stdout, chunk); });
+                    // 只认 exit 的退出码；close 用于确保 stdout/stderr 已消费完毕再结算
+                    channel.on("exit", (code) => {
+                        exitCode = typeof code === "number" ? code : null;
+                    });
+                    channel.on("close", finish);
+                    try {
+                        channel.end(command.endsWith("\n") ? command : `${command}\n`);
+                    }
+                    catch {
+                        settle(PRECHECK_PASS, true);
+                    }
+                });
+            }
+            catch (e) {
+                log.error(`远程发送前语法预检异常，放行命令 (session ${this.sessionID}, term ${this.name})`, e instanceof Error ? e : String(e));
+                settle(PRECHECK_PASS);
+            }
+        });
+    }
+    /**
+     * 用独立 SSH exec channel 启动 PowerShell 解析侧车（只解析不执行）：
+     * 复用本地 parse-check 的侧车脚本/响应协议，命令以 base64(UTF-8) 写入 stdin，
+     * 随后写 `!QUIT` 让侧车自行退出；只读 stdout 的 `ERRCOUNT=` 行，不触碰 PTY/连接状态。
+     * 命令超长或编码失败直接放行（fail-open）。
+     * @param client 当前 SSH 客户端（调用方已确认非 null 且已连接）
+     * @param command 待校验命令文本
+     * @returns 确认语法错误 `{ok:false,errors}`；其余情况一律 `{ok:true}`
+     */
+    _execPwshSyntaxCheck(client, command) {
+        if (command.length > REMOTE_PRECHECK_COMMAND_MAX) {
+            log.info(`远程 pwsh 语法预检：命令超长，放行命令 (session ${this.sessionID}, term ${this.name})`);
+            return Promise.resolve(PRECHECK_PASS);
+        }
+        let payload;
+        try {
+            payload = encodePwshSidecarPayload(command);
+        }
+        catch (e) {
+            log.error(`远程 pwsh 语法预检编码失败，放行命令 (session ${this.sessionID}, term ${this.name})`, e instanceof Error ? e : String(e));
+            return Promise.resolve(PRECHECK_PASS);
+        }
+        return this._runPwshCandidates(client, payload);
+    }
+    /**
+     * 按候选顺序（pwsh → powershell → powershell.exe）启动侧车，共享总超时预算。
+     * 只有"候选不可用"（找不到解释器/启动失败）才换下一个；拿到协议结果或通道异常/超时即结算，
+     * 除确认语法错误外一律返回 `{ok:true}`。
+     * @param client 当前 SSH 客户端
+     * @param payload base64(UTF-8 命令文本)
+     * @returns 预检结果（fail-open）
+     */
+    async _runPwshCandidates(client, payload) {
+        const deadlineAt = Date.now() + REMOTE_PRECHECK_TIMEOUT_MS;
+        for (const bin of REMOTE_PWSH_CANDIDATES) {
+            const remaining = deadlineAt - Date.now();
+            if (remaining <= 0)
+                break;
+            const outcome = await this._runPwshCandidate(client, bin, payload, remaining);
+            if (outcome.kind === "result") {
+                return outcome.errors.length === 0 ? PRECHECK_PASS : { ok: false, errors: outcome.errors };
+            }
+            if (outcome.kind === "unavailable") {
+                log.info(`远程 pwsh 语法预检候选不可用（${bin}），尝试下一候选 (session ${this.sessionID}, term ${this.name})`);
+                continue;
+            }
+            // 侧车内部异常 / 超时：放行，不再重试（超时已耗尽预算）
+            log.info(`远程 pwsh 语法预检未获结果（${bin}:${outcome.kind}），放行命令 (session ${this.sessionID}, term ${this.name})`);
+            return PRECHECK_PASS;
+        }
+        log.info(`远程 pwsh 语法预检无可用候选，放行命令 (session ${this.sessionID}, term ${this.name})`);
+        return PRECHECK_PASS;
+    }
+    /**
+     * 单个候选解释器的一次预检：打开独立 exec channel、写入请求与 `!QUIT`、收集 stdout/stderr。
+     * 结算时清定时器/销毁通道；通道错误与"命令不存在"都只影响本次预检。
+     * @param client 当前 SSH 客户端
+     * @param bin 候选解释器名（pwsh / powershell / powershell.exe）
+     * @param payload base64(UTF-8 命令文本)
+     * @param timeoutMs 本次候选的剩余预算（毫秒）
+     * @returns 候选结果（result/unavailable/error/timeout）
+     */
+    _runPwshCandidate(client, bin, payload, timeoutMs) {
+        return new Promise((resolve) => {
+            let settled = false;
+            /** 远端退出码；未收到 exit 事件时为 null（按"候选不可用"处理，交给下一个候选） */
+            let exitCode = null;
+            let stdout = "";
+            let stderr = "";
+            let stream = null;
+            let timer = null;
+            /** 单次结算：清定时器；destroy=true 时销毁预检通道（超时/错误路径） */
+            const settle = (outcome, destroy = false) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== null) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                if (destroy && stream !== null) {
+                    try {
+                        stream.destroy();
+                    }
+                    catch {
+                        /* 通道可能已关闭 */
+                    }
+                }
+                stream = null;
+                resolve(outcome);
+            };
+            /** 通道关闭：先找协议响应行；无响应时按退出码/错误文案判断是否换下一候选 */
+            const finishFromOutput = () => {
+                if (settled)
+                    return;
+                const line = findPwshResponseLine(stdout);
+                if (line !== null) {
+                    if (line.startsWith(PWSH_ERROR_PREFIX)) {
+                        settle({ kind: "error" });
+                        return;
+                    }
+                    const errors = parsePwshSidecarResponse(line);
+                    settle(errors === null ? { kind: "error" } : { kind: "result", errors });
+                    return;
+                }
+                settle(isPwshCandidateUnavailable(exitCode, stderr) ? { kind: "unavailable" } : { kind: "error" });
+            };
+            timer = setTimeout(() => settle({ kind: "timeout" }, true), Math.max(1, timeoutMs));
+            try {
+                client.exec(`${bin} ${PS_SIDECAR_ARGV}`, { pty: false }, (err, channel) => {
+                    // 超时/错误之后才建好的通道：直接销毁，避免泄漏
+                    if (settled) {
+                        try {
+                            channel?.destroy();
+                        }
+                        catch {
+                            /* 已关闭 */
+                        }
+                        return;
+                    }
+                    if (err || !channel) {
+                        settle({ kind: "unavailable" });
+                        return;
+                    }
+                    stream = channel;
+                    // 通道级错误只影响本候选（可能只是"命令不存在"导致写失败）：交给下一个候选
+                    channel.on("error", () => settle({ kind: "unavailable" }, true));
+                    channel.stderr.on("error", () => settle({ kind: "unavailable" }, true));
+                    channel.stderr.setEncoding("utf8");
+                    channel.stderr.on("data", (chunk) => { stderr = appendBounded(stderr, chunk); });
+                    channel.setEncoding("utf8");
+                    channel.on("data", (chunk) => { stdout = appendBounded(stdout, chunk); });
+                    channel.on("exit", (code) => {
+                        exitCode = typeof code === "number" ? code : null;
+                    });
+                    channel.on("close", finishFromOutput);
+                    try {
+                        // 一行请求 + !QUIT：侧车解析后输出 ERRCOUNT 行并自行退出
+                        channel.end(`${payload}\n!QUIT\n`);
+                    }
+                    catch {
+                        settle({ kind: "unavailable" }, true);
+                    }
+                });
+            }
+            catch (e) {
+                log.error(`远程 pwsh 语法预检通道异常，放行命令 (session ${this.sessionID}, term ${this.name})`, e instanceof Error ? e : String(e));
+                settle({ kind: "unavailable" });
+            }
+        });
+    }
     getStatus() {
         return {
             connected: this._connected,