@leonhardthust/dsh-decision-engine 1.9.2 → 1.11.0

package/lib/engine.js

@@ -28,9 +28,11 @@ const NOOP = Object.freeze({ mode: "off", action: undefined });
  * @param options.modeOf - `(cfg, id) => 'off'|'observe'|'enforce'`。
  * @param options.log - `(entry) => Promise<void>`，写 telemetry.jsonl。
  * @param options.specOf - `(id) => spec`，从注册表取 build/parse/decide。
- * @param options.recordDetail - 可选。`(record) => void`，写 decisions.jsonl
- *   （「决策历史」页的数据源）。缺省时不写——单元测试里的 runner 只关心
- *   裁决语义，不该被明细存储拖进来。
+ * @param options.recordDetail - 可选。`(record, session) => void`，写决策明细
+ *   （「决策历史」页的数据源）。第二个参数是**原始的会话引用**（Session 对象
+ *   或 id 字符串）：`session`/`workspace` 分文件模式要用它解析会话名与工作区名，
+ *   而名字不在记录体里。缺省时不写——单元测试里的 runner 只关心裁决语义，
+ *   不该被明细存储拖进来。
  */
 export function createDecisionRunner(options) {
   const { getConfig, client, logger, modeOf, log, specOf } = options;
@@ -99,7 +101,12 @@ export function createDecisionRunner(options) {
    *
    * @param id - 决策点 id（同时是遥测里的 `point` 字段）。
    * @param input - 传给 spec.build 的现场数据。
-   * @param extra - 可选：signal / tool / degradeHint。
+   * @param extra - 可选：signal / tool / session。
+   *   `session` 是**会话引用**，接受 Session 对象或 id 字符串 —— 思维链翻译点
+   *   只拿得到 `TranslationSpec.sessionId`，没有 Session 对象可传。它不参与
+   *   裁决，只用于把这条明细归属到会话。字段名就叫 `session`（不是
+   *   `sessionId`）：`sessionIdOf()` 与明细存储都从这里取，两个名字收同一件事
+   *   迟早只会改一个——那正是「付费通道的翻译决策归不到会话」那次的成因。
    *
    * 软缓存（同类复用）不在引擎层开启：决策点的裁决要么与完整 state 一一
    * 对应（精确键），要么干脆不复用。归一化签名会丢掉现场内容，任何
@@ -136,34 +143,40 @@ export function createDecisionRunner(options) {
      */
     const noteDetail = (builtState, builtQuestions, outcome, answeredPart) => {
       try {
-        recordDetail({
-          ts: new Date().toISOString(),
-          sessionId,
-          point: id,
-          tag: id,
-          mode,
-          topMode: cfg.mode,
-          provider: outcome.provider,
-          model: outcome.model,
-          action: outcome.action,
-          detail: outcome.detail,
-          cached: outcome.cached === true,
-          degraded: outcome.degraded === true,
-          latencyMs: outcome.latencyMs,
-          inputTokens: outcome.inputTokens,
-          outputTokens: outcome.outputTokens,
-          ...(extra.tool === undefined ? {} : { tool: extra.tool }),
-          ...(extra.turn === undefined ? {} : { turn: extra.turn }),
-          ...(extra.step === undefined ? {} : { step: extra.step }),
-          ...(outcome.scores === undefined ? {} : { scores: outcome.scores }),
-          // 内容一律交原始三件套；截断与脱敏在存储层做（它知道配置上限，
-          // 也负责「只落本地」的那条边界）。
-          content: {
-            state: builtState,
-            questions: builtQuestions,
-            ...(answeredPart === undefined ? {} : { answers: answeredPart }),
+        recordDetail(
+          {
+            ts: new Date().toISOString(),
+            sessionId,
+            point: id,
+            tag: id,
+            mode,
+            topMode: cfg.mode,
+            provider: outcome.provider,
+            model: outcome.model,
+            action: outcome.action,
+            detail: outcome.detail,
+            cached: outcome.cached === true,
+            degraded: outcome.degraded === true,
+            latencyMs: outcome.latencyMs,
+            inputTokens: outcome.inputTokens,
+            outputTokens: outcome.outputTokens,
+            ...(extra.tool === undefined ? {} : { tool: extra.tool }),
+            ...(extra.turn === undefined ? {} : { turn: extra.turn }),
+            ...(extra.step === undefined ? {} : { step: extra.step }),
+            ...(outcome.scores === undefined ? {} : { scores: outcome.scores }),
+            // 内容一律交原始三件套；截断与脱敏在存储层做（它知道配置上限，
+            // 也负责「只落本地」的那条边界）。
+            content: {
+              state: builtState,
+              questions: builtQuestions,
+              ...(answeredPart === undefined ? {} : { answers: answeredPart }),
+            },
           },
-        });
+          // 会话**对象**也一并交给存储层：session/workspace 分文件模式要拿
+          // 会话名与工作区名做文件名，而名字只挂在 Session 上（不是 id 字符串）。
+          // 思维链翻译点只有 id 字符串，同样原样传下去，由解析方兜底。
+          extra.session,
+        );
       } catch (error) {
         // 明细是旁路：写不进去只留一行警告，绝不影响裁决。
         logger?.warn?.(

package/lib/guard/effects.js

@@ -38,6 +38,20 @@ export function classifyToolEffect({ toolName, args, trustedContext = {}, scope
     }
   }
   if (toolName === "working_directory" && fields(args, [])) return known("read_local", "working-directory-query", { recoverability: "no-mutation" });
+  // `job_output` 是只读查询：它只读取指定后台任务已经产生的输出，不写文件、
+  // 不改任务状态。缺了这条契约，它就会落进末尾的 unknown 分支并把 highImpact
+  // 设成 true，于是一次纯读取也要先过模型复核（用户实际感受到的「读一下任务
+  // 输出都被拦」）。
+  //
+  // 只在参数形状**严格**匹配（`job_id` 字符串、`wait` 布尔、`timeout_ms` 有限数）
+  // 时才下这个结论：多出任何未知字段，就可能是在借这个工具做别的事（往参数里
+  // 夹带别名或其他动作），那时必须退回 unknown 交给模型复核，不能凭工具名放行。
+  if (toolName === "job_output" && fields(args, ["job_id", "wait", "timeout_ms"], ["job_id"])
+    && typeof args.job_id === "string"
+    && (args.wait === undefined || typeof args.wait === "boolean")
+    && (args.timeout_ms === undefined || Number.isFinite(args.timeout_ms))) {
+    return known("read_local", "known-local-job-output-query", { recoverability: "no-mutation" });
+  }
   if (toolName === "skill" && fields(args, ["name"], ["name"]) && typeof args.name === "string") return known("read_local", "known-skill-document-query", { recoverability: "no-mutation" });
   if (toolName === "cordis_inspect_list" && fields(args, [])) return known("read_local", "known-runtime-schema-query", { recoverability: "no-mutation" });
   if (toolName === "list_subagent_models" && fields(args, ["provider", "model"]) && strings(args, ["provider", "model"])) return known("read_local", "known-model-route-query", { recoverability: "no-mutation" });

package/lib/guard/listener.js

@@ -5,8 +5,8 @@ import { GUARD_QUESTIONS_VERSION, guardQuestions, parseModelAdvisory, decideMode
 import { createGuardAudit, hashSummary, joinHostOutcome } from "./audit.js";
 import { classifyWorkspaceTarget } from "../scope.js";
 import { resolveTolerance, severityOf, toleranceCutoff } from "../tolerance.js";
-import { redactGuardData, reviewWithFallback } from "./fallback.js";
-import { guardOutcomeMessage } from "./messages.js";
+import { redactGuardData, reviewWithFallback, GUARD_FALLBACKS } from "./fallback.js";
+import { guardOutcomeMessage, toleranceAskAction } from "./messages.js";
 
 export function approvalOutcomeForCall(session, callId, toolName, afterSeq) {
   if (!Number.isFinite(afterSeq) || !callId || typeof session?.snapshotEvents !== "function") return "unknown";
@@ -198,7 +198,27 @@ export function mountGuard(ctx, deps) {
       tolerated = resolveTolerance({ level: config.tolerance, legacyKind: baseAction.kind, severity, cutoff: cutoffInfo.cutoff, mandatory: enforcingPolicy ? mandatory : undefined, approvalAvailable: context.approvalAvailable });
       let action = tolerated.kind === baseAction.kind ? baseAction : { kind: tolerated.kind, reason: tolerated.note };
       decisionSource = "primary_model";
-      const unresolved = mandatory.status === "unknown";
+      // 为什么「本地未知副作用」可以只凭主模型意见收尾（去掉冗余的第二次复核）：
+      //
+      // `mandatory=unknown` 只表示「本地静态规则无法判定这次调用的权限边界」，
+      // 它本身**不是**「需要升级」。当 effect 只是 unknown（没有任何强制权限
+      // 约束）、主模型给出了有效意见且结论是 delegate、档位也没把它升级成询问、
+      // 而回退策略又只是「再叫一个模型复核一次」（session / model）时，再为
+      // `mandatory=unknown` 单独跑一次回退，等于给每条无法静态判定的本地命令
+      // 稳定加倍一次模型调用——正是用户报告的「决策模型定不了论就回退」。
+      //
+      // 刻意**不**豁免的三种情况：
+      //   - 外网/MCP 副作用（`external_network`）：边界在宿主之外，第二次独立
+      //     复核是刻意保留的安全余量，不是冗余；
+      //   - `baseAction` / `action` 是 ask，或主模型失效：这是软性判断本身要问，
+      //     与原逻辑一致；
+      //   - 显式 `allow` / `deny` 回退策略：那是用户写下的政策裁决，不能被这条
+      //     豁免绕过（`allow` 会放行、`deny` 会拦截，都不是「多跑一次模型」）。
+      const fallbackPolicy = GUARD_FALLBACKS.includes(config.guardFallback) ? config.guardFallback : "session";
+      const localUnknownDeferOnly = effect.kind === "unknown" && effect.known === false
+        && advisory?.status === "valid" && baseAction.kind === "delegate" && tolerated.kind === "delegate"
+        && ["session", "model"].includes(fallbackPolicy);
+      const unresolved = mandatory.status === "unknown" && !localUnknownDeferOnly;
       if (automaticReview(context, config) && (unresolved || baseAction.kind === "ask" || action.kind === "ask" || primary.status === "failed")) {
         action = await runFallback();
       } else if (primary.status === "failed") {
@@ -206,6 +226,11 @@ export function mountGuard(ctx, deps) {
       } else if (action.kind === "ask" && context.approvalPolicy === "never") {
         action = { ...action, kind: "deny" };
       }
+      // 档位把「默认放行」升级成「询问」时，`action.reason` 是档位 note（含
+      // `severity=` 与阈值小数）——那是审计口径，不能当审批卡标题。这里换成
+      // 固定双语文案；note 仍进 `humanReason` / 遥测 detail，事后核对仍能看出
+      // 是哪一档、什么分数。放在回退之后：回退给出的裁决有自己的文案。
+      if (tolerated.changed && action.kind === "ask") action = toleranceAskAction(action);
       return finish(action, degradedReason);
     } catch {
       ctx.logger?.warn?.("decision-engine: guard failed; explicit permission constraints remain protected");

package/lib/guard/messages.js

@@ -21,9 +21,44 @@ const MESSAGES = {
   "advisory-failed-unknown-effect": ["模型审查失败，无法确认此工具的副作用", "Model review failed and the tool's effects remain unresolved"],
   "guard-exception": ["审查链发生内部错误，未将错误视为授权", "The review pipeline failed; an error does not grant authorization"],
   "review-cancelled": ["审查已取消", "Review was cancelled"],
+  // 安全档位（tolerance）把「默认放行」升级成「询问」时的固定文案。
+  //
+  // 为什么需要一条独立词条而不是复用上面任何一条：那些描述的是**模型发现了
+  // 什么**（注入嫌疑、材料风险……），而这一条描述的是**用户选的档位要求问**。
+  // 借用前者会让审计记录说谎——一次模型判定低风险的调用，标题却写着「模型
+  // 提示可能有风险」。文案里刻意不出现档位 note 里的 `severity=` / 阈值小数：
+  // 审批卡标题是给人读的一行话，不是遥测字段。
+  "tolerance-ask": ["安全档位要求确认此次调用", "The safety level asks for confirmation"],
 };
 
+/**
+ * 给「安全档位把默认放行升级成询问」的裁决挂上固定双语标题。
+ *
+ * 为什么不能只靠 `MESSAGES` 按 `reason` 查表：这条 ask 的 `reason` 是档位
+ * note（`tolerance=relaxed（严重度 0.350 ≥ 0.600…）`），属于审计/遥测口径，
+ * 含字段名与裸小数，不能拿去当标题；但它又必须**逐字保留**，否则事后核对
+ * 无法解释「这次为什么问」。于是两条通道分开：
+ *   - `reason` 保持档位 note（审计与遥测原文）；
+ *   - `displayReason` 用本条固定文案（宿主审批卡只渲染它）。
+ *
+ * @param action - 当前 ask 裁决（`{kind:'ask', reason:<档位 note>}`）。
+ * @returns 附带 `reasonCode: 'tolerance-ask'` 与 `displayReason` 的副本。
+ */
+export function toleranceAskAction(action) {
+  const [zh, en] = MESSAGES["tolerance-ask"];
+  return { ...action, reasonCode: "tolerance-ask", displayReason: { zh, en } };
+}
+
 export function guardOutcomeMessage(action, mandatory) {
+  // 已显式带 `reasonCode` 的裁决（目前只有 tolerance 触发的 ask）：`reasonCode`
+  // 是权威口径，`reason` 是调用方给的审计原文，这里只补/保留 `displayReason`。
+  // 若走下面的通用分支，`reason` 会被文案表覆盖（档位 note 丢失），
+  // `displayReason` 又会被填成与 `reason` 逐字相同的旧口径——DEC-041 已取消
+  // 那条契约，标题必须说日常语言。
+  const explicit = action.reasonCode !== undefined && Object.hasOwn(MESSAGES, action.reasonCode) ? MESSAGES[action.reasonCode] : undefined;
+  if (explicit) {
+    return { ...action, ...(action.kind === "ask" ? { displayReason: action.displayReason ?? { zh: explicit[0], en: explicit[1] } } : {}) };
+  }
   const code = action.reason ?? mandatory?.reasonCodes?.[0] ?? action.kind;
   const message = MESSAGES[code];
   if (!message) return { ...action, reasonCode: code };