@zicolasjac-ai/remote-readonly-ssh 1.4.1 → 1.4.3

package/README.md

@@ -25,7 +25,7 @@ npx 会自动拉取最新版本、进入初始化向导，依次询问：
 1. 是否覆盖已有 `~/.rrs/config.json`（首次安装跳过此步）
 2. **认证组**：堡垒机主机 / 端口 / 用户名 / 认证模式（SSH 密钥或密码）/ 凭据；可配置多个认证组
 3. 目标主机白名单（每行 `ip=堡垒机搜索关键字`），并为每台主机指定归属的认证组（多台主机可共用同一组）
-4. 是否把 SKILL.md 安装到 opencode / Claude Code / Cursor 等 AI 助手
+4. 是否把 SKILL.md 安装到 opencode / Claude Code / Cursor 等 AI 助手（安装命令的 postinstall 已自动分发，此步幂等可确认）
 
 向导结束后 `~/.rrs/config.json` 已就位、`~/.rrs/audit.log` 已建好、AI skill 已分发。直接试跑：
 
@@ -38,7 +38,7 @@ npx -y @zicolasjac-ai/remote-readonly-ssh@latest sys-info --json
 每次调用都 `npx` 较慢（需下载/缓存）。如果要把 `rrs` 作为日常命令长期使用：
 
 ```bash
-npm install -g @zicolasjac-ai/remote-readonly-ssh
+npm install -g @zicolasjac-ai/remote-readonly-ssh   # postinstall 自动分发 AI skill
 rrs init                # TTY 下仍是交互向导；非交互环境只生成配置模板
 rrs sys-info --json     # 直接用 rrs 前缀
 ```
@@ -68,7 +68,7 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 | `dir <path>` | 列目录（同路径白名单） |
 | `bin-version <bin>` | 查二进制版本/编译参数（二进制白名单） |
 | `exec-only <cmd>` | 通用只读命令（前缀白名单 + 禁止模式） |
-| `download <远程> <本地>` | 下载单文件（SFTP，仅 direct 资产；shadow/.ssh 类路径防呆） |
+| `download <远程> <本地>` | 下载单文件（SFTP：direct 直连或堡垒机 koko 网关；shadow/.ssh 类路径防呆） |
 | `upload <本地> <远程>` | 上传单文件（写操作，**默认禁用**：须 `file_transfer.upload.enabled=true` + 独立写路径白名单） |
 
 ## 配置
@@ -78,7 +78,7 @@ 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...） |
@@ -99,10 +99,14 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 
 **硬约束**：
 
-- **仅支持 `direct: true` 直连认证组**。走堡垒机菜单的资产没有指向目标资产的 SFTP 通路，调用会被直接拒绝（这是防"误写到堡垒机文件系统"的保护，不是缺陷）；如需传输，请为该主机增加一个 `direct: true` 的专属认证组。
-- **大小不设上限**（1GB 级为常规场景），多线路网络下观察 `--` 进度提示即可判断耗时。
+- **双通道**：
+  - `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 模式同样生效）；上传/下载不受 `(语义路径) 之外的资产树越界`——映射后被强制限定在该资产目录内。
 
 **下载**（默认可用）：
 
@@ -141,7 +145,7 @@ rrs upload "E:\deploy\nginx.conf" /opt/upload/nginx.conf --host 10.0.0.2 --json
 
 ## Agent Skills
 
-本工具附带一份 `SKILL.md`，教 AI 助手何时用、怎么用 `rrs`。安装后用 `rrs setup skills` 一键分发到各 agent 的 skills 目录：
+本工具附带一份 `SKILL.md`，教 AI 助手何时用、怎么用 `rrs`。**`npm install` 时 postinstall 会自动分发**（agents 实体 + opencode/claude/qoder 软链接），无需手工执行；`rrs setup skills` 保留为手工重装 / 只装部分 agent 的方式：
 
 | `--agent` | 写入方式 | 路径 |
 |-----------|----------|------|
@@ -151,17 +155,16 @@ rrs upload "E:\deploy\nginx.conf" /opt/upload/nginx.conf --host 10.0.0.2 --json
 | `qoder` | 软链接 → agents | `~/.qoder/skills/remote-readonly-ssh/SKILL.md` |
 | `all`（默认） | 实体 + 上述 3 个软链接 | 一行命令装齐 |
 
-`rrs setup skills` 默认 `agent=all`（不询问，直接装），输出一行简明提示：
+`rrs setup skills` 默认 `agent=all`（不询问，直接装；postinstall 自动分发亦采用此默认），输出一行简明提示：
 
 ```
 rrs skill 已安装: agents (实体), opencode/claude/qoder (软链接)
 ```
 
-> **Windows 注意**：普通用户缺少 `SeCreateSymbolicLinkPrivilege`，软链接创建会被 OS 拒绝；rrs 会自动 fallback 为复制，并提示"Windows 已 fallback 为复制（请开启开发者模式以启用真软链接）"。开启开发者模式后重新跑 `rrs setup skills` 即可使用真软链接。
+> **Windows 注意**：普通用户缺少 `SeCreateSymbolicLinkPrivilege`，软链接创建会被 OS 拒绝；rrs 会自动 fallback 为复制，并提示"Windows 已 fallback 为复制（请开启开发者模式以启用真软链接）"。开启开发者模式后重新跑 `rrs setup skills`（或重装包）即可使用真软链接。
 
 ```bash
