dsh-paoding 0.3.9 → 0.4.0

package/tools/lib/doctor.mjs

@@ -0,0 +1,245 @@
+/**
+ * `dsh-paoding doctor` 的检查本体：只读体检，不动任何盘。与 health.mjs 的分工
+ * ——healthCheck 管「这次保存/应用会怎样」（面向 preview / apply 响应与
+ * --dry-run 报告的单次配置体检）；本模块管「这台机器装得正不正」（配置文件、
+ * 预设安装轨道、托管声明行、孤儿工作区预设目录、版本标记、预设漂移六项环境
+ * 对账），结果形状是人读导向的 { items: [{ status, label, detail }] }：
+ *   status: 'ok' | 'warn' | 'error' | 'skip'（skip = 前置事实缺失，降级不炸——
+ *   无 DSH_HOME / 无配置的干净机器上各项依此跳过）。
+ *
+ * 有意与 healthCheck 解耦、不复用其返回形状： doctor 的每项都有自己的前置探测
+ * 与降级语义，硬塞进 level/code 模型只会两头别扭；仅「预设漂移」一项复用
+ * healthCheck 的 preset_drift 判定（同一份 dry-run 对比，不另立标准）。
+ *
+ * 依赖 config（loadConfig）/ yaml（loadYaml）/ alloc（autoAssignments）/
+ * state（collectState）/ workspaces（assignSlugs / presetIdOf）/
+ * preset-system（轨道、托管块、标记）与 health（healthCheck）；被 cli 引用。
+ * 零运行时依赖（node:fs / node:path / node:url）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { loadConfig } from './config.mjs'
+import { loadYaml } from './yaml.mjs'
+import { autoAssignments } from './alloc.mjs'
+import { collectState } from './state.mjs'
+import { assignSlugs, presetIdOf } from './workspaces.mjs'
+import {
+  MANAGED_BEGIN,
+  MANAGED_END,
+  detectHostVersionTriple,
+  detectPresetSystem,
+  isDeclarativeTriple,
+  isPtcWorkerHost,
+  listOrchestratorPresetIds,
+  parseGeneratorMarker,
+  readHomePatchRows,
+} from './preset-system.mjs'
+import { healthCheck } from './health.mjs'
+
+const TRACK_LABELS = { declarative: '声明行轨 (declarative，DSH ≥ 0.1.7)', directory: '目录轨 (directory，DSH ≤ 0.1.6)' }
+const trackLabel = (track) => TRACK_LABELS[track] ?? String(track ?? '未知')
+
+/** 插件包版本（doctor 跑在插件包内，package.json 就在仓库根；读失败返回 null）。 */
+function repoVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+    return typeof pkg?.version === 'string' && pkg.version !== '' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+function managedMarkerLines(text) {
+  return new Set(
+    String(text ?? '')
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+  )
+}
+
+/** 孤儿工作区预设目录对账：配置 workspaces 键组统一过 assignSlugs（与生成层
+ * 同源，slug 稳定），得到「配置在册」的 presetId 集合；目录有、名册无 → 孤儿。 */
+function workspacePresetOrphans(dshHome, config) {
+  const dirs = listOrchestratorPresetIds(dshHome).filter((id) => id !== 'orchestrator')
+  if (dirs.length === 0) return { dirs, orphans: [] }
+  const wsPaths = Object.keys(config?.workspaces ?? {})
+  const inRegister = new Set([...assignSlugs(wsPaths).values()].map(presetIdOf))
+  return { dirs, orphans: dirs.filter((id) => !inRegister.has(id)) }
+}
+
+/**
+ * 跑全套 doctor 检查。参数（全可缺省，干净机器上逐项降级）：
+ *   - dshHome / configFile：DSH 家目录与配置文件路径。
+ *   - profile：传给 collectState 的 patch 层（--profile，默认全缺省）。
+ *   - state：调用方已采集的原始 state（测试注入用）；缺省时内部 collectState。
+ *   - generatorVersion：标记对账基准；缺省读包内 package.json（测试可注入）。
+ * 返回 { items, hasErrors }；本函数自身绝不 throw——单项探测失败折成条目。
+ */
+export async function runDoctor({ dshHome, configFile, profile = null, state = null, generatorVersion = null } = {}) {
+  const items = []
+  const add = (status, label, detail) => items.push({ status, label, detail })
+  const version = generatorVersion ?? repoVersion()
+
+  // 0) state：漂移与轨道两项的公共前置。拿不到时这两项降级，其余照查。
+  let stateError = null
+  if (state === null) {
+    try {
+      state = await collectState({ dshHome, configFile, profile, cwd: process.cwd() })
+    } catch (err) {
+      state = null
+      stateError = err?.message ?? String(err)
+    }
+  }
+
+  // ── 1. 配置文件存在性 / 可解析性 ──────────────────────────────────────────
+  let config = null
+  let configUsable = false
+  if (!existsSync(configFile)) {
+    add('skip', '配置文件', `${configFile} 不存在（全新安装语义：首装自动化会写入基础模板，不处理）`)
+  } else {
+    try {
+      config = loadConfig(configFile, loadYaml(dshHome))
+      configUsable = true
+      add('ok', '配置文件', `${configFile} 存在且可解析`)
+    } catch (err) {
+      add('error', '配置文件', `${configFile} 无法解析：${err?.message ?? err}——请先修复（面板加载 / 生成都会被拒）`)
+    }
+  }
+
+  // ── 2. 预设安装轨道 vs 宿主版本 ───────────────────────────────────────────
+  const track = state?.presetSystem ?? (await detectPresetSystem({ dshHome }).catch(() => null))
+  const hostTriple = detectHostVersionTriple()
+  if (state === null && stateError !== null) {
+    add('skip', '预设安装轨道', `检测管线不可用（${stateError}），跳过轨道核对`)
+  } else if (hostTriple === null) {
+    add('warn', '预设安装轨道', `当前判定 ${trackLabel(track)}，但宿主版本探测不到（PATH 上没有可用的 dsh），无法交叉验证`)
+  } else {
+    const expected = isDeclarativeTriple(hostTriple) ? 'declarative' : 'directory'
+    const versionText = `${hostTriple[0]}.${hostTriple[1]}.${hostTriple[2]}`
+    if (expected === track) {
+      add('ok', '预设安装轨道', `宿主 ${versionText} ↔ ${trackLabel(track)}，一致`)
+    } else {
+      add('warn', '预设安装轨道', `宿主 ${versionText} 应走 ${TRACK_LABELS[expected]}，当前判定 ${trackLabel(track)}（下次 DSH 启动自愈会自动迁移）`)
+    }
+  }
+
+  // ── 3. 声明行托管块（~/.dsh/cordis.patch.yml）────────────────────────────
+  // readHomePatchRows 对损坏块自捕返 []，读不出「损坏」——这里直接扫标记行补一道：
+  // 有 BEGIN 没 END = 托管块损坏，所有托管写盘都会被拒绝。
+  let patchText = null
+  try {
+    patchText = readFileSync(path.join(dshHome, 'cordis.patch.yml'), 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') add('skip', '声明行托管块', 'cordis.patch.yml 不存在（尚无声明行；目录轨宿主也不需要）')
+    else add('skip', '声明行托管块', `cordis.patch.yml 读取失败（${err?.message ?? err}），跳过该项`)
+  }
+  if (patchText !== null) {
+    const markers = managedMarkerLines(patchText)
+    const hasBegin = markers.has(MANAGED_BEGIN)
+    const hasEnd = markers.has(MANAGED_END)
+    if (hasBegin && !hasEnd) {
+      add('error', '声明行托管块', '托管块损坏（只有起始标记没有结束标记）：补回结束标记或删除整块，否则面板保存 / 自愈都会拒绝写盘')
+    } else {
+      let rows = []
+      try {
+        rows = readHomePatchRows(dshHome)
+      } catch {
+        rows = []
+      }
+      if (rows.length === 0) {
+        add('ok', '声明行托管块', hasBegin ? '托管块存在但无声明行' : 'cordis.patch.yml 无托管块（目录轨宿主无需声明行）')
+      } else {
+        const orphans = rows.filter((row) => row.presetId && !existsSync(path.join(dshHome, '.agent-presets', row.presetId)))
+        if (track === 'directory') {
+          add('warn', '声明行托管块', `检出 ${rows.length} 条声明行，但宿主是目录轨（≤ 0.1.6）——残留声明行会让 profile 启动失败，重启 DSH 触发自愈撤下`)
+        } else if (orphans.length > 0) {
+          add('warn', '声明行托管块', `孤儿声明行（指向已删目录）：${orphans.map((o) => o.rowId).join('、')}——重启 DSH 自愈会撤下，或重新应用一次同步`)
+        } else {
+          add('ok', '声明行托管块', `${rows.length} 条声明行均指向存在的预设目录`)
+        }
+      }
+    }
+  }
+
+  // ── 4. 孤儿工作区预设目录（.agent-presets/orchestrator-*）─────────────────
+  if (!configUsable && existsSync(configFile)) {
+    add('skip', '工作区预设目录', '配置文件无法解析，无法对账（先修配置）')
+  } else {
+    const { dirs, orphans } = workspacePresetOrphans(dshHome, config)
+    if (dirs.length === 0) {
+      add('ok', '工作区预设目录', '无 orchestrator-<slug> 目录（未配置过工作区）')
+    } else if (!configUsable) {
+      add('warn', '工作区预设目录', `无配置文件可对账，以下目录全部视为孤儿：${dirs.join('、')}——重新应用可恢复，不用可手动删除`)
+    } else if (orphans.length === 0) {
+      add('ok', '工作区预设目录', `${dirs.length} 个工作区预设目录均在配置名册内`)
+    } else {
+      add('warn', '工作区预设目录', `孤儿目录（配置 workspaces 已无对应条目）：${orphans.join('、')}——下次「保存并应用」会自动回收，不用可手动删除`)
+    }
+  }
+
+  // ── 5. 版本标记对账（.generator-version：版本 + 轨道 + worker 形态）────────
+  const presetDir = path.join(dshHome, '.agent-presets', 'orchestrator')
+  if (!existsSync(presetDir)) {
+    add('skip', '版本标记', '基础预设未安装（无 orchestrator 目录）：首装自动化或「保存并应用」会生成')
+  } else {
+    let marker = null
+    try {
+      marker = parseGeneratorMarker(readFileSync(path.join(presetDir, '.generator-version'), 'utf8'))
+    } catch {
+      marker = null
+    }
+    if (marker === null) {
+      add('warn', '版本标记', '.generator-version 缺失或不可解析——下次 DSH 启动自愈会补一次生成（无伤大雅，多跑一遍而已）')
+    } else {
+      const parts = []
+      if (version !== null && marker.version !== version) {
+        parts.push(`标记版本 ${marker.version} ≠ 当前生成器 v${version}（下次启动自动按新版重生成）`)
+      }
+      if (marker.track !== null && track !== null && marker.track !== track) {
+        parts.push(`标记轨道 ${TRACK_LABELS[marker.track] ?? marker.track} 与当前 ${trackLabel(track)} 不符（下次启动自动迁移）`)
+      }
+      // worker 形态只与探测得到的宿主版本比（探测不到不猜，保守不报）。
+      if (marker.worker !== null && hostTriple !== null) {
+        const workerNow = isPtcWorkerHost(hostTriple) ? 'ptc' : 'worker-thread'
+        if (marker.worker !== workerNow) {
+          parts.push(`标记 worker 形态 ${marker.worker} 与宿主所需 ${workerNow} 不符（下次启动整盘重生成）`)
+        }
+      }
+      if (parts.length === 0) {
+        add('ok', '版本标记', `标记 ${marker.version}（${marker.track ?? '轨道未知'}）与当前生成器一致`)
+      } else {
+        add('warn', '版本标记', parts.join('；'))
+      }
+    }
+  }
+
+  // ── 6. 预设与配置漂移（复用 healthCheck 的 preset_drift，同一把尺子）────────
+  if (state === null) {
+    add('skip', '预设漂移', `检测管线不可用（${stateError ?? 'state 缺失'}），跳过该项`)
+  } else {
+    try {
+      const assignments = autoAssignments({
+        existing: state.existing,
+        suggested: state.suggested,
+        staticBase: state.staticBase,
+      })
+      const { items: healthItems } = healthCheck({ state, assignments })
+      let sawDrift = false
+      for (const h of healthItems) {
+        if (h.code === 'preset_drift') {
+          sawDrift = true
+          add('warn', '预设漂移', h.message)
+        } else if (h.level === 'error') {
+          add('error', '配置体检', h.message)
+        }
+      }
+      if (!sawDrift && !healthItems.some((h) => h.level === 'error')) {
+        add('ok', '预设漂移', '已安装预设与当前配置的再生成结果一致')
+      }
+    } catch (err) {
+      add('skip', '预设漂移', `体检执行失败，已跳过：${err?.message ?? err}`)
+    }
+  }
+
+  return { items, hasErrors: items.some((i) => i.status === 'error') }
+}

package/tools/lib/glob.mjs

@@ -0,0 +1,76 @@
+/**
+ * 工具条目通配符展开（生成期专用）：配置里的工具条目支持 `*`（任意长字符段，
+ * 可为空）与 `?`（恰一个字符）两个通配符 —— 够 MCP 工具族场景使用（如
+ * `mcp__tavily__tavily_*` 展开为 search/crawl/extract/map/research 五个），不引
+ * 第三方依赖，也不支持字符类 `[...]` 与转义（工具名里它们不是合法成员，无需）。
+ * 展开只发生在生成期：产物里只落具体工具名，运行时 toolFilter 语义完全不变。
+ * 依赖 util（warn）；被 compose 引用。
+ */
+import { warn } from './util.mjs'
+
+/**
+ * 条目是否含通配符（`*` 或 `?`）：非字符串一律视为不含（配置规范化只放行非空
+ * 字符串，这里是 compose 层对 UI / 测试直传 assignments 的兜底口径）。
+ */
+export function hasWildcard(entry) {
+  return typeof entry === 'string' && /[*?]/.test(entry)
+}
+
+/** 通配符模式 → 全串锚定正则：`*` → 任意长字符段、`?` → 恰一字符，其余字符
+ * 按字面匹配（正则元字符一律转义，防 `mcp__x(y)` 之类名字被当正则解读）。 */
+function patternToRegExp(pattern) {
+  const source = [...pattern]
+    .map((ch) => {
+      if (ch === '*') return '[\\s\\S]*'
+      if (ch === '?') return '[\\s\\S]'
+      return ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    })
+    .join('')
+  return new RegExp(`^${source}$`)
+}
+
+/**
+ * 把含通配符的条目对候选集展开为具体工具名列表；不含通配符的条目原样保留。
+ *  - 输入不含任何通配符 → 原数组原样返回（同一引用）：零通配的默认路径零开销、
+ *    零行为变化，全默认生成产物与源逐字节一致的金测因此不受影响；
+ *  - 含通配符时逐条目原位展开：精确名条目留在原相对位置；每个模式条目展开为
+ *    命中的候选名，命中名按候选集自身的迭代顺序（Set 插入序，即调用方构造
+ *    presetUniverse ∪ inventory 时的稳定顺序）排列。选候选集顺序而非「匹配发现
+ *    顺序」的理由：(a) 候选集顺序与条目书写顺序、模式数量正交 —— 两个角色写
+ *    同一模式得到完全一致的展开序列，反复生成产物稳定、diff 可比；(b) 原位展开
+ *    保住作者书写条目的顺序语义（精确名不动、每个模式的展开成组可读）。若按
+ *    匹配发现顺序输出，命中名会被拉离其模式条目的位置、序列还随模式间交互
+ *    漂移，产物可读性与稳定性都差；
+ *  - 整体保序去重：先出现者保留（跨精确名/展开名统一去重，模式命中已在候选集
+ *    里的精确名时不产生重复行）；
+ *  - 某模式零匹配 → warn 一条（含模式串本身）并丢弃该条目：展开的契约是「产物
+ *    只含具体名」，保留裸模式串等于往运行时 allow 里塞一个永远匹配不上的字面量。
+ * candidates 接受 Set 或数组；entries 非数组时原样返回（tools 缺省为 null 的
+ * 既有口径由调用方 `?? []` 兜底，这里不再二次加工）。
+ */
+export function expandToolPatterns(entries, candidates) {
+  if (!Array.isArray(entries)) return entries
+  if (!entries.some((entry) => hasWildcard(entry))) return entries
+  const candidateList = candidates instanceof Set ? [...candidates] : Array.isArray(candidates) ? [...candidates] : []
+  const out = []
+  const seen = new Set()
+  for (const entry of entries) {
+    if (!hasWildcard(entry)) {
+      if (!seen.has(entry)) {
+        seen.add(entry)
+        out.push(entry)
+      }
+      continue
+    }
+    const re = patternToRegExp(entry)
+    let matched = 0
+    for (const candidate of candidateList) {
+      if (typeof candidate !== 'string' || seen.has(candidate) || !re.test(candidate)) continue
+      seen.add(candidate)
+      out.push(candidate)
+      matched++
+    }
+    if (matched === 0) warn(`工具通配符模式 '${entry}' 未匹配到任何候选工具名，已忽略该条目`)
+  }
+  return out
+}

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 }
+}