dsh-plugin-prompt-tool 0.8.1 → 2.0.0

package/engine/actions/catalog.mjs

@@ -0,0 +1,92 @@
+export const ACTION_DEGRADE = Object.freeze({
+  keep: 'keep',
+  exposeAll: 'expose-all',
+  empty: 'empty',
+  silent: 'silent',
+})
+
+/**
+ * 七类动作的声明：**合法事件通道** + **降级语义** + 触发时机。
+ * `events` 是动作允许注册的官方事件（注册到声明外的事件在挂载期 fail loud）；
+ * `services` 是它允许触碰的宿主服务方法（同一纪律的文档面）。
+ */
+export const ACTION_KINDS = Object.freeze({
+  'inject-text': {
+    title: '注入文本',
+    events: ['agent/pre-step', 'session/event', 'system-prompt/assemble', 'agent/request', 'llm/stream', 'tools/pre-execute', 'tools/post-execute', 'agent/turn-stopping', 'subagent/start', 'subagent/end'],
+    services: ['systemPrompt.section', 'systemPrompt.context', 'systemPrompt.variable'],
+    degrade: ACTION_DEGRADE.keep,
+    timing: '按配置声明的 layer 落到该层官方通道；pre-step 在 agent/pre-step，system-section/runtime-context 在注册期 + 官方 assembly。',
+    note: '复用九层注册通道，不新开通道；显式空正文 = 不注册（empty 情形）。`options` 原样交给该层的既有接线（pre-step 执行器的 `prepend` = 声明的位置策略）；`session/event` 是 pre-step 执行器自带的会话态旁听，不是第二条注入通道。',
+  },
+  assembly: {
+    title: '改装配',
+    events: ['system-prompt/assemble'],
+    services: [],
+    degrade: ACTION_DEGRADE.exposeAll,
+    timing: 'system-prompt/assemble 的下游结算之后（`await next()` 之后改，装配事实已就绪）。',
+    note: '失败时返回未改动的装配 = 对 tools 即暴露完整目录；不改 global，只作用于本次 assembly。',
+  },
+  decision: {
+    title: '裁决',
+    events: ['tools/pre-execute', 'tools/post-execute'],
+    services: [],
+    degrade: ACTION_DEGRADE.keep,
+    timing: 'pre 相在工具执行之前返回 allow|deny|ask；post 相在结果结算之后返回 accept|replace|block。',
+    note: '异常与条件未命中一律 `next()`（放行/接受），绝不让裁决 bug 卡死调用。',
+  },
+  'append-context': {
+    title: '追加上下文与续跑',
+    events: ['tools/post-execute', 'agent/turn-stopping'],
+    services: [],
+    degrade: ACTION_DEGRADE.keep,
+    timing: 'mode=context 在 post-execute 追加 durable user 通知；mode=continue 在 agent/turn-stopping steer 一步。',
+    note: '续跑共用引擎的续跑预算（每轮 1 次 / 每会话 3 次），无正文时不追加（empty 情形）；绝不伪造 assistant 角色。',
+  },
+  guard: {
+    title: '执行层 guard',
+    events: ['system-prompt/assemble'],
+    services: ['tools.guard', 'tools.restrict'],
+    degrade: ACTION_DEGRADE.silent,
+    timing: '首次 assembly 时按 agent scope 惰性注册一次（预设切换/重绑后按新的 agent.ctx 重注册）。',
+    note: '最终拒绝层：注册在 agent.ctx 上（工具本层与晚到工具也被裁决），命中返回拒绝原因；不注册全局 guard。guard 自身不吞异常——异常即失败，绝不退化成"放行"。',
+  },
+  'sdk-strip': {
+    title: '裁 SDK 声明文本',
+    events: ['system-prompt/assemble'],
+    services: [],
+    degrade: ACTION_DEGRADE.keep,
+    timing: 'system-prompt/assemble 下游结算之后，改写名为 tools:sdk 的段文本。',
+    note: '只删不增、保守失败：形态异常/自校验失败一律原样返回；空名单零开销。仅是呈现补救，执行边界在 guard。',
+  },
+  'request-params': {
+    title: '改模型请求参数',
+    events: ['agent/request'],
+    services: [],
+    degrade: ACTION_DEGRADE.keep,
+    timing: 'agent/request 的下游结算之后（`await next()` 拿到已冻结的 LlmCallConfig 再改写）。',
+    note: '与既有 promptConfigs 的 agent-request 层共用 applyAgentRequestParams；只改命中 scope/agent 的请求，删键仅删"本声明注入的那个值"。',
+  },
+  'inbox-prepend': {
+    title: '前置收件箱消息',
+    events: ['agent/inbox/inserted'],
+    services: ['agent.inbox.prepend'],
+    degrade: ACTION_DEGRADE.silent,
+    timing: 'emit 通道（**无 next**）：命中即前置一条消息，不命中什么都不做。',
+    note: '只前置不追加；插件来源消息（含本动作自己插入的那条）永不再次前置，防自触发插队。'
+      + '收件箱的持久化归宿主（`agent/inbox/spliced`），本动作不自己落盘。',
+  },
+  'pre-step-filter': {
+    title: '过滤 pre-step 注入消息',
+    events: ['agent/pre-step'],
+    services: [],
+    degrade: ACTION_DEGRADE.exposeAll,
+    timing: 'agent/pre-step 的下游结算之后（`await next()` 拿到 decision 再过滤 messages）。',
+    note: '两种白名单模式**互斥**：`sources` = 严格白名单（只放行这些 `source.kind`，含 claimed 批）；'
+      + '`keepKinds` = 保留 claimed 基线（按对象身份或 id）+ 这些 kind。未声明任一 = 不过滤（零开销）。'
+      + '`blockPlugins` 是与二者**正交**的另一维度、可共存：仅当来源 kind 为 plugin 时按 `source.plugin` '
+      + '做大小写不敏感的**精确等值**匹配并剔除命中项，不做子串/正则/glob；空名单 = 关闭'
+      + '（与白名单「空 = 全拦」不同），未声明 = 不过滤。'
+      + '**永不吞上下文**：异常一律返回未过滤的 decision（`expose-all`）。',
+  },
+})