-rrs setup skills                            # 一行命令装齐（实体 + 3 个软链接）
-npx -y @zicolasjac-ai/remote-readonly-ssh@latest setup skills   # 全局未装时用 npx
+rrs setup skills                            # 手工重装（正常情况 npm install 已自动分发）
 rrs setup skills --agent opencode           # 只装 opencode 链接（agents 实体也自动建）
 rrs setup skills --agent qoder              # 只装 qoder 链接
 rrs setup skills --dry-run                  # 仅预览将要创建的目标

package/bin/postinstall.js

@@ -7,7 +7,28 @@ const path = require("path");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 
+/**
+ * npm 安装完成后自动把 SKILL.md 分发到各 AI 助手的 skills 目录（agents 实体 + 软链接），
+ * 使 "npm install -g @latest" 一步完成 CLI 与 AI skill 的同步升级；失败不阻塞安装。
+ * 幂等：重复安装/升级会重建实体与软链（Windows 无符号链接权限时自动退化为复制）。
+ */
+function autoInstallSkills() {
+  try {
+    const results = setupSkill.install(PACKAGE_ROOT, { agent: "all" });
+    const canonical = results.find((r) => r.agent === "agents");
+    const links = results.filter((r) => r.agent !== "agents");
+    const anyFallback = links.some((r) => r.fallback);
+    const names = links.map((r) => r.agent).join("/");
+    const done = canonical && links.length ? `agents (实体), ${names} (软链接)` : canonical ? "agents (实体)" : names;
+    console.log(`rrs AI skill 已同步: ${done}${anyFallback ? " — Windows 已自动 fallback 为复制（开启开发者模式可获得真软链接）" : ""}`);
+  } catch (e) {
+    console.error(`[rrs postinstall] AI skill 自动分发失败（不影响 CLI 使用）: ${e.message}`);
+    console.error("可稍后手动执行: rrs setup skills");
+  }
+}
+
 (async () => {
+  autoInstallSkills();
   const tty = process.stdin.isTTY && process.stdout.isTTY;
   if (tty) {
     try {
@@ -19,9 +40,9 @@ const PACKAGE_ROOT = path.join(__dirname, "..");
   } else {
     console.log("");
     console.log("rrs 安装完成。下一步:");
-    console.log("  rrs init                # 交互式初始化 + 安装 AI skill（推荐）");
-    console.log("  rrs setup skills        # 仅安装 AI skill 到 opencode / claude 等");
+    console.log("  rrs init                # 交互式初始化配置（首次安装必跑；向导不再询问 skill 安装，见上）");
+    console.log("  rrs setup skills --agent opencode   # 如需只分发部分 AI 助手（默认已全量分发）");
     console.log("  rrs list-tools          # 查看白名单与配置");
     console.log("");
   }
-})();
+})();

package/bin/rrs.js

