dsh-decision-engine 0.0.0-stage → 0.5.0

package/lib/adapters/route.js

@@ -0,0 +1,145 @@
+/**
+ * 模型路由：`agent/request` 适配器。
+ *
+ * 这个点是**热路径**——每步一次模型请求就触发一次。若每次都问决策模型，
+ * 等于每步多等约 2 秒，比省下的 token 更贵。因此这里用三道闸把它压下来：
+ *
+ *   闸1 步数闸    每轮只在前 N 步判断（默认 3）。后续步骤沿用本轮的裁决——
+ *                一个任务的「要不要强模型」在开头就定了，逐步重问是浪费。
+ *   闸2 路由闸    提议的 config 与上一次实际使用的不同才问。同一 provider/model
+ *                连续多步时，裁决已经生效，不必再问。
+ *   闸3 机械闸    只有本地判定「看起来机械」的步骤才问：上一步有工具结果、
+ *                且最近没有用户新输入。新推理多半需要强模型，问了也是 keep。
+ *
+ * 生效方式：返回替换后的 LlmCallConfig。observe 只记录「本该换成什么」。
+ *
+ * 安全约束（照 `agent/request` 的契约）：这个 waterfall 不能改 messages，
+ * 只能改 config。因此这里只动 provider/model 两个字段，其余字段原样透传，
+ * 否则会把 maxTokens、reasoningEffort 等宿主已解析的默认值弄丢。
+ *
+ * @module dsh-decision-engine/adapters/route
+ */
+
+/**
+ * 挂载模型路由监听器。
+ * @param ctx - cordis 插件上下文。
+ * @param deps - 运行期依赖。
+ */
+export function mountRoutePoint(ctx, deps) {
+  const { runner, getConfig, digestRecent, telemetry } = deps;
+
+  /**
+   * 每轮的路由状态：turn → { askedSteps, lastProvider, lastModel }。
+   * 用 WeakMap 挂在 session 上，会话销毁即回收，不担心泄漏。
+   */
+  const perSession = new WeakMap();
+
+  const stateFor = (session) => {
+    let state = perSession.get(session);
+    if (state === undefined) {
+      state = { turn: -1, askedSteps: new Set(), lastProvider: undefined, lastModel: undefined };
+      perSession.set(session, state);
+    }
+    // 换轮即重置：新的一轮是一个新任务，前一轮的「机械」判断不适用。
+    return state;
+  };
+
+  /** 最近一条 user 消息是否比最近一条工具结果更新（= 有新推理进入）。 */
+  const hasFreshUserInput = (session) => {
+    let events;
+    try {
+      events = session.events ?? [];
+    } catch {
+      return false;
+    }
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index];
+      if (event?.type === "tool/result") return false;
+      if (event?.type === "user/message") return true;
+    }
+    return false;
+  };
+
+  const listener = async (payload, next) => {
+    const proposed = await next();
+    const agent = payload?.agent;
+    if (agent?.session === undefined) return proposed;
+    if (!runner.participates("route")) return proposed;
+
+    try {
+      const cfg = getConfig();
+      // 下沉目标没配就完全不判断：留空等于「不路由」，问一次模型再放弃是纯浪费。
+      if (
+        typeof cfg.routeCheapProvider !== "string" ||
+        cfg.routeCheapProvider.length === 0 ||
+        typeof cfg.routeCheapModel !== "string" ||
+        cfg.routeCheapModel.length === 0
+      ) {
+        return proposed;
+      }
+      const state = stateFor(agent.session);
+      if (state.turn !== payload.turn) {
+        state.turn = payload.turn;
+        state.askedSteps.clear();
+      }
+
+      // 闸1：本轮已问够步数就不再问，沿用当前（可能已被替换的）路由。
+      if (state.askedSteps.size >= Math.max(1, cfg.routeMaxStepsPerTurn ?? 3)) return proposed;
+
+      // 闸2：路由没变过就不必重问——裁决已经在上一问里生效。
+      if (state.lastProvider === proposed.provider && state.lastModel === proposed.model) {
+        // 但同一轮里第一次见到这个路由时，还是要问一次。
+        if (state.askedSteps.size > 0) return proposed;
+      }
+
+      // 闸3：新用户输入带来的步骤通常是新推理，问了也多半 keep。
+      if (hasFreshUserInput(agent.session) && state.askedSteps.size > 0) return proposed;
+
+      // 已经在用便宜模型了，再往下沉没有意义。
+      if (
+        proposed.provider === cfg.routeCheapProvider &&
+        proposed.model === cfg.routeCheapModel
+      ) {
+        return proposed;
+      }
+
+      state.askedSteps.add(payload.step);
+
+      const result = await runner.ask(
+        "route",
+        {
+          turn: payload.turn,
+          step: payload.step,
+          current: { provider: proposed.provider, model: proposed.model },
+          recent: digestRecent(agent.session, cfg.recentMessages, cfg.recentMessageChars),
+        },
+        { signal: payload.signal },
+      );
+
+      if (result.action?.kind !== "switch") return proposed;
+      // 校验目标路由确实配好了：留空等于「不路由」，不能真去请求空 provider。
+      const provider = result.action.provider;
+      const model = result.action.model;
+      if (typeof provider !== "string" || provider.length === 0) return proposed;
+      if (typeof model !== "string" || model.length === 0) return proposed;
+      if (provider === proposed.provider && model === proposed.model) return proposed;
+
+      // observe 到这里就结束：记录已写，但不改路由。
+      if (!runner.enforces("route")) return proposed;
+
+      state.lastProvider = provider;
+      state.lastModel = model;
+      ctx.logger?.info?.(
+        `dsh-decision-engine: 第 ${payload.turn}/${payload.step} 步路由 ${proposed.provider}/${proposed.model} → ${provider}/${model}`,
+      );
+      // 只覆盖 provider/model，其余字段（maxTokens / reasoningEffort / temperature）
+      // 原样保留——它们是宿主已解析好的，弄丢会改变请求语义。
+      return { ...proposed, provider, model };
+    } catch (error) {
+      telemetry.noteAdapterError("route", error, ctx);
+      return proposed;
+    }
+  };
+
+  ctx.on("agent/request", listener);
+}

