dsh-plugin-prompt-tool 2.1.0 → 3.0.1

package/engine/{st-world-book.mjs → context-activation.mjs}

@@ -1,20 +1,29 @@
-/** ST 世界书选择器；只消费显式 ST 导入字段，不改变原生 world-book 约定。 */
+/** 原生上下文激活选择器；扫描、候选池与实际投递提交共用一条运行链。 */
 import { createAnchorMatcher } from './anchor-match.mjs'
-import { sessionEvents } from './shared.mjs'
-import { interpolateVariables } from './interpolate.mjs'
+import { currentEvents, historyEvents } from './history.mjs'
+import { evaluateTemplate } from './template-evaluation.mjs'
+import { isConversationMessage } from './condition-facts.mjs'
+import { isSuccessfulCompactionEnd } from './compaction-epoch.mjs'
 
-/** 只扫描真实对话的可见文本，排除插件注入与思维块。 */
-export function stChatMessages(session, pending = []) {
+/** 只扫描真实对话的可见文本，排除插件注入与思维块（判据与 userText / 关键词 haystack 同源）。 */
+export function conversationMessages(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 || !['user', 'assistant'].includes(role) || !isConversationMessage(message)) 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)) {
+  // 关键词世界书由**模型看得见的**对话触发；被压缩遮蔽的旧对话不该再持续命中条目。
+  // 位置替换后同一 seq 可在 `surface.nodes` 里占多个位置（`history.mjs` 头部）：无 id 的消息
+  // 按 id 去不掉，会重复计数并抬高 `chat.length`（它驱动 delay / sticky 窗口与概率 generation）。
+  const seenSeq = new Set()
+  for (const event of currentEvents(session)) {
+    if (event?.seq !== undefined) {
+      if (seenSeq.has(event.seq)) continue
+      seenSeq.add(event.seq)
+    }
     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')
@@ -22,6 +31,8 @@ export function stChatMessages(session, pending = []) {
 }
 
 const sessions = new WeakMap()
+/** 每个会话最近一次成功压缩在日志里的位置；前推即窗口状态的重基准点。 */
+const boundaries = new WeakMap()
 const matchers = new WeakMap()
 /** 每个会话只保留最近一次选择的诊断快照（随会话对象 GC 释放）。 */
 const lastRuns = new WeakMap()
@@ -32,12 +43,27 @@ const DIAGNOSTIC_LIMIT = 200
 
 /** 最近一次世界书选择诊断（只读快照；无记录时返回空集合，不触发任何求值）。
  *  `evaluated: false` 表示该会话还没求值过，与"已求值但本次为空"区分开。 */
-export function lastWorldBookDiagnostics(session) {
+export function lastContextActivationDiagnostics(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)
+/**
+ * 最近一次成功压缩在日志里的位置（-1 = 从未压缩）。
+ *
+ * 窗口状态（`last` 与 delay / sticky / cooldown 的基准）记的是当时的**绝对可见计数**，
+ * 而 `chat` 现在来自 `currentEvents`（可缩小的视图）：成功压缩把可见面塌成一条摘要后计数骤降，
+ * 旧基准不重则 sticky 恒真（命中早已不可见的条目）、cooldown 被静默跳过。判据与 count / anchor
+ * 的失效点同源（`isSuccessfulCompactionEnd`）；本模块的选择由批首直接调用、没有 observe 接线，
+ * 所以在批首比边界。倒序查最近一次，压缩之后的日志长度即扫描代价。
+ */
+function lastCompactionBoundary(session) {
+  const events = historyEvents(session)
+  for (let index = events.length - 1; index >= 0; index--) if (isSuccessfulCompactionEnd(events[index])) return index
+  return -1
+}
+
+export function selectContextActivation(configs, session, messages, warn = () => {}, readVariables = () => ({ module: {}, global: {} })) {
+  const entries = configs.filter(config => config.enabled !== false && config.strategy === 'context-activation')
   // 本次选择的有界观测快照：`selection.diagnostics` 与会话最近快照引用**同一对象**，
   // 因此 commit 阶段追加记录或把 truncated 置真都写回同一份事实（不复制布尔值，
   // 否则 commit 越限时读取端仍看到 truncated=false）。
@@ -54,13 +80,20 @@ export function selectStWorldBook(configs, session, messages, warn = () => {}) {
   }
   // 被显式禁用的 ST 条目：由本层负责报告，不由 UI 猜测。
   for (const config of configs) {
-    if (config.enabled === false && config.strategy === 'world-book' && config.params?.stWorldBook) note(config, 'excluded', 'disabled')
+    if (config.enabled === false && config.strategy === 'context-activation') note(config, 'excluded', 'disabled')
   }
   if (!entries.length) return finish(new Set())
-  const chat = stChatMessages(session, messages)
+  const chat = conversationMessages(session, messages)
+  const batch = conversationMessages(undefined, messages)
   snapshot.step = chat.length
+  const boundary = lastCompactionBoundary(session)
   let state = sessions.get(session)
-  if (!state) { state = new WeakMap(); sessions.set(session, state) }
+  // 边界前推说明可见视图被重写过（成功压缩）→ 丢弃本会话全部窗口，让每条条目按当前可见面重判。
+  if (boundaries.get(session) !== boundary) {
+    state = new WeakMap()
+    sessions.set(session, state)
+    boundaries.set(session, boundary)
+  }
   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()
@@ -75,18 +108,21 @@ export function selectStWorldBook(configs, session, messages, warn = () => {}) {
   // 初始化即取走最小层级，因此「延迟到第 N 层」的条目在首次递归 pass 就能解锁；
   // 层级只增不减（:5131），已打开的层级对后续 pass 保持打开。
   const delayLevels = [...new Set(entries
-    .map(config => config.params.stWorldBook.delayUntilRecursion)
+    .map(config => config.params.activation.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)
+  // 池是全批共享的（对齐 ST `world_info_recursive` 的全局扫描缓冲：新入选正文都进同一个池），
+  // 这里只决定「池是否产生内容、pass 是否由递归驱动」（层级池推进依赖后者，缺省时既有语义不变）；
+  // 谁参与重扫按模块判，来源格式中的书级或条目级递归记录不参与运行。
+  const recursive = entries.some(config => config.contextActivationRecursive === true)
   /** 键匹配器（按 params 对象缓存；签名含插值后的键与匹配选项）。 */
   const matcherOf = (config, material) => {
     const p = config.params
-    const signature = JSON.stringify([material.keys, material.secondaryKeys, p.caseSensitive, p.wholeWords, p.useRegex])
+    const signature = JSON.stringify([material.keys, material.secondaryKeys, p.caseSensitive, p.wholeWords, p.useRegex, p.wordBoundary])
     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 }) }
+      compiled = { signature, matcher: createAnchorMatcher({ keys: material.keys, secondaryKeys: material.secondaryKeys, caseSensitive: p.caseSensitive === true, wholeWords: p.wholeWords === true, useRegex: p.useRegex, wordBoundary: p.wordBoundary }) }
       matchers.set(p, compiled)
     }
     return compiled.matcher
@@ -98,122 +134,126 @@ export function selectStWorldBook(configs, session, messages, warn = () => {}) {
     // 每 pass 的扫描材料缓存：递归文本随 pass 变化，材料必须按 pass 重新构造；
     // 材料只被匹配与评分读取，构造本身不改变入选结果。
     const scanCache = new Map()
-    const scanOf = (config, st) => {
+    const scanOf = (config, activation) => {
       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])
+      const history = activation.scan === 'history'
+      const depth = count(activation.scanDepth, history ? 2 : batch.length)
+      const parts = depth === 0 ? [] : (history ? chat : batch).slice(-depth).reverse().map(message => message.text)
+      const variables = readVariables(config)
+      const render = (text, source) => evaluateTemplate(text, { ...variables, session, sourceId: `${config.sourceModuleId ?? ''}:${config.id}:${source}`, readOnly: true }).text
+      for (const key of activation.scanVariables ?? []) {
+        const value = Object.hasOwn(variables.module, key) ? variables.module[key] : Object.hasOwn(variables.global, key) ? variables.global[key] : undefined
+        if (depth > 0 && typeof value === 'string') parts.push(render(value, `scan:${key}`))
       }
+      // 池是全批共享的；开关没开的模块靠下面的 pass 门控不参与重扫（隔离不靠分池）。
       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)
+      const keys = (p.keys ?? []).map((key, index) => render(key, `keys:${index}`)).filter(Boolean)
       // 空宏仍是一项未命中的副键：匹配器忽略空值，但 AND_ALL/NOT_ALL 的总数不能缩水。
-      const secondaryKeys = (Array.isArray(p.secondaryKeys) ? p.secondaryKeys : []).map(key => interpolateVariables(String(key), config.variables, session))
+      const secondaryKeys = (p.secondaryKeys ?? []).map((key, index) => render(key, `secondaryKeys:${index}`))
       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 scoreOf = (config, activation) => {
+      const material = scanOf(config, activation)
       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
+      const logic = config.params.selectiveLogic ?? 'AND_ANY'
+      if (logic === 'AND_ANY') return match.primary + match.secondary
+      if (logic === 'AND_ALL') 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 p = config.params, activation = p.activation
       const previous = state.get(config)
-      const sticky = previous?.last !== undefined && count(st.sticky) > 0 && chat.length < previous.last + count(st.sticky)
+      const sticky = previous?.last !== undefined && count(activation.sticky) > 0 && chat.length < previous.last + count(activation.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 }
+      if (chat.length < count(activation.delay)) { note(config, 'excluded', 'delay', { delay: count(activation.delay), messages: chat.length }); continue }
+      if (!sticky && previous?.last !== undefined && count(activation.cooldown) > 0 && chat.length > previous.last
+        && chat.length < previous.last + count(activation.sticky) + count(activation.cooldown)) { note(config, 'excluded', 'cooldown'); continue }
       // ST 的延迟门控（world-info.js:4860-4868）：非递归 pass 一律抑制（sticky 例外，
       // constant 也不例外）；递归 pass 中层级未到同样抑制。比较用条目原始值。
-      const delayUntil = st.delayUntilRecursion
+      const delayUntil = activation.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 }
+      // 递归 pass 的参与资格：条目自己的 excludeRecursion（ST world-info.js:4870）与本模块开关
+      // 都要过。延迟条目由层级池驱动——层级池是全批时钟（层级只增不减），与递归正文无关，
+      // 因此不受模块递归开关门控，开关缺省时它的既有语义不变。
+      if (pass > 0 && activation.excludeRecursion === true) { note(config, 'excluded', 'recursion'); continue }
+      if (pass > 0 && config.contextActivationRecursive !== true && !delayUntil) { note(config, 'excluded', 'recursion'); continue }
       let active = sticky || p.constant === true
-      let activation = sticky ? 'sticky' : p.constant === true ? 'constant' : 'key-match'
+      const reason = sticky ? 'sticky' : p.constant === true ? 'constant' : 'key-match'
       if (!active) {
-        const material = scanOf(config, st)
         try {
+          const material = scanOf(config, activation)
           const match = matcherOf(config, material).scan(material.text)
           active = match.primary > 0
-          const logic = p.selectiveLogic ?? 0
+          const logic = p.selectiveLogic ?? 'AND_ANY'
           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 && activation.selective === true && material.secondaryKeys.length > 0) {
+            active = logic === 'NOT_ALL' ? match.secondary < material.secondaryKeys.length : logic === 'NOT_ANY' ? match.secondary === 0
+              : logic === 'AND_ALL' ? 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)}`)
+          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 probability = typeof activation.probability === 'number' && Number.isFinite(activation.probability) ? Math.max(0, Math.min(100, activation.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)) {
+      if (!sticky && activation.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 })
+      note(config, 'candidate', reason, { probability, useProbability: activation.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)
+      const names = String(config.params.activation.selectionGroup ?? '').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())))
+      let remaining = members.filter(config => !failed.has(config) && !String(config.params.activation.selectionGroup).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)) {
+      if (!sticky.length && remaining.some(config => config.params.activation.useGroupScoring === true)) {
         let scores
         try {
-          scores = remaining.map(config => scoreOf(config, config.params.stWorldBook))
+          scores = remaining.map(config => scoreOf(config, config.params.activation))
         } catch (error) {
           scores = undefined
-          warn(`prompt-config-engine: 世界书分组评分失败：${String(error?.message ?? error)}`)
+          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 }
+            if (config.params.activation.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)
@@ -222,17 +262,17 @@ export function selectStWorldBook(configs, session, messages, warn = () => {}) {
           if (!remaining.length) continue
         }
       }
-      const overriding = sticky.length ? sticky : remaining.filter(config => config.params.stWorldBook.groupOverride === true)
+      const overriding = sticky.length ? sticky : remaining.filter(config => config.params.activation.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
+      const weight = config => typeof config.params.activation.groupWeight === 'number' ? Math.max(0, config.params.activation.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)
+      note(choice, 'selected', 'group-winner', { group: String(choice.params.activation.selectionGroup ?? '') })
+      for (const group of String(choice.params.activation.selectionGroup).split(',').map(value => value.trim()).filter(Boolean)) occupied.add(group)
       for (const config of members) {
         // 已按评分淘汰的成员只记 group-score-lost：它没有参与最后的组内竞争，
         // 再记一条 group-lost 会让诊断给出两个互相矛盾的原因。
@@ -246,11 +286,11 @@ export function selectStWorldBook(configs, session, messages, warn = () => {}) {
     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 })
+      if (previous.last === undefined || chat.length >= previous.last + count(config.params.activation.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) : []
+    const recursiveAdds = recursive ? added.filter(config => config.params.activation.preventRecursion !== true) : []
     if (recursiveAdds.length) recursiveText.push(...recursiveAdds.map(config => config.texts.join('\n')))
     else if (delayLevels.length) delayLevel = delayLevels.shift()
     else break

package/engine/delivery.d.mts

@@ -0,0 +1,2 @@
+/** 宿主使用的投递身份公开面。 */
+export function identityOf(config: Record<string, unknown>): string

package/engine/delivery.mjs

@@ -0,0 +1,93 @@
+import { historyEvents, viewRestricted } from './history.mjs'
+import { pluginKind, pluginOwner } from './source-kind.mjs'
+
+export function eventMessage(event) {
+  const data = event?.data
+  if (data === null || typeof data !== 'object') return undefined
+  const message = data.message !== null && typeof data.message === 'object' ? data.message : data
+  return message?.source !== null && typeof message?.source === 'object' ? message : undefined
+}
+
+export function moduleIdOf(value, field) {
+  const id = value?.[field]
+  return typeof id === 'string' && id.length > 0 ? id : undefined
+}
+
+export const moduleOf = source => moduleIdOf(source, 'moduleId')
+export const identityOf = config => config.mergeMode === 'merged' ? `merged:${config.position}` : config.identity.value
+
+export function pluginIdentityOf(source) {
+  if (typeof source?.plugin === 'string' && source.plugin.length > 0) return source.plugin
+  return pluginOwner(source?.kind)
+}
+
+export function identityStampOf(config) {
+  const plugin = identityOf(config)
+  const moduleId = moduleIdOf(config, 'sourceModuleId')
+  return {
+    kind: typeof config.sourceKind === 'string' && config.sourceKind.length > 0 ? config.sourceKind : pluginKind(plugin),
+    plugin,
+    ...(moduleId === undefined ? {} : { moduleId }),
+  }
+}
+
+export function identityHit(source, config, value) {
+  if (source?.kind !== config.sourceKind && pluginIdentityOf(source) !== value) return false
+  const moduleId = moduleOf(source)
+  return moduleId === undefined || moduleId === moduleIdOf(config, 'sourceModuleId')
+}
+
+/** 投递关联与去重读取相同的可见内容，投影删除的消息不能再充当事实。 */
+export function visibleMessages(session) {
+  const events = historyEvents(session)
+  const visible = viewRestricted(session, events) ? session.surface.nodes.map(seq => events[seq]) : events
+  const seen = new Set()
+  const out = []
+  for (const event of visible) {
+    const seq = Number.isSafeInteger(event.seq) ? event.seq : events.indexOf(event)
+    if (seq < 0 || seen.has(seq)) continue
+    seen.add(seq)
+    const message = typeof session?.surface?.deriveEventMessage === 'function'
+      ? session.surface.deriveEventMessage(event) : eventMessage(event)
+    if (message != null) out.push({ event, seq, message })
+  }
+  return out
+}
+
+export function injectedMessage(config, session) {
+  const value = identityOf(config)
+  return visibleMessages(session).find(({ message, seq }) => identityHit(message.source, config, value)
+    && (!config.linkedDelivery || message.source.sessionId === session.id && seq >= (session.inheritedEventCount ?? 0)))?.message
+}
+
+export function actionStamp(config, session) {
+  return config.ruleId === undefined || config.ruleActionId === undefined || session?.id === undefined ? {} : {
+    ruleId: config.ruleId, actionId: config.ruleActionId, sessionId: session?.id,
+  }
+}
+
+/** 官方同 order 按 name 排序，注册和投递查询共用这一份名字。 */
+export function textRegistrationName(config, field) {
+  const explicit = config.params?.[field]
+  if (typeof explicit === 'string' && explicit.length > 0) return explicit
+  if (config.sourceModuleId === undefined) return config.id
+  return `prompt-tool:${String(config.sequence).padStart(16, '0')}:${config.sourceModuleId}:${config.id}`
+}
+
+/** after 需要动作的严格证据；去重的宽松身份命中不能代替这份关联。 */
+export function findActionDelivery(session, config, messages = visibleMessages(session)) {
+  if (config === undefined || session?.id === undefined) return undefined
+  let found
+  for (const entry of messages) {
+    if (entry.seq < (session?.inheritedEventCount ?? 0)) continue
+    const source = entry.message.source
+    const matches = config.layer === 'runtime-context'
+      ? source?.kind === 'runtime-context' && source.form === 'snapshot'
+        && source.sections?.some(section => section.name === textRegistrationName(config, 'contextName') && typeof section.text === 'string' && section.text.length > 0)
+      : (source?.moduleId ?? '') === (config.sourceModuleId ?? '')
+        && source?.ruleId === config.ruleId && source?.actionId === config.ruleActionId
+        && source?.sessionId === session?.id
+    if (matches && (found === undefined || entry.seq > found.seq)) found = entry
+  }
+  return found
+}

package/engine/discovery.d.mts

@@ -0,0 +1,38 @@
+/** `discovery.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+export const DISCOVERY_ADAPTER_ROWS: Readonly<Record<string, string>>
+export const UNLOCKABLE_DISCOVERY_KINDS: ReadonlySet<string>
+
+export interface DiscoveryUnlock {
+  tool: string
+  key: string
+}
+
+export interface DiscoveryAdapterMetadata {
+  kind: string
+  tool: string
+  unlock?: DiscoveryUnlock
+}
+
+export interface DiscoveryRegistry {
+  register(agent: unknown, kind: string, adapter: DiscoveryAdapterMetadata): () => void
+  get(agent: unknown, kind: string): DiscoveryAdapterMetadata | undefined
+}
+
+export function createDiscoveryRegistry(): DiscoveryRegistry
+export function assertDiscoveryRows(rules: readonly unknown[], moduleIds: readonly string[] | undefined, moduleId: string): void
+export function queryTokens(query: unknown): string[]
+export function scoreRows(items: readonly unknown[], tokens: readonly string[], options?: {
+  nameOf?: (item: unknown) => unknown
+  haystackOf?: (item: unknown) => unknown
+}): Array<{ item: unknown; name: string; score: number; exact: boolean }>
+export function rankRows<T extends { exact: boolean; score: number; name: string }>(rows: readonly T[], admit?: (row: T) => boolean): T[]
+export function renderRows(rows: readonly unknown[], options?: {
+  query?: string
+  limit?: number
+  noun?: string
+  lineOf?: (row: unknown) => string
+  emptyText?: string
+  footer?: string
+  warnings?: readonly string[]
+}): string[]

package/engine/discovery.mjs

@@ -0,0 +1,146 @@
+/**
+ * discovery —— 发现引擎：搜索、排序、截断渲染与「适配器注册表」的唯一实现。
+ *
+ * 两个数据源（工具目录 / 技能目录）共用：
+ *  - 分词与候选打分（queryTokens / scoreRows）；
+ *  - 准入与排序（rankRows：默认 any-token，两个发现面同一口径；调用方可给更严的 admit）；
+ *  - 截断、空结果与页脚（renderRows）。
+ *
+ * 引擎之间通过 **cordis 服务** 互相调用，而不是直接 import 实现：
+ *  - 宿主 root provide `promptToolDiscovery`（createDiscoveryRegistry）；
+ *  - adapter 行的 apply 在拿到 { agent } 时注册自己的元数据；
+ *  - 消费方（tool-visibility）在首次装配时用 `ctx.get(DISCOVERY_SERVICE)` 按 agent 解析。
+ * 服务读取用 `ctx.get`（不需要 inject；cordis reflect.ts 的 get 明确「without the inject
+ * requirement」），属性读才需要 inject 且沿祖先链——这里刻意用 get。
+ *
+ * 注册表只存**元数据**（kind / tool / unlock / adapter 身份），工具仍由 adapter 行自己注册：
+ * 行的语义不变（挂行 = 有该工具），消费方只消费元数据（解锁名单从哪个参数回收、该用哪个工具名）。
+ */
+
+/** 每个 agent 的 adapter 只保留一份：同一个 adapter 重复注册是幂等的。 */
+export function createDiscoveryRegistry() {
+  const byAgent = new WeakMap()
+  const assertAdapter = (kind, adapter) => {
+    if (typeof kind !== 'string' || kind.length === 0) throw new TypeError('discovery adapter kind must be a non-empty string')
+    if (adapter === null || typeof adapter !== 'object') throw new TypeError(`discovery adapter "${kind}" must be an object`)
+    if (typeof adapter.tool !== 'string' || adapter.tool.length === 0) {
+      throw new TypeError(`discovery adapter "${kind}" needs a tool name`)
+    }
+    if (adapter.unlock !== undefined) {
+      for (const field of ['tool', 'key']) {
+        if (typeof adapter.unlock[field] !== 'string' || adapter.unlock[field].length === 0) {
+          throw new TypeError(`discovery adapter "${kind}" unlock.${field} must be a non-empty string`)
+        }
+      }
+    }
+  }
+  return {
+    /**
+     * 注册一份 adapter 元数据；同一 agent 同一 kind 只允许一个实现。
+     * 同一 adapter 身份重复注册（同一行在重绑/多次装配中再次 apply）是幂等的。
+     */
+    register(agent, kind, adapter) {
+      if (agent === undefined || agent === null) return () => {}
+      assertAdapter(kind, adapter)
+      let entries = byAgent.get(agent)
+      if (entries === undefined) {
+        entries = new Map()
+        byAgent.set(agent, entries)
+      }
+      const existing = entries.get(kind)
+      if (existing !== undefined) {
+        if (existing === adapter) return () => {}
+        throw new Error(`discovery kind "${kind}" is already registered for this agent`)
+      }
+      entries.set(kind, adapter)
+      return () => { if (entries.get(kind) === adapter) entries.delete(kind) }
+    },
+    /** 解析某 agent 的 adapter 元数据；没有注册过时返回 undefined（发现是可选能力）。 */
+    get(agent, kind) {
+      if (agent === undefined || agent === null) return undefined
+      return byAgent.get(agent)?.get(kind)
+    },
+  }
+}
+
+/** kind → 提供该 adapter 的组合行 id（准备期静态校验：声明了 discovery 就必须列对应行）。 */
+export const DISCOVERY_ADAPTER_ROWS = Object.freeze({
+  tools: 'tool-search',
+  skills: 'skill-search',
+})
+
+/** 可按名解锁的 kind：技能面只有搜索/加载，没有「解锁名单」语义。 */
+export const UNLOCKABLE_DISCOVERY_KINDS = new Set(['tools'])
+
+/**
+ * 准备期校验（纯函数，供 agent-assembly 调用）：规则里出现的 discovery.kind 必须有对应行。
+ * 失败信息点明缺哪一行，避免「装配成功但发现能力静默缺失」。
+ */
+export function assertDiscoveryRows(rules, moduleIds, moduleId) {
+  const ids = new Set(Array.isArray(moduleIds) ? moduleIds : [])
+  for (const rule of Array.isArray(rules) ? rules : []) {
+    // 未启用的规则不装配，也就不需要适配器行；启用后缺行会在下一次准备期失败。
+    if (rule?.enabled === false) continue
+    for (const action of Array.isArray(rule?.actions) ? rule.actions : []) {
+      const discovery = action?.discovery
+      if (discovery === undefined) continue
+      const kind = discovery.kind
+      const row = DISCOVERY_ADAPTER_ROWS[kind]
+      if (row === undefined) {
+        throw new TypeError(`模块 ${moduleId}：未知 discovery kind ${JSON.stringify(kind)} — 可用值：${Object.keys(DISCOVERY_ADAPTER_ROWS).join(', ')}`)
+      }
+      if (!ids.has(row)) {
+        throw new TypeError(`模块 ${moduleId} 声明 discovery kind "${kind}"，但 modules 未包含 "${row}" 行 — 发现适配器必须作为引擎行装配`)
+      }
+    }
+  }
+}
+
+/** 查询切成小写 token（Unicode 字母数字与下划线连字符；两个数据源同一口径）。 */
+export function queryTokens(query) {
+  return (typeof query === 'string' ? query : '').toLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(Boolean)
+}
+
+/**
+ * 候选打分：每个 token 在 haystack 里出现一次记 1 分；空查询返回空数组
+ * （调用方据此区分「没给查询」与「没搜到」）。
+ */
+export function scoreRows(items, tokens, { nameOf, haystackOf } = {}) {
+  if (!Array.isArray(items) || tokens.length === 0) return []
+  const name = nameOf ?? ((item) => item?.name)
+  const haystack = haystackOf ?? ((item) => `${item?.name ?? ''} ${item?.description ?? ''}`)
+  return items
+    .map((item) => {
+      const itemName = String(name(item) ?? '')
+      const text = String(haystack(item) ?? '').toLowerCase()
+      let score = 0
+      for (const token of tokens) if (text.includes(token)) score += 1
+      return { item, name: itemName, score, exact: tokens.includes(itemName.toLowerCase()) }
+    })
+    .filter((row) => row.name.length > 0)
+}
+
+/**
+ * 准入与排序：admit 决定哪些行算命中（默认 any-token，工具面与技能面同口径）；
+ * 精确名优先，其次命中数，同分按名字字典序。
+ */
+export function rankRows(rows, admit = (row) => row.exact || row.score >= 1) {
+  return rows
+    .filter(admit)
+    .sort((a, b) => (b.exact - a.exact) || (b.score - a.score) || a.name.localeCompare(b.name))
+}
+
+/**
+ * 渲染命中：标题、逐行、截断提示、页脚；空结果只回 emptyText。
+ * lineOf 负责单个条目的格式（描述截断长度等由各 adapter 决定）。
+ */
+export function renderRows(rows, { query, limit, noun, lineOf, emptyText, footer, warnings = [] } = {}) {
+  const matches = rows.slice(0, limit)
+  if (matches.length === 0) return [emptyText]
+  const lines = [`Matching ${noun} (${matches.length}${rows.length > limit ? ` of ${rows.length}` : ''}):`]
+  for (const row of matches) lines.push(lineOf(row))
+  if (rows.length > limit) lines.push(`(truncated at ${limit} — add tokens to narrow the query)`)
+  for (const warning of warnings) lines.push(warning)
+  if (footer !== undefined && footer.length > 0) lines.push(footer)
+  return lines
+}

package/engine/env-safety.mjs

@@ -0,0 +1,14 @@
+/**
+ * env 事实的安全边界：env-facts 只能读白名单里的环境变量，不能把任意 `process.env` 搬进提示词。
+ * 白名单与凭据形态判据是导出常量，供填充器与测试共用同一份事实。
+ */
+
+/** 疑似凭据的名字一律不放行。 */
+export const SENSITIVE_ENV_RE = /KEY|PASSWORD|SECRET|TOKEN/i
+
+/** env-facts 可读取的键：run-code-env 默认白名单 + 路径类事实（CWD/WORKSPACE）。 */
+export const SAFE_ENV_KEYS = new Set([
+  'PATH', 'PATHEXT', 'HOME', 'USERPROFILE', 'USERNAME', 'COMPUTERNAME', 'OS', 'TEMP', 'TMP',
+  'SystemRoot', 'ProgramFiles', 'ProgramFiles(x86)', 'LOCALAPPDATA', 'APPDATA',
+  'DSH_HOME', 'DSH_WORKSPACE', 'DSH_SESSION_ID', 'CWD', 'WORKSPACE',
+])