dsh-paoding 0.3.9 → 0.4.0

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

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

package/presets/orchestrator/agent.cordis.yml

@@ -7,6 +7,9 @@
 #   · orchestrator-restrict → restrict.mjs 在 system-prompt/assemble 瀑布上把
 #     主 agent 的工具面裁剪为「编排 + 内部搜索」白名单；子 agent（origin:
 #     'subagent'）放行，由各自 toolFilter 决定工具面
+#   · delegation-labels → delegation-labels.mjs 在 tools/pre-execute 瀑布上把
+#     命中角色的委派调用 description 原地改写为「角色名 · 原任务短语」，任务
+#     管理页 / 子代理目录树 / 后台任务列表的标签统一带角色名
 #   · delegation-*       → 4 个角色委派工具（dsh-tool-subagent，search_internal_deep 为静态委派），子 agent 创建时
 #     以 per-child tools.restrict() 只保留各自 allow 的工具
 #
@@ -68,6 +71,16 @@
 - id: orchestrator-restrict
   name: ./restrict.mjs
 
+# ── 委派标签角色名前缀 ───────────────────────────────────────────────────────
+# delegation-labels.mjs 挂 tools/pre-execute 瀑布，把命中角色的委派调用
+# description 原地改写为「角色名 · 原任务短语」——子会话 label 持久化后，任务
+# 管理页、会话头子代理目录树与后台任务列表统一显示角色名。roles 由生成器按
+# roles.<toolName>.name 填充；空对象 = 没有角色配了名字，插件不注册任何处理器。
+- id: delegation-labels
+  name: ./delegation-labels.mjs
+  config:
+    roles: {}          # 生成器按 roles.<toolName>.name 填充
+
 # ── shell ───────────────────────────────────────────────────────────────────
 
 - id: tool-bash

package/presets/orchestrator/delegation-labels.mjs

@@ -0,0 +1,80 @@
+/**
+ * 委派子代理标签带角色名（delegation-labels.mjs）
+ *
+ * Part of the dsh-paoding 编排模式 (orchestrator) preset. 主 agent 委派角色
+ * （implement / design / search_external 及自定义角色）时，委派工具调用的
+ * `description` 参数会成为子会话的持久 label——任务管理页（better-sidebar）、
+ * 原生会话头的子代理目录树、后台任务列表展示的都是它。编排模型随手写的
+ * description 只是一句任务短语，扫一眼分不清哪条子代理是谁在干活；本插件在
+ * `tools/pre-execute` 瀑布上把命中角色的委派调用改写成 `角色名 · 原任务短语`
+ * （如「民工码农 · 修复标签显示」），三处展示面统一带上角色名。
+ *
+ * 机制（提示词约束做不到的确定性改写）：
+ *   dsh-tools 调度器在每次工具执行前跑 tools/pre-execute 瀑布，随后把同一个
+ *   exec.arguments 对象原样交给工具本体。dsh-tool-subagent 的子会话 label、
+ *   jobs.start 的 job label、startContinuable 的 label 三者都取自
+ *   args.description，所以在这里原地改写该字段，下游一并生效，并随子会话
+ *   descriptor 持久化。处理完必须 `return await next()` 放行——本插件只管
+ *   标签，永不拦截委派。
+ *
+ * config.roles 由生成器按 dsh-paoding.config.yml 的 roles.<toolName>.name 填充
+ * （toolName → 显示名）：没配名字的角色不进映射、标签保持原样；全空时本插件
+ * 不注册任何处理器。幂等：已带 `角色名 · ` 前缀的 description 不重复加前缀
+ * （同一次委派重复过瀑布也不会双写）。
+ *
+ * 失败面：整段 try/catch 包住，任何异常只 warn 一次后照常放行——标签出错顶多
+ * 退回旧观感，绝不能拦掉一次委派。
+ */
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'orchestrator-delegation-labels'
+
+/** The waterfall rides on ctx events; tools guarantees the registry exists first. */
+export const inject = ['tools']
+
+/** 角色名与任务短语之间的缺省分隔符。 */
+const DEFAULT_SEPARATOR = ' · '
+
+/** 标签改写出错只提醒一次，避免每次委派都刷一条日志。 */
+let warned = false
+
+/**
+ * @param {object} ctx - cordis context（事件瀑布 / logger）。
+ * @param {{ separator?: string, roles?: Record<string, string> }} config
+ *   生成器写入的角色显示名映射与可选分隔符。
+ */
+export function apply(ctx, config = {}) {
+  const separator =
+    typeof config.separator === 'string' && config.separator !== '' ? config.separator : DEFAULT_SEPARATOR
+  // 只收非空显示名；一个名字都没有就什么都不注册（无事可做，零开销）。
+  const displayNames = new Map()
+  for (const [toolName, displayName] of Object.entries(config.roles ?? {})) {
+    if (typeof toolName !== 'string' || toolName === '') continue
+    if (typeof displayName !== 'string' || displayName.trim() === '') continue
+    displayNames.set(toolName, displayName.trim())
+  }
+  if (displayNames.size === 0) return
+
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    try {
+      const toolName = exec?.name
+      if (typeof toolName === 'string' && displayNames.has(toolName)) {
+        const args = exec.arguments
+        if (args !== null && typeof args === 'object') {
+          const prefix = `${displayNames.get(toolName)}${separator}`
+          const description = args.description
+          // 非空字符串且未带前缀才改写（幂等：再次进瀑布不双写前缀）。
+          if (typeof description === 'string' && description.trim() !== '' && !description.startsWith(prefix)) {
+            args.description = `${prefix}${description}`
+          }
+        }
+      }
+    } catch (error) {
+      if (!warned) {
+        warned = true
+        ctx.logger?.warn?.(`${name}: 标签前缀注入失败，本次按原 description 放行（后续不再提醒）: ${String(error)}`)
+      }
+    }
+    return await next()
+  })
+}