@@ -11,7 +11,6 @@ const {
 const setupSkill = require("../src/setup");
 const initWizard = require("../src/init");
 const transfer = require("../src/transfer");
-const { resolveProfile } = require("../src/jumpshell");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 
@@ -259,11 +258,6 @@ async function runTransfer(opts, conf) {
       ? `upload ${args.local || "(无)"} -> ${args.remote || "(无)"}`
       : `download ${args.remote || "(无)"} -> ${args.local || "(无)"}`];
     plan = transfer.prepareTransfer(conf, host, tool, args);
-    const entry = (conf.target_hosts || {})[host] || {};
-    const profile = resolveProfile(conf, host);
-    if (profile.direct !== true) {
-      throw new Error(`拒绝: 文件传输仅支持 direct: true 认证组；主机 [${host}] 当前认证组 [${entry.profile || "(未知)"}] 未启用直连。请在 auth_profiles 为该主机增加 direct: true 的专属认证组`);
-    }
   } catch (e) {
     audit(conf, tool, host || "", cmds, false, e.message);
     emitResult(opts, { ok: false, tool, host: host || "", error: e.message, kind: "拒绝" });
@@ -283,16 +277,17 @@ async function runTransfer(opts, conf) {
 
     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}${verifyTag}`;
+    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}`);
+      `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,
+      overwrite: plan.flags.overwrite, via: plan.mode,
       output: text,
     });
   } catch (e) {

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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "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,6 +1,6 @@
 ---
 name: remote-readonly-ssh
-description: 通过 JumpServer 堡垒机对服务器做白名单强制的运维查询与单文件传输（sys-info / proc / ports / dir / read-file / bin-version / exec-only / download / upload）。命令默认只读、前缀白名单 + 禁止模式 + 路径白名单 + 主机白名单多层校验；下载自带敏感路径防呆，上传默认禁用需配置显式开启且仅支持 direct 直连资产。每次调用（含被拒绝的）都写入本地审计日志。AI Agent 需要查看服务器现状或与 direct 服务器互传单文件时调用此 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:
@@ -11,7 +11,7 @@ metadata:
 
 # rrs — Read-Only SSH Inspection & File Transfer Skill
 
-`rrs`（remote-read-only-ssh）是一个面向 AI Agent 的只读 SSH 运维工具。它通过 JumpServer 风格的堡垒机在白名单目标主机上执行**白名单强制**的只读查询，并支持与 `direct: true` 直连资产做单文件上传/下载（SFTP）。每次调用（含被拒绝的）都写入本地审计日志。
+`rrs`（remote-read-only-ssh）是一个面向 AI Agent 的只读 SSH 运维工具。它通过 JumpServer 风格的堡垒机在白名单目标主机上执行**白名单强制**的只读查询，并支持对白名单主机做单文件上传/下载（SFTP）：`direct: true` 直连资产走真实文件系统，普通菜单资产走 JumpServer koko 的 SFTP 文件传输入口（资产树自动探测或 `sftp_root` 显式声明）。每次调用（含被拒绝的）都写入本地审计日志。
 
 安全定位：**命令查询技术上零写能力**；文件下载原则上不写远端；**文件上传是唯一写远程状态的能力**——默认禁用，须在本机配置显式开启 + 写路径白名单。
 
@@ -34,11 +34,10 @@ metadata:
 ## Setup（用户一次性）
 
 ```bash
-npm install -g @zicolasjac-ai/remote-readonly-ssh
-rrs init          # 生成配置模板 ~/.rrs/config.json
+npm install -g @zicolasjac-ai/remote-readonly-ssh   # postinstall 自动把 SKILL.md 分发到 opencode / claude / agents 等目录
+rrs init          # 生成配置模板 ~/.rrs/config.json（TTY 下为交互向导）
 # 编辑配置: auth_profiles（认证组，key/password 两种模式，可多个；direct:true 表示跳过堡垒机菜单直连裸机）
-#           target_hosts（IP → 认证组+搜索关键字，多 IP 可共用一组）
-rrs setup skills  # 把本 skill 安装到 opencode / claude / agents 等目录
+#           target_hosts（IP → 认证组+搜索关键字，多 IP 可共用一组；可选 sftp_root 声明 koko 资产树目录）
 ```
 
 ## Usage
@@ -114,7 +113,7 @@ rrs upload <本地绝对路径> <远程绝对路径> [--overwrite|--resume] [--h
 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` 直连认证组；菜单模式资产一律拒绝（不要为传输把读文件当替代方案混传）
