btsd321/dsh-remote-explorer

dsh-remote-explorer

灵感来自 VS Code Remote-SSH、Zed 和 JetBrains Gateway —— 代码和会话位于远程，本地机器仅负责渲染 UI。

支持的环境

- 本地（客户端）：Windows / Linux / macOS。仅在源码运行模式下才需要 Node.js v20.19+ 或 v22+ 以及 pnpm 11+（pnpm 是默认的开发包管理器，通过 packageManager 固定）；发布包自带 Node 运行时。
- 远程主机：Linux 或 macOS（POSIX）；aarch64（arm64）和 x86_64 均可。无需预装 Node —— 该工具会自行安装并自检。
- WSL（适用于 Linux 的 Windows 子系统）：在 Windows 上，支持将 WSL2 发行版作为远程目标。dsh 会自动安装在 WSL 内，通过 localhost 转发进行隧道连接 —— 无需 SSH 设置。点击面板中的“WSL Sessions”卡片即可使用；该入口在非 Windows 平台上隐藏。
- SSH 认证：私钥（IdentityFile，推荐）；未配置密钥时，交互式终端会提示输入密码（无回显）；--password 也可用（会通过进程列表 / shell 历史泄露 —— CLI 会发出警告）。
- 主机来自 ~/.ssh/config 中的 Host 条目，或临时的 user@host[:port]（IPv6 必须通过配置文件）。

安装与运行

CLI 有两种运行模式（命令和选项完全相同）；如果你已在本地运行 dsh，也可以将此工具安装为 dsh 插件（选项 3）。

选项 1：从源码运行

该仓库没有构建步骤；.ts 源码通过 tsx 直接执行。开发环境默认使用 pnpm（版本通过 package.json 中的 packageManager 固定）。获取源码后：

pnpm install
pnpm exec tsx src/cli/bin.ts list

选项 2：运行发布包

从发布页面下载适用于你平台的归档文件（由打包脚本生成，命名为 dsh-remote-explorer--.），解压后直接运行 —— 目标上无需 Node、npm 或网络：

| 平台 | 归档文件 | 解压后如何运行 |
|---|---|---|
| win32-x64 | .zip | dsh-remote-explorer.cmd  |
| linux-x64 / linux-arm64 | .tar.gz | ./dsh-remote-explorer  |
| darwin-x64 / darwin-arm64 | .tar.gz | ./dsh-remote-explorer  |

每个包都捆绑了官方 Node 二进制文件（下载时通过 SHASUMS256 校验）以及单文件 CLI dsh-remote-explorer.cjs（所有依赖均已打包在内）。请使用随发布版本一同发布的 sha256 校验归档文件。

选项 3：安装为 dsh 插件

如果你已在本机运行 dsh（Web/Desktop），可将此工具安装到 dsh 中，并通过设置面板、斜杠命令和 agent 工具来管理远程会话：

需要 pnpm 在 PATH 中（dsh plugin 命令会原样转发给 pnpm）
dsh plugin --profile web add dsh-remote-explorer
当 dsh 不在 PATH 中时：
npx --yes @deepseek-ai/dsh plugin --profile web add dsh-remote-explorer
从 GitHub 源安装（预构建产物已提交；无需额外配置）：
dsh plugin --profile web add github:btsd321/dsh-remote-explorer
从本地检出安装（先构建插件产物）：
pnpm run build:plugin && dsh plugin --profile web add /path/to/repo

pnpm 11.7+ 用户须知（构建脚本审批门禁）： pnpm 11.7 会将未决的依赖构建脚本视为硬性失败，而此包的依赖树带有三个（cpu-features、通过 tsx 引入的 esbuild、ssh2）——无论安装来源如何，首次 dsh plugin add 都会以 ERR_PNPM_IGNORED_BUILDS 失败。它们在插件运行时都不需要：产物已预构建（lib/，已提交），且 ssh2 会回退到纯 JS。推荐： 通过 dsh web GUI 的插件管理器页面安装——它提供内置的批准并重试流程。CLI 替代方案： 在添加失败后，将 ~/.dsh/profiles/web/pnpm-workspace.yaml 中三个待处理的 allowBuilds 条目设为 false，从 ~/.dsh/profiles/web/package.json 的 dependencies 中移除半提交的 dsh-remote-explorer 条目（失败的添加会将其留在那里，而直接重试会以 0 退出但不会激活插件——这是 0.1.7-rc.1/rc.2 中存在的 dsh CLI 怪癖），然后重新运行添加命令。

