dsh-plugin-prompt-tool 2.1.0 → 3.0.1

package/engine/declared-triggers.mjs

@@ -1,93 +0,0 @@
-/**
- * declared-triggers — 声明式触发器的运行时（B7）。
- *
- * 链路：`preset.yml` 顶层 `triggers` 段 →（`writePreset` 保存期校验 + 物化）→ 预设根
- * `triggers.yml` → 本模块读入、编译、注册。
- *
- * ## 声明由预设提供，引擎不带默认（2026-09-22 拍板）
- *
- * 所以 `triggers.yml` 缺失 = **没有声明**，不是错误：不注册任何触发器，也不让预设启动失败
- * ——与 `subagent-tool-policy` 的 ENOENT 降级同一纪律。文件在但内容非法才是真错误：
- * fail loud（且保存期就会先被 `engine/trigger-spec.mjs` 拒一次，这里是第二道）。
- *
- * ## 为什么 `apply` 是 async
- *
- * `preset` 原语要在**挂载期一次**解析官方模块导出（判定期零 IO，见 `predicates.mjs` 的
- * 三条硬约束），而那是动态 import。async `apply` 有官方先例（`dsh-api-remotes`、
- * `dsh-client-connection`），本仓库此前没有——这是第一处。
- */
-import { readFileSync } from 'node:fs'
-import { isAbsolute } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { parse as parseYaml } from './vendor/yaml/index.js'
-import { defineConfig, passthrough } from './fields.mjs'
-import { createWarnOnce, keepDisposer } from './shared.mjs'
-import { compileDeclarations, mountDeclarations } from './trigger-spec.mjs'
-import { loadStandingMountFor } from './predicates.mjs'
-
-/** Cordis plugin name used by loader diagnostics. */
-export const name = 'declared-triggers'
-
-/** 只经 `ctx.on`（动作注册）与 agent scope 的 tools 工作，无宿主服务依赖。 */
-export const inject = []
-
-export const configContract = defineConfig({
-  triggersFile: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : '../triggers.yml')),
-  strategyDir: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : undefined)),
-  presetRoot: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : undefined)),
-})
-
-/**
- * 插件装配由注册层传入声明文件的绝对 file URL；引擎实现始终来自已安装插件包。
- * 独立使用时才按本模块 URL 解析相对值，缺省路径不代表任何用户预设目录。
- *
- * 绝对路径必须走 `isAbsolute` 分支：`new URL(绝对路径, base)` 只在 POSIX 形态下忽略 base，
- * Windows 盘符会被当成 URL scheme 并抛 `ERR_INVALID_URL_SCHEME`。而「测试/嵌入可显式
- * 指定绝对路径」是本模块的契约（`loadStandingMountFor(entry)` 有同一约定）。
- */
-function resolveTriggersFile(config) {
-  const raw = typeof config?.triggersFile === 'string' && config.triggersFile.length > 0
-    ? config.triggersFile
-    : '../triggers.yml'
-  if (isAbsolute(raw)) return raw
-  return fileURLToPath(new URL(raw, import.meta.url))
-}
-
-/** 读声明；文件缺失返回 `undefined`（= 没有声明，交由调用方静默返回）。 */
-function readTriggerSpecs(file) {
-  let raw
-  try {
-    raw = readFileSync(file, 'utf8')
-  } catch (error) {
-    if (error?.code === 'ENOENT') return undefined
-    throw error
-  }
-  const parsed = parseYaml(raw, { logLevel: 'silent' })
-  if (!Array.isArray(parsed)) {
-    throw new TypeError(`${name}: triggers.yml must be a YAML array of trigger declarations`)
-  }
-  return parsed
-}
-
-export async function apply(ctx, config) {
-  const source = configContract.parse(config, name)
-  const file = resolveTriggersFile(source)
-  const specs = readTriggerSpecs(file)
-  if (specs === undefined || specs.length === 0) return
-  // 数据路径相对实际声明文件；允许根由注册层提供，不从包内引擎位置猜测用户目录。
-  const templateBaseUrl = pathToFileURL(file)
-  const templatePresetRoot = source.presetRoot === undefined
-    ? new URL('./', templateBaseUrl)
-    : isAbsolute(source.presetRoot) ? pathToFileURL(source.presetRoot.replace(/[\\/]?$/, '/'))
-      : new URL(source.presetRoot.replace(/\/?$/, '/'), templateBaseUrl)
-  const strategyDir = source.strategyDir === undefined ? undefined : (isAbsolute(source.strategyDir)
-    ? pathToFileURL(source.strategyDir).href
-    : new URL(source.strategyDir, templateBaseUrl).href)
-  const promptConfigOptions = { templateBaseUrl, templatePresetRoot, strategyDir }
-  // `preset` 原语需要官方模块导出（判定期零 IO，故在这里一次解析）；其余原语用不到它。
-  const standingMountFor = await loadStandingMountFor()
-  // 声明非法在这里 fail loud——保存期已校验过一次，这里再炸说明文件被绕过保存手改了。
-  const compiled = compileDeclarations(specs, { ctx, standingMountFor, promptConfigOptions })
-  const dispose = mountDeclarations(ctx, compiled, { plugin: name, warnOnce: createWarnOnce(ctx, name) })
-  keepDisposer(ctx, dispose, `${name}: declarations`)
-}

