dsh-plugin-prompt-tool 3.0.1 → 3.1.0

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)

package/engine/schema.mjs

@@ -198,7 +198,7 @@ export const KNOWN_MODEL_SCOPES = new Set(['all', 'pro', 'flash'])
  * 自定义策略或模板 patch 的角色仍由 executor 在出口校验，避免写出非法事件。
  */
 export const KNOWN_ROLES = new Set(['user'])
-export const KNOWN_FILLS = new Set(['instruction-hint', 'env-facts', 'skill-catalog', 'tool-catalog'])
+export const KNOWN_FILLS = new Set(['instruction-hint', 'env-facts', 'skill-catalog', 'tool-catalog', 'soul-self'])
 
 /** 层能力矩阵：每个字段只在对应注入层生效。客户端表单据此动态渲染。 */
 export const LAYER_FIELD_POLICIES = Object.fromEntries(

package/engine/service-names.d.mts

@@ -5,6 +5,11 @@ export const PRE_STEP_COORDINATOR_SERVICE: string
 
 /** 发现引擎注册表服务名：宿主 root provide，adapter 行按 agent 注册，动作按 agent 解析。 */
 export const DISCOVERY_SERVICE: string
+export const SOUL_SELF_SERVICE: string
+export const SOUL_MAINTENANCE_SERVICE: string
+
+/** 模块清单 checks 事实：宿主提供，宿主装配读取后经挂载 options 传给谓词。 */
+export const MANIFEST_CHECK_SERVICE: 'promptToolManifestCheck'
 
 /** 四个模块工具外壳的服务名：`pt-<引擎模块 id>`。前缀是本函数的内部细节。 */
 export function toolServiceName(engineModuleId: string): string

package/engine/service-names.mjs

@@ -3,6 +3,11 @@ export const PRE_STEP_COORDINATOR_SERVICE = 'promptToolPreStep'
 
 /** 发现引擎注册表：宿主 root provide，adapter 行按 agent 注册，动作按 agent 解析。 */
 export const DISCOVERY_SERVICE = 'promptToolDiscovery'
+export const SOUL_SELF_SERVICE = 'promptToolSoulSelf'
+export const SOUL_MAINTENANCE_SERVICE = 'promptToolSoulMaintenance'
+
+/** 模块清单 checks 事实：宿主提供，宿主装配读取后经挂载 options 传给谓词。 */
+export const MANIFEST_CHECK_SERVICE = 'promptToolManifestCheck'
 
 /** 五个模块工具外壳的服务名：`pt-<引擎模块 id>`。前缀是本函数的内部细节。 */
 export function toolServiceName(engineModuleId) {

package/engine/soul-ledger.mjs

@@ -0,0 +1,8 @@
+import { toolServiceName } from './service-names.mjs'
+
+export const name = 'soul-ledger'
+export function apply(ctx) {
+  ctx.inject([toolServiceName(name)], scopeCtx => {
+    scopeCtx.effect(() => scopeCtx.get(toolServiceName(name)).mount(scopeCtx), name + ': mount')
+  })
+}

package/engine/soul-maintenance.mjs

@@ -0,0 +1,20 @@
+import { bool, defineConfig, enumOf, passthrough } from './fields.mjs'
+import { SOUL_MAINTENANCE_SERVICE } from './service-names.mjs'
+
+export const name = 'soul-maintenance'
+const bounded = (fallback, min, max) => passthrough((value = fallback, plugin, field) => {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new TypeError(`${plugin}: ${field} must be an integer from ${min} to ${max}`)
+  return value
+})
+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),
+})
+export function apply(ctx, raw, options = {}) {
+  const config = configContract.parse(raw, name)
+  if (!config.enabled) return
+  ctx.inject([SOUL_MAINTENANCE_SERVICE], scopeCtx => {
+    scopeCtx.effect(() => scopeCtx.get(SOUL_MAINTENANCE_SERVICE).mount(scopeCtx, config, options), name + ': mount')
+  })
+}

package/lib/client.js

