dsh-interactive-terminal

DeepSeek Harness (DSH) 的核心设计理念是「一切皆插件」。在 Web 端开发智能体时，如果需要让模型直接执行 Shell 命令并保持会话状态，传统的方案往往需要跳转到本地终端。dsh-interactive-terminal 插件通过在浏览器中嵌入一个持久化的 PTY 终端，解决了这一割裂问题，实现了模型与用户在同一界面内的交互。

插件定位¶

这是一个由维护者 mingzhicode 开发的客户端插件。它利用 xterm.js 在 DeepSeek Harness Web 界面中渲染终端，允许 Agent 通过工具调用（shared_terminal_send）运行程序，同时也支持人类用户接管控制权继续交互。插件的核心目标是提供单 Agent 终端控制机制，确保一次只有一个视图可以写入终端，其他视图保持只读。

核心功能¶

持久化 Bash 会话：在 DSH Web 中运行持久化 Bash 终端，面板折叠或断线重连不会结束 Shell。
模型与用户共享：模型可以通过工具调用运行程序，人类用户可以接管并继续交互。
基于 xterm.js：使用标准的 Web 终端 UI 进行渲染。
单控制器机制：仅允许一个浏览器视图控制 Agent 的终端，其他视图为只读。
状态恢复：支持 PTY 屏幕快照恢复与断线重连。

安装与启用¶

安装和启动必须使用相同的 DSH_HOME（默认为 ~/.dsh）。

前置要求：
* 操作系统：macOS 或 Linux
* Shell：Bash
* 工具：Node.js (^22.19 || >=24)、pnpm（需在 PATH 中，版本 10.18.3）
* DSH 版本：0.1.0-rc.8

安装步骤：

在终端中执行以下命令安装插件包到 Web 配置文件中：

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

启动 DeepSeek Harness Web：

    dsh --profile web

在浏览器中打开打印出的 URL，配置模型和会话后，点击 Open terminal。
在空闲提示符下输入 echo hello 验证浏览器输入。

交互流程¶

插件接管终端后，存在明确的控制权流转逻辑：

打开终端：点击 Open terminal。首次展开或 Agent 调用工具时，Shell 会懒加载创建。
确认控制器：确认状态显示为 Controller。在空闲提示符下直接输入，首次按键请求人类输入所有权，后续按键等待授权。
模型运行：模型调用 shared_terminal_send 运行程序。此时模型拥有操作队列，普通键盘输入会被忽略。
接管输入：当程序请求输入时，点击 Take over input 并等待授权后再输入。这种接管保留了进程，不发送信号，并移除模型的操作截止时间。
继续交互：在同一个 PTY 中继续输入文本、换行或 UTF-8 字符。换行提交输入但不会释放所有权，直到 Shell 提示符确认或进程退出。
中断：使用 Interrupt input 发送 SIGINT，这会中断程序并保留所有权，直到提示符恢复。

配置说明¶

插件支持通过配置文件覆盖默认行为。配置文件路径为 ~/.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

配置生效后需要重启 DSH。以下是可配置字段的默认值与效果：

字段	默认值	效果
`shellPath`	`/bin/bash`	Bash 可执行文件，仅支持 Bash，其他 Shell 会被拒绝。
`shellArgs`	`--noprofile --norc -i`	交互式 Shell 参数，空参数会被拒绝。
`rows`	`40`	每个 PTY 生成固定的行数。
`cols`	`160`	每个 PTY 固定的列数。
`scrollbackLines`	`10000`	视口外的保留历史行数。
`scrollbackMaxBytes`	`4194304`	序列化 ANSI 历史记录的字节限制。
`maxToolOutputBytes`	`262144`	工具结果 JSON 的完整限制。
`maxInputBytes`	`65536`	每次模型发送或接受的人类输入租约的字节限制。
`maxQueuedOperations`	`128`	每个 Agent 允许的变更数（含当前操作）。
`maxSessions`	`32`	活跃的 Agent 终端最大数量。
`pollIntervalMs`	`50`	前台进程检查间隔。
`operationTimeoutMs`	`30000`	模型变更截止时间。
`interruptTimeoutMs`	`5000`	`SIGINT` 后受控提示符恢复截止时间。
`disconnectGraceMs`	`15000`	恢复连接前的宽限期。
`disposeGraceMs`	`3000`	重置或清理时的进程树终止宽限期。

注意事项¶

环境一致性：安装和启动必须使用相同的 DSH_HOME，否则插件可能无法加载。
依赖检查：如果 pnpm 报告没有版本可用，请检查是否使用了公共注册表（如 registry.npmjs.org）。
视图限制：一次只有一个浏览器视图可以控制 Agent 的终端，其他视图和移动视图为只读。如果需要接管，必须关闭当前控制视图并等待 disconnectGraceMs 后重连。
更新：修改配置文件后需要重启 DSH 才能生效。

总结¶

dsh-interactive-terminal 为 DSH 生态提供了一套标准化的终端交互方案。通过共享 PTY 和精细的输入控制逻辑，它让模型在 Web 界面中的自动化操作更加贴近真实的终端体验，同时也为开发者提供了灵活的配置空间。

插件目录：dsh-interactive-terminal
源码地址：mingzhicode/dsh-interactive-terminal