dsh-remote-agent 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -9,6 +9,38 @@
 
 ---
 
+## [0.5.0] - 2026-10-17
+
+### 功能：远程文件工具集（提案 #25）
+
+四个**只读**文件工具，装完即有 —— AI 可以直接读副机上的文件，**不用配
+网盘、不用挂载、不用 SMB**：
+
+- `remote_ls`：列目录（单层分页，目录优先，条目带类型/大小/修改时间）
+- `remote_read`：读文件 —— 文本 ≤8MB 按行分段（`offset`/`limit` 翻页，
+  单次响应 ≤256KB，超长行截断）；二进制只回 sha256 + 大小 + 头部 hex 预览
+- `remote_grep`：副机本地全文搜索（纯 JS 逐文件扫，**不 spawn 外部 grep**，
+  Windows 没有）；上限 2000 文件 / 单文件 2MB / 命中 ≤200 / 总时长 10s，
+  达到上限如实报告 `truncated`
+- `remote_tree`：目录树摘要（深度 1-6 默认 3，条目 ≤2000）—— 扫描在副机
+  跑完只回结构，50GB 目录也不搬数据
+
+架构与安全：
+
+- 独立协议帧 `fs/req`（hub→node）↔ `fs/res`（node→hub），带 `replyTo` 关联
+  与 15s 超时；副机断连即清理全部等待者。**不进任务队列、不占并发槽** ——
+  一条慢命令锁死队列的形态在这里结构性不存在
+- 安全模型与任务链路同一条底线：路径 `realpathSync.native`（展开 8.3 短名
+  与符号链接）后与 `roots` 前缀比对；`denyPaths` 在枚举与读取两层生效
+  （被禁条目连名字都不上报）；符号链接只列条目不解引用；整个模块没有写动词
+- `fs/req` 加入 E2E 必需加密帧集：relay 模式下文件路径与内容对中继不可见
+
+测试：`test/fs-service.test.js` 14 条单测 + hub⇄worker e2e 2 条（真实通道
+四工具贯通 + relay 窃听器验证文件内容/文件名不可见）+ 工具收口与 inject
+契约断言同步（8 → 12 个工具）。
+
+---
+
 ## [0.4.0] - 2026-10-17
 
 ### 验证：`agent` 链路两台真机确认通过

package/README.en.md

@@ -235,6 +235,10 @@ Once installed you **don't need to memorize commands** — just talk:
 | "What artifacts are there?" | `remote_manifest` |
 | "Pull report.pdf over" | `remote_pull` |
 | "Cancel that task" | `remote_cancel` |
+| "List what's in D:\BigData on the worker" | `remote_ls` |
+| "Read that config.json on the worker" | `remote_read` |
+| "Search the worker's 50GB folder for this term" | `remote_grep` |
+| "What does that folder on the worker look like?" | `remote_tree` |
 
 There is also a Web panel (sidebar → "远程同事"): node list (with CPU / memory
 / load badges), task dispatch, task states, result summaries, workspace
@@ -265,6 +269,40 @@ changes, change diffs, final artifacts, log tail.
 
 </details>
 
+### Reading files on the worker (no network drive needed)
+
+Four read-only file tools (`remote_ls` / `remote_read` / `remote_grep` /
+`remote_tree`) work out of the box: the AI can list directories, read files,
+run full-text search, and inspect folder structure — **no network share, no
+mount, no SMB setup**. Scan-type operations (grep/tree) run locally on the
+worker and only the results cross the wire — a 50GB folder never moves.
+
+<details>
+<summary>File tool parameters and boundaries</summary>
+
+| Tool | Parameters | Meaning |
+|---|---|---|
+| `remote_ls` | `path` (required), `limit`, `offset` | List a directory (single level, paged, directories first) |
+| `remote_read` | `path` (required), `offset`, `limit` | Text files ≤8MB are paged line by line (≤256KB per response); binaries return only sha256 + size + hex head preview |
+| `remote_grep` | `path`, `pattern` (required), `glob`, `regex`, `ignoreCase`, `maxMatches` | Full-text search on the worker (pure JS, no external grep spawned); caps: 2000 files / 2MB per file / 200 matches / 10 s |
+| `remote_tree` | `path` (required), `depth` | Directory-tree summary (depth 1-6, default 3; ≤2000 entries) |
+
+**Boundaries (same bottom line as the task pipeline)**: read-only — the module
+has no write verb; paths must be absolute and inside the node's `roots`,
+anything else is rejected (`workspace-denied`); `denyPaths` applies too (denied
+entries are not even reported by name); symbolic links are listed but never
+followed. File operations travel on a dedicated `fs/req`↔`fs/res` channel —
+**they never enter the task queue or occupy concurrency slots** — and under
+relay mode they are **end-to-end encrypted** like task frames (the relay sees
+ciphertext only).
+
+**Combining with manual setups**: for "AI looks up / searches a file" use
+these tools (zero config, works across NATs); for "browse huge media files
+like a local drive" SMB/network drives remain the right tool — they
+complement each other.
+
+</details>
+
 ---
 
 ## Security

package/README.md

@@ -208,6 +208,10 @@ ack 自动按明文兼容旧中继继续），安全边界与已知局限见
 | 「有哪些成品？」 | `remote_manifest` |
 | 「把 report.pdf 拉过来」 | `remote_pull` |
 | 「取消那个任务」 | `remote_cancel` |
+| 「看看副机 D:\BigData 里有什么」 | `remote_ls` |
+| 「读一下副机上那个 config.json」 | `remote_read` |
+| 「在副机 50GB 目录里搜这个词」 | `remote_grep` |
+| 「副机那个文件夹结构长什么样」 | `remote_tree` |
 
 另有一个 Web 面板（侧栏「远程同事」）：节点列表（含 CPU/内存/负载与仓库清单）、
 派发任务、**待审批卡**（exec 任务默认挂起，批准才下发）、任务状态、结果摘要、
@@ -238,6 +242,34 @@ ack 自动按明文兼容旧中继继续），安全边界与已知局限见
 
 </details>
 
+### 读副机上的文件（不用配网盘）
+
+四个只读文件工具（`remote_ls` / `remote_read` / `remote_grep` / `remote_tree`）
+装完即有：AI 可以直接列目录、读文件、全文搜索、看目录结构 —— **不用配网盘、
+不用挂载、不用 SMB**。扫描类操作（grep/tree）在副机本地跑完只回结果，
+50GB 目录也不用搬数据。
+
+<details>
+<summary>文件工具的参数与边界</summary>
+
+| 工具 | 参数 | 说明 |
+|---|---|---|
+| `remote_ls` | `path`（必填）、`limit`、`offset` | 列目录（单层分页，目录优先） |
+| `remote_read` | `path`（必填）、`offset`、`limit` | 文本 ≤8MB 按行分段（单次 ≤256KB）；二进制只回 sha256+大小+头部预览 |
+| `remote_grep` | `path`、`pattern`（必填）、`glob`、`regex`、`ignoreCase`、`maxMatches` | 副机本地全文搜索（纯 JS，不 spawn 外部命令）；上限 2000 文件 / 单文件 2MB / 命中 200 / 10 秒 |
+| `remote_tree` | `path`（必填）、`depth` | 目录树摘要（深度 1-6，默认 3；条目 ≤2000） |
+
+**边界（与任务链路同一条底线）**：只读，没有任何写操作；路径必须是绝对路径
+且落在该节点 `roots` 内，超出即拒（`workspace-denied`）；`denyPaths` 同样生效
+（被禁条目连名字都不上报）；符号链接只列条目不解引用。文件操作走独立的
+`fs/req`↔`fs/res` 帧，**不进任务队列、不占并发槽**，且在 relay 模式下与任务
+帧一样**全程端到端加密**（中继只见密文）。
+
+**与手工方案的组合**：要"AI 点读/搜索"用本组工具（零配置、跨网可用）；
+要"资源管理器像本地盘一样翻大文件"，SMB/网盘仍是正解 —— 两者互补。
+
+</details>
+
 ---
 
 ## 安全

