Shell 启动超时 dongkid/dsh-shell-boot-timeout

dsh-shell-boot-timeout

一个很小、单文件的 DeepSeek Harness 插件。

它只做一件事：挂一个 tools/execute 监听器，给 shell 工具的首次调用加上时限。这样当持久 shell 迟迟启动不起来时，会返回一条明确的错误，而不是一直静默空转、直到后端自己的 300 秒超时。

刻意做得很小：零依赖、一个源文件、profile patch 里只插入一行。它不修改任何随发行版分发的包，也不改动任何预设。

适用版本范围

安装前请先看这一节。 这是一个绑定上游具体行为的绕行方案，版本很关键。

| | 版本 |
| 已验证 | @deepseek-ai/dsh 0.2.0-rc.2 |
| 声明范围（package.json → dsh.supported） | >=0.2.0-rc.2 <0.3.0 |
| 已验证平台 | 仅 Windows |
| 未测试 | 0.1.x、0.3.x、macOS、Linux |

声明范围是预期，不是保证——它所依赖的行为只在 0.2.0-rc.2 上复现过。版本检查是软性的：遇到未验证的版本只记一条警告并继续工作，不会让你的 profile 启动失败。

它依赖什么，也就意味着上游哪些改动可能让它失效：

- Cordis 的 tools/execute 瀑布（模式、顺序、替换 signal 的规则）；
- defineTool 把 parameters 归一化成带 properties 的 JSON Schema；
- 两个随发行版分发的 shell 工具的参数形态（见下文《它如何判断该不该限时》）。

如果将来某个版本改动了其中任何一项，插件的表现是退回不限时——它的握手判断会返回 false，而不是在一个本来正常的模式里制造出新的失败。

它解决什么问题

极简模式下的 shell 工具是 @deepseek-ai/dsh-tool-pwsh-persistent，它通过一个持久 PTY 会话 执行命令。它的首次调用必须先启动 shell 并等到 readiness（就绪）。

dsh-terminal-bash 会装入一个 PowerShell prompt 函数，用来发出 OSC 133;D; 标记，并且 只接受 waitReason === 'stdin_read' 作为 shell 已就绪的凭据：

"function prompt { [Console]::Write([char]27 + ']133;D;' + [int]$LASTEXITCODE + [char]7); 'dsh> ' }"

在 Windows 上，当会话运行在 ACL 沙箱的 read-only 模式时，pwsh 会以
ConstrainedLanguage 启动（它写 AppLocker 探针临时文件被拒）。此时 [Console]::Write 报错：

InvalidOperation: Cannot create type. Only core types are supported in this language mode.

于是那个标记永远不会发出。而 Windows 的进程检查器 isStdinWaiting() 恒返回 false，导致该标记成为通往 stdin_read 的唯一路径；启动循环又忽略 inferred_idle 兜底，于是不停重发。
从头到尾没有任何命令被执行，所以也没有任何东西会失败——调用就一直挂着。

触发条件必须是：极简模式 + read-only 沙箱。其它模式用一次性 pwsh 工具，不需要启动握手，在任何权限模式下都正常。

它做什么、不做什么

做：把静默空转变成一条快速的结构化错误：

Error: the shell behind the pwsh tool never reported readiness within 20000ms, so no
command was run. ... Switch the permission preset to workspace-write ...

它会先 abort 再返回：abort 会解除挂起的 PTY spawn，所以被放弃的调用会真的停下来，而不是继续跑到后端的截止时间。

不做：它不会让 pwsh 在「极简 + 只读」下变得可用。这个空转是上游的引导缺陷，profile 插件无法修复；本插件只是让失败变得快速且可自我解释。

它如何判断该不该限时

限时绝不能作用到标准 / PTC / 创造模式——那里用的是一次性 pwsh，它的首次调用就已经是一条真实命令（npm install、跑测试套件），完全可能超过任何固定预算。两者靠声明的参数区分：

| 工具 | 模式 | 声明的参数 | 是否限时 |
| @deepseek-ai/dsh-tool-pwsh | standard、ptc、cordis | command、description、timeoutMs、workdir | 否 |
| @deepseek-ai/dsh-tool-pwsh-persistent | minimal | 仅 command | 是 |

一个接受自己的每条命令 timeoutMs 的工具，说明它立即执行真实命令、已经由调用方限时，因此不干预。读不到或无法识别的 schema 同样按「不限时」处理。

重试安全

被限时失败的调用不会把 shell 标记为已启动，所以重试仍会被限时，不会悄悄退回 300 秒空转。
真正启动成功之后，该 Agent 的限时才会解除，从而让长时间命令保留它们原有的预算。

安装

本插件是一个 DSH bundle：package.json 里声明了 dsh.bundle.patch 的包。用插件管理器安装（install_bundle，传入本目录），包安装与 bundle 选择由它自己完成。

包名与仓库名不同。 包名是 @local/dsh-shell-boot-timeout，而仓库名取自 patch 行的 id （shell-boot-timeout）。该包是 private: true、从不会发布到 npm——@local/ 只是「仅本地」 bundle 的命名惯例，所以这个名字只对 DSH 的模块解析有意义。

需要 pnpm ≥ 10。 DSH 的 profile 脚手架从 pnpm-workspace.yaml 读取 pnpm 设置，而只有
pnpm ≥ 10 才会读那里；pnpm 9 会以 ERR_PNPM_ADDING_TO_ROOT 失败。这是环境要求，与本插件无关。

修改模块文件后必须重启宿主才会生效：Node 的 ESM 加载器会缓存已导入的模块，所以把该行关掉再打开仍会复用旧代码。

配置

| 字段 | 默认值 | 含义 |
| bootTimeoutMs | 20000 | 首次 shell 工具调用的预算。宿主很慢时可调大。 |
| toolNames | ['pwsh', 'bash'] | 有资格被限时的工具名；仍会经过握手判断。 |
| verifiedDshVersion | 0.2.0-rc.2 | 已验证的下界；低于它只记一条警告。 |

配置非法会在激活时抛错（bootTimeoutMs 非正，或 toolNames 为空）。

测试

两套测试都只需普通 Node 运行——不启动 DSH、不联网：

node tests/offline.test.mjs # 12 项：超时、透传、重试安全、配置
node tests/discriminator.test.mjs # 7 项：真实的工具声明

discriminator.test.mjs 从随发行版分发的工具源码里读出参数名，再用 DSH 自己的 parameterSchemaSpecToJsonSchema 归一化，因此「是否限时」这个判断是针对真实声明证明的，而不是对着手写的假数据。它需要本机装有 @deepseek-ai/dsh 才能读取那些文件。

设计说明

- 不覆盖预设。 profile patch 无法伸进预设的 plugins 列表——那个列表是 preset-<id> 行的 config 数据，不是 Loader group。实测针对 persistent-shell 打补丁会得到 patch insert: entry "persistent-shell" not found。而改打 preset-minimal 则意味着每次上游升级都要把整个随发行版分发的预设重述一遍。
- 不注入 terminals。 极简模式的 terminals 提供者位于预设 isolate: terminals: true 的作用域内，宿主平面的行够不到。tools/execute 瀑布是能看见所有预设的公共接缝。
- 最小改动面： 插入一行、注入一个服务（tools）、不新增工具、不改 prompt、不动任何本来正常的模式。

许可

MIT