Windows 下选择工作区因后台启动与目录权限受阻

[bailong-Hakuryu]

在 Windows 上从 Codex 桌面环境启动 dsh web 后，“选择工作区”流程先后遇到原生目录选择器不可见、应用内目录浏览器无法读取用户主目录，以及重启时端口被旧实例占用的问题。最终在普通 PowerShell 中启动服务后恢复。希望项目改进自动后端选择、失败后的恢复入口和 Windows 启动诊断。

环境、复现、源码核对与建议

环境

• 操作系统：Windows，使用 Windows PowerShell
• 项目目录：D:\deepseek-harness-master（示例路径）
• 项目版本：@deepseek-ai/dsh-root 0.1.0-rc.5
• 项目声明的 Node.js 范围：^22.19.0 || >=24.0.0
• 实际 Node.js：v24.19.0
• 实际 pnpm：11.19.0；仓库 package.json 声明 pnpm@11.7.0
• Web 地址：http://127.0.0.1:3080
• 启动方式：先从 Codex 桌面环境后台启动，随后改为普通 PowerShell 前台启动

用户影响

用户看到“选择工作区目录”弹窗，但目录区域为空，底部显示：

cannot list C:\Users\<用户名>: EPERM: operation not permitted, opendir 'C:\Users\<用户名>'

此时“新建文件夹”和“打开”按钮不可用。标题栏右侧虽然有铅笔图标，可以在首次主目录加载失败时输入绝对路径，但界面没有文字说明这是恢复入口，容易被理解为整个弹窗无法交互。

本次流程因此无法通过常规的逐级浏览完成工作区选择。目标目录本身 D:\deepseek-harness-master 可用，问题发生在目录选择器首先尝试读取 C:\Users\<用户名> 时。发布时请使用脱敏后的占位符，不要公开真实 Windows 用户名。

完整复现与排障时间线

1. 构建和 Web 页面本身正常

依赖安装和构建成功：

pnpm install
pnpm run build

Web UI 可以从 http://127.0.0.1:3080 打开，页面返回 HTTP 200。工作区 D:\deepseek-harness-master 后来也能注册并创建空白会话，因此问题不在静态页面构建或工作区数据格式。

2. 默认自动后端选择了原生 Windows 目录选择器

Web bundle 默认组合 @deepseek-ai/dsh-host-directory-picker-auto。当前实现只要同时满足以下条件，就会在 Windows 上选择 native：

• Web 服务绑定 127.0.0.1；
• 没有 SSH_CONNECTION 或 SSH_TTY；
• process.platform === 'win32'。

对应源码：

• packages/bundle/web-app/cordis.patch.yml
• packages/host/directory-picker-auto/src/resolve.ts

这次 Web 服务由 Codex 桌面环境以隐藏后台进程方式启动。点击“选择工作区”后，浏览器需要等待宿主 Windows 原生对话框，但用户无法在当前交互界面中看到或操作该对话框。

这里可以确认的是：自动选择逻辑在该启动上下文中选中了 native，而用户没有可操作的选择器。仅凭这次现象不能断言 Windows COM IFileOpenDialog 实现本身失败；更可能的问题是启动侧的 win32 + loopback + 非 SSH 信号不足以证明操作者能看到并控制宿主桌面。directory-picker-auto 的 README 也已将“启动侧信号无法证明操作者位置”列为已知限制。

3. 强制切换到应用内 browse 后端

为使目录选择发生在网页内，profile patch 改为禁用自动选择器，并同时组合 browse 的 Host 与 Client 两侧：

- id: directory-picker
  disabled: true

- insert:
    - id: directory-picker-browse
      name: '@deepseek-ai/dsh-host-directory-picker-browse'

    - id: ui-directory-picker-browse
      name: '@deepseek-ai/dsh-client-ui-directory-picker-browse'

配置文件位于：

D:\deepseek-harness-master\.dsh-runtime\profiles\web\cordis.patch.yml

切换后应用内弹窗可以正常打开，但首次目录列表请求立即失败。

4. browse 后端固定从宿主账户主目录开始

packages/host/directory-picker-browse/src/index.ts 的 list(path?) 在没有传入路径时执行：

const home = homedir()
const target = resolve(path ?? home)
const opening = opendir(target)

在本机，os.homedir() 为 C:\Users\<用户名>。服务继承了 Codex 文件系统沙箱权限，不能枚举该目录，因此 opendir 返回 EPERM。使用最小 Node.js 命令可以复现同一错误：

node -e "require('node:fs').opendirSync('C:\\Users\\<用户名>')"

