dsh-plugin-prompt-tool 0.4.2 → 0.5.0

package/engine/executor.mjs

@@ -0,0 +1,271 @@
+/**
+ * executor — pre-step 消息批执行器。
+ * 职责:过滤(层/子代理/模型/晋升)→ resolve → 插值 → 去重/合并 → 落位插入。
+ * 任一提示词配置失败只跳过该提示词配置并 warnOnce,绝不让注入 bug 卡死会话。
+ */
+
+import {
+  PROMOTE_EVENTS,
+  createWarnOnce,
+  interpolateVariables,
+  isDelegated,
+  matchesModel,
+  newMessageId,
+} from './shared.mjs'
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { wireLayers } from './layers.mjs'
+
+const name = 'prompt-config-engine'
+
+/** 事件数据兼容两层形状:event.data 本身是消息,或 event.data.message 是消息。 */
+function eventMessage(event) {
+  const data = event?.data
+  if (data === null || typeof data !== 'object') return undefined
+  const message = data.message !== null && typeof data.message === 'object' ? data.message : data
+  return message?.source !== null && typeof message?.source === 'object' ? message : undefined
+}
+
+/** 合并身份:merged 模式按位置分组(merged:<position>);separate 模式保持自身身份。 */
+function mergedIdentity(config) {
+  if (config.mergeMode !== 'merged') return config.id
+  return `merged:${config.position}`
+}
+
+function hasInjected(config, session) {
+  const value = config.mergeMode === 'merged' ? mergedIdentity(config) : config.identity.value
+  return (Array.isArray(session.events) ? session.events : []).some((event) => {
+    const message = eventMessage(event)
+    // 双通道去重：kind（外来/第三方消息，如 context-gate 的 instruction-hint）或
+    // plugin（本引擎注入的命名空间，merged 组用 merged:<position>）。
+    return message?.source?.kind === config.sourceKind || message?.source?.plugin === value
+  })
+}
+
+/** 当前消息批内是否已有该提示词配置注入(每轮去重)。 */
+function hasInBatch(config, messages) {
+  const value = config.mergeMode === 'merged' ? mergedIdentity(config) : config.identity.value
+  return messages.some((message) =>
+    message?.source?.kind === config.sourceKind || message?.source?.plugin === value)
+}
+
+/** 构造默认 user/assistant 消息;策略返回完整 patch 时覆盖对应字段。 */
+function buildMessage(config, resolved) {
+  const text = typeof resolved.text === 'string' ? resolved.text : ''
+  const defaultContent = config.texts.length > 0
+    ? config.texts.map((item) => ({ type: 'text', text: item }))
+    : [{ type: 'text', text }]
+  const sourceValue = mergedIdentity(config)
+  return {
+    id: typeof resolved.id === 'string' && resolved.id.length > 0 ? resolved.id : newMessageId(config.id),
+    role: typeof resolved.role === 'string' ? resolved.role : config.role,
+    content: Array.isArray(resolved.content) ? resolved.content : defaultContent,
+    source: resolved.source !== null && typeof resolved.source === 'object'
+      ? resolved.source
+      : {
+          kind: config.sourceKind,
+          plugin: sourceValue,
+          ...(typeof config.form === 'string' ? { form: config.form } : {}),
+          ...(typeof config.summary === 'string' && config.summary.length > 0 ? { summary: config.summary } : {}),
+        },
+  }
+}
+
+/** 按提示词配置声明的插入位置写入消息批;找不到插入锚点返回 false(本提示词配置跳过)。 */
+function insertMessage(config, messages, message) {
+  if (config.position === 'before-all') {
+    messages.unshift(message)
+    return true
+  }
+  if (config.position === 'after-all') {
+    messages.push(message)
+    return true
+  }
+  // 默认 after-user:只锚真实用户消息,插件消息不算。
+  const userIndex = messages.findIndex((item) => item?.source?.kind === 'user')
+  if (userIndex < 0) return false
+  messages.splice(userIndex + 1, 0, message)
+  return true
+}
+
+/**
+ * 把一组运行时提示词配置装配为注入执行器。
+ * @param prepend 是否以 prepend 注册 pre-step(合并行恒 true;单条提示词配置兼容层由参数决定)。
+ */
+export function applyPromptConfigs(ctx, configs, options = {}) {
+  const list = configs.filter((config) => config !== undefined && config !== null)
+  if (list.length === 0) return
+  // 互斥组:同一 group 且 exclusive=true 时,只保留排序后第一个 enabled 提示词配置。
+  const claimedGroups = new Set()
+  const effectiveList = list.filter((config) => {
+    if (config.enabled === false) return false
+    if (config.group !== undefined && config.exclusive === true) {
+      if (claimedGroups.has(config.group)) return false
+      claimedGroups.add(config.group)
+    }
+    return true
+  })
+  const main = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: false })
+  const withSubagents = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: true })
+  ctx.on('session/event', (session, event) => {
+    main.observe(session, event)
+    withSubagents.observe(session, event)
+  })
+
+  /** 每提示词配置每会话的进程内快路径;真相在持久事件流。 */
+  // ponytail: 会话数上限防无界增长（Set 按 session.id 累积）；若需精确淘汰改 LRU。
+  const MAX_MEMO_SESSIONS = 4096
+  const injectedMemo = new Map()
+  const configMemo = (config) => {
+    let memo = injectedMemo.get(config.id)
+    if (memo === undefined) {
+      if (injectedMemo.size >= MAX_MEMO_SESSIONS) injectedMemo.clear()
+      memo = new Set()
+      injectedMemo.set(config.id, memo)
+    }
+    return memo
+  }
+
+  const warnOnce = createWarnOnce(ctx, name)
+  const prepend = options.prepend === true || list.some((config) => config.prepend === true)
+
+  // 非 pre-step 提示词配置接入各自声明的官方层级通道(system-section /
+  // runtime-context / agent-request / llm-stream / tool-pipeline)。
+  wireLayers(ctx, effectiveList.filter((config) => config.layer !== 'pre-step'), warnOnce)
+
+  ctx.on('agent/pre-step', async ({ agent }, next) => {
+    const decision = await next()
+    try {
+      if (decision.kind === 'reject') return decision
+      if (agent === undefined) return decision
+      const session = agent.session
+      if (session === undefined) return decision
+
+      const messages = Array.isArray(decision.messages) ? [...decision.messages] : []
+      let changed = false
+
+      const due = []
+      for (const config of effectiveList) {
+        try {
+          if (config.layer !== 'pre-step') continue
+          const delegated = isDelegated(session)
+          if (config.audience === 'main' && delegated) continue
+          if (config.audience === 'subagent' && !delegated) continue
+          if (!matchesModel(config.modelScope, agent.options?.model)) continue
+          if (config.promotion === 'main' && !main.status(agent).promoted) continue
+          if (config.promotion === 'include-subagents' && !withSubagents.status(agent).promoted) continue
+
+          const memo = configMemo(config)
+          if (config.dedupe === 'session') {
+            if (memo.has(session.id) || hasInjected(config, session)) {
+              memo.add(session.id)
+              continue
+            }
+          } else if (config.dedupe === 'batch' && hasInBatch(config, messages)) {
+            continue
+          }
+
+          const resolved = await config.resolve({ ctx, agent, session, decision, messages })
+          if (resolved === null || resolved === undefined) continue
+          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 : {}) }
+          if (typeof patched.text === 'string') {
+            // 提示词配置级模板变量 + filler 变量 + 内置环境变量插值。
+            patched.text = interpolateVariables(patched.text, mergedVars, session)
+          }
+          if (config.texts.length > 0) {
+            const blocks = config.texts
+              .map((item) => interpolateVariables(item, mergedVars, session))
+              .filter((item) => item.length > 0)
+              .map((item) => ({ type: 'text', text: item }))
+            if (blocks.length > 0) patched.content = blocks
+          }
+          const hasText = typeof patched.text === 'string' && patched.text.length > 0
+          const hasContent = Array.isArray(patched.content) && patched.content.length > 0
+          if (!hasText && !hasContent) continue
+          due.push({ config, resolved: patched })
+        } catch (error) {
+          // 单个提示词配置失败不得伤及会话:跳过该提示词配置,只告警一次。
+          warnOnce(`${name}: config ${String(config?.id ?? '<unknown>')} failed, skipping: ${String((error && error.message) || error)}`)
+        }
+      }
+
+  // order 升序(同值保持声明顺序):决定拼接顺序与同位置插入顺序。
+  due.sort((a, b) => a.config.order - b.config.order)
+
+      // merged 模式的多条提示词配置在首条配置的位置合并为一条消息;
+      // 文本按内容块拼接,source 身份改用 merged:<position> 以保持持久幂等。
+      const orderedGroups = []
+      const groupIndex = new Map()
+      for (const entry of due) {
+        const group = entry.config.mergeMode === 'merged'
+          ? mergedIdentity(entry.config)
+          : undefined
+        if (group === undefined) {
+          orderedGroups.push([entry])
+          continue
+        }
+        let index = groupIndex.get(group)
+        if (index === undefined) {
+          index = orderedGroups.length
+          groupIndex.set(group, index)
+          orderedGroups.push([])
+        }
+        orderedGroups[index].push(entry)
+      }
+
+      const planned = []
+      for (const group of orderedGroups) {
+        const base = group[0]
+        const message = buildMessage(base.config, base.resolved)
+        if (group.length > 1) {
+          message.content = group.flatMap((entry) => {
+            if (Array.isArray(entry.resolved.content)) return entry.resolved.content
+            return typeof entry.resolved.text === 'string' && entry.resolved.text.length > 0
+              ? [{ type: 'text', text: entry.resolved.text }]
+              : []
+          })
+          if (message.source !== null && typeof message.source === 'object') {
+            message.source = { ...message.source, plugin: mergedIdentity(base.config) }
+          }
+          if (new Set(group.map((entry) => entry.config.position)).size > 1) {
+            warnOnce(`${name}: merged group mixes positions — using ${String(base.config.position)} from the first config`)
+          }
+        }
+        planned.push({ position: base.config.position, message, group })
+      }
+
+      // 同位置批量插入:planned 已按 order 升序,多元素 splice/unshift/push 保持该顺序。
+      const markGroup = (group) => {
+        for (const entry of group) {
+          if (entry.config.dedupe === 'session') configMemo(entry.config).add(session.id)
+        }
+      }
+      const beforeAll = planned.filter((item) => item.position === 'before-all')
+      const afterUser = planned.filter((item) => item.position !== 'before-all' && item.position !== 'after-all')
+      const afterAll = planned.filter((item) => item.position === 'after-all')
+      if (beforeAll.length > 0) {
+        messages.unshift(...beforeAll.map((item) => item.message))
+        for (const item of beforeAll) markGroup(item.group)
+        changed = true
+      }
+      const userIndex = messages.findIndex((item) => item?.source?.kind === 'user')
+      if (afterUser.length > 0 && userIndex >= 0) {
+        messages.splice(userIndex + 1, 0, ...afterUser.map((item) => item.message))
+        for (const item of afterUser) markGroup(item.group)
+        changed = true
+      }
+      if (afterAll.length > 0) {
+        messages.push(...afterAll.map((item) => item.message))
+        for (const item of afterAll) markGroup(item.group)
+        changed = true
+      }
+
+      return changed ? { ...decision, messages } : decision
+    } catch (error) {
+      warnOnce(`${name}: prompt config failed, skipping: ${String((error && error.message) || error)}`)
+      return decision
+    }
+  }, { prepend })
+}

