dsh-shell-host: DSH Persistent PTY and Terminal Management Plugin

前言¶

DSH 插件生态奉行“一切皆插件”的理念。dsh-shell-host 是一个工具级 bundle，它原生支持 MSYS2 (UCRT64) bash，旨在为 DSH shell 接缝提供持久连接能力。它提供了持久 PTY 会话、预设终端启动器以及 WSL 桥接工具，与 shell 执行器无关，不提供 ctx.shell 上下文，也不接管上游 loader-row。

核心功能¶

持久 PTY 会话 (`./pty`)¶

./pty 是持久会话的核心，提供以下能力：
- PTY 管理：通过 src/pty/session-core.ts 实现。提供 pty_open、pty_send、pty_tail、pty_close 四个工具。
- SSH 交互：在 PTY 核心上构建全双工 SSH 会话，提供 ssh_start、ssh_tail、ssh_send、ssh_close。
- ssh_start({ host, jump?, shell?, port?, options? })：支持标准端口、非标准端口（通过 -p 参数）、Keepalive 默认设置（ServerAliveInterval=15）以及自定义 -o 选项。
- 注意：会话断开时不会自动重连，需显式重新调用 ssh_start。
- 限制：默认 maxSessions 为 8，超时会报错。

预设终端 (`./terminal`)¶

./terminal 是启动器层插件，提供单一工具 shell_open。
- 功能：shell_open(preset, cwd?, env?, idleTimeoutMs?)。它解析预设并通过 ./pty 的核心打开会话。
- 特性：
- 无中间人拦截，直接操作 PTY 核心。
- 支持自定义预设覆盖内置预设，结果包含 source（来源）、overrode（是否覆盖）、executable、probed、cwd 等字段。
- 支持可选的 idleTimeoutMs，当会话无新输出时自动关闭。

WSL 桥接 (`./wsl`)¶

提供 Windows 访问工具，供运行在 WSL 内的 agent 使用：
- win_ls、win_read、win_write、win_run、win_open
- win_path、win_drives

架构说明¶

非执行器：不包含 shell 执行器逻辑，不提供 ctx.shell provider。
非接管者：不执行上游 loader-row takeover。
职责分离：一次性远程命令属于独立的 dsh-shell-remote 插件；长生命周期的交互会话（如 ssh_start）由本插件处理。

宿主环境要求¶

本 bundle 假定宿主环境已安装 MSYS2 工具链，不负责安装 MSYS2。若缺失以下工具，agent 验证手段可能降级：

pacman -S --needed diffutils patch jq unzip rsync

代码示例¶

PTY 会话¶

import * as pty from 'dsh-shell-host/pty'

// 打开会话
const sessionId = pty.pty_open({ command: 'bash' })

// 发送数据
pty.pty_send(sessionId, 'ls -la\n')

// 查看输出
const output = pty.pty_tail(sessionId)

SSH 会话¶

import * as pty from 'dsh-shell-host/pty'

// 启动 SSH 会话
const sshSession = pty.ssh_start({
  host: 'example.com',
  user: 'admin',
  port: 22,
  options: '-o ProxyCommand=...' // 支持自定义选项
})

终端启动器¶

import * as terminal from 'dsh-shell-host/terminal'

// 打开预设终端
const session = terminal.shell_open('pwsh', { cwd: '/tmp', idleTimeoutMs: 30000 })

许可证与链接¶

许可证：MIT
维护者：ch1bug
GitHub：https://github.com/ch1bug/dsh-shell-host
目录：https://www.skillhub.cn/plugins/ch1bug/dsh-shell-host