本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-remote

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add dsh-remote

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• 远程 —— 一个机器下拉；路径输入框自动预填 / 并实时补全目录（点选一个目录后立即列出它的下一级，像系统/VSCode 逐级选目录）；另外有**「浏览…」浮窗**，选中仅回填到输入框（不直接提交），你复核 / 修改后点「设为远程工作区」。
• 多机 SSH —— 可存任意多台主机（host/port/user + 私钥或密码）。密码只存在本地，界面不回显；在设置里一键切当前机。
• 双 tab 工作区选择器（填充原生「Add workspace」流程）：
• • 本机 —— 走 host 端原生系统文件夹对话框选本地目录（或直接输入本地路径）→ 直接成为普通 DSH 本地工作区（与本地工作区共存）。优先用 DSH 的 directoryPicker 服务，服务缺失时回退到插件自持的原生选择器（macOS osascript / Linux zenity→kdialog）——桌面启动路径上框架服务不注册也能用。
• 双向 SFTP 同步（增量） —— rw_sync（远程→镜像）、rw_push（镜像→远程），本地镜像改动可回传机器。两者都会跳过 size+mtime 未变化的文件，并有单文件大小上限防误拉大二进制；目录遍历带有界并发。

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

安装后还需要做什么才能用？

首次使用需要在「设置 → 远程工作区」里添加至少一台 SSH 主机（host/port/user + 密码或私钥），保存后切换为当前机器，再到「Add workspace」选「远程」tab 选一台机器并指定远端目录即可开始用。

远程机器必须是 Linux 吗？

不必须。所有文件操作走 SFTP 协议层，不依赖远端 shell，所以 Linux、macOS 和 Windows 远程主机都可列目录、读、写、改、搜、同步。

密码和主机凭据存在哪里？安全吗？

默认存在本机 $DSH_HOME/remote-workspaces/machines.json 和 .secrets/ 下；可选「加密保存密码」让单台机器的密码走系统钥匙串（macOS Keychain / Windows DPAPI / Linux secret-tool），任何失败会自动回退到明文但不阻塞连接。

主机指纹会不会被中间人替换？

默认开启 TOFU（首次信任）校验。首次连接记录指纹，之后密钥变化立即拒绝；可改为 verify（拒绝未知主机）或 off（关闭，不推荐）；指纹误判可用「/remote-forget-key」重置。

修改远端文件会被本地工作区覆盖吗？

不会。rw_sync 和 rw_push 都是三路（远端 vs 本地 vs 上次同步快照）对比，两端同时改动会标记为冲突、绝不覆盖；要用本地覆盖远端时显式传 force=true。

出错提示「Channel open failure: open failed」怎么办？

通常是 SSH 空闲被服务端关闭，插件 0.7.3 起会自动丢弃旧连接并重连一次；如持续出现，调高 commandTimeoutMs / connectTimeoutMs，或主动 rw_disconnect 重连。

自带侧边栏会不会和已有 dsh-better-sidebar 冲突？

不会。自 0.7.2 起 dsh-better-sidebar 是硬依赖并自动挂载，bundle 用专门的 dsh-remote-sidebar 行 ID + 守卫探测是否已有同名行，存在就退避，不会重复注册 /sidebar/api 也不会让插件启动失败。

0.6 之前安装过，老数据会丢吗？

不会。首次启动会自动把 ~/.dsh/remote-workspaces 迁移到 $DSH_HOME/remote-workspaces；当你显式指向另外的 DSH_HOME（比如多安装实例）时则跳过迁移，避免误搬别人的数据。

profile 必须用 pnpm hoisted 否则会怎样？

loader 从 profile 根解析插件包；若 pnpm-workspace.yaml 丢了 nodeLinker: hoisted，内嵌侧边栏会报 Cannot find package 'dsh-better-sidebar'，把配置加回并 pnpm install 一次即可。

怎么把数据传给远程机器和从远程机器拉回来？

大目录走 rw_sync（拉）/ rw_push（推），都支持 dryRun 预演、async 后台任务、force 覆盖；单文件走 rw_download / rw_upload（流式 fastGet/fastPut）；单文件改动也可以直接 rw_write_file / rw_edit（带 mtime 乐观锁）绕过镜像。

— 源: plugin_wiki.faq_json

兼容性

• DSH: ^0.1.0-rc.6
• Node: 未声明

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则