@@ -742,7 +742,10 @@ window.__ModuleLoader__.load({
 			fileRead: "module_file_read",
 			fileAppend: "module_file_append",
 			manifest: "module_manifest",
-			variables: "module_variables"
+			variables: "module_variables",
+			soulLedger: "soul_ledger",
+			search: "module_search",
+			open: "module_open"
 		};
 		const MODULE_TOOL_CAPABILITIES = {
 			[MODULE_TOOL_NAMES.import]: "module-import-tools",
@@ -751,7 +754,10 @@ window.__ModuleLoader__.load({
 			[MODULE_TOOL_NAMES.fileRead]: "module-file-tools",
 			[MODULE_TOOL_NAMES.fileAppend]: "module-file-tools",
 			[MODULE_TOOL_NAMES.manifest]: "module-manifest-tools",
-			[MODULE_TOOL_NAMES.variables]: "module-variable-tools"
+			[MODULE_TOOL_NAMES.variables]: "module-variable-tools",
+			[MODULE_TOOL_NAMES.soulLedger]: "soul-ledger",
+			[MODULE_TOOL_NAMES.search]: "retrieval",
+			[MODULE_TOOL_NAMES.open]: "retrieval"
 		};
 		/** 旧公开类型名只作输入兼容。 */
 		/**
@@ -10469,6 +10475,7 @@ window.__ModuleLoader__.load({
 			"triggers.label.variable": "变量状态",
 			"triggers.label.op": "比较方式",
 			"triggers.label.value": "比较值",
+			"triggers.label.manifest": "清单检查",
 			"triggers.label.after": "限定在动作投递之后",
 			"triggers.label.afterAction": "起点动作标识",
 			"triggers.option.userMessage": "用户消息",
@@ -10494,6 +10501,7 @@ window.__ModuleLoader__.load({
 			"triggers.backToSettings": "返回本层参数",
 			"triggers.label.text": "文本",
 			"triggers.label.phase": "阶段",
+			"triggers.label.ok": "检查通过",
 			"triggers.label.source": "消息来源",
 			"triggers.label.count": "事件计数",
 			"triggers.label.names": "名称名单",
@@ -10549,7 +10557,7 @@ window.__ModuleLoader__.load({
 			"triggers.label.allowFrom": "按需解锁",
 			"triggers.label.tool": "发现工具",
 			"triggers.label.key": "键名",
-			"triggers.label.requireMatch": "名单工具缺失时保留完整目录",
+			"triggers.label.requireMatch": "名单工具全部缺失时保留完整目录",
 			"triggers.label.keep": "仅保留",
 			"triggers.label.remove": "移除",
 			"triggers.label.clear": "清空全部",
@@ -10693,6 +10701,7 @@ window.__ModuleLoader__.load({
 			"triggers.label.variable": "Variable state",
 			"triggers.label.op": "Comparison",
 			"triggers.label.value": "Comparison value",
+			"triggers.label.manifest": "Manifest check",
 			"triggers.label.after": "Observe after action delivery",
 			"triggers.label.afterAction": "Starting action ID",
 			"triggers.option.userMessage": "User message",
@@ -10718,6 +10727,7 @@ window.__ModuleLoader__.load({
 			"triggers.backToSettings": "Back to layer parameters",
 			"triggers.label.text": "Text",
 			"triggers.label.phase": "Phase",
+			"triggers.label.ok": "Checks passed",
 			"triggers.label.source": "Message source",
 			"triggers.label.count": "Event count",
 			"triggers.label.names": "Name list",
@@ -10773,7 +10783,7 @@ window.__ModuleLoader__.load({
 			"triggers.label.allowFrom": "On-demand unlocking",
 			"triggers.label.tool": "Discovery tool",
 			"triggers.label.key": "Key",
-			"triggers.label.requireMatch": "Keep the full catalog if a listed tool is missing",
+			"triggers.label.requireMatch": "Keep the full catalog only if no listed tool exists",
 			"triggers.label.keep": "Keep only",
 			"triggers.label.remove": "Remove",
 			"triggers.label.clear": "Clear all",
@@ -18457,7 +18467,7 @@ window.__ModuleLoader__.load({
 			"rules.surface.dynamic": "按需解锁",
 			"rules.surface.discoveryTool": "发现工具",
 			"rules.surface.argumentKey": "名单参数",
-			"rules.surface.requireMatch": "工具缺失时保留全部",
+			"rules.surface.requireMatch": "工具全部缺失时保留全部",
 			"rules.surface.textMode": "过滤方式",
 			"rules.surface.unrestricted": "不过滤",
 			"rules.surface.keep": "仅保留",
@@ -18582,7 +18592,7 @@ window.__ModuleLoader__.load({
 			"rules.surface.dynamic": "Unlock on demand",
 			"rules.surface.discoveryTool": "Discovery tool",
 			"rules.surface.argumentKey": "List argument",
-			"rules.surface.requireMatch": "Keep all if any tool is missing",
+			"rules.surface.requireMatch": "Keep all only if no tool exists",
 			"rules.surface.textMode": "Filter",
 			"rules.surface.unrestricted": "No filter",
 			"rules.surface.keep": "Keep only",