Skip to main content
C

dsh-scp-ops

ciskonc/dsh-scp-ops

SCP upload and download over the legacy wire protocol on an ssh2 exec channel — works against servers and network devices without an SFTP subsystem, with named auth profiles, recursive trees and remote glob-batch downloads.

Install

dsh plugin --profile web add github:ciskonc/dsh-scp-ops

README

dsh-scp-ops

一个基于 exec 通道线协议的 SCP 上传/下载插件,远端无需 SFTP 子系统。

scp_upload 与 scp_download 覆盖单文件、递归目录与通配符批量传输,命名 profile 面向不带 SFTP 子系统的老设备。

GitHub license GitHub last commit GitHub issues GitHub contributors

English | 中文


Introduction

dsh-scp-ops 是 DeepSeek Harness 的 SCP 上传/下载插件,dsh-ssh-ops 的伴生插件。它在 ssh2 的 exec 通道上实现 SCP 线协议(scp -t / scp -f),远端只要有 scp 可执行文件即可工作,不需要 SFTP 子系统。

原来在 DSH 里往远端传文件,只能在终端里手敲 scp:认证、路径处理与传完后的校验都得自己在终端里弄,插件层面没有入口;不带 SFTP 子系统的主机(嵌入式固件的常见形态)则让 ssh2 库没有现成通道可用。

装好这个插件后,会话里多出 scp_upload 与 scp_download 两个工具。单文件、递归目录与通配符批量传输直接下发,preserve 在双向保留 mtime/atime。老设备通过 profile 级 algorithms 与 keyboard-interactive 自动应答接入。

Installation

从 npm 安装
dsh plugin --profile web add dsh-scp-ops

ssh2 为惰性解析的依赖,不进 dependencies:同一 profile 里已有 dsh-ssh-ops 时自动满足;否则手动添加:

dsh plugin --profile <name> add ssh2

用 pnpm 手动安装 ssh2 时,可能报 ERR_PNPM_IGNORED_BUILDS 且 exit code 为 1;此时包实际已装好可用,该信号有误导性。

从源码构建
git clone https://github.com/ciskonc/dsh-scp-ops.git

ssh2 依赖的处理同上。

Usage

scp_upload

上传,本地到远端。支持单文件与递归目录(recursive)。同一台主机的传输默认排队(max_concurrent_per_host,默认 1);调高该值后,同一主机的不同目录可以并行。两次上传指向同一个远端目标属调用方输入冲突,结果未定义。

落点语义与 OpenSSH scp 一致:上传单文件时,远端目标若为已存在目录,文件落入该目录内;否则按精确路径写入。recursive 上传时,远端目标已存在则本地 basename 嵌套其下,目标尚不存在则该目录本身以本地 basename 的名字建成。结果带 local_path_resolved。

传输流式进行,双向常量内存,并做字节数校验。

scp_download

下载,远端到本地。支持单文件、递归目录与通配符批量(如 /logs/*.log);literal: true 时通配符字符按字面名处理。

recursive 下载时,远端顶层 basename 总是嵌套在 local_path 之内。结果带 local_path_resolved。

下载写入做包含性校验,拒绝 ./ 与 .. 条目;目标目录内的符号链接若指向该目录之外则拒绝进入,同名链接也不覆盖。插件宿主为 Windows 时,文件名按 Windows 语义消毒(剥离 ADS 冒号、保留名与尾点)。远端声明的文件大小按 4 GiB 上限校验,一棵目录树的条目数上限为 20000。

命名 profile

命名 profile 定义在 patch 层的 config.profiles 列表:

- id: scp-ops
  name: 'dsh-scp-ops'
  config:
    profiles:
      - name: legacy-nas
        host: 192.168.1.10
        username: admin
        password: 'app-password'
        algorithms:
          kex: [diffie-hellman-group14-sha1]
          cipher: [aes128-cbc]
        try_keyboard: true

命中 profile 后端点被锁定:内联的 host/port/username 与 profile 冲突时会被拒绝,仅认证材料(password/private_key/passphrase)可内联补充。

老设备兼容走 profile 级 algorithms(SHA1 KEX、CBC 一类)与 try_keyboard(keyboard-interactive 自动应答)。

通用参数
参数说明
profile 或内联 host/port/username/password/private_key/passphrase连接来源;命中 profile 后端点锁定,见上节
recursive递归目录传输(scp -r)
preserve双向保留 mtime/atime(scp -p;T 帧按 OpenSSH 四字段格式往返)
literal仅下载:通配符按字面名处理
timeout_ms取值区间 [5000, 3600000],默认 10 分钟;低于 5000 抬升到 5000,高于 3600000 钳到上限
algorithms内联覆盖 SSH 算法(kex、cipher),供老设备使用;一般写在 profile 里
try_keyboard自动应答 keyboard-interactive 认证提示;一般写在 profile 里

Compatibility

插件版本实测 DSH说明
0.2.3 (2026-11-20)≥ 0.2.0-rc.1(实测 0.2.2-rc.5)当前版本。不同主机写入同一 local_path 的下载按目标路径串行化
0.2.0 – 0.2.2≥ 0.2.0-rc.1早期线。上面那条按目标路径串行化是 0.2.3 才有的行为

远端兼容:

远端状态
OpenSSH 9.2p1(fnOS NAS)真机回归已验证
dropbear / BusyBox / 厂商固件未验证
Windows OpenSSH 远端,含空格路径不支持

插件为 host-only bundle:注册 host 工具与 patch config,不含 client 侧组件。

Known limitations

  • 无断点续传。
  • 同一主机串行传输(max_concurrent_per_host 默认 1)。
  • 传输中途失败时,已传文件保留,不做回滚。
  • 不做 SSH 主机密钥校验(TOFU,首次连接即信任)。
  • SCP 协议没有长度前缀,恶意远端可声明错误大小导致 ±1 字节歧义;靠本地收尾字节对账和超时进度定位来缓解。
  • 通配符下载依赖远端 scp 支持 -- 分隔符。
  • local_path 必须为绝对路径。
  • 单次下载单文件上限 4 GiB,一棵目录树最多 20000 个条目;远端声明超出即拒绝。
  • 0.2.3 起,不同主机并行下载写入同一 local_path 已按目标路径自动串行化。

Credits

  • dsh-ssh-ops(caoyiwei850):伴生插件。
  • ssh2(mscdex):exec 通道与 SCP 线协议的底层实现库。

License

以 MIT 许可证发布。

Related plugins