dsh-plugin-prompt-tool 0.8.0 → 1.0.0

package/engine/executor.mjs

@@ -28,6 +28,7 @@ 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'
 
 const name = 'prompt-config-engine'
 
@@ -253,28 +254,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
+      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)
       }
-      let index = groupIndex.get(group)
-      if (index === undefined) {
-        index = orderedGroups.length
-        groupIndex.set(group, index)
-        orderedGroups.push([])
-      }
-      orderedGroups[index].push(entry)
     }
 
     const planned = []
@@ -345,15 +341,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 +352,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 = 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 })
@@ -401,7 +413,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)
 
   // 协调器已在（正常装配顺序：插件先加载、预设后挂载）时立即登记来源；
   // 迟到/消失由下面的监听器按「先撤旧再启新」处理。

package/engine/instruction-hint.mjs

@@ -19,7 +19,7 @@
 import { randomUUID } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import { createEpochPromotion } from './compaction-epoch.mjs'
-import { booleanOption, createWarnOnce, parsePromoteOn, validateConfig } from './shared.mjs'
+import { booleanOption, createWarnOnce, getService, parsePromoteOn, validateConfig } from './shared.mjs'
 
 export const name = 'instruction-hint'
 
@@ -272,10 +272,14 @@ export function apply(ctx, config) {
       if (!promotion.status(agent).promoted) return decision
       if (!Array.isArray(decision.messages)) return decision
       if (agent?.session === undefined) return decision
+      const coordinator = getService(ctx, 'promptToolPreStep')
+      const messages = typeof coordinator?.filterInstructions === 'function'
+        ? coordinator.filterInstructions(agent, decision.messages)
+        : decision.messages
       // 1 换 1 的转换不能按长度判断（长度相同仍可能已转换），
       // instructionHintMessages 本身保留非目标消息，直接采用结果。
       const hintState = { instructionHinted: hasVisibleInstructionHint(agent.session) }
-      return { ...decision, messages: instructionHintMessages(decision.messages, hintState, name) }
+      return { ...decision, messages: instructionHintMessages(messages, hintState, name) }
     } catch (error) {
       // 转换失败不阻断会话：保留原消息。
       warnOnce(`${name}: instruction hint conversion failed, keeping messages: ${String((error && error.message) || error)}`)

package/engine/layers.mjs

@@ -18,6 +18,7 @@ import { KNOWN_STRATEGIES } from './schema.mjs'
 import { interpolateVariables, stripUnresolvedRefs, RUNTIME_FACTS, runtimeFactValue } from './interpolate.mjs'
 import { getSessionVar, sessionVarsSnapshot } from './session-vars.mjs'
 import { conditionHit, lastAssistantText, subagentTextOf, toolArgsText } from './condition.mjs'
+import { compareConfigSequence, compareTextPlacement } from './order.mjs'
 
 const name = 'prompt-config-engine'
 // 同一宿主会话共享投递账本，避免预设作用域重挂后重投同一次结束通知。
@@ -160,28 +161,31 @@ function officialChannelText(text, label, registry, warnOnce) {
   return result.text
 }
 
-/** 文本型层分组:merged 模式按位置分组,否则每条独立。 */
+/** 只合并排序后同来源、同官方档位和位置的连续 merged 卡，不跨过穿插段。 */
 function textLayerGroups(configs) {
-  const sorted = [...configs].sort((a, b) => a.order - b.order)
+  const sorted = [...configs].sort(compareTextPlacement)
   const groups = []
-  const index = new Map()
   for (const config of sorted) {
-    const key = config.mergeMode === 'merged' ? `merged:${config.position ?? ''}` : undefined
-    if (key === undefined) {
-      groups.push([config])
-      continue
-    }
-    let at = index.get(key)
-    if (at === undefined) {
-      at = groups.length
-      index.set(key, at)
-      groups.push([])
-    }
-    groups[at].push(config)
+    const previous = groups.at(-1)
+    const base = previous?.[0]
+    if (config.mergeMode === 'merged' && base?.mergeMode === 'merged'
+      && config.sourceModuleId === base.sourceModuleId
+      && config.position === base.position && config.order === base.order) previous.push(config)
+    else groups.push([config])
   }
   return groups
 }
 
+/** 官方同 order 按 name 排序：默认名编码安全整数序号，显式名仍由作者拥有。 */
+function textRegistrationName(config, field) {
+  const explicit = config.params?.[field]
+  if (typeof explicit === 'string' && explicit.length > 0) return explicit
+  if (config.sourceModuleId === undefined) return config.id
+  // 非负安全整数最多 16 位，跨过四位文件前缀后仍保持数值顺序。
+  const sequence = String(config.sequence).padStart(16, '0')
+  return `prompt-tool:${sequence}:${config.sourceModuleId}:${config.id}`
+}
+
 /** system-section:注册静态 system prompt 段(支持官方 {{variable}} 渲染与 merged 拼接)。 */
 function wireSystemSections(ctx, configs, registry, warnOnce) {
   const disposers = []
@@ -207,7 +211,7 @@ function wireSystemSections(ctx, configs, registry, warnOnce) {
               .join('\n\n')
         : groupText
       keepDisposer(ctx, systemPrompt.section({
-        name: typeof base.params?.sectionName === 'string' && base.params.sectionName.length > 0 ? base.params.sectionName : base.id,
+        name: textRegistrationName(base, 'sectionName'),
         order: base.order,
         text,
         ...(base.params?.complete === true ? { complete: true } : {}),
@@ -244,7 +248,7 @@ function wireRuntimeContexts(ctx, configs, registry, warnOnce) {
       const text = dynamic ? render : render()
       if (!dynamic && text.length === 0) continue
       keepDisposer(ctx, systemPrompt.context({
-        name: typeof base.params?.contextName === 'string' && base.params.contextName.length > 0 ? base.params.contextName : base.id,
+        name: textRegistrationName(base, 'contextName'),
         order: base.order,
         text,
       }), `${name}: context ${base.id}`)
@@ -255,7 +259,7 @@ function wireRuntimeContexts(ctx, configs, registry, warnOnce) {
   // 官方 provider 必须同步：先注册可渲染为空的私有变量占位，再在 waterfall 中填充。
   // 标记随官方排序/遮蔽进入本次 assembly，无会话缓存，也不依赖调用方 context 的对象身份。
   const placeholders = configs.filter(needsResolver)
-    .sort((a, b) => a.order - b.order)
+    .sort(compareTextPlacement)
   if (placeholders.length === 0) return disposers
   const slotVariable = `pt_runtime_${newMessageId('context').replace(/[^a-z0-9_]/gi, '_').toLowerCase()}`
   const slotText = `{{${slotVariable}}}`
@@ -265,7 +269,7 @@ function wireRuntimeContexts(ctx, configs, registry, warnOnce) {
   keepDisposer(ctx, systemPrompt.variable(slotVariable, () => ''), `${name}: runtime-context placeholder`)
   for (const config of placeholders) {
     try {
-      const contextName = typeof config.params?.contextName === 'string' && config.params.contextName.length > 0 ? config.params.contextName : config.id
+      const contextName = textRegistrationName(config, 'contextName')
       keepDisposer(ctx, systemPrompt.context({
         name: contextName,
         order: config.order,
@@ -337,20 +341,20 @@ export function applyAgentRequestParams(params, base) {
 
 /** agent-request:对冻结的 LlmCallConfig 做浅合并 / 整体替换 / 按值条件删键。 */
 function wireAgentRequests(ctx, configs, warnOnce) {
-  const disposers = []
-  for (const config of configs) {
-    disposers.push(ctx.on('agent/request', async (payload, next) => {
-      const base = await next()
+  if (configs.length === 0) return []
+  const ordered = configs.some(config => config.sequence !== undefined) ? configs : [...configs].reverse()
+  return [ctx.on('agent/request', async (payload, next) => {
+    let result = await next()
+    // 模块请求在 next 返回后按序合并；无文件来源的独立调用保持原回栈顺序。
+    for (const config of ordered) {
       try {
-        if (!matchesAgentScope(config, payload?.agent)) return base
-        return applyAgentRequestParams(config.params, base)
+        if (matchesAgentScope(config, payload?.agent)) result = applyAgentRequestParams(config.params, result)
       } catch (error) {
         warnOnce(`${name}: agent-request config ${config.id} failed: ${String(error?.message ?? error)}`)
-        return base
       }
-    }))
-  }
-  return disposers
+    }
+    return result
+  })]
 }
 
 /** 把流替换为提示词配置文本的最小合法 chunk 序列。 */
@@ -518,9 +522,12 @@ export function createTurnStopBudget() {
 function wireTurnStops(ctx, configs, warnOnce) {
   const disposers = []
   if (configs.length === 0) return disposers
-  const budget = createTurnStopBudget()
+  const budgets = new Map()
 
   for (const config of configs) {
+    const source = config.sourceModuleId ?? ''
+    if (!budgets.has(source)) budgets.set(source, createTurnStopBudget())
+    const budget = budgets.get(source)
     disposers.push(ctx.on('agent/turn-stopping', ({ agent, turn } = {}) => {
       try {
         const session = agent?.session
@@ -646,6 +653,7 @@ function wireSubagentEvents(ctx, configs, warnOnce) {
  *   变量注册走 keepDisposer（随 ctx fiber 释放），不在本函数的回收面内。
  */
 export function wireLayers(ctx, configs, warnOnce) {
+  configs = [...configs].sort(compareConfigSequence)
   // 官方插值两层共享一份变量注册：运行时事实按 assembly 求值，非法名走别名改写。
   const registry = registerOfficialVariables(ctx, configs.filter((config) => config.layer === 'system-section' || config.layer === 'runtime-context'), warnOnce)
   const registered = [

package/engine/order.mjs

@@ -0,0 +1,17 @@
+/** 加载器私有元数据：不进入 YAML、公共配置或客户端载荷。 */
+export const FILE_SEQUENCE = Symbol('prompt-tool:file-sequence')
+
+const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0
+
+/** 模块配置按持久序号执行；无物化来源的独立调用保留原 order 语义。 */
+export function compareConfigSequence(a, b) {
+  const difference = (a.sequence ?? a.order ?? 0) - (b.sequence ?? b.order ?? 0)
+  if (difference !== 0) return difference
+  if (a.sourceModuleId === undefined && b.sourceModuleId === undefined) return 0
+  return compareText(a.sourceModuleId ?? '', b.sourceModuleId ?? '') || compareText(a.id, b.id)
+}
+
+/** 官方文本段的定位仍由 order 决定；序号只提供同位置的稳定顺序。 */
+export function compareTextPlacement(a, b) {
+  return a.order - b.order || compareConfigSequence(a, b)
+}

package/engine/schema.mjs

@@ -9,6 +9,7 @@ import { sep } from 'node:path'
 import { parse as parseYaml } from './vendor/yaml/index.js'
 import { bindResolver } from './strategies.mjs'
 import { attachStRenderers } from './st-render.mjs'
+import { FILE_SEQUENCE, compareConfigSequence } from './order.mjs'
 import { MATCH_LOGIC, createAnchorMatcher } from './anchor-match.mjs'
 
 const name = 'prompt-config-engine'
@@ -126,11 +127,14 @@ export function loadPromptConfigFiles(dirUrl) {
   const specs = []
   for (const fileName of promptConfigFileNames(entries)) {
     const raw = readFileSync(new URL(fileName, dirUrl), 'utf8')
-    if (/\.json$/i.test(fileName)) {
-      specs.push(JSON.parse(raw))
-    } else {
-      specs.push(parsePromptConfigYaml(raw))
+    const spec = /\.json$/i.test(fileName) ? JSON.parse(raw) : parsePromptConfigYaml(raw)
+    const prefix = /^(\d+)-/.exec(fileName)
+    if (prefix !== null && spec !== null && typeof spec === 'object' && !Array.isArray(spec)) {
+      const sequence = Number(prefix[1])
+      if (!Number.isSafeInteger(sequence)) throw new TypeError(`${name}: unsafe config sequence in ${fileName}`)
+      Object.defineProperty(spec, FILE_SEQUENCE, { value: sequence })
     }
+    specs.push(spec)
   }
   for (const spec of specs) {
     if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) continue
@@ -632,17 +636,23 @@ export function createPromptConfigs(specs, options = {}) {
       templatePatch,
       params,
     }
+    const sequence = (Object.hasOwn(options.configOrder ?? {}, spec.id) ? options.configOrder[spec.id] : undefined) ?? spec[FILE_SEQUENCE]
+      ?? (typeof options.sourceModuleId === 'string' ? index * 10 : undefined)
+    if (sequence !== undefined) config.sequence = sequence
+    if (typeof options.sourceModuleId === 'string') config.sourceModuleId = options.sourceModuleId
     // 条件判定的匹配器在挂载期编译一次，执行侧（condition.mjs）直接复用：
     // normalizeMatch 已用同一份参数试编译过，这里是同源的第二句（失败会抛出）。
     config.matchScan = match === undefined ? undefined : createAnchorMatcher(match).scan
     config.resolve = bindResolver(config, options.strategyDir)
     return config
   })
-  // 排序契约:anchor 提示词配置保持模块文件相对顺序(固定锚点),ordered 提示词配置按 order
-  // 稳定升序排在其后。默认 order=0 时等价于文件顺序。
+  // 模块/物化来源按持久序号；没有文件来源的独立数组继续采用 anchor + order 契约。
   return attachStRenderers(configs
     .map((config, fileOrder) => ({ config, fileOrder }))
     .sort((a, b) => {
+      if (a.config.sequence !== undefined || b.config.sequence !== undefined) {
+        return compareConfigSequence(a.config, b.config) || a.fileOrder - b.fileOrder
+      }
       const aAnchor = a.config.configKind === 'anchor' ? 0 : 1
       const bAnchor = b.config.configKind === 'anchor' ? 0 : 1
       if (aAnchor !== bAnchor) return aAnchor - bAnchor

package/engine/session-var-tools.mjs

@@ -2,10 +2,7 @@
 export const name = "session-var-tools"
 
 export function apply(ctx) {
-  const service = ctx.get("pt-session-var-tools")
-  if (service === null || service === undefined || typeof service.mount !== "function") {
-    ctx.logger?.warn(name + ": service unavailable; session-var tools not mounted for this preset")
-    return
-  }
-  ctx.effect(() => service.mount(ctx), name + ": mount")
+  ctx.inject(["pt-session-var-tools"], (scopeCtx) => {
+    scopeCtx.effect(() => scopeCtx.get("pt-session-var-tools").mount(scopeCtx), name + ": mount")
+  })
 }

package/engine/st-render.mjs

@@ -5,6 +5,7 @@ import { sessionVarsSnapshot } from './session-vars.mjs'
 import { sessionEvents, isDelegated, matchesModel } from './shared.mjs'
 import { stripUnresolvedRefs } from './interpolate.mjs'
 import { isSuccessfulCompactionEnd } from './compaction-epoch.mjs'
+import { compareConfigSequence } from './order.mjs'
 
 function visible(config, agent) {
   if (config.enabled === false) return false
@@ -92,10 +93,13 @@ export function attachStRenderers(configs) {
         frame.evaluate = evaluate
         if (session) sessions.set(session, frame)
       }
-      // 同一帧允许后到的 pre-step 资格补入；已求值模板不重放副作用或随机宏。
-      for (const config of templates.filter(config => approved(config)
-        && config.strategy === 'static' && config.dedupe === 'none' && !frame.text.has(config))
-        .sort((a, b) => a.order - b.order)) frame.evaluate(config)
+      // 模块 pre-step 已跨来源按序调度，不能预跑本模块后面的卡而越过另一模块。
+      // 其它入口沿用原预求值语义；同帧已求值模板不重放副作用或随机宏。
+      if (target.sequence === undefined || eligible === undefined) {
+        for (const config of templates.filter(config => approved(config)
+          && config.strategy === 'static' && config.dedupe === 'none' && !frame.text.has(config))
+          .sort(compareConfigSequence)) frame.evaluate(config)
+      }
       if (token && typeof token === 'object') tokens.set(token, frame)
       if (!frame.text.has(target)) frame.evaluate(target)
       return frame.text.get(target) ?? ''

package/engine/subagent-tool-policy.mjs

@@ -291,22 +291,30 @@ export function apply(ctx, config) {
   }
   const compositionScope = scopeOf(ctx)
   if (compositionScope === undefined) throw new Error(`${name}: requires a preset scope`)
-  const installs = new WeakMap()
+  const installs = new Map()
+  const installing = new WeakSet()
+  let active = true
   const belongsToComposition = (agent) => scopeChainOf(scopeOf(agent.ctx)).includes(compositionScope)
   const install = (agent) => {
-    if (installs.has(agent) || !belongsToComposition(agent)) return
+    if (!active || installing.has(agent) || installs.has(agent) || !belongsToComposition(agent)) return
     // 注册走 disposer 契约。这里保留 ctx.effect 而不是 shared.keepDisposer，两条依据：
     // (1) 两个 shadow 必须整组注册：任一个失败时由 Cordis 回滚已注册的那个
     //     （keepDisposer 无回滚语义，第二个失败会留下第一个的残留注册）；
     // (2) remove(agent) 需要按 agent 定向撤销，而 keepDisposer 返回 void，拿不到句柄。
-    const dispose = agent.ctx.effect(() => {
-      const disposers = [
-        agent.ctx.tools.register(createShadowTool(ctx, agent.ctx.tools, compositionScope, compiled, 'spawn', source)),
-        agent.ctx.tools.register(createShadowTool(ctx, agent.ctx.tools, compositionScope, compiled, 'fork', source)),
-      ]
-      return () => { for (const item of disposers) item() }
-    }, `${name}: ${agent.id} shadow`)
-    installs.set(agent, dispose)
+    // register/unregister 同步发 tools/change；登记完成前的重入不能再次注册同名工具。
+    installing.add(agent)
+    try {
+      const dispose = agent.ctx.effect(() => {
+        const disposers = [
+          agent.ctx.tools.register(createShadowTool(ctx, agent.ctx.tools, compositionScope, compiled, 'spawn', source)),
+          agent.ctx.tools.register(createShadowTool(ctx, agent.ctx.tools, compositionScope, compiled, 'fork', source)),
+        ]
+        return () => { for (const item of disposers) item() }
+      }, `${name}: ${agent.id} shadow`)
+      installs.set(agent, dispose)
+    } finally {
+      installing.delete(agent)
+    }
   }
   const remove = (agent) => {
     const dispose = installs.get(agent)
@@ -323,5 +331,12 @@ export function apply(ctx, config) {
     }
   }
   ctx.on('tools/change', reconcile)
+  ctx.effect(() => () => {
+    // Agent 可以继续存活：模块先停接线，再撤回其持有的 Agent scope 贡献。
+    active = false
+    const disposers = [...installs.values()]
+    installs.clear()
+    return Promise.all(disposers.map(dispose => dispose())).then(() => undefined)
+  }, `${name}: shadows`)
   reconcile()
 }

package/engine/world-book-tools.mjs

@@ -2,10 +2,7 @@
 export const name = "world-book-tools"
 
 export function apply(ctx) {
-  const service = ctx.get("pt-world-book-tools")
-  if (service === null || service === undefined || typeof service.mount !== "function") {
-    ctx.logger?.warn(name + ": service unavailable; world-book tools not mounted for this preset")
-    return
-  }
-  ctx.effect(() => service.mount(ctx), name + ": mount")
+  ctx.inject(["pt-world-book-tools"], (scopeCtx) => {
+    scopeCtx.effect(() => scopeCtx.get("pt-world-book-tools").mount(scopeCtx), name + ": mount")
+  })
 }