@dsh-tui-ecosystem/dsh-remote

dsh-remote 面向 dsh-TUI 提供 Live + Daemon 双模式远程控制： Live mode 将文件系统和子进程执行切换到远端 Linux 主机，Daemon mode 用于远端 session 的创建、attach 与断线恢复。

当前版本先交付 Live MVP；Daemon、文件传输和多 target 见 [docs/roadmap.md](docs/roadmap.md)。

当前能力

通过 SSH 将 dsh 的文件系统和 subprocess provider 切换到远端 Linux。
/remote 场景提供连接管理、主机指标、诊断和远端 workspace 切换。
支持 SSH Agent、私钥和交互式密码三种认证。
远端 workspace 会创建独立的 dsh-TUI session；!command 和 Agent 工具在远端执行。

前置条件

本机 Node.js ^22.19 或 >=24、pnpm 10+（建议 pnpm 11）和 dsh CLI。
dsh-TUI 0.8.1 或更高版本。0.8.0 的部分终端渲染路径可能出现空白页面。
可从本机访问的远端 Linux SSH 服务；远端需要 /bin/sh。
使用密码认证时，远端 sshd 必须允许该账号密码登录。root 账号还需要允许 root

密码登录。

先创建或更新 dsh-tui profile：

npm install -g @deepseek-ai/dsh pnpm@latest
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest

从源码安装

插件尚未发布到 npm，目前必须从源码安装。远程核心以 Git submodule 固定在 vendor/dsh-remote，因此要使用 --recurse-submodules；GitHub 自动生成的 Source ZIP 不包含 submodule，不能用于安装。

git clone --recurse-submodules https://github.com/GeekCmore/dsh-tui-remote.git
cd dsh-tui-remote
pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile dsh-tui add "$PWD"
dsh --profile dsh-tui

add "$PWD" 会把当前源码目录链接到这个 profile。安装插件和启动 TUI 时必须使用同一个 profile；上面的示例统一使用 dsh-tui。当前不要使用 dsh plugin add dsh-tui-remote，该名称尚未发布到 npm。

已有普通 clone 可以补拉 submodule 后再安装：

git submodule sync --recursive
git submodule update --init --recursive
pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile dsh-tui add "$PWD"

快速配置

密码认证

不要把 SSH 密码写进环境变量或 YAML。只配置目标和认证模式，插件会在每次 Connect/Reconnect 时通过 TUI 遮罩输入密码：

DSH_REMOTE_HOST=203.0.113.10 \
DSH_REMOTE_PORT=22 \
DSH_REMOTE_USER=root \
DSH_REMOTE_AUTH=password \
DSH_REMOTE_CWD=/root \
dsh --profile dsh-tui

进入 TUI 后执行 /remote connect，输入密码并回车。也可以执行 /remote，用左右键选择 Connect 后按回车。

连接失败时先用系统 SSH 客户端验证网络、账号和 sshd 设置：

ssh -p 22 root@203.0.113.10

常见的远端 sshd 要求是 PasswordAuthentication yes；root 密码登录时 PermitRootLogin 不能是 no 或 prohibit-password。修改 sshd 配置后需要按远端系统的方式 reload/restart SSH 服务。

私钥认证

设置 DSH_REMOTE_KEY 会自动选择私钥认证：

DSH_REMOTE_HOST=203.0.113.10 \
DSH_REMOTE_USER=deploy \
DSH_REMOTE_KEY="$HOME/.ssh/id_ed25519" \
DSH_REMOTE_CWD=/srv/app \
dsh --profile dsh-tui

SSH Agent 认证

agent 是默认认证方式。确保 ssh-add -l 能看到可用密钥，然后启动：

DSH_REMOTE_HOST=203.0.113.10 \
DSH_REMOTE_USER=deploy \
DSH_REMOTE_AUTH=agent \
DSH_REMOTE_CWD=/srv/app \
dsh --profile dsh-tui

持久配置

临时环境变量最适合单个目标。需要固定配置或多个 workspace 时，编辑：

$DSH_HOME/profiles/dsh-tui/cordis.patch.yml

未设置 DSH_HOME 时通常是 ~/.dsh/profiles/dsh-tui/cordis.patch.yml。按相同 id 覆盖 dsh-remote 行；config 是整块替换，必须保留全部字段：

- id: dsh-remote
  config:
    targetId: production
    title: Production
    host: 203.0.113.10
    port: 22
    username: root
    auth: password
    privateKeyPath: ''
    autoConnect: false
    workspaces:
      - /root
      - /srv/app
    monitorIntervalMs: 5000
    readyTimeoutMs: 15000
    keepaliveIntervalMs: 0

密码仍然不会从配置文件读取。重启 dsh --profile dsh-tui 后执行 /remote connect，在 TUI 中临时输入。

配置参考

