dsh-plugin-prompt-tool 0.7.2 → 0.8.0

package/engine/st-macros.d.mts

@@ -0,0 +1,22 @@
+/** 数字运算保留 number；JSON 数组以字符串保存，与 ST 变量存储一致。 */
+export type StVariableTable = Record<string, string | number>
+
+export interface StTextOptions {
+  variables?: Readonly<Record<string, unknown>>
+  local?: StVariableTable
+  global?: StVariableTable
+  /** 原样传给 interpolateVariables，仅供读取会话事实。 */
+  session?: unknown
+  sourceId?: string
+  warn?: (message: string) => void
+}
+
+/** 清理注释/trim/ERA、归一宏写法、替换已知角色与默认用户；不求值变量。 */
+export function prepareStText(text: string, cardName?: string): string
+
+/**
+ * 顺序求值，仅修改显式 local/global；getvar 的非空 fallback 初始化所属表。
+ * 未知普通引用保留；危险键拒绝并 warn；循环、超过 32 层或 1 MiB 抛 RangeError。
+ * 另设总展开工作量上限，防止零输出的重复展开耗尽资源。
+ */
+export function renderStText(text: string, options?: StTextOptions): string

package/engine/st-macros.mjs

@@ -0,0 +1,208 @@
+/** ST 文本预处理与顺序求值；状态只归调用方传入的 local/global 所有。 */
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { interpolateVariables, normalizeMacroSyntax } from './interpolate.mjs'
+
+const MAX_BYTES = 1024 * 1024
+const MAX_DEPTH = 32
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+const DISCARDED_MACRO = /^\s*(?:\/\/|(?:trim|ERA)(?=$|[:\s]))/i
+
+function byteLength(text) {
+  const size = Buffer.byteLength(text, 'utf8')
+  if (size > MAX_BYTES) throw new RangeError('ST macro text exceeds 1 MiB')
+  return size
+}
+
+/** 双花括号是宏边界；JSON 单花括号及字符串内的右括号不是。 */
+function macroEnd(text, start, depth = 0) {
+  const frames = [{ braces: 0, brackets: 0, quote: false, escape: false }]
+  if (depth >= MAX_DEPTH) throw new RangeError('ST macro depth exceeds 32')
+  for (let index = start + 2; index < text.length; index++) {
+    const frame = frames.at(-1)
+    const char = text[index]
+    if (frame.escape) {
+      frame.escape = false
+      continue
+    }
+    if (frame.quote && char === '\\') {
+      frame.escape = true
+      continue
+    }
+    if (char === '"' && (frame.quote || frame.braces > 0 || frame.brackets > 0)) {
+      frame.quote = !frame.quote
+      continue
+    }
+    if (text.startsWith('{{', index)) {
+      if (depth + frames.length >= MAX_DEPTH) throw new RangeError('ST macro depth exceeds 32')
+      frames.push({ braces: 0, brackets: 0, quote: false, escape: false })
+      index++
+      continue
+    }
+    if (frame.quote) continue
+    if (char === '{') frame.braces++
+    else if (char === '}' && frame.braces > 0) frame.braces--
+    else if (text.startsWith('}}', index)) {
+      frames.pop()
+      if (frames.length === 0) return index + 2
+      index++
+    } else if (char === '[') frame.brackets++
+    else if (char === ']') frame.brackets = Math.max(0, frame.brackets - 1)
+  }
+  return -1
+}
+
+/** 先找到完整边界再求值，未闭合宏的内部指令不会被意外执行。 */
+function transformText(text, macro) {
+  let work = 0
+  function walk(source, depth = 0, path = '') {
+    work += byteLength(source)
+    // 零输出的重复变量展开也必须有界，不能只限制最终输出。
+    if (work > MAX_BYTES * MAX_DEPTH) throw new RangeError('ST macro expansion work limit exceeded')
+    const chunks = []
+    let size = 0
+    const append = (value) => {
+      size += byteLength(value)
+      if (size > MAX_BYTES) throw new RangeError('ST macro output exceeds 1 MiB')
+      chunks.push(value)
+    }
+    let cursor = 0
+    while (cursor < source.length) {
+      const start = source.indexOf('{{', cursor)
+      if (start < 0) {
+        append(source.slice(cursor))
+        break
+      }
+      append(source.slice(cursor, start))
+      const end = macroEnd(source, start, depth)
+      if (end < 0) {
+        if (!DISCARDED_MACRO.test(source.slice(start + 2))) append(source.slice(start))
+        break
+      }
+      append(macro(source.slice(start + 2, end - 2), (value) => walk(value, depth + 1, `${path}/${start}`), `${path}/${start}`))
+      cursor = end
+    }
+    return chunks.join('')
+  }
+  return walk(text)
+}
+
+/** 只分割当前层的第一个 ::，嵌套宏中的分隔符属于嵌套宏。 */
+function splitArgument(text) {
+  for (let index = 0; index < text.length; index++) {
+    if (text.startsWith('{{', index)) {
+      const end = macroEnd(text, index)
+      if (end < 0) break
+      index = end - 1
+    } else if (text.startsWith('::', index)) {
+      return [text.slice(0, index), text.slice(index + 2)]
+    }
+  }
+  return [text, undefined]
+}
+
+/** 对齐 ST getVariable 的数值转换；空白文本仍是文本。 */
+function stValue(value) {
+  return (typeof value === 'string' && value.trim() === '') || Number.isNaN(Number(value))
+    ? (value || '')
+    : Number(value)
+}
+
+function addValue(value, increment) {
+  const current = stValue(value) || 0
+  byteLength(String(current))
+  let parsed
+  try { parsed = JSON.parse(current) } catch { /* 非 JSON 值继续按数字或文本处理。 */ }
+  if (Array.isArray(parsed)) {
+    parsed.push(increment)
+    return JSON.stringify(parsed)
+  }
+  const amount = Number(increment)
+  if (Number.isNaN(amount) || Number.isNaN(Number(current))) return String(current || '') + increment
+  const result = Number(current) + amount
+  return Number.isNaN(result) ? undefined : result
+}
+
+/** 不求值变量/动态宏，不执行 ERA 内容；未知角色名留给运行时。 */
+export function prepareStText(text, cardName = '') {
+  const name = cardName.trim()
+  return transformText(text, (body, expand) => {
+    if (DISCARDED_MACRO.test(body)) return ''
+    if (/^char$/i.test(body) && name) return name
+    if (/^user$/i.test(body)) return '用户'
+    return normalizeMacroSyntax(`{{${expand(body)}}}`)
+  }).replace(/(?:\r?\n){3,}/g, '\n\n').trim()
+}
+
+/** 按出现顺序求值；variables/session 只读，不持久化或缓存任何状态。 */
+export function renderStText(text, { variables = {}, local = {}, global = {}, session, sourceId = '', warn = () => {} } = {}) {
+  const sourceKey = createHash('sha256').update(sourceId).update(text).digest('hex')
+  const tables = { local, global, variables }
+  const resolving = new Set()
+  const allowed = (key) => {
+    if (key && !FORBIDDEN_KEYS.has(key)) return true
+    warn(`ST variable key blocked: ${key}`)
+    return false
+  }
+  const write = (table, key, value) => {
+    if (value === undefined) return
+    byteLength(String(value))
+    // 禁止危险键，并显式定义 own 数据属性，避免触发继承的 setter。
+    Object.defineProperty(table, key, { value, writable: true, enumerable: true, configurable: true })
+  }
+  const read = (scope, key, expand, numeric = false) => {
+    const id = `${scope}:${key}`
+    if (resolving.has(id)) throw new RangeError(`ST variable cycle: ${id}`)
+    resolving.add(id)
+    try {
+      const value = tables[scope][key]
+      return expand(String((numeric ? stValue(value) : value) ?? ''))
+    } finally {
+      resolving.delete(id)
+    }
+  }
+
+  return transformText(text, (body, expand, path) => {
+    if (DISCARDED_MACRO.test(body)) return ''
+    const [name, args] = splitArgument(body)
+    const operation = /^(set|add|get|inc|dec)(global)?var$/i.exec(name.trim())
+    if (operation && args !== undefined) {
+      const [rawKey, rawValue] = splitArgument(args)
+      const key = expand(rawKey).trim()
+      if (!allowed(key)) return ''
+      const action = operation[1].toLowerCase()
+      const scope = operation[2] ? 'global' : 'local'
+      const table = tables[scope]
+      const exists = Object.hasOwn(table, key)
+      if (action === 'get') {
+        if (exists) return read(scope, key, expand, true)
+        if (scope === 'local' && Object.hasOwn(variables, key)) return read('variables', key, expand, true)
+        if (rawValue === undefined) return ''
+        const fallback = expand(rawValue)
+        if (fallback !== '') write(table, key, fallback)
+        return fallback
+      }
+      if ((action === 'set' || action === 'add') && rawValue !== undefined) {
+        const value = expand(rawValue)
+        write(table, key, action === 'set' ? value : addValue(exists ? table[key] : '', value))
+        return ''
+      }
+      if ((action === 'inc' || action === 'dec') && rawValue === undefined) {
+        const value = addValue(exists ? table[key] : '', action === 'inc' ? 1 : -1)
+        write(table, key, value)
+        return String(value ?? '')
+      }
+      return `{{${body}}}`
+    }
+
+    const whole = normalizeMacroSyntax(`{{${expand(body)}}}`)
+    const [key] = splitArgument(whole.slice(2, -2))
+    if (!allowed(key)) return whole
+    if (Object.hasOwn(local, key)) return read('local', key, expand)
+    if (Object.hasOwn(variables, key)) return read('variables', key, expand)
+    if (/^user$/i.test(key)) return '用户'
+    // 未解析的嵌套引用交给官方出口清洗，不让扁平插值器截断它。
+    if (whole.slice(2, -2).includes('{{')) return whole
+    return interpolateVariables(whole, {}, session, undefined, `${sourceKey}:${path}`)
+  })
+}