package/engine/actions/content.mjs

@@ -0,0 +1,205 @@
+/**
+ * strategies — 引擎内容策略绑定(config.resolve)。
+ * 内容策略: static / placeholder / first-turn-anchor / guide-auto / anchor-notice / world-book。
+ * 策略参数全部来自 config.params（由 preset.yml 单一配置源下发），引擎只负责组装。
+ * 仍支持 strategyDir 懒加载自定义模板策略。
+ */
+
+import { extractText } from '../shared.mjs'
+import { MATCH_LOGIC, createAnchorMatcher } from '../anchor-match.mjs'
+import { createTaskClassifier } from '../classify-task.mjs'
+import { createPlaceholderResolver } from '../fillers.mjs'
+import { createAnchorState } from '../conditions/anchor.mjs'
+
+const name = 'prompt-config-engine'
+
+/**
+ * first-turn-anchor:首条真实用户消息后的一次性任务锚点。
+ * 正则与锚句文本全部来自 config.params（由 preset.yml 单一配置源下发）。
+ */
+function createFirstTurnAnchorResolver(config) {
+  const useCustom = config.params?.useCustom === true
+  const customText = typeof config.params?.text === 'string' ? config.params.text : ''
+  const buildPattern = typeof config.params?.buildPattern === 'string' ? config.params.buildPattern : ''
+  const complexPattern = typeof config.params?.complexPattern === 'string' ? config.params.complexPattern : ''
+  const firstTurnBuild = typeof config.params?.firstTurnBuild === 'string' ? config.params.firstTurnBuild : ''
+  const firstTurnInspect = typeof config.params?.firstTurnInspect === 'string' ? config.params.firstTurnInspect : ''
+  const firstTurnDeep = typeof config.params?.firstTurnDeep === 'string' ? config.params.firstTurnDeep : ''
+  const classifier = createTaskClassifier({ buildPattern, complexPattern })
+  return ({ messages }) => {
+    if (useCustom) {
+      const text = customText.trim()
+      return text.length > 0 ? { text } : null
+    }
+    if (!classifier.ready || (firstTurnBuild.length === 0 && firstTurnInspect.length === 0 && firstTurnDeep.length === 0)) {
+      return null
+    }
+    const userIndex = messages.findIndex((message) => message?.source?.kind === 'user')
+    if (userIndex < 0) return null
+    const taskText = extractText(messages[userIndex])
+    if (taskText.length === 0) return null
+    const kind = classifier.classify(taskText)
+    const anchor = kind === 'complex' ? firstTurnDeep : kind === 'build' ? firstTurnBuild : firstTurnInspect
+    return anchor.length > 0 ? { text: anchor } : null
+  }
+}
+
+/**
+ * guide-auto:晋升后每轮用户消息后的弱/深度引导。
+ * 正则与引导文本全部来自 config.params（由 preset.yml 单一配置源下发）。
+ * 复杂任务判定 fallback 复用锚定功能的 complexPattern（guideComplexPattern
+ * 冗余副本已移除）——锚定与引导是独立功能，仅分类器共用。
+ */
+function createGuideAutoResolver(config) {
+  const useCustom = config.params?.useCustom === true
+  const customText = typeof config.params?.text === 'string' ? config.params.text : ''
+  const complexPattern = typeof config.params?.complexPattern === 'string' ? config.params.complexPattern : ''
+  const guideWeak = typeof config.params?.guideWeak === 'string' ? config.params.guideWeak : ''
+  const guideDeep = typeof config.params?.guideDeep === 'string' ? config.params.guideDeep : ''
+  const rawMinChars = config.params?.complexMinChars
+  const complexMinChars = rawMinChars == null || rawMinChars === '' ? undefined : rawMinChars
+  if (complexMinChars !== undefined && (!Number.isSafeInteger(complexMinChars) || complexMinChars < 0)) throw new TypeError(`${name}: guide-auto complexMinChars must be a non-negative integer`)
+  // 复杂判定 fallback 复用锚定分类器（buildPattern 不参与引导判定）。
+  const classifier = createTaskClassifier({ complexPattern })
+  return ({ messages }) => {
+    const userIndex = messages.findIndex((message) => message?.source?.kind === 'user')
+    if (userIndex < 0) return null
+    const text = extractText(messages[userIndex])
+    if (text.length === 0) return null
+    if (useCustom) {
+      const guide = customText.trim()
+      return guide.length > 0 ? { text: guide } : null
+    }
+    if (guideWeak.length === 0 && guideDeep.length === 0) return null
+    return { text: ((complexMinChars !== undefined && text.length > complexMinChars) || classifier.isComplex(text)) ? guideDeep : guideWeak }
+  }
+}
+
+/**
+ * anchor-notice 只生成显式正文与来源说明；资格由规则条件单独负责。
+ */
+function createAnchorNoticeResolver(config) {
+  const promptText = config.texts.length > 0
+    ? config.texts.join('\n\n')
+    : (typeof config.params?.text === 'string' && config.params.text.length > 0 ? config.params.text : undefined)
+  // 确认词无内置默认（默认值归模板/预设）：空 = 不做词确认，只走未命中兜底注入。
+  const firstTurnWord = typeof config.params?.firstTurnWord === 'string' ? config.params.firstTurnWord : ''
+  // 确认词集合：writePreset 派生的 anchorWords 优先（锚句信号词多词 prefix，任一命中即
+  // 确认——deep 档 Let…/自定义锚句首词都覆盖）；无 anchorWords 时用显式确认词。
+  const anchorWords = Array.isArray(config.params?.anchorWords) && config.params.anchorWords.length > 0
+    ? config.params.anchorWords.map(String).filter((word) => word.length > 0)
+    : (firstTurnWord.length > 0 ? [firstTurnWord] : [])
+  const inspect = createAnchorState({ keys: anchorWords })
+
+  return ({ agent }) => {
+    if (promptText === undefined) return null
+    const { confirmed } = inspect(agent.session)
+    return {
+      text: promptText,
+      source: {
+        // v4 要求 kind 是生产者名：裸 `plugin` 是退役包装，会被会话格式校验拒绝。
+        kind: `plugin:${config.id}`,
+        plugin: config.id,
+        form: 'notice',
+        summary: confirmed
+          ? (firstTurnWord.length > 0 ? `prompt-tool 提示词(「${firstTurnWord}」锚定确认后注入)` : 'prompt-tool 提示词(无确认词,锚定就绪后注入)')
+          : (firstTurnWord.length > 0 ? `prompt-tool 提示词(「${firstTurnWord}」未确认,兜底注入)` : 'prompt-tool 提示词(无确认词,兜底注入)'),
+      },
+    }
+  }
+}
+
+/**
+ * world-book:世界书条目(角色卡 lorebook)。constant=true 恒注入(不扫 keys);
+ * selective 条目扫描当前消息批文本,keys/secondaryKeys 按 selectiveLogic 组合
+ * (any=任一命中 / all=副键全中 / not=副键全不中)。匹配经 anchor-match 引擎。
+ */
+function createWorldBookResolver(config) {
+  if (config.params?.stWorldBook) return ({ stWorldBookSelected }) => stWorldBookSelected === true ? { text: config.texts.join('\n\n') } : null
+  const constant = config.params?.constant === true
+  // selectiveLogic：ST world_info_logic 0=AND_ANY 1=NOT_ALL 2=NOT_ANY 3=AND_ALL。
+  const rawLogic = config.params?.selectiveLogic
+  const logic = rawLogic === 3
+    ? MATCH_LOGIC.ALL
+    : (rawLogic === 1
+      ? MATCH_LOGIC.NOT
+      : (rawLogic === 2 ? MATCH_LOGIC.NOT_ANY : MATCH_LOGIC.ANY))
+  const matcher = createAnchorMatcher({
+    keys: Array.isArray(config.params?.keys) ? config.params.keys : [],
+    secondaryKeys: Array.isArray(config.params?.secondaryKeys) ? config.params.secondaryKeys : [],
+    caseSensitive: config.params?.caseSensitive === true,
+    wholeWords: config.params?.wholeWords === true,
+    // 三态透传：undefined=ST 语义自动检测（/regex/ 或含特殊字符键按正则）；
+    // 存量配置显式 true/false 仍强制对应行为。
+    useRegex: config.params?.useRegex,
+    logic,
+  })
+  // ST 语义：constant 或无任何键的条目恒注入（always active）。
+  const hasAnyKey = (Array.isArray(config.params?.keys) ? config.params.keys : [])
+      .some((key) => String(key).trim().length > 0)
+    || (Array.isArray(config.params?.secondaryKeys) ? config.params.secondaryKeys : [])
+      .some((key) => String(key).trim().length > 0)
+  const promptText = config.texts.length > 0
+    ? config.texts.join('\n\n')
+    : (typeof config.params?.text === 'string' && config.params.text.length > 0 ? config.params.text : undefined)
+  return ({ messages }) => {
+    if (promptText === undefined) return null
+    if (constant || !hasAnyKey) return { text: promptText }
+    const haystack = (Array.isArray(messages) ? messages : [])
+      .map((message) => extractText(message))
+      .filter((text) => text.length > 0)
+      .join('\n')
+    if (haystack.length === 0) return null
+    return matcher.scan(haystack).active ? { text: promptText } : null
+  }
+}
+
+/**
+ * 为归一化后的提示词配置绑定策略 resolve(策略状态随提示词配置对象,不随 apply)。
+ * strategyDir:外部策略模块目录(相对本文件 URL)。未声明时只允许内置策略。
+ */
+export function bindResolver(config, strategyDir) {
+  switch (config.strategy) {
+    case 'placeholder': return createPlaceholderResolver(config)
+    case 'first-turn-anchor': return createFirstTurnAnchorResolver(config)
+    case 'guide-auto': return createGuideAutoResolver(config)
+    case 'custom-fallback':
+      throw new TypeError(`${name}: migrate custom-fallback to an anchor condition and anchor-notice content`)
+    case 'anchor-notice':
+      return createAnchorNoticeResolver(config)
+    case 'world-book':
+      return createWorldBookResolver(config)
+    case 'static': {
+      const texts = config.texts
+      const patch = config.templatePatch ?? {}
+      return () => {
+        if (texts.length > 0) return { ...patch, content: texts.map((item) => ({ type: 'text', text: item })) }
+        return null
+      }
+    }
+    default: {
+      // 模板专属策略:懒加载 <strategyDir>/<strategy>.mjs,模块约定导出
+      // `createResolver(config)` 或默认导出同名工厂。加载失败按单配置失败语义
+      // 抛给调用方(executor 会跳过该配置并 warnOnce)。
+      if (typeof strategyDir !== 'string' || strategyDir.length === 0) {
+        throw new TypeError(`${name}: unknown config strategy ${JSON.stringify(config.strategy)}`)
+      }
+      const moduleUrl = new URL(`${config.strategy}.mjs`, strategyDir.endsWith('/') ? strategyDir : `${strategyDir}/`)
+      let loaded
+      return async (args) => {
+        if (loaded === undefined) {
+          loaded = await import(moduleUrl.href)
+        }
+        const make = typeof loaded.createResolver === 'function'
+          ? loaded.createResolver
+          : typeof loaded.default === 'function'
+            ? loaded.default
+            : undefined
+        if (typeof make !== 'function') {
+          throw new TypeError(`${name}: strategy module ${moduleUrl.href} must export createResolver(config)`)
+        }
+        return make(config)(args)
+      }
+    }
+  }
+}

