@master0071/dsh-systemone 0.4.4 → 0.6.0

package/lib/index.js

@@ -7,17 +7,18 @@
  * - 注册 2 个 Agent 工具：
  *     systemone_scenario — 统一场景调度（list / describe / run）
  *     systemone_decide   — 自定义问题的低层入口
- * - 场景库内置 10 大业务域，并支持在配置里用 JSON 追加/覆盖场景
+ * - 场景库内置 11 大业务域，并支持在配置里用 JSON 追加/覆盖/patch 场景
  * - 暴露 `ctx.systemone.decide()` 供其他插件编程调用
  * - 提供商可配置（unisound / http / mock），切换厂商不影响工具层
  */
 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']
@@ -27,16 +28,29 @@ const KNOWN_PROVIDERS = ['unisound', 'http', 'mock']
  *
  * 工具与自动决策在装配期就拿到了这个对象并长期持有；有了它，
  * 配置页里切换 `provider` 后它们无需重新装配即可用上新提供商。
+ *
+ * 与 liveScenarios 同一原则：**不做 trap 白名单**，统一转发全部
+ * （对象目标上合法的）内部方法——白名单的毛病是「漏一个就静默拿不到
+ * 新实例的成员」。provider 将来新增 health()/close() 之类接口时，
+ * 走代理的调用方自动可见，不需要回来改这里。
+ * 注意 apply/construct 两个 trap 只对函数目标合法，provider 是普通对象，不适用。
  */
 function createProviderProxy(current) {
-  return {
-    get name() {
-      return current().name
-    },
-    decide(options) {
-      return current().decide(options)
-    },
-  }
+  // trap 的第一个参数是创建时固定的代理目标（占位空对象），必须丢弃、
+  // 换成「当前提供商实例」——转发全部 trap 参数会把占位对象错当成属性名
+  const forward = (name) => (_target, ...args) => Reflect[name](current(), ...args)
+  return new Proxy({}, {
+    get: forward('get'),
+    set: forward('set'),
+    has: forward('has'),
+    deleteProperty: forward('deleteProperty'),
+    ownKeys: forward('ownKeys'),
+    getOwnPropertyDescriptor: forward('getOwnPropertyDescriptor'),
+    defineProperty: forward('defineProperty'),
+    getPrototypeOf: forward('getPrototypeOf'),
+    setPrototypeOf: forward('setPrototypeOf'),
+    isExtensible: forward('isExtensible'),
+  })
 }
 
 /**
@@ -60,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(),
@@ -72,6 +100,12 @@ const Config = z.object({
   timeoutMs: z.number().min(1000).default(30000).volatile(),
   /** 置信度阈值：任一答案低于该值则建议人工复核 */
   minConfidence: z.number().min(0).max(1).default(0.6).volatile(),
+  /**
+   * 发送前对 state 做内置脱敏：手机号/身份证/邮箱/银行卡号替换为
+   * `[手机号]` 等类型标签（判断语义保留）。state 会发给上游决策服务，
+   * 处理含隐私数据的场景（尤其 data_governance）时建议开启。
+   */
+  redact: z.boolean().default(false).volatile(),
 
   /* ── 结构性字段：不在配置页里，改动需要重启 ───────────────────────────────── */
 
@@ -81,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(),
   /** 捕获的历史消息条数（不含本轮新消息） */
@@ -95,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 {
@@ -135,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') {
@@ -144,6 +211,7 @@ export default class SystemOneService extends Service {
       // 惰性读取：场景库可能已随 customScenarios 热更新重建，
       // 这里必须每次取最新的 warnings，而不是装配期快照。
       warnings: () => this.scenarioWarnings || [],
+      usage: this.usageLedger,
     }).map((tool) => tools.register(tool))
 
     // 自动决策：默认关闭；开启后在每一步推理前自动捕获上下文并注入判断
@@ -155,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}`)
@@ -168,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` 配置变化时按需重建。
    *
@@ -181,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,10 +15,15 @@
  *   - "mock"    ：本地确定性模拟（无需 API Key，用于测试与演示）
  */
 
-import { readNumber, readString } from './volatile.js'
+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'
 const DEFAULT_MODEL = 'u2-decision'