安装后重启 dsh web。该插件提供三个界面：

- 左侧导航中的“Remote SSH Sessions”全局面板：选择主机，以两种窗口模式连接（在当前标签页中进入 / 打开新标签页），断开连接，管理远程插件，实时进度日志；远程窗口带有一个状态胶囊，用于返回管理器或关闭/停止连接
- 斜杠命令 /remote-explorer：hosts | connect  [remote-dir] | status | disconnect  [--keep-remote]
- Agent 工具 remote_hosts_list / remote_connect / remote_status / remote_kill（位于 dsh 常规工具审批门禁之后）

该插件共享 CLI 的会话编排和远程布局（~/.dsh-remote-explorer/btsd321/），会话表在两个方向上共享：dsh-remote-explorer status 显示插件保留的会话，而面板显示 CLI 保留的会话（只读，标记为“external”）。有两个差异：会话生命周期依附于宿主 dsh 进程——退出 dsh 默认也会停止远程 dsh（配置文件补丁中的 keepRemoteOnDispose: true 会保留它）；LLM 密钥从启动 dsh 的进程环境中读取。参见使用指南。

快速开始

以下示例使用源码运行形式。使用发布包时，将 pnpm exec tsx src/cli/bin.ts 替换为 ./dsh-remote-explorer（Windows：dsh-remote-explorer.cmd）——选项完全相同。

从 ~/.ssh/config 列出主机
pnpm exec tsx src/cli/bin.ts list
诊断主机的预置条件（将 myhost 替换为你的别名或 user@host[:port]）
pnpm exec tsx src/cli/bin.ts doctor myhost
pnpm exec tsx src/cli/bin.ts doctor myhost --refresh-mirrors   # 强制重新基准测试镜像源

主命令：预置 → 启动远程 dsh → 建立隧道 → 打开浏览器（长时间运行）
为你使用的任意提供商导出 API 密钥（提供商列表来自 ~/.dsh/settings.yaml）
DEEPSEEK_API_KEY=sk-xxx pnpm exec tsx src/cli/bin.ts connect myhost --cwd //home/youruser

显示本机上维护的所有会话
pnpm exec tsx src/cli/bin.ts status

停止远程 dsh
pnpm exec tsx src/cli/bin.ts kill myhost --all

清理过期的远程资源（旧版本、失效的会话目录；运行中的会话受保护）
pnpm exec tsx src/cli/bin.ts clean myhost
pnpm exec tsx src/cli/bin.ts clean myhost --keep 2   # 每个类别保留 2 个版本

仅预置，不启动服务（幂等；复用已安装的版本）
pnpm exec tsx src/cli/bin.ts provision myhost --cwd //home/youruser

使用不同的 ssh 配置文件
pnpm exec tsx src/cli/bin.ts list --ssh-config /path/to/config

执行 connect 后，该进程必须保持运行——本地隧道监听器和 LLM 代理都位于其中。Ctrl-C 也会停止远程 dsh（断开连接 = 清理）。若想断开连接但保留远程进程以便复用，请添加 --keep-remote。如果会话因失败而进入终态，远程进程同样会被保留。

关于每条命令和选项的详细演练，请参阅 docs/usage-en.md。

凭据如何工作

模型调用不会直接访问公共互联网。相反，它们会经过一条反向 SSH 隧道。多提供商支持：代理按路径前缀进行路由——DeepSeek 的原生通道使用 /anthropic，其他本地配置的提供商各自使用 /r/。路由会被自动提取——无需手动配置。

远程 dsh ──(占位令牌)──▶ 远程 127.0.0.1:/r/ ──SSH 反向隧道──▶ 本地代理
├─ /anthropic → api.deepseek.com
└─ /r/ → 对应的上游
（按路由注入真实密钥）