package/SECURITY.md

@@ -202,6 +202,30 @@ docs/verification-repos-routing-real.md §4③）。超长值 400 字符截断
 协议里**不带模型 API key**。副机用自己的 DSH 配置与凭证 ——
 主机只能派任务，拿不到副机的模型凭证。
 
+### 远程文件工具：只读、roots 边界、链接不跟随（提案 #25）
+
+四个文件工具（`remote_ls` / `remote_read` / `remote_grep` / `remote_tree`）
+让 AI 直接读副机文件 —— 它们的安全模型：
+
+- **只读**。`lib/node/fs-service.js` 整个模块没有任何写动词；二进制文件
+  只回 sha256 + 大小 + 64 字节头部预览，不回原始字节。
+- **`roots` 是同一条边界**。每个入口路径先 `realpathSync.native`（展开
+  8.3 短名与符号链接，与任务工作区解析同口径）再与 `roots` 前缀比对，
+  越界即 `workspace-denied`；`denyPaths` 在**枚举层**就生效 —— 被禁
+  条目连名字都不会上报给 hub。
+- **符号链接不跟随**。tree/grep 遍历时链接只列条目本身：roots 内一个指向
+  `C:\Users` 的链接不是逃逸口。
+- **带宽有界**。read 单响应 ≤256KB；grep 上限 2000 文件 / 单文件 2MB /
+  命中 200 / 10 秒；tree 条目 ≤2000。副机不会被一次请求拖死。
+- **独立通道 + 加密**。文件操作走 `fs/req`↔`fs/res` 专用帧（15s 超时，
+  断连即失败），**不进任务队列、不占并发槽**；`fs/req` 在 relay 模式下
+  属于必需加密帧集 —— 文件路径与内容对中继不可见。
+
+注意：本组工具与 `remote_task` 共享 `roots` 的**读取**面 —— 给了
+`roots` 就意味着主机 AI 可以读那些内容（与派任务让副机 agent 读文件
+的既有能力等价，只是更快更直接）。不想让 AI 读某目录，把它加进
+`denyPaths`。
+
 ### exec 两阶段审批：默认挂起，等不到人不跑（提案 #2）
 
 `mode:"exec"` 的任务**默认 `approval:"manual"`**：hub 收到派单后挂起，

package/lib/hub/node-registry.js