package/engine/session-var-tools.mjs

@@ -1,8 +0,0 @@
-/** 会话变量工具预设模块。 */
-export const name = "session-var-tools"
-
-export function apply(ctx) {
-  ctx.inject(["pt-session-var-tools"], (scopeCtx) => {
-    scopeCtx.effect(() => scopeCtx.get("pt-session-var-tools").mount(scopeCtx), name + ": mount")
-  })
-}

package/engine/session-vars.mjs

@@ -1,54 +0,0 @@
-/**
- * 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, create = false) {
-  if (session === null || typeof session !== 'object') return undefined
-  let vars = Object.hasOwn(session, SESSION_VARS_KEY) ? session[SESSION_VARS_KEY] : undefined
-  if (vars === undefined) {
-    if (!create) return undefined
-    vars = Object.create(null)
-    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 || !Object.hasOwn(vars, String(key)) ? undefined : vars[String(key)]
-}
-
-/** 设置会话变量（值转字符串；空值仍记录）。 */
-export function setSessionVar(session, key, value) {
-  const vars = varsOf(session, true)
-  if (vars === undefined) return
-  // defineProperty 同时保护仍在运行的旧实例创建的普通对象（__proto__ 不能触发 setter）。
-  Object.defineProperty(vars, String(key), { value: String(value ?? ''), writable: true, enumerable: true, configurable: true })
-}
-
-/** 清除会话变量；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/st-macros.d.mts

@@ -1,22 +0,0 @@
-/** 数字运算保留 number；JSON 数组以字符串保存，与 ST 变量存储一致。 */
-export type StVariableTable = Record<string, string | number>
-
-export interface StTextOptions {
-  variables?: Readonly<Record<string, unknown>>
-  local?: StVariableTable
-  global?: StVariableTable
-  /** 原样传给 interpolateVariables，仅供读取会话事实。 */
-  session?: unknown
-  sourceId?: string
-  warn?: (message: string) => void
-}
-
-/** 清理注释/trim/ERA、归一宏写法、替换已知角色与默认用户；不求值变量。 */
-export function prepareStText(text: string, cardName?: string): string
-
-/**
- * 顺序求值，仅修改显式 local/global；getvar 的非空 fallback 初始化所属表。
- * 未知普通引用保留；危险键拒绝并 warn；循环、超过 32 层或 1 MiB 抛 RangeError。
- * 另设总展开工作量上限，防止零输出的重复展开耗尽资源。
- */
-export function renderStText(text: string, options?: StTextOptions): string

package/engine/st-macros.mjs