package/tools/lib/cli.mjs

@@ -8,17 +8,21 @@
  * 自带的 Web 配置器（侧栏底部「庖丁配置」入口）。
  *
  * 依赖 util（ROLES / SRC_DIR / PROFILE_NAME_RE）、config（normalizeRoleName）、
- * host（removedReason）、state（collectState /
+ * 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'
 import { PROFILE_NAME_RE, ROLES, SRC_DIR } from './util.mjs'
 import { normalizeRoleName } from './config.mjs'
 import { removedReason } from './host.mjs'
-import { collectState, generateAndInstall } from './state.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')
   }
@@ -196,7 +227,7 @@ export function printReport({ scanned, mcpReports, pluginReports, roleResults, d
     `${dryRun ? '[dry-run] would write' : 'wrote'} ${path.join(dstDir, 'agent.cordis.yml')}` +
       (dryRun ? '' : ' (allow lists rewritten)'),
   )
-  console.log(`${dryRun ? '[dry-run] would copy' : 'copied'} preset.yml, restrict.mjs as-is`)
+  console.log(`${dryRun ? '[dry-run] would copy' : 'copied'} ${PRESET_ASIS_FILES.join(', ')} as-is`)
   if (!dryRun) {
     console.log()
     console.log('next steps:')
@@ -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

@@ -16,10 +16,18 @@
  * 行行尾兜底注入；'one-shot' 不动源行 —— 源模板四块各预置
  * `backgroundMode: one-shot`（可见性），全默认产物与源零 diff）、
  * restrict config.allow 注入（computeRestrictAllow /
- * injectRestrictAllow / filterUsableTools）与整文 compose（composeGenerated）。
+ * injectRestrictAllow / filterUsableTools）、委派标签角色名映射注入
+ * （injectDelegationLabelRoles：roles.<toolName>.name → delegation-labels 行的
+ * config.roles，运行期给委派调用的 description 加「角色名 · 」前缀）与整文
+ * compose（composeGenerated）。
  * 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 性质随之保留）。
@@ -30,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 行的宿主版本适配 ─────────────────────────────────────────
 
@@ -217,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(
@@ -278,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'),
     )
   }
@@ -299,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 ?? [])])
@@ -328,6 +351,45 @@ export function injectRestrictAllow(srcText, allowList) {
   return srcText.slice(0, insertAt) + block + srcText.slice(insertAt)
 }
 