package/engine/actions/decision.mjs

@@ -0,0 +1,54 @@
+import { labelOf, toolNameSet } from './shared.mjs'
+
+export function prepareDecision(action, plugin) {
+  const label = labelOf(action)
+  const names = toolNameSet(action.toolNames, plugin, `${label}.toolNames`)
+  const matchesTool = (exec) => names === undefined || names.has(exec?.name)
+  const hit = (exec, result) => typeof action.match !== 'function' || action.match(exec, result) === true
+  const phase = action.phase === undefined ? 'pre' : action.phase
+  if (!['pre', 'post'].includes(phase)) {
+    throw new TypeError(`${plugin}: ${label}.phase must be one of pre, post`)
+  }
+  if (phase === 'pre') {
+    const decision = action.decision ?? 'allow'
+    if (!['allow', 'deny', 'ask'].includes(decision)) {
+      throw new TypeError(`${plugin}: ${label}.decision must be one of allow, deny, ask`)
+    }
+    return (_ctx, { warnOnce, on, collect, take }) => collect(on('tools/pre-execute', async (exec, next) => {
+      try {
+        if (!matchesTool(exec) || !hit(exec)) return next()
+        if (decision === 'allow') return next()
+        const outcome = decision === 'deny'
+          ? { kind: 'deny', reason: String(action.reason ?? `${label}: denied by action`) }
+          : { kind: 'ask' }
+        return take(exec) ? outcome : next()
+      } catch (error) {
+        warnOnce(`${plugin}: decision(pre) action ${label} failed: ${String(error?.message ?? error)}`)
+        return next()
+      }
+    }))
+  }
+  const postAction = action.action ?? 'accept'
+  if (!['accept', 'replace', 'block'].includes(postAction)) {
+    throw new TypeError(`${plugin}: ${label}.action must be one of accept, replace, block`)
+  }
+  const text = typeof action.text === 'string' ? action.text : ''
+  return (_ctx, { warnOnce, on, collect, take }) => collect(on('tools/post-execute', async (exec, result, next) => {
+    try {
+      if (!matchesTool(exec) || !hit(exec, result)) return next()
+      if (postAction === 'accept') return next()
+      if (postAction === 'replace' && text.length > 0) {
+        if (!take(exec)) return next()
+        return { kind: 'accept', content: [{ type: 'text', text }] }
+      }
+      if (postAction === 'block') {
+        if (!take(exec)) return next()
+        return { kind: 'block', feedback: [{ type: 'text', text: text.length > 0 ? text : `${label}: blocked by action` }] }
+      }
+      return next()
+    } catch (error) {
+      warnOnce(`${plugin}: decision(post) action ${label} failed: ${String(error?.message ?? error)}`)
+      return next()
+    }
+  }))
+}