@@ -1,208 +0,0 @@
-/** ST 文本预处理与顺序求值；状态只归调用方传入的 local/global 所有。 */
-import { Buffer } from 'node:buffer'
-import { createHash } from 'node:crypto'
-import { interpolateVariables, normalizeMacroSyntax } from './interpolate.mjs'
-
-const MAX_BYTES = 1024 * 1024
-const MAX_DEPTH = 32
-const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
-const DISCARDED_MACRO = /^\s*(?:\/\/|(?:trim|ERA)(?=$|[:\s]))/i
-
-function byteLength(text) {
-  const size = Buffer.byteLength(text, 'utf8')
-  if (size > MAX_BYTES) throw new RangeError('ST macro 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('ST macro depth exceeds 32')
-  for (let index = start + 2; index < text.length; index++) {
-    const frame = frames.at(-1)
-    const 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('ST macro 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 === 0) return index + 2
-      index++
-    } else if (char === '[') frame.brackets++
-    else if (char === ']') frame.brackets = Math.max(0, frame.brackets - 1)
-  }
-  return -1
-}
-
-/** 先找到完整边界再求值，未闭合宏的内部指令不会被意外执行。 */
-function transformText(text, macro) {
-  let work = 0
-  function walk(source, depth = 0, path = '') {
-    work += byteLength(source)
-    // 零输出的重复变量展开也必须有界，不能只限制最终输出。
-    if (work > MAX_BYTES * MAX_DEPTH) throw new RangeError('ST macro expansion work limit exceeded')
-    const chunks = []
-    let size = 0
-    const append = (value) => {
-      size += byteLength(value)
-      if (size > MAX_BYTES) throw new RangeError('ST macro output exceeds 1 MiB')
-      chunks.push(value)
-    }
-    let cursor = 0
-    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) {
-        if (!DISCARDED_MACRO.test(source.slice(start + 2))) append(source.slice(start))
-        break
-      }
-      append(macro(source.slice(start + 2, end - 2), (value) => walk(value, depth + 1, `${path}/${start}`), `${path}/${start}`))
-      cursor = end
-    }
-    return chunks.join('')
-  }
-  return walk(text)
-}
-
-/** 只分割当前层的第一个 ::，嵌套宏中的分隔符属于嵌套宏。 */
-function splitArgument(text) {
-  for (let index = 0; index < text.length; index++) {
-    if (text.startsWith('{{', index)) {
-      const end = macroEnd(text, index)
-      if (end < 0) break
-      index = end - 1
-    } else if (text.startsWith('::', index)) {
-      return [text.slice(0, index), text.slice(index + 2)]
-    }
-  }
-  return [text, undefined]
-}
-
-/** 对齐 ST getVariable 的数值转换；空白文本仍是文本。 */
-function stValue(value) {
-  return (typeof value === 'string' && value.trim() === '') || Number.isNaN(Number(value))
-    ? (value || '')
-    : Number(value)
-}
-
-function addValue(value, increment) {
-  const current = stValue(value) || 0
-  byteLength(String(current))
-  let parsed
-  try { parsed = JSON.parse(current) } catch { /* 非 JSON 值继续按数字或文本处理。 */ }
-  if (Array.isArray(parsed)) {
-    parsed.push(increment)
-    return JSON.stringify(parsed)
-  }
-  const amount = Number(increment)
-  if (Number.isNaN(amount) || Number.isNaN(Number(current))) return String(current || '') + increment
-  const result = Number(current) + amount
-  return Number.isNaN(result) ? undefined : result
-}
-
-/** 不求值变量/动态宏，不执行 ERA 内容；未知角色名留给运行时。 */
-export function prepareStText(text, cardName = '') {
-  const name = cardName.trim()
-  return transformText(text, (body, expand) => {
-    if (DISCARDED_MACRO.test(body)) return ''
-    if (/^char$/i.test(body) && name) return name
-    if (/^user$/i.test(body)) return '用户'
-    return normalizeMacroSyntax(`{{${expand(body)}}}`)
-  }).replace(/(?:\r?\n){3,}/g, '\n\n').trim()
-}
-
-/** 按出现顺序求值；variables/session 只读，不持久化或缓存任何状态。 */
-export function renderStText(text, { variables = {}, local = {}, global = {}, session, sourceId = '', warn = () => {} } = {}) {
-  const sourceKey = createHash('sha256').update(sourceId).update(text).digest('hex')
-  const tables = { local, global, variables }
-  const resolving = new Set()
-  const allowed = (key) => {
-    if (key && !FORBIDDEN_KEYS.has(key)) return true
-    warn(`ST variable key blocked: ${key}`)
-    return false
-  }
-  const write = (table, key, value) => {
-    if (value === undefined) return
-    byteLength(String(value))
-    // 禁止危险键，并显式定义 own 数据属性，避免触发继承的 setter。
-    Object.defineProperty(table, key, { value, writable: true, enumerable: true, configurable: true })
-  }
-  const read = (scope, key, expand, numeric = false) => {
-    const id = `${scope}:${key}`
-    if (resolving.has(id)) throw new RangeError(`ST variable cycle: ${id}`)
-    resolving.add(id)
-    try {
-      const value = tables[scope][key]
-      return expand(String((numeric ? stValue(value) : value) ?? ''))
-    } finally {
-      resolving.delete(id)
-    }
-  }
-
-  return transformText(text, (body, expand, path) => {
-    if (DISCARDED_MACRO.test(body)) return ''
-    const [name, args] = splitArgument(body)
-    const operation = /^(set|add|get|inc|dec)(global)?var$/i.exec(name.trim())
-    if (operation && args !== undefined) {
-      const [rawKey, rawValue] = splitArgument(args)
-      const key = expand(rawKey).trim()
-      if (!allowed(key)) return ''
-      const action = operation[1].toLowerCase()
-      const scope = operation[2] ? 'global' : 'local'
-      const table = tables[scope]
-      const exists = Object.hasOwn(table, key)
-      if (action === 'get') {
-        if (exists) return read(scope, key, expand, true)
-        if (scope === 'local' && Object.hasOwn(variables, key)) return read('variables', key, expand, true)
-        if (rawValue === undefined) return ''
-        const fallback = expand(rawValue)
-        if (fallback !== '') write(table, key, fallback)
-        return fallback
-      }
-      if ((action === 'set' || action === 'add') && rawValue !== undefined) {
-        const value = expand(rawValue)
-        write(table, key, action === 'set' ? value : addValue(exists ? table[key] : '', value))
-        return ''
-      }
-      if ((action === 'inc' || action === 'dec') && rawValue === undefined) {
-        const value = addValue(exists ? table[key] : '', action === 'inc' ? 1 : -1)
-        write(table, key, value)
-        return String(value ?? '')
-      }
-      return `{{${body}}}`
-    }
-
-    const whole = normalizeMacroSyntax(`{{${expand(body)}}}`)
-    const [key] = splitArgument(whole.slice(2, -2))
-    if (!allowed(key)) return whole
-    if (Object.hasOwn(local, key)) return read('local', key, expand)
-    if (Object.hasOwn(variables, key)) return read('variables', key, expand)
-    if (/^user$/i.test(key)) return '用户'
-    // 未解析的嵌套引用交给官方出口清洗，不让扁平插值器截断它。
-    if (whole.slice(2, -2).includes('{{')) return whole
-    return interpolateVariables(whole, {}, session, undefined, `${sourceKey}:${path}`)
-  })
-}

