前言¶
在 DeepSeek Harness（DSH）里让 Agent 执行 shell，输出往往只在对话流或工具结果里出现片段。长时间编译、交互式提示、TUI 界面时，你很难像本地终端一样「盯着屏幕」跟进；Agent 自己也缺少对「当前终端画面」的稳定读取方式。社区插件 dsh-live-terminal（维护者 Lancang-hzau）在 DSH 右侧栏拉起基于 xterm.js + PTY 的真实终端，把 Agent 的前台 pwsh / bash 调用流式显示到应用内，并提供一整套 live_terminal_* 工具供 Agent 截图、等待、搜索与控制终端。分类为客户端插件；npm 当前版本为 1.2.1，要求 DSH >=0.2.1-rc.2 <0.3.0-0（MIT 许可证）。
这是什么¶
dsh-live-terminal 是 DSH 的可见终端面板插件：Agent 执行的 shell 命令在应用内终端窗口里实时滚动；Agent 可对终端屏幕做「截图」（纯文本、ANSI 或 PNG），并通过工具集等待进程、发信号、分页读取、搜索、在已有 shell 里继续执行命令等。用户也可以手动新建多标签终端、键盘输入、调整尺寸与重连。
与「只看工具返回的 stdout 尾部」相比，它把执行过程变成可观察、可交互、可回溯的 UI，并把同一套能力暴露给 Agent。
核心功能¶
下面按 README 已说明的能力归纳，不展开未在资料中出现的细节。
终端面板与用户操作¶
- 在 DSH 右侧栏显示终端，支持 PowerShell / cmd / bash，多标签、resize、刷新重连。
- 接管默认 shell 工具：Agent 前台
pwsh/bash调用自动在面板执行并实时输出；Agent 开始执行时右侧栏会自动弹出（每个 DSH 会话最多一次，失败会重试）。 - 短命令过滤（v1.2.1）：被接管的命令若从 shell 就绪起运行时间短于
interceptMinVisibleMs（默认 1500ms），不上屏、不自动弹栏；设为0可全部上屏。 - 结束后自动关闭：一次性命令终端成功默认 8s、失败/超时/中止默认 30s 后关闭，关闭前有倒计时；悬停、选中、输入或滚动会暂停；可一键「保留」。关闭的命令进入最近命令历史（默认 20 条，可配置、可落盘）。
- 本地
http://localhost:PORT等输出可变成可点击链接；中英文界面，跟随 DSH 主题与终端字体设置。
Agent 工具面¶
README 列出的工具包括（节选说明）：
| 工具 | 作用 |
|---|---|
live_terminal_run |
在可见终端跑命令，支持 cwd / shell / cols / rows / env / keepOpen |
live_terminal_screenshot |
截取屏幕：text（默认）/ ansi / png |
live_terminal_send |
向交互终端写入文本或按键序列 |
live_terminal_read / live_terminal_search |
分页读取、在保留输出中搜索 |
live_terminal_wait / live_terminal_expect |
等待退出或输出匹配 |
live_terminal_status / live_terminal_signal / live_terminal_resize |
状态、信号、尺寸 |
live_terminal_exec |
在已有交互终端执行命令，保留 cd / env / venv 等上下文 |
live_terminal_open / live_terminal_close / live_terminal_list / live_terminal_rename |
会话生命周期 |
live_terminal_history / live_terminal_export |
历史与导出 |
安全与回退¶
- 带
run_in_background或sandbox_permissions（升权）的 shell 调用不会被接管，仍走 DSH 原生实现。 - 面板与 Agent 创建的 PTY 不套 DSH 文件沙箱，以当前系统用户权限运行；工具结果与 UI 会标注沙箱状态。若部署依赖 DSH 沙箱，可在配置中设
requireSandbox: true强制回退或拒绝新建未沙箱终端。 interceptShellTools: false可完全恢复原生 shell 行为，仅保留 Agent 主动调用的live_terminal_*。
安装与启用¶
DSH 生态里插件通过 profile 安装；安装后需按说明重启 Host 或完全退出桌面版再打开。
桌面版 DSH：
dsh plugin --profile desktop add dsh-live-terminal
安装后需完全退出并重新打开 DeepSeek Harness 一次。
Web 版 DSH：
dsh plugin --profile web add dsh-live-terminal
# 重启该 Host 后生效
也可在 设置 → 插件 → 添加插件 中输入 dsh-live-terminal；或在 awesome-dsh-plugin / dsh-market 搜索 Live Terminal 或包名。社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
用户侧¶
- 正常与 DSH 对话，让 Agent 执行命令（例如运行测试）。命令会出现在右侧终端面板，输出实时滚动。
- 自行开终端：右侧栏 → 终端面板 → 会话条 +。
- 命令结束后可用「保留」阻止自动关闭；通过 ⋯ → 历史 回看已关闭命令。
- 复制：
Ctrl+Shift+C或右键；整屏复制在 ⋯ → 复制屏幕文本；Ctrl+F搜索输出。 - 常用快捷键（面板聚焦时）：
Ctrl+Shift+\`` 打开/聚焦面板；Ctrl+Alt+T新建；Ctrl+Alt+F` 切换跟随最新命令。
Agent 侧示例思路¶
让 Agent 在可见终端启动 dev server 后，可用 live_terminal_expect 等待就绪提示，再用 live_terminal_screenshot 取 text 或 png 确认界面；长时间任务用 live_terminal_wait 而不杀进程；需要结束时用 live_terminal_signal 发送 SIGINT 等。具体参数以 DSH 工具 schema 与 README 表格为准。
配置要点¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中覆盖插件 config。常用项包括：
- id: dsh-live-terminal
name: dsh-live-terminal
config:
interceptShellTools: true
interceptMinVisibleMs: 1500
autoCloseCommandDelayMs: 8000
autoCloseFailedDelayMs: 30000
historySize: 20
historyPersist: true
requireSandbox: false
maxSessions: 16
完整字段与默认值见仓库 README「配置」一节；修改后按 DSH 插件加载方式生效。
适用场景与注意¶
适合：需要在 DSH 内直观观察 Agent 命令执行、调试交互式/TUI、让 Agent 基于终端画面做判断、或希望命令历史可搜索、可导出的开发者。
注意：
- 终端以当前 DSH 进程对应用户的系统权限运行，PTY 不套文件沙箱；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证，并按团队安全策略配置
requireSandbox/allowUnconfined。 - Node 引擎要求为
^22.19.0 || >=24.0.0（见package.json）。 - 资料中 GitHub 星标为 0，不代表功能完整度；以 README 与 npm 发布为准。
结尾¶
dsh-live-terminal 把 Agent 的 shell 执行从「黑盒工具回调」变成应用内可见、可截屏、可控制的终端会话，并兼顾短命令过滤、自动关闭、历史持久化与沙箱标注。插件目录页：skillhub.cn/plugins/Lancang-hzau/dsh-live-terminal；源码与文档：github.com/Lancang-hzau/dsh-live-terminal。
