dsh-plugin-prompt-tool 0.5.0 → 0.6.1

package/README.md

@@ -21,14 +21,16 @@ dsh --profile prompt-tool                                          # 首次启
 - 🔌 **六层一次接线**：一个引擎注册全部可注入层级，共享同一套过滤与降级语义
 - ✍️ **一切皆可配置**：`layer / strategy / position / promotion / subagents / modelScope / mergeMode / order / text / texts / fill / variables / params` 全开放
 - 🧑‍🤝‍🧑 **子代理三态**：`subagents: none / inherit / only`，身份类提示词可只注入子代理
-- 🗂️ **内容与执行分离**：每条提示词配置一个 yml/json 放 `prompt-configs/`，引擎按文件名数字前缀顺序扫描
-- 🧩 **三源合并**：默认提示词配置 < 目录文件 < settings 数组，同名 `id` 覆盖
+- 🗂️ **内容与执行分离**：每条提示词配置渲染为 `~/.dsh/.agent-presets/<预设>/prompt-configs/` 下的 yml，引擎按文件名数字前缀顺序扫描
+- 🧩 **三层合并**：引擎默认（按 params 生成）< 模板默认 promptConfigs < 预设 promptConfigs，同名 `id` 覆盖
 - 🖥️ **独立工作台**：侧边栏「提示词工具」入口（主会话/子代理/注入层/技能设置/预设配置五页）+ 设置面板提示词配置页（列表/表单/模板插入/保存前校验）
-- 🧪 **七种内容策略**：`static / first-turn-anchor / guide-auto / custom-fallback / instruction-hint / placeholder / world-book`
+- 🧪 **七种内容策略**：`static / first-turn-anchor / guide-auto / custom-fallback / instruction-hint / placeholder / world-book`（world-book 支持 ST selectiveLogic 选择性触发：任一/副键全中/排除）
 - 🛡️ **失败不伤会话**：单条失败跳过 + `warnOnce`；配置错误挂载时 fail loud；`dedupe: session` 持久幂等
-- 🎭 **SillyTavern 导入**：JSON 预设卡片一键转换为本地预设——`prompts[]` 映射提示词配置、采样参数进 `params.model*`、`enable_web_search` 按开关装配工具
+- 🎭 **SillyTavern 导入**：JSON 预设卡片一键转换为本地预设——`prompts[]` 映射提示词配置、setvar/getvar 收集进顶层 `variables`（未定义自定义宏自动登记空值占位）、`enable_web_search` 按开关装配工具；采样参数剥离（模型设置 UI 管理）
 - 🎴 **角色卡库**：SillyTavern 角色卡（PNG tEXt chunk `ccv3`/`chara`，或 chara_card JSON）导入独立库（`.characters/<id>/`，含原图/转换参数/角色记忆），按需「导入到当前预设」（`chara-<卡>-` 前缀合并、幂等可移除），多文件自动合并
-- 📚 **世界书**：`character_book` 转 world-book 策略配置（`keys` 命中触发 / `constant` 常驻 / `useRegex` 正则），与模块卡片同一存储与编辑（模块列表「世界书」过滤 + 批量启用/禁用）；ST 变量规则（`setvar`/`getvar` 含默认值）由 params fallback 插值承载
+- 📚 **世界书**：`character_book` 转 world-book 策略配置（`keys` 命中触发 / `constant` 常驻 / `useRegex` 正则 / `selectiveLogic` 组合逻辑），与模块卡片同一存储与编辑（模块列表「世界书」过滤 + 批量启用/禁用）
+- 🧩 **模板变量**：预设级 `variables` 段（`{{key}}` 插值源）——模块列表顶部「模板变量」卡片统一编辑（可折叠/清空/停用/失焦自动保存）；锚定匹配引擎（anchor-match）统一 custom-fallback 与 world-book 的匹配语义
+- 💬 **会话变量工具**：`session_var`（list/get/set/clear）——模型维护角色状态（`{{心情}}` 等），会话级覆盖预设默认；ST 运行时宏（`{{lastusermessage}}` / `{{lastcharmessage}}`）从会话事件提取
 
 ## 预设参数体系
 
