dsh-plugin-prompt-tool 0.7.2 → 0.8.1

package/engine/fields.mjs

@@ -0,0 +1,219 @@
+/**
+ * fields — 配置字段类型系统（B2 配置契约统一的底座）。
+ *
+ * 把「每个模块自己写白名单、自己写归一化、自己决定缺省语义」收敛为
+ * 「一份字段声明 + 一个校验运行时」：
+ *
+ *   const { allowedKeys, parse } = defineConfig({
+ *     enabled: bool({ default: false }),
+ *     envKeys: stringList({ trim: true, dedupe: true, message: '...', emptyMessage: '...' }),
+ *   })
+ *   const config = parse(source, name)   // 未知键 / 类型错 / 缺必填一律 fail loud
+ *
+ * 硬约束（B2）：**逐字段的校验结果与错误消息必须与迁移前逐字一致**，
+ * 唯一允许的行为变更是 `enabled` 的 fail loud（见 PLAN T3）。因此：
+ *   - 缺省语义由每个字段**显式声明**，不再有隐式 `undefined` / `[]` / `new Set()` 的混用；
+ *   - 底层复用 shared.mjs 的既有 helper（`booleanOption` / `requiredInt` / `requiredText` /
+ *     `validateConfig`），不复制它们的逻辑，默认消息也就自动逐字相同；
+ *   - 模块需要用别的措辞时，用 `message` / `emptyMessage` 覆盖（模板里的 `{plugin}`、
+ *     `{field}` 会被替换）。
+ *
+ * 字段类型与它替代的历史 helper：
+ *   bool(...)        ← booleanOption                        （缺省 → default）
+ *   int({min,...})   ← requiredInt / optionalPositiveInt     （required 缺键即抛）
+ *   text(...)        ← requiredText / requiredStageField     （requiredText 的空串 → undefined）
+ *   stringList(...)  ← nameSet / allowKindList / sourceList / deferredList / stringList /
+ *                      stringListOrEmpty / normalizeEnvKeys（返回数组或 Set、可选 dedupe/trim）
+ *   enumOf(...)      ← 枚举白名单（如 promoteOn 一族）
+ */
+
+import { booleanOption, requiredInt, requiredText, validateConfig } from './shared.mjs'
+
+/** 把 `{plugin}` / `{field}` 占位替换进消息模板。 */
+const format = (template, plugin, field) =>
+  String(template).replaceAll('{plugin}', plugin).replaceAll('{field}', field)
+
+/**
+ * 缺省值解析：`default` 既可以是值，也可以是**工厂函数**。
+ * 工厂形态是必要的 —— 像 `new Set()` / `[]` 这种可变默认值若被多次 parse 共享，
+ * 调用方一旦 mutate 就会串味到别的会话。
+ */
+const resolveDefault = (fallback) => (typeof fallback === 'function' ? fallback() : fallback)
+
+/** 字段公共形状：每个字段都提供 parse(value, plugin, field)。 */
+const makeField = (spec) => {
+  if (spec === null || typeof spec !== 'object' || typeof spec.parse !== 'function') {
+    throw new TypeError('fields: a field must be produced by bool()/int()/text()/stringList()/enumOf()')
+  }
+  return spec
+}
+
+/** 布尔开关：缺省返回 default；非布尔一律 fail loud。 */
+export function bool({ default: fallback = false, message } = {}) {
+  return makeField({
+    kind: 'bool',
+    default: fallback,
+    parse: (value, plugin, field) => {
+      if (message === undefined) return booleanOption(plugin, value, field, resolveDefault(fallback))
+      if (value === undefined) return resolveDefault(fallback)
+      if (typeof value !== 'boolean') throw new TypeError(format(message, plugin, field))
+      return value
+    },
+  })
+}
+
+/**
+ * 整数：`required: true` 时缺键即抛（消息与 shared.requiredInt 逐字一致）；
+ * 否则缺键返回 default。`max` 只在声明了才检查。
+ */
+export function int({ min = 0, default: fallback, required = false, message } = {}) {
+  if (!Number.isSafeInteger(min)) throw new TypeError('fields: int({min}) must be a safe integer')
+  return makeField({
+    kind: 'int',
+    default: fallback,
+    parse: (value, plugin, field) => {
+      // 缺键的 required 错误交给 requiredInt 生成，消息逐字相同。
+      if (value === undefined) {
+        if (required) requiredInt(plugin, value, field, min)
+        return resolveDefault(fallback)
+      }
+      // 不设 max：engine 里 11 处 requiredInt 调用全部只传最小值，上限语义零需求（YAGNI）。
+      // message 只在需要偏离 requiredInt 默认措辞时使用。
+      if (message !== undefined) {
+        if (!Number.isSafeInteger(value) || value < min) throw new TypeError(format(message, plugin, field))
+        return value
+      }
+      return requiredInt(plugin, value, field, min)
+    },
+  })
+}
+
+/**
+ * 文本：
+ *  - `required: true` 走 shared.requiredText —— 非字符串抛、**空串返回 undefined**
+ *    （「空串 = 显式留空」是既有语义，调用方据此跳过注册）；
+ *  - `allowEmpty: false` 时空串按错值处理（对应 tool-bootstrap 的 requiredStageField）；
+ *  - 否则缺键返回 default。
+ */
+export function text({ required = false, default: fallback, allowEmpty = true, message } = {}) {
+  return makeField({
+    kind: 'text',
+    default: fallback,
+    parse: (value, plugin, field) => {
+      // required 且未覆盖消息、且不需要"空串即错"时，**完全委托** requiredText：
+      // 非字符串抛它自己的消息（含中文后缀）、空串返回 undefined —— 与迁移前逐字相同。
+      if (required && message === undefined && allowEmpty) return requiredText(plugin, value, field)
+      if (value === undefined) {
+        if (required) requiredText(plugin, value, field)
+        return resolveDefault(fallback)
+      }
+      if (typeof value !== 'string') {
+        throw new TypeError(message === undefined
+          ? `${plugin}: ${field} must be a string`
+          : format(message, plugin, field))
+      }
+      if (!allowEmpty && value.length === 0) {
+        throw new TypeError(message === undefined
+          ? `${plugin}: ${field} must be a non-empty string`
+          : format(message, plugin, field))
+      }
+      // requiredText 的空串契约：显式留空 → undefined，由调用方跳过注册。
+      return required && value.length === 0 ? undefined : value
+    },
+  })
+}
+
+/**
+ * 字符串列表：
+ *  - `required: true` 时缺键即抛；否则缺键返回 default（可给工厂，如 `() => new Set()`）；
+ *  - 形状错误（非数组 / 含非字符串 / 含空串）抛 `message`；
+ *  - `trim: true` 先修剪再**丢弃**空项（normalizeEnvKeys 的语义），修剪后为空抛 `emptyMessage`；
+ *  - 空数组在 `allowEmpty: false` 时抛 `emptyMessage ?? message`；
+ *  - `as: 'set'` 返回 Set（nameSet / allowKindList / sourceList / deferredList 的形态）。
+ */
+export function stringList({
+  required = false, default: fallback, dedupe = false, trim = false,
+  allowEmpty = false, as = 'array', message, emptyMessage,
+} = {}) {
+  const shapeTemplate = message ?? '{plugin}: {field} must be an array of non-empty strings'
+  const emptyTemplate = emptyMessage ?? shapeTemplate
+  return makeField({
+    kind: 'stringList',
+    default: fallback,
+    parse: (value, plugin, field) => {
+      if (value === undefined) {
+        if (required) throw new TypeError(format(shapeTemplate, plugin, field))
+        return resolveDefault(fallback)
+      }
+      if (!Array.isArray(value)) throw new TypeError(format(shapeTemplate, plugin, field))
+      // 空数组是**形状**问题，与「给出了但被 trim 丢光」是两回事：normalizeEnvKeys 对 [] 与
+      // ['  '] 给的是两条不同消息，必须能分别表达。
+      if (value.length === 0 && !allowEmpty) throw new TypeError(format(shapeTemplate, plugin, field))
+      const items = []
+      for (const item of value) {
+        if (typeof item !== 'string') throw new TypeError(format(shapeTemplate, plugin, field))
+        const trimmed = trim ? item.trim() : item
+        if (trimmed.length === 0) {
+          // trim 模式下空项是「被丢弃的噪声」；非 trim 模式下空串是形状错误。
+          if (trim) continue
+          throw new TypeError(format(shapeTemplate, plugin, field))
+        }
+        items.push(trimmed)
+      }
+      if (items.length === 0 && !allowEmpty) throw new TypeError(format(emptyTemplate, plugin, field))
+      const list = dedupe ? [...new Set(items)] : items
+      return as === 'set' ? new Set(list) : list
+    },
+  })
+}
+
+/**
+ * 直通字段：**只登记白名单**，值的归一化交给模块自己的 parse —— 用于旧代码里刻意存在的
+ * 「非法值即静默取默认」语义（如 `typeof x === 'string' && x.length > 0 ? x : 默认值`）。
+ * 换用严格字段类型会把这些静默降级变成挂载期报错，而那是 B2 未授权的行为变更，
+ * 所以这类键一律用 passthrough 保住原语义，并在模块里注明依据。
+ */
+export function passthrough(parse, { default: fallback } = {}) {
+  if (typeof parse !== 'function') throw new TypeError('fields: passthrough(parse) requires a function')
+  return makeField({ kind: 'passthrough', default: fallback, parse })
+}
+
+/** 枚举：值必须落在 `values` 里；`required: true` 时缺键即抛。 */
+export function enumOf(values, { default: fallback, required = false, message } = {}) {
+  const allowed = [...values]
+  if (allowed.length === 0) throw new TypeError('fields: enumOf(values) must not be empty')
+  const template = message ?? `{plugin}: {field} must be one of ${allowed.map((item) => JSON.stringify(item)).join(', ')}`
+  return makeField({
+    kind: 'enum',
+    default: fallback,
+    parse: (value, plugin, field) => {
+      if (value === undefined) {
+        if (required) throw new TypeError(format(template, plugin, field))
+        return resolveDefault(fallback)
+      }
+      if (!allowed.includes(value)) throw new TypeError(format(template, plugin, field))
+      return value
+    },
+  })
+}
+
+/**
+ * 由字段声明派生 `{ allowedKeys, parse }`：
+ *  - `allowedKeys` 取代手写 `ALLOWED_KEYS`（未知键的报错格式沿用 shared.validateConfig）；
+ *  - `parse(source, plugin)` 先做信封校验再逐字段归一化，返回**只含声明键**的对象。
+ */
+export function defineConfig(fields) {
+  if (fields === null || typeof fields !== 'object' || Array.isArray(fields)) {
+    throw new TypeError('fields: defineConfig(fields) requires an object of field declarations')
+  }
+  const entries = Object.entries(fields)
+  for (const [key, spec] of entries) makeField(spec)
+  const allowedKeys = new Set(entries.map(([key]) => key))
+  const parse = (source, plugin) => {
+    const config = validateConfig(plugin, source, allowedKeys)
+    const normalized = {}
+    for (const [key, spec] of entries) normalized[key] = spec.parse(config[key], plugin, key)
+    return normalized
+  }
+  return { allowedKeys, parse, fields }
+}