browse 后端当前 Config 只有 maxEntries，没有 defaultPath、initialPath 或 browseRoot。因此部署方无法仅通过插件配置把首次列表改为已授权的目录，例如 D:\deepseek-harness-master。

5. 错误传到 UI，但恢复入口不明显

Host 将此失败映射为 directory-unreadable；Client runtime 使用 DirectoryBrowseError 保留 Host 的消息；DirectoryBrowser 的 failureText() 再把消息原样显示在弹窗中。相关源码：

• packages/host/directory-picker-browse/src/index.ts
• packages/host/apiproxy/src/api/host.ts
• packages/client/runtime/src/client/workspaces/service.ts
• packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx

客户端其实实现了一个重要的恢复路径：即使首次 home listing 失败、parent === null，右上角的路径编辑按钮仍保持可用；点击铅笔后可以输入完整绝对路径并按 Enter。源码注释也明确称它是“failed home listing”的 remaining way forward。

但是截图中的弹窗只有一个铅笔图标，没有“输入路径”文字、错误恢复按钮或针对 EPERM 的说明。用户首先看到的是空白目录区、红色底层错误和两个禁用按钮，因此很难发现必须点击铅笔继续。

6. 改为普通 PowerShell 启动时，pnpm 不在 PATH

为避免服务继承 Codex 沙箱权限，尝试在普通 PowerShell 中启动：

Set-Location 'D:\deepseek-harness-master'
$env:DSH_HOME = 'D:\deepseek-harness-master\.dsh-runtime'
pnpm dsh web

普通 PowerShell 报错：

pnpm : 无法将“pnpm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

Codex 使用的 pnpm 位于其私有运行时目录，没有加入普通 PowerShell 的 PATH。本机最终使用：

& '<Codex runtime>\\dependencies\\bin\\fallback\\pnpm.cmd' dsh web

该 pnpm.cmd 会使用同一 Codex runtime 中的 Node.js，因此不依赖普通 PowerShell 的 pnpm 命令解析。

项目开发文档已说明需要启用 Corepack，并建议 pnpm --version 无法解析时运行 corepack enable。不过对于从 Codex 桌面环境切换到普通 Windows 终端这一实际恢复场景，用户仍需要明确知道：Codex 内可用的 pnpm 不一定存在于系统 PATH。

7. 第一次用绝对 pnpm 路径启动时工作目录错误

在新 PowerShell 窗口中直接运行绝对 pnpm 路径时，当前目录仍是 C:\Users\<用户名>，因此 pnpm 报错：

[ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND] No package.json (or package.yaml, or package.json5) was found in "C:\Users\<用户名>".

切换到仓库根目录并在同一个 PowerShell 会话中设置 DSH_HOME 后解决：

Set-Location 'D:\deepseek-harness-master'
$env:DSH_HOME = 'D:\deepseek-harness-master\.dsh-runtime'

8. 旧的受限实例仍占用 3080

从普通 PowerShell 启动的新实例随后两次失败：

listen EADDRINUSE: address already in use 127.0.0.1:3080

连续 netstat -ano -p tcp 采样确认旧实例 PID 36516 一直监听 127.0.0.1:3080，且存在多个已建立连接。停止确切的旧进程树：

taskkill /PID 36516 /T /F

输出确认终止了 PID 36516 及其子进程 PID 38632。

当前 EADDRINUSE 错误包含地址和端口，但没有显示占用 PID、没有提示已有 dsh web 实例，也没有给出选择其他端口或停止旧实例的下一步操作。对于不熟悉端口诊断的用户，这会形成第二个启动阻塞。

9. 最终恢复与验证

在普通 PowerShell 的仓库根目录中，使用同一个 .dsh-runtime 重新启动：

Set-Location 'D:\deepseek-harness-master'
$env:DSH_HOME = 'D:\deepseek-harness-master\.dsh-runtime'
& '<Codex runtime>\\dependencies\\bin\\fallback\\pnpm.cmd' dsh web

成功输出：

$ node --import tsx/esm apps/cli/src/bin.ts "web"
dsh web: http://127.0.0.1:3080

验证结果：

• 新监听 PID：46668
• GET http://127.0.0.1:3080：HTTP 200
• 响应类型：text/html; charset=utf-8
• 原有 .dsh-runtime 配置、工作区和会话数据保留
• 工作区路径 D:\deepseek-harness-master 可继续使用

这说明主要故障来自服务启动上下文继承的文件权限，而不是目标工作区不可用或 Web 页面构建失败。

根因与相关问题的划分

已验证的直接原因

