fix: 改进 Windows SSH PowerShell 错误提示

scripts/src/ssh-runtime.ts

@@ -117,6 +117,20 @@ export function sshWindowsPlaneHint(invocation: ParsedSshInvocation, exitCode: n
   })}\n`;
 }
 
+export function sshWindowsPowerShellPipelineHint(invocation: ParsedSshInvocation, exitCode: number, stderrText: string): string {
+  if (invocation.route.plane !== "win" || exitCode === 0 || !/An empty pipe element is not allowed/iu.test(stderrText)) return "";
+  return `UNIDESK_SSH_HINT ${JSON.stringify({
+    code: "windows-powershell-statement-pipeline-boundary",
+    providerId: safeProviderId(invocation.providerId),
+    route: invocation.route.raw,
+    exitCode,
+    message: "PowerShell cannot pipe a statement such as foreach directly at this syntax boundary.",
+    action: "Wrap the statement in @(...), then pipe the resulting values, or use a multiline quoted PowerShell heredoc.",
+    examples: ["@(foreach (...) { ... }) | Format-List", "trans <route> ps <<'PS'"],
+    note: "This hint intentionally does not echo the submitted PowerShell source.",
+  })}\n`;
+}
+
 export function sshSlowWarningThresholdMs(env: NodeJS.ProcessEnv = process.env): number {
   const raw = env.UNIDESK_SSH_SLOW_WARNING_MS;
   const parsed = raw === undefined ? NaN : Number(raw);
@@ -1015,6 +1029,7 @@ async function runSshCaptureRemoteCommand(config: UniDeskConfig, invocation: Par
         stderrText: stderr,
       }));
       stderr += sshWindowsPlaneHint(invocation, exitCode, stderr);
+      stderr += sshWindowsPowerShellPipelineHint(invocation, exitCode, stderr);
       resolve({ exitCode, stdout, stderr });
     };
     const runtimeTimer = setTimeout(() => {
@@ -1538,6 +1553,8 @@ export async function runSsh(config: UniDeskConfig, providerId: string, args: st
       if (!timedOut) {
         const windowsPlaneHint = sshWindowsPlaneHint(invocation, exitCode, stderrTail);
         if (windowsPlaneHint) process.stderr.write(windowsPlaneHint);
+        const pipelineHint = sshWindowsPowerShellPipelineHint(invocation, exitCode, stderrTail);
+        if (pipelineHint) process.stderr.write(pipelineHint);
       }
       if (!timedOut) {
         const tcpPoolHint = formatSshTcpPoolHint(sshTcpPoolHint({