@goodandready/dsh-remote-workspace

dsh plugin --profile web add @goodandready/dsh-remote-workspace

📦 @goodandready/dsh-remote-workspace

<div align="center">

<h3>适用于 DeepSeek Harness 的企业级远程工作区插件：SSH、SFTP 文件同步与端口转发</h3>

<p align="center">

<a href="https://www.npmjs.com/package/@goodandready/dsh-remote-workspace"><img src="https://img.shields.io/npm/v/@goodandready/dsh-remote-workspace.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>

<a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-remote-workspace.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>

<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>

<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>

</p>

<!-- 作者作品展示按钮 -->

<p align="center">

<a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>

</p>

<p align="center">

<a href="README.md"><b>🇬🇧 English</b></a> •

<a href="README.ru.md"><b>🇷🇺 Русский</b></a> •

<a href="README.zh.md"><b>🇨🇳 中文说明</b></a>

</p>

<table align="center">

<tr>

<td align="center">

⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。

<br><br>

🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。

</td>

</tr>

</table>

</div>

---

⚡ 概述与解决的核心痛点

在现代软件工程与智能体工作流中，由 DeepSeek Harness (DSH) 驱动的 AI Agent 往往需要跨越本地限制，在远程基础设施中开展编码与部署工作，例如高性能 GPU 计算节点、云端虚拟机、预发布环境和容器集群。

若没有 @goodandready/dsh-remote-workspace，开发者与 Agent 将面临诸多瓶颈：

1. 本地环境边界：标准 DSH 的工具与运行环境完全受限于部署 DSH 的本地物理机。

2. 临时脚本脆弱不堪：使用系统命令封装的 SSH/SCP 缺乏连接池复用机制，在遇到网络延迟波动时易卡死或断连，且重连握手开销极大。

3. 静默覆盖与文件损坏风险：单纯的文件传输无法感知多端并发修改，且在网络中断时极易留下残缺破损的半成品文件。

4. 服务端口隔离：访问远程节点上启动的 Web 服务、调试端口或大模型推理接口，往往需要开发者在外部繁琐地配置端口映射。

@goodandready/dsh-remote-workspace 将企业级远程工作区能力无缝注入 Cordis 架构：提供基于 SSH2 的高性能连接池、具备原子写入保护的 SFTP、基于 SHA-256 的三向冲突感知同步引擎、动态端口转发隧道，以及参照 dsh-clinebot 风格精心打造的 Web UI 设置卡片。

---

🏗️ 架构设计

graph LR
  subgraph DSH["DeepSeek Harness (Cordis 运行时)"]
    UI["Web UI 设置卡片<br/>(dsh-clinebot 视觉风格)"]
    Routes["REST API 路由<br/>(/state, /browse, /test, /sync)"]
    Tools["模型工具集<br/>(remote_exec, remote_fs, sync, tunnel)"]
    Ssh["SshService<br/>(SSH2 连接池与心跳保活)"]
    SFTP["RemoteFsService<br/>(原子 SFTP 流式传输)"]
    Sync["MirrorSyncService<br/>(三向 SHA-256 同步引擎)"]
    Tunnel["TunnelService<br/>(本地端口转发)"]
  end

  subgraph RemoteNode["远程环境 (云主机 / GPU 算力节点)"]
    SSHD["SSH 服务端 (:22)"]
    FS["远程文件系统"]
    AppPort["远程开发服务 / 应用端口"]
  end

  UI -->|REST API| Routes
  Routes --> Ssh
  Routes --> SFTP
  Routes --> Sync
  Tools --> Ssh
  Tools --> SFTP
  Tools --> Sync
  Tools --> Tunnel
  Ssh -->|SSH2 通道 / 密钥或密码认证| SSHD
  SFTP -->|SFTP 子系统| FS
  Sync -->|增量 Pull / Push| FS
  Tunnel -->|本地端口映射| AppPort

  classDef default fill:#1e1e2e,stroke:#6366f1,stroke-width:1px,color:#cdd6f4;
  classDef accent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#a6e3a1;
  class DSH,RemoteNode accent;

---

✨ 核心特性深度解析

1. SshService — 高性能连接池与双认证支持