@@ -50,7 +52,7 @@ dsh --profile prompt-tool                                          # 首次启
 | PTC/门控 | `usePtcMode` `bootstrapMaxTokens` `injectPrompt` `allowKinds` |
 | 主对话模型 | `modelProvider` `modelName` `modelReasoningEffort` `modelTemperature` `modelMaxTokens` |
 | 子代理模型 | `subagentModelProvider` `subagentModelName` `subagentReasoningEffort` `subagentTemperature` `subagentMaxTokens` |
-| 人设 | `mainPersona`（主对话 Flash 档）`subagentPersona`（子代理，回退 `mainPersona` → 继承主会话） |
+| 人设 | 模块列表的 `persona-main`（system-section + `deployment:persona`，complete 互斥 + suppressRuntimeContext）；`subagentPersona`（子代理显式，缺省经 scope 链继承主会话） |
 | 工具集 | `toolFilterAllow` `toolFilterDeny`（子代理 toolFilter；主对话 tool-filter 模块共用） |
 | 深度 | `maxDepth`（0 禁止委派 / `provider-managed` / 正整数） |
 
@@ -71,7 +73,7 @@ dsh --profile prompt-tool                                          # 首次启
 
 - `mergeMode`：`separate`（默认）同位置多条为独立消息；`merged` 同位置拼接为一条
 - `order`：数值小者更靠近插入锚点，同时决定 `merged` 组内拼接顺序
-- 文本插值：仅 `pre-step` 支持内置环境变量与 filler 变量；`system-section` 额外走官方 `{{variable}}` 渲染
+- 文本插值：`{{key}}` 全层支持——配置/预设 `variables` 优先，ST 运行时宏（lastusermessage 等）次之，内置 `{{DSH_HOME}}/{{WORKSPACE}}/{{CWD}}` 兜底，未注册保留字面（system-section 注册期无会话时运行时宏替换为空，不残留）
 
 
 ## SillyTavern 导入
@@ -79,7 +81,8 @@ dsh --profile prompt-tool                                          # 首次启
 工作台「预设配置」页导入 SillyTavern JSON 预设卡片（导入包无定义文件、仅含单个 `.json` 时自动识别转换），按注入层级映射为本地预设：
 
 - `prompts[]` → `promptConfigs`：`system_prompt + role=system` → `system-section`（多条可 `mergeMode: merged` 拼接）；其余 → `pre-step`（`injection_position=0` → `before-all`，否则 `after-user`）；OFF 状态与 `injection_order` 原样保留
-- 采样参数 → 顶层 `params.model*`：`temperature` / `openai_max_tokens` / `reasoning_effort`
+- 采样参数（`temperature` / `openai_max_tokens` / `reasoning_effort`）**剥离**——模型参数统一由「模型设置」UI / 宿主默认管理
+- ST 变量：`setvar`/`getvar`（含默认值）收集进顶层 `variables`；未定义自定义宏自动登记空值占位（不留字面）
 - `enable_web_search`：`true` → 组装 `tool-web`（fetch 启用）；`false` → 不组装，改加 `tool-filter` 黑名单 `web_search / web_fetch`
 - `modules` 按需装配：`prompt-config-engine` 始终；含 system-section 时补 `persona`（`complete: false` 允许 system 段生效）
 
@@ -92,7 +95,7 @@ dsh --profile prompt-tool                                          # 首次启
 - **PNG**：tEXt chunk（`ccv3` 优先 / `chara` 兜底）base64 解析，原图存 `avatar.png`（字节无损）
 - **JSON**：chara_card_v2/v3 直接转换；多文件（角色卡 × 响应预设）自动合并
 - 正文映射：`first_mes` → 开场白（`dedupe: session`）、`alternate_greetings` → 备用开场白、
-  `description/personality/scenario` → 角色设定、采样参数 → `params.model*`
+  `description/personality/scenario` → 角色设定；采样参数剥离（模型设置 UI 管理）
 - **导入到当前预设**：参数合并进当前预设 promptConfigs（`chara-<卡>-` 前缀、幂等）；可一键移除
 - **角色记忆**：`memory.md` 跟随角色卡跨预设，应用时合并为 world-book constant 配置注入
 