+   - 通道：`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` 族不可覆盖）

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 含非法路径段（空段 / "." / ".." 不允许）`);
+        }
+      }
     }
   }
 

package/src/jumpshell.js

@@ -241,22 +241,18 @@ class JumpShell {
   }
 
   /**
-   * 打开 SFTP 子系统通道（文件传输专用）。仅支持 direct: true 直连认证组：
-   * 堡垒机菜单模式下没有指向目标资产的 SFTP 通路（菜单会话只是 PTY），
-   * 若堡垒机自身恰好提供 SFTP 子系统，路径语义也指向堡垒机而非目标资产，属错位写入，必须拒绝。
+   * 打开 SFTP 子系统通道（文件传输专用）。两种模式：
+   * - direct: true 直连认证组 → 通道即目标机真实文件系统
+   * - 堡垒机菜单认证组 → JumpServer koko 的 SFTP 文件传输入口（资产树虚拟根），
+   *   无需菜单导航；路径映射与资产定位由 transfer 层完成。
+   * 失败通常意味着堡垒机未开放文件传输或资产未授权 SFTP，报错给出可操作指引。
    */
   async openSftp() {
-    if (this.direct !== true) {
-      throw new Error(
-        `文件传输仅支持 direct: true 认证组（当前主机 ${this.host} 未启用直连）。` +
-        `请在 auth_profiles 中为该主机增加一个 direct: true 的专属认证组，并在 target_hosts 引用它`
-      );
-    }
     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}（目标机需运行 OpenSSH sftp-server；口令账号需有读写权限）`));
+          reject(new Error(`SFTP 子系统打开失败: ${err.message}（堡垒机需开放文件传输（koko）或走 direct 直连认证组；口令账号需有读写权限）`));
         } else {
           resolve(sftp);
         }

package/src/transfer.js

