@zicolasjac-ai/remote-readonly-ssh 1.4.0 → 1.4.2

package/README.md

@@ -2,7 +2,7 @@
 
 **CLI and Agent Skill for safe read-only SSH inspection via JumpServer.**
 
-让 AI 助手（opencode / Claude Code / Cursor / Windsurf / Codex 等）通过堡垒机白名单强制地在服务器上做只读查询——技术上零写能力，每次调用（含被拒绝的）写入本地审计日志。
+让 AI 助手（opencode / Claude Code / Cursor / Windsurf / Codex 等）通过堡垒机白名单强制地在服务器上做只读查询——技术上零写能力，每次调用（含被拒绝的）写入本地审计日志；另支持与 `direct: true` 直连资产通过 SFTP 做单文件传输（下载开箱可用、带敏感路径防呆；**上传默认禁用**，须配置显式开启 + 独立写路径白名单）。
 
 ## 为什么需要它
 
@@ -68,6 +68,8 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 | `dir <path>` | 列目录（同路径白名单） |
 | `bin-version <bin>` | 查二进制版本/编译参数（二进制白名单） |
 | `exec-only <cmd>` | 通用只读命令（前缀白名单 + 禁止模式） |
+| `download <远程> <本地>` | 下载单文件（SFTP：direct 直连或堡垒机 koko 网关；shadow/.ssh 类路径防呆） |
+| `upload <本地> <远程>` | 上传单文件（写操作，**默认禁用**：须 `file_transfer.upload.enabled=true` + 独立写路径白名单） |
 
 ## 配置
 
@@ -76,13 +78,14 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 | 键 | 说明 |
 |-----|------|
 | `auth_profiles` | **认证组**（可多个）：`{组名: {host, port, username, auth, direct?}}`。`auth.mode` 支持 `key`（`private_key_path` 必填，可选 `private_key_passphrase`）与 `password`（`password` 必填）。`direct: true` 表示**直连裸机**（跳过堡垒机菜单，适合无堡垒机的服务器；命令只读校验与堡垒机模式完全一致）。`list-tools` 只显示模式与主机，不显示任何凭据 |
-| `target_hosts` | 目标主机白名单 `{ip: {profile, keyword?}}`：`profile` 引用认证组名，`keyword` 为堡垒机资产搜索关键字（缺省用 IP）。**多台主机可共用同一认证组（N:1）** |
+| `target_hosts` | 目标主机白名单 `{ip: {profile, keyword?, sftp_root?}}`：`profile` 引用认证组名，`keyword` 为堡垒机资产搜索关键字（缺省用 IP）；`sftp_root` 可选——koko 资产树资产目录（如 `Default/业务分组/10.0.0.3`），文件传输在菜单资产模式下用于路径映射，未配置时自动探测（命中多个要求显式声明）。**多台主机可共用同一认证组（N:1）** |
 | `audit` | `enabled`（默认 true，关闭则不留痕）与 `include_output`（默认 false，true 时把命令输出摘要写入审计日志） |
 | `allowed_version_bins` | 允许执行 `-v/-V` 的二进制白名单 |
 | `allowed_command_prefixes` | 只读命令前缀白名单（cat/ls/grep/ps/ss/tail...） |
 | `allowed_path_prefixes` | 允许读取的路径前缀 |
 | `blocked_paths` | 敏感路径黑名单（shadow/passwd/密钥/家目录） |
 | `container_exec` | 可选：`docker exec` 容器只读策略（允许子命令、路径前缀、递归路径前缀、超时、输出上限） |
+| `file_transfer` | 可选：文件传输策略 `{upload: {enabled, allowed_path_prefixes}, download: {blocked_paths}, verify}`，见下节 |
 
 > **凭据安全提示**：密码为明文存放于本机 `config.json`（与私钥文件同级信任，仅本机可读）。Windows 建议收紧 ACL，Linux/macOS 建议 `chmod 600 ~/.rrs/config.json`。
 >
@@ -90,6 +93,56 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 
 审计日志：`~/.rrs/audit.log`
 
+## 文件传输（SFTP，单文件）
+
+`download` / `upload` 通过 SSH **SFTP 子系统**传文件，与巡检命令共用同一套连接层（TOFU 主机密钥校验、审计留痕一致）。
+
+**硬约束**：
+
+- **双通道**：
+  - `direct: true` 直连认证组 → SFTP 通道即目标机**真实文件系统**；
+  - 普通堡垒机菜单资产 → 走 JumpServer **koko 的 SFTP 文件传输入口**（与 SSH 菜单同端口同一套凭据，无需进菜单）。语义路径自动映射进该资产在 koko 资产树中的目录（如 `Default/资产组/10.0.0.3`）：默认**自动探测**（逐层 readdir 找名为资产 IP 的目录，命中多个则要求显式配置）；特殊命名可在 `target_hosts` 条目加 `"sftp_root": "Default/资产组/10.0.0.3"` 显式声明。
+  - koko 模式暂不支持 `verify: "sha256"`（远端散列需直达 exec 通道），配置为 sha256 时明确报错。
+- **大小不设上限**（1GB 级为常规场景；速度受链路带宽约束）。
+- 目标（两端）**已存在即拒绝**：`--overwrite` 从头重传；`--resume` 断点续传未完成半成品 `<目标>.rrs-part`（互斥，续传前校验两端字节数一致）。产物先写半成品、校验后原子改名，**见到正式文件即视为完整**。
+- 单文件传输；不支持目录递归、不支持 `docker exec` 容器内文件。
+- 上传需 opt-in + 独立写路径白名单（语义路径层校验，koko 模式同样生效）；上传/下载不受 `(语义路径) 之外的资产树越界`——映射后被强制限定在该资产目录内。
+
+**下载**（默认可用）：
+
+```bash
+rrs download /var/log/app.log "E:\logs\app.log" --host 10.0.0.2 --json
+rrs download /var/log/app.log "E:\logs\app.log" --resume --host 10.0.0.2   # 续传
+```
+
+不做读白名单限制，但敏感路径防呆生效：内置 `/etc/shadow` 族、任意 `/.ssh/` 目录/密钥一律拒绝，且你的 `blocked_paths` 全局黑名单与 `file_transfer.download.blocked_paths` 追加同样生效（读白名单放开 ≠ 敏感黑名单放开）。
+
+**上传**（opt-in，默认拒绝）：
+
+在 `~/.rrs/config.json` 显式开启（写路径与读路径分开管，不上读白名单的当）：
+
+```json
+"file_transfer": {
+  "upload": {
+    "enabled": true,
+    "allowed_path_prefixes": ["/opt/upload/", "/data/deploy/"]
+  },
+  "download": { "blocked_paths": [] },
+  "verify": "size"
+}
+```
+
+```bash
+rrs upload "E:\deploy\nginx.conf" /opt/upload/nginx.conf --host 10.0.0.2 --json
+```
+
+- 未配置 `allowed_path_prefixes` 时**上传一律拒绝**（避免"开了开关即全盘可写"）。
+- 远程路径拒绝控制字符与 shell 元字符；`--overwrite` / `--resume` 语义同上。
+
+**完整性校验**：默认核两端**字节大小**（零开销）。需要防"传输期间文件被改"时把 `verify` 设为 `"sha256"`——远端会跑 `sha256sum`，因此须把 `"sha256sum "` 加入 `allowed_command_prefixes`（黑白名单语义不受影响，缺白名单会明确报错而非静默绕过）。
+
+`--json` 输出含 `bytes` / `elapsed_ms` / `resumed` / `verify` 等元数据；终端下进度打在 stderr，不污染 JSON。
+
 ## Agent Skills
 
 本工具附带一份 `SKILL.md`，教 AI 助手何时用、怎么用 `rrs`。安装后用 `rrs setup skills` 一键分发到各 agent 的 skills 目录：