@@ -104,8 +107,11 @@ dsh --profile prompt-tool                                          # 首次启
 - **匹配选项**：`caseSensitive` / `wholeWords` / `useRegex`（keys 按正则）
 - **管理**：模块列表顶部下拉选「世界书」过滤（完整模块卡片编辑 + 批量启用/禁用）；
   模型工具 `world_book_list/upsert/delete`（`note` 写入角色卡记忆）
-- **ST 变量**：`setvar` 收集进 params、`getvar`（含默认值）改写为 `{{key}}` 由引擎插值兜底；
-  `trim`/注释/ERA 剥离，`{{user}}`/`{{char}}` 替换；TavernHelper 扩展注入物自动剥离
+- **ST 变量**：`setvar`/`getvar` 收集进顶层 `variables`、未定义自定义宏自动登记空值占位；
+  `trim`/注释/ERA 剥离，`{{user}}`/`{{char}}` 替换；运行时宏（lastusermessage/lastcharmessage）
+  从会话事件提取；TavernHelper 扩展注入物自动剥离
+- **会话变量**：`session_var` 工具（list/get/set/clear）维护角色状态（会话级覆盖预设默认，
+  结束即失）；跨会话长期记忆用 `world_book` note（持久 memory.md 跟随角色卡）
 
 详细转换规则见 [SillyTavern.md](SillyTavern.md)。
 