+/** 临时故障（5xx/429/网络错误）自动重试次数与退避间隔；决策请求是幂等读，重发安全。 */
+const RETRY_LIMIT = 1
+const RETRY_DELAY_MS = 300
 
 /** 创建提供商实例。config 来自插件配置（已由 Config schema 校验）。未知 provider 值回退到 unisound（入口层负责告警）。 */
 export function createProvider(config) {
@@ -49,21 +54,31 @@ export class HttpProvider {
       if (!ep) {
         throw new Error('SystemOne: provider=http 需要配置 endpoint 或 baseUrl')
       }
-      return ep
+      return assertValidUrl(ep)
     }
     const base = String(baseUrl || DEFAULT_BASE_URL).trim().replace(/\/+$/, '')
-    return `${base}/systemone`
+    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
@@ -78,6 +93,11 @@ export class HttpProvider {
     const endpoint = this.resolveEndpoint()
     const apiKey = this.resolveApiKey()
     const timeoutMs = readNumber(this.config, 'timeoutMs', 30000) || 30000
+    const body = JSON.stringify({
+      model: model || readString(this.config, 'model', DEFAULT_MODEL) || DEFAULT_MODEL,
+      state: redactValue(state, readBoolean(this.config, 'redact', false)),
+      questions,
+    })
 
     const controller = new AbortController()
     const timer = setTimeout(() => controller.abort(new Error(`SystemOne: 请求超时（${timeoutMs}ms）`)), timeoutMs)
@@ -91,35 +111,49 @@ export class HttpProvider {
       }
     }
 
-    try {
+    /** 单次请求：非 2xx 抛错并带上 status，供重试判定。 */
+    const sendOnce = async () => {
       const res = await fetch(endpoint, {
         method: 'POST',
         headers: {
           Authorization: `Bearer ${apiKey}`,
           'Content-Type': 'application/json',
         },
-        body: JSON.stringify({
-          model: model || readString(this.config, 'model', DEFAULT_MODEL) || DEFAULT_MODEL,
-          state,
-          questions,
-        }),
+        body,
         signal: controller.signal,
       })
-
       const text = await res.text().catch(() => '')
       if (!res.ok) {
-        throw new Error(
+        const error = new Error(
           `SystemOne: HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''} — ${text.slice(0, 500) || '无响应体'}`,
         )
+        error.status = res.status
+        throw error
       }
-
-      let data
       try {
-        data = JSON.parse(text)
+        return JSON.parse(text)
       } catch {
         throw new Error(`SystemOne: 响应不是合法 JSON — ${text.slice(0, 300) || '空响应'}`)
       }
-      return data
+    }
+
+    try {
+      let lastError
+      for (let attempt = 0; attempt <= RETRY_LIMIT; attempt += 1) {
+        if (attempt > 0) {
+          // 已中止（超时/外部取消）不再重试，让上一次的原始错误穿透
+          if (controller.signal.aborted) throw lastError
+          await sleep(RETRY_DELAY_MS)
+        }
+        try {
+          return await sendOnce()
+        } catch (error) {
+          lastError = error
+          if (attempt < RETRY_LIMIT && !controller.signal.aborted && isRetryable(error)) continue
+          throw error
+        }
+      }
+      throw lastError
     } finally {
       clearTimeout(timer)
       if (signal && typeof signal.removeEventListener === 'function') {
@@ -195,11 +229,12 @@ function mockAnswer(id, q, seedSource) {
         confidence: probabilities[top],
       }
     }
-    case 'noul':
-      return {
-        type: 'noul',
-        noul: Math.round((rand() * 0.6 + 0.2) * 1000) / 1000,
-      }
+    case 'noul': {
+      // 与真实响应对齐：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) }
+    }
     case 'score': {
       const list = Array.isArray(q.criteria) ? q.criteria : []
       const len = Math.max(list.length, 1)
@@ -247,4 +282,154 @@ function mulberry32(seed) {
     t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
     return ((t ^ (t >>> 14)) >>> 0) / 4294967296
   }
+}
+
+/* ─── 敏感数据脱敏（redact=true 时，发送前对 state 生效） ──────────────────── */
+
+/**
+ * 内置脱敏规则：手机号/身份证/邮箱/银行卡号替换为类型标签。
+ * 替换成标签（而不是抹成 ***）是有意的：决策模型仍能看出「这段内容
+ * 包含手机号」——对 data_governance 这类场景，这个信号正是判断依据。
+ * 顺序有意义：身份证（18 位）先于银行卡（13~19 位）匹配，
+ * 环视断言保证不会在更长的数字串内部截取匹配。
+ */
+const REDACT_RULES = [
+  { pattern: /(?<![\dXx])\d{17}[\dXx](?![\dXx])/g, tag: '[身份证]' },
+  { pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, tag: '[邮箱]' },
+  { pattern: /(?<!\d)1[3-9]\d{9}(?!\d)/g, tag: '[手机号]' },
+  { pattern: /(?<!\d)\d{13,19}(?!\d)/g, tag: '[银行卡号]' },
+]
+
+function redactString(text) {
+  return REDACT_RULES.reduce((acc, rule) => acc.replace(rule.pattern, rule.tag), text)
+}
+
+/**
+ * 递归脱敏 state：字符串叶子做规则替换，对象/数组逐层下钻。
+ * 不修改原对象（调用方可能还要用），返回脱敏后的副本；非字符串叶子原样保留。
+ */
+function redactValue(value, enabled) {
+  if (!enabled) return value
+  if (typeof value === 'string') return redactString(value)
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, enabled))
+  if (value !== null && typeof value === 'object') {
+    const out = {}
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = redactValue(item, enabled)
+    }
+    return out
+  }
+  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 的报错非常隐晦，不如直接说清楚。 */
+function assertValidUrl(url) {
+  try {
+    new URL(url)
+  } catch {
+    throw new Error(`SystemOne: 端点不是合法 URL：${url}（需以 http:// 或 https:// 开头）`)
+  }
+  return url
+}
+
+/** 仅临时故障值得重试：5xx、429 限流、网络层错误（fetch 失败抛 TypeError）。 */
+function isRetryable(error) {
+  if (error instanceof TypeError) return true
+  return error?.status === 429 || (typeof error?.status === 'number' && error.status >= 500)
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    timer.unref?.()
+  })
 }