1. browse 后端无路径请求固定从 os.homedir() 开始。
2. 受限启动上下文中的 Node.js 进程对 C:\Users\<用户名> 执行 opendir 返回 EPERM。
3. 旧服务 PID 36516 持续占用 127.0.0.1:3080，导致普通 PowerShell 中的新实例报 EADDRINUSE。

有源码支持的产品可用性问题

1. directory-picker-auto 在 Windows 上把 win32 + loopback + 非 SSH 直接视为原生选择器可供当前操作者使用，无法识别隐藏后台进程或受限桌面启动上下文。
2. browse 后端没有可配置的初始路径；home 不可读时只能依靠客户端路径编辑器恢复。
3. UI 已实现“首次 home 加载失败时输入绝对路径”的恢复能力，但入口只有铅笔图标，错误状态没有明确引导。
4. Web 启动失败时，EADDRINUSE 诊断没有提供占用进程或明确恢复动作。
5. 从 Codex runtime 切换到普通 Windows 终端时，Node/pnpm 的可见性和工作目录前提容易连续产生新的阻塞。

不应过度归因的部分

• EPERM 本身符合宿主进程的文件系统权限，不建议通过放宽产品文件系统策略来修复。
• 本次没有证明 Windows IFileOpenDialog 的 COM 实现出错；已证明的是自动选择出的原生交互在当前启动方式下不可供用户操作。
• 普通 PowerShell 找不到 pnpm 是本机工具链/PATH 问题，但文档可以降低恢复成本。

期望行为

至少满足以下一种恢复方式：

1. 自动选择器在无法可靠确认宿主原生对话框可见时选择 browse，或提供明确的 CLI/profile 选项强制 native/browse。
2. browse 首次 home listing 返回 directory-unreadable 时，弹窗明确显示“输入绝对路径”操作，并把焦点或按钮引导到路径编辑器。
3. browse 后端允许部署方配置初始目录，例如 defaultPath；如果增加 browseRoot，应明确它只是 UX 范围还是安全限制。
4. 启动发现端口占用时，提示当前端口、可能的已有实例、查询 PID 的命令，以及更换端口的正确参数。

建议改进

A. 提升自动后端选择的可控性

• 为 Web 启动提供显式选项，例如 --directory-picker=native|browse|auto，或在公开 profile 配置文档中给出一段官方覆盖示例。
• 如果 Codex/自动化/隐藏启动上下文存在稳定信号，将其纳入 directory-picker-auto 判断。
• 启动日志输出最终选择的后端及原因，例如 directory picker: browse (forced by profile)，便于直接诊断。

B. 改善 browse 首屏失败后的恢复体验

• directory-unreadable 时显示本地化说明，例如“无法读取默认主目录。请输入一个可访问的绝对路径，或在宿主终端重新启动服务”。
• 增加带文字的“输入路径”按钮，不只依赖铅笔图标；首次列表失败时可自动聚焦路径输入框。
• 保留原始 EPERM 详情供展开查看或复制，不要丢失诊断证据。
• 可考虑给 BrowseDirectoryPicker.Config 增加 defaultPath。该字段应在插件加载或第一次可解析时验证为完全限定路径，并明确读取失败行为。

C. 改善 Windows 启动文档

• 明确命令必须从仓库根目录运行。
• 明确 DSH_HOME 需要在启动命令所在的同一个 PowerShell 会话设置。
• 在 pnpm 不可用时给出 Corepack 检查步骤：corepack enable、pnpm --version。
• 对 Codex 桌面环境补充说明：内置 pnpm 可能只对 Codex 进程可见；普通终端应使用系统 Corepack/pnpm，Codex 私有 runtime 的绝对路径只能作为本机临时恢复手段，不宜作为通用文档命令。

D. 改善端口占用诊断

• 在 Windows 上可行时，启动错误中附加监听 PID；无法可靠查询时至少提示：

netstat -ano -p tcp | Select-String ':3080'

• 提示只终止确认属于旧 dsh web 的 PID，避免给出宽泛的 Node 进程清理命令。
• 在错误中显示更换端口的 CLI 用法。

建议验收条件

• 在 Windows 上模拟 home opendir 返回 EPERM，应用内弹窗仍提供清晰、可键盘操作的绝对路径恢复流程。
• 自动选择器或显式配置能在隐藏/无人值守的宿主启动中稳定选择 browse。
• directory-unreadable 的 UI 同时包含面向用户的恢复动作和可复制的底层错误详情。
• 3080 已被旧实例占用时，启动错误能引导用户识别旧实例或使用其他端口。
• Windows 文档中的最短启动流程能从一个未预先配置 pnpm 的普通 PowerShell 开始完成。