package/engine/fillers.mjs

@@ -0,0 +1,273 @@
+/**
+ * fillers — 引擎内置的动态填充器(strategy=placeholder 的数据源)。
+ * 全部遵循同一铁律:服务缺失或列表失败时返回 null(跳过该配置),绝不伤及会话。
+ */
+
+import { readFileSync } from 'node:fs'
+import { getService, parseToolNames } from './shared.mjs'
+
+const name = 'prompt-config-engine'
+
+const PROJECT_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
+const USER_GLOBAL_CANDIDATE = 'AGENTS.md'
+
+/** instruction-hint 提示文本:agents-instruction.md 优先,否则动态探测。
+ *  path 可经提示词配置 params.agentsInstructionPath 指定（共享引擎时引擎文件在
+ *  预设根 .engine，必须显式指向预设目录内的文件，如 ../<预设>/agents-instruction.md）。 */
+function readAgentsInstructionText(path = './agents-instruction.md') {
+  try {
+    return readFileSync(new URL(path, import.meta.url), 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+/** Find the project root: first ancestor containing any root marker (e.g. .git). */
+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 (project candidates). */
+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
+}
+
+/** Join one path segment onto a directory (platform-agnostic string join). */
+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. */
+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
+}
+
+/**
+ * instruction-hint:晋升后一次性提示指令文件存在(agents-instruction.md 优先)。
+ * 可自定义参数:params.text 直接作为提示文本(覆盖文件与动态探测);
+ * 其余字段语义与 env-facts / skill-catalog 一致(config.params 由单一配置源下发)。
+ */
+function createInstructionHintResolver(config) {
+  const customText = typeof config?.params?.text === 'string' && config.params.text.trim().length > 0
+    ? config.params.text.trim()
+    : ''
+  // 共享引擎：引擎文件在预设根 .engine，agents-instruction.md 必须经
+  // params.agentsInstructionPath 显式指向预设目录内文件（旧版无此参数时回退
+  // './agents-instruction.md'——引擎文件与内容资产同目录的旧布局；显式 .txt 旧路径
+  // 仍可读（升级前生成的组合，文件未重建前保持兼容））。
+  const instructionPath = typeof config?.params?.agentsInstructionPath === 'string'
+    && config.params.agentsInstructionPath.trim().length > 0
+    ? config.params.agentsInstructionPath
+    : './agents-instruction.md'
+  const agentsInstructionText = readAgentsInstructionText(instructionPath)
+  return async ({ ctx, agent, session }) => {
+    const id = `instruction-hint-${session.id}`
+    if (customText.length > 0) {
+      return {
+        id,
+        text: customText,
+        source: { kind: 'instruction-hint', form: 'hint' },
+      }
+    }
+    if (agentsInstructionText.length > 0) {
+      return {
+        id,
+        text: agentsInstructionText,
+        source: { kind: 'instruction-hint', form: 'hint' },
+      }
+    }
+    const fs = ctx.get('fs')
+    if (fs === undefined) return null
+    const cwd = session.header?.cwd ?? process.cwd()
+    const projectFiles = []
+    const root = await findProjectRoot(fs, cwd, agent.signal)
+    projectFiles.push(...await presentInDir(fs, root, PROJECT_CANDIDATES, agent.signal))
+    const userGlobalFiles = []
+    try {
+      const dshHome = process.env.DSH_HOME ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : undefined)
+      if (dshHome !== undefined) {
+        userGlobalFiles.push(...await presentInDir(fs, dshHome, [USER_GLOBAL_CANDIDATE], agent.signal))
+      }
+    } catch {
+      // Unreadable home probe — ignore.
+    }
+    const sections = []
+    if (projectFiles.length > 0) {
+      sections.push(`Workspace instruction files exist: ${projectFiles.join(', ')} (project root: ${root}).`)
+    }
+    if (userGlobalFiles.length > 0) {
+      sections.push(`A user-global instruction file exists: ${USER_GLOBAL_CANDIDATE}.`)
+    }
+    if (sections.length === 0) return null
+    return {
+      id,
+      text: [
+        ...sections,
+        'Do NOT assume their content. When a task touches this workspace, read the relevant instruction files first and follow them.',
+      ].join(' '),
+      source: { kind: 'instruction-hint', form: 'hint' },
+    }
+  }
+}
+
+/**
+ * env-facts:机器事实动态填充器。
+ * params.envKeys 逗号分隔环境变量白名单,默认 DSH_HOME,DSH_WORKSPACE;
+ * CWD 特殊映射到 session.header.cwd ?? process.cwd()。
+ * 返回 facts 变量表与默认文本;用户可用 text 模板 + {{变量}} 完全自定义输出。
+ */
+function createEnvFactsResolver(config) {
+  const keys = parseToolNames(typeof config.params?.envKeys === 'string' && config.params.envKeys.length > 0
+    ? config.params.envKeys
+    : 'DSH_HOME,DSH_WORKSPACE')
+  return ({ agent }) => {
+    const session = agent?.session
+    const cwd = session?.header?.cwd ?? process.cwd()
+    const builtinHome = process.env.DSH_HOME ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : '')
+    const facts = {}
+    for (const key of keys) {
+      let value
+      if (key === 'CWD' || key === 'WORKSPACE') value = cwd
+      else if (key === 'DSH_HOME') value = builtinHome
+      else value = process.env[key]
+      if (typeof value === 'string' && value.length > 0) facts[key] = value
+    }
+    facts.WORKSPACE = process.env.DSH_WORKSPACE ?? cwd
+    facts.CWD = cwd
+    const defaultText = ['Environment facts:', ...Object.entries(facts).map(([key, value]) => `- ${key}=${value}`)].join('\n')
+    return { text: defaultText, variables: facts }
+  }
+}
+
+/**
+ * skill-catalog:技能目录动态填充器。
+ * 数据来自宿主 skills 服务(聚合各 provider;本插件 provider 的 list 已按
+ * skillSwitches 过滤,因此目录天然只含已启用技能)。服务缺失或列表失败时
+ * 跳过本配置并告警一次,绝不伤及会话。
+ */
+function createSkillCatalogResolver(config) {
+  const limit = Number.isSafeInteger(config.params?.limit) && config.params.limit >= 0
+    ? config.params.limit
+    : 20
+  const fields = parseToolNames(typeof config.params?.fields === 'string' ? config.params.fields : 'name,description')
+    .filter((field) => ['name', 'description', 'whenToUse'].includes(field))
+  const providers = parseToolNames(config.params?.providers)
+  const emptyBehavior = config.params?.emptyBehavior === 'text' ? 'text' : 'skip'
+  const emptyText = typeof config.params?.emptyText === 'string' && config.params.emptyText.length > 0
+    ? config.params.emptyText
+    : '当前没有可用技能。'
+  let warned = false
+  const warnOnceLocal = (ctx, message) => {
+    if (warned) return
+    warned = true
+    try {
+      ctx?.logger?.warn(message)
+    } catch {
+      // Logger unavailable — the guard exists only to avoid spamming.
+    }
+  }
+
+  return async ({ ctx, agent, session }) => {
+    try {
+      const skills = getService(ctx, 'skills')
+      if (skills === undefined || typeof skills.list !== 'function') {
+        warnOnceLocal(ctx, `${name}: skills service unavailable — skill-catalog config ${config.id} skipped`)
+        return null
+      }
+      const all = await skills.list({
+        scope: agent ?? ctx,
+        ...(session?.header?.cwd !== undefined ? { cwd: session.header.cwd } : {}),
+        ...(agent?.signal !== undefined ? { signal: agent.signal } : {}),
+      })
+      const visible = Array.isArray(all) ? all : []
+      const scoped = providers.length === 0
+        ? visible
+        : visible.filter((skill) => providers.includes(skill?.provider))
+      const total = scoped.length
+      if (total === 0) {
+        if (emptyBehavior !== 'text') return null
+        return { text: emptyText, variables: { SKILL_COUNT: '0', SKILL_NAMES: '', SKILLS_TEXT: '' } }
+      }
+
+      const nameOf = (skill) => {
+        const value = skill?.name
+        if (typeof value === 'string' && value.length > 0) return value
+        if (typeof skill?.locator === 'string' && skill.locator.length > 0) return skill.locator
+        return String(skill?.id ?? '(unnamed)')
+      }
+      const firstLine = (value) => typeof value === 'string' ? value.split('\n')[0].trim() : ''
+      const rows = (limit === 0 ? scoped : scoped.slice(0, limit)).map((skill) => {
+        const parts = []
+        if (fields.includes('name')) parts.push(nameOf(skill))
+        if (fields.includes('description')) {
+          const description = firstLine(skill?.description)
+          if (description.length > 0) parts.push(description)
+        }
+        if (fields.includes('whenToUse')) {
+          const whenToUse = firstLine(skill?.whenToUse)
+          if (whenToUse.length > 0) parts.push(`适用：${whenToUse}`)
+        }
+        return parts.length === 0 ? '' : `- ${parts.join(': ')}`
+      }).filter((line) => line.length > 0)
+      const skillsText = rows.join('\n')
+      const skillsNames = scoped.map((skill) => nameOf(skill)).join(', ')
+      return {
+        text: `Available skills (${total}):\n${skillsText}`,
+        variables: {
+          SKILL_COUNT: String(total),
+          SKILL_NAMES: skillsNames,
+          SKILLS_TEXT: skillsText,
+        },
+      }
+    } catch (error) {
+      warnOnceLocal(ctx, `${name}: skill-catalog config ${config.id} failed, skipping: ${String((error && error.message) || error)}`)
+      return null
+    }
+  }
+}
+
+/** 动态填充器:strategy=placeholder 时按 fill 键在注入点填充内容。 */
+export const FILLERS = {
+  'instruction-hint': (config) => createInstructionHintResolver(config),
+  'env-facts': (config) => createEnvFactsResolver(config),
+  'skill-catalog': (config) => createSkillCatalogResolver(config),
+}
+
+export function createPlaceholderResolver(config) {
+  const make = FILLERS[config.fill]
+  if (make === undefined) {
+    throw new TypeError(`${name}: unknown config fill ${JSON.stringify(config.fill)}`)
+  }
+  return make(config)
+}
+
+export { createInstructionHintResolver }