@leonhardthust/dsh-decision-engine 0.0.0-stage → 1.9.1

package/lib/index.js

@@ -0,0 +1,3823 @@
+/**
+ * dsh-decision-engine — 便宜的决策层：在主模型动手前问一个决策小模型。
+ * 可接任意提供决策端点的服务（`/v1/decisions` 或 `/v1/systemone`，路径由服务商决定）。
+ *
+ * 与 dsh-jev-interceptor 的三处关键差异：
+ *
+ * 1. **零可选 API 依赖**。不调用 `settings.installSection`（该 API 在 DSH 中不存在），
+ *    不依赖 `@deepseek-ai/dsh-credentials`、`launchEnvironmentOf`、`dshHomePath`。
+ *    密钥走 config → 环境变量两级，路径走 `home-paths.js`（与宿主同一套规则）。
+ *    宿主 API 缺失不会炸成静默失效。
+ *
+ * 2. **endpoint 每次请求重新解析**。`classify()` 现读 `cfg` 并重新解析 provider，
+ *    改配置立刻对下一次决策生效，无需重启（旧插件在 apply 期把 endpoint 固化进
+ *    JevClient，之后改 Base URL 永远不生效）。
+ *
+ * 3. **provider 抽象 + URL 规范化**。地址、鉴权变量名、默认模型全部来自
+ *    `providers.js` 的预设表，本文件不再出现任何具体服务商的域名。
+ *    `.../v1` 与 `.../v1/decisions` 等价——自动补端点段，不重复也不缺失。
+ *
+ * 省 token 的手段：结果缓存、think_mode 默认 never、只读工具跳过、
+ * state 截断、失败冷却。所有决策先过 shadow，默认绝不阻塞。
+ *
+ * @module dsh-decision-engine
+ */
+
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import z from "@deepseek-ai/schemastery";
+
+import { DecisionCache } from "./decision-cache.js";
+import { DECISION_POINTS, POINT_MODES, readPointModes } from "./decision-points.js";
+import { createDecisionRunner } from "./engine.js";
+import { POINT_SPECS } from "./points/spec.js";
+import { DEFAULT_RETRIEVAL_TOOLS, mountToolPoints } from "./adapters/tools.js";
+import { mountRoutePoint } from "./adapters/route.js";
+import { mountAgentPoints } from "./adapters/agent.js";
+import { mountCotTranslatePoint } from "./adapters/translate.js";
+import { applyConfigUpdates, parseConfigText } from "./config-file.js";
+import { EndpointMemory, sendWithEndpointFallback } from "./endpoint-fallback.js";
+// 韧性策略：哪些失败值得重试、冷却如何退避、失败如何翻译给用户看。
+// 三个判断都放在零依赖的纯函数模块里（时间由调用方传入），因此本文件只负责
+// 「照它执行」——热路径上的分支不再各写一份，避免两处规则漂移。
+import { describeFailure, isRetryableReason, nextCooldownMs, shouldRetry } from "./resilience.js";
+import { resolveDshHome } from "./home-paths.js";
+import { applyRefUpdates, listRefNames, pickRefValue } from "./credentials.js";
+import { RANGE_LABELS, RANGE_PRESETS, aggregate, buildRecord, resolveRange, sortRows } from "./stats.js";
+import { StatsStore } from "./stats-store.js";
+import { buildDecisionRecord, DecisionStore, MAX_ENTRIES_PER_QUERY } from "./decision-store.js";
+// 作用域边界（DEC-045）：越出工作区的写入、模型给用户挑方案、模型等用户
+// 澄清——这三类决定不属于本插件，遇到时让位给用户。
+import { GUARD_FALLBACKS, guardModelCatalog } from "./guard/fallback.js";
+import { mountGuard } from "./guard/listener.js";
+import { guardQuestions as safetyGuardQuestions, extractGuardAnswers as strictGuardAnswers, decideModelAdvisory } from "./guard/advisory.js";
+import { TELEMETRY_LEVELS, TelemetryReporter } from "./telemetry.js";
+import { estimateRequestTokens } from "./tokenizer.js";
+// 人工审核比例（DEC-035）：模型无关的打扰频率设定。与现有阈值分开——
+// 阈值回答「这个模型说什么算高」，tolerance 回答「大概每多少次问一次」。
+import {
+  DEFAULT_TOLERANCE,
+  TOLERANCE_LEVELS,
+  TOLERANCE_PRESETS,
+  ToleranceCalibrator,
+  resolveTolerance,
+  severityOf,
+  toleranceCutoff,
+  tolerancePreset,
+} from "./tolerance.js";
+// 服务端下发的取数与内存缓存（DEC-030）。刻意用零 fs 的独立模块：下发的
+// key 只活在 ServerConfigSource 实例里，本文件只负责把它接进各解析点。
+import { SERVER_CONFIG_ENDPOINT, ServerConfigSource } from "./server-config.js";
+import {
+  DEFAULT_PROVIDER,
+  DEFAULT_THINK_MODE,
+  ENDPOINT_STYLES,
+  PROVIDER_IDS,
+  PROVIDER_PRESETS,
+  SERVER_PROVIDER_ID,
+  SERVER_PROVIDER_LABEL,
+  THINK_MODES,
+  buildEndpoint,
+  buildHeaders,
+  buildRequestBody,
+  endpointStyleOfPath,
+  normalizeBaseUrl,
+  normalizeThinkMode,
+  parseCustomHeaders,
+  providerCatalog,
+  resolveKeyFor,
+  resolveProvider,
+  validateBaseUrl,
+} from "./providers.js";
+
+export const name = "dsh-decision-engine";
+export const inject = [];
+
+/**
+ * 默认端点：由 provider 预设推导，而不是写死域名。
+ *
+ * 保留这个导出是为了让 `scripts/verify-endpoint.mjs` 等外部脚本仍能取到
+ * 「默认往哪发」，同时保证它只在一个地方定义（providers.js）。
+ */
+const DEFAULT_BASE_URL = buildEndpoint(
+  PROVIDER_PRESETS[DEFAULT_PROVIDER].baseUrl,
+  PROVIDER_PRESETS[DEFAULT_PROVIDER].endpointStyle,
+);
+/** 默认 provider 的默认模型 id。 */
+const DEFAULT_MODEL = PROVIDER_PRESETS[DEFAULT_PROVIDER].defaultModel;
+/** 实测稳态约 2s、抖动可达 9.5s，默认给足 20s。旧插件默认 1500ms 必然超时。 */
+const DEFAULT_TIMEOUT_MS = 20000;
+
+const DEFAULTS = {
+  enabled: false,
+  mode: "shadow",
+  // ---- provider ---------------------------------------------------------
+  // 内置预设与 custom 的字段全部并列在顶层：本插件的配置读取器是极简
+  // YAML 子集（只认标量），嵌套对象读不出来；并列 + 前缀是本文件里
+  // 唯一既能手写、又能被面板回显、还不互相覆盖的形态。
+  provider: DEFAULT_PROVIDER,
+  /** bamboonode 预设的地址覆盖（老版本唯一的地址字段，必须继续生效）。 */
+  baseUrl: PROVIDER_PRESETS.bamboonode.baseUrl,
+  /** bamboonode 的模型字段（老版本唯一的模型键，默认值与历史一致）。 */
+  model: DEFAULT_MODEL,
+  /** system one 的模型字段；留空 = 由服务端选默认（jev-latest）。 */
+  systemoneModel: "",
+  /**
+   * 硅基流动 / Silicon Flow 的模型字段。
+   *
+   * 刻意留空、不在这里钉模型名：这两个端点把 `model` 列为必填（实测省略或
+   * 空串都回 400 `Model field is required.`），「留空」的语义由
+   * `resolveProvider` 解释为「用预设默认 Kev-4B」。填了就以填的为准
+   * （想换 SemIf 填 SemIf），两条路都不会发出注定失败的请求。
+   */
+  siliconflowModel: "",
+  siliconflowIntlModel: "",
+  /**
+   * Perplexity Decider / Openrouter 的模型字段。
+   *
+   * 与硅基流动同理：这两家的端点不接受省略 model，留空由 `resolveProvider`
+   * 回落到预设默认（见 providers.js）。默认值本身未实测，接通后按需覆盖。
+   */
+  perplexityModel: "",
+  openrouterModel: "",
+  /** 自定义 provider：地址、端点风格、鉴权、请求头、模型。 */
+  customBaseUrl: "",
+  customEndpointStyle: "auto",
+  customApiKey: "",
+  customApiKeyEnv: "",
+  /** 各 provider 的显式 key（与变量名分开存，互不覆盖）。 */
+  systemoneApiKey: "",
+  bamboonodeApiKey: "",
+  siliconflowApiKey: "",
+  siliconflowIntlApiKey: "",
+  perplexityApiKey: "",
+  openrouterApiKey: "",
+  customModel: "",
+  customHeaders: "",
+  /** 各预设的密钥来源变量名，留空即用预设内置值。 */
+  bamboonodeApiKeyEnv: "",
+  systemoneApiKeyEnv: "",
+  siliconflowApiKeyEnv: "",
+  siliconflowIntlApiKeyEnv: "",
+  perplexityApiKeyEnv: "",
+  openrouterApiKeyEnv: "",
+  /**
+   * 密钥保存位置：
+   *   credentials = ~/.dsh/.credentials.yaml 的 refs 段（默认，与其他服务统一托管）
+   *   config      = 插件自己的 config.yml（自包含，便于随目录备份/迁移）
+   */
+  keyStorage: "credentials",
+  /**
+   * 使用免费模型（DEC-030，原名「跟随服务端下发」；DEC-037 改名）。
+   *
+   * 默认 **false**：这是一个「显式选择要联系授权服务端」的开关，升级后
+   * 不该悄悄发起任何新请求。打开后下发的地址/模型/key 只在内存里覆盖本地
+   * 配置，**永不写进 cfg / config.yml / 凭据文件**（实现与理由见
+   * lib/server-config.js 顶部三条设计红线）。
+   *
+   * 配置键名保持 `serverProvider`（改名不改行为，改的是用户看到的文案；
+   * 键名是已落盘的契约，改名会让老配置静默失效）。
+   */
+  serverProvider: false,
+  apiKeyEnv: "BAMBOO_API_KEY",
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+  /**
+   * 超时 / 网络错误的重试次数。**只对这两类重试**：4xx 是配置错（地址、模型、
+   * key），5xx 是服务端自己的故障，重发只会拿回同一个错误、多烧一次额度。
+   *
+   * 为什么默认 1：服务端冷启动时首发实测要 7–16 秒，而**首发即使被超时掐断，
+   * 也已经把服务端焐热了**——紧接着的第二发 1.1–1.7 秒必中（4 组独立实验
+   * 一致）。生产遥测里 timeout 83 次、network-error 84 次，其中相当一部分正是
+   * 「首发被 8s 预算掐断」。只重试一次而不是更多：第二发仍失败说明不是冷启动
+   * 问题，继续重试只是把一次失败拖成一次更慢的失败。
+   */
+  retryAttempts: 1,
+  // 思考模式：取值与默认值都来自 providers.js，避免两处各写一份而漂移。
+  thinkMode: DEFAULT_THINK_MODE,
+  cooldownMs: 60000,
+  /**
+   * 冷却期内的试探间隔（毫秒）——冷却从「整段全黑」改成半开。
+   *
+   * 为什么是 10000：连续 3 败后的 60 秒冷却在生产遥测里制造了 **93 次**
+   * cooldown 降级，它们不是真的失败，而是「冷却期间所有决策直接快速失败」
+   * （0–1ms）——这是前几类失败的放大器。而冷启动抖动实测往往 3 秒就恢复，
+   * 60 秒全黑等于把一次瞬时失败放大成整整一分钟不工作。每 10 秒放行一次
+   * 试探，把恢复时间从「最多 60s」压到「最多 10s」；间隔又不能太小，否则
+   * 服务真故障时会变成重试风暴。
+   */
+  cooldownProbeMs: 10000,
+  failureThreshold: 3,
+  cacheSize: 256,
+  recentMessages: 4,
+  recentMessageChars: 240,
+  argsHeadChars: 1024,
+  argsTailChars: 256,
+  maxStateChars: 6000,
+  guardEnabled: true,
+  guardPolicyMode: "enforce",
+  guardFallback: "session",
+  guardFallbackProvider: "",
+  guardFallbackModel: "",
+  guardFallbackReasoningEffort: "",
+  guardReadOnlyTools: ["read", "read_image", "grep", "glob", "list_agents"],
+  guardExcludeTools: [],
+  guardConfidenceMin: 0.6,
+  guardDenyConfidence: 0.85,
+  guardIrreversibleCeiling: 0.2,
+  /**
+   * 任务相关性否决线：低风险 + 可能不可逆的调用，只有当「服务于当前任务」
+   * 的概率低于此线时才升级询问。实测（DEC-008）决策模型对普通 bash 命令的
+   * irreversible 输出基线在 0.2–0.4，单看该分数会把大量良性调用推进人工
+   * 确认；而 taskP 与 ask 组高度相关（ask 组里 100% taskP≥0.5），作为否决
+   * 条件能把误打扰砍掉约六成，同时保留真正「与任务无关且可能不可逆」的可疑调用。
+   */
+  guardTaskRelevanceFloor: 0.5,
+  guardIrreversibleDenyFloor: 0.5,
+  guardInjectionAskThreshold: 0.8,
+  // ---- 模型路由（pointRoute）--------------------------------------------
+  // 下沉目标：留空表示「不路由」（即便点被打开也不换模型）。
+  routeCheapProvider: "",
+  routeCheapModel: "",
+  routeMaxStepsPerTurn: 3,
+  routeMaxScore: 0.4,
+  routeMechanicalFloor: 0.6,
+  routeRiskFloor: 0.3,
+  // ---- 子任务分派（pointDelegate）---------------------------------------
+  delegateConfidenceFloor: 0.5,
+  delegateBlockingFloor: 0.6,
+  delegateParallelFloor: 0.5,
+  // ---- 上下文压缩（pointCompact）----------------------------------------
+  // contextWindow 拿不到时用 compactTriggerTokens 作绝对阈值。
+  compactContextWindow: 0,
+  compactThresholdRatio: 0.7,
+  compactTriggerTokens: 100000,
+  compactToolResultChars: 8192,
+  // 实测：结论已落地 → distilled 0.81；结论未落地 → 0.41。
+  compactDistilledFloor: 0.6,
+  // 安全否决：仍需逐字原文时绝不裁剪（实测两类均 0.26，故门槛取高）。
+  compactVerbatinFloor: 0.6,
+  // ---- 轮次延续（pointTurnStop）-----------------------------------------
+  turnStopMaxSteers: 1,
+  // 实测：已完成 → closed 0.74 / unfin 0.09 / value 0.09；
+  //        未完成 → closed 0.28 / unfin 0.83 / value 0.39。
+  // value 取 0.35 而不是更高：「未完成」那组的 value 只有 0.39，门槛设到 0.4
+  // 会把它判成不续轮。value 在这里只是「有增量」的弱确认，主判据是 unfin。
+  turnStopClosedFloor: 0.6,
+  turnStopUnfinishedFloor: 0.6,
+  turnStopValueFloor: 0.35,
+  /**
+   * 「这一轮在等用户」的判定门槛（DEC-045）。
+   *
+   * 达线即让位：不续轮，把决定权交还用户。取 0.5 是因为**两类错代价不对等**：
+   * 漏判（把「在等用户」当成「还有活没干完」）= 替用户把选择顶掉，这是本
+   * 插件最不该犯的错；误判（把「干完了」当成「在等用户」）= 少续一轮，代价小得多。
+   *
+   * 注意这条**只用于让位**：模型判出「在等用户」的结果**不会**变成
+   * 「所以替用户选了方案 A」——插件没有任何「代替用户决定」的路。
+   */
+  turnStopAwaitingUserFloor: 0.5,
+  /**
+   * 是否让守卫退出「越出工作区」这件事（DEC-045）。
+   *
+   * 默认 **true**：越界写入的判定权属于用户与宿主沙箱，不属于本插件。
+   * 打开后，守卫遇到目标确定在写根之外的调用时**直接放行**（不询问、不拦下、
+   * 不发请求），把「能不能写到工作区外面」这个决定完整地留给宿主沙箱与用户。
+   *
+   * 关掉它不会让插件去**管**这件事，只会让它回到旧行为（照常问模型）。
+   */
+  guardDeferOutsideWorkspace: true,
+  // ---- 检索必要性（pointRetrieval）--------------------------------------
+  retrievalTools: [...DEFAULT_RETRIEVAL_TOOLS],
+  // 实测（问法见 points/spec.js）：
+  //   已覆盖（完整问答）covered 0.87 / would_add 0.53
+  //   已覆盖（简短）    covered 0.53 / would_add 0.79
+  //   未覆盖            covered 0.03 / would_add 0.93
+  // covered 取 0.5 以容纳「简短覆盖」那种情形；would_add 上限取 0.8，
+  // 使「已覆盖且再搜基本没新增」才跳过。两个条件必须同时满足。
+  retrievalCoveredFloor: 0.5,
+  retrievalWouldAddCeiling: 0.8,
+  // ---- 技能选择（pointSkillPick）----------------------------------------
+  skillPickCandidates: 8,
+  skillPickConfidenceFloor: 0.5,
+  // ---- 思维链翻译门槛（pointCotTranslate）-------------------------------
+  cotProseFloor: 0.5,
+  cotSameLanguageFloor: 0.7,
+  // ---- 决策点参与模式（off | observe | enforce）--------------------------
+  // 未显式设置时，`pointAuthorize` 回退到旧的顶层 `mode`（shadow→observe、
+  // enforce→enforce），其余决策点默认不参与。这样升级不会改变现有行为。
+  pointAuthorize: "auto",
+  pointRoute: "off",
+  pointDelegate: "off",
+  pointCompact: "off",
+  pointTurnStop: "off",
+  pointRetrieval: "off",
+  pointSkillPick: "off",
+  pointCotTranslate: "off",
+  // ---- 自身开销护栏 ----------------------------------------------------
+  cacheTtlMs: 600000,
+  // ---- 匿名使用统计（DEC-020）-------------------------------------------
+  // 默认 daily：每天都上报一次。为什么不选 install（只报首次）——那样
+  // daily_active 只会在安装当天有一行，之后 DAU/WAU 恒为 0，等于统计失效。
+  // 「默认不擅自介入」约束的是守卫（改裁决），不是这条旁路。
+  telemetryLevel: "daily",
+  /** 上报地址；留空用 lib/telemetry.js 的默认端点（dsh.zuos.us）。 */
+  telemetryEndpoint: "",
+  // ---- 决策历史（DEC-022）-------------------------------------------------
+  /**
+   * 是否记录决策明细并在会话里挂「决策历史」标签页。
+   *
+   * 默认 **true**：这是用户要的功能，不记录就等于这个页面永远空着。
+   * 但它仍然是个开关——关掉之后**不写任何明细文件**（不采集内容、不占
+   * 磁盘），而不是「写了再藏起来」。理由：明细里可能有会话正文与命令
+   * 片段，用户说不记录就该真的不落盘。
+   *
+   * 注意它与 `enabled` 无关：守卫没启用时明细也照记，因为「记录」本身
+   * 正是这个页面的用途（观察模式下尤其如此）。
+   */
+  decisionsTabEnabled: true,
+  /**
+   * 接管宿主审批卡的正文块（`conversation.approval.detail`），把它从「命令原文
+   * 原样铺一整块」改成「摘要 + 可展开的原文」（DEC-042，DEC-043 起默认开启）。
+   *
+   * 默认 **true**：宿主把 `args.command` 塞进一个 `word-break: break-all` 的
+   * 块里，且没有 `white-space: pre-wrap`——换行因此全部被折叠，一段 heredoc
+   * 脚本会变成一整面读不出结构的字墙。这就是不打任何补丁时的真实体验，而
+   * 「读得懂」正是这个插件存在的理由，所以可读卡片才是默认。
+   *
+   * 但它仍然是个开关：关掉之后回到宿主的渲染，与 1.5.x **逐字节一致**。
+   * 需要说清的代价是——接管意味着这块 UI 由我们渲染，宿主将来对它的改进
+   * 不会自动落到我们身上。更认宿主那套呈现的用户，把它关掉即可。
+   *
+   * 与 `decisionsTabEnabled` 无关：那个管「记录」，这个管「审批卡长什么样」。
+   */
+  approvalDetailReadable: true,
+  /** 单条内容的序列化长度上限；超了按「参数 → 摘要 → 整个 state」依次裁剪。 */
+  decisionsMaxContentChars: 4000,
+  /** 明细文件体积上限（字节）；到顶轮转成 `decisions.jsonl.1`（只留一代）。 */
+  decisionsMaxBytes: 8 * 1024 * 1024,
+  /**
+   * 人工审核比例（tolerance，DEC-035）。
+   *
+   * 与上面那些 `guard*` 阈值是**两件事**：
+   *
+   *   - `guard*` 阈值是在**某一家决策模型**的输出分布上校准的绝对分数，
+   *     换模型就失去意义；
+   *   - `tolerance` 是**模型无关**的体验设定：用户说的是「大概每多少次调用
+   *     来问我一次」，而不是「阈值取多少」。
+   *
+   * 默认 `default` = 当前的默认行为（逐字不变），升级不改变任何东西。
+   * 四档：autonomous（0%）/ relaxed（最前 1%）/ default（当前）/ cautious（更保守）。
+   */
+  tolerance: DEFAULT_TOLERANCE,
+};
+
+/**
+ * 插件配置。
+ *
+ * **刻意不使用 `.volatile()`**：本插件的配置只来自 profile 的
+ * `cordis.patch.yml`，不进 Settings 面板（只有一个 api key，放面板里没必要）。
+ * 而 `.volatile()` 会让 Schemastery 把值包装成 `{ get(), [volatile.write] }`
+ * 对象，`cfg.enabled === true` 之类判断就会失效——除非处处 `get()`。
+ * 不走 settings 服务就不用付这个代价，配置读出来全是普通值。
+ */
+export const Config = z.object({
+  enabled: z.boolean().default(DEFAULTS.enabled),
+  mode: z.union(["shadow", "enforce"]).default(DEFAULTS.mode),
+  // ---- provider 选择 -----------------------------------------------------
+  provider: z.union([...PROVIDER_IDS]).default(DEFAULTS.provider)
+    .description(
+      "systemone = TypeSafe 官方端点（POST /v1/systemone）；"
+        + "bamboonode = StartLux 官方端点（POST /v1/decisions，原有默认）；"
+        + "siliconflow = 硅基流动（api.siliconflow.cn，POST /v1/systemone）；"
+        + "siliconflow-intl = Silicon Flow 国际站（api.siliconflow.com）；"
+        + "perplexity = Perplexity Decider（api.perplexity.ai，待实测）；"
+        + "openrouter = OpenRouter（openrouter.ai/api/v1，待实测）；"
+        + "custom = 自己填地址（任意提供决策端点的服务，路径可自动回退）",
+    ),
+  baseUrl: z.string().default(DEFAULTS.baseUrl)
+    .description("bamboonode 预设的地址覆盖；/v1 与 /v1/decisions 两种写法都接受"),
+  model: z.string().default(DEFAULTS.model)
+    .description("bamboonode 预设的模型 id；留空表示由服务端选默认"),
+  systemoneModel: z.string().default(DEFAULTS.systemoneModel)
+    .description("system one 预设的模型 id；留空表示由服务端选默认（jev-latest）"),
+  siliconflowModel: z.string().default(DEFAULTS.siliconflowModel)
+    .description("硅基流动预设的模型 id；留空用预设默认 Kev-4B（该端点 model 必填，不可省略）"),
+  siliconflowIntlModel: z.string().default(DEFAULTS.siliconflowIntlModel)
+    .description("Silicon Flow 国际站预设的模型 id；留空用预设默认 Kev-4B（该端点 model 必填）"),
+  perplexityModel: z.string().default(DEFAULTS.perplexityModel)
+    .description("Perplexity Decider 预设的模型 id；留空用预设默认 sonar（端点 model 必填）"),
+  openrouterModel: z.string().default(DEFAULTS.openrouterModel)
+    .description("OpenRouter 预设的模型 slug；留空用预设默认 openai/gpt-4o-mini（请求必带 model）"),
+  customBaseUrl: z.string().default(DEFAULTS.customBaseUrl)
+    .description("provider=custom 时的 base URL，必须是 http/https 地址"),
+  customEndpointStyle: z.union([...ENDPOINT_STYLES]).default(DEFAULTS.customEndpointStyle)
+    .description("custom 的端点风格：auto 已带端点就原样用 / decisions / systemone"),
+  customApiKey: z.string().role("secret").default(DEFAULTS.customApiKey)
+    .description("custom 的 API key；留空则读 customApiKeyEnv 指定的 refs 键/环境变量"),
+  systemoneApiKey: z.string().role("secret").default(DEFAULTS.systemoneApiKey)
+    .description("system one 的 API key；留空则读 TYPESAFE_API_KEY"),
+  bamboonodeApiKey: z.string().role("secret").default(DEFAULTS.bamboonodeApiKey)
+    .description("bamboonode 的 API key；留空则读 BAMBOO_API_KEY"),
+  siliconflowApiKey: z.string().role("secret").default(DEFAULTS.siliconflowApiKey)
+    .description("硅基流动的 API key；留空则读 SILICONFLOW_API_KEY"),
+  siliconflowIntlApiKey: z.string().role("secret").default(DEFAULTS.siliconflowIntlApiKey)
+    .description("Silicon Flow 国际站的 API key；留空则读 SILICONFLOW_INTL_API_KEY"),
+  perplexityApiKey: z.string().role("secret").default(DEFAULTS.perplexityApiKey)
+    .description("Perplexity Decider 的 API key；留空则读 PERPLEXITY_API_KEY"),
+  openrouterApiKey: z.string().role("secret").default(DEFAULTS.openrouterApiKey)
+    .description("OpenRouter 的 API key；留空则读 OPENROUTER_API_KEY"),
+  customApiKeyEnv: z.string().default(DEFAULTS.customApiKeyEnv)
+    .description("custom 的密钥来源变量名（环境变量或 .credentials.yaml 的 refs 键）"),
+  customModel: z.string().default(DEFAULTS.customModel)
+    .description("custom 的模型 id；留空表示由服务端选默认"),
+  customHeaders: z.string().default(DEFAULTS.customHeaders)
+    .description("custom 的附加请求头，形如 `X-Tenant: a; X-Trace: b`"),
+  bamboonodeApiKeyEnv: z.string().default(DEFAULTS.bamboonodeApiKeyEnv)
+    .description("bamboonode 预设的密钥变量名覆盖；留空用 BAMBOO_API_KEY"),
+  systemoneApiKeyEnv: z.string().default(DEFAULTS.systemoneApiKeyEnv)
+    .description("systemone 预设的密钥变量名覆盖；留空用 TYPESAFE_API_KEY"),
+  siliconflowApiKeyEnv: z.string().default(DEFAULTS.siliconflowApiKeyEnv)
+    .description("siliconflow 预设的密钥变量名覆盖；留空用 SILICONFLOW_API_KEY"),
+  siliconflowIntlApiKeyEnv: z.string().default(DEFAULTS.siliconflowIntlApiKeyEnv)
+    .description("siliconflow-intl 预设的密钥变量名覆盖；留空用 SILICONFLOW_INTL_API_KEY"),
+  perplexityApiKeyEnv: z.string().default(DEFAULTS.perplexityApiKeyEnv)
+    .description("perplexity 预设的密钥变量名覆盖；留空用 PERPLEXITY_API_KEY"),
+  openrouterApiKeyEnv: z.string().default(DEFAULTS.openrouterApiKeyEnv)
+    .description("openrouter 预设的密钥变量名覆盖；留空用 OPENROUTER_API_KEY"),
+  apiKey: z.string().role("secret")
+    .description("当前 provider 的 API key；留空则读 apiKeyEnv 指定的环境变量"),
+  apiKeyEnv: z.string().default(DEFAULTS.apiKeyEnv)
+    .description("bamboonode 预设的密钥变量名覆盖；留空用 BAMBOO_API_KEY"),
+  keyStorage: z.union(["credentials", "config"]).default(DEFAULTS.keyStorage)
+    .description(
+      "密钥保存位置：credentials = ~/.dsh/.credentials.yaml（默认，与其他服务统一托管）；"
+        + "config = 插件配置目录下的 config.yml",
+    ),
+  serverProvider: z.boolean().default(DEFAULTS.serverProvider)
+    .description(
+      "使用免费模型（DEC-030，原名「跟随服务端下发」）：开启后从授权服务获取地址/模型/密钥并在内存中覆盖本地配置；"
+        + "下发的密钥只在内存里，永不写入 config.yml 或凭据文件。默认关闭（不主动联系该端点）。"
+        + "免费通道可能会失效——不可用时插件回落到本地手动配置",
+    ),
+  timeoutMs: z.number().step(1).min(1000).default(DEFAULTS.timeoutMs),
+  retryAttempts: z.number().step(1).min(0).max(3).default(DEFAULTS.retryAttempts)
+    .description("仅对超时与网络错误重试的次数；4xx/5xx 不重试（配置错与服务端故障，重发只会多烧额度）"),
+  thinkMode: z.union(["never", "auto", "always"]).default(DEFAULTS.thinkMode)
+    .description("never 最省 token；auto 仅在不确定时思考"),
+  cooldownMs: z.number().step(1).min(1000).default(DEFAULTS.cooldownMs),
+  cooldownProbeMs: z.number().step(1).min(1000).default(DEFAULTS.cooldownProbeMs)
+    .description("冷却期内每隔这么久放行一次试探请求；试探成功即彻底解除冷却"),
+  failureThreshold: z.number().step(1).min(1).default(DEFAULTS.failureThreshold),
+  cacheSize: z.number().step(1).min(0).default(DEFAULTS.cacheSize),
+  recentMessages: z.number().step(1).min(0).max(12).default(DEFAULTS.recentMessages),
+  recentMessageChars: z.number().step(1).min(40).default(DEFAULTS.recentMessageChars),
+  argsHeadChars: z.number().step(1).min(64).default(DEFAULTS.argsHeadChars),
+  argsTailChars: z.number().step(1).min(0).default(DEFAULTS.argsTailChars),
+  maxStateChars: z.number().step(1).min(500).default(DEFAULTS.maxStateChars),
+  guardEnabled: z.boolean().default(DEFAULTS.guardEnabled),
+  guardPolicyMode: z.union(["observe", "enforce"]).default(DEFAULTS.guardPolicyMode),
+  guardFallback: z.union(GUARD_FALLBACKS).default(DEFAULTS.guardFallback),
+  guardFallbackProvider: z.string().default(DEFAULTS.guardFallbackProvider),
+  guardFallbackModel: z.string().default(DEFAULTS.guardFallbackModel),
+  guardFallbackReasoningEffort: z.string().default(DEFAULTS.guardFallbackReasoningEffort),
+  guardReadOnlyTools: z.array(z.string()).default([...DEFAULTS.guardReadOnlyTools]),
+  guardExcludeTools: z.array(z.string()).default([...DEFAULTS.guardExcludeTools]),
+  guardConfidenceMin: z.number().min(0).max(1).default(DEFAULTS.guardConfidenceMin),
+  guardDenyConfidence: z.number().min(0).max(1).default(DEFAULTS.guardDenyConfidence),
+  guardIrreversibleCeiling: z.number().min(0).max(1).default(DEFAULTS.guardIrreversibleCeiling),
+  guardTaskRelevanceFloor: z.number().min(0).max(1).default(DEFAULTS.guardTaskRelevanceFloor)
+    .description("任务相关性否决线：低风险且可能不可逆的调用，仅当 taskP 低于此值才升级询问"),
+  guardIrreversibleDenyFloor: z.number().min(0).max(1).default(DEFAULTS.guardIrreversibleDenyFloor),
+  guardInjectionAskThreshold: z.number().min(0).max(1).default(DEFAULTS.guardInjectionAskThreshold),
+  // ---- 模型路由 --------------------------------------------------------
+  routeCheapProvider: z.string().default(DEFAULTS.routeCheapProvider)
+    .description("下沉目标的 provider；留空表示不路由"),
+  routeCheapModel: z.string().default(DEFAULTS.routeCheapModel)
+    .description("下沉目标的 model；与 provider 一起留空即不路由"),
+  routeMaxStepsPerTurn: z.number().step(1).min(1).max(20).default(DEFAULTS.routeMaxStepsPerTurn)
+    .description("每轮最多判断几步路由；后续步骤沿用本轮裁决"),
+  routeMaxScore: z.number().min(0).max(1).default(DEFAULTS.routeMaxScore),
+  routeMechanicalFloor: z.number().min(0).max(1).default(DEFAULTS.routeMechanicalFloor),
+  routeRiskFloor: z.number().min(0).max(1).default(DEFAULTS.routeRiskFloor),
+  // ---- 子任务分派 ------------------------------------------------------
+  delegateConfidenceFloor: z.number().min(0).max(1).default(DEFAULTS.delegateConfidenceFloor)
+    .description("分派倾向的置信门槛；三选项均分为 0.33，实测需 ≥0.5 才算有倾向"),
+  delegateBlockingFloor: z.number().min(0).max(1).default(DEFAULTS.delegateBlockingFloor),
+  delegateParallelFloor: z.number().min(0).max(1).default(DEFAULTS.delegateParallelFloor),
+  // ---- 上下文压缩 ------------------------------------------------------
+  compactContextWindow: z.number().step(1).min(0).default(DEFAULTS.compactContextWindow)
+    .description("上下文窗口 token 数；0 表示改用 compactTriggerTokens 绝对阈值"),
+  compactThresholdRatio: z.number().min(0.1).max(1).default(DEFAULTS.compactThresholdRatio),
+  compactTriggerTokens: z.number().step(1).min(1000).default(DEFAULTS.compactTriggerTokens),
+  compactToolResultChars: z.number().step(1).min(1024).default(DEFAULTS.compactToolResultChars),
+  compactDistilledFloor: z.number().min(0).max(1).default(DEFAULTS.compactDistilledFloor)
+    .description("判定「工具结果的信息已落地」的门槛；达线才允许只裁剪"),
+  compactVerbatinFloor: z.number().min(0).max(1).default(DEFAULTS.compactVerbatinFloor)
+    .description("仍需逐字原文的门槛；达线一律改走摘要"),
+  // ---- 轮次延续 --------------------------------------------------------
+  turnStopMaxSteers: z.number().step(1).min(0).max(5).default(DEFAULTS.turnStopMaxSteers),
+  turnStopClosedFloor: z.number().min(0).max(1).default(DEFAULTS.turnStopClosedFloor),
+  turnStopUnfinishedFloor: z.number().min(0).max(1).default(DEFAULTS.turnStopUnfinishedFloor),
+  turnStopValueFloor: z.number().min(0).max(1).default(DEFAULTS.turnStopValueFloor),
+  turnStopAwaitingUserFloor: z.number().min(0).max(1).default(DEFAULTS.turnStopAwaitingUserFloor)
+    .description("判定「这一轮在等用户」的门槛；达线即让位，不续轮"),
+  guardDeferOutsideWorkspace: z.boolean().default(DEFAULTS.guardDeferOutsideWorkspace)
+    .description("越出工作区的写入不由本插件裁决：放行并把决定权留给宿主沙箱与用户"),
+  // ---- 检索必要性 ------------------------------------------------------
+  retrievalTools: z.array(z.string()).default([...DEFAULTS.retrievalTools]),
+  retrievalCoveredFloor: z.number().min(0).max(1).default(DEFAULTS.retrievalCoveredFloor)
+    .description("上下文已覆盖该事实的门槛"),
+  retrievalWouldAddCeiling: z.number().min(0).max(1).default(DEFAULTS.retrievalWouldAddCeiling)
+    .description("再搜也拿不到新信息的门槛上限"),
+  // ---- 技能选择 --------------------------------------------------------
+  skillPickCandidates: z.number().step(1).min(2).max(20).default(DEFAULTS.skillPickCandidates),
+  skillPickConfidenceFloor: z.number().min(0).max(1).default(DEFAULTS.skillPickConfidenceFloor),
+  // ---- 会话标题 --------------------------------------------------------
+  // ---- 思维链翻译门槛 --------------------------------------------------
+  cotProseFloor: z.number().min(0).max(1).default(DEFAULTS.cotProseFloor),
+  cotSameLanguageFloor: z.number().min(0).max(1).default(DEFAULTS.cotSameLanguageFloor),
+  // 决策点参与模式由注册表生成，保证配置项与 DECISION_POINTS 永不脱节。
+  // "auto" 仅对 authorize 有意义：跟随旧的顶层 `mode`。
+  ...Object.fromEntries(
+    DECISION_POINTS.map((point) => [
+      point.key,
+      z
+        .union(point.id === "authorize" ? [...POINT_MODES, "auto"] : POINT_MODES)
+        .default(DEFAULTS[point.key])
+        .description(`${point.label}：off 不参与 / observe 只记录 / enforce 生效`),
+    ]),
+  ),
+  cacheTtlMs: z.number().step(1).min(1000).default(DEFAULTS.cacheTtlMs)
+    .description("缓存存活时间；改策略或配置后旧裁决不应继续被复用"),
+  telemetryLevel: z.union([...TELEMETRY_LEVELS]).default(DEFAULTS.telemetryLevel)
+    .description(
+      "匿名使用统计：off 完全不联网 / install 仅首次运行报一次（默认）/ "
+        + "daily 每天报一次（含当日决策数）。只上报插件版本、平台、架构与计数，"
+        + "永不上报 prompt、密钥、路径或会话内容",
+    ),
+  telemetryEndpoint: z.string().default(DEFAULTS.telemetryEndpoint)
+    .description("统计上报地址；留空用内置端点（https://dsh.zuos.us/api/e）"),
+  decisionsTabEnabled: z.boolean().default(DEFAULTS.decisionsTabEnabled)
+    .description(
+      "决策历史：在本会话里新增一个「决策历史」标签页，按时间列出经本插件做出的每次决策。"
+        + "关闭后不写任何明细文件（不采集内容、不占磁盘）",
+    ),
+  approvalDetailReadable: z.boolean().default(DEFAULTS.approvalDetailReadable)
+    .description(
+      "审批卡正文可读化：接管宿主的命令块，显示「几步、哪几步危险」的摘要，"
+        + "原文默认收起、可展开（保留换行、限高滚动）。默认开启；"
+        + "关闭后完全沿用宿主的渲染，与升级前逐字节一致",
+    ),
+  decisionsMaxContentChars: z.number().step(1).min(200).default(DEFAULTS.decisionsMaxContentChars)
+    .description("单条决策内容的字符上限；超出时依次裁剪工具参数、对话摘要、整个 state"),
+  decisionsMaxBytes: z.number().step(1).min(1024 * 1024).default(DEFAULTS.decisionsMaxBytes)
+    .description("明细文件体积上限（字节）；到顶轮转成 decisions.jsonl.1，只留一代"),
+  tolerance: z.union([...TOLERANCE_LEVELS]).default(DEFAULTS.tolerance)
+    .description(
+      "人工审核比例（模型无关）：autonomous 从不问用户 / relaxed 只问最前 1% / "
+        + "default 按决策模型自己的判断（当前默认）/ cautious 在默认之外再问最前 25%",
+    ),
+});
+
+/**
+ * 解析每个决策点此刻的生效模式。
+ *
+ * `auto` 是向后兼容用的：它把旧的顶层 `mode` 映射成三态
+ * （shadow → observe、enforce → enforce）。这样从 0.1.x 升上来时，
+ * 已经写了 `mode: enforce` 的用户行为不变，不必再配一遍。
+ *
+ * 其余决策点没有历史包袱，`auto` 一律按 off 处理。
+ *
+ * @param cfg - 已合并的配置。
+ * @returns id → 模式 的表。
+ */
+export function effectivePointModes(cfg) {
+  const legacy = cfg?.mode === "enforce" ? "enforce" : cfg?.mode === "shadow" ? "observe" : "off";
+  /** @type {Record<string, string>} */
+  const modes = readPointModes({});
+  for (const point of DECISION_POINTS) {
+    const raw = cfg?.[point.key];
+    if (POINT_MODES.includes(raw)) {
+      modes[point.id] = raw;
+    } else if (raw === "auto") {
+      modes[point.id] = point.id === "authorize" ? legacy : "off";
+    } else {
+      modes[point.id] = "off";
+    }
+  }
+  return modes;
+}
+
+/**
+ * 把用户填的 base URL 规范化为完整端点。
+ *
+ * 保留这个导出的理由：它是最早的公开契约（`verify-wiring.mjs` 与用户脚本
+ * 都在用它）。实现已经下沉到 `providers.buildEndpoint`——本文件不再持有
+ * 任何具体服务商的域名。
+ *
+ * 语义向后兼容：不传 style 时按 `decisions` 处理，与旧行为一致；
+ * `.../v1` 与 `.../v1/decisions` 仍等价。
+ *
+ * @param raw - 配置里的 baseUrl。
+ * @param style - `decisions` / `systemone` / `auto`，默认 decisions。
+ * @returns 可直接 POST 的完整 URL；输入为空时返回默认端点。
+ */
+export function normalizeEndpoint(raw, style = "decisions") {
+  const trimmed = typeof raw === "string" ? raw.trim() : "";
+  if (trimmed.length === 0) return DEFAULT_BASE_URL;
+  // 老配置允许省略 scheme（`api.x.dev/v1`），这里补齐后再交给 buildEndpoint。
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  return buildEndpoint(withScheme, style);
+}
+
+/**
+ * 校验一次 provider 相关的配置改动。
+ *
+ * 刻意在**落盘之前**校验：先写 yml 再报错，等于把坏配置留在文件里，
+ * 用户重启后就带着它跑（而降级是静默的，只会表现为「守卫没反应」）。
+ *
+ * 校验对象是「合并后的结果」而不是 patch 本身——因为必填项依赖当前选择：
+ * 切到 custom 但 customBaseUrl 为空时必须拒绝，而单看 patch 里只有 provider
+ * 一个键，是看不出这个冲突的。
+ *
+ * @param patch - 待写入的键值。
+ * @param current - 当前生效配置。
+ * @returns `{ ok: true }` 或 `{ ok: false, error }`（error 可直接展示）。
+ */
+export function validateProviderPatch(patch, current) {
+  if (Object.hasOwn(patch, "provider")) {
+    if (!PROVIDER_IDS.includes(patch.provider)) {
+      return { ok: false, error: `未知 provider: ${String(patch.provider)}（可选 ${PROVIDER_IDS.join(" / ")}）` };
+    }
+  }
+  if (Object.hasOwn(patch, "customEndpointStyle") && !ENDPOINT_STYLES.includes(patch.customEndpointStyle)) {
+    return {
+      ok: false,
+      error: `未知端点风格: ${String(patch.customEndpointStyle)}（可选 ${ENDPOINT_STYLES.join(" / ")}）`,
+    };
+  }
+  // serverProvider 只认布尔（DEC-030）：生效判定全部是 `=== true` 的严格比较，
+  // 字符串 "true" 或 1 落盘后会得到「界面显示开、解析永远走本地」的半真状态，
+  // 而这里又是「使用免费模型」（原名「跟随服务端下发」）这条隐私开关的唯一写入口
+  // ——坏值必须拦在落盘前。
+  if (Object.hasOwn(patch, "serverProvider") && typeof patch.serverProvider !== "boolean") {
+    return {
+      ok: false,
+      error: `serverProvider 必须是布尔值: ${String(patch.serverProvider)}`,
+    };
+  }
+
+  for (const key of ["enabled", "guardEnabled"]) {
+    if (Object.hasOwn(patch, key) && typeof patch[key] !== "boolean") return { ok: false, error: `${key} 必须是布尔值` };
+  }
+  if (Object.hasOwn(patch, "pointAuthorize") && ![...POINT_MODES, "auto"].includes(patch.pointAuthorize)) {
+    return { ok: false, error: "无效的工具授权模式" };
+  }
+  if (Object.hasOwn(patch, "mode") && !["shadow", "enforce"].includes(patch.mode)) return { ok: false, error: "无效的守卫模式" };
+  if (Object.hasOwn(patch, "guardPolicyMode") && !["observe", "enforce"].includes(patch.guardPolicyMode)) {
+    return { ok: false, error: "无效的安全策略模式" };
+  }
+  if (Object.hasOwn(patch, "guardFallback") && !GUARD_FALLBACKS.includes(patch.guardFallback)) {
+    return { ok: false, error: "无效的自动审查 Fallback 策略" };
+  }
+  for (const key of ["guardFallbackProvider", "guardFallbackModel", "guardFallbackReasoningEffort"]) {
+    if (Object.hasOwn(patch, key) && (typeof patch[key] !== "string" || patch[key].length > 256 || /[\r\n\0]/.test(patch[key]))) {
+      return { ok: false, error: `${key} 必须是单行模型标识（最长 256 字符）` };
+    }
+  }
+  const merged = { ...current, ...patch };
+  const providerId = PROVIDER_IDS.includes(merged.provider) ? merged.provider : DEFAULT_PROVIDER;
+
+  // 自定义地址只要出现就必须合法——哪怕当前 provider 不是 custom，
+  // 否则用户先存一个错地址、再切过去，就得到一次静默失效。
+  if (typeof merged.customBaseUrl === "string" && merged.customBaseUrl.trim().length > 0) {
+    const checked = validateBaseUrl(merged.customBaseUrl);
+    if (!checked.ok) return { ok: false, error: `自定义 base URL 不合法：${checked.error}` };
+  } else if (providerId === "custom") {
+    return {
+      ok: false,
+      error: "选择 custom provider 时必须填写 base URL（形如 https://api.example.com/v1）",
+    };
+  }
+
+  // 内置预设的地址覆盖同样要校验：老字段 baseUrl 仍可指向自建兼容服务。
+  if (Object.hasOwn(patch, "baseUrl") && typeof patch.baseUrl === "string" && patch.baseUrl.trim().length > 0) {
+    const text = patch.baseUrl.trim();
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}`;
+    const checked = validateBaseUrl(withScheme);
+    if (!checked.ok) return { ok: false, error: `base URL 不合法：${checked.error}` };
+  }
+
+  // 请求头格式：只要写了内容就必须至少解析出一项，否则用户会以为头已生效。
+  if (Object.hasOwn(patch, "customHeaders") && typeof patch.customHeaders === "string") {
+    const raw = patch.customHeaders.trim();
+    if (raw.length > 0 && Object.keys(parseCustomHeaders(raw)).length === 0) {
+      return {
+        ok: false,
+        error: "自定义请求头格式不正确：应为 `名称: 值`，多项用分号分隔（如 `X-Tenant: a; X-Trace: b`）",
+      };
+    }
+  }
+
+  if (Object.hasOwn(patch, "keyStorage") && !["credentials", "config"].includes(patch.keyStorage)) {
+    return {
+      ok: false,
+      error: `未知密钥保存位置: ${String(patch.keyStorage)}（可选 credentials / config）`,
+    };
+  }
+
+  // 思考模式同样在落盘前拦下：写进 yml 再报错等于让用户带着坏配置重启，
+  // 而坏值只会得到一次静默降级。
+  if (Object.hasOwn(patch, "thinkMode") && !THINK_MODES.includes(patch.thinkMode)) {
+    return {
+      ok: false,
+      error: `未知思考模式: ${String(patch.thinkMode)}（可选 ${THINK_MODES.join(" / ")}）`,
+    };
+  }
+
+  // 人工审核比例（DEC-035）：四档之外的值一律拒在落盘前。
+  //
+  // 必须拦在这里：tolerance 的每一处判定都是「档位 id 精确匹配」，收到一个
+  // relax（少了 ed）之后所有分支都会退回默认档——用户看到「轻松」被打勾，
+  // 实际仍按默认在问，且没有任何报错。
+  if (Object.hasOwn(patch, "tolerance") && !TOLERANCE_LEVELS.includes(patch.tolerance)) {
+    return {
+      ok: false,
+      error: `未知的人工审核比例: ${String(patch.tolerance)}（可选 ${TOLERANCE_LEVELS.join(" / ")}）`,
+    };
+  }
+
+  // 变量名必须能当环境变量用，否则凭据永远读不到。
+  // 逐个预设取它自己的变量名覆盖字段，而不是写死三个名字——否则新增预设时
+  // 漏加这一项，用户填的变量名会被原样写进 yml，然后永远读不到 key
+  //（守卫是 fail-open 的，症状又是「配了没反应」）。
+  for (const preset of Object.values(PROVIDER_PRESETS)) {
+    const key = preset.keyEnvField;
+    if (!Object.hasOwn(patch, key)) continue;
+    const value = typeof patch[key] === "string" ? patch[key].trim() : "";
+    if (value.length === 0) continue;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+      return { ok: false, error: `${key} 不是合法的变量名：${value}` };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * 解析生效的 API key。优先级：
+ *
+ *   0. `options.memoryKey`——服务端随配置一起下发的 key（DEC-030，最高优先级）
+ *   1. 当前 provider 的显式 key（`apiKey` 或 `customApiKey`，适合临机覆盖）
+ *   2. `~/.dsh/.credentials.yaml` 的 `refs:` 段（**推荐**，与其他服务统一管理）
+ *   3. 环境变量（该 provider 自己的变量名，如 BAMBOO_API_KEY / TYPESAFE_API_KEY）
+ *
+ * 第 2 项是本插件的默认路径：key 和 DeepSeek / ModelScope 等放在一起，
+ * 由 DSH 统一托管，不必在插件目录里另存一份明文。
+ *
+ * 变量名由 provider 决定，因此「换 provider」也会自动换到它自己的凭据，
+ * 不会误用上一个 provider 的 key。
+ *
+ * 第 0 项为什么排最前：服务端下发是一整套配置（地址 + key），只取地址而
+ * 拿本地 key 去打，等于用另一个账号的凭据请求，几乎必然 401（见
+ * providers.js 的 resolveKeyFor）。memoryKey 只从内存来、绝不进 cfg——
+ * 这是「下发的 key 永不落盘」不变量的一部分（DEC-030）。
+ *
+ * @param cfg - 当前配置。
+ * @param provider - 可选的已解析 provider（避免重复解析）。
+ * @param options - 透传给 `resolveKeyFor`（memoryKey / env 等）；provider 缺省时
+ *   同时透给 `resolveProvider`，这样 `{ server }` 也能在这里生效。
+ * @returns 密钥，或 undefined。
+ */
+export function resolveKey(cfg, provider, options = {}) {
+  const resolved = provider ?? resolveProvider(cfg, options);
+  return resolveKeyFor(resolved, { credentialReader: readCredentialFromDsh, ...options });
+}
+
+/**
+ * 从 DSH 统一的 `~/.dsh/.credentials.yaml`（`refs:` 段）读取密钥。
+ *
+ * 这是本插件的首选来源：与 DeepSeek / ModelScope 等其他服务的 key 放在一起，
+ * 由 DSH 统一管理，不必在插件私有配置里存第二份明文。
+ *
+ * 刻意直读文件而不依赖 `credentials` 服务：该服务是可选注入的，且在插件
+ * 加载早期不一定就绪；直读只是一次同步 I/O，且失败即返回 undefined，
+ * 不会让补全路径抛错。
+ *
+ * @param ref - refs 段的键名（如 BAMBOO_API_KEY / TYPESAFE_API_KEY）。
+ * @returns 密钥，或 undefined（文件缺失 / 键不存在 / 值为空）。
+ */
+export function readCredentialFromDsh(ref) {
+  const name = typeof ref === "string" ? ref.trim() : "";
+  if (name.length === 0) return undefined;
+  // 读侧与写侧必须用**同一套**规则，否则会出现"存了却读不回"。
+  // 两边都交给 resolveDshHome()，候选只剩一个路径。
+  const path = join(resolveDshHome(), ".credentials.yaml");
+  const raw = readCredentialText(path);
+  return raw === undefined ? undefined : pickRefValue(raw, name);
+}
+
+/**
+ * 凭据文件文本缓存：只缓存「读到的文本」，不缓存「结论」。
+ *
+ * 为什么要有它：这个函数在**每一次决策**上都会被调用（resolveKeyFor 传进来
+ * 当 credentialReader，bamboonode 这类 provider 有 2 个候选变量名），而
+ * 过去每次调用都 readFileSync 整个文件、再从头解析一遍 refs。实测单次
+ * resolveKeyFor 因此要 16.6–33 µs，其中大头就是这些同步读盘。
+ *
+ * 为什么仍然「改了配置立刻生效」：每次调用都先 stat 一次，键是
+ * **(路径, mtimeMs, size)**。用户改文件 → mtime 或 size 变 → 自动重读。
+ * 这一点必须保住——「不重启就生效」是本插件的设计前提。
+ *
+ * 两个刻意的例外：
+ *
+ *   1. **不缓存失败**。文件不存在 / 读不了时不写缓存，下次仍然重新 stat
+ *      与读取：用户完全可能先开插件、后补 key，那条路径必须能通。
+ *   2. stat 本身失败时退回直接读（与旧行为一致），绝不让缓存层把
+ *      「能读」变成「读不到」。
+ */
+let credentialTextCache = { path: "", mtimeMs: 0, size: 0, text: undefined };
+
+/**
+ * 读取凭据文件文本（带 mtime+size 失效）。
+ *
+ * @param path - 凭据文件路径。
+ * @returns 文件文本；读不到时 undefined。
+ */
+function readCredentialText(path) {
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    // 文件不存在：清掉缓存（可能刚被删），保持「读不到」的语义。
+    credentialTextCache = { path: "", mtimeMs: 0, size: 0, text: undefined };
+    return undefined;
+  }
+  if (
+    credentialTextCache.path === path &&
+    credentialTextCache.mtimeMs === stat.mtimeMs &&
+    credentialTextCache.size === stat.size
+  ) {
+    return credentialTextCache.text;
+  }
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+  credentialTextCache = { path, mtimeMs: stat.mtimeMs, size: stat.size, text: raw };
+  return raw;
+}
+
+/**
+ * 读服务端下发的共享门禁令牌（DEC-030）。
+ *
+ * 顺序：环境变量 `DECISION_SERVER_CONFIG_TOKEN` 优先，其次
+ * `.credentials.yaml` 的同名 refs 键——与 API key 的既有取法一致，
+ * 管理员部署时既可以写进 launchd 环境，也可以放进统一凭据文件。
+ *
+ * 为什么要单独抽出来：这个令牌**不是**任何 provider 的 API key，它只是
+ * 领取配置的准入凭据；取回后原样交给 ServerConfigSource（非空才会附
+ * `x-provider-token` 头）。它同样只在内存里，绝不进 cfg / config.yml。
+ *
+ * @returns 令牌字符串；没有时为空串。
+ */
+function readServerToken() {
+  const fromEnv = typeof process.env.DECISION_SERVER_CONFIG_TOKEN === "string"
+    ? process.env.DECISION_SERVER_CONFIG_TOKEN.trim()
+    : "";
+  if (fromEnv.length > 0) return fromEnv;
+  const fromCredentials = readCredentialFromDsh("DECISION_SERVER_CONFIG_TOKEN");
+  return typeof fromCredentials === "string" ? fromCredentials.trim() : "";
+}
+
+/**
+ * DSH 统一凭据文件的路径。
+ *
+ * 优先 `$DSH_HOME/.credentials.yaml`，其次 `~/.dsh/.credentials.yaml`——
+ * 与读取侧保持同一套候选，避免"读得到但写不进去"。
+ *
+ * @returns 凭据文件绝对路径（不保证已存在）。
+ */
+export function credentialFilePath() {
+  // 读取侧（readCredentialFromDsh）与写入侧必须用**同一套**规则，否则会
+  // 出现"保存成功但读不回来"——写到了 A 文件、读的是 B 文件。
+  // 早先写入侧只认 ~/.dsh，就是在这一步把 key 写进真实家目录的。
+  // 现在两侧都从 resolveDshHome() 派生，规则只有一份。
+  return join(resolveDshHome(), ".credentials.yaml");
+}
+
+/**
+ * 把密钥写进 `~/.dsh/.credentials.yaml` 的 `refs:` 段。
+ *
+ * 为什么需要写：本插件允许把 key 托管在 DSH 的统一凭据文件里，而面板上的
+ * "粘贴 key → 保存"必须真的落盘。只读不写会让用户以为保存了，实际没存。
+ *
+ * 安全性上的取舍：
+ *
+ *   - 只改 `refs:` 段，`records:`（授权记录）与注释一律不动；
+ *   - 写入前先整份读出来做文本变换，再一次性覆盖，不做增量 append
+ *    （append 会在键已存在时产生重复键）；
+ *   - 权限固定 600，与 DSH 自己创建该文件时保持一致；
+ *   - 值为空字符串表示**删除**该键（用户清空即撤销）。
+ *
+ * @param ref - 键名。
+ * @param value - 密钥；传 "" 删除。
+ * @returns `{ ok: true }` 或 `{ ok: false, error }`。
+ */
+export async function writeCredentialToDsh(ref, value) {
+  const name = typeof ref === "string" ? ref.trim() : "";
+  if (name.length === 0) return { ok: false, error: "密钥变量名为空，无法保存" };
+  const { writeFile } = await import("node:fs/promises");
+  const path = credentialFilePath();
+  let raw = "";
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    // 文件不存在就新建一个最小骨架（version + refs）。
+    raw = "version: 1\nrefs:\n";
+  }
+  try {
+    const next = applyRefUpdates(raw, { [name]: typeof value === "string" ? value.trim() : "" });
+    await writeFile(path, next, { encoding: "utf8", mode: 0o600 });
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * 列出凭据文件里已配置的键名（不返回值）。
+ *
+ * @returns 键名数组；读不到文件时为空数组。
+ */
+export function listCredentialRefs() {
+  try {
+    return listRefNames(readFileSync(credentialFilePath(), "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+/** 插件更名后的数据目录名（`~/.dsh/<name>/`）。 */
+const DATA_DIR_NAME = "dsh-decision-engine";
+
+/**
+ * 当前配置文件名。
+ *
+ * 早期叫 `startlux.yml`——那时本插件只服务 startlux 一家。现在它是
+ * 「对任意决策服务的决策层」，名字里再挂某个服务商就会误导
+ * （用户会以为换 provider 要换文件），所以改叫 `config.yml`。
+ *
+ * **旧名字必须继续读**（见 `LEGACY_CONFIG_FILE_NAMES`）：改文件名本身
+ * 不影响任何配置语义，一旦处理不当，用户唯一感知到的就是「我的 key 没了」。
+ */
+const CONFIG_FILE_NAME = "config.yml";
+
+/**
+ * 历史配置文件名，按新→旧优先级排列。
+ *
+ * 只做**一次性迁移 + 回退读取**，绝不删除旧文件：配置里可能有明文 key，
+ * 删错一次就要用户重填。留在原地的成本只有 2KB。
+ */
+const LEGACY_CONFIG_FILE_NAMES = ["startlux.yml"];
+
+/**
+ * 读本插件自己的版本号。
+ *
+ * 为什么不 import package.json：`engines.node >= 20.3.0` 早于 import attributes
+ * 的稳定版本；用 `import ... with { type: "json" }` 在目标 Node 上会直接语法
+ * 报错，而不用 attributes 又会被当成 JS 解析。`package.json` 一定随包发布
+ * （在 files 白名单里），所以运行期按需同步读一次即可；读失败返回空串，
+ * 由 `normalizeVersion` 兜成 "unknown"——版本号缺失不能变成插件故障。
+ *
+ * @returns 版本号字符串，读不到时为空串。
+ */
+function readOwnPackage() {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 本插件自己的版本号。
+ *
+ * @returns 版本号字符串，读不到时为空串。
+ */
+function readOwnVersion() {
+  const pkg = readOwnPackage();
+  return typeof pkg.version === "string" ? pkg.version : "";
+}
+
+/**
+ * 本插件自己的标识（npm 包名）。上报体靠它自报家门，服务端按它分插件统计。
+ *
+ * 为什么从 package.json 读而不是写死：将来这个仓库若拆出子包、或有人 fork 后
+ * 改名，写死的常量会把两个不同的插件混成同一条统计线——而这类脏数据只有在
+ * 出现之后才会被发现，回溯成本极高。
+ *
+ * @returns 插件标识；读不到时为空串（上报会在 prepare 阶段被拦下）。
+ */
+function readOwnPluginId() {
+  const pkg = readOwnPackage();
+  return typeof pkg.name === "string" ? pkg.name : "";
+}
+
+/**
+ * 插件数据目录：`~/.dsh/dsh-decision-engine/`。
+ * 与插件源码分离——源码可以 clone 到任意位置，运行期数据只在 DSH 家目录下。
+ */
+function defaultTelemetryDir() {
+  // 家目录解析统一走 home-paths.js：优先级、空白值处理、~ 展开与
+  // 绝对路径规范化都与宿主 @deepseek-ai/dsh-home-paths 一致。
+  // 早期各处手写一份 `DSH_HOME || ~/.dsh`，既重复又漏了规范化。
+  return join(resolveDshHome(), DATA_DIR_NAME);
+}
+
+/**
+ * 旧版本（更名前）使用的配置目录。
+ *
+ * 本项目改过两次名：`dsh-startlux-guard` → `dsh-startlux-decision` →
+ * `dsh-decision-engine`。若只认新目录，用户升级后已保存的 API key 与决策点
+ * 开关会突然「消失」（表现为守卫静默不工作）。
+ *
+ * 处理方式是**一次性迁移 + 保留回退**：启动时把旧目录里的配置拷到新目录
+ *（见 `migrateLegacyData`），搬完之后只读写新目录；只有在搬迁失败
+ *（目录只读等）时才回退到旧位置，避免"因为搬不了就彻底不用配置"。
+ *
+ * **这里的目录名必须是历史真实名字，不能跟着更名一起改**——改了就等于
+ * 找不到老配置。顺序即优先级：越新的旧位置越靠前。
+ */
+function legacyConfigPaths() {
+  const base = resolveDshHome();
+  return [
+    // 上一代数据目录（本项目改名前的正式位置）
+    join(base, "dsh-startlux-decision", "startlux.yml"),
+    // 更名前的旧位置
+    join(base, "plugins", "dsh-startlux-guard", "startlux.yml"),
+    // 当前目录结构确立前的位置（配置曾与源码同层）
+    join(base, "plugins", "dsh-startlux-decision", "startlux.yml"),
+  ];
+}
+
+/**
+ * 把旧数据目录里的数据一次性搬到新目录。
+ *
+ * 为什么是「拷贝」而不是「改名」：
+ *
+ *   1. 改名跨卷会失败，而 `~/.dsh` 与其它位置未必同卷；
+ *   2. 旧文件留着没有代价（配置只有 2KB），搬丢了却要用户重填 key；
+ *   3. 迁移失败必须能安静降级——所有异常都吞掉，由调用方回退。
+ *
+ * 搬两类东西：配置（含本次 `startlux.yml` → `config.yml` 的改名）与
+ * `telemetry.jsonl`。只搬这些已知文件、不递归整个目录：里面可能有用户
+ * 自己放的笔记或备份，插件无权擅自处理。
+ *
+ * @returns 是否真的搬了东西（供启动日志说明）。
+ */
+function migrateLegacyData() {
+  const targetDir = defaultTelemetryDir();
+  const targetConfig = join(targetDir, CONFIG_FILE_NAME);
+  try {
+    // 新目录已有配置 → 之前迁移过，或用户主动建过。一律不再动它。
+    if (existsSync(targetConfig)) return false;
+
+    // 候选来源按「越新越靠前」排列：
+    //   1) 新目录里的旧文件名（本次改名的迁移来源，最常见）
+    //   2) 历史数据目录里的旧文件名
+    const candidates = [
+      ...LEGACY_CONFIG_FILE_NAMES.map((name) => join(targetDir, name)),
+      ...legacyConfigPaths(),
+    ];
+    const legacyConfig = candidates.find((path) => existsSync(path));
+    if (legacyConfig === undefined) return false;
+
+    // 同目录改名时直接 rename：保留 mtime 之外的一切，且不会因为
+    // 「拷贝 + 旧文件仍在」造成两份配置并存（并存会导致读哪份说不清）。
+    // 跨目录/跨卷时 rename 会抛错，回退到拷贝。
+    mkdirSync(targetDir, { recursive: true });
+    if (join(legacyConfig, "..") === targetDir) {
+      try {
+        renameSync(legacyConfig, targetConfig);
+      } catch {
+        copyFileSync(legacyConfig, targetConfig);
+      }
+    } else {
+      copyFileSync(legacyConfig, targetConfig);
+    }
+    try {
+      // 配置里可能有明文 key，权限保持 600。
+      chmodSync(targetConfig, 0o600);
+    } catch {
+      /* 改不了权限不算失败，文件已经在了 */
+    }
+    // 遥测一起搬：否则「按点分账」在新目录里从零开始，看起来像数据丢了。
+    const legacyTelemetry = join(legacyConfig, "..", "telemetry.jsonl");
+    const targetTelemetry = join(targetDir, "telemetry.jsonl");
+    if (existsSync(legacyTelemetry) && !existsSync(targetTelemetry)) {
+      try {
+        copyFileSync(legacyTelemetry, targetTelemetry);
+      } catch {
+        /* 遥测是旁路数据，搬不动不影响决策路径 */
+      }
+    }
+    return true;
+  } catch {
+    // 目录不可写等情况：保持回退行为，绝不因此让插件失效。
+    return false;
+  }
+}
+
+/**
+ * 在多个候选位置中挑出第一个存在的配置文件。
+ *
+ * 顺序：新文件名 → 新目录里的旧文件名 → 历史目录里的旧文件名。
+ * 后两者只在迁移没成功（目录只读等）时才可能命中，此时继续读写旧文件，
+ * 好过「因为搬不动就彻底不用配置」。
+ *
+ * @returns 配置文件绝对路径（都不存在时返回新路径，供首次写入使用）。
+ */
+function resolveConfigPath() {
+  const targetDir = defaultTelemetryDir();
+  const preferred = join(targetDir, CONFIG_FILE_NAME);
+  try {
+    if (existsSync(preferred)) return preferred;
+    // 迁移失败但旧文件名还在新目录里：继续用它，避免配置凭空消失。
+    for (const name of LEGACY_CONFIG_FILE_NAMES) {
+      const stale = join(targetDir, name);
+      if (existsSync(stale)) return stale;
+    }
+    for (const legacy of legacyConfigPaths()) {
+      if (existsSync(legacy)) return legacy;
+    }
+  } catch {
+    /* 探测失败就用首选路径 */
+  }
+  return preferred;
+}
+
+/**
+ * 遥测目录：正常情况下就是新目录（迁移已把历史记录搬过来）。
+ *
+ * 仅当新目录写不进去、而旧目录已有历史记录时才回退到旧目录，
+ * 避免"写不了新地方，又把旧记录弄丢"。
+ */
+function resolveTelemetryDir() {
+  const preferred = defaultTelemetryDir();
+  try {
+    if (existsSync(join(preferred, "telemetry.jsonl"))) return preferred;
+    // 新目录里还没有记录：只有「迁移失败」才继续用旧目录，
+    // 否则应当写进新目录（迁移成功但还没有新记录时属于这种情形）。
+    // 新旧两个文件名都要认：迁移失败时配置仍留在旧文件名下。
+    if (existsSync(join(preferred, CONFIG_FILE_NAME))) return preferred;
+    for (const name of LEGACY_CONFIG_FILE_NAMES) {
+      if (existsSync(join(preferred, name))) return preferred;
+    }
+    for (const legacy of legacyConfigPaths()) {
+      const dir = join(legacy, "..");
+      if (existsSync(join(dir, "telemetry.jsonl"))) return dir;
+    }
+  } catch {
+    /* 探测失败就用首选路径 */
+  }
+  return preferred;
+}
+
+/**
+ * 已经确认存在的遥测目录。
+ *
+ * 为什么要有它：`recordTelemetry` 在每一次决策上都会被 await 一次，而
+ * `mkdir(dir, {recursive:true})` 每次都是一次系统调用——目录建好之后它
+ * 什么也没做，却照样花了时间。这里记住「已经建好的目录」，后续追加直接写。
+ *
+ * 为什么要配一次重试：缓存可能与真实文件系统脱节（用户删了数据目录、
+ * 或测试里把临时目录清掉重建）。追加失败时**忘掉这次记忆**并重试一次，
+ * 语义就退回旧行为：该建的目录照样会建出来。
+ */
+const readyTelemetryDirs = new Set();
+
+/** 追加一条 JSONL 遥测。永远不抛：遥测失败不能影响决策路径。 */
+async function recordTelemetry(dir, entry) {
+  const line = `${JSON.stringify(entry)}\n`;
+  const file = join(dir, "telemetry.jsonl");
+  try {
+    if (!readyTelemetryDirs.has(dir)) {
+      await mkdir(dir, { recursive: true });
+      readyTelemetryDirs.add(dir);
+    }
+    await appendFile(file, line, "utf8");
+    return true;
+  } catch {
+    // 目录可能刚被删掉：忘掉记忆、重建一次再试。仍失败就放弃（遥测是旁路）。
+    readyTelemetryDirs.delete(dir);
+    try {
+      await mkdir(dir, { recursive: true });
+      readyTelemetryDirs.add(dir);
+      await appendFile(file, line, "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** 截断到指定长度，保留头尾（中段省略），避免 state 过大浪费 token。 */
+function headTail(text, headChars, tailChars) {
+  const value = typeof text === "string" ? text : String(text ?? "");
+  if (value.length <= headChars + tailChars) return value;
+  const tail = tailChars > 0 ? value.slice(-tailChars) : "";
+  return `${value.slice(0, headChars)}\n...[省略 ${value.length - headChars - tail.length} 字符]...\n${tail}`;
+}
+
+/** 把工具参数压成一段紧凑预览。 */
+function previewArguments(args, headChars, tailChars) {
+  let text;
+  try {
+    text = JSON.stringify(args ?? {});
+  } catch {
+    text = String(args);
+  }
+  return headTail(text, headChars, tailChars);
+}
+
+/** 从会话消息里摘出最近若干条对话，压缩为单行摘要。 */
+function digestRecent(session, count, chars) {
+  if (count <= 0) return "";
+  let messages;
+  try {
+    messages = session.deriveMessages?.() ?? [];
+  } catch {
+    return "";
+  }
+  const tail = messages.slice(-count);
+  const lines = [];
+  for (const message of tail) {
+    const role = message?.role ?? "unknown";
+    let text = "";
+    const content = message?.content;
+    if (typeof content === "string") text = content;
+    else if (Array.isArray(content)) {
+      text = content
+        .map((block) => (block?.type === "text" && typeof block.text === "string" ? block.text : ""))
+        .filter((part) => part.length > 0)
+        .join(" ");
+    }
+    if (text.length > 0) lines.push(`${role}: ${headTail(text.trim(), chars, 0)}`);
+  }
+  return lines.join("\n");
+}
+
+/** 守卫的四问：风险等级、不可逆性、任务相关性、注入嫌疑。 */
+function guardQuestions() {
+  return safetyGuardQuestions();
+}
+
+function extractGuardAnswers(answers) {
+  return strictGuardAnswers(answers);
+}
+
+/**
+ * ask 裁决的两张文案表：审计原文（DEC-019）与人类标题（DEC-041）。
+ *
+ * 为什么 `reason` 之外还要 `displayReason`：`reason` 是**审计与遥测的原文**，
+ * 一直保持中文——宿主把它写进 `approval/asked` 审计事件、本插件把它写进遥测的
+ * `detail`，改它会让历史记录的口径漂移。而宿主审批卡渲染的是
+ * `displayReason`（优先）而非 `reason`：`@deepseek-ai/dsh-client-ui-approval`
+ * 的 ApprovalPanel 取 `displayReason === undefined ? reason : resolveReason(displayReason)`，
+ * 再用 `ctx.locale.resolveText()` 按当前宿主语言解析。没有它，标题就永远
+ * 回退到中文 `reason`——宿主界面是英文时就成了「英文卡壳 + 中文标题」。
+ *
+ * 映射必须**中英成对**：`resolveText` 的契约要求带 `en` 回退值。
+ *
+ * DEC-041 起拆成两张表：`reason` 与 `displayReason.zh` **不再逐字相同**。
+ * 原先把整条 reason（含 `risk=` / `p=` / `irrev=` / `task=` / `inj=` 遥测字段
+ * 名与裸小数）直接当标题，用户反馈「审批内容对人不具可读性」——那些是给
+ * 事后核对用的审计口径，不是给人看的一行中文。于是：
+ *
+ *   - `GUARD_ASK_REASON`：**只**进 `reason`，逐字保持改动前的样子（历史口径不漂移）；
+ *   - `GUARD_ASK_TITLE`：**只**进 `displayReason`，日常语言、不含字段名与小数。
+ */
+const GUARD_ASK_REASON = {
+  injection: "工具输入疑似提示注入，升级人工确认",
+  high: "高风险调用，需人工确认",
+  medium: "中风险调用，需人工确认",
+  lowIrreversible: "风险低但可能不可逆且与任务相关性低，需人工确认",
+};
+
+/** 审批卡标题正文（DEC-041）：给人读的一句话，不含遥测字段名与小数。 */
+const GUARD_ASK_TITLE = {
+  injection: {
+    zh: "输入里疑似藏着给 AI 的指令（提示注入）",
+    en: "the input looks like it hides instructions aimed at an AI (prompt injection)",
+  },
+  high: {
+    zh: "高风险，可能删除内容、外传数据或越出工作区",
+    en: "high risk — may delete content, leak data, or escape the workspace",
+  },
+  medium: {
+    zh: "中风险，会改动可恢复的状态",
+    en: "medium risk — modifies recoverable state",
+  },
+  lowIrreversible: {
+    zh: "风险低，但可能改不回来，也不像在服务当前任务",
+    en: "low risk — possibly irreversible, and not serving the current task",
+  },
+};
+
+/** 标题里路径最多显示多少个字符，超出加省略号。 */
+const TITLE_PATH_MAX = 60;
+
+/** 把一条路径压到标题能放下的长度。 */
+function shortPath(path) {
+  return path.length > TITLE_PATH_MAX ? `${path.slice(0, TITLE_PATH_MAX - 1)}…` : path;
+}
+
+/**
+ * 从工具参数里取一个用于标题的路径。
+ *
+ * `write` / `edit` / `read` 的参数是 `file_path`；`apply_patch` **没有**路径
+ * 字段——它的路径藏在 patch 文本里（`*** Update File: …` / `*** Add File: …` /
+ * `*** Delete File: …`，宿主 dsh-tool-fs 的 schema 已核对）。取不到就返回
+ * undefined，标题里省掉路径那一节，绝不编造。
+ *
+ * @param tool - 工具名。
+ * @param args - 该次工具调用的参数对象。
+ * @returns 路径字符串或 undefined。
+ */
+function titlePathOf(tool, args) {
+  if (args === null || typeof args !== "object") return undefined;
+  const direct = args.file_path ?? args.path ?? args.file;
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  if (tool === "apply_patch" && typeof args.input === "string") {
+    const match = args.input.match(/^\*\*\* (?:Update|Add|Delete|Move) File: (.+)$/m);
+    if (match !== null && match[1].trim().length > 0) return match[1].trim();
+  }
+  return undefined;
+}
+
+/** 标题里工具名最多显示多少个字符，超出加省略号。 */
+const TITLE_TOOL_MAX = 40;
+
+/**
+ * 把工具名压成标题能安全承载的形式。
+ *
+ * 工具名来自宿主注册表，正常情况下是短的标识符；但标题是**一行文本**，
+ * 一个带换行的名字会把标题劈成两行、一个超长的名字会把「为什么问」那节
+ * 挤到看不见的地方。这里只做纯展示层的收敛（去控制字符 + 截断），不影响
+ * 任何裁决逻辑。
+ *
+ * @param name - 原始工具名。
+ * @returns 可安全放进标题的工具名。
+ */
+function titleToolName(name) {
+  // 控制字符（含换行/制表）在 CSS 可能被折叠或撑破布局，统一换成空格。
+  const flat = name.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  return flat.length > TITLE_TOOL_MAX ? `${flat.slice(0, TITLE_TOOL_MAX - 1)}…` : flat;
+}
+
+/**
+ * 标题里的「这次是什么操作」短句；不需要就不给（标题里省掉这一节）。
+ *
+ * 为什么需要它（DEC-041）：宿主审批卡的正文 detail 行**只显示 bash 的
+ * `args.command`**，`write` / `edit` / `apply_patch` 那边是空白——对写文件这类
+ * 操作，整张卡除了我们的标题就只剩按钮。所以标题得自己点名「要改哪个文件」，
+ * 否则一行「中风险」等于没说。
+ *
+ * `bash` / `shell` 一律返回 undefined：命令原文已经由宿主那行 detail 显示在
+ * 标题正下方，标题再写一句「命令行操作」纯属重复。
+ *
+ * @param tool - 工具名（如 `bash` / `write` / `edit`）。
+ * @param args - 该次工具调用的参数对象（已是对象，不需要再 parse）。
+ * @returns `{zh, en}` 短句，或 undefined。
+ */
+function toolHint(tool, args) {
+  const name = typeof tool === "string" ? titleToolName(tool) : "";
+  if (name.length === 0) return undefined;
+  // bash 的命令由宿主 detail 行负责，标题不加重复的一句。
+  if (name === "bash" || name === "shell") return undefined;
+  if (name === "write" || name === "edit" || name === "apply_patch") {
+    const path = titlePathOf(name, args);
+    return path === undefined
+      ? { zh: "修改文件", en: "modifying a file" }
+      : { zh: `修改文件 ${shortPath(path)}`, en: `modifying ${shortPath(path)}` };
+  }
+  if (name === "read") {
+    const path = titlePathOf(name, args);
+    return path === undefined
+      ? { zh: "读取文件", en: "reading a file" }
+      : { zh: `读取文件 ${shortPath(path)}`, en: `reading ${shortPath(path)}` };
+  }
+  return { zh: `使用 ${name} 工具`, en: `the ${name} tool` };
+}
+
+/**
+ * 把 toolHint 与标题正文拼成一行；两语言同一结构。
+ *
+ * @param titleZh - 中文正文（不含插件前缀）。
+ * @param titleEn - 英文正文（不含插件前缀）。
+ * @param context - `{tool, args}`；缺省时省掉工具那一节。
+ * @param options.askWords - 是否在末尾加「需要你确认」；tolerance 的标题自带
+ *   这个语义，传 false 以免变成「确认……需要你确认」的重复。
+ * @returns `{zh, en}`。
+ */
+function askTitle(titleZh, titleEn, context, { askWords = true } = {}) {
+  const hint = toolHint(context?.tool, context?.args);
+  const sep = " · ";
+  const tailZh = askWords ? `${sep}需要你确认` : "";
+  const tailEn = askWords ? `${sep}needs your confirmation` : "";
+  return {
+    zh: `decision-engine：${hint === undefined ? "" : hint.zh + sep}${titleZh}${tailZh}`,
+    en: `decision-engine: ${hint === undefined ? "" : hint.en + sep}${titleEn}${tailEn}`,
+  };
+}
+
+/**
+ * 组装一条 ask 裁决：`reason` 保持审计原文（DEC-019，逐字不变），
+ * `displayReason` 给出中英成对、给人读的审批卡标题（DEC-041）。
+ *
+ * @param key - `GUARD_ASK_REASON` / `GUARD_ASK_TITLE` 的键。
+ * @param evidence - 四个概率的可读摘要；**只**进 `reason`，两种语言都不再展示。
+ * @param context - `{tool, args}`，可选；缺省时标题省掉工具那一节。
+ * @returns `{kind:'ask', reason, displayReason}`。
+ */
+function askOutcome(key, evidence, context) {
+  const reason = `decision-engine: ${GUARD_ASK_REASON[key]}（${evidence}）`;
+  const title = GUARD_ASK_TITLE[key];
+  return {
+    kind: "ask",
+    reason,
+    displayReason: askTitle(title.zh, title.en, context),
+  };
+}
+
+/**
+ * 「人工审核比例」把一次默认放行的调用升级成 ask 时的文案（DEC-035）。
+ *
+ * 与 `askOutcome` 分开是因为语义不同：那四条文案描述**模型发现了什么**，
+ * 这一条描述**用户选的档位要求问**。混用会让审计记录说谎——「高风险调用」
+ * 这个理由出现在一条模型判定为低风险的记录上，事后核对时无法解释。
+ *
+ * DEC-041 只改标题：`reason` 仍逐字保持原样（含 `severity=` 与阈值小数），
+ * 标题则只点名用户选的档位，不出现字段名与 0.xxx 数字。
+ *
+ * @param severity - 本次严重度（0–1）。
+ * @param cutoff - 该档的严重度阈值；未校准好时为 null。
+ * @param context - `{tool, args, level}`，可选；`level` 是档位 id，用于取档位名。
+ * @returns `{kind:'ask', reason, displayReason}`，中英成对（DEC-019）。
+ */
+function askOutcomeForSeverity(severity, cutoff, context) {
+  const evidence =
+    `severity=${severity.toFixed(3)} ` +
+    `(档位阈值 ${cutoff === null ? "未校准" : cutoff.toFixed(3)})`;
+  const reason = `decision-engine: 按「人工审核比例」设定，这次调用需人工确认（${evidence}）`;
+  // 档位名从预设表取；`tolerancePreset()` 对未知值退回默认档且会做档位合法性
+  // 检查，比直接 `TOLERANCE_PRESETS[level]` 稳：后者在 level 为 `__proto__`
+  // 这类键时会把原型链上的东西当档位读出来。不传第三参时同样回落默认档。
+  const preset = tolerancePreset(context?.level);
+  const label = preset.label;
+  const labelEn = preset.labelEn;
+  return {
+    kind: "ask",
+    reason,
+    displayReason: askTitle(
+      `你选的「${label}」档要求这次也确认一下`,
+      `your "${labelEn}" review setting asks to confirm this call`,
+      context,
+      { askWords: false },
+    ),
+  };
+}
+
+/**
+ * 四问 → 处置。纯函数，便于单测与校准。阈值全部来自配置。
+ *
+ * 第三参 `context` 是可选的（DEC-041）：它只影响审批卡标题，不影响任何
+ * 阈值判断。不传时标题省掉「这次是什么操作」那一节——现有调用方与测试
+ * 因此不必改就能继续跑。
+ *
+ * @param answers - 已校验的答案。
+ * @param cfg - 当前配置。
+ * @param context - `{tool, args}`：本次工具名与参数对象；参数已是对象，
+ *   不需要再 parse 字符串。
+ * @returns `{kind}`，kind 为 delegate / ask / deny；ask 另带中英成对的
+ *   `displayReason`（DEC-019；DEC-041 起它**不再等于** `reason`），
+ *   调用方须原样转交给宿主。
+ */
+export function decideGuardLegacy(answers, cfg, context = {}) {
+  const evidence =
+    `risk=${answers.risk.choice} p=${answers.risk.confidence.toFixed(2)} ` +
+    `irrev=${answers.irreversibleP.toFixed(2)} task=${answers.taskP.toFixed(2)} ` +
+    `inj=${answers.injectionP.toFixed(2)}`;
+
+  if (answers.injectionP >= cfg.guardInjectionAskThreshold) {
+    return askOutcome("injection", evidence, context);
+  }
+  if (answers.risk.choice === "high") {
+    if (
+      answers.risk.confidence >= cfg.guardDenyConfidence &&
+      answers.irreversibleP >= cfg.guardIrreversibleDenyFloor
+    ) {
+      return { kind: "deny", reason: `decision-engine: 高风险且不可逆，已拦截（${evidence}）` };
+    }
+    return askOutcome("high", evidence, context);
+  }
+  if (answers.risk.choice === "medium") {
+    if (answers.risk.confidence < cfg.guardConfidenceMin) return { kind: "delegate" };
+    return askOutcome("medium", evidence, context);
+  }
+  // 实测校准（DEC-008，telemetry 1647 条回放）：决策模型对「执行后是否不可逆」
+  // 的输出基线并不接近 0——普通 bash 命令（ls/git status 等）普遍落在 0.2–0.4，
+  // 而这批调用的 risk 判定本身就是 low。只看 irreversibleP 单一分数，等于把
+  // 「模型对 bash 的惯性谨慎」当成风险本身，80% 的 ask 从这条分支漏出来。
+  //
+  // 修复：叠加任务相关性否决。ask 组样本里 taskP 全部 ≥0.5（模型其实确信
+  // 这些调用服务于任务），因此「任务相关性高」时模型自己的两问已经互相矛盾
+  //（低风险 + 服务于任务 + 唯一顾虑是有点不可逆），此时放行符合本插件的定位——
+  // 只有「可能不可逆且模型自己都不认为它服务于当前任务」才值得升级人工确认。
+  // 回放数据：95 次 ask → 38 次（-60%），剩余样本全部是 irrev 高且 task 低的
+  // 真正可疑调用；deny 与高风险/中风险/注入各分支语义不变。
+  if (
+    answers.irreversibleP >= cfg.guardIrreversibleCeiling &&
+    answers.taskP < cfg.guardTaskRelevanceFloor
+  ) {
+    return askOutcome("lowIrreversible", evidence, context);
+  }
+  return { kind: "delegate" };
+}
+
+export function decideGuard(answers, cfg, context = {}) {
+  const advisory = { ...answers, status: answers?.status ?? "valid" };
+  const decision = decideModelAdvisory(advisory, cfg);
+  if (decision.kind !== "ask") return decision;
+  const numeric = (value) => Number.isFinite(value) ? value.toFixed(2) : "unknown";
+  const evidence = `risk=${answers?.risk?.choice ?? "unknown"} p=${numeric(answers?.risk?.confidence)} irrev=${numeric(answers?.irreversibleP)} task=${numeric(answers?.taskP)} inj=${numeric(answers?.injectionP)}`;
+  const branch = answers?.injectionP >= cfg.guardInjectionAskThreshold ? "injection"
+    : answers?.risk?.choice === "high" ? "high"
+    : answers?.risk?.choice === "medium" ? "medium" : "lowIrreversible";
+  return askOutcome(branch, evidence, context);
+}
+
+/** 小型 LRU：命中即完全跳过网络，是省 token 的主力。 */
+/**
+ * StartLux 决策客户端。
+ *
+ * endpoint / model / key 三者**每次请求都从 cfg 现读**，因此改 Base URL、
+ * 换模型、换 key 都对下一次决策立即生效——这正是旧插件缺失的能力。
+ *
+ * @param options - 运行时依赖。
+ */
+class StartluxClient {
+  constructor(options) {
+    this.getConfig = options.getConfig;
+    this.logger = options.logger;
+    this.fetchFn = options.fetchFn ?? globalThis.fetch;
+    // 遥测目录由 apply() 注入：它要兼顾「更名前的旧目录里已有历史记录」，
+    // 这个判断需要文件系统探测，不适合放进纯客户端。
+    this.telemetryDir = options.telemetryDir;
+    /**
+     * 统计存储：按 provider × model 记 token 与耗时。
+     *
+     * 与遥测分开存（见 lib/stats-store.js 的说明）：遥测缺 provider、
+     * output token 与基线，满足不了统计需求。
+     *
+     * 可缺省：单元测试里不注入也能跑（此时不记统计）。
+     */
+    this.statsStore = options.statsStore ?? null;
+    // 缓存也传「取值函数」而不是快照：与 endpoint/model/key 同一套
+    // 原则——配置改了立刻对下一次生效，不要求重启。
+    this.cache = new DecisionCache(
+      () => this.getConfig().cacheSize,
+      () => this.getConfig().cacheTtlMs,
+    );
+    this.failures = 0;
+    this.cooldownUntil = 0;
+    /**
+     * 半开冷却（half-open）的两个游标。
+     *
+     * `cooldownNextProbe` 是「冷却期内下一个允许试探的时刻」：冷却期间只有过了
+     * 这个时刻的那**一次**请求被放行，其余照旧快速降级——否则冷却就形同虚设。
+     * `cooldownStreak` 是「连续第几轮进入冷却」，供指数退避使用，只在成功时归零。
+     */
+    this.cooldownNextProbe = 0;
+    this.cooldownStreak = 0;
+    this.lastDegrade = undefined;
+    this.stats = { requests: 0, cached: 0, degraded: 0, ok: 0, lastStatus: undefined };
+    /** 按决策点分账：不分开统计就无法判断哪个点值得留。 */
+    this.byPoint = new Map();
+    /**
+     * 记住「哪条路径真的能用」。
+     *
+     * 路径后缀由服务商决定（实测 SiliconFlow 只通 /systemone），而守卫是
+     * fail-open 的——路径踩空等于静默失效。404 时换另一条再试，并记住胜出的
+     * 那条，下次直接打它，省掉热路径上多余的一次往返。
+     */
+    this.endpointMemory = new EndpointMemory();
+    /**
+     * 服务端下发（DEC-030）：由 apply() 注入的两个回调。
+     *
+     *   - `getServerOverride()`：返回「此刻生效」的下发值
+     *     `{ baseUrl, model, endpointStyle, key, … }`，未开启或未取到返回 undefined；
+     *   - `refreshServer()`：开着而值不可用时后台补一发（不 await、绝不抛）。
+     *
+     * 为什么是注入而不是客户端自建：网络与内存缓存归 apply() 作用域里那个
+     * ServerConfigSource 实例（宿主重载插件即随之销毁，key 不留存），客户端
+     * 只消费「现在生效」的结果。缺省视为「没有服务端下发」——直接 `new` 的
+     * 既有调用方（含单测）行为逐字不变。
+     */
+    this.getServerOverride = typeof options.getServerOverride === "function" ? options.getServerOverride : undefined;
+    this.refreshServer = typeof options.refreshServer === "function" ? options.refreshServer : undefined;
+  }
+
+  /** 取（或建）某个决策点的计数器。 */
+  pointCounter(point) {
+    const id = point ?? "unknown";
+    let entry = this.byPoint.get(id);
+    if (entry === undefined) {
+      entry = { requests: 0, cached: 0, degraded: 0, ok: 0, tokens: 0, latencySum: 0, latencyMax: 0 };
+      this.byPoint.set(id, entry);
+    }
+    return entry;
+  }
+
+  /**
+   * 失败累计到阈值后进入冷却，避免对着故障端点反复烧钱。
+   *
+   * 冷却时长按**连续进入冷却的轮次**指数退避（见 resilience.js 的
+   * `nextCooldownMs`）：一次瞬时抖动不该换来一整分钟的静默。上限取
+   * `10 × cooldownMs`，既让连续故障时等待真的变长，又不会长到用户以为插件坏了。
+   *
+   * @param options.duringCooldown - 这次失败发生在**冷却期的试探**里：立即按指数
+   *   退避重新封锁，不等失败计数再攒满一轮。冷却开始时 `failures` 刚被归零，
+   *   若还要攒满 `failureThreshold` 次才延长，试探失败就只是把冷却**原地续期**
+   *   （或干脆什么都没发生），半开冷却退化成「每 10 秒白试一次」。
+   */
+  noteFailure({ duringCooldown = false } = {}) {
+    this.failures += 1;
+    if (duringCooldown || this.failures >= this.getConfig().failureThreshold) {
+      const cfg = this.getConfig();
+      // 直接 `new` 的调用方（含单测）可能只给了一部分配置：缺项回落到 DEFAULTS。
+      // 不兜底的话 `Date.now() + undefined` 会得到 NaN，而 `now < NaN` 恒为 false
+      // ——冷却游标一旦是 NaN，半开判定就会静默失效（每次请求都当成试探放行）。
+      const baseCooldownMs = Number(cfg.cooldownMs ?? DEFAULTS.cooldownMs);
+      const probeGapMs = Number(cfg.cooldownProbeMs ?? DEFAULTS.cooldownProbeMs);
+      // streak 从 1 起：本轮是第几次进入冷却。首轮正好等于 cooldownMs（与
+      // 改动前逐字一致），之后逐轮翻倍——这正是「指数退避」的语义。
+      this.cooldownStreak += 1;
+      const waitMs = nextCooldownMs({
+        baseCooldownMs,
+        streak: this.cooldownStreak,
+        maxCooldownMs: baseCooldownMs * 10,
+      });
+      this.cooldownUntil = Date.now() + waitMs;
+      // 下一个试探窗口从现在开始算：刚进冷却就立刻试探等于没有冷却。
+      this.cooldownNextProbe = Date.now() + (Number.isFinite(probeGapMs) && probeGapMs > 0 ? probeGapMs : DEFAULTS.cooldownProbeMs);
+      this.failures = 0;
+      this.logger?.warn?.(`dsh-decision-engine: 连续失败，进入 ${waitMs}ms 冷却`);
+    }
+  }
+
+  /**
+   * 成功：清空失败计数与冷却状态。
+   *
+   * 冷却里的一次试探成功必须**彻底**解除冷却（`cooldownUntil = 0`）并归零
+   * streak——否则下一轮失败会接着上一轮翻倍，服务端明明已经恢复，等待却越来越长。
+   */
+  noteSuccess() {
+    this.failures = 0;
+    this.cooldownUntil = 0;
+    this.cooldownStreak = 0;
+    this.cooldownNextProbe = 0;
+  }
+
+  /**
+   * 发起一次决策。
+   * @param call - 问题、state 与取消信号。
+   * @returns 决策结果，或 `null` 表示降级（调用方应放行）。
+   */
+  async classify(call) {
+    const cfg = this.getConfig();
+    const started = Date.now();
+    const point = call.point ?? "authorize";
+    const counter = this.pointCounter(point);
+
+    const degrade = async (reason, extra) => {
+      this.stats.degraded += 1;
+      counter.degraded += 1;
+      const previous = this.lastDegrade;
+      this.lastDegrade = { reason, at: Date.now() };
+      // 同一原因的降级 60s 内只记一条，避免日志刷屏。
+      // 即便不写遥测，也要把降级原因回传给调用方——否则「标记」列只能写
+      // 一个笼统的 degraded，用户扫表格时完全看不出这次到底是 404 还是 401。
+      if (previous && previous.reason === reason && Date.now() - previous.at < 60000) return { degraded: reason, ...(extra && typeof extra.status === "number" ? { status: extra.status } : {}) };
+      // 即便 60s 内只记一条遥测，也要把降级原因与状态码回传，否则「标记」列只能写 degraded。
+      // 降级**也要记统计**：这次决策确实消耗了时间（可能还有 token），
+      // 而它在裁决分账里属于「未裁决」——两套口径互不排斥。
+      //
+      // 这里记的消耗是「到降级为止」的量：provider / model 在解析失败时
+      // 可能还不知道（invalid-base-url / no-key），此时只能用 unknown，
+      // 不能猜一个服务商名——猜错会让「按 provider 对比」出现一家不存在的。
+      const degradedProvider = provider?.id ?? "unknown";
+      // 记录降级时实际会用的模型：配置里留空则回落到该 provider 的默认模型
+      // （bamboonode 不强制带 model，留空就是空串，不能让它变成 unknown
+      // 而在统计表里凭空多出一行「bamboonode / unknown」的零数据）。这里绝不
+      // 猜 provider，只补 model——provider 在降级时已经解析出来了（id 已知）。
+      const degradedModel = provider?.model || provider?.defaultModel || "";
+      this.recordDecision({
+        facts: {
+          point,
+          provider: degradedProvider,
+          model: degradedModel,
+          // 降级记录也要带模式：它同样可能来自观察模式，虽然降级没有
+          // 裁决、基线也没什么可归因的，但模式是这次决策的事实。
+          mode: call.pointMode ?? "unknown",
+          inputTokens: 0,
+          outputTokens: 0,
+          durationMs: Date.now() - started,
+          inputSource: "unknown",
+          outputSource: "unknown",
+        },
+        action: "degraded",
+        detail: reason,
+        degraded: true,
+      });
+      await recordTelemetry(this.telemetryDir ?? defaultTelemetryDir(), {
+        ts: new Date().toISOString(),
+        point,
+        tag: call.tag,
+        mode: call.mode,
+        ...(call.tool === undefined ? {} : { tool: call.tool }),
+        // 遥测必须自带 provider 与 model：遥测是**回填历史统计的唯一来源**
+        // （见 lib/stats-store.js 的 backfillFromTelemetry）。缺了它们，回填
+        // 只能把记录归到 "unknown"，界面上就会出现「未知（历史）」整块——
+        // 降级记录尤其惨：它们没有 model（没拿到任何答案），于是连按模型名
+        // 反推都做不到，只能整块记成 unknown / unknown。
+        //
+        // provider 在降级时已经解析出来了（id 已知），model 用的是「本来会
+        // 用」的那个——失败也要归因到发起失败的那个服务商，否则「按 provider
+        // 对比」会把失败藏起来。
+        ...(degradedProvider === "unknown" ? {} : { provider: degradedProvider }),
+        ...(degradedModel.length > 0 ? { model: degradedModel } : {}),
+        action: "degraded",
+        detail: reason,
+        ...(extra === undefined ? {} : { extra }),
+        latencyMs: Date.now() - started,
+      });
+      // 把降级原因回传给调用方（之前是 null）：明细与「标记」列才能写出
+      // 真实失败情况（http-404 / auth-failed / timeout …），而不是只有 degraded。
+      return { degraded: reason, ...(extra && typeof extra.status === "number" ? { status: extra.status } : {}) };
+    };
+
+    // 服务端下发（DEC-030）：有可用值时整段覆盖本地 provider——resolveProvider
+    // 的 server 分支刻意不读本地配置（用户机器上的残留地址不该盖掉管理员的
+    // 改动）。热路径**绝不 await 网络**：拿不到值就照旧走本地，只顺带喊一发
+    // 后台刷新（并发去重与 30s 重试下限都收敛在 ServerConfigSource 里）。
+    const server = this.getServerOverride?.();
+    if (server === undefined) this.refreshServer?.();
+    // provider 每请求重新解析：换 provider / 改地址立刻对下一次决策生效。
+    // 解析失败（custom 地址非法）时直接降级，而不是打到一个猜出来的地址上——
+    // 「静默 404」是本插件最难自查的故障。
+    const provider = server !== undefined ? resolveProvider(cfg, { server }) : resolveProvider(cfg);
+    if (!provider.valid) {
+      return degrade("invalid-base-url", { provider: provider.id, hint: provider.error });
+    }
+    // memoryKey 是随下发一起到达的明文 key：与地址必须来自**同一套**下发，
+    // 拿本地 key 打下发地址等于用错账号（必 401 且症状像地址坏了）。它只在
+    // 这次调用的参数里出现——绝不写进 cfg，绝不进任何持久化 patch（DEC-030）。
+    const key = resolveKey(cfg, provider, { memoryKey: server?.key });
+    if (key === undefined) {
+      return degrade("no-key", {
+        provider: provider.id,
+        hint:
+          provider.apiKeyEnv.length > 0
+            // 指名该 provider 自己的字段（siliconflowApiKey / bamboonodeApiKey /
+            // customApiKey …）。写死 apiKey 会让人把 key 填进 bamboonode 的格子，
+            // 而其它 provider 并不读它——遥测里就会出现「填了 key 仍报 no-key」。
+            ? `设置 ${provider.preset?.keyField ?? "apiKey"} 或导出 $${provider.apiKeyEnv}`
+            : `为 ${provider.id} 填写 ${provider.preset?.keyField ?? "自定义 key 字段"}，或设置 ${provider.preset?.keyEnvField ?? "密钥变量名"}`,
+      });
+    }
+    const endpoint = provider.endpoint;
+    // 允许留空：不发送 model 字段时，服务端会用它当前的默认决策模型
+    //（实测省略 model 返回 200 且 model 回填为实际使用的模型）。
+    // 这样即便服务商将来换模型名，留空配置也不会因此 400。
+    const model = (provider.model ?? "").trim();
+
+    const exactKey = DecisionCache.exactKey([endpoint, model, call.state, call.questions]);
+    // 软键（归一化「同类」复用）默认关闭，fail-closed：只有调用方显式传
+    // `softCacheable: true` 才启用。授权（authorize）这类安全检查绝不启用——
+    // 归一化签名只保留「工具名 + 命令族 + 风险标记」，丢弃了参数内容，
+    // 一次低风险放行会被扩散到参数完全不同的调用上（评审意见 2026-10：
+    // bind authorization caching to the full call/context, or disable soft reuse）。
+    const softKey =
+      call.softCacheable === true && typeof call.signatureText === "string" && call.signatureText.length > 0
+        ? DecisionCache.softKey(`${point}:${call.tool ?? ""}`, call.signatureText)
+        : undefined;
+
+    const hit = this.cache.get(exactKey) ?? (softKey === undefined ? undefined : this.cache.get(softKey));
+    if (hit !== undefined) {
+      this.stats.cached += 1;
+      counter.cached += 1;
+      // 缓存命中：这次没发请求，0 token、0 毫秒。但它**替掉**了一次完整
+      // 请求——那份开销就是省下来的量，基线取被复用那次记录里的数值。
+      //
+      // 缓存里存的是**上一次真实请求**的结果（含它当时的 input token 与
+      // 耗时），所以直接拿来当基线：省下的正是「本来要再付一次」的那份。
+      //
+      // 基线优先用 **statInputTokens**（含估算的数）：上一次请求若遇到服务
+      // 方不报 usage，它的 input token 只能用估算值，而那才是「本来要付
+      // 多少」的真实量级。
+      //
+      // 这里**不写**统计记录，只把「消耗事实」挂在返回值上：裁决（allow /
+      // ask / reject）是调用方算出 `spec.decide()` 之后才有的，写在
+      // classify 里会永远缺这一维（见 recordDecision 的说明）。
+      return {
+        ...hit,
+        cached: true,
+        latencyMs: 0,
+        statsFacts: {
+          point,
+          provider: provider.id,
+          model: hit.model ?? model ?? "(server-default)",
+          // 缓存命中的节省量是「省得最多的一类」，但它只在观察模式下
+          // 才是有意义的实测对比（见 lib/stats.js 顶部说明）。
+          mode: call.pointMode ?? "unknown",
+          cached: true,
+          inputTokens: 0,
+          outputTokens: 0,
+          durationMs: 0,
+          baseInputTokens: hit.statInputTokens ?? hit.inputTokens ?? 0,
+          baseOutputTokens: hit.statOutputTokens ?? hit.outputTokens ?? 0,
+          baseDurationMs: hit.latencyMs ?? 0,
+          inputSource: hit.inputSource ?? "unknown",
+          outputSource: hit.outputSource ?? "unknown",
+        },
+      };
+    }
+
+    /**
+     * 半开冷却：冷却期内**每隔 cooldownProbeMs 放行一次**试探请求，其余照旧快速降级。
+     *
+     * 位置很关键：这一关必须放在**缓存查找之后**。冷却拦的是「要发出去的请求」，
+     * 而缓存命中根本不出网——把冷却放在缓存之前，会让冷却期里本来 0 token、
+     * 0 毫秒就能答的命中一起变成 `degrade("cooldown")`，等于服务抖一下就连
+     * 缓存一起废掉。既有实现里这一关在缓存之前，是 93 次 cooldown 之外的另一层
+     * 放大：本该被缓存吸收的调用也全被算进了降级。
+     *
+     * 改动前这里是「冷却期内一律降级」，于是 60 秒冷却期间所有决策都在 0–1ms
+     * 内失败——遥测里那 93 次 cooldown 不是服务真的坏了 60 秒，而是保护机制
+     * 把一次 3 秒的抖动放大成了一分钟的全黑。现在每 cooldownProbeMs 放行一次
+     * 试探：成功由 `noteSuccess()` 彻底解除冷却，失败则 `noteFailure()` 按
+     * streak 指数退避重设冷却并后推试探窗口。detail 保持 "cooldown" 不变
+     * ——遥测与统计里都有对它的既有断言。
+     */
+    const nowMs = Date.now();
+    /** 本次调用是不是「冷却期里被放行的那一次试探」。它决定失败时怎么记。 */
+    let cooldownProbe = false;
+    if (nowMs < this.cooldownUntil) {
+      if (nowMs < this.cooldownNextProbe) return degrade("cooldown");
+      // 放行这一次试探：立刻把窗口推到下一轮，避免并发的多个决策同时闯进来。
+      this.cooldownNextProbe = nowMs + Math.max(1000, Number(cfg.cooldownProbeMs ?? DEFAULTS.cooldownProbeMs));
+      cooldownProbe = true;
+    }
+
+    const timeoutMs = Math.max(1000, cfg.timeoutMs);
+    /**
+     * 重试的总预算与总次数（含首发）。
+     *
+     * 预算从**进入 classify 时**算起（`started`），而不是从发请求时算起：整轮
+     * 决策对调用方的时间成本才是它真正等的东西。封顶 30s——两次 20s 的预算
+     * 已经超过任何一次工具调用能忍的等待，再重试只会把一次失败拖成一次更慢的失败。
+     */
+    const maxBudgetMs = Math.min(timeoutMs * 2, 30000);
+    // retryAttempts 是「重试次数」，maxAttempts 是「总尝试次数（含首发）」。
+    // 非数字（旧配置文件里写了脏值）一律按默认值算：重试策略本身不能因为
+    // 一个坏配置变成「永不重试」或「无限重试」。
+    const retryAttempts = Number(cfg.retryAttempts ?? DEFAULTS.retryAttempts);
+    const maxAttempts = Math.max(
+      1,
+      Math.floor(Number.isFinite(retryAttempts) ? retryAttempts : DEFAULTS.retryAttempts) + 1,
+    );
+
+    this.stats.requests += 1;
+    counter.requests += 1;
+    // 请求体只构造一次：换路径重试时内容必须完全相同，否则第二次请求
+    // 与第一次不可比（缓存键也随之失配）。
+    const bodyText = JSON.stringify(
+      buildRequestBody(provider, {
+        state: call.state,
+        questions: call.questions,
+        thinkMode: cfg.thinkMode,
+      }),
+    );
+    // 候选端点：主路径优先，404 时换另一条（实测 SiliconFlow 只通
+    // /systemone、bamboonode 两条都通）。记忆里验证过的路径会被提到最前，
+    // 因此只有第一次探测会多一次往返。
+    const candidates = this.endpointMemory.order(provider.baseUrl, provider.candidates ?? [endpoint]);
+    let response;
+    let usedEndpoint = endpoint;
+    let attempts = [];
+    for (let attempt = 0; ; attempt += 1) {
+      // 每次尝试各自一份 timer：上一次的 AbortSignal 已经 abort，复用它会让
+      // 第二发**立刻**以同一个超时失败，重试就成了纯粹的浪费。
+      const timer = AbortSignal.timeout(timeoutMs);
+      const signal = call.signal === undefined ? timer : AbortSignal.any([call.signal, timer]);
+      try {
+        const result = await sendWithEndpointFallback(candidates, async (target) => {
+          usedEndpoint = target;
+          return this.fetchFn(target, {
+            method: "POST",
+            // 鉴权与请求头同样由 provider 构造：custom 可以带额外头，
+            // 但 authorization / content-type 永远由本插件决定。
+            headers: buildHeaders(provider, key),
+            body: bodyText,
+            signal,
+          });
+        });
+        response = result.response;
+        usedEndpoint = result.endpoint;
+        attempts = result.attempts;
+        // 探测到可用路径：记住它，下次直接打（省掉一次多余往返）。
+        if (response?.ok === true) {
+          const style = styleOfEndpoint(usedEndpoint);
+          if (style !== undefined) this.endpointMemory.record(provider.baseUrl, usedEndpoint, style);
+        }
+        break;
+      } catch (error) {
+        if (call.signal?.aborted) return degrade("caller-aborted");
+        const reason = timer.aborted || error?.name === "AbortError" ? "timeout" : "network-error";
+        // 只有 timeout 与 network-error 值得重试（见 resilience.js 的实测理由）：
+        // 冷启动首发被掐断时服务端已被焐热，第二发通常 1–2 秒返回。4xx/5xx 走不到
+        // 这里（它们不是抛错），而它们的重试逻辑刻意**不存在**。
+        if (
+          shouldRetry({
+            reason,
+            attempt,
+            elapsedMs: Date.now() - started,
+            timeoutMs,
+            maxAttempts,
+            maxBudgetMs,
+          })
+        ) {
+          continue;
+        }
+        // **只在最终失败时记一次**：重试的中间那次不代表端点已被判定故障，
+        // 每次都 noteFailure 会让失败阈值提前触发，冷却反而更容易被点着。
+        this.noteFailure({ duringCooldown: cooldownProbe });
+        // 值得重试却还是失败了（重试次数或总预算用尽）：单独留一条日志。
+        // 它与「本来就不该重试的失败」是两件事，混在一起会让人以为重试没生效。
+        if (isRetryableReason(reason) && attempt > 0) {
+          this.logger?.warn?.(
+            `dsh-decision-engine: ${reason} 重试后仍失败（共 ${attempt + 1} 次尝试，预算 ${maxBudgetMs}ms）`,
+          );
+        }
+        if (reason === "timeout") {
+          return degrade("timeout", { timeoutMs, endpoint: usedEndpoint, attempts: attempt + 1 });
+        }
+        return degrade("network-error", {
+          endpoint: usedEndpoint,
+          message: error instanceof Error ? error.message : String(error),
+          attempts: attempt + 1,
+        });
+      }
+    }
+
+    this.stats.lastStatus = response.status;
+
+    if (!response.ok) {
+      let bodyText = "";
+      try {
+        bodyText = (await response.text()).slice(0, 400);
+      } catch {
+        /* 读不到 body 就只报状态码 */
+      }
+      // 4xx 是配置错误（地址/模型/key），不该重试；5xx 计入失败阈值。
+      if (response.status >= 500) this.noteFailure({ duringCooldown: cooldownProbe });
+      // 401/403 单列一类：这是「key 不对」而不是「地址不对」，两者的
+      // 修复动作完全不同，混成一个 http-4xx 会让用户去改错的字段。
+      if (response.status === 401 || response.status === 403) {
+        return degrade("auth-failed", {
+          provider: provider.id,
+          endpoint: usedEndpoint,
+          status: response.status,
+          keyEnv: provider.apiKeyEnv,
+          body: bodyText,
+          hint: `鉴权被拒（HTTP ${response.status}）：检查 ${provider.id} 的 API key 是否有效、是否与地址匹配`,
+        });
+      }
+      // 404 且两条路径都试过：路径风格不对是最常见的原因，必须说清楚
+      // 试过哪两条——否则用户只看到「HTTP 404」，完全猜不到是路径选错。
+      const tried = attempts.map((item) => item.endpoint);
+      const allMissing = response.status === 404 && attempts.length > 1;
+      return degrade(`http-${response.status}`, {
+        provider: provider.id,
+        endpoint: usedEndpoint,
+        model,
+        body: bodyText,
+        ...(tried.length > 1 ? { tried } : {}),
+        ...(allMissing
+          ? {
+              hint:
+                `路径不存在（HTTP 404）：已试过 ${tried.join(" 与 ")}。` +
+                `若该服务用的是另一条路径，请在配置页把「端点风格」改成对应的那条。`,
+            }
+          : {}),
+      });
+    }
+
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      this.noteFailure({ duringCooldown: cooldownProbe });
+      return degrade("invalid-json", { endpoint: usedEndpoint });
+    }
+    if (body === null || typeof body !== "object") {
+      this.noteFailure({ duringCooldown: cooldownProbe });
+      return degrade("invalid-response", { endpoint: usedEndpoint });
+    }
+
+    const answers = body.answers;
+    if (answers === null || typeof answers !== "object") {
+      return degrade("missing-answers", { endpoint: usedEndpoint });
+    }
+
+    const usage = typeof body.usage === "object" && body.usage !== null ? body.usage : {};
+    // API 返回的 token 计数（优先采信）。缺失时用估算器兜底——
+    // 统计需求明确要求「优先采用 API 返回计数，缺失时用 tokenizer 估算」。
+    const apiInputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : undefined;
+    const apiOutputTokens = typeof usage.output_tokens === "number" ? usage.output_tokens : undefined;
+    const inputSource = apiInputTokens === undefined ? "estimated" : "api";
+    const outputSource = apiOutputTokens === undefined ? "estimated" : "api";
+    const inputTokens = apiInputTokens ?? estimateRequestTokens(bodyText);
+    const outputTokens = apiOutputTokens ?? 0;
+    const result = {
+      answers,
+      model: typeof body.model === "string" ? body.model : model || "(server-default)",
+      // 这次决策实际用的服务商。遥测必须带上它：遥测是回填历史统计的唯一
+      // 来源，缺了 provider 就只能靠模型名反推，反推不上只能记 unknown，
+      // 界面上便是整块「未知（历史）」（见 lib/stats-store.js 的
+      // backfillFromTelemetry）。
+      provider: provider.id,
+      latencyMs: Date.now() - started,
+      // **只放 API 报的值**（没有就 undefined）。
+      //
+      // 遥测（telemetry.jsonl）是「服务端到底说了什么」的审计记录：把估算值
+      // 塞进去会让人把推算当成实测。而统计（stats.jsonl）有自己的字段与
+      // 来源标记（inputSource / outputSource），估算值放在那里才有出处。
+      inputTokens: apiInputTokens,
+      outputTokens: apiOutputTokens,
+      inputSource,
+      outputSource,
+      // 统计用的 token 数（含估算）。与上面的「API 原始值」分开存：
+      // 前者进遥测（审计记录），后者进统计与缓存基线。
+      statInputTokens: inputTokens,
+      statOutputTokens: outputTokens,
+      cached: false,
+    };
+
+    this.noteSuccess();
+    this.stats.ok += 1;
+    counter.ok += 1;
+    counter.latencySum += result.latencyMs;
+    counter.latencyMax = Math.max(counter.latencyMax, result.latencyMs);
+    if (typeof apiInputTokens === "number") {
+      counter.tokens += apiInputTokens;
+    }
+
+    // 记一条统计：这次请求的实际消耗。
+    //
+    // 这里**只把消耗事实挂到返回值上，不立刻写盘**——裁决（allow / ask /
+    // reject）是调用方算出 `spec.decide()` 之后才有的，而写盘必须带上它，
+    // 否则统计里永远缺「这次裁决了什么」这一维（见 recordDecision 的说明）。
+    //
+    // 基线默认 = 实际（`buildRecord` 的语义）：本次决策请求本身没有可归因
+    // 优化——插件省的是**别的**东西（缓存命中省掉整次请求、上下文截断
+    // 省掉 input token），那些在各自的位置记基线。
+    //
+    // 这里用**含估算**的 inputTokens / outputTokens：统计要的是「花了多少」，
+    // 服务方不报数时用估算值填上，并靠 inputSource / outputSource 标明来源。
+    result.statsFacts = {
+      point,
+      provider: provider.id,
+      model: result.model,
+      // 模式决定这条记录是否计入节省量（见 lib/stats.js 顶部说明）：
+      // 只有观察模式计入，因为只有那时「普通 LLM 路径」与「决策模型路径」
+      // 跑在同一批工作上，反事实才成立。
+      mode: call.pointMode ?? "unknown",
+      inputTokens,
+      outputTokens,
+      durationMs: result.latencyMs,
+      inputSource,
+      outputSource,
+    };
+
+    this.cache.set(exactKey, result);
+    // 软键写入同样 fail-closed：softKey 只在调用方显式声明 softCacheable:true
+    // 时才非 undefined，这里不存在「没声明也能进软缓存」的路径。
+    if (softKey !== undefined) {
+      this.cache.set(softKey, result, true);
+    }
+    return result;
+  }
+
+  /**
+   * 记一条**带裁决**的统计（旁路，永不抛）。
+   *
+   * 统计是**辅助信息**，绝不能因为它把决策路径搞挂。因此这里吞掉所有
+   * 异常：写盘失败、序列化失败、存储没注入——都只是「这次没统计上」。
+   *
+   * 为什么统计必须由调用方在拿到裁决后才写：
+   *
+   *   裁决（allow / ask / reject）是 `spec.decide()` 的产物，而
+   *   `spec.decide()` 要等决策模型的答案回来才跑得出来。若在
+   *   `classify()` 里就把统计写掉，写进去的记录必然**没有裁决**——
+   *   实测就是这么留下的：stats.jsonl 里 132 条实时记录的 `action` 是空串，
+   *   而按裁决分账的统计永远只能显示「未裁决」。
+   *
+   * 因此 `classify()` 只把「消耗事实」挂在返回值上（`statsFacts`），
+   * 由拿到裁决的一方调用本方法补齐并写盘。
+   *
+   * @param options - 字段：
+   *   - `facts`  `classify()` 返回的 `statsFacts`（消耗那一半）。
+   *   - `action` 裁决词（`spec.decide()` 返回的 `action.kind`）。
+   *   - `detail` 裁决原因。
+   *   - `degraded` 是否降级（降级时没有裁决，只记消耗）。
+   * @returns 是否真的写了（存储没注入时返回 false）。
+   */
+  recordDecision(options = {}) {
+    if (this.statsStore === null || this.statsStore === undefined) return false;
+    const facts = options.facts ?? {};
+    try {
+      this.statsStore.record(
+        buildRecord({
+          ...facts,
+          action: options.action ?? "",
+          detail: options.detail ?? "",
+          degraded: options.degraded === true,
+        }),
+      );
+      return true;
+    } catch {
+      /* 统计失败不影响决策 */
+      return false;
+    }
+  }
+}
+
+/**
+ * 读取插件自己的配置文件 `<插件目录>/config.yml`。
+ *
+ * 配置**只放这里**，不进 DSH 的 Settings 面板，也不依赖 profile 的
+ * cordis.patch.yml 覆盖——只有一项 api key，单独一个文件最省心，
+ * 而且不会因为 profile 里忘了写 config 行而静默退回默认值（旧插件正是这样）。
+ *
+ * 用极简 YAML 子集解析：只支持 `key: value` 与 `#` 注释，值做布尔/数字推断。
+ * 这不追求通用 YAML，只保证配置项（全是标量或字符串数组）能被可靠读出，
+ * 从而不引入任何运行时依赖。
+ *
+ * @param path - 配置文件绝对路径。
+ * @returns 解析出的键值对；文件不存在或读失败返回空对象。
+ */
+async function readOwnConfig(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return {};
+  }
+  // 解析逻辑放在零依赖的 config-file.js：它需要往返测试（保存→重读→回显），
+  // 而带 schemastery 的模块在裸仓库里没法被单测加载。
+  return parseConfigText(raw);
+}
+
+/**
+ * 挂载守卫。
+ * @param ctx - cordis 插件上下文。
+ * @param config - profile 里可选的 config（留空即可，本插件主配置在 config.yml）。
+ */
+export function apply(ctx, config) {
+  // 更名迁移必须先跑：它决定后面读写的到底是哪个目录。
+  // 放在 apply 的最前面，保证第一次 reloadOwnConfig 就能读到正确位置。
+  const migrated = migrateLegacyData();
+  const ownConfigPath = resolveConfigPath();
+
+  // 优先级：config.yml > profile 的 config 行 > DEFAULTS。
+  // 文件是主配置，profile 里的 config 只作为可选覆盖（便于临时试验）。
+  // 注意：DSH 传给 apply 的 config 是 Schemastery 解析后的**完整默认值**
+  //（enabled:false / mode:shadow / timeoutMs:20000 ...），并非用户显式配置。
+  // 若直接用它覆盖 config.yml，文件里保存的开关就会被永久压回默认值——
+  // 这正是「保存后开关回弹」的根因。因此这里先用 DEFAULTS 打底，
+  // 由 reloadOwnConfig 以「yml 优先、config 仅补空缺」的顺序合成。
+  let cfg = { ...DEFAULTS };
+  const getConfig = () => cfg;
+
+  // ---- 服务端下发（DEC-030）---------------------------------------------
+  /**
+   * 服务端配置源：下发的地址/模型/key 只活在这个实例的内存里。
+   *
+   * 为什么建在 apply()：实例随插件挂载创建、随宿主重载销毁（内存 key 一并
+   * 消失）；它自己零 fs——既不读也不写任何配置文件，门禁令牌由本文件读取
+   * 后注入。这里再包一层 `serverOverride()` 做「开关 × 有效期」双闸，
+   * 下发的 key 离开该实例的唯一出口就是这两个函数的返回值。
+   */
+  const serverConfig = new ServerConfigSource({
+    endpoint: SERVER_CONFIG_ENDPOINT,
+    token: readServerToken(),
+    logger: ctx.logger,
+  });
+  /** 此刻生效的服务端覆盖值；「开关打开 且 值未过期」才存在，否则 undefined。 */
+  const serverOverride = () =>
+    (cfg.serverProvider === true && serverConfig.usable() ? serverConfig.value() : undefined);
+  /** 当前应该使用的 provider：有服务端覆盖时整段走下发值，否则逐字不变地走本地。 */
+  const activeProvider = (base = cfg) => {
+    const server = serverOverride();
+    return server !== undefined ? resolveProvider(base, { server }) : resolveProvider(base);
+  };
+  /** 与 activeProvider 配对取 key：下发值里的 key 以 memoryKey 身份进入解析。 */
+  const activeKey = (provider) => resolveKey(cfg, provider, { memoryKey: serverOverride()?.key });
+  /**
+   * 后台补一发：开着而值不可用时刷新一次（不 await）。
+   *
+   * 给热路径（classify）与 /status 用。刷新失败只体现在 status() 上；
+   * 重试下限保证不会每次工具调用都打一发。
+   */
+  const refreshServerInBackground = () => {
+    if (cfg.serverProvider === true && !serverConfig.usable()) void serverConfig.refresh();
+  };
+
+  /**
+   * 人工审核比例（DEC-035）的滚动校准器。
+   *
+   * 按 provider × model 分开记「最近 200 次授权决策的严重度」，据此算出
+   * 「最前的 1% / 25%」分别落在什么分数上。**纯内存**：分位数的语义是
+   * 「这个模型**最近**怎么说的」，落盘会把几天前的分布混进来。
+   *
+   * 它只在授权点用得上——那一个点是唯一真正会打断用户的点。
+   */
+  const toleranceCalibrator = new ToleranceCalibrator();
+
+  const telemetryDir = resolveTelemetryDir();
+  // 统计存储：与遥测同目录，但独立文件（见 lib/stats-store.js 的说明）。
+  // 写盘是异步的，不阻塞决策路径。
+  const statsStore = new StatsStore({ dir: telemetryDir, logger: ctx.logger });
+  const client = new StartluxClient({
+    getConfig,
+    logger: ctx.logger,
+    telemetryDir,
+    statsStore,
+    getServerOverride: serverOverride,
+    refreshServer: refreshServerInBackground,
+  });
+  /**
+   * 决策明细存储（「决策历史」页的数据源，见 lib/decision-store.js）。
+   *
+   * 三个取值函数都由配置现读，因此配置页改了开关立刻生效——不需要重启，
+   * 与插件其余配置的处理方式一致。开关关闭时 `record()` 直接返回 false，
+   * 既不建文件也不占磁盘；开启时明细一定带内容（每条记录上的 `capture`
+   * 只反映 `truncateContent()` 的截断结果，没有任何配置能把它降级成 meta）。
+   */
+  const decisionStore = new DecisionStore({
+    dir: telemetryDir,
+    logger: ctx.logger,
+    getEnabled: () => cfg.decisionsTabEnabled !== false,
+    getMaxBytes: () => cfg.decisionsMaxBytes,
+    getMaxContentChars: () => cfg.decisionsMaxContentChars,
+  });
+
+  /**
+   * 启动时把旧遥测回填进统计文件（**只做一次**，靠标记文件记住）。
+   *
+   * 为什么必须落盘而不是查询时现算：现算的话历史只在「统计文件为空」时
+   * 才在——而统计文件在插件跑起来后第一笔新请求就会被创建，于是用户刚
+   * 升级就发现「以前一个月的记录不见了」。落盘之后历史与新记录同处一个
+   * 文件，随时间范围一起被统计到。
+   *
+   * 不 await：回填是旁路，不该拖住插件启动。失败也只记警告。
+   */
+  /**
+   * 启动时的两步历史整理，**必须按顺序**跑。
+   *
+   *   1. 回填：把旧遥测里的历史追加进统计文件。
+   *   2. 补模式：给已有记录补上 `mode` 字段。
+   *
+   * 为什么不能并发：第 2 步是「读整个文件 → 改 → 整体写回」。若它与
+   * 第 1 步并发，第 2 步可能在第 1 步追加**之前**读完文件、又在第 1 步
+   * 追加**之后**写回——于是第 1 步刚追加的那些历史记录被覆盖丢失。
+   * 这类「并发写同一个文件」的竞态在真实环境里极少复现，却极难自查，
+   * 所以这里老老实实串行。
+   *
+   * 为什么不 await：整理是旁路，不该拖住插件启动。失败也只记警告。
+   */
+  void statsStore
+    .backfillOnce()
+    .then((count) => {
+      if (count > 0) {
+        ctx.logger?.info?.(`dsh-decision-engine: 已从旧遥测回填 ${count} 条历史统计`);
+      }
+      return statsStore.fillMissingModesOnce();
+    })
+    .then((count) => {
+      if (count > 0) {
+        ctx.logger?.info?.(
+          `dsh-decision-engine: 已为 ${count} 条历史统计补上模式字段（观察模式的记录才计入节省量）`,
+        );
+      }
+      return statsStore.repairLegacyProviderOnce();
+    })
+    .then((count) => {
+      if (count > 0) {
+        ctx.logger?.info?.(
+          `dsh-decision-engine: 已按模型名补回 ${count} 条历史统计的 provider（startlux→bamboonode、Kev/SemIf→硅基流动）`,
+        );
+      }
+    })
+    .catch(() => {
+      /* 历史整理失败不影响插件启动 */
+    });
+
+
+  /**
+   * 匿名使用统计（DEC-020）。
+   *
+   * 放在 `apply()` 里的理由与紧挨着的 `backfillOnce` 完全一致：它是一次性的
+   * 旁路动作，`void` 掉即可，**绝不能**进入决策路径（`guardListener` /
+   * `client.classify`）——statistics 失败不能变成插件故障，更不能给每次工具
+   * 调用加一次网络等待。
+   *
+   * 上报内容只来自本进程能直接读到的量：插件版本、平台、架构，以及当天
+   * 决策数（从 stats.jsonl 聚合，不是内存计数器——后者只反映本次会话）。
+   * 不再上报任何别的东西（见 lib/telemetry.js 顶部的承诺）。
+   */
+  const startTelemetry = async () => {
+    const level = cfg.telemetryLevel ?? DEFAULTS.telemetryLevel;
+    // off 时连读取都省掉：这是「关掉就是真的不联网」的执行点之一。
+    if (level === "off") return;
+    let decisions = 0;
+    try {
+      // 只统计「今天」的决策数：心跳的语义是「今天用没用、用多少」。
+      // 聚合失败就当 0（不上报该字段），不影响上报本身。
+      const rows = await statsStore.read();
+      const range = resolveRange({ preset: "today" });
+      if (range.valid === true) {
+        const result = aggregate(rows, range);
+        // 字段名是 `requests`（见 stats.js 的 emptyBucket）。这里曾写成
+        // 不存在的 `turns`，于是永远取到 undefined → 0，线上每一条心跳的
+        // 决策数都是 0，D1 里 5646 条活跃记录 SUM(decisions)=0 就是证据。
+        decisions = Number(result?.totals?.requests) || 0;
+      }
+    } catch {
+      decisions = 0;
+    }
+    await new TelemetryReporter({
+      dir: telemetryDir,
+      logger: ctx.logger,
+      pluginId: readOwnPluginId(),
+      level,
+      endpoint: cfg.telemetryEndpoint,
+    }).start({
+      version: readOwnVersion(),
+      platform: process.platform,
+      arch: process.arch,
+      // 宿主版本拿不到就留空，buildPayload 会整字段省略（不猜、不伪造）。
+      hostVersion: "",
+      decisions,
+    });
+  };
+  // 不 await：首次运行会真的发一次网络请求，绝不能拖住插件启动。
+  //
+  // **必须等 reloadOwnConfig 落定之后再跑**：`apply()` 开头 `cfg` 只是 DEFAULTS
+  // 的副本，用户在 config.yml 里写的 `telemetryLevel: off` 要等那次读取才合并进来。
+  // 若在此刻直接上报，会把「用户明确关掉」当成默认档上报一次——既违背 off 的
+  // 承诺，也把一个本不该发的请求发出去。与文件里其它旁路动作一样，失败只记日志。
+
+  const isLive = () => cfg.enabled === true;
+
+  /**
+   * 载入 config.yml 并与当前配置合并。每次工具调用前都会调一次，
+   * 因此**改 yml 立即生效，不用重启**（靠 mtime 判断是否需要重读）。
+   */
+  let lastMtime = 0;
+  const reloadOwnConfig = async () => {
+    try {
+      const { stat } = await import("node:fs/promises");
+      const info = await stat(ownConfigPath);
+      if (info.mtimeMs === lastMtime) return;
+      // 注意：mtime 必须在**合并完成之后**才记录。
+      // 若像原来那样先记录再 await 读文件，并发的第二次调用会看到「mtime 已更新」
+      // 而立刻 return，此时 cfg 还是旧值——启动瞬间的第一次状态请求正好撞上这个
+      // 窗口，会显示一份默认配置（provider/地址全错）。代价只是并发时多读一次文件。
+      const own = await readOwnConfig(ownConfigPath);
+      if (Object.keys(own).length === 0) return;
+      // 优先级：DEFAULTS < config.yml < profile 的 config 行。
+      // profile 显式配置必须能覆盖文件——否则用户在 cordis.patch.yml 里改的
+      // 值会被文件静默吃掉，测试与运维都无法覆盖（DSH 的配置层级也是这个顺序）。
+      // 合成顺序：DEFAULTS < DSH 传入的 config < config.yml。
+      // config.yml 放最后，因为它是用户显式保存的唯一入口；DSH 传入的
+      // config 多为 schema 默认值，不能让它盖掉用户的选择。
+      cfg = { ...DEFAULTS, ...stripUndefined(config ?? {}), ...own };
+      lastMtime = info.mtimeMs;
+      // 这行日志是「此刻实际会打哪」的第一现场：用生效解析（activeProvider），
+      // 否则服务端下发在时报告的是本地地址，排查的人会照着假地址找。
+      // 启动早期刷新多半还没完成，此时它就是本地解析——语义与从前一致。
+      const loaded = activeProvider();
+      ctx.logger?.info?.(
+        `dsh-decision-engine: 已载入 ${ownConfigPath}（enabled=${cfg.enabled}, mode=${cfg.mode}, provider ${loaded.id}, 端点 ${loaded.endpoint || "(不可用)"}）`,
+      );
+      // 只有 yml 存在时才重算 cfg；文件缺失时保留 apply 期的基础值。
+    } catch {
+      // 文件不存在就用 DEFAULTS + config 的组合，不算错误。
+    }
+  };
+
+  /**
+   * 把键值写回 config.yml —— 保留原有注释与顺序，只替换/追加目标键。
+   *
+   * 面板「保存」的落盘实现。刻意不做整文件重写：用户的注释是说明书，
+   * 重写一次就全丢。做法是逐行扫描，命中 `key:` 就改值，没命中就在末尾追加。
+   *
+   * `model` 的特殊语义：空字符串表示「自动（服务端默认）」，必须写成
+   * `model: ` 而不是删掉该行——否则键缺失会回落到内置硬编码模型名。
+   *
+   * @param updates - 要写入的键值。
+   */
+  const persistConfig = async (updates) => {
+    const wasServerProvider = cfg.serverProvider === true;
+    const { writeFile } = await import("node:fs/promises");
+    // 先建目录：全新安装时数据目录还不存在，直接 writeFile 会 ENOENT。
+    // 那会造成最糟的一种失败——凭据已经写进去了、配置却写不进去，
+    // 用户只看到一条报错，而 key 其实「存了一半」。
+    // 目录创建必须幂等（recursive），已有目录时是无操作。
+    await mkdir(dirname(ownConfigPath), { recursive: true });
+    let lines = [];
+    try {
+      lines = (await readFile(ownConfigPath, "utf8")).split("\n");
+    } catch {
+      // 首次写入：给一份最小骨架，并说明这个文件是什么（用户会直接编辑它）。
+      lines = [
+        "# dsh-decision-engine 配置（插件自有，唯一配置文件）",
+        "#",
+        "# 改这个文件即生效：每次工具调用前都会检查 mtime，改完不用重启 DSH。",
+        "# 完整配置项说明见 config.example.yml。",
+        "",
+      ];
+    }
+    // 逐行替换而不是整文件重写：用户的注释是说明书，重写一次就全丢。
+    // 具体实现与格式规则见 config-file.js（有往返测试）。
+    const next = applyConfigUpdates(lines, updates);
+    await writeFile(ownConfigPath, next.join("\n"), { encoding: "utf8", mode: 0o600 });
+    lastMtime = 0;
+    await reloadOwnConfig();
+    // 开关刚被关掉（DEC-030）：立刻把内存里的下发 key 扔掉。
+    //
+    // 位置刻意放在 reloadOwnConfig 之后：只有读到新配置才算「用户确实关了」，
+    // 否则一次写盘失败（此时不抛、只是没改成）会把下发值误清——而用户看到的
+    // 是「开关还开着、值却没了」。
+    //
+    // 关掉就清，而不是留到下次启动：这个开关的全部意义就是「别再拿服务端的
+    // 账号了」。留一份内存副本，等于关掉之后进程里还攥着别人的 key。
+    if (wasServerProvider === true && cfg.serverProvider !== true) serverConfig.clear();
+  };
+
+  /**
+   * 按 `keyStorage` 把密钥写到用户选定的位置。
+   *
+   * 三条规则：
+   *
+   *   1. `credentials`（默认）：写进 `~/.dsh/.credentials.yaml` 的 `refs:` 段，
+   *      键名就是该 provider 自己的变量名（TYPESAFE_API_KEY / BAMBOO_API_KEY /
+   *      custom 的变量名）。此时 yml 里**不保留**明文 key，也不会写显式 key 字段。
+   *   2. `config`：写进插件自己的 `config.yml`，字段是该 provider 的显式 key
+   *      字段（`systemoneApiKey` / `bamboonodeApiKey` / `customApiKey`）。
+   *      key 存进凭据文件的旧值**不清除**——换回 credentials 模式时还能用。
+   *   3. 传空字符串：删除该位置的 key（用户清空即撤销）。
+   *
+   * 只有 body 里真的带了某个 key 字段才处理，避免「保存开关」时误删 key。
+   *
+   * @param patch - 前端提交的改动。
+   * @param current - 当前生效配置。
+   * @returns `{ ok, patch }`：patch 是还要写进 yml 的部分（已剔除已托管到凭据文件的 key）。
+   */
+  const persistKeys = async (patch, current) => {
+    const storage = patch.keyStorage ?? current.keyStorage ?? "credentials";
+    /** 本次要写进凭据文件的键值（ref 名 → key）。 */
+    const credentialWrites = {};
+    /** 本次要写进 yml 的键值。 */
+    const ymlPatch = { ...patch };
+
+    // provider → 它的显式 key 字段名与 refs 键名。
+    // 逐个预设生成而不是写死：漏掉一个 provider，它的 key 就会**绕过凭据文件
+    // 直接以明文写进 config.yml**——那是「托管到凭据文件」这条承诺的破口。
+    const slots = Object.values(PROVIDER_PRESETS).map((preset) => {
+      const override = typeof current[preset.keyEnvField] === "string" ? current[preset.keyEnvField].trim() : "";
+      return { keyField: preset.keyField, refName: override.length > 0 ? override : preset.apiKeyEnv };
+    });
+    // 历史共享字段：老前端只认 apiKey，按 bamboonode 处理
+    slots.push({
+      keyField: "apiKey",
+      refName: current.bamboonodeApiKeyEnv || PROVIDER_PRESETS.bamboonode.apiKeyEnv,
+    });
+
+    for (const slot of slots) {
+      if (!Object.hasOwn(patch, slot.keyField)) continue;
+      const raw = typeof patch[slot.keyField] === "string" ? patch[slot.keyField].trim() : "";
+      if (storage === "credentials") {
+        credentialWrites[slot.refName] = raw;
+        // 明文不落 yml：这是「托管到凭据文件」的意义。
+        delete ymlPatch[slot.keyField];
+      } else {
+        // 存到配置文件：yml 里直接写显式 key 字段。
+        ymlPatch[slot.keyField] = raw;
+      }
+    }
+
+    const names = Object.keys(credentialWrites);
+    if (names.length === 0) return { ok: true, patch: ymlPatch };
+
+    /** 已成功写入的项，带上写入前的值，供上层在后续步骤失败时回滚。 */
+    const applied = [];
+    for (const name of names) {
+      // 先记下旧值：万一配置没写成功，要把凭据恢复原状，
+      // 否则会出现「凭据存了、配置没存」的半成功状态。
+      const previous = readCredentialFromDsh(name);
+      const result = await writeCredentialToDsh(name, credentialWrites[name]);
+      if (!result.ok) {
+        // 本次之前已经写成功的，一并回滚，避免留下半套改动。
+        for (const done of applied) {
+          try {
+            await writeCredentialToDsh(done.refName, done.previous ?? "");
+          } catch {
+            /* 回滚尽力而为，失败也不能再抛 */
+          }
+        }
+        return {
+          ok: false,
+          patch: ymlPatch,
+          error: `写入 ~/.dsh/.credentials.yaml 失败（${name}）：${result.error}`,
+        };
+      }
+      applied.push({ refName: name, previous });
+    }
+    return { ok: true, patch: ymlPatch, applied };
+  };
+
+  /** 一次决策的完整记录，写入 telemetry.jsonl 便于事后核对。 */
+  const logDecision = async (entry) => recordTelemetry(telemetryDir, entry);
+
+  /**
+   * 写一条「工具授权」的决策明细。
+   *
+   * 为什么授权点要单独一个 helper，而不是复用 `engine.js` 的 `noteDetail`：
+   * 授权是**手写**路径（它要处理 ask / deny 这类改变行为的返回，见
+   * `guardListener` 头部注释），不经过 `createDecisionRunner`，因此拿不到
+   * 引擎里那个闭包。两边写的字段形状必须一致，否则同一个页面上两种记录
+   * 会长得不一样——所以这里按 `buildDecisionRecord` 的签名逐个对齐。
+   *
+   * 任何异常都吞掉：明细是旁路，绝不能让守卫从「降级放行」变成抛错。
+   *
+   * @param options.session - `exec.agent.session`（宿主的 Session 对象）。
+   * @param options.pointMode - 该决策点此刻的三态（observe / enforce）。
+   * @param options.exec - 工具执行现场，提供 `name` 与 `signal`。
+   * @param options.state - 发给决策模型的现场数据。
+   * @param options.questions - 发给决策模型的问题集。
+   * @param options.result - `classify()` 的回包（降级路径可能没有）。
+   * @param options.action / detail / degraded / scores - 裁决那一半。
+   */
+  const recordGuardDetail = (options) => {
+    try {
+      const sessionId = (() => {
+        try {
+          const id = options.session?.id;
+          return typeof id === "string" ? id : "";
+        } catch {
+          return "";
+        }
+      })();
+      const result = options.result;
+      decisionStore.record(
+        buildDecisionRecord({
+          ts: new Date().toISOString(),
+          sessionId,
+          point: "authorize",
+          tag: "guard",
+          mode: options.pointMode,
+          topMode: cfg.mode,
+          provider: typeof result?.provider === "string" ? result.provider : "",
+          model: typeof result?.model === "string" ? result.model : "",
+          action: options.action,
+          detail: options.detail,
+          degraded: options.degraded === true,
+          cached: result?.cached === true,
+          latencyMs: result?.latencyMs,
+          inputTokens: result?.inputTokens,
+          outputTokens: result?.outputTokens,
+          tool: options.exec?.name,
+          ...(options.scores === undefined ? {} : { scores: options.scores }),
+          ...(options.status === undefined ? {} : { status: options.status }),
+          maxContentChars: cfg.decisionsMaxContentChars,
+          content: {
+            state: options.state,
+            questions: options.questions,
+            ...(result?.answers === undefined ? {} : { answers: result.answers }),
+          },
+        }),
+      );
+    } catch (error) {
+      ctx.logger?.warn?.(
+        `dsh-decision-engine: 授权明细写入失败（${error instanceof Error ? error.message : String(error)}）`,
+      );
+    }
+  };
+
+  /**
+   * Layered authorization guard: mandatory policy precedes model advisory.
+   */
+  mountGuard(ctx, {
+    getConfig,
+    reloadOwnConfig,
+    effectivePointModes,
+    client,
+    toleranceCalibrator,
+    digestRecent,
+    previewArguments,
+    logDecision,
+    recordGuardDetail,
+  });
+
+  // ---- 其余八个决策点 ----------------------------------------------------
+  //
+  // 与工具授权不同，这八个点共用一条 execution 链路（engine.js）：模式判断、
+  // 冷却、答案校验、遥测都由 runner.ask() 统一处理，适配器只负责
+  // 「给出 state」与「落地副作用」。这样任何一处降级逻辑都不会漏。
+  const runner = createDecisionRunner({
+    getConfig,
+    client,
+    logger: ctx.logger,
+    modeOf: (current, id) => effectivePointModes(current)[id] ?? "off",
+    log: logDecision,
+    specOf: (id) => POINT_SPECS[id],
+    // 裁决统计必须由引擎在拿到裁决后写盘（裁决此时才存在）。
+    recordDecision: (options) => client.recordDecision(options),
+    /**
+     * 决策明细（「决策历史」页）。与 `log`（遥测）是两条独立旁路：
+     * 遥测是「服务端说了什么」的结论口径，明细是本地的现场 + 会话归属。
+     * 这里补上限指针——截断策略属于存储层，引擎不该知道配置项叫什么。
+     */
+    recordDetail: (record) =>
+      decisionStore.record(
+        buildDecisionRecord({ ...record, maxContentChars: cfg.decisionsMaxContentChars }),
+      ),
+  });
+
+  /** 遥测 + 适配器异常的统一出口（适配器出错必须只留痕、不改行为）。 */
+  const telemetry = {
+    log: logDecision,
+    noteAdapterError(point, error, context) {
+      const message = error instanceof Error ? error.message : String(error);
+      context?.logger?.warn?.(`dsh-decision-engine: ${point} 适配器异常已忽略（${message}）`);
+      void logDecision({
+        ts: new Date().toISOString(),
+        point,
+        tag: `adapter/${point}`,
+        action: "degraded",
+        detail: "adapter-error",
+        extra: { message },
+      });
+    },
+  };
+
+  /** 检索工具名集合：每次现读配置，改了立刻生效。 */
+  const retrievalTools = () => new Set(cfg.retrievalTools ?? DEFAULT_RETRIEVAL_TOOLS);
+
+  /**
+   * 构造一条插件注入的消息。
+   *
+   * `source.kind` 必须是「生产者自有」的 kind（v4 格式拒绝 `plugin` 这种
+   * 已退役的写法），并且要用 `form: 'notice'` + `summary`，这样 UI 会把它
+   * 渲染成一条上下文提示而不是一条用户发言。
+   */
+  const makeUserMessage = (text, kind) => ({
+    id: `decision-engine:${kind}:${Date.now().toString(36)}:${Math.random().toString(36).slice(2, 8)}`,
+    role: "user",
+    content: [{ type: "text", text }],
+    source: { kind: `decision-engine-${kind}`, form: "notice", summary: text.slice(0, 120) },
+  });
+
+  const adapterDeps = {
+    runner,
+    getConfig,
+    telemetry,
+    digestRecent,
+    makeUserMessage,
+    retrievalTools,
+  };
+
+  // 模型路由：agent/request（热路径，内部有三道闸）
+  mountRoutePoint(ctx, adapterDeps);
+  // 分派 / 轮次 / 压缩：agent/pre-step 与 agent/turn-stopping
+  mountAgentPoints(ctx, adapterDeps);
+  // 检索必要性 / 技能选择：tools/pre-execute（按工具名过滤）
+  mountToolPoints(ctx, adapterDeps);
+  // 思维链翻译门槛：包住 translator.translate()
+  const translateMounted = mountCotTranslatePoint(ctx, adapterDeps);
+
+  /**
+   * 某个决策点的适配器是否真的挂上了。
+   *
+   * 挂在 hooks 上的点注册成功即算挂载；翻译点依赖宿主的 translator 服务，
+   * 该服务不存在时挂载会静默失败——配置页必须能看出这一点，否则用户
+   * 会对着一个永远不生效的开关。
+   *
+   * @param id - 决策点 id。
+   * @returns 是否已挂载。
+   */
+  const pointMounted = (id) => {
+    if (id === "cotTranslate") return translateMounted;
+    return true;
+  };
+
+  // ---- 命令：状态、开关、统计、自检 -------------------------------------
+  /** 真正打一次端点并报告结果，用于不依赖工具调用链路的即时验证。 */
+  const probe = async () => {
+    await reloadOwnConfig();
+    // 探测与实际决策必须打同一个目标：两边都走「生效解析」，否则会出现
+    // 「测试通过但守卫不工作」——下发在时探测打服务端、决策也打服务端。
+    const provider = activeProvider();
+    if (!provider.valid) {
+      return { ok: false, text: `配置不可用：${provider.error}\n请检查 provider 与 base URL` };
+    }
+    const endpoint = provider.endpoint;
+    const key = activeKey(provider);
+    if (key === undefined) {
+      return {
+        ok: false,
+        text:
+          `未找到 API key（provider: ${provider.id}）：\n` +
+          // 指名该 provider 自己的那一格（bamboonodeApiKey / siliconflowApiKey /
+          // customApiKey …）。写死 apiKey 会让人把 key 填进 bamboonode 的字段，
+          // 而其它 provider 根本不读它——「填了 key 还是说没 key」就是这么来的。
+          `请在 ${CONFIG_FILE_NAME} 写 ${provider.preset?.keyField ?? "显式 key 字段"}，` +
+          (provider.apiKeyEnv.length > 0
+            ? `或导出 $${provider.apiKeyEnv}（也可存入 .credentials.yaml 的 refs 段）`
+            : `或设置 ${provider.preset?.keyEnvField ?? "密钥变量名"}`),
+      };
+    }
+    const started = Date.now();
+    /**
+     * 探测的**独立预算**：20s 起，不再复用热路径的 `max(5000, timeoutMs)`。
+     *
+     * 为什么必须分开：用户点「测试」时永远是**闲置后的首发**，而冷启动首发
+     * 实测要 7–16 秒——借热路径 8s 预算就等于每次都在最差的采样点上采样，
+     * 于是「测试失败」但实际守卫工作正常。诊断工具不该被热路径预算绑住：
+     * 它的目的就是把真实端点叫醒并报告真实延迟。（同一个文件里给 `/v1/models`
+     * 早已单独开了 20s，probe 这里当初漏了。）
+     *
+     * 为什么是 20s 而不是更大：实测冷启动上界 15.9s，20s 已经覆盖并留了余量。
+     * 探测是个**按钮**，用户盯着转圈等——把它设成 30s 会让最坏等待变成一分钟
+     * （两发各 30s），那是「慢到以为卡死」，比报错更糟。诊断工具要准，但也要
+     * 在人的耐心之内给出结论。
+     */
+    const timeoutMs = Math.max(20000, cfg.timeoutMs);
+    // 与 classify 同一套重试：首发把服务端焐热、第二发通常 1–2 秒返回。
+    const maxAttempts = 2;
+    // 总预算封顶 35s：覆盖「首发 16s 超时 + 第二发 19s」这一最坏组合，
+    // 又不会让按钮在最坏情况下等满两整轮 20s。
+    const maxBudgetMs = Math.min(timeoutMs * 2, 35000);
+    /**
+     * 冷却期的说明**不改变行为**：用户点测试就是想验证端点，拦下来毫无意义。
+     * 但必须说清「这次请求是一次试探」，否则用户会以为守卫此刻已经正常工作。
+     */
+    const cooldownLeftMs = client.cooldownUntil - Date.now();
+    const cooldownText =
+      cooldownLeftMs > 0
+        ? `当前处于冷却中，距冷却结束还有 ${Math.ceil(cooldownLeftMs / 1000)} 秒；本次为试探请求\n`
+        : "";
+    // 探测与实际决策走**同一套**候选顺序与 404 回退：否则会出现
+    // 「测试通过但守卫不工作」或反之。实测 SiliconFlow 只通 /systemone，
+    // 而 /v1/decisions 回 404——只试一条路径必然误报。
+    const bodyText = JSON.stringify(
+      buildRequestBody(provider, {
+        state: { probe: true, cwd: process.cwd() },
+        questions: { alive: { type: "noul", instructions: "Is this request well formed?" } },
+        thinkMode: cfg.thinkMode,
+      }),
+    );
+    const candidates = client.endpointMemory.order(provider.baseUrl, provider.candidates ?? [endpoint]);
+    let usedEndpoint = endpoint;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      // 每次尝试各自一份 timer：上一份已经 abort，复用会让第二发立刻超时。
+      const timer = AbortSignal.timeout(timeoutMs);
+      try {
+        const result = await sendWithEndpointFallback(candidates, (target) => {
+          usedEndpoint = target;
+          // 必须走 `client.fetchFn` 而不是裸 `fetch`：classify 用的就是它，
+          // 注入的 fetch（测试桩 / 宿主定制）对裸 fetch 不可见——那会造出
+          // 「测试通过但实跑不同」的假象，正是本函数要消灭的那类问题。
+          return client.fetchFn(target, {
+            method: "POST",
+            headers: buildHeaders(provider, key),
+            // 与 classify 保持一致：同一个 buildRequestBody，探测不可能与实际
+            // 请求形状不同步（这正是「测试通过但守卫不工作」的经典来源）。
+            body: bodyText,
+            signal: timer,
+          });
+        });
+        const response = result.response;
+        const elapsed = Date.now() - started;
+        // 追踪 id 各家名字不同：bamboonode 走 x-oneapi-request-id，SiliconFlow
+        // 走 x-siliconcloud-trace-id（实测）。只读一家会让另一家的诊断永远显示
+        //「(无)」，而排查问题时这个 id 是唯一的抓手。
+        const requestId =
+          response?.headers?.get?.("x-oneapi-request-id")
+          ?? response?.headers?.get?.("x-siliconcloud-trace-id")
+          ?? "(无)";
+        let bodyTextOut = "";
+        try {
+          bodyTextOut = (await response.text()).slice(0, 300);
+        } catch {
+          /* 忽略 */
+        }
+        // 探测成功即记住胜出的路径：下次决策直接打它。
+        if (response?.ok === true) {
+          const style = styleOfEndpoint(result.endpoint);
+          if (style !== undefined) client.endpointMemory.record(provider.baseUrl, result.endpoint, style);
+        }
+        // 换过路径就要说出来：用户需要知道「实际打的是哪条」。
+        const triedText =
+          result.attempts.length > 1
+            ? `尝试过的路径: ${result.attempts.map((item) => `${item.endpoint} → ${item.status}`).join("，")}\n`
+            : "";
+        return {
+          ok: response?.ok === true,
+          text:
+            `provider: ${provider.label}（${provider.id}）\n` +
+            `POST ${result.endpoint}\n` +
+            cooldownText +
+            `model: ${(provider.model ?? "").trim().length > 0 ? provider.model : "自动（服务端默认）"}\n` +
+            `HTTP ${response?.status ?? "(无响应)"}　耗时 ${elapsed}ms\n` +
+            `x-oneapi-request-id: ${requestId}\n` +
+            (triedText.length > 0 ? `${triedText}` : "") +
+            `响应: ${bodyTextOut}`,
+        };
+      } catch (error) {
+        const reason = timer.aborted || error?.name === "AbortError" ? "timeout" : "network-error";
+        if (
+          shouldRetry({
+            reason,
+            attempt,
+            elapsedMs: Date.now() - started,
+            timeoutMs,
+            maxAttempts,
+            maxBudgetMs,
+          })
+        ) {
+          continue;
+        }
+        // 失败原因翻译成人话：`error.message` 只有 "fetch failed" / "The operation
+        // was aborted"，用户据此既不知道该改什么，也分不清是本机链路还是服务端。
+        // describeFailure 给出「标题 + 可执行下一步」，与 classify 侧同一套文案。
+        const failure = describeFailure(reason, {
+          timeoutMs,
+          endpoint: usedEndpoint,
+          message: error instanceof Error ? error.message : String(error),
+        });
+        return {
+          ok: false,
+          text:
+            `provider: ${provider.label}（${provider.id}）\n` +
+            `POST ${usedEndpoint}\n` +
+            cooldownText +
+            `请求失败（${Date.now() - started}ms）: ` +
+            `${error instanceof Error ? error.message : String(error)}\n` +
+            `失败原因: ${failure.title}\n` +
+            `建议: ${failure.hint}`,
+        };
+      }
+    }
+    // 理论上到不了这里（循环每次都以 return 或 continue 结束），保持返回值完整。
+    return { ok: false, text: `provider: ${provider.label}（${provider.id}）\nPOST ${usedEndpoint}\n请求失败（${Date.now() - started}ms）` };
+  };
+
+  // ---- 面板 API：给前端 UI 用（不经过 settings 服务）-------------------------
+  ctx.inject?.(["connection"], () => {
+    const connection = ctx.get?.("connection");
+    if (connection === undefined || typeof connection.fetch?.register !== "function") return;
+
+    const json = (data, status = 200) =>
+      Promise.resolve(
+        new Response(JSON.stringify(data), {
+          status,
+          headers: { "content-type": "application/json", "cache-control": "no-store" },
+        }),
+      );
+
+    /**
+     * 把「密钥来源」翻成用户能核对的一句话。
+     *
+     * 为什么不让前端自己拼：界面只知道变量名（`BAMBOO_API_KEY`），
+     * 不知道真正命中的是配置文件里的哪一格。只显示变量名会造成误判——
+     * 用户看到 `BAMBOO_API_KEY` 会以为 key 在 `.credentials.yaml` 里，
+     * 而实际生效的可能是 `config.yml` 的 `bamboonodeApiKey`，甚至以为
+     * 那个变量「过期了」。来源判定与文案因此都放在服务端，只有一份真相。
+     *
+     * @param source - config / credentials / env / server / none。
+     * @param provider - 已解析的 provider（提供 keyField 与 apiKeyEnv）。
+     * @returns 可直接展示的中文说明。
+     */
+    const keySourceLabel = (source, provider) => {
+      // 服务端下发（DEC-030）：文案必须把「只在内存」说死——用户开这个开关
+      // 前最想确认的就是「我的机器上会不会多出一份别人的明文 key」。
+      if (source === "server") {
+        return "服务端下发";
+      }
+      if (source === "config") {
+        const field = provider.preset?.keyField ?? "显式 key 字段";
+        return `配置文件 ${CONFIG_FILE_NAME} 的 ${field}`;
+      }
+      if (source === "credentials") {
+        return `~/.dsh/.credentials.yaml 的 ${provider.apiKeyEnv}`;
+      }
+      if (source === "env") {
+        return `环境变量 ${provider.apiKeyEnv}`;
+      }
+      return "未配置";
+    };
+
+    /**
+     * 汇总三个 provider 各自的 key 状态。
+     *
+     * 只回报「有没有」「从哪来的」「末四位」，绝不回传明文——
+     * 这份 JSON 会经过浏览器，明文 key 不应出现在网络响应里。
+     *
+     * @returns id → `{ configured, hint, source, refName, sourceLabel }`。
+     */
+    const buildKeyStatus = () => {
+      const out = {};
+      for (const id of PROVIDER_IDS) {
+        const probe = resolveProvider({ ...cfg, provider: id });
+        const key = resolveKey({ ...cfg, provider: id }, probe);
+        const inCredentials =
+          probe.apiKeyEnv.length > 0 && readCredentialFromDsh(probe.apiKeyEnv) !== undefined;
+        const source =
+          probe.explicitKey.length > 0
+            ? "config"
+            : inCredentials
+              ? "credentials"
+              : key === undefined
+                ? "none"
+                : "env";
+        out[id] = {
+          configured: key !== undefined,
+          hint: key === undefined ? "" : `…${key.slice(-4)}`,
+          refName: probe.apiKeyEnv,
+          // 该 provider 的显式 key 字段名：`keyStorage=config` 时保存的目标。
+          // 与 refName（凭据文件/环境变量的变量名）是两个不同的位置，
+          // 界面上必须分开说，否则「存到插件配置的 BAMBOO_API_KEY」这种
+          // 自相矛盾的文案就会出现。
+          keyField: probe.preset?.keyField ?? "",
+          // explicit = 配置里写了明文；credentials = 凭据文件；env = 环境变量
+          source,
+          // 给界面直接用的可读来源。**必须由服务端算**：只有这里同时知道
+          // provider 的显式字段名（bamboonodeApiKey）与真正命中的来源。
+          //
+          // 早先界面只显示 `apiKeyEnv`（如 BAMBOO_API_KEY），在
+          // keyStorage=config 时会造成严重误解——那个变量根本没被读取，
+          // 用户会以为 key 存在 .credentials.yaml 里，甚至以为它过期了。
+          sourceLabel: keySourceLabel(source, probe),
+        };
+      }
+      return out;
+    };
+
+    /**
+     * 人工审核比例（DEC-035）的完整回显——**两处界面共用这一份**。
+     *
+     * 配置页（走 /status 与 /decisions）与「决策历史」页（走 /session-decisions）
+     * 都要放这个滑块。若各自拼一份，加一档或改一个文案就得改三处，漏一处就是
+     * 「同一个设置在两个页面显示不一样」。
+     *
+     * 四档的元数据（label / summary / percentile）由服务端下发，前端不抄一份
+     * ——与决策点清单一同理：加一档只改 lib/tolerance.js 一处。
+     *
+     * calibration 回答「这个模型最近攒了多少样本」：用户切到轻松档却还没攒够
+     * 样本时，界面要能说明「现在用的是冷启动阈值，攒够后按该模型自己的分布算」，
+     * 否则看起来就像设置没生效。
+     *
+     * @returns 冻结形状：{ level, levels, presets, calibration }。
+     */
+    const tolerancePayload = () => {
+      const level = cfg.tolerance ?? DEFAULTS.tolerance;
+      const active = activeProvider();
+      const stats = toleranceCalibrator.stats(active.id, active.model);
+      const preset = tolerancePreset(level);
+      const threshold =
+        preset.percentile === null
+          ? null
+          : toleranceCalibrator.threshold(active.id, active.model, preset.percentile);
+      return {
+        level,
+        levels: TOLERANCE_LEVELS,
+        presets: TOLERANCE_LEVELS.map((id) => {
+          const item = TOLERANCE_PRESETS[id];
+          return {
+            id: item.id,
+            label: item.label,
+            labelEn: item.labelEn,
+            summary: item.summary,
+            summaryEn: item.summaryEn,
+            percentile: item.percentile,
+          };
+        }),
+        calibration: {
+          provider: active.id,
+          model: active.model,
+          samples: stats.samples,
+          ready: stats.ready,
+          minSamples: toleranceCalibrator.minSamples,
+          windowSize: toleranceCalibrator.windowSize,
+          threshold: threshold === null ? null : Number(threshold.toFixed(4)),
+          // 未校准好时实际生效的绝对阈值（界面要如实说明「现在用的是它」）。
+          fallbackSeverity: preset.fallbackSeverity,
+        },
+      };
+    };
+
+    /** 汇总当前状态；key 只回报“是否已配置”与末四位，绝不回传明文。 */
+    const statusPayload = () => {
+      // 两条解析路径在这里分叉（DEC-030）：
+      //
+      //   - **本地**（provider.id / providerLabel / providerSource / raw* /
+      //     custom*）：前端把它们写回 config.yml。它们若被下发值污染上线
+      //     就危险了——面板会把 `provider: server` 提交回来，而
+      //     `validateProviderPatch` 只认 PROVIDER_IDS，12 秒后就是一次 400
+      //     「未知 provider」。所以本地三元组永远照实报本地选择。
+      //   - **生效值**（baseUrl / model / keyConfigured / keyHint / keySource）：
+      //     前端显示「实际打到哪、用哪把 key」。服务端生效时这些必须是下发值，
+      //     否则界面会一边说「走 systemone」一边把请求打到别处。
+      const local = resolveProvider(cfg);
+      const server = serverOverride();
+      const provider = server !== undefined ? resolveProvider(cfg, { server }) : local;
+      const key = resolveKey(cfg, provider, { memoryKey: server?.key });
+      return {
+        enabled: cfg.enabled,
+        mode: cfg.mode,
+        guardEnabled: cfg.guardEnabled !== false,
+        guardPolicyMode: cfg.guardPolicyMode,
+        guardFallback: cfg.guardFallback,
+        guardFallbackProvider: cfg.guardFallbackProvider,
+        guardFallbackModel: cfg.guardFallbackModel,
+        guardFallbackReasoningEffort: cfg.guardFallbackReasoningEffort,
+        // provider 三元组：前端据此渲染选择器与 custom 表单，回显也靠它。
+        provider: local.id,
+        providerLabel: local.label,
+        providerSource: local.source,
+        providerValid: provider.valid,
+        providerError: provider.error ?? "",
+        providerCatalog: providerCatalog(),
+        baseUrl: provider.endpoint || provider.baseUrl,
+        rawBaseUrl: provider.baseUrl,
+        // 只回报「实际会发什么」。预设的默认模型单独放 defaultModel：
+        // 把预设默认值显示成当前模型，会让人以为插件固定了模型（其实没发字段）。
+        model: provider.model || "(服务端默认)",
+        defaultModel: provider.defaultModel,
+        rawModel: provider.model,
+        rawSystemoneModel: typeof cfg.systemoneModel === "string" ? cfg.systemoneModel : "",
+        rawSiliconflowModel: typeof cfg.siliconflowModel === "string" ? cfg.siliconflowModel : "",
+        rawSiliconflowIntlModel:
+          typeof cfg.siliconflowIntlModel === "string" ? cfg.siliconflowIntlModel : "",
+        /**
+         * 全部 provider 的模型原值，键 = config.yml 里的字段名（model /
+         * systemoneModel / siliconflowModel / …）。
+         *
+         * 上面几项是历史散字段（回显用），这张表是给「模型输入框写回配置」用的：
+         * 界面必须知道当前 provider 的那一格叫什么名字，而名字只有预设表知道。
+         * 由预设表生成并下发，前端就不必为每个 provider 抄一份分支——新增预设
+         * 只改 providers.js 一处，界面的模型框自动接上。
+         *
+         * 值取 cfg 原文而非 provider.model：后者对 requiresModel 的 provider
+         * 已经回落到预设默认（Kev-4B），把它回显成「当前值」会让用户以为自己
+         * 填过模型，进而不知道留空本来就有默认。
+         */
+        rawModels: Object.fromEntries(
+          Object.values(PROVIDER_PRESETS).map((preset) => [
+            preset.modelField,
+            typeof cfg[preset.modelField] === "string" ? cfg[preset.modelField] : "",
+          ]),
+        ),
+        // custom 的字段原样回显（除 key 明文）：用户保存后再打开必须看到自己填的值。
+        customBaseUrl: cfg.customBaseUrl ?? "",
+        customEndpointStyle: cfg.customEndpointStyle ?? "auto",
+        // 实际用得通的那条路径（探测出来的）。路径后缀由服务商决定，
+        // 实测 SiliconFlow 只通 /systemone；界面必须显示「实际打哪」，
+        // 否则用户看到 404 完全猜不到是路径选错了。
+        detectedEndpoint: client.endpointMemory.get(provider.baseUrl)?.endpoint ?? "",
+        detectedEndpointStyle: client.endpointMemory.get(provider.baseUrl)?.style ?? "",
+        customModel: cfg.customModel ?? "",
+        customHeaders: cfg.customHeaders ?? "",
+        customApiKeyEnv: cfg.customApiKeyEnv ?? "",
+        customKeyConfigured:
+          typeof cfg.customApiKey === "string" && cfg.customApiKey.trim().length > 0,
+        // 密钥保存位置：界面据此显示「当前存到哪」以及切换后的实际行为。
+        keyStorage: cfg.keyStorage ?? "credentials",
+        // 各 provider 是否已配好 key（不泄露明文，只回报布尔与来源）。
+        // 三个预设各自独立，切换时界面能准确显示"这一项有没有 key"。
+        keyStatus: buildKeyStatus(),
+        // 思考模式：回传归一化后的值，避免界面把 `thinkMode: sometimes`
+        // 原样回显成「已生效」；可选清单由服务端下发，前端不硬编码。
+        thinkMode: normalizeThinkMode(cfg.thinkMode),
+        thinkModes: THINK_MODES,
+        // 匿名统计档位：**必须回显**。
+        //
+        // 此前这里没有这一项，于是配置页的「匿名统计」下拉永远停在兜底值
+        // `daily`，用户改成 `off` 既不落盘、重新打开也看不到自己的选择。
+        // 隐私开关显示一个与实际不符的状态，比没有这个开关更糟。
+        telemetryLevel: cfg.telemetryLevel ?? DEFAULTS.telemetryLevel,
+        telemetryLevels: TELEMETRY_LEVELS,
+        timeoutMs: cfg.timeoutMs,
+        keyConfigured: key !== undefined,
+        keyHint: key === undefined ? "" : `…${key.slice(-4)}`,
+        // 来源要报**真正生效的那个**（DEC-030）：服务端下发一旦生效，
+        // 本地配置里那把 key 就没有参与本次解析。照旧报 "config" 会让
+        // 界面说「密钥来自 config.yml 的 xxx」，而用户明明没往那儿填过。
+        keySource:
+          server !== undefined
+            ? "server"
+            : provider.explicitKey.length > 0
+              ? "config"
+              : provider.apiKeyEnv.length > 0 && readCredentialFromDsh(provider.apiKeyEnv) !== undefined
+                ? "credentials"
+                : "env",
+        keyEnvName: provider.apiKeyEnv,
+        configPath: ownConfigPath,
+        // 决策历史（DEC-022）：配置页的回显、以及客户端「是否挂载 tab」的
+        // 唯一依据。**必须回传生效值而不是原值**——配置里可能根本没写这一项
+        // （用 DEFAULTS 的 true），原样回 `undefined` 会让界面把开关画成关。
+        decisionsTabEnabled: cfg.decisionsTabEnabled !== false,
+        // 审批卡正文可读化（DEC-042 / DEC-043）：客户端据此决定是否接管宿主的
+        // detail slot。同样回传**生效值**——配置里没写这一项时，DEFAULTS 的 true
+        // 才是真值；回 `undefined` 会让界面把开关画成关。
+        approvalDetailReadable: cfg.approvalDetailReadable !== false,
+        decisionsFile: decisionStore.path,
+        // 人工审核比例（DEC-035）：配置页滑块的唯一数据源。
+        tolerance: tolerancePayload(),
+        stats: client.stats,
+        // 决策点与缓存：配置页靠这两项显示「哪个点在花多少钱」。
+        points: effectivePointModes(cfg),
+        cache: client.cache.report,
+        /**
+         * 服务端下发（DEC-030）的完整状态。
+         *
+         * 形状是**冻结契约**（前端 lib/client.js 按字段名消费），因此这里
+         * 逐字段拼出来而不是把 `serverConfig.status()` 整个摊开：摊开会把
+         * 将来新增的内部字段（例如重试计数）也一并送进浏览器，而这份 JSON
+         * 的读者只有设置页。
+         *
+         * 注意 `enabled` 来自配置、`active` 来自「开关 × 有效期」两个闸：
+         * 界面靠 enabled 画开关、靠 active 决定「生效端点」行要不要打角标。
+         * 两者不一致正是回落发生的那一刻，这个区别必须能显示出来，
+         * 否则用户看到一个开着的开关 + 本地地址，会以为功能坏了。
+         */
+        serverProvider: (() => {
+          const state = serverConfig.status();
+          const enabled = cfg.serverProvider === true;
+          return {
+            enabled,
+            active: enabled && state.usable,
+            endpoint: SERVER_CONFIG_ENDPOINT,
+            label: SERVER_PROVIDER_LABEL,
+            status: state.status,
+            usable: state.usable,
+            // 曾经取到过值之后又失败：错误文案要能说明「是回落了，不是从没开过」。
+            error: enabled ? state.error : "",
+            // 只有末四位：这是本插件对 key 暴露面的既有上限（见 buildKeyStatus）。
+            keyHint: state.keyHint,
+            baseUrl: state.baseUrl,
+            model: state.model,
+            endpointStyle: state.endpointStyle,
+            fetchedAt: state.fetchedAt,
+            expiresAt: state.expiresAt,
+            expired: state.expired,
+          };
+        })(),
+      };
+    };
+
+    connection.fetch.register({
+      path: "/api/decision-engine/status",
+      methods: ["GET"],
+      requestBody: "buffered",
+      fetch: async () => {
+        await reloadOwnConfig();
+        // 打开着而手上没有可用值：顺带补一发（不 await，界面不等网络）。
+        // 放在这里而不是只放启动时，是因为「刚打开面板」正是发现配置过期的
+        // 最好时机——用户就在等这个页面。
+        if (cfg.serverProvider === true && !serverConfig.usable()) void serverConfig.refresh();
+        return json(statusPayload());
+      },
+    });
+
+    /**
+     * 强制刷新下发配置（DEC-030）。
+     *
+     * 为什么要一条单独的路由：保存配置时服务端按 TTL 决定拉不拉（没过期就
+     * 复用缓存），而用户点「重新获取」表达的是「现在就要一份新的」。
+     * 返回形状与 `/status` 相同，前端直接走 `applyServerState`，草稿与服务端
+     * 状态一次对齐，不会出现「界面显示旧值、服务端已是新值」。
+     */
+    connection.fetch.register({
+      path: "/api/decision-engine/server-provider",
+      methods: ["POST"],
+      requestBody: "buffered",
+      fetch: async () => {
+        await reloadOwnConfig();
+        // force：绕过 30s 重试下限——用户明确要求了，就真的去试一次。
+        await serverConfig.refresh({ force: true });
+        return json({ ok: true, ...statusPayload() });
+      },
+    });
+
+    connection.fetch.register({
+      path: "/api/decision-engine/config",
+      methods: ["PUT"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        try {
+          const body = JSON.parse(await request.text());
+          // 只允许改这些键，避免前端误写任意字段。
+          //
+          // 各 provider 自己的三格（模型 / 显式 key / 密钥变量名）由预设表生成，
+          // 不逐个写死：漏掉一个 provider，界面上「粘贴 key / 选模型」会 200
+          // 成功但什么都没写——正是最难自查的「保存了没生效」。
+          const allowed = [
+            "enabled",
+            "mode",
+            "guardEnabled",
+            "pointAuthorize",
+            "guardPolicyMode",
+            "guardFallback",
+            "guardFallbackProvider",
+            "guardFallbackModel",
+            "guardFallbackReasoningEffort",
+            "apiKey",
+            "baseUrl",
+            "thinkMode",
+            "timeoutMs",
+            // 匿名统计档位（DEC-020）。
+            //
+            // 它此前**不在这个白名单里**，于是配置页上那个「匿名统计」下拉
+            // 能点、能显示、点完还显示「已保存」——但后端 400「no updatable
+            // fields」，值从来没落盘。用户以为关掉了统计，实际每天照发。
+            // 隐私开关静默失效是这类问题里最严重的一种，所以这里补上。
+            "telemetryLevel",
+            // 人工审核比例（DEC-035）。与 telemetryLevel 同一类风险：不在白名单里的
+            // 后果是「面板能拨、显示已保存、值却从来没落盘」——用户以为改成了
+            // 自治，实际还在被反复打扰。这类静默失效必须在白名单里堵死。
+            "tolerance",
+            // 决策历史（DEC-022）：只有「决策历史」这一个开关。
+            // `decisionsCapture` 已退役——开关开着就记明细且一定带内容，
+            // 开关关掉就什么都不写，不存在「只记元数据」的第二档。
+            // **上限项刻意不在白名单里**——那两个是运维旋钮（改体积上限、
+            // 改截断长度），不是用户日常会拨的开关，走配置页会把界面变复杂；
+            // 需要时手改 config.yml 即可。
+            "decisionsTabEnabled",
+            // 审批卡正文可读化（DEC-042）：配置页要能拨，否则拨了也存不下去。
+            "approvalDetailReadable",
+            // 服务端下发开关（DEC-030）：不在白名单里的后果与上面 telemetryLevel
+            // 完全一样——面板能拨、能显示「已保存」，而服务端 400 什么都没写。
+            "serverProvider",
+            "provider",
+            "customBaseUrl",
+            "customEndpointStyle",
+            "customHeaders",
+            "keyStorage",
+            ...Object.values(PROVIDER_PRESETS).flatMap((preset) => [
+              preset.modelField,
+              preset.keyField,
+              preset.keyEnvField,
+            ]),
+          ];
+          const patch = {};
+          for (const key of allowed) {
+            if (Object.hasOwn(body, key)) patch[key] = body[key];
+          }
+          if (Object.keys(patch).length === 0) return json({ error: "no updatable fields" }, 400);
+
+          // 校验在落盘之前：写进 yml 再报错等于让用户带着坏配置重启。
+          const checked = validateProviderPatch(patch, cfg);
+          if (!checked.ok) return json({ error: checked.error }, 400);
+
+          // key 按 provider 分开存，各自落到「用户选的位置」。
+          // 先处理 key 再写 yml：写入凭据文件可能失败（权限/磁盘），
+          // 失败时必须整体报错回滚，不能让"配置说存了、实际没存"。
+          const keyResult = await persistKeys(patch, cfg);
+          if (!keyResult.ok) return json({ error: keyResult.error }, 500);
+          // key 已被写进指定位置的，不能同时再写进 yml（会变成两处明文）。
+          const ymlPatch = { ...keyResult.patch };
+
+          try {
+            await persistConfig(ymlPatch);
+          } catch (error) {
+            // 配置没写成功，就把已落地的凭据恢复原状：宁可整体失败，
+            // 也不要留下「凭据存了、配置没存」的半套状态——那种状态在
+            // 界面上看起来是保存失败，实际 key 已经悄悄换了。
+            for (const done of keyResult.applied ?? []) {
+              try {
+                await writeCredentialToDsh(done.refName, done.previous ?? "");
+              } catch {
+                /* 回滚尽力而为 */
+              }
+            }
+            return json(
+              {
+                error:
+                  `写入配置文件失败：${error instanceof Error ? error.message : String(error)}` +
+                  (keyResult.applied?.length > 0 ? "（已回滚本次写入的凭据）" : ""),
+              },
+              500,
+            );
+          }
+          return json({ ok: true, ...statusPayload() });
+        } catch (error) {
+          return json({ error: error instanceof Error ? error.message : String(error) }, 500);
+        }
+      },
+    });
+
+    /**
+     * 决策点总览与切换。
+     *
+     * GET  返回注册表 + 当前模式 + 分账实测数据。
+     * PUT  改模式。
+     *
+     * 合成一个注册项按 method 分支，而不是同路径注册两次：
+     * DSH 的 fetch 注册表以 path 为键，重复注册会互相覆盖（实测踩过）。
+     *
+     * 元数据由服务端下发而不是前端硬编码，是为了让「加了哪个决策点」
+     * 只改一处（decision-points.js）。未实装的点显示为「即将支持」而不是
+     * 消失，避免用户以为功能被删了。
+     */
+    const decisionsPayload = () => {
+      const modes = effectivePointModes(cfg);
+      return {
+        points: DECISION_POINTS.map((point) => {
+          const counter = client.pointCounter(point.id);
+          return {
+            id: point.id,
+            key: point.key,
+            hook: point.hook,
+            hotPath: point.hotPath,
+            available: point.available,
+            trigger: point.trigger,
+            label: point.label,
+            labelEn: point.labelEn,
+            summary: point.summary,
+            saving: point.saving,
+            gate: point.gate,
+            mode: modes[point.id] ?? "off",
+            configured: cfg[point.key],
+            // 「这个点的适配器到底挂上了没有」必须能看见：装进一个没有
+            // translator 服务的宿主时，开关能打开但永远不会生效，
+            // 不显示真实挂载状态就会变成「配了没反应」。
+            mounted: pointMounted(point.id),
+            stats: {
+              requests: counter.requests,
+              cached: counter.cached,
+              degraded: counter.degraded,
+              ok: counter.ok,
+              tokens: counter.tokens,
+              avgLatencyMs: counter.ok === 0 ? 0 : Math.round(counter.latencySum / counter.ok),
+              maxLatencyMs: counter.latencyMax,
+            },
+          };
+        }),
+        modes: POINT_MODES,
+        cache: client.cache.report,
+        // 人工审核比例（DEC-035）：与配置页共用同一份元数据。
+        tolerance: tolerancePayload(),
+      };
+    };
+
+    connection.fetch.register({
+      path: "/api/decision-engine/decisions",
+      methods: ["GET", "PUT"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        try {
+          if (request.method === "GET") {
+            await reloadOwnConfig();
+            return json(decisionsPayload());
+          }
+          const body = JSON.parse(await request.text());
+          const patch = {};
+          const requested = body.points;
+          if (requested !== null && typeof requested === "object") {
+            for (const [id, mode] of Object.entries(requested)) {
+              const point = DECISION_POINTS.find((item) => item.id === id);
+              if (point === undefined) continue;
+              // off/observe/enforce/auto 之外的值一律拒绝，避免脏配置进 yml。
+              if (![...POINT_MODES, "auto"].includes(mode)) {
+                return json({ error: `invalid mode for ${id}: ${String(mode)}` }, 400);
+              }
+              if (!point.available && mode !== "off") {
+                return json({ error: `decision point ${id} is not implemented yet` }, 400);
+              }
+              // 适配器没挂上时也拒绝开启：否则用户会配出一个「看起来生效、
+              // 实际永不触发」的开关（例如宿主没有 translator 服务）。
+              if (mode !== "off" && !pointMounted(point.id)) {
+                return json(
+                  { error: `decision point ${id} is unavailable in this host: its service is not mounted` },
+                  400,
+                );
+              }
+              patch[point.key] = mode;
+            }
+          }
+          if (Object.keys(patch).length === 0) return json({ error: "no updatable fields" }, 400);
+          await persistConfig(patch);
+          // 立即回一份新的总览，前端不必再发一次 GET。
+          return json({ ok: true, ...decisionsPayload() });
+        } catch (error) {
+          return json({ error: error instanceof Error ? error.message : String(error) }, 500);
+        }
+      },
+    });
+
+    /**
+     * 列出可用于**决策端点**的模型。
+     *
+     * 不能把 `/v1/models` 原样交给用户选：bamboonode 的该端点返回全部 20 个
+     * 模型，其中多数是 chat 模型，拿去打 `/v1/decisions` 会 400
+     *「model ... is not served by this plugin」。因此按 `supported_endpoint_types`
+     * 过滤——只有声明了 `StartLux Decision` / `StartLux SystemOne` 的才是决策端点
+     * 真正接受的。bamboonode 作为预设**严格**适用这条：没声明类型的一律排除。
+     *
+     * 对 custom：指向的是**用户自己的服务**，类型声明不可信——很多网关只声明
+     * `chat` / `openai` 之类，按 StartLux 类型过滤会把整份列表清空，下拉里只剩
+     * 「自动」。因此 custom 不做类型过滤，模型清单交还给用户自己判断；
+     * 请求本身仍有 404/400 回退与降级兜底。
+     *
+     * 对 systemone：自建服务的 `/v1/models` 未必带
+     * `supported_endpoint_types`，此时若继续按类型过滤会得到空列表，用户会以为
+     * 「服务没有可用模型」。因此改为「有类型就按类型过滤，没类型就全收」，
+     * 并把过滤与否回报给前端说明。
+     */
+    connection.fetch.register({
+      path: "/api/decision-engine/guard-models",
+      methods: ["GET"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        const url = new URL(request.url);
+        return json(await guardModelCatalog(ctx.get?.("llm"), url.searchParams.get("provider"), url.searchParams.get("model")));
+      },
+    });
+
+    connection.fetch.register({
+      path: "/api/decision-engine/models",
+      methods: ["GET"],
+      requestBody: "buffered",
+      fetch: async () => {
+        const provider = resolveProvider(cfg);
+        if (!provider.valid) return json({ models: [], error: "bad-endpoint", hint: provider.error });
+        const key = resolveKey(cfg, provider);
+        if (key === undefined) return json({ models: [], error: "no-key" });
+
+        // /v1/models 是 OpenAI 兼容路径：由 base URL 反推 origin。
+        // 刻意用 provider.baseUrl 而不是 endpoint：端点可能已经带
+        // /decisions 或 /systemone，取 origin 才不会拼出 /decisions/v1/models。
+        let origin;
+        try {
+          const url = new URL(provider.baseUrl);
+          origin = `${url.protocol}//${url.host}`;
+        } catch {
+          return json({ models: [], error: "bad-endpoint", hint: provider.error });
+        }
+
+        try {
+          const response = await fetch(`${origin}/v1/models`, {
+            headers: buildHeaders(provider, key),
+            // 列表接口比决策接口慢（实测数秒），且只在用户打开配置页时调用一次，
+            // 用独立超时，不占用决策路径的 timeoutMs。
+            signal: AbortSignal.timeout(20000),
+          });
+          if (!response.ok) {
+            const hint =
+              response.status === 401 || response.status === 403
+                ? `鉴权被拒（HTTP ${response.status}）：检查 ${provider.id} 的 API key`
+                : `模型列表请求失败（HTTP ${response.status}）`;
+            return json({ models: [], error: `http-${response.status}`, hint });
+          }
+          const body = await response.json();
+          const rows = Array.isArray(body?.data) ? body.data : [];
+          // 只认 StartLux 系端点类型。实测 `typesafe/jev-1.14` 虽声明
+          // `jev-decisions`，打到本插件的 /v1/decisions 仍会 400
+          //「model ... is not served by this plugin」——它对应的是另一个端点，
+          // 放进下拉会让用户选了就失败，因此排除。
+          const decisionTypes = ["StartLux Decision", "StartLux SystemOne"];
+          const typedOnly = provider.id === "bamboonode";
+          // custom 不做类型过滤（理由见上方路由说明）。
+          const skipTypeFilter = provider.id === "custom";
+          // 预设给了 knownModels 的 provider（SiliconFlow 实测）：它的
+          // /v1/models 会一并返回 98 个模型，其中决策模型只有 Kev-4B / SemIf，
+          // 且**没有任何一条**带 supported_endpoint_types——按类型过滤会得到
+          // 空列表，全收则把 96 个 chat 模型塞进下拉，选一个就是一个 400
+          // `Model does not exist.`。这类端点只认预设清单里的名字。
+          const knownModels = provider.preset?.knownModels ?? [];
+          const models = [];
+          for (const row of rows) {
+            const id = typeof row?.id === "string" ? row.id : "";
+            if (id.length === 0) continue;
+            if (knownModels.length > 0) {
+              if (!knownModels.some((name) => name.toLowerCase() === id.toLowerCase())) continue;
+              models.push({ id, types: [] });
+              continue;
+            }
+            const types = Array.isArray(row?.supported_endpoint_types) ? row.supported_endpoint_types : [];
+            const isDecision = types.some((type) =>
+              decisionTypes.some((needle) => String(type).toLowerCase() === needle.toLowerCase()),
+            );
+            // bamboonode：没声明类型的一律排除（它会 400）。
+            // custom：一律全收（见上方说明）。
+            // 其它 provider：只在「有人声明类型」时才按类型过滤，否则全收。
+            if (typedOnly) {
+              if (!isDecision) continue;
+            } else if (!skipTypeFilter && types.length > 0 && !isDecision && provider.endpointStyle !== "systemone") {
+              continue;
+            }
+            models.push({ id, types });
+          }
+          return json({
+            models,
+            current: provider.model,
+            defaultHint: provider.defaultModel || DEFAULT_MODEL,
+            provider: provider.id,
+            filtered: typedOnly || knownModels.length > 0,
+          });
+        } catch (error) {
+          return json({
+            models: [],
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      },
+    });
+
+    connection.fetch.register({
+      path: "/api/decision-engine/test",
+      methods: ["POST"],
+      requestBody: "buffered",
+      fetch: async () => {
+        const result = await probe();
+        return json({ ok: result.ok, text: result.text });
+      },
+    });
+
+    /**
+     * 统计与对比。
+     *
+     * 查询参数：
+     *   - `preset`  today | week | month | year | custom（默认 today）
+     *   - `start`   自定义起始（`YYYY-MM-DDTHH:mm`）
+     *   - `end`     自定义结束（`YYYY-MM-DDTHH:mm`）
+     *   - `sort`    排序字段（默认 inputTokens）
+     *   - `dir`     asc | desc（默认 desc）
+     *   - `includeLegacy`  是否把旧遥测回填成历史统计（默认 1）
+     *
+     * 回填只在**统计文件为空**时做一次（首次访问）：回填结果不落盘，
+     * 每次请求都重新算一遍历史遥测会拖慢响应，而且回填记录本身也没法
+     * 与真实记录区分。
+     */
+    connection.fetch.register({
+      path: "/api/decision-engine/stats",
+      methods: ["GET"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        await reloadOwnConfig();
+        const params = new URL(request.url).searchParams;
+        const range = resolveRange({
+          preset: params.get("preset") ?? "today",
+          start: params.get("start") ?? undefined,
+          end: params.get("end") ?? undefined,
+        });
+        if (range.valid !== true) {
+          return json({ error: range.error, range: { preset: range.preset, valid: false } }, 400);
+        }
+        let records = [];
+        try {
+          records = await statsStore.read();
+        } catch {
+          records = [];
+        }
+        // 历史回填在**启动时**做完了（并落盘），这里直接读统计文件即可。
+        // 若它还没跑完（插件刚启动、用户立刻打开统计页），补一次即可。
+        if (records.length === 0) {
+          try {
+            await statsStore.backfillOnce();
+            records = await statsStore.read();
+          } catch {
+            records = [];
+          }
+        }
+        // 推算出来的历史条数（老遥测缺 provider 与 output token）。
+        const legacyCount = records.filter((row) => row.estimated === true).length;
+        const result = aggregate(records, range);
+        const sortKey = params.get("sort") ?? "inputTokens";
+        const direction = params.get("dir") === "asc" ? "asc" : "desc";
+        return json({
+          ...result,
+          rows: sortRows(result.rows, sortKey, direction),
+          byProvider: sortRows(result.byProvider, sortKey, direction),
+          // 范围预设与标签由服务端下发：前端不抄一份清单，避免两边漂移。
+          presets: RANGE_PRESETS,
+          labels: RANGE_LABELS,
+          // 历史数据说明：回填的记录 provider 由模型名反推（可能不准），
+          // 仍缺 output token 与耗时基线，界面必须让用户知道「这一段数字是
+          // 推算的」，否则会被当成实测。
+          legacy: {
+            included: legacyCount > 0,
+            count: legacyCount,
+            note: legacyCount > 0
+              ? "含由旧遥测推算的历史数据（provider 按模型名推断，output token 与耗时基线为推算值）"
+              : "",
+          },
+          store: {
+            path: statsStore.path,
+            written: statsStore.written,
+            failed: statsStore.failed,
+            dropped: statsStore.dropped,
+          },
+        });
+      },
+    });
+
+    connection.fetch.register({
+      path: "/api/decision-engine/log",
+      methods: ["GET"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        const limit = Number(new URL(request.url).searchParams.get("limit") ?? "50");
+        const count = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 200) : 50;
+        let raw = "";
+        try {
+          raw = await readFile(join(telemetryDir, "telemetry.jsonl"), "utf8");
+        } catch {
+          return json([]);
+        }
+        const entries = [];
+        for (const line of raw.split("\n").slice(-400)) {
+          const trimmed = line.trim();
+          if (trimmed.length === 0) continue;
+          try {
+            entries.push(JSON.parse(trimmed));
+          } catch {
+            /* 半行跳过 */
+          }
+        }
+        return json(entries.slice(-count).reverse());
+      },
+    });
+
+    /**
+     * 某个会话的决策明细（「决策历史」标签页的数据源）。
+     *
+     * 与 `/log` 的区别不是路径而是**口径**：
+     *
+     *   - `/log` 读的是 telemetry.jsonl（全机、无会话维度、只有结论）；
+     *   - 这里读的是 decisions.jsonl（有会话归属、有决策内容、按体积轮转）。
+     *
+     * `sessionId` 是**必填**的：没有会话参数时返回 400 而不是「返回全部」。
+     * 返回全部会让人以为「这个会话里居然有别的会话的记录」，而正确的回答是
+     * 「不知道你要问哪个会话」。这一条与列表页「跨会话聚合是统计页的事」
+     * 的边界一致。
+     */
+    connection.fetch.register({
+      path: "/api/decision-engine/session-decisions",
+      methods: ["GET"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        const params = new URL(request.url).searchParams;
+        const sessionId = params.get("sessionId") ?? "";
+        if (sessionId.trim().length === 0) {
+          return json({ error: "sessionId is required" }, 400);
+        }
+        const limit = Number(params.get("limit") ?? "200");
+        try {
+          const page = await decisionStore.readForSession(sessionId, {
+            limit: Number.isFinite(limit) && limit > 0 ? Math.min(limit, MAX_ENTRIES_PER_QUERY) : 200,
+          });
+          return json({
+            sessionId,
+            enabled: page.enabled,
+            entries: page.entries,
+            total: page.total,
+            scanned: page.scanned,
+            truncated: page.truncated,
+            // 文件路径给排查用：用户常问「记录到底写到哪了」。
+            file: page.file,
+            // 单条内容长度上限：界面据此说明内容可能被截断。截断是内容丢失的
+            // **唯一**来源——没有任何配置键能把整条内容剥成只留元数据。
+            contentLimit: cfg.decisionsMaxContentChars,
+            // 人工审核比例（DEC-035）：**决策历史页也要放那个滑块**。
+            // 用户是在这个页面上看到「刚才又问我了」的，于是「改一下打扰频率」的
+            // 动作最自然的位置就在这里。随本页轮询一起回传，滑块才不会在别处
+            // 改了之后显示一个过期档位。
+            tolerance: tolerancePayload(),
+          });
+        } catch (error) {
+          return json({ error: error instanceof Error ? error.message : String(error) }, 500);
+        }
+      },
+    });
+  });
+
+  const emitBootLog = () => {
+    // 迁移结果必须可见：用户升级后如果发现「配置跑到了新目录」，
+    // 至少日志里能查到这是插件做的，而不是以为文件被谁动了。
+    if (migrated === true) {
+      ctx.logger?.info?.(
+        `dsh-decision-engine: 已把旧数据目录的配置迁移到 ${ownConfigPath}（原文件保留）`,
+      );
+    }
+    const provider = resolveProvider(cfg);
+    const keyState = resolveKey(cfg, provider) === undefined ? "未配置 ❌" : "已配置 ✅";
+    ctx.logger?.info?.(
+      `dsh-decision-engine：${cfg.enabled ? `运行中（${cfg.mode} 模式）` : "已注册但未启用（在插件配置页启用）"}；` +
+        `provider ${provider.id}；端点 ${provider.endpoint || `(不可用：${provider.error})`}；` +
+        `模型 ${provider.model || "自动（服务端默认）"}；密钥 ${keyState}；超时 ${cfg.timeoutMs}ms`,
+    );
+  };
+  // reloadOwnConfig 已在上面 void 调用过一次；这里等它落定后再打日志。
+  void reloadOwnConfig().then(emitBootLog, emitBootLog);
+  void reloadOwnConfig()
+    .catch(() => {
+      /* 读配置失败就用 DEFAULTS，上报仍按默认档走 */
+    })
+    .then(() => startTelemetry())
+    .catch((err) => {
+      ctx.logger?.warn?.(`dsh-decision-engine: 匿名统计跳过（不影响插件）：${String(err?.message ?? err)}`);
+    });
+
+}
+
+/** 丢掉 undefined，避免覆盖 DEFAULTS。 */
+function stripUndefined(source) {
+  const out = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * 从完整端点里取出它的路径风格（`decisions` / `systemone`）。
+ *
+ * 端点一定来自 buildEndpoint，理论上必然是合法 URL；但这里仍然做保护——
+ * 它在**请求失败后的降级路径**上被调用，一个解析异常不该把整次决策变成
+ * 未捕获异常（那会让守卫从「降级放行」变成「抛错」，行为倒退）。
+ *
+ * @param endpoint - 完整端点。
+ * @returns 路径风格；无法识别时返回 undefined。
+ */
+function styleOfEndpoint(endpoint) {
+  try {
+    return endpointStyleOfPath(new URL(endpoint).pathname);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 供测试与运维脚本使用的导出。
+ *
+ * `DECISION_POINTS` 必须在这里导出：`scripts/verify-wiring.mjs` 靠它逐个
+ * 校验「每个点的 pointXxx 键都在 schema 里」。早先漏掉这一项时，脚本里的
+ * `?? []` 让它静默跳过了一整轮检查——检查脚本自己静默失败，比没有检查更危险。
+ */
+export {
+  StartluxClient,
+  DEFAULTS,
+  DEFAULT_BASE_URL,
+  DEFAULT_MODEL,
+  DEFAULT_PROVIDER,
+  DEFAULT_TOLERANCE,
+  DECISION_POINTS,
+  ENDPOINT_STYLES,
+  POINT_MODES,
+  PROVIDER_IDS,
+  PROVIDER_PRESETS,
+  TOLERANCE_LEVELS,
+  TOLERANCE_PRESETS,
+  ToleranceCalibrator,
+  buildEndpoint,
+  extractGuardAnswers,
+  normalizeBaseUrl,
+  providerCatalog,
+  resolveKeyFor,
+  resolveProvider,
+  resolveTolerance,
+  severityOf,
+  toleranceCutoff,
+  tolerancePreset,
+  validateBaseUrl,
+};