dsh-plugin-prompt-tool 0.7.2 → 0.8.0

package/engine/prompt-config-engine.mjs

@@ -4,7 +4,8 @@
  * 本文件只做装配:
  *   - schema.mjs    提示词配置加载/归一化/权威校验
  *   - strategies.mjs 内置策略绑定 + 模板专属策略懒加载(strategyDir)
- *   - fillers.mjs   placeholder 动态填充器(instruction-hint / env-facts / skill-catalog)
+ *   - fillers.mjs   placeholder 动态填充器（instruction-hint / env-facts / skill-catalog）
+ *   - instruction-hint.mjs 通用指令文件提示实现（策略与 context-gate 共用）
  *   - layers.mjs    非 pre-step 五个官方层级接线
  *   - executor.mjs  pre-step 消息批执行器(过滤/去重/合并/落位)
  *
@@ -18,8 +19,12 @@
  * 铁律:任一提示词配置失败只跳过该提示词配置并 warnOnce;配置错误挂载时 fail loud。
  */
 
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { createPromptConfigs, loadPromptConfigFiles, parsePromptConfigYaml } from './schema.mjs'
 import { applyPromptConfigs } from './executor.mjs'
+import { defineConfig, passthrough } from './fields.mjs'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'prompt-config-engine'
@@ -32,18 +37,68 @@ export const inject = ['systemPrompt', 'tools', 'llm']
 
 export { parsePromptConfigYaml, loadPromptConfigFiles, createPromptConfigs, applyPromptConfigs }
 
+/** 物化清单里是否仍挂着官方指令加载行（负责人冲突事实）。 */
+const OFFICIAL_INSTRUCTIONS_ROW = /dsh-agent-instructions|(^|\s)id:\s*agent-instructions\b/m
+
+/**
+ * 本 mount 的装配事实：来源 id（协调器注册键，取预设目录名）+ 是否仍挂着官方
+ * 指令行。协调器据此拒绝在官方负责人仍在时同时注入插件指令文件正文。
+ * 引擎直接以源码方式被引用（无物化组合文件）时按未知处理，不声明冲突。
+ */
+function compositionFacts(dirUrl) {
+  try {
+    const dir = new URL('..', dirUrl)
+    return {
+      sourceId: `preset:${basename(fileURLToPath(dir))}`,
+      officialInstructions: OFFICIAL_INSTRUCTIONS_ROW.test(readFileSync(new URL('../agent.cordis.yml', dirUrl), 'utf8')),
+    }
+  } catch {
+    return { sourceId: undefined, officialInstructions: false }
+  }
+}
+
 /**
  * 引擎插件入口:config.configsDir 为提示词配置模块目录(相对本文件的 URL),
  * config.strategyDir 为模板专属策略目录(可选)。引擎扫描目录内每个
  * *.yml / *.yaml / *.json 并装配为提示词配置。
  */
+/**
+ * 配置契约：白名单由字段声明派生（此前没有白名单，未知键被静默忽略）。
+ * 三个键都刻意用 passthrough 保住既有语义——迁移前它们对**非字符串或空串**是静默取默认值
+ * （`typeof x === 'string' && x.length > 0 ? x : 默认`），换成 text() 会把静默降级变成挂载期
+ * 报错，那是 B2 未授权的行为变更。归一化结果与迁移前逐字段一致，唯一新增的是「未知键报错」。
+ *
+ * `presetRoot` 是可选的预设根基准（绝对 file URL）：引擎由插件包提供、不再位于
+ * `<预设根>/.engine/` 时，`templateFile` 的越界校验无法再从引擎位置推导，改由装配期注入。
+ */
+export const configContract = defineConfig({
+  configsDir: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : './prompt-configs')),
+  strategyDir: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : undefined)),
+  presetRoot: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : undefined)),
+})
+
 export function apply(ctx, config) {
-  const dirName = typeof config?.configsDir === 'string' && config.configsDir.length > 0
-    ? config.configsDir
-    : './prompt-configs'
+  const { configsDir: dirName, strategyDir: rawStrategyDir, presetRoot: rawPresetRoot } = configContract.parse(config, name)
   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 })
