前言¶
在 DeepSeek Harness（DSH）的 web profile 里，agent 执行前台 shell 时，默认往往只有工具返回的文本摘要，看不到提示符、命令回显和 ANSI 着色。排查构建失败、长时间跑测试或需要与 agent 共用同一交互 shell 时，这种「黑盒执行」会增加沟通成本。
下面介绍的 dsh-web-terminal（维护者 fightingFirefox）把 agent 的前台 pwsh / bash 调用送进常驻真实 PTY，右侧栏显示的就是该终端本身——提示符、回显、输出与退出码由 shell 产生，插件不拼接、不回放输出。同时向模型暴露 17 个 live_terminal_* 工具，便于读屏、截图与交互控制。桌面版 desktop profile 不在本仓库范围，需使用上游 dsh-live-terminal。
这是什么¶
dsh-web-terminal 是 DSH 生态中的客户端类插件（当前 GitHub 星标为 0）。host 侧通过 ctx.subprocess.spawnTerminal 与 webServer / connection 服务注册 PTY；客户端注入 @deepseek-ai/dsh-client-ui-sidebar-right，在浏览器右侧栏渲染 Claude 风格终端面板（ANSI 调色板可随宿主浅色/深色主题切换）。逻辑 fork 自 dsh-live-terminal 1.3.1（MIT），本仓库改动集中在视觉层、包名与安装链路。许可证 MIT，当前 package 版本 1.1.3。
适用范围与环境¶
| 项 | 要求 |
|---|---|
| DSH | >= 0.2.1-alpha.3 且 < 0.3.0-0 |
| profile | web（~/.dsh/profiles/web） |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| 系统 | Windows 为当前测试平台；macOS / Linux 复用同一 spawnTerminal 路径 |
面板数据经宿主 HTTP/SSE（前缀 /dsh-terminal-panel）在本地浏览器与宿主之间传输，不访问外部服务。
核心功能¶
可见终端面板¶
- 同一 DSH 对话复用一个常驻 PTY；命令串行排队，不并发写同一 shell。
- 仅拦截 agent 前台 shell 调用；带
run_in_background或sandbox_permissions的调用不拦截，保持 DSH 原生语义。 - 出现新的可见终端时自动打开右侧栏；命令结束后终端停在提示符上（无默认自动关闭；可通过配置调整延迟）。
- 面板内可直接键入，与 agent 共用同一 shell；
+可新建独立交互终端。
live_terminal_* 工具（17 个）¶
模型侧可调用例如 live_terminal_list、live_terminal_run、live_terminal_read、live_terminal_screenshot（支持 text / ansi / png）、live_terminal_send、live_terminal_wait、live_terminal_open / live_terminal_close 等。完整列表见仓库 README「工具接口」一节。
实现要点（与面板所见一致）¶
拦截路径不创建一次性「命令终端」，而是把命令写入常驻交互 shell：逐行发送并单独发送回车；完成判定依赖屏幕最后一行为提示符且静置 140 ms；输出通过命令前后屏幕差异抽取。初始化或运行失败时回退内置工具，命令语义不变。
安装与启用¶
官方 README 说明：dsh plugin add 可能因 engines 校验被拒绝，本仓库推荐用手工安装路径。
方式一：仓库内脚本（推荐）¶
在已获取源码的目录中执行（也可下载 Release v1.1.3 源码包解压后执行同一份脚本）：
pwsh -NoProfile -File install.ps1
脚本会备份 profile 的 package.json 与 cordis.patch.yml，复制插件文件到 ~/.dsh/profiles/web/node_modules/dsh-web-terminal，安装 @xterm/headless、@xterm/addon-serialize，在 dsh.profile.bundles 注册 dsh-web-terminal，并在 cordis.patch.yml 写入默认 interceptShellTools: true。
方式二：手动安装¶
$dest = "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-web-terminal"
New-Item -ItemType Directory -Force $dest | Out-Null
Copy-Item lib, package.json, cordis.patch.yml, LICENSE, NOTICE, icon.svg $dest -Recurse
cd $dest; npm install --omit=dev
在 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 加入 "dsh-web-terminal"，并在 cordis.patch.yml 追加：
- id: dsh-web-terminal
name: dsh-web-terminal
config:
interceptShellTools: true
卸载：
pwsh -NoProfile -File uninstall.ps1
安装后必须完全退出 DSH 再启动（dsh web），host 插件与 client bundle 在启动时加载。
安装后验证¶
- 重启 DSH 后，右侧栏应出现终端标签页（kind：
web-terminal-panel）。 - 在对话中触发一次前台 shell（例如让 agent 运行
npm test）：右侧栏自动打开pwsh标签页，命令以PS <cwd>> <命令>形式出现；结束后回到提示符，下一条命令在同一屏追加。 - 模型可通过
live_terminal_list查看当前终端。
配置¶
覆盖位置：~/.dsh/profiles/web/cordis.patch.yml 中 dsh-web-terminal 的 config。常用项包括：
| 键 | 默认 | 说明 |
|---|---|---|
interceptShellTools |
true |
是否拦截 agent 前台 shell |
autoCloseCommandDelayMs |
8000 |
成功结束后自动关闭延迟；-1 为永不 |
requireSandbox |
false |
true 时在非 danger-full-access 下拒绝接管 |
scrollback |
2000 |
单终端回滚行数 |
commandTimeoutMs |
180000 |
live_terminal_run(wait:true) 默认超时 |
其余键（历史、输出上限、会话数、shellPath 等）见 README「配置」表。
适用场景与注意¶
适合：主要在 DSH web profile 下开发、希望肉眼看到 agent 命令在真实 shell 中执行、或需要 live_terminal_screenshot 等工具辅助模型读终端的场景。可与 dsh-claude-style 主题共存。
务必知晓的安全属性：面板终端与 agent 终端以当前系统用户权限运行，PTY 不套用 DSH 文件沙箱；该信息会出现在面板状态栏与工具结果的 sandbox 字段中。安装并启用前，应自行审阅 源码与 LICENSE。requireSandbox: true 时，非 danger-full-access 环境不会接管，回退内置沙箱工具。
排障简述：没有 live_terminal_* 工具时检查 dsh.profile.bundles 与是否完整重启；面板不出现则查 cordis.patch.yml 与浏览器控制台 client bundle 报错；命令不上屏则查 interceptShellTools、是否后台/升权调用、以及 requireSandbox 与沙箱模式组合。
链接¶
- 社区目录页：https://www.skillhub.cn/plugins/fightingFirefox/dsh-web-terminal
- GitHub 仓库：https://github.com/fightingFirefox/dsh-web-terminal
DSH 生态强调「一切皆插件」；SkillHub 等目录为社区站点，与 DeepSeek / 幻方无官方从属关系。本文事实均来自上述仓库 README 与 package 元数据。
