dsh-plugin-prompt-tool 0.4.2 → 0.6.0

package/engine/layers.mjs

@@ -0,0 +1,224 @@
+/**
+ * layers — 非 pre-step 的五个官方层级接线。
+ * 所有注册都只作用于本插件提示词配置;单条失败 warnOnce 后继续。
+ */
+
+import {
+  getService,
+  isDelegated,
+  keepDisposer,
+  matchesModel,
+  parseToolNames,
+} from './shared.mjs'
+import { interpolateVariables, interpolateStatic } from './interpolate.mjs'
+
+const name = 'prompt-config-engine'
+
+/** 单条文本型配置的完整文本:texts 数组按空行拼接（单一文本字段）。 */
+function configText(config) {
+  return config.texts
+    .map((item) => interpolateStatic(item, config.variables))
+    .filter((item) => item.length > 0)
+    .join('\n\n')
+}
+
+/** agent/request 与 tools/* 层的作用域过滤。 */
+function matchesAgentScope(config, agent) {
+  if (agent === undefined) return true
+  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)
+}
+
+/** 文本型层分组:merged 模式按位置分组,否则每条独立。 */
+function textLayerGroups(configs) {
+  const sorted = [...configs].sort((a, b) => a.order - b.order)
+  const groups = []
+  const index = new Map()
+  for (const config of sorted) {
+    const key = config.mergeMode === 'merged' ? `merged:${config.position ?? ''}` : undefined
+    if (key === undefined) {
+      groups.push([config])
+      continue
+    }
+    let at = index.get(key)
+    if (at === undefined) {
+      at = groups.length
+      index.set(key, at)
+      groups.push([])
+    }
+    groups[at].push(config)
+  }
+  return groups
+}
+
+/** 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`)
+    return
+  }
+  for (const group of textLayerGroups(configs)) {
+    const base = group[0]
+    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}`)
+      // 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) {
+  const systemPrompt = getService(ctx, 'systemPrompt')
+  if (systemPrompt === undefined || typeof systemPrompt.context !== 'function') {
+    if (configs.length > 0) warnOnce(`${name}: systemPrompt service unavailable — runtime-context configs skipped`)
+    return
+  }
+  const staticConfigs = configs.filter((config) => config.strategy !== 'placeholder')
+  for (const group of textLayerGroups(staticConfigs)) {
+    const base = group[0]
+    try {
+      const text = group.map((config) => configText(config)).filter((item) => item.length > 0).join('\n\n')
+      if (text.length === 0) continue
+      keepDisposer(ctx, systemPrompt.context({
+        name: typeof base.params?.contextName === 'string' && base.params.contextName.length > 0 ? base.params.contextName : base.id,
+        order: base.order,
+        text,
+      }), `${name}: context ${base.id}`)
+    } catch (error) {
+      warnOnce(`${name}: runtime-context config ${base.id} failed: ${String(error?.message ?? error)}`)
+    }
+  }
+  // placeholder:官方 context 接受函数 provider,在每次 assembly 时动态填充。
+  const placeholders = configs.filter((config) => config.strategy === 'placeholder')
+    .sort((a, b) => a.order - b.order)
+  for (const config of placeholders) {
+    try {
+      const resolver = config.resolve
+      keepDisposer(ctx, systemPrompt.context({
+        name: typeof config.params?.contextName === 'string' && config.params.contextName.length > 0 ? config.params.contextName : config.id,
+        order: config.order,
+        text: async (assembly) => {
+          const agent = assembly?.agent
+          const session = agent?.session
+          const resolved = await resolver({ ctx, agent, session, decision: { kind: 'ok', messages: [] }, messages: [] })
+          if (resolved === null || resolved === undefined) return ''
+          const variables = { ...config.variables, ...(resolved.variables !== null && typeof resolved.variables === 'object' ? resolved.variables : {}) }
+          if (config.texts.length > 0) return interpolateVariables(config.texts.join('\n\n'), variables, session)
+          return typeof resolved.text === 'string' ? interpolateVariables(resolved.text, variables, session) : ''
+        },
+      }), `${name}: context ${config.id}`)
+    } catch (error) {
+      warnOnce(`${name}: runtime-context placeholder ${config.id} failed: ${String(error?.message ?? error)}`)
+    }
+  }
+}
+
+/** agent-request:对冻结的 LlmCallConfig 做浅合并 / 整体替换。 */
+function wireAgentRequests(ctx, configs, warnOnce) {
+  for (const config of configs) {
+    ctx.on('agent/request', async (payload, next) => {
+      const base = await next()
+      try {
+        if (!matchesAgentScope(config, payload?.agent)) return base
+        const patch = config.params?.patch !== null && typeof config.params?.patch === 'object' && !Array.isArray(config.params.patch)
+          ? config.params.patch
+          : {}
+        if (config.params?.replace === true) return { ...patch }
+        return { ...base, ...patch }
+      } catch (error) {
+        warnOnce(`${name}: agent-request config ${config.id} failed: ${String(error?.message ?? error)}`)
+        return base
+      }
+    })
+  }
+}
+
+/** 把流替换为提示词配置文本的最小合法 chunk 序列。 */
+async function* replacedStream(text) {
+  yield { type: 'block-start', index: 0, blockType: 'text' }
+  yield { type: 'text-delta', index: 0, text }
+  yield { type: 'block-end', index: 0, block: { type: 'text', text } }
+}
+
+/** llm-stream:pass 透传;replace 用提示词配置文本替代整个模型流。 */
+function wireLlmStreams(ctx, configs, warnOnce) {
+  for (const config of configs) {
+    ctx.on('llm/stream', (options, next) => {
+      try {
+        const mode = config.params?.mode ?? 'pass'
+        if (mode === 'replace' && config.texts.length > 0 && matchesModel(config.modelScope, options?.model)) {
+          return replacedStream(config.texts.join('\n\n'))
+        }
+        return next()
+      } catch (error) {
+        warnOnce(`${name}: llm-stream config ${config.id} failed: ${String(error?.message ?? error)}`)
+        return next()
+      }
+    })
+  }
+}
+
+/** tool-pipeline:pre-execute 判定、execute 包装、post-execute 结果替换/阻断。 */
+function wireToolPipelines(ctx, configs, warnOnce) {
+  for (const config of configs) {
+    const names = parseToolNames(config.params?.toolNames)
+    const matchesTool = (exec) => names.length === 0 || names.includes(exec?.name)
+    ctx.on('tools/pre-execute', async (exec, next) => {
+      try {
+        if (!matchesTool(exec) || !matchesAgentScope(config, exec?.agent)) return next()
+        const decision = config.params?.preDecision ?? 'allow'
+        if (decision === 'allow') return next()
+        if (decision === 'deny') {
+          return { kind: 'deny', reason: String(config.params?.denyReason ?? `${config.name}: denied by prompt config`) }
+        }
+        if (decision === 'ask') return { kind: 'ask' }
+        return next()
+      } catch (error) {
+        warnOnce(`${name}: tool-pipeline(pre) config ${config.id} failed: ${String(error?.message ?? error)}`)
+        return next()
+      }
+    })
+    ctx.on('tools/post-execute', async (exec, result, next) => {
+      try {
+        if (!matchesTool(exec) || !matchesAgentScope(config, exec?.agent)) return next()
+        const action = config.params?.postAction ?? 'accept'
+        if (action === 'accept') return next()
+        if (action === 'replace' && config.texts.length > 0) {
+          return { kind: 'accept', content: [{ type: 'text', text: config.texts.join('\n\n') }] }
+        }
+        if (action === 'block') {
+          return { kind: 'block', feedback: [{ type: 'text', text: config.texts.length > 0 ? config.texts.join('\n\n') : `${config.name}: blocked by prompt config` }] }
+        }
+        return next()
+      } catch (error) {
+        warnOnce(`${name}: tool-pipeline(post) config ${config.id} failed: ${String(error?.message ?? error)}`)
+        return next()
+      }
+    })
+  }
+}
+
+/** 把非 pre-step 提示词配置接入其声明的官方层级通道。 */
+export function wireLayers(ctx, configs, warnOnce) {
+  wireSystemSections(ctx, configs.filter((config) => config.layer === 'system-section'), warnOnce)
+  wireRuntimeContexts(ctx, configs.filter((config) => config.layer === 'runtime-context'), warnOnce)
+  wireAgentRequests(ctx, configs.filter((config) => config.layer === 'agent-request'), warnOnce)
+  wireLlmStreams(ctx, configs.filter((config) => config.layer === 'llm-stream'), warnOnce)
+  wireToolPipelines(ctx, configs.filter((config) => config.layer === 'tool-pipeline'), warnOnce)
+}

