dsh-plugin-prompt-tool 0.8.1 → 2.0.0

package/engine/conditions/subject.mjs

@@ -0,0 +1,121 @@
+import { lastAssistantText, subagentTextOf, toolArgsText, userMessagesText } from '../condition.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 事实。
+ *
+ * 官方 `subagent/start`、`subagent/end` 的载荷只有 `runId/provider/id/local`；
+ * `wireSubagentEvents` 是在 handler 里才把 child 挂上 frame 的，而 `ruleMatches`
+ * 在 handler **之前**执行。结果是 `scope.modelScope`（availability 要求 model 为非空
+ * 字符串）与 `scope.audience`（要求 session 可达）在子代理两层恒判 UNAVAILABLE——UI 上
+ * 配了却永远不命中，正是 schema 注释要避免的「配了没效果也不报错」。
+ *
+ * 这里在**判定前**用事件里的 `id` 反查 agent 补齐同样的事实。取不到时不写键：判定
+ * 退回 UNAVAILABLE（fail-closed），不得乐观放行。
+ */
+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
+}
+
+/**
+ * 把事件参数表归一为谓词载荷。
+ *
+ * `args` 传的是**去掉 `next` 之后的参数表**（无 `next` 的 emit/serial 通道原样传）。
+ * 未知通道回落到「第一个实参」（= 归一化之前的旧行为）并**告警一次**——不静默丢弃，
+ * 否则新增通道会悄悄失去判定能力；也不抛错，判定期抛错会打断会话。
+ *
+ * @param {string} channel 事件名
+ * @param {unknown[]} args 去掉 next 的参数表
+ * @param {Function} [warn] 告警回调（缺省静默）
+ * @param {unknown} [ctx] 判定期服务入口（目前只被子代理事件的 agent 反查使用）
+ * @returns {unknown} 谓词载荷
+ */
+export function subjectOf(channel, args, warn, ctx) {
+  // 第一个实参的字段**原样保留**在载荷顶层：旧形态（如 `agent/turn-stopping` 的
+  // `{ 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`，因此 `when: { 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) {
+    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, ...pick(args), ...text, [SUBJECT_MARK]: true, channel, args }
+}
+
+/**
+ * 从载荷取 agent：**归一化载荷**读 `agent`（`subjectOf` 的标记为凭）；**旧形态**
+ * （载荷本身就是 agent——手写调用方与既有测试都这样传）原样返回。
+ */
+export function agentOf(payload) {
+  if (payload === null || typeof payload !== 'object') return undefined
+  return payload[SUBJECT_MARK] === true ? payload.agent : payload
+}
+
+/**
+ * 从载荷取 session：归一化载荷走 `session` → `agent.session`；旧形态走
+ * `session` → 载荷自身。取不到时返回原载荷——`sessionEvents` 对无 `snapshotEvents`
+ * 的对象返回空，语义是「无事件」，与归一化之前逐例一致。
+ */
+export function sessionOf(payload) {
+  if (payload === null || typeof payload !== 'object') return payload
+  if (payload[SUBJECT_MARK] !== true) return payload.session ?? payload
+  return payload.session ?? payload.agent?.session
+}

package/engine/conditions/text.mjs

@@ -0,0 +1,44 @@
+import { MATCH_LOGIC, createAnchorMatcher } from '../anchor-match.mjs'
+import { subjectTextOf } from '../condition.mjs'
+import { keyList } from './values.mjs'
+import { conditionInputAvailable, UNAVAILABLE } from './availability.mjs'
+const MATCH_FLAGS = ['caseSensitive', 'wholeWords', 'useRegex', 'stWords']
+const MATCH_MODES = ['scan', 'prefix']
+
+export function createTextPredicate(options = {}) {
+  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 logic = options.logic ?? MATCH_LOGIC.ANY
+  if (!Object.values(MATCH_LOGIC).includes(logic)) {
+    throw new TypeError(`predicates: logic must be one of ${Object.values(MATCH_LOGIC).join(', ')}`)
+  }
+  const mode = options.mode ?? 'scan'
+  if (!MATCH_MODES.includes(mode)) {
+    throw new TypeError(`predicates: mode must be one of ${MATCH_MODES.join(', ')}`)
+  }
+  for (const field of MATCH_FLAGS) {
+    if (options[field] !== undefined && typeof options[field] !== 'boolean') {
+      throw new TypeError(`predicates: ${field} must be a boolean when present`)
+    }
+  }
+  // 与 anchor-match 逐例等价的关键：匹配器就是 anchor-match 的匹配器，本层不加也不减语义。
+  const matcher = createAnchorMatcher({
+    keys,
+    secondaryKeys,
+    caseSensitive: options.caseSensitive === true,
+    wholeWords: options.wholeWords === true,
+    useRegex: options.useRegex,
+    logic,
+    mode,
+    stWords: options.stWords === true,
+  })
+  const subject = options.subject
+  const predicate = (payload) => conditionInputAvailable('text', options, payload)
+    ? matcher.scan(typeof payload === 'string' ? payload : subjectTextOf(subject, payload)).active === true
+    : UNAVAILABLE
+  predicate.kind = 'text'
+  return predicate
+}