@@ -113,7 +119,7 @@ dsh --profile prompt-tool                                          # 首次启
 
 ```sh
 pnpm install && pnpm build
-pnpm test          # 235 单测：渲染/合并/六层接线/preset 生成
+pnpm test          # 287 单测：渲染/合并/六层接线/preset 生成/锚定匹配/插值/会话变量
 pnpm typecheck && pnpm lint
 pnpm sync:anchored       # 刷新 upstream/dsh-anchored-standard 内联快照
 pnpm sync:yaml           # 刷新 engine/vendor/yaml（生成目录运行时 YAML 解析器）

package/engine/anchor-match.mjs

@@ -0,0 +1,117 @@
+/**
+ * anchor-match — 关键词锚定匹配引擎（纯函数，无状态，无依赖）。
+ *
+ * 从 strategies 拆解：custom-fallback（自定义锚定词）与 world-book（关键词触发）
+ * 共用同一套匹配语义——主键/副键、大小写、整词、正则、组合逻辑。
+ *
+ * 逻辑对齐 ST world_info_logic：
+ *   any  = AND_ANY(0)：主键或副键任一命中即激活（world-book 默认 / custom-fallback 单锚）；
+ *   all     = AND_ALL(3)：主键命中且副键全部命中；
+ *   not     = NOT_ALL(1)：主键命中且副键全部未命中（排除）；
+ *   notAny  = NOT_ANY(2)：主键命中且至少一个副键未命中（部分排除）。
+ *
+ * 模式：
+ *   scan   = 全文扫描（world-book 消息批匹配）；
+ *   prefix = 文本开头匹配（custom-fallback 首轮 reasoning 锚定确认：ASCII 词边界前缀，
+ *            非 ASCII 直 prefix）。
+ */
+
+/** 组合逻辑（ST world_info_logic 映射）。 */
+export const MATCH_LOGIC = {
+  ANY: 'any',
+  ALL: 'all',
+  NOT: 'not',
+  NOT_ANY: 'notAny',
+}
+
+/** 正则转义（关键词原样匹配时用）。 */
+export function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** 单键正则编译（逐键匹配：any/all/not 需要精确的命中键数，捕获组会干扰 match 计数）。 */
+function compileSingle(key, { caseSensitive, wholeWords, useRegex }) {
+  const flags = caseSensitive ? '' : 'i'
+  if (useRegex) {
+    // ST use_regex=true：键原样作为正则（作者负责合法性）。
+    return new RegExp(key, flags)
+  }
+  if (wholeWords) {
+    return new RegExp(`(^|[^\\p{L}\\p{N}])(${escapeRegExp(key)})(?![\\p{L}\\p{N}])`, `${flags}u`)
+  }
+  return new RegExp(escapeRegExp(key), flags)
+}
+
+/** 编译键列表 → [{ key, re }]（剔除空键）。 */
+function compileKeyList(list, options) {
+  return (Array.isArray(list) ? list : [])
+    .map((key) => String(key).trim())
+    .filter((key) => key.length > 0)
+    .map((key) => ({ key, re: compileSingle(key, options) }))
+}
+
+/**
+ * 创建锚定匹配器。
+ * @param {object} options
+ * @param {string[]} options.keys 主键
+ * @param {string[]} [options.secondaryKeys] 副键
+ * @param {boolean} [options.caseSensitive]
+ * @param {boolean} [options.wholeWords]
+ * @param {boolean} [options.useRegex]
+ * @param {'any'|'all'|'not'|'notAny'} [options.logic] 组合逻辑（缺省 any）
+ * @param {'scan'|'prefix'} [options.mode] 匹配模式（缺省 scan）
+ * @returns {{ scan: (text: string) => { primary: number, secondary: number, active: boolean } }}
+ */
+export function createAnchorMatcher(options = {}) {
+  const {
+    keys = [],
+    secondaryKeys = [],
+    caseSensitive = false,
+    wholeWords = false,
+    useRegex = false,
+    logic = MATCH_LOGIC.ANY,
+    mode = 'scan',
+  } = options
+  const primaryList = compileKeyList(keys, { caseSensitive, wholeWords, useRegex })
+  const secondaryList = compileKeyList(secondaryKeys, { caseSensitive, wholeWords, useRegex })
+
+  const scan = (raw) => {
+    const text = String(raw ?? '')
+    if (mode === 'prefix') {
+      // custom-fallback 锚定确认：仅主键首词，文本开头匹配。
+      const word = (Array.isArray(keys) ? keys : []).map((key) => String(key).trim())
+        .find((key) => key.length > 0)
+      if (word === undefined || text.length === 0) return { primary: 0, secondary: 0, active: false }
+      const hit = /^[\x20-\x7E]+$/.test(word)
+        ? new RegExp(`^${escapeRegExp(word.toLowerCase())}\\b`, 'i').test(text)
+        : text.startsWith(word)
+      return { primary: hit ? 1 : 0, secondary: 0, active: hit }
+    }
+    if (primaryList.length === 0 && secondaryList.length === 0) {
+      return { primary: 0, secondary: 0, active: false }
+    }
+    const countHits = (list) => {
+      let hits = 0
+      for (const { re } of list) {
+        re.lastIndex = 0
+        if (re.test(text)) hits += 1
+      }
+      return hits
+    }
+    const primary = countHits(primaryList)
+    const secondary = countHits(secondaryList)
+    let active = false
+    if (logic === MATCH_LOGIC.ALL) {
+      active = primary > 0 && (secondaryList.length === 0 || secondary === secondaryList.length)
+    } else if (logic === MATCH_LOGIC.NOT) {
+      active = primary > 0 && secondary === 0
+    } else if (logic === MATCH_LOGIC.NOT_ANY) {
+      active = primary > 0 && secondaryList.length > 0 && secondary < secondaryList.length
+    } else {
+      active = primary > 0 || secondary > 0
+    }
+    return { primary, secondary, active }
+  }
+
+  return { scan }
+}

package/engine/compositions/library/context-gate.yml

@@ -6,7 +6,7 @@
   config:
     promoteOn: either
     includeSubagents: false
-    allowKinds: __ALLOW_KINDS__
+    allowKinds: __allowKinds__
 
 # ── bootstrap ───────────────────────────────────────────────────────────────
 
@@ -37,4 +37,4 @@
 #
 # `includeSubagents: true` keeps the subagent phase in sync with the
 # context-gate row: a subagent's first request sees the bootstrap pair, then
-# its own first reply or tool call promotes it to the assembled catalog.
+# its own first reply or tool call promotes it to the assembled catalog.

package/engine/compositions/library/delegation.yml

@@ -37,7 +37,7 @@
         provider: spawn
         toolName: subagent
         backgroundMode: continuable
-        __SUBAGENT_CONFIG__
+        __subagentConfig__
 
     - id: tool-subagent-fork
       name: '@deepseek-ai/dsh-tool-subagent'
@@ -45,7 +45,7 @@
         provider: fork
         toolName: subagent_fork
         backgroundMode: continuable
-        __SUBAGENT_CONFIG__
+        __subagentConfig__
 
     # Production dsh does not install these optional providers. An opting-in
     # Profile mounts each provider once on the host plane; copy this preset,

package/engine/compositions/library/str-replace-editor.yml

@@ -7,4 +7,4 @@
 - id: str-replace-editor
   name: '@deepseek-ai/dsh-tool-str-replace-editor'
   config:
-    maxOutputChars: __STR_REPLACE_EDITOR_MAX_OUTPUT_CHARS__
+    maxOutputChars: __strReplaceEditorMaxOutputChars__

package/engine/compositions/library/tool-bootstrap.yml

@@ -7,8 +7,8 @@
     bootstrapTools: [bash, str_replace_editor]
     promoteOn: either
     includeSubagents: false
-    usePtcMode: __USE_PTC_MODE__
-    __BOOTSTRAP_MAX_TOKENS__
+    usePtcMode: __usePtcMode__
+    __bootstrapMaxTokens__
     # Post-compaction core work set: the model is mid-task and needs to keep
     # working, but faces a small catalog instead of the full Standard set.
     compactionTools: [read, write, edit, glob, grep, todo_write, ask_user_question]

package/engine/compositions/library/tool-filter.yml

@@ -7,6 +7,6 @@
 - id: tool-filter
   name: ./engine/tool-filter.mjs
   config:
-    allow: __MAIN_TOOL_FILTER_ALLOW__
-    deny: __MAIN_TOOL_FILTER_DENY__
-    includeSubagents: __MAIN_TOOL_FILTER_SUBAGENTS__
+    allow: __mainToolFilterAllow__
+    deny: __mainToolFilterDeny__
+    includeSubagents: __mainToolFilterSubagents__

package/engine/compositions/source/local/context-gate.yml

@@ -3,7 +3,7 @@
   config:
     promoteOn: either
     includeSubagents: false
-    allowKinds: __ALLOW_KINDS__
+    allowKinds: __allowKinds__
 
 # ── bootstrap ───────────────────────────────────────────────────────────────
 
@@ -34,4 +34,4 @@
 #
 # `includeSubagents: true` keeps the subagent phase in sync with the
 # context-gate row: a subagent's first request sees the bootstrap pair, then
-# its own first reply or tool call promotes it to the assembled catalog.
+# its own first reply or tool call promotes it to the assembled catalog.

package/engine/compositions/source/local/tool-bootstrap.yml

@@ -4,10 +4,10 @@
     bootstrapTools: [bash, str_replace_editor]
     promoteOn: either
     includeSubagents: true
-    usePtcMode: __USE_PTC_MODE__
-    __BOOTSTRAP_MAX_TOKENS__
+    usePtcMode: __usePtcMode__
+    __bootstrapMaxTokens__
     # Post-compaction core work set: the model is mid-task and needs to keep
     # working, but faces a small catalog instead of the full Standard set.
     compactionTools: [read, write, edit, glob, grep, todo_write, ask_user_question]
 
-# ── prompt-tool 模板自带行(由 write-preset 按 manifest 变量物化) ─────────────
+# ── prompt-tool 模板自带行(由 write-preset 按 manifest 变量物化) ─────────────

package/engine/executor.mjs

@@ -7,13 +7,14 @@
 import {
   PROMOTE_EVENTS,
   createWarnOnce,
-  interpolateVariables,
   isDelegated,
   matchesModel,
   newMessageId,
 } from './shared.mjs'
+import { interpolateVariables } from './interpolate.mjs'
 import { createEpochPromotion } from './compaction-epoch.mjs'
 import { wireLayers } from './layers.mjs'
+import { sessionVarsSnapshot } from './session-vars.mjs'
 
 const name = 'prompt-config-engine'
 
@@ -169,7 +170,13 @@ export function applyPromptConfigs(ctx, configs, options = {}) {
           const patched = { ...resolved }
           // params 并入插值变量：ST 变量（setvar/getvar 收集 + 预设参数）顶层 key 直接可插值
           //（含中文 key 如 {{接受值}}——引擎正则已支持 Unicode 字母）。
-          const mergedVars = { ...config.variables, ...config.params, ...(resolved.variables !== null && typeof resolved.variables === 'object' ? resolved.variables : {}) }
+          // 会话变量（session_var 工具维护）覆盖配置/预设默认：resolved > 会话 > params > 配置。
+          const mergedVars = {
+            ...config.variables,
+            ...config.params,
+            ...sessionVarsSnapshot(session),
+            ...(resolved.variables !== null && typeof resolved.variables === 'object' ? resolved.variables : {}),
+          }
           if (typeof patched.text === 'string') {
             // 提示词配置级模板变量 + filler 变量 + 内置环境变量插值。
             patched.text = interpolateVariables(patched.text, mergedVars, session)

package/engine/interpolate.mjs

@@ -0,0 +1,116 @@
+/**
+ * interpolate — 模板变量插值引擎（纯函数，无依赖）。
+ *
+ * 从 shared 拆出：{{key}} 插值是引擎官方对齐的核心语义（variables 优先 + 内置
+ * 兜底），独立为纯能力包，与 anchor-match 同级；消费方（layers / executor /
+ * fillers）按需引用。
+ *
+ * 插值规则：
+ *   - {{key}}：配置 variables 有值 → 替换；否则 ST 运行时宏（lastusermessage /
+ *     lastcharmessage 等，大小写不敏感）→ 会话事件提取；否则动态宏（roll/random/
+ *     pick/chance/time/date 等，支持 {{name::arg}} 参数）→ 运行时计算；否则内置
+ *     变量（DSH_HOME / WORKSPACE / CWD）→ 替换；否则保留字面（宽容）。
+ *   - 键字符集：字母数字、下划线、点、中文、连字符（与 ST setvar/getvar 一致）。
+ */
+
+/** 会话事件中最后一条指定类型消息的文本（事件倒序扫描；无则空串）。 */
+function lastMessageOf(session, type) {
+  const events = session?.events
+  if (!Array.isArray(events)) return ''
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index]
+    if (event?.type !== type) continue
+    const content = event.data?.message?.content
+    if (!Array.isArray(content)) continue
+    const text = content
+      .map((block) => (block !== null && typeof block === 'object' && typeof block.text === 'string') ? block.text : '')
+      .join('')
+      .trim()
+    if (text.length > 0) return text
+  }
+  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)
+  if (items.length === 0) return ''
+  return items[Math.floor(Math.random() * items.length)]
+}
+
+/** 骰子表达式（{{roll::2d6+3}} / {{roll::1d20}}；非法表达式原样返回）。 */
+function rollDice(arg) {
+  const text = String(arg ?? '').replace(/\s+/g, '').toLowerCase()
+  const match = text.match(/^(\d*)d(\d+)([+-]\d+)?$/)
+  if (match === null) return text
+  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
+  let sum = 0
+  for (let index = 0; index < count; index++) sum += 1 + Math.floor(Math.random() * sides)
+  return String(sum + modifier)
+}
+
+/** 百分比概率（{{chance::50}} → true/false）。 */
+function chancePercent(arg) {
+  const value = Number(String(arg ?? '').replace('%', '').trim())
+  if (!Number.isFinite(value)) return ''
+  return Math.random() * 100 < value ? 'true' : 'false'
+}
+
+/** 本地 HH:MM（{{time}}）。 */
+function formatTime(now) {
+  return `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`
+}
+
+/** UTC YYYY-MM-DD（{{date}}）。 */
+function formatDate(now) {
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+}
+
+/** ST 动态宏（大小写不敏感；函数签名 (arg) => string；无会话上下文时同样可用）。 */
+const DYNAMIC_MACROS = {
+  lastusermessage: (_arg, session) => lastMessageOf(session, 'user/message'),
+  lastcharmessage: (_arg, session) => lastMessageOf(session, 'assistant/message'),
+  // charIfNotGroup：ST 群聊时空、单聊为角色名；dsh 会话 header 无角色名
+  //（单角色会话），统一返回空串（不残留字面，也不注入错误内容）。
+  charifnotgroup: () => '',
+  random: (arg) => pickRandom(arg),
+  pick: (arg) => pickRandom(arg),
+  roll: (arg) => rollDice(arg),
+  chance: (arg) => chancePercent(arg),
+  time: () => formatTime(new Date()),
+  date: () => formatDate(new Date()),
+  weekday: () => '星期' + '日一二三四五六'[new Date().getDay()],
+  isotime: () => new Date().toISOString().slice(11, 19),
+  isodate: () => new Date().toISOString().slice(0, 10),
+  newline: () => '\n',
+  pipe: () => '|',
+}
+
+/** 模板变量插值：配置 variables 优先，ST 运行时宏次之，内置 {{DSH_HOME}} / {{WORKSPACE}} / {{CWD}} 兜底。 */
+export function interpolateVariables(text, variables, session) {
+  const builtins = {
+    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
+  })
+}

package/engine/layers.mjs

@@ -3,15 +3,14 @@
  * 所有注册都只作用于本插件提示词配置;单条失败 warnOnce 后继续。
  */
 
-import {
-  getService,
-  interpolateVariables,
-  interpolateStatic,
-  isDelegated,
-  keepDisposer,
-  matchesModel,
-  parseToolNames,
-} from './shared.mjs'
+import {
+  getService,
+  isDelegated,
+  keepDisposer,
+  matchesModel,
+  parseToolNames,
+} from './shared.mjs'
+import { interpolateVariables, interpolateStatic } from './interpolate.mjs'
 
 const name = 'prompt-config-engine'
 
@@ -54,8 +53,8 @@ function textLayerGroups(configs) {
   return groups
 }
 
-/** system-section:注册静态 system prompt 段(支持官方 {{variable}} 渲染与 merged 拼接)。 */
-function wireSystemSections(ctx, configs, warnOnce) {
+/** system-section:注册静态 system prompt 段(支持官方 {{variable}} 渲染与 merged 拼接)。 */
+function wireSystemSections(ctx, configs, warnOnce) {
   const systemPrompt = getService(ctx, 'systemPrompt')
   if (systemPrompt === undefined || typeof systemPrompt.section !== 'function') {
     if (configs.length > 0) warnOnce(`${name}: systemPrompt service unavailable — system-section configs skipped`)
@@ -66,17 +65,22 @@ function wireSystemSections(ctx, configs, warnOnce) {
     try {
       const text = group.map((config) => configText(config)).filter((item) => item.length > 0).join('\n\n')
       if (text.length === 0) continue
-      keepDisposer(ctx, systemPrompt.section({
-        name: typeof base.params?.sectionName === 'string' && base.params.sectionName.length > 0 ? base.params.sectionName : base.id,
-        order: base.order,
-        text,
-        ...(base.params?.complete === true ? { complete: true } : {}),
-      }), `${name}: section ${base.id}`)
-    } catch (error) {
-      warnOnce(`${name}: system-section config ${base.id} failed: ${String(error?.message ?? error)}`)
-    }
-  }
-}
+      keepDisposer(ctx, systemPrompt.section({
+        name: typeof base.params?.sectionName === 'string' && base.params.sectionName.length > 0 ? base.params.sectionName : base.id,
+        order: base.order,
+        text,
+        ...(base.params?.complete === true ? { complete: true } : {}),
+      }), `${name}: section ${base.id}`)
+      // persona 语义透传：suppressRuntimeContext 抑制该 scope 的动态 runtime-context
+      // 快照（官方 dsh-persona includeRuntimeContext:false 等价；多段重复调用幂等）。
+      if (base.params?.suppressRuntimeContext === true) {
+        keepDisposer(ctx, systemPrompt.suppressRuntimeContext(), `${name}: suppressRuntimeContext ${base.id}`)
+      }
+    } catch (error) {
+      warnOnce(`${name}: system-section config ${base.id} failed: ${String(error?.message ?? error)}`)
+    }
+  }
+}
 
 /** runtime-context:注册动态运行时上下文(晋升后由 context-gate 差分投影;支持 merged 拼接与 placeholder 函数 provider)。 */
 function wireRuntimeContexts(ctx, configs, warnOnce) {

package/engine/schema.mjs

@@ -70,11 +70,22 @@ export function loadPromptConfigFiles(dirUrl) {
   } catch (error) {
     throw new TypeError(`${name}: configsDir ${String(dirUrl)} is not readable: ${String(error?.message ?? error)}`)
   }
+  // 预设级模板变量（writePreset 生成 variables.yml）：读入后合并进每条配置
+  // variables（配置自身优先）；variables.yml 本身不当作配置解析。缺失或损坏
+  // 时为空变量源，不阻断加载。
+  let presetVariables = {}
+  try {
+    const parsed = parseYaml(readFileSync(new URL('variables.yml', dirUrl), 'utf8'))
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) presetVariables = parsed
+  } catch {
+    // 无 variables.yml（旧产物/手写目录）或解析失败：保持空变量源。
+  }
   const specs = []
   const files = entries
     .filter((entry) => entry.isFile() && /\.(ya?ml|json)$/i.test(entry.name))
     .sort((a, b) => a.name.localeCompare(b.name))
   for (const entry of files) {
+    if (entry.name === 'variables.yml') continue
     const url = new URL(entry.name, dirUrl)
     const raw = readFileSync(url, 'utf8')
     if (/\.json$/i.test(entry.name)) {
@@ -83,6 +94,13 @@ export function loadPromptConfigFiles(dirUrl) {
       specs.push(parsePromptConfigYaml(raw))
     }
   }
+  for (const spec of specs) {
+    if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) continue
+    const own = spec.variables !== null && typeof spec.variables === 'object' && !Array.isArray(spec.variables)
+      ? spec.variables
+      : {}
+    spec.variables = { ...presetVariables, ...own }
+  }
   return specs
 }
 

package/engine/session-vars.mjs

@@ -0,0 +1,52 @@
+/**
+ * session-vars — 会话变量（ST setvar/getvar 运行时语义）。
+ *
+ * 变量挂在 session 对象上（SESSION_VARS_KEY 属性），因此 .engine 引擎实例与
+ * 插件进程工具实例（不同模块副本）操作同一 session 即共享同一份数据——
+ * 无跨实例状态同步问题。WeakMap 不需要：session 释放后属性随对象回收。
+ *
+ * 插值优先级：resolved 运行时 > 会话变量 > 配置 params > 配置 variables（含预设）。
+ */
+
+/** session 对象上的变量属性键（字符串常量，跨模块实例一致）。 */
+export const SESSION_VARS_KEY = '__pt_session_vars__'
+
+function varsOf(session) {
+  if (session === null || typeof session !== 'object') return undefined
+  let vars = session[SESSION_VARS_KEY]
+  if (vars === undefined) {
+    vars = {}
+    session[SESSION_VARS_KEY] = vars
+  }
+  return vars
+}
+
+/** 会话变量快照（无会话/未设置 → 空对象）。 */
+export function sessionVarsSnapshot(session) {
+  const vars = varsOf(session)
+  return vars === undefined ? {} : { ...vars }
+}
+
+/** 读取单个会话变量（未设置 → undefined）。 */
+export function getSessionVar(session, key) {
+  const vars = varsOf(session)
+  return vars === undefined ? undefined : vars[String(key)]
+}
+
+/** 设置会话变量（值转字符串；空值仍记录）。 */
+export function setSessionVar(session, key, value) {
+  const vars = varsOf(session)
+  if (vars === undefined) return
+  vars[String(key)] = String(value ?? '')
+}
+
+/** 清除会话变量；key 缺省时清空全部。 */
+export function clearSessionVars(session, key) {
+  const vars = varsOf(session)
+  if (vars === undefined) return
+  if (key === undefined || key === '') {
+    for (const name of Object.keys(vars)) delete vars[name]
+  } else {
+    delete vars[String(key)]
+  }
+}

package/engine/shared.mjs

@@ -116,22 +116,3 @@ export function keepDisposer(ctx, disposer, label) {
     // 极简测试桩没有 effect:保持注册随进程,测试自行隔离。
   }
 }
-
-/** 模板变量插值:配置 variables 优先,内置 {{DSH_HOME}} / {{WORKSPACE}} / {{CWD}}。 */
-export function interpolateVariables(text, variables, session) {
-  const builtins = {
-    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) => {
-    if (Object.prototype.hasOwnProperty.call(variables, key)) return String(variables[key])
-    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) =>
-    Object.prototype.hasOwnProperty.call(variables, key) ? String(variables[key]) : whole)
-}