dsh-remote-agent 0.4.3 → 0.6.0

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 成错误结果。
@@ -26,6 +34,9 @@ import {
   newTaskId,
   validateTaskStart,
 } from '../protocol.js'
+// exec/agent 分开的默认超时（提案 #26-1）——与副机兜底**同源**，
+// 避免"工具说 10 分钟、副机兜底 1 小时"的分裂。
+import { AGENT_DEFAULT_TIMEOUT_MS, EXEC_DEFAULT_TIMEOUT_MS } from '../node/task-engine.js'
 // 视图投影共享层：与 UI 路由用**同一份**白名单（见 lib/hub/views.js 的说明）。
 import { handoffView } from './views.js'
 
@@ -340,7 +351,7 @@ export function handoffSummaryText(task) {
  */
 export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults = {} }) {
   const disposers = []
-  const defaultTimeoutMs = num(defaults.timeoutMs) ?? 60 * 60 * 1000
+  const explicitTimeoutMs = num(defaults.timeoutMs)
 
   /**
    * 注册一个工具，并给它的 `execute` **统一套上返回值净化**。
@@ -411,6 +422,18 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
                     at: { type: 'number' },
                   },
                 },
+                // 队列健康快照（提案 #26-3）：副机未上报（旧版本）时为 null，
+                // 由 dropNullForSchema 剥掉。字段全部有值（0/false 兜底）。
+                queue: {
+                  type: 'object',
+                  properties: {
+                    queued: { type: 'number' },
+                    running: { type: 'number' },
+                    maxConcurrent: { type: 'number' },
+                    oldestQueuedMs: { type: 'number' },
+                    starved: { type: 'boolean' },
+                  },
+                },
               },
               required: ['nodeId', 'online'],
             },
@@ -433,6 +456,15 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
           if (n.resource) {
             lines.push(`  资源: CPU ${n.resource.cpuPct ?? '—'}% · 内存 ${n.resource.memUsedMb ?? '—'}/${n.resource.memTotalMb ?? '—'}MB · load1 ${n.resource.load1 ?? '—'}`)
           }
+          // 队列健康（提案 #26-3）：starved 是"该去副机看看卡在哪"的强信号
+          if (n.queue) {
+            if (n.queue.starved === true) {
+              const waited = Math.round((n.queue.oldestQueuedMs ?? 0) / 60000)
+              lines.push(`  ⚠ 队列疑似堵死：${n.queue.running}/${n.queue.maxConcurrent} 并发占满，${n.queue.queued} 条排队，最久已等 ${waited >= 1 ? `${waited} 分钟` : `${n.queue.oldestQueuedMs}ms`}。用 remote_status 逐条查 running 任务，必要时 remote_cancel。`)
+            } else if ((n.queue.queued ?? 0) > 0) {
+              lines.push(`  队列: ${n.queue.running}/${n.queue.maxConcurrent} 在跑，${n.queue.queued} 条排队`)
+            }
+          }
         }
         return lines.join('\n')
       }),
@@ -471,7 +503,7 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
           additionalProperties: false,
         },
         outputs: { type: 'array', items: { type: 'string' }, description: '期望产出物的 glob（相对工作区），用于产物清单筛选。' },
-        timeoutMs: { type: 'number', description: `副机侧任务超时（毫秒），默认 ${defaultTimeoutMs}。` },
+        timeoutMs: { type: 'number', description: `副机侧任务超时（毫秒）。缺省按模式：exec ${EXEC_DEFAULT_TIMEOUT_MS / 60000} 分钟、agent ${AGENT_DEFAULT_TIMEOUT_MS / 60000} 分钟。` },
         denyPaths: { type: 'array', items: { type: 'string' }, description: '副机侧额外禁止访问的路径（绝对路径）。' },
         artifactRules: {
           type: 'object',
@@ -581,7 +613,10 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
         // 只有消费者没有生产者，用户无法覆盖内置的产物角色判定）
         artifactRules: args?.artifactRules,
         constraints: {
-          timeoutMs: num(args?.timeoutMs) ?? defaultTimeoutMs,
+          // 提案 #26-1：缺省按模式分开（exec 10min / agent 1h），与副机兜底
+          // 同源常量；defaults.timeoutMs（配置显式指定）优先于一切缺省。
+          timeoutMs: num(args?.timeoutMs) ?? explicitTimeoutMs
+            ?? (v.spec.mode === TASK_MODE.EXEC ? EXEC_DEFAULT_TIMEOUT_MS : AGENT_DEFAULT_TIMEOUT_MS),
           denyPaths: Array.isArray(args?.denyPaths) ? args.denyPaths : [],
         },
         origin: 'hub',
@@ -1016,6 +1051,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
 }