dsh-remote-agent 0.9.6 → 0.9.8

package/lib/client.js

@@ -163,6 +163,30 @@ window.__ModuleLoader__.load({
       // 模板库降级提示（文件坏了 / 读不了）：用 warn 的视觉语言，不是错误
       '.dra-tplnote{font-size:11px;color:var(--dsw-alias-label-secondary);',
       'padding:2px 0 4px;flex:1 1 100%}',
+      // ── 可折叠区块（2026-10-20，UI 改进）──────────────────────────
+      //
+      // 问题：加了一键修复、外部工具、SMB 共享之后，面板区块到了 9 个
+      // （配置/体检/工具/配对/卡片/节点/共享/派发/任务），首屏被淹没 ——
+      // 用户打开面板先看到一堆"当前不需要"的东西。
+      //
+      // 做法：把"配置类"区块收进折叠面板，默认只展开**当前最需要的**：
+      //   · 没副机在线 → 展开"接入"
+      //   · 有副机在线 → 展开"任务"
+      //
+      // 用原生 <details>：零 JS 状态、可访问性好、无 hydration 问题。
+      '.dra-fold{border:1px solid var(--dsw-alias-border-l1);border-radius:8px;',
+      'margin:10px 0;background:var(--dsw-alias-bg-layer-1);overflow:hidden}',
+      '.dra-fold>summary{padding:8px 12px;cursor:pointer;font-size:12px;',
+      'font-weight:600;color:var(--dsw-alias-label-secondary);',
+      'list-style:none;user-select:none;display:flex;align-items:center;gap:6px}',
+      '.dra-fold>summary::-webkit-details-marker{display:none}',
+      '.dra-fold>summary::before{content:"▸";font-size:10px;opacity:.7;',
+      'transition:transform .12s}',
+      '.dra-fold[open]>summary::before{transform:rotate(90deg)}',
+      '.dra-fold>summary:hover{background:var(--dsw-alias-bg-layer-2)}',
+      '.dra-fold-b{padding:4px 12px 12px}',
+      // 折叠块里的小标题要更轻 —— 避免和区块标题抢视觉层级
+      '.dra-fold .dra-sec{margin:8px 0 4px;font-size:10px}',
     ].join('')
 
     /* ───────────────────────── 数据层 ───────────────────────── */
@@ -1093,6 +1117,82 @@ window.__ModuleLoader__.load({
           .then(function () { setEnvBusy(false) })
       }
 
+      // ── 一键修复状态（2026-10-20）────────────────────────────────────
+      //
+      // 三步流程，每一步都要用户看得见：
+      //   fixPlan === null   → 只显示「预览修复」按钮
+      //   fixPlan !== null   → 显示"将要改什么"，给「确认修复」
+      //   点确认后            → 写盘 + 写后校验 + 提示重启
+      const fixPlanS = React.useState(null)
+      const fixPlan = fixPlanS[0]
+      const setFixPlan = fixPlanS[1]
+      const fixBusyS = React.useState(false)
+      const fixBusy = fixBusyS[0]
+      const setFixBusy = fixBusyS[1]
+      const fixMsgS = React.useState('')
+      const fixMsg = fixMsgS[0]
+      const setFixMsg = fixMsgS[1]
+
+      /** 第一步：只读预览（不写任何文件）。 */
+      const previewFix = function () {
+        if (fixBusy) return
+        setFixBusy(true)
+        setFixMsg('')
+        apiPost('/fix', { action: 'plan' })
+          .then(function (r) {
+            if (r && r.ok) {
+              setFixPlan(r.plan || null)
+            } else {
+              setFixMsg((r && r.error) || '预览失败')
+            }
+          })
+          .catch(function (err) { setFixMsg('预览失败：' + ((err && err.message) || err)) })
+          .then(function () { setFixBusy(false) })
+      }
+
+      /** 第二步：确认后写盘（带 confirm: 'yes'）。 */
+      const applyFix = function () {
+        if (fixBusy) return
+        setFixBusy(true)
+        setFixMsg('')
+        apiPost('/fix', { action: 'apply', confirm: 'yes' })
+          .then(function (r) {
+            if (r && r.ok) {
+              setFixMsg('已修复：' + (r.applied || []).join(', ') + ' —— 重启 DSH 生效')
+              setFixPlan(null)
+              // 修完重新体检一次，让用户看到"确实好了"
+              runEnvCheck()
+            } else {
+              setFixMsg((r && r.error) || '修复失败')
+            }
+          })
+          .catch(function (err) { setFixMsg('修复失败：' + ((err && err.message) || err)) })
+          .then(function () { setFixBusy(false) })
+      }
+
+      // ── 外部工具检测（2026-10-20）───────────────────────────────────
+      //
+      // 用户要求"自动装依赖"。我们把范围收窄到**外部工具**，且**不代下载**：
+      //   · 零 npm 依赖是核心卖点，代装 npm 包会自毁卖点
+      //   · 代下载第三方二进制会让我们变成软件分发方（供应链责任）
+      //
+      // 所以这里只做：探测 → 说清缺了会怎样 → 给官方链接 + 安装命令（可复制）。
+      const toolsS = React.useState(null)
+      const extTools = toolsS[0]
+      const setExtTools = toolsS[1]
+      const toolsBusyS = React.useState(false)
+      const toolsBusy = toolsBusyS[0]
+      const setToolsBusy = toolsBusyS[1]
+
+      const runToolProbe = function () {
+        if (toolsBusy) return
+        setToolsBusy(true)
+        apiGet('/tools')
+          .then(function (r) { setExtTools(r || null) })
+          .catch(function (err) { setNote('工具检测失败：' + ((err && err.message) || err)) })
+          .then(function () { setToolsBusy(false) })
+      }
+
       // 首次自动体检的闸门。用 ref（不是 state）—— 它只控制"要不要跑一次"，
       // 改了不需要重渲染。
       const autoChecked = React.useRef(false)
@@ -1607,6 +1707,14 @@ window.__ModuleLoader__.load({
           disabled: envBusy,
           onClick: runEnvCheck,
         }, envBusy ? '体检中…' : '体检'),
+        // ── 外部工具检测（2026-10-20）────────────────────────────────
+        //
+        // 不自动跑：每次要 spawn 4 个进程查版本。用户点了才查。
+        h('button', {
+          className: 'dra-btn',
+          disabled: toolsBusy,
+          onClick: runToolProbe,
+        }, toolsBusy ? '检测中…' : '检测工具'),
         // ── 清理任务视图 ─────────────────────────────────────────────
         //
         // 为什么面板上需要这个按钮：hub 侧任务视图会累积（副机的任务记录
@@ -1806,7 +1914,60 @@ window.__ModuleLoader__.load({
             (envCheck.failed === 0
               ? '核心项全部通过'
               : '共 ' + envCheck.failed + ' 项需要处理')
-            + (envCheck.autoFixable > 0 ? '（其中 ' + envCheck.autoFixable + ' 项修法机械，照抄即可）' : '')),
+            + (envCheck.autoFixable > 0 ? '（其中 ' + envCheck.autoFixable + ' 项修法机械，可一键修复）' : '')),
+          // ── 一键修复（2026-10-20）─────────────────────────────────
+          //
+          // ⚠ 这会改 profile 的 cordis.patch.yml（DSH 自己的配置文件）。
+          // 所以流程刻意做成**两步**：
+          //   1. 点「预览修复」→ 只读，列出"将要改什么"+"不会做什么"
+          //   2. 看清后点「确认修复」→ 才写盘（带 confirm: 'yes'）
+          //
+          // 写盘有备份 + 写后校验，改完给「撤销」按钮。
+          fixPlan !== null
+            ? h('div', { className: 'dra-warn', style: { marginBottom: '8px' } },
+              h('div', { style: { fontWeight: '600' } }, '将要修改 profile 配置（需重启生效）'),
+              h('div', { className: 'dra-dim', style: { marginTop: '4px' } }, '文件：' + (fixPlan.file || '')),
+              fixPlan.fixable.length > 0
+                ? h('div', { style: { marginTop: '4px' } },
+                  fixPlan.fixable.map(function (f) {
+                    return h('div', { key: f.id, className: 'dra-dim' }, '· ' + f.change)
+                  }))
+                : h('div', { className: 'dra-dim', style: { marginTop: '4px' } }, '没有可自动修的项。'),
+              // 明确列出"不会做什么"——比承诺做什么更重要
+              fixPlan.fixable.length > 0
+                ? h('div', { className: 'dra-dim', style: { marginTop: '4px' } },
+                  '只会改托管块里那几个字段，你的其它配置条目一个字节不动；'
+                  + '写前自动备份，改坏可一键撤销。')
+                : null,
+              fixPlan.skipped.length > 0
+                ? h('div', { className: 'dra-dim', style: { marginTop: '4px' } },
+                  '这些项需要你判断，不会自动改：' + fixPlan.skipped.map(function (s) { return s.label }).join('、'))
+                : null,
+              h('div', { className: 'dra-actions', style: { marginTop: '6px' } },
+                fixPlan.fixable.length > 0
+                  ? h('button', {
+                    className: 'dra-btn',
+                    disabled: fixBusy,
+                    onClick: function () { applyFix() },
+                  }, fixBusy ? '写入中…' : '确认修复')
+                  : null,
+                h('button', {
+                  className: 'dra-btn',
+                  onClick: function () { setFixPlan(null); setFixMsg('') },
+                }, '取消'),
+                fixMsg ? h('span', { className: 'dra-dim' }, fixMsg) : null,
+              ),
+            )
+            : (envCheck.failed > 0 || envCheck.autoFixable > 0)
+              ? h('div', { className: 'dra-actions', style: { marginBottom: '8px' } },
+                h('button', {
+                  className: 'dra-btn',
+                  disabled: fixBusy,
+                  onClick: function () { previewFix() },
+                }, fixBusy ? '检查中…' : '预览修复'),
+                h('span', { className: 'dra-dim' }, '只读预览 —— 先看要改什么，再决定'),
+              )
+              : null,
           (envCheck.items || []).map(function (it) {
             const mark = it.ok ? '✓' : (it.severity === 'warn' ? '⚠' : '✗')
             return h('div', { key: it.id, className: 'dra-env-item' },
@@ -1845,6 +2006,64 @@ window.__ModuleLoader__.load({
           }),
         )
 
+      // ── 外部工具（2026-10-20）──────────────────────────────────────
+      //
+      // 只在用户点了「检测工具」后显示（不自动跑：每次要 spawn 4 个进程）。
+      // 缺失的项给"为什么需要 + 安装命令（可复制）+ 官方链接"。
+      // **不代下载** —— 边界写在 lib/external-tools.js 头注释。
+      const toolsSection = extTools === null
+        ? null
+        : h('div', null,
+          h('div', { className: 'dra-sec' }, '外部工具'),
+          (extTools.tools || []).map(function (t) {
+            return h('div', { key: t.id, style: { marginBottom: '6px' } },
+              h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                h('span', {
+                  className: 'dra-mono',
+                  style: { color: t.installed ? 'var(--dsw-alias-state-success-primary, currentColor)' : 'var(--dsw-alias-state-warning-primary, currentColor)' },
+                }, t.installed ? '✓' : '⚠'),
+                h('span', { style: { flex: '1' } }, t.name + (t.required ? '（必需）' : '')),
+                t.installed
+                  ? h('span', { className: 'dra-dim' }, t.version)
+                  : h('span', { className: 'dra-dim' }, '未安装'),
+              ),
+              !t.installed
+                ? h('div', null,
+                  h('div', { className: 'dra-dim', style: { paddingLeft: '20px' } }, t.why),
+                  h('div', { className: 'dra-row', style: { paddingLeft: '20px', marginTop: '2px' } },
+                    t.install
+                      ? h('button', {
+                        className: 'dra-btn',
+                        style: { padding: '2px 8px', fontSize: '11px' },
+                        onClick: function () {
+                          copyText(t.install).then(function (ok) {
+                            setNote(ok ? '已复制安装命令' : '复制失败，请手动选中')
+                          })
+                        },
+                      }, '复制安装命令')
+                      : null,
+                    t.url
+                      ? h('button', {
+                        className: 'dra-btn',
+                        style: { padding: '2px 8px', fontSize: '11px' },
+                        onClick: function () {
+                          // 用系统浏览器打开官方下载页（不是我们代理下载）
+                          try { window.open(t.url, '_blank', 'noopener') } catch { setNote('打开失败：' + t.url) }
+                        },
+                      }, '官方下载页')
+                      : null,
+                    t.install
+                      ? h('span', { className: 'dra-dim dra-mono', style: { fontSize: '11px' } }, t.install)
+                      : null,
+                  ),
+                )
+                : null,
+            )
+          }),
+          h('div', { className: 'dra-dim', style: { marginTop: '4px' } },
+            '本插件不代下载第三方软件 —— 只告诉你缺什么、怎么装。'),
+        )
+
       const errBox = state.error
         ? h('div', { className: 'dra-err' }, '读取失败：' + state.error)
         : null
@@ -1940,6 +2159,34 @@ window.__ModuleLoader__.load({
           h('div', { className: 'dra-card-l' }, '任务总数')),
       )
 
+      // ── 可折叠区块（2026-10-20，UI 改进）──────────────────────────
+      //
+      // 加了一键修复 / 外部工具 / SMB 共享之后，面板区块到了 9 个，
+      // 首屏被淹没：用户打开面板先看到一堆"当前不需要"的东西。
+      //
+      // 用原生 `<details>`：
+      //   · 零 JS 状态（不用 React 管展开/收起）
+      //   · 可访问性好（键盘可操作、屏幕阅读器认）
+      //   · 无 hydration 问题
+      //
+      // 默认展开策略由调用方决定（见下面的 render）：
+      //   · 没副机在线 → 展开「接入与配置」（那是用户当下要解决的）
+      //   · 有副机在线 → 展开「任务」
+      const Fold = function (props) {
+        return h('details', {
+          className: 'dra-fold',
+          open: props.open === true,
+        },
+          h('summary', null,
+            h('span', null, props.title || ''),
+            props.badge
+              ? h('span', { className: 'dra-badge' }, props.badge)
+              : null,
+          ),
+          h('div', { className: 'dra-fold-b' }, props.children),
+        )
+      }
+
       // ── 节点 ──
       //
       // 空态不能只说"还没有节点接入"（2026-10-20，体验提升 ①）。
@@ -2458,18 +2705,41 @@ window.__ModuleLoader__.load({
         head,
         h('div', { className: 'dra-body' },
           errBox,
+          // ── 首屏只放"当前最需要的"（2026-10-20，UI 改进）─────────────
+          //
+          // 改动前：9 个区块全展开（配置/体检/工具/配对/卡片/节点/共享/
+          // 派发/任务），首屏被淹 —— 用户打开面板先看到一堆当前不需要的东西。
+          //
+          // 改动后：
+          //   · **错误与可达性横幅**永远在最上（那是必须立刻知道的）
+          //   · 有副机在线 → 先看任务；没副机 → 先看接入
+          //   · 配置/体检/工具/共享收进折叠块，需要时再展开
           reachBox,
-          cfgSection,
-          envSection,
-          pairSection,
           cards,
           nodeSection,
-          // 工作区共享（2026-10-17）：**放在派发表单之前** —— 它是"配好之后
-          // 想用本地 IDE 打开副机文件"的进阶需求，不该抢首屏位置，但也不该
-          // 埋在任务列表下面。二次确认在组件内部。
-          h(SharePanel, { nodes: state.nodes }),
+          // 任务区放在节点之后（有任务时它是主角）
+          taskSection,
           dispatchForm,
-          taskSection),
+          // ── 以下收进折叠块：配好之后很少再动 ──────────────────────
+          Fold({
+            title: '接入与配置',
+            open: state.nodes.length === 0,
+            children: h('div', null, cfgSection, pairSection),
+          }),
+          Fold({
+            title: '环境体检与工具',
+            // 有失败项时默认展开 —— 那说明确实需要处理
+            open: Boolean(envCheck && envCheck.failed > 0),
+            badge: envCheck && envCheck.failed > 0 ? String(envCheck.failed) : '',
+            children: h('div', null, envSection, toolsSection),
+          }),
+          // 工作区共享（2026-10-17）：**在派发表单之前**，但不抢首屏。
+          // 折叠默认收起 —— 它是"配好之后想用本地 IDE 打开副机文件"的进阶需求。
+          Fold({
+            title: '工作区共享（SMB）',
+            children: h('div', null, h(SharePanel, { nodes: state.nodes })),
+          }),
+        ),
       )
     }
 

package/lib/e2e.js

@@ -97,8 +97,49 @@ export function normalizeE2EPub(raw) {
   return raw
 }
 
+/**
+ * X25519 PKCS#8 私钥的 DER 前缀（16 字节）。
+ *
+ * 结构：SEQUENCE { INTEGER 0, SEQUENCE { OID 1.3.101.110 (X25519) },
+ *                OCTET STRING { OCTET STRING(32 字节原始标量) } }
+ * 后接 32 字节标量即完整私钥。
+ */
+const X25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex')
+
+/**
+ * 由 base64url 的 32 字节标量构造 X25519 私钥。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ⚠ 为什么用 DER 而不是 JWK（2026-10-20 CI 抓到的真实缺陷）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 原实现：`createPrivateKey({ key: { kty:'OKP', crv:'X25519', d: b64, x: '' }, format:'jwk' })`
+ *
+ * 在本地 Node 24.18 上能过，但在 GitHub Actions 的 `ubuntu-latest / node 24.x`
+ * 上抛 **`ERR_CRYPTO_INVALID_JWK`** —— 那个版本对 JWK 的 `x` 校验更严
+ * （空串不是合法 base64url；省略 `x` 同样被拒）。
+ *
+ * 后果很隐蔽：E2E 握手失败 → 测试只看到
+ * `timeout waiting for e2e session on test-worker`，**真因被完全掩盖**。
+ *
+ * ── 修法 ────────────────────────────────────────────────────────────────
+ *
+ * 直接用 **DER** 构造：X25519 私钥的 PKCS#8 就是固定 16 字节前缀 + 32 字节
+ * 标量。这条路径**不经过 JWK 校验**，跨 Node 小版本稳定。
+ *
+ * 实测验证：DER 构造出的私钥导出的公钥 `x` 与原始 JWK 完全一致，
+ * 且 DH 协商结果与正常生成的密钥对一致。
+ */
 function x2PrivateKeyFromB64(b64) {
-  return createPrivateKey({ key: { kty: 'OKP', crv: 'X25519', d: b64, x: '' }, format: 'jwk' })
+  const raw = Buffer.from(String(b64), 'base64url')
+  if (raw.length !== X2_PUB_BYTES) {
+    throw new Error(`bad x25519 private key length: ${raw.length} (expect ${X2_PUB_BYTES})`)
+  }
+  return createPrivateKey({
+    key: Buffer.concat([X25519_PKCS8_PREFIX, raw]),
+    format: 'der',
+    type: 'pkcs8',
+  })
 }
 
 function x2PublicKeyFromB64(b64) {

package/lib/external-tools.js

@@ -0,0 +1,238 @@
+/**
+ * 外部工具检测（2026-10-20，用户要求的"自动装依赖"）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 边界：**检测 + 给命令，不代下载**
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 用户原话是"自动装依赖"，但我们把范围收窄到"**外部工具**"，并且
+ * **不代下载**。理由（用户此前也确认过这条边界）：
+ *
+ *   · 本插件的核心卖点是**零 npm 依赖** —— 代装 npm 包会自毁卖点
+ *   · 代下载第三方二进制会让我们变成软件分发方：
+ *     装哪个版本、从哪下、校验和怎么保证、装失败算谁的、供应链攻击面
+ *     —— 全落在我们头上
+ *
+ * 所以本模块做三件事：
+ *   1. **探测**这些工具在不在（不执行它们做实际工作，只查版本）
+ *   2. **说清缺了会怎样**（用户才能判断要不要装）
+ *   3. **给官方下载链接 + 安装命令**（用户自己决定、自己执行）
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么这些工具值得检测
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 都是"**缺了会静默失败或体验大幅退化**"的那类：
+ *
+ *   · **Tailscale** —— 跨网场景的唯一现实路径。缺了副机连不上，
+ *     而错误表现是"连接超时"，用户根本想不到是缺个 VPN 工具。
+ *   · **PowerShell** —— Windows 上 SMB 共享、部分 exec 任务依赖它。
+ *     缺了表现为"命令找不到"，很难归因。
+ *   · **git** —— 仓库感知调度（提案 #13）依赖它。缺了只是少个功能，
+ *     但用户不知道为什么 repo 路由不生效。
+ *   · **Node.js** —— 插件本身跑在 DSH 里（DSH 自带），但副机侧某些
+ *     headless 场景要独立的 node。缺了报错很难懂。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 探测方式：只查版本，不做事
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 每个工具跑 `<tool> --version`（或等价），超时 3 秒。
+ * **不传任何用户输入**，命令是写死的常量 —— 没有注入面。
+ */
+
+import { spawnSync } from 'node:child_process'
+
+/**
+ * 工具清单。
+ *
+ * 字段说明：
+ *   · `required`：缺了核心功能不可用（true）还是只是功能退化（false）
+ *   · `why`：缺了会怎样 —— 用户据此判断要不要装
+ *   · `install`：**给用户复制粘贴的命令**（我们不执行它）
+ *   · `url`：官方下载页
+ */
+const TOOLS = Object.freeze([
+  {
+    id: 'tailscale',
+    name: 'Tailscale',
+    // 探测命令：`tailscale version` 输出形如 `1.62.0\n  go1.21`
+    probe: { cmd: 'tailscale', args: ['version'], timeoutMs: 3000 },
+    required: false,
+    why: '跨网（不在同一局域网）时的推荐路径。缺了副机连不上，'
+      + '而错误表现只是"连接超时"，很难想到是缺个 VPN 工具。'
+      + '同一局域网可以不用它。',
+    install: {
+      win: 'winget install --id Tailscale.Tailscale -e',
+      mac: 'brew install --cask tailscale',
+      linux: 'curl -fsSL https://tailscale.com/install.sh | sh',
+    },
+    url: 'https://tailscale.com/download',
+  },
+  {
+    id: 'powershell',
+    name: 'PowerShell',
+    // Windows 上叫 powershell / pwsh；非 Windows 上可能没有
+    probe: { cmd: process.platform === 'win32' ? 'powershell' : 'pwsh', args: ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.Major'], timeoutMs: 4000 },
+    required: process.platform === 'win32',
+    why: 'Windows 上的 SMB 共享、部分 exec 任务依赖它。缺了表现为"命令找不到"，很难归因。',
+    install: {
+      win: '（Windows 自带；若缺失说明系统组件被裁剪）',
+      mac: 'brew install --cask powershell',
+      linux: 'https://learn.microsoft.com/powershell/scripting/install/installing-powershell',
+    },
+    url: 'https://learn.microsoft.com/powershell/scripting/install/installing-powershell',
+  },
+  {
+    id: 'git',
+    name: 'git',
+    probe: { cmd: 'git', args: ['--version'], timeoutMs: 3000 },
+    required: false,
+    why: '仓库感知调度（remote_task 的 repo 参数）依赖它扫描副机上的仓库。'
+      + '缺了只是少这个功能，但用户不知道为什么 repo 路由不生效。',
+    install: {
+      win: 'winget install --id Git.Git -e',
+      mac: 'brew install git',
+      linux: 'sudo apt install git   # 或 dnf / pacman',
+    },
+    url: 'https://git-scm.com/downloads',
+  },
+  {
+    id: 'node',
+    name: 'Node.js',
+    probe: { cmd: 'node', args: ['--version'], timeoutMs: 3000 },
+    required: false,
+    why: '插件本身跑在 DSH 里（DSH 自带 node），但副机的 headless 后端'
+      + '要一个独立的 node 才能 spawn 子进程。缺了 agent 模式会退化。',
+    install: {
+      win: 'winget install --id OpenJS.NodeJS.LTS -e',
+      mac: 'brew install node@22',
+      linux: 'https://nodejs.org/en/download',
+    },
+    url: 'https://nodejs.org/en/download',
+  },
+])
+
+/** 当前平台的安装命令键。 */
+function platformKey() {
+  if (process.platform === 'win32') return 'win'
+  if (process.platform === 'darwin') return 'mac'
+  return 'linux'
+}
+
+/**
+ * 探测单个工具。
+ *
+ * @returns {{id:string, name:string, installed:boolean, version:string, error:string}}
+ */
+function probeTool(tool) {
+  const base = { id: tool.id, name: tool.name, installed: false, version: '', error: '' }
+  try {
+    const r = spawnSync(tool.probe.cmd, tool.probe.args, {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: tool.probe.timeoutMs,
+      // 不继承用户 shell 的 alias / 函数 —— 只跑真实可执行文件
+      shell: false,
+    })
+    if (r.error) {
+      // ENOENT = 没装，这是最常见的情形，不算"错误"
+      base.error = r.error.code === 'ENOENT' ? '' : String(r.error.message ?? r.error)
+      return base
+    }
+    if (r.status !== 0) {
+      base.error = `退出码 ${r.status}`
+      return base
+    }
+    const out = String(r.stdout ?? '').trim()
+    if (out === '') {
+      base.error = '没有输出'
+      return base
+    }
+    base.installed = true
+    // 只取第一行、截断 —— 版本串不需要整段
+    base.version = out.split(/\r?\n/)[0].slice(0, 60)
+    return base
+  } catch (err) {
+    base.error = String(err?.message ?? err)
+    return base
+  }
+}
+
+/**
+ * 探测所有外部工具。
+ *
+ * @param {object} [o]
+ * @param {boolean} [o.onlyMissing] 只返回缺失的（面板用，省流量）
+ * @returns {{platform:string, tools:Array, missing:Array, requiredMissing:Array}}
+ */
+export function probeExternalTools({ onlyMissing = false } = {}) {
+  const pk = platformKey()
+  const tools = []
+  for (const t of TOOLS) {
+    const p = probeTool(t)
+    const entry = {
+      id: p.id,
+      name: p.name,
+      installed: p.installed,
+      version: p.version,
+      required: t.required,
+      // 缺了会怎样 —— 这是用户判断"要不要装"的唯一依据
+      why: t.why,
+      // 安装命令（**给用户复制，我们不执行**）
+      install: t.install[pk] ?? '',
+      url: t.url,
+      error: p.error,
+    }
+    if (onlyMissing && entry.installed) continue
+    tools.push(entry)
+  }
+  const missing = tools.filter((t) => !t.installed)
+  return {
+    platform: process.platform,
+    tools,
+    missing,
+    requiredMissing: missing.filter((t) => t.required),
+  }
+}
+
+/**
+ * 把探测结果渲染成人读文本（命令行用）。
+ */
+export function renderExternalTools(result) {
+  const lines = ['外部工具检测', '']
+  if (!result || !Array.isArray(result.tools) || result.tools.length === 0) {
+    lines.push('（未探测到任何工具）')
+    return lines.join('\n')
+  }
+  for (const t of result.tools) {
+    const mark = t.installed ? '✓' : (t.required ? '✗' : '⚠')
+    const ver = t.installed && t.version !== '' ? `  ${t.version}` : ''
+    lines.push(`${mark} ${t.name}${ver}`)
+    if (!t.installed) {
+      if (t.why) lines.push(`    ${t.why}`)
+      if (t.install) lines.push(`    安装：${t.install}`)
+      if (t.url) lines.push(`    下载：${t.url}`)
+    }
+  }
+  lines.push('')
+  if (result.requiredMissing.length === 0) {
+    lines.push('必需工具都在。')
+  } else {
+    lines.push(`缺少 ${result.requiredMissing.length} 个必需工具：${result.requiredMissing.map((t) => t.name).join(', ')}`)
+  }
+  return lines.join('\n')
+}
+
+/** 导出清单（测试与面板共用，避免两处写死）。 */
+export function toolCatalog() {
+  const pk = platformKey()
+  return TOOLS.map((t) => ({
+    id: t.id,
+    name: t.name,
+    required: t.required,
+    why: t.why,
+    install: t.install[pk] ?? '',
+    url: t.url,
+  }))
+}