dsh-plugin-prompt-tool 3.1.3 → 3.1.5

package/README.md

@@ -112,7 +112,7 @@ persona:
 | module-file-tools | module_file_read / module_file_append |
 | module-manifest-tools | module_manifest |
 | module-import-tools | module_import |
-| soul-ledger | soul_ledger |
+| soul-ledger | soul_ledger / soul_state |
 | retrieval | module_search / module_open |
 | tool-config-engine | customTools 中的实际工具 |
 
@@ -134,11 +134,17 @@ outlet/vectorized/triggers 不能等价执行，相关规则禁用并报告；
 
 Soul 模块包含结构化账本、授权文件／历史检索、每步动态 SELF、上下文压缩与裁剪溯源、生成恢复和维护心跳。SELF 由 `rule-engine` 的内置动态内容源提供（`strategy: placeholder`、`fill: soul-self`），无需模块附带策略 JS。先用上述初始化预览补齐 `SELF.src.md` 骨架；已有模块副本须显式更新，包升级不会覆盖用户定义或私有数据，旧副本仍可使用自身保留的自定义策略。
 
-`soul_ledger` 自动署名真实会话，`lead` 需宿主审批，只有最后主导会话可追加 `promise`；通用文件追加拒绝新旧账本名。`module_search` 返回的引用交给 `module_open` 回取，历史会话只读取声明的白名单。SELF 的当前身份在每步读取时加入，维护默认每分钟只更新索引与快照，`wake` 独立且默认关闭。
+`soul_ledger` 自动署名真实会话；`lead` 需宿主审批，`promise` 仅当前主导会话追加/收口，`shelved` 可由原作者或当前主导收口。`close` 通过稳定 `targetId` 追加完成/取消及依据，保留历史原行；`list` 的 `pending/open/pending-review` 视图提供版本分页。升级前历史事项标为待核对，不猜测已完成。
+
+SELF 每步读取当前骨架、账本投影和身份/时钟，维护关闭或诊断快照陈旧也能呈现；索引只报告最近成功观测，不逐步扫描历史。`soul_state status/mark/check` 提供当前会话状态、带版本的短标记及只读运行诊断。未结提醒默认仅主会话，在集合变化或成功压缩后实际投递一次；候选装配不消费提醒。Soul 显式开启 45/60/80% 水位提示，只提示，不自动压缩。
+
+`module_search` 支持全半角/大小写/千分位归一化、Soul 声明的有界近义表及 `mode: timeline` 时间线；命中标注方式，引用交给 `module_open` 重验授权与原文。历史会话仍只读白名单。维护默认每分钟更新索引与诊断快照，等待可取消，`wake` 独立且默认关闭。
 
 `generation-recovery` 的通用默认只截断；Soul 显式启用空回合检测和有界恢复，主会话额度 3、子代理 1，每会话独立且重挂不清零。维护压缩和扩大范围默认关闭。配置与边界见 [引擎运行时](docs/engine-reuse.md#重复输出安全截断)、[账本与SELF](docs/architecture-params.md#soul账本与派生快照)。
 
-这些运行能力由本插件实现，不需要源项目 `dsh-agent-soul` 的仓库、插件或后台服务；上下文治理仍要求宿主提供[官方能力包](docs/engine-reuse.md#上下文运行时与溯源)（按包名白名单从 DSH 自带包解析，运行期不比对版本）。本模块不等价于源项目的全部功能：检索采用授权范围内的字面匹配，未提供源近义检索、上下文水位提醒、完整 doctor/诊断工具或附属面板；恢复判据与额度策略也有差异。`assets/reference/` 保留的源文档用于背景参考，其中的源 CLI 和第三方工具不表示本插件已提供对应能力。
+这些运行能力由本插件实现，不需要源项目 `dsh-agent-soul` 的仓库、插件或后台服务；上下文治理仍要求宿主提供[官方能力包](docs/engine-reuse.md#上下文运行时与溯源)。未提供向量库、规模持久索引、压缩帧直取、附属面板、源安装体系或恢复补额/惩罚。`assets/reference/` 保留源背景文档，其 CLI 不代表本插件接口。
+
+已有 Soul 定义通过 `soul_state check` 显式传 `includeUpgrade: true` 查看定向升级候选及冲突；完整 `files` 含必要配置、近义词表和现有可交换资产，再交 `module_import` 模型工具预览确认及重建，该入口保留私有数据、记忆和技能资产。包内种子不覆盖用户副本。包含 `close` 的账本要求支持账本 v2 的程序：旧版会忽略收口且仍能写入，回滚前必须撤写能力及旧 SELF/提醒贡献，不能删除 close 行迁就旧版。
 
 上下文能力按包名白名单从 DSH 自带包解析，不增加插件依赖，运行期不校验版本；仅包缺失或未登记时拒绝该能力装配。包代码更新需要用户重启 DSH 加载；加载后修改模块启停／参数沿运行时刷新，不改官方 preset 或 profile patch。
 

package/engine/compaction-epoch.d.mts

@@ -23,3 +23,4 @@ export interface EpochPromotionOptions {
 
 /** 建一份相位追踪器；`promoteEvents` 是 durable 事件类型集合（见 `shared.mjs#PROMOTE_EVENTS`）。 */
 export function createEpochPromotion(promoteEvents: Iterable<string>, options?: EpochPromotionOptions): PromotionTracker
+export function isSuccessfulCompactionEnd(event: unknown): boolean

package/engine/conditions/composite.mjs

@@ -35,21 +35,26 @@ export function composite(node) {
   const children = list.map(composite)
   const predicates = {
     [MATCH_LOGIC.ANY]: (payload) => {
+      predicate.soulReminders = []
       let unknown = false
       for (const child of children) {
         const result = child(payload)
         if (result === UNAVAILABLE) unknown = true
-        else if (result) return true
+        else if (result) { predicate.soulReminders = child.soulReminders ?? []; return true }
       }
       return unknown ? UNAVAILABLE : false
     },
     [MATCH_LOGIC.ALL]: (payload) => {
+      predicate.soulReminders = []
+      const reminders = []
       let unknown = false
       for (const child of children) {
         const result = child(payload)
         if (result === UNAVAILABLE) unknown = true
         else if (!result) return false
+        if (result === true) reminders.push(...(child.soulReminders ?? []))
       }
+      if (!unknown) predicate.soulReminders = reminders
       return unknown ? UNAVAILABLE : true
     },
     [MATCH_LOGIC.NOT_ANY]: (payload) => {

package/engine/conditions/evaluation.mjs

@@ -9,7 +9,7 @@ import { UNAVAILABLE } from './availability.mjs'
  * 缺省不传即零开销，也不改变任何判定结果。
  */
 export function ruleFrame(channel, args, warnOnce = () => {}, ctx, onOutcome) {
-  return { channel, args, subject: subjectOf(channel, args, warnOnce, ctx), decisions: new Map(), actionDecisions: new Set(), warnOnce, onOutcome }
+  return { channel, args, subject: subjectOf(channel, args, warnOnce, ctx), decisions: new Map(), actionDecisions: new Set(), reminders: new Map(), warnOnce, onOutcome }
 }
 
 /** 条件返回值的三值归一：词表与 bridge 的 `RuleOutcomeKind` 共享，故只此一处定义。 */
@@ -42,7 +42,7 @@ function decideRule(rule, frame) {
       frame.warnOnce(`rule ${rule.id} condition failed: ${String(error?.message ?? error)}`)
     }
   }
-  const decided = { hit, outcome }
+  const decided = { hit, outcome, reminders: hit ? rule.when?.soulReminders ?? [] : [] }
   frame.decisions.set(rule, decided)
   return decided
 }
@@ -70,7 +70,11 @@ export function ruleMatches(rule, frame) {
  */
 export function actionMatches(entry, frame) {
   const branched = entry.actionWhen !== undefined || entry.bypassRuleWhen === true
-  if (!branched) return ruleMatches(entry.rule, frame)
+  if (!branched) {
+    const hit = ruleMatches(entry.rule, frame)
+    frame.reminders.set(entry, hit ? decideRule(entry.rule, frame).reminders ?? [] : [])
+    return hit
+  }
   // `else`（bypassRuleWhen）自带 not(if)，不叠加规则级判定；其余带分支的动作自判
   // 规则级（不发上报），判定仍走同一份帧内缓存，同帧同规则依旧只判一次。
   const ruled = entry.bypassRuleWhen === true ? { hit: true, outcome: 'hit' } : decideRule(entry.rule, frame)
@@ -92,5 +96,20 @@ export function actionMatches(entry, frame) {
     frame.actionDecisions.add(entry)
     report(frame, entry.rule, outcome)
   }
+  frame.reminders.set(entry, hit ? [...(ruled.reminders ?? []), ...(entry.actionWhen?.soulReminders ?? [])] : [])
   return hit
 }
+
+/** 只关联实际命中路径的正向Soul事实；普通分支没有提醒戳。 */
+export function actionSoulReminder(entry, frame) {
+  return frame.reminders.get(entry)?.[0]
+}
+
+export function recheckSoulReminder(entry, frame, expected) {
+  if (expected === undefined) return true
+  const current = ruleFrame(frame.channel, frame.args, frame.warnOnce, undefined)
+  if (!actionMatches(entry, current)) return false
+  const fact = actionSoulReminder(entry, current)
+  return fact?.predicate === expected.predicate && fact.moduleId === expected.moduleId
+    && fact.pendingVersion === expected.pendingVersion && fact.epoch === expected.epoch
+}

package/engine/conditions/examples.mjs

@@ -10,4 +10,5 @@ export const PREDICATE_EXAMPLES = {
   anchor: { subject: 'assistantReasoning', keys: ['确认'], mode: 'prefix' },
   variable: { key: 'quota', op: 'lte', value: '0', scope: 'effective' },
   manifest: { ok: true },
+  soul: { pending: true },
 }

package/engine/conditions/index.mjs

@@ -9,6 +9,7 @@ import { createScopePredicate } from './scope.mjs'
 import { createAnchorPredicate } from './anchor.mjs'
 import { createVariablePredicate } from './variable.mjs'
 import { createManifestPredicate } from './manifest.mjs'
+import { createSoulPredicate } from './soul.mjs'
 import { withAvailableInput } from './availability.mjs'
 import { composite } from './composite.mjs'
 import { COMPOSITE_OPERATORS } from './operators.mjs'
@@ -23,6 +24,7 @@ export * from './scope.mjs'
 export * from './anchor.mjs'
 export * from './variable.mjs'
 export * from './manifest.mjs'
+export * from './soul.mjs'
 export { subjectOf, channelTextSubjects, channelFactSubjects, FACT_PREDICATE_SUBJECTS } from './subject.mjs'
 export { composite } from './composite.mjs'
 export const PREDICATE_FACTORIES = Object.freeze({
@@ -37,6 +39,7 @@ export const PREDICATE_FACTORIES = Object.freeze({
   anchor: createAnchorPredicate,
   variable: createVariablePredicate,
   manifest: createManifestPredicate,
+  soul: createSoulPredicate,
 })
 export { COMPOSITE_OPERATORS }
 
@@ -102,5 +105,6 @@ export function compileWhen(node, context = {}) {
   if (key === 'manifest') {
     return createManifestPredicate(options, { manifestCheck: context.manifestCheck, moduleId: context.moduleId })
   }
+  if (key === 'soul') return createSoulPredicate(options, context)
   return withAvailableInput(key, options, factory(options))
 }

package/engine/conditions/soul.mjs

@@ -0,0 +1,15 @@
+import { UNAVAILABLE } from './availability.mjs'
+import { agentOf } from './subject.mjs'
+
+export function createSoulPredicate(options = {}, context = {}) {
+  if (Object.keys(options).some(key => key !== 'pending') || options.pending !== true) throw new TypeError('predicates: soul requires pending: true')
+  const predicate = payload => {
+    predicate.soulReminders = []
+    if (typeof context.soulReminder?.read !== 'function' || !context.moduleId) return UNAVAILABLE
+    const fact = context.soulReminder.read(context.moduleId, agentOf(payload))
+    if (fact?.due === true) predicate.soulReminders = [{ ...fact, predicate, moduleId: context.moduleId }]
+    return typeof fact?.due === 'boolean' ? fact.due : UNAVAILABLE
+  }
+  predicate.kind = 'soul'
+  return predicate
+}

package/engine/delivery.d.mts

@@ -1,2 +1,3 @@
 /** 宿主使用的投递身份公开面。 */
 export function identityOf(config: Record<string, unknown>): string
+export function eventMessage(event: unknown): { source: Record<string, unknown> } | undefined

package/engine/executor.mjs

@@ -30,7 +30,7 @@ import { wireLayers } from './layers.mjs'
 import { renderTemplate } from './template-frame.mjs'
 import { selectContextActivation } from './context-activation.mjs'
 import { compareConfigSequence } from './order.mjs'
-import { ruleFrame, actionMatches } from './conditions/evaluation.mjs'
+import { ruleFrame, actionMatches, actionSoulReminder, recheckSoulReminder } from './conditions/evaluation.mjs'
 import { composePreStepSources, promotionOwnerOf } from './pre-step-source.mjs'
 // 标记键名与「已登记进 config 白名单」同源（schema.mjs），此处不另写字面量。
 import { SESSION_VARIABLES_DISABLED } from './schema.mjs'
@@ -329,12 +329,15 @@ async function runPromptConfigBatch(options) {
           continue
         }
 
+        const reminder = actionSoulReminder(config, options.ruleFrame)
         const signal = options.payload?.signal
         if (signal?.aborted) continue
         const resolved = await config.resolve({ ctx, agent, session, signal, decision, messages, contextActivationSelected: scope.contextActivation.has(config) })
         if (signal?.aborted) continue
         if (resolved === null || resolved === undefined) continue
+        if (!recheckSoulReminder(config, options.ruleFrame, reminder)) continue
         const patched = { ...resolved }
+        if (reminder !== undefined) patched.source = { ...patched.source, soulReminder: { pendingVersion: reminder.pendingVersion, epoch: reminder.epoch } }
         // 按来源读取最新持久值；无变量正文不因另一个坏候选的读盘失败撤回。
         const mergedVars = {
           ...(config[SESSION_VARIABLES_DISABLED] === true ? {} : config.params?.templateEvaluation !== true && [patched.text, ...config.texts].some(text => typeof text === 'string' && text.includes('{{'))

package/engine/fillers.mjs

@@ -191,7 +191,8 @@ 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) }
+    const text = service.render(config.sourceModuleId, agent, signal)
+    return typeof text?.then === 'function' ? text.then(value => ({ text: value })) : { text }
   }
 }
 

package/engine/generation-recovery.d.mts

@@ -0,0 +1,6 @@
+export interface RecoveryObservation { state: string; observedAt: string }
+export function recoveryObservationOf(agent: object): RecoveryObservation | undefined
+export const name: string
+export const inject: string[]
+export const configContract: { parse(raw: unknown, plugin: string): Record<string, unknown> }
+export function apply(ctx: unknown, raw: unknown, options?: Record<string, unknown>): (() => void) | undefined

package/engine/generation-recovery.mjs

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { bool, defineConfig, enumOf, int, passthrough } from './fields.mjs'
 import { capabilityAudience } from './agent-capability.mjs'
 import { recoveryCoordinator } from './generation-recovery-coordinator.mjs'
@@ -6,6 +7,8 @@ import { recoveryMaintenance } from './generation-recovery-maintenance.mjs'
 
 export const name = 'generation-recovery'
 export const inject = ['llm']
+const observations = new WeakMap()
+export const recoveryObservationOf = agent => observations.get(agent)
 
 const recoveryLimit = passthrough((value, plugin, field) => {
   if (value === undefined) return 0
@@ -19,6 +22,8 @@ export const configContract = defineConfig({
   textRepeatChars: int({ min: 3, default: 4096 }),
   reasoningRepeatChars: int({ min: 3, default: 8192 }),
   silentReasoningChars: int({ min: 0, default: 0 }),
+  lineRepeatChars: int({ min: 0, default: 0 }),
+  crossCallRepeatChars: int({ min: 0, default: 0 }),
   recoverEmpty: bool({ default: false }),
   mainRecoveryLimit: recoveryLimit,
   subagentRecoveryLimit: recoveryLimit,
@@ -54,20 +59,53 @@ function repeatDetector(threshold, maxCycle) {
   }
 }
 
+// 只保存行摘要；窗口与单行都有上限，引用与代码围栏不计入材料判据。
+function materialDetector(config, previous) {
+  const counts = new Map()
+  let line = '', fenced = false, overflow = false, chars = 0, lines = 0, repeated = 0, dominant = 0
+  const overlap = [0, 0]
+  return {
+    push(text) {
+      let offset = 0
+      for (const char of text) {
+        offset += char.length
+        if (char !== '\n') { if (line.length < 1024) line += char; else overflow = true; continue }
+        const value = line.trim(); line = ''
+        if (value.startsWith('```') || value.startsWith('~~~')) { fenced = !fenced; overflow = false; continue }
+        if (overflow || fenced || value.startsWith('>') || value.length < 12 || lines >= 128) { overflow = false; continue }
+        const key = createHash('sha256').update(value).digest('hex')
+        const count = (counts.get(key) ?? 0) + 1
+        counts.set(key, count); lines++; chars += value.length
+        if (count > 1) repeated += value.length
+        dominant = Math.max(dominant, count)
+        previous.forEach((sample, index) => { if (sample.has(key)) overlap[index] += value.length })
+        if (config.lineRepeatChars > 0 && chars >= config.lineRepeatChars && lines >= 6 && repeated / chars >= 0.8 && dominant / lines >= 0.5) return { offset, cause: 'repeated-lines' }
+        if (config.crossCallRepeatChars > 0 && chars >= config.crossCallRepeatChars && lines >= 6 && previous.length === 2 && overlap.every(value => value / chars >= 0.9)) return { offset, cause: 'repeated-material' }
+      }
+    },
+    sample: () => lines >= 6 && chars >= config.crossCallRepeatChars ? new Set(counts.keys()) : 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 samples = { text: [], reasoning: [] }
+  const clearSamples = () => { samples.text.length = 0; samples.reasoning.length = 0 }
+  const observe = state => observations.set(agent, { state, observedAt: new Date().toISOString() })
+  const report = message => { observe('reported'); ctx.logger?.warn?.(`${name}: ${message}`) }
   const limit = capabilityAudience(agent) === 'subagent' ? config.subagentRecoveryLimit : config.mainRecoveryLimit
   const coordinator = recoveryCoordinator(ctx, agent, config, { ...options, recover(candidate) {
+    observe('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 }
+      observe('claimed')
       void (async () => {
         try {
           await agent.whenIdle()
@@ -82,18 +120,21 @@ export function apply(ctx, raw, options = {}) {
           const text = '上一轮输出因异常重复或仅有推理而未完成。请停止重复，检查已完成的工作，并给出有效结果或明确说明阻塞原因。'
             + (maintenance ? `\n维护压缩已完成，实际来源事件：${maintenance.shadowedSeqs.join(',')}。` : '')
           agent.followup(pluginMessage('generation-recovery', text, '恢复异常生成'))
+          observe('enqueued')
         } catch (error) { report(String(error?.message ?? error)) }
       })()
     } catch (error) { report(String(error?.message ?? error)) }
   } }, () => active)
-  const stop = ctx.effect(() => () => { active = false })
+  const stop = ctx.effect(() => () => { active = false; clearSamples() })
   const off = ctx.on('llm/stream', (options, next) => {
+    if (options.sessionId === agent.session.id && options.signal?.aborted) clearSamples()
     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 materials = { text: materialDetector(config, samples.text), reasoning: materialDetector(config, samples.reasoning) }
       const open = new Map()
       const closed = new Set()
       const finalized = new Set()
@@ -102,7 +143,7 @@ export function apply(ctx, raw, options = {}) {
       let reasoningChars = 0
       for await (const chunk of next()) {
         if (finalized.has(chunk.index)) continue
-        if (!active || options.signal?.aborted) { yield chunk; continue }
+        if (!active || options.signal?.aborted) { clearSamples(); 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) }
@@ -114,6 +155,8 @@ export function apply(ctx, raw, options = {}) {
         if (kind === 'text' && chunk.text.trim()) visibleText = true
         let cutoff = safe ? detectors[kind](chunk.text) : undefined
         let cause = 'repeated-' + kind
+        const material = safe ? materials[kind].push(chunk.text) : undefined
+        if (material && (cutoff === undefined || material.offset < cutoff)) { cutoff = material.offset; cause = material.cause }
         if (safe && kind === 'reasoning' && !visibleText && config.silentReasoningChars > 0) {
           const chars = [...chunk.text]
           const remaining = config.silentReasoningChars - reasoningChars
@@ -147,7 +190,13 @@ export function apply(ctx, raw, options = {}) {
         yield { type: 'finish', reason: { kind: 'stop' } }
         return
       }
+      if (active && !options.signal?.aborted && !hasToolCall && config.crossCallRepeatChars > 0) {
+        for (const kind of ['text', 'reasoning']) {
+          const sample = materials[kind].sample()
+          if (sample) { samples[kind].push(sample); if (samples[kind].length > 2) samples[kind].shift() }
+        }
+      }
     })()
   })
-  return () => { stop(); off(); coordinator.dispose() }
+  return () => { stop(); off(); coordinator.dispose(); observations.delete(agent) }
 }

package/engine/layers.mjs

@@ -18,7 +18,7 @@ import { INJECTION_LAYERS, KNOWN_STRATEGIES, SESSION_VARIABLES_DISABLED } from '
 import { interpolateVariables, stripUnresolvedRefs, RUNTIME_FACTS, runtimeFactValue, isReservedInterpolationName } from './interpolate.mjs'
 import { renderTemplate } from './template-frame.mjs'
 import { compareConfigSequence, compareTextPlacement } from './order.mjs'
-import { ruleFrame, actionMatches } from './conditions/evaluation.mjs'
+import { ruleFrame, actionMatches, actionSoulReminder, recheckSoulReminder } from './conditions/evaluation.mjs'
 import { textRegistrationName, identityStampOf, actionStamp, injectedMessage, findActionDelivery } from './delivery.mjs'
 
 const name = 'prompt-config-engine'
@@ -303,10 +303,15 @@ function wireRuleTextContributions(ctx, configs, registry, warnOnce, keep, on, o
       for (const config of binding.group) {
         if (!active || context.signal?.aborted || !actionMatches(config, frame) || !matchesAgentScope(config, context.agent)) continue
         try {
+          const reminder = actionSoulReminder(config, frame)
           const text = config.layer === 'runtime-context' && (config.strategy === 'placeholder' || !KNOWN_STRATEGIES.has(config.strategy))
             ? await resolvedContextText(ctx, config, context, registry.get(config), warnOnce)
             : configText(config, registry, warnOnce, context)
-          if (text.length) blocks.push(text)
+          if (!recheckSoulReminder(config, frame, reminder)) continue
+          if (text.length) {
+            const stamp = reminder === undefined ? '' : `\n<!-- soul-reminder:${Buffer.from(JSON.stringify({ moduleId: config.sourceModuleId, sessionId: context.agent.session.id, pendingVersion: reminder.pendingVersion, epoch: reminder.epoch })).toString('base64')} -->`
+            blocks.push(text + stamp)
+          }
         } catch (error) { warnOnce(`${name}: rule text ${config.id} failed: ${String(error?.message ?? error)}`) }
       }
       if (active && !context.signal?.aborted) {

package/engine/retrieval-reference.d.mts

@@ -1,4 +1,4 @@
-export type RetrievalEvent = { readonly seq: number; readonly type: string }
+export type RetrievalEvent = { readonly seq: number; readonly type: string; readonly time?: number }
 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

package/engine/retrieval.mjs

@@ -1,4 +1,4 @@
-import { bool, defineConfig, stringList } from './fields.mjs'
+import { bool, defineConfig, stringList, text } from './fields.mjs'
 import { toolServiceName } from './service-names.mjs'
 
 export const name = 'retrieval'
@@ -7,6 +7,7 @@ export const configContract = defineConfig({
   enabled: bool({ default: false }),
   paths: stringList({ default: () => [], allowEmpty: true, dedupe: true }),
   sessions: stringList({ default: () => [], allowEmpty: true, dedupe: true }),
+  synonymsFile: text({ default: undefined, allowEmpty: false }),
 })
 
 export function apply(ctx, raw, options) {

package/engine/rule-runtime.d.mts

@@ -16,6 +16,9 @@ export interface RuleManifestCheck {
   read(moduleId: string): boolean | undefined
 }
 
+export interface SoulReminderFact { count: number; pendingVersion: string; epoch: number; due: boolean }
+export interface RuleSoulReminder { read(moduleId: string, agent: unknown): SoulReminderFact | undefined }
+
 /** 判定上报载荷；仅覆盖插件依赖面（宿主按 `RuleOutcomeReport` 消费它）。 */
 export interface RuleOutcomeReport {
   moduleId?: string
@@ -37,6 +40,7 @@ export interface MountRuleSourcesOptions {
   variableStore?: RuleVariableStore
   /** 清单 checks 事实；缺省＝manifest 条件恒不可用。 */
   manifestCheck?: RuleManifestCheck
+  soulReminder?: RuleSoulReminder
   /** 官方预设兜底；缺省＝没有兜底（预设条件恒不命中）。 */
   standingMountFor?: StandingMountFor
   /** 注入的晋升相位实例对；缺省从协调器或自建池取。 */

package/engine/rule-runtime.mjs

@@ -82,7 +82,7 @@ function mountSources(ctx, sources, options = {}) {
   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 }) }
+      try { rebindConditions([source], { ctx, standingMountFor: options.standingMountFor, promotionPool: pool, variableStore: options.variableStore, manifestCheck: options.manifestCheck, soulReminder: options.soulReminder }) }
       catch (error) { throw sourceError(error, source.moduleId) }
     }
     const rules = sources.flatMap(source => source.rules.filter(rule => rule.enabled !== false))
@@ -115,7 +115,8 @@ function mountSources(ctx, sources, options = {}) {
       for (const item of point.items) {
         const { action, rule, moduleId } = item
         if (action.kind === 'inject-text') {
-          const config = { ...action.compiledConfig, rule, sourceModuleId: moduleId, variableStore: options.variableStore, group: undefined, exclusive: false, enabled: true, actionWhen: action.actionWhen, bypassRuleWhen: action.bypassRuleWhen, runtimeOrder: action.channelOrder, runtimeRuleIndex: item.ruleIndex }
+          const config = { ...action.compiledConfig, rule, sourceModuleId: moduleId, variableStore: options.variableStore,
+            group: undefined, exclusive: false, enabled: true, actionWhen: action.actionWhen, bypassRuleWhen: action.bypassRuleWhen, runtimeOrder: action.channelOrder, runtimeRuleIndex: item.ruleIndex }
           if (config.layer === 'pre-step') injections.get(moduleId).configs.push(config)
           else textConfigs.push(config)
           continue

package/engine/rule-spec.mjs

@@ -18,6 +18,8 @@ import { record } from './record.mjs'
 /** 规则字段：只有 `if`/`then`/`else`；旧名 `when`/`do` 留在名单里，只为把 unknown fields 换成一句「已退役，改用 X」。 */
 const RULE_FIELDS = new Set(['id', 'name', 'enabled', 'layer', 'group', 'exclusive', 'if', 'then', 'else', 'when', 'do'])
 const nonempty = value => typeof value === 'string' && value.trim().length > 0
+const hasSoulCondition = node => node !== null && typeof node === 'object'
+  && (Object.hasOwn(node, 'soul') || Object.values(node).some(hasSoulCondition))
 
 /** `prepend` 退役文案（动作层与 `inject-text.config` 共用）：等价档只有「注册到最外层」一档，而 `inject-text` 连它也不接受。 */
 const PREPEND_RETIRED = '`prepend` 已取消 — 它是未文档化的注册后门（executor 直读 config.prepend），作用只有「注册到最外层」一档：非 inject-text 动作改用 `waterfallPosition: outermost`；`inject-text` 不接受该字段，没有等价写法'
@@ -232,7 +234,7 @@ export function compileRules(specs, options = {}) {
   // 条件的绑定**不在编译期**：`preset` 谓词的取法要挂载 scope 的 ctx（`conditions/preset.mjs`），
   // 准备期拿不到。这里显式剥掉挂载期选项——传了也不生效，免得调用方以为已经绑好。
   // variableStore / manifestCheck 与 ctx/standingMountFor 同理：绑定发生在挂载期，准备期传了也不生效。
-  const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, manifestCheck: _manifestCheck, ...conditionOptions } = options
+  const { ctx: _ctx, standingMountFor: _standingMountFor, variableStore: _variableStore, manifestCheck: _manifestCheck, soulReminder: _soulReminder, ...conditionOptions } = options
   const ids = new Set()
   const pendingConfigs = []
   const moduleId = options.moduleId ?? options.sourceModuleId
@@ -294,6 +296,9 @@ export function compileRules(specs, options = {}) {
       const action = structuredClone(source)
       if (action.kind === 'inject-text') {
         action.config = injectionConfigSpec(spec, action, options)
+        if ((hasSoulCondition(ruleIf) || conditions.some(hasSoulCondition)) && !['pre-step', 'runtime-context'].includes(action.config.layer)) {
+          throw new TypeError('soul reminder conditions support only pre-step or runtime-context delivery')
+        }
       }
       const execution = ruleActionExecution(action)
       // 未知键检查必须在 normalizeActionGates **之后**：中性旧 audience/modelScope/promotion
@@ -413,6 +418,7 @@ function needsMountContext(node) {
   if (Object.hasOwn(node, 'variable')) return true
   // manifest 要读挂载 scope 的清单检查服务（准备期没有）。
   if (Object.hasOwn(node, 'manifest')) return true
+  if (Object.hasOwn(node, 'soul')) 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)

package/engine/soul-maintenance.mjs

@@ -10,6 +10,11 @@ export const configContract = defineConfig({
   enabled: bool({ default: false }), intervalMs: bounded(60000, 1000, 2147483647),
   wake: bool({ default: false }), audience: enumOf(['all', 'main', 'subagent'], { default: 'all' }),
   budgetBytes: bounded(12288, 1024, 65536),
+  pressureThresholds: passthrough((value, plugin, field) => {
+    if (value === undefined) return undefined
+    if (!Array.isArray(value) || value.length !== 3 || value.some((ratio, index) => typeof ratio !== 'number' || !Number.isFinite(ratio) || ratio <= 0 || ratio >= 1 || index > 0 && ratio <= value[index - 1])) throw new TypeError(`${plugin}: ${field} must be three increasing ratios between 0 and 1`)
+    return [...value]
+  }),
 })
 export function apply(ctx, raw, options = {}) {
   const config = configContract.parse(raw, name)

package/lib/client.js

@@ -744,6 +744,7 @@ window.__ModuleLoader__.load({
 			manifest: "module_manifest",
 			variables: "module_variables",
 			soulLedger: "soul_ledger",
+			soulState: "soul_state",
 			search: "module_search",
 			open: "module_open"
 		};
@@ -756,6 +757,7 @@ window.__ModuleLoader__.load({
 			[MODULE_TOOL_NAMES.manifest]: "module-manifest-tools",
 			[MODULE_TOOL_NAMES.variables]: "module-variable-tools",
 			[MODULE_TOOL_NAMES.soulLedger]: "soul-ledger",
+			[MODULE_TOOL_NAMES.soulState]: "soul-ledger",
 			[MODULE_TOOL_NAMES.search]: "retrieval",
 			[MODULE_TOOL_NAMES.open]: "retrieval"
 		};