mingzhicode/dsh-interactive-terminal

dsh-interactive-terminal

在 DeepSeek Harness Web 中提供模型与用户共享的持久 Bash 终端。每个存活的 Agent 独占一个 PTY，通过 xterm.js 显示在对话输入框上方。模型可以调用终端工具，用户也可以在同一交互进程中继续输入，无需另开 shell。

完成多轮 UTF-8 终端交互后的 Controller 视图

模型启动交互程序后，用户完成四轮 UTF-8 输入时的已连接 Controller 视图。

快速开始

要求：macOS 或 Linux、Bash、Node.js ^22.19 || >=24，且 PATH 中有 pnpm。插件 0.1.0 已针对 DSH 0.1.0-rc.8 和 pnpm 10.18.3 验证。

npm install -g @deepseek-ai/dsh@0.1.0-rc.8 pnpm@10.18.3
dsh plugin --profile web add dsh-interactive-terminal@0.1.0
dsh --profile web

打开 DSH 输出的 Web 地址，按需配置模型，选择工作区和对话，再点击 Open terminal（打开终端）。在空闲提示符下输入 echo hello，即可验证浏览器输入。以后启动只需：

dsh --profile web

安装

使用已安装的 DSH CLI 加载 npm 包

dsh plugin --profile web add dsh-interactive-terminal@0.1.0
dsh --profile web

插件命令会把包安装到 Web profile，并自动启用包内的 cordis.patch.yml，无需额外添加 --patch。仅执行 npm install -g 全局安装插件不会在 DSH 中启用它。

安装和启动必须使用同一个 DSH_HOME，默认值是 ~/.dsh。添加或更新插件后，需要重启已运行的 DSH。若 pnpm 报告没有可用版本，请确认 profile 使用 npm 公共 registry：

cd "${DSH_HOME:-$HOME/.dsh}/profiles/web"
pnpm config set registry https://registry.npmjs.org/ --location=project

从 DSH 源码加载 npm 包

使用插件支持的 DSH 标签，再运行仓库中的源码 CLI：

git clone --branch dsh-v0.1.0-rc.8 --depth 1 https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm dsh plugin --profile web add dsh-interactive-terminal@0.1.0
pnpm dsh --profile web

第一个 pnpm dsh 等价于已安装的 dsh 命令，但直接运行源码。Profile 仍保存在同一个 DSH_HOME 下，因此后续从源码启动只需执行最后一条命令。

从插件源码安装

git clone https://github.com/mingzhicode/dsh-interactive-terminal.git
cd dsh-interactive-terminal
pnpm install
pnpm run build
dsh plugin --profile web add "$PWD"
dsh --profile web

Profile 会加载本地 checkout 中已构建的 lib/ 和 dist/ 文件。修改插件源码后，需要重新构建并重启 DSH。如果同时使用 DSH 源码，请在 DSH 仓库中运行 pnpm dsh，并把本插件的绝对目录传给 plugin add。

安装已下载的 npm 压缩包

dsh plugin --profile web add ./dsh-interactive-terminal-0.1.0.tgz
dsh --profile web

压缩包包含服务端和浏览器构建产物，安装时不执行构建或 postinstall；安装依赖仍可能需要访问 registry。可用 npm pack dsh-interactive-terminal@0.1.0 单独下载已发布的压缩包。

交互过程

1. 点击 Open terminal（打开终端）。首次展开面板或首次调用 Agent 工具时，才为该 Agent 创建 shell。
2. 确认状态栏以 Controller 开头。Shell 空闲时可以直接输入；首个按键申请人工输入权，后续按键等待授权。
3. 让模型调用 shared_terminal_send 启动程序。模型操作占用队列时，普通键盘输入会被忽略，不会在稍后变成 shell 命令。
4. 程序要求输入时，点击 Take over input（接手输入），等待授权后再输入。接手保留原进程、不发送信号，并解除模型操作的时限。
5. 在同一个 PTY 中继续输入文字、Enter、emoji 或其他 UTF-8 内容。Enter 只提交输入，不释放输入权；验证过的 shell 提示符或进程退出才结束本轮交互。所有人工交互完成后，无论是从空闲提示符直接输入还是通过接手输入，插件都会直接通知 Agent，使其读取终端并继续执行。
6. 使用 Interrupt input（中断输入） 向重新检查后的前台进程组发送 SIGINT。它会中断程序，并保持输入权直到提示符恢复；它不是输入接手。