- 每个提供商的真实密钥（DEEPSEEK_API_KEY 等）仅存在于本地进程中——绝不会写入远程磁盘，也绝不会放入远程环境。远程进程环境中包含的是代理令牌（随机值）。
- 真实密钥解析：优先读取 process.env，回退到 $DSH_HOME/.credentials.yaml 引用——与 dsh 自身的凭据解析优先级保持一致。通过 dsh Models 页面存储的密钥会自动生效，无需导出到环境变量。
- Provider 配置来源：严格按运行时形态读取——Desktop dsh 读取 profiles/desktop/cordis.patch.yml，Web dsh 读取 profiles/web/cordis.patch.yml，CLI 读取 $DSH_HOME/settings.yaml。配置会镜像到远程会话中（诸如 agent-default-model 之类的键会被镜像，使远程默认模型与本地一致）。只有 provider 的 baseURL 会被重定向到隧道中。仅镜像配置（凭据引用，不含密钥）；.credentials.yaml 从不镜像（其中可能包含真实密钥）。
- 缺少某个 provider 的密钥只会影响该 provider（返回 502 并附带明确指引）；其他 provider 照常运行。
- 代理令牌和反向端口按会话固定，持久化到远程 .runtime/（令牌权限为 600），并在重连时读回并复用。
- 多个本地 CLI 共享同一会话时共用凭据路径（反向端口先到先得；后到的视图会自动让出）。
- 已知残留风险：远程主机上同权限用户可能通过你的隧道消耗你的配额（他们无法提取密钥本身）。在多用户远程主机上请注意：代理通过按会话令牌、速率限制和路径允许列表提高了门槛，但无法完全阻止同权限用户。

用于 GitHub 访问的远程代理（DSH_REMOTE_PROXY）

远程 dsh 由本工具启动，因此其环境默认不携带任何代理变量——在没有直连互联网的远程主机上，安装 GitHub 插件（使用 HTTPS git ls-remote）会超时，即使 SSH（22 端口）可用。在本地机器上设置 DSH_REMOTE_PROXY 可解决此问题：启动器会将 http_proxy / https_proxy / ALL_PROXY（大小写两种形式）注入远程 dsh 进程，指向你的 SSH 反向隧道在远程暴露的代理端口（例如 http://127.0.0.1:18890）：
bash
DSH_REMOTE_PROXY=http://127.0.0.1:18890 DEEPSEEK_API_KEY=sk-xxx pnpm exec tsx src/cli/bin.ts connect myhost

dsh 本身会将代理变量传递给其生成的 git/pnpm 子进程，因此插件安装和依赖拉取都会经过同一代理。不设置 DSH_REMOTE_PROXY 则不注入任何内容——可直连互联网的机器不受影响。在插件形态下，按主机自定义的变量（面板上的齿轮按钮，持久化在 ~/.dsh/remote-host-env.json）优先于此回退值。

远程磁盘隔离

参照 VS Code 的 ~/.vscode-server 单一根目录自包含模型：本工具在远程写入的所有内容都位于 ~/.dsh-remote-explorer/btsd321/ 内（安装、按会话状态、npm 缓存、临时文件）。它从不写入远程 ~/.dsh（官方 dsh 的主目录）或 ~/.npm（共享 npm 缓存）。远程 dsh 的技能目录也被重定向到会话内（DSH_AGENTS_HOME），而非机器全局的 ~/.agents。

- 同一机器上运行官方 dsh 的其他用户不受影响；doctor 的隔离检查部分会报告使用情况。
- 完全卸载 = rm -rf ~/.dsh-remote-explorer/btsd321，一条命令，干净利落。
- 已知低风险共享：远程 pnpm store —— 仅在有人主动在远程运行 dsh plugin 时才会被触及；内容寻址且并发安全。

在 Git Bash 中编写远程路径时，请使用双斜杠（--cwd //home/xxx），或先设置 MSYS_NO_PATHCONV=1。MSYS 会在参数到达程序之前将 /home/xxx 重写为类似 D:/SoftWare/Git/home/xxx 的内容，CLI 只能检测并拒绝这种情况。

doctor 检查连通性、平台、基本命令、磁盘空间、已安装的运行时、Node 运行时稳定性以及实时镜像延迟。它是排查远程环境问题的首选工具——大多数远程开发失败是环境问题，而非代码问题。

