Windows 下 pwsh/子进程执行闪现黑色控制台窗口（spawn 缺 windowsHide）

[muyi123567]

Windows 上执行 pwsh/子进程命令时，桌面会闪现黑色控制台窗口（console window flash），非常干扰使用。

复现、预期与验收

• 复现步骤：
  1. Windows 环境（Electron 桌面版）下，在会话中让 agent 调用一次 pwsh 工具（或任何经 dsh-subprocess-local 拉起的控制台子进程，如 node/git 脚本）；
  2. 观察桌面：每次调用都会闪现一个新的黑色控制台窗口，命令执行完窗口即消失（或短暂驻留）。
• 实际结果：每次子进程执行都在桌面上弹出黑窗；GUI 应用（DSH 桌面版）宿主从无控制台环境 spawn 控制台程序时，Windows 默认会为其创建可见控制台窗口。
• 预期结果：子进程在后台静默执行，无任何窗口闪现。
• 环境：Windows（win32），DeepSeek Harness 桌面版；dsh-subprocess-local 的 spawn() 未设置 windowsHide: true。
• 验收条件：Windows 下任意 pwsh/bash 子进程执行时桌面不出现新控制台窗口；stdout/stderr 管道收集不受影响；非 Windows 平台行为不变。

[argszero]

已按 rc.8（141eb6fef8）源码验证，报告准确，且修复点可以收敛到一处：

根因确认：packages/subprocess/subprocess-local/src/spawn.ts:350-361 的 spawn(program, args, {...}) 选项里没有 windowsHide（Node 默认 false）。Windows 上从无控制台的 GUI 宿主（Electron 桌面版）拉起控制台子系统程序（pwsh.exe / cmd.exe / node.exe）时，Windows 会为其新建可见控制台窗口——每次工具调用闪一次黑窗，与报告现象一致。注意这里 win32 分支 detached: false（:360），子进程不脱离宿主控制台上下文，恰好叠加了窗口闪现。

单点修复即覆盖整条调用链：tool-pwsh / tool-bash（及 persistent 变体）→ pwsh-local / bash-local 都经 ctx.subprocess.spawn()（pwsh-local/src/index.ts:263/:286）→ spawnSubprocess → 同一个 spawn()。所以在 :350 加 windowsHide: true 一处，pwsh、bash 以及任何经 dsh-subprocess-local 拉起的 node/git 脚本全部生效。

In-tree 先例（模式已确立，subprocess-local 是例外）：

• host/directory-picker-native/src/win32-dialog-host.ts:28-30（windowsHide: true，且 native-path-opener.spec.ts:157 有断言 options.windowsHide === true 的回归测试）
• util/native-command/src/index.ts:30

次要修复点：windows-inspector.ts:139 的 spawnSync('taskkill', ..., { stdio: 'ignore' }) 同样无 windowsHide——teardown 时 taskkill 也会闪一下（spawnSync 同样接受该选项），建议顺手补上。

不受影响：spawnTerminal（index.ts:161-184）走 node-pty（Windows ConPTY），无可见窗口；stdio 管道收集不受 windowsHide 影响（它只抑制窗口创建，POSIX 上是 no-op，可无条件加）。

两点提醒：

1. 回归测试可照 native-path-opener.spec.ts:157 的 mock 模式（mock node:child_process spawn，断言选项含 windowsHide: true）；subprocess-local 已有同款 mock 夹具（spawn.spec.ts:240/:847），internals.platform 注入也能覆盖 win32 分支。
2. 潜在交互：native/sandbox-windows-acl 的 README 记录了受限令牌下 CREATE_NO_WINDOW 子进程会以 STATUS_DLL_INIT_FAILED (0xC0000142) 死亡——那是该沙箱原生路径的约束，与当前 subprocess-local 无关；但将来若把 Windows 沙箱接入这条 spawn 链，注意不要叠加。

修复体量：1 行主修复 + 1 行次要 + 1 个 mock 回归测试，PR-ready。

[muyi123567]

更新：第一层补丁（dsh-subprocess-local spawn 加 windowsHide: true）只能隐藏外层 runner 进程，黑窗仍然存在。深挖后确认真正弹窗的是沙箱链路：

