@leonhardthust/dsh-decision-engine 1.9.2 → 1.11.0

package/lib/adapters/tools.js

@@ -58,6 +58,45 @@ export function retrievalQuery(args) {
   }
 }
 
+/**
+ * 时效性意图：出现这些词就说明用户要的是**此刻**的事实。
+ *
+ * 中文用子串匹配（没有词边界这回事），英文用 `\b` 防止 "known" 里的 "now"、
+ * "download" 里的 "load" 之类的假命中。
+ */
+export const TIME_SENSITIVE_PATTERN =
+  /最新|今天|当前|目前|现在|版本|发布|价格|新闻|实时|\b(?:latest|today|current|currently|version|versions|release|released|price|prices|pricing|news|now)\b/i;
+
+/** 查询里出现它就说明这次要抓的是一个**具体地址**。 */
+const URL_PATTERN = /(?:https?:\/\/|www\.)/i;
+
+/**
+ * 「这类检索绝不能交给模型决定跳过」的确定性判据。
+ *
+ * 为什么需要它：retrieval 点的 skip 在 enforce 下会变成 deny（真的把调用拦下来）。
+ * 模型的判断依据只有「recent 里是否已覆盖」和「再搜是否有新信息」，而下面三种
+ * 情况下这个依据**在原理上就不成立**：
+ *
+ *   1. web_fetch：调用方给的是一条具体 URL。要判断「这份文档已经在上下文里了」
+ *      需要内容指纹，我们没有；模型只能凭 URL 猜。
+ *   2. 查询里带 URL：同上——用户明确要抓这个地址，不是要「一般性的知识」。
+ *   3. 时效性关键词（最新/今天/版本/发布/价格……）：这类问题**天然**需要重新
+ *      检索，哪怕上下文里提过一次——「上次的答案」正是它要更新的东西。
+ *      `would_add` 问的是「再搜会不会有新信息」，对这一类几乎必然答「会」，
+ *      可一旦模型答错，代价是一次被判死的检索，而用户完全无法理解为什么。
+ *
+ * @param name - 工具名。
+ * @param query - `retrievalQuery()` 摘出来的查询文本。
+ * @returns 命中的保护类别；不命中返回 undefined（= 可以交给模型裁决）。
+ */
+export function retrievalGuardReason(name, query) {
+  if (name === "web_fetch") return "explicit-url";
+  const text = typeof query === "string" ? query : "";
+  if (URL_PATTERN.test(text)) return "url-in-query";
+  if (TIME_SENSITIVE_PATTERN.test(text)) return "time-sensitive";
+  return undefined;
+}
+
 /**
  * 挂载检索必要性 + 技能选择两个监听器。
  *
@@ -80,7 +119,7 @@ export function mountToolPoints(ctx, deps) {
     if (name === SKILL_TOOL && runner.participates("skillPick")) {
       try {
         const requested = typeof exec.arguments?.name === "string" ? exec.arguments.name : "";
-        const candidates = await loadSkillCandidates(ctx, exec, cfg);
+        const candidates = await loadSkillCandidates(ctx, exec, cfg, requested);
         // 候选太少时挑选没有意义，直接放行——别为一次「只有一个选项」付费。
         if (candidates.length >= 2) {
           const result = await runner.ask(
@@ -97,6 +136,28 @@ export function mountToolPoints(ctx, deps) {
           if (runner.enforces("skillPick") && result.action?.kind === "redirect") {
             const suggest = result.action.suggest;
             if (typeof suggest === "string" && suggest.length > 0 && suggest !== requested) {
+              /**
+               * 修之前这里直接采用模型给的 suggest，不校验它是不是候选之一。
+               * 模型偶尔会答一个「听起来更对」的名字（甚至是被截断掉、根本没
+               * 进候选的那个），于是这次调用被 deny 并指去一个**不存在的技能**：
+               * 模型照着原因再试一次只会再错一次，一次本来正确的调用被拖成
+               * 两次失败。候选清单就在手里，白名单校验是零成本的。
+               *
+               * 不合法就按「没有更匹配的」处理（放行），并留一条记录——
+               * 否则这类模型漂移在用户侧完全不可见（他只会看到偶发的怪错误）。
+               */
+              if (!candidates.some((item) => item.name === suggest)) {
+                await telemetry.log({
+                  ts: new Date().toISOString(),
+                  point: "skillPick",
+                  tag: "adapter/skillPick",
+                  action: "degraded",
+                  detail: "skill-suggest-unlisted",
+                  latencyMs: 0,
+                  cached: false,
+                });
+                return next();
+              }
               // 不改写参数（那会替模型做决定），而是拦下并告知更匹配的那个：
               // 模型看到原因后可以自己重发，避免「装错再换」付两遍正文 token。
               return {
@@ -117,6 +178,18 @@ export function mountToolPoints(ctx, deps) {
     if (runner.participates("retrieval") && isRetrievalTool(name, deps.retrievalTools())) {
       try {
         const query = retrievalQuery(exec.arguments);
+        /**
+         * 确定性保护：命中就**不问模型**，直接放行。
+         *
+         * 修之前这里无条件交给模型判断，模型说 skip 就 deny。于是一次抓取
+         * 还没读过的 URL、或一句「查一下最新版本」，都可能因为 recent 里恰好
+         * 提过相关字眼被判死——而且 enforce 下是真的拦下，模型连重试的机会
+         * 都没有。这不是省钱，是把「不确定」变成了「确定地不检索」。
+         *
+         * 这里不写遥测：它根本不是一次裁决（没有问、没有答），写进
+         * telemetry.jsonl 会让「服务端说了什么」的流水账里多出没有服务端的行。
+         */
+        if (retrievalGuardReason(name, query) !== undefined) return next();
         const result = await runner.ask(
           "retrieval",
           {
@@ -162,9 +235,10 @@ export function mountToolPoints(ctx, deps) {
  * @param ctx - 插件上下文（用于 `ctx.get('skills')`）。
  * @param exec - 待执行的工具调用（提供 agent scope 与 cwd）。
  * @param cfg - 当前配置。
+ * @param requested - 这次调用请求的技能名（保证它不会被截断掉）。
  * @returns 候选数组；取不到时返回空数组。
  */
-async function loadSkillCandidates(ctx, exec, cfg) {
+async function loadSkillCandidates(ctx, exec, cfg, requested) {
   const skills = ctx.get?.("skills");
   if (skills === undefined || typeof skills.list !== "function") return [];
   let summaries;
@@ -179,8 +253,37 @@ async function loadSkillCandidates(ctx, exec, cfg) {
   }
   // 决策模型每次只有很小的一段 state；候选超过上限就截断，宁可少挑不可超长。
   const limit = Math.max(2, cfg.skillPickCandidates ?? 8);
-  return summaries.slice(0, limit).map((summary) => ({
-    name: String(summary.name ?? ""),
-    description: String(summary.description ?? "").slice(0, 160),
-  }));
+  /**
+   * 先规范化 + 去重。
+   *
+   * 去重不是洁癖：同名技能在 list 里出现两次时，state 会白花一行，
+   * 而且 choice 的 criteria 是按键名索引的对象——同名条目会互相覆盖，
+   * 模型看到两个候选、实际只有一份描述。
+   * 没有名字的条目直接丢掉：它既不能出现在 criteria 里，也不可能被选中。
+   */
+  const seen = new Set();
+  const unique = [];
+  for (const summary of summaries ?? []) {
+    const nameValue = String(summary?.name ?? "");
+    if (nameValue.length === 0 || seen.has(nameValue)) continue;
+    seen.add(nameValue);
+    unique.push({ name: nameValue, description: String(summary?.description ?? "").slice(0, 160) });
+  }
+  const head = unique.slice(0, limit);
+  /**
+   * 用户当前请求的那个技能必须留在候选里。
+   *
+   * 修之前是直接 `summaries.slice(0, limit)`，而 skills.list() 的顺序与本次
+   * 请求无关。技能多的环境里（超过上限）请求第 9 个技能时，它根本不在候选
+   * 里，模型只能从「别的技能」里挑一个——一次完全正确的调用被判成错误并改写，
+   * 这比不做技能选择坏得多（用户看到的是「我请求的技能被告知不存在」）。
+   *
+   * 替换最后一项而不是追加：候选上限是给决策模型 state 的长度预算，
+   * 追加会突破预算。替换掉的那一项排在最后，本来就最可能是被截断的边界项。
+   */
+  if (head.length > 0 && seen.has(requested) && !head.some((item) => item.name === requested)) {
+    const wanted = unique.find((item) => item.name === requested);
+    if (wanted !== undefined) head[head.length - 1] = wanted;
+  }
+  return head;
 }

package/lib/adapters/translate.js

@@ -18,6 +18,19 @@
  * @module dsh-decision-engine/adapters/translate
  */
 
+import { createHash } from "node:crypto";
+
+/**
+ * 本地裁决缓存的「问法版本号」。
+ *
+ * 缓存里存的是**裁决**（要不要翻译），而一条裁决只对产生它的那套 questions
+ * 成立。spec.js 里 cotTranslate 的问法一改（加一问、换措辞、换判定口径），
+ * 旧裁决立刻失效——可这个缓存是内存里的 Map，热更新代码时它会跨版本存活。
+ * 把版本号写进键里，改问法时手动 +1 是最小的保险：忘了 +1 的后果是「新问法
+ * 一直在用老答案」，而且从现象上完全看不出来（翻译时好时坏，与文本无关）。
+ */
+const QUESTIONS_VERSION = 1;
+
 /** 判断一段文本里「值得翻译的正文」占比是否够高（本地预筛，免费的）。 */
 function looksLikeProse(text) {
   if (typeof text !== "string" || text.length === 0) return false;
@@ -34,6 +47,32 @@ function looksLikeProse(text) {
   return letters >= 4;
 }
 
+/**
+ * 构造一条裁决的缓存键。
+ *
+ * 修之前键是 `${targetLanguage}|${text.length}|${text.slice(0, 64)}`：
+ *
+ *   - 同长 + 前 64 字符相同、后面不同的两段文本会共用一条裁决。翻译文本
+ *     经常以同样的开场白起头（"Here's my plan: ..."），撞键不是理论问题；
+ *   - `sourceLanguage` 根本不在键里：同一段英文，一次标 en、一次标 zh，
+ *     第二次直接复用第一次的结论——可 source 正是「是否已是目标语言」那
+ *     一问的输入。
+ *
+ * 现在键 = 问法版本 + 源语言 + 目标语言 + **全文**的 sha256。为什么用摘要而
+ * 不是全文：这个 Map 最多留 256 条，键若存全文，等于把 256 段思维链全文钉在
+ * 内存里；摘要定长，缓存体积与文本长度无关。
+ *
+ * @param spec - 翻译规格（只读 `sourceLanguage` / `targetLanguage`）。
+ * @param text - 待翻译全文。
+ * @returns 缓存键。
+ */
+function decisionKey(spec, text) {
+  const digest = createHash("sha256").update(text, "utf8").digest("hex");
+  const source = typeof spec?.sourceLanguage === "string" ? spec.sourceLanguage : "auto";
+  const target = typeof spec?.targetLanguage === "string" ? spec.targetLanguage : "auto";
+  return `${QUESTIONS_VERSION}|${source}|${target}|${digest}`;
+}
+
 /**
  * 包住 translator.translate。
  *
@@ -70,9 +109,39 @@ export function mountCotTranslatePoint(ctx, deps) {
     if (!runner.participates("cotTranslate")) return original.call(this, spec, signal);
 
     try {
+      /**
+       * 本点此刻是否允许真正改变行为。一次执行里只取一次。
+       *
+       * 为什么先取而不是每处现问：下面有三处要用它（本地预筛、缓存命中、
+       * 裁决落地），每次都读配置的话，配置中途被改会得到「预筛按 enforce
+       * 跳过、落裁决按 observe 放行」这种自相矛盾的一次执行。
+       */
+      const enforced = runner.enforces("cotTranslate");
       const text = typeof spec?.text === "string" ? spec.text : "";
       // 本地预筛：明显不需要翻译的文本零成本跳过，不必问模型。
       if (!looksLikeProse(text)) {
+        /**
+         * 修之前这个 return 跑在 `enforces()` 之前：observe 模式下也直接返回
+         * 原文，于是「只观察」变成了「真的跳过翻译」——用户拿到的是没翻译的
+         * 原文，而遥测里这次却被记成一次 observe。observe 的契约是只记录、
+         * 不改变行为；违反它比不开启这个点更坏，因为观察期得出的数据会被
+         * 当成「没人开过这个点」的干净样本。
+         *
+         * 现在：只有 enforce 才允许这条路真的返回原文；observe 一律走原翻译器，
+         * 只留一条「本该跳过」的记录，这样观察数据里仍能看到它到底值不值得开。
+         */
+        if (!enforced) {
+          await telemetry.log({
+            ts: new Date().toISOString(),
+            point: "cotTranslate",
+            tag: "cotTranslate",
+            action: "skip",
+            detail: "decision-engine-cot: 本地预筛判定无正文；observe 模式仍走原翻译器（本该跳过）",
+            latencyMs: 0,
+            cached: false,
+          });
+          return original.call(this, spec, signal);
+        }
         await telemetry.log({
           ts: new Date().toISOString(),
           point: "cotTranslate",
@@ -85,11 +154,27 @@ export function mountCotTranslatePoint(ctx, deps) {
         return text;
       }
 
-      // 缓存键：目标语言 + 文本摘要。同一段文本重复翻译（重放、重渲染）很常见。
-      const key = `${spec.targetLanguage ?? "auto"}|${text.length}|${text.slice(0, 64)}`;
+      // 缓存键：问法版本 + 源/目标语言 + 全文摘要（见 decisionKey 的说明）。
+      const key = decisionKey(spec, text);
       let verdict = decisions.get(key);
       if (verdict === undefined) {
         const cfg = getConfig();
+        /**
+         * 会话引用：`spec.sessionId` 只有**付费** provider 才有
+         * （`AnonymousTranslationSpec` 没有这个字段）。因此这个点的会话归属是
+         * 「有则记、没有就算不可归属」：免费通道（google / bing）的决策不会
+         * 出现在任何会话的「决策历史」里。这是刻意的取舍，不是遗漏——为它
+         * 编造一个会话 id 会让用户看到一条不属于自己会话的记录，比缺失更糟
+         * （见 DEC-022）。
+         *
+         * 修之前这里传的是 `{ sessionId }`，而 engine.js 的 `ask()` 只从
+         * `extra.session` 取会话——字段名对不上，于是**付费通道的翻译决策也
+         * 永远归不到会话**：明细里的 sessionId 恒为空串，界面上永远不进任何
+         * 会话页。引擎的 `sessionIdOf()` 本来就接受 id 字符串，所以这里直接按
+         * 它认的字段名传，不新增第二个字段（两个名字收同一件事，迟早只改一个）。
+         */
+        const sessionRef =
+          typeof spec.sessionId === "string" && spec.sessionId.length > 0 ? spec.sessionId : undefined;
         const result = await runner.ask(
           "cotTranslate",
           {
@@ -98,15 +183,13 @@ export function mountCotTranslatePoint(ctx, deps) {
             sourceLanguage: spec.sourceLanguage,
             head: text.slice(0, 400),
           },
-          // `spec.sessionId` 只有**付费** provider 才有（AnonymousTranslationSpec
-          // 没有这个字段）。因此这个点的会话归属是「有则记、没有就算不可归属」：
-          // 免费通道（google / bing）的决策不会出现在任何会话的「决策历史」里。
-          // 这是刻意的取舍，不是遗漏——为它编造一个会话 id 会让用户看到一条
-          // 不属于自己会话的记录，比缺失更糟（见 DEC-022）。
-          { signal, sessionId: typeof spec.sessionId === "string" ? spec.sessionId : "" },
+          {
+            signal,
+            ...(sessionRef === undefined ? {} : { session: sessionRef }),
+          },
         );
         // 降级 / observe / 关闭：一律按「需要翻译」处理，走原方法。
-        if (result.action === undefined || !runner.enforces("cotTranslate")) {
+        if (result.action === undefined || !enforced) {
           return original.call(this, spec, signal);
         }
         verdict = result.action.kind === "translate";
@@ -114,6 +197,8 @@ export function mountCotTranslatePoint(ctx, deps) {
       }
 
       if (verdict === true) return original.call(this, spec, signal);
+      // 缓存里可能存着本点 enforce 期的裁决：切到 observe 后不能再拿它改行为。
+      if (!enforced) return original.call(this, spec, signal);
 
       // 判为不需要翻译：返回原文。这与「已经是目标语言」的语义一致，
       // 调用方不会看到异常，用户看到的还是那段文本。