@mzzsfy/dsh-shared-terminal
v0.4.8
Published
AI 与用户通过 DSH 官方交互终端共同操作 Session shell
Readme
DSH 共享终端
AI terminal 工具与用户通过 DSH 官方 Sidebar terminal tab 操作同一 Session-owned shell,并对同一终端的 Host xterm active viewport 做只读快照。写入通道随宿主代际:0.2.0 与 0.2.1-alpha.2 代 AI 借用官方 xterm UI 的输入 attachment 写入;0.2.1-rc.2 起插件自持输入附着(attach 泵,见下)。
功能
只注册一个工具 terminal:
| 动作 | 参数与语义 |
| --- | --- |
| open | 当前 Session 创建官方终端,返回 terminal_id。默认 cols=80, rows=24,整数范围 cols=2..300, rows=1..200,宿主仍可进一步限制;shell_path 只能选择 Controller 发现的 shell。成功结果挂载后打开官方 tab。 |
| list | 列出当前 Session 终端的标题、目录、尺寸、状态与附着状态。0.2.1-rc.2 起附着状态以插件泵为准(Controller info 不暴露 controllerId),其他代际沿用 Controller 的附着标识。 |
| read | 必填 terminal_id;lines 默认 20,范围 1–200。读取 active buffer viewport 内最新内容起的最多 N 个物理行——以最后一个非空行与光标行(非空时)为界,高窗口不会读到尾部空白;保留内部空行、软换行和当前 alternate screen(整屏坐标)。 |
| write | 必填 terminal_id, text;原样输入,submit=true 附加 CR。0.2.0 与 0.2.1-alpha.2 蹭 UI attachment 写(无附着返回 NOT_ATTACHED,不创建 follower、不抢 control);0.2.1-rc.2 起自持 attach 泵:写入时抢附着,空闲冷却 10s 后释放(冷却期内连续写复用同一附着,sequence 递增;释放后首写重建附着并重置 sequence,最后写入者胜出,用户可随时接管);重抢仍失败返回 TERMINAL_ERROR,可重试。 |
| wait | 必填 terminal_id, text;text 为待等待子串(大小写敏感逐字),timeout_ms 默认 10000、范围 100–55000(上限为工具超时减返回余量)。阻塞轮询屏幕直到 text 出现(found,携带命中时刻屏幕快照与 elapsed_ms)、终端进入 exited/failed(exited,退出优先于命中)、用户手动跳过(skipped,携带跳过时刻屏幕快照)或超时(timeout,携带 timeout_ms 与最后一次屏幕快照)。匹配面为 read 同款 active viewport:滚出屏幕的历史不参与匹配;等待中终端被关闭返回 TERMINAL_UNAVAILABLE;回合取消即中止。轮询间隔 100ms。 |
| close | 必填 terminal_id;通过官方 Controller 关闭终端,同一 Session 重复关闭保持宿主的幂等语义。 |
read 返回 text, lines, truncated, state, sequence;truncated 表示该读取窗口上方仍有当前 viewport 行未返回,不表示截断历史。sequence 是宿主输出帧编号,不是所有屏幕变化的修订号。请求行数超过屏幕内容范围时只返回实际内容行数。wait 复用同一快照形状并增加 kind;长命令(构建、服务启动、交互提示符)用 wait 同步完成信号,替代反复 read 轮询。
open 结果提供“打开终端”按钮;已有匹配 tab 则揭示该 tab,不重复打开。read/write/close 只呈现结果,不触发导航。历史 open 结果只能打开仍存在的终端,不能恢复已经关闭的 PTY。
会话内工具卡片
terminal 调用在会话流中经官方 tool.call.toolview 槽位渲染:动作标题 + 摘要 + 可展开详情(read/wait 的屏幕文本、list 的终端清单、write 的输入回显、open/close 的终端短 ID);wait 摘要为等待子串并以徽章标示 found/timeout/exited/skipped 终态。错误显示错误码与消息,参数或结果无法解析时回退原文行。文案经 locale 字典注册(中英双语),图标与文本微光使用官方 primitives,样式注入按 data-plugin 契约。
wait 手动打断(0.4.0 起)
wait 等待期间,工具卡片以等待子串替代「执行中」摘要(提示正在等什么)并显示「跳过等待」按钮;点击经宿主路由 /api/shared-terminal/wait/skip(POST JSON {sessionId, terminalId})中断该终端当前全部 pending wait,wait 以 skipped 终态携带当前屏幕快照返回,AI 继续后续步骤——不打断回合。判定次序:回合取消 > 终端退出 > 文本命中 > 手动跳过 > 超时。路由首行回问宿主 connection.requestRejection(无 cookie 401),并保留 Origin 同源比对,不自建认证层。
只读终端自愈
宿主在附着结束时只把 controller 清空,不把 writable 交还 UI——宿主按 controller === follower 判定可写,泵 detach 后 UI 即长期只读,直到用户点「接管输入」。UI 只读分支跳过 fitScreen,只按 info.cols/rows 固定 xterm;窗口或侧栏变矮后,底部内容被 .screen{overflow:hidden} 裁掉且 viewport 不可滚,用户于是「看不全」。0.4.3 起插件客户端做兜底自愈:每 6s 扫可见的 [data-sidebar-terminal],若「宿主只读状态栏在场 + 内容超出容器(扣除状态栏自身占位,状态栏挤矮不算裁切)+ 屏上 Session 没有附着中的泵」同时成立,就点宿主「接管输入」,UI 重新附着成控制者后由宿主自己按容器重算几何。泵附着期间不动(宁可漏自愈也不抢 AI 的写入,否则下一次 write 会以 read-only 被拒),命中后 5s 冷却防抖。0.4.8 起两处收紧:viewport 仍可滚动(overflowY 非 hidden)时不算被裁,裁掉的只是用户能滚回去的 scrollback,避免每次 AI 写完都白抢一次;接管会让宿主把焦点拉到终端,因此点击后若用户焦点原本不在终端,下一帧(requestAnimationFrame)把焦点还给原元素,仅在 document.activeElement 已落进终端时才动作。
附着判定经宿主路由 /api/shared-terminal/pump(POST JSON {sessionId})回答整条 Session 是否有泵在写,返回 {ok, attached};查询失败或超时按「仍在附着」处理。该判断按 Session 汇总而非按 tab:tab id 在不同 Session 之间会重号,按 Session 保守处理只会漏自愈,不会误抢控制权。
终端面板复用
宿主的 terminal tab 类型注册为 multiple,openTabIn 每次调用都生成新的随机 contentId 并新建 tab。工具结果卡片会在刷新、切会话、重新挂载时重新渲染并导航,按 openTabIn 处理就会不断叠出多个共同指向同一终端的面板——每个面板各挂一份 xterm 与终端订阅,页面越用越卡。0.4.3 起按 terminalId 固定 contentId(dsh-resource://dsh-shared-terminal/panel/<terminalId>)走 openResourceIn,宿主按 findContentTab 复用同一面板,插件面板一终端一址;用户自己用官方「新建终端」打开的面板不再被改写,导航另按 sessionId:terminalId 去重(原按 callId,刷新即失效)。
终端查询应答(0.4.7 起)
Windows 的 ConPTY 在终端尺寸变化后向终端侧发 ESC[6n(DSR 光标查询)并阻塞等待应答;500ms 未收到就重发,一次 resize 实测重试到 3 次。宿主把这段查询当普通输出广播,浏览器 xterm 会在 onData 里自动回 ESC[1;1R,而宿主客户端把它与键盘输入走同一条通道写回 PTY。ConPTY 只消费一个应答,多余或迟到的应答成为 shell 键盘输入:提示符后出现 ;1R;1R;1R 残片,命令首词被吞(RRRecho … → command not found);没有 UI 面板时则无人应答,bash 连首次提示符都不绘制。
插件在服务端接管这条链路:包装宿主 BrowserTerminal#output,按出现位置摘出 ESC[6n、ESC[?6n、ESC[c,同批同类只应答一次,按 xterm-headless 当前光标回写。远端 follower 看不到查询,也就不会再产生应答;ConPTY 在 500ms 内得到应答,不再重试。这是本包唯一的宿主内部改动,边界与 read 相同:结构漂移时安装失败、工具照常工作(回到宿主原行为),不抛错、不阻塞启动。响应器依赖 output/handle.write/screen.buffer.active 三处私有形状;允许表内旧代际若字段不同,同样走安装失败回落路径。
write 另做输入卫生:submit=true 且 shell 是 POSIX 系列、当前为 normal buffer 时,payload 前置 Ctrl+U(0x15),清掉已落入输入行的残片;alternate buffer(TUI)与 cmd/pwsh 不加。
权限与版本边界
命令由 shell 执行;本工具不做命令安全校验。Controller 使用 system-user execution permissions,不受 Agent sandbox/approval 策略约束。命令可能修改系统用户有权限访问的文件。回合取消会拒绝尚未完成的插件泵写入并丢弃该附着尚未消费的输入;已经交给 Controller/provider 的 write/close 无法撤销。同代并发写随取消一起中止时,其他尚未确认的写报结果未知且不自动重发,以免重复执行已经投递的输入。卸载与关闭永久销毁对应泵,旧引用不可继续写入或自动重抢;关闭失败也不复用旧附着,仍允许再次尝试关闭。
仅支持实测版本 DSH 0.2.0-rc.1、0.2.0-rc.2、0.2.1-alpha.2、0.2.1-rc.2、0.2.1-rc.3、0.2.1-rc.4、0.2.1-rc.5、0.2.2-alpha.3、0.2.2-rc.1、0.2.2-rc.2 与 0.2.2-rc.3(精确允许表;其他版本启动时干净禁用并告警)。read 使用这些版本共同的 @deepseek-ai/dsh-api-terminal-controller 私有 owner lookup、BrowserTerminal operation queue 和 xterm-headless active buffer。新建终端的工作目录:0.2.0-rc.2 为创建时的宿主默认工作区目录;0.2.1 起为 Session 当前目录(Controller 工作目录服务)。插件不重建 PTY、不读取 serializer 输出;唯一的宿主内部改动是服务端接管终端查询应答(见上);附着策略随宿主代际:0.2.0 系与 0.2.1-alpha.2 蹭 UI 附着写入(不调用 follow 抢 attachment),0.2.1-rc.2 起自持 attach 泵(见下)。
装载与功能是两层:peerDependencies 声明装载面(允许宿主装载后走停用路径),允许表声明功能面。dsh 0.2.1-rc.2 实测:Controller 移除 write/resize 公开方法,输入改经 attach 命令帧通道——本包自持 attach 泵适配该模型:工具 write 时插件成为控制者(0.2.1-rc.2 输入排他),最后一笔写入 ack 后空闲冷却 10s 才释放附着。释放仍必要:无人附着时宿主向 UI 广播状态使其恢复可写并按容器重算终端几何——若泵永久附着,UI 长期只读,官方布局重算被跳过,插件写入推高的 PTY 行数会把终端底部推出可视区且滚动失效。冷却期亦必要:写完立即释放会让每次写入都经历 attach/detach,宿主 gateway cancellableStream 的 abort 竞态偶发吞掉 UI 输出流的终止信号(实机复现:渲染冻结在旧屏、phase 停留 connected,须换代重连恢复);高频连续写场景下"写完即释放"的停摆概率显著,冷却把 attach/detach 频率从每写一次收敛到每轮命令一次。用户点官方「接管输入」随时拿回控制权;用户接管后泵的下一次写入会重新附着抢回(最后写入者胜出,双方交替互斥)。0.2.1-rc.2 上切走浏览器页面等价于放弃输入控制权,AI 写入不再依赖 UI 附着。
Host 启动检查 Controller 版本、方法和 owner map;检测不匹配时不注册工具并告警。每次读取另检查终端实例、队列和屏幕结构,失败返回 TERMINAL_UNAVAILABLE。这不是公开 API,升级后不保证兼容。
安装与重装
在已安装受支持 DSH 版本的环境中,用 dsh plugin --profile web add @mzzsfy/dsh-shared-terminal 安装已发布版本,然后重启该 profile 的宿主;重装或升级即重新执行同一命令并重启。仓库版本与 npm latest 同步,该命令获取的就是当前发布版本。
仓库开发态在仓库根使用唯一链接入口;Windows 脚本固定操作 %USERPROFILE%/.dsh/profiles/web,需该 profile 已初始化且 pnpm/cmd 可用,不跟随隔离 DSH_HOME:
node scripts/dev-link.mjs dsh-shared-terminal新增 bundle 后需重启宿主;不需要改 DSH 源码或构建官方前端。此插件客户端已按宿主 classic-script ModuleLoader 格式编写。
验证
测试需要任一受支持版本完整、独立安装的宿主闭包(独立 DSH_HOME 安装该版本即得)。宿主目录指包含该宿主 node_modules 的目录,不是 Controller 包目录:
# 在插件包目录执行
npm test -- /path/to/isolated-dsh-host也可设 DSH_TEST_HOST。runner 校验精确 Controller 版本后将绝对宿主路径传入子进程;测试 helper 从该宿主显式解析、校验并导入受支持版本的 Tools 与 Controller(同一允许表),不依赖 ESM 的 NODE_PATH 查找。未提供宿主且普通模块解析链缺少限定版本时明确失败。旧 Controller 没有 attach 时,attach 专属真实生命周期场景会明确跳过;验证 attach 修复必须另跑支持 attach 的主测宿主,要求这些场景全部执行且通过。
测试包含真实 BrowserTerminal/xterm 的宽字符、组合字符、软换行、scrollback、alternate buffer、resize、队列与关闭竞态;UI 附着夹具按宿主能力使用 follow/resize 或 attach resize 命令帧,验证读取排在 resize 之后,且原 follower、控制者和可写权限保持不变。其 subprocess 边界为测试替身,不等于真实 shell E2E。真实 shell、工具调度和客户端装载须在独立 DSH_HOME、独立 profile、独立端口中另做验收。
dsh 版本兼容
按仓库动态窗口验证(scripts/compat/window.mjs),不预置任何固定版本槽:主测 = 渠道 dist-tag 最新 rc,完全适配口径;基线 = npm latest,不崩溃底线口径;主测与基线同版时收敛单槽。本包声明 dsh.hostMin = "0.2.0-rc.1":低于该代际的宿主 API 面未验证,compat 装载层自动排除。逐格证据见本包 兼容性测试.md,轮次汇总见 docs/兼容性测试/逐包测试进度.md(本地维护,不入库)。
dsh 0.2.1-rc.2 起官方 Controller 移除 write/resize 公开方法,终端输入改经 attach 命令帧通道(gateway 侧 uplink):本包自持 attach 泵适配——工具 write 经 controller.terminal(agent,id).attach() 建立插件侧附着,命令帧 sequence 按附着世代严格递增(空闲冷却释放与重抢后随新附着重置);read-only(用户接管)与 detached(附着流断)触发自动重抢一次,重抢仍失败返回 TERMINAL_ERROR 并提示重试;版本白名单已纳入 0.2.1-rc.2、0.2.1-rc.3、0.2.1-rc.4、0.2.1-rc.5、0.2.2-alpha.3、0.2.2-rc.1、0.2.2-rc.2 与 0.2.2-rc.3(dshReleases compatible)。逐格断言、精确版本允许表与 D01-D15 维度适用表见本包 兼容性测试.md。
