dsh-plugin-prompt-tool 0.4.2 → 0.6.0

package/engine/schema.mjs

@@ -0,0 +1,312 @@
+/**
+ * schema — prompt-config-engine 的提示词配置加载、归一化与权威校验。
+ * 只负责"配置长什么样";执行语义见 executor.mjs,内容策略见 strategies.mjs。
+ */
+
+import { readFileSync, readdirSync } from 'node:fs'
+import { parse as parseYaml } from './vendor/yaml/index.js'
+import { bindResolver } from './strategies.mjs'
+
+const name = 'prompt-config-engine'
+
+/**
+ * 内容模板加载:提示词配置可声明 templateFile,由外部 yml / json / 纯文本模板提供内容,
+ * 引擎只负责读取与注入(内容与执行分离)。
+ *   - .json:解析为 { text, id?, role?, content?, source? },或纯字符串;
+ *   - .yml/.yaml:用 vendored yaml 完整解析(顶层对象取 text 等字段);
+ *   - 其他扩展名:整个文件内容作为 text。
+ */
+function readTextFile(url) {
+  return readFileSync(url, 'utf8')
+}
+
+function loadTemplate(file) {
+  if (typeof file !== 'string' || file.length === 0) return undefined
+  let raw
+  try {
+    raw = readTextFile(new URL(file, import.meta.url))
+  } catch {
+    throw new TypeError(`${name}: templateFile ${JSON.stringify(file)} is not readable`)
+  }
+  if (/\.json$/i.test(file)) {
+    try {
+      const parsed = JSON.parse(raw)
+      return typeof parsed === 'string' ? { text: parsed } : parsed
+    } catch (error) {
+      throw new TypeError(`${name}: templateFile ${JSON.stringify(file)} is not valid JSON: ${String(error?.message ?? error)}`)
+    }
+  }
+  if (/\.ya?ml$/i.test(file)) {
+    try {
+      const parsed = parseYaml(raw)
+      return typeof parsed === 'string' ? { text: parsed } : parsed
+    } catch (error) {
+      throw new TypeError(`${name}: templateFile ${JSON.stringify(file)} is not valid YAML: ${String(error?.message ?? error)}`)
+    }
+  }
+  return { text: raw }
+}
+
+/**
+ * 完整 YAML 解析(vendored yaml 包):提示词配置文件直接使用标准 YAML。
+ * 支持缩进 map、列表、block scalar、行尾注释、引号转义等全部语法。
+ */
+export function parsePromptConfigYaml(raw) {
+  const parsed = parseYaml(raw)
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new TypeError(`${name}: prompt config yaml must contain a single object`)
+  }
+  return parsed
+}
+
+/**
+ * 从提示词配置模块目录加载全部提示词配置描述:按文件名排序扫描 *.yml / *.yaml / *.json。
+ * 文件名用数字前缀表达引擎执行顺序(00-…、10-…)。
+ */
+export function loadPromptConfigFiles(dirUrl) {
+  let entries
+  try {
+    entries = readdirSync(dirUrl, { withFileTypes: true })
+  } catch (error) {
+    throw new TypeError(`${name}: configsDir ${String(dirUrl)} is not readable: ${String(error?.message ?? error)}`)
+  }
+  // 预设级模板变量（writePreset 生成 variables.yml）：读入后合并进每条配置
+  // variables（配置自身优先）；variables.yml 本身不当作配置解析。缺失或损坏
+  // 时为空变量源，不阻断加载。
+  let presetVariables = {}
+  try {
+    const parsed = parseYaml(readFileSync(new URL('variables.yml', dirUrl), 'utf8'))
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) presetVariables = parsed
+  } catch {
+    // 无 variables.yml（旧产物/手写目录）或解析失败：保持空变量源。
+  }
+  const specs = []
+  const files = entries
+    .filter((entry) => entry.isFile() && /\.(ya?ml|json)$/i.test(entry.name))
+    .sort((a, b) => a.name.localeCompare(b.name))
+  for (const entry of files) {
+    if (entry.name === 'variables.yml') continue
+    const url = new URL(entry.name, dirUrl)
+    const raw = readFileSync(url, 'utf8')
+    if (/\.json$/i.test(entry.name)) {
+      specs.push(JSON.parse(raw))
+    } else {
+      specs.push(parsePromptConfigYaml(raw))
+    }
+  }
+  for (const spec of specs) {
+    if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) continue
+    const own = spec.variables !== null && typeof spec.variables === 'object' && !Array.isArray(spec.variables)
+      ? spec.variables
+      : {}
+    spec.variables = { ...presetVariables, ...own }
+  }
+  return specs
+}
+
+export const KNOWN_STRATEGIES = new Set(['static', 'placeholder', 'instruction-hint', 'first-turn-anchor', 'guide-auto', 'custom-fallback', 'world-book'])
+export const KNOWN_SLOT_KINDS = new Set(['ordered', 'anchor'])
+export const KNOWN_LAYERS = new Set(['pre-step', 'system-section', 'runtime-context', 'agent-request', 'llm-stream', 'tool-pipeline'])
+export const KNOWN_POSITIONS = new Set(['after-user', 'before-all', 'after-all'])
+export const KNOWN_DEDUPES = new Set(['session', 'batch', 'none'])
+export const KNOWN_PROMOTIONS = new Set(['none', 'main', 'include-subagents'])
+/** audience 专用标记：缺省（null/省略）= 公用（主会话+子代理通用）；main=仅主会话；subagent=仅子代理。 */
+export const KNOWN_AUDIENCES = new Set(['main', 'subagent'])
+export const KNOWN_MERGE_MODES = new Set(['separate', 'merged'])
+export const KNOWN_MODEL_SCOPES = new Set(['all', 'pro', 'flash'])
+export const KNOWN_ROLES = new Set(['user', 'assistant'])
+export const KNOWN_FILLS = new Set(['instruction-hint', 'env-facts', 'skill-catalog'])
+
+/** 层能力矩阵：每个字段只在对应注入层生效。客户端表单据此动态渲染。 */
+export const LAYER_FIELD_POLICIES = {
+  'pre-step': { position: true, dedupe: true, promotion: true, audience: true, modelScope: true, merge: true, order: true, role: true, placeholder: true },
+  'system-section': { position: false, dedupe: false, promotion: false, audience: false, modelScope: false, merge: true, order: true, role: false, placeholder: false },
+  'runtime-context': { position: false, dedupe: false, promotion: false, audience: false, modelScope: false, merge: true, order: true, role: false, placeholder: true },
+  'agent-request': { position: false, dedupe: false, promotion: false, audience: true, modelScope: true, merge: false, order: true, role: false, placeholder: false },
+  'llm-stream': { position: false, dedupe: false, promotion: false, audience: false, modelScope: true, merge: false, order: true, role: false, placeholder: false },
+  'tool-pipeline': { position: false, dedupe: false, promotion: false, audience: true, modelScope: true, merge: false, order: true, role: false, placeholder: false },
+}
+
+/** 层显示名与说明：由引擎统一下发，客户端不再各自维护。 */
+export const LAYER_LABELS = {
+  'pre-step': { title: '消息批层', detail: '官方默认层：agent/pre-step 消息批。支持 position / dedupe / promotion / audience / mergeMode 与文本插值。' },
+  'system-section': { title: '系统段层', detail: 'system-section 静态层：注册即全局，由 order 与 params.complete / sectionName 控制。' },
+  'runtime-context': { title: '运行上下文', detail: 'runtime-context 层：static 按 order 注册，placeholder 单条生效，由 params.contextName 控制。' },
+  'agent-request': { title: '调用配置层', detail: 'agent-request 层：按 order 注册，params.patch 改写请求配置。' },
+  'llm-stream': { title: '模型流层', detail: 'llm/stream 层：按 order 注册，params.mode = pass | replace。' },
+  'tool-pipeline': { title: '工具管线层', detail: 'tools/* 层：按 order 注册，params.toolNames 与 preDecision / postAction 控制。' },
+}
+
+/** 引擎能力矩阵：作为 /meta 的唯一数据源，客户端表单据此动态渲染。 */
+export function getEngineMeta() {
+  return {
+    layers: [...KNOWN_LAYERS].sort(),
+    strategies: [...KNOWN_STRATEGIES].sort(),
+    slotKinds: [...KNOWN_SLOT_KINDS].sort(),
+    positions: [...KNOWN_POSITIONS].sort(),
+    dedupes: [...KNOWN_DEDUPES].sort(),
+    promotions: [...KNOWN_PROMOTIONS].sort(),
+  audienceModes: [...KNOWN_AUDIENCES].sort(),
+    modelScopes: [...KNOWN_MODEL_SCOPES].sort(),
+    roles: [...KNOWN_ROLES].sort(),
+    mergeModes: [...KNOWN_MERGE_MODES].sort(),
+    fills: [...KNOWN_FILLS].sort(),
+    layerFieldPolicies: LAYER_FIELD_POLICIES,
+    layerLabels: LAYER_LABELS,
+  }
+}
+
+/** 从 YAML 提示词配置描述构造运行时提示词配置。配置错误必须在挂载时暴露(fail loud)。 */
+export function createPromptConfigs(specs, options = {}) {
+  if (specs === undefined) return []
+  if (!Array.isArray(specs)) throw new TypeError(`${name}: config.configs must be an array`)
+  const configs = specs.map((spec, index) => {
+    const label = `configs[${index}]`
+    if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+      throw new TypeError(`${name}: ${label} must be an object`)
+    }
+    if (typeof spec.id !== 'string' || spec.id.length === 0) {
+      throw new TypeError(`${name}: ${label}.id must be a non-empty string`)
+    }
+    const rawStrategy = spec.strategy ?? 'static'
+    const strategy = rawStrategy
+    if (!KNOWN_STRATEGIES.has(strategy)) {
+      // 模板专属策略:声明了 strategyDir 时由 strategies.bindResolver 懒加载,
+      // 否则视为未知策略 fail loud。
+      if (typeof options.strategyDir !== 'string' || options.strategyDir.length === 0) {
+        throw new TypeError(`${name}: ${label} unknown strategy ${JSON.stringify(strategy)}`)
+      }
+    }
+    const configKind = spec.configKind ?? 'ordered'
+    if (!KNOWN_SLOT_KINDS.has(configKind)) {
+      throw new TypeError(`${name}: ${label} unknown configKind ${JSON.stringify(configKind)}`)
+    }
+    const layer = spec.layer ?? 'pre-step'
+    if (!KNOWN_LAYERS.has(layer)) {
+      throw new TypeError(`${name}: ${label} unknown layer ${JSON.stringify(layer)} — known layers: ${[...KNOWN_LAYERS].sort().join(', ')}`)
+    }
+    // 层能力矩阵同时是引擎校验源：矩阵标记 false 的字段在对应层不生效，
+    // 显式提供时 fail loud（UI 表单已按矩阵隐藏，此处兜底手写配置）。
+    const restricted = ['position', 'dedupe', 'promotion', 'audience', 'modelScope', 'merge', 'role']
+      .filter((field) => LAYER_FIELD_POLICIES[layer][field] === false && spec[field === 'merge' ? 'mergeMode' : field] != null)
+    if (restricted.length > 0) {
+      throw new TypeError(`${name}: ${label} layer ${JSON.stringify(layer)} does not support field(s): ${restricted.join(', ')}`)
+    }
+    const position = spec.position ?? 'after-user'
+    if (!KNOWN_POSITIONS.has(position)) {
+      throw new TypeError(`${name}: ${label} unknown position ${JSON.stringify(position)}`)
+    }
+    const dedupe = spec.dedupe ?? 'none'
+    if (!KNOWN_DEDUPES.has(dedupe)) {
+      throw new TypeError(`${name}: ${label} unknown dedupe ${JSON.stringify(dedupe)}`)
+    }
+    const promotion = spec.promotion ?? 'none'
+    if (!KNOWN_PROMOTIONS.has(promotion)) {
+      throw new TypeError(`${name}: ${label} unknown promotion ${JSON.stringify(promotion)}`)
+    }
+    const audience = spec.audience
+    if (audience !== undefined && audience !== null && !KNOWN_AUDIENCES.has(audience)) {
+      throw new TypeError(`${name}: ${label} unknown audience ${JSON.stringify(audience)}`)
+    }
+    const modelScope = spec.modelScope ?? 'all'
+    if (!KNOWN_MODEL_SCOPES.has(modelScope)) {
+      throw new TypeError(`${name}: ${label} unknown modelScope ${JSON.stringify(modelScope)}`)
+    }
+    const role = spec.role ?? 'user'
+    if (!KNOWN_ROLES.has(role)) {
+      throw new TypeError(`${name}: ${label} unknown role ${JSON.stringify(role)}`)
+    }
+  // identity 仅支持 plugin 命名空间（kind 模式与 sourceKind 重复，已归一）。
+  const identity = spec.identity ?? { field: 'plugin', value: spec.id }
+  if (identity === null || typeof identity !== 'object' || Array.isArray(identity)
+  || identity.field !== 'plugin' || typeof identity.value !== 'string' || identity.value.length === 0) {
+    throw new TypeError(`${name}: ${label}.identity must be { field: 'plugin', value: string }`)
+    }
+    const order = spec.order ?? 0
+    if (typeof order !== 'number' || !Number.isFinite(order)) {
+      throw new TypeError(`${name}: ${label}.order must be a finite number`)
+    }
+    if (spec.group !== undefined && (typeof spec.group !== 'string' || spec.group.length === 0)) {
+      throw new TypeError(`${name}: ${label}.group must be a non-empty string when present`)
+    }
+    if (spec.exclusive !== undefined && typeof spec.exclusive !== 'boolean') {
+      throw new TypeError(`${name}: ${label}.exclusive must be a boolean when present`)
+    }
+    if (spec.name !== undefined && (typeof spec.name !== 'string' || spec.name.length === 0)) {
+      throw new TypeError(`${name}: ${label}.name must be a non-empty string when present`)
+    }
+    if (spec.variables !== undefined && (spec.variables === null || typeof spec.variables !== 'object' || Array.isArray(spec.variables))) {
+      throw new TypeError(`${name}: ${label}.variables must be an object when present`)
+    }
+    if (spec.texts !== undefined && (!Array.isArray(spec.texts) || spec.texts.some((item) => typeof item !== 'string'))) {
+      throw new TypeError(`${name}: ${label}.texts must be an array of strings when present`)
+    }
+    const mergeMode = spec.mergeMode ?? 'separate'
+    if (!KNOWN_MERGE_MODES.has(mergeMode)) {
+      throw new TypeError(`${name}: ${label} unknown mergeMode ${JSON.stringify(mergeMode)}`)
+    }
+    if (strategy === 'placeholder' && layer !== 'pre-step' && layer !== 'runtime-context') {
+      throw new TypeError(`${name}: ${label} strategy=placeholder supports layer pre-step or runtime-context only, got ${JSON.stringify(layer)}`)
+    }
+    let fill
+    if (strategy === 'placeholder') {
+      fill = typeof spec.fill === 'string' && spec.fill.length > 0 ? spec.fill : undefined
+      if (fill === undefined || !KNOWN_FILLS.has(fill)) {
+        throw new TypeError(`${name}: ${label} strategy=placeholder requires fill in [${[...KNOWN_FILLS].sort().join(', ')}]`)
+      }
+    }
+    const template = loadTemplate(spec.templateFile)
+    const templatePatch = template !== null && typeof template === 'object'
+      ? { id: template.id, role: template.role, content: template.content, source: template.source }
+      : undefined
+    const config = {
+      id: spec.id,
+      name: typeof spec.name === 'string' ? spec.name : spec.id,
+      enabled: spec.enabled !== false,
+      strategy,
+      configKind,
+      layer,
+      group: typeof spec.group === 'string' ? spec.group : undefined,
+      exclusive: spec.exclusive === true,
+      order,
+      role,
+      fill,
+      position,
+      dedupe,
+      promotion,
+      audience,
+      modelScope,
+      sourceKind: typeof spec.sourceKind === 'string' && spec.sourceKind.length > 0 ? spec.sourceKind : spec.id,
+      form: typeof spec.form === 'string' ? spec.form : 'notice',
+      summary: typeof spec.summary === 'string' ? spec.summary : '',
+      identity,
+      // text/texts 统一：text 为单块便捷写法，运行时与渲染只消费 texts。
+      texts: (() => {
+        const specText = typeof spec.text === 'string' && spec.text.length > 0 ? spec.text : undefined
+        const specTexts = Array.isArray(spec.texts) ? spec.texts.filter((item) => typeof item === 'string' && item.length > 0) : []
+        const templateText = typeof template?.text === 'string' ? template.text : ''
+        return specText !== undefined || specTexts.length > 0
+          ? [...(specText !== undefined ? [specText] : []), ...specTexts]
+          : (templateText.length > 0 ? [templateText] : [])
+      })(),
+      mergeMode,
+      variables: spec.variables !== null && typeof spec.variables === 'object' && !Array.isArray(spec.variables) ? spec.variables : {},
+      templatePatch,
+      params: spec.params !== null && typeof spec.params === 'object' && !Array.isArray(spec.params) ? spec.params : {},
+    }
+    config.resolve = bindResolver(config, options.strategyDir)
+    return config
+  })
+  // 排序契约:anchor 提示词配置保持模块文件相对顺序(固定锚点),ordered 提示词配置按 order
+  // 稳定升序排在其后。默认 order=0 时等价于文件顺序。
+  return configs
+    .map((config, fileOrder) => ({ config, fileOrder }))
+    .sort((a, b) => {
+      const aAnchor = a.config.configKind === 'anchor' ? 0 : 1
+      const bAnchor = b.config.configKind === 'anchor' ? 0 : 1
+      if (aAnchor !== bAnchor) return aAnchor - bAnchor
+      if (aAnchor === 1 && a.config.order !== b.config.order) return a.config.order - b.config.order
+      return a.fileOrder - b.fileOrder
+    })
+    .map(({ config }) => config)
+}

