dsh-paoding 0.3.10 → 0.4.0

package/plugins/paoding-config-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paoding-config-ui",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "private": true,
   "type": "module",
   "main": "index.mjs",

package/tools/lib/cli.mjs

@@ -10,7 +10,9 @@
  * 依赖 util（ROLES / SRC_DIR / PROFILE_NAME_RE）、config（normalizeRoleName）、
  * host（removedReason）、state（PRESET_ASIS_FILES / collectState /
  * generateAndInstall）、alloc（autoAssignments，--auto 语义与插件首装共享）、
- * version（getVersionInfo，main 收尾的新版提示）以及 node:os / node:path。
+ * health（captureWarnings / healthCheck，--dry-run 报告的结构化体检）、
+ * doctor（runDoctor，doctor 子命令的只读体检）、version（getVersionInfo，
+ * main 收尾的新版提示）以及 node:os / node:path。
  */
 import { homedir } from 'node:os'
 import path from 'node:path'
@@ -19,6 +21,8 @@ import { normalizeRoleName } from './config.mjs'
 import { removedReason } from './host.mjs'
 import { PRESET_ASIS_FILES, collectState, generateAndInstall } from './state.mjs'
 import { autoAssignments } from './alloc.mjs'
+import { captureWarnings, healthCheck } from './health.mjs'
+import { runDoctor } from './doctor.mjs'
 import { getVersionInfo } from './version.mjs'
 
 // ── CLI ─────────────────────────────────────────────────────────────────────
