dsh-plugin-prompt-tool 3.0.2 → 3.1.1

package/engine/fillers.mjs

@@ -1,6 +1,6 @@
 /**
  * fillers — 引擎内置的动态填充器(strategy=placeholder 的数据源)。
- * 全部遵循同一铁律:服务缺失或列表失败时返回 null(跳过该配置),绝不伤及会话。
+ * 按本次求值读取宿主能力；失败由填充器或调用方诊断并跳过该配置。
  */
 
 import { getService, parseToolNames } from './shared.mjs'
@@ -8,7 +8,7 @@ import { toolScopeSnapshot } from './tool-scope.mjs'
 import { machinePaths } from './machine-paths.mjs'
 import { SAFE_ENV_KEYS } from './env-safety.mjs'
 import { createInstructionHintResolver } from './instruction-hint.mjs'
-import { DISCOVERY_SERVICE } from './service-names.mjs'
+import { DISCOVERY_SERVICE, SOUL_SELF_SERVICE } from './service-names.mjs'
 
 const name = 'prompt-config-engine'
 
@@ -187,12 +187,21 @@ function createSkillCatalogResolver(config) {
   }
 }
 
+function createSoulSelfResolver(config) {
+  return ({ ctx, agent, signal }) => {
+    const service = getService(ctx, SOUL_SELF_SERVICE)
+    if (typeof service?.render !== 'function') throw new Error('SELF dependency missing')
+    return { text: service.render(config.sourceModuleId, agent, signal) }
+  }
+}
+
 /** 动态填充器:strategy=placeholder 时按 fill 键在注入点填充内容。 */
 export const FILLERS = {
   'instruction-hint': (config) => createInstructionHintResolver(config),
   'env-facts': (config) => createEnvFactsResolver(config),
   'skill-catalog': (config) => createSkillCatalogResolver(config),
   'tool-catalog': (config) => createToolCatalogResolver(config),
+  'soul-self': (config) => createSoulSelfResolver(config),
 }
 
 export function createPlaceholderResolver(config) {

package/engine/generation-recovery-coordinator.mjs

@@ -0,0 +1,40 @@
+import { historyEvents } from './history.mjs'
+
+const visible = content => Array.isArray(content) && content.some(block => block.type !== 'reasoning' && (block.type !== 'text' || block.text?.trim()))
+
+/** 候选只在 durable turn/end 后发布；流与结算共用官方 turn/step。 */
+export function recoveryCoordinator(ctx, agent, config, options, isActive) {
+  let frame
+  let emitted
+  const offRequest = ctx.on('agent/request', (payload, next) => {
+    if (payload.agent !== agent) return next()
+    frame = { turn: payload.turn, step: payload.step, signal: payload.signal, visible: false }
+    return next()
+  })
+  const offEvent = ctx.on('session/event', (session, event) => {
+    if (!isActive() || session.id !== agent.session.id || !frame) return
+    const data = event.data ?? {}
+    if (event.type === 'assistant/message' && data.turn === frame.turn) {
+      if (data.step !== frame.step) return
+      frame.visible = visible(data.message?.content)
+      if (data.interrupted) frame.interrupted = true
+    }
+    if (event.type !== 'turn/end' || data.turn !== frame.turn || frame.signal?.aborted || frame.interrupted) return
+    if (data.reason?.kind !== 'completed' && data.reason?.kind !== 'no-visible-output') return
+    const execution = `${frame.turn}:${frame.step}`
+    if (execution === emitted || (!frame.reason && (!config.recoverEmpty || frame.visible))) return
+    emitted = execution
+    const candidate = { sessionId: session.id, execution, turn: frame.turn, step: frame.step, reason: frame.reason ?? 'empty-final-step', signal: frame.signal }
+    options.onRecoveryCandidate?.(candidate)
+    options.recover?.(candidate)
+  })
+  return {
+    mark(reason) { if (frame && !frame.signal?.aborted) frame.reason = reason },
+    dispose() { offRequest(); offEvent() },
+    // 迟到idle回调不能跨过新的用户执行边界。
+    unchanged(candidate) {
+      const latest = historyEvents(agent.session).findLast(event => event.type === 'turn/start')
+      return !latest || latest.data?.turn === candidate.turn
+    },
+  }
+}

package/engine/generation-recovery-maintenance.mjs

@@ -0,0 +1,18 @@
+/** 维护窗口与范围选择归上下文runtime，这里只决定是否允许扩大范围。 */
+export async function recoveryMaintenance(runtime, signal, allowFullFallback, valid, report) {
+  if (!runtime) { report('context runtime unavailable; recovery stopped'); return null }
+  let result
+  try {
+    result = await runtime.compactRecovery(signal)
+  } catch (error) {
+    if (!valid() || error?.name === 'AbortError' || error?.code === 'ABORTED') return null
+    if (!allowFullFallback) { report(`regional maintenance failed; recovery stopped (${String(error?.message ?? error)})`); return null }
+    result = await runtime.compactNow(signal)
+  }
+  if (!valid()) return null
+  if (result === null || !Array.isArray(result?.shadowedSeqs) || result.shadowedSeqs.length === 0) {
+    report('maintenance no-op; recovery stopped')
+    return null
+  }
+  return result
+}

package/engine/generation-recovery.mjs

@@ -0,0 +1,153 @@
+import { bool, defineConfig, enumOf, int, passthrough } from './fields.mjs'
+import { capabilityAudience } from './agent-capability.mjs'
+import { recoveryCoordinator } from './generation-recovery-coordinator.mjs'
+import { pluginMessage } from './layers.mjs'
+import { recoveryMaintenance } from './generation-recovery-maintenance.mjs'
+
+export const name = 'generation-recovery'
+export const inject = ['llm']
+
+const recoveryLimit = passthrough((value, plugin, field) => {
+  if (value === undefined) return 0
+  if (!Number.isSafeInteger(value) || value < 0 || value > 1000) throw new TypeError(`${plugin}: ${field} must be an integer from 0 to 1000`)
+  return value
+})
+
+export const configContract = defineConfig({
+  enabled: bool({ default: false }),
+  audience: enumOf(['all', 'main', 'subagent'], { default: 'all' }),
+  textRepeatChars: int({ min: 3, default: 4096 }),
+  reasoningRepeatChars: int({ min: 3, default: 8192 }),
+  silentReasoningChars: int({ min: 0, default: 0 }),
+  recoverEmpty: bool({ default: false }),
+  mainRecoveryLimit: recoveryLimit,
+  subagentRecoveryLimit: recoveryLimit,
+  maintenanceCompression: bool({ default: false }),
+  allowFullFallback: bool({ default: false }),
+  maxCycleChars: passthrough((value, plugin, field) => {
+    if (value === undefined) return 256
+    if (!Number.isSafeInteger(value) || value < 1 || value > 1024) throw new TypeError(`${plugin}: ${field} must be an integer from 1 to 1024`)
+    return value
+  }),
+})
+
+// 逐 Unicode 字符比较周期，内存只随最长周期增长，不保留整段推理。
+function repeatDetector(threshold, maxCycle) {
+  const tail = new Array(maxCycle)
+  const matches = new Float64Array(maxCycle + 1)
+  let seen = 0
+  return text => {
+    let offset = 0
+    for (const char of text) {
+      offset += char.length
+      let repeated = false
+      for (let period = 1; period <= Math.min(seen, maxCycle); period++) {
+        const needed = Math.max(threshold - period, 2 * period)
+        matches[period] = tail[(seen - period) % maxCycle] === char ? Math.min(matches[period] + 1, needed) : 0
+        if (matches[period] >= needed) repeated = true
+      }
+      tail[seen % maxCycle] = char
+      seen++
+      if (repeated) return offset
+    }
+    return undefined
+  }
+}
+
+export function apply(ctx, raw, options = {}) {
+  const { agent } = options
+  const config = configContract.parse(raw, name)
+  if (!config.enabled || typeof agent?.session?.id !== 'string') return
+  if (config.audience !== 'all' && config.audience !== capabilityAudience(agent)) return
+  let active = true
+  const report = message => ctx.logger?.warn?.(`${name}: ${message}`)
+  const limit = capabilityAudience(agent) === 'subagent' ? config.subagentRecoveryLimit : config.mainRecoveryLimit
+  const coordinator = recoveryCoordinator(ctx, agent, config, { ...options, recover(candidate) {
+    if (!limit) return
+    if (!options.recoveryState) { report('persistent recovery state unavailable; automatic recovery disabled'); return }
+    try {
+      const claimed = options.recoveryState.claim(agent.session.id, candidate.execution, limit)
+      if (!claimed.claimed) { report(`recovery unavailable (${claimed.used}/${limit})`); return }
+      void (async () => {
+        try {
+          await agent.whenIdle()
+          const valid = () => active && !candidate.signal?.aborted && coordinator.unchanged(candidate)
+          if (!valid()) return
+          let maintenance
+          if (config.maintenanceCompression) {
+            maintenance = await recoveryMaintenance(options.contextRuntimeOf?.(agent), candidate.signal, config.allowFullFallback, valid, report)
+            if (!maintenance) return
+          }
+          if (!valid()) return
+          const text = '上一轮输出因异常重复或仅有推理而未完成。请停止重复，检查已完成的工作，并给出有效结果或明确说明阻塞原因。'
+            + (maintenance ? `\n维护压缩已完成，实际来源事件：${maintenance.shadowedSeqs.join(',')}。` : '')
+          agent.followup(pluginMessage('generation-recovery', text, '恢复异常生成'))
+        } catch (error) { report(String(error?.message ?? error)) }
+      })()
+    } catch (error) { report(String(error?.message ?? error)) }
+  } }, () => active)
+  const stop = ctx.effect(() => () => { active = false })
+  const off = ctx.on('llm/stream', (options, next) => {
+    if (!active || options.signal?.aborted || options.purpose !== undefined || options.sessionId !== agent.session.id) return next()
+    return (async function* () {
+      const detectors = {
+        text: repeatDetector(config.textRepeatChars, config.maxCycleChars),
+        reasoning: repeatDetector(config.reasoningRepeatChars, config.maxCycleChars),
+      }
+      const open = new Map()
+      const closed = new Set()
+      const finalized = new Set()
+      let hasToolCall = false
+      let visibleText = false
+      let reasoningChars = 0
+      for await (const chunk of next()) {
+        if (finalized.has(chunk.index)) continue
+        if (!active || options.signal?.aborted) { yield chunk; continue }
+        if (chunk.type === 'tool-call-delta' || chunk.blockType === 'tool-call' || chunk.block?.type === 'tool-call') hasToolCall = true
+        if (chunk.type === 'block-start') open.set(chunk.index, { type: chunk.blockType, text: '' })
+        if (chunk.type === 'block-end') { open.delete(chunk.index); closed.add(chunk.index) }
+        const kind = chunk.type === 'text-delta' ? 'text' : chunk.type === 'reasoning-delta' ? 'reasoning' : undefined
+        if (kind === undefined || closed.has(chunk.index)) { yield chunk; continue }
+        if (!open.has(chunk.index)) open.set(chunk.index, { type: kind, text: '' })
+        // 已闭合工具也要保留原始finish语义，不把工具回合伪装成普通stop。
+        const safe = !hasToolCall && [...open.values()].every(block => block.type === 'text' || block.type === 'reasoning')
+        if (kind === 'text' && chunk.text.trim()) visibleText = true
+        let cutoff = safe ? detectors[kind](chunk.text) : undefined
+        let cause = 'repeated-' + kind
+        if (safe && kind === 'reasoning' && !visibleText && config.silentReasoningChars > 0) {
+          const chars = [...chunk.text]
+          const remaining = config.silentReasoningChars - reasoningChars
+          reasoningChars += chars.length
+          if (remaining > 0 && remaining <= chars.length) {
+            const silentCutoff = chars.slice(0, remaining).join('').length
+            if (cutoff === undefined || silentCutoff < cutoff) { cutoff = silentCutoff; cause = 'silent-reasoning' }
+          }
+        }
+        const text = cutoff === undefined ? chunk.text : chunk.text.slice(0, cutoff)
+        const block = open.get(chunk.index)
+        if (block !== undefined) block.text += text
+        yield cutoff === undefined ? chunk : { ...chunk, text }
+        if (cutoff === undefined) continue
+        if (!active || options.signal?.aborted) {
+          const remainder = chunk.text.slice(cutoff)
+          if (remainder) yield { ...chunk, text: remainder }
+          continue
+        }
+        for (const [index, value] of open) {
+          if (!active || options.signal?.aborted) break
+          finalized.add(index)
+          yield { type: 'block-end', index, block: value }
+        }
+        if (!active || options.signal?.aborted) {
+          const remainder = chunk.text.slice(cutoff)
+          if (!finalized.has(chunk.index) && remainder) yield { ...chunk, text: remainder }
+          continue
+        }
+        coordinator.mark(cause)
+        yield { type: 'finish', reason: { kind: 'stop' } }
+        return
+      }
+    })()
+  })
+  return () => { stop(); off(); coordinator.dispose() }
+}

package/engine/host-package.mjs

@@ -49,3 +49,16 @@ export function resolveHostPackage(id, entry, self) {
 export async function importHostPackage(id, entry, self) {
   return import(pathToFileURL(resolveHostPackage(id, entry, self)).href)
 }
+
+/** 允许从宿主解析的官方能力包；版本随宿主（alpha/rc 均可），不在插件内做精确匹配。 */
+export const HOST_CAPABILITY_PACKAGES = Object.freeze([
+  '@deepseek-ai/dsh-compaction-basic',
+  '@deepseek-ai/dsh-compaction-tool-result-pruner',
+  '@deepseek-ai/dsh-compaction',
+  '@deepseek-ai/dsh-llm',
+])
+
+export async function importHostCapability(id) {
+  if (!HOST_CAPABILITY_PACKAGES.includes(id)) throw new Error(`host capability not declared: ${id}`)
+  return importHostPackage(id)
+}

package/engine/layers.d.mts

@@ -0,0 +1,4 @@
+import type { UserMessage } from '@deepseek-ai/dsh-llm'
+
+/** 已有提示词引擎通知消息；使用宿主当前的插件来源契约。 */
+export function pluginMessage(prefix: string, text: string, summary: string): UserMessage

package/engine/layers.mjs

@@ -183,7 +183,7 @@ function textLayerGroups(configs) {
 }
 
 /** system-section:注册静态 system prompt 段(支持官方 {{variable}} 渲染与 merged 拼接)。 */
-function wireSystemSections(ctx, configs, registry, warnOnce, keep, ordered) {
+function wireSystemSections(ctx, configs, registry, warnOnce, keep, ordered, sourceError) {
   const systemPrompt = getService(ctx, 'systemPrompt')
   if (systemPrompt === undefined || typeof systemPrompt.section !== 'function') {
     if (configs.length > 0) warnOnce(`${name}: systemPrompt service unavailable — system-section configs skipped`)
@@ -218,6 +218,7 @@ function wireSystemSections(ctx, configs, registry, warnOnce, keep, ordered) {
         keep(systemPrompt.suppressRuntimeContext(), `${name}: suppressRuntimeContext ${base.id}`)
       }
     } catch (error) {
+      if (sourceError !== undefined) throw sourceError(error, base.sourceModuleId)
       warnOnce(`${name}: system-section config ${base.id} failed: ${String(error?.message ?? error)}`)
     }
   }
@@ -240,7 +241,7 @@ async function resolvedContextText(ctx, config, context, registry, warnOnce) {
 }
 
 /** 条件化文本保留官方排序占位；仅在本次真实 assembly 填充，不缓存 context 身份。 */
-function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, ordered) {
+function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, ordered, sourceError) {
   if (!configs.length) return []
   const systemPrompt = getService(ctx, 'systemPrompt')
   if (systemPrompt === undefined) { warnOnce(`${name}: systemPrompt unavailable`); return [] }
@@ -252,8 +253,26 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
     const section = layer === 'system-section'
     const base = group[0]
     const entryName = textRegistrationName(base, section ? 'sectionName' : 'contextName')
-    keep(systemPrompt[section ? 'section' : 'context']({ name: entryName, order: base.order, text: marker }), `${name}: conditional ${entryName}`)
-    bindings.push({ group, name: entryName, collection: section ? 'sections' : 'contexts' })
+    // runtime-context 在官方 refreshContext 里按注册 provider 重算：provider 必须返回当前文本，
+    // 否则 assemble 钩子的填充会在请求前被 marker 覆盖。system-section 不重算，仍用 marker 占位。
+    // 文本槽按 Agent 分区：同一挂载服务多个 Agent，交错装配时不能互相读到对方的正文。
+    const holders = section ? undefined : new WeakMap()
+    const sharedHolder = section ? undefined : { text: '' }
+    const holderOf = section ? undefined : (context) => {
+      const key = context?.agent
+      if (key === undefined || key === null) return sharedHolder
+      let holder = holders.get(key)
+      if (holder === undefined) { holder = { text: '' }; holders.set(key, holder) }
+      return holder
+    }
+    try {
+      keep(systemPrompt[section ? 'section' : 'context']({
+        name: entryName,
+        order: base.order,
+        text: section ? marker : (context) => holderOf(context).text,
+      }), `${name}: conditional ${entryName}`)
+    } catch (error) { throw sourceError === undefined ? error : sourceError(error, base.sourceModuleId) }
+    bindings.push({ group, name: entryName, collection: section ? 'sections' : 'contexts', holderOf })
     ordered[section ? 'sections' : 'contexts'].push(orderedEntry(entryName, base))
   }
   let active = true
@@ -261,9 +280,13 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
   return [on('system-prompt/assemble', async (assembly, context, next, invocation) => {
     const frame = invocation ?? ruleFrame('system-prompt/assemble', [assembly, context], warnOnce)
     for (const binding of bindings) {
-      const entry = assembly[binding.collection].find(item => item.name === binding.name && item.text === marker)
+      const entry = binding.collection === 'sections'
+        ? assembly.sections.find(item => item.name === binding.name && item.text === marker)
+        : assembly.contexts.find(item => item.name === binding.name)
       if (entry === undefined) continue
+      const holder = binding.holderOf === undefined ? undefined : binding.holderOf(context)
       entry.text = ''
+      if (holder !== undefined) holder.text = ''
       const blocks = []
       for (const config of binding.group) {
         if (!active || context.signal?.aborted || !actionMatches(config, frame) || !matchesAgentScope(config, context.agent)) continue
@@ -274,7 +297,10 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
           if (text.length) blocks.push(text)
         } catch (error) { warnOnce(`${name}: rule text ${config.id} failed: ${String(error?.message ?? error)}`) }
       }
-      if (active && !context.signal?.aborted) entry.text = blocks.join('\n\n')
+      if (active && !context.signal?.aborted) {
+        entry.text = blocks.join('\n\n')
+        if (holder !== undefined) holder.text = entry.text
+      }
     }
     return next()
   })]
@@ -282,7 +308,7 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
 }
 
 /** runtime-context:注册运行时上下文；静态文本支持 merged，动态策略在官方 assembly waterfall 中填充。 */
