@master0071/dsh-systemone 0.4.2 → 0.4.3

package/README.md

@@ -305,7 +305,7 @@ const decision = await waterfall('agent/pre-step', {         // ③ 再跑瀑布
     provider: unisound        # unisound / http / mock
     apiKey: ''                # 留空则读环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY
     model: u2-decision
-    customScenarios: ''       # 结构性：需要重启
+    customScenarios: ''       # 热更新：保存后场景库立即重建
     autoDecide: false         # 结构性：需要重启
 ```
 
@@ -332,6 +332,13 @@ const decision = await waterfall('agent/pre-step', {         // ③ 再跑瀑布
 
 也可以在 profile 的 `cordis.patch.yml` 里配置 `customScenarios`（同样的 JSON 字符串）。同 `id` 会覆盖内置场景，否则新增。
 
+覆盖与别名的解析规则：
+
+- **同 `id` 覆盖**：自定义场景替换同名内置场景，只写 `title`/`questions` 也够——被替换场景原有的 `aliases` 会被**继承**（省略 `aliases` 不等于清空别名），新声明的别名与继承的别名共存且自动去重。
+- **别名冲突**：别名与 `id` 平权参与查找，冲突时**后登记者获胜**（自定义场景优先于内置场景，自定义之间后声明者优先）。因此自定义场景声明的别名一定指向它自己，不会被内置场景抢走。
+- **冲突提示**：别名撞名是**非致命**的——场景照常可用，但插件会给出提示（宿主日志里带「（提示）」前缀，`systemone_scenario(action: "list")` 的 `warnings` 字段与「配置提示」小节里也会列出），说明谁遮蔽了谁，避免调用方把「别名被占」误判成「场景不存在」。
+- **查找大小写不敏感**，`findScenario` 同时匹配 `id` 与 `aliases`。
+
 ### 用自定义场景做通用意图识别
 
 SystemOne 是「结构化问题 → 概率分布」的决策模型，**不是开放式意图分类器**：它的标签空间就是你声明的 `criteria`。所以要「通用意图识别」，就自己定义一个意图场景，把标签集写进去，再把「固定场景」指向它：
@@ -425,11 +432,11 @@ SystemOne 是「结构化问题 → 概率分布」的决策模型，**不是开
 
 | 字段 | 必填 | 说明 |
 | --- | --- | --- |
-| `id` | ✅ | 唯一标识 |
+| `id` | ✅ | 唯一标识；首尾空白会被自动 trim |
 | `title` | ✅ | 展示名 |
 | `description` | | 场景说明（`list` 时展示） |
-| `aliases` | | 别名数组，便于按中文名/英文名查找 |
-| `questions` | ✅ | 问题映射，最多 16 个（延迟随问题数线性增长） |
+| `aliases` | | 别名数组，便于按中文名/英文名查找；与 `id` 平权，冲突时自定义场景优先于内置场景。首尾空白自动 trim，空串/纯空白项会被丢弃 |
+| `questions` | ✅ | 问题映射，最多 16 个（延迟随问题数线性增长）。问题 id 不能是 `__proto__` / `constructor` / `prototype` |
 | `derive` | | 派生字段：`{ name: { question, values } }` 或 `{ name: { question, map } }` |
 | `recommendation` | | 建议模板 |
 

package/lib/index.js

@@ -44,7 +44,8 @@ function createProviderProxy(current) {
  *
  * 标了 `.volatile()` 的字段可以在「插件 → @master0071/dsh-systemone → systemone」配置页
  * 里直接修改并立即生效，无需重启；读取时必须经 `unwrap()` 脱壳（见 volatile.js）。
- * 结构性字段（provider 之外的场景库、autoDecide 开关）不在配置页里，改动需重启。
+ * 唯一的非 volatile 字段是 `autoDecide`（结构性：决定装配期要不要挂 pre-step 钩子），
+ * 它不在配置页里，改动需重启。
  */
 const Config = z.object({
   /* ── 热更新字段（volatile）：配置页可直接编辑 ────────────────────────────── */
@@ -52,8 +53,9 @@ const Config = z.object({
   /**
    * 自定义场景：JSON 数组字符串，同 id 覆盖内置场景。
    *
-   * 这是「通用意图识别」的入口——把意图标签集写成 choice 的 criteria 即可，
-   * 场景库会随保存立即重建（见 liveScenarios），无需重启。
+   * 这是「通用意图识别」的入口——把意图标签集写成 choice 的 criteria 即可。
+   * volatile：配置页（client.js 的 CUSTOM_FIELDS）可直接编辑，场景库会随保存
+   * 立即重建（见 liveScenarios），无需重启。
    */
   customScenarios: z.string().default('').volatile(),
   /** 提供商类型：unisound（官方）/ http（SystemOne 兼容端点）/ mock（本地模拟） */
@@ -71,7 +73,7 @@ const Config = z.object({
   /** 置信度阈值：任一答案低于该值则建议人工复核 */
   minConfidence: z.number().min(0).max(1).default(0.6).volatile(),
 
-  /* ── 结构性字段：改动需要重启（不在配置页里） ─────────────────────────────── */
+  /* ── 结构性字段：不在配置页里，改动需要重启 ───────────────────────────────── */
 
   /** 是否在每一步推理前自动捕获上下文并执行决策（挂载 pre-step，改动需重启） */
   autoDecide: z.boolean().default(false),
@@ -128,6 +130,7 @@ export default class SystemOneService extends Service {
     this._scenarioSource = null
     this._scenarioRawValue = undefined
     this.scenarioProblems = []
+    this.scenarioWarnings = []
     this._scenarioArray = []
     this._refreshScenarios()
     const scenarios = this.liveScenarios()
@@ -137,7 +140,11 @@ export default class SystemOneService extends Service {
     if (!tools || typeof tools.register !== 'function') {
       throw new Error('@master0071/dsh-systemone: 工具注册表不可用（inject: [\'tools\'] 未生效）')
     }
-    this._disposers = createTools(this.provider, config, scenarios).map((tool) => tools.register(tool))
+    this._disposers = createTools(this.provider, config, scenarios, {
+      // 惰性读取：场景库可能已随 customScenarios 热更新重建，
+      // 这里必须每次取最新的 warnings，而不是装配期快照。
+      warnings: () => this.scenarioWarnings || [],
+    }).map((tool) => tools.register(tool))
 
     // 自动决策：默认关闭；开启后在每一步推理前自动捕获上下文并注入判断
     this._autoDispose = () => {}
@@ -192,31 +199,57 @@ export default class SystemOneService extends Service {
    * 返回一个 Proxy：任何读取（`.map`、`.length`、`findScenario` 的遍历……）都会
    * 先按需重建，然后转发到真实数组。这样工具与自动决策在装配期捕获一次引用就够，
    * 之后 `customScenarios` 怎么改都能立刻看到新场景。
+   *
+   * 实现要点：**不维护 trap 白名单**，而是统一走 `_forwardTrap()` 转发全部
+   * 内部方法（[[Get]]/[[HasProperty]]/[[OwnPropertyKeys]]/[[GetPrototypeOf]]/
+   * [[IsExtensible]]……）。白名单的毛病是「漏一个就静默读到旧值」——早期版本
+   * 只挂了 get/has/ownKeys/getOwnPropertyDescriptor，`getPrototypeOf` 与
+   * `isExtensible` 就绕过了刷新（`instanceof`、按原型嗅探 `Array.prototype`
+   * 方法的库都会走这两条路），于是同一份引用在不同消费方眼里可能新旧不一。
+   * 补齐 trap 后，将来新增的内部方法也自动覆盖，不需要再回来改这里。
+   *
+   * 注意 `Array.isArray` 是规范内部方法，不经过任何 trap（也无从拦截），
+   * 它靠目标数组本身判定，因此始终正确、无需刷新。
    */
   liveScenarios() {
     if (this._scenarioProxy === undefined) {
+      // 转发全部内部方法：每个 trap 都先刷新，再调用目标数组上的同名方法。
       this._scenarioProxy = new Proxy(this._scenarioArray, {
-        get: (target, prop, receiver) => {
-          this._refreshScenarios()
-          return Reflect.get(target, prop, receiver)
-        },
-        has: (target, prop) => {
-          this._refreshScenarios()
-          return Reflect.has(target, prop)
-        },
-        ownKeys: (target) => {
-          this._refreshScenarios()
-          return Reflect.ownKeys(target)
-        },
-        getOwnPropertyDescriptor: (target, prop) => {
-          this._refreshScenarios()
-          return Reflect.getOwnPropertyDescriptor(target, prop)
-        },
+        get: this._forwardTrap('get'),
+        set: this._forwardTrap('set'),
+        has: this._forwardTrap('has'),
+        deleteProperty: this._forwardTrap('deleteProperty'),
+        ownKeys: this._forwardTrap('ownKeys'),
+        getOwnPropertyDescriptor: this._forwardTrap('getOwnPropertyDescriptor'),
+        defineProperty: this._forwardTrap('defineProperty'),
+        getPrototypeOf: this._forwardTrap('getPrototypeOf'),
+        setPrototypeOf: this._forwardTrap('setPrototypeOf'),
+        isExtensible: this._forwardTrap('isExtensible'),
+        preventExtensions: this._forwardTrap('preventExtensions'),
+        apply: this._forwardTrap('apply'),
+        construct: this._forwardTrap('construct'),
       })
     }
     return this._scenarioProxy
   }
 
+  /**
+   * 生成一个「先刷新、再转发」的 Proxy trap。
+   *
+   * 统一入口而不是逐个手写，保证刷新逻辑只有一份，新增 trap 也不会漏掉刷新。
+   *
+   * @param {PropertyKey} name - Reflect 上的方法名，与 trap 名一一对应
+   * @returns {(...args: unknown[]) => unknown}
+   */
+  _forwardTrap(name) {
+    return (...args) => {
+      // 目标数组恒为 this._scenarioArray（原地改写，引用不变），
+      // 但刷新必须发生在读取之前，否则拿到的是上一版场景。
+      this._refreshScenarios()
+      return Reflect[name](...args)
+    }
+  }
+
   /**
    * 按需重建场景库：`customScenarios` 的原始字符串变了才重建。
    *
@@ -232,14 +265,20 @@ export default class SystemOneService extends Service {
     this._scenarioRawValue = value
     const source = String(value).trim()
     if (source === this._scenarioSource) return
-    const { scenarios, problems } = resolveScenarios(source)
+    const { scenarios, problems, warnings } = resolveScenarios(source)
     this._scenarioArray.length = 0
     this._scenarioArray.push(...scenarios)
     this._scenarioSource = source
     this.scenarioProblems = problems
+    this.scenarioWarnings = warnings
+    // problems=致命（条目已被跳过），warnings=非致命提示（别名遮蔽等，场景仍可用）。
+    // 两者都用 warn 输出，但文案前缀区分，便于一眼看出是否需要处理。
     for (const problem of problems) {
       this.ctx?.logger?.warn?.(`@master0071/dsh-systemone: ${problem}`)
     }
+    for (const warning of warnings) {
+      this.ctx?.logger?.warn?.(`@master0071/dsh-systemone（提示）: ${warning}`)
+    }
   }
 
   /** 列出当前全部场景（内置 + 自定义）。 */

package/lib/scenarios.js

@@ -406,6 +406,12 @@ export function validateScenario(spec) {
   if (ids.length === 0) problems.push('questions 至少需要 1 个问题')
   if (ids.length > 16) problems.push(`questions 最多 16 个（当前 ${ids.length} 个，延迟随问题数线性增长）`)
   for (const [qid, q] of Object.entries(questions)) {
+    if (isUnsafeKey(qid)) {
+      // 提前拦下：这类键在普通对象上会与原型机制冲突（见 normalizeScenario），
+      // 与其在规范化时静默丢弃、产出一个零问题的空场景，不如直接报错。
+      problems.push(`问题 id 不能是 ${qid}（与对象原型机制冲突）`)
+      continue
+    }
     if (!q || typeof q !== 'object') {
       problems.push(`问题 ${qid} 必须是对象`)
       continue
@@ -437,28 +443,50 @@ export function validateScenario(spec) {
  * 从配置的 JSON 字符串加载自定义场景，并与内置场景合并。
  * 同 id 的自定义场景会覆盖内置场景；非法条目被跳过并记入 problems。
  *
+ * 别名解析的正确性由两件事共同保证：
+ *   1. 覆盖内置场景时**继承**被替换者的别名（见下面的 merged），
+ *      避免原场景的中文别名变成查不到的死键；
+ *   2. `findScenario` 采用「后写优先」的倒序匹配（见该函数注释）。
+ *      早期实现用 `Array.find` 正序匹配，等价于「内置永远优先」，
+ *      自定义场景声明的别名会被内置场景静默抢走。
+ *
+ * 返回值分两条通道：
+ *   - `problems`：**致命**问题，对应场景已被跳过（解析失败、字段非法）；
+ *   - `warnings`：**非致命**提示，场景仍然可用，只是别名解析结果需要知会用户
+ *     （例如自定义场景的别名与内置场景撞名——按「后写优先」自定义场景获胜，
+ *     但被遮蔽者从此查不到，应当告知）。分开是因为 warnings 不该让条目被跳过，
+ *     也不该在每次重建时按 problems 的级别刷日志。
+ *
  * @param {string} customJson - 自定义场景 JSON（数组）
- * @returns {{ scenarios: object[], problems: string[] }}
+ * @returns {{ scenarios: object[], problems: string[], warnings: string[] }}
  */
 export function resolveScenarios(customJson) {
   const scenarios = BUILTIN_SCENARIOS.map((s) => ({ ...s, source: 'builtin' }))
   const problems = []
+  const warnings = []
   const raw = typeof customJson === 'string' ? customJson.trim() : ''
-  if (!raw) return { scenarios, problems }
+  if (!raw) return { scenarios, problems, warnings }
 
   let parsed
   try {
     parsed = JSON.parse(raw)
   } catch (error) {
     problems.push(`自定义场景 JSON 解析失败：${messageOf(error)}`)
-    return { scenarios, problems }
+    return { scenarios, problems, warnings }
   }
   if (!Array.isArray(parsed)) {
     problems.push('自定义场景必须是 JSON 数组（[...]）')
-    return { scenarios, problems }
+    return { scenarios, problems, warnings }
   }
 
+  // 仅用于「按 id 判断是覆盖还是新增」；别名解析不经过这里。
   const indexById = new Map(scenarios.map((s, i) => [s.id.toLowerCase(), i]))
+  // 别名 → 当前持有者，仅用于生成遮蔽提示（不参与查找）。
+  const aliasOwner = new Map()
+  scenarios.forEach((s) => {
+    for (const alias of s.aliases || []) aliasOwner.set(alias.toLowerCase(), s.id)
+  })
+
   parsed.forEach((spec, i) => {
     const issues = validateScenario(spec)
     if (issues.length > 0) {
@@ -467,20 +495,69 @@ export function resolveScenarios(customJson) {
     }
     const entry = normalizeScenario(spec)
     const key = entry.id.toLowerCase()
-    if (indexById.has(key)) {
-      scenarios[indexById.get(key)] = entry
-    } else {
+
+    // 别名撞名是一条提示：声明者获胜（后写优先），被遮蔽者从此无法通过该别名查到。
+    // 覆盖内置场景时继承的别名不算撞名——那是同一个场景换了实现。
+    const shadowed = []
+    for (const alias of entry.aliases) {
+      const akey = alias.toLowerCase()
+      // 与自己的 id 同名是无害的（findScenario 两者都会命中自己）
+      if (akey === key) continue
+      const owner = aliasOwner.get(akey)
+      if (owner !== undefined && owner.toLowerCase() !== key) {
+        shadowed.push(`别名「${alias}」原本指向 "${owner}"`)
+      }
+    }
+
+    if (!indexById.has(key)) {
       indexById.set(key, scenarios.length)
       scenarios.push(entry)
+    } else {
+      // 覆盖时继承被替换场景的别名：覆盖者通常只想改 title/questions，
+      // 不该顺手把原场景的中文别名变成查不到的死键（省略 aliases ≠ 清空别名）。
+      const replaced = scenarios[indexById.get(key)]
+      const merged = [...(replaced.aliases || [])]
+      for (const alias of entry.aliases || []) {
+        if (!merged.some((a) => a.toLowerCase() === alias.toLowerCase())) merged.push(alias)
+      }
+      entry.aliases = merged
+      scenarios[indexById.get(key)] = entry
+    }
+
+    // 覆盖已完成，刷新别名归属（继承来的别名也一并登记）
+    for (const alias of entry.aliases || []) aliasOwner.set(alias.toLowerCase(), entry.id)
+
+    if (shadowed.length > 0) {
+      warnings.push(
+        `自定义场景 "${entry.id}" 的别名与已有场景冲突，按「自定义优先」解析到 "${entry.id}"`
+        + `（被遮蔽者不再能通过该别名查到）：${shadowed.join('；')}`,
+      )
     }
   })
-  return { scenarios, problems }
+  return { scenarios, problems, warnings }
 }
 
-/** 规范化场景定义，补齐可选字段。 */
+/**
+ * 规范化场景定义，补齐可选字段。
+ *
+ * 两处规范化是**必要**的，不是美化：
+ *
+ * 1. `id` / `aliases` 一律 trim。`validateScenario` 只用 trim 判空，
+ *    若这里原样存，而 `findScenario` 又会 trim 查询值，两边就不对称——
+ *    `id: '  legal\n'` 能通过校验、能出现在 list 里，却连用自己的原值都查不到，
+ *    且想覆盖内置场景时只会新增一个永久查不到的副本。
+ *    trim 后 `indexById` / `aliasOwner` / 去重比较的 key 也与存储值一致。
+ *
+ * 2. `questions` 用 `Object.create(null)` 建，并跳过 `__proto__` 这类危险键。
+ *    普通对象上 `questions['__proto__'] = q` 走的是 [[Set]]，改的是**原型**而不是
+ *    添加属性；而 `Object.keys()` 又能看到 `__proto__` 这个自有键，
+ *    于是「至少 1 个问题」的校验会通过、却产出 0 个问题的空场景，
+ *    下游 run 静默返回 ok + 空 answers。无原型的对象天然免疫这类键。
+ */
 function normalizeScenario(spec) {
-  const questions = {}
+  const questions = Object.create(null)
   for (const [qid, q] of Object.entries(spec.questions)) {
+    if (isUnsafeKey(qid)) continue
     const question = {
       type: q.type,
       instructions: String(q.instructions ?? ''),
@@ -496,10 +573,12 @@ function normalizeScenario(spec) {
     questions[qid] = question
   }
   return {
-    id: spec.id,
+    id: spec.id.trim(),
     title: spec.title,
     description: typeof spec.description === 'string' ? spec.description : '',
-    aliases: Array.isArray(spec.aliases) ? spec.aliases.filter((a) => typeof a === 'string') : [],
+    aliases: Array.isArray(spec.aliases)
+      ? spec.aliases.filter((a) => typeof a === 'string').map((a) => a.trim()).filter(Boolean)
+      : [],
     questions,
     derive: spec.derive && typeof spec.derive === 'object' ? spec.derive : {},
     recommendation: typeof spec.recommendation === 'string' ? spec.recommendation : '',
@@ -508,16 +587,39 @@ function normalizeScenario(spec) {
   }
 }
 
+/**
+ * 判断一个键名是否会与对象内部机制冲突（原型污染类键）。
+ *
+ * `__proto__` 在普通对象上是访问器而非普通属性，赋值会改原型；
+ * `constructor` / `prototype` 虽然赋值本身无害，但没有理由作为问题 id，
+ * 一并拒绝以免下游做 `Object.prototype` 相关操作时踩坑。
+ */
+function isUnsafeKey(key) {
+  return key === '__proto__' || key === 'constructor' || key === 'prototype'
+}
+
 /**
  * 按 id 或别名查找场景（大小写不敏感）。
+ *
+ * 匹配顺序与 `resolveScenarios` 的登记顺序保持一致——**必须倒序**遍历：
+ * 后登记的场景在后，覆盖关系由下标大小体现，倒序即「后写优先」。
+ *
+ * 早期实现用 `Array.find` 正序匹配，等价于「内置永远优先」，于是自定义场景
+ * 声明的别名一旦与内置场景撞名，就会被内置场景静默抢走——场景就在库里，
+ * 却永远查不到。
+ *
  * @returns {object | undefined}
  */
 export function findScenario(scenarios, id) {
   if (typeof id !== 'string' || !id.trim()) return undefined
   const needle = id.trim().toLowerCase()
-  return scenarios.find(
-    (s) => s.id.toLowerCase() === needle || (s.aliases || []).some((a) => a.toLowerCase() === needle),
-  )
+  for (let i = scenarios.length - 1; i >= 0; i--) {
+    const s = scenarios[i]
+    if (!s) continue
+    if (String(s.id).toLowerCase() === needle) return s
+    if ((s.aliases || []).some((a) => String(a).toLowerCase() === needle)) return s
+  }
+  return undefined
 }
 
 function messageOf(err) {

package/lib/tools.js

@@ -20,17 +20,26 @@ import { readNumber, readString } from './volatile.js'
 
 const DEFAULT_MIN_CONFIDENCE = 0.6
 
-/** 创建全部工具定义。 */
-export function createTools(provider, config, scenarios) {
+/**
+ * 创建全部工具定义。
+ *
+ * @param {object} provider - 提供商
+ * @param {object} config - 插件配置
+ * @param {object[]} scenarios - 场景库（活引用）
+ * @param {object} [hooks] - 可选运行时钩子
+ * @param {() => string[]} [hooks.warnings] - 读取当前非致命提示（如别名遮蔽），
+ *   用于让 `action=list` 把「哪个别名被抢走了」告诉模型，而不只是写进宿主日志。
+ */
+export function createTools(provider, config, scenarios, hooks = {}) {
   return [
-    scenarioTool(provider, config, scenarios),
+    scenarioTool(provider, config, scenarios, hooks),
     decideTool(provider, config),
   ]
 }
 
 /* ─── 1. 场景调度工具 ─────────────────────────────────────────────────────── */
 
-function scenarioTool(provider, config, scenarios) {
+function scenarioTool(provider, config, scenarios, hooks = {}) {
   return {
     name: 'systemone_scenario',
     description: [
@@ -74,7 +83,7 @@ function scenarioTool(provider, config, scenarios) {
       const action = args.action || 'run'
 
       if (action === 'list') {
-        return listScenarios(scenarios, args.keyword)
+        return listScenarios(scenarios, args.keyword, readWarnings(hooks))
       }
       if (action === 'describe') {
         return describeScenario(scenarios, args.scenario)
@@ -98,7 +107,17 @@ function scenarioTool(provider, config, scenarios) {
   }
 }
 
-function listScenarios(scenarios, keyword) {
+/** 安全读取钩子里的提示列表：钩子缺失或抛错都不应影响 list。 */
+function readWarnings(hooks) {
+  try {
+    const value = hooks?.warnings?.()
+    return Array.isArray(value) ? value : []
+  } catch {
+    return []
+  }
+}
+
+function listScenarios(scenarios, keyword, warnings = []) {
   const needle = typeof keyword === 'string' ? keyword.trim().toLowerCase() : ''
   const items = scenarios
     .filter((s) => {
@@ -120,11 +139,23 @@ function listScenarios(scenarios, keyword) {
   const summary = [
     `## SystemOne 场景库（${items.length} 个）`,
     ...items.map((s) => `- **${s.id}**：${s.title} — ${s.question_count} 个问题（${s.questions.join('，')}）`),
+    // 别名遮蔽提示只在 list 时给出：它影响「用别名能否调到这个场景」，
+    // 不说的话调用方会以为是场景不存在，而不是别名被别的场景占了。
+    ...(warnings.length > 0
+      ? ['', '### 配置提示', ...warnings.map((w) => `- ${w}`)]
+      : []),
     '',
     '用 action=describe 查看某场景的问题定义，用 action=run 执行决策。',
   ].join('\n')
 
-  return { ok: true, action: 'list', count: items.length, scenarios: items, summary }
+  return {
+    ok: true,
+    action: 'list',
+    count: items.length,
+    scenarios: items,
+    ...(warnings.length > 0 ? { warnings } : {}),
+    summary,
+  }
 }
 
 function describeScenario(scenarios, id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@master0071/dsh-systemone",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "DeepSeek Harness 插件：将 SystemOne 决策模型（默认云知声 u2-decision，可切换提供商）接入软件开发、客服、内容审核、路由、销售线索、风控、招聘、数据治理、教育、需求变更等 10 大业务场景，为 Agent 返回带概率分布的决策与处置建议。",
   "license": "MIT",
   "type": "module",