dsh-plugin-prompt-tool 1.0.0 → 2.0.1

package/engine/dev-tool-search.mjs

@@ -0,0 +1,213 @@
+/**
+ * 工具面的按需发现与解锁。
+ *
+ * 为什么：工具面实测 **156 个、工具描述合计 46894 字符**（≈12K token，每个请求都付），
+ * 而多数请求只用到其中几个。收窄成常驻核心集之后，本工具是唯一的发现入口。
+ *
+ * 两个动作合一：
+ *  - `query` 关键词搜索**完整装配目录**（只回名字 + 一行截断描述，不回 parameters）；
+ *  - `toolNames` 按**精确名**解锁。解锁名写进本次 `tool/call` 的持久参数，
+ *    `assembly.target.tools.allowFrom` 从那里读回 → 下次请求起生效，且跨压缩保留。
+ *
+ * **能力摘要来自运行时截获，不手工维护**（2026-10-05 用户指出）：空查询时按前缀把
+ * `ctx.tools.schemas()` 的可见目录折叠成分组摘要（`mcp__github__* ×46`，实测 433 字符
+ * 覆盖全部 156 个工具）。此前的实现写死一份 UNLOCKABLE_INDEX——工具增删就要改代码，
+ * 名字写错还会让模型照着错名字解锁（那份实现甚至需要一条专门测试来防错名）。
+ * 官方注册表只投影 name/description（无分组字段），所以分组只能按前缀在本地折叠。
+ *
+ * 与原 `dev-tool-search.mjs` 的两处修正照搬：
+ *  1. 匹配是**打分**而非 AND 过滤——长自然语言查询（"file edit write replace"）在
+ *     AND 口径下命中零个，等于白搜。现在精确名优先，其次按命中 token 数排序。
+ *  2. 描述里显式教解锁路径（"搜索为空 ≠ 工具不存在"）——实测模型只会搜、不会传
+ *     toolNames，于是收窄后永远拿不到工具。
+ */
+export const name = 'dev-tool-search'
+
+/** 工具注册表必须先于本工具存在（同 skill-search 的 inject 纪律）。 */
+export const inject = ['tools']
+
+/** 单次搜索结果上限：再多就该让模型收窄关键词。 */
+export const MAX_RESULTS = 25
+
+/** 一行描述在结果里的截断长度。 */
+const DESC_LIMIT = 90
+
+/** 空查询摘要里最多列出的分组数，超出则并入「其他」。 */
+const MAX_GROUPS = 24
+
+/** 常驻核心集：由工具面收窄模板声明，这里只在描述里如实告知模型。 */
+const RESIDENT = ['pwsh', 'read', 'write', 'edit', 'glob', 'grep', 'todo_write', 'skill_search', 'skill_load']
+
+/** 零依赖的最小 JSON schema 编译器（与 skill-search 同构）。 */
+function toJsonSchema(spec) {
+  const properties = {}
+  const required = []
+  for (const [key, meta] of Object.entries(spec || {})) {
+    const prop = { type: meta.type }
+    if (meta.description) prop.description = meta.description
+    if (meta.items) prop.items = meta.items
+    properties[key] = prop
+    if (meta.required) required.push(key)
+  }
+  return { type: 'object', properties, required, additionalProperties: false }
+}
+
+/**
+ * 能力索引：常驻核心集（pwsh / read / write / edit / glob / grep / todo_write /
+ * skill_search / skill_load）覆盖不到的能力。名字全部取自实测工具面。
+ */
+
+/** 把查询切成小写 token（Unicode 字母数字与下划线连字符，与 skill-search 同口径）。 */
+export function queryTokens(query) {
+  return (typeof query === 'string' ? query : '').toLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(Boolean)
+}
+
+/**
+ * 一个工具名的分组键：MCP 工具折到服务级（`mcp__github__*`），其余折到首个下划线段
+ * （`task_board_create` → `task_*`），无下划线的单名自成一组。
+ */
+export function groupKeyOf(name) {
+  if (typeof name !== 'string' || name.length === 0) return undefined
+  if (name.startsWith('mcp__')) {
+    const parts = name.split('__')
+    return parts.length >= 2 ? `${parts[0]}__${parts[1]}__*` : `${name}*`
+  }
+  const cut = name.indexOf('_')
+  return cut <= 0 ? name : `${name.slice(0, cut)}_*`
+}
+
+/**
+ * 从**运行时目录**折叠出分组摘要——这是替代手工能力索引的唯一来源。
+ * 名字、分组、数量全部来自 `ctx.tools.schemas()`，工具增删不需要改本模块的代码。
+ * 超过 MAX_GROUPS 个分组时，把长尾并成一行「其他」而不是无限增长。
+ */
+export function summarizeCatalog(schemas) {
+  const counts = new Map()
+  for (const schema of Array.isArray(schemas) ? schemas : []) {
+    const key = groupKeyOf(schema?.name)
+    if (key === undefined) continue
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  const sorted = [...counts.entries()].sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]))
+  const head = sorted.slice(0, MAX_GROUPS)
+  const tail = sorted.slice(MAX_GROUPS)
+  const parts = head.map(([key, count]) => `${key}(${count})`)
+  if (tail.length > 0) parts.push(`其他 ${tail.length} 组(${tail.reduce((sum, [, n]) => sum + n, 0)})`)
+  return { total: [...counts.values()].reduce((sum, n) => sum + n, 0), text: parts.join(' ') }
+}
+
+/**
+ * 对目录打分排序（纯函数，可单测）：
+ * 精确名命中排最前，其次按命中 token 数降序，同分按名字字典序。
+ * `wanted` 为空时返回空数组——调用方据此区分「没给查询」与「没搜到」。
+ */
+export function scoreTools(schemas, wanted) {
+  if (!Array.isArray(schemas) || wanted.length === 0) return []
+  return schemas
+    .map((schema) => {
+      const name = typeof schema?.name === 'string' ? schema.name : ''
+      const haystack = `${name} ${schema?.description ?? ''}`.toLowerCase()
+      let score = 0
+      for (const token of wanted) if (haystack.includes(token)) score += 1
+      return { schema, name, score, exact: wanted.includes(name.toLowerCase()) }
+    })
+    .filter((entry) => entry.name.length > 0 && (entry.exact || entry.score >= 1))
+    .sort((a, b) => (b.exact - a.exact) || (b.score - a.score) || a.name.localeCompare(b.name))
+}
+
+/** 解锁名单归一：只留非空字符串，去重保序。 */
+export function unlockNames(value) {
+  if (!Array.isArray(value)) return []
+  const seen = new Set()
+  for (const item of value) {
+    if (typeof item !== 'string') continue
+    const name = item.trim()
+    if (name.length > 0) seen.add(name)
+  }
+  return [...seen]
+}
+
+/** 把目录搜索结果渲染成给模型的文本（带截断提示与解锁引导）。 */
+export function renderMatches(scored, query) {
+  const lines = []
+  const matches = scored.slice(0, MAX_RESULTS)
+  if (matches.length === 0) {
+    lines.push(
+      `No tools match "${query}". An empty result only means no tool matched your keywords — if you need a specific tool, unlock it directly by exact name, e.g. dev_tool_search({"toolNames":["web_search"]}).`,
+    )
+    return lines
+  }
+  lines.push(`Matching tools (${matches.length}${scored.length > MAX_RESULTS ? ` of ${scored.length}` : ''}):`)
+  for (const { schema, name, exact } of matches) {
+    const desc = String(schema?.description ?? '').split('\n')[0].slice(0, DESC_LIMIT)
+    lines.push(`- ${name}${exact ? ' (exact)' : ''}: ${desc}`)
+  }
+  if (scored.length > MAX_RESULTS) {
+    lines.push(`(truncated at ${MAX_RESULTS} — add tokens to narrow the query)`)
+  }
+  lines.push('Unlock with dev_tool_search({"toolNames": ["<exact name>"]}).')
+  return lines
+}
+
+/** 注册模型可见的 `dev_tool_search`。 */
+export function apply(ctx) {
+  ctx.tools.register({
+    name: 'dev_tool_search',
+    description: [
+      'Discover and unlock tools that are NOT currently available.',
+      '',
+      `This session starts with a minimal resident set: ${RESIDENT.join(', ')}. Everything else is unlocked on demand through this tool.`,
+      '',
+      'Usage:',
+      '- `query` — search the catalog by keyword (matches tool names AND descriptions, 1-2 short words work best).',
+      '- call with NO arguments — list the catalog as group counts (`<prefix>_*(count) ...`), so you can see what exists before searching.',
+      '- `toolNames` — unlock exact names. Unlocked tools appear from the NEXT request on and stay unlocked for the session.',
+      '',
+      'Example: dev_tool_search({"query":"pull request","toolNames":["mcp__github__create_pull_request"]}) — search AND unlock in one call.',
+      'IMPORTANT: an empty search result does NOT mean the tool does not exist — it only means no tool matched your keywords. Call with no arguments to see the catalog groups, then unlock by exact name.',
+    ].join('\n'),
+    parameters: toJsonSchema({
+      query: { type: 'string', required: false, description: 'search keywords (e.g. "web", "subagent", "github")' },
+      toolNames: {
+        type: 'array',
+        required: false,
+        items: { type: 'string' },
+        description: 'exact tool names to unlock for the next request',
+      },
+    }),
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } }, required: ['text'] },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const query = typeof args?.query === 'string' ? args.query.trim() : ''
+      const unlock = unlockNames(args?.toolNames)
+      const lines = []
+      // 解锁动作本身不需要任何运行时服务：引擎的 allowFrom 只读本工具的持久调用参数，
+      // 所以即便目录不可用（无 tools 服务/无 agent），解锁也必须照样回报成功。
+      if (unlock.length > 0) lines.push(`Unlocked for the next request: ${unlock.join(', ')}`)
+      if (query.length === 0 && unlock.length > 0) return { text: lines.join('\n') }
+      let schemas
+      try {
+        // 执行中的 agent 就是观察作用域：preset 工具注册在 agent scope 层，
+        // 不带 scope 的 schemas() 只看全局层，会漏掉它们。
+        schemas = ctx.tools.schemas(exec?.agent)
+      } catch (error) {
+        return { text: [...lines, `catalog search unavailable: ${String(error?.message ?? error)}`].join('\n') }
+      }
+      // 空查询 = 要目录概览。摘要由运行时目录折叠而来，不需要维护任何索引。
+      if (query.length === 0) {
+        const summary = summarizeCatalog(schemas)
+        lines.push(
+          summary.total === 0
+            ? 'The catalog is empty — nothing to unlock.'
+            : `Catalog groups (${summary.total} tools): ${summary.text}`,
+          'Search with `query`, or unlock by exact name with `toolNames`.',
+        )
+        return { text: lines.join('\n') }
+      }
+      lines.push(...renderMatches(scoreTools(schemas, queryTokens(query)), query))
+      return { text: lines.join('\n') }
+    },
+  })
+}

