dsh-plugin-prompt-tool 2.1.0 → 3.0.0

package/engine/rule-runtime.mjs

@@ -1,22 +1,64 @@
 import { prepareAction } from './actions/index.mjs'
 import { applyPromptConfigSources } from './executor.mjs'
+import { createPreStepSource, moduleSourceId } from './pre-step-source.mjs'
 import { wireLayers } from './layers.mjs'
+import { rebindConditions, validateDeliverySources } from './rule-spec.mjs'
 import { wireTriggerObservers } from './trigger.mjs'
 import { ruleFrame, actionMatches } from './conditions/evaluation.mjs'
-import { createWarnOnce } from './shared.mjs'
+import { createPromotionPool } from './promotion-pool.mjs'
+import { PROMOTE_EVENTS, createWarnOnce, getService } from './shared.mjs'
+import { PRE_STEP_COORDINATOR_SERVICE } from './service-names.mjs'
 
 const noNext = new Set(['agent/inbox/inserted', 'agent/turn-stopping', 'subagent/start', 'subagent/end'])
+// 判据与 `order.mjs#compareConfigSequence` 有意不同：这里在同通道同点内按 moduleId 字母序 +
+// 规则声明序（ruleIndex）定位，`compareConfigSequence` 按 `sequence`（= 编辑器顺序，缺省回退
+// `order`）+ `ruleId` 排。收敛到 `ruleId` 会打断现网依赖的「编辑器顺序 = 执行顺序」，别顺手统一。
 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
 