package/lib/adapters/tools.js

@@ -0,0 +1,183 @@
+/**
+ * 检索必要性 + 技能选择的 tools/pre-execute 适配器。
+ *
+ * 这两个点都挂在 `tools/pre-execute` 上，但只对「特定工具」生效：
+ *
+ *   检索必要性  只有 web_search / web_fetch / research 等检索工具才判断。
+ *               其余工具一行 `includes` 就返回，零请求零延迟。
+ *   技能选择    只有 `skill` 工具、且候选清单非空时才判断。
+ *
+ * 「只对特定工具生效」不是优化，而是必要条件：这两个点在注册表里都是
+ * 非热路径，但 `tools/pre-execute` 本身是每次工具调用都会走的，
+ * 若不按工具名过滤，就等于给每个 bash/read/edit 都加 2 秒。
+ *
+ * 两者的生效方式不同：
+ *   检索  deny 直接拦下（这是唯一能真省下搜索 token 的方式）
+ *   技能  deny 会给出更匹配的名字（拦掉错的、指对对的）
+ *
+ * @module dsh-decision-engine/adapters/tools
+ */
+
+/** 检索类工具名（默认值；可在配置里用 retrievalTools 覆盖）。 */
+export const DEFAULT_RETRIEVAL_TOOLS = ["web_search", "web_fetch", "research", "multi_search", "advanced_search"];
+
+/** 技能加载工具名。 */
+export const SKILL_TOOL = "skill";
+
+/**
+ * 判断一次工具调用是不是检索。
+ * @param name - 工具名。
+ * @param tools - 配置里的检索工具名集合。
+ * @returns 是否按检索处理。
+ */
+export function isRetrievalTool(name, tools) {
+  return typeof name === "string" && tools.has(name);
+}
+
+/**
+ * 从工具参数里摘出「这次要检索什么」。
+ *
+ * 不同检索工具的参数名不一样（web_search 用 queries，web_fetch 用 url，
+ * research 用 question），逐个认；认不出来就退回整段参数预览。
+ * 这个字符串同时是软缓存的签名——同一个问题问第二遍应该命中缓存。
+ *
+ * @param args - 工具参数。
+ * @returns 用于 state 与缓存的查询文本。
+ */
+export function retrievalQuery(args) {
+  if (args === null || typeof args !== "object") return "";
+  const candidates = [args.query, args.question, args.url, args.prompt];
+  if (Array.isArray(args.queries)) candidates.push(args.queries.join(" | "));
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) return candidate.trim();
+  }
+  try {
+    return JSON.stringify(args).slice(0, 400);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * 挂载检索必要性 + 技能选择两个监听器。
+ *
+ * 两者合成一个 `tools/pre-execute` 监听器而不是注册两个：一个监听器里先按
+ * 工具名分派，省掉一次 dispatch 往返，也让「这次调用归哪个点管」在日志里
+ * 只有一个明确答案（不会出现两个点同时记录同一次调用）。
+ *
+ * @param ctx - cordis 插件上下文。
+ * @param deps - 运行期依赖。
+ */
+export function mountToolPoints(ctx, deps) {
+  const { runner, getConfig, digestRecent, telemetry } = deps;
+
+  const listener = async (exec, next) => {
+    if (exec?.agent === undefined) return next();
+    const name = exec.name;
+    const cfg = getConfig();
+
+    // ---- 技能选择 ------------------------------------------------------
+    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);
+        // 候选太少时挑选没有意义，直接放行——别为一次「只有一个选项」付费。
+        if (candidates.length >= 2) {
+          const result = await runner.ask(
+            "skillPick",
+            {
+              requested,
+              candidates,
+              recent: digestRecent(exec.agent.session, cfg.recentMessages, cfg.recentMessageChars),
+            },
+            { tool: name, signal: exec.signal, softCacheable: (value) => value !== undefined },
+          );
+          // observe 只记录；enforce 且判出更匹配的技能时才改写这次调用。
+          if (runner.enforces("skillPick") && result.action?.kind === "redirect") {
+            const suggest = result.action.suggest;
+            if (typeof suggest === "string" && suggest.length > 0 && suggest !== requested) {
+              // 不改写参数（那会替模型做决定），而是拦下并告知更匹配的那个：
+              // 模型看到原因后可以自己重发，避免「装错再换」付两遍正文 token。
+              return {
+                kind: "deny",
+                reason: `${result.action.reason}。若要装该技能，请改用以 skill(name: "${suggest}") 重试。`,
+                info: { name: "StartluxSkillPickError", code: "STARTLUX_SKILLPICK_REDIRECT", suggest },
+              };
+            }
+          }
+        }
+      } catch (error) {
+        telemetry.noteAdapterError("skillPick", error, ctx);
+      }
+      return next();
+    }
+
+    // ---- 检索必要性 ----------------------------------------------------
+    if (runner.participates("retrieval") && isRetrievalTool(name, deps.retrievalTools())) {
+      try {
+        const query = retrievalQuery(exec.arguments);
+        const result = await runner.ask(
+          "retrieval",
+          {
+            tool: name,
+            query,
+            recent: digestRecent(exec.agent.session, cfg.recentMessages, cfg.recentMessageChars),
+          },
+          {
+            tool: name,
+            signal: exec.signal,
+            // 只有「检索有必要」的裁决可跨调用复用；skip 永不复用，
+            // 免得一次「已知」把后续同类问题全部拦掉。
+            softCacheable: (value) => value !== undefined,
+          },
+        );
+        if (runner.enforces("retrieval") && result.action?.kind === "skip") {
+          return {
+            kind: "deny",
+            reason: result.action.reason,
+            info: { name: "StartluxRetrievalError", code: "STARTLUX_RETRIEVAL_SKIP" },
+          };
+        }
+      } catch (error) {
+        telemetry.noteAdapterError("retrieval", error, ctx);
+      }
+      return next();
+    }
+
+    return next();
+  };
+
+  ctx.on("tools/pre-execute", listener);
+}
+
+/**
+ * 取当前可见的技能候选清单（名称 + 描述）。
+ *
+ * 只带名字和一行描述，绝不带正文：决策模型每次约 1.9k token，把技能正文
+ * 塞进 state 会让这个「省钱的点」变成主要花销。正文只在模型真正加载时付费。
+ *
+ * @param ctx - 插件上下文（用于 `ctx.get('skills')`）。
+ * @param exec - 待执行的工具调用（提供 agent scope 与 cwd）。
+ * @param cfg - 当前配置。
+ * @returns 候选数组；取不到时返回空数组。
+ */
+async function loadSkillCandidates(ctx, exec, cfg) {
+  const skills = ctx.get?.("skills");
+  if (skills === undefined || typeof skills.list !== "function") return [];
+  let summaries;
+  try {
+    summaries = await skills.list({
+      cwd: exec.agent?.session?.header?.cwd,
+      signal: exec.signal,
+      scope: exec.agent,
+    });
+  } catch {
+    return [];
+  }
+  // 决策模型每次只有很小的一段 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),
+  }));
+}