package/engine/actions/examples.mjs

@@ -0,0 +1,11 @@
+export const ACTION_EXAMPLES = {
+  'inject-text': { config: { id: 'notice', layer: 'pre-step', text: '' } },
+  assembly: { target: {} },
+  decision: { phase: 'pre', decision: 'allow' },
+  'append-context': { mode: 'context', text: '' },
+  guard: { mask: { deny: [] } },
+  'sdk-strip': { mask: { deny: [] } },
+  'request-params': { patch: {} },
+  'inbox-prepend': { target: 'next-turn', text: '' },
+  'pre-step-filter': { blockPlugins: [] },
+}

package/engine/actions/guard.mjs

@@ -0,0 +1,80 @@
+import { labelOf, createMask, RUN_CODE } from './shared.mjs'
+
+export function prepareGuard(action, plugin) {
+  const label = labelOf(action)
+  const mask = createMask(action.mask ?? action, `${label}.mask`, plugin)
+  const includeSubagents = action.includeSubagents === true
+  const reasonFor = (toolName) => String(action.reason ?? `${label}: tool ${JSON.stringify(toolName)} is denied by action`)
+
+  return (_ctx, { warnOnce, on, collect }) => {
+    /** session -> { ctx, disposers }：同一 agent.ctx 只注册一次，重绑后按新 ctx 重注册。 */
+    const appliedBySession = new WeakMap()
+    const states = new Set()
+    const releaseState = (state) => {
+      states.delete(state)
+      for (const dispose of state.disposers.splice(0)) {
+        try { dispose() } catch { /* 释放失败不得反过来打断卸载 */ }
+      }
+    }
+    const releaseAll = () => { for (const state of [...states]) releaseState(state) }
+
+    const applyTo = (agent) => {
+      const session = agent?.session
+      const scoped = agent?.ctx
+      if (session === undefined || scoped === undefined) return
+      // 受众不在本动作的裁决面内就不注册（子代理的 guard 由它自己的 assembly 决定；
+      // 万一父 guard 经 scope 链被走到，guard 体内的同一道受众判定仍然放行）。
+      const depth = session.header?.delegationDepth ?? 0
+      if (depth > 0 ? !includeSubagents : action.audience === 'subagent') return
+      const existing = appliedBySession.get(session)
+      if (existing !== undefined) {
+        // 预设切换/重绑会换掉 agent.ctx：旧 scope 的 guard 随旧 scope 失效，必须重注册。
+        if (existing.ctx === scoped) return
+        releaseState(existing)
+        appliedBySession.delete(session)
+      }
+      const tools = scoped.tools
+      if (tools === undefined || typeof tools.guard !== 'function') {
+        warnOnce(`${plugin}: guard action ${label} found no agent-scoped tools service — execution guard not registered`)
+        return
+      }
+      const state = { ctx: scoped, disposers: [] }
+      states.add(state)
+      appliedBySession.set(session, state)
+      const denials = {
+        ...(mask.allow !== undefined ? { allow: [...mask.allow] } : {}),
+        ...(mask.deny !== undefined ? { deny: [...mask.deny] } : {}),
+      }
+      // restrict 沿父 scope 链传播且不识别受众；只在子代理也受限时复用。
+      if (includeSubagents && typeof tools.restrict === 'function') {
+        try {
+          const dispose = tools.restrict(denials)
+          if (typeof dispose === 'function') state.disposers.push(dispose)
+        } catch (error) {
+          // restrict 只收继承面：本层/晚到工具不在它的可限制集合里，交给 guard 裁决。
+          warnOnce(`${plugin}: guard action ${label} restrict skipped (own-layer/late tools stay covered by the guard): ${String(error?.message ?? error)}`)
+        }
+      }
+      state.disposers.push(tools.guard((exec) => {
+        const toolName = exec?.name
+        if (toolName === RUN_CODE || typeof toolName !== 'string' || toolName.length === 0) return undefined
+        const depth = exec?.agent?.session?.header?.delegationDepth ?? 0
+        // 主子代理隔离：scope 注册之外再按受众判定一次（子代理 scope 可能挂在父链上）。
+        if (depth > 0 ? !includeSubagents : action.audience === 'subagent') return undefined
+        return mask.blocks(toolName) ? reasonFor(toolName) : undefined
+      }))
+    }
+
+    collect(releaseAll)
+    collect(on('system-prompt/assemble', async (assembly, context, next) => {
+      // Downstream errors propagate untouched; only this action's own logic is guarded.
+      const assembled = await next()
+      try {
+        applyTo(context?.agent)
+      } catch (error) {
+        warnOnce(`${plugin}: guard action ${label} failed to register: ${String(error?.message ?? error)}`)
+      }
+      return assembled
+    }))
+  }
+}

