5.2 KiB
description, kind
| description | kind |
|---|---|
| 用户交互式终端:执行环境默认 shell、有界屏幕恢复和类型化 Remote 控制。 | package-reference |
@deepseek-ai/dsh-api-terminal-controller
English | 中文
概述
从 Web 侧栏在会话工作区打开执行环境的默认 shell。重新连接已有进程,并关闭 provider 管理的完整进程范围。终端输出不进入 Agent 对话记录。保留终端会占用进程和有界屏幕缓存。
目录
使用此包
Web bundle 将此包与 subprocess provider、sandbox policy 和 Typert Gateway 一起挂载。remote.terminal 提供 environment、list、create、follow、write、resize、rename 和 close;每个操作均按 Session 标识限定范围。
新终端使用执行环境声明的默认 shell。仅当 provider 未声明默认值时,才在 POSIX 使用 /bin/sh,在 Windows 使用 cmd.exe。可选的 shell profile 通过可执行路径 path、显示名称 name 和参数 args(默认 [])覆盖这一选择。provider 在创建时验证可执行文件;解析失败会直接报告,不尝试其他 shell。环境查询只返回工作目录和限制,不解析 shell,因此默认 shell 不可用时仍可重新连接已有进程。POSIX 自动 profile 以交互模式启动,PowerShell 使用 -NoLogo,补全和启动配置仍由 shell 提供。初始目录来自 Session 工作区,终端遵循同一 sandbox policy。
| 配置 | 默认值 | 含义 |
|---|---|---|
shell |
省略 | 使用执行环境默认 shell,或指定一个 profile |
maxTerminals |
8 |
每个 Session 保留的终端和创建请求上限 |
maxCols、maxRows |
500、200 |
PTY 最大尺寸 |
scrollback |
1000 |
屏幕历史行数 |
maxBufferedBytes |
2097152 |
单个订阅者的输出排队上限 |
maxInputBytes |
65536 |
单次输入请求的字节上限 |
disposeGraceMs |
1000 |
provider 终止宽限期,单位毫秒 |
了解实现
实现细节
Host 通过 ctx.subprocess.spawnTerminal 创建 TERM=xterm-256color 的终端,不启动桌面终端应用。控制请求走 Gateway,follow 使用其复用的 Remote stream。Headless xterm 和序列化 addon 在此前输出写入后生成初始屏幕,后续增量携带单调序号。过慢的订阅者明确失败;重新连接恢复当前屏幕。
最新连接持有输入和尺寸控制权。断开连接只释放输入权,不结束进程。显式关闭等待进程清理和最后输出;清理失败时保留资源以便重试。Session 记住已关闭的标识并拒绝迟到或重复的创建请求,包括关闭到达时仍在进行的创建。新终端使用新标识。取消创建且清理失败时,已分配的进程仍有所有者。Session owner 和 controller 卸载也会终止所拥有的进程。存在终端或创建请求时不能改变该 Session 的 sandbox mode。
Client 视图只在内存中关联侧栏标签页与终端标识。恢复操作查询 Host 保留的终端;新视图可以创建进程,恢复视图在目标缺失时显示错误,不创建替代进程。Client 模型在浏览器完成屏幕解析后确认帧,按序发送输入,并忽略旧连接迟到的响应。
关闭时先保存未完成的清理请求并释放标签页,再在后台等待 Host 清理。失败时提供重试通知。每个请求使用独立的终端 ID localStorage key,清理成功后删除;启动时重试已保存的请求。保存的是清理意图,不是侧栏布局、打开标签页映射、选中标签页或进程 PID。浏览器存储不可用时,内存中的清理仍可工作,但刷新后无法恢复该请求。
延伸阅读
模型体验
无;此包只处理用户交互式终端,不向模型请求添加内容。
KV 缓存影响
无;终端输出只在浏览器与 Host 之间传输。
已知限制与延期工作
- 浏览器刷新保留进程和屏幕;Host 或 Session owner 卸载不保留。不提供持久终端恢复或自动重启 shell。
- 原生 PTY 可用性和进程树清理保证由 subprocess provider 决定。找到可执行文件并不保证 PTY 分配成功。
- 屏幕恢复只保留有界历史,不保留完整记录。同一时刻只有一个连接可输入或调整尺寸。
开发备注
维护说明
不发布运行时 invariant companion。终端元数据与屏幕更新由同一对象按序写入,没有独立的进程尺寸观测可供比较。