@master0071/dsh-systemone 0.5.0 → 0.6.0

package/lib/auto.js

@@ -25,22 +25,48 @@
  * 安全约束（任何一条不满足都直接放行，绝不阻塞会话）：
  *   - 默认关闭（config.autoDecide = false）
  *   - 超时（autoTimeoutMs）与失败一律 fail-open
- *   - 相同 state 走缓存（autoCacheTtlMs），并发相同 state 走 in-flight 去重
+ *   - 相同 state 且决策参数未变时走缓存（autoCacheTtlMs），并发相同 state 走 in-flight 去重
  *   - 只在"本轮有新用户消息"时触发，工具结果步骤不触发
- *   - 跳过斜杠命令、跳过本插件自己注入的运行时上下文
+ *   - 跳过斜杠命令、跳过本插件自己注入的决策消息（按 INJECTED_SOURCE 识别）
  */
 import { runScenarioDecision } from './tools.js'
-import { findScenario } from './scenarios.js'
+import { MAX_CHOICE_OPTIONS, findScenario } from './scenarios.js'
+import { recordUsage } from './usage.js'
 import { readBoolean, readNumber, readString } from './volatile.js'
 
-/** 宿主运行时上下文使用的 source.kind（见 dsh-agent-loop 的 SOURCE 常量）。 */
-const RUNTIME_CONTEXT_SOURCE = 'runtime-context'
+/**
+ * 本插件注入消息的 source.kind —— **必须用自己的 kind，绝不能复用宿主的 `runtime-context`**。
+ *
+ * 宿主 `@deepseek-ai/dsh-agent-loop` 的 RuntimeContextProjection 只凭
+ * `message.source.kind === 'runtime-context'` 判定"这是我自己写的动态上下文快照"
+ * （runtime-context.ts 的 `isOwned()`），并据此维护 `retained`（上一条自有快照的
+ * 序号与文本），用来决定下一步要不要再追加一条：
+ *
+ *   if (event.type === 'user/message' && isOwned(event.data)) this.retained = {...}
+ *   if (this.retained?.text === snapshot) return          // 未变则不追加
+ *   return [{ message: ..., intent: { surfaceOp: 'append' } }]
+ *
+ * 复用该 kind 的后果（本插件 v0.5.0 及更早版本的缺陷）：
+ *   1. 每一步注入都把宿主的 retained 覆写成决策文本，于是宿主发现
+ *      retained.text !== 自己渲染的上下文，**再追加一条冗余快照**；
+ *   2. 会话恢复时宿主倒序扫描，会把本插件的最新决策消息误认成自己保留的快照；
+ *   3. 宿主还有 CLEARED 归一化逻辑，任何按该 kind 过滤/替换的宿主代码都会误伤。
+ *
+ * 宿主 llm/message.ts 把 MessageSourceMap 定义为 merge-extensible：
+ * "each producer declares its own `kind` in its own module; there is no shared
+ * catch-all `plugin` kind"。首方同类插件（time-context / tmux-context）同样各用
+ * 自己的 kind。本常量同时用于**写入**注入消息与**读取**时的自我排除，两者必须一致。
+ */
+const INJECTED_SOURCE = 'systemone-decision'
 
 /** 自动决策结果缓存的最大条目数；达到后先清过期再按插入序淘汰最旧。 */
 const MAX_AUTO_CACHE = 200
 
