37 lines
4.8 KiB
Markdown
37 lines
4.8 KiB
Markdown
# @deepseek-ai/dsh-pty-local
|
||
|
||
[English](README.md) | 中文
|
||
|
||
这是基于 `ctx.subprocess.spawnTerminal` 的 `ctx.pty` 持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
|
||
|
||
## 插件（`pty-local`）
|
||
|
||
该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
|
||
|
||
就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
|
||
|
||
取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
|
||
|
||
## 模型体验
|
||
|
||
### 间接消费方
|
||
|
||
#### 模型看到的内容
|
||
|
||
没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
|
||
|
||
#### Token 影响
|
||
|
||
消费方返回有界的后端输出前没有影响。此包不会把保留的 PTY scrollback 放入模型历史。
|
||
|
||
#### KV Cache 影响
|
||
|
||
不会直接失效；提示词、schema 与追加结果由消费方负责。
|
||
|
||
## 已知限制与暂缓工作
|
||
|
||
- 输出按行规范化；不支持全屏备用缓冲区交互。
|
||
- 精确 stdin 等待检测取决于挂载的进程管理提供方；无法证明该事实的提供方使用提示符标记和静默／超时就绪机制。
|
||
- 清理保证遵循 `SubprocessTerminalHandle`；提供方特有缺口属于该实现的契约，而非此 PTY 消费方。
|
||
- 会话无法跨 harness 进程退出保留。
|