package/engine/session-vars.mjs

@@ -0,0 +1,52 @@
+/**
+ * session-vars — 会话变量（ST setvar/getvar 运行时语义）。
+ *
+ * 变量挂在 session 对象上（SESSION_VARS_KEY 属性），因此 .engine 引擎实例与
+ * 插件进程工具实例（不同模块副本）操作同一 session 即共享同一份数据——
+ * 无跨实例状态同步问题。WeakMap 不需要：session 释放后属性随对象回收。
+ *
+ * 插值优先级：resolved 运行时 > 会话变量 > 配置 params > 配置 variables（含预设）。
+ */
+
+/** session 对象上的变量属性键（字符串常量，跨模块实例一致）。 */
+export const SESSION_VARS_KEY = '__pt_session_vars__'
+
+function varsOf(session) {
+  if (session === null || typeof session !== 'object') return undefined
+  let vars = session[SESSION_VARS_KEY]
+  if (vars === undefined) {
+    vars = {}
+    session[SESSION_VARS_KEY] = vars
+  }
+  return vars
+}
+
+/** 会话变量快照（无会话/未设置 → 空对象）。 */
+export function sessionVarsSnapshot(session) {
+  const vars = varsOf(session)
+  return vars === undefined ? {} : { ...vars }
+}
+
+/** 读取单个会话变量（未设置 → undefined）。 */
+export function getSessionVar(session, key) {
+  const vars = varsOf(session)
+  return vars === undefined ? undefined : vars[String(key)]
+}
+
+/** 设置会话变量（值转字符串；空值仍记录）。 */
+export function setSessionVar(session, key, value) {
+  const vars = varsOf(session)
+  if (vars === undefined) return
+  vars[String(key)] = String(value ?? '')
+}
+
+/** 清除会话变量；key 缺省时清空全部。 */
+export function clearSessionVars(session, key) {
+  const vars = varsOf(session)
+  if (vars === undefined) return
+  if (key === undefined || key === '') {
+    for (const name of Object.keys(vars)) delete vars[name]
+  } else {
+    delete vars[String(key)]
+  }
+}