package/engine/fillers.mjs

@@ -3,152 +3,19 @@
  * 全部遵循同一铁律:服务缺失或列表失败时返回 null(跳过该配置),绝不伤及会话。
  */
 
-import { readFileSync } from 'node:fs'
 import { getService, parseToolNames } from './shared.mjs'
+import { createInstructionHintResolver } from './instruction-hint.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()。
+ * params.envKeys 逗号分隔环境变量白名单：取值归模板/预设，留空 = 不附加宿主环境
+ * 变量（CWD/WORKSPACE 仍由会话事实提供）。
  * 返回 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')
+  const keys = parseToolNames(typeof config.params?.envKeys === 'string' ? config.params.envKeys : '')
   return ({ agent }) => {
     const session = agent?.session
     const cwd = session?.header?.cwd ?? process.cwd()
@@ -182,10 +49,14 @@ function createSkillCatalogResolver(config) {
     .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
-    : '当前没有可用技能。'
+  // 空结果提示文案归模板/预设：留空且 emptyBehavior=text 时按 skip 处理（不注入空消息）。
+  const emptyText = typeof config.params?.emptyText === 'string' ? config.params.emptyText : ''
   let warned = false
+  // 保留本地 warnOnce：本工厂只拿得到 config，ctx 要到每次 resolve 调用时才由
+  // 参数传入；换成 shared 的 createWarnOnce(ctx, name) 必须改工厂签名，而唯一
+  // 调用点 engine/strategies.mjs 的 createPlaceholderResolver(config) 不在本支
+  // 写区。为替换而扩大改动面违反 PLAN，故此处按原语义手写（一次性 + logger
+  // 不可用时不抛）。
   const warnOnceLocal = (ctx, message) => {
     if (warned) return
     warned = true
@@ -214,7 +85,7 @@ function createSkillCatalogResolver(config) {
         : visible.filter((skill) => providers.includes(skill?.provider))
       const total = scoped.length
       if (total === 0) {
-        if (emptyBehavior !== 'text') return null
+        if (emptyBehavior !== 'text' || emptyText.length === 0) return null
         return { text: emptyText, variables: { SKILL_COUNT: '0', SKILL_NAMES: '', SKILLS_TEXT: '' } }
       }
 

package/engine/host-package.mjs

@@ -0,0 +1,51 @@
+/**
+ * host-package — 从运行中的 DSH 宿主入口解析宿主侧包。
+ *
+ * 全局 dsh 常以 junction/symlink 暴露（npm-global/@deepseek-ai/dsh → 真实包目录），
+ * 而 pnpm 在包内建立的相对 symlink 只在真实路径下可解析：沿 junction 路径用
+ * createRequire(process.argv[1]) 解析会得到 Cannot find module '@deepseek-ai/dsh-tools'。
+ * 入口先取 realpath，再回退原路径与引擎自身，两种安装形态都能解析到同一份宿主依赖。
+ */
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+/**
+ * 按优先级列出 createRequire 的解析基准：真实入口 → 原始入口 → 引擎文件自身。
+ * @param {string|undefined} entry 宿主入口路径（默认 process.argv[1]）。
+ * @param {string|undefined} self 引擎文件路径（默认 import.meta.url）。
+ * @returns {string[]} 去重后的基准列表。
+ */
+export function hostResolutionBases(entry = process.argv[1], self = fileURLToPath(import.meta.url)) {
+  const bases = []
+  const push = (value) => {
+    if (typeof value === 'string' && value.length > 0 && !bases.includes(value)) bases.push(value)
+  }
+  if (typeof entry === 'string' && entry.length > 0) {
+    try { push(realpathSync(entry)) } catch { /* 入口不存在（测试/嵌入式）时退回原路径 */ }
+    push(entry)
+  }
+  push(self)
+  return bases
+}
+
+/**
+ * 解析宿主侧包 id。
+ * @param {string} id 包名（如 '@deepseek-ai/dsh-tools'）。
+ * @param {string|undefined} entry 宿主入口路径。
+ * @param {string|undefined} self 引擎文件路径。
+ * @returns {string} 解析到的绝对文件路径。
+ * @throws 全部基准都解析失败时抛出，并列出已尝试的基准。
+ */
+export function resolveHostPackage(id, entry, self) {
+  const bases = hostResolutionBases(entry, self)
+  for (const base of bases) {
+    try { return createRequire(base).resolve(id) } catch { /* 下一个基准 */ }
+  }
+  throw new Error(`prompt-tool: cannot resolve ${id} from host entry (tried: ${bases.join(', ')})`)
+}
+
+/** 动态 import 宿主侧包，返回其命名空间。 */
+export async function importHostPackage(id, entry, self) {
+  return import(pathToFileURL(resolveHostPackage(id, entry, self)).href)
+}