package/engine/prompt-config-engine.mjs

@@ -0,0 +1,49 @@
+/**
+ * prompt-config-engine — prompt-tool 的唯一提示词注入执行器(装配入口)。
+ *
+ * 本文件只做装配:
+ *   - schema.mjs    提示词配置加载/归一化/权威校验
+ *   - strategies.mjs 内置策略绑定 + 模板专属策略懒加载(strategyDir)
+ *   - fillers.mjs   placeholder 动态填充器(instruction-hint / env-facts / skill-catalog)
+ *   - layers.mjs    非 pre-step 五个官方层级接线
+ *   - executor.mjs  pre-step 消息批执行器(过滤/去重/合并/落位)
+ *
+ * agent.cordis.yml 引擎行:
+ *   - id: prompt-config-engine
+ *     name: ./engine/prompt-config-engine.mjs
+ *     config:
+ *       configsDir: ../prompt-configs        # 提示词配置模块目录(相对本文件)
+ *       strategyDir: ../strategies           # 模板专属策略目录(可选,相对本文件)
+ *
+ * 铁律:任一提示词配置失败只跳过该提示词配置并 warnOnce;配置错误挂载时 fail loud。
+ */
+
+import { createPromptConfigs, loadPromptConfigFiles, parsePromptConfigYaml } from './schema.mjs'
+import { applyPromptConfigs } from './executor.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'prompt-config-engine'
+
+/**
+ * 等待全部可注入层级的宿主服务。preset 行在 agent 组合内解析这些服务
+ * (persona 依赖 systemPrompt,工具行依赖 tools,agent loop 依赖 llm)。
+ */
+export const inject = ['systemPrompt', 'tools', 'llm']
+
+export { parsePromptConfigYaml, loadPromptConfigFiles, createPromptConfigs, applyPromptConfigs }
+
+/**
+ * 引擎插件入口:config.configsDir 为提示词配置模块目录(相对本文件的 URL),
+ * config.strategyDir 为模板专属策略目录(可选)。引擎扫描目录内每个
+ * *.yml / *.yaml / *.json 并装配为提示词配置。
+ */
+export function apply(ctx, config) {
+  const dirName = typeof config?.configsDir === 'string' && config.configsDir.length > 0
+    ? config.configsDir
+    : './prompt-configs'
+  const dirUrl = new URL(dirName.endsWith('/') ? dirName : `${dirName}/`, import.meta.url)
+  const strategyDir = typeof config?.strategyDir === 'string' && config.strategyDir.length > 0
+    ? config.strategyDir
+    : undefined
+  applyPromptConfigs(ctx, createPromptConfigs(loadPromptConfigFiles(dirUrl), { strategyDir }), { prepend: true })
+}

