@master0071/dsh-systemone 0.5.0 → 0.6.1

package/lib/tools.js

@@ -8,14 +8,15 @@
  * 场景全部来自 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
@@ -25,7 +26,7 @@ const DEFAULT_MIN_CONFIDENCE = 0.6
  * MAX_CURRENT_CHARS / 每条历史 2000 字），这里只防工具路径被塞进超大输入
  * 直接打到上游 API；超长内容对决策质量也没有增量。
  */
-const MAX_TOOL_STATE_CHARS = 16000
+export const MAX_TOOL_STATE_CHARS = 16000
 
 /**
  * 给 state 套硬上限：超长字符串截断；对象/数组按序列化长度衡量，
@@ -59,11 +60,12 @@ function capState(state) {
  * @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),
   ]
 }
 
@@ -113,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)
@@ -126,6 +128,7 @@ function scenarioTool(provider, config, scenarios, hooks = {}) {
         state: capState(args.state),
         params: args.params,
         exec,
+        usage: hooks?.usage,
       })
     },
     presentCall: (args) => ({
@@ -147,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) => {
@@ -166,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('，')}）`),
@@ -174,6 +190,7 @@ function listScenarios(scenarios, keyword, warnings = []) {
     ...(warnings.length > 0
       ? ['', '### 配置提示', ...warnings.map((w) => `- ${w}`)]
       : []),
+    ...(usageLine ? ['', '### 用量', `- ${usageLine}`] : []),
     '',
     '用 action=describe 查看某场景的问题定义，用 action=run 执行决策。',
   ].join('\n')
@@ -184,6 +201,7 @@ function listScenarios(scenarios, keyword, warnings = []) {
     count: items.length,
     scenarios: items,
     ...(warnings.length > 0 ? { warnings } : {}),
+    ...(usageSnapshot ? { usage_today: usageSnapshot } : {}),
     summary,
   }
 }
@@ -237,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({
@@ -248,6 +267,7 @@ export async function runScenarioDecision({
   params,
   exec,
   minConfidence,
+  usage,
 }) {
   const scenario = findScenario(scenarios, scenarioRef)
   if (!scenario) {
@@ -286,6 +306,7 @@ export async function runScenarioDecision({
     config,
     minConfidence: threshold,
     exec,
+    usage,
     warnings: ignored.length > 0
       ? [`以下 params 覆盖无效，已忽略：${ignored.join('；')}`]
       : [],
@@ -355,7 +376,7 @@ function applyParams(questions, params) {
 
 /* ─── 2. 通用决策工具 ─────────────────────────────────────────────────────── */
 
-function decideTool(provider, config) {
+function decideTool(provider, config, hooks = {}) {
   return {
     name: 'systemone_decide',
     description: [
@@ -404,6 +425,7 @@ function decideTool(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: '' }
@@ -433,6 +455,7 @@ async function executeDecision({
   model,
   finalize,
   warnings = [],
+  usage,
 }) {
   try {
     const started = Date.now()
@@ -443,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)
@@ -461,6 +544,7 @@ async function executeDecision({
       recommendation,
       notes: warnings,
       needsHumanReview,
+      reviewReasons: assessment.reasons,
     })
     return {
       ok: true,
@@ -475,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,6 +1,6 @@
 {
   "name": "@master0071/dsh-systemone",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "DeepSeek Harness 插件：将 SystemOne 决策模型（默认云知声 u2-decision，可切换提供商）接入软件开发、需求预检、客服、内容审核、路由、销售线索、风控、招聘、数据治理、教育、需求变更等 11 大业务场景，为 Agent 返回带概率分布的决策与处置建议。",
   "license": "MIT",
   "type": "module",
@@ -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"
   }
 }