dsh-sidebar-remote

前言¶

在 DSH（DeepSeek Harness）的插件化架构中，侧边栏与 SSH 远程会话的集成通常需要分别处理。dsh-sidebar-remote 插件通过聚合 dsh-better-sidebar 和 @dsh-ssh/dsh-ssh，提供了一套单一可安装的解决方案。它解决了远程工作区文件操作、终端和 Git 需要在远端执行，而本地工作区侧边栏保持原有行为的需求。

插件介绍¶

dsh-sidebar-remote 是一个 DSH Web 聚合插件。它由 zijun-T 维护。其核心价值在于将 SSH 远程工作区的功能（文件、预览、传输、终端、Git）完全下沉到远端执行，同时通过插件机制保持本地侧边栏的一致性。

核心功能¶

插件提供以下能力：
* 文件树 / 浏览：通过 SFTP readdir 和 stat 探测。
* 读取 / 编辑 / 保存：通过 Sftp.readText、applyLiteralEdit 和 writeFileAtomic。
* 上传 / 下载：使用 Sftp.createWriteStream / createReadStream，失败时自动清理。
* 预览：通过 /sidebar/remote/html/<sid>/<path> 路由提供。
* 终端：通过 SshConn.shell PTY 实现，支持 30s 重连优雅期。
* Git：通过 git -C <cwd> --no-pager -c color.ui=false 在远端执行。

安装与配置¶

插件通过 dsh plugin 命令安装，安装后 cordis.patch.yml 会自动挂载聚合插件。

本地路径安装：

    dsh plugin --profile web add /path/to/remote-sidebar-plugin

Tarball 安装（推荐用于换机部署）：
先在源机器打包：

    npm pack

再在目标机器安装：

    dsh plugin --profile web add ./dsh-sidebar-remote-0.2.1.tgz

NPM 安装：

    dsh plugin --profile web add dsh-sidebar-remote

移除插件：

dsh plugin --profile web remove dsh-sidebar-remote

依赖要求¶

运行本插件需满足以下环境：
* DSH: 0.1.1-rc.2
* Cordis: ^4.0.1
* Node: >=22
* 上游插件: dsh-better-sidebar (0.17.1), @dsh-ssh/dsh-ssh (0.1.3)

使用与更新¶

安装后行为：
插件无额外 UI，无独立入口。安装后侧边栏会自动区分本地与远程会话。本地会话不建立 SSH 连接，沿用原 dsh-better-sidebar 行为。

更新注意事项：
1. 更新后必须重启 dsh web 进程（Host 半边无热重载）。
2. 浏览器端需硬刷新（Ctrl+Shift+R）以避免沿用旧 client bundle。

更新命令：

# 使用 pnpm 更新 git 依赖
cd ~/.dsh/profiles/web && pnpm update dsh-sidebar-remote

提示词路径改写 (0.2.1+)¶

远程会话的 cwd 在模型提示词的 sandbox:policy 中原为占位符。插件在组装期将其改写回真实远程路径。

主路径改写：通过 deepseek-harness-zh_pro 的 registerAssembleRewriter 注册（运行于翻译之后）。
兜底改写：agent/pre-step 监听器对 decision.messages 做同样替换。
映射构建：由 remoteCwdMapOf() 构建，基于 ctx.sessions.list() 返回的活会话数组。

验证方式：远程会话对话的上下文注入中 sandbox:policy 显示真实路径，Host 日志输出 rewriter: replaced "<占位符>" → "<真实路径>"。

换机部署¶

客户端在挂载时会向 GET /sidebar/remote/root 取回权威占位根，一份 bundle 可服务任意部署。

迁移配置：
迁移 ~/.dsh/settings.yaml 即可带走主机配置与侧边栏偏好。注意私钥和 known_hosts 不会自动迁移，需在新设备上手动复制 ~/.ssh/* 或通过 TOFU 对话重建。

验证¶

插件包含自动化验证脚本，无需网络与远端主机即可运行部分测试。

npm install
npm run typecheck
npm test             # 102 tests / 14 suites
npm run build
npm pack --dry-run

真机端到端验证：

DSH_ORIGIN=http://127.0.0.1:3080 \
DSH_HOST_ID=<settings.yaml 里的主机 id> \
DSH_REMOTE_PATH=/path/on/remote \
DSH_EXPECT_ENTRY=<该目录下必然存在的名字> \
  npm run verify:live    # 14 项断言