dsh-plugin-prompt-tool 2.1.0 → 3.0.1

package/engine/conditions/index.mjs

@@ -7,8 +7,10 @@ import { createSessionStatePredicate } from './session.mjs'
 import { createPresetPredicate } from './preset.mjs'
 import { createScopePredicate } from './scope.mjs'
 import { createAnchorPredicate } from './anchor.mjs'
+import { createVariablePredicate } from './variable.mjs'
 import { withAvailableInput } from './availability.mjs'
 import { composite } from './composite.mjs'
+import { COMPOSITE_OPERATORS } from './operators.mjs'
 export * from './text.mjs'
 export * from './phase.mjs'
 export * from './source.mjs'
@@ -18,7 +20,8 @@ export * from './session.mjs'
 export * from './preset.mjs'
 export * from './scope.mjs'
 export * from './anchor.mjs'
-export { subjectOf } from './subject.mjs'
+export * from './variable.mjs'
+export { subjectOf, channelTextSubjects, channelFactSubjects, FACT_PREDICATE_SUBJECTS } from './subject.mjs'
 export { composite } from './composite.mjs'
 export const PREDICATE_FACTORIES = Object.freeze({
   text: createTextPredicate,
@@ -30,13 +33,14 @@ export const PREDICATE_FACTORIES = Object.freeze({
   preset: createPresetPredicate,
   scope: createScopePredicate,
   anchor: createAnchorPredicate,
+  variable: createVariablePredicate,
 })
-export const COMPOSITE_OPERATORS = Object.freeze(['any', 'all', 'not', 'notAny'])
+export { COMPOSITE_OPERATORS }
 
 const objectOrUndefined = (value, label) => {
   if (value === undefined || value === null) return undefined
   if (typeof value !== 'object' || Array.isArray(value)) {
-    throw new TypeError(`trigger-spec: ${label} must be an object`)
+    throw new TypeError(`rule.if: ${label} must be an object`)
   }
   return value
 }
@@ -44,15 +48,15 @@ const objectOrUndefined = (value, label) => {
 export function compileWhen(node, context = {}) {
   if (node === undefined || node === null) return undefined
   if (typeof node !== 'object' || Array.isArray(node)) {
-    throw new TypeError('trigger-spec: when must be an object (a composite node or a predicate node)')
+    throw new TypeError('rule.if: when must be an object (a composite node or a predicate node)')
   }
   const keys = Object.keys(node)
   if (keys.length === 0) {
-    throw new TypeError('trigger-spec: when must not be an empty object — 空节点是「恒真」还是「写漏了」无法区分')
+    throw new TypeError('rule.if: when must not be an empty object — 空节点是「恒真」还是「写漏了」无法区分')
   }
   if (keys.length > 1) {
     throw new TypeError(
-      `trigger-spec: when must declare exactly one key — got ${keys.sort().join(', ')}`
+      `rule.if: when must declare exactly one key — got ${keys.sort().join(', ')}`
       + `（allowed: ${[...COMPOSITE_OPERATORS, ...Object.keys(PREDICATE_FACTORIES)].sort().join(', ')}）`,
     )
   }
@@ -64,7 +68,7 @@ export function compileWhen(node, context = {}) {
       return composite({ not: compileWhen(value, context) })
     }
     if (!Array.isArray(value) || value.length === 0) {
-      throw new TypeError(`trigger-spec: when.${key} must be a non-empty array of nodes`)
+      throw new TypeError(`rule.if: when.${key} must be a non-empty array of nodes`)
     }
     return composite({ [key]: value.map((child) => compileWhen(child, context)) })
   }
@@ -72,14 +76,24 @@ export function compileWhen(node, context = {}) {
   const factory = PREDICATE_FACTORIES[key]
   if (factory === undefined) {
     throw new TypeError(
-      `trigger-spec: unknown predicate ${JSON.stringify(key)}`
+      `rule.if: unknown predicate ${JSON.stringify(key)}`
       + ` — known predicates: ${Object.keys(PREDICATE_FACTORIES).join(', ')}; composite: ${COMPOSITE_OPERATORS.join(', ')}`,
     )
   }
   const options = objectOrUndefined(value, `when.${key}`) ?? {}
-  // `preset` 原语的取法需要挂载期注入（见 predicates.mjs 的三条硬约束），其余原语只用选项。
+  // 条件上下文只补宿主查询、共享晋升池和同规则动作引用，不建立第二套运行状态。
+  if (key === 'anchor') {
+    return withAvailableInput(key, options, createAnchorPredicate(options, context))
+  }
   if (key === 'preset') {
     return withAvailableInput(key, options, createPresetPredicate({ ...options, ctx: context.ctx, standingMountFor: context.standingMountFor }))
   }
+  if (key === 'phase') {
+    return withAvailableInput(key, options, createPhasePredicate({ ...options, promotionPool: context.promotionPool }))
+  }
+  // 变量谓词自带三值处理：适配器缺失返回 UNAVAILABLE，不走通道事实的 availableInput。
+  if (key === 'variable') {
+    return createVariablePredicate(options, { store: context.variableStore, moduleId: context.moduleId })
+  }
   return withAvailableInput(key, options, factory(options))
 }

package/engine/conditions/operators.mjs

@@ -0,0 +1,4 @@
+/** 条件树组合算子的唯一清单：纯 ESM，无宿主 import，client 可打包。 */
+import { MATCH_LOGIC } from '../anchor-match.mjs'
+
+export const COMPOSITE_OPERATORS = Object.freeze(Object.values(MATCH_LOGIC))

package/engine/conditions/phase.mjs

@@ -18,7 +18,13 @@ export function createPhasePredicate(options = {}) {
     reasoningNegativePattern: options.reasoningNegativePattern,
     reasoningFlags: options.reasoningFlags,
   }
-  const tracker = createEpochPromotion(promoteEvents, trackerOptions)
+  // 订阅模式：追踪器从挂载缝的池里取（同配置复用、事件由池统一喂），本谓词**不再提供 observe**
+  // ——共用实例后重复喂会让门控步数翻倍（`applyEvent` 的 `steps += 1` 不幂等）。
+  // 池缺席（不经挂载缝直接调 `compileWhen` 的调用方，例如谓词单测）：退回自建并自带 observe，
+  // 行为与从前一致。不订阅模式（作者显式要求）：保持每次判定冷扫、且不给 observe——那正是
+  // 「不订阅」的语义，多一个入口只会诱使调用方以为状态被记住了。
+  const pooled = subscribe ? options.promotionPool : undefined
+  const tracker = pooled === undefined ? createEpochPromotion(promoteEvents, trackerOptions) : pooled.tracker(promoteEvents, trackerOptions)
   // 载荷归一后 agent 在 `payload.agent`；旧的手工形态（载荷本身就是 agent）由 agentOf 兼容。
   //
   // `compacted`（2026-09-22 用户拍板「扩原语」）：`status()` 本来就返回 `boundary`
@@ -47,7 +53,7 @@ export function createPhasePredicate(options = {}) {
     return status.promoted === (promotedOption ?? true)
   }
   predicate.kind = 'phase'
-  // 只有订阅模式才有增量入口：不订阅时多一个入口只会诱使调用方以为状态被记住了。
-  if (subscribe) predicate.observe = (session, event) => tracker.observe(session, event)
+  // 只有「自建 + 订阅」才提供增量入口：池已经统一喂过，再给入口就是重复推进相位。
+  if (subscribe && pooled === undefined) predicate.observe = (session, event) => tracker.observe(session, event)
   return predicate
 }

package/engine/conditions/preset.mjs

@@ -46,7 +46,7 @@ export function agentPresetId(ctx, agent, standingMountFor) {
     const mount = typeof standingMountFor === 'function' ? standingMountFor(agent?.ctx) : undefined
     return mount?.presetId
   } catch {
-    // 判定不抛出：拿不到就是「没有预设」（不命中），与 condition.mjs 的降级纪律一致。
+    // 判定不抛出：拿不到就是「没有预设」（不命中），与 condition-facts.mjs 的降级纪律一致。
     return undefined
   }
 }

package/engine/conditions/session.mjs

@@ -1,4 +1,5 @@
-import { isDelegated, sessionEvents } from '../shared.mjs'
+import { SURFACE_MESSAGE_TYPES, currentEvents, historyEvents } from '../history.mjs'
+import { isDelegated } from '../shared.mjs'
 import { sessionOf } from './subject.mjs'
 import { optionalBoolean } from './values.mjs'
 
@@ -12,9 +13,14 @@ export function createSessionStatePredicate(options = {}) {
   // `true` = 只在子代理命中，未声明 = 不判受众。子代理判定复用 `shared.isDelegated`，
   // 不写字面量比较（trigger.mjs 的会话态契约第 (2) 条纪律）。
   const delegated = optionalBoolean(options.delegated, 'delegated', undefined)
+  // `present` 对消息类镜像的是**当前上下文**，不是「本会话发生过」：被压缩遮蔽的事件模型已经看不到。
+  // 非 surface 承载的类型（`tool/call`、`turn/start`、`compaction/end`）永远不是 surface 节点，
+  // 按当前上下文判只会恒 false（`present: true`）/ 恒 true（`present: false`）——配置能编译能挂载，
+  // 却永不按意图命中，所以这类类型按完整历史判（类型表见 `history.mjs#SURFACE_MESSAGE_TYPES`）。
+  const view = SURFACE_MESSAGE_TYPES.has(type) ? currentEvents : historyEvents
   const predicate = (payload) => {
     if (delegated !== undefined && isDelegated(sessionOf(payload)) !== delegated) return false
-    return sessionEvents(sessionOf(payload))
+    return view(sessionOf(payload))
       .some((event) => event?.type === type) === present
   }
   predicate.kind = 'session'

package/engine/conditions/subject.mjs

@@ -1,30 +1,6 @@
-import { lastAssistantText, subagentTextOf, toolArgsText, userMessagesText } from '../condition.mjs'
+import { SUBJECT_FIELDS, lastAssistantText, subagentTextOf, toolArgsText, userMessagesText } from '../condition-facts.mjs'
 import { extractText } from '../shared.mjs'
 
-const CHANNEL_SUBJECTS = {
-  'system-prompt/assemble': (args) => ({ agent: args[1]?.agent }),
-  'agent/request': (args) => ({ agent: args[0]?.agent }),
-  'agent/pre-step': (args) => ({ agent: args[0]?.agent }),
-  'agent/inbox/inserted': (args) => ({ agent: args[0]?.agent, source: args[0]?.message?.source }),
-  'agent/turn-stopping': (args) => ({ agent: args[0]?.agent }),
-  'tools/pre-execute': (args) => ({ agent: args[0]?.agent, name: args[0]?.name }),
-  'tools/post-execute': (args) => ({ agent: args[0]?.agent, name: args[0]?.name }),
-  'session/event': (args) => ({ session: args[0] }),
-  'llm/stream': (args) => ({ model: args[0]?.model }),
-  'subagent/start': () => ({}),
-  'subagent/end': () => ({}),
-}
-
-/** 未知通道的告警去重（每个通道一次；判定期不刷屏）。 */
-const warnedChannels = new Set()
-
-/**
- * 归一化载荷的标记（Symbol，非字符串键）：`subjectOf` 产出它，`agentOf`/`sessionOf` 据此
- * 区分「归一化载荷」与「旧形态的直接 payload」——**不用启发式猜**（曾按「有没有 `.session`」
- * 判断，结果把测试里 `{ id, ctx }` 形状的假 agent 误判成归一化载荷）。
- */
-const SUBJECT_MARK = Symbol('predicate-subject')
-
 /**
  * 子代理事件判定期可见的 agent 事实。
  *
@@ -34,22 +10,139 @@ const SUBJECT_MARK = Symbol('predicate-subject')
  * 字符串）与 `scope.audience`（要求 session 可达）在子代理两层恒判 UNAVAILABLE——UI 上
  * 配了却永远不命中，正是 schema 注释要避免的「配了没效果也不报错」。
  *
- * 这里在**判定前**用事件里的 `id` 反查 agent 补齐同样的事实。取不到时不写键：判定
- * 退回 UNAVAILABLE（fail-closed），不得乐观放行。
+ * 这里在**判定前**用事件里的 `id` 反查 agent 补齐同样的事实。取不到时返回 `undefined`
+ * （取值器不写键）：判定退回 UNAVAILABLE（fail-closed），不得乐观放行。
+ */
+const subagentAgent = (args, ctx) => {
+  const id = args[0]?.id
+  if (typeof id !== 'string' || id.length === 0) return undefined
+  return ctx?.agents?.get?.(id) ?? undefined
+}
+
+const streamAgent = (args, ctx) => {
+  const call = args[0]
+  if (call?.agent !== undefined) return call.agent
+  if (typeof call?.sessionId !== 'string') return undefined
+  return (ctx?.get?.('agents') ?? ctx?.agents)?.get?.(call.sessionId)
+}
+
+/**
+ * 子代理两层的事实。`name` = provider（`SubagentRunInfo` 里唯一稳定的分类事实：
+ * spawn / fork / acp / codex / claude-code / dsh-sdk），`names` 谓词读的就是它，
+ * 因此 `names` 在这两层合法（编译期据此放行）。provider 可能缺席（官方注释：已接受的
+ * one-shot 变 ready 或持久 Activation 冷恢复时提供方未必仍注册）——那时返回 `undefined`
+ * 让取值器不写键、`names` 走 **运行期** UNAVAILABLE，而不是塞空串当「已知为空」，
+ * 也不是编译期拒绝。
+ */
+const SUBAGENT_FACTS = {
+  name: (args) => {
+    const provider = args[0]?.provider
+    return typeof provider === 'string' && provider.length > 0 ? provider : undefined
+  },
+  agent: subagentAgent,
+  session: (args, ctx) => subagentAgent(args, ctx)?.session,
+  model: (args, ctx) => {
+    const model = subagentAgent(args, ctx)?.options?.model
+    return typeof model === 'string' && model.length > 0 ? model : undefined
+  },
+}
+
+/**
+ * 通道 → 归一化载荷的字段与取值器：**唯一**的「该通道提供什么事实」真相。
+ * `channelTextSubjects` 与 `channelFactSubjects` 都从这张表派生，不另立第二张手抄表。
+ *
+ * - `text[字段名] = args => value`：字段名取自 `condition-facts.mjs#SUBJECT_FIELDS`，
+ *   经 `SUBJECT_OF_FIELD` 反查成文本 subject。
+ * - `facts[字段名] = (args, ctx) => value`：字段名本身即 subject（`name` / `source` /
+ *   `agent` / `session` / `model`）；返回 `undefined` 即不写键（判定退回 UNAVAILABLE）。
  */
-function subagentFacts(info, ctx) {
-  const facts = {}
-  const id = info?.id
-  if (typeof id !== 'string' || id.length === 0) return facts
-  const agent = ctx?.agents?.get?.(id)
-  if (agent === undefined || agent === null) return facts
-  facts.agent = agent
-  if (agent.session !== undefined) facts.session = agent.session
-  const model = agent.options?.model
-  if (typeof model === 'string' && model.length > 0) facts.model = model
-  return facts
+const CHANNELS = {
+  'system-prompt/assemble': { facts: { agent: args => args[1]?.agent } },
+  'agent/request': { facts: { agent: args => args[0]?.agent } },
+  'agent/pre-step': {
+    facts: { agent: args => args[0]?.agent },
+    text: { userText: args => userMessagesText(args[0]?.messages) },
+  },
+  'agent/inbox/inserted': {
+    facts: { agent: args => args[0]?.agent, source: args => args[0]?.message?.source },
+    text: { userText: args => userMessagesText([args[0]?.message]) },
+  },
+  'agent/turn-stopping': {
+    facts: { agent: args => args[0]?.agent },
+    text: { assistantText: args => lastAssistantText(args[0]?.agent?.session) },
+  },
+  'tools/pre-execute': {
+    facts: { agent: args => args[0]?.agent, name: args => args[0]?.name },
+    text: { argsText: args => toolArgsText(args[0]?.arguments) },
+  },
+  'tools/post-execute': {
+    facts: { agent: args => args[0]?.agent, name: args => args[0]?.name },
+    text: { argsText: args => toolArgsText(args[0]?.arguments), resultText: args => extractText(args[1]) },
+  },
+  'session/event': { facts: { session: args => args[0] } },
+  'llm/stream': { facts: { model: args => args[0]?.model, agent: streamAgent } },
+  'subagent/start': { facts: SUBAGENT_FACTS, text: { subagentText: args => subagentTextOf(args[0]) } },
+  'subagent/end': { facts: SUBAGENT_FACTS, text: { subagentText: args => subagentTextOf(args[0]) } },
 }
 
+/** 字段名 → subject 反查；键名只在 SUBJECT_FIELDS 声明一次，表与名单交叉而不重复。 */
+const SUBJECT_OF_FIELD = Object.fromEntries(Object.entries(SUBJECT_FIELDS).map(([subject, field]) => [field, subject]))
+
+/**
+ * 事实谓词 → 它读取的事实 subject：校验面与运行面的**唯一**登记处——新谓词还要在
+ * `PREDICATE_FACTORIES` 与通道可用性表登记，但「谓词 → subject」只此一处，
+ * `rule-spec.mjs#conditionSubjects` 直接消费本对象、`FACT_SUBJECTS` 也由它派生。
+ * shortcut: 漂移断言靠运行时改写本对象；将来若 `Object.freeze`，需把判据换成「同一引用」。
+ */
+export const FACT_PREDICATE_SUBJECTS = { names: 'name', source: 'source' }
+
+/** 谓词能消费的事实 subject：`names` 读 `name`、`source` 读 `source`；agent/session/model 不是谓词 subject。 */
+const FACT_SUBJECTS = Object.values(FACT_PREDICATE_SUBJECTS)
+
+/**
+ * 本通道可用的文本 subject。未列出的通道（`system-prompt/assemble`、`agent/request`、
+ * `llm/stream`、`session/event`）不提供任何文本，其上声明的 `text` 条件永不命中。
+ * @param {string} channel 官方事件名
+ * @returns {string[]} 可用 subject
+ */
+export function channelTextSubjects(channel) {
+  const fields = CHANNELS[channel]?.text
+  if (fields === undefined) return []
+  return Object.keys(fields).map(field => SUBJECT_OF_FIELD[field]).filter(subject => subject !== undefined)
+}
+
+/**
+ * 本通道可用的事实 subject（`name` / `source` 中它具备的那些）——编译期据此拒绝
+ * `names` / `source` 的死条件（见 `rule-spec.mjs`）。
+ * @param {string} channel 官方事件名
+ * @returns {string[]} 可用 subject
+ */
+export function channelFactSubjects(channel) {
+  const facts = CHANNELS[channel]?.facts
+  if (facts === undefined) return []
+  return FACT_SUBJECTS.filter(subject => Object.hasOwn(facts, subject))
+}
+
+/** 按表取字段：`undefined` 不写键——判定据此退回 UNAVAILABLE，而不是把「取不到」当成「已知为空」。 */
+function pickFields(readers, args, ctx) {
+  const out = {}
+  for (const [field, read] of Object.entries(readers ?? {})) {
+    const value = read(args, ctx)
+    if (value !== undefined) out[field] = value
+  }
+  return out
+}
+
+/** 未知通道的告警去重（每个通道一次；判定期不刷屏）。 */
+const warnedChannels = new Set()
+
+/**
+ * 归一化载荷的标记（Symbol，非字符串键）：`subjectOf` 产出它，`agentOf`/`sessionOf` 据此
+ * 区分「归一化载荷」与「旧形态的直接 payload」——**不用启发式猜**（曾按「有没有 `.session`」
+ * 判断，结果把测试里 `{ id, ctx }` 形状的假 agent 误判成归一化载荷）。
+ */
+const SUBJECT_MARK = Symbol('predicate-subject')
+
 /**
  * 把事件参数表归一为谓词载荷。
  *
@@ -68,36 +161,22 @@ export function subjectOf(channel, args, warn, ctx) {
   // `{ agent, turn }`）因此继续可见，既有断言不会因归一化而失效。
   const first = args[0]
   const base = first !== null && typeof first === 'object' && !Array.isArray(first) ? { ...first } : {}
-  const pick = CHANNEL_SUBJECTS[channel]
-  const text = (() => {
-    switch (channel) {
-      case 'tools/pre-execute': return { argsText: toolArgsText(args[0]?.arguments) }
-      case 'tools/post-execute': return { argsText: toolArgsText(args[0]?.arguments), resultText: extractText(args[1]) }
-      case 'agent/pre-step': return { userText: userMessagesText(args[0]?.messages) }
-      case 'agent/inbox/inserted': return { userText: userMessagesText([args[0]?.message]) }
-      case 'agent/turn-stopping': return { assistantText: lastAssistantText(args[0]?.agent?.session) }
-      // 子代理事件的 `name` = provider（`SubagentRunInfo` 里唯一稳定的分类事实：
-      // spawn / fork / acp / codex / claude-code / dsh-sdk）。`names` 谓词读的就是
-      // `payload.name`，因此 `if: { names: { allow: ['fork'] } }` 在此可用。
-      // provider 可能缺席（官方注释：已接受的 one-shot 变 ready 或持久 Activation 冷恢复时
-      // 提供方未必仍注册）——那时不写键，让 `names` 走 UNAVAILABLE，而不是塞空串当「已知为空」。
-      case 'subagent/start':
-      case 'subagent/end': return {
-        subagentText: subagentTextOf(args[0]),
-        ...(typeof args[0]?.provider === 'string' && args[0].provider.length > 0 ? { name: args[0].provider } : {}),
-        ...subagentFacts(args[0], ctx),
-      }
-      default: return {}
-    }
-  })()
-  if (pick === undefined) {
+  const spec = CHANNELS[channel]
+  if (spec === undefined) {
     if (typeof warn === 'function' && !warnedChannels.has(channel)) {
       warnedChannels.add(channel)
       warn(`predicates: unknown channel ${JSON.stringify(channel)} — 无显式取法，退回「第一个实参即载荷」的旧语义`)
     }
-    return { ...base, ...text, [SUBJECT_MARK]: true, channel, args }
+    return { ...base, [SUBJECT_MARK]: true, channel, args }
+  }
+  return {
+    ...base,
+    ...pickFields(spec.facts, args, ctx),
+    ...pickFields(spec.text, args, ctx),
+    [SUBJECT_MARK]: true,
+    channel,
+    args,
   }
-  return { ...base, ...pick(args), ...text, [SUBJECT_MARK]: true, channel, args }
 }
 
 /**
@@ -111,8 +190,8 @@ export function agentOf(payload) {
 
 /**
  * 从载荷取 session：归一化载荷走 `session` → `agent.session`；旧形态走
- * `session` → 载荷自身。取不到时返回原载荷——`sessionEvents` 对无 `snapshotEvents`
- * 的对象返回空，语义是「无事件」，与归一化之前逐例一致。
+ * `session` → 载荷自身。取不到时返回原载荷——`history.mjs#historyEvents` / `#currentEvents`
+ * 对无 `snapshotEvents` 的对象返回空，语义是「无事件」，与归一化之前逐例一致。
  */
 export function sessionOf(payload) {
   if (payload === null || typeof payload !== 'object') return payload

package/engine/conditions/text.mjs

@@ -1,15 +1,29 @@
 import { MATCH_LOGIC, createAnchorMatcher } from '../anchor-match.mjs'
-import { subjectTextOf } from '../condition.mjs'
+import { subjectTextOf } from '../condition-facts.mjs'
 import { keyList } from './values.mjs'
 import { conditionInputAvailable, UNAVAILABLE } from './availability.mjs'
-const MATCH_FLAGS = ['caseSensitive', 'wholeWords', 'useRegex', 'stWords']
+const MATCH_FLAGS = ['caseSensitive', 'wholeWords', 'useRegex']
 const MATCH_MODES = ['scan', 'prefix']
 
 export function createTextPredicate(options = {}) {
+  if (options.stWords !== undefined) throw new TypeError('stWords 已退役，请显式转换为 wordBoundary')
+  if (options.wordBoundary !== undefined && !['ascii-token', 'unicode'].includes(options.wordBoundary)) throw new TypeError('wordBoundary 必须是 ascii-token 或 unicode')
   const keys = keyList(options.keys, 'keys')
   const secondaryKeys = keyList(options.secondaryKeys, 'secondaryKeys')
-  if (keys.length === 0 && secondaryKeys.length === 0) {
-    throw new TypeError('predicates: a text predicate needs at least one non-empty key')
+  const bounds = ['minChars', 'maxChars'].map(field => {
+    const value = options[field]
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+      throw new TypeError(`predicates: ${field} must be a non-negative safe integer`)
+    }
+    return value
+  })
+  const [minChars, maxChars] = bounds
+  if (minChars !== undefined && maxChars !== undefined && minChars > maxChars) {
+    throw new TypeError('predicates: minChars cannot exceed maxChars')
+  }
+  const hasKeys = keys.length > 0 || secondaryKeys.length > 0
+  if (!hasKeys && minChars === undefined && maxChars === undefined) {
+    throw new TypeError('predicates: a text predicate needs a non-empty key or minChars/maxChars')
   }
   const logic = options.logic ?? MATCH_LOGIC.ANY
   if (!Object.values(MATCH_LOGIC).includes(logic)) {
@@ -33,12 +47,16 @@ export function createTextPredicate(options = {}) {
     useRegex: options.useRegex,
     logic,
     mode,
-    stWords: options.stWords === true,
+    wordBoundary: options.wordBoundary,
   })
   const subject = options.subject
-  const predicate = (payload) => conditionInputAvailable('text', options, payload)
-    ? matcher.scan(typeof payload === 'string' ? payload : subjectTextOf(subject, payload)).active === true
-    : UNAVAILABLE
+  const predicate = (payload) => {
+    if (!conditionInputAvailable('text', options, payload)) return UNAVAILABLE
+    const text = typeof payload === 'string' ? payload : subjectTextOf(subject, payload)
+    return (minChars === undefined || text.length >= minChars)
+      && (maxChars === undefined || text.length <= maxChars)
+      && (!hasKeys || matcher.scan(text).active === true)
+  }
   predicate.kind = 'text'
   return predicate
 }

package/engine/conditions/variable.mjs

@@ -0,0 +1,83 @@
+/**
+ * variable 谓词：把模块级持久变量接进规则条件。
+ *
+ * 适配器由挂载期绑定（`variableStore.read(moduleId)` → { module, global, effective, enabled }），
+ * 与模板求值共用同一个 owner；编译期没有适配器，判定为 UNAVAILABLE（三值语义，不能经 not 反转）。
+ */
+import { UNAVAILABLE } from './availability.mjs'
+
+const OPS = new Set(['eq', 'ne', 'in', 'gt', 'gte', 'lt', 'lte', 'present', 'absent'])
+const SCOPES = new Set(['effective', 'module', 'global'])
+
+/** 严格数字：空串与空白不算数字（`Number('')` 是 0，是陷阱）；非有限数不算数字。 */
+function numeric(text) {
+  if (text.trim().length === 0) return undefined
+  const value = Number(text)
+  return Number.isFinite(value) ? value : undefined
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.key 变量名（模块声明，引擎不认前缀）
+ * @param {'eq'|'ne'|'in'|'gt'|'gte'|'lt'|'lte'|'present'|'absent'} [options.op] 缺省 eq
+ * @param {string|string[]} [options.value] in 用数组；present/absent 不收
+ * @param {'effective'|'module'|'global'} [options.scope] 缺省 effective（模块覆盖全局）
+ * @param {{ store?: { read: (moduleId: string) => { module?: Record<string, string>, global?: Record<string, string>, effective?: Record<string, string>, enabled?: boolean } }, moduleId?: string }} [context]
+ */
+export function createVariablePredicate(options = {}, context = {}) {
+  const key = options.key
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError('predicates: variable key must be a non-empty string')
+  }
+  const op = options.op ?? 'eq'
+  if (!OPS.has(op)) {
+    throw new TypeError(`predicates: variable op must be one of ${[...OPS].join(', ')}`)
+  }
+  const scope = options.scope ?? 'effective'
+  if (!SCOPES.has(scope)) {
+    throw new TypeError(`predicates: variable scope must be one of ${[...SCOPES].join(', ')}`)
+  }
+  let expected
+  if (op === 'present' || op === 'absent') {
+    if (options.value !== undefined) throw new TypeError(`predicates: variable ${op} does not take value`)
+  } else if (op === 'in') {
+    if (!Array.isArray(options.value) || options.value.length === 0
+      || options.value.some((item) => typeof item !== 'string')) {
+      throw new TypeError('predicates: variable in needs a non-empty array of strings')
+    }
+    expected = options.value
+  } else {
+    if (typeof options.value !== 'string') throw new TypeError('predicates: variable value must be a string')
+    expected = options.value
+  }
+  const store = context.store
+  const moduleId = context.moduleId
+  const predicate = () => {
+    // 适配器缺失（准备期、复制协议未接）是「缺事实」，不是「变量为假」。
+    if (store === undefined || typeof store.read !== 'function') return UNAVAILABLE
+    if (typeof moduleId !== 'string' || moduleId.length === 0) return UNAVAILABLE
+    const state = store.read(moduleId)
+    if (state === null || typeof state !== 'object' || state.enabled === false) return UNAVAILABLE
+    const values = scope === 'global' ? state.global : scope === 'module' ? state.module : state.effective
+    if (values === null || typeof values !== 'object' || Array.isArray(values)) return UNAVAILABLE
+    const present = Object.hasOwn(values, key)
+    if (op === 'present') return present
+    if (op === 'absent') return !present
+    // 键缺失不是错误：比较类按假处理（作者写 present 才能区分「没有」）。
+    if (!present) return false
+    const actual = values[key]
+    if (typeof actual !== 'string') return false
+    if (op === 'eq') return actual === expected
+    if (op === 'ne') return actual !== expected
+    if (op === 'in') return expected.includes(actual)
+    const left = numeric(actual)
+    const right = numeric(expected)
+    if (left === undefined || right === undefined) return false
+    if (op === 'gt') return left > right
+    if (op === 'gte') return left >= right
+    if (op === 'lt') return left < right
+    return left <= right
+  }
+  predicate.kind = 'variable'
+  return predicate
+}

package/engine/context-activation.d.mts

@@ -0,0 +1,11 @@
+/** 上下文激活诊断的只读类型声明。 */
+export interface ContextActivationDiagnosticsSnapshot {
+  records: Array<{ id: string; stage: string; reason: string; [key: string]: unknown }>
+  truncated: boolean
+  step: number
+  /** false = 该会话尚未求值；true = 已求值（records 为空表示本次没有参与/入选条目）。 */
+  evaluated: boolean
+}
+export function lastContextActivationDiagnostics(session: unknown): ContextActivationDiagnosticsSnapshot
+export function selectContextActivation(...args: unknown[]): Set<Record<string, unknown>> & { diagnostics?: { records: unknown[]; truncated: boolean } }
+export function conversationMessages(session: unknown, pending?: unknown[]): Array<{ id: unknown; role: string; text: string }>