• Windows 沙箱走 dsh-sandbox-windows-acl 的 runner：node runner.js 内部用 CreateProcessAsUserW 在 restricted token 下创建 pwsh。
• 该层 ABI 注释（win32-abi.ts）明确说明 CREATE_NO_WINDOW / CREATE_NEW_CONSOLE 故意不用：restricted token 下隐藏控制台的子进程会以 STATUS_DLL_INIT_FAILED (0xC0000142) 崩溃（已实测验证）。
• 宿主进程（dsh web server，无控制台）→ runner 无控制台 → pwsh 作为控制台应用被 CreateProcessAsUserW 创建时，Windows 会为它分配新的可见控制台窗口——这就是黑窗来源。

第二层修复（用户态参数，规避 ABI 限制）：给 pwsh argv 注入 -WindowStyle Hidden（dsh-pwsh-local 的 argv()，仅 win32 注入）。已实证：Start-Process pwsh -WindowStyle Hidden 的进程 MainWindowHandle = 0（无窗口）。该参数由 pwsh 自身应用，不涉及 CreateProcessAsUserW 标志位，不触发 0xC0000142。

完整补丁（两处，均为 node_modules 内单行级改动）：

1. @deepseek-ai/dsh-subprocess-local spawn options 加 windowsHide: platform === "win32"
2. @deepseek-ai/dsh-pwsh-local argv 注入 -WindowStyle Hidden（win32 only）

[argszero]

你这个实测闭环很扎实——0xC0000142 的 ABI 约束正是我在首回里提示的那个交互（sandbox-windows-acl README 记录的受限令牌下 CREATE_NO_WINDOW 崩溃），现在被你的深挖实证确认了。也修正我首回的一个覆盖范围假设：windowsHide 只覆盖 subprocess-local 链（bash-local/pwsh-local），沙箱链独立（windows-acl runner 经 CreateProcessAsUserW）——所以第一层补丁盖不到沙箱拉起的 pwsh，你的判断正确。

对第二层修复（-WindowStyle Hidden argv 注入）有一个机制上的提醒，和一个更干净的第三修复点：

1. 机制区分：你的实证证据不能直接迁移到 argv 注入方案。
你实测的 Start-Process pwsh -WindowStyle Hidden 是 PowerShell 宿主在 CreateProcess 调用点把 STARTUPINFO.wShowWindow 设为 SW_HIDE（STARTF_USESHOWWINDOW）——窗口从创建起就是隐藏态。而计划注入的 pwsh -WindowStyle Hidden 是 pwsh 进程启动后自解析参数再隐藏：Windows 在 CreateProcess 完成时已分配可见控制台窗口，pwsh 随后才应用 SW_HIDE——理论上存在一帧的窗口闪现窗口（高负载/慢速机器上可见）。两个 -WindowStyle 同名但机制不同，MainWindowHandle=0 的实证只能证明前者。建议实测一下 argv 注入路径是否有肉眼可见的闪现。

2. 第三修复点（更通用、无闪现）：直接在 runner 的 STARTUPINFOW 写 SW_HIDE。
rc.8 源码里 packages/sandbox/sandbox-windows-acl/src/ffi.ts:142-155 的 STARTUPINFOW 结构已经包含 wShowWindow: 'uint16' 字段（布局对齐到 win32-abi.ts:172 的 size 断言），但两处 encodeStartupInfo 调用（spawn.ts:114-120 和 :298-...）都只写 cb + dwFlags(STARTF_USESTDHANDLES) + 三个 std 句柄，没设 STARTF_USESHOWWINDOW。补丁 = 在 win32-abi.ts 加两个常量：

export const STARTF_USESHOWWINDOW = 0x00000001
export const SW_HIDE = 0

两处 encodeStartupInfo 的 dwFlags 改为 STARTF_USESTDHANDLES | STARTF_USESHOWWINDOW，并加 wShowWindow: SW_HIDE。关键点：STARTF_USESHOWWINDOW 是 STARTUPINFO 字段，与 CREATE_NO_WINDOW（创建标志位）正交——进程仍正常获得控制台（不触发 0xC0000142），只是窗口以隐藏态创建（nShowWindow 指定初始显示状态），且覆盖所有经沙箱拉起的控制台子进程（pwsh/node/git 一网打尽），无需 pwsh 特定参数，也无创建后隐藏的闪现窗口。这与第一层 windowsHide 在 subprocess-local 的作用位置对称——修复点放在进程创建源头。

3. 两层补丁的关系：沙箱链（本方案/argv 注入）盖沙箱拉起的 pwsh；subprocess-local 的 windowsHide 盖非沙箱链（bash-local 直拉、taskkill teardown 等）。两层都值得合，各自覆盖一条链。回归测试：STARTUPINFOW 编码断言（dwFlags 含 SHOWWINDOW 位 + wShowWindow=0）+ runner 冒烟即可；窗口句柄断言在自动化里不可靠（MainWindowHandle 需进程稳定运行后查询）。