多用户与远程插件管理

多用户模型遵循 VS Code Remote-SSH：

- 同一主机上的不同远程操作系统账户 = 完全隔离（独立的远程根目录、会话、插件）
- 同一远程账户 = 共享会话根目录：相同的（主机、远程目录）意味着相同的远程会话（多个视图），会话之间相互可见，凭据代理属于第一个视图——这是预期行为（VS Code 同样为每个账户共享一个服务器）。为完全隔离，请为每个人使用独立的远程账户
- kill --all 和 clean 默认仅作用于从本机启动的会话（会话启动时将所有者指纹写入远程 .runtime/owner）以及无进程的残留项；其他所有者的会话会被跳过并列出，--include-others 可恢复旧的全局范围行为

远程插件管理，两个界面（VS Code 的“连接时管理”）。插件存储是用户级的（每个远程操作系统账户一个，由其所有会话共享——对应 ~/.vscode-server/extensions/；会话配置文件通过符号链接附加，零副本）：

- 在远程窗口内：远程 dsh 自带的设置插件 UI 功能完整（provisioning 会在远程安装 pnpm）
- 本地管理器页面：远程会话面板的“远程插件”部分可列出 / 安装 / 启用 / 禁用 / 卸载；更改通过远程 hmr 热应用到您自己的实时会话，并在其他会话下次连接时生效（相当于 VS Code 的“需要重新加载”——不会自动重启远程）

架构

本地 (Windows/Linux/macOS)                        远程 (Linux/macOS)
┌────────────────────────────────┐              ┌──────────────────────────────┐
│ 浏览器                          │              │ dsh（完整 npm 安装）           │
│ 127.0.0.1:            │              │ webserver 127.0.0.1:    │
└───────────────┬────────────────┘              │                              │
│ HTTP / WS + 会话令牌           │  ├ session / agent           │
┌───────────────▼────────────────┐  转发         │  ├ fs / subprocess           │
│ dsh-remote-explorer CLI（长期运行）│══════════════▶│  ├ terminal / lsp            │
│ ├ transport  ssh2 conn & fwd   │              │  └ sandbox                    │
│ ├ provision  install Node & dsh│              │                              │
│ ├ tunnel     port forwarding   │  reverse     │                              │
│ ├ session    heartbeat & recon │◀═════════════│  baseURL → 127.0.0.1:   │
│ └ credential LLM proxy         │              │                              │
│   ▲ DEEPSEEK_API_KEY only here │              └──────────────────────────────┘
└───┼────────────────────────────┘
│
Real LLM API (local direct egress)

依赖关系严格单向，自上而下；下层不得导入上层：

Entry        cli/
Orchestration session/
Capability   provision/   tunnel/   credential/
Transport    transport/
Foundation   hosts/   util/

