dsh-paoding 0.3.10 → 0.4.1

package/tools/lib/health.mjs

@@ -0,0 +1,298 @@
+/**
+ * 结构化配置体检（save-time config health check）：把散落在生成期 console.warn
+ * 里的告警（fork+model 互斥、roles_remove 命中 start_mode 等）与「配置了但宿主
+ * 未挂载」「零工具角色」「未知模型」「预设漂移」四类静默问题收口成
+ * { items: [{ level: 'error'|'warn'|'info', code, message }] }，随面板 preview /
+ * apply 响应的 warnings 字段与 CLI --dry-run 报告透传（面板渲染由客户端批次做，
+ * 本模块只负责产出结构化字段）。
+ *
+ * 检查项一览（每项一个独立函数，可单测）：
+ *   - unmounted_tool (warn)：assignments 配置的具体工具名（roles.*.tools 与
+ *     main_agent_extra）不在 presetUniverse ∪ inventory。白名单语义与生成层
+ *     filterUsableTools 同源（不另立判断，防两处漂移）；含 `*`/`?` 的条目跳过
+ *     （glob 支持由另一批次实现，这里不抢）。
+ *   - zero_tool_role (error)：内置角色过滤后 allow 为空（提前给可读信息；
+ *     composeGenerated 的既有 throw 行为不变，体检在前、throw 兜底）；自定义
+ *     角色 tools 为空同口径（renderCustomRoleBlocks 的 throw 同样不动）。
+ *   - unknown_model (warn)：roles.*.model 配了但模型目录（models，可选）查无
+ *     此名；models 为 null（CLI / 面板模型目录拿不到）时整项跳过。
+ *   - preset_drift (info)：已安装预设与当前配置的再生成结果不一致（复用
+ *     generateAndInstall 的 dryRun 产物文本对比；dryRunResult 已由调用方传入时
+ *     直接消费，不再重跑生成）。
+ *   - generation (warn)：生成期 warn 原样透传（captureWarnings 接管 console.warn
+ *     抓取 warning: 前缀行），不重复实现判定逻辑。
+ *
+ * 依赖 util（ROLES）、compose（filterUsableTools）、state（generateAndInstall，
+ * 仅在未拿到 dryRunResult 时做一次 dry-run 预演）；被 api-core / cli / doctor
+ * 引用。healthCheck 自身绝不 throw——体检坏了不该连带请求 500。
+ */
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { ROLES } from './util.mjs'
+import { filterUsableTools } from './compose.mjs'
+import { generateAndInstall } from './state.mjs'
+
+const WARN_PREFIX = 'warning: '
+
+/**
+ * 临时接管 console.warn，收集窗口期内所有告警行。返回 [fn() 结果, 消息数组]；
+ * 消息剥掉 util.warn 的 `warning: ` 前缀（透传给结构化 items 的 message 用）。
+ * 非字符串参数取 message 字段或 String() 兜底；finally 里必还原，fn 抛错也
+ * 不吞——需要「抓告警 + 容错」的调用方自己包 try/catch（见 installAssignments）。
+ */
+export function captureWarnings(fn) {
+  const messages = []
+  const original = console.warn
+  console.warn = (...args) => {
+    const text = args.map((a) => (typeof a === 'string' ? a : String(a?.message ?? a))).join(' ')
+    messages.push(text.startsWith(WARN_PREFIX) ? text.slice(WARN_PREFIX.length) : text)
+  }
+  let result
+  try {
+    result = fn()
+  } finally {
+    console.warn = original
+  }
+  return [result, messages]
+}
+
+/** 体检结果条目工厂：统一形状，防各检查项字段漂移。 */
+function item(level, code, message) {
+  return { level, code, message }
+}
+
+/**
+ * presetUniverse（restrict.mjs 主 agent 白名单 ∪ 源 preset 各角色 allow 自带面），
+ * 与 composeGenerated 同一构造。state 必须是原始 collectState 产物（blocks 是
+ * Map）——序列化视图喂进来 blocks 不可枚举时按空面兜底（结果只会多报
+ * unmounted_tool warn，不会误报 error）。
+ */
+function presetUniverseOf(state) {
+  const universe = new Set(Array.isArray(state.restrictBase) ? state.restrictBase : [])
+  if (state.blocks instanceof Map) {
+    for (const block of state.blocks.values()) {
+      for (const name of block.names) universe.add(name)
+    }
+  }
+  return universe
+}
+
+/** inventory 兜底：原始 state 是 Set；容一个数组形态（序列化视图误入时）。 */
+function inventoryOf(state) {
+  return state.inventory instanceof Set
+    ? state.inventory
+    : new Set(Array.isArray(state.inventory) ? state.inventory : [])
+}
+
+/** assignments 里配置的具体工具名 → [{ name, where }]（roles.*.tools + main_agent_extra）。 */
+function configuredToolRefs(assignments) {
+  const refs = []
+  const roles = assignments && typeof assignments.roles === 'object' && assignments.roles !== null ? assignments.roles : {}
+  for (const [role, conf] of Object.entries(roles)) {
+    if (!conf || typeof conf !== 'object') continue
+    const tools = Array.isArray(conf.tools) ? conf.tools : []
+    for (const tool of tools) {
+      if (typeof tool === 'string' && tool !== '') refs.push({ name: tool, where: `roles.${role}.tools` })
+    }
+  }
+  const extra = Array.isArray(assignments?.main_agent_extra) ? assignments.main_agent_extra : []
+  for (const tool of extra) {
+    if (typeof tool === 'string' && tool !== '') refs.push({ name: tool, where: 'main_agent_extra' })
+  }
+  return refs
+}
+
+/** 收集 roles.*.model 引用（[{ toolName, model }]，trim 后非空才算配置了）。 */
+export function collectModelRefs(assignments) {
+  const refs = []
+  const roles = assignments && typeof assignments.roles === 'object' && assignments.roles !== null ? assignments.roles : {}
+  for (const [toolName, conf] of Object.entries(roles)) {
+    if (!conf || typeof conf !== 'object') continue
+    if (typeof conf.model === 'string' && conf.model.trim() !== '') {
+      refs.push({ toolName, model: conf.model.trim() })
+    }
+  }
+  return refs
+}
+
+// ── 检查项：unmounted_tool ──────────────────────────────────────────────────
+
+/**
+ * 配置了但当前未挂载（presetUniverse ∪ inventory 都查无）的工具名。可用性判定
+ * 直接复用生成层的 filterUsableTools（同一白名单语义，零漂移）；`*`/`?` 通配
+ * 条目跳过（glob 支持另一批次实现）。
+ */
+function checkUnmountedTools(refs, presetUniverse, inventory) {
+  const names = [...new Set(refs.map((r) => r.name))]
+  const kept = new Set(filterUsableTools(names, presetUniverse, inventory))
+  const items = []
+  const seen = new Set()
+  for (const { name, where } of refs) {
+    if (name.includes('*') || name.includes('?')) continue
+    if (kept.has(name)) continue
+    const key = `${name}\u0000${where}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    items.push(item('warn', 'unmounted_tool', `已配置但当前未挂载：${name}（${where}）`))
+  }
+  return items
+}
+
+// ── 检查项：zero_tool_role ──────────────────────────────────────────────────
+
+/**
+ * 过滤后工具为空的角色。意图（intent）取法与 composeGenerated 逐字对齐：
+ * 显式 `tools: []` 就按空算（不回落源模板 allow），只有键缺省才回落 blocks；
+ * 自定义角色不经过滤、tools 为空即零工具（与 renderCustomRoleBlocks 同口径）。
+ * 只产 error 条目，不在本层拦下生成——composeGenerated 的既有 throw 照旧兜底。
+ */
+function checkZeroToolRoles(assignments, state, presetUniverse, inventory) {
+  const items = []
+  const roles = assignments && typeof assignments.roles === 'object' && assignments.roles !== null ? assignments.roles : {}
+  const removedRoles = new Set(Array.isArray(assignments?.roles_remove) ? assignments.roles_remove : [])
+  const blocks = state.blocks instanceof Map ? state.blocks : null
+  for (const role of ROLES) {
+    if (removedRoles.has(role)) continue
+    const conf = roles[role] && typeof roles[role] === 'object' ? roles[role] : null
+    const intent = Array.isArray(conf?.tools) ? conf.tools : (blocks?.get(role)?.names ?? [])
+    if (filterUsableTools(intent, presetUniverse, inventory).length === 0) {
+      items.push(
+        item(
+          'error',
+          'zero_tool_role',
+          `角色 ${role} 过滤后没有任何可用工具（零工具角色会被拒绝安装）：` +
+            `请在配置里为它勾选至少一个已挂载工具，或加入 roles_remove 删除该角色`,
+        ),
+      )
+    }
+  }
+  for (const [toolName, conf] of Object.entries(roles)) {
+    if (ROLES.includes(toolName)) continue
+    const tools = Array.isArray(conf?.tools) ? conf.tools : []
+    if (tools.length === 0) {
+      items.push(
+        item(
+          'error',
+          'zero_tool_role',
+          `自定义角色 ${toolName} 没有配置任何工具（零工具角色会被拒绝安装）：请在配置里为它写 tools 列表`,
+        ),
+      )
+    }
+  }
+  return items
+}
+
+// ── 检查项：unknown_model ───────────────────────────────────────────────────
+
+/** 模型目录（面板 models 路由的 groups 形状）→ 已知模型 id 集合；容忍扁平 id 数组。 */
+function knownModelIds(models) {
+  const ids = new Set()
+  if (!Array.isArray(models)) return ids
+  for (const entry of models) {
+    if (typeof entry === 'string' && entry !== '') {
+      ids.add(entry)
+      continue
+    }
+    if (!entry || typeof entry !== 'object') continue
+    if (typeof entry.id === 'string' && entry.id !== '') ids.add(entry.id)
+    if (Array.isArray(entry.models)) {
+      for (const model of entry.models) {
+        if (typeof model === 'string' && model !== '') ids.add(model)
+        else if (model && typeof model.id === 'string' && model.id !== '') ids.add(model.id)
+      }
+    }
+  }
+  return ids
+}
+
+/** roles.*.model 配了但目录查无 → warn。models 为 null（拿不到目录）整项跳过。 */
+function checkUnknownModels(assignments, models) {
+  if (models === null || models === undefined) return []
+  const known = knownModelIds(models)
+  if (known.size === 0) return []
+  return collectModelRefs(assignments)
+    .filter(({ model }) => !known.has(model))
+    .map(({ toolName, model }) =>
+      item('warn', 'unknown_model', `roles.${toolName}.model: '${model}' 不在当前模型目录中（名单以设置页模型选择器为准，配错会被静默回落）`),
+    )
+}
+
+// ── 检查项：preset_drift ────────────────────────────────────────────────────
+
+/**
+ * 已安装预设 vs 再生成结果：对比 dryRunResult.text 与落盘的 agent.cordis.yml
+ * （按 dryRunResult.presetId 定位，工作区预设同样适用）。文本一致 → 无条目；
+ * 落盘文件缺失（未安装）→ info 条目提示应用后生成；内容有差 → info「落后于
+ * 配置」。拿不到 dryRunResult（调用方没生成过）时返回空，由调用方决定是否
+ * 先做 dry-run 预演再传入。
+ */
+function checkPresetDrift(state, dryRunResult) {
+  if (!dryRunResult || typeof dryRunResult.text !== 'string') return []
+  const presetId = typeof dryRunResult.presetId === 'string' && dryRunResult.presetId !== '' ? dryRunResult.presetId : 'orchestrator'
+  const dshHome = typeof state.dshHome === 'string' ? state.dshHome : null
+  if (!dshHome) return []
+  let installed = null
+  try {
+    installed = readFileSync(path.join(dshHome, '.agent-presets', presetId, 'agent.cordis.yml'), 'utf8')
+  } catch {
+    installed = null
+  }
+  if (installed === dryRunResult.text) return []
+  return [
+    item(
+      'info',
+      'preset_drift',
+      installed === null
+        ? `预设 ${presetId} 尚未安装：应用一次（面板「保存并应用」或 CLI --auto）即生成`
+        : `预设 ${presetId} 落后于配置，重新应用即同步`,
+    ),
+  ]
+}
+
+// ── 入口 ────────────────────────────────────────────────────────────────────
+
+/**
+ * 跑全套体检，返回 { items }。参数：
+ *   - state：原始 collectState 产物（restrictBase / blocks / inventory / dshHome）。
+ *   - assignments：待检的目标字段集合（配置面板提交形状或 loadConfig 产物）。
+ *   - models：模型目录（面板 models 路由的 groups 数组）；null = 跳过 unknown_model。
+ *   - dryRunResult：调用方已有的 generateAndInstall 产物（preview/apply 顺路传入，
+ *     不重跑生成）；null 时本函数自己跑一次 dry-run 预演（doctor / 直接调用）。
+ *   - generationWarnings：调用方在其生成窗口内用 captureWarnings 抓到的告警
+ *     （installAssignments 传入，避免同一次生成跑两遍）；null 且无 dryRunResult
+ *     时由本函数的预演自行抓取。
+ * 任何内部失败都折成条目（generation_error），本函数自身不 throw。
+ */
+export function healthCheck({ state, assignments, models = null, dryRunResult = null, generationWarnings = null } = {}) {
+  const items = []
+  if (!state || typeof state !== 'object') return { items }
+
+  const presetUniverse = presetUniverseOf(state)
+  const inventory = inventoryOf(state)
+
+  // 生成（或复用调用方产物）与生成期告警：三条互斥路径——
+  //   1) dryRunResult 已给 → 全复用，零重跑；
+  //   2) 只有 generationWarnings（原生成已失败，installAssignments 容错路径）
+  //      → 消费现成告警，不再重跑（失败场景重跑只会复现同一个错）；
+  //   3) 都没有 → 自己做一次 dry-run 预演并抓告警；预演失败折成 generation_error。
+  let result = dryRunResult
+  let warns = Array.isArray(generationWarnings) ? generationWarnings : null
+  if (result === null && warns === null) {
+    try {
+      const [ran, captured] = captureWarnings(() => generateAndInstall(state, assignments ?? {}, { dryRun: true }))
+      result = ran
+      warns = captured
+    } catch (err) {
+      items.push(item('error', 'generation_error', `生成预演失败：${err?.message ?? err}`))
+    }
+  }
+
+  items.push(...checkUnmountedTools(configuredToolRefs(assignments), presetUniverse, inventory))
+  items.push(...checkZeroToolRoles(assignments, state, presetUniverse, inventory))
+  items.push(...checkUnknownModels(assignments, models))
+  if (Array.isArray(warns)) {
+    for (const message of warns) items.push(item('warn', 'generation', message))
+  }
+  items.push(...checkPresetDrift(state, result))
+  return { items }
+}

package/tools/lib/upgrade.mjs

@@ -13,7 +13,10 @@
  *     profile 目录里直跑 `pnpm add dsh-paoding@<目标版本>`：本包已在 profile
  *     package.json 的 dsh.profile.bundles 清单里，无需 bundle reconcile；用
  *     精确版本而非 update，避开 pnpm 新鲜度防护 / 镜像 packument 滞后造成的
- *     静默空转。
+ *     静默空转。pnpm 本身按候选链解析（裸 pnpm → corepack pnpm → PNPM_HOME
+ *     常见落位，仅 ENOENT 换下一路）——corepack 管的机器没跑过 corepack
+ *     enable 时 PATH 里没有裸 pnpm，0.3.8~0.4.0 直 spawn 裸名即报
+ *     `spawn pnpm ENOENT`（0.4.1 修）。
  *
  * 本模块只负责「拿目标版本 → 探测自身 profile → 跑子进程」这一段编排；
  * profile 名从本文件运行时真实路径反推（registry 安装形态必然位于
@@ -77,7 +80,7 @@ function defaultSpawn(command, args, options, timeoutMs, timeoutLabel) {
     }, timeoutMs)
     child.on('error', (err) => {
       clearTimeout(timer)
-      resolve({ code: null, output: tailOutput(output), error: String(err?.message ?? err) })
+      resolve({ code: null, output: tailOutput(output), error: String(err?.message ?? err), errorCode: err?.code ?? null })
     })
     child.on('close', (code) => {
       clearTimeout(timer)
@@ -128,8 +131,10 @@ function desktopProfileDir() {
  *     node:child_process 的 spawn、Date.now()。
  *   - timeoutMs：升级子进程超时（含 pnpm 下载安装），默认 120s。
  *   - spawnImpl 契约：(command, args, options, timeoutMs, timeoutLabel) →
- *     Promise resolving { code, output, error? }（同 defaultSpawn 的收敛形状；
- *     timeoutLabel 仅缺省实现用于超时文案，注入桩可忽略）。
+ *     Promise resolving { code, output, error?, errorCode? }（同 defaultSpawn
+ *     的收敛形状；errorCode 为子进程 spawn 失败的 err.code，如 'ENOENT'，
+ *     desktop 分支据此走 pnpm 候选链回落；timeoutLabel 仅缺省实现用于超时
+ *     文案，注入桩可忽略）。
  * @returns {Promise<object>} 恒不抛错，收敛为：
  *   - { ok: true, upToDate: true, current }                    本地已不落后 registry
  *   - { ok: true, version, profile, output, elapsedMs }        升级成功（退出码 0）
@@ -193,19 +198,62 @@ async function doRunUpgrade({ profile, fetchImpl, spawnImpl, timeoutMs, now }) {
     return { ok: false, error: `desktop profile 目录不存在或未初始化: ${desktopDir}` }
   }
   const useShell = process.platform === 'win32'
-  const command = isDesktop ? (useShell ? 'pnpm.cmd' : 'pnpm') : useShell ? 'dsh.cmd' : 'dsh'
   const args = isDesktop
     ? ['add', `dsh-paoding@${targetVersion}`]
     : ['plugin', '--profile', resolved, 'update', 'dsh-paoding']
   const run = typeof spawnImpl === 'function' ? spawnImpl : defaultSpawn
-  const proc = await run(command, args, {
+  const spawnOptions = {
     cwd: isDesktop ? desktopDir : os.tmpdir(),
     env: process.env,
     stdio: ['ignore', 'pipe', 'pipe'],
     shell: useShell,
-  }, timeoutMs, isDesktop ? 'pnpm add' : 'dsh plugin update')
+  }
+
+  // pnpm/dsh 候选链：spawn ENOENT（命令在 PATH 里不存在）才换下一路，
+  // EACCES / 超时 / 退出码非 0 都是真实运行结果，如实返回不换通道。
+  //   - 裸 pnpm：npm i -g pnpm / homebrew 等常规安装直接命中；
+  //   - corepack pnpm：corepack 随 node 发行，node 在 PATH 就兜得住，
+  //     未 enable 也能即装即用（corepack pnpm add ...）；
+  //   - PNPM_HOME 常见落位（darwin ~/Library/pnpm、linux ~/.local/share/pnpm）
+  //     的绝对路径：pnpm 独立安装脚本形态，spawn 绝对路径不依赖 PATH；
+  //     existsSync 预筛，不存在不浪费一次 spawn。
+  // 常规 profile 的 dsh 单候选同走这套循环，ENOENT 也收敛成可读文案。
+  const suffix = useShell ? '.cmd' : ''
+  const candidates = isDesktop
+    ? [
+        { command: `pnpm${suffix}`, argsPrefix: [], label: 'pnpm' },
+        { command: `corepack${suffix}`, argsPrefix: ['pnpm'], label: 'corepack pnpm' },
+      ]
+    : [{ command: `dsh${suffix}`, argsPrefix: [], label: 'dsh' }]
+  if (isDesktop) {
+    const homes = [path.join(os.homedir(), 'Library', 'pnpm'), path.join(os.homedir(), '.local', 'share', 'pnpm')]
+    for (const home of homes) {
+      const bin = path.join(home, `pnpm${suffix}`)
+      if (existsSync(bin)) candidates.push({ command: bin, argsPrefix: [], label: bin })
+    }
+  }
+
+  let proc = null
+  for (const cand of candidates) {
+    proc = await run(cand.command, [...cand.argsPrefix, ...args], spawnOptions, timeoutMs,
+      isDesktop ? 'pnpm add' : 'dsh plugin update')
+    if (proc?.errorCode !== 'ENOENT') break
+  }
   const output = tailOutput(proc?.output)
 
+  // 全候选 ENOENT：给可操作的出路，不裸抛 spawn xxx ENOENT。
+  if (proc?.errorCode === 'ENOENT') {
+    const tried = candidates.map((c) => c.label).join(' / ')
+    return {
+      ok: false,
+      error: isDesktop
+        ? `未找到可用的 pnpm（已试 ${tried}）。可先在终端执行 corepack enable 并重启 DSH 后重试；或手动升级：cd ${desktopDir} && corepack pnpm add dsh-paoding@${targetVersion}`
+        : `未找到 dsh 命令（PATH 异常？已试 ${tried}），请检查 dsh 安装后重试`,
+      output,
+      elapsedMs: elapsedMs(),
+    }
+  }
+
   // ④ 无磁盘后验（旧 npx 时代读 $DSH_HOME/dsh-paoding 对账的方案已随该目录
   //    一并废弃）：本进程代码不随升级变化，无从对账；成功与否以退出码为准，
   //    新版本重启 DSH 后生效（preset 由新版启动钩子自动重生成）。