+/**
+ * 委派标签角色名映射注入（delegation-labels 行的 config.roles）：把
+ * delegation-labels.mjs 模板行的 `roles: {}` 占位改写为实际映射
+ * （toolName → 显示名，键值均过 yamlScalar 落安全标量）。运行期
+ * delegation-labels.mjs 据此在 tools/pre-execute 瀑布上给委派调用的
+ * description 加「角色名 · 」前缀（子会话 label / job label 的持久展示名）。
+ * 无任何名字时直接返回原文（产物与源零 diff，插件侧拿到空映射也不注册
+ * 处理器）；找不到 delegation-labels 行或 `roles: {}` 占位属模板漂移，硬
+ * 错误（与 injectRestrictAllow 的失败口径一致）。键按字典序落盘，同一配置
+ * 反复生成产物稳定。
+ */
+export function injectDelegationLabelRoles(srcText, roleNames) {
+  const entries = Object.entries(roleNames ?? {})
+    .filter(
+      ([toolName, displayName]) =>
+        typeof toolName === 'string' && toolName !== '' && typeof displayName === 'string' && displayName.trim() !== '',
+    )
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  if (entries.length === 0) return srcText
+  const marker = '- id: delegation-labels'
+  const idx = srcText.indexOf(marker)
+  if (idx === -1) throw new Error('delegation-labels row not found')
+  // 行块边界 = 下一条顶层 `- id: ` 行（本块只有 id / name / config.roles 三件），
+  // 占位匹配限定在块内，防误吞后续行的同名键。
+  const nextRow = srcText.indexOf('\n- id: ', idx + marker.length)
+  const blockEnd = nextRow === -1 ? srcText.length : nextRow
+  const rolesIdx = srcText.indexOf('roles: {}', idx)
+  if (rolesIdx === -1 || rolesIdx >= blockEnd) {
+    throw new Error('delegation-labels row: `roles: {}` placeholder not found')
+  }
+  const lineStart = srcText.lastIndexOf('\n', rolesIdx - 1) + 1
+  const lineEnd = srcText.indexOf('\n', rolesIdx)
+  const rendered = entries
+    .map(([toolName, displayName]) => `      ${yamlScalar(toolName)}: ${yamlScalar(displayName.trim())}`)
+    .join('\n')
+  const end = lineEnd === -1 ? srcText.length : lineEnd
+  return srcText.slice(0, lineStart) + `    roles:\n${rendered}` + srcText.slice(end)
+}
+
 /**
  * Append text to the main-agent persona (`- id: persona` row) block scalar,
  * used to inline the selected skills' full SKILL.md bodies (composeGenerated,
@@ -688,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.`)
@@ -844,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（未检测或不存在），已跳过`)
@@ -874,6 +949,18 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
   }
   if (restrictAllow !== null) out = injectRestrictAllow(out, restrictAllow)
 
+  // 委派标签角色名映射（delegation-labels 行的 config.roles）：roles.<toolName>.name
+  // 的第二处生效点——内置与自定义角色一律收（配了名字才进映射，标签才带前缀）；
+  // roles_remove 删除的角色委派行已整条不存在，跳过；全空则产物与源零 diff，
+  // 插件侧对空映射也不注册任何处理器。
+  const delegationLabelRoles = {}
+  for (const [toolName, role] of Object.entries(assignments.roles)) {
+    if (removedRoles.includes(toolName)) continue
+    const name = typeof role?.name === 'string' && role.name.trim() !== '' ? role.name.trim() : null
+    if (name !== null) delegationLabelRoles[toolName] = name
+  }
+  out = injectDelegationLabelRoles(out, delegationLabelRoles)
+
   // Main-agent skills (dual mode, mirrors the roles' skill soft guidance):
   //   - main_agent_skills (soft): one compact "# skill: <name> — <description>"
   //     row + "Read full rules: <file>" per skill appended to the main-agent