@@ -167,14 +167,34 @@ function remoteSha256(shell, conf, p) {
 
 // ==== 前置校验（不经网络）====
 
+// 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, local, remote, total}。
+ * 返回 {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(
@@ -190,7 +210,10 @@ function prepareTransfer(conf, host, tool, args = {}) {
     }
     if (!st.isFile()) throw tErr(`拒绝: 本地路径不是文件 [${local}]`);
     const remote = validateRemotePath(args.remote, "upload", conf);
-    return { tool, flags, tc, local, remote, total: st.size };
+    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("拒绝: 缺少远程文件路径（第一个参数）");
@@ -209,11 +232,48 @@ function prepareTransfer(conf, host, tool, args = {}) {
     if (partL && !flags.resume && !flags.overwrite) {
       throw tErr(`拒绝: 检测到未完成的传输 ${partPath(local)}。加 --resume 续传，或 --overwrite 删除后重传`);
     }
-    return { tool, flags, tc, remote, local };
+    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) {
@@ -226,9 +286,14 @@ async function uploadFile(shell, conf, plan, onProgress) {
   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, remote, "远程目标");
+  const remoteInfo = await sftpStat(sftp, rRemote, "远程目标");
   if (remoteInfo) {
     if (flags.resume) {
       throw tErr(`拒绝: --resume 只用于续传 ${part} 半成品；远程正式目标已存在 [${remote}]（覆盖请用 --overwrite）`);
@@ -236,10 +301,10 @@ async function uploadFile(shell, conf, plan, onProgress) {
     if (!flags.overwrite) {
       throw tErr(`拒绝: 远程目标已存在 [${remote}]。加 --overwrite 重传，或 --resume 续传半成品`);
     }
-    await sftpUnlink(sftp, remote, "远程正式目标");
+    await sftpUnlink(sftp, rRemote, "远程正式目标");
   }
 
-  const partInfo = await sftpStat(sftp, part, "半成品");
+  const partInfo = await sftpStat(sftp, rPart, "半成品");
   let offset = 0;
   let resumed = false;
   if (partInfo) {
@@ -247,7 +312,7 @@ async function uploadFile(shell, conf, plan, onProgress) {
       throw tErr(`拒绝: 检测到未完成的传输 ${part}。加 --resume 续传，或 --overwrite 删除后重传`);
     }
     if (flags.overwrite) {
-      await sftpUnlink(sftp, part, "半成品");
+      await sftpUnlink(sftp, rPart, "半成品");
     } else {
       const r = computeResumeOffset(partInfo.size, total);
       if (r.mode === "ready") {
@@ -256,15 +321,15 @@ async function uploadFile(shell, conf, plan, onProgress) {
           const localSha = await sha256File(local);
           const remoteSha = await remoteSha256(shell, conf, part);
           if (remoteSha !== localSha) {
-            await sftpUnlink(sftp, part, "不一致的半成品");
+            await sftpUnlink(sftp, rPart, "不一致的半成品");
             throw tErr(`校验失败: 半成品 sha256 与本地源不一致，已删除 ${part}（请用 --overwrite 重传）`);
           }
         }
-        await sftpRename(sftp, part, remote);
+        await sftpRename(sftp, rPart, rRemote);
         return { bytes: total, resumed: false, elapsedMs: Date.now() - startedAt, verify: tc.verify };
       }
       if (r.mode === "restart") {
-        await sftpUnlink(sftp, part, "与源大小不符的半成品");
+        await sftpUnlink(sftp, rPart, "与源大小不符的半成品");
       } else {
         offset = r.offset;
         resumed = true;
@@ -281,14 +346,14 @@ async function uploadFile(shell, conf, plan, onProgress) {
   await (async () => {
     if (offset === 0 && total > 0) {
       try {
-        await sftpFastPut(sftp, local, part, onProgress);
+        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(part, offset > 0 ? { flags: "r+", start: offset } : { flags: "w" });
+    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,
@@ -300,13 +365,13 @@ async function uploadFile(shell, conf, plan, onProgress) {
   if (tc.verify === "sha256") {
     const remoteSha = await remoteSha256(shell, conf, part);
     if (remoteSha !== localSha) {
-      await sftpUnlink(sftp, part, "校验失败的半成品");
+      await sftpUnlink(sftp, rPart, "校验失败的半成品");
       throw tErr(`校验失败: 上传内容 sha256 与本地源不一致（网络或源文件变动），已删除半成品`);
     }
   }
 
-  await sftpRename(sftp, part, remote);
-  return { bytes: total, resumed, elapsedMs: Date.now() - startedAt, verify: tc.verify };
+  await sftpRename(sftp, rPart, rRemote);
+  return { bytes: total, resumed, via: plan.mode, elapsedMs: Date.now() - startedAt, verify: tc.verify };
 }
 
 // ==== 下载 ====
@@ -322,8 +387,11 @@ async function downloadFile(shell, conf, plan, onProgress) {
   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, remote, "远程文件");
+  const remoteInfo = await sftpStat(sftp, rRemote, "远程文件");
   if (!remoteInfo) throw tErr(`拒绝: 远程文件不存在或不可读 [${remote}]`);
   if (remoteInfo.isDirectory()) throw tErr(`拒绝: 远程目标是目录，传输仅支持单文件 [${remote}]`);
   const total = Number(remoteInfo.size || 0);
@@ -383,13 +451,13 @@ async function downloadFile(shell, conf, plan, onProgress) {
   await (async () => {
     if (offset === 0 && total > 0) {
       try {
-        await sftpFastGet(sftp, remote, part, onProgress);
+        await sftpFastGet(sftp, rRemote, part, onProgress);
         return;
       } catch (e) {
         // fastGet 失败（如非 OpenSSH sftp-server）：回退 stream 管道，保可用性
       }
     }
-    const rs = sftp.createReadStream(remote, offset > 0 ? { start: offset } : { flags: "r" });
+    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,
@@ -408,7 +476,7 @@ async function downloadFile(shell, conf, plan, onProgress) {
   }
 
   fs.renameSync(part, local);
-  return { bytes: total, resumed, elapsedMs: Date.now() - startedAt, verify: tc.verify };
+  return { bytes: total, resumed, via: plan.mode, elapsedMs: Date.now() - startedAt, verify: tc.verify };
 }
 
 module.exports = {
@@ -419,4 +487,6 @@ module.exports = {
   pump,
   remoteSha256,
   sha256File,
+  normalizeSftpRoot,
+  resolveKokoBase,
 };