dsh-plugin-prompt-tool 2.1.0 → 3.0.0

package/engine/sdk-strip.mjs

@@ -125,7 +125,7 @@ function parseTsMembers(lines, block) {
 
 /** 行多重集包含：`after` 的每一行都能在 `before` 里找到未用尽的同款（= 只删不增）。 */
 function linesOnlyRemoved(before, after) {
-  // ponytail: O(行长) 计数表，够用；段文本是单次 assembly 的投影，不做字典序指纹。
+  // shortcut: O(行长) 计数表，够用；段文本是单次 assembly 的投影，不做字典序指纹。
   const pool = new Map()
   for (const line of before) pool.set(line, (pool.get(line) ?? 0) + 1)
   for (const line of after) {
@@ -256,7 +256,7 @@ function stripPython(lines, names) {
   }
   if (removed.size === 0) return undefined
   // 删空协议体（只剩注释）不是合法 Python，而补 pass 属于"新增"：保守放弃。
-  // ponytail: 这是刻意的保守上限，不是缺口——真要「一个工具都不给」应在名单/guard
+  // shortcut: 这是刻意的保守上限，不是缺口——真要「一个工具都不给」应在名单/guard
   // 层表达（执行边界），文本裁剪只做剩余呈现补救；若将来需要裁剪到空，改法是把
   // pruned 名单交回官方渲染器重生全文，而不是在这里补 pass。
   const body = lines.slice(header + 1, footer)

package/engine/service-names.d.mts

@@ -0,0 +1,10 @@
+/** `service-names.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** pre-step 协调服务名：插件 provide、引擎 getService 读取，两侧共用这一个名字。 */
+export const PRE_STEP_COORDINATOR_SERVICE: string
+
+/** 发现引擎注册表服务名：宿主 root provide，adapter 行按 agent 注册，动作按 agent 解析。 */
+export const DISCOVERY_SERVICE: string
+
+/** 四个模块工具外壳的服务名：`pt-<引擎模块 id>`。前缀是本函数的内部细节。 */
+export function toolServiceName(engineModuleId: string): string

package/engine/service-names.mjs

@@ -0,0 +1,10 @@
+/** pre-step 协调服务名：插件 provide、引擎 getService 读取，两侧共用这一个名字。 */
+export const PRE_STEP_COORDINATOR_SERVICE = 'promptToolPreStep'
+
+/** 发现引擎注册表：宿主 root provide，adapter 行按 agent 注册，动作按 agent 解析。 */
+export const DISCOVERY_SERVICE = 'promptToolDiscovery'
+
+/** 五个模块工具外壳的服务名：`pt-<引擎模块 id>`。前缀是本函数的内部细节。 */
+export function toolServiceName(engineModuleId) {
+  return `pt-${engineModuleId}`
+}

package/engine/shared.d.mts

@@ -0,0 +1,21 @@
+/** `shared.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** 会话对象的结构化最小形状：引擎只读 `header.delegationDepth` 判主子身份。 */
+export interface SessionLike {
+  header?: { delegationDepth?: number } | null
+}
+
+/** 主子身份判据：`delegationDepth > 0` 即子代理。 */
+export function isDelegated(session: SessionLike | null | undefined): boolean
+
+/** 视为晋升信号的 durable 会话事件类型，按 `promoteOn` 词表分档。 */
+export const PROMOTE_EVENTS: {
+  'tool-call': string[]
+  'assistant-message': string[]
+  either: string[]
+}
+
+/** 按消息去重的有界告警出口。 */
+export type WarnOnce = (message: string, key?: string) => void
+
+export function createWarnOnce(ctx: { logger?: { warn(message: string): void } } | undefined, pluginName: string): WarnOnce

package/engine/shared.mjs

@@ -63,17 +63,34 @@ export function validateConfig(pluginName, source, allowedKeys) {
   return config
 }
 
-/** One-shot logger guard shared by filters that degrade instead of throwing. */
+/** 同一句告警只记一次的 key 上限（进程内、按 mount 一份），防不同故障刷屏。 */
+export const WARN_ONCE_LIMIT = 64
+/** 抑制提示的固定键（提示本身不占新故障的名额）。 */
+const WARN_ONCE_SUPPRESSED = Symbol('warnOnceSuppressed')
+
+/**
+ * 按消息去重的有界 logger 守卫：同一条消息只记一次，不同故障各记一次。
+ *
+ * `key` 缺省取整条消息（内嵌错误文本，因此不同故障不同 key、重复故障同 key）。
+ * 只有 logger 调用**成功之后**才登记，失败的告警不占名额；到上限时补一条抑制提示，此后静默。
+ * shortcut: 消息全文当键 → 同一故障的变体文本（id/数值不同）各占一个 key；等出现这种刷屏源再抽结构化键。
+ */
 export function createWarnOnce(ctx, pluginName) {
-  let warned = false
-  return (message) => {
-    if (warned) return
-    warned = true
+  const seen = new Set()
+  return (message, key = message) => {
+    if (seen.has(key)) return
+    const suppressed = seen.size >= WARN_ONCE_LIMIT
+    if (suppressed) {
+      if (seen.has(WARN_ONCE_SUPPRESSED)) return
+      message = `${pluginName}: 后续告警已抑制（已达 ${WARN_ONCE_LIMIT} 条不同告警上限）`
+    }
     try {
       ctx.logger.warn(message)
     } catch {
       // Logger unavailable — the guard exists only to avoid spamming.
+      return
     }
+    seen.add(suppressed ? WARN_ONCE_SUPPRESSED : key)
   }
 }
 
@@ -99,13 +116,9 @@ export function isDelegated(session) {
   return (session?.header?.delegationDepth ?? 0) > 0
 }
 
-/**
- * 读取当前 Session 的不可变事件快照。
- * 正式 API 是 snapshotEvents()（DSH 0.1.2-alpha.4+）；宿主缺失该接口时按空日志处理，不再读取旧 events 数组。
- */
-export function sessionEvents(session) {
-  const snapshot = session?.snapshotEvents?.()
-  return Array.isArray(snapshot) ? snapshot : []
+/** 已校验的静态受众；未声明或 null 同时覆盖主会话与子代理。 */
+export function matchesAudience(declared, target) {
+  return declared == null || declared === target
 }
 
 /** True when a model id looks like a Flash-family model. */
@@ -120,6 +133,26 @@ export function matchesModel(scope, model) {
   return scope === 'flash' ? isFlash : !isFlash
 }
 
+/**
+ * 零依赖的最小 JSON schema 编译器：把工具参数的字段字面量编译成宿主
+ * `ctx.tools.register` 需要的形状。`tool-search` 与 `skill-search` 共用这一份。
+ *
+ * `meta.items` 是数组元素的项描述——保留这一支：删掉它等于让带 items 的参数丢掉项描述
+ * （`tool-search` 的 `toolNames` 正是这种参数）。
+ */
+export 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 }
+}
+
 /** 逗号分隔的 token 列表;空 = 空数组(调用方自行决定"全部"语义)。 */
 export function parseToolNames(value) {
   if (typeof value !== 'string' || value.trim() === '') return []
@@ -187,7 +220,7 @@ export const MAX_TRACKED_SESSIONS = 4096
 export function sessionState(ctx, create, { weak = false, limit = MAX_TRACKED_SESSIONS, evict = 'clear', reset } = {}) {
   const store = weak ? new WeakMap() : new Map()
   const keyOf = (session) => (weak ? session : session?.id)
-  // ponytail: 无上限档（weak / limit: null / evict: null）与有上限档共用一条读写路径，
+  // shortcut: 无上限档（weak / limit: null / evict: null）与有上限档共用一条读写路径，
   // 只在上限判定处分支；未声明上限时不创建任何额外计数器。
   const finite = !weak && typeof limit === 'number' && limit > 0 && evict !== null
   /** 超限处理：`clear` 与 `oldest` 是**两档不同语义**，绝不互相降级。 */

package/engine/skill-search.mjs

@@ -21,10 +21,24 @@
  * dsh-tool-skill. If skills are unavailable the tools answer with a short
  * message instead of throwing.
  *
+ * 与 `tool-search.mjs` 同形状的三条修正（2026-10-16，技能面照搬工具面）：
+ *  1. **打分而非 AND 过滤**：完整命中（命中全部 token）优先，其次近似命中；
+ *     长自然语言查询不再全灭。精确名命中最前。中文与英文同口径——中文整句
+ *     是一个 token，`includes` 仍是子串匹配。
+ *  2. **空查询列出全部（截到上限）**：`skill_load` 已有精确名时直接加载，空查询是
+ *     「先看看有什么」的入口——完整列表连同截断标注比分组摘要更好用。
+ *  3. **截断与空结果都明说**：显示条数 / 命中总数分列，并写明「空结果只说明
+ *     关键词没命中」——模型据此收窄查询或直接按精确名 `skill_load`，而不是
+ *     转去翻文件系统猜名字。
+ *
  * NOTE: this plugin REPLACES the `dsh-tool-skill` row in the composition —
  * the composition must NOT mount both, or the catalog injection returns.
  */
 import { importHostPackage } from './host-package.mjs'
+import { toJsonSchema } from './shared.mjs'
+import { currentEvents } from './history.mjs'
+import { queryTokens, renderRows, rankRows, scoreRows } from './discovery.mjs'
+import { DISCOVERY_SERVICE } from './service-names.mjs'
 
 const { isModelInvocable, renderSkillContent } = await importHostPackage('@deepseek-ai/dsh-skill')
 
@@ -34,78 +48,108 @@ export const name = 'skill-search'
 /** The agent, tools, and skills services must exist before these tools can register. */
 export const inject = ['agents', 'tools', 'skills']
 
+/** 参数 schema 由 `shared.mjs` 的统一实现生成（与 `tool-search` 同一份）。 */
+
+/** 把查询切成小写 token（Unicode 字母数字与下划线连字符，与 tool-search 同口径）。 */
+export { queryTokens }
+
+/**
+ * 对目录打分排序（纯函数，可单测）：精确名命中排最前，其次按命中 token 数降序，
+ * 同分按名字字典序。`wanted` 为空时返回空数组——调用方据此区分「没给查询」与「没搜到」。
+ *
+ * 与工具面同一口径（any-token 打分，不做 AND 过滤）：长自然语言查询在 AND 下命中零个，
+ * 等于白搜；噪声由分数排序与 MAX_RESULTS 截断控制（2026-10-22 用户指出工具面无此问题）。
+ */
+export function scoreSkills(skills, wanted) {
+  return rankRows(scoreRows(skills, wanted, {
+    nameOf: (skill) => skill?.name,
+    haystackOf: (skill) => `${skill?.name ?? ''} ${skill?.description ?? ''} ${skill?.whenToUse ?? ''}`,
+  })).map((row) => ({ ...row, skill: row.item }))
+}
+
+/** 搜索结果上限：再多就该让模型收窄关键词。 */
 const MAX_RESULTS = 20
 
-/** Minimal JSON schema compiler for tool parameters (zero dependencies). */
-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
-    properties[key] = prop
-    if (meta.required) required.push(key)
-  }
-  return { type: 'object', properties, required, additionalProperties: false }
+/** 把目录搜索结果渲染成给模型的文本（带截断提示与加载引导）。 */
+export function renderMatches(scored, query, complete = true) {
+  return renderRows(scored, {
+    query,
+    limit: MAX_RESULTS,
+    noun: 'skills',
+    emptyText: complete
+      ? `No skills match "${query}" — no skill matched your keywords; skill_load still loads any exact name in the registry, and calling skill_search with no arguments lists every visible skill.`
+      : `Skill discovery did not complete, so nothing can be concluded about "${query}". Retry skill_search before treating a skill as unavailable.`,
+    lineOf: ({ skill, name, exact }) => `- ${name}${exact ? ' (exact)' : ''}: ${String(skill?.description ?? '').split('\n')[0]}`,
+    warnings: complete ? [] : ['Skill discovery is incomplete; these results may be partial.'],
+    footer: 'Load one with skill_load({"name": "<exact name>"}).',
+  })
 }
 
-/** Register the two on-demand skill tools. */
+/**
+ * 该技能是否已在本会话的**当前可见上下文**里注入过——去重按 `currentEvents()` 口径：
+ * 压缩/位置替换遮蔽掉的注入不算「已加载」，下次 `skill_load` 仍会重新注入正文。
+ * 官方 `/名字` 手势与 `skill_load` 写的是同一形状的 `skill-invocation` 事件，因此一并覆盖。
+ */
+export function skillLoadedInContext(session, name) {
+  return currentEvents(session).some(event => event?.type === 'user/message'
+    && event.data?.source?.kind === 'skill-invocation'
+    && event.data.source.name === name)
+}
+
+/** 注册两个按需技能工具。 */
 /**
  * 本模块**刻意保持单参形态**：它不读任何 config 键，因此没有白名单可声明。
  * B2 T4 要求「四个无白名单插件行补字段声明与校验」，本行按 PLAN 的例外处理——
- * 若将来需要 config，先确认组合行与调用方确实都在传 config，再补 defineConfig 声明。
+ * 若将来需要 config，先确认组合行与调用方确实在传 config，再补 defineConfig 声明。
  */
-export function apply(ctx) {
-  /** Normalize a query into lowercase tokens for simple substring matching. */
-  const tokens = (text) => (text || '').toLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(Boolean)
-
-  ctx.tools.register({
+export function apply(ctx, _config, options = {}) {
+  const disposeSearch = ctx.tools.register({
     name: 'skill_search',
-    description: 'Search the available skills by keyword and return matching skill names with short descriptions. This session keeps NO skill catalog in the prompt — if a task looks like it matches a skill (document conversion, image processing, game reviews, markdown, PDF, spreadsheets, …), call skill_search FIRST to find it, then skill_load to activate it. Do NOT assume skill names from memory.',
+    description: [
+      'Search the available skills by keyword and return matching skill names with short descriptions.',
+      '',
+      'skill_load loads any exact name in the registry, so a skill the search did not surface still loads by its name.',
+      '',
+      'Usage:',
+      '- `query` — search skill names and descriptions (Chinese keywords work).',
+      '- call with NO arguments — list every visible skill (truncation is marked with the matching total).',
+    ].join('\n'),
     parameters: toJsonSchema({
-      query: { type: 'string', required: true, description: 'search keywords (e.g. "pdf", "obsidian", "game review")' },
+      query: { type: 'string', required: false, description: 'search keywords (e.g. "pdf", "obsidian", "代码审查")' },
     }),
     output: {
       schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } }, required: ['text'] },
       render: (_a, v) => [{ type: 'text', text: v.text }],
     },
     async execute(args, exec) {
-      const wanted = tokens(args.query)
-      const scope = exec?.agent ?? ctx
+      const query = typeof args?.query === 'string' ? args.query.trim() : ''
       try {
+        // 执行中的 agent 就是观察作用域（同 tool-search）：preset 层注册的技能不带
+        // scope 时看不到；cwd 决定项目级技能根，两个入口共用同一组查询参数。
         const snapshot = await ctx.skills.snapshot({
-          scope,
+          scope: exec?.agent ?? ctx,
           cwd: exec?.agent?.session?.header?.cwd,
           signal: exec?.signal,
         })
         exec?.signal?.throwIfAborted()
-        const matches = snapshot.skills.filter(isModelInvocable).filter((skill) => {
-          if (wanted.length === 0) return true
-          const haystack = tokens(`${skill.name} ${skill.description ?? ''} ${skill.whenToUse ?? ''}`).join(' ')
-          return wanted.every((token) => haystack.includes(token))
-        })
-        const head = matches.slice(0, MAX_RESULTS)
-        const lines = head.map((skill) => {
-          const desc = (skill.description || '').split('\n')[0]
-          return `- ${skill.name}: ${desc}`
-        })
-        if (lines.length === 0) return { text: snapshot.complete
-          ? `No skills match "${args.query}". Use skill_search with other keywords.`
-          : 'Skill discovery is incomplete. Retry skill_search before concluding no skills match.' }
-        const extra = matches.length > MAX_RESULTS ? `\n…(${matches.length - MAX_RESULTS} more)` : ''
-        const incomplete = snapshot.complete ? '' : '\nSkill discovery is incomplete; these results may be partial.'
-        return { text: `Matching skills (${matches.length}):\n${lines.join('\n')}${extra}${incomplete}\n\nLoad one with skill_load (exact name).` }
+        const visible = snapshot.skills.filter(isModelInvocable)
+        // 空查询列出可见技能（`scoreSkills` 按契约对空 token 返回 `[]`，不能代表「列出全部」）；
+        // 不完整读只作标注、不作否决，避免把「没读全」变成「搜不到」。
+        const scored = query.length === 0
+          ? visible.map((skill) => ({ skill, name: skill.name, score: 0, exact: false }))
+          : scoreSkills(visible, queryTokens(query))
+        return { text: renderMatches(scored, query, snapshot.complete).join('\n') }
       } catch (error) {
         return { text: `skill_search unavailable: ${String((error && error.message) || error)}` }
       }
     },
   })
 
-  ctx.tools.register({
+  const disposeLoad = ctx.tools.register({
     name: 'skill_load',
-    description: 'Load the full instructions of ONE skill by its exact name (from skill_search results) and inject them for the next request. Call this before acting on a task that matches the skill.',
+    description: 'Load the full instructions of ONE skill by its exact registered name and inject them for the next request. Call this before acting on a task that matches the skill. The name may come from skill_search, from the skill list, or from the user — any exact name in the registry works, and when nothing matches, ask the user for it.',
     parameters: toJsonSchema({
-      name: { type: 'string', required: true, description: 'exact skill name (kebab-case, from skill_search)' },
+      name: { type: 'string', required: true, description: 'exact skill name (kebab-case, as registered)' },
     }),
     output: {
       schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } }, required: ['text'] },
@@ -115,6 +159,13 @@ export function apply(ctx) {
       try {
         const agent = exec?.agent
         if (agent === undefined) return { text: 'skill_load requires an agent context.' }
+        // 名字归一：非字符串与去空白后为空都算「没给名字」，与 tool_search 的
+        // unlockNames 同口径。否则空串会落进「未注册」文案，调用方分不清是输入
+        // 非法还是名字拼错——这两件事该做的事不同。
+        const name = typeof args?.name === 'string' ? args.name.trim() : ''
+        if (name.length === 0) {
+          return { text: 'skill_load needs an exact skill name — call it with one, or run skill_search with no arguments to list every visible skill.' }
+        }
         const options = {
           scope: agent,
           cwd: agent.session.header.cwd,
@@ -122,34 +173,55 @@ export function apply(ctx) {
         }
         const snapshot = await ctx.skills.snapshot(options)
         options.signal?.throwIfAborted()
-        const summary = snapshot.skills.find((entry) => entry.name === args.name)
+        const summary = snapshot.skills.find((entry) => entry.name === name)
         if (summary === undefined) {
+          // 名字错、发现没跑完、调用面缺 agent——三种成因的应对不同。
           return { text: snapshot.complete
-            ? `No skill named "${args.name}". Run skill_search to list available skills.`
-            : 'Skill discovery is incomplete. Retry skill_search before loading this skill.' }
+            ? `No skill named "${name}" is registered for this session. Check the exact name against what skill_search lists, or ask the user for it.`
+            : 'Skill discovery is incomplete, so the name could not be confirmed. Retry skill_load before concluding the skill does not exist.' }
         }
-        if (!isModelInvocable(summary)) return { text: `Skill "${args.name}" is not available for model invocation.` }
-        const skill = await ctx.skills.get(args.name, options)
+        if (!isModelInvocable(summary)) return { text: `Skill "${name}" is not available for model invocation.` }
+        const skill = await ctx.skills.get(name, options)
         options.signal?.throwIfAborted()
         if (skill === undefined) {
-          return { text: `Skill "${args.name}" is no longer available. Run skill_search again.` }
+          return { text: `Skill "${name}" is no longer available — it was registered but its body could not be loaded. Retry once, then run skill_search to see what is still registered.` }
+        }
+        // 去重：正文已在当前可见上下文里就不再注入（少一份重复 token）。
+        // 只有「已加载且仍可见」才跳过——压缩遮蔽掉的注入不算已加载，见 skillLoadedInContext。
+        // shortcut: 同一批次内连调两次 `skill_load` 时，第一次的注入尚未落入会话，去重看不到，
+        // 会重复注入一份；跨批次重复才是常态，等真出现同批重复再按 step 消息判重。
+        if (skillLoadedInContext(agent.session, name)) {
+          return { text: `Skill "${name}" is already loaded in this context — its instructions are above (or earlier in this session), so nothing was injected again. Follow them without another load; if the user explicitly asks to reload it, let them re-send it as a /${name} gesture.` }
         }
-        if (!isModelInvocable(skill)) return { text: `Skill "${args.name}" is not available for model invocation.` }
+        if (!isModelInvocable(skill)) return { text: `Skill "${name}" is not available for model invocation.` }
         if (skill.content.trim().length === 0) {
-          return { text: `Skill "${args.name}" has no loadable body.` }
+          return { text: `Skill "${name}" has no loadable body.` }
         }
         // Queue the skill content as a non-waking next-step context message,
         // exactly like dsh-tool-skill's invocation injection.
         agent.inject({
-          id: `skill-load-${args.name}-${Date.now()}`,
+          id: `skill-load-${name}-${Date.now()}`,
           role: 'user',
           content: [{ type: 'text', text: renderSkillContent(skill) }],
-          source: { kind: 'skill-invocation', name: args.name, form: 'instructions' },
+          source: { kind: 'skill-invocation', name, form: 'instructions' },
         })
-        return { text: `Skill "${args.name}" loaded; its instructions will be injected for the next request.` }
+        return { text: `Skill "${name}" loaded; its instructions will be injected for the next request.` }
       } catch (error) {
         return { text: `skill_load failed: ${String((error && error.message) || error)}` }
       }
     },
   })
+  const registry = typeof ctx.get === 'function' ? ctx.get(DISCOVERY_SERVICE) : undefined
+  const disposeAdapter = registry === undefined ? undefined : registry.register(options.agent, 'skills', discoveryAdapter)
+  return () => {
+    if (typeof disposeAdapter === 'function') disposeAdapter()
+    if (typeof disposeSearch === 'function') disposeSearch()
+    if (typeof disposeLoad === 'function') disposeLoad()
+  }
 }
+
+/** 本引擎向发现注册表提供的元数据：技能面没有「解锁名单」，只登记工具身份。 */
+export const discoveryAdapter = Object.freeze({
+  kind: 'skills',
+  tool: 'skill_search',
+})

package/engine/source-kind.d.mts

@@ -0,0 +1,9 @@
+/**
+ * `source-kind.mjs` 的手写声明：只声明 `src/` 消费的导出，形状按实现写实。
+ */
+
+/** 拼接 v4 生产者身份。 */
+export declare const pluginKind: (owner: string) => string
+
+/** 从 v4 `plugin:<owner>` 解析 owner；裸 `plugin` 与其他形态返回 undefined。 */
+export declare const pluginOwner: (kind: unknown) => string | undefined

package/engine/source-kind.mjs

@@ -0,0 +1,16 @@
+/**
+ * v4 消息来源的生产者身份：`plugin:<owner>`。
+ * 前缀拼接、owner 解析与「是否插件来源」只在这里解释；旧日志的裸 `plugin` 只在
+ * `isPluginKind` 兼容，不进入 `pluginOwner`。
+ */
+const PLUGIN_KIND_PREFIX = 'plugin:'
+
+export const pluginKind = owner => `${PLUGIN_KIND_PREFIX}${owner}`
+
+export const pluginOwner = kind => typeof kind === 'string' && kind.startsWith(PLUGIN_KIND_PREFIX)
+  ? kind.slice(PLUGIN_KIND_PREFIX.length)
+  : undefined
+
+/** 本插件的 kind：v4 `plugin:<owner>`，或旧日志的裸 `plugin`（不是合法 v4 kind）。 */
+export const isPluginKind = kind => kind === 'plugin'
+  || (typeof kind === 'string' && kind.startsWith(PLUGIN_KIND_PREFIX))

package/engine/strategy-ids.mjs

@@ -0,0 +1,5 @@
+/** rule facts 与 schema 共用的 context-activation strategy id；纯 ESM，不 import 宿主或引擎模块。 */
+export const CONTEXT_ACTIVATION_STRATEGY = 'context-activation'
+
+// shortcut: context-activation 的其他字面量仍在 context-activation/actions/宿主导入路径；
+// 这些路径未在本轮统一，等它们也要共享这个 id 时再收。

package/engine/template-evaluation.d.mts

@@ -0,0 +1,16 @@
+export interface TemplateSnapshot {
+  module?: Readonly<Record<string, string>>
+  global?: Readonly<Record<string, string>>
+  session?: unknown
+  sourceId?: string
+  readOnly?: boolean
+  samples?: Map<string, string>
+}
+export interface TemplateResult {
+  text: string
+  reads: Array<'global' | 'module'>
+  changes?: { scope: 'global' | 'module'; values: Record<string, string> }
+}
+export function evaluateTemplate(text: string, options?: TemplateSnapshot): TemplateResult
+export function transformTemplate(text: string, macro: (body: string, expand: (value: string) => string, occurrence: number) => string): string
+export function splitTemplateArgument(text: string): [string, string | undefined]

package/engine/template-evaluation.mjs

@@ -0,0 +1,178 @@
+/** 有界模板解析与原生求值；只返回正文和变更，不持有或写入持久状态。 */
+import { Buffer } from 'node:buffer'
+import { interpolateVariables, isReservedInterpolationName, normalizeMacroSyntax } from './interpolate.mjs'
+
+const MAX_BYTES = 1024 * 1024
+const MAX_DEPTH = 32
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+function byteLength(text) {
+  const size = Buffer.byteLength(text, 'utf8')
+  if (size > MAX_BYTES) throw new RangeError('Template text exceeds 1 MiB')
+  return size
+}
+
+/** JSON 单花括号及字符串内的右括号不构成模板边界。 */
+function macroEnd(text, start, depth = 0) {
+  const frames = [{ braces: 0, brackets: 0, quote: false, escape: false }]
+  if (depth >= MAX_DEPTH) throw new RangeError('Template depth exceeds 32')
+  for (let index = start + 2; index < text.length; index++) {
+    const frame = frames.at(-1), char = text[index]
+    if (frame.escape) { frame.escape = false; continue }
+    if (frame.quote && char === '\\') { frame.escape = true; continue }
+    if (char === '"' && (frame.quote || frame.braces > 0 || frame.brackets > 0)) { frame.quote = !frame.quote; continue }
+    if (text.startsWith('{{', index)) {
+      if (depth + frames.length >= MAX_DEPTH) throw new RangeError('Template depth exceeds 32')
+      frames.push({ braces: 0, brackets: 0, quote: false, escape: false }); index++; continue
+    }
+    if (frame.quote) continue
+    if (char === '{') frame.braces++
+    else if (char === '}' && frame.braces > 0) frame.braces--
+    else if (text.startsWith('}}', index)) {
+      frames.pop()
+      if (!frames.length) return index + 2
+      index++
+    } else if (char === '[') frame.brackets++
+    else if (char === ']') frame.brackets = Math.max(0, frame.brackets - 1)
+  }
+  return -1
+}
+
+/** ST 编辑残片不是可执行表达式；只保留顶层尾部未知裸名，不放宽操作或嵌套语法。 */
+function isLiteralFragment(text) {
+  const match = /^\{\{\s*([A-Za-z0-9_.\u4e00-\u9fff-]+)\s*\}?$/.exec(text.trimEnd())
+  if (!match) return false
+  const key = match[1]
+  return !FORBIDDEN_KEYS.has(key) && !isReservedInterpolationName(key)
+    && !/^(?:(?:module|global)(?:\.|$)|(?:set|add|get|inc|dec)(?:global)?var$|char$|charifnotgroup$|user$|trim$|ERA$)/i.test(key)
+}
+
+/** 转换端和求值端共用边界与预算；出现身份不含正文字符偏移。 */
+export function transformTemplate(text, macro) {
+  let work = 0, occurrence = 0
+  function walk(source, depth = 0) {
+    work += byteLength(source)
+    if (work > MAX_BYTES * MAX_DEPTH) throw new RangeError('Template expansion work limit exceeded')
+    const chunks = []
+    let size = 0, cursor = 0
+    const append = value => {
+      size += byteLength(value)
+      if (size > MAX_BYTES) throw new RangeError('Template output exceeds 1 MiB')
+      chunks.push(value)
+    }
+    while (cursor < source.length) {
+      const start = source.indexOf('{{', cursor)
+      if (start < 0) { append(source.slice(cursor)); break }
+      append(source.slice(cursor, start))
+      const end = macroEnd(source, start, depth)
+      if (end < 0) {
+        const rest = source.slice(start)
+        if (depth === 0 && isLiteralFragment(rest)) { append(rest); break }
+        throw new TypeError('Unclosed template expression')
+      }
+      append(macro(source.slice(start + 2, end - 2), value => walk(value, depth + 1), occurrence++))
+      cursor = end
+    }
+    return chunks.join('')
+  }
+  return walk(text)
+}
+
+/** 当前层第一个分隔符；嵌套表达式里的分隔符属于子表达式。 */
+export function splitTemplateArgument(text) {
+  for (let index = 0; index < text.length; index++) {
+    if (text.startsWith('{{', index)) {
+      const end = macroEnd(text, index)
+      if (end < 0) throw new TypeError('Unclosed template expression')
+      index = end - 1
+    } else if (text.startsWith('::', index)) return [text.slice(0, index), text.slice(index + 2)]
+  }
+  return [text, undefined]
+}
+
+function addValue(value, increment) {
+  const current = value || '0'
+  let parsed
+  try { parsed = JSON.parse(current) } catch { /* 非 JSON 继续按数值或文本处理。 */ }
+  if (Array.isArray(parsed)) { parsed.push(increment); return JSON.stringify(parsed) }
+  if (Number.isNaN(Number(increment)) || Number.isNaN(Number(current))) return (value || '') + increment
+  const result = Number(current) + Number(increment)
+  if (!Number.isFinite(result)) throw new RangeError('Template variable number is not finite')
+  return String(result)
+}
+
+export function evaluateTemplate(text, { module = {}, global = {}, session, sourceId = '', readOnly = false, samples = new Map() } = {}) {
+  const tables = { module: { ...module }, global: { ...global } }
+  const reads = new Set(), resolving = new Set(), values = {}
+  let scope, pick = 0
+  const keyOf = key => {
+    if (!key || FORBIDDEN_KEYS.has(key) || isReservedInterpolationName(key)) throw new TypeError(`Template variable key blocked: ${key}`)
+    return key
+  }
+  const raw = (domain, key) => {
+    reads.add(domain)
+    if (Object.hasOwn(tables[domain], key)) return { domain, value: tables[domain][key] }
+    if (domain === 'module') {
+      reads.add('global')
+      if (Object.hasOwn(tables.global, key)) return { domain: 'global', value: tables.global[key] }
+    }
+    return undefined
+  }
+  const read = (found, key, expand) => {
+    if (!found) return ''
+    const id = `${found.domain}:${key}`
+    if (resolving.has(id)) throw new RangeError(`Template variable cycle: ${id}`)
+    resolving.add(id)
+    try { return expand(String(found.value)) } finally { resolving.delete(id) }
+  }
+  const write = (domain, key, value) => {
+    if (readOnly) throw new TypeError('Read-only template cannot write variables')
+    if (scope !== undefined && scope !== domain) throw new TypeError('One template may write only one variable scope')
+    byteLength(value)
+    scope = domain
+    tables[domain][key] = value
+    values[key] = value
+  }
+  const output = transformTemplate(text, (body, expand, occurrence) => {
+    const [name, args] = splitTemplateArgument(body)
+    const operation = /^(module|global)\.(set|get|add|inc|dec)$/.exec(name.trim())
+    if (operation) {
+      if (args === undefined) throw new TypeError(`Missing arguments for ${name}`)
+      const [rawKey, rawValue] = splitTemplateArgument(args)
+      const key = keyOf(expand(rawKey).trim()), domain = operation[1], action = operation[2]
+      if (readOnly && (action !== 'get' || rawValue !== undefined)) throw new TypeError('Read-only template cannot write variables')
+      if (action === 'get') {
+        const found = raw(domain, key)
+        if (found) return read(found, key, expand)
+        const fallback = rawValue === undefined ? '' : expand(rawValue)
+        if (fallback !== '') write(domain, key, fallback)
+        return fallback
+      }
+      if ((action === 'set' || action === 'add') && rawValue !== undefined) {
+        const value = expand(rawValue)
+        write(domain, key, action === 'set' ? value : addValue(read(raw(domain, key), key, expand), value))
+        return ''
+      }
+      if ((action === 'inc' || action === 'dec') && rawValue === undefined) {
+        const value = addValue(read(raw(domain, key), key, expand), action === 'inc' ? '1' : '-1')
+        write(domain, key, value)
+        return value
+      }
+      throw new TypeError(`Invalid arguments for ${name}`)
+    }
+    if (/^(set|add|get|inc|dec)(global)?var$/i.test(name.trim())) throw new TypeError('ST variable operations are retired; reimport or explicitly convert to module/global operations')
+    const whole = normalizeMacroSyntax(`{{${expand(body)}}}`)
+    const [key] = splitTemplateArgument(whole.slice(2, -2))
+    if (FORBIDDEN_KEYS.has(key)) throw new TypeError(`Template variable key blocked: ${key}`)
+    if (args === undefined && !isReservedInterpolationName(key)) {
+      const found = raw('module', key)
+      if (found) return read(found, key, expand)
+    }
+    if (whole.slice(2, -2).includes('{{')) return whole
+    const identity = key.toLowerCase() === 'pick' ? `pick:${pick++}` : String(occurrence)
+    const sample = `${identity}:${whole}`
+    if (!samples.has(sample)) samples.set(sample, interpolateVariables(whole, {}, session, undefined, `${sourceId}:${identity}`))
+    return samples.get(sample)
+  })
+  return { text: output, reads: [...reads], ...(scope === undefined ? {} : { changes: { scope, values } }) }
+}