dsh-decision-engine 0.0.0-stage → 0.4.0

package/lib/adapters/agent.js

@@ -0,0 +1,307 @@
+/**
+ * 子任务分派、轮次延续、上下文压缩 —— 三个都挂在 `agent/pre-step` 与
+ * `agent/turn-stopping` 上的适配器。
+ *
+ * 为什么合在一个文件：三者的触发条件都依赖「这一步/这一轮到哪了」，
+ * 分成三个监听器会让同一份 inbox/step 状态被读三遍，也让「这一步到底问了
+ * 几个决策点」变得难以推断。这里用一个 pre-step 监听器内部分派。
+ *
+ * 各点的生效方式都刻意保守：
+ *
+ *   分派    只注入一条 runtime-context 建议，绝不替模型开子代理
+ *           （开子代理是模型的决定，插件越权会让上下文分叉不可控）
+ *   轮次    用 `agent.steer()` 续一轮，且每轮最多一次
+ *   压缩    只在自己判定够便宜时先跑确定性裁剪；摘要交给 compaction-basic
+ *
+ * @module dsh-decision-engine/adapters/agent
+ */
+
+/**
+ * 挂载分派 / 轮次 / 压缩三个监听器。
+ * @param ctx - cordis 插件上下文。
+ * @param deps - 运行期依赖。
+ */
+export function mountAgentPoints(ctx, deps) {
+  const { runner, getConfig, digestRecent, telemetry, makeUserMessage } = deps;
+
+  /** 每会话的续轮计数：turn → 已 steer 次数。防止自续无限循环。 */
+  const steerCounts = new WeakMap();
+
+  const steersThisTurn = (session, turn) => {
+    const map = steerCounts.get(session);
+    return map?.get(turn) ?? 0;
+  };
+
+  const noteSteer = (session, turn) => {
+    let map = steerCounts.get(session);
+    if (map === undefined) {
+      map = new Map();
+      steerCounts.set(session, map);
+    }
+    map.set(turn, (map.get(turn) ?? 0) + 1);
+    // 只保留最近两轮，避免长会话里这个 Map 无界增长。
+    if (map.size > 2) {
+      const oldest = map.keys().next();
+      if (!oldest.done) map.delete(oldest.value);
+    }
+  };
+
+  /** 取最近一步的助手文本，作为「这一轮说了什么」的判断依据。 */
+  const lastAssistantText = (session, chars) => {
+    let events;
+    try {
+      events = session.events ?? [];
+    } catch {
+      return "";
+    }
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index];
+      if (event?.type !== "assistant/message") continue;
+      const content = event.data?.message?.content;
+      if (!Array.isArray(content)) continue;
+      const text = content
+        .map((block) => (block?.type === "text" && typeof block.text === "string" ? block.text : ""))
+        .filter((part) => part.length > 0)
+        .join(" ");
+      if (text.length > 0) return text.slice(-chars);
+    }
+    return "";
+  };
+
+  // ---------------------------------------------------------------- pre-step
+  const preStep = async (payload, next) => {
+    const decision = await next();
+    // 判 reject 说明这一步根本没进入，注入建议没有意义。
+    if (decision.kind === "reject") return decision;
+    const agent = payload?.agent;
+    if (agent?.session === undefined) return decision;
+    const cfg = getConfig();
+
+    try {
+      const additions = [];
+
+      // ---- 上下文压缩 ------------------------------------------------
+      if (runner.participates("compact")) {
+        const compacted = await maybePruneContext(ctx, agent, payload, cfg, runner, telemetry);
+        if (compacted !== undefined) additions.push(compacted);
+      }
+
+      // ---- 子任务分派 ------------------------------------------------
+      // 只在「每轮第一步 + 这一步确实带着新的用户输入」时判断：
+      // 分派决策只在这个时刻可能改变，后续步骤再问必然是 inline。
+      if (runner.participates("delegate") && payload.step === 1 && payload.messages.length > 0) {
+        const incoming = payload.messages
+          .map((message) => textOf(message))
+          .filter((text) => text.length > 0)
+          .join("\n")
+          .slice(0, 1200);
+        if (incoming.length > 0) {
+          const result = await runner.ask(
+            "delegate",
+            {
+              turn: payload.turn,
+              step: payload.step,
+              incoming,
+              recent: digestRecent(agent.session, cfg.recentMessages, cfg.recentMessageChars),
+            },
+            { signal: payload.signal },
+          );
+          // 只有明确建议「开子代理/组队」时才注入提示；inline 不打扰。
+          if (runner.enforces("delegate") && result.action?.kind === "advise") {
+            additions.push(
+              makeUserMessage(
+                `[decision-engine-delegate] ${result.action.reason}\n` +
+                  `如果确实适合，请用 subagent / 团队工具把它分出去；否则直接在当前上下文里做完，不要为了分派而分派。`,
+                "delegate",
+              ),
+            );
+          }
+        }
+      }
+
+      if (additions.length === 0) return decision;
+      return { ...decision, messages: [...decision.messages, ...additions] };
+    } catch (error) {
+      telemetry.noteAdapterError("pre-step", error, ctx);
+      return decision;
+    }
+  };
+
+  ctx.on("agent/pre-step", preStep);
+
+  // ----------------------------------------------------------- turn-stopping
+  /**
+   * 轮次延续：`agent/turn-stopping` 是 serial 而不是 waterfall，返回值不传递，
+   * 唯一的生效方式是调用 `agent.steer(...)` 把消息塞回 inbox —— 机器随后
+   * 重新读一遍 inbox，有东西就再跑一步。
+   *
+   * 契约明确写了「数据决定，监听器顺序不改变结果」，因此这里唯一能做的就是
+   * 「steer 或不 steer」，不能否决别的监听器的意见。
+   */
+  const turnStopping = async (payload) => {
+    const agent = payload?.agent;
+    if (agent?.session === undefined) return;
+    if (!runner.participates("turnStop")) return;
+
+    try {
+      const cfg = getConfig();
+      // 每轮最多续一次：否则一轮里的空转会被无限放大成烧钱循环。
+      if (steersThisTurn(agent.session, payload.turn) >= Math.max(0, cfg.turnStopMaxSteers ?? 1)) return;
+
+      const last = lastAssistantText(agent.session, cfg.recentMessageChars * 4);
+      const result = await runner.ask(
+        "turnStop",
+        {
+          turn: payload.turn,
+          last,
+          pendingTools: 0,
+          steered: steersThisTurn(agent.session, payload.turn),
+        },
+        { signal: payload.signal },
+      );
+
+      if (!runner.enforces("turnStop")) return;
+      if (result.action?.kind !== "continue") return;
+      if (typeof agent.steer !== "function") return;
+
+      noteSteer(agent.session, payload.turn);
+      agent.steer(
+        makeUserMessage(
+          `[decision-engine-turnstop] ${result.action.reason}\n继续把没做完的部分做完；如果其实已经完成，直接说明结论即可。`,
+          "turnStop",
+        ),
+      );
+      ctx.logger?.info?.(`dsh-decision-engine: 第 ${payload.turn} 轮按决策续一轮`);
+    } catch (error) {
+      telemetry.noteAdapterError("turnStop", error, ctx);
+    }
+  };
+
+  ctx.on("agent/turn-stopping", turnStopping);
+}
+
+/** 把一条消息压成纯文本（只取 text block）。 */
+function textOf(message) {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => (block?.type === "text" && typeof block.text === "string" ? block.text : ""))
+    .filter((part) => part.length > 0)
+    .join(" ");
+}
+
+/**
+ * 上下文压缩：判断「现在只丢陈旧工具结果够不够」。
+ *
+ * 生效方式是调用宿主的 `toolResultPruner.pruneSession(session)` —— 这是一个
+ * 纯确定性、无模型、replay 安全的裁剪，把超长工具结果的中间段换成标记。
+ * 裁完之后 compaction-basic 会在同一步重新测量压力：低于阈值它就**跳过摘要**，
+ * 于是真正省下一次摘要调用。
+ *
+ * 绝不在 observe 模式下裁剪（那会改变会话内容），也绝不在没超阈值时裁剪。
+ *
+ * @returns 需要追加进这一步的提示消息，或 undefined（不注入）。
+ */
+async function maybePruneContext(ctx, agent, payload, cfg, runner, telemetry) {
+  const meter = ctx.get?.("tokenMeter");
+  const pruner = ctx.get?.("toolResultPruner");
+  if (meter === undefined || pruner === undefined) return undefined;
+
+  let measurement;
+  try {
+    measurement = meter.measure(agent.session);
+  } catch {
+    return undefined;
+  }
+  const total = Number(measurement?.totalTokens ?? 0);
+  if (total <= 0) return undefined;
+
+  // 触发线：compaction-basic 默认 thresholdRatio 0.8。它只在达到 0.8×contextWindow
+  // 时才动手，所以我们要在它之前判断，取 0.7 作为「提前介入」的位置。
+  // 拿不到 contextWindow 时退回绝对阈值，避免完全不动。
+  const contextWindow = Number(cfg.compactContextWindow ?? 0);
+  const threshold = contextWindow > 0 ? contextWindow * (cfg.compactThresholdRatio ?? 0.7) : (cfg.compactTriggerTokens ?? 100000);
+  if (total < threshold) return undefined;
+
+  // 先数一下有多少超长工具结果，没有就不必问模型。
+  const oversized = countOversizedToolResults(agent.session, cfg.compactToolResultChars ?? 8192);
+  if (oversized === 0) return undefined;
+
+  const result = await runner.ask(
+    "compact",
+    {
+      totalTokens: total,
+      triggerTokens: Math.round(threshold),
+      oversized,
+      nodes: Array.isArray(measurement?.nodes) ? measurement.nodes.length : 0,
+      recent: digestRecentSafe(agent.session, cfg),
+    },
+    { signal: payload.signal },
+  );
+
+  if (!runner.enforces("compact")) return undefined;
+  if (result.action?.kind !== "prune") return undefined;
+
+  let pruned;
+  try {
+    pruned = pruner.pruneSession(agent.session);
+  } catch (error) {
+    telemetry.noteAdapterError("compact", error, ctx);
+    return undefined;
+  }
+  if (pruned === undefined || pruned.pruned.length === 0) return undefined;
+
+  ctx.logger?.info?.(
+    `dsh-decision-engine: 裁剪 ${pruned.pruned.length} 条超长工具结果，省 ${pruned.charsRemoved} 字符（${result.action.reason}）`,
+  );
+  return undefined;
+}
+
+/** 数当前 surface 上超长的 tool/result 数量。 */
+function countOversizedToolResults(session, limit) {
+  let count = 0;
+  let nodes;
+  try {
+    nodes = session.surface?.nodes;
+  } catch {
+    return 0;
+  }
+  if (nodes === undefined) return 0;
+  for (const seq of nodes) {
+    let event;
+    try {
+      event = session.eventAt(seq);
+    } catch {
+      continue;
+    }
+    if (event?.type !== "tool/result") continue;
+    const content = event.data?.message?.content;
+    if (!Array.isArray(content)) continue;
+    let chars = 0;
+    for (const block of content) {
+      if (block?.type === "text" && typeof block.text === "string") chars += block.text.length;
+    }
+    if (chars > limit) count += 1;
+  }
+  return count;
+}
+
+/** 压缩判断里只需要很短的上下文；单独一个 helper 避免把大字符串传进 state。 */
+function digestRecentSafe(session, cfg) {
+  try {
+    const count = Math.min(cfg.recentMessages ?? 0, 4);
+    if (count <= 0) return "";
+    const events = session.events ?? [];
+    const lines = [];
+    for (let index = events.length - 1; index >= 0 && lines.length < count; index -= 1) {
+      const event = events[index];
+      if (event?.type !== "user/message" && event?.type !== "assistant/message") continue;
+      const text = textOf(event.data?.message ?? event.data);
+      if (text.length > 0) lines.unshift(text.slice(0, 160));
+    }
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}

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),
+  }));
+}