-/** 当前请求注入 state 的最大字符数（历史逐条限 2000，这里限制本轮原文）。 */
-const MAX_CURRENT_CHARS = 8000
+/** 当前请求注入 state 的最大字符数（历史逐条限 HISTORY_CHARS_PER_MESSAGE，这里限制本轮原文）。 */
+export const MAX_CURRENT_CHARS = 8000
+
+/** 历史消息**每条**进入 state 的最大字符数（index.js 的外发声明预算同源引用）。 */
+export const HISTORY_CHARS_PER_MESSAGE = 2000
 
 /** 自动决策数字配置的兜底默认值（与 lib/index.js Config schema 的 default 保持同一份来源）。 */
 export const AUTO_DEFAULTS = {
@@ -52,6 +78,11 @@ export const AUTO_DEFAULTS = {
   autoMinChars: 4,
 }
 
+/** fail-closed 档判定：closed 只对"本应得到决策却没有"的真失败生效（见各调用点）。 */
+function isFailClosed(config) {
+  return readString(config, 'autoFailMode', 'open') === 'closed'
+}
+
 /**
  * 安装自动决策。返回卸载函数。
  *
@@ -60,7 +91,7 @@ export const AUTO_DEFAULTS = {
  * @returns {() => void}
  */
 export function installAutoDecide(ctx, deps) {
-  const { provider, config, scenarios, logger } = deps
+  const { provider, config, scenarios, logger, usage } = deps
   if (!readBoolean(config, 'autoDecide', false)) return () => {}
 
   const disposers = []
@@ -70,9 +101,9 @@ export function installAutoDecide(ctx, deps) {
   const perAgent = new Map()
   /** agentId → 上次注入的决策文本：同一决策只注入一次，避免每步重复污染历史。 */
   const lastInjected = new Map()
-  /** stateHash → { at, result }：避免同一内容重复请求。 */
+  /** 决策 key（state + 决策指纹）→ { at, result }：避免同一内容在同一配置下重复请求。 */
   const cache = new Map()
-  /** stateHash → Promise：并发相同 state 只发一次上游请求。 */
+  /** 决策 key → Promise：并发相同 state 且同配置时只发一次上游请求。 */
   const inFlight = new Map()
   /** 已告警过的无效固定场景 id：同一错误只提示一次，避免每步刷日志。 */
   const warnedScenarios = new Set()
@@ -208,6 +239,7 @@ export function installAutoDecide(ctx, deps) {
             signal: timeout.signal,
             log,
             warnedScenarios,
+            usage,
           }),
           timeoutMs,
         )
@@ -215,6 +247,12 @@ export function installAutoDecide(ctx, deps) {
         timeout.dispose()
       }
     } catch (error) {
+      // fail-closed 档：决策管线失败 = 本轮没有可用决策，按 closed 语义否决
+      // （宿主把 turn 记为 blocked）。open 档维持注入语义：记 warning 放行。
+      if (isFailClosed(config)) {
+        log('warn', `自动决策失败，fail-closed 拦截本轮：${messageOf(error)}`)
+        return { kind: 'reject' }
+      }
       log('warn', `自动决策失败，已放行：${messageOf(error)}`)
       return decision
     }
@@ -259,6 +297,7 @@ export function installAutoDecide(ctx, deps) {
             signal: timeout.signal,
             log,
             warnedScenarios,
+            usage,
           }),
           timeoutMs,
         )