package/engine/conditions/values.mjs

@@ -0,0 +1,32 @@
+export function optionalBoolean(value, field, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') throw new TypeError(`predicates: ${field} must be a boolean`)
+  return value
+}
+
+/** 键集合归一化：非字符串数组 / 非数组一律 fail loud；空白键丢弃。 */
+export function keyList(value, field) {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new TypeError(`predicates: ${field} must be an array of strings when present`)
+  }
+  return value.map((item) => item.trim()).filter((item) => item.length > 0)
+}
+
+/** 名称集合：与 tool-filter 的 nameSet 同严格度（空串不是合法名称）。 */
+export function nameList(value, field) {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    throw new TypeError(`predicates: ${field} must be an array of non-empty strings`)
+  }
+  return [...new Set(value)]
+}
+
+/** 计数上下限：缺省 = 不设该侧；非安全非负整数一律 fail loud。 */
+export function boundOf(value, field) {
+  if (value === undefined) return undefined
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`predicates: count ${field} must be an integer >= 0`)
+  }
+  return value
+}

package/engine/dev-tool-search.mjs

@@ -0,0 +1,213 @@
+/**
+ * 工具面的按需发现与解锁。
+ *
+ * 为什么：工具面实测 **156 个、工具描述合计 46894 字符**（≈12K token，每个请求都付），
+ * 而多数请求只用到其中几个。收窄成常驻核心集之后，本工具是唯一的发现入口。
+ *
+ * 两个动作合一：
+ *  - `query` 关键词搜索**完整装配目录**（只回名字 + 一行截断描述，不回 parameters）；
+ *  - `toolNames` 按**精确名**解锁。解锁名写进本次 `tool/call` 的持久参数，
+ *    `assembly.target.tools.allowFrom` 从那里读回 → 下次请求起生效，且跨压缩保留。
+ *
+ * **能力摘要来自运行时截获，不手工维护**（2026-10-05 用户指出）：空查询时按前缀把
+ * `ctx.tools.schemas()` 的可见目录折叠成分组摘要（`mcp__github__* ×46`，实测 433 字符
+ * 覆盖全部 156 个工具）。此前的实现写死一份 UNLOCKABLE_INDEX——工具增删就要改代码，
+ * 名字写错还会让模型照着错名字解锁（那份实现甚至需要一条专门测试来防错名）。
+ * 官方注册表只投影 name/description（无分组字段），所以分组只能按前缀在本地折叠。
+ *
+ * 与原 `dev-tool-search.mjs` 的两处修正照搬：
+ *  1. 匹配是**打分**而非 AND 过滤——长自然语言查询（"file edit write replace"）在
+ *     AND 口径下命中零个，等于白搜。现在精确名优先，其次按命中 token 数排序。
+ *  2. 描述里显式教解锁路径（"搜索为空 ≠ 工具不存在"）——实测模型只会搜、不会传
+ *     toolNames，于是收窄后永远拿不到工具。
+ */
+export const name = 'dev-tool-search'
+
+/** 工具注册表必须先于本工具存在（同 skill-search 的 inject 纪律）。 */
+export const inject = ['tools']
+
+/** 单次搜索结果上限：再多就该让模型收窄关键词。 */
+export const MAX_RESULTS = 25
+
+/** 一行描述在结果里的截断长度。 */
+const DESC_LIMIT = 90
+
+/** 空查询摘要里最多列出的分组数，超出则并入「其他」。 */
+const MAX_GROUPS = 24
+
+/** 常驻核心集：由工具面收窄模板声明，这里只在描述里如实告知模型。 */
+const RESIDENT = ['pwsh', 'read', 'write', 'edit', 'glob', 'grep', 'todo_write', 'skill_search', 'skill_load']
+
+/** 零依赖的最小 JSON schema 编译器（与 skill-search 同构）。 */
+function toJsonSchema(spec) {
+  const properties = {}
+  const required = []
+  for (const [key, meta] of Object.entries(spec || {})) {
+    const prop = { type: meta.type }
+    if (meta.description) prop.description = meta.description
+    if (meta.items) prop.items = meta.items
+    properties[key] = prop
+    if (meta.required) required.push(key)
+  }
+  return { type: 'object', properties, required, additionalProperties: false }
+}
+
+/**
+ * 能力索引：常驻核心集（pwsh / read / write / edit / glob / grep / todo_write /
+ * skill_search / skill_load）覆盖不到的能力。名字全部取自实测工具面。
+ */
+
+/** 把查询切成小写 token（Unicode 字母数字与下划线连字符，与 skill-search 同口径）。 */
+export function queryTokens(query) {
+  return (typeof query === 'string' ? query : '').toLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(Boolean)
+}
+
+/**
+ * 一个工具名的分组键：MCP 工具折到服务级（`mcp__github__*`），其余折到首个下划线段
+ * （`task_board_create` → `task_*`），无下划线的单名自成一组。
+ */
+export function groupKeyOf(name) {
+  if (typeof name !== 'string' || name.length === 0) return undefined
+  if (name.startsWith('mcp__')) {
+    const parts = name.split('__')
+    return parts.length >= 2 ? `${parts[0]}__${parts[1]}__*` : `${name}*`
+  }
+  const cut = name.indexOf('_')
+  return cut <= 0 ? name : `${name.slice(0, cut)}_*`
+}
+
+/**
+ * 从**运行时目录**折叠出分组摘要——这是替代手工能力索引的唯一来源。
+ * 名字、分组、数量全部来自 `ctx.tools.schemas()`，工具增删不需要改本模块的代码。
+ * 超过 MAX_GROUPS 个分组时，把长尾并成一行「其他」而不是无限增长。
+ */
+export function summarizeCatalog(schemas) {
+  const counts = new Map()
+  for (const schema of Array.isArray(schemas) ? schemas : []) {
+    const key = groupKeyOf(schema?.name)
+    if (key === undefined) continue
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  const sorted = [...counts.entries()].sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]))
+  const head = sorted.slice(0, MAX_GROUPS)
+  const tail = sorted.slice(MAX_GROUPS)
+  const parts = head.map(([key, count]) => `${key}(${count})`)
+  if (tail.length > 0) parts.push(`其他 ${tail.length} 组(${tail.reduce((sum, [, n]) => sum + n, 0)})`)
+  return { total: [...counts.values()].reduce((sum, n) => sum + n, 0), text: parts.join(' ') }
+}
+
+/**
+ * 对目录打分排序（纯函数，可单测）：
+ * 精确名命中排最前，其次按命中 token 数降序，同分按名字字典序。
+ * `wanted` 为空时返回空数组——调用方据此区分「没给查询」与「没搜到」。
+ */
+export function scoreTools(schemas, wanted) {
+  if (!Array.isArray(schemas) || wanted.length === 0) return []
+  return schemas
+    .map((schema) => {
+      const name = typeof schema?.name === 'string' ? schema.name : ''
+      const haystack = `${name} ${schema?.description ?? ''}`.toLowerCase()
+      let score = 0
+      for (const token of wanted) if (haystack.includes(token)) score += 1
+      return { schema, name, score, exact: wanted.includes(name.toLowerCase()) }
+    })
+    .filter((entry) => entry.name.length > 0 && (entry.exact || entry.score >= 1))
+    .sort((a, b) => (b.exact - a.exact) || (b.score - a.score) || a.name.localeCompare(b.name))
+}
+
+/** 解锁名单归一：只留非空字符串，去重保序。 */
+export function unlockNames(value) {
+  if (!Array.isArray(value)) return []
+  const seen = new Set()
+  for (const item of value) {
+    if (typeof item !== 'string') continue
+    const name = item.trim()
+    if (name.length > 0) seen.add(name)
+  }
+  return [...seen]
+}
+
+/** 把目录搜索结果渲染成给模型的文本（带截断提示与解锁引导）。 */
+export function renderMatches(scored, query) {
+  const lines = []
+  const matches = scored.slice(0, MAX_RESULTS)
+  if (matches.length === 0) {
+    lines.push(
+      `No tools match "${query}". An empty result only means no tool matched your keywords — if you need a specific tool, unlock it directly by exact name, e.g. dev_tool_search({"toolNames":["web_search"]}).`,
+    )
+    return lines
+  }
+  lines.push(`Matching tools (${matches.length}${scored.length > MAX_RESULTS ? ` of ${scored.length}` : ''}):`)
+  for (const { schema, name, exact } of matches) {
+    const desc = String(schema?.description ?? '').split('\n')[0].slice(0, DESC_LIMIT)
+    lines.push(`- ${name}${exact ? ' (exact)' : ''}: ${desc}`)
+  }
+  if (scored.length > MAX_RESULTS) {
+    lines.push(`(truncated at ${MAX_RESULTS} — add tokens to narrow the query)`)
+  }
+  lines.push('Unlock with dev_tool_search({"toolNames": ["<exact name>"]}).')
+  return lines
+}
+
+/** 注册模型可见的 `dev_tool_search`。 */
+export function apply(ctx) {
+  ctx.tools.register({
+    name: 'dev_tool_search',
+    description: [
+      'Discover and unlock tools that are NOT currently available.',
+      '',
+      `This session starts with a minimal resident set: ${RESIDENT.join(', ')}. Everything else is unlocked on demand through this tool.`,
+      '',
+      'Usage:',
+      '- `query` — search the catalog by keyword (matches tool names AND descriptions, 1-2 short words work best).',
+      '- call with NO arguments — list the catalog as group counts (`<prefix>_*(count) ...`), so you can see what exists before searching.',
+      '- `toolNames` — unlock exact names. Unlocked tools appear from the NEXT request on and stay unlocked for the session.',
+      '',
+      'Example: dev_tool_search({"query":"pull request","toolNames":["mcp__github__create_pull_request"]}) — search AND unlock in one call.',
+      'IMPORTANT: an empty search result does NOT mean the tool does not exist — it only means no tool matched your keywords. Call with no arguments to see the catalog groups, then unlock by exact name.',
+    ].join('\n'),
+    parameters: toJsonSchema({
+      query: { type: 'string', required: false, description: 'search keywords (e.g. "web", "subagent", "github")' },
+      toolNames: {
+        type: 'array',
+        required: false,
+        items: { type: 'string' },
+        description: 'exact tool names to unlock for the next request',
+      },
+    }),
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } }, required: ['text'] },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const query = typeof args?.query === 'string' ? args.query.trim() : ''
+      const unlock = unlockNames(args?.toolNames)
+      const lines = []
+      // 解锁动作本身不需要任何运行时服务：引擎的 allowFrom 只读本工具的持久调用参数，
+      // 所以即便目录不可用（无 tools 服务/无 agent），解锁也必须照样回报成功。
+      if (unlock.length > 0) lines.push(`Unlocked for the next request: ${unlock.join(', ')}`)
+      if (query.length === 0 && unlock.length > 0) return { text: lines.join('\n') }
+      let schemas
+      try {
+        // 执行中的 agent 就是观察作用域：preset 工具注册在 agent scope 层，
+        // 不带 scope 的 schemas() 只看全局层，会漏掉它们。
+        schemas = ctx.tools.schemas(exec?.agent)
+      } catch (error) {
+        return { text: [...lines, `catalog search unavailable: ${String(error?.message ?? error)}`].join('\n') }
+      }
+      // 空查询 = 要目录概览。摘要由运行时目录折叠而来，不需要维护任何索引。
+      if (query.length === 0) {
+        const summary = summarizeCatalog(schemas)
+        lines.push(
+          summary.total === 0
+            ? 'The catalog is empty — nothing to unlock.'
+            : `Catalog groups (${summary.total} tools): ${summary.text}`,
+          'Search with `query`, or unlock by exact name with `toolNames`.',
+        )
+        return { text: lines.join('\n') }
+      }
+      lines.push(...renderMatches(scoreTools(schemas, queryTokens(query)), query))
+      return { text: lines.join('\n') }
+    },
+  })
+}