| 模块 | 职责 |
|---|---|
| src/util/ | Shell 转义、错误类型、交互式密码提示（无回显） |
| src/hosts/ssh-config-parser.ts | 主机配置的唯一来源：解析 ssh config（以及临时的 user@host[:port]），递归解析 ProxyJump，应用认证覆盖 |
| src/transport/types.ts | 传输抽象（为多种传输设计；后续可支持 Docker/WSL） |
| src/transport/ssh-transport.ts | ssh2 实现：跳板机链、命令执行、SFTP、正向/反向转发、密码认证（被拒绝时重试，最多 3 次） |
| src/transport/channel-pool.ts | SSH 通道配额，避免超过 MaxSessions |
| src/transport/platform.ts | 共享平台检测与命令构建：架构映射、uname 解析、PATH 组装 |
| src/provision/probe.ts | 远程探测 + Node 稳定性自检 |
| src/provision/mirror-selector.ts | 实时镜像延迟测量与自适应选择 |
| src/provision/remote-paths.ts | 远程路径规则的唯一来源 |
| src/provision/node-installer.ts | 安装 Node，版本隔离，安装后自检 |
| src/provision/dsh-installer.ts | 安装 dsh，显式指定版本（不依赖 dist-tag） |
| src/provision/profile-writer.ts | 每会话独立的 DSH_HOME 及 profile/patch 生成 |
| src/provision/provisioner.ts | 配置编排，每一步均幂等 |
| src/provision/remote-context.ts | 远程执行上下文：绑定传输实例与路径信息 |
| src/util/session-id.ts | 基于主机别名 + 远程目录的确定性会话 ID |
| src/tunnel/port-allocator.ts | 远程端口分配与监听确认 |
| src/tunnel/forward-local.ts | 正向隧道，监听器在重连后仍然存活 |
| src/session/remote-process.ts | 远程 dsh 分离启动、令牌捕获、安全关闭 |
| src/session/lifecycle-state.ts | 会话状态机，纯函数 |
| src/session/heartbeat.ts | 心跳：进程 + 端口 + HTTP 应用层，单条命令 |
| src/session/reconnect.ts | 有界指数退避 |
| src/session/session-registry.ts | 本地会话表，锁文件 + 原子替换 |
| src/session/session-manager.ts | 会话编排：5 阶段打开、心跳、重连、关闭 |
| src/credential/tunnel-proxy.ts | 反向隧道 LLM 代理（多提供商路由），注入真实密钥 |
| src/credential/provider-routes.ts | 从本地配置（settings.yaml / profile patch）提取提供商路由，生成远程镜像 |
| src/credential/local-credentials.ts | 读取本地 .credentials.yaml 引用作为环境变量凭据回退 |
| src/credential/token.ts | 代理令牌：生成与常量时间比较 |
| src/credential/proxy-secret.ts | 凭据材料 I/O：会话作用域令牌与反向端口持久化到远程 |
| src/plugin/remote-plugin-store.ts | 远程插件包管理：列出 / 安装 / 移除 / 切换 |
| src/cli/ | 命令分发、参数解析、终端输出、按命令的认证接线 |

开发
bash
类型检查
pnpm run typecheck

⚠️ 贡献者：克隆后请安装一次 git 钩子——没有它不要提交。

bash
pnpm run setup:hooks

pnpm install 不再构建任何内容：prepare 脚本已被有意移除，因为 pnpm 11 拒绝安装声明了任何生命周期脚本的 git 托管包（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED）。插件产物（lib/）已提交到仓库，并且每当 src/、scripts/ 或 tests/ 发生变化时，pre-commit 钩子会自动重新构建它们。如果你跳过 setup:hooks 并且也忘记手动运行 pnpm run build:plugin，你的提交会附带过时的 lib/——所有从 GitHub 安装的人都会静默地得到过时的插件代码。 没有钩子时，请始终运行 pnpm run build:plugin，并在同一次提交中包含更新后的 lib/。

代码风格指南见 docs/type_script_style.md——写任何代码之前请先阅读它。

打包
生成发布包（参见安装与运行）：esbuild 将 CLI 及其所有运行时依赖打包为单个 dsh-remote-explorer.cjs，然后加入目标平台的官方 Node 二进制文件，以及启动器和文档，最后将所有内容归档。输出位于 dist/（已被 gitignore）——这不会改变源代码本身通过 tsx 运行的方式。
bash
pnpm exec tsx scripts/package.ts                        # 为当前平台打包
pnpm exec tsx scripts/package.ts --all                  # 完整的五平台矩阵
pnpm exec tsx scripts/package.ts --os linux --arch arm64

| 选项 | 描述 |
|---|---|
| --os  | 目标操作系统：win32 / linux / darwin（默认：当前平台） |
| --arch  | 目标架构：x64 / arm64（默认：当前架构） |
| --all | 构建完整的五平台矩阵；忽略 --os / --arch |
| --node-version  | 要捆绑的 Node 版本（默认：v24.21.0） |
| --mirror  | Node 下载源：npmmirror（默认）/ official / 自定义 URL 前缀 |
| --out-dir  | 输出目录（默认：dist） |
| --minify | 压缩打包产物（默认关闭，以保留可读的堆栈跟踪） |

Node 发行版在下载时会根据 SHASUMS256 进行校验，并缓存到 dist/.node-cache，因此重复打包会跳过下载。每次运行都会打印每个产物的路径、大小和 sha256。

许可证

Apache License 2.0 — 参见 LICENSE。