@@ -35,6 +39,7 @@ export function printHelp() {
 
 Usage:
   node tools/install.mjs [options]
+  node tools/install.mjs doctor [options]
 
 Options:
   --profile <name>   Profile whose patch layer is scanned (default: web).
@@ -47,13 +52,19 @@ Options:
   --auto             Non-interactive: apply the config file when present,
                      otherwise apply the base template (--suggest seeds smart
                      defaults on a fresh install instead).
-  --dry-run          Print the detection report and the generated allow lists
-                     without writing anything; exit 0.
+  --dry-run          Print the detection report, the generated allow lists and
+                     the config health check without writing anything; exit 0.
   --suggest          Fresh install without a config file: seed smart defaults
                      from the detected host/MCP tools instead of the base
                      template (host tools are folded in automatically).
   --help             Show this help and exit.
 
+Subcommands:
+  doctor             Read-only health check of the local install (config file,
+                     preset track vs host version, managed patch rows, orphan
+                     workspace presets, config drift, version marker) and a
+                     summary; exit 1 only on error-level findings.
+
 Environment:
   DSH_HOME           Directory holding cordis.patch.yml etc. (default: $HOME/.dsh)
 
@@ -73,10 +84,15 @@ function assertProfileName(value) {
 }
 
 export function parseArgs(argv) {
-  const opts = { profile: null, patches: [], dryRun: false, help: false, auto: false, config: undefined, suggest: false }
+  const opts = { command: 'install', profile: null, patches: [], dryRun: false, help: false, auto: false, config: undefined, suggest: false }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
-    if (arg === '--help' || arg === '-h') {
+    if (arg === 'doctor') {
+      // 子命令：doctor = 只读体检；缺省 install（原 installer 主流程）。位置参数
+      // 只认这一个，其余仍按未知选项报错；--help / --profile / --config 等照常
+      // 解析，doctor 分支共用。
+      opts.command = 'doctor'
+    } else if (arg === '--help' || arg === '-h') {
       opts.help = true
     } else if (arg === '--dry-run') {
       opts.dryRun = true
@@ -130,7 +146,7 @@ export function parseArgs(argv) {
 
 // ── report & install ────────────────────────────────────────────────────────
 
-export function printReport({ scanned, mcpReports, pluginReports, roleResults, dstDir, dryRun, staleNote, mainAgent }) {
+export function printReport({ scanned, mcpReports, pluginReports, roleResults, dstDir, dryRun, staleNote, mainAgent, health = null }) {
   const pad = (s, n) => String(s).padEnd(n)
   console.log('dsh-paoding installer — orchestrator preset (host-aware tool filtering)')
   console.log(`  preset source : ${SRC_DIR}`)
@@ -188,6 +204,21 @@ export function printReport({ scanned, mcpReports, pluginReports, roleResults, d
   } else {
     console.log('  removed: none — every host-dependent allow entry is enabled')
   }
+  if (health !== null) {
+    // 配置体检小节（--dry-run 报告专属；health 为 null 时不打印，--auto 输出
+    // 保持原样）。条目结构与面板 preview/apply 响应的 warnings 字段同源
+    //（tools/lib/health.mjs healthCheck）。
+    console.log()
+    console.log('config health (体检):')
+    if (health.length === 0) {
+      console.log('  ✔ 未发现问题')
+    } else {
+      for (const h of health) {
+        const mark = h.level === 'error' ? '✘' : h.level === 'warn' ? '⚠' : 'ℹ'
+        console.log(`  ${mark} ${h.code} — ${h.message}`)
+      }
+    }
+  }
   if (staleNote) {
     console.log('\nnote: 检测到 patch 配置在本次安装后有过修改，改动后请重跑 node tools/install.mjs --auto')
   }
@@ -211,6 +242,30 @@ export function printReport({ scanned, mcpReports, pluginReports, roleResults, d
   console.log(`uninstall: rm -rf "${dstDir}"`)
 }
 
+/** doctor 子命令的人读报告：每行「✔/✘/⚠/– 项目 — 一句说明」，结尾汇总。
+ *  渲染与检查本体分离（tools/lib/doctor.mjs 只产结构化 items，便于测试）。 */
+export function printDoctorReport(report, { dshHome, configFile }) {
+  const marks = { ok: '✔', error: '✘', warn: '⚠', skip: '–' }
+  console.log('dsh-paoding doctor — 安装体检（只读，不改任何文件）')
+  console.log(`  DSH_HOME : ${dshHome}`)
+  console.log(`  配置文件 : ${configFile}`)
+  console.log()
+  for (const { status, label, detail } of report.items) {
+    console.log(`${marks[status] ?? '·'} ${label} — ${detail}`)
+  }
+  const count = (status) => report.items.filter((i) => i.status === status).length
+  const errors = count('error')
+  const warns = count('warn')
+  console.log()
+  if (errors > 0) {
+    console.log(`汇总: ${report.items.length} 项检查，${errors} 项错误（✘）${warns > 0 ? `、${warns} 项警告（⚠）` : ''}——请先处理 ✘ 再使用；详细说明见 docs/installation.md 排查节`)
+  } else if (warns > 0) {
+    console.log(`汇总: ${report.items.length} 项检查，无错误；${warns} 项警告（⚠）不影响使用，可按各行说明处理`)
+  } else {
+    console.log(`汇总: ${report.items.length} 项检查全部正常`)
+  }
+}
+
 // ── main ────────────────────────────────────────────────────────────────────
 
 /**
@@ -232,6 +287,16 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
     return 0
   }
 
+  // doctor 子命令：只读体检，不走 --auto 门禁（门禁仅拦会动盘的安装主流程），
+  // 也不用 collectState 的全量检测——runDoctor 内部按项自行探测与降级。
+  if (opts.command === 'doctor') {
+    const dshHome = process.env.DSH_HOME || path.join(homedir(), '.dsh')
+    const configFile = opts.config || path.join(dshHome, 'dsh-paoding.config.yml')
+    const report = await runDoctor({ dshHome, configFile, profile: opts.profile })
+    printDoctorReport(report, { dshHome, configFile })
+    return report.hasErrors ? 1 : 0
+  }
+
   // 无 --auto 直接拒绝（交互模式已删）：--dry-run 只读不动盘，放行作检测预览。
   // 门禁放在 collectState 之前：被拒路径不做任何检测 / 握手，快速失败。
   if (!opts.auto && !opts.dryRun) {
@@ -281,12 +346,24 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
   // saveConfigOnWrite：fresh 非交互安装把基础模板落进配置文件（显式
   // main_agent_extra: [] 锚定「未开启 host 工具」）；existing 路径绝不覆写
   // 用户配置文件。
+  // --dry-run 顺路做一次结构化体检（captureWarnings 抓生成期告警 + healthCheck，
+  // 产物 dryRunResult 直喂体检零重跑；models 缺省 null，CLI 不做模型目录发现）：
+  // health 条目由 printReport 的新小节打印。--auto 路径不体检，输出保持原样。
   let composed
+  let healthItems = null
   try {
-    composed = generateAndInstall(state, assignments, {
-      dryRun: opts.dryRun,
-      saveConfigOnWrite: !existing && !opts.dryRun,
-    })
+    if (opts.dryRun) {
+      const [result, generationWarnings] = captureWarnings(() =>
+        generateAndInstall(state, assignments, { dryRun: true, saveConfigOnWrite: false }),
+      )
+      composed = result
+      healthItems = healthCheck({ state, assignments, dryRunResult: composed, generationWarnings }).items
+    } else {
+      composed = generateAndInstall(state, assignments, {
+        dryRun: false,
+        saveConfigOnWrite: !existing,
+      })
+    }
   } catch (err) {
     console.error(`error: ${err.message}`)
     return 1
@@ -307,6 +384,7 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
       extra: assignments.main_agent_extra ?? [],
       removed: assignments.main_agent_remove ?? [],
     },
+    health: healthItems,
   })
   if (!existing && !opts.dryRun) {
     // fresh 非交互安装：提示基础模板已落盘、host/MCP 工具去哪补（--suggest 可

package/tools/lib/compose.mjs

@@ -23,6 +23,11 @@
  * allow 过滤走白名单语义（usableWith / presetUniverse ∪ inventory，见
  * filterUsableTools 上方说明）：手写进配置、既不在 preset 自带工具面也不在
  * 检测库存的名字一律从 allow 丢弃，不再「非 host 依赖名直通」。
+ * 工具条目支持 `*` / `?` 通配（expandToolPatterns，见 glob.mjs）：主 agent 侧
+ * （computeRestrictAllow 的 base / mainAgentExtra / customToolNames 三路）与角色
+ * 侧（内置角色 intent、自定义角色 tools）都在白名单过滤**之前**先对候选集展开
+ * 为具体名 —— 语义叠加不替代，展开后的名字仍走既有 usableWith / 直通过滤；
+ * 产物只落具体名，运行时 toolFilter 语义不变。
  * workflow worker 行按宿主版本生成期适配（adaptWorkflowWorkerRow：≥0.1.6 把
  * 0.1.5-only 的 workflow-worker-thread 条目换成 workflow-ptc；探测不到版本
  * 保守保留源行，产物零 diff 性质随之保留）。
@@ -33,13 +38,14 @@
  * agent persona 委派行（composeMainPersonaEdit 第 4 参 customBullets →
  * `- <职责>: delegate to <toolName>.`），否则主 agent 永远不会委派给自定义角色。
  * 依赖 util（ROLES / warn / DEFAULT_MAIN_AGENT_PERSONA_EXTRA）、config
- * （normalizeModelRef / yamlScalar）与 host
+ * （normalizeModelRef / yamlScalar）、glob（expandToolPatterns）与 host
  * （isHostDependent）；被 state 引用。
  */
 import { DEFAULT_MAIN_AGENT_PERSONA_EXTRA, ROLES, warn } from './util.mjs'
 import { normalizeModelRef, yamlScalar } from './config.mjs'
 import { isHostDependent } from './host.mjs'
 import { isPtcWorkerHost } from './preset-system.mjs'
+import { expandToolPatterns } from './glob.mjs'
 
 // ── workflow worker 行的宿主版本适配 ─────────────────────────────────────────
 
@@ -220,18 +226,25 @@ export function replaceRoleIdentity(text, displayName) {
 /**
  * Render the delegation block(s) for custom roles, matching the existing
  * delegation-* indentation (4-space list items).
+ * expandCandidates（可选，Set/数组）：传入时角色 tools 先过通配符展开（与内置
+ * 角色同一候选集口径，见 composeGenerated），展开后的具体名直接进块内 allow ——
+ * 自定义角色的 allow 不走 usableWith（角色名本身就不在既有工具面里），展开是
+ * 纯加法，不过滤；模式零匹配被丢弃后 tools 若变空，走下方既有的零工具 throw
+ *（拒绝安装零工具角色，warn 已提示是哪个模式没匹配上）。缺省不展开（直接调用
+ * 方/测试的旧签名行为不变）。
  */
-export function renderCustomRoleBlocks(roles, skillsMap, restrictBase = []) {
+export function renderCustomRoleBlocks(roles, skillsMap, restrictBase = [], expandCandidates = null) {
   const custom = Object.entries(roles).filter(([toolName]) => !ROLES.includes(toolName))
   if (custom.length === 0) return ''
   const chunks = []
   for (const [toolName, role] of custom) {
     // 保留名校验（见 assertCustomToolName）+ 零工具防护（与 composeGenerated
-    // 内置角色循环同款）：tools 为空（缺省或 `tools:` 空列表）会生成
-    // `toolFilter.allow:`（YAML null），子 agent 创建后零工具——宁可拒绝安装，
-    // 也不静默生成一个干不了活的角色。
+    // 内置角色循环同款）：tools 为空（缺省或 `tools:` 空列表，或传入候选集时
+    // 通配符展开后零命中）会生成 `toolFilter.allow:`（YAML null），子 agent
+    // 创建后零工具——宁可拒绝安装，也不静默生成一个干不了活的角色。
     assertCustomToolName(toolName, restrictBase)
-    if ((role.tools ?? []).length === 0) {
+    const tools = expandCandidates === null ? (role.tools ?? []) : expandToolPatterns(role.tools ?? [], expandCandidates)
+    if (tools.length === 0) {
       throw new Error(`role "${toolName}" would end up with an empty toolFilter.allow — refusing to install a zero-tool role.`)
     }
     const persona = withSkillGuidance(
@@ -281,7 +294,7 @@ export function renderCustomRoleBlocks(roles, skillsMap, restrictBase = []) {
         ...persona.split('\n').map((l) => `          ${l}`),
         '        toolFilter:',
         '          allow:',
-        ...(role.tools ?? []).map((t) => `            - ${yamlScalar(t)}`),
+        ...tools.map((t) => `            - ${yamlScalar(t)}`),
       ].join('\n'),
     )
   }
@@ -302,16 +315,23 @@ export function firstLine(text) {
  * removed: once roles_remove is non-empty the explicit allow MUST be injected,
  * otherwise the static restrict.mjs MAIN_AGENT_ALLOW would keep delegating to
  * the deleted role (删除不生效).
+ * 三路入参（base / mainAgentExtra / customToolNames）先过通配符展开（候选集 =
+ * presetUniverse ∪ inventory，与 usableWith 判定用的同一集合），展开后的名字仍
+ * 走各自既有的过滤口径（base / extra 过 usableWith，customToolNames 直通收）——
+ * 语义叠加不替代。base 与 customToolNames 实际都是精确名（restrict.mjs 源名单 /
+ * assignments.roles 的键），展开为恒等变换，零风险；mainAgentExtra 是手写配置
+ * 条目，通配符的主战场。零通配时展开是同引用恒等，默认路径输出逐字节不变。
  */
 export function computeRestrictAllow(base, presetUniverse, inventory, mainAgentExtra, mainAgentRemove, customToolNames, removedRoleNames = []) {
+  const expandCandidates = new Set([...presetUniverse, ...inventory])
   const kept = []
-  for (const name of base) {
+  for (const name of expandToolPatterns(base, expandCandidates)) {
     if (usableWith(name, presetUniverse, inventory)) kept.push(name)
   }
-  for (const name of mainAgentExtra) {
+  for (const name of expandToolPatterns(mainAgentExtra, expandCandidates)) {
     if (!kept.includes(name) && usableWith(name, presetUniverse, inventory)) kept.push(name)
   }
-  for (const name of customToolNames) {
+  for (const name of expandToolPatterns(customToolNames, expandCandidates)) {
     if (!kept.includes(name)) kept.push(name)
   }
   const removed = new Set([...(mainAgentRemove ?? []), ...(removedRoleNames ?? [])])
@@ -730,11 +750,18 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
     for (const name of block.names) presetUniverse.add(name)
   }
 
+  // 通配符展开候选集 = presetUniverse ∪ inventory（与 usableWith 判定用的同一
+  // 集合）：内置角色 intent / 自定义角色 tools / main_agent_extra 三处的 `*` /
+  // `?` 模式条目都先对它展开成具体名，再进各自既有的过滤（语义叠加不替代）。
+  const expandCandidates = new Set([...presetUniverse, ...inventory])
+
   // Role allow results (default roles only; custom roles are rendered fresh).
   const roleResults = []
   for (const role of ROLES) {
     if (removedRoles.includes(role)) continue // 已删除角色：不产 roleResults / allow edits
-    const intent = assignments.roles[role]?.tools ?? blocks.get(role).names
+    // 意图先过通配符展开再进白名单过滤；roleResults 的 intent/removed 都记展开
+    // 后的具体名（报告口径「配了几个 → 留几个」对模式条目才有意义）。
+    const intent = expandToolPatterns(assignments.roles[role]?.tools ?? blocks.get(role).names, expandCandidates)
     const filtered = filterUsableTools(intent, presetUniverse, inventory)
     if (filtered.length === 0) {
       throw new Error(`role "${role}" would end up with an empty toolFilter.allow — refusing to install a zero-tool role.`)
@@ -886,17 +913,23 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
   // workflow worker 行宿主版本适配（≥0.1.6 换 workflow-ptc；见 adaptWorkflowWorkerRow）。
   out = adaptWorkflowWorkerRow(out, hostVersionTriple)
 
-  const customBlock = renderCustomRoleBlocks(assignments.roles, skillsMap, restrictBase)
+  // 自定义角色块：tools 里的通配符条目按同一候选集展开成具体名再进 allow
+  //（第 4 参见 renderCustomRoleBlocks）。
+  const customBlock = renderCustomRoleBlocks(assignments.roles, skillsMap, restrictBase, expandCandidates)
   if (customBlock !== '') out = insertCustomRoles(out, customBlock)
 
   const mainAgentRemove = assignments.main_agent_remove ?? []
   // Warn about removals that are not part of the main agent's current allow
   // (undetected host tools, typos, names never present) and skip them.
+  // main_agent_extra 贡献先过通配符展开（与 computeRestrictAllow 的 allow 口径
+  // 一致），否则 extra 里的模式条目会让精确名的 remove 误报「不在当前 allow」。
   if (mainAgentRemove.length > 0) {
     const removable = new Set(
-      [...restrictBase, ...(assignments.main_agent_extra ?? []), ...customToolNames].filter((n) =>
-        usableWith(n, presetUniverse, inventory),
-      ),
+      [
+        ...restrictBase,
+        ...expandToolPatterns(assignments.main_agent_extra ?? [], expandCandidates),
+        ...customToolNames,
+      ].filter((n) => usableWith(n, presetUniverse, inventory)),
     )
     for (const name of mainAgentRemove) {
       if (!removable.has(name)) warn(`main_agent_remove: '${name}' 不在主 agent 当前 allow（未检测或不存在），已跳过`)

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