@master0071/dsh-systemone 0.4.4 → 0.5.0

package/README.md

@@ -11,9 +11,9 @@ SystemOne 协议一次请求携带业务状态与**结构化问题**（`choice`
 
 ---
 
-## 内置场景（10 大业务域）
+## 内置场景（11 大业务域）
 
-每个场景 = 3 个结构化问题，覆盖 30 项业务能力。
+每个场景 = 3 个结构化问题，覆盖 33 项业务能力。
 
 | 场景 id | 业务域 | 覆盖能力 |
 | --- | --- | --- |
@@ -27,6 +27,7 @@ SystemOne 协议一次请求携带业务状态与**结构化问题**（`choice`
 | `education` | 教育内容 | 题目知识点归类、难度分级评分、内容合规预检 |
 | `requirements` | 需求与变更 | 优先级评分、变更风险评级、子任务派发 |
 | `software_dev` | **软件开发** | 任务类型（缺陷/功能/重构/评审/测试/文档/构建/性能）、改动复杂度、是否需先探查代码库 |
+| `requirement_clarity` | **需求预检** | 需求明确度评分、最缺信息（目标/范围/验收/约束）、不澄清就推进的返工风险 |
 
 ### `software_dev`：给编码 Agent 用的软件开发场景
 
@@ -126,7 +127,7 @@ systemone_decide(
 
 - **提供商无关**：所有工具只依赖统一的 `provider.decide()` 接口。切换厂商只改一行配置，业务工具零改动。
 - **图形配置页**：侧栏「插件 → @master0071/dsh-systemone → systemone」里可直接改提供商、Key、模型与自动决策参数，保存即生效（volatile 热更新，无需重启）。
-- **场景可扩展**：内置 10 大场景（含软件开发），并可在配置页里用 JSON 追加或覆盖场景，**无需改代码、无需重启**
+- **场景可扩展**：内置 11 大场景（含软件开发与需求预检），并可在配置页里用 JSON 追加或覆盖场景，**无需改代码、无需重启**
 - **可自动决策**：开启后挂 `agent/pre-step`，每一步推理前自动捕获上下文并注入判断（fail-open、硬超时、可缓存）。
 - **概率化输出**：返回每个选项的概率分布与置信度，而非单一答案。
 - **置信度兜底**：任一答案置信度低于 `minConfidence`（默认 0.6）时标记 `needs_human_review: true`。
@@ -318,6 +319,7 @@ const decision = await waterfall('agent/pre-step', {         // ③ 再跑瀑布
 | `model` | `u2-decision` | 热更新 | 决策模型名 |
 | `timeoutMs` | `30000` | 热更新 | 请求超时（毫秒） |
 | `minConfidence` | `0.6` | 热更新 | 置信度阈值，低于则建议人工复核 |
+| `redact` | `false` | 热更新 | 发送前对 `state` 脱敏：手机号/身份证/邮箱/银行卡号替换为 `[手机号]` 等类型标签（判断语义保留；处理含隐私数据的内容时建议开启） |
 | `customScenarios` | 空 | 热更新 | 自定义场景 JSON 数组（见下）。保存后**场景库立即重建**，无需重启 |
 | `autoDecide` | `false` | 需重启 | 是否开启自动决策（挂载 `agent/pre-step`） |
 | `auto*` | 见「自动决策」 | 热更新 | 自动决策的运行参数（钩子挂载后实时生效） |
@@ -334,6 +336,14 @@ const decision = await waterfall('agent/pre-step', {         // ③ 再跑瀑布
 
 覆盖与别名的解析规则：
 
+- **patch 式覆盖**：默认同 `id` 是**整体替换**。只想改一两个字段时，给条目加 `"patch": true` 即可做**字段级合并**——`title`/`description`/`recommendation` 给了才覆盖；`questions` 按 qid 合并（只换给出的字段，如只覆盖某个问题的 `criteria`，其余问题原样保留，新 qid 追加）；`derive` 同名覆盖；`aliases` 求并集。例如给 `customer_service` 的部门问题加一个 VIP 通道：
+
+  ```json
+  [{ "id": "customer_service", "patch": true,
+     "questions": { "department": { "criteria": { "vip": "VIP 专属通道", "billing": "账单", "technical": "技术", "account": "账号", "logistics": "物流", "other": "其他" } } } }]
+  ```
+
+  patch 目标不存在、或合并结果非法（如 choice 选项少于 2 个）时该条目会被跳过并记入日志。不带 `patch` 的条目维持整体替换语义，已有配置不受影响。
 - **同 `id` 覆盖**：自定义场景替换同名内置场景，只写 `title`/`questions` 也够——被替换场景原有的 `aliases` 会被**继承**（省略 `aliases` 不等于清空别名），新声明的别名与继承的别名共存且自动去重。
 - **别名冲突**：别名与 `id` 平权参与查找，冲突时**后登记者获胜**（自定义场景优先于内置场景，自定义之间后声明者优先）。因此自定义场景声明的别名一定指向它自己，不会被内置场景抢走。
 - **冲突提示**：别名撞名是**非致命**的——场景照常可用，但插件会给出提示（宿主日志里带「（提示）」前缀，`systemone_scenario(action: "list")` 的 `warnings` 字段与「配置提示」小节里也会列出），说明谁遮蔽了谁，避免调用方把「别名被占」误判成「场景不存在」。
@@ -380,7 +390,7 @@ SystemOne 是「结构化问题 → 概率分布」的决策模型，**不是开
 ]
 ```
 
-配合 `autoScenario: "intent"`，自动决策就不再受内置 10 个业务场景的约束。
+配合 `autoScenario: "intent"`，自动决策就不再受内置 11 个业务场景的约束。
 
 **容量上限**：每个场景最多 **16 个问题**（延迟随问题数线性增长），`choice` 的选项 **2~26 个**，所以意图标签集实践上限约 26 类——超了只能合并或落到 `other`。
 
@@ -473,7 +483,7 @@ SystemOne 是「结构化问题 → 概率分布」的决策模型，**不是开
 ```powershell
 npm run check   # 语法检查
 npm run test    # 59 项测试：
-                # - 场景库完整性、10 大场景端到端、自定义场景合并/覆盖/非法跳过
+                # - 场景库完整性、11 大场景端到端、自定义场景合并/覆盖/patch/非法跳过
                 # - params 覆盖语义、确定性、失败路径（无网络、无 Key）
                 # - 插件入口装配（临时桩实例化：工具注册、降级、卸载）
                 # - 自动决策（开关、注入形状、fail-open、硬超时、缓存、去重、

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: '（空 = 只用内置场景）',
@@ -72,8 +72,12 @@ 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）',
@@ -112,7 +116,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)',
@@ -142,8 +146,12 @@ 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)',
@@ -268,7 +276,7 @@ window.__ModuleLoader__.load({
     /**
      * 内置场景候选（供「固定场景」输入框的下拉提示）。
      *
-     * 用 `<datalist>` 而不是 `<select>`：既能把 10 个内置场景列出来点选，
+     * 用 `<datalist>` 而不是 `<select>`：既能把 11 个内置场景列出来点选，
      * 又允许手填自定义场景 id 或别名（别名见 README 的场景表）。
      * 这里只放 id + 中文标题；id 用别名也能命中（findScenario 会按别名匹配）。
      */
@@ -283,6 +291,7 @@ window.__ModuleLoader__.load({
       { id: 'education', label: '教育内容 · 知识点、难度与合规' },
       { id: 'requirements', label: '需求与变更 · 优先级、风险与派发' },
       { id: 'software_dev', label: '软件开发 · 任务类型、复杂度与处置' },
+      { id: 'requirement_clarity', label: '需求预检 · 明确度与澄清点' },
     ]
 
     const SERVICE_FIELDS = [
@@ -293,6 +302,7 @@ window.__ModuleLoader__.load({
       { key: 'model', kind: 'text' },
       { key: 'timeoutMs', kind: 'number' },
       { key: 'minConfidence', kind: 'number' },
+      { key: 'redact', kind: 'select', options: ['false', 'true'] },
     ]
 
     /** 自定义场景编辑区（JSON）。 */
@@ -328,35 +338,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 的数组`)
+              }
             }
           }
         }
@@ -390,6 +422,9 @@ window.__ModuleLoader__.load({
         if (value === 'message') return t('autoInjectMessage')
         if (value === 'context') return t('autoInjectContext')
       }
+      if (key === 'redact') {
+        return value === 'true' ? t('redactOn') : t('redactOff')
+      }
       return value
     }
 
@@ -599,11 +634,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 +667,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 +871,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/index.d.ts

@@ -19,6 +19,8 @@ export interface Config {
   timeoutMs?: number
   /** 置信度阈值 */
   minConfidence?: number
+  /** 发送前对 state 做内置脱敏（手机号/身份证/邮箱/银行卡号替换为类型标签） */
+  redact?: boolean
   /** 自定义场景：JSON 数组字符串 */
   customScenarios?: string
 

package/lib/index.js

@@ -7,7 +7,7 @@
  * - 注册 2 个 Agent 工具：
  *     systemone_scenario — 统一场景调度（list / describe / run）
  *     systemone_decide   — 自定义问题的低层入口
- * - 场景库内置 10 大业务域，并支持在配置里用 JSON 追加/覆盖场景
+ * - 场景库内置 11 大业务域，并支持在配置里用 JSON 追加/覆盖/patch 场景
  * - 暴露 `ctx.systemone.decide()` 供其他插件编程调用
  * - 提供商可配置（unisound / http / mock），切换厂商不影响工具层
  */
@@ -27,16 +27,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'),
+  })
 }
 
 /**
@@ -72,6 +85,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(),
 
   /* ── 结构性字段：不在配置页里，改动需要重启 ───────────────────────────────── */
 

package/lib/provider.js

@@ -15,10 +15,13 @@
  *   - "mock"    ：本地确定性模拟（无需 API Key，用于测试与演示）
  */
 
-import { readNumber, readString } from './volatile.js'
+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,10 +52,10 @@ 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：配置优先，其次环境变量。 */
@@ -78,6 +81,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 +99,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 +217,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 下 computeNeedsHumanReview 走不到置信度分支
+      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 +270,67 @@ 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
+}
+
+/* ─── 通用内部工具 ─────────────────────────────────────────────────────────── */
+
+/** 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?.()
+  })
 }

package/lib/scenarios.js

@@ -7,10 +7,10 @@
  * 场景定义格式：
  * {
  *   id: string,                       // 唯一标识（必填）
- *   title: string,                    // 展示名（必填）
+ *   title: string,                    // 展示名（必填；patch 条目可省略，继承目标场景）
  *   description?: string,             // 场景说明
  *   aliases?: string[],               // 别名，便于模型用中文名/英文名查找
- *   questions: {                      // 问题映射（必填，至少 1 个）
+ *   questions: {                      // 问题映射（必填，至少 1 个；patch 条目可省略）
  *     [qid]: {
  *       type: 'choice' | 'noul' | 'score',
  *       instructions: string,         // 给模型的问题描述
@@ -22,6 +22,7 @@
  *     [name]: { question: string, values?: string[], map?: object }
  *   },
  *   recommendation?: string,          // 可选建议模板
+ *   patch?: boolean,                  // true=与同 id 已有场景做字段级合并（只覆盖给出的字段），默认整体替换
  * }
  *
  * 建议模板语法：
@@ -32,7 +33,7 @@
  *   {qid?文案A|文案B}     → 条件文案（noul 为真 / 分值≥1 / choice 非空非 none 时取 A）
  */
 
-/** 内置场景：10 个业务域，每个 3 个结构化问题。 */
+/** 内置场景：11 个业务域，每个 3 个结构化问题。 */
 export const BUILTIN_SCENARIOS = [
   {
     id: 'customer_service',
@@ -384,6 +385,44 @@ export const BUILTIN_SCENARIOS = [
     derive: { effort: { question: 'complexity', values: ['S', 'M', 'L', 'XL'] } },
     recommendation: '任务类型「{task_type}」，改动规模 {effort}。{needs_context?建议先检索代码库并确认相关实现|可直接动手}',
   },
+  {
+    id: 'requirement_clarity',
+    title: '需求预检 · 明确度与澄清点',
+    description: '接到开发需求先做结构化预检：判断明确程度、最缺什么信息、不澄清就推进的返工风险。',
+    // 别名刻意避开 requirements 已占用的 requirement / 需求 / 变更管理
+    aliases: ['clarity', '预检', '需求预检'],
+    questions: {
+      clarity: {
+        type: 'score',
+        label: '明确度',
+        instructions: '该开发任务的需求明确程度是？',
+        criteria: [
+          '模糊：目标都不清楚',
+          '偏低：目标清楚但范围或关键约束不明',
+          '较高：目标范围清楚，细节可自行决策',
+          '明确：目标、范围、验收都清楚',
+        ],
+      },
+      missing: {
+        type: 'choice',
+        label: '缺失项',
+        instructions: '当前最需要澄清的信息是？',
+        criteria: {
+          goal: '目标/预期结果',
+          scope: '范围与边界',
+          acceptance: '验收标准',
+          constraint: '技术约束或依赖',
+          none: '无明显缺失',
+        },
+      },
+      proceed: {
+        type: 'noul',
+        label: '可直接推进',
+        instructions: '不做额外澄清就推进，返工风险是否可接受？',
+      },
+    },
+    recommendation: '明确度 {clarity}，最缺 {missing}。{proceed?可直接推进|建议先澄清目标再动手}',
+  },
 ]
 
 const VALID_TYPES = new Set(['choice', 'noul', 'score'])
@@ -488,12 +527,24 @@ export function resolveScenarios(customJson) {
   })
 
   parsed.forEach((spec, i) => {
-    const issues = validateScenario(spec)
+    let candidate = spec
+    // patch 条目：先与同 id 已有场景做字段级合并，再走与整体替换完全相同的
+    // 校验/规范化/别名继承路径——patch 与替换的唯一区别就在这一步合并。
+    if (spec && typeof spec === 'object' && !Array.isArray(spec) && spec.patch === true) {
+      const id = typeof spec.id === 'string' ? spec.id.trim() : ''
+      const key = id.toLowerCase()
+      if (!id || !indexById.has(key)) {
+        problems.push(`自定义场景 #${i + 1} 已跳过：patch 目标 "${id || '（未提供）'}" 不在场景库中（patch 只能修改已有场景）`)
+        return
+      }
+      candidate = mergeScenario(scenarios[indexById.get(key)], spec)
+    }
+    const issues = validateScenario(candidate)
     if (issues.length > 0) {
       problems.push(`自定义场景 #${i + 1} 已跳过：${issues.join('；')}`)
       return
     }
-    const entry = normalizeScenario(spec)
+    const entry = normalizeScenario(candidate)
     const key = entry.id.toLowerCase()
 
     // 别名撞名是一条提示：声明者获胜（后写优先），被遮蔽者从此无法通过该别名查到。
@@ -537,6 +588,47 @@ export function resolveScenarios(customJson) {
   return { scenarios, problems, warnings }
 }
 
+/**
+ * 把 patch 条目与已有场景做字段级合并，产出「完整场景定义」形状的对象：
+ * - title/description/recommendation：patch 给了才覆盖，否则保留目标的值；
+ * - questions：按 qid 合并——patch 里给出的字段（instructions/label/criteria）
+ *   覆盖目标同名问题的对应字段，其余问题原样保留，新 qid 直接追加；
+ * - derive：同名派生覆盖，其余保留；
+ * - aliases：目标与 patch 求并集（与整体替换的继承规则一致）。
+ *
+ * 返回值随后会重新过 validateScenario：patch 把合法问题改非法（如 criteria
+ * 少于 2 个选项）在校验处被拦下，而不是静默产出坏场景。
+ */
+function mergeScenario(target, spec) {
+  // Object.create(null)：patch 里的 __proto__ 这类键只会长成普通属性，
+  // 由 validateScenario 的 isUnsafeKey 统一拦下，不会走到原型 setter
+  const questions = Object.create(null)
+  for (const [qid, question] of Object.entries(target.questions || {})) {
+    questions[qid] = question
+  }
+  for (const [qid, patch] of Object.entries(spec.questions || {})) {
+    questions[qid] = patch && typeof patch === 'object'
+      ? { ...(questions[qid] || {}), ...patch }
+      : patch
+  }
+  return {
+    id: target.id,
+    title: typeof spec.title === 'string' && spec.title.trim() ? spec.title : target.title,
+    description: typeof spec.description === 'string' ? spec.description : target.description,
+    aliases: [
+      ...(target.aliases || []),
+      ...(Array.isArray(spec.aliases) ? spec.aliases : []),
+    ],
+    questions,
+    derive: {
+      ...(target.derive || {}),
+      ...(spec.derive && typeof spec.derive === 'object' && !Array.isArray(spec.derive) ? spec.derive : {}),
+    },
+    recommendation: typeof spec.recommendation === 'string' ? spec.recommendation : target.recommendation,
+    minConfidence: typeof spec.minConfidence === 'number' ? spec.minConfidence : target.minConfidence,
+  }
+}
+
 /**
  * 规范化场景定义，补齐可选字段。
  *

package/lib/tools.js

@@ -5,7 +5,7 @@
  *   1. systemone_scenario — action: list / describe / run，覆盖全部内置与自定义场景
  *   2. systemone_decide   — 直接提交自定义 questions 的低层入口
  *
- * 场景全部来自 scenarios.js 的场景库（内置 10 个 + 配置追加），新增场景无需改代码。
+ * 场景全部来自 scenarios.js 的场景库（内置 11 个 + 配置追加），新增场景无需改代码。
  */
 import {
   computeNeedsHumanReview,
@@ -20,6 +20,36 @@ import { readNumber, readString } from './volatile.js'
 
 const DEFAULT_MIN_CONFIDENCE = 0.6
 
+/**
+ * 工具入参 state 的硬上限。自动决策路径有自己的截断（见 auto.js 的
+ * MAX_CURRENT_CHARS / 每条历史 2000 字），这里只防工具路径被塞进超大输入
+ * 直接打到上游 API；超长内容对决策质量也没有增量。
+ */
+const MAX_TOOL_STATE_CHARS = 16000
+
+/**
+ * 给 state 套硬上限：超长字符串截断；对象/数组按序列化长度衡量，
+ * 超限降级为截断后的 JSON 文本（决策模型反正是按文本理解的）。
+ * undefined/null/空字符串原样返回，让「缺少 state」的校验路径保持不变。
+ */
+function capState(state) {
+  if (state === undefined || state === null) return state
+  if (typeof state === 'string') {
+    return state.length <= MAX_TOOL_STATE_CHARS
+      ? state
+      : `${state.slice(0, MAX_TOOL_STATE_CHARS)}…（已截断，原 ${state.length} 字符）`
+  }
+  let serialized
+  try {
+    serialized = JSON.stringify(state)
+  } catch {
+    // 循环引用等无法序列化的结构：原样交给下游，由序列化失败的报错路径兜底
+    return state
+  }
+  if (serialized.length <= MAX_TOOL_STATE_CHARS) return state
+  return `${serialized.slice(0, MAX_TOOL_STATE_CHARS)}…（已截断，原 ${serialized.length} 字符）`
+}
+
 /**
  * 创建全部工具定义。
  *
@@ -45,7 +75,7 @@ function scenarioTool(provider, config, scenarios, hooks = {}) {
     description: [
       'SystemOne 场景决策：把业务状态与预置的结构化问题一次性提交给决策模型，返回带概率分布的判断与处置建议。',
       'action=list 列出全部场景；action=describe 查看某个场景的问题定义与可覆盖参数；action=run 执行决策。',
-      '内置 10 大业务场景，可用 params 覆盖问题定义。',
+      '内置 11 大业务场景，可用 params 覆盖问题定义。',
     ].join(' '),
     parameters: {
       type: 'object',
@@ -93,7 +123,7 @@ function scenarioTool(provider, config, scenarios, hooks = {}) {
         config,
         scenarios,
         scenario: args.scenario,
-        state: args.state,
+        state: capState(args.state),
         params: args.params,
         exec,
       })
@@ -367,7 +397,7 @@ function decideTool(provider, config) {
       return executeDecision({
         title: 'SystemOne 通用决策',
         scenarioId: null,
-        state: args.state,
+        state: capState(args.state),
         questions: args.questions || {},
         provider,
         config,

package/package.json

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