前言¶
在 DeepSeek Harness（DSH）里让智能体操作交互式终端程序时，常见做法是直接读 PTY 输出的转义序列字节流。vim、htop、lazygit、less 以及各类安装向导 TUI 会不断刷新屏幕，裸字节流对模型来说难以稳定「看懂当前界面」，按键也容易在界面未就绪时连发，形成盲操作。
下面介绍社区插件 dsh-terminal-vision（维护者 fdfdfdfgbfdgfdg-star），它把每个持久 PTY 会话用 @xterm/headless 持续解析成结构化屏幕模型（可见文本行、光标位置、活动行），再向 DSH 注册一组 terminal_* 工具，使智能体可以按「读屏 → 发键 → 再读屏」的闭环驱动 TUI，而不是啃原始字节流。插件归类为客户端，在 SkillHub 目录 可查到条目；生态上 DSH 强调「一切皆插件」，该目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-terminal-vision 是面向 DSH 的终端语义视觉插件：在宿主机侧用 node-pty 管理持久会话，用 @xterm/headless（README 中的 Variant A）在 Node 内构建屏幕模型，无需 Python、无需长期桥接进程，可离线工作。许可证为 MIT（见仓库 package.json）；当前资料中的版本号为 0.1.0。运行环境要求 Node.js >= 22.19（与 DSH 宿主一致）。
向 DSH 注册的工具¶
插件在 Cordis 的 apply(ctx) 中向 ctx.tools 注册 6 个工具，名称与用途如下（与 README 一致）：
| 工具 | 作用 |
|---|---|
terminal_open(session_name, shell?, cwd?, cols?, rows?) |
打开持久 PTY，返回 session_id；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 / 方向键、Ctrl+C、Alt+b 以及空格分隔序列（如 ":wq Enter"）。 |
terminal_read_output(session_id, lines?) |
读取视口上方滚动区最近 N 行。 |
terminal_close(session_id) |
关闭会话并释放 PTY。 |
terminal_list_sessions() |
列出活跃会话的 id、名称、shell、cwd、存活状态。 |
未知 session_id 时工具返回明确错误，而不是让宿主崩溃；所有返回值均为可 JSON 序列化的对象。
架构要点¶
- 宿主部分（TypeScript，
src/）：Cordis 插件，用 node-pty 管理会话；Windows 上使用预编译 ConPTY 二进制，README 说明无需本机编译器。 - 语义解析（
src/screen-model.ts）：PTY 输出写入无头 xtermTerminal，按需从buffer.active读出文本行；按键经encodeKeys()转为终端字节。 - 打包接入：包声明
dsh.bundle.patch（cordis.patch.yml），执行dsh plugin add时会自动写入 profile，无需手改 patch 文件。
仓库中已提交编译产物 lib/，因此普通安装不必本地 npm run build；包刻意不设 prepare，以避免 pnpm 对 git 依赖阻止 prepare 脚本的问题。
安装与启用¶
在已安装 DSH CLI 的前提下，从 GitHub 安装到 web profile 可使用 README 中的命令：
dsh plugin --profile web add github:fdfdfdfgbfdgfdg-star/dsh-terminal-vision
若你已在本地检出插件目录，也可：
dsh plugin --profile web add file:./dsh-terminal-vision
Windows 说明： pnpm 默认可能忽略 native 模块的安装脚本。若 add 失败并出现 ERR_PNPM_IGNORED_BUILDS: node-pty，在 profile 目录手动重建 node-pty（复制 conpty.dll 的 postinstall）：
cd ~/.dsh/profiles/web
pnpm rebuild node-pty
然后重启 DSH（重新打开 DeepSeek Harness 应用，或重新执行 dsh --profile web），在启动日志中应看到类似：
[terminal-vision] loaded: tools=6
可在对话中让智能体列举终端相关工具，确认六个 terminal_* 已加载。插件在 DSH 宿主进程内运行，权限与当前 DSH 进程相同；安装前建议浏览 GitHub 仓库 源码与 MIT 许可证。
典型用法¶
README 中的 htop 示例（工具调用为示意，实际由智能体通过 DSH 工具接口执行）：
terminal_open(session_name="htop", shell="htop") → session_id
terminal_get_screen(session_id) → htop 界面的 lines[] 与 cursor
terminal_send_keys(session_id, "F10") → 退出 htop，返回新屏幕
terminal_close(session_id)
在 shell 中执行命令并读屏、读滚动历史：
terminal_open(session_name="work", shell="bash")
terminal_send_keys(session_id, "ls -la\n")
terminal_get_screen(session_id) → ls 输出
terminal_read_output(session_id, lines=200) → 滚出视口的内容
经过上面的步骤，智能体对 vim / lazygit 类程序也可沿用同一感知—动作循环，只要通过 terminal_open 的 shell 参数直接拉起对应程序即可。
适用场景与已知限制¶
适合： 需要在 DSH 对话中由智能体操作全屏 TUI、交互式安装器、或需要「看当前屏再按键」的终端工作流；希望依赖纯 JS 屏幕解析、不引入 Python 侧长期进程的团队。
限制（摘自 README）：
- 屏幕模型仅暴露文本；颜色与属性由模拟器解析但不进入快照。
cursorHidden为参考信息，xterm.js 不暴露 DECTCEM 状态。Alt+<letter>发送 ESC 前缀字节；未按程序单独协商应用键盘模式。- 会话绑定 DSH 宿主进程，重启 DSH 会关闭全部会话。
- Windows 默认 shell 为
cmd.exe；若 PATH 上有 Git Bash / WSL 的bash可选用 bash。
结尾¶
dsh-terminal-vision 把交互式终端从字节流升级为可读的屏幕模型，并用就绪等待降低盲发按键的风险，是 DSH「客户端」类插件里专门补齐 TUI 语义视觉的一块。目录页：https://www.skillhub.cn/plugins/fdfdfdfgbfdgfdg-star/dsh-terminal-vision；源码与完整说明：https://github.com/fdfdfdfgbfdgfdg-star/dsh-terminal-vision。