package/engine/actions/inbox-prepend.mjs

@@ -0,0 +1,37 @@
+import { labelOf, requireString } from './shared.mjs'
+import { newMessageId } from '../shared.mjs'
+
+export function prepareInboxPrepend(action, plugin) {
+  const label = labelOf(action)
+  const target = action.target ?? 'next-turn'
+  if (target !== 'next-turn' && target !== 'next-step') {
+    throw new TypeError(`${plugin}: ${label}.target must be "next-turn" or "next-step"`)
+  }
+  const text = requireString(action.text, `${label}.text`, plugin)
+  // 空正文 = 没有可插入的内容（empty 情形）：不注册，而不是插入一条空消息。
+  if (text.length === 0) return
+  return (_ctx, { warnOnce, on, collect, take }) => collect(on('agent/inbox/inserted', ({ agent, message } = {}) => {
+    try {
+      // 无 session 的 agent 不锚定（与原 `anchor-turn` 的守卫逐条对齐；声明侧见
+      // `test/engine/declarations/anchor-turn.yml` 的 session 谓词）：锚定是**会话**
+      // 首轮语义，没有会话就没有「首轮」；缺这条会让匿名/临时 agent 也被插一条合成消息
+      // （对拍实测：声明路径多插 2 条）。
+      if (agent?.session === undefined) return
+      if (typeof agent?.inbox?.prepend !== 'function') return
+      // v4 起插件来源的 kind 是生产者名（`plugin:<name>`）；两种形态一起认，否则换代后
+      // 「插件来源消息永不再次前置」这道防自触发的闸会静默失效。
+      if (typeof message?.source?.kind === 'string' && message.source.kind.startsWith('plugin:')) return
+      if (message?.source?.kind === 'plugin') return
+      if (typeof action.match === 'function' && action.match(agent, message) !== true) return
+      if (!take({ agent })) return
+      agent.inbox.prepend(target, {
+        id: newMessageId(`action-${label}`),
+        role: 'user',
+        content: [{ type: 'text', text }],
+        source: { kind: `plugin:${label}`, plugin: label, form: 'notice', summary: `${label} ${target}` },
+      })
+    } catch (error) {
+      warnOnce(`${plugin}: inbox-prepend action ${label} failed: ${String(error?.message ?? error)}`)
+    }
+  }))
+}