-/** 所有来源只进入这个装配入口；注入保留原有批处理和协调器所有权。 */
+/** 所有来源只进入这个装配入口；受众限定固定效果要求 ctx 属于 options.agent 的 scope。 */
 export function mountRuleSources(ctx, sources, options = {}) {
+  validateDeliverySources(sources)
+  // 晋升相位池先建：条件的挂载期绑定要用它（`phase` 的订阅模式从池取实例，见 promotion-pool.mjs）。
+  // 池自己订阅 `session/event` 并统一喂事件；自建的随本挂载释放，注入的由创建者释放。
+  const coordinator = (() => {
+    const service = getService(ctx, PRE_STEP_COORDINATOR_SERVICE)
+    return service !== null && typeof service === 'object' && typeof service.registerPreset === 'function'
+      ? service
+      : undefined
+  })()
+  const pool = options.promotionPool ?? coordinator?.promotionPool ?? createPromotionPool(ctx)
+  const ownsPool = options.promotionPool === undefined && coordinator?.promotionPool === undefined
+  // 条件绑定**在这里**发生：`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。
+  const report = options.onOutcome === undefined ? undefined : (() => {
+    const moduleOfRule = new Map()
+    for (const source of sources) for (const rule of source.rules) if (!moduleOfRule.has(rule)) moduleOfRule.set(rule, source.moduleId)
+    return (rule, channel, outcome) => options.onOutcome({ moduleId: moduleOfRule.get(rule), ruleId: rule.id, channel, outcome })
+  })()
   const releases = []
+  // 自建池随本挂载释放；协调器/调用方注入的池由创建者释放（生命周期随归属，不跨界代管）。
+  if (ownsPool) releases.push(() => pool.dispose())
   const points = new Map()
-  const injections = new Map(sources.map(source => [source.moduleId, { sourceId: `module:${source.moduleId}`, configs: [], ruleActions: [], officialInstructions: source.officialInstructions === true }]))
+  // 续跑预算按来源模块一份：同模块的 turn-stop 动作共享上限，
+  // 不再按动作各建一份。本 mount 可能含多个模块（agent-assembly 一次装载全部启用模块），
+  // 因此按 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))
-  const observer = wireTriggerObservers(ctx, rules, { plugin: options.plugin ?? 'rule-engine', warnOnce })
+  // 动作级分支条件（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)
@@ -25,7 +67,6 @@ export function mountRuleSources(ctx, sources, options = {}) {
       if (rule.enabled === false) continue
       for (const action of rule.actions) {
         const item = { moduleId: source.moduleId, ruleIndex, rule, action }
-        if (action.execution.lifecycle === 'registration' && action.kind === 'guard') { releases.push(bind(item)); continue }
         const point = action.execution
         const key = `${point.channel}:${point.phase}:${action.waterfallPosition}`
         const bucket = points.get(key) ?? { ...point, waterfallPosition: action.waterfallPosition, items: [] }
@@ -39,6 +80,8 @@ export function mountRuleSources(ctx, sources, options = {}) {
       const flushLayers = () => {
         if (!textConfigs.length) return
         releases.push(wireLayers(ctx, textConfigs, warnOnce, {
+          agent: options.agent,
+          turnStopBudgets,
           on: (channel, handler) => {
             if (channel !== point.channel) throw new TypeError(`rule action registered outside ${point.channel}: ${channel}`)
             handlers.push({ handler }); return () => {}
@@ -49,20 +92,30 @@ export function mountRuleSources(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, group: undefined, exclusive: false, enabled: true, actionWhen: action.actionWhen, bypassRuleWhen: action.bypassRuleWhen }
+          const config = { ...action.compiledConfig, rule, sourceModuleId: moduleId, variableStore: options.variableStore, group: undefined, exclusive: false, enabled: true, actionWhen: action.actionWhen, bypassRuleWhen: action.bypassRuleWhen }
           if (config.layer === 'pre-step') injections.get(moduleId).configs.push(config)
           else textConfigs.push(config)
           continue
         }
         flushLayers()
+        const created = []
         const on = (channel, handler) => {
           if (channel !== point.channel) throw new TypeError(`rule action registered outside ${point.channel}: ${channel}`)
           const entry = { rule, handler, sequence: action.channelOrder, sourceModuleId: moduleId, ruleId: rule.id, ruleActionIndex: action.actionIndex, id: action.id, actionWhen: action.actionWhen, bypassRuleWhen: action.bypassRuleWhen }
           if (channel === 'agent/pre-step' && point.waterfallPosition === 'default') injections.get(moduleId).ruleActions.push(entry)
           else handlers.push(entry)
+          created.push(entry)
+          // 显式放弃：handler 的存活期由下面唯一的 `ctx.on(point.channel, …)` 统一撤销，
+          // 这里再返回一个真 disposer 会与它重复释放同一批 handler。
           return () => {}
         }
-        releases.push(bind(item, on))
+        const dispose = bind(item, on)
+        // 未命中通知：条件为假时动作不会进入 handler，撤销型动作（tool-visibility 的执行闸）
+        // 只能靠这条回调收手——否则第一轮为真后永久留闸。
+        if (typeof dispose?.miss === 'function') {
+          for (const entry of created) entry.miss = dispose.miss
+        }
+        releases.push(dispose)
       }
       flushLayers()
       if (!handlers.length) continue
@@ -71,11 +124,23 @@ export function mountRuleSources(ctx, sources, options = {}) {
         const payload = free ? args : args.slice(0, -1)
         const next = free ? () => undefined : args[args.length - 1]
         if (!active) return next()
-        const frame = ruleFrame(point.channel, payload, warnOnce, ctx)
+        // 帧构造失败（如宿主 snapshotEvents 抛错）只告警并按「无事实」跳过本点动作，
+        // 不得把异常抛出整条分派。
+        let frame
+        try {
+          frame = ruleFrame(point.channel, payload, warnOnce, ctx, report)
+        } catch (error) {
+          warnOnce(`rule engine: frame construction failed on ${point.channel}: ${String(error?.message ?? error)}`)
+          return next()
+        }
         if (free) {
           let pending
           for (const entry of handlers) {
-            const invoke = () => active && actionMatches(entry, frame) ? entry.handler(...payload, undefined, frame) : undefined
+            const invoke = () => {
+              if (!active) return undefined
+              if (!actionMatches(entry, frame)) { entry.miss?.(frame); return undefined }
+              return entry.handler(...payload, undefined, frame)
+            }
             pending = pending?.then ? pending.then(invoke) : invoke()
           }
           return pending
@@ -83,7 +148,8 @@ export function mountRuleSources(ctx, sources, options = {}) {
         if (point.phase === 'after-next') return Promise.resolve(next()).then(async initial => {
           let result = initial
           for (const entry of handlers) {
-            if (!active || !actionMatches(entry, frame)) continue
+            if (!active) continue
+            if (!actionMatches(entry, frame)) { entry.miss?.(frame); continue }
             result = await entry.handler(...payload, () => result, frame)
           }
           return result
@@ -91,13 +157,32 @@ export function mountRuleSources(ctx, sources, options = {}) {
         const invoke = index => {
           if (!active || index === handlers.length) return next()
           const entry = handlers[index]
-          return actionMatches(entry, frame) ? entry.handler(...payload, () => invoke(index + 1), frame) : invoke(index + 1)
+          if (!actionMatches(entry, frame)) {
+            entry.miss?.(frame)
+            return invoke(index + 1)
+          }
+          return entry.handler(...payload, () => invoke(index + 1), frame)
         }
         return invoke(0)
       }, point.waterfallPosition === 'outermost' ? { prepend: true } : undefined))
     }
-    const preStep = [...injections.values()].filter(source => source.configs.length || source.ruleActions.length)
-    if (preStep.length) releases.push(applyPromptConfigSources(ctx, preStep, { layers: false }))
+    // 晋升相位实例对：`options.promotion` 注入（托管路径传协调器那两份），否则从池里按配置取
+    // ——池在挂载开头已建，条件绑定也用它。共用实例后事件由池统一喂，消费者一律不得再 observe。
+    const promotion = options.promotion ?? coordinator?.promotion ?? {
+      main: pool.tracker(PROMOTE_EVENTS.either, { includeSubagents: false }),
+      withSubagents: pool.tracker(PROMOTE_EVENTS.either, { includeSubagents: true }),
+    }
+    const preStep = [...injections.values()]
+      .filter(source => source.configs.length || source.ruleActions.length)
+      .map(source => createPreStepSource({
+        sourceId: source.sourceId,
+        ctx,
+        configs: source.configs,
+        ruleActions: source.ruleActions,
+        onOutcome: options.onOutcome === undefined ? undefined : report => options.onOutcome({ moduleId: source.moduleId, ...report }),
+        promotion,
+      }))
+    if (preStep.length) releases.push(applyPromptConfigSources(preStep, { layers: false }))
   } catch (error) {
     active = false
     for (const dispose of releases.reverse()) { try { dispose?.() } catch {} }

package/engine/rule-spec.d.mts

@@ -0,0 +1,106 @@
+/**
+ * `rule-spec.mjs` 的手写声明：只声明 `src/` 与 `test/engine/` 消费的导出，形状按实现写实。
+ *
+ * 这里不复用插件侧类型（声明文件与 `.mjs` 同目录，`src/` 不在引擎的类型解析面内），
+ * 只用结构等价的本地形状；被消费的字段与 `engine/rule-spec.mjs` 的产物逐名对应。
+ */
+import type { RuleAudience } from './audience.mjs'
+export type { RuleAudience }
+
+/** 编译后的动作；仅覆盖插件依赖面（装配侧只读 id/kind/channelOrder/waterfallPosition/compiledConfig）。 */
+export interface CompiledRuleAction {
+  id: string
+  kind: string
+  channelOrder: number
+  waterfallPosition: string
+  actionIndex: number
+  /** inject-text 动作编译出的注入叶子；其余动作没有这个字段。 */
+  compiledConfig?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/** 编译后的规则；仅覆盖插件依赖面（装配侧只读 id/enabled/actions）。 */
+export interface CompiledRule {
+  id: string
+  name?: string
+  layer?: string
+  enabled: boolean
+  exclusive: boolean
+  sequence: number
+  actions: CompiledRuleAction[]
+  [key: string]: unknown
+}
+
+/** `options.promptConfigOptions`：模板与策略的取法，交给 `schema.mjs#createPromptConfigs`。 */
+export interface PromptConfigCompileOptions {
+  templateBaseUrl?: URL
+  templateModuleRoot?: URL
+  strategyDir?: string
+  loadTemplate?: (file: unknown) => unknown
+}
+
+export interface CompileRulesOptions {
+  moduleId?: string
+  sourceModuleId?: string
+  configOrder?: Record<string, number>
+  variables?: Record<string, string>
+  variablesEnabled?: boolean
+  contextActivationRecursive?: boolean
+  /** 人设已独占 complete 段时拒绝第二条（宿主聚合用）。 */
+  personaComplete?: boolean
+  promptConfigOptions?: PromptConfigCompileOptions
+  /** 挂载期输入：编译期显式剥掉，绑定由 `rule-runtime.mjs` 完成。 */
+  ctx?: unknown
+  standingMountFor?: unknown
+}
+
+/** 引擎编译出的注入配置叶子；只列编译必产出的字段，宿主按自己的 `PromptConfigSpec` 消费它。 */
+export interface InjectionConfigSpec {
+  id: string
+  layer: string
+  strategy?: string
+  order?: number
+  sourceKind?: string
+  text?: string
+  texts?: string[]
+  templateFile?: string
+  fill?: string
+  variables?: Record<string, string>
+  params?: Record<string, unknown>
+}
+
+/** 规则与动作的执行点目录（编辑器元数据）；结构等价于 `src/shared/rules.ts` 的 `RuleEditorMeta`。 */
+export interface RuleEditorMeta {
+  predicates: Array<{ kind: string; example: Record<string, unknown> }>
+  actions: Array<{
+    kind: string
+    example: Record<string, unknown>
+    channel: string
+    phase: string
+    lifecycle: 'event' | 'registration'
+    supportsWhen: boolean
+  }>
+  composites: string[]
+  waterfallPositions: string[]
+}
+
+/** 规则及物化身份的唯一安全边界；非法值抛 `TypeError`。 */
+export function assertRuleId(id: unknown): void
+
+export function compileRules(specs: readonly unknown[], options?: CompileRulesOptions): CompiledRule[]
+
+/** 该受众下独占的 `complete` 系统段，身份是 `rule.id/action.id`。 */
+export function completeRuleSections(rules: readonly unknown[], audience: RuleAudience): string[]
+
+
+
+/** 动作级受众事实：规则级 when 与动作级 conditions 的合取；else 动作（bypassRuleWhen）只读动作条件。 */
+export function actionAudiences(rule: unknown, actionId: string): Set<RuleAudience>
+
+export function injectionConfigSpec(
+  rule: { id: string; layer?: string },
+  action: { id: string; kind?: string; config?: unknown },
+  options?: { variables?: Record<string, string>; variablesEnabled?: boolean },
+): InjectionConfigSpec
+
+export function getRuleEditorMeta(): RuleEditorMeta