@@ -84,6 +84,8 @@ class NodeRegistryCore {
     this.pendingApprovals = new Map()
     /** taskId → HubTask（全局索引，工具只拿得到 taskId） */
     this.tasks = new Map()
+    /** reqId → { resolve, timer }（提案 #25：远程文件请求的等待者表） */
+    this.fsPending = new Map()
     /** @type {import('./pull-manager.js').PullManager | undefined} */
     this.pulls = undefined
     /** @type {import('./relay-link.js').RelayLink | undefined} */
@@ -710,6 +712,72 @@ class NodeRegistryCore {
     return false
   }
 
+  /**
+   * 远程文件请求（提案 #25）：发 fs/req 并等 fs/res，超时 fail-fast。
+   *
+   * 为什么不用既有工具的"发完就走"模式：ls/read/grep/tree 是**查询语义**，
+   * 调用方（AI 工具）必须拿到结果才有意义 —— 所以这里把"发帧 + 等 replyTo"
+   * 包成一个 promise。超时拒收而不是无限等：节点掉线 / 帧丢失时调用方拿到
+   * fs-timeout 而不是永久挂起。
+   *
+   * @returns {Promise<object>} node 回的 result（或 reject {code, message}）
+   */
+  fsRequest(nodeId, op, params = {}, { timeoutMs = 15_000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const rec = this.nodes.get(nodeId)
+      if (!rec?.online) {
+        reject(Object.assign(new Error(`node not online: ${nodeId}`), { code: ERROR_CODE.TASK_UNKNOWN }))
+        return
+      }
+      const env = envelope(HUB_TO_NODE.FS_REQ, { op, ...params })
+      const reqId = env.id
+      const timer = setTimeout(() => {
+        this.fsPending.delete(reqId)
+        this.log('warn', 'fs request timeout', { nodeId, op, reqId, timeoutMs })
+        reject(Object.assign(new Error(`fs ${op} timed out after ${timeoutMs}ms`), { code: ERROR_CODE.FS_TIMEOUT }))
+      }, timeoutMs)
+      if (typeof timer.unref === 'function') timer.unref()
+      this.fsPending.set(reqId, { resolve, reject, timer, op, nodeId })
+      const sent = this.send(nodeId, HUB_TO_NODE.FS_REQ, { op, ...params }, { id: reqId })
+      if (!sent) {
+        clearTimeout(timer)
+        this.fsPending.delete(reqId)
+        reject(Object.assign(new Error(`failed to send fs request to ${nodeId}`), { code: ERROR_CODE.TASK_UNKNOWN }))
+      }
+    })
+  }
+
+  /** fs/res 到达：按 replyTo 找等待者并唤醒（registry-ingest 的 FS_RES case 转发到这里）。 */
+  handleFsRes(nodeId, d) {
+    const reqId = typeof d.replyTo === 'string' ? d.replyTo : ''
+    const waiter = reqId !== '' ? this.fsPending.get(reqId) : undefined
+    if (!waiter) {
+      // 迟到的响应（超时后才回来）：丢弃即可，等待者已经拿到 fs-timeout
+      this.log('info', 'late fs response dropped', { nodeId, reqId })
+      return
+    }
+    clearTimeout(waiter.timer)
+    this.fsPending.delete(reqId)
+    if (d.ok === true) {
+      waiter.resolve(d.result ?? {})
+    } else {
+      waiter.reject(Object.assign(
+        new Error(typeof d.message === 'string' ? d.message : 'fs request failed'),
+        { code: typeof d.code === 'string' ? d.code : ERROR_CODE.INTERNAL },
+      ))
+    }
+  }
+
+  /** 节点断连：清掉它名下还没等到 fs/res 的等待者（fail-fast，不挂调用方）。 */
+  fsCancelForNode(nodeId) {
+    for (const [reqId, w] of this.fsPending) {
+      if (w.nodeId !== nodeId) continue
+      clearTimeout(w.timer)
+      w.reject(Object.assign(new Error('node disconnected during fs request'), { code: ERROR_CODE.FS_TIMEOUT }))
+      this.fsPending.delete(reqId)
+    }
+  }
+
   /**
    * 发一个二进制帧给节点（header.to 由中继用来路由）。
    * E2E 会话存在时整体封密：外层只留 t/seq/iv + to。
@@ -813,6 +881,8 @@ class NodeRegistryCore {
     this.log('info', 'node offline', { nodeId, reason })
     // 断连时在途的产物分块必然残缺，直接失败掉，别让临时文件挂着
     this.pulls?.onNodeOffline?.(nodeId)
+    // 在途的远程文件请求同样 fail-fast（提案 #25）：等不到 fs/res 就别挂调用方
+    this.fsCancelForNode(nodeId)
   }
 
   startHeartbeat() {

package/lib/hub/registry-ingest.js

@@ -201,6 +201,12 @@ export function withIngest(Base) {
         case NODE_TO_HUB.PONG:
           return
 
+        case NODE_TO_HUB.FS_RES:
+          // 远程文件响应（提案 #25）：按 replyTo 唤醒 hub 侧的 fsRequest 等待者。
+          // 加密帧 —— fs 结果（目录结构 / 文件内容）不许明文过中继。
+          this.handleFsRes(nodeId, d)
+          return
+
         case NODE_TO_HUB.ERROR:
           this.log('warn', 'node reported error', { nodeId, code: d.code, taskId: d.taskId })
           if (d.code === ERROR_CODE.E2E_REQUIRED) {

package/lib/hub/tools.js

@@ -2,8 +2,9 @@
  * 主机侧 remote_* 工具集（零外部依赖）。
  *
  * 设计原则：**主电脑只消费 handoff，不消费副机的原始日志。**
- * 七个工具的职责边界刻意切得很窄：
+ * 工具的职责边界刻意切得很窄：
  *
+ * 任务链路：
  *   remote_nodes    看有哪些副机在线（信息汇聚的入口）
  *   remote_task     派一条任务（幂等 taskId，立即返回，不阻塞等结果）
  *   remote_status   看一条任务现在到哪了（进度尾巴 + 日志尾巴）
@@ -11,6 +12,13 @@
  *   remote_manifest 取产物清单（先看清单，再决定拉什么）
  *   remote_pull     显式拉取成品（只有 role:final 能过河）
  *   remote_cancel   打断一条任务
+ *   remote_purge    清理 hub 侧任务视图（逃生舱）
+ *
+ * 远程文件（提案 #25，只读，走 fs/req↔fs/res 独立通道，不进任务队列）：
+ *   remote_ls       列副机目录（分页）
+ *   remote_read     读文件（文本按行分段 / 二进制只回元数据）
+ *   remote_grep     副机本地全文搜索（纯 JS，不 spawn）
+ *   remote_tree     目录树摘要（扫描在副机跑完只回结构）
  *
  * 所有 execute 都返回普通 JSON（output.schema 描述它），错误以
  * RemoteAgentError 抛出，由框架统一materialize 成错误结果。
@@ -1016,6 +1024,228 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
     },
   })
 
+  // ── remote_ls / remote_read / remote_grep / remote_tree（提案 #25）──
+  //
+  // 四个只读文件工具共用同一条 RPC 通道：registry.fsRequest(nodeId, op, params)
+  // （fs/req ↔ fs/res，15s 超时，断连即失败）。与任务链路的本质区别：
+  // **不进副机任务队列、不 spawn、不占并发槽** —— 一条 grep 卡住锁死队列
+  // 的形态在这里结构性不存在（fs-service 自带 10s/2000 文件等扫描上限）。
+  //
+  // 副机 reject 的形态是 { code, message }（node/index.js handleFsReq 从
+  // FsError.code 透传），这里转成 RemoteAgentError 让 DSH 框架统一物化，
+  // 同时保留 code（workspace-denied / artifact-missing / artifact-too-large）
+  // —— 调用方可以区分"越界""不存在""太大"三种最常见的失败。
+  const fsOp = (name, description, parameters, output, op) => {
+    reg({
+      name,
+      description,
+      parameters,
+      output,
+      async execute(args) {
+        // resolveNodeId 会抛 unknown node / node offline（RemoteAgentError）
+        const nodeId = resolveNodeId(registry, args?.node)
+        // 只有 node 是路由概念不透传；path 是副机 op 的正式参数（fs-service 签名）
+        const params = { ...(args ?? {}) }
+        delete params.node
+        try {
+          const result = await registry.fsRequest(nodeId, op, params)
+          return { node: nodeId, ...(result && typeof result === 'object' ? result : {}) }
+        } catch (err) {
+          const code = typeof err?.code === 'string' ? err.code : ERROR_CODE.INTERNAL
+          throw new RemoteAgentError(`remote ${op} on ${nodeId} failed: ${String(err?.message ?? err)}`, code)
+        }
+      },
+    })
+  }
+
+  // 通用参数块：path 必填（副机上的绝对路径）；node 可选（自动路由）。
+  const pathParam = { type: 'string', description: '副机上的绝对路径，必须落在该节点允许的 roots 之内（超出会被副机以 workspace-denied 拒绝）。' }
+  const nodeParam = { type: 'string', description: '目标节点 id（或主机名）。省略时自动选在线节点。' }
+  const fsReq = (props, required) => ({ type: 'object', properties: { node: nodeParam, ...props }, required: ['path', ...required], additionalProperties: false })
+
+  fsOp(
+    'remote_ls',
+    '列出远程副机上的一个目录（单层、分页，按名称/大小/修改时间/类型）。用于"看看副机这个文件夹里有什么"。安全模型：只读；路径必须在该节点允许的 roots 内；denyPaths 生效；符号链接只列条目不解引用。',
+    fsReq({
+      path: pathParam,
+      limit: { type: 'number', description: '单页条目数（1-2000，默认 500）。' },
+      offset: { type: 'number', description: '起始偏移（配合 limit 翻页，默认 0）。' },
+    }, []),
+    {
+      schema: {
+        type: 'object',
+        properties: {
+          node: { type: 'string' },
+          path: { type: 'string' },
+          total: { type: 'number' },
+          offset: { type: 'number' },
+          truncated: { type: 'boolean' },
+          entries: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                name: { type: 'string' },
+                type: { type: 'string' },
+                size: { type: 'number' },
+                mtimeMs: { type: 'number' },
+              },
+              required: ['name', 'type'],
+            },
+          },
+        },
+        required: ['node', 'path', 'entries'],
+      },
+      render: renderText((_args, value) => {
+        const entries = arr(value?.entries)
+        if (entries.length === 0) return `${value?.path ?? '?'} 是空目录（或条目被 denyPaths 全部过滤）。`
+        const lines = [`${value.path}（共 ${value.total} 项${value.truncated ? '，本页截断' : ''}）：`, '']
+        for (const e of entries.slice(0, 200)) {
+          lines.push(`- ${e.type === 'dir' ? '[目录]' : e.type === 'link' ? '[链接]' : '[文件]'} ${e.name}${e.type === 'file' ? ` (${human(e.size)})` : ''}`)
+        }
+        if (value.truncated) lines.push('', '还有更多：用 offset/limit 翻页。')
+        return lines.join('\n')
+      }),
+    },
+    'ls',
+  )
+
+  fsOp(
+    'remote_read',
+    '读取远程副机上的一个文件。文本文件（≤8MB）按行分段返回（offset+limit 翻页，单次响应 ≤256KB，超长行截断）；二进制文件只回元数据（sha256、大小、头部 hex 预览），不回原始字节。用于"读一眼副机上的某个文件"。只读；路径必须在 roots 内。',
+    fsReq({
+      path: pathParam,
+      offset: { type: 'number', description: '起始行号（0 起，默认 0）。' },
+      limit: { type: 'number', description: '本次读取行数（1-5000，默认 500）。' },
+    }, []),
+    {
+      schema: {
+        type: 'object',
+        properties: {
+          node: { type: 'string' },
+          path: { type: 'string' },
+          binary: { type: 'boolean' },
+          size: { type: 'number' },
+          sha256: { type: 'string' },
+          ext: { type: 'string' },
+          head: { type: 'string' },
+          totalLines: { type: 'number' },
+          offset: { type: 'number' },
+          truncated: { type: 'boolean' },
+          lines: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['node', 'path', 'binary'],
+      },
+      render: renderText((_args, value) => {
+        if (value?.binary === true) {
+          return [
+            `二进制文件 ${value.path}（${human(value.size)}）`,
+            `sha256: ${value.sha256 ?? 'n/a'}`,
+            value.head ? `头部: ${String(value.head).slice(0, 64)}…` : '',
+          ].filter((l) => l !== '').join('\n')
+        }
+        const lines = arr(value?.lines)
+        if (lines.length === 0) return `${value?.path ?? '?'} 无内容（空文件或翻页越界）。`
+        const out = [`${value.path} 第 ${value.offset} 行起（全文 ${value.totalLines} 行${value.truncated ? '，截断' : ''}）：`, '']
+        for (const l of lines.slice(0, 400)) out.push(`│ ${l}`)
+        if (value.truncated) out.push('', `还有更多：用 offset=${(value.offset ?? 0) + lines.length} 继续读。`)
+        return out.join('\n')
+      }),
+    },
+    'read',
+  )
+
+  fsOp(
+    'remote_grep',
+    '在远程副机上做全文搜索：递归扫描目录下的文本文件（可按 glob 过滤文件名），返回命中的文件/行号/内容。扫描在副机本地完成，只回命中结果——50GB 目录也不搬数据。上限：2000 文件 / 单文件 2MB / 命中 ≤200 / 总时长 10s，达到上限如实报告 truncated。只读；路径必须在 roots 内。',
+    fsReq({
+      path: pathParam,
+      pattern: { type: 'string', description: '搜索内容。默认按字面量匹配；regex:true 时按正则解释。' },
+      regex: { type: 'boolean', description: '是否把 pattern 当正则（默认 false=字面量）。' },
+      ignoreCase: { type: 'boolean', description: '忽略大小写（默认 true）。' },
+      glob: { type: 'string', description: '文件名过滤（如 "*.txt"、"log*"），默认扫全部文本文件。' },
+      maxMatches: { type: 'number', description: '命中上限（1-200，默认 200）。想快就调小。' },
+    }, ['pattern']),
+    {
+      schema: {
+        type: 'object',
+        properties: {
+          node: { type: 'string' },
+          path: { type: 'string' },
+          pattern: { type: 'string' },
+          filesScanned: { type: 'number' },
+          filesSkipped: { type: 'number' },
+          matchCount: { type: 'number' },
+          truncated: { type: 'boolean' },
+          truncatedBy: { type: 'string' },
+          matches: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                file: { type: 'string' },
+                line: { type: 'number' },
+                text: { type: 'string' },
+              },
+              required: ['file', 'line'],
+            },
+          },
+        },
+        required: ['node', 'path', 'matches'],
+      },
+      render: renderText((_args, value) => {
+        const matches = arr(value?.matches)
+        if (matches.length === 0) {
+          return `无命中：pattern="${value?.pattern ?? ''}"（扫描 ${value?.filesScanned ?? 0} 个文件，跳过 ${value?.filesSkipped ?? 0} 个）。`
+        }
+        const lines = [
+          `"${value.pattern}" 命中 ${value.matchCount} 处（扫描 ${value.filesScanned} 文件${value.truncated ? `，按${value.truncatedBy === 'time' ? '超时' : '命中上限'}截断` : ''}）：`,
+          '',
+        ]
+        for (const m of matches.slice(0, 100)) lines.push(`${m.file}:${m.line}: ${String(m.text ?? '').slice(0, 300)}`)
+        if (value.truncated) lines.push('', '（结果被截断——缩小搜索范围或减小 maxMatches 可拿到更完整的结果）')
+        return lines.join('\n')
+      }),
+    },
+    'grep',
+  )
+
+  fsOp(
+    'remote_tree',
+    '查看远程副机上一个目录树的结构摘要（深度与条目数可配，默认 3 层 / 最多 2000 条）。扫描在副机本地完成，只回结构不回内容——适合"50GB 文件夹里到底长什么样"这类问题。只读；路径必须在 roots 内；符号链接只列条目不深入。',
+    fsReq({
+      path: pathParam,
+      depth: { type: 'number', description: '最大深度（1-6，默认 3）。' },
+    }, []),
+    {
+      schema: {
+        type: 'object',
+        properties: {
+          node: { type: 'string' },
+          path: { type: 'string' },
+          depth: { type: 'number' },
+          entries: { type: 'number' },
+          maxEntries: { type: 'number' },
+          truncated: { type: 'boolean' },
+          items: { type: 'array', items: { type: 'object' } },
+        },
+        required: ['node', 'path', 'items'],
+      },
+      render: renderText((_args, value) => {
+        const renderItems = (items, prefix, sink) => {
+          for (const it of arr(items).slice(0, 120)) {
+            sink.push(`${prefix}${it.type === 'dir' ? '📁' : '·'} ${it.name}`)
+            if (it.type === 'dir' && prefix.length <= 6) renderItems(it.children, `${prefix}  `, sink)
+          }
+        }
+        const lines = [`${value?.path ?? '?'}（深度 ${value?.depth}，${value?.entries} 条目${value?.truncated ? '，截断' : ''}）`, '']
+        renderItems(value?.items, '', lines)
+        return lines.join('\n')
+      }),
+    },
+    'tree',
+  )
+
   return disposers
 }
 

package/lib/node/fs-service.js

@@ -0,0 +1,504 @@
+/**
+ * 远程文件工具集（提案 #25）的副机本地实现 —— 四个只读操作：
+ *   ls / read / grep / tree
+ *
+ * 安全模型（与任务链路同一条底线，缺一不可）：
+ *  - **只读**。整个模块没有任何写路径 —— fs-service 拿不到"写"这个动词。
+ *  - **roots 边界**：每个入口路径先 realpathSync.native（展开 8.3 短名与符号
+ *    链接，与 exec.js resolveWorkspace 同款口径），再与 roots 前缀比对。
+ *  - **denyPaths 生效**：isDenied 与 artifacts.js / task-engine 同一条规则，
+ *    被禁路径在枚举与读取两层都被拦（枚举层拦是为了连名字都不上报）。
+ *  - **符号链接不跟随**：tree/grep 遍历时 withFileTypes 发现的链接只列条目
+ *    本身、绝不深入 —— 否则 roots 内一个指向 C:\Users 的链接就是逃逸口。
+ *
+ * 上限（防御 50GB 级文件夹被一次请求拖死副机）：
+ *  - read：文本模式仅支持 ≤ READABLE_FILE_MAX (8MB) 的文件按行分段；二进制
+ *    只回 sha256/size/头部预览；单次响应文本量 ≤ READ_TEXT_MAX (256KB)。
+ *  - grep：文件数 ≤ GREP_MAX_FILES (2000)、单文件 ≤ GREP_FILE_MAX (2MB)、
+ *    命中 ≤ maxMatches (200)、总时长 ≤ GREP_TIME_MS (10s)。
+ *  - tree：深度 ≤ depth、总条目 ≤ maxEntries (2000)。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { isDenied } from './exec.js'
+import { normalizePath, extname } from '../glob.js'
+import { ERROR_CODE } from '../protocol.js'
+
+/** 文本模式 read 的文件大小上限：超过就拒绝（建议 grep 定位后再读片段）。 */
+export const READABLE_FILE_MAX = 8 * 1024 * 1024
+/** 单次 read 响应携带的文本量上限（字节）。 */
+export const READ_TEXT_MAX = 256 * 1024
+/** grep 递归扫描的文件数上限。 */
+export const GREP_MAX_FILES = 2000
+/** grep 单文件大小上限：更大的文件直接跳过（防止二进制/巨型日志拖死）。 */
+export const GREP_FILE_MAX = 2 * 1024 * 1024
+/** grep 默认总时长上限（ms）：超时停下并如实报告 truncated。 */
+export const GREP_TIME_MS = 10 * 1000
+/** grep 默认命中上限。 */
+export const GREP_MAX_MATCHES = 200
+/** tree 默认最大深度与条目数。 */
+export const TREE_DEFAULT_DEPTH = 3
+export const TREE_MAX_ENTRIES = 2000
+/** ls 单页条目上限。 */
+export const LS_PAGE_MAX = 2000
+/** 二进制嗅探窗口：前 64 字节出现 NUL 即视为二进制。 */
+const SNIFF_BYTES = 64
+
+/** 复用任务链路的错误形态（code 会被 hub 工具层原样透出）。 */
+export class FsError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'FsError'
+    this.code = code
+  }
+}
+
+/**
+ * 解析"可以是文件也可以是目录"的路径：realpath + roots 前缀 + denyPaths。
+ * 与 resolveWorkspace 的差异只在两点：不要求是目录；不存在时直接拒
+ * （读一个不存在的文件没有"任务会创建它"的借口）。
+ */
+function resolveAny(requested, cfg) {
+  const { roots, caseInsensitive } = cfg
+  if (typeof requested !== 'string' || requested === '') {
+    throw new FsError('path is required', ERROR_CODE.WORKSPACE_DENIED)
+  }
+  if (!path.isAbsolute(requested)) {
+    throw new FsError(`path must be absolute: ${requested}`, ERROR_CODE.WORKSPACE_DENIED)
+  }
+  let resolved
+  try {
+    resolved = fs.realpathSync.native ? fs.realpathSync.native(requested) : fs.realpathSync(requested)
+  } catch {
+    throw new FsError(`path not found: ${requested}`, ERROR_CODE.ARTIFACT_MISSING)
+  }
+  const allowed = (roots ?? []).map((r) => {
+    let base = r
+    try {
+      base = fs.realpathSync.native ? fs.realpathSync.native(r) : fs.realpathSync(r)
+    } catch {
+      // 与 resolveWorkspace 同口径：不可达的根保持原样，后面照样拒一切子路径
+    }
+    return normalizePath(base, { caseInsensitive })
+  })
+  const norm = normalizePath(resolved, { caseInsensitive })
+  const ok = allowed.some((r) => norm === r || norm.startsWith(`${r}/`))
+  if (!ok) {
+    throw new FsError(
+      `path outside allowed roots: ${resolved}`,
+      ERROR_CODE.WORKSPACE_DENIED,
+    )
+  }
+  if (isDenied(resolved, cfg.denyPaths ?? [], { caseInsensitive })) {
+    throw new FsError(`path denied by denyPaths: ${resolved}`, ERROR_CODE.WORKSPACE_DENIED)
+  }
+  return resolved
+}
+
+/** 枚举层拒绝：条目级 denyPaths（连名字都不上报给 hub）。 */
+function entryDenied(absPath, cfg) {
+  return isDenied(absPath, cfg.denyPaths ?? [], { caseInsensitive: cfg.caseInsensitive })
+}
+
+/** 目录条目排序：目录优先，同级按名字（locale 感知，大小写不敏感）。 */
+function sortEntries(list) {
+  return list.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1
+    return a.name.localeCompare(b.name, undefined, { sensitivity: 'base', numeric: true })
+  })
+}
+
+/** 文件是否疑似二进制：前 SNIFF_BYTES 字节出现 NUL。 */
+function looksBinary(fd) {
+  const buf = Buffer.alloc(SNIFF_BYTES)
+  // ⚠ fs.readSync 直接返回 bytesRead 数字（不是 {bytesRead, buffer} 对象 ——
+  // 那是 fs.read 的 promise 版）。解构会得到 undefined，subarray(0, undefined)
+  // 变成整个缓冲，而 alloc 未写区域全零 → **任何文件都被误判二进制**。
+  const bytesRead = fs.readSync(fd, buf, 0, SNIFF_BYTES, 0)
+  return buf.subarray(0, bytesRead).includes(0)
+}
+
+/**
+ * 建一个 fs-service 实例。roots/denyPaths 来自副机配置（与任务链路同源），
+ * caseInsensitive 跟随 Windows 语义。
+ */
+export function createFsService(cfg) {
+  const { roots, caseInsensitive = false } = cfg
+  const conf = { roots, caseInsensitive, denyPaths: cfg.denyPaths ?? [] }
+
+  return {
+    /** 列目录（单层，分页）。 */
+    ls({ path: p, limit = 500, offset = 0 } = {}) {
+      const dir = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(dir)
+      } catch {
+        throw new FsError(`path not found: ${dir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (!st.isDirectory()) {
+        throw new FsError(`not a directory: ${dir}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const limitN = Math.min(Math.max(Number(limit) || 500, 1), LS_PAGE_MAX)
+      const offsetN = Math.max(Number(offset) || 0, 0)
+      const all = []
+      for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const abs = path.join(dir, ent.name)
+        if (entryDenied(abs, conf)) continue
+        let type = 'file'
+        let size = 0
+        let mtimeMs = 0
+        if (ent.isSymbolicLink()) {
+          // 链接只报条目本身，不深入也不解引用 —— 防止 roots 内链接逃逸
+          type = 'link'
+        } else if (ent.isDirectory()) {
+          type = 'dir'
+        } else if (ent.isFile()) {
+          try {
+            const s = fs.statSync(abs)
+            size = s.size
+            mtimeMs = s.mtimeMs
+          } catch {
+            // 竞态（文件刚被删）：仍上报名字，大小/时间留空
+          }
+        } else {
+          continue // socket/fifo 等非常规条目不上报
+        }
+        all.push({ name: ent.name, type, size, mtimeMs })
+      }
+      sortEntries(all)
+      return {
+        path: dir,
+        total: all.length,
+        offset: offsetN,
+        truncated: offsetN + limitN < all.length,
+        entries: all.slice(offsetN, offsetN + limitN),
+      }
+    },
+
+    /**
+     * 读文件。文本模式：≤ READABLE_FILE_MAX 的文件按行分段（offset/limit），
+     * 单次文本量 ≤ READ_TEXT_MAX；二进制模式：只回 sha256/size/头部预览。
+     */
+    read({ path: p, offset = 0, limit = 500 } = {}) {
+      const file = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(file)
+      } catch {
+        throw new FsError(`path not found: ${file}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (!st.isFile()) {
+        throw new FsError(`not a regular file: ${file}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      let fd
+      try {
+        fd = fs.openSync(file, 'r')
+        if (looksBinary(fd)) {
+          // 二进制：hash 全文件 + 头部预览（hex），绝不回原始字节
+          const buf = Buffer.alloc(Math.min(st.size, SNIFF_BYTES))
+          fs.readSync(fd, buf, 0, buf.length, 0)
+          const hash = createHash('sha256')
+          const chunk = Buffer.alloc(1024 * 1024)
+          for (;;) {
+            const n = fs.readSync(fd, chunk, 0, chunk.length, null)
+            if (n <= 0) break
+            hash.update(chunk.subarray(0, n))
+          }
+          return {
+            path: file,
+            binary: true,
+            size: st.size,
+            sha256: hash.digest('hex'),
+            ext: extname(normalizePath(file, { caseInsensitive })),
+            head: buf.toString('hex'),
+          }
+        }
+        if (st.size > READABLE_FILE_MAX) {
+          throw new FsError(
+            `file too large for text read (${st.size} > ${READABLE_FILE_MAX}); use grep to locate then read a narrower path`,
+            ERROR_CODE.ARTIFACT_TOO_LARGE,
+          )
+        }
+        const raw = fs.readFileSync(file)
+        const text = raw.toString('utf8')
+        const lines = text.split('\n')
+        // 尾部空行是 split 的伪影：文件以 \n 结尾时多出一个空串
+        if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+        const offsetN = Math.max(Number(offset) || 0, 0)
+        const limitN = Math.min(Math.max(Number(limit) || 500, 1), 5000)
+        const slice = []
+        let bytes = 0
+        let truncated = false
+        for (let i = offsetN; i < lines.length; i++) {
+          const line = lines[i]
+          // 单行超长截断：一行 1MB 的压缩 JSON 会独自顶爆响应
+          const clipped = line.length > 2000 ? `${line.slice(0, 2000)}…[line truncated]` : line
+          const cost = Buffer.byteLength(clipped, 'utf8') + 1
+          if (bytes + cost > READ_TEXT_MAX) {
+            truncated = true
+            break
+          }
+          slice.push(clipped)
+          bytes += cost
+          if (slice.length >= limitN) {
+            truncated = i < lines.length - 1
+            break
+          }
+        }
+        return {
+          path: file,
+          binary: false,
+          size: st.size,
+          totalLines: lines.length,
+          offset: offsetN,
+          truncated: truncated || offsetN + slice.length < lines.length,
+          lines: slice,
+        }
+      } finally {
+        try {
+          if (fd !== undefined) fs.closeSync(fd)
+        } catch {
+          // 关闭失败不影响结果
+        }
+      }
+    },
+
+    /**
+     * 副机本地全文搜索：递归扫 roots 内目录，文本文件逐行匹配。
+     * 纯 JS（Windows 没有外部 grep 可 spawn）；上限见模块头注释。
+     */
+    grep({ path: p, pattern, regex = false, ignoreCase = true, glob = '', maxMatches = GREP_MAX_MATCHES } = {}) {
+      if (typeof pattern !== 'string' || pattern === '') {
+        throw new FsError('pattern is required', ERROR_CODE.WORKSPACE_DENIED)
+      }
+      let re
+      try {
+        re = regex
+          ? new RegExp(pattern, ignoreCase ? 'i' : '')
+          : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), ignoreCase ? 'i' : '')
+      } catch (err) {
+        throw new FsError(`invalid pattern: ${err.message}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const dir = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(dir)
+      } catch {
+        throw new FsError(`path not found: ${dir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      const maxN = Math.min(Math.max(Number(maxMatches) || GREP_MAX_MATCHES, 1), GREP_MAX_MATCHES)
+      const matches = []
+      let filesScanned = 0
+      let filesSkipped = 0
+      let truncatedByTime = false
+      let truncatedByLimit = false
+      const started = Date.now()
+
+      const isGlobMatch = (name) => {
+        if (!glob) return true
+        // 极简 glob：* 任意（不含 /）、? 单字符 —— 覆盖 *.txt / src* 之类
+        const esc = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]')
+        return new RegExp(`^${esc}$`, caseInsensitive ? 'i' : '').test(name)
+      }
+
+      const scan = (dirAbs) => {
+        if (matches.length >= maxN) {
+          truncatedByLimit = true
+          return
+        }
+        if (Date.now() - started > GREP_TIME_MS) {
+          truncatedByTime = true
+          return
+        }
+        let ents
+        try {
+          ents = fs.readdirSync(dirAbs, { withFileTypes: true })
+        } catch {
+          filesSkipped++
+          return
+        }
+        for (const ent of ents) {
+          if (matches.length >= maxN) {
+            truncatedByLimit = true
+            return
+          }
+          if (Date.now() - started > GREP_TIME_MS) {
+            truncatedByTime = true
+            return
+          }
+          const abs = path.join(dirAbs, ent.name)
+          if (entryDenied(abs, conf)) continue
+          if (ent.isDirectory()) {
+            scan(abs)
+            continue
+          }
+          // 链接与非常规文件跳过：不跟随、不读
+          if (!ent.isFile()) {
+            filesSkipped++
+            continue
+          }
+          if (!isGlobMatch(ent.name)) continue
+          let fst
+          try {
+            fst = fs.statSync(abs)
+          } catch {
+            filesSkipped++
+            continue
+          }
+          if (fst.size > GREP_FILE_MAX || fst.size === 0) {
+            filesSkipped++
+            continue
+          }
+          let fd
+          try {
+            fd = fs.openSync(abs, 'r')
+            if (looksBinary(fd)) {
+              filesSkipped++
+              continue
+            }
+            const content = fs.readFileSync(abs)
+            filesScanned++
+            const text = content.toString('utf8')
+            const lines = text.split('\n')
+            for (let i = 0; i < lines.length && matches.length < maxN; i++) {
+              if (re.test(lines[i])) {
+                matches.push({
+                  file: abs,
+                  line: i + 1,
+                  text: lines[i].length > 500 ? `${lines[i].slice(0, 500)}…` : lines[i],
+                })
+                // 达到全局上限即如实报告截断 —— 即使恰好在最后一个文件结束，
+                // 未报出的命中大概率还存在（用户视角"还有更多"才是事实）
+                if (matches.length >= maxN) truncatedByLimit = true
+              }
+            }
+          } catch {
+            filesSkipped++
+          } finally {
+            try {
+              if (fd !== undefined) fs.closeSync(fd)
+            } catch {
+              // 忽略关闭失败
+            }
+          }
+        }
+      }
+
+      if (st.isDirectory()) {
+        scan(dir)
+      } else if (st.isFile()) {
+        // 单文件 grep：直接匹配该文件
+        let fd
+        try {
+          fd = fs.openSync(dir, 'r')
+          if (!looksBinary(fd)) {
+            filesScanned++
+            const lines = fs.readFileSync(dir).toString('utf8').split('\n')
+            for (let i = 0; i < lines.length && matches.length < maxN; i++) {
+              if (re.test(lines[i])) {
+                matches.push({ file: dir, line: i + 1, text: lines[i].slice(0, 500) })
+              }
+            }
+          }
+        } catch {
+          filesSkipped++
+        } finally {
+          try {
+            if (fd !== undefined) fs.closeSync(fd)
+          } catch {
+            // 忽略
+          }
+        }
+      } else {
+        throw new FsError(`not a directory or file: ${dir}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+
+      return {
+        path: dir,
+        pattern,
+        filesScanned,
+        filesSkipped,
+        matches,
+        matchCount: matches.length,
+        truncated: truncatedByTime || truncatedByLimit,
+        truncatedBy: truncatedByTime ? 'time' : truncatedByLimit ? 'maxMatches' : undefined,
+      }
+    },
+
+    /** 目录树摘要：扫描在副机跑完只回结构（50GB 也不搬家）。 */
+    tree({ path: p, depth = TREE_DEFAULT_DEPTH, maxEntries = TREE_MAX_ENTRIES } = {}) {
+      const rootDir = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(rootDir)
+      } catch {
+        throw new FsError(`path not found: ${rootDir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (!st.isDirectory()) {
+        throw new FsError(`not a directory: ${rootDir}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const depthN = Math.min(Math.max(Number(depth) || TREE_DEFAULT_DEPTH, 1), 6)
+      const maxN = Math.min(Math.max(Number(maxEntries) || TREE_MAX_ENTRIES, 1), TREE_MAX_ENTRIES)
+      let used = 0
+      let truncated = false
+
+      const build = (dirAbs, level) => {
+        if (level > depthN || used >= maxN) {
+          if (used >= maxN) truncated = true
+          return []
+        }
+        let ents
+        try {
+          ents = fs.readdirSync(dirAbs, { withFileTypes: true })
+        } catch {
+          return [{ name: '(unreadable)', type: 'error' }]
+        }
+        const items = []
+        const dirs = []
+        const files = []
+        for (const ent of ents) {
+          const abs = path.join(dirAbs, ent.name)
+          if (entryDenied(abs, conf)) continue
+          if (ent.isDirectory()) dirs.push(ent.name)
+          else if (ent.isFile()) files.push(ent.name)
+          // 链接只报名字标注 link，不深入（与 ls 同口径）
+          else if (ent.isSymbolicLink()) files.push(ent.name)
+        }
+        const collator = (a, b) => a.localeCompare(b, undefined, { sensitivity: 'base', numeric: true })
+        dirs.sort(collator)
+        files.sort(collator)
+        for (const name of dirs) {
+          if (used >= maxN) {
+            truncated = true
+            break
+          }
+          used++
+          const node = { name, type: 'dir', children: build(path.join(dirAbs, name), level + 1) }
+          items.push(node)
+        }
+        for (const name of files) {
+          if (used >= maxN) {
+            truncated = true
+            break
+          }
+          used++
+          items.push({ name, type: 'file' })
+        }
+        return items
+      }
+
+      const items = build(rootDir, 1)
+      return {
+        path: rootDir,
+        depth: depthN,
+        entries: used,
+        maxEntries: maxN,
+        truncated: truncated || used >= maxN,
+        items,
+      }
+    },
+  }
+}

package/lib/node/index.js

@@ -51,6 +51,9 @@ import { friendlyConnectError } from '../setup.js'
 import { scanRepos } from './repos.js'
 import { TaskEngine } from './task-engine.js'
 import { TaskStore } from './task-store.js'
+// 远程文件工具集（提案 #25）：ls/read/grep/tree 只读实现，与任务链路共用
+// roots / denyPaths / caseInsensitive 三个配置（同一个安全边界，两处入口）。
+import { createFsService } from './fs-service.js'
 import { NodeTransport, TRANSPORT_MODE } from './transport.js'
 
 const PLUGIN_NAME = 'dsh-remote-agent'
@@ -452,6 +455,10 @@ function startWorker(ctx, config) {
     stateDir,
   ]
 
+  // 远程文件工具集（提案 #25）：与任务链路同源的 roots/denyPaths —— 同一个
+  // 安全边界，两处入口。只读实现，见 lib/node/fs-service.js 头注释。
+  const fsService = createFsService({ roots, denyPaths, caseInsensitive })
+
   /* 3) 任务仓库 ------------------------------------------------------- */
   let store
   try {
@@ -782,6 +789,11 @@ function startWorker(ctx, config) {
         // transport 自己已回 pong；这里保留一条兜底，防止上层换实现后 ping 悬空
         send(NODE_TO_HUB.PONG, { echo: frame.id, nodeId, time: Date.now() }, { replyTo: frame.id })
         return
+      case HUB_TO_NODE.FS_REQ:
+        // 远程文件工具集（提案 #25）：异步执行，不挡后续帧；结果回 fs/res，
+        // reqId 就是请求信封 id（hub 按 replyTo 对 pending 表）。
+        handleFsReq(frame, d)
+        return
       case HUB_TO_NODE.ERROR:
         logger.warn('hub reported error', { code: d.code, message: d.message, replyTo: d.replyTo })
         return
@@ -790,6 +802,31 @@ function startWorker(ctx, config) {
     }
   }
 
+  /**
+   * 执行一条远程文件请求（提案 #25）。所有错误——包括被 FsError 表达的
+   * 业务拒绝（越界 / denyPaths / 超限）——都折进 fs/res 的 ok:false 载荷，
+   * 让 hub 工具层拿到结构化的 code 而不是一条 ERROR 帧。
+   */
+  function handleFsReq(frame, d) {
+    const op = typeof d.op === 'string' ? d.op : ''
+    const ops = { ls: 'ls', read: 'read', grep: 'grep', tree: 'tree' }
+    const fn = ops[op]
+    if (!fn) {
+      send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: false, code: ERROR_CODE.WORKSPACE_DENIED, message: `unknown fs op: ${op || '(empty)'}` })
+      return
+    }
+    const started = Date.now()
+    swallow(Promise.resolve().then(() => {
+      const result = fsService[fn](d)
+      logger.debug('fs op done', { op, ms: Date.now() - started, nodeId })
+      send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: true, result })
+    }).catch((err) => {
+      const code = typeof err?.code === 'string' ? err.code : ERROR_CODE.INTERNAL
+      logger.warn('fs op failed', { op, ms: Date.now() - started, code, error: msgOf(err) })
+      send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: false, code, message: msgOf(err) })
+    }))
+  }
+
   /* 9) 事件接线 ------------------------------------------------------- */
   const listenerDisposers = []
   const on = (evt, fn) => {

package/lib/node/transport.js

@@ -66,6 +66,8 @@ const E2E_REQUIRED_TYPES = new Set([
   HUB_TO_NODE.ARTIFACT_LIST,
   HUB_TO_NODE.ARTIFACT_PULL,
   HUB_TO_NODE.ARTIFACT_CANCEL,
+  // 远程文件请求（提案 #25）：目录结构与文件内容是敏感信息，必须加密。
+  HUB_TO_NODE.FS_REQ,
 ])
 
 /** 副机侧永远明文的帧类型（握手/心跳/交换本身）。 */

package/lib/protocol.js

@@ -25,6 +25,12 @@ export const HUB_TO_NODE = Object.freeze({
    * ed25519 身份签出（绑定双方公钥 + 连接 nonce）。中继只转发，无法伪造。
    */
   E2E_ACK: 'hub/e2e',
+  /**
+   * 远程文件请求（提案 #25）：hub → node 的只读文件操作（ls/read/grep/tree）。
+   * 载荷 { op, ...params }；reqId 用信封 id 本身，node 回 fs/res 时 replyTo 对上。
+   * 必须加密（E2E_REQUIRED_TYPES）：目录结构 / 文件内容都是敏感信息。
+   */
+  FS_REQ: 'fs/req',
   TASK_START: 'task/start',
   TASK_CANCEL: 'task/cancel',
   TASK_QUERY: 'task/query',
@@ -60,6 +66,11 @@ export const NODE_TO_HUB = Object.freeze({
    * 旧 hub 按未知帧忽略 → 协商不成就继续明文（混跑安全）。
    */
   E2E_OFFER: 'node/e2e',
+  /**
+   * 远程文件响应（提案 #25）：node → hub 的 fs/req 结果。载荷
+   * { replyTo, ok, result?, code?, message? }。加密发送（node→hub 默认封密）。
+   */
+  FS_RES: 'fs/res',
   PONG: 'pong',
   ERROR: 'error',
 })
@@ -137,6 +148,8 @@ export const ERROR_CODE = Object.freeze({
   ARTIFACT_MISSING: 'artifact-missing',
   ARTIFACT_TOO_LARGE: 'artifact-too-large',
   HASH_MISMATCH: 'hash-mismatch',
+  /** 远程文件请求超时（提案 #25）：node 未在时限内回 fs/res。 */
+  FS_TIMEOUT: 'fs-timeout',
   /** hub 身份验证失败：指纹不匹配 / 签名无效 / nonce 对不上 / 时间戳超窗。 */
   HUB_IDENTITY_MISMATCH: 'hub-identity-mismatch',
   /** relay 模式下 hub 身份帧尚未到达（宽限窗口内），任务暂不执行。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-agent",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "type": "module",
   "description": "把另一台电脑变成你 DSH 的远程 Agent 同事：副机本地持久跑任务、独立 Agent 循环，只回传 handoff 摘要与产物清单，成品按需拉取。",
   "license": "MIT",

package/scripts/check-doc-drift.mjs

@@ -417,9 +417,24 @@ for (const [i, [file, why]] of MAINT_FILES.entries()) {
     /五分钟上手/.test(rootReadme) && /--doctor/.test(rootReadme) && /dsh-remote-setup/.test(rootReadme),
     'README.md 五分钟上手一节')
   check('37', 'package.json 声明了 dsh-remote-setup 的 bin 入口且文件存在',
-    pkg.bin?.['dsh-remote-setup'] === './bin/dsh-remote-setup.js'
-      && fs.existsSync(path.join(ROOT, 'bin', 'dsh-remote-setup.js')),
-    'package.json bin + bin/dsh-remote-setup.js')
+    // ⚠ 路径写法：**规范形态是不带 `./` 前缀**。
+    //
+    // npm 对 `bin` 里的 `./bin/x.js` 会给出警告并在发布时**自动移除前缀**：
+    //   npm warn publish "bin[dsh-remote-setup]" script name bin/dsh-remote-setup.js
+    //                      was invalid and removed
+    // 那条 warn 的措辞容易误读成"这条 bin 被删了"，实际是"前缀被修正了" ——
+    // 但它说明**写 `./` 是非规范形态**，应当避免。
+    //
+    // 这条断言原本写死 `'./bin/dsh-remote-setup.js'`，等于在保护一个
+    // npm 会改写掉的写法。现在接受规范形态（无前缀），并容忍带前缀的历史
+    // 配置 —— `npm pkg fix` 会把带前缀的改成规范形态。
+    (() => {
+      const v = pkg.bin?.['dsh-remote-setup']
+      if (typeof v !== 'string') return false
+      return v.replace(/^\.\//, '') === 'bin/dsh-remote-setup.js'
+        && fs.existsSync(path.join(ROOT, 'bin', 'dsh-remote-setup.js'))
+    })(),
+    'package.json bin（规范形态：不带 ./ 前缀）+ bin/dsh-remote-setup.js')
   check('38', '生成器替用户填好 inject: []（worker 片段必须自带）',
     /inject:\s*\[\]/.test(setupLib),
     'lib/setup.js buildWorkerYaml')

package/scripts/diag-inject.mjs

@@ -185,14 +185,14 @@ try {
 }
 
 if (applyHub) {
-  // 4a. inject 齐全 → 不抛，且 8 个工具都在
+  // 4a. inject 齐全 → 不抛，且 12 个工具都在（8 任务 + 4 文件，提案 #25）
   try {
     const ctx = fakeCtx(declared)
     applyHub(ctx, { role: 'hub', nodeToken: 'nt_diag' })
     check('inject 齐全时 applyHub 不抛', true)
     check(
-      'inject 齐全时注册 8 个 remote_* 工具',
-      ctx.registered.tools.length === 8,
+      'inject 齐全时注册 12 个 remote_* 工具',
+      ctx.registered.tools.length === 12,
       `实际 ${ctx.registered.tools.length} 个：${ctx.registered.tools.join(', ') || '(无)'}`,
     )
     check('inject 齐全时注册了路由', ctx.registered.routes.length > 0, `${ctx.registered.routes.length} 条`)