package/engine/executor.mjs

@@ -28,6 +28,8 @@ import { createEpochPromotion } from './compaction-epoch.mjs'
 import { wireLayers } from './layers.mjs'
 import { sessionVarsSnapshot } from './session-vars.mjs'
 import { selectStWorldBook } from './st-world-book.mjs'
+import { compareConfigSequence } from './order.mjs'
+import { ruleFrame, ruleMatches, actionMatches } from './conditions/evaluation.mjs'
 
 const name = 'prompt-config-engine'
 
@@ -65,13 +67,25 @@ function identityOf(config) {
   return config.mergeMode === 'merged' ? mergedIdentity(config) : config.identity.value
 }
 
+/**
+ * 消息来源的插件身份（去重身份）。v4 起 `source.kind` 是生产者名（`plugin:<name>`），
+ * `source.plugin` 只作为旧日志字段保留——两条通道都要认，否则去重记账会在格式换代后静默失效。
+ */
+function pluginIdentityOf(source) {
+  if (source === null || typeof source !== 'object') return undefined
+  if (typeof source.plugin === 'string' && source.plugin.length > 0) return source.plugin
+  return typeof source.kind === 'string' && source.kind.startsWith('plugin:')
+    ? source.kind.slice('plugin:'.length)
+    : undefined
+}
+
 function hasInjected(config, session) {
   const value = identityOf(config)
   return sessionEvents(session).some((event) => {
     const message = eventMessage(event)
     // 双通道去重：kind（外来/第三方消息，如 context-gate 的 instruction-hint）或
     // plugin（本引擎注入的命名空间，merged 组用 merged:<position>）。
-    return message?.source?.kind === config.sourceKind || message?.source?.plugin === value
+    return message?.source?.kind === config.sourceKind || pluginIdentityOf(message?.source) === value
   })
 }
 