+  // strategyDir 在入口统一解析成绝对 URL：bindResolver 用 `new URL(x.mjs, strategyDir)`
+  // 懒加载，相对写法的 base 不是合法绝对 URL（ERR_INVALID_URL），会让整行挂载失败。
+  const strategyDir = rawStrategyDir === undefined
+    ? undefined
+    : new URL(rawStrategyDir.endsWith('/') ? rawStrategyDir : `${rawStrategyDir}/`, import.meta.url).href
+  // 预设根基准（可选）：装配期注入绝对 file URL；缺省时由 schema 按「引擎上一级目录」推导。
+  const templatePresetRoot = rawPresetRoot === undefined
+    ? undefined
+    : new URL(rawPresetRoot.endsWith('/') ? rawPresetRoot : `${rawPresetRoot}/`)
+  const facts = compositionFacts(dirUrl)
+  applyPromptConfigs(ctx, createPromptConfigs(loadPromptConfigFiles(dirUrl), {
+    strategyDir,
+    // 注入预设根时（引擎由插件包提供）：相对 templateFile 仍按**历史引擎位置**
+    // `<预设根>/.engine/` 解析，用户预设与提示词配置零改写；越界校验基准则是预设根本身。
+    ...(templatePresetRoot === undefined
+      ? {}
+      : { templateBaseUrl: new URL('.engine/prompt-config-engine.mjs', templatePresetRoot), templatePresetRoot }),
+  }), {
+    prepend: true,
+    ...facts,
+  })
 }

package/engine/run-code-env.mjs

@@ -18,35 +18,14 @@
  * native 模式自动空转。
  */
 
-import { validateConfig } from './shared.mjs'
+import { bool, defineConfig, stringList } from './fields.mjs'
 
 /** Cordis 插件名，供 loader 诊断使用。 */
 export const name = 'run-code-env'
 
-/** Every config key this plugin accepts — anything else is a typo. */
-const ALLOWED_KEYS = new Set(['enabled', 'envKeys'])
-
 /** 需要 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
 
@@ -54,15 +33,52 @@ export const SENSITIVE_ENV_RE = /KEY|PASSWORD|SECRET|TOKEN/i
 const PATCHED = new WeakSet()
 
 /**
- * 校验 envKeys：非空字符串数组；缺省/空数组回退默认白名单。
+ * envKeys 字段：非空字符串数组，逐项 trim 后去重。
+ * 两条消息与迁移前逐字一致：空数组/缺键 → 消息 A（白名单缺失），trim 后为空 → 消息 B。
+ * `allowEmpty: false` 是显式取值——迁移前 `!Array.isArray(value) || value.length === 0`
+ * 一律抛消息 A，空数组不得通过。
+ */
+const ENV_KEYS = stringList({
+  required: true,
+  trim: true,
+  dedupe: true,
+  allowEmpty: false,
+  message: `${name}: envKeys must be a non-empty array of env var names — 白名单归模板/预设，请在本预设或组合源提供`,
+  emptyMessage: `${name}: envKeys must contain at least one non-empty env var name`,
+})
+
+/**
+ * envKeys 声明的 parse 包一层「非字符串项降级为空串」：迁移前的 normalizeEnvKeys 对
+ * `[1, 'PATH']` 是**宽容**的（数字映射成空串后过滤掉，返回 ['PATH']），而 stringList 默认
+ * 对非字符串项 fail loud。B2 硬约束是「除 enabled 外逐字段结果与消息逐字一致」，故保留旧语义。
+ */
+const envKeysField = {
+  kind: 'stringList',
+  parse: (value, plugin, field) => ENV_KEYS.parse(
+    Array.isArray(value) ? value.map((item) => (typeof item === 'string' ? item : '')) : value,
+    plugin,
+    field,
+  ),
+}
+
+/**
+ * 配置契约：字段声明是白名单与逐字段归一化的单一来源（导出供契约对拍测试使用）。
+ * `enabled` 走 fail loud 的布尔开关：未声明 = 关闭（组合源 run-code-env.yml 显式 enabled: true），
+ * 非布尔在挂载期抛 `enabled must be a boolean`。
+ */
+export const configContract = defineConfig({
+  enabled: bool({ default: false }),
+  envKeys: envKeysField,
+})
+
+/**
+ * 校验 envKeys：非空字符串数组；缺失或全空一律 fail loud——暴露哪些变量
+ * 归组合源 / 预设（见 engine/compositions/source/local/run-code-env.yml）。
  * 单个键为敏感名时在 buildEnv 阶段过滤，这里只校验形状。
+ * 导出供测试直接调用；归一化规则归 configContract 的 envKeys 字段（此处不重复实现）。
  */
 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]
+  return envKeysField.parse(value, name, 'envKeys')
 }
 
 /**
@@ -171,9 +187,10 @@ export function patchRunCodeTool(tool, ctx, keys) {
 
 /** 注册 PTC env 注入：只在目标 scope 出现 run_code 时生效。 */
 export function apply(ctx, config) {
-  const source = validateConfig(name, config, ALLOWED_KEYS)
-  const enabled = source.enabled !== false
-  const keys = normalizeEnvKeys(source.envKeys)
+  // 校验入口：未知键 / enabled 非布尔 / envKeys 缺失或全空都在挂载期 fail loud。
+  const source = configContract.parse(config, name)
+  // 开关语义：未声明 = 关闭（组合源为本模块显式写 enabled: true）。
+  const { enabled, envKeys: keys } = source
 
   const tryPatch = (scope) => {
     if (!enabled) return