package/engine/st-render.mjs

@@ -1,109 +0,0 @@
-/** ST 模板变量帧：只求值显式导入的模板，不决定任何官方插入点的执行顺序。 */
-import { createHash } from 'node:crypto'
-import { renderStText } from './st-macros.mjs'
-import { sessionVarsSnapshot } from './session-vars.mjs'
-import { sessionEvents, isDelegated, matchesModel } from './shared.mjs'
-import { stripUnresolvedRefs } from './interpolate.mjs'
-import { isSuccessfulCompactionEnd } from './compaction-epoch.mjs'
-import { compareConfigSequence } from './order.mjs'
-
-function visible(config, agent) {
-  if (config.enabled === false) return false
-  const delegated = isDelegated(agent?.session)
-  if (config.audience === 'main' && delegated) return false
-  if (config.audience === 'subagent' && !delegated) return false
-  return matchesModel(config.modelScope, agent?.options?.model)
-}
-
-/** 历史与尚未入库的真实输入使用同一消息身份；插件注入消息不触发第二次赋值。 */
-function generationKey(session, pending) {
-  const events = sessionEvents(session)
-  // 宿主先 assemble/pre-step，之后才 append step/start；不能用 step/start 切帧。
-  const boundary = events.findLast(event => event?.type === 'turn/start' || event?.type === 'step/end' || isSuccessfulCompactionEnd(event))
-  if (boundary) return JSON.stringify([boundary.type, boundary.seq, boundary.data?.turn, boundary.data?.step])
-  const seen = new Set()
-  const hash = createHash('sha256')
-  const add = (message, kind) => {
-    if (!message || message.source?.plugin || (message.source?.kind && message.source.kind !== 'user')) return
-    const value = JSON.stringify([kind, message.id ?? null, message.content ?? []])
-    if (seen.has(value)) return
-    seen.add(value)
-    hash.update(value)
-  }
-  for (const event of events) {
-    if (event?.type === 'user/message' || event?.type === 'assistant/message') {
-      add(event.data?.message ?? event.data, event.type)
-    } else if (event?.type === 'tool/call') hash.update(JSON.stringify([event.type, event.seq, event.data?.id]))
-  }
-  for (const message of pending) add(message, `${message.role ?? 'user'}/message`)
-  return hash.digest('hex')
-}
-
-export function attachStRenderers(configs) {
-  const claimed = new Set()
-  const templates = configs.filter(config => {
-    if (config.enabled === false) return false
-    if (config.group !== undefined && config.exclusive === true) {
-      if (claimed.has(config.group)) return false
-      claimed.add(config.group)
-    }
-    return config.params?.stMacros === true
-  })
-  if (!templates.length) return configs
-  // 状态只活在本次 mount 与会话对象的生命周期内；不持有会话 id 的无界全局 Map。
-  const sessions = new WeakMap()
-  const tokens = new WeakMap()
-  for (const target of templates) {
-    target.renderSt = (agent, messages = [], warn = () => {}, token, eligible) => {
-      // 官方 assembly 只拥有两个文本插入点；pre-step 的资格由执行器确认。
-      const approved = config => visible(config, agent) && (eligible === undefined
-        ? (config.layer === 'system-section' || config.layer === 'runtime-context') && config.promotion === 'none'
-        : eligible.has(config.renderSt))
-      if (!approved(target)) return ''
-      const session = agent?.session
-      const cached = token && tokens.get(token)
-      if (cached) {
-        if (!cached.text.has(target)) cached.evaluate(target)
-        return cached.text.get(target) ?? ''
-      }
-      const manual = sessionVarsSnapshot(session)
-      const generation = generationKey(session, messages)
-      const key = `${generation}:${JSON.stringify(manual)}`
-      const previous = session && sessions.get(session)
-      let frame = previous
-      if (!frame || frame.key !== key) {
-        const initialLocal = { ...(previous?.generation === generation ? previous.initialLocal : previous?.local), ...manual }
-        for (const key of Object.keys(previous?.manual ?? {})) if (!Object.hasOwn(manual, key)) delete initialLocal[key]
-        const initialGlobal = { ...(previous?.generation === generation ? previous.initialGlobal : previous?.global) }
-        frame = { key, generation, manual, initialLocal, initialGlobal, local: { ...initialLocal }, global: { ...initialGlobal }, text: new Map() }
-        const evaluate = config => {
-          try {
-            const local = { ...frame.local }, global = { ...frame.global }
-            const text = renderStText(config.texts.join('\n\n'), { variables: config.variables, local, global, session, sourceId: config.id, warn })
-            const cleaned = stripUnresolvedRefs(text)
-            if (cleaned.stripped.length) warn(`prompt-config-engine: ST 模板 ${config.id} 有 ${cleaned.stripped.length} 处未支持引用，已移除`)
-            frame.local = local
-            frame.global = global
-            frame.text.set(config, cleaned.text)
-          } catch (error) {
-            frame.text.set(config, '')
-            warn(`prompt-config-engine: ST 模板 ${config.id} 求值失败：${String(error?.message ?? error)}`)
-          }
-        }
-        frame.evaluate = evaluate
-        if (session) sessions.set(session, frame)
-      }
-      // 模块 pre-step 已跨来源按序调度，不能预跑本模块后面的卡而越过另一模块。
-      // 其它入口沿用原预求值语义；同帧已求值模板不重放副作用或随机宏。
-      if (target.sequence === undefined || eligible === undefined) {
-        for (const config of templates.filter(config => approved(config)
-          && config.strategy === 'static' && config.dedupe === 'none' && !frame.text.has(config))
-          .sort(compareConfigSequence)) frame.evaluate(config)
-      }
-      if (token && typeof token === 'object') tokens.set(token, frame)
-      if (!frame.text.has(target)) frame.evaluate(target)
-      return frame.text.get(target) ?? ''
-    }
-  }
-  return configs
-}

package/engine/st-world-book.d.mts

@@ -1,10 +0,0 @@
-/** 引擎侧 TS 类型声明（运行期实现在 st-world-book.mjs；仅 src/ 侧导入需要）。 */
-export interface WorldBookDiagnosticsSnapshot {
-  records: Array<{ id: string; stage: string; reason: string; [key: string]: unknown }>
-  truncated: boolean
-  step: number
-  /** false = 该会话尚未求值；true = 已求值（records 为空表示本次没有参与/入选条目）。 */
-  evaluated: boolean
-}
-export function lastWorldBookDiagnostics(session: unknown): WorldBookDiagnosticsSnapshot
-export function selectStWorldBook(...args: unknown[]): Set<Record<string, unknown>> & { diagnostics?: { records: unknown[]; truncated: boolean } }