@@ -300,11 +339,62 @@ export function installAutoDecide(ctx, deps) {
 /* ─── 决策流程 ─────────────────────────────────────────────────────────────── */
 
 /**
- * 计算决策（带并发去重）。相同 state 只发一次上游请求。
+ * 决策指纹：把**影响决策结果的全部配置**压成一个短字符串。
+ *
+ * 缓存与 in-flight 去重的 key 必须是 `hashString(state + 指纹)`，不能只哈希 state
+ * ——否则用户在配置页改了「固定场景」、切了 model/provider、或调了两个置信度门槛后，
+ * 最长 autoCacheTtlMs（默认 60 秒）内仍会继续注入**旧场景的旧结论**，与
+ * "保存即生效、无需重启"的承诺直接冲突。
+ *
+ * 指纹含 `scenariosRef`：场景库本身也是热更新的（customScenarios），而自动路由的
+ * 结果是一个场景 id；若期间删除/改名了该场景，旧的路由结论会指向已不存在的场景，
+ * 表现为"决策突然不注入了"。把场景库指纹纳入 key 让这种变更立即失效。
+ *
+ * 刻意**不含** `autoTimeoutMs` / `autoCacheTtlMs` / `autoMaxMessages`：
+ *   - 前两个只影响等待与缓存寿命，不影响判定内容，纳入只会让改超时白白清空缓存；
+ *   - autoMaxMessages 已通过 state 文本体现（改变条数就会改变 state）。
+ *
+ * provider 用实例的 `name`（它本身由 provider 配置派生），model / 门槛现读现取，
+ * 因此本函数必须**在每次决策时调用**，而不能在装配期算一次。
+ *
+ * @param {object} config - 插件配置（volatile 字段经 readString/readNumber 脱壳）
+ * @param {object} provider - 当前提供商实例
+ * @param {string} scenariosRef - 场景库指纹（见 scenariosFingerprint）
+ * @returns {string} 形如 `customer_service|unisound|u2-decision|0.6|0.35|11:customer_service,…`
+ */
+function decisionFingerprint(config, provider, scenariosRef) {
+  return [
+    readString(config, 'autoScenario', ''),
+    readString(provider, 'name', ''),
+    readString(config, 'model', ''),
+    String(readNumber(config, 'autoMinConfidence', AUTO_DEFAULTS.autoMinConfidence)),
+    String(readNumber(config, 'autoRouteMinConfidence', AUTO_DEFAULTS.autoRouteMinConfidence)),
+    scenariosRef,
+  ].join('|')
+}
+
+/**
+ * 场景库指纹：场景总数 + 每个场景的 `id:title`。
+ *
+ * 自定义场景是热更新的，改一个别名/加一个场景都会让自动路由的候选集变化。
+ * 用这个便宜字符串（远小于任何一次上游请求）换取"配置一改、缓存立即失效"。
+ *
+ * @param {object[]} scenarios - 场景库（活引用）
+ * @returns {string}
+ */
+function scenariosFingerprint(scenarios) {
+  const list = Array.isArray(scenarios) ? scenarios : []
+  const parts = list.map((s) => `${s?.id ?? ''}:${s?.title ?? ''}`)
+  return `${list.length}:${parts.join(',')}`
+}
+
+/**
+ * 计算决策（带并发去重）。相同 state 且决策参数未变时只发一次上游请求。
  */
-async function computeDecision({ agent, newText, provider, config, scenarios, cache, inFlight, signal, log, warnedScenarios }) {
+async function computeDecision({ agent, newText, provider, config, scenarios, cache, inFlight, signal, log, warnedScenarios, usage }) {
   const state = captureState(agent, newText, readNumber(config, 'autoMaxMessages', AUTO_DEFAULTS.autoMaxMessages))
-  const key = hashString(state)
+  // key = state 文本 + 决策指纹：state 决定"问什么"，指纹决定"按什么配置问"
+  const key = hashString(`${state}\u0000${decisionFingerprint(config, provider, scenariosFingerprint(scenarios))}`)
   const existing = inFlight.get(key)
   if (existing) return existing
   const promise = decide({
@@ -319,6 +409,7 @@ async function computeDecision({ agent, newText, provider, config, scenarios, ca
     signal,
     log,
     warnedScenarios,
+    usage,
   }).finally(() => {
     if (inFlight.get(key) === promise) inFlight.delete(key)
   })
@@ -326,7 +417,7 @@ async function computeDecision({ agent, newText, provider, config, scenarios, ca
   return promise
 }
 
-async function decide({ agent, newText, state, key, provider, config, scenarios, cache, signal, log, warnedScenarios }) {
+async function decide({ agent, newText, state, key, provider, config, scenarios, cache, signal, log, warnedScenarios, usage }) {
   const ttl = readNumber(config, 'autoCacheTtlMs', AUTO_DEFAULTS.autoCacheTtlMs) || 0
   if (ttl > 0) {
     const hit = cache.get(key)
@@ -334,7 +425,7 @@ async function decide({ agent, newText, state, key, provider, config, scenarios,
   }
 
   // 1) 选场景：固定绑定，或让模型做一次自动路由
-  const routed = await resolveScenario({ state, provider, config, scenarios, signal, log, warnedScenarios })
+  const routed = await resolveScenario({ state, provider, config, scenarios, signal, log, warnedScenarios, usage })
   if (!routed) return null
 
   // 路由置信度不足：宁可不注入，也不要塞一个瞎猜的结论
@@ -354,8 +445,14 @@ async function decide({ agent, newText, state, key, provider, config, scenarios,
     state,
     exec: { signal },
     minConfidence: readNumber(config, 'autoMinConfidence', AUTO_DEFAULTS.autoMinConfidence),
+    usage,
   })
   if (!result?.ok) {
+    // 上游明确回答"决策失败"：closed 档必须上抛，让 pre-step 的 catch 按语义拦截；
+    // open 档维持原行为：warn + 不注入（= 放行）。
+    if (isFailClosed(config)) {
+      throw new Error(`场景 ${routed.scenario.id} 执行失败：${result?.error || '未知错误'}`)
+    }
     log?.('warn', `场景 ${routed.scenario.id} 执行失败，已放行：${result?.error || '未知错误'}`)
     return null
   }
@@ -384,8 +481,36 @@ async function decide({ agent, newText, state, key, provider, config, scenarios,
   return injected
 }
 
-/** 选择场景：固定绑定优先，否则用一次 choice 问句自动路由。 */
-async function resolveScenario({ state, provider, config, scenarios, signal, log, warnedScenarios }) {
+/**
+ * 自动路由分批题的问题 id 前缀。
+ *
+ * 必须与"场景自己的问题 id"不可能相撞：场景问题 id 由用户定义，`scenario_0`
+ * 这种名字（正好也是 practice 里常见的场景 id 形态）会与之冲突，导致消费方
+ * 无法区分"这是路由题"还是"这是场景决策题"。用带命名空间的前缀 + 双下划线。
+ */
+const ROUTE_QUESTION_PREFIX = 'systemone_route__'
+
+/**
+ * 把场景清单切成每个不超过 MAX_CHOICE_OPTIONS 个选项的批次。
+ *
+ * 上游决策模型对单道 choice 的选项数有硬限制，而自动路由原本把**全部**场景塞进
+ * 一道题——11 个内置 + 15 个自定义即越界，且越界的问题不经过任何校验，只会被上游
+ * 拒绝（表现为路由静默失效）。分批后每道题都在限制内。
+ *
+ * @param {object[]} scenarios - 场景库
+ * @returns {object[][]} 批次数组；场景数不超限时只有一个批次
+ */
+function chunkScenarios(scenarios) {
+  const size = Math.max(1, MAX_CHOICE_OPTIONS)
+  const batches = []
+  for (let i = 0; i < scenarios.length; i += size) {
+    batches.push(scenarios.slice(i, i + size))
+  }
+  return batches
+}
+
+/** 选择场景：固定绑定优先，否则用一次分批 choice 问句自动路由。 */
+async function resolveScenario({ state, provider, config, scenarios, signal, log, warnedScenarios, usage }) {
   const fixed = readString(config, 'autoScenario', '').trim()
   if (fixed) {
     const scenario = findScenario(scenarios, fixed)
@@ -402,22 +527,59 @@ async function resolveScenario({ state, provider, config, scenarios, signal, log
   if (scenarios.length === 0) return null
   if (scenarios.length === 1) return { scenario: scenarios[0], source: '唯一场景', confidence: null }
 
+  // 场景数超过单道 choice 的上限时拆成多道题，一次请求并行问出（题目之间相互独立）
+  const batches = chunkScenarios(scenarios)
+  const questions = {}
+  batches.forEach((batch, index) => {
+    questions[`${ROUTE_QUESTION_PREFIX}${index}`] = {
+      type: 'choice',
+      instructions: batches.length === 1
+        ? '这段内容最需要哪一类业务判断？'
+        : `这段内容最需要哪一类业务判断？（第 ${index + 1}/${batches.length} 组；若都不匹配，选组内语义最近的一项）`,
+      criteria: Object.fromEntries(batch.map((s) => [s.id, s.title])),
+    }
+  })
+
   const response = await provider.decide({
     state,
-    questions: {
-      scenario: {
-        type: 'choice',
-        instructions: '这段内容最需要哪一类业务判断？',
-        criteria: Object.fromEntries(scenarios.map((s) => [s.id, s.title])),
-      },
-    },
+    questions,
     model: readString(config, 'model', ''),
     signal,
   })
-  const answer = response?.answers?.scenario
-  const scenario = answer?.choice ? findScenario(scenarios, answer.choice) : undefined
-  if (!scenario) return null
-  return { scenario, source: '自动路由', confidence: Number(answer?.confidence) }
+  // 记账：路由请求不经过 executeDecision，必须在这里单独记，否则自动路由的花销完全不可见。
+  // 注意别重复计：目标场景那次决策由 runScenarioDecision → executeDecision 统一记账。
+  recordUsage(usage, {
+    source: 'auto-route',
+    ok: true,
+    model: response?.model || readString(config, 'model', ''),
+    provider: provider.name,
+    usage: response?.usage,
+    latencyMs: response?.latency_ms,
+  })
+  // 每题各选出一个候选，取置信度最高的那题作为路由结果；
+  // 置信度不可用时按题目顺序（第 1 组优先），保持确定性。
+  const answers = response?.answers || {}
+  const candidates = []
+  batches.forEach((_batch, index) => {
+    const answer = answers[`${ROUTE_QUESTION_PREFIX}${index}`]
+    const scenario = answer?.choice ? findScenario(scenarios, answer.choice) : undefined
+    if (scenario) candidates.push({ scenario, confidence: Number(answer?.confidence) })
+  })
+  if (candidates.length === 0) {
+    // 路由题全部无法映射回场景 = 上游给了不可用的回答，与请求异常同级。
+    // closed 档上抛拦截本轮；open 档维持"静默不注入"。
+    if (isFailClosed(config)) {
+      throw new Error('自动路由没有产出任何可映射到场景的回答')
+    }
+    return null
+  }
+  candidates.sort((a, b) => {
+    const ac = Number.isFinite(a.confidence) ? a.confidence : -1
+    const bc = Number.isFinite(b.confidence) ? b.confidence : -1
+    return bc - ac
+  })
+  const best = candidates[0]
+  return { scenario: best.scenario, source: '自动路由', confidence: best.confidence }
 }
 
 /** 把决策结果渲染成注入文本。 */
@@ -441,7 +603,13 @@ function renderInjection(result, routed, config) {
   if (derived) lines.push(`派生：${derived}`)
 
   if (result.recommendation) lines.push(`建议：${result.recommendation}`)
-  if (result.needs_human_review) lines.push('注意：本次判断置信度偏低，请人工确认后再执行。')
+  if (result.needs_human_review) {
+    // 带上判定理由：只写"置信度偏低"会让模型无法判断该不该采信这条结论
+    const reasons = Array.isArray(result.review_reasons) && result.review_reasons.length > 0
+      ? `（${result.review_reasons.slice(0, 2).join('；')}）`
+      : ''
+    lines.push(`注意：本次判断的可能分布不够集中${reasons}，请人工确认后再执行。`)
+  }
 
   return lines.join('\n')
 }
@@ -453,18 +621,28 @@ function questionLabel(scenario, qid) {
 /* ─── 上下文捕获 ───────────────────────────────────────────────────────────── */
 
 /**
- * 判断是否为"无业务含义"的输入，用于跳过自动决策。
+ * 判断是否应当跳过自动决策：**只有"短促"且"整体是寒暄"才跳过**。
+ *
+ * 语义（0.6.0 起修正）：早期实现是"短于 autoMinChars 一律跳过"的**或**关系，
+ * 在中文里会静默误杀完整的业务请求——"退款""报错""超时""闪退"都只有 2 个字，
+ * 却都是真实请求，结果是开了自动决策却什么都不发生、且没有任何日志。
+ *
+ * 现在两条规则取**交集**：
+ *   1. `TRIVIAL_PATTERN` 是整体匹配（`^…$`），单独一条就足以识别寒暄；
+ *   2. `autoMinChars` 从"长度下限"变为**寒暄判定的长度上界**——超过这个长度
+ *      即使内容是"你好…"也交给模型判断（如「你好，我的订单一直没到账」）。
  *
- * 两条独立的跳过规则（命中任一即跳过）：
- *   1. 长度阈值：短于 autoMinChars 的一律跳过（默认 4，"退款失败" 恰好 4 字不被误伤）；
- *   2. 寒暄黑名单：整体就是一句寒暄/致谢的跳过，与长度无关。
+ * 注意：`autoMinChars: 0` 表示**不做长度限制**，即只按寒暄黑名单判定。
+ * 副作用：短业务请求现在会真的发起一次上游调用（有 token 与延迟成本）。
  */
 const TRIVIAL_PATTERN = /^(你好|您好|哈喽|在吗|hi|hello|hey|ok|okay|好的|好嘞|收到|明白|嗯+|谢谢|多谢|感谢|thanks|thank you|thx|再见|拜拜|bye|测试|test)[\s!！。.~～,，、?？]*$/i
 
 function isTrivialInput(text, minChars) {
   const trimmed = text.trim()
-  if (Number.isFinite(minChars) && minChars > 0 && trimmed.length < minChars) return true
-  return TRIVIAL_PATTERN.test(trimmed)
+  // 只按寒暄黑名单判定（不做长度限制）
+  if (!Number.isFinite(minChars) || minChars <= 0) return TRIVIAL_PATTERN.test(trimmed)
+  // 短 + 整体是寒暄：两个条件同时成立才跳过
+  return trimmed.length < minChars && TRIVIAL_PATTERN.test(trimmed)
 }
 
 /**
@@ -493,9 +671,9 @@ function readHistory(agent, limit) {
     else if (event?.type === 'assistant/message') message = event.data?.message
     else continue
 
-    if (event.type === 'user/message' && message?.source?.kind === RUNTIME_CONTEXT_SOURCE) continue
+    if (event.type === 'user/message' && message?.source?.kind === INJECTED_SOURCE) continue
     const text = textOfMessage(message)
-    if (text) picked.unshift(`- ${event.type === 'user/message' ? '用户' : '助手'}：${truncate(text, 2000)}`)
+    if (text) picked.unshift(`- ${event.type === 'user/message' ? '用户' : '助手'}：${truncate(text, HISTORY_CHARS_PER_MESSAGE)}`)
   }
   return picked
 }
@@ -504,7 +682,7 @@ function extractUserText(messages) {
   const texts = []
   for (const message of messages || []) {
     if (message?.role !== 'user') continue
-    if (message?.source?.kind === RUNTIME_CONTEXT_SOURCE) continue
+    if (message?.source?.kind === INJECTED_SOURCE) continue
     const text = textOfMessage(message)
     if (text) texts.push(text)
   }
@@ -523,12 +701,12 @@ function textOfMessage(message) {
     .trim()
 }
 
-/** 构造与宿主 runtime-context 同形的消息（UserMessage）。 */
+/** 构造本插件自己的注入消息（UserMessage）；kind 见 INJECTED_SOURCE 的说明。 */
 function buildContextMessage(text) {
   return {
     role: 'user',
     content: [{ type: 'text', text }],
-    source: { kind: RUNTIME_CONTEXT_SOURCE },
+    source: { kind: INJECTED_SOURCE },
   }
 }
 

package/lib/client.js

@@ -61,6 +61,9 @@ window.__ModuleLoader__.load({
       providerMock: '本地模拟',
       apiKey: 'API Key',
       apiKeyHint: '也可用环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY。出于安全，已保存的 Key 不会回显。',
+      apiKeyRef: '凭证引用名（推荐）',
+      apiKeyRefHint: '从 ~/.dsh/.credentials.yaml 的 refs.<名字> 读取密钥，配置里只留名字、不落明文。留空则依次尝试 SYSTEMONE_API_KEY / UNISOUND_API_KEY / TYPESAFE_API_KEY。',
+      apiKeyRefPlaceholder: '例如 SYSTEMONE_API_KEY',
       apiKeyPlaceholder: '留空表示不修改已保存的值',
       baseUrl: 'API 基础地址',
       baseUrlHint: '默认 https://maas-api.unisound.com/v1',
@@ -82,6 +85,10 @@ window.__ModuleLoader__.load({
       autoInjectHint: 'message=同一步生效；context=走宿主动态上下文，不写入会话历史',
       autoInjectMessage: '同步注入（message）',
       autoInjectContext: '动态上下文（context）',
+      autoFailMode: '失败语义',
+      autoFailModeHint: 'open=决策失败时放行（注入用途的正确默认）；closed=决策失败时否决本轮（供将来做闸门用；仅对真失败生效，寒暄/低置信度等主动跳过不受影响；仅 message 通道会拦截）',
+      autoFailModeOpen: '放行（open）',
+      autoFailModeClosed: '拦截本轮（closed）',
       autoTimeoutMs: '自动决策超时（毫秒）',
       autoTimeoutMsHint: '超时即放行，绝不阻塞会话',
       autoMaxMessages: '捕获历史条数',
@@ -135,6 +142,9 @@ window.__ModuleLoader__.load({
       providerMock: 'Local mock',
       apiKey: 'API key',
       apiKeyHint: 'UNISOUND_API_KEY / SYSTEMONE_API_KEY also work. A saved key is never echoed back.',
+      apiKeyRef: 'Credential ref (recommended)',
+      apiKeyRefHint: 'Read the key from refs.<name> in ~/.dsh/.credentials.yaml, so only a name lands in the config. Empty tries SYSTEMONE_API_KEY / UNISOUND_API_KEY / TYPESAFE_API_KEY in order.',
+      apiKeyRefPlaceholder: 'e.g. SYSTEMONE_API_KEY',
       apiKeyPlaceholder: 'Leave empty to keep the saved value',
       baseUrl: 'Base URL',
       baseUrlHint: 'Defaults to https://maas-api.unisound.com/v1',
@@ -156,6 +166,10 @@ window.__ModuleLoader__.load({
       autoInjectHint: 'message=applies in the same step; context=host dynamic context, not written to history',
       autoInjectMessage: 'Same step (message)',
       autoInjectContext: 'Dynamic context (context)',
+      autoFailMode: 'Failure semantics',
+      autoFailModeHint: 'open=pass through when the decision fails (correct default for injection); closed=veto the turn on failure (reserved for future gates; only real failures, deliberate skips still pass; message channel only)',
+      autoFailModeOpen: 'Pass through (open)',
+      autoFailModeClosed: 'Veto the turn (closed)',
       autoTimeoutMs: 'Auto decision timeout (ms)',
       autoTimeoutMsHint: 'On timeout the step proceeds — never blocks the session',
       autoMaxMessages: 'Captured history messages',
@@ -296,6 +310,7 @@ window.__ModuleLoader__.load({
 
     const SERVICE_FIELDS = [
       { key: 'provider', kind: 'select', options: ['unisound', 'http', 'mock'] },
+      { key: 'apiKeyRef', kind: 'text' },
       { key: 'apiKey', kind: 'password' },
       { key: 'baseUrl', kind: 'text' },
       { key: 'endpoint', kind: 'text' },
@@ -403,6 +418,7 @@ window.__ModuleLoader__.load({
     const AUTO_FIELDS = [
       { key: 'autoScenario', kind: 'datalist', options: SCENARIO_OPTIONS },
       { key: 'autoInject', kind: 'select', options: ['message', 'context'] },
+      { key: 'autoFailMode', kind: 'select', options: ['open', 'closed'] },
       { key: 'autoTimeoutMs', kind: 'number' },
       { key: 'autoMaxMessages', kind: 'number' },
       { key: 'autoCacheTtlMs', kind: 'number' },
@@ -422,6 +438,10 @@ window.__ModuleLoader__.load({
         if (value === 'message') return t('autoInjectMessage')
         if (value === 'context') return t('autoInjectContext')
       }
+      if (key === 'autoFailMode') {
+        if (value === 'open') return t('autoFailModeOpen')
+        if (value === 'closed') return t('autoFailModeClosed')
+      }
       if (key === 'redact') {
         return value === 'true' ? t('redactOn') : t('redactOff')
       }
@@ -534,7 +554,7 @@ window.__ModuleLoader__.load({
           inputMode: field.kind === 'number' ? 'decimal' : undefined,
           value,
           disabled,
-          placeholder: field.key === 'apiKey' ? t('apiKeyPlaceholder') : undefined,
+          placeholder: field.key === 'apiKey' ? t('apiKeyPlaceholder') : field.key === 'apiKeyRef' ? t('apiKeyRefPlaceholder') : undefined,
           autoComplete: 'off',
           onChange: (event) => onChange(field.key, event.target.value),
         })

package/lib/format.js

@@ -13,6 +13,7 @@ export function formatSummary({
   recommendation,
   notes = [],
   needsHumanReview = false,
+  reviewReasons = [],
 }) {
   const out = [
     `## ${title}`,
@@ -22,6 +23,8 @@ export function formatSummary({
   for (const note of notes) out.push(`- **注意**：${note}`)
   if (recommendation) out.push(`- **建议**：${recommendation}`)
   out.push(`- **建议复核**：${needsHumanReview ? '需要人工复核' : '无需人工复核'}`)
+  // 只给结论不给理由，调用方无法判断该不该信；把判据一并写出来。
+  for (const reason of reviewReasons) out.push(`  - ${reason}`)
   if (requestId) out.push(`- **请求 ID**：${requestId}（延迟 ${latencyMs}ms）`)
   return out.join('\n')
 }
@@ -159,16 +162,110 @@ const NOUL_UNCERTAIN_HIGH = 0.55
 /** choice 返回这些取值时视为「无法判断」。 */
 const UNCERTAIN_CHOICES = new Set(['uncertain', 'unknown'])
 
-/** 是否需要人工复核：置信度低于阈值，或出现不确定项。 */
-export function computeNeedsHumanReview(answers, minConfidence) {
-  for (const a of Object.values(answers || {})) {
-    if (!a || typeof a !== 'object') continue
-    if (typeof a.confidence === 'number' && a.confidence < minConfidence) return true
-    if (a.type === 'choice' && (a.choice == null || UNCERTAIN_CHOICES.has(a.choice))) return true
-    if (a.type === 'noul' && typeof a.noul === 'number'
-      && a.noul > NOUL_UNCERTAIN_LOW && a.noul < NOUL_UNCERTAIN_HIGH) return true
+/**
+ * 概率分布的"平坦度"兜底阈值：`最大概率 / (1/选项数)` 低于该值即视为模型在猜。
+ *
+ * 为什么用比值而不是绝对概率：**不同后端算 confidence 的公式不同**（TypeSafe 与
+ * Laya 就不一样），文献里的实测也表明这类概率**未标定**——把 0.6 这种绝对阈值
+ * 套在所有后端上，等于把"某个后端的经验值"当成通用标准。而"最大概率有没有明显
+ * 高出均匀分布"是**不依赖标定**的性质：0.5 除以 1/3 = 1.5 倍，说明只是略偏。
+ *
+ * 1.5 的取法：二选一题里对应 p≈0.75（比掷硬币强，但不足以据此自动执行）；
+ * 三选一题里对应 p≈0.5。要更宽松/更严格可调本常量。
+ */
+const FLATNESS_RATIO = 1.5
+
+/**
+ * 概率分布的平坦度比值：最大概率相对均匀分布的倍数。
+ * 选项少于 2 个或除基为 0 时返回 null。choice 与 score 共用
+ * （同是 probabilities 分布，复核判据也相同）。
+ */
+function flatnessRatio(probs) {
+  const keys = probs && typeof probs === 'object' ? Object.keys(probs) : []
+  if (keys.length < 2) return null
+  const max = Math.max(...keys.map((k) => Number(probs[k]) || 0))
+  const uniform = 1 / keys.length
+  return uniform > 0 ? max / uniform : null
+}
+
+/**
+ * 单题的可信度评估。
+ * @param {object} answer - 原始 answer（choice/noul/score）
+ * @returns {{ reason: string|null, ratio: number|null }} 不可信时给出原因与平坦度比值
+ */
+function assessAnswer(answer) {
+  if (!answer || typeof answer !== 'object') return { reason: null, ratio: null }
+
+  if (answer.type === 'choice') {
+    if (answer.choice == null) return { reason: 'choice 未给出选项', ratio: null }
+    if (UNCERTAIN_CHOICES.has(answer.choice)) return { reason: `choice 返回「${answer.choice}」`, ratio: null }
+    const ratio = flatnessRatio(answer.probabilities)
+    if (ratio !== null && ratio < FLATNESS_RATIO) {
+      return { reason: `choice 的分布接近均匀（最大概率仅均匀分布的 ${ratio.toFixed(2)} 倍）`, ratio }
+    }
+    return { reason: null, ratio: null }
+  }
+
+  if (answer.type === 'noul') {
+    const v = Number(answer.noul)
+    if (!Number.isFinite(v)) return { reason: 'noul 未给出数值', ratio: null }
+    if (v > NOUL_UNCERTAIN_LOW && v < NOUL_UNCERTAIN_HIGH) {
+      return { reason: `noul=${v.toFixed(3)} 落在 ${NOUL_UNCERTAIN_LOW}~${NOUL_UNCERTAIN_HIGH} 的摇摆区间`, ratio: null }
+    }
+    return { reason: null, ratio: null }
   }
-  return false
+
+  if (answer.type === 'score') {
+    const ratio = flatnessRatio(answer.probabilities)
+    if (ratio !== null && ratio < FLATNESS_RATIO) {
+      return { reason: `score 的分布接近均匀（最大概率仅均匀分布的 ${ratio.toFixed(2)} 倍）`, ratio }
+    }
+    if (!Number.isFinite(Number(answer.score))) return { reason: 'score 未给出分值', ratio: null }
+    return { reason: null, ratio: null }
+  }
+
+  return { reason: null, ratio: null }
+}
+
+/**
+ * 复核评估：判定是否需要人工复核，并给出**理由**。
+ *
+ * 判据分两类，区别很重要：
+ *   - **分布平坦**（`assessAnswer`）：概率没有明显高出均匀分布 → 模型在猜。
+ *     这是不依赖标定的信号，是主要判据。
+ *   - **绝对置信度低于 `minConfidence`**：保留为次要信号以兼容既有配置，
+ *     但它在跨后端时意义有限（各家 confidence 公式不同，且实测未标定）。
+ *
+ * @param {object} answers - 原始 answers
+ * @param {number} [minConfidence] - 绝对置信度阈值；不传则只按平坦度判定
+ * @returns {{ needed: boolean, reasons: string[] }}
+ */
+export function reviewAssessment(answers, minConfidence) {
+  const reasons = []
+  const threshold = Number(minConfidence)
+  for (const [qid, answer] of Object.entries(answers || {})) {
+    const { reason } = assessAnswer(answer)
+    if (reason) reasons.push(`${qid}：${reason}`)
+    if (Number.isFinite(threshold)
+      && typeof answer?.confidence === 'number'
+      && answer.confidence < threshold) {
+      reasons.push(`${qid}：置信度 ${(answer.confidence * 100).toFixed(1)}% 低于阈值 ${(threshold * 100).toFixed(0)}%`)
+    }
+  }
+  return { needed: reasons.length > 0, reasons }
+}
+
+/**
+ * 是否需要人工复核。
+ *
+ * 语义已从"只看绝对置信度阈值"改为"**看概率分布是否平坦**（分布接近均匀说明模型
+ * 在猜），并保留 `minConfidence` 作为次要信号"。理由见 reviewAssessment。
+ *
+ * @deprecated 直接用 `reviewAssessment()`——它额外给出**判定理由**，调用方不必
+ *   只拿到一个布尔值就无从判断该不该信。本函数保留为布尔快捷方式。
+ */
+export function computeNeedsHumanReview(answers, minConfidence) {
+  return reviewAssessment(answers, minConfidence).needed
 }
 
 /* ─── 内部工具 ─────────────────────────────────────────────────────────────── */