设置菜单提供 Reconnect（重新连接）、本地 Clear view（清除显示）、字号调整和需要确认的 Reset Terminal（重置终端）。折叠面板、清屏或重连不会结束 shell；调整面板大小也不会改变固定的 PTY 行列数。服务端销毁终端时，面板会关闭并清理本地渲染器和未发送输入；短暂断线仍会自动重连。

每个 Agent 只允许一个浏览器视图控制终端，其他视图和所有移动端视图均为只读。Take over input 是把模型当前占用的队列操作转交给浏览器 Controller，并不会从另一个浏览器视图夺取 Controller。若状态栏显示 Read only，请关闭控制端视图，等待 disconnectGraceMs，再点击 Reconnect。

配置

在 ~/.dsh/profiles/web/cordis.patch.yml 中添加覆盖项；使用自定义目录时，路径为 $DSH_HOME/profiles/web/cordis.patch.yml：

- id: dsh-interactive-terminal
config:
shellPath: /bin/bash
shellArgs: [--noprofile, --norc, -i]
rows: 40
cols: 160

Patch 会替换该条目的完整 config；请写入所有需要保留的自定义值。省略字段使用下表默认值。

插件加载时解析配置。修改 patch 后需要重启 DSH，新值才会生效。Reset Terminal 会销毁当前 shell，并使用内存中已经加载的配置创建新代次；它不会重新读取 YAML 文件。

| 字段 | 默认值 | 生效方式 |
| --- | ---: | --- |
| shellPath | /bin/bash | Bash 可执行文件，不支持其他 shell；创建终端代次时使用。 |
| shellArgs | --noprofile --norc -i | 交互式 shell 参数，不允许空参数；生成 shell 时使用。 |
| rows | 40 | 每个新终端代次固定的 PTY 行数。 |
| cols | 160 | 每个新终端代次固定的 PTY 列数。 |
| scrollbackLines | 10000 | 保留的历史行数，不含视口；用于服务端快照和浏览器渲染器。 |
| scrollbackMaxBytes | 4194304 | 序列化 ANSI 历史的 UTF-8 字节上限，不含视口。 |
| maxToolOutputBytes | 262144 | 完整工具结果 JSON 的字节上限；至少 1024，且不超过 scrollbackMaxBytes。 |
| maxInputBytes | 65536 | 单次模型发送或一次人工输入授权的字节上限。 |
| maxQueuedOperations | 128 | 每个 Agent 接受的修改操作数上限，包含当前操作。 |
| maxSessions | 32 | 存活 Agent 终端数上限。 |
| pollIntervalMs | 50 | 两次前台进程检查之间的等待时间。 |
| operationTimeoutMs | 30000 | 模型修改操作进入中断恢复前的时限。 |
| interruptTimeoutMs | 5000 | 发送 SIGINT 后等待受控提示符恢复的时限。 |
| disconnectGraceMs | 15000 | Controller 断开后，在恢复并释放人工输入权前保留重连机会的时间。 |
| disposeGraceMs | 3000 | 重置或销毁时终止进程树的宽限时间。 |

方案说明

终端持有与生命周期

- 终端属于确切的存活 Agent，而不是浏览器标签页或某次工具调用。首次展开 UI 或调用工具时，才在该 Agent 的工作区和 sandbox 策略下创建终端。
- 折叠面板和通过认证的重连会保留原 shell。重连先恢复有界屏幕快照，再接收实时输出，并校验终端代次和输出序号。
- 每个 Agent 只有一个浏览器 WebSocket 是 Controller。私有重连凭证可以在 disconnectGraceMs 内恢复控制权；其他桌面视图和所有移动端视图只读。
- 重置会终止当前进程树并创建新代次。Agent 销毁、插件卸载和 HMR 会撤销浏览器连接并终止所属进程树。Shell 自然退出后保留最终屏幕，直到重置。

FIFO 队列、接手与恢复

