@master0071/dsh-systemone 0.5.0 → 0.6.1

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,12 +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
 
   /* ── 自动决策（默认关闭） ─────────────────────────────── */
   /** 是否在每一步推理前自动捕获上下文并执行决策 */
@@ -31,6 +41,8 @@ export interface Config {
   autoScenario?: string
   /** 注入通道：message=同一步生效并去重；context=宿主动态上下文（不写历史） */
   autoInject?: string
+  /** 自动决策失败语义：open=放行（默认）；closed=决策失败时否决本轮（供将来做闸门用，仅 message 通道） */
+  autoFailMode?: string
   /** 自动决策超时（毫秒） */
   autoTimeoutMs?: number
   /** 捕获的历史消息条数 */
@@ -64,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 决策服务。 */

package/lib/index.js

@@ -13,11 +13,12 @@
  */
 import { Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
-import { createProvider } from './provider.js'
-import { createTools } from './tools.js'
+import { createProvider, redactRuleSummary } from './provider.js'
+import { createTools, MAX_TOOL_STATE_CHARS } from './tools.js'
 import { resolveScenarios } from './scenarios.js'
-import { installAutoDecide, AUTO_DEFAULTS } from './auto.js'
-import { readBoolean, readString, unwrap } from './volatile.js'
+import { installAutoDecide, AUTO_DEFAULTS, MAX_CURRENT_CHARS, HISTORY_CHARS_PER_MESSAGE } from './auto.js'
+import { createUsageLedger } from './usage.js'
+import { readBoolean, readNumber, readString, unwrap } from './volatile.js'
 
 /** 合法的提供商类型；其他值会按 unisound 处理并告警一次。 */
 const KNOWN_PROVIDERS = ['unisound', 'http', 'mock']
@@ -73,7 +74,21 @@ const Config = z.object({
   customScenarios: z.string().default('').volatile(),
   /** 提供商类型：unisound（官方）/ http（SystemOne 兼容端点）/ mock（本地模拟） */
   provider: z.string().default('unisound').volatile(),
-  /** Unisound API Key（也可用环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY） */
+  /**
+   * 凭证引用名：从 DSH 凭证缝 `$DSH_HOME/.credentials.yaml` 的 `refs.<名字>` 读取密钥。
+   *
+   * 这是**推荐的凭证方式**：`apiKey` 虽然标了 `.role('secret')`（表单不回显），
+   * 但值仍以明文落在 profile 的 `cordis.patch.yml` 里。用引用名则配置文件里只有
+   * 一个名字，真正的密钥留在凭证文件（或环境变量）中。
+   *
+   * 留空时按顺序尝试内置默认引用名：SYSTEMONE_API_KEY → UNISOUND_API_KEY → TYPESAFE_API_KEY。
+   */
+  apiKeyRef: z.string().default('').volatile(),
+  /**
+   * Unisound API Key（明文；不想落明文请改用 apiKeyRef 或环境变量）。
+   *
+   * 解析顺序：apiKey → 环境变量 → 凭证引用（apiKeyRef 或内置默认名）。
+   */
   apiKey: z.string().default('').role('secret').volatile(),
   /** Unisound API 基础地址（默认 https://maas-api.unisound.com/v1） */
   baseUrl: z.string().default('https://maas-api.unisound.com/v1').volatile(),
@@ -100,8 +115,27 @@ const Config = z.object({
   /* ── 自动决策运行参数（volatile）：钩子已挂载时实时生效 ────────────────────── */
   /** 自动决策固定使用的场景 id；留空则用一次 choice 问句自动路由 */
   autoScenario: z.string().default('').volatile(),
-  /** 注入通道：message=本步生效（pre-step 注入）；context=官方动态上下文（晚一步生效） */
-  autoInject: z.string().default('message').volatile(),
+  /**
+   * 注入通道：message=本步生效（pre-step 注入）；context=官方动态上下文（晚一步生效）。
+   *
+   * 必须是枚举而不是裸 string：auto.js 的三处门控都是精确比较
+   * （`!== 'context'` / `=== 'context'` / `!== 'message'`），写错大小写
+   * （如 `Context`）会静默掉进 message 分支、产生意料之外的历史写入。
+   * 枚举让非法值在加载期就报错，而不是运行时无提示地走错通道。
+   */
+  autoInject: z.union(['message', 'context']).default('message').volatile(),
+  /**
+   * 自动决策失败语义：open=放行（注入用途的正确默认）；closed=否决本轮
+   * （pre-step 返回 `{ kind: 'reject' }`，宿主把本轮 turn 记为 blocked）。
+   *
+   * 必须是枚举而不是裸 string，理由同 autoInject：auto.js 的分支是精确比较，
+   * 写错值会静默落回 open。closed 只对"本应得到决策却没有"的真失败生效
+   * （请求异常、超时、场景执行失败、路由无可用品）；"主动不注入"
+   * （寒暄、低置信度、斜杠命令）永远放行。仅 message 通道会拦截——
+   * context 通道只注入参考信息，不 gate 任何东西。本档是为将来做闸门
+   * （形态 C）预留的语义缝，当前注入用途请保持 open。
+   */
+  autoFailMode: z.union(['open', 'closed']).default('open').volatile(),
   /** 自动决策超时（毫秒），超时即放行，绝不阻塞会话 */
   autoTimeoutMs: z.number().min(500).default(AUTO_DEFAULTS.autoTimeoutMs).volatile(),
   /** 捕获的历史消息条数（不含本轮新消息） */
@@ -114,6 +148,11 @@ const Config = z.object({
   autoRouteMinConfidence: z.number().min(0).max(1).default(AUTO_DEFAULTS.autoRouteMinConfidence).volatile(),
   /** 触发自动决策的最小输入长度（字符）；低于该长度且整体是寒暄才跳过 */
   autoMinChars: z.number().min(0).default(AUTO_DEFAULTS.autoMinChars).volatile(),
+
+  /* ── 用量台账（volatile）────────────────────────────────────────────────── */
+
+  /** 用量台账文件路径；留空则用 `$DSH_HOME/dsh-systemone/usage.jsonl` */
+  usageLogPath: z.string().default('').volatile(),
 })
 
 export default class SystemOneService extends Service {
@@ -154,6 +193,15 @@ export default class SystemOneService extends Service {
     this._refreshScenarios()
     const scenarios = this.liveScenarios()
 
+    // 外发声明：装载时打印一行，之后 provider / redact 变化时再打印一次。
+    // 见 _announceEgress 的说明——state 会原样发往上游，这件事必须是可审计的。
+    this._egressStamp = null
+    this._announceEgress()
+
+    // 用量台账：工具路径与自动路径都记账（含路由请求），让花销可见。
+    // 台账写盘失败会降级为仅内存统计，绝不影响决策。
+    this.usageLedger = createUsageLedger({ path: readString(config, 'usageLogPath', ''), logger: ctx.logger })
+
     // inject 保证 ctx.tools 存在；注册失败必须显式抛出，绝不静默降级
     const tools = ctx.get('tools') ?? ctx.tools
     if (!tools || typeof tools.register !== 'function') {
@@ -163,6 +211,7 @@ export default class SystemOneService extends Service {
       // 惰性读取：场景库可能已随 customScenarios 热更新重建，
       // 这里必须每次取最新的 warnings，而不是装配期快照。
       warnings: () => this.scenarioWarnings || [],
+      usage: this.usageLedger,
     }).map((tool) => tools.register(tool))
 
     // 自动决策：默认关闭；开启后在每一步推理前自动捕获上下文并注入判断
@@ -174,6 +223,7 @@ export default class SystemOneService extends Service {
           config,
           scenarios,
           logger: ctx.logger,
+          usage: this.usageLedger,
         })
       } catch (error) {
         ctx.logger?.warn?.(`@master0071/dsh-systemone: 自动决策安装失败，工具仍可用：${error?.message || error}`)
@@ -187,6 +237,66 @@ export default class SystemOneService extends Service {
     )
   }
 
+  /**
+   * 外发声明：把「这次会不会联网、往哪发、发什么」打成一行可审计的日志。
+   *
+   * 为什么需要它：`state`（含对话历史与用户原文）会原样发往上游决策服务，
+   * 而 `redact` 默认是 **false**。生态里同类插件被审计出的最常见问题正是
+   * 「名为 guard/gate 的模块同时在往外发数据，而 README 不说」。一行启动声明
+   * 让这件事在日志里可见，而不是只藏在配置文档里。
+   *
+   * `provider` 与 `redact` 都是热更新字段，所以本方法在**值变化时**会再打一次；
+   * 相同状态不重复输出，避免每步刷日志。
+   */
+  _announceEgress() {
+    try {
+      const kind = readString(this.config, 'provider', 'unisound')
+      const redact = readBoolean(this.config, 'redact', false)
+      const stamp = `${kind}|${redact}`
+      if (stamp === this._egressStamp) return
+      this._egressStamp = stamp
+
+      const logger = this.ctx?.logger
+      if (kind === 'mock') {
+        logger?.info?.('@master0071/dsh-systemone[egress]: OFF — provider=mock，不会发起任何网络请求')
+        return
+      }
+
+      const budget = this._stateBudget()
+      // 尽量报告真实端点；解析失败（配错 URL 等）时退回配置原文，不让声明本身抛错
+      let target = ''
+      try {
+        target = this.currentProvider().resolveEndpoint()
+      } catch {
+        target = readString(this.config, 'endpoint', '') || readString(this.config, 'baseUrl', '')
+      }
+      const where = target || '(端点未配置)'
+
+      const redactLine = redact
+        ? `ON — 发送前把 ${redactRuleSummary()} 替换为 [类型] 标签（尽力而为：不在规则内的敏感串仍会外发）`
+        : `OFF — ${redactRuleSummary()} 等敏感内容**原样外发**，建议在处理含隐私数据的内容时开启 redact`
+
+      logger?.info?.(`@master0071/dsh-systemone[egress]: ON → ${where}`)
+      logger?.info?.(
+        `@master0071/dsh-systemone[egress]: SENDS state(<=${budget} 字符，含对话历史与用户原文) + questions`
+        + ` + model；redact=${redactLine}`,
+      )
+    } catch {
+      // 声明失败绝不能影响装配
+    }
+  }
+
+  /**
+   * state 的字符预算：工具路径截断到 MAX_TOOL_STATE_CHARS，自动决策路径拼装后可能更大。
+   * 声明里报一个保守上界，让「发出去多大」有个量级概念。
+   * 数字全部同源引用（tools.js / auto.js 的截断常量），改一处声明自动跟随。
+   */
+  _stateBudget() {
+    if (!readBoolean(this.config, 'autoDecide', false)) return MAX_TOOL_STATE_CHARS
+    const messages = readNumber(this.config, 'autoMaxMessages', 6)
+    return Math.max(MAX_TOOL_STATE_CHARS, MAX_CURRENT_CHARS + messages * HISTORY_CHARS_PER_MESSAGE)
+  }
+
   /**
    * 返回当前应当使用的提供商；`provider` 配置变化时按需重建。
    *
@@ -200,6 +310,10 @@ export default class SystemOneService extends Service {
       this._provider = createProvider(this.config)
       this._providerKind = kind
     }
+    // 所有请求路径（工具/自动决策/服务 decide）取提供商都经过这里：
+    // provider **或 redact** 任一变化（stamp 去重）即重发外发声明。
+    // 放在方法末尾，保证声明解析端点用的是（可能刚重建的）新提供商。
+    this._announceEgress()
     return this._provider
   }
 

package/lib/provider.js

@@ -15,6 +15,8 @@
  *   - "mock"    ：本地确定性模拟（无需 API Key，用于测试与演示）
  */
 
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { readBoolean, readNumber, readString } from './volatile.js'
 
 const DEFAULT_BASE_URL = 'https://maas-api.unisound.com/v1'
@@ -58,15 +60,25 @@ export class HttpProvider {
     return assertValidUrl(`${base}/systemone`)
   }
 
-  /** 解析 API Key：配置优先，其次环境变量。 */
+  /**
+   * 解析 API Key，顺序为：插件配置明文 → 环境变量 → DSH 凭证缝引用。
+   *
+   * 推荐用最后一种（`apiKeyRef`）：配置里只留一个引用名，密钥本体留在
+   * `$DSH_HOME/.credentials.yaml`，避免明文落进 profile 的 `cordis.patch.yml`。
+   * 三种来源都没有时给出可操作的报错。
+   */
   resolveApiKey() {
     const key = readString(this.config, 'apiKey', '')
       || process.env.UNISOUND_API_KEY
       || process.env.SYSTEMONE_API_KEY
+      || readCredentialRef(readString(this.config, 'apiKeyRef', ''))
       || ''
     if (!key) {
       throw new Error(
-        'SystemOne: 未配置 apiKey（请在插件配置中填写，或设置环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY）',
+        'SystemOne: 未配置凭证。按序尝试了：插件配置的 apiKey → 环境变量 UNISOUND_API_KEY / SYSTEMONE_API_KEY '
+        + `→ 凭证缝 ${credentialsPath()} 的 refs.<apiKeyRef>`
+        + `${readString(this.config, 'apiKeyRef', '') ? '' : '（apiKeyRef 留空，回退默认名 ' + DEFAULT_KEY_REFS.join(' / ') + '）'}。`
+        + '推荐在凭证文件里写 `refs: { SYSTEMONE_API_KEY: <你的 key> }` 并保持 apiKey 为空。',
       )
     }
     return key
@@ -218,8 +230,8 @@ function mockAnswer(id, q, seedSource) {
       }
     }
     case 'noul': {
-      // 与真实响应对齐：noul 也带 confidence（取倾向一侧的概率），
-      // 否则 mock 下 computeNeedsHumanReview 走不到置信度分支
+      // 与真实响应对齐：noul 也带 confidence（取倾向一侧的概率）。
+      // mock 的分布是合成的，**不代表真实模型行为**，只能用于契约与确定性回归。
       const v = Math.round((rand() * 0.6 + 0.2) * 1000) / 1000
       return { type: 'noul', noul: v, confidence: Math.max(v, 1 - v) }
     }
@@ -310,6 +322,93 @@ function redactValue(value, enabled) {
   return value
 }
 
+/* ─── DSH 凭证缝读取 ───────────────────────────────────────────────────────── */
+
+/** DSH 主目录：与用量台账同源（usage.js 导出）。 */
+import { dshHome } from './usage.js'
+
+/** 未配置 apiKeyRef 时依次尝试的内置引用名（覆盖 SystemOne 各家后端）。 */
+const DEFAULT_KEY_REFS = ['SYSTEMONE_API_KEY', 'UNISOUND_API_KEY', 'TYPESAFE_API_KEY']
+
+/** 凭证文件路径（用于报错文案与读取）。 */
+function credentialsPath() {
+  return join(dshHome(), '.credentials.yaml')
+}
+
+/**
+ * 从凭证文件里取 `refs.<name>` 的值。
+ *
+ * 只解析 `refs:` 下的**单层标量**，不引入 YAML 依赖（插件对 `@deepseek-ai/*` 之外的
+ * 依赖保持为零）。解析要点：
+ *   - 只认 `refs:` 之后、缩进更深的行，避免误取段外同名键；
+ *   - 值两端的成对引号会被剥掉（`TYPESAFE_API_KEY: "sk-x"` 应得到 `sk-x`）——
+ *     这是同类实现常见的一个缺陷：直接把捕获组当值，会连引号一起塞进 Authorization 头；
+ *   - 行内 ` #` 注释会被裁掉（仅对未加引号的值）；
+ *   - 多个候选名都在文件里时，**按 `wanted` 的顺序**返回，而不是按文件出现顺序。
+ *
+ * @param {string} name - 引用名；留空时依次尝试 DEFAULT_KEY_REFS
+ * @returns {string|undefined} 找到的凭证；找不到返回 undefined
+ */
+function readCredentialRef(name) {
+  const wanted = name && String(name).trim() ? [String(name).trim()] : DEFAULT_KEY_REFS
+  let raw
+  try {
+    raw = readFileSync(credentialsPath(), 'utf8')
+  } catch {
+    return undefined // 文件不存在/不可读 → 视为未配置
+  }
+  const refs = new Map()
+  let inRefs = false
+  let refsIndent = -1
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
+    const indent = line.length - line.trimStart().length
+    if (!inRefs) {
+      if (/^refs\s*:\s*$/.test(line.trim())) {
+        inRefs = true
+        refsIndent = indent
+      }
+      continue
+    }
+    // 缩进不深于 refs: 即说明已离开该段
+    if (indent <= refsIndent) break
+    const match = /^\s*([^\s:#][^:]*?)\s*:\s*(.*)$/.exec(line)
+    if (!match) continue
+    const value = unquoteScalar(match[2]) ?? ''
+    if (value) refs.set(match[1].trim(), value)
+  }
+  // 按候选名给定的优先级取值（不是文件顺序）
+  for (const key of wanted) {
+    const hit = refs.get(key)
+    if (hit) return hit
+  }
+  return undefined
+}
+
+/** 剥掉标量两端成对的引号并裁掉未加引号值后的行内注释。 */
+function unquoteScalar(raw) {
+  const trimmed = String(raw ?? '').trim()
+  if (trimmed === '') return ''
+  const first = trimmed[0]
+  if (first === '"' || first === "'") {
+    // 引号值：取到配对的收尾引号为止，引号内的 # 不算注释
+    const end = trimmed.indexOf(first, 1)
+    return end === -1 ? trimmed.slice(1) : trimmed.slice(1, end)
+  }
+  const hash = trimmed.indexOf(' #')
+  return hash === -1 ? trimmed : trimmed.slice(0, hash).trim()
+}
+
+/* ─── 脱敏规则清单（供外发声明复用，避免文案与实现漂移）────────────────────── */
+
+/** 规则的中文类型标签，按 REDACT_RULES 的顺序。 */
+const REDACT_TAGS = REDACT_RULES.map((rule) => rule.tag.replace(/^\[|\]$/g, ''))
+
+/** 脱敏规则的中文清单，形如 `手机号/身份证/邮箱/银行卡号`。 */
+export function redactRuleSummary() {
+  return REDACT_TAGS.join('/')
+}
+
 /* ─── 通用内部工具 ─────────────────────────────────────────────────────────── */
 
 /** URL 合法性在发请求前拦下：漏写协议时 fetch 的报错非常隐晦，不如直接说清楚。 */
@@ -329,8 +428,10 @@ function isRetryable(error) {
 }
 
 function sleep(ms) {
+  // ref 定时器（不能 unref）：重试退避期间调用方正在 await decide()，
+  // 这个承诺必须落定。unref 会让无其他句柄的进程（如测试 runner）事件循环
+  // 提前抽干、承诺悬空，也可能在宿主退出时静默吞掉一次重试。
   return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms)
-    timer.unref?.()
+    setTimeout(resolve, ms)
   })
 }

package/lib/scenarios.js

@@ -33,6 +33,17 @@
  *   {qid?文案A|文案B}     → 条件文案（noul 为真 / 分值≥1 / choice 非空非 none 时取 A）
  */
 
+/**
+ * choice 题型的选项数上限。
+ *
+ * 单一真源：场景校验（validateScenario）与自动路由的分批逻辑都读这里。
+ * 上游决策模型对 choice 的选项数有硬限制，超过会被拒——因此不仅是"建议"。
+ */
+export const MAX_CHOICE_OPTIONS = 26
+
+/** choice 题型的选项数下限。 */
+export const MIN_CHOICE_OPTIONS = 2
+
 /** 内置场景：11 个业务域，每个 3 个结构化问题。 */
 export const BUILTIN_SCENARIOS = [
   {
@@ -465,10 +476,10 @@ export function validateScenario(spec) {
     if (q.type === 'choice') {
       if (!q.criteria || typeof q.criteria !== 'object' || Array.isArray(q.criteria)) {
         problems.push(`问题 ${qid}（choice）的 criteria 必须是"选项 key → 说明"的对象`)
-      } else if (Object.keys(q.criteria).length < 2) {
-        problems.push(`问题 ${qid}（choice）至少需要 2 个选项`)
-      } else if (Object.keys(q.criteria).length > 26) {
-        problems.push(`问题 ${qid}（choice）选项建议不超过 26 个`)
+      } else if (Object.keys(q.criteria).length < MIN_CHOICE_OPTIONS) {
+        problems.push(`问题 ${qid}（choice）至少需要 ${MIN_CHOICE_OPTIONS} 个选项`)
+      } else if (Object.keys(q.criteria).length > MAX_CHOICE_OPTIONS) {
+        problems.push(`问题 ${qid}（choice）选项最多 ${MAX_CHOICE_OPTIONS} 个（当前 ${Object.keys(q.criteria).length} 个）`)
       }
     }
     if (q.type === 'score' && (!Array.isArray(q.criteria) || q.criteria.length < 2)) {