package/engine/executor.mjs

@@ -29,6 +29,7 @@ import { wireLayers } from './layers.mjs'
 import { sessionVarsSnapshot } from './session-vars.mjs'
 import { selectStWorldBook } from './st-world-book.mjs'
 import { compareConfigSequence } from './order.mjs'
+import { ruleFrame, ruleMatches, actionMatches } from './conditions/evaluation.mjs'
 
 const name = 'prompt-config-engine'
 
@@ -66,13 +67,25 @@ function identityOf(config) {
   return config.mergeMode === 'merged' ? mergedIdentity(config) : config.identity.value
 }
 
+/**
+ * 消息来源的插件身份（去重身份）。v4 起 `source.kind` 是生产者名（`plugin:<name>`），
+ * `source.plugin` 只作为旧日志字段保留——两条通道都要认，否则去重记账会在格式换代后静默失效。
+ */
+function pluginIdentityOf(source) {
+  if (source === null || typeof source !== 'object') return undefined
+  if (typeof source.plugin === 'string' && source.plugin.length > 0) return source.plugin
+  return typeof source.kind === 'string' && source.kind.startsWith('plugin:')
+    ? source.kind.slice('plugin:'.length)
+    : undefined
+}
+
 function hasInjected(config, session) {
   const value = identityOf(config)
   return sessionEvents(session).some((event) => {
     const message = eventMessage(event)
     // 双通道去重：kind（外来/第三方消息，如 context-gate 的 instruction-hint）或
     // plugin（本引擎注入的命名空间，merged 组用 merged:<position>）。
-    return message?.source?.kind === config.sourceKind || message?.source?.plugin === value
+    return message?.source?.kind === config.sourceKind || pluginIdentityOf(message?.source) === value
   })
 }
 
