终端语义视窗 fdfdfdfgbfdgfdg-star/dsh-terminal-vision

dsh-terminal-vision

给 DeepSeek Harness（DSH）用的终端语义视觉插件。

让智能体对交互式终端程序拥有「语义视觉」——vim、htop、lazygit、less、安装向导 TUI——而不是面对原始转义序列字节流。每个 PTY 会话都由 @xterm/headless（xterm.js 的无头 JS 移植版）持续解析成结构化屏幕模型：可见文本行、光标位置、当前行。智能体随后就能读屏、发送按键、再读屏——在任何 TUI 上跑感知/动作循环。

DSH 中注册的工具

| 工具 | 用途 |
| terminal_open(session_name, shell?, cwd?, cols?, rows?) | 打开持久 PTY 会话，返回 session_id。shell 可以是 shell 名（bash、pwsh、cmd），也可以是要直接运行的 TUI 程序（htop、vim file.txt）。 |
| terminal_get_screen(session_id) | 结构化屏幕模型：lines[]、cursor {x, y}、active_line、终端标题。 |
| terminal_send_keys(session_id, keys, wait_ms?) | 发送按键序列，等屏幕变化（就绪等待，默认 500 ms），然后返回新屏幕。接受纯文本、具名按键（Enter、Esc、Up…）、修饰键（Ctrl+C、Alt+b）、空格分隔的序列（":wq Enter"）。 |
| terminal_read_output(session_id, lines?) | 回滚缓冲区最后 N 行（视口上方的历史）。 |
| terminal_close(session_id) | 关闭会话，释放 PTY。 |
| terminal_list_sessions() | 列出活动会话，含 id、名称、shell、cwd、存活状态。 |

架构

- 宿主部分（TypeScript，src/）——Cordis 插件：apply(ctx) 在 ctx.tools 上注册工具，通过 node-pty 管理持久会话（Windows 上用预编译 ConPTY 二进制，无需编译器）。
- 语义解析器（src/screen-model.ts）——方案 A：@xterm/headless 在 Node 里原生构建屏幕模型。原始 PTY 输出写入无头 xterm Terminal，按需读出缓冲区（buffer.active、translateToString）。不用 Python，没有常驻桥接进程，离线可用。
- 按键由 encodeKeys() 转换（友好名称 → 终端字节，含 Ctrl/Alt 修饰键、方向键、F 键）。
- 就绪等待：每次 terminal_send_keys 之后，工具会等到屏幕版本变化（数据到达）或超时——避免「盲发」。
- 所有工具返回可 JSON 序列化的对象；未知 session id 返回明确错误，不会崩溃。

安装

from a local checkout
dsh plugin --profile web add file:./dsh-terminal-vision

or from GitHub
dsh plugin --profile web add github:fdfdfdfgbfdgfdg-star/dsh-terminal-vision

Windows 注意： pnpm 默认拦截原生模块的安装脚本。如果 add 步骤报 ERR_PNPM_IGNORED_BUILDS: node-pty 失败，手动跑被拦截的构建步骤（node-pty 自带预编译 ConPTY 二进制，无需编译器）：

bash
cd ~/.dsh/profiles/web
pnpm rebuild node-pty # runs the postinstall that copies conpty.dll

然后重启 DSH（重新启动 DeepSeek Harness 应用，或重新运行 dsh --profile web），在启动日志里确认出现：

[terminal-vision] loaded: tools=6

在聊天里验证：「Какие инструменты терминала тебе доступны?」——智能体应当列出六个 terminal_* 工具。

包内声明了 dsh.bundle.patch（cordis.patch.yml），因此 dsh plugin add 会自动把插件接入配置档，无需手动修改 cordis.patch.yml。

会话示例 text
terminal_open(session_name="htop", shell="htop") → session_id
terminal_get_screen(session_id) → lines[] of the htop interface, cursor
terminal_send_keys(session_id, "F10") → quit htop, new screen
terminal_close(session_id)

驱动 shell： text
terminal_open(session_name="work", shell="bash")
terminal_send_keys(session_id, "ls -la\n")
terminal_get_screen(session_id) → the ls output
terminal_read_output(session_id, lines=200) → anything that scrolled off

构建与测试（开发） bash
npm install
npm run build # tsc → lib/
npm test # node --test test/integration.test.js

lib/（编译后的 JS）已提交到仓库，所以直接 dsh plugin add 无需构建步骤。同样出于这个原因，包内刻意不设 prepare 脚本：pnpm 禁止 git 托管的包在安装时运行构建脚本（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），而 lib/ 已在仓库里，构建也就没必要了。开发时运行 npm run build，并提交更新后的 lib/。

依赖

- Node.js >= 22.19（DSH 宿主的要求）
- node-pty ^1.1.0 —— 自带预编译的 Windows ConPTY 二进制文件；在 Windows 11 上无需 Visual Studio Build Tools
- @xterm/headless ^6.0.0 —— 纯 JS，无原生代码
- 不需要 Python，也不需要 root/管理员权限

已知限制

- 屏幕模型只处理文本：颜色与属性由模拟器解析，但不会出现在快照里。
- cursorHidden 仅供参考（xterm.js 不暴露 DECTCEM 状态）；多数 TUI 会让光标保持可见。
- Alt+<letter> 发送带 ESC 前缀的字节（不按程序协商应用小键盘模式）。
- 会话存活在 DSH 宿主进程里；重启 DSH 会关闭所有会话。
- 在 Windows 上默认 shell 是 cmd.exe（ConPTY）；如果 PATH 里有 Git Bash / WSL bash，bash 也能用。