dsh-plugin-prompt-tool 2.0.1 → 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 []
@@ -151,24 +184,12 @@ export function keepDisposer(ctx, disposer, label) {
  *  （进程内快路径，真相在 durable 事件流，清空仅触发一次冷扫重建）。 */
 export const MAX_TRACKED_SESSIONS = 4096
 
-/** 按会话 key 取 Map 条目；超限时清空后重建（防 session 数无界增长）。 */
-export function sessionMapGet(map, key, create) {
-  let entry = map.get(key)
-  if (entry === undefined) {
-    if (map.size >= MAX_TRACKED_SESSIONS) map.clear()
-    entry = create()
-    map.set(key, entry)
-  }
-  return entry
-}
-
 /**
  * 会话态声明的统一访问接口（B4 T1 步骤一）。
  *
  * 收敛「每个模块自己维护会话态 Map、自己决定上限与清空策略、自己决定复位时机」，
  * 但**不改变任何既有策略**：键类型、淘汰策略、复位语义逐项由调用方按现状声明，
- * 本函数只把它们收进同一套读写入口。它**不替代** `sessionMapGet`（后者仍是
- * 「按 id + 超限全清」这一档的实现，本函数在 `evict` 缺省且按 id 索引时逐字复用它）。
+ * 本函数只把它们收进同一套读写入口。
  *
  * ## 三个必答项（正好对应现状的三处差异）
  *
@@ -199,7 +220,7 @@ export function sessionMapGet(map, key, create) {
 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]