package/engine/run-code-env.mjs

@@ -0,0 +1,208 @@
+/**
+ * run-code-env — prompt-tool 的 PTC 环境注入配置。
+ *
+ * 官方 Code Mode 的 worker 线程刻意以 `env: {}` 启动（比普通 shell 的
+ * credential scrub 更严格），因此 run_code 程序里的 `process.env` 恒为空。
+ * 本插件不试图推翻该安全设计，而是在每个 run_code 程序执行前注入一个
+ * 冻结的 `env` 全局：
+ *
+ *   const env = Object.freeze(JSON.parse(<curated json>))
+ *
+ * `env` 的内容只来自三处，且全部经过白名单/敏感名过滤：
+ *   1. 宿主 process.env 中列在 `envKeys` 里的键；
+ *   2. `ctx.shellEnv` 受管快照（DSH_HOME / DSH_SESSION_ID / 插件贡献的 DSH_*）；
+ *   3. 当前会话工作区（DSH_WORKSPACE）。
+ *
+ * 模型侧始终可写 `env.PATH`、`env.HOME`、`env.DSH_HOME` 等；不要读
+ * `process.env`（恒为 {}）。本插件只在存在 run_code 传输的 scope 生效，
+ * native 模式自动空转。
+ */
+
+/** Cordis 插件名，供 loader 诊断使用。 */
+export const name = 'run-code-env'
+
+/** 需要 tools 视图与 systemPrompt 段。shellEnv 为机会型读取，不写进 inject。 */
+export const inject = ['tools', 'systemPrompt']
+
+/** 默认暴露的系统环境变量（无凭据形态）。 */
+export const DEFAULT_ENV_KEYS = [
+  'PATH',
+  'PATHEXT',
+  'HOME',
+  'USERPROFILE',
+  'USERNAME',
+  'COMPUTERNAME',
+  'OS',
+  'TEMP',
+  'TMP',
+  'SystemRoot',
+  'ProgramFiles',
+  'ProgramFiles(x86)',
+  'LOCALAPPDATA',
+  'APPDATA',
+]
+
+/** 任何疑似凭据的名字一律不放行。 */
+export const SENSITIVE_ENV_RE = /KEY|PASSWORD|SECRET|TOKEN/i
+
+/** run_code 定义对象只 patch 一次（跨 HMR 安全）。 */
+const PATCHED = new WeakSet()
+
+/**
+ * 校验 envKeys：非空字符串数组；缺省/空数组回退默认白名单。
+ * 单个键为敏感名时在 buildEnv 阶段过滤，这里只校验形状。
+ */
+export function normalizeEnvKeys(value) {
+  if (value === undefined) return [...DEFAULT_ENV_KEYS]
+  if (!Array.isArray(value) || value.length === 0) return [...DEFAULT_ENV_KEYS]
+  const keys = value.map((key) => (typeof key === 'string' ? key.trim() : ''))
+    .filter((key) => key.length > 0)
+  return keys.length > 0 ? [...new Set(keys)] : [...DEFAULT_ENV_KEYS]
+}
+
+/**
+ * 在 process.env 里按平台语义查找一个键；Windows 大小写不敏感。
+ * @param env - 宿主环境对象（通常是 process.env）
+ * @param key - 期望键名
+ */
+function lookupEnv(env, key) {
+  if (env === undefined || env === null) return undefined
+  if (process.platform === 'win32') {
+    const wanted = key.toUpperCase()
+    const match = Object.keys(env).find((candidate) => candidate.toUpperCase() === wanted)
+    return match === undefined ? undefined : env[match]
+  }
+  return env[key]
+}
+
+/**
+ * 构造本次 run_code 注入的 env 对象。所有来源统一脱敏。
+ * @param ctx - Cordis context（机会型读取 shellEnv）
+ * @param keys - 白名单键
+ * @param agent - 当前执行 agent（可空）
+ */
+export function buildEnv(ctx, keys, agent) {
+  const env = {}
+  const hostEnv = typeof process === 'undefined' ? undefined : process.env
+
+  for (const key of keys) {
+    if (SENSITIVE_ENV_RE.test(key)) continue
+    const value = lookupEnv(hostEnv, key)
+    if (value !== undefined && value !== null) env[key] = String(value)
+  }
+
+  // 受管 DSH_* 快照：shellEnv 不存在或 collect 失败时静默降级。
+  try {
+    const shellEnv = ctx?.get?.('shellEnv')
+    if (shellEnv !== undefined && typeof shellEnv.collect === 'function') {
+      const execution = agent === undefined ? {} : { agent }
+      const managed = shellEnv.collect(execution) ?? {}
+      for (const [key, value] of Object.entries(managed)) {
+        if (typeof value === 'string' && !SENSITIVE_ENV_RE.test(key)) env[key] = value
+      }
+    }
+  } catch {
+    // shellEnv 缺失/失败只意味着没有受管变量，不阻断 PTC。
+  }
+
+  // DSH_HOME 兜底：启动器/宿主进程通常显式设置了 DSH_HOME（本机为
+  // D:\AI\DeepSeek harness\.dsh）。shellEnv 不可用时退回到该值；shellEnv
+  // 已给出受管值时这里不会覆盖。
+  if (env.DSH_HOME === undefined) {
+    const ambientHome = lookupEnv(hostEnv, 'DSH_HOME')
+    if (ambientHome !== undefined && ambientHome !== null && !SENSITIVE_ENV_RE.test('DSH_HOME')) {
+      env.DSH_HOME = String(ambientHome)
+    }
+  }
+
+  const cwd = agent?.session?.header?.cwd
+  if (typeof cwd === 'string' && cwd.length > 0 && !SENSITIVE_ENV_RE.test('DSH_WORKSPACE')) {
+    env.DSH_WORKSPACE = cwd
+  }
+
+  return env
+}
+
+/** 生成注入前缀：JSON 双序列化后作为 JS 字符串字面量安全嵌入。 */
+export function injectEnvPrefix(code, env) {
+  const payload = JSON.stringify(env ?? {}) ?? '{}'
+  const literal = JSON.stringify(payload)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+  return `const env = Object.freeze(JSON.parse(${literal}));\n${code}`
+}
+
+/** 渲染 PTC 提示段；native（无 run_code）返回空串。 */
+function envSectionText(ctx, keys) {
+  const names = [...keys]
+    .filter((key) => !SENSITIVE_ENV_RE.test(key))
+  const sample = names.includes('HOME') ? 'HOME' : names[0]
+  return [
+    '## run_code environment',
+    '',
+    'Inside every run_code program a frozen global `env` is available; `process.env` is always empty by design.',
+    `Available keys: ${names.join(', ') || '(none)'}`,
+    'Managed DSH_* facts (for example DSH_HOME, DSH_SESSION_ID) and DSH_WORKSPACE are also present when the harness provides them.',
+    sample ? `Example: \`const home = env.${sample}\`` : 'Example: const cwd = env.DSH_WORKSPACE',
+    'Read values from `env.*`; never try to read `process.env`.',
+  ].join('\n')
+}
+
+/** 给 run_code 的 ToolDefinition 打补丁：execute 前注入 env 前缀。 */
+export function patchRunCodeTool(tool, ctx, keys) {
+  if (tool === undefined || tool.name !== 'run_code') return false
+  if (PATCHED.has(tool)) return false
+  PATCHED.add(tool)
+
+  const originalExecute = tool.execute.bind(tool)
+  tool.execute = async (rawArgs, exec) => {
+    const args = rawArgs ?? {}
+    const env = buildEnv(ctx, keys, exec?.agent)
+    const code = injectEnvPrefix(typeof args.code === 'string' ? args.code : '', env)
+    return originalExecute({ ...args, code }, exec)
+  }
+  return true
+}
+
+/** 注册 PTC env 注入：只在目标 scope 出现 run_code 时生效。 */
+export function apply(ctx, config) {
+  const source = config === undefined ? {} : config
+  const enabled = source.enabled !== false
+  const keys = normalizeEnvKeys(source.envKeys)
+
+  const tryPatch = (scope) => {
+    if (!enabled) return
+    try {
+      patchRunCodeTool(ctx.tools.get('run_code', scope), ctx, keys)
+    } catch {
+      // run_code 尚未物化或 registry 不可用：下一次 assemble/execute 再试。
+    }
+  }
+
+  // 动态工具变化后，新 scope 的 run_code transport 可能刚创建。
+  ctx.on('tools/change', () => tryPatch())
+
+  // 组装前先确保当前 scope 的 run_code 已 patch（此时 SDK 会引用它）。
+  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
+    tryPatch(context?.scope)
+    return next()
+  })
+
+  // 第一条 run_code 调用是最终兜底：dispatch 前按调用 agent 补 patch。
+  ctx.on('tools/execute', async (exec, next) => {
+    if (enabled && exec?.name === 'run_code') tryPatch(exec.agent)
+    return next()
+  })
+
+  if (enabled) {
+    ctx.systemPrompt.section({
+      name: 'tools:run-code-env',
+      order: 160,
+      text: (context) => {
+        const schemas = ctx.tools.schemas(context?.scope)
+        if (!Array.isArray(schemas) || !schemas.some((schema) => schema?.name === 'run_code')) return ''
+        return envSectionText(ctx, keys)
+      },
+    })
+  }
+}