package/lib/adapters/translate.js

@@ -0,0 +1,138 @@
+/**
+ * 思维链翻译门槛：包住 `translator.translate()`。
+ *
+ * 翻译链路没有提供任何 hook —— `ctx.translator` 是一个 Service，`cotTranslation`
+ * 直接调用它的 `translate(spec, signal)`。所以这里只能包住那个方法。
+ *
+ * 包装是「有边界的、可撤销的」，不是野生 monkeypatch：
+ *
+ *   - 用 `ctx.effect(...)` 注册，卸载时一定把原方法装回去；
+ *   - 原方法的 `this` 保持为 translator 实例，签名与返回值完全不变；
+ *   - 判定失败一律调用原方法（fail-open），绝不让翻译因为守卫而不可用；
+ *   - 返回一个空串表示「不需要翻译」会破坏调用方语义，因此**跳过翻译时
+ *     返回原文**——调用方拿到的是「已经是目标语言」的合理解释。
+ *
+ * 生效方式与省 token 的关系：翻译按条计费。判为 skip 时直接返回原文，
+ * 那条就完全不发请求；判为 translate 时正常走下原方法。
+ *
+ * @module dsh-decision-engine/adapters/translate
+ */
+
+/** 判断一段文本里「值得翻译的正文」占比是否够高（本地预筛，免费的）。 */
+function looksLikeProse(text) {
+  if (typeof text !== "string" || text.length === 0) return false;
+  // 去掉代码块、行内代码、URL —— 这些不需要翻译。
+  const prose = text
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`]*`/g, " ")
+    .replace(/https?:\/\/\S+/g, " ");
+  // 统计字母/汉字数量；纯符号/数字/路径不值得发一次翻译请求。
+  let letters = 0;
+  for (const char of prose) {
+    if (/[\p{L}]/u.test(char)) letters += 1;
+  }
+  return letters >= 4;
+}
+
+/**
+ * 包住 translator.translate。
+ *
+ * @param ctx - cordis 插件上下文。
+ * @param deps - 运行期依赖。
+ * @returns 是否成功挂载。
+ */
+export function mountCotTranslatePoint(ctx, deps) {
+  const { runner, getConfig, telemetry } = deps;
+
+  const translator = ctx.get?.("translator");
+  if (translator === undefined || typeof translator.translate !== "function") {
+    ctx.logger?.info?.("dsh-decision-engine: 未找到 translator 服务，思维链翻译门槛不挂载");
+    return false;
+  }
+
+  const original = translator.translate;
+  /** 命中缓存的「需要翻译」判断：同一段文本重复翻译时不再问模型。 */
+  const decisions = new Map();
+  const MAX_DECISIONS = 256;
+
+  const remember = (key, value) => {
+    if (decisions.has(key)) decisions.delete(key);
+    decisions.set(key, value);
+    while (decisions.size > MAX_DECISIONS) {
+      const oldest = decisions.keys().next();
+      if (oldest.done) break;
+      decisions.delete(oldest.value);
+    }
+  };
+
+  const wrapped = async function translate(spec, signal) {
+    // 这个点关掉时连一次判断都不做，直接走原路径。
+    if (!runner.participates("cotTranslate")) return original.call(this, spec, signal);
+
+    try {
+      const text = typeof spec?.text === "string" ? spec.text : "";
+      // 本地预筛：明显不需要翻译的文本零成本跳过，不必问模型。
+      if (!looksLikeProse(text)) {
+        await telemetry.log({
+          ts: new Date().toISOString(),
+          point: "cotTranslate",
+          tag: "cotTranslate",
+          action: "skip",
+          detail: "decision-engine-cot: 本地预筛判定为无正文，跳过翻译",
+          latencyMs: 0,
+          cached: false,
+        });
+        return text;
+      }
+
+      // 缓存键：目标语言 + 文本摘要。同一段文本重复翻译（重放、重渲染）很常见。
+      const key = `${spec.targetLanguage ?? "auto"}|${text.length}|${text.slice(0, 64)}`;
+      let verdict = decisions.get(key);
+      if (verdict === undefined) {
+        const cfg = getConfig();
+        const result = await runner.ask(
+          "cotTranslate",
+          {
+            text,
+            targetLanguage: spec.targetLanguage,
+            sourceLanguage: spec.sourceLanguage,
+            head: text.slice(0, 400),
+          },
+          { signal },
+        );
+        // 降级 / observe / 关闭：一律按「需要翻译」处理，走原方法。
+        if (result.action === undefined || !runner.enforces("cotTranslate")) {
+          return original.call(this, spec, signal);
+        }
+        verdict = result.action.kind === "translate";
+        remember(key, verdict);
+      }
+
+      if (verdict === true) return original.call(this, spec, signal);
+
+      // 判为不需要翻译：返回原文。这与「已经是目标语言」的语义一致，
+      // 调用方不会看到异常，用户看到的还是那段文本。
+      await telemetry.log({
+        ts: new Date().toISOString(),
+        point: "cotTranslate",
+        tag: "cotTranslate",
+        action: "skip",
+        detail: "decision-engine-cot: 决策判定无需翻译，返回原文",
+        latencyMs: 0,
+        cached: true,
+      });
+      return text;
+    } catch (error) {
+      telemetry.noteAdapterError("cotTranslate", error, ctx);
+      // 任何意外都必须回到原生行为：翻译不能因为守卫而不可用。
+      return original.call(this, spec, signal);
+    }
+  };
+
+  translator.translate = wrapped;
+  // 卸载时恢复原方法：否则插件热卸载后 translator 会一直指着我们的包装。
+  ctx.effect(() => () => {
+    if (translator.translate === wrapped) translator.translate = original;
+  });
+  return true;
+}