-function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on, ordered) {
+function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on, ordered, sourceError) {
   const disposers = []
   const systemPrompt = getService(ctx, 'systemPrompt')
   if (systemPrompt === undefined || typeof systemPrompt.context !== 'function') {
@@ -309,44 +335,55 @@ function wireRuntimeContexts(ctx, configs, registry, warnOnce, keep, on, ordered
       }), `${name}: context ${base.id}`)
       ordered.contexts.push(orderedEntry(entryName, base))
     } catch (error) {
+      if (sourceError !== undefined) throw sourceError(error, base.sourceModuleId)
       if (base.linkedDelivery) throw error
       warnOnce(`${name}: runtime-context config ${base.id} failed: ${String(error?.message ?? error)}`)
     }
   }
-  // 官方 provider 必须同步：先注册可渲染为空的私有变量占位，再在 waterfall 中填充。
-  // 标记随官方排序/遮蔽进入本次 assembly，无会话缓存，也不依赖调用方 context 的对象身份。
+  // 官方 provider 必须同步：注册函数 provider 读取 holder，再在 waterfall 中填充。
+  // 官方 refreshContext 会用注册 provider 重算 contexts；返回 holder 当前值，填充才不会被 reset。
   const placeholders = configs.filter(needsResolver)
     .sort(compareTextPlacement)
   if (placeholders.length === 0) return disposers
