@master0071/dsh-systemone 0.4.4 → 0.6.0

package/lib/client.js

@@ -42,7 +42,7 @@ window.__ModuleLoader__.load({
       tabCustom: '自定义场景',
       tabCustomHint: '用 JSON 定义自己的场景（含「通用意图识别」）。保存后场景库立即重建，无需重启。',
       customScenarios: '场景定义（JSON 数组）',
-      customScenariosHint: '同 id 会覆盖内置场景；留空 [] 表示只用内置 10 个。每个场景最多 16 个问题，choice 选项 2~26 个。',
+      customScenariosHint: '同 id 默认整体覆盖内置场景；加 "patch": true 则只改给出的字段。留空 [] 表示只用内置 11 个。每个场景最多 16 个问题，choice 选项 2~26 个。',
       customScenariosPlaceholder: '[\n  {\n    "id": "intent",\n    "title": "通用意图识别",\n    "questions": {\n      "intent": {\n        "type": "choice",\n        "instructions": "用户最想做什么？",\n        "criteria": { "query": "查询", "action": "执行操作", "chat": "闲聊" }\n      }\n    }\n  }\n]',
       insertTemplate: '插入意图识别模板',
       jsonEmpty: '（空 = 只用内置场景）',
@@ -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',
@@ -72,12 +75,20 @@ window.__ModuleLoader__.load({
       timeoutMsHint: '单次决策请求的最长等待时间',
       minConfidence: '置信度阈值',
       minConfidenceHint: '任一答案低于该值时，结果会标记为建议人工复核（0~1）',
+      redact: '发送前脱敏',
+      redactHint: '开启后把 state 里的手机号/身份证/邮箱/银行卡号替换为 [类型] 标签再发给决策服务，判断语义保留',
+      redactOn: '开启（含隐私数据时建议）',
+      redactOff: '关闭',
       autoScenario: '固定场景（可选）',
-      autoScenarioHint: '点右侧箭头可从 10 个内置场景里选，也可手填场景 id 或别名（如 software_dev / 开发）；留空则每次自动选场景（多一次路由请求）',
+      autoScenarioHint: '点右侧箭头可从 11 个内置场景里选，也可手填场景 id 或别名（如 software_dev / 开发）；留空则每次自动选场景（多一次路由请求）',
       autoInject: '注入通道',
       autoInjectHint: 'message=同一步生效；context=走宿主动态上下文，不写入会话历史',
       autoInjectMessage: '同步注入（message）',
       autoInjectContext: '动态上下文（context）',
+      autoFailMode: '失败语义',
+      autoFailModeHint: 'open=决策失败时放行（注入用途的正确默认）；closed=决策失败时否决本轮（供将来做闸门用；仅对真失败生效，寒暄/低置信度等主动跳过不受影响；仅 message 通道会拦截）',
+      autoFailModeOpen: '放行（open）',
+      autoFailModeClosed: '拦截本轮（closed）',
       autoTimeoutMs: '自动决策超时（毫秒）',
       autoTimeoutMsHint: '超时即放行，绝不阻塞会话',
       autoMaxMessages: '捕获历史条数',
@@ -112,7 +123,7 @@ window.__ModuleLoader__.load({
       tabCustom: 'Custom scenarios',
       tabCustomHint: 'Define your own scenarios in JSON (including general intent recognition). Saving rebuilds the library immediately.',
       customScenarios: 'Scenario definitions (JSON array)',
-      customScenariosHint: 'An id matching a built-in overrides it; empty [] keeps only the 10 built-ins. Max 16 questions per scenario, 2~26 choice options.',
+      customScenariosHint: 'An id matching a built-in overrides it; add "patch": true to merge only the given fields. Empty [] keeps only the 11 built-ins. Max 16 questions per scenario, 2~26 choice options.',
       customScenariosPlaceholder: '[\n  {\n    "id": "intent",\n    "title": "General intent",\n    "questions": {\n      "intent": {\n        "type": "choice",\n        "instructions": "What does the user want?",\n        "criteria": { "query": "Look up", "action": "Do something", "chat": "Small talk" }\n      }\n    }\n  }\n]',
       insertTemplate: 'Insert intent template',
       jsonEmpty: '(empty = built-in scenarios only)',
@@ -131,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',
@@ -142,12 +156,20 @@ window.__ModuleLoader__.load({
       timeoutMsHint: 'Longest wait for one decision request',
       minConfidence: 'Confidence threshold',
       minConfidenceHint: 'Below this value a result is flagged for human review (0~1)',
+      redact: 'Redact before send',
+      redactHint: 'Replace phone/ID-card/email/bank-card numbers in state with [type] tags before sending to the decision service; semantics preserved',
+      redactOn: 'On (recommended with PII)',
+      redactOff: 'Off',
       autoScenario: 'Fixed scenario (optional)',
-      autoScenarioHint: 'Pick one of the 10 built-in scenarios from the dropdown, or type a scenario id/alias (e.g. software_dev); empty routes automatically on every step (one extra request)',
+      autoScenarioHint: 'Pick one of the 11 built-in scenarios from the dropdown, or type a scenario id/alias (e.g. software_dev); empty routes automatically on every step (one extra request)',
       autoInject: 'Injection channel',
       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',
@@ -268,7 +290,7 @@ window.__ModuleLoader__.load({
     /**
      * 内置场景候选（供「固定场景」输入框的下拉提示）。
      *
-     * 用 `<datalist>` 而不是 `<select>`：既能把 10 个内置场景列出来点选，
+     * 用 `<datalist>` 而不是 `<select>`：既能把 11 个内置场景列出来点选，
      * 又允许手填自定义场景 id 或别名（别名见 README 的场景表）。
      * 这里只放 id + 中文标题；id 用别名也能命中（findScenario 会按别名匹配）。
      */
@@ -283,16 +305,19 @@ window.__ModuleLoader__.load({
       { id: 'education', label: '教育内容 · 知识点、难度与合规' },
       { id: 'requirements', label: '需求与变更 · 优先级、风险与派发' },
       { id: 'software_dev', label: '软件开发 · 任务类型、复杂度与处置' },
+      { id: 'requirement_clarity', label: '需求预检 · 明确度与澄清点' },
     ]
 
     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' },
       { key: 'model', kind: 'text' },
       { key: 'timeoutMs', kind: 'number' },
       { key: 'minConfidence', kind: 'number' },
+      { key: 'redact', kind: 'select', options: ['false', 'true'] },
     ]
 
     /** 自定义场景编辑区（JSON）。 */
@@ -328,35 +353,57 @@ window.__ModuleLoader__.load({
           return { ok: false, error: `item:${at}`, ids, count: 0 }
         }
         const issues = []
+        const isPatch = spec.patch === true
         if (typeof spec.id !== 'string' || spec.id.trim() === '') issues.push('缺少 id')
-        if (typeof spec.title !== 'string' || spec.title.trim() === '') issues.push('缺少 title')
+        if (!isPatch && (typeof spec.title !== 'string' || spec.title.trim() === '')) issues.push('缺少 title')
         const questions = spec.questions
-        if (!questions || typeof questions !== 'object' || Array.isArray(questions)) {
-          issues.push('缺少 questions 对象')
-        } else {
-          const qids = Object.keys(questions)
-          if (qids.length === 0) issues.push('questions 至少 1 个')
-          if (qids.length > 16) issues.push(`questions 最多 16 个（当前 ${qids.length}）`)
-          for (const [qid, q] of Object.entries(questions)) {
-            if (!q || typeof q !== 'object') { issues.push(`问题 ${qid} 必须是对象`); continue }
-            if (!['choice', 'noul', 'score'].includes(q.type)) {
-              issues.push(`问题 ${qid} 的 type 必须是 choice/noul/score`)
-              continue
+        if (!isPatch || questions !== undefined) {
+          if (!questions || typeof questions !== 'object' || Array.isArray(questions)) {
+            issues.push(isPatch ? 'patch 的 questions 必须是对象' : '缺少 questions 对象')
+          } else if (isPatch) {
+            // patch 的问题允许省略 type/instructions/criteria（继承目标场景的同名字段），
+            // 深层合法性由宿主对「合并结果」统一校验；这里只拦立刻能发现的结构错误
+            for (const [qid, q] of Object.entries(questions)) {
+              if (qid === '__proto__' || qid === 'constructor' || qid === 'prototype') {
+                issues.push(`问题 id ${qid} 不能使用（与对象原型机制冲突），请换一个 id`)
+                continue
+              }
+              if (!q || typeof q !== 'object') { issues.push(`问题 ${qid} 必须是对象`); continue }
+              if (q.type !== undefined && !['choice', 'noul', 'score'].includes(q.type)) {
+                issues.push(`问题 ${qid} 的 type 必须是 choice/noul/score`)
+              }
             }
-            if (typeof q.instructions !== 'string' || q.instructions.trim() === '') {
-              issues.push(`问题 ${qid} 缺少 instructions`)
-            }
-            if (q.type === 'choice') {
-              const keys = q.criteria && typeof q.criteria === 'object' && !Array.isArray(q.criteria)
-                ? Object.keys(q.criteria)
-                : null
-              if (keys === null) issues.push(`问题 ${qid}（choice）需要 criteria 对象`)
-              else if (keys.length < 2) issues.push(`问题 ${qid}（choice）至少 2 个选项`)
-              else if (keys.length > 26) issues.push(`问题 ${qid}（choice）选项不能超过 26 个（当前 ${keys.length}）`)
-            }
-            if (q.type === 'score'
-              && (!Array.isArray(q.criteria) || q.criteria.length < 2)) {
-              issues.push(`问题 ${qid}（score）criteria 需为长度 ≥2 的数组`)
+          } else {
+            const qids = Object.keys(questions)
+            if (qids.length === 0) issues.push('questions 至少 1 个')
+            if (qids.length > 16) issues.push(`questions 最多 16 个（当前 ${qids.length}）`)
+            for (const [qid, q] of Object.entries(questions)) {
+              // 与宿主侧 validateScenario 对齐：这类键会被宿主拒绝，
+              // 这里不拦的话配置页会显示「JSON 有效」、场景却静默不生效
+              if (qid === '__proto__' || qid === 'constructor' || qid === 'prototype') {
+                issues.push(`问题 id ${qid} 不能使用（与对象原型机制冲突），请换一个 id`)
+                continue
+              }
+              if (!q || typeof q !== 'object') { issues.push(`问题 ${qid} 必须是对象`); continue }
+              if (!['choice', 'noul', 'score'].includes(q.type)) {
+                issues.push(`问题 ${qid} 的 type 必须是 choice/noul/score`)
+                continue
+              }
+              if (typeof q.instructions !== 'string' || q.instructions.trim() === '') {
+                issues.push(`问题 ${qid} 缺少 instructions`)
+              }
+              if (q.type === 'choice') {
+                const keys = q.criteria && typeof q.criteria === 'object' && !Array.isArray(q.criteria)
+                  ? Object.keys(q.criteria)
+                  : null
+                if (keys === null) issues.push(`问题 ${qid}（choice）需要 criteria 对象`)
+                else if (keys.length < 2) issues.push(`问题 ${qid}（choice）至少 2 个选项`)
+                else if (keys.length > 26) issues.push(`问题 ${qid}（choice）选项不能超过 26 个（当前 ${keys.length}）`)
+              }
+              if (q.type === 'score'
+                && (!Array.isArray(q.criteria) || q.criteria.length < 2)) {
+                issues.push(`问题 ${qid}（score）criteria 需为长度 ≥2 的数组`)
+              }
             }
           }
         }
@@ -371,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' },
@@ -390,6 +438,13 @@ 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')
+      }
       return value
     }
 
@@ -499,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),
         })
@@ -599,11 +654,11 @@ window.__ModuleLoader__.load({
       const dirty = draft !== null && Object.keys(draft).some((key) => draft[key] !== current[key])
       const canSave = dirty && !busy && writable && customCheck.ok && Object.keys(numberErrors).length === 0
 
-      // 「固定场景」候选 = 10 个内置 + 当前生效的自定义场景 id
+      // 「固定场景」候选 = 11 个内置 + 当前生效的自定义场景 id（patch 条目指向已有 id，去重避免重复项）
       const scenarioOptions = [
         ...SCENARIO_OPTIONS,
         ...(customCheck.ok
-          ? customCheck.ids
+          ? [...new Set(customCheck.ids)]
               .filter((id) => !SCENARIO_OPTIONS.some((option) => option.id === id))
               .map((id) => ({ id, label: id }))
           : []),
@@ -632,6 +687,8 @@ window.__ModuleLoader__.load({
               if (!Number.isFinite(parsed)) continue
               next = parsed
             }
+            // redact 下拉在草稿里是字符串，schema 要的是布尔
+            if (key === 'redact') next = value === 'true'
             ops.push({ op: 'set', path: [key], value: next })
           }
           if (ops.length === 0) {
@@ -834,6 +891,8 @@ window.__ModuleLoader__.load({
     exports.name = name
     exports.inject = inject
     exports.apply = apply
+    // 仅供测试：暴露纯函数（宿主只读 name/inject/apply，多余导出对宿主无影响）
+    exports.__internals = { validateCustomScenarios, describeCustomError }
     return module.exports
   },
 })

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
 }
 
 /* ─── 内部工具 ─────────────────────────────────────────────────────────────── */

package/lib/index.d.ts

@@ -7,7 +7,12 @@ import { Context, Service } from '@deepseek-ai/cordis'
 export interface Config {
   /** 提供商类型：unisound（官方）/ http（SystemOne 兼容端点）/ mock（本地模拟） */
   provider?: string
-  /** Unisound API Key（也可用环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY） */
+  /**
+   * 凭证引用名（推荐）：从 `$DSH_HOME/.credentials.yaml` 的 `refs.<名字>` 读密钥，
+   * 配置文件里只留这个名字。留空时依次尝试 SYSTEMONE_API_KEY / UNISOUND_API_KEY / TYPESAFE_API_KEY。
+   */
+  apiKeyRef?: string
+  /** 明文 API Key（备用；也可用环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY） */
   apiKey?: string
   /** Unisound API 基础地址 */
   baseUrl?: string
@@ -17,10 +22,17 @@ export interface Config {
   model?: string
   /** 请求超时（毫秒） */
   timeoutMs?: number
-  /** 置信度阈值 */
+  /**
+   * **次要**复核信号：置信度低于该值时也标记需复核。
+   * 主要判据是概率分布平坦度（见 `reviewAssessment` 语义），因为这类概率未标定、跨后端不可比。
+   */
   minConfidence?: number
+  /** 发送前对 state 做内置脱敏（手机号/身份证/邮箱/银行卡号替换为类型标签） */
+  redact?: boolean
   /** 自定义场景：JSON 数组字符串 */
   customScenarios?: string
+  /** 用量台账文件路径；留空则用 `$DSH_HOME/dsh-systemone/usage.jsonl` */
+  usageLogPath?: string
 
   /* ── 自动决策（默认关闭） ─────────────────────────────── */
   /** 是否在每一步推理前自动捕获上下文并执行决策 */
@@ -29,6 +41,8 @@ export interface Config {
   autoScenario?: string
   /** 注入通道：message=同一步生效并去重；context=宿主动态上下文（不写历史） */
   autoInject?: string
+  /** 自动决策失败语义：open=放行（默认）；closed=决策失败时否决本轮（供将来做闸门用，仅 message 通道） */
+  autoFailMode?: string
   /** 自动决策超时（毫秒） */
   autoTimeoutMs?: number
   /** 捕获的历史消息条数 */
@@ -62,6 +76,46 @@ export interface ScenarioInfo {
   questions: string[]
 }
 
+/**
+ * 工具决策结果里与复核相关的字段。
+ *
+ * `computeNeedsHumanReview` 的语义自本版本起改为「**概率分布是否平坦**」
+ * （最大概率相对均匀分布不足 1.5 倍即视为在猜，不依赖标定），
+ * 绝对置信度 `minConfidence` 降为次要信号。
+ */
+export interface ReviewOutcome {
+  /**
+   * 是否需要人工复核。判据为分布平坦（主要）或低于 `minConfidence`（次要），
+   * 以及 `choice` 返回 uncertain/空值、`noul` 落在 0.45~0.55 摇摆区间。
+   */
+  needs_human_review: boolean
+  /** 判定理由（每条形如 `qid：原因`）；为空表示无需复核。仅工具输出提供。 */
+  review_reasons?: string[]
+}
+
+/** 工具返回的决策结果（`systemone_scenario(action:"run")` 与 `systemone_decide`）。 */
+export interface DecisionResult extends ReviewOutcome {
+  ok: boolean
+  scenario: string | null
+  provider: string
+  model?: string
+  request_id?: string
+  latency_ms?: number
+  answers?: Record<string, unknown>
+  decision?: Record<string, unknown>
+  labels?: Record<string, unknown>
+  derived?: Record<string, unknown>
+  confidences?: Record<string, number>
+  recommendation?: string
+  warnings?: string[]
+  /** 人可读的 Markdown 摘要（含复核理由子项）。 */
+  summary: string
+  /** 失败时的人类可读原因。 */
+  error?: string
+  /** 未知场景时列出的可用场景 id。 */
+  available?: string[]
+}
+
 declare module '@deepseek-ai/cordis' {
   interface Context {
     /** SystemOne 决策服务。 */