插件包自带 cordis.patch.yml，会禁用本地 fs-sandbox 和 dsh-subprocess-local，并将 shell sandbox 策略固定为 danger-full-access。这样保留 dsh-TUI 的 sandbox/preset contract，但实际 Bash 与 PTY 都通过 SSH 执行，不会在本机或远端额外要求 bwrap。远程 profile 只提供 danger-full-access 权限档位，避免切换到需要本地 bwrap 的模式；有效边界是 SSH 账号权限。默认 target id 为 default。

配置字段

字段	默认值	说明
`host`	`localhost`	SSH 主机
`port`	`22`	SSH 端口
`username`	`$USER` / `root`	SSH 用户
`auth`	`agent`	`agent`、`key` 或 `password`
`privateKeyPath`	空	`key` 模式必填
`autoConnect`	`true`	插件挂载后连接；`password` 模式下不自动连接
`workspaces`	`['/']`	常用远端绝对 POSIX 路径
`monitorIntervalMs`	`5000`	指标采样周期
`readyTimeoutMs`	`15000`	SSH 握手超时
`keepaliveIntervalMs`	`0`	SSH keepalive 周期，0 为关闭

环境变量

环境变量	对应配置	说明
`DSH_REMOTE_HOST`	`host`	SSH 主机名或 IP
`DSH_REMOTE_PORT`	`port`	SSH 端口
`DSH_REMOTE_USER`	`username`	SSH 用户名
`DSH_REMOTE_AUTH`	`auth`	`agent`、`key` 或 `password`
`DSH_REMOTE_KEY`	`privateKeyPath`	私钥路径；设置后默认选择 `key`
`DSH_REMOTE_CWD`	`workspaces[0]`	初始远端绝对路径

TUI 操作

/remote 打开全屏场景，包含 Overview、Diagnostics、Workspaces：

Tab / Shift+Tab 切换页面。
Overview 中用左右键选择 Connect、Disconnect、Reconnect，回车执行。
/remote connect、/remote disconnect、/remote reconnect 可以直接执行操作。
Workspaces 中用上下键选择配置路径，也可以输入远端绝对路径并回车。
Esc 或 q 关闭场景；r 重连；d 断开。

密码认证下，Connect 和 Reconnect 会显示遮罩输入框；密码只保留到本次连接尝试结束。

未指定 DSH_REMOTE_CWD 时，新会话默认使用远端 /，避免把本机启动目录误传给 SSH。设置该变量后，新会话使用指定目录。在 Workspaces 中选择已配置路径，或输入一个远端绝对路径，dsh-TUI 会在该远端 cwd 新建 session。这个 session 的 !command 由远端 /bin/sh -lc 执行，默认 30 秒超时。

临时输入的 workspace 会被识别为远端路径，并在提供 dsh-TUI storage.local 能力且插件获得相应授权时持久化。重启或 /resume 后仍会显示 REMOTE badge；存储按 target id、用户名、主机和端口隔离。旧 profile、未授权或存储不可用时，当前进程仍可使用临时路径，但重启后需要将路径加入 workspaces 或 DSH_REMOTE_CWD。

更新和验证

git pull --ff-only
git submodule sync --recursive
git submodule update --init --recursive
pnpm install --frozen-lockfile
pnpm build
pnpm test
dsh plugin --profile dsh-tui add "$PWD"

如果 /remote 命令不存在，通常是插件安装到了另一个 profile。检查 add 和启动命令是否使用同一个 --profile。如果命令存在但场景空白，先更新 dsh-TUI：

dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest

SSH 握手超时通常表示地址、端口、防火墙或安全组不可达；Permission denied 通常表示用户名、认证方式或远端 sshd 策略不匹配。

安全边界

Live mode 不使用本地 sandbox，远端 SSH 账户权限就是有效权限边界。
密码仅用于当前连接尝试，不写入插件配置或环境变量；插件不输出密码或私钥内容。
临时 workspace 归属只通过 dsh-TUI storage.local 保存；插件不直接读写

~/.dsh-tui、~/.dsh 或自有 JSON 文件，存储键和值不会写入日志。

SSH host-key verification 通过 runtime verifier 接入；Diagnostics 不会声称

主机密钥已验证。连接前会在 /remote 中显示 SSH host fingerprint；未知指纹必须显式 Trust，指纹变化默认拒绝。

已接受的 fingerprint 保存在 $DSH_HOME/dsh-remote/known-hosts.json（未设置

DSH_HOME 时为 ~/.dsh/dsh-remote/known-hosts.json）。插件不修改系统 ~/.ssh/known_hosts；删除该文件中的 target 记录即可重新触发首次信任。

插件包包含 Community Consensus v0.15 的 dsh-plugin.json。在提供

tuiPluginHost 的新 profile 中，/remote 会先经过 admission，再通过宿主 mediated command path 注册；旧 profile 回退到传统 command registration。

新 profile 使用官方 tuiStatus 显示连接状态、target 和延迟；旧 profile

回退到 tuiStatusItems。