dsh-remote-console

dsh-remote-console

中文 | English

DSH 右侧栏的「SSH 远程控制终端」：你在这里亲手输 SSH 密码，agent 通过同一个 PTY 读写远端； 人的操作和 agent 的操作落在同一条可回看的日志里。

它不重新实现终端：渲染、输入、窗口管理全部复用 DSH 自带的终端，插件只做三件事—— 往 shell 列表里加远端启动器、捕获这条 PTY 的字节流、给 agent 一组写进同一个终端的工具。

它解决什么

普通的「agent 远程执行」通常是另开一条 ssh 通道，于是：

• 你看不到 agent 在远端敲了什么，也接不回它的会话；
• 密码、sudo、主机指纹这些必须由人完成的交互没有地方做；
• cd/export 这类 shell 状态在两次调用之间丢失。

这个插件把 agent 放进你正在看的那个终端：agent 的命令像人打字一样出现在窗口里， 退出码由 shell 自己的 PROMPT_COMMAND 钩子（OSC 序列）回报，而不是靠猜提示符。

安装

要求：DSH >= 0.2.1-rc.2 <0.3.0，本机有系统 ssh 客户端。

npm 包名：dsh-remote-console（https://www.npmjs.com/package/dsh-remote-console）。

插件市场（推荐，能显示「有新版本」）：插件市场索引（DSH plugin market format 1）：

https://cccodder.github.io/dsh-remote-console/market/index.json

这是 GitHub Pages 镜像，每次推送后自动更新（首次启用约需 1 分钟）。如果它不通，

可改用 jsDelivr https://cdn.jsdelivr.net/gh/cccodder/dsh-remote-console@main/market/index.json

（分支缓存最长约 12 小时）或 GitHub 原链

https://raw.githubusercontent.com/cccodder/dsh-remote-console/main/market/index.json；

也可以把仓库里的 market/index.json 放到你自己的静态服务器上（索引就是一份 JSON）。

1. 侧栏「发现」（需要启用实验性 bundle @deepseek-ai/dsh-experimental-plugin-market-bundle）。
2. 「添加索引源」→ 粘贴上面的 URL。
3. 在列表里点安装；以后有新版本会显示「有新版本」，直接更新。

CLI 管理的 profile（例如 web）：

# 1. 装进 profile（--profile 换成你自己的 profile 名）
dsh plugin --profile web add dsh-remote-console

# 2. 把插件加进该 profile 的 bundle 列表
#    编辑 $DSH_HOME/profiles/web/package.json：
#      "dsh": { "profile": { "bundles": [ ..., "dsh-remote-console" ] } }

# 3. 确认插件层被组合进来（应看到 id: dsh-remote-console）
dsh --profile web --dump-config | grep -A2 dsh-remote-console

Electron 桌面版：desktop profile 由 App 独占管理，CLI 会直接拒绝 （profile "desktop" is managed exclusively by the Electron application）。 请用 App 内置的插件管理器安装：包名填 dsh-remote-console（从 npm 装）， 或粘贴 github:cccodder/dsh-remote-console（从 git 装最新提交）。 它会自动写入 profile 的 dependencies 与 dsh.profile.bundles。注意全局 dsh CLI 版本可能低于 App 自带的 DSH，以 App 内的版本为准。

不需要 Python、不需要改 ~/.ssh/config、不改 shell rc。

用法

1. 右侧栏 →「SSH 远程」卡片 → 选中一个远端（来自 ~/.ssh/config 的 Host，或手动新建）。
2. 终端里执行 ssh -M -S -t ，密码/口令由 ssh 自己提示，插件不接触。
3. 登录成功后 agent 可用这些工具：