package/{preset → engine}/shared.mjs

@@ -81,3 +81,38 @@ export function isDelegated(session) {
 export function isFlashModel(modelId) {
   return typeof modelId === 'string' && /flash/i.test(modelId)
 }
+
+/** 模型范围过滤:flash=仅 Flash 家族模型;pro=仅非 Flash;all=全部。 */
+export function matchesModel(scope, model) {
+  if (scope === 'all') return true
+  const isFlash = isFlashModel(model)
+  return scope === 'flash' ? isFlash : !isFlash
+}
+
+/** 逗号分隔的 token 列表;空 = 空数组(调用方自行决定"全部"语义)。 */
+export function parseToolNames(value) {
+  if (typeof value !== 'string' || value.trim() === '') return []
+  return value.split(',').map((item) => item.trim()).filter((item) => item.length > 0)
+}
+
+/** 读取可选服务;测试桩 / 极简组合里缺失时返回 undefined,由调用方降级。 */
+export function getService(ctx, name) {
+  try {
+    return typeof ctx.get === 'function' ? ctx.get(name) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** 把服务注册返回的 disposer 挂到 fiber(资源注册契约)。 */
+export function keepDisposer(ctx, disposer, label) {
+  if (typeof disposer !== 'function') return
+  try {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(() => disposer, label)
+      return
+    }
+  } catch {
+    // 极简测试桩没有 effect:保持注册随进程,测试自行隔离。
+  }
+}

package/engine/strategies.mjs

@@ -0,0 +1,213 @@
+/**
+ * strategies — 引擎内容策略绑定(config.resolve)。
+ * 内置策略: static / placeholder / instruction-hint / first-turn-anchor / guide-auto / custom-fallback。
+ * 策略参数全部来自 config.params（由 preset.yml 单一配置源下发），引擎只负责组装。
+ * 仍支持 strategyDir 懒加载自定义模板策略。
+ */
+
+import { extractText } from './shared.mjs'
+import { MATCH_LOGIC, createAnchorMatcher } from './anchor-match.mjs'
+import { createInstructionHintResolver, createPlaceholderResolver } from './fillers.mjs'
+
+const name = 'prompt-config-engine'
+
+/**
+ * first-turn-anchor:首条真实用户消息后的一次性任务锚点。
+ * 正则与锚句文本全部来自 config.params（由 preset.yml 单一配置源下发）。
+ */
+function createFirstTurnAnchorResolver(config) {
+  const useCustom = config.params?.useCustom === true
+  const customText = typeof config.params?.firstTurnText === 'string' ? config.params.firstTurnText : ''
+  const buildPattern = typeof config.params?.buildPattern === 'string' ? config.params.buildPattern : ''
+  const complexPattern = typeof config.params?.complexPattern === 'string' ? config.params.complexPattern : ''
+  const firstTurnBuild = typeof config.params?.firstTurnBuild === 'string' ? config.params.firstTurnBuild : ''
+  const firstTurnInspect = typeof config.params?.firstTurnInspect === 'string' ? config.params.firstTurnInspect : ''
+  const firstTurnDeep = typeof config.params?.firstTurnDeep === 'string' ? config.params.firstTurnDeep : ''
+  const buildRe = buildPattern.length > 0 ? new RegExp(buildPattern, 'i') : undefined
+  const complexRe = complexPattern.length > 0 ? new RegExp(complexPattern, 'i') : undefined
+  return ({ messages }) => {
+    if (useCustom) {
+      const text = customText.trim()
+      return text.length > 0 ? { text } : null
+    }
+    if (buildRe === undefined || complexRe === undefined || (firstTurnBuild.length === 0 && firstTurnInspect.length === 0 && firstTurnDeep.length === 0)) {
+      return null
+    }
+    const userIndex = messages.findIndex((message) => message?.source?.kind === 'user')
+    if (userIndex < 0) return null
+    const taskText = extractText(messages[userIndex])
+    if (taskText.length === 0) return null
+    let anchor
+    if (complexRe.test(taskText)) anchor = firstTurnDeep
+    else if (buildRe.test(taskText)) anchor = firstTurnBuild
+    else anchor = firstTurnInspect
+    return anchor.length > 0 ? { text: anchor } : null
+  }
+}
+
+/**
+ * guide-auto:晋升后每轮用户消息后的弱/深度引导。
+ * 正则与引导文本全部来自 config.params（由 preset.yml 单一配置源下发）。
+ */
+function createGuideAutoResolver(config) {
+  const useCustom = config.params?.useCustom === true
+  const customText = typeof config.params?.text === 'string' ? config.params.text : ''
+  const guideComplexPattern = typeof config.params?.guideComplexPattern === 'string' ? config.params.guideComplexPattern : ''
+  const guideWeak = typeof config.params?.guideWeak === 'string' ? config.params.guideWeak : ''
+  const guideDeep = typeof config.params?.guideDeep === 'string' ? config.params.guideDeep : ''
+  const guideComplexRe = guideComplexPattern.length > 0 ? new RegExp(guideComplexPattern, 'i') : undefined
+  return ({ messages }) => {
+    const userIndex = messages.findIndex((message) => message?.source?.kind === 'user')
+    if (userIndex < 0) return null
+    const text = extractText(messages[userIndex])
+    if (text.length === 0) return null
+    if (useCustom) {
+      const guide = customText.trim()
+      return guide.length > 0 ? { text: guide } : null
+    }
+    if (guideWeak.length === 0 && guideDeep.length === 0) return null
+    return { text: (text.length > 120 || (guideComplexRe !== undefined && guideComplexRe.test(text))) ? guideDeep : guideWeak }
+  }
+}
+
+/**
+ * custom-fallback:自定义锚定词命中后注入一次，未命中最多两轮兜底。
+ * 参数全部来自 config.params（由 preset.yml 单一配置源下发）。
+ */
+function createCustomFallbackResolver(config) {
+  const promptText = config.texts.length > 0
+    ? config.texts.join('\n\n')
+    : (typeof config.params?.text === 'string' && config.params.text.length > 0 ? config.params.text : undefined)
+  const firstTurnWord = typeof config.params?.firstTurnWord === 'string' && config.params.firstTurnWord.length > 0
+    ? config.params.firstTurnWord
+    : 'we'
+  // 锚定匹配经 anchor-match 引擎（prefix 模式：首轮 reasoning 开头命中锚定词）。
+  const anchor = createAnchorMatcher({ keys: [firstTurnWord], mode: 'prefix' })
+
+  const anchorScanned = new Map()
+
+  const isAnchorConfirmed = (agent) => {
+    const session = agent.session
+    const cached = anchorScanned.get(session.id)
+    if (cached !== undefined) return cached
+    const first = session.events.find((event) => event.type === 'assistant/message')
+    if (first === undefined) return false
+    const content = first.data?.message?.content ?? []
+    const reasoning = content.find((block) => block.type === 'reasoning')
+    const confirmed = reasoning !== undefined && anchor.scan(String(reasoning.text ?? '')).active
+    anchorScanned.set(session.id, confirmed)
+    return confirmed
+  }
+
+  const assistantRounds = (agent) =>
+    agent.session.events.filter((event) => event.type === 'assistant/message').length
+
+  return ({ agent }) => {
+    if (promptText === undefined) return null
+    const session = agent.session
+    const confirmed = isAnchorConfirmed(agent)
+    if (!confirmed && assistantRounds(agent) <= 1) return null
+    return {
+      text: promptText,
+      source: {
+        kind: 'plugin',
+        plugin: config.id,
+        form: 'notice',
+        summary: confirmed
+          ? `prompt-tool 提示词(「${firstTurnWord}」锚定确认后注入)`
+          : `prompt-tool 提示词(「${firstTurnWord}」未确认,兜底注入)`,
+      },
+    }
+  }
+}
+
+/**
+ * world-book:世界书条目(角色卡 lorebook)。constant=true 恒注入(不扫 keys);
+ * selective 条目扫描当前消息批文本,keys/secondaryKeys 按 selectiveLogic 组合
+ * (any=任一命中 / all=副键全中 / not=副键全不中)。匹配经 anchor-match 引擎。
+ */
+function createWorldBookResolver(config) {
+  const constant = config.params?.constant === true
+  // selectiveLogic：ST world_info_logic 0=AND_ANY 1=NOT_ALL 2=NOT_ANY 3=AND_ALL。
+  const rawLogic = config.params?.selectiveLogic
+  const logic = rawLogic === 3
+    ? MATCH_LOGIC.ALL
+    : (rawLogic === 1
+      ? MATCH_LOGIC.NOT
+      : (rawLogic === 2 ? MATCH_LOGIC.NOT_ANY : MATCH_LOGIC.ANY))
+  const matcher = createAnchorMatcher({
+    keys: Array.isArray(config.params?.keys) ? config.params.keys : [],
+    secondaryKeys: Array.isArray(config.params?.secondaryKeys) ? config.params.secondaryKeys : [],
+    caseSensitive: config.params?.caseSensitive === true,
+    wholeWords: config.params?.wholeWords === true,
+    useRegex: config.params?.useRegex === true,
+    logic,
+  })
+  // ST 语义：constant 或无任何键的条目恒注入（always active）。
+  const hasAnyKey = (Array.isArray(config.params?.keys) ? config.params.keys : [])
+      .some((key) => String(key).trim().length > 0)
+    || (Array.isArray(config.params?.secondaryKeys) ? config.params.secondaryKeys : [])
+      .some((key) => String(key).trim().length > 0)
+  const promptText = config.texts.length > 0
+    ? config.texts.join('\n\n')
+    : (typeof config.params?.text === 'string' && config.params.text.length > 0 ? config.params.text : undefined)
+  return ({ messages }) => {
+    if (promptText === undefined) return null
+    if (constant || !hasAnyKey) return { text: promptText }
+    const haystack = (Array.isArray(messages) ? messages : [])
+      .map((message) => extractText(message))
+      .filter((text) => text.length > 0)
+      .join('\n')
+    if (haystack.length === 0) return null
+    return matcher.scan(haystack).active ? { text: promptText } : null
+  }
+}
+
+/**
+ * 为归一化后的提示词配置绑定策略 resolve(策略状态随提示词配置对象,不随 apply)。
+ * strategyDir:外部策略模块目录(相对本文件 URL)。未声明时只允许内置策略。
+ */
+export function bindResolver(config, strategyDir) {
+  switch (config.strategy) {
+    case 'placeholder': return createPlaceholderResolver(config)
+    case 'instruction-hint': return createInstructionHintResolver(config)
+    case 'first-turn-anchor': return createFirstTurnAnchorResolver(config)
+    case 'guide-auto': return createGuideAutoResolver(config)
+    case 'custom-fallback':
+      return createCustomFallbackResolver(config)
+    case 'world-book':
+      return createWorldBookResolver(config)
+    case 'static': {
+      const texts = config.texts
+      const patch = config.templatePatch ?? {}
+      return () => {
+        if (texts.length > 0) return { ...patch, content: texts.map((item) => ({ type: 'text', text: item })) }
+        return null
+      }
+    }
+    default: {
+      // 模板专属策略:懒加载 <strategyDir>/<strategy>.mjs,模块约定导出
+      // `createResolver(config)` 或默认导出同名工厂。加载失败按单配置失败语义
+      // 抛给调用方(executor 会跳过该配置并 warnOnce)。
+      if (typeof strategyDir !== 'string' || strategyDir.length === 0) {
+        throw new TypeError(`${name}: unknown config strategy ${JSON.stringify(config.strategy)}`)
+      }
+      const moduleUrl = new URL(`${config.strategy}.mjs`, strategyDir.endsWith('/') ? strategyDir : `${strategyDir}/`)
+      let loaded
+      return async (args) => {
+        if (loaded === undefined) {
+          loaded = await import(moduleUrl.href)
+        }
+        const make = typeof loaded.createResolver === 'function'
+          ? loaded.createResolver
+          : typeof loaded.default === 'function'
+            ? loaded.default
+            : undefined
+        if (typeof make !== 'function') {
+          throw new TypeError(`${name}: strategy module ${moduleUrl.href} must export createResolver(config)`)
+        }
+        return make(config)(args)
+      }
+    }
+  }
+}