@master0071/dsh-systemone 0.4.4 → 0.6.0

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,18 @@
  *   {qid?文案A|文案B}     → 条件文案（noul 为真 / 分值≥1 / choice 非空非 none 时取 A）
  */
 
-/** 内置场景：10 个业务域，每个 3 个结构化问题。 */
+/**
+ * choice 题型的选项数上限。
+ *
+ * 单一真源：场景校验（validateScenario）与自动路由的分批逻辑都读这里。
+ * 上游决策模型对 choice 的选项数有硬限制，超过会被拒——因此不仅是"建议"。
+ */
+export const MAX_CHOICE_OPTIONS = 26
+
+/** choice 题型的选项数下限。 */
+export const MIN_CHOICE_OPTIONS = 2
+
+/** 内置场景：11 个业务域，每个 3 个结构化问题。 */
 export const BUILTIN_SCENARIOS = [
   {
     id: 'customer_service',
@@ -384,6 +396,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'])
@@ -426,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)) {
@@ -488,12 +538,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 +599,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,21 +5,52 @@
  *   1. systemone_scenario — action: list / describe / run，覆盖全部内置与自定义场景
  *   2. systemone_decide   — 直接提交自定义 questions 的低层入口
  *
- * 场景全部来自 scenarios.js 的场景库（内置 10 个 + 配置追加），新增场景无需改代码。
+ * 场景全部来自 scenarios.js 的场景库（内置 11 个 + 配置追加），新增场景无需改代码。
  */
 import {
-  computeNeedsHumanReview,
   deriveFields,
   formatAnswerLines,
   formatSummary,
   normalizeAnswers,
   renderTemplate,
+  reviewAssessment,
 } from './format.js'
 import { findScenario } from './scenarios.js'
+import { recordUsage } from './usage.js'
 import { readNumber, readString } from './volatile.js'
 
 const DEFAULT_MIN_CONFIDENCE = 0.6
 
+/**
+ * 工具入参 state 的硬上限。自动决策路径有自己的截断（见 auto.js 的
+ * MAX_CURRENT_CHARS / 每条历史 2000 字），这里只防工具路径被塞进超大输入
+ * 直接打到上游 API；超长内容对决策质量也没有增量。
+ */
+export 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} 字符）`
+}
+
 /**
  * 创建全部工具定义。
  *
@@ -29,11 +60,12 @@ const DEFAULT_MIN_CONFIDENCE = 0.6
  * @param {object} [hooks] - 可选运行时钩子
  * @param {() => string[]} [hooks.warnings] - 读取当前非致命提示（如别名遮蔽），
  *   用于让 `action=list` 把「哪个别名被抢走了」告诉模型，而不只是写进宿主日志。
+ * @param {object} [hooks.usage] - 用量台账（createUsageLedger 的返回值）。有则记录每次上游调用。
  */
 export function createTools(provider, config, scenarios, hooks = {}) {
   return [
     scenarioTool(provider, config, scenarios, hooks),
-    decideTool(provider, config),
+    decideTool(provider, config, hooks),
   ]
 }
 
@@ -45,7 +77,7 @@ function scenarioTool(provider, config, scenarios, hooks = {}) {
     description: [
       'SystemOne 场景决策：把业务状态与预置的结构化问题一次性提交给决策模型，返回带概率分布的判断与处置建议。',
       'action=list 列出全部场景；action=describe 查看某个场景的问题定义与可覆盖参数；action=run 执行决策。',
-      '内置 10 大业务场景，可用 params 覆盖问题定义。',
+      '内置 11 大业务场景，可用 params 覆盖问题定义。',
     ].join(' '),
     parameters: {
       type: 'object',
@@ -83,7 +115,7 @@ function scenarioTool(provider, config, scenarios, hooks = {}) {
       const action = args.action || 'run'
 
       if (action === 'list') {
-        return listScenarios(scenarios, args.keyword, readWarnings(hooks))
+        return listScenarios(scenarios, args.keyword, readWarnings(hooks), hooks?.usage)
       }
       if (action === 'describe') {
         return describeScenario(scenarios, args.scenario)
@@ -93,9 +125,10 @@ function scenarioTool(provider, config, scenarios, hooks = {}) {
         config,
         scenarios,
         scenario: args.scenario,
-        state: args.state,
+        state: capState(args.state),
         params: args.params,
         exec,
+        usage: hooks?.usage,
       })
     },
     presentCall: (args) => ({
@@ -117,7 +150,7 @@ function readWarnings(hooks) {
   }
 }
 
-function listScenarios(scenarios, keyword, warnings = []) {
+function listScenarios(scenarios, keyword, warnings = [], usage) {
   const needle = typeof keyword === 'string' ? keyword.trim().toLowerCase() : ''
   const items = scenarios
     .filter((s) => {
@@ -136,6 +169,19 @@ function listScenarios(scenarios, keyword, warnings = []) {
       questions: Object.entries(s.questions).map(([qid, q]) => `${qid}:${q.type}`),
     }))
 
+  // 用量台账：list 是调用方最容易顺手调用的入口，把今日花销挂在这里，
+  // 让「花了多少」不需要另开一个工具就能看到。
+  let usageLine = null
+  let usageSnapshot = null
+  try {
+    if (typeof usage?.today === 'function') {
+      usageSnapshot = usage.today()
+      usageLine = typeof usage.formatToday === 'function' ? usage.formatToday() : null
+    }
+  } catch {
+    // 台账读取失败不影响 list
+  }
+
   const summary = [
     `## SystemOne 场景库（${items.length} 个）`,
     ...items.map((s) => `- **${s.id}**：${s.title} — ${s.question_count} 个问题（${s.questions.join('，')}）`),