package/engine/st-render.mjs

@@ -0,0 +1,105 @@
+/** ST 模板变量帧：只求值显式导入的模板，不决定任何官方插入点的执行顺序。 */
+import { createHash } from 'node:crypto'
+import { renderStText } from './st-macros.mjs'
+import { sessionVarsSnapshot } from './session-vars.mjs'
+import { sessionEvents, isDelegated, matchesModel } from './shared.mjs'
+import { stripUnresolvedRefs } from './interpolate.mjs'
+import { isSuccessfulCompactionEnd } from './compaction-epoch.mjs'
+
+function visible(config, agent) {
+  if (config.enabled === false) return false
+  const delegated = isDelegated(agent?.session)
+  if (config.audience === 'main' && delegated) return false
+  if (config.audience === 'subagent' && !delegated) return false
+  return matchesModel(config.modelScope, agent?.options?.model)
+}
+
+/** 历史与尚未入库的真实输入使用同一消息身份；插件注入消息不触发第二次赋值。 */
+function generationKey(session, pending) {
+  const events = sessionEvents(session)
+  // 宿主先 assemble/pre-step，之后才 append step/start；不能用 step/start 切帧。
+  const boundary = events.findLast(event => event?.type === 'turn/start' || event?.type === 'step/end' || isSuccessfulCompactionEnd(event))
+  if (boundary) return JSON.stringify([boundary.type, boundary.seq, boundary.data?.turn, boundary.data?.step])
+  const seen = new Set()
+  const hash = createHash('sha256')
+  const add = (message, kind) => {
+    if (!message || message.source?.plugin || (message.source?.kind && message.source.kind !== 'user')) return
+    const value = JSON.stringify([kind, message.id ?? null, message.content ?? []])
+    if (seen.has(value)) return
+    seen.add(value)
+    hash.update(value)
+  }
+  for (const event of events) {
+    if (event?.type === 'user/message' || event?.type === 'assistant/message') {
+      add(event.data?.message ?? event.data, event.type)
+    } else if (event?.type === 'tool/call') hash.update(JSON.stringify([event.type, event.seq, event.data?.id]))
+  }
+  for (const message of pending) add(message, `${message.role ?? 'user'}/message`)
+  return hash.digest('hex')
+}
+
+export function attachStRenderers(configs) {
+  const claimed = new Set()
+  const templates = configs.filter(config => {
+    if (config.enabled === false) return false
+    if (config.group !== undefined && config.exclusive === true) {
+      if (claimed.has(config.group)) return false
+      claimed.add(config.group)
+    }
+    return config.params?.stMacros === true
+  })
+  if (!templates.length) return configs
+  // 状态只活在本次 mount 与会话对象的生命周期内；不持有会话 id 的无界全局 Map。
+  const sessions = new WeakMap()
+  const tokens = new WeakMap()
+  for (const target of templates) {
+    target.renderSt = (agent, messages = [], warn = () => {}, token, eligible) => {
+      // 官方 assembly 只拥有两个文本插入点；pre-step 的资格由执行器确认。
+      const approved = config => visible(config, agent) && (eligible === undefined
+        ? (config.layer === 'system-section' || config.layer === 'runtime-context') && config.promotion === 'none'
+        : eligible.has(config.renderSt))
+      if (!approved(target)) return ''
+      const session = agent?.session
+      const cached = token && tokens.get(token)
+      if (cached) {
+        if (!cached.text.has(target)) cached.evaluate(target)
+        return cached.text.get(target) ?? ''
+      }
+      const manual = sessionVarsSnapshot(session)
+      const generation = generationKey(session, messages)
+      const key = `${generation}:${JSON.stringify(manual)}`
+      const previous = session && sessions.get(session)
+      let frame = previous
+      if (!frame || frame.key !== key) {
+        const initialLocal = { ...(previous?.generation === generation ? previous.initialLocal : previous?.local), ...manual }
+        for (const key of Object.keys(previous?.manual ?? {})) if (!Object.hasOwn(manual, key)) delete initialLocal[key]
+        const initialGlobal = { ...(previous?.generation === generation ? previous.initialGlobal : previous?.global) }
+        frame = { key, generation, manual, initialLocal, initialGlobal, local: { ...initialLocal }, global: { ...initialGlobal }, text: new Map() }
+        const evaluate = config => {
+          try {
+            const local = { ...frame.local }, global = { ...frame.global }
+            const text = renderStText(config.texts.join('\n\n'), { variables: config.variables, local, global, session, sourceId: config.id, warn })
+            const cleaned = stripUnresolvedRefs(text)
+            if (cleaned.stripped.length) warn(`prompt-config-engine: ST 模板 ${config.id} 有 ${cleaned.stripped.length} 处未支持引用，已移除`)
+            frame.local = local
+            frame.global = global
+            frame.text.set(config, cleaned.text)
+          } catch (error) {
+            frame.text.set(config, '')
+            warn(`prompt-config-engine: ST 模板 ${config.id} 求值失败：${String(error?.message ?? error)}`)
+          }
+        }
+        frame.evaluate = evaluate
+        if (session) sessions.set(session, frame)
+      }
+      // 同一帧允许后到的 pre-step 资格补入；已求值模板不重放副作用或随机宏。
+      for (const config of templates.filter(config => approved(config)
+        && config.strategy === 'static' && config.dedupe === 'none' && !frame.text.has(config))
+        .sort((a, b) => a.order - b.order)) frame.evaluate(config)
+      if (token && typeof token === 'object') tokens.set(token, frame)
+      if (!frame.text.has(target)) frame.evaluate(target)
+      return frame.text.get(target) ?? ''
+    }
+  }
+  return configs
+}