-  const slotVariable = `pt_runtime_${newMessageId('context').replace(/[^a-z0-9_]/gi, '_').toLowerCase()}`
-  const slotText = `{{${slotVariable}}}`
   const registered = new Map()
   let active = true
   keep(() => { active = false }, `${name}: runtime-context lifecycle`)
-  keep(systemPrompt.variable(slotVariable, () => ''), `${name}: runtime-context placeholder`)
   for (const config of placeholders) {
     try {
       const contextName = textRegistrationName(config, 'contextName')
+      // 文本槽按 Agent 分区：交错装配时 A 的 refresh 不得读到 B 的正文。
+      const holders = new WeakMap()
+      const sharedHolder = { text: '' }
+      const holderOf = (context) => {
+        const key = context?.agent
+        if (key === undefined || key === null) return sharedHolder
+        let holder = holders.get(key)
+        if (holder === undefined) { holder = { text: '' }; holders.set(key, holder) }
+        return holder
+      }
       keep(systemPrompt.context({
         name: contextName,
         order: config.order,
-        text: slotText,
+        text: (context) => holderOf(context).text,
       }), `${name}: context ${config.id}`)
-      registered.set(contextName, config)
+      registered.set(contextName, { config, holderOf })
       ordered.contexts.push(orderedEntry(contextName, config))
     } catch (error) {
+      if (sourceError !== undefined) throw sourceError(error, config.sourceModuleId)
       warnOnce(`${name}: runtime-context placeholder ${config.id} failed: ${String(error?.message ?? error)}`)
     }
   }
   disposers.push(on('system-prompt/assemble', async (assembly, context, next) => {
-    const entries = assembly.contexts.filter(entry => registered.has(entry.name) && entry.text === slotText)
+    const entries = assembly.contexts.filter(entry => registered.has(entry.name))
     for (const entry of entries) {
-      const config = registered.get(entry.name)
+      const { config, holderOf } = registered.get(entry.name)
+      const holder = holderOf(context)
       entry.text = ''
+      holder.text = ''
       if (!active || context.signal?.aborted) continue
       try {
         const text = await resolvedContextText(ctx, config, context, registry.get(config), warnOnce)
-        if (active && !context.signal?.aborted) entry.text = text
+        if (active && !context.signal?.aborted) { entry.text = text; holder.text = text }
       } catch (error) {
         warnOnce(`${name}: runtime-context ${config.id} resolve failed: ${String(error?.message ?? error)}`)
       }
@@ -681,9 +718,9 @@ export function wireLayers(ctx, configs, warnOnce, options = {}) {
       && (typeof config.rule?.when === 'function' || typeof config.actionWhen === 'function'
         || (config.rule !== undefined || config.params?.templateEvaluation === true) && config.params?.complete !== true && config.params?.suppressRuntimeContext !== true))
     const regular = configs.filter(config => !conditional.includes(config))
-    wireSystemSections(ctx, regular.filter((config) => config.layer === 'system-section'), registry, warnOnce, keep, ordered)
-    wireRuntimeContexts(ctx, regular.filter((config) => config.layer === 'runtime-context'), registry, warnOnce, keep, on, ordered)
-    wireRuleTextContributions(ctx, conditional, registry, warnOnce, keep, on, ordered)
+    wireSystemSections(ctx, regular.filter((config) => config.layer === 'system-section'), registry, warnOnce, keep, ordered, options.sourceError)
+    wireRuntimeContexts(ctx, regular.filter((config) => config.layer === 'runtime-context'), registry, warnOnce, keep, on, ordered, options.sourceError)
+    wireRuleTextContributions(ctx, conditional, registry, warnOnce, keep, on, ordered, options.sourceError)
     wireTurnStops(ctx, configs.filter((config) => config.layer === 'turn-stop'), warnOnce, on, options.turnStopBudgets)
     wireSubagentEvents(ctx, configs.filter((config) => config.layer === 'subagent-start' || config.layer === 'subagent-end'), warnOnce, on)
     // 官方 order 只提供初始槽位；configOrder 覆盖段/上下文的先后（平台段与其他插件段不动）。

package/engine/present-as.mjs

@@ -13,8 +13,8 @@
  * declared for this scope`）——本行不捕获、不降级，让它响亮失败（装配失败优于静默换形态）。
  *
  * `ptc` 需要 `ctx.ptcRuntime`（宿主 base bundle 的 `ptc-runtime` 行提供）：用 `ctx.inject`
- * 等它就绪再声明；等不到本行停在 pending，由预设注册表指名报告**不可用的行**——刻意不静默
- * 退回 native，否则「开了 PTC」的部署会悄悄以 native 跑。`native` 不需要运行时，直接声明。
+ * 等它就绪再声明；等不到本行停在 pending。受管装配观察初始化结果，声明失败时按来源
+ * 回退或撤销模块；本行不自行改成 native。`native` 不需要运行时，直接声明。
  *
  * disposer：`presentAs` 本身就是 effect（它用调用方的 ctx 注册、并把那个 disposer 还回来），
  * 本行不再包一层，随 fiber 释放即撤销。

package/engine/retrieval-reference.d.mts

@@ -0,0 +1,5 @@
+export type RetrievalEvent = { readonly seq: number; readonly type: string }
+export type SessionReference = { kind: 'session'; moduleId: string; sessionId: string; seqs: number[]; revision: string; start: number; end: number }
+export const MAX_REFERENCE_CHARS: number
+export function sessionReferenceText(events: readonly RetrievalEvent[], seqs: readonly number[]): string
+export function makeSessionReference(moduleId: string, sessionId: string, events: readonly RetrievalEvent[], seqs: readonly number[], range?: { start?: number; end?: number }): SessionReference

package/engine/retrieval-reference.mjs

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto'
+
+export const MAX_REFERENCE_CHARS = 8192
+
+/** seq 是持久日志身份；不排序为数值区间，也不以相同正文替代。 */
+export function sessionReferenceText(events, seqs) {
+  if (!Array.isArray(seqs) || seqs.length === 0 || seqs.length > 2048 || new Set(seqs).size !== seqs.length || seqs.some(seq => !Number.isSafeInteger(seq) || seq < 0)) throw new Error('检索引用事件身份无效')
+  const bySeq = new Map(events.map(event => [event.seq, event]))
+  let bytes = 0
+  return seqs.map(seq => {
+    const event = bySeq.get(seq)
+    if (!event) throw new Error('检索引用已失效')
+    const text = JSON.stringify(event)
+    bytes += Buffer.byteLength(text)
+    if (bytes > 64 * 1024 * 1024) throw new Error('检索引用来源超过64 MiB上限')
+    return text
+  }).join('\n')
+}
+
+export function makeSessionReference(moduleId, sessionId, events, seqs, range = {}) {
+  if (typeof moduleId !== 'string' || !moduleId || typeof sessionId !== 'string' || !sessionId) throw new Error('检索引用缺少真实来源身份')
+  const text = sessionReferenceText(events, seqs)
+  const start = range.start ?? 0, end = range.end ?? Math.min(text.length, start + MAX_REFERENCE_CHARS)
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start || end > text.length || end - start > MAX_REFERENCE_CHARS) throw new Error('检索引用范围无效')
+  return { kind: 'session', moduleId, sessionId, seqs: [...seqs], revision: createHash('sha256').update(text).digest('hex'), start, end }
+}

package/engine/retrieval.mjs

@@ -0,0 +1,17 @@
+import { bool, defineConfig, stringList } from './fields.mjs'
+import { toolServiceName } from './service-names.mjs'
+
+export const name = 'retrieval'
+export const inject = ['tools']
+export const configContract = defineConfig({
+  enabled: bool({ default: false }),
+  paths: stringList({ default: () => [], allowEmpty: true, dedupe: true }),
+  sessions: stringList({ default: () => [], allowEmpty: true, dedupe: true }),
+})
+
+export function apply(ctx, raw, options) {
+  const config = configContract.parse(raw, name)
+  if (!config.enabled) return
+  const fiber = ctx.inject([toolServiceName(name)], scopeCtx => scopeCtx.effect(() => scopeCtx.get(toolServiceName(name)).mount(scopeCtx, config, options)))
+  return () => { void fiber.dispose() }
+}

package/engine/rule-engine.mjs

@@ -37,5 +37,6 @@ export async function apply(ctx, config) {
   const moduleId = typeof packet.moduleId === 'string' ? packet.moduleId : basename(dirname(file))
   const rules = compileRules(packet.rules, { moduleId, variables: packet.variables, variablesEnabled: packet.variablesEnabled, configOrder: packet.configOrder, promptConfigOptions: { templateBaseUrl, templateModuleRoot, strategyDir } })
   // 条件在挂载缝绑定（preset 需要挂载 scope 的 ctx）；官方模块导出只作可选兜底。
+  // 独立装配路径没有插件侧服务，manifest 条件在这个入口恒不可用（见 docs/engine-reuse.md）。
   return mountRuleSources(ctx, [{ moduleId, rules }], { standingMountFor: await loadStandingMountFor() })
 }

package/engine/rule-runtime.d.mts

@@ -11,6 +11,11 @@ export interface RuleVariableStore {
   publish(moduleId: string): void
 }
 
+/** 清单检查事实通道（宿主读取器）；引擎只调用 read，undefined 表示不可用。 */
+export interface RuleManifestCheck {
+  read(moduleId: string): boolean | undefined
+}
+
 /** 判定上报载荷；仅覆盖插件依赖面（宿主按 `RuleOutcomeReport` 消费它）。 */
 export interface RuleOutcomeReport {
   moduleId?: string
@@ -30,6 +35,8 @@ export interface MountRuleSourcesOptions {
   plugin?: string
   warnOnce?: WarnOnce
   variableStore?: RuleVariableStore
+  /** 清单 checks 事实；缺省＝manifest 条件恒不可用。 */
+  manifestCheck?: RuleManifestCheck
   /** 官方预设兜底；缺省＝没有兜底（预设条件恒不命中）。 */
   standingMountFor?: StandingMountFor
   /** 注入的晋升相位实例对；缺省从协调器或自建池取。 */
@@ -38,7 +45,7 @@ export interface MountRuleSourcesOptions {
   onOutcome?(report: RuleOutcomeReport): void
 }
 
-/** 所有规则来源的唯一装配入口；返回释放本次挂载的 disposer。 */
+/** 所有规则来源的唯一装配入口；返回 disposer。可归因挂载错误携带 sourceModuleId，原错误保留在 cause。 */
 export function mountRuleSources(
   ctx: unknown,
   sources: ReadonlyArray<RuleSourceLike>,

package/engine/rule-runtime.mjs

@@ -16,6 +16,8 @@ const noNext = new Set(['agent/inbox/inserted', 'agent/turn-stopping', 'subagent
 const compare = (a, b) => a.action.channelOrder - b.action.channelOrder
   || a.moduleId.localeCompare(b.moduleId) || a.ruleIndex - b.ruleIndex || a.action.actionIndex - b.action.actionIndex
 
+const sourceError = (error, moduleId) => Object.assign(new Error(String(error?.message ?? error), { cause: error }), { sourceModuleId: moduleId })
+
 /** 所有来源只进入这个装配入口；受众限定固定效果要求 ctx 属于 options.agent 的 scope。 */
 export function mountRuleSources(ctx, sources, options = {}) {
   validateDeliverySources(sources)
@@ -32,7 +34,6 @@ export function mountRuleSources(ctx, sources, options = {}) {
   // 条件绑定**在这里**发生：`compileRules` 编译期没有挂载 scope 的 ctx（preset 条件在那边恒
   // UNAVAILABLE 且静默）。必须早于事件订阅与动作注册——动作级 `actionWhen.observe` 是订阅通道，
   // 绑晚了那一类谓词会漏事件。`standingMountFor` 是可选兜底（官方包缺席＝没有兜底，不是错误）。
-  rebindConditions(sources, { ctx, standingMountFor: options.standingMountFor, promotionPool: pool, variableStore: options.variableStore })
   const warnOnce = options.warnOnce ?? createWarnOnce(ctx, options.plugin ?? 'rule-engine')
   // 非 pre-step 动作仍共享一次 ruleFrame；规则实例没有来源字段（RuleDefinition 不暴露 moduleId），
   // 因此保留一份局部 rule→module 映射。它不是 pre-step 来源事实的重建，不参与 pre-step 的 source sink。
@@ -50,19 +51,23 @@ export function mountRuleSources(ctx, sources, options = {}) {
   // 因此按 moduleId 分档；来源 id 缺失时落空串兜底键（与 wireTurnStops 同源）。
   const turnStopBudgets = new Map()
   const injections = new Map(sources.map(source => [source.moduleId, { moduleId: source.moduleId, sourceId: moduleSourceId(source.moduleId), configs: [], ruleActions: [] }]))
-  const rules = sources.flatMap(source => source.rules.filter(rule => rule.enabled !== false))
   // 动作级分支条件（actionWhen）也要喂 session/event：否则 else / 嵌套 if 里的 phase / count
   // 谓词永远收不到事件，状态停在冷扫那一刻（规则级 when 已由 rules 覆盖，动作级单独补齐）。
-  const observer = wireTriggerObservers(ctx, [
-    ...rules,
-    ...rules.flatMap(rule => (rule.actions ?? [])
-      .filter(action => typeof action.actionWhen?.observe === 'function')
-      .map(action => ({ id: action.id, when: action.actionWhen }))),
-  ], { plugin: options.plugin ?? 'rule-engine', warnOnce })
-  if (observer) releases.push(observer)
   let active = true
   const bind = (item, on) => prepareAction(item.action, { plugin: options.plugin, warnOnce, promptConfigOptions: item.rule.promptConfigOptions, on })(ctx)
   try {
+    for (const source of sources) {
+      try { rebindConditions([source], { ctx, standingMountFor: options.standingMountFor, promotionPool: pool, variableStore: options.variableStore, manifestCheck: options.manifestCheck }) }
+      catch (error) { throw sourceError(error, source.moduleId) }
+    }
+    const rules = sources.flatMap(source => source.rules.filter(rule => rule.enabled !== false))
+    const observer = wireTriggerObservers(ctx, [
+      ...rules,
+      ...rules.flatMap(rule => (rule.actions ?? [])
+        .filter(action => typeof action.actionWhen?.observe === 'function')
+        .map(action => ({ id: action.id, when: action.actionWhen }))),
+    ], { plugin: options.plugin ?? 'rule-engine', warnOnce })
+    if (observer) releases.push(observer)
     for (const source of sources) for (const [ruleIndex, rule] of source.rules.entries()) {
       if (rule.enabled === false) continue
       for (const action of rule.actions) {
@@ -82,6 +87,7 @@ export function mountRuleSources(ctx, sources, options = {}) {
         releases.push(wireLayers(ctx, textConfigs, warnOnce, {
           agent: options.agent,
           turnStopBudgets,
+          sourceError,
           on: (channel, handler) => {
             if (channel !== point.channel) throw new TypeError(`rule action registered outside ${point.channel}: ${channel}`)
             handlers.push({ handler }); return () => {}
@@ -109,7 +115,9 @@ export function mountRuleSources(ctx, sources, options = {}) {
           // 这里再返回一个真 disposer 会与它重复释放同一批 handler。
           return () => {}
         }
-        const dispose = bind(item, on)
+        let dispose
+        try { dispose = bind(item, on) }
+        catch (error) { throw sourceError(error, moduleId) }
         // 未命中通知：条件为假时动作不会进入 handler，撤销型动作（tool-visibility 的执行闸）
         // 只能靠这条回调收手——否则第一轮为真后永久留闸。
         if (typeof dispose?.miss === 'function') {

package/engine/rule-spec.mjs

@@ -231,8 +231,8 @@ export function compileRules(specs, options = {}) {
   if (!Array.isArray(specs)) throw new TypeError('rules must be an array')
   // 条件的绑定**不在编译期**：`preset` 谓词的取法要挂载 scope 的 ctx（`conditions/preset.mjs`），
   // 准备期拿不到。这里显式剥掉挂载期选项——传了也不生效，免得调用方以为已经绑好。
-  // variableStore 与 ctx/standingMountFor 同理：绑定发生在挂载期，准备期传了也不生效。
-  const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, ...conditionOptions } = options
+  // variableStore / manifestCheck 与 ctx/standingMountFor 同理：绑定发生在挂载期，准备期传了也不生效。
+  const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, manifestCheck: _manifestCheck, ...conditionOptions } = options
   const ids = new Set()
   const pendingConfigs = []
   const moduleId = options.moduleId ?? options.sourceModuleId
@@ -411,6 +411,8 @@ function needsMountContext(node) {
   if (Object.hasOwn(node, 'preset')) return true
   // variable 要读挂载 scope 的变量适配器（准备期没有）。
   if (Object.hasOwn(node, 'variable')) return true
+  // manifest 要读挂载 scope 的清单检查服务（准备期没有）。
+  if (Object.hasOwn(node, 'manifest')) return true
   if (Object.hasOwn(node, 'phase') && node.phase?.subscribe !== false) return true
   if (node.anchor?.after !== undefined) return true
   return Object.values(node).some(needsMountContext)