dsh-superagent 原型在 Windows 上的六处不适配（附补丁与端到端验证）

[Ersith]

在 Windows 11 上把 deepseek-ai/dsh-superagent-prototype v0.1.0（DSH 0.2.1-rc.5、Node 24、GitHub CLI 2.103.3）跑起来了。原型本身是一套很干净的设计，但代码里有四处 POSIX 假设，各自卡在不同阶段，全修完才走通「Issue → 评估 → 工单 → 自动开 PR」。记录在这里，给同样在 Windows 上试的人省点时间，也给作者留个档。

原型仓的 Issues / Discussions / PR 都是关的（GET /pulls 返回 404），所以发在这里。不是求合并，只是把踩到的坑和改法说清楚；需要的话我可以把它拆成 PR 或按你们的风格重写。

六处不适配

位置	症状	原因
src/deployment.ts stateDir	插件完全不激活：$.stateDir expect string to match regexp /^\//	校验要求以 / 开头，Windows 盘符路径必然不满足
src/deployment.ts workerProbe	setup 读不到账号：spawn env ENOENT	argv 前缀是 env PATH=…，Windows 没有 env 这个程序
src/app/sessions.ts orchestrator preset	编排不挂载，/orchestrator/api/* 一律 404 且没有别的报错	preset 把工具限制为 bash；Windows profile 里是 pwsh，tools.restrict() 拒绝未知名字，整个挂载被中断
src/executor/dsh.ts prepare	每个工单立刻失败：The prepare command failed: spawn sh ENOENT	prepare 命令写死 sh -c
src/policy.ts executor.directory	填盘符根目录报 Invalid settings: directory	用「以 / 开头」代替「是绝对路径」
docs/006-deployment.md	按文档装完就会遇到上面四条	没有 Windows 说明：agent CLI 不能是 .cmd，prepare shell 也不可配

第三条最阴：它不报错、不崩溃，只是编排那一块静默消失，表现是面板 404，很难从现象倒推回去。

改法

• stateDir 接受 POSIX / 盘符 / UNC 三种绝对路径。
• workerProbe 在 POSIX 保留 env PATH=… 前缀；win32 直接传 argv —— 那个前缀本来是为了把 worker shim 排除出 PATH，而 Windows 上配置的是绝对路径，不需要它。
• 编排的受限工具表按平台取 shell 名（bash / pwsh），跟 bundle 里已有的 !!js process.platform === 'win32' 写法一致。
• prepare shell 从平台分支改成设置项 prepareShell（默认 sh -c）：POSIX 行为零变化，Windows 填 cmd.exe /d /s /c 或 bash -lc。之所以不写死平台分支，是因为这样行为显式、可测，也不需要为「Windows 上用什么 shell」做猜测。
• executor.directory 改用 path.isAbsolute()。
• 文档补一节 Windows：agent CLI 必须是可执行文件（Node 不能直接 spawn .cmd，所以 CLI 填 gh.exe，把身份放进服务进程的 GH_CONFIG_DIR）、prepareShell 怎么填、两种 shell 的语法差异（$VAR vs %VAR%）。

补丁：Ersith/dsh-superagent-prototype 分支 windows-compat，commit 6c53839，5 个文件 +39/−8，pnpm build 通过。
比较链接：Ersith/dsh-superagent-prototype@main...windows-compat

验证

Windows 11 + DSH 0.2.1-rc.5 + GitHub CLI 2.103.3，端到端走了一遍：

1. setup 解析出仓库与 agent 账号；
2. 允许名单里的账号开一个 Issue，来源收到并交给模型评估；
3. 命中 Policy 规则 → eval.mode=auto → 建工单；
4. prepare 把仓库 clone 进工单目录，worker session 改一处措辞、提交、推分支；
5. agent 自动开出 PR，正文自带「This is by an automated agent, not a human.」、改动前后对照和自检说明。

最后交付的 PR 是单行 diff（README.md 两行文件里的一行措辞）。

测试说明（如实）

仓库的测试直接断言 POSIX 行为——spawn argv 以 env / sh 开头、工具名 bash。这些断言在 Windows 上本来就有 39 个失败；打了补丁后变 131 个，多出来的都是那些断言在新平台分支下看到的差异。

我没有在 POSIX 主机上跑过全套，所以不能替你们保证 CI 绿。但代码上，POSIX 的每个判断都还是原来的值（同样的 env PATH=… 前缀、同样的 sh -c argv、同样的工具名、path.isAbsolute 对 POSIX 路径的结果不变）。如果希望测试覆盖两个平台，我可以把 shell argv 和工具名抽成常量让 spec 读取，而不是硬编码。

另外两处没动

• scripts/dsh-superagent（Python + fcntl + tmux）和 src/app/migration.ts 里对 tmux 的假设仍然是 POSIX 的。前者只是控制脚本，后者是迁移路径；这次改的是「产品本身能不能跑」，没碰它们。Windows 上我另外写了个 start/stop/status 的 PowerShell 启动器替代 tmux 那层。
• sessions.ts 里 worker preset 已经在用平台判断，说明 Windows 不是明确不支持，只是没适配全 —— 所以这几处大概属于「补完」而不是「新增支持」。

---

顺带一个非 Windows 的发现，可以单独开一条：线程 id 是 github:<编号>，不含仓库名（源码注释也写了 "of any repository"）。在面板里更换 Source 的 repository 时，会跟旧仓同号 Issue 撞线程——我实测换仓后，新仓 #2 的标题被覆盖，但时间戳和裁决理由还是旧仓的，received 也不增加。迁移路径可能需要处理这个。

[TasfiqSami]

The path.isAbsolute() change makes sense here. I'd probably add a Windows runner to CI as well, rather than relying only on the POSIX tests to confirm nothing regressed.

Especially for the spawn changes, testing the actual arguments and executable resolution on Windows would catch issues that a Linux runner won't.

Also, nice catch on the tools.restrict() failure silently preventing the orchestrator routes from mounting. That sounds like a particularly annoying one to debug.

[Ersith]

Both taken — and the Windows runner paid for itself on the first run.

CI (.github/workflows/ci.yml): pnpm typecheck, pnpm test and pnpm build on ubuntu-latest and windows-latest. Getting the Windows job green turned up four things a POSIX-only run could not see:

1. executable() had no PATHEXT rule at all — the file with the path.isAbsolute() change. cli: gh never resolved to gh.exe, so a bare command name only worked if the profile named an absolute .exe. Two more Windows facts in the same function: accessSync(X_OK) is a no-op there, so any file passed the executable check; and bin\gh slipped through as a "command name" because only / counted as a separator. executable() now takes the platform and follows its rules, and tests/executable.spec.ts covers both rule sets — the Windows half runs on Windows, where the extension search and the ;-split PATH actually mean something. A .cmd/.bat match now fails by name ("Node cannot spawn one without a shell") instead of being reported as "not on PATH", which is exactly the kind of message you end up debugging twice.

2. The tools.restrict() fix was still a platform guess. bash on a pwsh profile was one assumption; pwsh on a profile that has bash (a Windows install with Git Bash, say) is the same bug one step out. It now names the shell tool the profile actually exposes — the Executor Session's filter already read it that way — and keeps the platform's name as the fallback, so a profile with neither still fails loudly rather than silently losing the shell. Your read of the original was right: the rejection aborts the whole mount and nothing says why, so the 404 is the only symptom.

3. scripts/dsh-superagent was checked out as CRLF on Windows. With the default core.autocrlf=true, bash cannot run it — the first Windows user to try the service script would have hit it. .gitattributes now pins * text=auto eol=lf.

4. Two failures the patch introduced itself: the expected executor in two settings specs was missing the new prepareShell, and the docs gate compared \-separated paths with the / the documents spell.

Numbers. Windows 11 (10.0.22631), Node 24.19.0: 131 failed / 1066 passed before, 1172 passed / 36 skipped / 0 failed after. The 36 skips are explicit in the specs (it.skipIf(process.platform === 'win32')) and say why: #!/bin/sh stand-ins for gh/lark-cli, execute bits, sh -c exit codes, and the ps/tmux fixtures of the service script. The default test timeout also had to move (5 s → 15 s): a two-core runner starved it and timed out in a different file on each run.

The ubuntu job found one pre-existing flake while it was there: the Feishu consumer prints [event] ready on stderr and events on stdout, and the two pipes are read independently, so a late ready could overwrite the error a malformed line reported — 2 runs in 3 failed. The test now records every report instead of asserting the last one standing.

Branch and run: BigfishEEob/dsh-superagent-prototype@62a65da (windows-compat), both jobs green —
https://github.com/BigfishEEob/dsh-superagent-prototype/actions/runs/41661929045

One thing I would rather say than imply: the POSIX-only specs skip themselves on my machine, so ubuntu-latest was the first place they ran. That job is the evidence for them, not my local run.