工具 · 作用 remote_status · 终端、主机、socket、状态、最后几行屏幕 remote_run(command) · 写进同一个 PTY（窗口里可见），返回输出 + 真实退出码（PTY 会把 stderr 并进输出） remote_exec(command, cwd?) · 复用 ControlMaster socket 的带外执行：原生 stdout/stderr/退出码，不污染终端窗口 remote_screen(lines) · 当前屏幕纯文本（剥 ANSI） remote_log(cursor) · 统一 JSONL 日志的增量读：人敲的命令、agent 的命令、两边输出 remote_close() · 断开 ssh master 并清理 socket/rendezvous 文件

remote_run 适合：要你看着执行、需要 TTY（sudo/vim/嵌套 ssh）、需要在两次调用间保留 shell 状态。 remote_exec 适合：纯数据收集、脚本、必须用退出码判断成败的事。

注意 `exit` 的语义：面板里的主机启动器和「新建会话」都是一次性的——远端 shell 退出 （命令里带 exit、logout，或 ssh 断开）后，整个终端就结束了，所有 remote_* 工具失效， 需要人工重新打开终端并重新输密码。插件会拦下这类命令要一次审批，并在终端里明确提示 「这个终端已经结束」，不会假装还能继续用。

更新

怎么知道有新版本：面板底部左侧是「密码只在终端里输入…」，右侧显示当前版本 （如 v0.6.5）。客户端会查一次 GitHub 最新 Release（结果缓存 6 小时，离线/限流/CORS 失败都静默），发现更高版本时在同一位置显示「有新版本 vX.Y.Z」，点开是 GitHub Release 页。

方式一：插件市场（有真正的「更新」入口）

插件已发布到 npm，并提供 format 1 的市场索引：

https://cccodder.github.io/dsh-remote-console/market/index.json

在侧栏「发现」→「添加索引源」里加上这个 URL 后，发现页会列出本插件；索引里的版本比 已安装的新时显示「有新版本」，点一下就走 DSH 的安装/更新流程（安装源是 npm 的 dsh-remote-console@）。安装位置不会变，数据目录也不受影响。

索引源只接受 JSON 的 URL。GitHub Pages 不通时换 jsDelivr 或 raw 原链，或把

market/index.json 放到你自己的静态服务器上——内容一样，DSH 不关心它托管在哪。

方式二：手动重装（没有启用插件市场时）

1. 侧栏「插件」→「已安装插件」→ dsh-remote-console → 卸载（会二次确认）。
2. 「添加插件」→ 输入 dsh-remote-console（npm）或 github:cccodder/dsh-remote-console

（git 最新提交）→ 安装 → 「立即启用」。

1. 重启一次 DSH 桌面 App。插件在热更新后会重新 apply()，虽然已经做了幂等保护，

但重启最干净（0.6.0/0.6.1 升级上来的旧包装必须靠重启清掉）。

主机列表、hosts.tsv 这些数据在 ~/.dsh/remote-console/，不在插件包里，卸载重装不会丢。

关于一键更新：DSH 插件管理器只给官方按需插件提供「更新」按钮；第三方插件想要同样的 体验，就得通过插件市场索引（本仓库的 market/index.json）或发布到 npm 让方负责分发。

安全模型

• 凭据不经过插件：密码只在 ssh 自己的提示符里输入。hosts.tsv 只记 host/user/port（0600），

数据目录 0700；仓库里不含任何密钥。

• 认证期拒写：屏幕停在 password:、(yes/no)?、Permission denied 等状态时，

agent 的任何写入都会被拒绝（AUTH_REQUIRED），避免它替你回答认证问题。

• 危险命令审批：remote_run / remote_exec 绕过 DSH 沙箱，所以插件额外加了一道闸门：