@@ -80,7 +93,7 @@ function hasInjected(config, session) {
 function hasInBatch(config, messages) {
   const value = identityOf(config)
   return messages.some((message) =>
-    message?.source?.kind === config.sourceKind || message?.source?.plugin === value)
+    message?.source?.kind === config.sourceKind || pluginIdentityOf(message?.source) === value)
 }
 
 /**
@@ -113,6 +126,10 @@ export function confirmDelivered(memo, session, event) {
     if (typeof value !== 'string' || value.length === 0) continue
     deliveredSessions(memo, `${field}:${value}`).add(session.id)
   }
+  // v4 起生产者身份挂在 kind（`plugin:<name>`），旧日志才有 plugin 字段；
+  // 两种形态都补记到 plugin: 账本，alreadyDelivered 的 `confirmed('plugin', …)` 才不会漏。
+  const plugin = pluginIdentityOf(source)
+  if (plugin !== undefined && source.plugin === undefined) deliveredSessions(memo, `plugin:${plugin}`).add(session.id)
 }
 
 /** dedupe=session：本会话是否已有该身份的已确认投递（快路径 + 持久事件真相）。 */
@@ -151,7 +168,9 @@ function buildMessage(config, resolved, warnOnce) {
   const base = resolved.source !== null && typeof resolved.source === 'object'
     ? resolved.source
     : {
-        kind: config.sourceKind,
+        // v4 要求 kind 是**生产者名**：声明了 sourceKind 就用它，否则用与 pluginMessage 同一形状的
+        // `plugin:<身份>`。裸 kind（undefined / 'plugin'）都会被 codec 拒绝，历史走的是同一个坑。
+        kind: typeof config.sourceKind === 'string' && config.sourceKind.length > 0 ? config.sourceKind : `plugin:${sourceValue}`,
         plugin: sourceValue,
         ...(typeof config.form === 'string' ? { form: config.form } : {}),
         ...(typeof config.summary === 'string' && config.summary.length > 0 ? { summary: config.summary } : {}),
@@ -178,6 +197,27 @@ function buildMessage(config, resolved, warnOnce) {
  * @returns 注入后的 decision；reject、缺 agent/session、全部跳过或异常时原样返回。
  */
 export async function runPreStepBatch(options) {
+  const initialFrame = options.ruleFrame ?? ruleFrame('agent/pre-step', [{ agent: options.agent, messages: options.decision?.messages ?? [] }], options.warnOnce, options.ctx)
+  if (!options.ruleActions?.length) return runPromptConfigBatch({ ...options, ruleFrame: initialFrame })
+  const entries = [...options.configs.map(config => ({ ...config, config })), ...options.ruleActions].sort(compareConfigSequence)
+  let decision = options.decision
+  if (decision?.kind === 'reject') return decision
+  let pending = []
+  const placement = { beforeAll: new Set(), afterUser: new Set() }
+  const flush = async () => {
+    if (pending.length) decision = await runPromptConfigBatch({ ...options, decision, configs: pending, ruleFrame: initialFrame, placement })
+    pending = []
+  }
+  for (const entry of entries) {
+    if (entry.config) { pending.push(entry.config); continue }
+    await flush()
+    if (ruleMatches(entry.rule, initialFrame)) decision = await entry.handler(options.payload ?? initialFrame.args[0], () => decision, initialFrame)
+  }
+  await flush()
+  return decision
+}
+
+async function runPromptConfigBatch(options) {
   const { ctx, agent, decision, configs, promotion, memo, warnOnce } = options
   if (decision === null || typeof decision !== 'object') return decision
   if (decision.kind === 'reject') return decision
@@ -204,6 +244,7 @@ export async function runPreStepBatch(options) {
       && (config.promotion !== 'main' || main.status(agent).promoted)
       && (config.promotion !== 'include-subagents' || withSubagents.status(agent).promoted)
       && conditionHit(config, { userText })
+      && actionMatches(config, options.ruleFrame)
     const qualifiedConfigs = configs.filter(qualified)
     // 协调器为绑定来源 ctx 会复制 config；renderSt 函数身份在副本间保持不变。
     const eligible = new Set(qualifiedConfigs.map(config => config.renderSt))
@@ -310,13 +351,18 @@ export async function runPreStepBatch(options) {
     const afterUser = planned.filter((item) => item.position !== 'before-all' && item.position !== 'after-all')
     const afterAll = planned.filter((item) => item.position === 'after-all')
     if (beforeAll.length > 0) {
-      messages.unshift(...beforeAll.map((item) => item.message))
+      // 混合动作把注入切成多批；继续排在此前仍存活的同位置消息之后。
+      const index = options.placement === undefined ? 0 : messages.findLastIndex(message => options.placement.beforeAll.has(message)) + 1
+      messages.splice(index, 0, ...beforeAll.map((item) => item.message))
+      for (const item of beforeAll) options.placement?.beforeAll.add(item.message)
       for (const item of beforeAll) markGroup(item.group)
       changed = true
     }
     const userIndex = messages.findIndex((item) => item?.source?.kind === 'user')
     if (afterUser.length > 0 && userIndex >= 0) {
-      messages.splice(userIndex + 1, 0, ...afterUser.map((item) => item.message))
+      const last = options.placement === undefined ? -1 : messages.findLastIndex(message => options.placement.afterUser.has(message))
+      messages.splice(Math.max(userIndex, last) + 1, 0, ...afterUser.map((item) => item.message))
+      for (const item of afterUser) options.placement?.afterUser.add(item.message)
       for (const item of afterUser) markGroup(item.group)
       changed = true
     }
@@ -358,7 +404,7 @@ function effectivePromptConfigs(configs) {
 export function applyPromptConfigSources(ctx, sources, options = {}) {
   const selected = sources.map(source => ({ ...source, configs: effectivePromptConfigs(source.configs) }))
   const releases = selected.map(source => applyPromptConfigs(ctx, source.configs, { ...options, ...source, layers: false }))
-  const releaseLayers = wireLayers(ctx, selected.flatMap(source => source.configs)
+  const releaseLayers = options.layers === false ? () => {} : wireLayers(ctx, selected.flatMap(source => source.configs)
     .filter(config => config.layer !== 'pre-step'), createWarnOnce(ctx, name))
   return () => {
     for (const release of releases) release()
@@ -388,6 +434,7 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
   const promotion = { main, withSubagents }
   const source = {
     configs: effectiveList,
+    ruleActions: options.ruleActions ?? [],
     officialInstructions: options.officialInstructions === true,
   }
   /** 已交给协调器的注册(仅管理路径非空)。 */
@@ -444,9 +491,11 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
     if (!active) return decision
     return runPreStepBatch({
       ctx,
+      payload,
       agent: payload?.agent,
       decision,
       configs: effectiveList,
+      ruleActions: source.ruleActions,
       promotion,
       memo: injectedMemo,
       warnOnce,

package/engine/fillers.mjs

@@ -8,13 +8,20 @@ import { createInstructionHintResolver } from './instruction-hint.mjs'
 
 const name = 'prompt-config-engine'
 
+function explicitTemplate(config) {
+  const texts = Array.isArray(config.texts) ? config.texts : typeof config.text === 'string' ? [config.text] : []
+  return texts.length > 0 ? texts.join('\n\n') : typeof config.params?.text === 'string' ? config.params.text : ''
+}
+
 /**
  * env-facts:机器事实动态填充器。
  * params.envKeys 逗号分隔环境变量白名单：取值归模板/预设，留空 = 不附加宿主环境
  * 变量（CWD/WORKSPACE 仍由会话事实提供）。
- * 返回 facts 变量表与默认文本;用户可用 text 模板 + {{变量}} 完全自定义输出。
+ * 只提供 facts 变量；正文必须由 text/params.text 显式模板声明。
  */
 function createEnvFactsResolver(config) {
+  const template = explicitTemplate(config)
+  if (template.trim().length === 0) return () => null
   const keys = parseToolNames(typeof config.params?.envKeys === 'string' ? config.params.envKeys : '')
   return ({ agent }) => {
     const session = agent?.session
@@ -30,8 +37,8 @@ function createEnvFactsResolver(config) {
     }
     facts.WORKSPACE = process.env.DSH_WORKSPACE ?? cwd
     facts.CWD = cwd
-    const defaultText = ['Environment facts:', ...Object.entries(facts).map(([key, value]) => `- ${key}=${value}`)].join('\n')
-    return { text: defaultText, variables: facts }
+    const envFacts = Object.entries(facts).map(([key, value]) => `- ${key}=${value}`).join('\n')
+    return { text: template, variables: { ...facts, ENV_FACTS: envFacts } }
   }
 }
 
@@ -42,21 +49,21 @@ function createEnvFactsResolver(config) {
  * 跳过本配置并告警一次,绝不伤及会话。
  */
 function createSkillCatalogResolver(config) {
-  const limit = Number.isSafeInteger(config.params?.limit) && config.params.limit >= 0
-    ? config.params.limit
-    : 20
-  const fields = parseToolNames(typeof config.params?.fields === 'string' ? config.params.fields : 'name,description')
+  const template = explicitTemplate(config)
+  if (template.trim().length === 0) return () => null
+  const rawLimit = config.params?.limit
+  const limit = rawLimit == null || rawLimit === '' ? undefined : rawLimit
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) throw new TypeError(`${name}: skill-catalog limit must be a non-negative integer`)
+  const fields = parseToolNames(typeof config.params?.fields === 'string' ? config.params.fields : '')
     .filter((field) => ['name', 'description', 'whenToUse'].includes(field))
+  const whenToUseLabel = typeof config.params?.whenToUseLabel === 'string' ? config.params.whenToUseLabel : ''
+  const unnamedLabel = typeof config.params?.unnamedLabel === 'string' ? config.params.unnamedLabel : ''
   const providers = parseToolNames(config.params?.providers)
   const emptyBehavior = config.params?.emptyBehavior === 'text' ? 'text' : 'skip'
   // 空结果提示文案归模板/预设：留空且 emptyBehavior=text 时按 skip 处理（不注入空消息）。
   const emptyText = typeof config.params?.emptyText === 'string' ? config.params.emptyText : ''
   let warned = false
-  // 保留本地 warnOnce：本工厂只拿得到 config，ctx 要到每次 resolve 调用时才由
-  // 参数传入；换成 shared 的 createWarnOnce(ctx, name) 必须改工厂签名，而唯一
-  // 调用点 engine/strategies.mjs 的 createPlaceholderResolver(config) 不在本支
-  // 写区。为替换而扩大改动面违反 PLAN，故此处按原语义手写（一次性 + logger
-  // 不可用时不抛）。
+  // ctx 直到 resolve 时才可用；每个填充器实例只告警一次，不让日志失败伤及会话。
   const warnOnceLocal = (ctx, message) => {
     if (warned) return
     warned = true
@@ -93,10 +100,10 @@ function createSkillCatalogResolver(config) {
         const value = skill?.name
         if (typeof value === 'string' && value.length > 0) return value
         if (typeof skill?.locator === 'string' && skill.locator.length > 0) return skill.locator
-        return String(skill?.id ?? '(unnamed)')
+        return String(skill?.id ?? unnamedLabel)
       }
       const firstLine = (value) => typeof value === 'string' ? value.split('\n')[0].trim() : ''
-      const rows = (limit === 0 ? scoped : scoped.slice(0, limit)).map((skill) => {
+      const rows = (limit === undefined || limit === 0 ? scoped : scoped.slice(0, limit)).map((skill) => {
         const parts = []
         if (fields.includes('name')) parts.push(nameOf(skill))
         if (fields.includes('description')) {
@@ -105,14 +112,14 @@ function createSkillCatalogResolver(config) {
         }
         if (fields.includes('whenToUse')) {
           const whenToUse = firstLine(skill?.whenToUse)
-          if (whenToUse.length > 0) parts.push(`适用：${whenToUse}`)
+          if (whenToUse.length > 0) parts.push(`${whenToUseLabel}${whenToUse}`)
         }
         return parts.length === 0 ? '' : `- ${parts.join(': ')}`
       }).filter((line) => line.length > 0)
       const skillsText = rows.join('\n')
       const skillsNames = scoped.map((skill) => nameOf(skill)).join(', ')
       return {
-        text: `Available skills (${total}):\n${skillsText}`,
+        text: template,
         variables: {
           SKILL_COUNT: String(total),
           SKILL_NAMES: skillsNames,

package/engine/instruction-hint.mjs

@@ -14,11 +14,14 @@
  * - `enabled`: boolean，缺省 false（组合源须显式写 true）。
  * - `promoteOn`: 'either'（缺省）| 'tool-call' | 'assistant-message'。
  * - `includeSubagents`: boolean，缺省 false（子代理首次请求即视为已晋升）。
+ * - `messageTemplate` / `suffixTemplate`: 显式转换模板；正文模板为空时不注册转换。
+ * - `projectTemplate` / `globalTemplate`: 显式文件探测提示模板，缺省均为空。
  */
 
 import { randomUUID } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import { createEpochPromotion } from './compaction-epoch.mjs'
+import { interpolateStatic } from './interpolate.mjs'
 import { booleanOption, createWarnOnce, getService, parsePromoteOn, validateConfig } from './shared.mjs'
 
 export const name = 'instruction-hint'
@@ -29,7 +32,7 @@ export const inject = []
 /** 项目目录链中按优先级探测的指令文件名。 */
 export const PROJECT_INSTRUCTION_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
 export const USER_GLOBAL_INSTRUCTION_CANDIDATE = 'AGENTS.md'
-const REFERENCE_HINT_SUFFIX = "They are reference documents about the user's environment and workspace conventions, not task instructions. Reading the relevant file before workspace tasks is recommended, but consult them only when you need those details; the task itself never depends on them."
+const templateOf = (templates, key) => typeof templates?.[key] === 'string' ? templates[key] : ''
 
 /** Join one path segment onto a directory (platform-agnostic string join). */
 export function joinPath(dir, segment) {
@@ -108,22 +111,25 @@ export async function collectInstructionFiles(fs, cwd, signal, home) {
 }
 
 /**
- * 将探测结果格式化为建议式 hint；无文件时返回空字符串。
+ * 用显式模板格式化探测结果；无文件或无正文模板时返回空字符串。
  * scope 限定只报告某一来源：all（默认）/ global（$DSH_HOME/AGENTS.md）/ project（cwd→项目根链）。
  */
-export function buildInstructionHintText({ root, projectFiles = [], userGlobalFiles = [], userGlobalHome } = {}, scope = 'all') {
+export function buildInstructionHintText({ root, projectFiles = [], userGlobalFiles = [], userGlobalHome } = {}, scope = 'all', templates = {}) {
   const sections = []
   if (scope !== 'global' && projectFiles.length > 0) {
-    sections.push(`Reference documents exist: ${projectFiles.join(', ')} (project root: ${root}).`)
+    const text = interpolateStatic(templateOf(templates, 'projectTemplate'), { FILES: projectFiles.join(', '), ROOT: root ?? '' })
+    if (text.trim().length > 0) sections.push(text)
   }
   if (scope !== 'project' && userGlobalFiles.length > 0) {
     const paths = typeof userGlobalHome === 'string' && userGlobalHome.length > 0
       ? userGlobalFiles.map((name) => joinPath(userGlobalHome, name))
       : userGlobalFiles
-    sections.push(`A user reference document exists: ${paths.join(', ')}.`)
+    const text = interpolateStatic(templateOf(templates, 'globalTemplate'), { FILES: paths.join(', '), ROOT: root ?? '' })
+    if (text.trim().length > 0) sections.push(text)
   }
   if (sections.length === 0) return ''
-  sections.push(REFERENCE_HINT_SUFFIX)
+  const suffix = templateOf(templates, 'suffixTemplate')
+  if (suffix.trim().length > 0) sections.push(suffix)
   return sections.join(' ')
 }
 
@@ -137,13 +143,13 @@ function hintScope(value) {
  * prompt-config placeholder fill=instruction-hint 的 resolver。
  * params.text（自定义提示）优先；params.file（文件卡绑定的单个指令文件）次之——
  * 运行时读该文件正文并加 `Instructions from:` 头注入；最后按 params.scope 探测来源
- * （all / global / project）只发「文件存在」提示。
+ * （all / global / project）按显式 projectTemplate/globalTemplate 生成提示。
+ * 未配置提示模板时返回 null；引擎不提供默认引导文案。
  * 文件缺失、不可读或空内容时返回 null，不注入任何消息。
  */
 export function createInstructionHintResolver(config = {}) {
-  const customText = typeof config?.params?.text === 'string' && config.params.text.trim().length > 0
-    ? config.params.text.trim()
-    : ''
+  const customText = typeof config?.params?.text === 'string' ? config.params.text.trim()
+    : Array.isArray(config.texts) ? config.texts.join('\n\n').trim() : ''
   const scope = hintScope(config?.params?.scope)
   const file = typeof config?.params?.file === 'string' && config.params.file.trim().length > 0
     ? config.params.file.trim()
@@ -171,11 +177,12 @@ export function createInstructionHintResolver(config = {}) {
         ? { id, text: `Instructions from: ${fileLabel}\n\n${content}`, source: { kind: 'instruction-file', form: 'instructions' } }
         : null
     }
+    if (templateOf(config.params, 'projectTemplate').trim().length === 0 && templateOf(config.params, 'globalTemplate').trim().length === 0) return null
     const fs = ctx.get('fs')
     if (fs === undefined) return null
     const cwd = session.header?.cwd ?? process.cwd()
     const found = await collectInstructionFiles(fs, cwd, agent.signal)
-    const text = buildInstructionHintText(found, scope)
+    const text = buildInstructionHintText(found, scope, config.params)
     return text.length > 0
       ? { id, text, source: { kind: 'instruction-hint', form: 'hint' } }
       : null
@@ -199,36 +206,41 @@ export function extractInstructionPaths(message) {
 }
 
 /** 构造一次性非命令式 hint 消息；替换已有消息时保留其 id。 */
-export function buildInstructionHint(original, paths, sourceName = 'instruction-hint') {
+export function buildInstructionHint(original, paths, sourceName = 'instruction-hint', templates = {}) {
+  const template = templateOf(templates, 'messageTemplate')
+  if (template.trim().length === 0) return original
+  const text = interpolateStatic(template, { FILES: paths.join(', '), SUFFIX: templateOf(templates, 'suffixTemplate') })
+  if (text.trim().length === 0) return original
   return {
     id: typeof original?.id === 'string' && original.id !== '' ? original.id : `instruction-hint-${randomUUID()}`,
     role: 'user',
     content: [{
       type: 'text',
-      text: '<system-reminder>\n'
-        + `Reference documents exist: ${paths.join(', ')}. ${REFERENCE_HINT_SUFFIX}`
-        + '\n</system-reminder>',
+      text,
     }],
     source: { kind: 'instruction-hint', form: 'hint', plugin: sourceName },
   }
 }
 
 /** 将 agent-instructions 全文替换为一次性 hint，后续全文消息丢弃。 */
-export function instructionHintMessages(messages, state, sourceName = 'instruction-hint') {
+export function instructionHintMessages(messages, state, sourceName = 'instruction-hint', templates = {}) {
+  if (templateOf(templates, 'messageTemplate').trim().length === 0) return messages
   const kept = []
   for (const message of messages) {
     if (message?.source?.kind !== 'agent-instructions') {
       kept.push(message)
       continue
     }
-    if (state.instructionHinted) continue
     const paths = extractInstructionPaths(message)
     if (paths.length === 0) {
-      kept.push(message)
+      if (!state.instructionHinted) kept.push(message)
       continue
     }
+    const hint = buildInstructionHint(message, paths, sourceName, templates)
+    if (hint === message) { kept.push(message); continue }
+    if (state.instructionHinted) continue
     state.instructionHinted = true
-    kept.push(buildInstructionHint(message, paths, sourceName))
+    kept.push(hint)
   }
   return kept
 }
@@ -236,7 +248,7 @@ export function instructionHintMessages(messages, state, sourceName = 'instructi
 // ── plugin 形态 ─────────────────────────────────────────────────────────────
 
 /** Every config key this plugin accepts — anything else is a typo. */
-const ALLOWED_KEYS = new Set(['enabled', 'promoteOn', 'includeSubagents'])
+const ALLOWED_KEYS = new Set(['enabled', 'promoteOn', 'includeSubagents', 'projectTemplate', 'globalTemplate', 'suffixTemplate', 'messageTemplate'])
 
 /** The visible surface, not the append-only log, owns hint lifetime. */
 function hasVisibleInstructionHint(session) {
@@ -258,7 +270,7 @@ export function apply(ctx, config) {
   const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
   // 开关语义：未声明 = 关闭（组合源为本模块显式写 enabled: true）。
   const enabled = booleanOption(name, source.enabled, 'enabled', false)
-  if (!enabled) return
+  if (!enabled || templateOf(source, 'messageTemplate').trim().length === 0) return
 
   const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
   const warnOnce = createWarnOnce(ctx, name)
@@ -279,7 +291,7 @@ export function apply(ctx, config) {
       // 1 换 1 的转换不能按长度判断（长度相同仍可能已转换），
       // instructionHintMessages 本身保留非目标消息，直接采用结果。
       const hintState = { instructionHinted: hasVisibleInstructionHint(agent.session) }
-      return { ...decision, messages: instructionHintMessages(messages, hintState, name) }
+      return { ...decision, messages: instructionHintMessages(messages, hintState, name, source) }
     } catch (error) {
       // 转换失败不阻断会话：保留原消息。
       warnOnce(`${name}: instruction hint conversion failed, keeping messages: ${String((error && error.message) || error)}`)