dsh-remote-agent 0.9.7 → 0.9.8

package/lib/hub/tools.js

@@ -1363,6 +1363,295 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
     'tree',
   )
 
+  /* ═══════════════════════════════════════════════════════════════════════
+   * 写操作工具（2026-10-20，用户要求"更多工具 = 文件写操作"）
+   * ═══════════════════════════════════════════════════════════════════════
+   *
+   * ⚠⚠ **这四个工具会改副机的文件** —— 前四个 fs 工具全是只读。
+   *
+   * 与只读工具的关键区别：**必须带 `confirm: 'yes'`**。
+   *
+   * 为什么强制确认而不是靠参数默认值：
+   *   · 这些操作**不可逆**（删了就是删了）
+   *   · 调用方通常是 AI，而 AI 会"顺手"多调一次工具
+   *   · 用户对"AI 改了我的文件"的容忍度远低于"AI 读了我的文件"
+   *
+   * 确认不是形式主义：`confirm` 必须由**调用方显式表达**，缺了直接拒绝。
+   * 副机侧还有一层护栏（roots / 不覆盖 / 不递归删），两层独立。
+   */
+  const confirmParam = {
+    type: 'string',
+    description: '必须显式传 "yes" 才能执行。这是不可逆的文件操作，插件要求调用方明确表示知情。',
+  }
+
+  /**
+   * 写操作工具的通用包装。
+   *
+   * @param {string} name 工具名
+   * @param {string} description 说明（要讲清危险）
+   * @param {object} parameters 参数 schema
+   * @param {object} output 输出 schema
+   * @param {string} op 副机侧的 op 名
+   */
+  const writeOp = (name, description, parameters, output, op) => {
+    reg({
+      name,
+      description,
+      parameters,
+      output,
+      async execute(args) {
+        // ⚠ 二次确认是**硬要求**：缺了直接拒，不给默认通过
+        if (args?.confirm !== 'yes') {
+          throw new RemoteAgentError(
+            `${name} 会修改副机上的文件（不可逆）。`
+            + '请在参数里显式传 confirm: "yes" 表示你已确认目标路径正确。',
+            ERROR_CODE.WORKSPACE_DENIED,
+          )
+        }
+        const nodeId = resolveNodeId(registry, args?.node)
+        const params = { ...(args ?? {}) }
+        // confirm / node 都是 hub 侧概念，不透传给副机
+        delete params.node
+        delete params.confirm
+        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,
+          )
+        }
+      },
+    })
+  }
+
+  const writeReq = (props, required) => ({
+    type: 'object',
+    properties: { node: nodeParam, confirm: confirmParam, ...props },
+    required: ['path', 'confirm', ...required],
+    additionalProperties: false,
+  })
+
+  writeOp(
+    'remote_write',
+    '在副机上写一个文件（**会修改文件，不可逆**）。默认**不覆盖**已有文件 —— 要覆盖必须显式传 overwrite: true。'
+    + '路径必须在副机允许的 roots 内。写盘是原子的（临时文件 + rename），不会留半截文件。'
+    + '单次内容上限 8MB。**必须传 confirm: "yes"**。',
+    writeReq({
+      path: pathParam,
+      content: { type: 'string', description: '文件内容（UTF-8 文本）。上限 8MB。' },
+      overwrite: { type: 'boolean', description: '目标已存在时是否覆盖。默认 false（拒绝）。' },
+    }, ['content']),
+    {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        path: { type: 'string' },
+        bytes: { type: 'number' },
+        overwritten: { type: 'boolean' },
+      },
+      required: ['node', 'path'],
+    },
+    'write',
+  )
+
+  writeOp(
+    'remote_mkdir',
+    '在副机上建目录（递归，已存在视为成功）。路径必须在 roots 内。**必须传 confirm: "yes"**。',
+    writeReq({ path: pathParam }, []),
+    {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        path: { type: 'string' },
+        created: { type: 'boolean' },
+      },
+      required: ['node', 'path'],
+    },
+    'mkdir',
+  )
+
+  writeOp(
+    'remote_move',
+    '在副机上移动/重命名文件（同盘 rename）。两端都必须在 roots 内。'
+    + '默认不覆盖目标；跨盘移动会明确报错（不做静默复制）。**必须传 confirm: "yes"**。',
+    {
+      type: 'object',
+      properties: {
+        node: nodeParam,
+        confirm: confirmParam,
+        from: { type: 'string', description: '源路径（副机绝对路径，须在 roots 内）。' },
+        to: { type: 'string', description: '目标路径（副机绝对路径，须在 roots 内）。' },
+        overwrite: { type: 'boolean', description: '目标已存在时是否覆盖。默认 false。' },
+      },
+      required: ['from', 'to', 'confirm'],
+      additionalProperties: false,
+    },
+    {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        from: { type: 'string' },
+        to: { type: 'string' },
+      },
+      required: ['node', 'from', 'to'],
+    },
+    'move',
+  )
+
+  writeOp(
+    'remote_delete',
+    '删除副机上的**单个文件或空目录**（**不可逆**）。'
+    + '刻意**不支持递归删除** —— 非空目录会被拒绝，真有需要请用 exec 显式执行删除命令。'
+    + '路径必须在 roots 内。**必须传 confirm: "yes"**。',
+    writeReq({ path: pathParam }, []),
+    {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        path: { type: 'string' },
+        kind: { type: 'string' },
+      },
+      required: ['node', 'path'],
+    },
+    'delete',
+  )
+
+  /* ═══════════════════════════════════════════════════════════════════════
+   * 进程与端口诊断（2026-10-20，用户要求"更多工具 = 进程与端口诊断"）
+   * ═══════════════════════════════════════════════════════════════════════
+   *
+   * 为什么需要：远程排查时用户不在副机前面，看不见任务管理器。
+   * 这两天排查"副机连不上"，最耗时的几步全靠手工敲 netstat / Get-Process。
+   *
+   *   · `remote_ps`   —— 列进程（**只读**）
+   *   · `remote_port` —— 查端口占用（**只读**）
+   *   · `remote_kill` —— 杀进程（**不可逆** → 必须 confirm: 'yes'）
+   *
+   * ⚠ 这三个工具**不受 roots 约束**（进程没有路径概念）。kill 的护栏在
+   * 副机侧 `lib/node/process-service.js`：confirm + 拒杀自身/父进程/系统进程。
+   */
+  reg({
+    name: 'remote_ps',
+    description: '列出副机上的进程（PID / 名称 / 内存 / CPU 时间）。只读。'
+    + '用于排查"副机上到底跑着什么"、"那个卡住的进程还在不在"。'
+    + '可按进程名子串过滤。',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: nodeParam,
+        limit: { type: 'number', description: '最多返回多少个（1-1000，默认 200）。' },
+        filter: { type: 'string', description: '按进程名子串过滤（不区分大小写）。留空返回全部。' },
+      },
+      additionalProperties: false,
+    },
+    output: {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        platform: { type: 'string' },
+        processes: { type: 'array', items: { type: 'object' } },
+        truncated: { type: 'boolean' },
+      },
+      required: ['node'],
+    },
+    async execute(args) {
+      const nodeId = resolveNodeId(registry, args?.node)
+      const params = { ...(args ?? {}) }
+      delete params.node
+      try {
+        const result = await registry.fsRequest(nodeId, 'ps', 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 ps on ${nodeId} failed: ${String(err?.message ?? err)}`, code)
+      }
+    },
+  })
+
+  reg({
+    name: 'remote_port',
+    description: '查副机上某个端口的占用情况（谁在监听、谁在连接、对应 PID）。只读。'
+    + '用于排查"端口被占用"、"副机到底有没有在监听 19387"。',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: nodeParam,
+        port: { type: 'number', description: '要查的端口（1-65535）。' },
+      },
+      required: ['port'],
+      additionalProperties: false,
+    },
+    output: {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        port: { type: 'number' },
+        listeners: { type: 'array', items: { type: 'object' } },
+      },
+      required: ['node', 'port'],
+    },
+    async execute(args) {
+      const nodeId = resolveNodeId(registry, args?.node)
+      try {
+        const result = await registry.fsRequest(nodeId, 'port', { port: args?.port })
+        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 port on ${nodeId} failed: ${String(err?.message ?? err)}`, code)
+      }
+    },
+  })
+
+  reg({
+    name: 'remote_kill',
+    description: '杀掉副机上的一个进程（**不可逆**）。**必须传 confirm: "yes"**。'
+    + '副机侧有三道保护：拒绝杀本插件进程、拒绝杀其父进程（通常是 DSH 本体）、'
+    + '拒绝杀系统关键进程（System/csrss/wininit/services/lsass 等）。'
+    + '杀掉副机的 DSH 会让它彻底失联 —— 除非你确实无法通过其它方式恢复，否则不要这样做。',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: nodeParam,
+        pid: { type: 'number', description: '要杀的进程 PID（正整数）。先用 remote_ps 确认它是什么。' },
+        confirm: confirmParam,
+      },
+      required: ['pid', 'confirm'],
+      additionalProperties: false,
+    },
+    output: {
+      type: 'object',
+      properties: {
+        node: { type: 'string' },
+        ok: { type: 'boolean' },
+        pid: { type: 'number' },
+        name: { type: 'string' },
+      },
+      required: ['node', 'ok', 'pid'],
+    },
+    async execute(args) {
+      if (args?.confirm !== 'yes') {
+        throw new RemoteAgentError(
+          'remote_kill 会终止副机上的进程（不可逆）。请在参数里显式传 confirm: "yes"。',
+          ERROR_CODE.WORKSPACE_DENIED,
+        )
+      }
+      const nodeId = resolveNodeId(registry, args?.node)
+      try {
+        const result = await registry.fsRequest(nodeId, 'kill', {
+          pid: args?.pid,
+          confirm: 'yes',
+        })
+        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 kill on ${nodeId} failed: ${String(err?.message ?? err)}`, code)
+      }
+    },
+  })
+
   return disposers
 }
 

package/lib/hub/ui-routes.js

@@ -80,6 +80,7 @@
  * 因为创建空目录不是数据泄漏，而写入越界文件才是。见 `resolvePullDest()`。
  */
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { ERROR_CODE, RemoteAgentError, TASK_MODE } from '../protocol.js'
 // 分模式默认超时（提案 #26-1）：与 remote_task 工具同源常量。
@@ -107,6 +108,14 @@ import { envChecks } from '../env-check.js'
 // 角色解析**只有一份实现**：v0.9.0 起默认 role 是 'auto'，凡是判定
 // "是不是 hub" 的地方都必须过这一层（v0.9.0 审查 H1 的根因就是这里漏了）。
 import { resolveRole } from '../index.js'
+// 一键修复（2026-10-20）：只改托管块 + 备份 + 写后校验 + 可撤销。
+// 用户此前说过"不要改 DSH"，所以这个模块的每道防线都对应一次真实事故。
+import { applyFixPlan, isManagedBackup, listBackups, planFixes, undoFix } from '../auto-fix.js'
+// 外部工具检测（2026-10-20）：探测 Tailscale/PowerShell/git/node 在不在，
+// 缺了给"为什么需要 + 官方链接 + 安装命令"，**不代下载**。
+import { probeExternalTools } from '../external-tools.js'
+// 写盘器：自带备份 + 冲突检测 + 写后校验 + 失败回滚（与 setup 向导共用同一份）。
+import { writePatchBlock } from '../setup.js'
 
 export const UI_API_PREFIX = '/api/remote-agent/ui'
 
@@ -324,6 +333,21 @@ export function registerUiRoutes({
   const disposers = []
   const guard = makeGuard(ctx, log)
 
+  /**
+   * 当前 profile 的 cordis.patch.yml 绝对路径（与 setup-routes 同口径）。
+   *
+   * 一键修复要改的就是这个文件。判定方式与 `lib/setup-routes.js` 的
+   * `currentPatchFile()` **完全一致** —— 两处不一致会让"面板显示改的是 A、
+   * 实际写的是 B"，是最难排查的一类错。
+   */
+  const currentPatchFile = () => {
+    const raw = typeof process.env.DSH_PROFILE === 'string' && process.env.DSH_PROFILE.trim() !== ''
+      ? process.env.DSH_PROFILE.trim()
+      : 'desktop'
+    const safe = raw.replace(/[^A-Za-z0-9._-]/g, '')
+    return path.join(os.homedir(), '.dsh', 'profiles', safe === '' ? 'desktop' : safe, 'cordis.patch.yml')
+  }
+
   /** 取当前可达性结论：getter 优先，静态快照兜底（兼容老调用方/测试）。 */
   const reachOf = () => {
     if (typeof getReachability === 'function') {
@@ -788,6 +812,164 @@ export function registerUiRoutes({
     writeJson(res, 200, result)
   })
 
+  // ── 一键修复（2026-10-20，用户要求）──────────────────────────────
+  //
+  // ⚠⚠ **这会改 `<profile>/cordis.patch.yml`** —— DSH 自己的配置文件。
+  // 用户此前明确说过「不要改 DSH」，所以这里的每一道防线都是**踩过的坑**：
+  //
+  //   · 我们手写过 `host: '0.0.0.0'` → DSH 启动崩溃（10 份 crash 日志）
+  //   · 我们追加过 remote-agent 段 → 被 DSH 下次启动重写冲掉
+  //
+  // 防线（缺一不可）：
+  //   1. `POST` 必须带 `confirm: 'yes'` —— 缺了直接 400，没有默认通过
+  //   2. `action: 'plan'` 是**只读**的，先让用户看清"将要改什么"
+  //   3. 写盘走 `writePatchBlock` —— 它自带备份 + 冲突检测 + 写后校验 + 回滚
+  //   4. 只改**托管块**，用户手写的其它条目一个字节不碰
+  //   5. 写后本模块再校验一遍（重复 id / 条目缺失 → 提示用「撤销」）
+  //   6. `action: 'undo'` 用备份覆盖回去 —— 一键回滚
+  //
+  // **只修机械可判定的项**（webserver host / role）。端口占用、防火墙、
+  // 装软件、模型凭证这些需要人判断的，只给建议不动手。
+  route(`${UI_API_PREFIX}/fix`, async (req, res) => {
+    if (req.method !== 'POST') return writeJson(res, 405, { error: 'method' })
+    const body = await readJson(req)
+    const action = typeof body?.action === 'string' ? body.action : ''
+
+    // ── 只读：生成修复计划 ─────────────────────────────────────────
+    if (action === 'plan') {
+      try {
+        const nodes = registry.list()
+        const env = envChecks({
+          role: resolveRole(config) || 'hub',
+          config,
+          reachability: reachOf(),
+          nodesOnline: nodes.filter((n) => n.online).length,
+        })
+        const plan = planFixes({
+          envCheck: env,
+          patchFile: currentPatchFile(),
+          listenHost: typeof config.listenHost === 'string' ? config.listenHost : '',
+        })
+        // 附上可撤销的备份列表（用户改坏了能回退）
+        plan.backups = listBackups(path.dirname(plan.file), 5)
+        return writeJson(res, 200, { ok: true, plan })
+      } catch (err) {
+        return writeJson(res, 200, { ok: false, error: shortMessage(err) })
+      }
+    }
+
+    // ── 写盘：应用修复 ─────────────────────────────────────────────
+    if (action === 'apply') {
+      // ⚠ 二次确认是**硬要求**：这是唯一会改用户 DSH 配置的动作
+      if (body?.confirm !== 'yes') {
+        return writeJson(res, 400, {
+          error: 'confirm-required',
+          message: '一键修复会改 profile 的 cordis.patch.yml（DSH 自己的配置文件）。'
+            + '请先在面板上确认"将要改什么"，然后带 confirm: "yes" 重试。',
+        })
+      }
+      try {
+        const nodes = registry.list()
+        const env = envChecks({
+          role: resolveRole(config) || 'hub',
+          config,
+          reachability: reachOf(),
+          nodesOnline: nodes.filter((n) => n.online).length,
+        })
+        const plan = planFixes({
+          envCheck: env,
+          patchFile: currentPatchFile(),
+          listenHost: typeof config.listenHost === 'string' ? config.listenHost : '',
+        })
+        const role = resolveRole(config) || 'hub'
+        const result = applyFixPlan({
+          plan,
+          writePatchBlock,
+          readFile: (f) => fs.readFileSync(f, 'utf8'),
+          role,
+        })
+        if (result.ok === true) {
+          log('info', 'auto-fix applied', {
+            file: result.file,
+            backup: result.backup,
+            applied: result.applied,
+          })
+        } else {
+          log('warn', 'auto-fix failed', { file: result.file, error: result.error })
+        }
+        return writeJson(res, 200, {
+          ok: result.ok === true,
+          file: result.file,
+          backup: result.backup,
+          applied: result.applied,
+          error: result.error || null,
+          // 改完必须重启才生效（配置在启动时读取）
+          note: result.ok === true ? '已写入。**重启 DSH 后生效**。' : null,
+        })
+      } catch (err) {
+        return writeJson(res, 200, { ok: false, error: shortMessage(err) })
+      }
+    }
+
+    // ── 撤销：用备份覆盖回去 ───────────────────────────────────────
+    if (action === 'undo') {
+      if (body?.confirm !== 'yes') {
+        return writeJson(res, 400, { error: 'confirm-required', message: '撤销会覆盖当前配置文件，请带 confirm: "yes" 重试。' })
+      }
+      const backup = typeof body?.backup === 'string' ? body.backup : ''
+      const file = currentPatchFile()
+      // 安全：备份必须在我们管理的命名空间里（防任意文件覆盖）
+      if (!isManagedBackup(path.basename(backup))) {
+        return writeJson(res, 400, { error: 'bad-backup', message: '备份文件名不符合预期（应为 cordis.patch.yml.bak-*）' })
+      }
+      // 且必须与目标文件同目录（防路径穿越到别处）
+      if (path.dirname(path.resolve(backup)) !== path.dirname(path.resolve(file))) {
+        return writeJson(res, 400, { error: 'bad-backup', message: '备份必须与配置文件在同一目录' })
+      }
+      const result = undoFix({ file, backup })
+      if (result.ok === true) {
+        log('info', 'auto-fix undone', { file, backup })
+      }
+      return writeJson(res, 200, { ok: result.ok === true, error: result.error || null })
+    }
+
+    return writeJson(res, 400, { error: 'bad-action', message: 'action 必须是 plan / apply / undo' })
+  })
+
+  // ── 外部工具检测（2026-10-20）──────────────────────────────────
+  //
+  // 用户要求"自动装依赖"，我们把范围收窄到**外部工具**，且**不代下载**：
+  //   · 零 npm 依赖是核心卖点 —— 代装 npm 包会自毁卖点
+  //   · 代下载第三方二进制会让我们变成软件分发方（版本/来源/校验/责任/
+  //     供应链攻击面全落在我们头上）
+  //
+  // 所以这里只做三件事：探测在不在、说清缺了会怎样、给官方链接与安装命令。
+  route(`${UI_API_PREFIX}/tools`, (req, res) => {
+    if (req.method !== 'GET') return writeJson(res, 405, { error: 'method' })
+    try {
+      const r = probeExternalTools()
+      writeJson(res, 200, {
+        ok: true,
+        platform: r.platform,
+        tools: r.tools.map((t) => ({
+          id: typeof t.id === 'string' ? t.id : '',
+          name: typeof t.name === 'string' ? t.name : '',
+          installed: t.installed === true,
+          version: typeof t.version === 'string' ? t.version : '',
+          required: t.required === true,
+          why: typeof t.why === 'string' ? t.why : '',
+          install: typeof t.install === 'string' ? t.install : '',
+          url: typeof t.url === 'string' ? t.url : '',
+        })),
+        missing: r.missing.map((t) => t.id),
+        requiredMissing: r.requiredMissing.map((t) => t.id),
+      })
+    } catch (err) {
+      log('warn', 'tool probe failed', { error: shortMessage(err) })
+      writeJson(res, 200, { ok: false, error: shortMessage(err), tools: [], missing: [], requiredMissing: [] })
+    }
+  })
+
   // ── 工作区 SMB 共享（2026-10-17）──────────────────────────────
   //
   // 用户需求：想用本地 IDE 直接打开副机的项目目录 —— 唯一现实路径是把工作区