dsh-plugin-prompt-tool 0.7.2 → 0.8.1

package/engine/instruction-hint.mjs

@@ -0,0 +1,285 @@
+/**
+ * instruction-hint — 通用内置指令文件提示引擎。
+ *
+ * 本模块同时是「可 import 的纯函数库」与「可被组合源挂载的 plugin」：
+ * - prompt-config 的 strategy=placeholder + fill=instruction-hint
+ *   直接使用本模块的探测与消息构造；
+ * - plugin 形态（见文件末尾 apply）：**挂本行 = 开启**「晋升后把
+ *   agent-instructions 全文替换为一次性 hint，后续全文消息丢弃」的转换。
+ *
+ * 只提示参考文件存在，不把文件正文塞进每轮上下文。文件探测失败时返回空结果，
+ * 不阻断会话；独立生成的 hint 使用随机 id，替换既有消息时保留其 id。
+ *
+ * PLUGIN CONFIG（挂载期校验；声明即校验，未声明 `enabled` = 关闭）：
+ * - `enabled`: boolean，缺省 false（组合源须显式写 true）。
+ * - `promoteOn`: 'either'（缺省）| 'tool-call' | 'assistant-message'。
+ * - `includeSubagents`: boolean，缺省 false（子代理首次请求即视为已晋升）。
+ */
+
+import { randomUUID } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { booleanOption, createWarnOnce, parsePromoteOn, validateConfig } from './shared.mjs'
+
+export const name = 'instruction-hint'
+
+/** 无 inject：监听器只在使用时触碰 ctx 服务（同 tool-bootstrap / context-gate 纪律）。 */
+export const inject = []
+
+/** 项目目录链中按优先级探测的指令文件名。 */
+export const PROJECT_INSTRUCTION_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
+export const USER_GLOBAL_INSTRUCTION_CANDIDATE = 'AGENTS.md'
+const REFERENCE_HINT_SUFFIX = "They are reference documents about the user's environment and workspace conventions, not task instructions. Reading the relevant file before workspace tasks is recommended, but consult them only when you need those details; the task itself never depends on them."
+
+/** Join one path segment onto a directory (platform-agnostic string join). */
+export function joinPath(dir, segment) {
+  if (dir.endsWith('/') || dir.endsWith('\\')) return dir + segment
+  const sep = dir.includes('\\') ? '\\' : '/'
+  return dir + sep + segment
+}
+
+/** Parent of an absolute Windows or POSIX path. */
+export function parentPath(path) {
+  const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  if (idx <= 0) return path
+  const parent = path.slice(0, idx)
+  return parent.length === 0 ? path : parent
+}
+
+/** Find the project root: first ancestor containing any root marker. */
+export async function findProjectRoot(fs, cwd, signal) {
+  let current = cwd
+  for (;;) {
+    for (const marker of ['.git', '.hg', '.svn']) {
+      try {
+        const target = await fs.resolve(joinPath(current, marker), { cwd, signal })
+        const info = await fs.stat(target, signal)
+        if (info !== undefined) return current
+      } catch {
+        // Probe failure = marker absent; continue.
+      }
+    }
+    const parent = parentPath(current)
+    if (parent === current || parent.length === 0) return cwd
+    current = parent
+  }
+}
+
+/** List instruction files present in one directory. */
+export async function presentInDir(fs, dir, candidates, signal) {
+  const found = []
+  for (const candidate of candidates) {
+    try {
+      const target = await fs.resolve(joinPath(dir, candidate), { cwd: dir, signal })
+      const info = await fs.stat(target, signal)
+      if (info !== undefined && info.type === 'file') found.push(candidate)
+    } catch {
+      // Absent or unreadable — skip.
+    }
+  }
+  return found
+}
+
+/**
+ * 探测 cwd 到项目根的完整目录链，以及 DSH_HOME 下的用户级 AGENTS.md。
+ * home 未传时使用当前宿主的 DSH_HOME/USERPROFILE 推导值。
+ */
+export async function collectInstructionFiles(fs, cwd, signal, home) {
+  const root = await findProjectRoot(fs, cwd, signal)
+  const projectFiles = []
+  let probed = cwd
+  for (;;) {
+    for (const candidate of await presentInDir(fs, probed, PROJECT_INSTRUCTION_CANDIDATES, signal)) {
+      projectFiles.push(probed === root ? candidate : joinPath(probed, candidate))
+    }
+    if (probed === root) break
+    const parent = parentPath(probed)
+    if (parent === probed || parent.length === 0) break
+    probed = parent
+  }
+
+  const userGlobalFiles = []
+  const dshHome = home ?? process.env.DSH_HOME
+    ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : undefined)
+  if (dshHome !== undefined) {
+    userGlobalFiles.push(...await presentInDir(fs, dshHome, [USER_GLOBAL_INSTRUCTION_CANDIDATE], signal))
+  }
+  return { root, projectFiles, userGlobalFiles, userGlobalHome: dshHome }
+}
+
+/**
+ * 将探测结果格式化为建议式 hint；无文件时返回空字符串。
+ * scope 限定只报告某一来源：all（默认）/ global（$DSH_HOME/AGENTS.md）/ project（cwd→项目根链）。
+ */
+export function buildInstructionHintText({ root, projectFiles = [], userGlobalFiles = [], userGlobalHome } = {}, scope = 'all') {
+  const sections = []
+  if (scope !== 'global' && projectFiles.length > 0) {
+    sections.push(`Reference documents exist: ${projectFiles.join(', ')} (project root: ${root}).`)
+  }
+  if (scope !== 'project' && userGlobalFiles.length > 0) {
+    const paths = typeof userGlobalHome === 'string' && userGlobalHome.length > 0
+      ? userGlobalFiles.map((name) => joinPath(userGlobalHome, name))
+      : userGlobalFiles
+    sections.push(`A user reference document exists: ${paths.join(', ')}.`)
+  }
+  if (sections.length === 0) return ''
+  sections.push(REFERENCE_HINT_SUFFIX)
+  return sections.join(' ')
+}
+
+const HINT_SCOPES = new Set(['all', 'global', 'project'])
+
+function hintScope(value) {
+  return typeof value === 'string' && HINT_SCOPES.has(value) ? value : 'all'
+}
+
+/**
+ * prompt-config placeholder fill=instruction-hint 的 resolver。
+ * params.text（自定义提示）优先；params.file（文件卡绑定的单个指令文件）次之——
+ * 运行时读该文件正文并加 `Instructions from:` 头注入；最后按 params.scope 探测来源
+ * （all / global / project）只发「文件存在」提示。
+ * 文件缺失、不可读或空内容时返回 null，不注入任何消息。
+ */
+export function createInstructionHintResolver(config = {}) {
+  const customText = typeof config?.params?.text === 'string' && config.params.text.trim().length > 0
+    ? config.params.text.trim()
+    : ''
+  const scope = hintScope(config?.params?.scope)
+  const file = typeof config?.params?.file === 'string' && config.params.file.trim().length > 0
+    ? config.params.file.trim()
+    : ''
+  const fileLabel = typeof config?.params?.displayPath === 'string' && config.params.displayPath.trim().length > 0
+    ? config.params.displayPath.trim()
+    : file
+  /** 文件即真相：每次注入都重读绑定文件，外部编辑立即生效。 */
+  const readBoundFile = () => {
+    try {
+      return readFileSync(file, 'utf8').trim()
+    } catch {
+      return ''
+    }
+  }
+
+  return async ({ ctx, agent, session }) => {
+    const id = `instruction-hint-${session.id}-${randomUUID()}`
+    if (customText.length > 0) {
+      return { id, text: customText, source: { kind: 'instruction-hint', form: 'hint' } }
+    }
+    if (file.length > 0) {
+      const content = readBoundFile()
+      return content.length > 0
+        ? { id, text: `Instructions from: ${fileLabel}\n\n${content}`, source: { kind: 'instruction-file', form: 'instructions' } }
+        : null
+    }
+    const fs = ctx.get('fs')
+    if (fs === undefined) return null
+    const cwd = session.header?.cwd ?? process.cwd()
+    const found = await collectInstructionFiles(fs, cwd, agent.signal)
+    const text = buildInstructionHintText(found, scope)
+    return text.length > 0
+      ? { id, text, source: { kind: 'instruction-hint', form: 'hint' } }
+      : null
+  }
+}
+
+const INSTRUCTION_FROM_RE = /(?:^|\n) *(?:Additional |Updated )?Instructions from: ([^\n]+)/g
+
+/** 从 agent-instructions 注入消息提取参考文件路径。 */
+export function extractInstructionPaths(message) {
+  const paths = []
+  const blocks = Array.isArray(message?.content) ? message.content : []
+  for (const block of blocks) {
+    if (block?.type !== 'text' || typeof block.text !== 'string') continue
+    for (const match of block.text.matchAll(INSTRUCTION_FROM_RE)) {
+      const path = match[1].trim()
+      if (path !== '' && !paths.includes(path)) paths.push(path)
+    }
+  }
+  return paths
+}
+
+/** 构造一次性非命令式 hint 消息；替换已有消息时保留其 id。 */
+export function buildInstructionHint(original, paths, sourceName = 'instruction-hint') {
+  return {
+    id: typeof original?.id === 'string' && original.id !== '' ? original.id : `instruction-hint-${randomUUID()}`,
+    role: 'user',
+    content: [{
+      type: 'text',
+      text: '<system-reminder>\n'
+        + `Reference documents exist: ${paths.join(', ')}. ${REFERENCE_HINT_SUFFIX}`
+        + '\n</system-reminder>',
+    }],
+    source: { kind: 'instruction-hint', form: 'hint', plugin: sourceName },
+  }
+}
+
+/** 将 agent-instructions 全文替换为一次性 hint，后续全文消息丢弃。 */
+export function instructionHintMessages(messages, state, sourceName = 'instruction-hint') {
+  const kept = []
+  for (const message of messages) {
+    if (message?.source?.kind !== 'agent-instructions') {
+      kept.push(message)
+      continue
+    }
+    if (state.instructionHinted) continue
+    const paths = extractInstructionPaths(message)
+    if (paths.length === 0) {
+      kept.push(message)
+      continue
+    }
+    state.instructionHinted = true
+    kept.push(buildInstructionHint(message, paths, sourceName))
+  }
+  return kept
+}
+
+// ── plugin 形态 ─────────────────────────────────────────────────────────────
+
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['enabled', 'promoteOn', 'includeSubagents'])
+
+/** The visible surface, not the append-only log, owns hint lifetime. */
+function hasVisibleInstructionHint(session) {
+  const messages = session?.deriveMessages?.()
+  return Array.isArray(messages) && messages.some((message) => message?.source?.kind === 'instruction-hint')
+}
+
+/**
+ * 注册晋升后的指令正文转换。
+ *
+ * `prepend: true` + 组合首选行：waterfall after-next 变换按注册逆序生效，本转换因此
+ * 是最外层——后注册的注入无法绕过它。`promotion.status(agent)` 兼作冷扫入口（resume /
+ * reload 后由 durable 事件流重建相位）。声明即校验：非法配置在挂载期暴露，未声明
+ * `enabled` 时同样报错。
+ */
+export function apply(ctx, config) {
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  const promoteEvents = parsePromoteOn(name, source.promoteOn)
+  const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
+  // 开关语义：未声明 = 关闭（组合源为本模块显式写 enabled: true）。
+  const enabled = booleanOption(name, source.enabled, 'enabled', false)
+  if (!enabled) return
+
+  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
+  const warnOnce = createWarnOnce(ctx, name)
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  ctx.on('agent/pre-step', async ({ agent }, next) => {
+    // Downstream errors propagate untouched; only this filter's own logic is guarded.
+    const decision = await next()
+    if (decision.kind === 'reject') return decision
+    try {
+      if (!promotion.status(agent).promoted) return decision
+      if (!Array.isArray(decision.messages)) return decision
+      if (agent?.session === undefined) return decision
+      // 1 换 1 的转换不能按长度判断（长度相同仍可能已转换），
+      // instructionHintMessages 本身保留非目标消息，直接采用结果。
+      const hintState = { instructionHinted: hasVisibleInstructionHint(agent.session) }
+      return { ...decision, messages: instructionHintMessages(decision.messages, hintState, name) }
+    } catch (error) {
+      // 转换失败不阻断会话：保留原消息。
+      warnOnce(`${name}: instruction hint conversion failed, keeping messages: ${String((error && error.message) || error)}`)
+      return decision
+    }
+  }, { prepend: true })
+}