• 持久连接池：按 host:port:username 缓存已建立认证的 SSH2 客户端会话，极大降低重复握手延迟。
• 双重认证方式：
• SSH 私钥认证：支持读取本地私钥文件路径（如 ~/.ssh/id_ed25519）、直接输入 PEM 格式密钥文本以及解密口令（Passphrase）。
• 密码认证：原生支持常规账号密码安全登录。
• 链路诊断探测：内置 testConnection 方法，精确测定毫秒级网络延迟，并自动探测远程主机内核与架构（uname -srm）。
• 心跳保活机制：主动发送 Keep-Alive 探测包，有效防止各类网络防火墙超时断开空闲连接。
• 代理命令与跳板：proxyCommand 运行 OpenSSH 风格命令，令牌为 %h、%p、%r、%n 和 %%。jumpHosts 是按顺序排列的配置编号；jumpHostId 可以用逗号分隔作为后备。第一跳来自连接池，后续跳板使用独立连接，并在目标会话结束时关闭。
• 代理与一次性验证码：agentPath 指定 SSH 代理套接字。留空则使用 SSH_AUTH_SOCK；在 Windows 上可填写 pageant。需要键盘交互时，验证码显示在设置卡片上，60 秒后失效。
• 空闲连接：没有隧道、也没有正在执行的命令时，池中的连接在 30 分钟后关闭。下一次命令会重新连接。
• 输出前重连：如果连接在命令产生任何输出之前断开，同一命令最多再试 3 次。命令超时、已经开始的输出，以及 idempotent: false 不会重试。
• 独立终端：终端不共用连接池。关闭终端只关闭这一条 SSH 会话。

2. RemoteFsService — 原子高可用 SFTP 文件系统

• 原子安全写入：文件首先上传至独立的临时文件（.tmp.<timestamp>.<hash>)，上传完成校验后通过原子重命名完成替换，彻底避免因网络异常产生残缺文件。
• 高性能流式读取：采用分块流式读取技术，高效传输大文件且不消耗过多内存。
• 完整文件基语：提供 stat、listDir、递归创建目录 mkdir -p 以及递归删除 remove。

3. MirrorSyncService — 冲突感知的两向/三向镜像同步

• 哈希状态基线：在 .dsh-sync-manifest.json 中完整记录受控文件的 SHA-256 摘要。
• 并发冲突拦截：精准识别本地与远程自上次同步基线以来的同时变动，并在发生冲突时主动中断操作并输出详细冲突列表，绝不静默覆盖。
• 定向传输模式：支持 pull（远程 → 本地）和 push（本地 → 远程），并支持安全强制覆盖（force）参数。
• 演练预览 (Dry-Run)：支持在不产生任何实际磁盘写入的情况下，完整模拟输出变动、新增与删除文件清单。
• 智能忽略规则：内置对版本控制目录、依赖包及临时构建文件的过滤（.git、node_modules、.dsh、.worktrees、.DS_Store）。

4. TunnelService — 深度集成的 SSH 端口转发

• 本地端口转发 (Local Port Forwarding)：在运行 DSH 的主机上开启本地监听端口，将流量通过加密 SSH 隧道透明转发至远程主机的指定端口（例如访问远程 127.0.0.1:8080）。
• 生命周期管控：支持动态开启、注销并实时查询活跃隧道列表。

5. tools.js — 专为 AI Agent 设计的模型工具

为 Agent 赋予 4 个精简、正交的系统级能力：

• remote_exec：在远程工作区执行 Shell 命令，获取标准输出、错误输出及返回码。
• remote_fs：执行远程文件的读、写、状态查询、目录列表、创建与删除。
• remote_sync：在本地镜像与远程目录间发起具备冲突感知的同步操作。
• remote_tunnel：开启、关闭或枚举 SSH 端口转发隧道。
• remote_hosts：返回不含密码、私钥和代理命令的主机 Markdown 表。query 必填，空字符串列出全部主机。
• remote_cluster：在符合环境、标签和别名的主机上运行同一条命令。maxWorkers 默认 8。

6. client.js — 原生 DSH 设置面板

• 深度适配 settings.plugin.item 插槽（Key: dsh-remote-workspace）。
• 分段式认证切换器：优雅切换私钥认证与密码认证。
• 远程目录浏览器弹窗：可视化浏览远程服务器目录树，支持面包屑导航与一键选取。
• 实时连接状态徽章：可视化展示连通性、网络延迟以及远程操作系统信息。页眉徽章读取 /dsh-remote-workspace/state，分别表示正在检查、没有活动主机、主机已就绪或状态不可用，不再固定显示“就绪”。
• 快捷动作触发：一键发起定向文件同步并监控隧道运行状态。保存、删除、设为活动、浏览目录或关闭隧道失败时，卡片上的警告会显示服务器返回的错误。连接测试提交的是配置本身，其中包含 host。
• 插件列表名称：英文为 Remote Workspace，中文为 远程开发工作区，取自随卡片加载的词典。
• 更新版本：该行显示状态接口返回的已安装版本。结果返回前显示“版本未知”。
• 主机分组：配置可以填写 environment、tags、location 和 description。卡片可按平铺、环境或标签显示，并一次测试整组。
• 文件传输：文件页可以上传和下载远程文件，按已传输字节显示进度，并可取消。超过 512MB 的文件会被拒绝。
• 终端字体：terminalFontFamily 是终端的 CSS 字体族。留空则使用默认等宽字体。
• 隐藏页面：浏览

…(truncated)