命中 rm -rf、mkfs、dd of=/dev/*、shutdown/reboot、fork bomb、curl | sh、 git push --force、DROP TABLE 等模式时，通过 DSH 的 ctx.approval 弹一次审批卡片， 一次授权只对本次命令有效；没有审批服务（headless/未挂载 answerer）时直接拒绝执行。 remote_run 里会结束整个终端的 exit / logout / pkill ssh 同样需要审批。

• 日志会消失：PTY 结束即删除会话日志（保留内存事件供当场回看）；DSH 崩溃留下的

残留日志会在下次插件启动时清扫。日志写入前会对 Bearer token、sk-*、 password=/token:/secret= 一类赋值做脱敏，但命令参数里的明文密钥仍可能出现在会话期间， 敏感操作请用环境变量或 ssh-agent。

• 关窗即失能：关终端标签立即杀进程树；关浏览器在最后一个窗口持有消失 8 秒后杀

（刷新会重连并取消）；DSH 崩溃时 PTY master 消失，ssh 随 HUP 退出。

威胁模型：插件保护的是「凭据不被 agent/日志带走」和「破坏性操作需你点头」，

它不能防御你已经授权的 agent 在远端做任何事。远端命令本身就是你给 agent 的能力。

发现安全问题请走私密渠道，见 SECURITY.md。

环境变量

变量 · 默认 · 作用 DSH_REMOTE_CONSOLE_DIR · $DSH_HOME/remote-console · 数据目录（logs/sessions/socks/bin） DSH_SSH_CONFIG · ~/.ssh/config · 主机别名来源 DSH_RC_DANGER_GUARD · approve · 设为 off 关闭危险命令审批（自担风险，仍会记审计事件） DSH_RC_DRYRUN · 0 · 包装器 dry-run：只打印 ssh 命令不执行（测试用） DSH_RC_NO_CLEAR · 0 · 设为 1 不自动清屏（排查时用） DSH_RC_SELFTEST · 0 · 启动后跑一次内建自测并写 selftest.log

兼容性与限制

• 插件包住的是 DSH 的终端服务（ctx.subprocess.spawnTerminal、ctx.terminalController.shells|retain、

客户端 ctx.webTerminals.launchShells），这与社区插件的常用手法一致，但不是文档化扩展点； DSH 改动这些内部实现时需要同步适配（package.json 的 engines.dsh 声明了已验证范围）。

• 远端默认用 bash -li 启动以挂 PROMPT_COMMAND 钩子；远端没有 bash 时自动退回哨兵模式

（窗口里会看到一行 __dsh 包装命令），功能不受影响、只是观感略差。

• 终端输出没有做全终端模拟：行内覆盖用「保留最后一个 \r 之后内容」的简化处理，

极端 TUI 场景下 remote_screen 可能与真实画面有出入，命令结果以 remote_run/remote_exec 为准。

开发与测试

npm test      # 69 个测试 + 发版元数据检查
npm run verify  # 只查版本号、客户端 VERSION、CHANGELOG、市场索引是否一致

测试不需要 ssh，也不需要真 PTY：tests/link-peers.mjs 会把全局安装的 DSH 里的 peer 包 软链进本目录（CI 里改用 npm install --no-save 装同样的包）， tests/console.test.mjs 用一个假远端 shell 回放 OSC 帧来验证退出码、回显剥离和超时。

• 开发规则与分支模型：CONTRIBUTING.md（中文：CONTRIBUTING.zh.md）
• AI 协作规则：AGENTS.md
• 端到端验证（需要一台有 ssh 的机器）：docs/verify-e2e.md
• 发版前真机清单：docs/dev/release-checklist.md
• 发版流程：release PR 里改版本 + CHANGELOG + npm run market:index，合并后在 main 发布

vX.Y.Z Release；workflow 校验 tag、跑测试、带 provenance 发 npm 并把 .tgz 挂到 Release。

数据目录

${DSH_HOME:-~/.dsh}/remote-console/

• bin/：按 ~/.ssh/config 生成的主机启动器（dsh-ssh-）
• hosts.tsv：手动新建过的主机（host/user/port）
• sessions/：terminal ↔ socket 的 rendezvous（进程退出即清）
• socks/：ControlMaster socket
• logs/：会话 JSONL（会话结束即删）
• plugin.log：插件诊断日志（不含凭据）

许可

MIT。见 LICENSE。