package/bin/rrs.js

@@ -10,6 +10,7 @@ const {
 } = require("../src/whitelist");
 const setupSkill = require("../src/setup");
 const initWizard = require("../src/init");
+const transfer = require("../src/transfer");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 
@@ -24,13 +25,17 @@ function printUsage() {
     ["dir <path>", "列目录（路径白名单）"],
     ["bin-version <bin>", "查二进制版本（二进制白名单）"],
     ["exec-only <cmd>", "通用只读命令（前缀白名单+禁止模式）"],
+    ["download <远程> <本地>", "下载单文件（SFTP，仅 direct 主机；内置敏感路径防呆）"],
+    ["upload <本地> <远程>", "上传单文件（SFTP，默认禁用需配置开启 + 写路径白名单）"],
     ["setup skills [--agent <n>]", "把 SKILL.md 装到 agents(实体) + opencode/claude/qoder(软链接)"],
     ["setup uninstall skills [--agent <n>]", "移除上述目录的 skill"],
   ];
   console.log("rrs — CLI and Agent Skill for safe read-only SSH inspection\n");
   console.log("用法: rrs <工具> [参数] [--host <ip>] [--config <file>] [--json]");
+  console.log("      rrs download <远程绝对路径> <本地绝对路径> [--overwrite|--resume] [--host <ip>]");
+  console.log("      rrs upload <本地绝对路径> <远程绝对路径> [--overwrite|--resume] [--host <ip>]");
   console.log("      rrs setup skills [--agent opencode|claude|cursor|windsurf|codex|openhands|agents|all] [--dry-run]\n");
-  console.log("选项: --json 以 JSON 输出结果（便于脚本/AI 调用）; -v/--version 查看版本\n");
+  console.log("选项: --json 以 JSON 输出结果（便于脚本/AI 调用）; --overwrite 重传; --resume 断点续传; -v/--version 查看版本\n");
   for (const [k, v] of cmds) {
     console.log(`  ${k.padEnd(40)} ${v}`);
   }
@@ -48,6 +53,8 @@ function parseArgs(argv) {
     config: null,
     version: false,
     json: false,
+    overwrite: false,
+    resume: false,
   };
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
@@ -56,6 +63,8 @@ function parseArgs(argv) {
     else if (a === "--config") opts.config = argv[++i];
     else if (a === "--agent") opts.agent = argv[++i];
     else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--overwrite") opts.overwrite = true;
+    else if (a === "--resume") opts.resume = true;
     else if (a === "-h" || a === "--help") { opts.mode = "tool"; opts.tool = "help"; }
     else if (a === "-v" || a === "--version") opts.version = true;
     else if (a === "--json") opts.json = true;
@@ -74,6 +83,7 @@ function parseArgs(argv) {
   }
   opts.tool = opts.tool || rest[0] || "help";
   opts.arg = rest[1] || null;
+  opts.arg2 = rest[2] || null;
   return opts;
 }
 
@@ -188,6 +198,10 @@ function listTools(conf) {
   console.log(`允许主机: ${Object.keys(conf.target_hosts || {}).join(", ")}`);
   console.log(`允许查版本: ${(conf.allowed_version_bins || []).join(", ")}`);
   console.log(`允许读路径前缀: ${(conf.allowed_path_prefixes || []).join(", ")}`);
+  const ft = conf.file_transfer || {};
+  const upEnabled = ft.upload && ft.upload.enabled === true;
+  const upPrefixes = (ft.upload && ft.upload.allowed_path_prefixes || []).join(", ") || "(未配置=全禁)";
+  console.log(`文件传输: 下载=可用（内置敏感路径防呆） | 上传=${upEnabled ? `启用（写路径前缀: ${upPrefixes}）` : "禁用（file_transfer.upload.enabled=true 开启）"}`);
   console.log(`配置文件: ${process.env.RRS_CONFIG || path.join(configDir(), "config.json")}`);
   console.log(`审计日志: ${path.join(configDir(), "audit.log")}`);
 }
@@ -198,6 +212,93 @@ function emitResult(opts, data) {
   else console.log(data.output);
 }
 