package/engine/actions/index.mjs

@@ -0,0 +1,100 @@
+import { createWarnOnce, keepDisposer } from '../shared.mjs'
+import { labelOf } from './shared.mjs'
+import { ACTION_KINDS } from './catalog.mjs'
+import { actionSupportsWhen, actionExecutionPoint, createTurnBudget, withWhen, channelBinder } from './registration.mjs'
+import { prepareInjectText } from './inject-text.mjs'
+import { prepareAssembly } from './assembly.mjs'
+import { prepareDecision } from './decision.mjs'
+import { prepareAppendContext } from './append-context.mjs'
+import { prepareGuard } from './guard.mjs'
+import { prepareSdkStrip } from './sdk-strip.mjs'
+import { prepareRequestParams } from './request-params.mjs'
+import { prepareInboxPrepend } from './inbox-prepend.mjs'
+import { preparePreStepFilter } from './pre-step-filter.mjs'
+export { ACTION_KINDS, ACTION_DEGRADE } from './catalog.mjs'
+export { actionSupportsWhen, actionExecutionPoint } from './registration.mjs'
+const DEFAULT_PLUGIN = 'prompt-actions'
+
+const PREPARERS = {
+  'inject-text': prepareInjectText,
+  assembly: prepareAssembly,
+  decision: prepareDecision,
+  'append-context': prepareAppendContext,
+  guard: prepareGuard,
+  'sdk-strip': prepareSdkStrip,
+  'request-params': prepareRequestParams,
+  'inbox-prepend': prepareInboxPrepend,
+  'pre-step-filter': preparePreStepFilter,
+}
+
+/**
+ * 注入整批编译与动作准备共用选项校验；不装配服务，也不单独编译注入叶子。
+ *
+ * @param action `{ kind, id?, ... }`，形状见 {@link ACTION_KINDS}。
+ * @param options.plugin 调用方插件名（错误消息 / 告警 / disposer 标签），与
+ *   `mountTriggers(ctx, declarations, { plugin })` 同一约定；缺省 `prompt-actions`。
+ * @param options.warnOnce 复用宿主模块的告警器；缺省为本文件自己的 warnOnce。
+ * @param options.when 可选判定：不命中（非 `true`）即放行下游、不执行本动作。仅对
+ *   {@link ON_REGISTERED_KINDS} 里的动作有效；对 `inject-text` / `guard` 传它会挂载期报错
+ *   （那两类不走 `on(...)`，静默忽略就是"配了没效果"）。
+ * @param options.prepend 让本动作落在宿主 waterfall 的**最外层**（否决型动作需要）。同样只对
+ *   `ON_REGISTERED_KINDS` 有效；它表达的是**位置**，不承担声明之间的排序。
+ * @param options.promptConfigOptions 宿主提供的 createPromptConfigs 选项（模板基准和策略目录），不从动作数据读取。
+ * @returns 已校验的动作类别与调用方插件名。
+ */
+export function validateActionOptions(action, options = {}) {
+  const kind = action?.kind
+  const plugin = typeof options.plugin === 'string' && options.plugin.length > 0 ? options.plugin : DEFAULT_PLUGIN
+  if (!Object.hasOwn(ACTION_KINDS, kind)) {
+    throw new TypeError(`${plugin}: unknown action kind ${JSON.stringify(kind)} — known kinds: ${Object.keys(ACTION_KINDS).join(', ')}`)
+  }
+  if (!actionSupportsWhen(kind) && (options.when !== undefined || options.prepend === true)) {
+    const feature = options.when !== undefined ? 'a when predicate' : 'prepend'
+    throw new TypeError(`${plugin}: action ${kind} does not support ${feature} — 它不经 on(...) 注册（inject-text 注册层、guard 注册 agent scope 的最终拒绝）`)
+  }
+  // `maxPerTurn` 与 `when` 的支持面相同：都只对经 `on(...)` 注册的动作有效。
+  if (!actionSupportsWhen(kind) && action?.maxPerTurn !== undefined) {
+    throw new TypeError(`${plugin}: action ${kind} does not support maxPerTurn — 它不经 on(...) 注册`)
+  }
+  const max = action?.maxPerTurn
+  if (max !== undefined && (!Number.isSafeInteger(max) || max <= 0)) {
+    throw new TypeError(`${labelOf(action)}.maxPerTurn must be a positive integer`)
+  }
+  return { kind, plugin }
+}
+
+/** 纯准备阶段返回真实 ctx 的绑定函数；options.on 可由统一规则收集实际执行点。 */
+export function prepareAction(action, options = {}) {
+  const { kind, plugin } = validateActionOptions(action, options)
+  const max = action?.maxPerTurn
+  const bind = PREPARERS[kind](action, plugin, options.promptConfigOptions)
+  const phase = actionSupportsWhen(kind) ? actionExecutionPoint(action).phase : undefined
+  return (ctx) => {
+    const warnOnce = options.warnOnce ?? createWarnOnce(ctx, plugin)
+    const budget = createTurnBudget(max)
+    const on = withWhen(options.on ?? channelBinder(ctx, kind, plugin, options.prepend === true), options.when, warnOnce, phase)
+    const disposers = []
+    const collect = (disposer) => { if (typeof disposer === 'function') disposers.push(disposer) }
+    // 每轮预算的轮边界由 durable 事件驱动（与谓词的 observe 同一事件源，但**独立记账**：
+    // 预算是「本动作生效次数」，不是 durable 事件计数）。
+    if (budget !== undefined) collect(ctx.on('session/event', (session, event) => budget.observe(session, event)))
+    const take = (subject) => budget?.take(subject) ?? true
+    bind?.(ctx, { warnOnce, on, collect, take })
+    const dispose = () => {
+      for (const release of disposers.splice(0)) {
+        try {
+          release()
+        } catch {
+          // 释放失败不得反过来打断卸载流程。
+        }
+      }
+    }
+    keepDisposer(ctx, dispose, `${plugin}: action ${labelOf(action)}`)
+    return dispose
+  }
+}
+
+/** 校验后把动作接到其合法通道，返回释放函数。 */
+export function registerAction(ctx, action, options = {}) {
+  return prepareAction(action, options)(ctx)
+}

package/engine/actions/inject-text.mjs

@@ -0,0 +1,22 @@
+import { applyPromptConfigs } from '../executor.mjs'
+import { wireLayers } from '../layers.mjs'
+import { createPromptConfigs } from '../schema.mjs'
+
+export function prepareInjectText(action, plugin, promptConfigOptions) {
+  const source = action.config
+  if (source === null || typeof source !== 'object' || Array.isArray(source)) {
+    throw new TypeError(`${plugin}: inject-text requires a config object (与 promptConfigs 同形状的提示词配置)`)
+  }
+  if (typeof source.layer !== 'string' || source.layer.length === 0) {
+    throw new TypeError(`${plugin}: inject-text config.layer is required (九层之一)`)
+  }
+  // 纯声明复用提示词配置编译；函数仅来自已有编程接口，不写回可序列化声明。
+  const config = typeof source.resolve === 'function' ? source : createPromptConfigs([source], promptConfigOptions)[0]
+  return (ctx, { warnOnce, collect }) => {
+    if (config.layer === 'pre-step') {
+      collect(applyPromptConfigs(ctx, [config], action.options ?? {}))
+      return
+    }
+    collect(wireLayers(ctx, [config], warnOnce))
+  }
+}