package/engine/st-world-book.d.mts

@@ -0,0 +1,10 @@
+/** 引擎侧 TS 类型声明（运行期实现在 st-world-book.mjs；仅 src/ 侧导入需要）。 */
+export interface WorldBookDiagnosticsSnapshot {
+  records: Array<{ id: string; stage: string; reason: string; [key: string]: unknown }>
+  truncated: boolean
+  step: number
+  /** false = 该会话尚未求值；true = 已求值（records 为空表示本次没有参与/入选条目）。 */
+  evaluated: boolean
+}
+export function lastWorldBookDiagnostics(session: unknown): WorldBookDiagnosticsSnapshot
+export function selectStWorldBook(...args: unknown[]): Set<Record<string, unknown>> & { diagnostics?: { records: unknown[]; truncated: boolean } }

package/engine/st-world-book.mjs

@@ -0,0 +1,259 @@
+/** ST 世界书选择器；只消费显式 ST 导入字段，不改变原生 world-book 约定。 */
+import { createAnchorMatcher } from './anchor-match.mjs'
+import { sessionEvents } from './shared.mjs'
+import { interpolateVariables } from './interpolate.mjs'
+
+/** 只扫描真实对话的可见文本，排除插件注入与思维块。 */
+export function stChatMessages(session, pending = []) {
+  const result = [], ids = new Set()
+  const add = (message, role) => {
+    if (!message || !['user', 'assistant'].includes(role) || message.source?.plugin
+      || (message.source?.kind && message.source.kind !== 'user')) return
+    if (message.id && ids.has(message.id)) return
+    if (message.id) ids.add(message.id)
+    const text = (Array.isArray(message.content) ? message.content : []).filter(block => block.type === 'text' || block.type === undefined).map(block => block.text ?? '').join('')
+    result.push({ id: message.id, role, text })
+  }
+  for (const event of sessionEvents(session)) {
+    if (event?.type === 'user/message' || event?.type === 'assistant/message') add(event.data?.message ?? event.data, event.type.split('/')[0])
+  }
+  for (const message of pending) add(message, message.role ?? 'user')
+  return result
+}
+
+const sessions = new WeakMap()
+const matchers = new WeakMap()
+/** 每个会话只保留最近一次选择的诊断快照（随会话对象 GC 释放）。 */
+const lastRuns = new WeakMap()
+const count = (value, fallback = 0) => Number.isSafeInteger(value) && value >= 0 ? Math.min(value, 1000) : fallback
+
+/** 只读诊断上限：只截断观测记录，绝不改变入选、抽样与时间窗状态。 */
+const DIAGNOSTIC_LIMIT = 200
+
+/** 最近一次世界书选择诊断（只读快照；无记录时返回空集合，不触发任何求值）。
+ *  `evaluated: false` 表示该会话还没求值过，与"已求值但本次为空"区分开。 */
+export function lastWorldBookDiagnostics(session) {
+  return lastRuns.get(session) ?? { records: [], truncated: false, step: 0, evaluated: false }
+}
+
+export function selectStWorldBook(configs, session, messages, warn = () => {}) {
+  const entries = configs.filter(config => config.enabled !== false && config.strategy === 'world-book' && config.params?.stWorldBook)
+  // 本次选择的有界观测快照：`selection.diagnostics` 与会话最近快照引用**同一对象**，
+  // 因此 commit 阶段追加记录或把 truncated 置真都写回同一份事实（不复制布尔值，
+  // 否则 commit 越限时读取端仍看到 truncated=false）。
+  const snapshot = { records: [], truncated: false, step: 0, evaluated: true }
+  const note = (config, stage, reason, extra) => {
+    if (snapshot.records.length >= DIAGNOSTIC_LIMIT) { snapshot.truncated = true; return }
+    snapshot.records.push({ id: String(config.id ?? ''), stage, reason, ...extra })
+  }
+  const finish = selection => {
+    selection.diagnostics = snapshot
+    // 最近一次求值总是替换快照（含空集合）：空结果不能被读成"本次又注入了旧条目"。
+    lastRuns.set(session, snapshot)
+    return selection
+  }
+  // 被显式禁用的 ST 条目：由本层负责报告，不由 UI 猜测。
+  for (const config of configs) {
+    if (config.enabled === false && config.strategy === 'world-book' && config.params?.stWorldBook) note(config, 'excluded', 'disabled')
+  }
+  if (!entries.length) return finish(new Set())
+  const chat = stChatMessages(session, messages)
+  snapshot.step = chat.length
+  let state = sessions.get(session)
+  if (!state) { state = new WeakMap(); sessions.set(session, state) }
+  const generation = JSON.stringify([chat.length, chat.at(-1)])
+  const selected = new Set(), failed = new Set(), occupied = new Set(), stickyEntries = new Set(), candidates = []
+  const updates = new Map()
+  selected.commit = config => {
+    if (!selected.has(config)) return
+    note(config, 'committed', 'injected')
+    if (updates.has(config)) state.set(config, updates.get(config))
+  }
+  const priority = [...entries].sort((a, b) => b.order - a.order)
+  const recursiveText = []
+  // ST 的延迟层级池（world-info.js:4753-4762）：只收真值，true 归一为 1，升序去重；
+  // 初始化即取走最小层级，因此「延迟到第 N 层」的条目在首次递归 pass 就能解锁；
+  // 层级只增不减（:5131），已打开的层级对后续 pass 保持打开。
+  const delayLevels = [...new Set(entries
+    .map(config => config.params.stWorldBook.delayUntilRecursion)
+    .filter(Boolean)
+    .map(value => value === true ? 1 : value))].sort((a, b) => a - b)
+  let delayLevel = delayLevels.shift() ?? 0
+  const hasRecursive = entries.some(config => config.params.stWorldBook.recursive === true)
+  /** 键匹配器（按 params 对象缓存；签名含插值后的键与匹配选项）。 */
+  const matcherOf = (config, material) => {
+    const p = config.params
+    const signature = JSON.stringify([material.keys, material.secondaryKeys, p.caseSensitive, p.wholeWords, p.useRegex])
+    let compiled = matchers.get(p)
+    if (compiled?.signature !== signature) {
+      compiled = { signature, matcher: createAnchorMatcher({ keys: material.keys, secondaryKeys: material.secondaryKeys, caseSensitive: p.caseSensitive === true, wholeWords: p.wholeWords === true, useRegex: p.useRegex, stWords: true }) }
+      matchers.set(p, compiled)
+    }
+    return compiled.matcher
+  }
+  // 每个继续的 pass 至少新增一条或消耗一个延迟层级；预算覆盖两种推进，仍是有限闭包。
+  const maxPasses = entries.length + delayLevels.length
+  for (let pass = 0; pass <= maxPasses; pass++) {
+    candidates.length = 0
+    // 每 pass 的扫描材料缓存：递归文本随 pass 变化，材料必须按 pass 重新构造；
+    // 材料只被匹配与评分读取，构造本身不改变入选结果。
+    const scanCache = new Map()
+    const scanOf = (config, st) => {
+      let material = scanCache.get(config)
+      if (material !== undefined) return material
+      const depth = count(st.scanDepth, 2)
+      const parts = depth === 0 ? [] : chat.slice(-depth).reverse().map(message => message.text)
+      // 角色字段扫描（ST globalScanData，world-info.js:294-320）：每个开关只在对应变量
+      // 有值时并入扫描文本；creator_notes / depth_prompt 由导入期登记（未开启不并入，
+      // 既有触发面不变）。
+      for (const [flag, key] of [['matchCharacterDescription', 'description'], ['matchCharacterPersonality', 'personality'], ['matchScenario', 'scenario'], ['matchPersonaDescription', 'persona'], ['matchCreatorNotes', 'creator_notes'], ['matchCharacterDepthPrompt', 'depth_prompt']]) {
+        if (depth > 0 && st[flag] === true && typeof config.variables[key] === 'string') parts.push(config.variables[key])
+      }
+      if (pass > 0 && depth > 0) parts.push(...recursiveText)
+      const p = config.params
+      const keys = (Array.isArray(p.keys) ? p.keys : []).map(key => interpolateVariables(String(key), config.variables, session)).filter(Boolean)
+      // 空宏仍是一项未命中的副键：匹配器忽略空值，但 AND_ALL/NOT_ALL 的总数不能缩水。
+      const secondaryKeys = (Array.isArray(p.secondaryKeys) ? p.secondaryKeys : []).map(key => interpolateVariables(String(key), config.variables, session))
+      material = { depth, keys, secondaryKeys, text: parts.length ? '\x01' + parts.join('\n\x01') : '' }
+      scanCache.set(config, material)
+      return material
+    }
+    // ST getScore 等价（world-info.js:428-473）：只统计命中数，否定逻辑（NOT_ALL/NOT_ANY）
+    // 不参与加分，主键为空记 0 分。
+    const scoreOf = (config, st) => {
+      const material = scanOf(config, st)
+      const match = matcherOf(config, material).scan(material.text)
+      if (material.keys.length === 0) return 0
+      if (material.secondaryKeys.length === 0) return match.primary
+      const logic = config.params.selectiveLogic ?? 0
+      if (logic === 0) return match.primary + match.secondary
+      if (logic === 3) return match.secondary === material.secondaryKeys.length ? match.primary + match.secondary : match.primary
+      return match.primary
+    }
+    for (const config of priority) {
+      if (selected.has(config) || failed.has(config)) continue
+      const p = config.params, st = p.stWorldBook
+      const previous = state.get(config)
+      const sticky = previous?.last !== undefined && count(st.sticky) > 0 && chat.length < previous.last + count(st.sticky)
+      if (sticky) { stickyEntries.add(config); note(config, 'candidate', 'sticky') }
+      if (chat.length < count(st.delay)) { note(config, 'excluded', 'delay', { delay: count(st.delay), messages: chat.length }); continue }
+      if (!sticky && previous?.last !== undefined && count(st.cooldown) > 0 && chat.length > previous.last
+        && chat.length < previous.last + count(st.sticky) + count(st.cooldown)) { note(config, 'excluded', 'cooldown'); continue }
+      // ST 的延迟门控（world-info.js:4860-4868）：非递归 pass 一律抑制（sticky 例外，
+      // constant 也不例外）；递归 pass 中层级未到同样抑制。比较用条目原始值。
+      const delayUntil = st.delayUntilRecursion
+      if (!sticky && delayUntil && (pass === 0 || delayUntil > delayLevel)) {
+        note(config, 'excluded', 'delay-until-recursion', { delayUntilRecursion: delayUntil, level: delayLevel, pass })
+        continue
+      }
+      // 递归 pass 的参与资格：excludeRecursion 对任何条目生效；其余条目仍要求自身声明
+      // recursive（延迟条目由层级池驱动，ST 的门控不要求全局 recursive）。
+      if (pass > 0 && (st.excludeRecursion === true || (!delayUntil && st.recursive !== true))) { note(config, 'excluded', 'recursion'); continue }
+      let active = sticky || p.constant === true
+      let activation = sticky ? 'sticky' : p.constant === true ? 'constant' : 'key-match'
+      if (!active) {
+        const material = scanOf(config, st)
+        try {
+          const match = matcherOf(config, material).scan(material.text)
+          active = match.primary > 0
+          const logic = p.selectiveLogic ?? 0
+          const detail = { scanDepth: material.depth, primary: match.primary, secondary: match.secondary, secondaryKeys: material.secondaryKeys.length, logic }
+          if (active && st.selective === true && material.secondaryKeys.length > 0) {
+            active = logic === 1 ? match.secondary < material.secondaryKeys.length : logic === 2 ? match.secondary === 0
+              : logic === 3 ? match.secondary === material.secondaryKeys.length : match.secondary > 0
+            if (!active) note(config, 'rejected', 'secondary-miss', detail)
+          } else if (!active) {
+            note(config, 'rejected', 'primary-miss', detail)
+          }
+        } catch (error) {
+          note(config, 'rejected', 'match-error', { message: String(error?.message ?? error).slice(0, 120) })
+          warn(`prompt-config-engine: 世界书 ${config.id} 匹配失败：${String(error?.message ?? error)}`)
+          failed.add(config)
+          continue
+        }
+      }
+      if (!active) continue
+      const probability = typeof st.probability === 'number' && Number.isFinite(st.probability) ? Math.max(0, Math.min(100, st.probability)) : 100
+      const roll = previous?.generation === generation ? previous.roll : Math.random() * 100
+      state.set(config, { ...previous, generation, roll })
+      if (!sticky && st.useProbability !== false && (probability <= 0 || roll >= probability)) {
+        note(config, 'rejected', 'probability', { probability, roll })
+        failed.add(config)
+        continue
+      }
+      note(config, 'candidate', activation, { probability, useProbability: st.useProbability !== false })
+      candidates.push(config)
+    }
+    if (!candidates.length && !delayLevels.length) break
+    const groups = new Map()
+    for (const config of candidates) {
+      const names = String(config.params.stWorldBook.group ?? '').split(',').map(name => name.trim()).filter(Boolean)
+      if (!names.length) { selected.add(config); note(config, 'selected', 'ungrouped'); continue }
+      if (names.some(name => occupied.has(name))) { note(config, 'rejected', 'group-occupied'); failed.add(config); continue }
+      for (const name of names) { const members = groups.get(name) ?? []; members.push(config); groups.set(name, members) }
+    }
+    for (const [name, members] of groups) {
+      if (occupied.has(name)) continue
+      let remaining = members.filter(config => !failed.has(config) && !String(config.params.stWorldBook.group).split(',').some(group => occupied.has(group.trim())))
+      if (!remaining.length) continue
+      const sticky = remaining.filter(config => stickyEntries.has(config))
+      // 组内评分（ST filterGroupsByScoring 5292-5328）：无全局开关时，只要组内存在显式
+      // 开启 useGroupScoring 的条目就整组参与评分；组内有 sticky 时整组跳过（5300-5305）。
+      // 只有开启评分的条目会被淘汰（严格小于最高分）；未开启者不被淘汰，但其分数计入最高分。
+      const scoreOut = new Set()
+      if (!sticky.length && remaining.some(config => config.params.stWorldBook.useGroupScoring === true)) {
+        let scores
+        try {
+          scores = remaining.map(config => scoreOf(config, config.params.stWorldBook))
+        } catch (error) {
+          scores = undefined
+          warn(`prompt-config-engine: 世界书分组评分失败：${String(error?.message ?? error)}`)
+        }
+        if (scores !== undefined) {
+          const maxScore = Math.max(...scores)
+          const survivors = []
+          for (const [index, config] of remaining.entries()) {
+            if (config.params.stWorldBook.useGroupScoring !== true || scores[index] >= maxScore) { survivors.push(config); continue }
+            note(config, 'rejected', 'group-score-lost', { group: name, score: scores[index], maxScore })
+            scoreOut.add(config)
+            failed.add(config)
+          }
+          remaining = survivors
+          if (!remaining.length) continue
+        }
+      }
+      const overriding = sticky.length ? sticky : remaining.filter(config => config.params.stWorldBook.groupOverride === true)
+      const available = overriding.length ? overriding : remaining
+      const weight = config => typeof config.params.stWorldBook.groupWeight === 'number' ? Math.max(0, config.params.stWorldBook.groupWeight) : 100
+      let choice = available[0]
+      if (!overriding.length) {
+        let roll = (state.get(choice).roll / 100) * available.reduce((sum, config) => sum + weight(config), 0)
+        for (const config of available) { roll -= weight(config); if (roll < 0) { choice = config; break } }
+      }
+      selected.add(choice)
+      note(choice, 'selected', 'group-winner', { group: String(choice.params.stWorldBook.group ?? '') })
+      for (const group of String(choice.params.stWorldBook.group).split(',').map(value => value.trim()).filter(Boolean)) occupied.add(group)
+      for (const config of members) {
+        // 已按评分淘汰的成员只记 group-score-lost：它没有参与最后的组内竞争，
+        // 再记一条 group-lost 会让诊断给出两个互相矛盾的原因。
+        if (config === choice || scoreOut.has(config)) continue
+        note(config, 'rejected', 'group-lost', { group: name })
+        failed.add(config)
+      }
+    }
+    const added = candidates.filter(config => selected.has(config))
+    if (!added.length && !delayLevels.length) break
+    for (const config of added) {
+      const previous = state.get(config)
+      // sticky 期间的重发不延长有效期；新命中才开始下一段窗口。
+      if (previous.last === undefined || chat.length >= previous.last + count(config.params.stWorldBook.sticky)) updates.set(config, { ...previous, last: chat.length })
+    }
+    // 递归驱动优先于延迟层级（ST world-info.js:5097-5133）：有新正文可递归时层级保持不变；
+    // 没有新正文而层级池仍有剩余时打开下一层继续扫描；两者都没有才结束。
+    const recursiveAdds = hasRecursive ? added.filter(config => config.params.stWorldBook.preventRecursion !== true) : []
+    if (recursiveAdds.length) recursiveText.push(...recursiveAdds.map(config => config.texts.join('\n')))
+    else if (delayLevels.length) delayLevel = delayLevels.shift()
+    else break
+  }
+  return finish(selected)
+}