+// ==== 文件传输（upload / download）====
+
+function fmtBytes(n) {
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let v = Number(n) || 0;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) { v /= 1024; i++; }
+  return `${v >= 100 || i === 0 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
+}
+
+function fmtDur(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m${String(s % 60).padStart(2, "0")}s`;
+}
+
+/** 进度只打到 stderr（不污染 --json 的 stdout），且仅终端场景显示 */
+function makeProgress(opts) {
+  if (opts.json || !process.stderr.isTTY) return null;
+  const startedAt = Date.now();
+  return (sent, total) => {
+    const pct = total > 0 ? ((sent / total) * 100).toFixed(1) : "-";
+    const speed = sent / 1048576 / Math.max(0.25, (Date.now() - startedAt) / 1000);
+    process.stderr.write(`  已传 ${fmtBytes(sent)} / ${fmtBytes(total)}（${pct}%，~${speed.toFixed(1)} MiB/s）   \r`);
+  };
+}
+
+async function runTransfer(opts, conf) {
+  const tool = opts.tool;
+  const isUpload = tool === "upload";
+  // 语义：upload <本地> <远程>；download <远程> <本地>
+  const args = isUpload
+    ? { local: opts.arg, remote: opts.arg2, overwrite: opts.overwrite, resume: opts.resume }
+    : { remote: opts.arg, local: opts.arg2, overwrite: opts.overwrite, resume: opts.resume };
+
+  // ---- 静态校验（拒绝类：退出码 2）----
+  let host = null;
+  let cmds = [];
+  let plan;
+  try {
+    host = validateHost(opts.host || Object.keys(conf.target_hosts || {})[0], conf);
+    cmds = [isUpload
+      ? `upload ${args.local || "(无)"} -> ${args.remote || "(无)"}`
+      : `download ${args.remote || "(无)"} -> ${args.local || "(无)"}`];
+    plan = transfer.prepareTransfer(conf, host, tool, args);
+  } catch (e) {
+    audit(conf, tool, host || "", cmds, false, e.message);
+    emitResult(opts, { ok: false, tool, host: host || "", error: e.message, kind: "拒绝" });
+    process.exit(2);
+  }
+
+  // ---- 连接与执行（错误类：退出码 1）----
+  const shell = new JumpShell(conf, host);
+  try {
+    await shell.connect(); // direct 连接即到目标机，无需菜单 login
+    const onProgress = makeProgress(opts);
+    const result = isUpload
+      ? await transfer.uploadFile(shell, conf, plan, onProgress)
+      : await transfer.downloadFile(shell, conf, plan, onProgress);
+    shell.close();
+    try { if (onProgress) process.stderr.write("\n"); } catch (_) {}
+
+    const speedBps = result.bytes / Math.max(0.001, result.elapsedMs / 1000);
+    const resumeTag = result.resumed ? "（断点续传）" : "";
+    const viaTag = plan.mode === "koko" ? "（koko 资产树直传）" : "";
+    const verifyTag = result.verify === "sha256" ? "，sha256 校验通过" : "";
+    const text = `${isUpload ? "上传" : "下载"}完成: ${plan.local} ↔ ${plan.remote} | ${fmtBytes(result.bytes)} 耗时 ${fmtDur(result.elapsedMs)} 均 ${(speedBps / 1048576).toFixed(1)} MiB/s${resumeTag}${viaTag}${verifyTag}`;
+    audit(conf, tool, host, cmds, true,
+      `bytes=${result.bytes} elapsed=${result.elapsedMs}ms resumed=${result.resumed} verify=${result.verify} overwrite=${plan.flags.overwrite} via=${plan.mode}`);
+    emitResult(opts, {
+      ok: true, tool, host,
+      local: plan.local, remote: plan.remote,
+      bytes: result.bytes, resumed: result.resumed,
+      elapsed_ms: result.elapsedMs, verify: result.verify,
+      overwrite: plan.flags.overwrite, via: plan.mode,
+      output: text,
+    });
+  } catch (e) {
+    shell.close();
+    try { if (!opts.json && process.stderr.isTTY) process.stderr.write("\n"); } catch (_) {}
+    audit(conf, tool, host, cmds, false, e.message);
+    emitResult(opts, { ok: false, tool, host, error: e.message, kind: "错误" });
+    process.exit(1);
+  }
+}
+
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.version) {
@@ -224,6 +325,7 @@ async function main() {
   }
 
   if (opts.tool === "list-tools") { listTools(conf); return; }
+  if (opts.tool === "upload" || opts.tool === "download") { await runTransfer(opts, conf); return; }
 
   let host, cmds;
   try {

package/config.example.json

@@ -32,7 +32,8 @@
   },
   "target_hosts": {
     "10.0.0.1": { "profile": "profile_a", "keyword": "10.0.0" },
-    "10.0.0.2": { "profile": "profile_a", "keyword": "10.0.0" }
+    "10.0.0.2": { "profile": "profile_a", "keyword": "10.0.0" },
+    "10.0.0.3": { "profile": "profile_b", "keyword": "10.0.0", "sftp_root": "Default/业务分组/10.0.0.3" }
   },
   "audit": {
     "enabled": true,
@@ -90,6 +91,16 @@
     "/etc/",
     "/var/log/"
   ],
+  "file_transfer": {
+    "upload": {
+      "enabled": false,
+      "allowed_path_prefixes": ["/opt/upload/"]
+    },
+    "download": {
+      "blocked_paths": []
+    },
+    "verify": "size"
+  },
   "blocked_paths": [
     "/etc/shadow",
     "/etc/passwd",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "只读 SSH 运维 CLI 与 Agent Skill：通过 JumpServer 堡垒机白名单强制执行只读查询；认证组支持 SSH 私钥/密码两种模式与按 IP 分组；附 SKILL.md 让 opencode / Claude Code / Cursor 等 AI 助手自动发现并正确调用。",
   "license": "MIT",
   "bin": {

package/skills/remote-readonly-ssh/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: remote-readonly-ssh
-description: 通过 JumpServer 堡垒机对服务器做白名单强制的只读运维查询（sys-info / proc / ports / dir / read-file / bin-version / exec-only）。技术强制只读、命令前缀白名单 + 禁止模式 + 路径白名单 + 主机白名单多层校验，每次调用（含被拒绝的）都写入本地审计日志。AI Agent 需要做"查看服务器现状"这类操作时调用此 skill；它不会写入任何远程状态。
+description: 通过 JumpServer 堡垒机对服务器做白名单强制的运维查询与单文件传输（sys-info / proc / ports / dir / read-file / bin-version / exec-only / download / upload）。命令默认只读、前缀白名单 + 禁止模式 + 路径白名单 + 主机白名单多层校验；下载自带敏感路径防呆，上传默认禁用需配置显式开启；传输支持 direct 直连资产与堡垒机菜单资产（koko 资产树自动探测或 sftp_root 显式声明）。每次调用（含被拒绝的）都写入本地审计日志。AI Agent 需要查看服务器现状或与白名单服务器互传单文件时调用此 skill。
 license: MIT
 compatibility: opencode, claude-code, cursor, windsurf, openhands, qoder, codex
 metadata:
   audience: ai-agents
   category: ops
-  safe: read-only
+  safe: readonly-with-audited-optional-upload
 ---
 
-# rrs — Read-Only SSH Inspection Skill
+# rrs — Read-Only SSH Inspection & File Transfer Skill
 
-`rrs`（remote-read-only-ssh）是一个面向 AI Agent 的只读 SSH 运维工具。它通过 JumpServer 风格的堡垒机在白名单目标主机上执行**白名单强制**的只读查询。每次调用（含被拒绝的）都写入本地审计日志。
+`rrs`（remote-read-only-ssh）是一个面向 AI Agent 的只读 SSH 运维工具。它通过 JumpServer 风格的堡垒机在白名单目标主机上执行**白名单强制**的只读查询，并支持对白名单主机做单文件上传/下载（SFTP）：`direct: true` 直连资产走真实文件系统，普通菜单资产走 JumpServer koko 的 SFTP 文件传输入口（资产树自动探测或 `sftp_root` 显式声明）。每次调用（含被拒绝的）都写入本地审计日志。
+
+安全定位：**命令查询技术上零写能力**；文件下载原则上不写远端；**文件上传是唯一写远程状态的能力**——默认禁用，须在本机配置显式开启 + 写路径白名单。
 
 ## When to use me
 
@@ -24,8 +26,10 @@ metadata:
 - 列目录结构（`dir /var/log`）
 - 查二进制版本（`bin-version nginx`）
 - 跑一段自定义只读命令（`exec-only "df -h | head"`）
+- 从 `direct` 直连服务器**下载**文件到本地（`download /var/log/app.log 本地路径`）
+- 向 `direct` 直连服务器**上传**文件（仅当用户已配置启用上传后可用；运行前先征得用户同意，因为这是写操作）
 
-**不要**用它做任何写操作——rm / mv / cp / vi / sed -i / systemctl / 重定向到文件 等一律被拒绝。
+**不要**用它做任何写操作——rm / mv / cp / vi / sed -i / systemctl / 重定向到文件 等一律被拒绝；**不要**试图用 `upload` 绕过这一约束，上传路径有独立白名单。
 
 ## Setup（用户一次性）
 
@@ -41,6 +45,8 @@ rrs setup skills  # 把本 skill 安装到 opencode / claude / agents 等目录
 
 ```bash
 rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
+rrs download <远程绝对路径> <本地绝对路径> [--overwrite|--resume] [--host <ip>]
+rrs upload <本地绝对路径> <远程绝对路径> [--overwrite|--resume] [--host <ip>]
 ```
 
 **始终加 `--json`**，便于解析。
@@ -56,6 +62,8 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 | `dir <path>` | 列目录 | `rrs dir /var/log --json` |
 | `bin-version <bin>` | 查二进制版本/编译参数 | `rrs bin-version nginx --json` |
 | `exec-only <cmd>` | 通用只读命令（白名单校验） | `rrs exec-only "df -h" --json` |
+| `download <远程> <本地>` | 下载单文件（SFTP，仅 direct 资产） | `rrs download /var/log/app.log E:\logs\app.log --json` |
+| `upload <本地> <远程>` | 上传单文件（opt-in，写路径白名单） | `rrs upload E:\deploy\a.conf /opt/upload/a.conf --json` |
 | `list-tools` | 查看白名单 / 配置 | `rrs list-tools --json` |
 | `init` | 生成配置模板 | `rrs init` |
 
@@ -63,6 +71,8 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 
 - `--host <ip>`：指定目标主机（必须存在于 `target_hosts` 白名单）
 - `--config <file>`：使用自定义配置文件
+- `--overwrite`：传输目标已存在时从头重传（默认拒绝覆盖）
+- `--resume`：断点续传半成品 `.rrs-part` 文件（与 `--overwrite` 互斥）
 - `--json`：以 JSON 输出
 - `-v` / `--version`：查看版本
 - `-h` / `--help`：查看用法
@@ -75,6 +85,12 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 {"ok":true,"tool":"sys-info","host":"10.0.0.1","output":"..."}
 ```
 
+传输成功（JSON 含传输元数据）：
+
+```json
+{"ok":true,"tool":"download","host":"10.0.0.2","local":"E:\\logs\\app.log","remote":"/var/log/app.log","bytes":1234,"resumed":true,"elapsed_ms":5678,"verify":"size","overwrite":false,"output":"下载完成: ..."}
+```
+
 拒绝（参数非法 / 敏感路径 / 命令不在白名单）：
 
 ```json
@@ -97,6 +113,14 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 4. **不要**试图把 `;` `&&` `|` `>` `$()` 拼到参数里——所有路径和参数都做严格字符集校验
 5. **容器命令只走受控路径**：若使用 `docker exec`，必须遵守 `container_exec.allowed_path_prefixes`；默认只允许 `/workspace/ds-dev` 这类明确前缀，`grep -r` 只允许递归配置中的日志目录，禁止 `bash/sh`、`tail -f`、`ls -R`、相对路径和越界路径。
 6. **修改 `~/.rrs/config.json` 前必须先征得用户确认**（`~/.rrs/` 下的所有文件均如此，含白名单、target_hosts、认证组、known_hosts）。被拒绝时不要直接动手改配置：先把需要的路径/主机/变更内容展示给用户，等用户明确同意后再编辑。配置文件属于用户资产，不在工具的只读授权范围内自行变更。
+7. **传输约束（upload/download）**：
+   - 通道：`direct: true` 直连资产 = 真实文件系统；普通菜单资产 = **koko SFTP 网关**（连接后自动探测 koko 资产树定位该资产目录并映射语义路径；命名特殊时在 `target_hosts` 加 `"sftp_root": "模块/资产组/IP"` 显式声明；koko 模式不支持 `verify:"sha256"`，远端散列不可用）
+   - `upload` 是**写操作**：默认禁用；只有用户明确要求传文件且配置已启用（`file_transfer.upload.enabled: true` + 写路径白名单）时才可用；启用与否、白名单变更属配置修改，须先征得用户同意（同规则 6）
+   - `download` 无读白名单，但敏感路径防呆生效：内置（`/etc/shadow` 族、任意 `/.ssh/` 目录）+ `blocked_paths` 全局黑名单 + `file_transfer.download.blocked_paths` 追加；被拒即是禁止信号，**不要**换路径表达方式重试（可把需求转述给用户人工决策）
+   - `upload` 在写白名单之上同样受防呆约束（`.ssh` / shadow / `blocked_paths` 族不可覆盖）
+   - 仅单文件；**不支持**目录递归与容器内传文件；目标已存在默认拒绝，`--overwrite` / `--resume` 二选一且互斥
+   - 断点续传依赖 `.rrs-part` 半成品文件；续传前工具会校验两端字节数一致
+   - `file_transfer.verify: "sha256"` 时远端会跑 `sha256sum`（须加入 `allowed_command_prefixes`）；未开启时只核字节大小，AI 不应宣称"内容校验通过"
 
 被拒绝的尝试一样会进审计日志。
 
@@ -115,4 +139,6 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
     ...
 ```
 
-如需让审计同时记录命令输出摘要，在 `~/.rrs/config.json` 设置 `"audit": { "include_output": true }`。
+如需让审计同时记录命令输出摘要，在 `~/.rrs/config.json` 设置 `"audit": { "include_output": true }`。
+
+transmit 类调用（`upload`/`download`）同样按上述格式落审计：巡检项为"文件上传（写操作·opt-in）"/"文件下载"，备注含字节数、耗时、是否续传与校验方式（不含文件内容）。

package/src/config.js

@@ -99,6 +99,13 @@ function validateConfig(conf) {
       } else if (!profiles || !profiles[entry.profile]) {
         errors.push(`target_hosts[${ip}] 引用不存在的认证组 [${entry.profile}]`);
       }
+      if (entry.sftp_root !== undefined) {
+        if (typeof entry.sftp_root !== "string") {
+          errors.push(`target_hosts[${ip}] sftp_root 必须是字符串（koko 资产树目录，如 "Default/资产组/${ip}"）`);
+        } else if (entry.sftp_root.split("/").some((seg) => !seg || seg === "." || seg === "..")) {
+          errors.push(`target_hosts[${ip}] sftp_root 含非法路径段（空段 / "." / ".." 不允许）`);
+        }
+      }
     }
   }
 
@@ -123,6 +130,40 @@ function validateConfig(conf) {
     }
   }
 
+  const ft = conf.file_transfer;
+  if (ft !== undefined) {
+    if (!ft || typeof ft !== "object" || Array.isArray(ft)) {
+      errors.push("file_transfer 必须是对象 {upload: {enabled, allowed_path_prefixes}, download: {blocked_paths}, verify}");
+    } else {
+      if (ft.upload !== undefined) {
+        if (!ft.upload || typeof ft.upload !== "object" || Array.isArray(ft.upload)) {
+          errors.push("file_transfer.upload 必须是对象 {enabled, allowed_path_prefixes}");
+        } else {
+          if (ft.upload.enabled !== undefined && typeof ft.upload.enabled !== "boolean") {
+            errors.push(`file_transfer.upload.enabled 必须是布尔值（true=显式启用上传），当前: ${ft.upload.enabled}`);
+          }
+          if (ft.upload.allowed_path_prefixes !== undefined) {
+            if (!Array.isArray(ft.upload.allowed_path_prefixes) || !ft.upload.allowed_path_prefixes.every((x) => typeof x === "string" && x)) {
+              errors.push("file_transfer.upload.allowed_path_prefixes 必须是非空字符串数组（上传写入路径白名单）");
+            }
+          }
+        }
+      }
+      if (ft.download !== undefined) {
+        if (!ft.download || typeof ft.download !== "object" || Array.isArray(ft.download)) {
+          errors.push("file_transfer.download 必须是对象 {blocked_paths}");
+        } else if (ft.download.blocked_paths !== undefined) {
+          if (!Array.isArray(ft.download.blocked_paths) || !ft.download.blocked_paths.every((x) => typeof x === "string" && x)) {
+            errors.push("file_transfer.download.blocked_paths 必须是非空字符串数组");
+          }
+        }
+      }
+      if (ft.verify !== undefined && ft.verify !== "size" && ft.verify !== "sha256") {
+        errors.push(`file_transfer.verify 必须是 "size" 或 "sha256"，当前: ${ft.verify}`);
+      }
+    }
+  }
+
   if (errors.length) throw cfgError(errors.join("；"));
   return true;
 }
@@ -135,6 +176,8 @@ const TOOL_PURPOSE = {
   "dir": "目录结构核对",
   "bin-version": "软件版本核对",
   "exec-only": "只读命令核查",
+  "upload": "文件上传（写操作·opt-in）",
+  "download": "文件下载（内置敏感路径防呆）",
 };
 
 function describeCmd(tool, cmd) {
@@ -159,6 +202,12 @@ function describeCmd(tool, cmd) {
       const m = cmd.match(/^([^\s]+)/);
       return m ? `核对 ${m[1]} 版本信息` : "核对版本信息";
     }
+    case "upload":
+      return "上传本地文件到服务器（写操作，须配置显式启用）";
+    case "download":
+      return "下载服务器文件到本机（黑名单防呆：shadow / .ssh）";
+    case "verify-sha256":
+      return "传输完整性校验（sha256sum，只读）";
     default:
       return TOOL_PURPOSE[tool] || "只读核查";
   }

package/src/jumpshell.js

@@ -240,6 +240,47 @@ class JumpShell {
     }
   }
 
+  /**
+   * 打开 SFTP 子系统通道（文件传输专用）。两种模式：
+   * - direct: true 直连认证组 → 通道即目标机真实文件系统
+   * - 堡垒机菜单认证组 → JumpServer koko 的 SFTP 文件传输入口（资产树虚拟根），
+   *   无需菜单导航；路径映射与资产定位由 transfer 层完成。
+   * 失败通常意味着堡垒机未开放文件传输或资产未授权 SFTP，报错给出可操作指引。
+   */
+  async openSftp() {
+    if (!this.conn) throw new Error("SSH 未连接");
+    return new Promise((resolve, reject) => {
+      this.conn.sftp((err, sftp) => {
+        if (err) {
+          reject(new Error(`SFTP 子系统打开失败: ${err.message}（堡垒机需开放文件传输（koko）或走 direct 直连认证组；口令账号需有读写权限）`));
+        } else {
+          resolve(sftp);
+        }
+      });
+    });
+  }
+
+  /**
+   * 直连模式下在目标机执行单条已校验命令并收集 stdout/stderr/exit code。
+   * 用于 file_transfer.verify: "sha256" 时跑远端 sha256sum（命令须经 validateCmd 白名单校验后传入）。
+   */
+  execOnce(cmd) {
+    if (!this.conn) throw new Error("SSH 未连接");
+    return new Promise((resolve, reject) => {
+      this.conn.exec(cmd, { pty: false }, (err, stream) => {
+        if (err) return reject(mapConnError(err));
+        let out = "";
+        let errText = "";
+        stream.on("data", (d) => { out += d.toString("utf8"); });
+        if (stream.stderr) stream.stderr.on("data", (d) => { errText += d.toString("utf8"); });
+        stream.on("close", (code) => {
+          resolve({ code: code == null ? 0 : code, stdout: out, stderr: errText });
+        });
+        stream.on("error", reject);
+      });
+    });
+  }
+
   checkErr() {
     for (const p of ERR_PATTERNS) {
       if (p.test(this.err)) {

package/src/transfer.js

@@ -0,0 +1,492 @@
+"use strict";
+
+/**
+ * 文件传输（upload / download）核心逻辑，基于 SFTP 子系统（仅 direct: true 认证组）。
+ *
+ * 安全模型（用户决策记录）：
+ * - 上传是写操作：默认全禁，须配置 file_transfer.upload.enabled=true + allowed_path_prefixes
+ * - 下载不做读白名单：仅内置敏感路径防呆（shadow / .ssh 族）+ 可配置追加黑名单
+ * - 大小不设上限；存在即拒绝，--overwrite 重传 / --resume 断点续传（两 flag 互斥）
+ * - 产物先写 .rrs-part 半成品，校验通过后原子改名，正式目标出现即视为完整
+ * - 校验默认只核字节大小；verify:"sha256" 时远端跑 sha256sum（须加入 allowed_command_prefixes）
+ * - 单文件；不支持目录递归与容器内传输
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { shellQuote } = require("./jumpshell");
+const {
+  transferConf, validateRemotePath, partPath, resolveTransferFlags, computeResumeOffset, validateCmd,
+} = require("./whitelist");
+
+// 30s 无任何字节增量视为传输停滞（避免连接静默挂死）
+const STALL_TIMEOUT_MS = 30000;
+// 进度回调节流间隔
+const PROGRESS_INTERVAL_MS = 2000;
+
+function tErr(msg) {
+  return new Error(msg);
+}
+
+// ==== 通用小工具 ====
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const h = crypto.createHash("sha256");
+    const rs = fs.createReadStream(file);
+    rs.on("data", (d) => h.update(d));
+    rs.on("error", reject);
+    rs.on("end", () => resolve(h.digest("hex")));
+  });
+}
+
+function sftpStat(sftp, p, what) {
+  return new Promise((resolve, reject) => {
+    sftp.stat(p, (err, info) => {
+      if (err) {
+        // code 2 = SSH_FX_NO_SUCH_FILE
+        if (err.code === 2) resolve(null);
+        else reject(tErr(`${what || "远程 stat"} 失败: ${err.message || err.code || err}`));
+      } else {
+        resolve(info);
+      }
+    });
+  });
+}
+
+function sftpUnlink(sftp, p, what) {
+  return new Promise((resolve, reject) => {
+    sftp.unlink(p, (err) => {
+      if (err && err.code !== 2) reject(tErr(`删除${what || "远程文件"}失败 [${p}]: ${err.message || err.code}`));
+      else resolve();
+    });
+  });
+}
+
+function sftpRename(sftp, from, to) {
+  return new Promise((resolve, reject) => {
+    sftp.rename(from, to, (err) => {
+      if (err) reject(tErr(`改名 ${from} → ${to} 失败: ${err.message || err.code || err}`));
+      else resolve();
+    });
+  });
+}
+
+// ---- fast 通道（ssh2 内建的并行分块读写，吞吐比 ReadStream/WriteStream 高数倍）----
+
+const FAST_CONCURRENCY = 32;
+
+function sftpFastPut(sftp, localPath, remotePath, onProgress) {
+  return new Promise((resolve, reject) => {
+    sftp.fastPut(localPath, remotePath, {
+      concurrency: FAST_CONCURRENCY,
+      step: onProgress ? (_t, cur, total) => { try { onProgress(cur, total); } catch (_) {} } : undefined,
+    }, (err) => (err ? reject(err) : resolve()));
+  });
+}
+
+function sftpFastGet(sftp, remotePath, localPath, onProgress) {
+  return new Promise((resolve, reject) => {
+    sftp.fastGet(remotePath, localPath, {
+      concurrency: FAST_CONCURRENCY,
+      step: onProgress ? (_t, cur, total) => { try { onProgress(cur, total); } catch (_) {} } : undefined,
+    }, (err) => (err ? reject(err) : resolve()));
+  });
+}
+
+/**
+ * 带进度回调与停滞看门狗的双向泵：把 rs 泵到 ws。
+ * sentBytes() 返回当前已传字节数（调用方按方向提供）；返回 Promise，随 ws close 正常收尾。
+ */
+function pump(rs, ws, { sentBytes, onProgress, watchdogMsg }) {
+  return new Promise((resolve, reject) => {
+    let done = false;
+    let lastTickSent = -1;
+    let lastTickAt = 0;
+    let lastProgressAt = 0;
+    let lastProgressPrintAt = Date.now();
+    const finish = (fn, e) => {
+      if (done) return;
+      done = true;
+      clearInterval(timer);
+      fn(e);
+    };
+    const fail = (e) => {
+      finish(reject, e);
+      try { rs.destroy(); } catch (_) {}
+      try { ws.destroy(); } catch (_) {}
+    };
+    const tick = () => {
+      const sent = sentBytes();
+      const now = Date.now();
+      if (lastTickSent >= 0 && now - lastTickAt > STALL_TIMEOUT_MS && sent === lastTickSent) {
+        fail(tErr(`传输停滞超时（${STALL_TIMEOUT_MS / 1000}s 无数据增量），已中止`));
+        return;
+      }
+      lastTickSent = sent;
+      lastTickAt = now;
+      if (onProgress && sent !== lastProgressAt && now - lastProgressPrintAt > PROGRESS_INTERVAL_MS) {
+        lastProgressAt = sent;
+        lastProgressPrintAt = now;
+        onProgress(sent);
+      }
+    };
+    const timer = setInterval(tick, 1000);
+    rs.on("error", fail);
+    ws.on("error", fail);
+    ws.on("close", () => { if (!done) { done = true; clearInterval(timer); resolve(); } });
+    rs.pipe(ws);
+  });
+}
+
+/**
+ * 远端 sha256（file_transfer.verify="sha256" 时使用）。
+ * 命令必须先过 validateCmd 白名单（要求 allowed_command_prefixes 含 "sha256sum "），
+ * 失败时给出可操作的指引，绝不静默绕过白名单。
+ */
+function remoteSha256(shell, conf, p) {
+  let cmd;
+  try {
+    cmd = validateCmd(`sha256sum ${shellQuote(p)}`, conf);
+  } catch (e) {
+    throw tErr(
+      `${e.message} — file_transfer.verify="sha256" 需要把 "sha256sum " 加入 allowed_command_prefixes；` +
+      `敏感路径（shadow/密钥等）不在散列校验范围`
+    );
+  }
+  return shell.execOnce(cmd).then(({ code, stdout, stderr }) => {
+    if (code !== 0) {
+      throw tErr(`远端 sha256sum 执行失败（exit ${code}）: ${(stderr || stdout).trim().slice(0, 300)}`);
+    }
+    const m = stdout.match(/^([0-9a-fA-F]{64})\s/m);
+    if (!m) throw tErr("远端 sha256sum 输出无法解析");
+    return m[1].toLowerCase();
+  });
+}
+
+// ==== 前置校验（不经网络）====
+
+// koko 资产树路径归一化（显式 sftp_root）：去首尾 /，禁止空段/./.. 与控制字符；空值 → 交给自动探测
+function normalizeSftpRoot(raw) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim().replace(/^\/+|\/+$/g, "");
+  if (!trimmed) return null;
+  for (const seg of trimmed.split("/")) {
+    if (!seg || seg === "." || seg === "..") {
+      throw tErr(`配置错误: target_hosts.sftp_root 含非法路径段 "${seg}"（空段 / "." / ".." 不允许）[${raw}]`);
+    }
+    if (/[\x00-\x1f]/.test(seg)) {
+      throw tErr(`配置错误: target_hosts.sftp_root 含控制字符 [${raw}]`);
+    }
+  }
+  return trimmed;
+}
+
+/**
+ * 传输意图校验：开关/白名单/本地文件/远程路径/flag 互斥。
+ * 任何失败抛"拒绝"类错误（调用方按退出码 2 处理并审计）。
+ * 返回 {tool, flags, tc, mode: "direct"|"koko", sftpRoot, local, remote, total}。
+ */
+function prepareTransfer(conf, host, tool, args = {}) {
+  const flags = resolveTransferFlags(args);
+  const tc = transferConf(conf);
+  // 连接模式判定：direct → 通道即目标机真实文件系统；菜单资产 → koko 资产树虚拟根
+  const entry = (conf.target_hosts || {})[host] || {};
+  const profileEntry = (conf.auth_profiles || {})[entry.profile] || {};
+  const isDirect = profileEntry.direct === true;
+  if (tool === "upload") {
+    if (!tc.upload.enabled) {
+      throw tErr(
+        '拒绝: 文件上传默认禁用（安全默认）。请在本机配置文件中增加 ' +
+        '"file_transfer": {"upload": {"enabled": true, "allowed_path_prefixes": ["/目录/"]}} 后重试'
+      );
+    }
+    if (!args.local) throw tErr("拒绝: 缺少本地文件路径（第一个参数）");
+    const local = path.resolve(args.local);
+    let st;
+    try { st = fs.statSync(local); } catch (_) {
+      throw tErr(`拒绝: 本地文件不存在 [${local}]`);
+    }
+    if (!st.isFile()) throw tErr(`拒绝: 本地路径不是文件 [${local}]`);
+    const remote = validateRemotePath(args.remote, "upload", conf);
+    if (!isDirect && tc.verify === "sha256") {
+      throw tErr('拒绝: 菜单资产（koko 模式）暂不支持 verify:"sha256"（远端 sha256sum 需直达 exec 通道）；请将 file_transfer.verify 设为 "size"');
+    }
+    return { tool, host, flags, tc, mode: isDirect ? "direct" : "koko", sftpRoot: isDirect ? null : normalizeSftpRoot(entry.sftp_root), local, remote, total: st.size };
+  }
+  if (tool === "download") {
+    if (!args.remote) throw tErr("拒绝: 缺少远程文件路径（第一个参数）");
+    const remote = validateRemotePath(args.remote, "download", conf);
+    if (!args.local) throw tErr("拒绝: 缺少本地保存路径（第二个参数）");
+    const local = path.resolve(args.local);
+    // 本地正式目标已存在属"拒绝"级冲突（无需连接即可判定）；--resume 只接半成品，不视为冲突
+    let formal = null;
+    try { formal = fs.statSync(local); } catch (_) {}
+    if (formal && !flags.resume && !flags.overwrite) {
+      throw tErr(`拒绝: 本地目标已存在 [${local}]。加 --overwrite 重传，或 --resume 续传半成品`);
+    }
+    // 本地半成品已存在且未给 --resume/--overwrite → 同为拒绝级（引导用户明确续传或重传意图）
+    let partL = null;
+    try { partL = fs.statSync(partPath(local)); } catch (_) {}
+    if (partL && !flags.resume && !flags.overwrite) {
+      throw tErr(`拒绝: 检测到未完成的传输 ${partPath(local)}。加 --resume 续传，或 --overwrite 删除后重传`);
+    }
+    if (!isDirect && tc.verify === "sha256") {
+      throw tErr('拒绝: 菜单资产（koko 模式）暂不支持 verify:"sha256"（远端 sha256sum 需直达 exec 通道）；请将 file_transfer.verify 设为 "size"');
+    }
+    return { tool, host, flags, tc, mode: isDirect ? "direct" : "koko", sftpRoot: isDirect ? null : normalizeSftpRoot(entry.sftp_root), remote, local };
+  }
+  throw tErr(`未知传输方向 [${tool}]`);
+}
+
+// ==== koko 资产树定位（菜单资产模式专用）====
+
+/**
+ * 在 koko 资产树虚拟根中定位目标资产的目录路径（自动探测，DFS 深度 ≤3 层）。
+ * 返回 "/Default/资产组/资产IP" 形态；命中多个 → 报错要求显式 sftp_root；未命中 → 报错引导配置。
+ */
+function resolveKokoBase(sftp, host, explicitRoot) {
+  if (explicitRoot) return Promise.resolve(`/${explicitRoot}`);
+  const hits = [];
+  const walk = (dir, remainingDepth) => new Promise((resolveWalk) => {
+    sftp.readdir(dir, async (err, list) => {
+      if (err) return resolveWalk(); // 不可读子树静默跳过（收藏夹等）
+      const tasks = [];
+      for (const x of list) {
+        if (!x.longname.startsWith("d")) continue;
+        const full = `${dir.replace(/\/+$/, "")}/${x.filename}`;
+        if (x.filename === host) { hits.push(full); continue; }
+        if (remainingDepth > 0) tasks.push(walk(full, remainingDepth - 1));
+      }
+      if (tasks.length) await Promise.all(tasks);
+      resolveWalk();
+    });
+  });
+  return walk("/", 2).then(() => {
+    if (hits.length > 1) {
+      throw tErr(`拒绝: 资产 [${host}] 在 koko 资产树命中多个目录（${hits.join("、")}）；请在 target_hosts[${host}] 增加 "sftp_root" 显式声明资产目录`);
+    }
+    if (hits.length === 0) {
+      throw tErr(`拒绝: 自动探测未在 koko 资产树中找到资产目录 [${host}]（已扫描根下两层）。请在 target_hosts[${host}] 增加 "sftp_root": "资产模块/资产组/${host}" 显式声明`);
+    }
+    return hits[0];
+  });
+}
+
+// ==== 上传 ====
+
+async function uploadFile(shell, conf, plan, onProgress) {
+  const startedAt = Date.now();
+  const { flags, tc } = plan;
+  const local = plan.local;
+  const remote = plan.remote;
+  const part = partPath(remote);
+  const st = fs.statSync(local);
+  const total = st.size;
+
+  const sftp = await shell.openSftp();
+  // direct 通道 → base=""（语义路径即真实路径）；koko 通道 → base=资产树目录（语义路径映射进去）
+  const base = plan.mode === "direct" ? "" : await resolveKokoBase(sftp, plan.host, plan.sftpRoot);
+  const P = (semanticAbs) => base ? base + semanticAbs : semanticAbs;
+  const rRemote = P(remote);
+  const rPart = P(part);
+
+  // 冲突裁决：正式目标 / 半成品 / flags
+  const remoteInfo = await sftpStat(sftp, rRemote, "远程目标");
+  if (remoteInfo) {
+    if (flags.resume) {
+      throw tErr(`拒绝: --resume 只用于续传 ${part} 半成品；远程正式目标已存在 [${remote}]（覆盖请用 --overwrite）`);
+    }
+    if (!flags.overwrite) {
+      throw tErr(`拒绝: 远程目标已存在 [${remote}]。加 --overwrite 重传，或 --resume 续传半成品`);
+    }
+    await sftpUnlink(sftp, rRemote, "远程正式目标");
+  }
+
+  const partInfo = await sftpStat(sftp, rPart, "半成品");
+  let offset = 0;
+  let resumed = false;
+  if (partInfo) {
+    if (!flags.overwrite && !flags.resume) {
+      throw tErr(`拒绝: 检测到未完成的传输 ${part}。加 --resume 续传，或 --overwrite 删除后重传`);
+    }
+    if (flags.overwrite) {
+      await sftpUnlink(sftp, rPart, "半成品");
+    } else {
+      const r = computeResumeOffset(partInfo.size, total);
+      if (r.mode === "ready") {
+        // 半成品与源大小一致：可选 sha 校验后直接改名（免重传）
+        if (tc.verify === "sha256") {
+          const localSha = await sha256File(local);
+          const remoteSha = await remoteSha256(shell, conf, part);
+          if (remoteSha !== localSha) {
+            await sftpUnlink(sftp, rPart, "不一致的半成品");
+            throw tErr(`校验失败: 半成品 sha256 与本地源不一致，已删除 ${part}（请用 --overwrite 重传）`);
+          }
+        }
+        await sftpRename(sftp, rPart, rRemote);
+        return { bytes: total, resumed: false, elapsedMs: Date.now() - startedAt, verify: tc.verify };
+      }
+      if (r.mode === "restart") {
+        await sftpUnlink(sftp, rPart, "与源大小不符的半成品");
+      } else {
+        offset = r.offset;
+        resumed = true;
+      }
+    }
+  }
+
+  let localSha = null;
+  if (tc.verify === "sha256") {
+    localSha = await sha256File(local);
+  }
+
+  // 推送：offset===0 走 fastPut（并行分块，吞吐比 stream 高数倍），续传用 stream 管道定位追加
+  await (async () => {
+    if (offset === 0 && total > 0) {
+      try {
+        await sftpFastPut(sftp, local, rPart, onProgress);
+        return;
+      } catch (e) {
+        // fastPut 失败（如非 OpenSSH sftp-server）：回退 stream 管道，保可用性
+      }
+    }
+    const rs = fs.createReadStream(local, { start: offset });
+    const ws = sftp.createWriteStream(rPart, offset > 0 ? { flags: "r+", start: offset } : { flags: "w" });
+    await pump(rs, ws, {
+      sentBytes: () => offset + rs.bytesRead,
+      onProgress: onProgress ? (sent) => onProgress(sent, total) : null,
+      watchdogMsg: "上传",
+    });
+  })();
+
+  // 完整性校验（对 part 散列，改名字节即与校验字节一致）
+  if (tc.verify === "sha256") {
+    const remoteSha = await remoteSha256(shell, conf, part);
+    if (remoteSha !== localSha) {
+      await sftpUnlink(sftp, rPart, "校验失败的半成品");
+      throw tErr(`校验失败: 上传内容 sha256 与本地源不一致（网络或源文件变动），已删除半成品`);
+    }
+  }
+
+  await sftpRename(sftp, rPart, rRemote);
+  return { bytes: total, resumed, via: plan.mode, elapsedMs: Date.now() - startedAt, verify: tc.verify };
+}
+
+// ==== 下载 ====
+
+async function downloadFile(shell, conf, plan, onProgress) {
+  const startedAt = Date.now();
+  const { flags, tc } = plan;
+  const remote = plan.remote;
+  const local = plan.local;
+  const part = partPath(local);
+
+  const dir = path.dirname(local);
+  if (!fs.existsSync(dir)) throw tErr(`拒绝: 本地目标目录不存在 [${dir}]`);
+
+  const sftp = await shell.openSftp();
+  const base = plan.mode === "direct" ? "" : await resolveKokoBase(sftp, plan.host, plan.sftpRoot);
+  const P = (semanticAbs) => base ? base + semanticAbs : semanticAbs;
+  const rRemote = P(remote);
+
+  const remoteInfo = await sftpStat(sftp, rRemote, "远程文件");
+  if (!remoteInfo) throw tErr(`拒绝: 远程文件不存在或不可读 [${remote}]`);
+  if (remoteInfo.isDirectory()) throw tErr(`拒绝: 远程目标是目录，传输仅支持单文件 [${remote}]`);
+  const total = Number(remoteInfo.size || 0);
+
+  // 本地正式目标冲突裁决
+  let localFormal = null;
+  try { localFormal = fs.statSync(local); } catch (_) {}
+  if (localFormal) {
+    if (flags.resume) {
+      throw tErr(`拒绝: --resume 只用于续传 ${part} 半成品；本地正式目标已存在 [${local}]（覆盖请用 --overwrite）`);
+    }
+    if (!flags.overwrite) {
+      throw tErr(`拒绝: 本地目标已存在 [${local}]。加 --overwrite 重传，或 --resume 续传半成品`);
+    }
+    fs.unlinkSync(local);
+  }
+
+  // 本地半成品裁决
+  let partSt = null;
+  try { partSt = fs.statSync(part); } catch (_) {}
+  let offset = 0;
+  let resumed = false;
+  if (partSt) {
+    if (!flags.overwrite && !flags.resume) {
+      throw tErr(`拒绝: 检测到未完成的传输 ${part}。加 --resume 续传，或 --overwrite 删除后重传`);
+    }
+    if (flags.overwrite) {
+      fs.unlinkSync(part);
+    } else {
+      const r = computeResumeOffset(partSt.size, total);
+      if (r.mode === "ready") {
+        if (tc.verify === "sha256") {
+          const remoteSha = await remoteSha256(shell, conf, remote);
+          const localSha = await sha256File(part);
+          if (remoteSha !== localSha) {
+            fs.unlinkSync(part);
+            throw tErr(`校验失败: 半成品 sha256 与远端文件不一致，已删除 ${part}（请用 --overwrite 重传）`);
+          }
+        }
+        fs.renameSync(part, local);
+        return { bytes: total, resumed: false, elapsedMs: Date.now() - startedAt, verify: tc.verify };
+      }
+      if (r.mode === "restart") {
+        fs.unlinkSync(part);
+      } else {
+        offset = r.offset;
+        resumed = true;
+      }
+    }
+  }
+
+  // 远端整体散列（可选）：与下载内容比对，可捕获"传输期间远端文件被改"
+  let remoteSha = null;
+  if (tc.verify === "sha256") remoteSha = await remoteSha256(shell, conf, remote);
+
+  // 拉取：offset===0 走 fastGet（并行分块，吞吐比 stream 高数倍），续传用 stream 管道追加
+  await (async () => {
+    if (offset === 0 && total > 0) {
+      try {
+        await sftpFastGet(sftp, rRemote, part, onProgress);
+        return;
+      } catch (e) {
+        // fastGet 失败（如非 OpenSSH sftp-server）：回退 stream 管道，保可用性
+      }
+    }
+    const rs = sftp.createReadStream(rRemote, offset > 0 ? { start: offset } : { flags: "r" });
+    const ws = fs.createWriteStream(part, resumed ? { flags: "a" } : { flags: "w" });
+    await pump(rs, ws, {
+      sentBytes: () => offset + ws.bytesWritten,
+      onProgress: onProgress ? (sent) => onProgress(sent, total) : null,
+      watchdogMsg: "下载",
+    });
+  })();
+
+  // 完整性校验
+  if (tc.verify === "sha256") {
+    const localSha = await sha256File(part);
+    if (localSha !== remoteSha) {
+      fs.unlinkSync(part);
+      throw tErr(`校验失败: 下载内容 sha256 与远端文件不一致（传输期间文件可能被改），已删除半成品`);
+    }
+  }
+
+  fs.renameSync(part, local);
+  return { bytes: total, resumed, via: plan.mode, elapsedMs: Date.now() - startedAt, verify: tc.verify };
+}
+
+module.exports = {
+  prepareTransfer,
+  uploadFile,
+  downloadFile,
+  // 仅供测试与进度展示
+  pump,
+  remoteSha256,
+  sha256File,
+  normalizeSftpRoot,
+  resolveKokoBase,
+};

package/src/whitelist.js

@@ -224,6 +224,107 @@ function validateBin(bin, conf) {
   return b;
 }
 
+// ==== 文件传输（upload / download）校验 ====
+// 上传是写操作：默认全禁，须显式 file_transfer.upload.enabled=true 且配置 allowed_path_prefixes。
+// 下载不做读白名单（决策：放开），仅保留内置敏感路径防呆（shadow / .ssh 目录族），配置可追加黑名单。
+
+function transferConf(conf) {
+  const ft = (conf && conf.file_transfer) || {};
+  const up = ft.upload || {};
+  const dl = ft.download || {};
+  return {
+    upload: {
+      enabled: up.enabled === true,
+      allowed_path_prefixes: Array.isArray(up.allowed_path_prefixes)
+        ? up.allowed_path_prefixes.filter((x) => typeof x === "string" && x)
+        : [],
+    },
+    download: {
+      blocked_paths: Array.isArray(dl.blocked_paths)
+        ? dl.blocked_paths.filter((x) => typeof x === "string" && x)
+        : [],
+    },
+    verify: ft.verify === "sha256" ? "sha256" : "size",
+  };
+}
+
+// SFTP 路径本身是纯数据，但会进入审计日志与（verify:sha256 时）远端 sha256sum 命令行，
+// 因此拒绝控制字符与 shell 元字符；空格等常规字符允许（拼接处一律 shellQuote）。
+const REMOTE_PATH_RE = /^[A-Za-z0-9 ._\-/:@+=,%()]+$/;
+
+// 传输内置防呆（读/写共用）：shadow 族文件 + 任意 .ssh 目录（含 /root/.ssh、/home/*/.ssh），不可配置关闭。
+// 下载拒绝 = 不允许拉取；上传拒绝 = 不允许覆盖（防误写密钥）。
+function isSensitivePath(p, extraBlocked) {
+  if (p.startsWith("/etc/shadow")) return true;
+  if (p.startsWith("/etc/ssh/")) return true;
+  if (p.includes("/.ssh/") || p.endsWith("/.ssh")) return true;
+  for (const sp of extraBlocked || []) {
+    if (p.startsWith(sp)) return true;
+  }
+  return false;
+}
+const isDownloadBlocked = isSensitivePath; // 兼容旧名
+
+/**
+ * 校验传输远程路径。mode: "upload"（须命中上传白名单）| "download"（仅黑名单防呆）。
+ * 黑名单 = 内置防呆（shadow/.ssh 族）⊕ file_transfer.download.blocked_paths ⊕ 全局 blocked_paths
+ * （读白名单放开不等于敏感黑名单放开——用户手工维护的 blocked_paths 对传输同样生效）。
+ * 返回 posix normalize 后的路径（/a/./b、/a//b 归一后再比对，防绕过）。
+ */
+function validateRemotePath(raw, mode, conf) {
+  const s = String(raw || "").trim();
+  if (!s.startsWith("/")) throw new Error(`拒绝: 传输路径必须是绝对路径 [${s}]`);
+  if (!REMOTE_PATH_RE.test(s)) {
+    throw new Error(`拒绝: 传输路径含非法字符（控制字符 / shell 元字符）[${s}]`);
+  }
+  const p = path.posix.normalize(s);
+  const tc = transferConf(conf);
+  const extraBlocked = [
+    ...(tc.download.blocked_paths || []),
+    ...(Array.isArray(conf.blocked_paths) ? conf.blocked_paths : []),
+  ];
+  if (mode === "upload") {
+    const prefixes = tc.upload.allowed_path_prefixes;
+    if (!prefixes.length) {
+      throw new Error(`拒绝: 上传路径白名单未配置（file_transfer.upload.allowed_path_prefixes），未配置时上传一律拒绝 [${p}]`);
+    }
+    if (!prefixes.some((pfx) => p.startsWith(pfx))) {
+      throw new Error(`拒绝: 上传路径不在 file_transfer.upload.allowed_path_prefixes 白名单 [${p}]`);
+    }
+    // 上传内置防呆：即使命中写白名单，也不允许覆盖 .ssh / shadow / blocked_paths 族文件
+    if (isSensitivePath(p, extraBlocked)) {
+      throw new Error(`拒绝: 上传命中敏感路径保护 [${p}]（防呆：shadow / .ssh / blocked_paths 族不可覆盖）`);
+    }
+  } else {
+    if (isSensitivePath(p, extraBlocked)) {
+      throw new Error(`拒绝: 下载命中敏感路径保护 [${p}]（内置防呆 shadow/.ssh + 配置黑名单；可用 file_transfer.download.blocked_paths 追加）`);
+    }
+  }
+  return p;
+}
+
+// 半成品临时文件名：传输完成才原子改名，正式目标出现即视为完整文件
+function partPath(target) {
+  return `${target}.rrs-part`;
+}
+
+/** --overwrite / --resume 解析与互斥校验 */
+function resolveTransferFlags(opts = {}) {
+  const overwrite = opts.overwrite === true;
+  const resume = opts.resume === true;
+  if (overwrite && resume) {
+    throw new Error("拒绝: --overwrite 与 --resume 互斥（--overwrite 从头重传；--resume 仅续传半成品）");
+  }
+  return { overwrite, resume };
+}
+
+/** 断点续传决策：半成品字节与目标大小的三种关系 → 不传/续传/重来 */
+function computeResumeOffset(partSize, total) {
+  if (partSize === total) return { mode: "ready", offset: total }; // 传完整但未改名，直接 rename
+  if (partSize > total) return { mode: "restart", offset: 0 };    // 源文件已变更，删除半成品重传
+  return { mode: "continue", offset: partSize };
+}
+
 module.exports = {
   validateCmd,
   validatePath,
@@ -232,4 +333,10 @@ module.exports = {
   validateBin,
   containerExecConf,
   DEFAULT_CONTAINER_EXEC,
+  transferConf,
+  validateRemotePath,
+  isSensitivePath,
+  partPath,
+  resolveTransferFlags,
+  computeResumeOffset,
 };