package/lib/budget.js

@@ -0,0 +1,92 @@
+/**
+ * 决策模型自身的 token 预算。
+ *
+ * 引入理由：StartLux 每次决策实测约 1,900 token，p50 延迟约 2 秒。
+ * 把这个判断层挂到多个决策点上，调用量会成倍上升——如果不设上限，
+ * 「省 token 的插件」反而会变成主要的 token 消耗方。
+ *
+ * 预算按滑动窗口统计（默认 1 小时）。一旦超限，所有决策点立刻退回
+ * 本地启发式并 fail-open，等窗口滚过去自动恢复；不需要重启，也不会
+ * 让工具调用被卡住。
+ */
+export class TokenBudget {
+  /**
+   * @param getLimitTokens - 返回当前上限的取值函数；0 表示不限制。
+   *   刻意接收函数而不是数值：本插件的原则是「配置每次现读」，
+   *   若在构造时固化，用户在配置页改了预算就得重启才生效。
+   * @param getWindowMs - 返回当前窗口长度的取值函数。
+   */
+  constructor(getLimitTokens, getWindowMs) {
+    this.getLimitTokens = getLimitTokens;
+    this.getWindowMs = getWindowMs;
+    /** @type {Array<{at: number, tokens: number}>} */
+    this.entries = [];
+    this.blocked = 0;
+  }
+
+  /** 当前生效的上限（读不到时按不限制处理，绝不因预算自身出错而卡住决策）。 */
+  get limitTokens() {
+    const raw = typeof this.getLimitTokens === "function" ? this.getLimitTokens() : this.getLimitTokens;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  }
+
+  /** 当前生效的窗口长度。 */
+  get windowMs() {
+    const raw = typeof this.getWindowMs === "function" ? this.getWindowMs() : this.getWindowMs;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : 3600000;
+  }
+
+  /** 丢弃窗口外的记录。 */
+  prune(now = Date.now()) {
+    const cutoff = now - this.windowMs;
+    let drop = 0;
+    while (drop < this.entries.length && this.entries[drop].at < cutoff) drop += 1;
+    if (drop > 0) this.entries.splice(0, drop);
+  }
+
+  /** 窗口内已消耗的 token。 */
+  used(now = Date.now()) {
+    this.prune(now);
+    let total = 0;
+    for (const entry of this.entries) total += entry.tokens;
+    return total;
+  }
+
+  /** 预算是否已耗尽（未设置上限时永远 false）。 */
+  exhausted(now = Date.now()) {
+    if (this.limitTokens <= 0) return false;
+    return this.used(now) >= this.limitTokens;
+  }
+
+  /**
+   * 记一次消耗。
+   * @param tokens - 本次估算或实测的 input token 数。
+   */
+  spend(tokens) {
+    const amount = Number.isFinite(tokens) && tokens > 0 ? tokens : 0;
+    if (amount === 0) return;
+    this.entries.push({ at: Date.now(), tokens: amount });
+  }
+
+  /** 记一次「因为预算耗尽而放弃判断」，用于配置页展示。 */
+  noteBlocked() {
+    this.blocked += 1;
+  }
+
+  /** 供 UI 展示的快照。 */
+  get report() {
+    const now = Date.now();
+    const used = this.used(now);
+    const limit = this.limitTokens;
+    return {
+      used,
+      limit,
+      windowMs: this.windowMs,
+      remaining: limit <= 0 ? null : Math.max(0, limit - used),
+      exhausted: this.exhausted(now),
+      blocked: this.blocked,
+    };
+  }
+}