package/engine/interpolate.mjs

@@ -13,10 +13,12 @@
  *   - 键字符集：字母数字、下划线、点、中文、连字符（与 ST setvar/getvar 一致）。
  */
 
+import { sessionEvents } from './shared.mjs'
+import { createHash } from 'node:crypto'
+
 /** 会话事件中最后一条指定类型消息的文本（事件倒序扫描；无则空串）。 */
 function lastMessageOf(session, type) {
-  const events = session?.events
-  if (!Array.isArray(events)) return ''
+  const events = sessionEvents(session)
   for (let index = events.length - 1; index >= 0; index--) {
     const event = events[index]
     if (event?.type !== type) continue
@@ -31,22 +33,26 @@ function lastMessageOf(session, type) {
   return ''
 }
 
-/** 逗号分隔随机选一个（{{random::a,b,c}} / {{pick::a,b,c}}）。 */
-function pickRandom(arg) {
-  const items = String(arg ?? '').split(',').map((item) => item.trim()).filter((item) => item.length > 0)
+/** ST 双冒号/逗号列表；有 seed 时稳定选择，否则每次采样。 */
+function pickRandom(arg, seed) {
+  const input = String(arg ?? '')
+  const items = input.includes('::') ? input.split('::')
+    : input.split(/(?<!\\),/).map(item => item.trim().replaceAll('\\,', ','))
   if (items.length === 0) return ''
-  return items[Math.floor(Math.random() * items.length)]
+  const random = seed === undefined ? Math.random() : createHash('sha256').update(seed).digest().readUInt32BE() / 2 ** 32
+  return items[Math.floor(random * items.length)]
 }
 
-/** 骰子表达式（{{roll::2d6+3}} / {{roll::1d20}}；非法表达式原样返回）。 */
+/** 骰子表达式（{{roll::2d6+3}} / {{roll::6}}；非法或不安全输入为空）。 */
 function rollDice(arg) {
-  const text = String(arg ?? '').replace(/\s+/g, '').toLowerCase()
+  const raw = String(arg ?? '').replace(/\s+/g, '').toLowerCase()
+  const text = /^\d+$/.test(raw) ? `1d${raw}` : raw
   const match = text.match(/^(\d*)d(\d+)([+-]\d+)?$/)
-  if (match === null) return text
+  if (match === null) return ''
   const count = match[1] === '' ? 1 : Number.parseInt(match[1], 10)
   const sides = Number.parseInt(match[2], 10)
   const modifier = match[3] === undefined ? 0 : Number.parseInt(match[3], 10)
-  if (!Number.isSafeInteger(count) || count <= 0 || count > 100 || !Number.isSafeInteger(sides) || sides <= 0) return text
+  if (!Number.isSafeInteger(count) || count <= 0 || count > 100 || !Number.isSafeInteger(sides) || sides <= 0 || !Number.isSafeInteger(modifier) || !Number.isSafeInteger(count * sides + Math.abs(modifier))) return ''
   let sum = 0
   for (let index = 0; index < count; index++) sum += 1 + Math.floor(Math.random() * sides)
   return String(sum + modifier)
@@ -64,7 +70,7 @@ function formatTime(now) {
   return `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`
 }
 
-/** UTC YYYY-MM-DD（{{date}}）。 */
+/** 本地 YYYY-MM-DD（{{date}}）；UTC 日期由 isodate 提供。 */
 function formatDate(now) {
   return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
 }
@@ -89,28 +95,150 @@ const DYNAMIC_MACROS = {
   pipe: () => '|',
 }
 
-/** 模板变量插值：配置 variables 优先，ST 运行时宏次之，内置 {{DSH_HOME}} / {{WORKSPACE}} / {{CWD}} 兜底。 */
-export function interpolateVariables(text, variables, session) {
-  const builtins = {
+/** 内置变量：路径类事实（无会话上下文时回退进程 cwd）；两条插值通道同源。 */
+function builtinVariables(session) {
+  return {
     DSH_HOME: process.env.DSH_HOME ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : ''),
     WORKSPACE: process.env.DSH_WORKSPACE ?? session?.header?.cwd ?? process.cwd(),
     CWD: session?.header?.cwd ?? process.cwd(),
   }
-  return text.replace(/\{\{([A-Za-z0-9_.\u4e00-\u9fff-]+)(?:::(.*?))?\}\}/g, (whole, key, arg) => {
-    if (Object.prototype.hasOwnProperty.call(variables, key)) return String(variables[key])
-    const dynamic = DYNAMIC_MACROS[key.toLowerCase()]
-    if (dynamic !== undefined) return dynamic(arg, session)
-    return Object.prototype.hasOwnProperty.call(builtins, key) ? builtins[key] : whole
-  })
 }
 
-/** 仅做配置级静态变量替换（无 session 上下文的层）。 */
-export function interpolateStatic(text, variables) {
-  return text.replace(/\{\{([A-Za-z0-9_.\u4e00-\u9fff-]+)(?:::(.*?))?\}\}/g, (whole, key, arg) => {
-    if (Object.prototype.hasOwnProperty.call(variables, key)) return String(variables[key])
-    // ST 运行时宏在无会话上下文（system-section 注册期）时替换为空串——
-    // 不残留字面，也不触发官方 unknown variable 渲染报错。
-    const dynamic = DYNAMIC_MACROS[key.toLowerCase()]
-    return dynamic !== undefined ? dynamic(arg, undefined) : whole
-  })
+/** 模板变量插值：配置 variables 优先，ST 运行时宏次之，内置 {{DSH_HOME}} / {{WORKSPACE}} / {{CWD}} 兜底。 */
+export function interpolateVariables(text, variables, session, keep, sourceId = '') {
+  const builtins = builtinVariables(session)
+  const active = new Set()
+  // 限制展开增加的字符数、递归深度与工作量；原始正文不截断，失败引用留给出口清洗。
+  let remainingChars = 1024 * 1024
+  let remainingExpansions = 4096
+  function render(input, depth = 0) {
+    return normalizeMacroSyntax(input).replace(REFERENCE_RE, (whole, key, arg, offset) => {
+      if (arg === undefined && keep?.has(key)) return `{{${key}}}`
+      if (active.has(key)) return whole
+      let value
+      if (Object.hasOwn(variables, key)) value = String(variables[key] ?? '')
+      else if (key.toLowerCase() === 'pick') value = pickRandom(arg, JSON.stringify([session?.id ?? '', sourceId, input, offset]))
+      else if (Object.hasOwn(DYNAMIC_MACROS, key.toLowerCase())) value = DYNAMIC_MACROS[key.toLowerCase()](arg, session)
+      else if (Object.hasOwn(builtins, key)) value = builtins[key]
+      else return whole
+      const growth = Math.max(0, value.length - whole.length)
+      const nested = value.includes('{{')
+      if (growth > remainingChars || (nested && (depth >= 32 || remainingExpansions <= 0))) return whole
+      remainingChars -= growth
+      if (!nested) return value
+      remainingExpansions--
+      active.add(key)
+      try {
+        return render(value, depth + 1)
+      } finally {
+        active.delete(key)
+      }
+    })
+  }
+  return render(text)
+}
+
+/**
+ * 静态层插值：配置 variables 优先，ST 运行时宏取空串，内置路径变量按无会话语义解析。
+ * @param keep 需要交给官方变量通道按 assembly 求值的名字（运行时事实与已注册变量）——
+ *   命中即原样保留引用，不做静态替换。
+ */
+export function interpolateStatic(text, variables, keep) {
+  return interpolateVariables(text, variables, undefined, keep)
+}
+
+/**
+ * 需要按 assembly 求值的运行时事实（官方变量注册用）。
+ * random/pick/roll/chance 是「每次出现各算一次」的求值宏，newline/pipe 是字面宏，
+ * 都不在其中——它们继续由 interpolate* 内联处理。
+ */
+export const RUNTIME_FACTS = new Set([
+  'lastusermessage',
+  'lastcharmessage',
+  'charifnotgroup',
+  'time',
+  'date',
+  'weekday',
+  'isotime',
+  'isodate',
+])
+
+/**
+ * 运行时事实求值（大小写不敏感）。非事实名返回 undefined。
+ * @param session 会话对象；缺省时按静态语义（运行时宏为空、时间取当前值）。
+ */
+export function runtimeFactValue(name, session) {
+  const key = String(name ?? '').toLowerCase()
+  if (!RUNTIME_FACTS.has(key)) return undefined
+  return DYNAMIC_MACROS[key](undefined, session)
+}
+
+/**
+ * 引用正则：键允许字母数字、下划线、点、中文与连字符（与 ST setvar/getvar 一致），
+ * `::` 之后是本项目宏参数。官方插值语法更窄，故这两条通道各用各的。
+ */
+const REFERENCE_RE = /\{\{\s*([A-Za-z0-9_.\u4e00-\u9fff-]+)\s*(?:::([^{}]*?))?\}\}/g
+
+/** ST 宏形态 → 本项目语法（幂等）。 */
+const MACRO_ALIASES = 'roll|random|pick|chance'
+/** 空格形态：{{roll 1d6}}（ST 语料常见，本项目语法要求 ::）。 */
+const MACRO_SPACE_RE = new RegExp(`\\{\\{\\s*(${MACRO_ALIASES})\\s+([^{}]*?)\\s*\\}\\}`, 'gi')
+/** 单冒号形态：{{roll:1d6}}（`::` 已是本项目语法，用负向断言排除）。 */
+const MACRO_SINGLE_COLON_RE = new RegExp(`\\{\\{\\s*(${MACRO_ALIASES})\\s*:(?!:)\\s*([^{}]*?)\\s*\\}\\}`, 'gi')
+
+/**
+ * ST 宏写法归一：{{roll 1d6}} / {{roll:1d6}} → {{roll::1d6}}。
+ * 与 `src/host/sillytavern.ts` 的导入期归一同源（两处物理隔离，改动需同步）。
+ */
+export function normalizeMacroSyntax(text) {
+  return text
+    .replace(MACRO_SPACE_RE, (_whole, macro, arg) => `{{${String(macro).toLowerCase()}::${arg}}}`)
+    .replace(MACRO_SINGLE_COLON_RE, (_whole, macro, arg) => `{{${String(macro).toLowerCase()}::${arg}}}`)
+}
+
+/**
+ * 官方插值通道（system-section / runtime-context）专用清洗。
+ *
+ * 官方 renderPrompt 对 section/context 文本做严格插值：畸形引用、`{{}}`、未注册名、
+ * 值为 undefined 都抛错并让整轮 assembly 失败，而 runtime-context 在 0.1.6 没有
+ * `interpolate:false`（PromptContext 无该字段）。因此交给官方之前必须保证文本里
+ * 不再有本项目解析后残留的引用：
+ *   - `{{…}}` 成组引用（含畸形名字）→ 整段剥离（决策：未命中引用剥离）；
+ *   - 有 `{{` 却没成组、但后文存在 `}}` → 只移除 `{{`（官方判畸形），保留可见文本；
+ *   - 只有 `{{` 且其后无 `}}` → 官方按字面处理，原样保留。
+ * @returns 清洗后文本与已剥离片段（供调用方一次性告警）。
+ */
+export function stripUnresolvedRefs(text, keep) {
+  const stripped = []
+  let out = ''
+  let index = 0
+  while (index < text.length) {
+    const open = text.indexOf('{{', index)
+    if (open < 0) {
+      out += text.slice(index)
+      break
+    }
+    out += text.slice(index, open)
+    const rest = text.slice(open)
+    const group = /^\{\{([^{}]*)\}\}/.exec(rest)
+    if (group !== null) {
+      // 白名单（已注册的官方变量名）原样保留，交给官方按 assembly 求值。
+      if (/^[a-z][a-z0-9_]*$/.test(group[1]) && keep?.has(group[1])) {
+        out += group[0]
+        index = open + group[0].length
+        continue
+      }
+      stripped.push(group[0])
+      index = open + group[0].length
+      continue
+    }
+    if (rest.indexOf('}}', 2) >= 0) {
+      stripped.push(rest.slice(0, 2))
+      index = open + 2
+      continue
+    }
+    out += '{{'
+    index = open + 2
+  }
+  return { text: out, stripped }
 }