[muyi123567]

已按第三修复点落地验证（本机 DSH 桌面版）：

• dsh-sandbox-windows-acl types-CNjZgO4h.js：新增 STARTF_USESHOWWINDOW = 1 / SW_HIDE = 0 常量；两处 encodeStartupInfo（spawnSandboxed 管道路径 + spawnSandboxedInherited 继承路径）的 dwFlags 均改为 256 | STARTF_USESHOWWINDOW 并补 wShowWindow: SW_HIDE。
• 移除了临时的 argv 注入方案（-WindowStyle Hidden），保留 subprocess-local 的 windowsHide: platform === "win32" 作为非沙箱链修复。
• 三个文件 node --check 语法通过；STARTUPINFOW 结构 koffi 布局原已含 wShowWindow: "uint16"（size 断言 104 通过），无需改布局。

待 DSH 桌面版重启后实测确认沙箱链 pwsh 无黑窗。感谢三处修复点的完整指引（windowsHide 盖非沙箱链 + STARTUPINFOW SW_HIDE 盖沙箱链 + taskkill teardown 次要点，后者待官方 PR 一并处理）。

[muyi123567]

非常感谢维护者的快速响应和细致排查——从首回确认根因、指出 in-tree 先例，到第二回给出 STARTUPINFOW 这一层的更优解法，三处修复点（windowsHide 盖非沙箱链、STARTUPINFOW SW_HIDE 盖沙箱链、taskkill teardown 次要点）梳理得非常清晰专业，还贴心地说明了回归测试的 mock 模式和受限令牌 ABI 的交互约束，帮我们少走了很多弯路。辛苦啦！

本地已按第三修复点落地并验证通过：

• dsh-sandbox-windows-acl 新增 STARTF_USESHOWWINDOW = 1 / SW_HIDE = 0，两处 encodeStartupInfo（spawnSandboxed + spawnSandboxedInherited）的 dwFlags 均加 SHOWWINDOW 位并补 wShowWindow: SW_HIDE
• 移除了临时的 argv 注入方案，保留 subprocess-local 的 windowsHide 作为非沙箱链修复
• 三个文件 node --check 语法通过，STARTUPINFOW koffi 布局无需改动

修复不着急，我们理解官方有排期，会耐心等待正式版本，本地补丁先顶着用。再次感谢！

[denial123789]

I consolidated the verified two-path diagnosis into an operator runbook: https://sandbaseai.github.io/deepseek-harness-handbook/windows-console-window-flash.html

The important boundary is now explicit:

• local subprocess-local children are created through Node spawn(), so windowsHide belongs at that creator and at the taskkill teardown call;
• sandboxed children are created later through restricted-token CreateProcessAsUserW(), so the local option cannot hide that final child. The rc.8 ABI intentionally avoids CREATE_NO_WINDOW because of the documented 0xC0000142 failure. The source-level display contract is instead STARTF_USESTDHANDLES | STARTF_USESHOWWINDOW with wShowWindow = SW_HIDE in both sandbox spawn variants.

The guide also records why pwsh -WindowStyle Hidden, Start-Process evidence, disabling the sandbox, and generated node_modules edits are incomplete, plus acceptance gates for stdout/stderr, cancellation, tree teardown, sandbox allow/deny behavior, Unicode paths, and cold restart.

Canonical source-backed runbook: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/windows-console-window-flash.md

[muyi123567]

感谢 denial123789 整理成 runbook！逐条核对了手册内容，与我们本机落地完全一致：

• 路径划分（local spawn → windowsHide；ACL sandbox → STARTUPINFOW）与我们实测的两条创建链一一对应
• "常见修复为什么不够"部分（-WindowStyle Hidden 的机制差异、Start-Process 实证不迁移、CREATE_NO_WINDOW 的 0xC0000142 边界、不禁用沙箱）正是我们排查中验证过的结论
• 验收门禁里的冷重启复现、taskkill teardown、Unicode 路径等补充了很好的工程细节

一个小的补充观察（供手册参考）：本机落地时 STARTUPINFOW 的 koffi 布局已含 wShowWindow: "uint16"（size 断言 104 通过），无需改结构定义，只改两处 encode 调用即可——手册的"source-level repair"描述与之一致。

再次感谢 argszero 的三处修复点指引和 denial123789 的手册整理，这份 runbook 对后来者会很有价值。