可提供的附件

• “选择工作区目录”弹窗的 EPERM 截图
• 完整 EADDRINUSE 堆栈
• netstat 连续采样结果
• 最终成功启动和 HTTP 200 验证输出

DeepSeek Harness Windows workspace picker incident =================================================

This attachment is redacted for public sharing.

Environment

• OS: Windows PowerShell
• Project version: @deepseek-ai/dsh-root 0.1.0-rc.5
• Node.js: v24.19.0
• pnpm: 11.19.0 (repository packageManager: pnpm@11.7.0)
• Web URL: http://127.0.0.1:3080

1. Reproduced filesystem symptom

---

Command:

node -e "require('node:fs').opendirSync('C:\\Users\\<username>')"

Result:

EPERM: operation not permitted, opendir 'C:\Users\<username>'

The directory picker uses os.homedir() when no path is supplied, so the first
browse request targets the same home directory.

2. Wrong working directory symptom

---

Command was first run from C:\Users<username>:

<pnpm command> dsh web

Result:

[ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND]
No package.json (or package.yaml, or package.json5) was found in
"C:\Users\<username>"

Recovery:

Set-Location 'D:\deepseek-harness-master'
$env:DSH_HOME = 'D:\deepseek-harness-master\.dsh-runtime'

3. Port collision symptom

---

Result while the restricted old service was still running:

listen EADDRINUSE: address already in use 127.0.0.1:3080

Read-only netstat sampling identified the listener:

TCP    127.0.0.1:3080    0.0.0.0:0    LISTENING    <old dsh web PID>

The old process tree was stopped only after confirming that it was the old
dsh web instance:

taskkill /PID <old dsh web PID> /T /F

4. Successful recovery

---

The service was then started from a normal Windows PowerShell session, from
the repository root, with the existing DSH_HOME:

Set-Location 'D:\deepseek-harness-master'
$env:DSH_HOME = 'D:\deepseek-harness-master\.dsh-runtime'
& '<Codex runtime>\\dependencies\\bin\\fallback\\pnpm.cmd' dsh web

Output:

dsh web: http://127.0.0.1:3080

Validation:

GET http://127.0.0.1:3080 -> HTTP 200
Content-Type: text/html; charset=utf-8
Listener PID: <new dsh web PID>

The existing .dsh-runtime configuration, workspace registration, and session
data remained available after the restart.

Source references

• packages/host/directory-picker-browse/src/index.ts
• packages/host/directory-picker-auto/src/resolve.ts
• packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx
• packages/client/runtime/src/client/workspaces/service.ts
• packages/host/apiproxy/src/api/host.ts
• .dsh-runtime/profiles/web/cordis.patch.yml

[PerryLink]

这份报告里三个阻塞实际上是互相独立的三件事，各自的判据不同，分开说。

一、原生选择器为什么「不可见」——这是判据不足，不是对话框坏了

自动后端是一个纯函数 + 启动期一次性采样，四条提前返回，全部输入有五个：bindHost、ssh、platform、linuxChooser，以及 env（只读其中的 DISPLAY / WAYLAND_DISPLAY）：

条件	选谁
bindHost !== '127.0.0.1'	browse
是 SSH 启动（继承的 SSH_CONNECTION/SSH_TTY）	browse
platform 是 darwin 或 win32	native
linux 且 PATH 上没有 zenity/kdialog	browse
linux 有 chooser，但 DISPLAY / WAYLAND_DISPLAY 都没有	browse

源码 packages/host/directory-picker-auto/src/resolve.ts:49-55（:54 就是读 facts.env.DISPLAY / facts.env.WAYLAND_DISPLAY 那一行），判定输入在 packages/host/directory-picker-auto/src/index.ts:63-69 采样、packages/host/directory-picker-auto/README.md:58-66 有同一张表。

你的情形命中第三行：win32 直接返回 native，后面两行（linux 才走）根本不会执行。没有任何输入能表达「这次是隐藏后台进程启动的、操作者看不到宿主桌面」，所以「选了 native 却没人能操作它」是这个设计的必然盲区，而不是 Windows 对话框实现失败——你自己那句「仅凭这次现象不能断言 IFileOpenDialog 实现本身失败」是对的。

这一点包文档已经把它列为已知限制（packages/host/directory-picker-auto/README.md:108），原话是「Detection infers operator location from launch context, which no launch-side signal can prove」，并明确举了「通过 ssh -L 到达的本地启动会解析成 native 并在无人值守的工作站上弹窗」这个同构例子，给出的官方建议就是：这种部署直接组合 -browse 那一行。