@@ -79,7 +93,7 @@ function hasInjected(config, session) {
 function hasInBatch(config, messages) {
   const value = identityOf(config)
   return messages.some((message) =>
-    message?.source?.kind === config.sourceKind || message?.source?.plugin === value)
+    message?.source?.kind === config.sourceKind || pluginIdentityOf(message?.source) === value)
 }
 
 /**
@@ -112,6 +126,10 @@ export function confirmDelivered(memo, session, event) {
     if (typeof value !== 'string' || value.length === 0) continue
     deliveredSessions(memo, `${field}:${value}`).add(session.id)
   }
+  // v4 起生产者身份挂在 kind（`plugin:<name>`），旧日志才有 plugin 字段；
+  // 两种形态都补记到 plugin: 账本，alreadyDelivered 的 `confirmed('plugin', …)` 才不会漏。
+  const plugin = pluginIdentityOf(source)
+  if (plugin !== undefined && source.plugin === undefined) deliveredSessions(memo, `plugin:${plugin}`).add(session.id)
 }
 
 /** dedupe=session：本会话是否已有该身份的已确认投递（快路径 + 持久事件真相）。 */
@@ -150,7 +168,9 @@ function buildMessage(config, resolved, warnOnce) {
   const base = resolved.source !== null && typeof resolved.source === 'object'
     ? resolved.source
     : {
-        kind: config.sourceKind,
+        // v4 要求 kind 是**生产者名**：声明了 sourceKind 就用它，否则用与 pluginMessage 同一形状的
+        // `plugin:<身份>`。裸 kind（undefined / 'plugin'）都会被 codec 拒绝，历史走的是同一个坑。
+        kind: typeof config.sourceKind === 'string' && config.sourceKind.length > 0 ? config.sourceKind : `plugin:${sourceValue}`,
         plugin: sourceValue,
         ...(typeof config.form === 'string' ? { form: config.form } : {}),
         ...(typeof config.summary === 'string' && config.summary.length > 0 ? { summary: config.summary } : {}),
@@ -177,6 +197,27 @@ function buildMessage(config, resolved, warnOnce) {
  * @returns 注入后的 decision；reject、缺 agent/session、全部跳过或异常时原样返回。
  */
 export async function runPreStepBatch(options) {
+  const initialFrame = options.ruleFrame ?? ruleFrame('agent/pre-step', [{ agent: options.agent, messages: options.decision?.messages ?? [] }], options.warnOnce, options.ctx)
+  if (!options.ruleActions?.length) return runPromptConfigBatch({ ...options, ruleFrame: initialFrame })
+  const entries = [...options.configs.map(config => ({ ...config, config })), ...options.ruleActions].sort(compareConfigSequence)
+  let decision = options.decision
+  if (decision?.kind === 'reject') return decision
+  let pending = []
+  const placement = { beforeAll: new Set(), afterUser: new Set() }
+  const flush = async () => {
+    if (pending.length) decision = await runPromptConfigBatch({ ...options, decision, configs: pending, ruleFrame: initialFrame, placement })
+    pending = []
+  }
+  for (const entry of entries) {
+    if (entry.config) { pending.push(entry.config); continue }
+    await flush()
+    if (ruleMatches(entry.rule, initialFrame)) decision = await entry.handler(options.payload ?? initialFrame.args[0], () => decision, initialFrame)
+  }
+  await flush()
+  return decision
+}
+
+async function runPromptConfigBatch(options) {
   const { ctx, agent, decision, configs, promotion, memo, warnOnce } = options
   if (decision === null || typeof decision !== 'object') return decision
   if (decision.kind === 'reject') return decision
@@ -203,6 +244,7 @@ export async function runPreStepBatch(options) {
       && (config.promotion !== 'main' || main.status(agent).promoted)
       && (config.promotion !== 'include-subagents' || withSubagents.status(agent).promoted)
       && conditionHit(config, { userText })
+      && actionMatches(config, options.ruleFrame)
     const qualifiedConfigs = configs.filter(qualified)
     // 协调器为绑定来源 ctx 会复制 config；renderSt 函数身份在副本间保持不变。
     const eligible = new Set(qualifiedConfigs.map(config => config.renderSt))
@@ -253,28 +295,23 @@ export async function runPreStepBatch(options) {
       }
     }
 
-    // order 升序(同值保持声明顺序):决定拼接顺序与同位置插入顺序。
-    due.sort((a, b) => a.config.order - b.config.order)
+    // 模块来源按序号；独立调用仍按 order，同值保留稳定身份顺序。
+    due.sort((a, b) => compareConfigSequence(a.config, b.config))
 
-    // merged 模式的多条提示词配置在首条配置的位置合并为一条消息;
-    // 文本按内容块拼接,source 身份改用 merged:<position> 以保持持久幂等。
+    // 每个落位内只合并同来源的连续 merged 卡；其他落位不会穿插在本落位的输出中。
+    // source 仍用既有 merged:<position>，不因分段或排序改写持久去重身份。
     const orderedGroups = []
-    const groupIndex = new Map()
+    const lastAtPosition = new Map()
     for (const entry of due) {
-      const group = entry.config.mergeMode === 'merged'
-        ? mergedIdentity(entry.config)
-        : undefined
-      if (group === undefined) {
-        orderedGroups.push([entry])
-        continue
-      }
-      let index = groupIndex.get(group)
-      if (index === undefined) {
-        index = orderedGroups.length
-        groupIndex.set(group, index)
-        orderedGroups.push([])
+      const previous = lastAtPosition.get(entry.config.position)
+      const base = previous?.[0].config
+      if (entry.config.mergeMode === 'merged' && base?.mergeMode === 'merged'
+        && entry.config.sourceModuleId === base.sourceModuleId) previous.push(entry)
+      else {
+        const group = [entry]
+        orderedGroups.push(group)
+        lastAtPosition.set(entry.config.position, group)
       }
-      orderedGroups[index].push(entry)
     }
 
     const planned = []
@@ -314,13 +351,18 @@ export async function runPreStepBatch(options) {
     const afterUser = planned.filter((item) => item.position !== 'before-all' && item.position !== 'after-all')
     const afterAll = planned.filter((item) => item.position === 'after-all')
     if (beforeAll.length > 0) {
-      messages.unshift(...beforeAll.map((item) => item.message))
+      // 混合动作把注入切成多批；继续排在此前仍存活的同位置消息之后。
+      const index = options.placement === undefined ? 0 : messages.findLastIndex(message => options.placement.beforeAll.has(message)) + 1
+      messages.splice(index, 0, ...beforeAll.map((item) => item.message))
+      for (const item of beforeAll) options.placement?.beforeAll.add(item.message)
       for (const item of beforeAll) markGroup(item.group)
       changed = true
     }
     const userIndex = messages.findIndex((item) => item?.source?.kind === 'user')
     if (afterUser.length > 0 && userIndex >= 0) {
-      messages.splice(userIndex + 1, 0, ...afterUser.map((item) => item.message))
+      const last = options.placement === undefined ? -1 : messages.findLastIndex(message => options.placement.afterUser.has(message))
+      messages.splice(Math.max(userIndex, last) + 1, 0, ...afterUser.map((item) => item.message))
+      for (const item of afterUser) options.placement?.afterUser.add(item.message)
       for (const item of afterUser) markGroup(item.group)
       changed = true
     }
@@ -345,15 +387,10 @@ export async function runPreStepBatch(options) {
  * @param options.officialInstructions 本 mount 的组合是否仍挂着官方指令加载行
  *   (负责人冲突事实;协调器据此拒绝同时注入文件正文)。
  */
-export function applyPromptConfigs(ctx, configs, options = {}) {
+function effectivePromptConfigs(configs) {
   const list = configs.filter((config) => config !== undefined && config !== null)
-  const sourceId = typeof options.sourceId === 'string' && options.sourceId.length > 0
-    ? options.sourceId
-    : `preset:${String(list[0]?.id ?? 'unknown')}`
-  // 空 mount 同样保留接管监听：装配事实与协调器迟到/HMR 不依赖是否有预设卡。
-  // 互斥组:同一 group 且 exclusive=true 时,只保留排序后第一个 enabled 提示词配置。
   const claimedGroups = new Set()
-  const effectiveList = list.filter((config) => {
+  return list.filter((config) => {
     if (config.enabled === false) return false
     if (config.group !== undefined && config.exclusive === true) {
       if (claimedGroups.has(config.group)) return false
@@ -361,6 +398,27 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
     }
     return true
   })
+}
+
+/** 多模块仍各自拥有来源/互斥组；只有非 pre-step 层汇总接线，避免模块块状执行。 */
+export function applyPromptConfigSources(ctx, sources, options = {}) {
+  const selected = sources.map(source => ({ ...source, configs: effectivePromptConfigs(source.configs) }))
+  const releases = selected.map(source => applyPromptConfigs(ctx, source.configs, { ...options, ...source, layers: false }))
+  const releaseLayers = options.layers === false ? () => {} : wireLayers(ctx, selected.flatMap(source => source.configs)
+    .filter(config => config.layer !== 'pre-step'), createWarnOnce(ctx, name))
+  return () => {
+    for (const release of releases) release()
+    releaseLayers()
+  }
+}
+
+export function applyPromptConfigs(ctx, configs, options = {}) {
+  const list = configs.filter((config) => config !== undefined && config !== null)
+  const sourceId = typeof options.sourceId === 'string' && options.sourceId.length > 0
+    ? options.sourceId
+    : `preset:${String(list[0]?.id ?? 'unknown')}`
+  // 互斥组仍在本来源内筛选；空来源也保留协调器迟到/HMR 接管。
+  const effectiveList = effectivePromptConfigs(list)
   const injectedMemo = new Map()
   const main = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: false })
   const withSubagents = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: true })
@@ -376,6 +434,7 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
   const promotion = { main, withSubagents }
   const source = {
     configs: effectiveList,
+    ruleActions: options.ruleActions ?? [],
     officialInstructions: options.officialInstructions === true,
   }
   /** 已交给协调器的注册(仅管理路径非空)。 */
@@ -401,7 +460,8 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
 
   // 非 pre-step 提示词配置接入各自声明的官方层级通道(system-section /
   // runtime-context / agent-request / llm-stream / tool-pipeline)。
-  const releaseLayers = wireLayers(ctx, effectiveList.filter((config) => config.layer !== 'pre-step'), warnOnce)
+  const releaseLayers = options.layers === false ? () => {}
+    : wireLayers(ctx, effectiveList.filter((config) => config.layer !== 'pre-step'), warnOnce)
 
   // 协调器已在（正常装配顺序：插件先加载、预设后挂载）时立即登记来源；
   // 迟到/消失由下面的监听器按「先撤旧再启新」处理。
@@ -431,9 +491,11 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
     if (!active) return decision
     return runPreStepBatch({
       ctx,
+      payload,
       agent: payload?.agent,
       decision,
       configs: effectiveList,
+      ruleActions: source.ruleActions,
       promotion,
       memo: injectedMemo,
       warnOnce,