- 模型发送、人工输入授权、信号和重置共用每个 Agent 的严格 FIFO 修改队列，按接受顺序执行；shared_terminal_read 不占用输入权并绕过该队列。
- 已授权的模型发送可以原地转交给 Controller。接手保留当前队列位置、清除模型超时、向模型返回 waitReason: human_handoff，并让后续操作继续等待。
- 提示符、检测到的前台 stdin_read 或进程退出会完成当前操作。macOS 上的 DSH rc.8 不报告 stdin_read，因此交互提示需要在 operationTimeoutMs 到期前显式接手。
- 模型超时或取消时，会向重新检查后的前台进程组发送 SIGINT，恢复提示符前不会释放队列。若在 interruptTimeoutMs 内未恢复，队列进入 blocked 状态；只有最早接受的 reset 可以替换它。
- 配置会限制队列长度、输入字节、保留输出、工具 JSON 和存活 Agent 终端数。输出快照截断时保留最新的有效 UTF-8 后缀。

Agent 工具

四个工具都作用于当前执行 Agent 的终端。调用者不能另选 Agent、PTY、工作目录、shell、环境或 sandbox。

| 工具 | 行为 |
| --- | --- |
| shared_terminal_send({ text, submit? }) | 排队发送模型输入。submit 默认为 true，会附加 Enter；在提示符、检测到 stdin_read、人工接手、退出或超时/取消恢复时返回。 |
| shared_terminal_read({ offset?, count? }) | 不申请输入权，读取视口和相对最新端的历史分页。offset 从最新端跳过行，count 选择此前的行。 |
| shared_terminal_signal({ signal }) | 排队向重新检查后的前台进程组发送 SIGINT、SIGTERM、SIGKILL、SIGTSTP 或 SIGHUP；拒绝对顶层 shell 发送 SIGKILL。 |
| shared_terminal_reset({}) | 排队终止进程树并创建新 shell 代次，也用于替换自然退出的 shell。 |

结果包含终端代次、输出序号、行列数、视口、光标、进程与队列状态、当前持有者、排队数和截断状态。修改类操作另含排队时长和 waitReason；发送与信号另含捕获的操作输出。读取另含 text、lineBegin（含）、lineEnd（不含）和 totalLines。光标坐标从零开始。

waitReason: human_handoff 表示用户持有仍在运行的交互，不表示命令已经完成。模型必须等待，不应在人工输入授权之后继续提交回答。超时同样不能证明前台进程已经退出。

恢复与限制

- queue is blocked until reset：中断恢复超时。等待最早接受的 reset；后续修改操作会被拒绝。
- terminal queue is full：等待已经接受的操作完成，不要并行重试。
- terminal capacity reached：先结束 Agent 或等待清理完成，再考虑提高 maxSessions。
- 浏览器写入被拒绝后，需要显式点击 Reconnect。Controller 断开恢复仍遵守 disconnectGraceMs。
- 固定使用 TERM=dumb、固定行列数和 PAGER=cat。不支持全屏或依赖终端查询的 TUI；浏览器会抑制自动生成的查询回复，Host 也没有查询响应器。
- Linux 可以在检测到前台标准输入等待时让出输入权，但 Linux 原生环境和多轮 REPL 尚待验证。

安全

Host 决定终端身份、工作目录和 sandbox 策略。需要隔离时，如果隔离不可用就拒绝启动，不会退回非隔离执行。Shell 不继承 Harness 凭据。

浏览器使用与 Agent 绑定、只存哈希、十秒有效的一次性令牌连接。WebSocket 不接受调用者指定的 Agent、Session 或 PTY 标识。原始终端输出和人工按键不作为会话事件记录；模型工具参数和有界结果仍正常记录。

自定义 subprocess provider 必须和官方 DSH rc.8 provider 一样，在发送信号时重新检查前台进程组，并拒绝对顶层 shell 发送 SIGKILL。

开发与打包

pnpm install
pnpm run build
npm pack --dry-run
npm pack

生成的 .tgz 可以按上方压缩包方式安装。需要隔离验证时，请在安装和启动前把 DSH_HOME 设为新目录。无密钥 Web 测试使用回放模型、真实 Agent loop 和原生 PTY，不等同于实时模型测试。

构建和验证不会发布 npm 包。手工发布前需运行发布检查、核对包内容，并确认 npm 账户、registry、版本和明确的发布授权。不要把凭据写入仓库或日志。

许可证

MIT，见 LICENSE。