所以你第 3 步做的 profile patch（disabled: true 关掉 auto + 手动组合 browse 的 Host/Client 两侧）就是官方文档给的正确解法，不是绕过。补一条：这个决策只在启动时采样一次，改完 patch 必须重启生效。

二、应用内浏览器读不到主目录——EPERM 来自外部的文件系统沙箱

两点先确认：

1. browse 后端在没有路径参数时确实从 os.homedir() 起步：packages/host/directory-picker-browse/src/index.ts:217-225（const home = homedir() → resolve(path ?? home) → opendir(target)）。
2. 它的 Config 只有一个字段 maxEntries（:195-197 的 schemastery 定义，README 的配置表同样只有这一行）。没有 defaultPath / initialPath / browseRoot —— 所以你「无法仅通过插件配置把首次列表改为已授权目录」的判断成立。README 还专门说明了「whole-filesystem scope」是有意为之：没有 per-deployment browse-root，加一个也只是 UX 范围而不是安全边界（packages/host/directory-picker-browse/README.md:112）。

而那个 EPERM 本身不是 DSH 的沙箱造成的。你的服务继承的是 Codex 桌面环境那个受限上下文，os.homedir() 返回 C:\Users\<用户名>，进程无权枚举它 —— 这是宿主进程自己的文件系统权限，DSH 侧没有 ACL 判断参与。所以这条路不应通过「放宽产品文件系统策略」来修（你自己那句判断也是对的）。

你能用的恢复入口已经存在：路径编辑按钮在「首屏 home listing 失败、parent === null」时仍然可用，点铅笔可以直接输入绝对路径。源码里写得很明确 —— packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx:850-853 的注释：「Stays available with no listed level: when the home listing itself fails, typing an absolute path is the one remaining way forward」，:864-865 再一次点名它是 failed home listing 的 recovery path。你指出它「没有文字说明、容易被理解为整个弹窗不可交互」——这是真实的可用性问题，如果官方要改，最小改动是给它加文案和首次失败时的自动聚焦。

当前版本的可用绕过：别在受限上下文里起服务。在普通 PowerShell 里、从仓库根目录起，一次设好 DSH_HOME：

Set-Location 'D:\deepseek-harness-master'
$env:DSH_HOME = 'D:\deepseek-harness-master\.dsh-runtime'
pnpm dsh web

（pnpm dsh web 走仓库根的 dsh script；裸 dsh web 只在全局安装下可用。）

三、端口被占用——报错里没有 PID，但有现成命令

EADDRINUSE 是 Node 的原始 listen 错误，DSH 侧没有把它加工成「带占用 PID + 已有实例提示 + 换端口用法」的形态（在 dsh web 的 CLI 路径上没有针对这个 errno 的分支）。你用的 netstat -ano -p tcp | Select-String ':3080' 就是当前环境下正确的定位手段。

换端口现在有 flag 了：

pnpm dsh web --port 8080   # 换端口（全局安装的 dsh 则用 dsh web --port 8080）
pnpm dsh web --port 0      # 让 OS 分配一个空闲端口
pnpm dsh web --help        # 看这个 app 自己的 flag 列表

（--host / --port / --trusted-host / --no-open 属于 web app；flag 优先于组合配置里写死的值，见 apps/cli/reference/README.md:88「--host and --port override the composed values」。）你报的那个 0.1.0-rc.5 就已经有 dsh web --port 了：把 flag 交给 web app 自管的那个提交是 82728808d4（2026-08-10 23:45），而 0.1.0-rc.5 的发布提交是 2026-08-13 18:49，晚于它 —— 我直接读了该发布提交树里的 packages/bundle/web-app/src/startup.ts，.option('--port <port>', …) 已经在里面；0.1.0-rc.6、0.1.0-rc.7 同样包含。npm 上 @deepseek-ai/dsh 最早一次发布（0.0.1-rc.1，2026-08-10T19:41Z）也晚于 82728808d4，所以所有已发布版本都带 --port，不用先验证「你那个版本有没有」。

关于「原生选择器」这一条官方可以怎么改

按性价比，我会把这两条排在最前：

1. 启动日志里打印最终选中的后端与理由（directory picker: browse (forced by profile)）——现在这个决策对用户完全不可见，是本次排查成本的主要来源。
2. 或者提供一个显式的 --directory-picker=native|browse|auto，让隐藏/无人值守启动能一次选对。

如果这条解释解决了你的问题，可以把它标为 answer，方便后面从类似 IDE/桌面环境后台启动 dsh 的人找到。