@@ -144,6 +190,7 @@ function listScenarios(scenarios, keyword, warnings = []) {
     ...(warnings.length > 0
       ? ['', '### 配置提示', ...warnings.map((w) => `- ${w}`)]
       : []),
+    ...(usageLine ? ['', '### 用量', `- ${usageLine}`] : []),
     '',
     '用 action=describe 查看某场景的问题定义，用 action=run 执行决策。',
   ].join('\n')
@@ -154,6 +201,7 @@ function listScenarios(scenarios, keyword, warnings = []) {
     count: items.length,
     scenarios: items,
     ...(warnings.length > 0 ? { warnings } : {}),
+    ...(usageSnapshot ? { usage_today: usageSnapshot } : {}),
     summary,
   }
 }
@@ -207,6 +255,7 @@ function describeScenario(scenarios, id) {
  * @param {object} [options.params] - 按问题 id 覆盖问题定义
  * @param {object} [options.exec] - 工具执行上下文（取 signal）
  * @param {number} [options.minConfidence] - 覆盖置信度阈值
+ * @param {object} [options.usage] - 用量台账；有则记录本次调用
  * @returns {Promise<object>} 与工具输出同构的决策结果
  */
 export async function runScenarioDecision({
@@ -218,6 +267,7 @@ export async function runScenarioDecision({
   params,
   exec,
   minConfidence,
+  usage,
 }) {
   const scenario = findScenario(scenarios, scenarioRef)
   if (!scenario) {
@@ -256,6 +306,7 @@ export async function runScenarioDecision({
     config,
     minConfidence: threshold,
     exec,
+    usage,
     warnings: ignored.length > 0
       ? [`以下 params 覆盖无效，已忽略：${ignored.join('；')}`]
       : [],
@@ -325,7 +376,7 @@ function applyParams(questions, params) {
 
 /* ─── 2. 通用决策工具 ─────────────────────────────────────────────────────── */
 
-function decideTool(provider, config) {
+function decideTool(provider, config, hooks = {}) {
   return {
     name: 'systemone_decide',
     description: [
@@ -367,13 +418,14 @@ function decideTool(provider, config) {
       return executeDecision({
         title: 'SystemOne 通用决策',
         scenarioId: null,
-        state: args.state,
+        state: capState(args.state),
         questions: args.questions || {},
         provider,
         config,
         minConfidence,
         exec,
         model: args.model,
+        usage: hooks?.usage,
         finalize(answers) {
           const { decision, labels, confidences } = normalizeAnswers(answers, args.questions || {})
           return { decision, labels, derived: {}, confidences, recommendation: '' }
@@ -403,6 +455,7 @@ async function executeDecision({
   model,
   finalize,
   warnings = [],
+  usage,
 }) {
   try {
     const started = Date.now()
@@ -413,9 +466,69 @@ async function executeDecision({
       model: model || configuredModel,
       signal: exec?.signal,
     })
+    // 记账：成功与失败都记（上游可能已计费）。记账失败绝不影响决策。
+    recordUsage(usage, {
+      source: 'tool',
+      ok: true,
+      model: response.model || model || configuredModel,
+      provider: provider.name,
+      scenario: scenarioId || '',
+      usage: response.usage,
+      latencyMs: response.latency_ms,
+    })
     const answers = response.answers || {}
     const { decision, labels, derived, confidences, recommendation } = finalize(answers)
-    const needsHumanReview = computeNeedsHumanReview(answers, minConfidence)
+
+    // ── 空决策守卫 ────────────────────────────────────────────────────────────
+    // 必须同时覆盖两种"沉默"形态：
+    //   a) answers 为空 / 全是无法识别的 type → decision 里一个键都没有；
+    //   b) 有 answers 但关键字段缺失（如 noul 答案没有 noul 数值）→
+    //      normalizeAnswers 会把该问题写成 null（"无法判断"）。
+    // 注意 type 的取值是 `question.type || raw.type`：上游给个无法识别的 type、
+    // 而问题定义是合法 type 时，会走 (b) 这条路——所以只看 decision 是否为空
+    // 是不够的，必须看**有没有任何一个问题真正产出了判断**。
+    // 若此时仍报 ok:true，调用方（模型）会以为"判断已完成"，实际拿到的是空判断；
+    // 对决策工具来说，这种静默空成功比显式失败更危险。
+    const asked = Object.keys(questions || {})
+    const usable = asked.filter((qid) => {
+      const value = decision[qid]
+      return value !== null && value !== undefined
+    })
+    if (usable.length === 0) {
+      const returned = Object.keys(answers)
+      const unusable = asked.filter((qid) => qid in decision)
+      let detail
+      if (asked.length === 0) {
+        detail = '本次没有提交任何问题'
+      } else if (returned.length === 0) {
+        detail = `提交了 ${asked.length} 个问题（${asked.join('、')}）；上游未返回任何 answers`
+      } else if (unusable.length > 0) {
+        detail = `提交了 ${asked.length} 个问题（${asked.join('、')}）；上游返回的 answers 里没有可用取值`
+          + `（无法判断：${unusable.join('、')}）`
+      } else {
+        detail = `提交了 ${asked.length} 个问题（${asked.join('、')}）；`
+          + `上游仅返回了 ${returned.join('、')}，与所问的问题对不上`
+      }
+      const error = `SystemOne 未产出任何可用的决策：${detail}`
+      return {
+        ok: false,
+        scenario: scenarioId,
+        provider: provider.name,
+        error,
+        answers,
+        decision,
+        labels,
+        derived: {},
+        confidences: {},
+        recommendation: '',
+        needs_human_review: true,
+        warnings,
+        summary: `## ${title}\n\n**未产出任何可用的决策**：${detail}\n\n无法给出置信度与概率分布。请核对问题定义（type 必须是 choice / noul / score；choice 的 criteria 需 2~26 个选项；score 的 criteria 需 ≥2 级标签）后重试。`,
+      }
+    }
+
+    const assessment = reviewAssessment(answers, minConfidence)
+    const needsHumanReview = assessment.needed
     const lines = formatAnswerLines(answers, questions)
     const latencyMs = Number.isFinite(Number(response.latency_ms))
       ? Number(response.latency_ms)
@@ -431,6 +544,7 @@ async function executeDecision({
       recommendation,
       notes: warnings,
       needsHumanReview,
+      reviewReasons: assessment.reasons,
     })
     return {
       ok: true,
@@ -445,12 +559,14 @@ async function executeDecision({
       derived,
       confidences,
       needs_human_review: needsHumanReview,
+      review_reasons: assessment.reasons,
       recommendation,
       warnings,
       summary,
     }
   } catch (err) {
     const msg = messageOf(err)
+    recordUsage(usage, { source: 'tool', ok: false, model, provider: provider?.name, scenario: scenarioId || '' })
     return {
       ok: false,
       scenario: scenarioId,

package/lib/usage.js

@@ -0,0 +1,167 @@
+/**
+ * usage.js — 调用与 token 用量台账。
+ *
+ * 为什么需要它：SystemOne 调用是**按量计费**的，而本插件默认关闭不了的两条路径
+ * （自动路由 + 场景决策）会随会话推进持续发请求。上游返回的 `usage.input_tokens`
+ * 原本只是塞进工具返回值里，既不累计也不设上限——用户看不到花销，也就没有刹车。
+ *
+ * 设计取舍（对齐生态里同类做法，如 dsh-jev-plugin 的 ledger + 双日限）：
+ *   - 每次调用**追加**一行 JSONL，包括失败/超时的调用（失败也可能已计费）；
+ *   - 日限在**发请求之前**判定并拒绝，附上该改哪个配置项；
+ *   - 台账不可写时降级为「仅内存」，绝不因为记账失败而让决策失败（fail-open 记账）；
+ *   - 计数按**本地日**切分，跨日自动归零，不需要定时任务。
+ *
+ * 模块无第三方依赖，使用 node:fs / node:os / node:path。
+ */
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** token 数缺失时的兜底（上游不保证返回 usage）。 */
+const UNKNOWN_TOKENS = 0
+
+/** 本地日键，形如 2026-10-05。 */
+function localDayKey(now = Date.now()) {
+  const d = new Date(now)
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+/** 解析 DSH 主目录（尊重 DSH_HOME）；provider.js 的凭证读取与此同源。 */
+export function dshHome() {
+  const fromEnv = typeof process.env.DSH_HOME === 'string' ? process.env.DSH_HOME.trim() : ''
+  return fromEnv || join(homedir(), '.dsh')
+}
+
+/**
+ * 安全记账：台账是**旁路**设施，任何异常都不得影响决策或注入。
+ *
+ * 台账自身已经吞掉了写盘失败，但调用方可能传入别的实现（测试桩、将来的远端
+ * 上报），所以这里再兜一层——「记账失败绝不影响决策」是写在文档里的承诺，
+ * 不能只靠台账实现自觉。auto.js 与 tools.js 共用本函数。
+ */
+export function recordUsage(usage, entry) {
+  try {
+    usage?.record?.(entry)
+  } catch {
+    // 静默忽略
+  }
+}
+
+/** 台账文件绝对路径。 */
+export function usageLogPath(dir) {
+  const base = typeof dir === 'string' && dir.trim() ? dir.trim() : join(dshHome(), 'dsh-systemone')
+  return join(base, 'usage.jsonl')
+}
+
+/** 从任意形态的 usage 字段里取 input_tokens（容忍缺字段与字符串）。 */
+function inputTokensOf(usage) {
+  const value = Number(usage?.input_tokens)
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : UNKNOWN_TOKENS
+}
+
+/**
+ * 创建用量台账。
+ *
+ * @param {object} [options]
+ * @param {string} [options.path] - 台账文件路径；留空则用 `$DSH_HOME/dsh-systemone/usage.jsonl`
+ * @param {object} [options.logger] - 可选 logger，用于告警（写盘失败等）
+ * @returns {{ record: Function, today: Function, check: Function, formatToday: Function }}
+ */
+export function createUsageLedger(options = {}) {
+  const file = typeof options.path === 'string' && options.path.trim()
+    ? options.path.trim()
+    : usageLogPath('')
+  const logger = options.logger
+
+  /** 内存累计：{ day, calls, tokens, failures, refused } —— 读取时先按天校验再复用 */
+  let totals = { day: localDayKey(), calls: 0, tokens: 0, failures: 0 }
+  /** 写盘是否失败过（只告警一次，避免每一步刷日志） */
+  let writeFailed = false
+
+  function rollIfNeeded(now = Date.now()) {
+    const day = localDayKey(now)
+    if (totals.day !== day) {
+      totals = { day, calls: 0, tokens: 0, failures: 0 }
+    }
+    return totals
+  }
+
+  /** 记录一次调用。永不抛错——记账失败不影响决策。 */
+  function record(entry = {}) {
+    const now = Number.isFinite(entry.at) ? entry.at : Date.now()
+    const tokens = inputTokensOf(entry.usage)
+    const ok = entry.ok !== false
+    const current = rollIfNeeded(now)
+    current.calls += 1
+    current.tokens += tokens
+    if (!ok) current.failures += 1
+
+    try {
+      mkdirSync(join(file, '..'), { recursive: true })
+      appendFileSync(file, `${JSON.stringify({
+        ts: now,
+        day: current.day,
+        source: String(entry.source || 'unknown'),
+        model: entry.model ? String(entry.model) : '',
+        provider: entry.provider ? String(entry.provider) : '',
+        scenario: entry.scenario ? String(entry.scenario) : '',
+        ok,
+        input_tokens: tokens,
+        latency_ms: Number.isFinite(Number(entry.latencyMs)) ? Number(entry.latencyMs) : null,
+      })}\n`, 'utf8')
+    } catch (error) {
+      if (!writeFailed) {
+        writeFailed = true
+        try {
+          logger?.warn?.(`@master0071/dsh-systemone[usage]: 台账写入失败，本次起降级为仅内存统计：${error?.message || error}`)
+        } catch {
+          // 日志失败不影响决策
+        }
+      }
+    }
+    return { calls: current.calls, tokens: current.tokens, failures: current.failures, day: current.day }
+  }
+
+  /** 今日累计（只读快照）。 */
+  function today(now = Date.now()) {
+    const current = rollIfNeeded(now)
+    return { day: current.day, calls: current.calls, tokens: current.tokens, failures: current.failures }
+  }
+
+  /**
+   * 发请求前的限额判定。
+   * @param {{dailyCallLimit:number, dailyTokenLimit:number}} limits - 0 表示不限
+   * @returns {{allowed:boolean, reason?:string, snapshot:object}}
+   */
+  function check(limits = {}) {
+    const snapshot = today()
+    const callLimit = Number(limits.dailyCallLimit)
+    const tokenLimit = Number(limits.dailyTokenLimit)
+    if (Number.isFinite(callLimit) && callLimit > 0 && snapshot.calls >= callLimit) {
+      return {
+        allowed: false,
+        snapshot,
+        reason: `今日调用数已达上限 ${callLimit}（当前 ${snapshot.calls}）。调大 dailyCallLimit，或设为 0 关闭上限。`,
+      }
+    }
+    if (Number.isFinite(tokenLimit) && tokenLimit > 0 && snapshot.tokens >= tokenLimit) {
+      return {
+        allowed: false,
+        snapshot,
+        reason: `今日 input token 已达上限 ${tokenLimit}（当前 ${snapshot.tokens}）。调大 dailyTokenLimit，或设为 0 关闭上限。`,
+      }
+    }
+    return { allowed: true, snapshot }
+  }
+
+  /** 一行人类可读的今日用量（供工具输出与日志）。 */
+  function formatToday(now = Date.now()) {
+    const s = today(now)
+    const tokens = s.tokens >= 1000 ? `${(s.tokens / 1000).toFixed(1)}k` : String(s.tokens)
+    const fail = s.failures > 0 ? `，其中失败 ${s.failures} 次` : ''
+    return `今日：${s.calls} 次判断 · ${tokens} input tokens（${s.day}）${fail}`
+  }
+
+  return { record, today, check, formatToday, get path() { return file } }
+}

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.6.0",
+  "description": "DeepSeek Harness 插件：将 SystemOne 决策模型（默认云知声 u2-decision，可切换提供商）接入软件开发、需求预检、客服、内容审核、路由、销售线索、风控、招聘、数据治理、教育、需求变更等 11 大业务场景，为 Agent 返回带概率分布的决策与处置建议。",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -18,7 +18,8 @@
   "files": [
     "lib/",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -31,6 +32,7 @@
     "./package.json": "./package.json"
   },
   "dsh": {
+    "manifestVersion": 1,
     "bundle": {
       "patch": "cordis.patch.yml"
     },
@@ -46,14 +48,18 @@
     "node": ">=22.19"
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/provider.js && node --check lib/tools.js && node --check lib/format.js && node --check lib/scenarios.js && node --check lib/auto.js && node --check lib/volatile.js && node --check lib/client.js",
-    "test": "node --test \"test/**/*.test.mjs\""
+    "check": "node -e \"const{readdirSync}=require('node:fs'),{spawnSync}=require('node:child_process');const files=readdirSync('lib').filter((f)=>f.endsWith('.js')).sort();if(files.length===0){console.error('check: lib/ 下没有 .js 文件，检查失败');process.exit(1)}const bad=files.filter((f)=>spawnSync(process.execPath,['--check','lib/'+f],{stdio:'inherit'}).status!==0);if(bad.length>0){console.error('check: 语法检查失败 -> '+bad.join(', '));process.exit(1)}console.log('check: '+files.length+' 个 lib/*.js 语法检查通过 -> '+files.join(', '))\"",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "probe": "node scripts/probe-host.mjs",
+    "verify:docs": "node scripts/verify-doc-claims.mjs",
+    "fix:docs": "node scripts/verify-doc-claims.mjs --update"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh": ">=0.1.7-rc.1 <0.3.0",
     "@deepseek-ai/schemastery": "^3.18.1"
   }
 }