dsh-subagent-profile 0.3.2 → 0.3.4

package/lib/core/cost-evidence.mjs

@@ -0,0 +1,145 @@
+// lib/core/cost-evidence.mjs — 省 token 证据（反事实对照，纯函数）。
+// 判定读 trace.requested.model（不能读 effective.model：buildMeta 会把继承的父
+// 模型名写进 effective，无法区分「继承父」与「显式选 pro」）。未指定 model 时
+// saving=0 并打标「未指定模型（继承父）」，让根因①可见。
+//
+// 成本口径：B 级五段单价可用时按 usage 逐段计价（元/千 token）；否则回退 A 级
+// 单次均价（docs/cost-closed-loop-design.md L14 实测）。无价格/无 usage/无模型
+// 一律 fail-soft 返回 undefined，不显示不猜数。
+
+import { MODEL_AVG_COST, MODEL_USAGE_PRICES, priceKeyFor } from './prices.mjs';
+
+function costFromUsage(model, usage) {
+  const key = priceKeyFor(model);
+  if (key === undefined) return undefined;
+  const prices = MODEL_USAGE_PRICES[key];
+  if (prices === undefined) return undefined;
+  let total = 0;
+  let any = false;
+  for (const seg of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+    const unit = prices[seg];
+    const amount = usage?.[seg];
+    if (typeof unit === 'number' && Number.isFinite(unit) && typeof amount === 'number' && Number.isFinite(amount) && amount >= 0) {
+      total += (unit * amount) / 1000;
+      any = true;
+    }
+  }
+  return any ? Number(total.toFixed(6)) : undefined;
+}
+
+// 单条派发的估算成本（元）。优先五段计价，其次 A 级单次均价。
+export function dispatchCost({ model, usage } = {}) {
+  const key = priceKeyFor(model);
+  if (key === undefined) return undefined;
+  const byUsage = costFromUsage(model, usage);
+  if (byUsage !== undefined) return byUsage;
+  const avg = MODEL_AVG_COST[key];
+  return typeof avg === 'number' ? avg : undefined;
+}
+
+// 反事实对照结果。record 为 dispatch.jsonl 行；显式指定 model 才有「继承父 vs
+// 指定 model」价差，未指定（继承父）saving 恒 0 并打 inherit 标。
+export function counterfactualFor(record) {
+  if (record === null || typeof record !== 'object') return undefined;
+  const requestedModel = record.requested?.model;
+  const usage = record.outcome?.usage;
+  const parentModel = record.parent_model;
+  if (typeof requestedModel !== 'string' || requestedModel === '') {
+    const parentCost = dispatchCost({ model: parentModel, usage });
+    return {
+      inherit: true,
+      model: parentModel ?? null,
+      actual: parentCost,
+      counterfactual: parentCost,
+      saving: 0,
+      ratio: null,
+    };
+  }
+  const actual = dispatchCost({ model: requestedModel, usage });
+  const counterfactual = dispatchCost({ model: parentModel, usage });
+  if (actual === undefined || counterfactual === undefined) return undefined;
+  const saving = Number((counterfactual - actual).toFixed(6));
+  return {
+    inherit: false,
+    model: requestedModel,
+    parentModel: parentModel ?? null,
+    actual,
+    counterfactual,
+    saving,
+    ratio: actual > 0 ? Number((counterfactual / actual).toFixed(2)) : null,
+  };
+}
+
+// 聚合一组 record 的估算成本与继承占比。只统计可计价（actual 非 undefined）记录。
+export function summarizeCosts(records) {
+  let actualSum = 0;
+  let counterfactualSum = 0;
+  let savingSum = 0;
+  let priced = 0;
+  let inheritCount = 0;
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') continue;
+    const c = counterfactualFor(record);
+    if (c === undefined) continue;
+    if (c.actual === undefined) continue;
+    actualSum += c.actual;
+    if (c.counterfactual !== undefined) counterfactualSum += c.counterfactual;
+    savingSum += c.saving;
+    priced += 1;
+    if (c.inherit) inheritCount += 1;
+  }
+  return {
+    estimated_cost: Number(actualSum.toFixed(4)),
+    estimated_inherit_cost: Number(counterfactualSum.toFixed(4)),
+    estimated_saving: Number(savingSum.toFixed(4)),
+    priced,
+    inherit_count: inheritCount,
+    inherit_ratio: priced > 0 ? Number((inheritCount / priced).toFixed(3)) : 0,
+  };
+}
+
+// 从 summaries.json 的 l1/l2 聚合成本汇总：全局（所有 L1 组求和）与按模型轴
+// （l2 的 :model: 键，同一模型多组归并）。同一记录只属一个 L1 组与一个 model 轴键，
+// 故全局与模型轴各自无重复。无数据返回空汇总（调用方省略显示）。
+export function costSummaryFromSummaries(summaries) {
+  const root = summaries !== null && typeof summaries === 'object' ? summaries : {};
+  const l1 = root.l1 !== null && typeof root.l1 === 'object' ? root.l1 : {};
+  const l2 = root.l2 !== null && typeof root.l2 === 'object' ? root.l2 : {};
+  const global = { estimated_cost: 0, estimated_inherit_cost: 0, estimated_saving: 0, priced: 0, inherit_count: 0 };
+  for (const group of Object.values(l1)) {
+    const c = group !== null && typeof group === 'object' ? group.cost : null;
+    if (c === null || typeof c !== 'object') continue;
+    if (typeof c.estimated_cost === 'number') global.estimated_cost += c.estimated_cost;
+    if (typeof c.estimated_inherit_cost === 'number') global.estimated_inherit_cost += c.estimated_inherit_cost;
+    if (typeof c.estimated_saving === 'number') global.estimated_saving += c.estimated_saving;
+    if (typeof c.priced === 'number') global.priced += c.priced;
+    if (typeof c.inherit_count === 'number') global.inherit_count += c.inherit_count;
+  }
+  global.estimated_cost = Number(global.estimated_cost.toFixed(4));
+  global.estimated_inherit_cost = Number(global.estimated_inherit_cost.toFixed(4));
+  global.estimated_saving = Number(global.estimated_saving.toFixed(4));
+  global.inherit_ratio = global.priced > 0 ? Number((global.inherit_count / global.priced).toFixed(3)) : 0;
+  const byModel = new Map();
+  for (const [key, group] of Object.entries(l2)) {
+    if (group === null || typeof group !== 'object') continue;
+    const match = /:model:([^|]+)$/.exec(key);
+    if (match === null) continue;
+    const model = match[1];
+    const cur = byModel.get(model) ?? { model, estimated_cost: 0, priced: 0, deployments: 0 };
+    const c = group.cost;
+    if (c !== null && typeof c === 'object') {
+      if (typeof c.estimated_cost === 'number') cur.estimated_cost += c.estimated_cost;
+      if (typeof c.priced === 'number') cur.priced += c.priced;
+    }
+    if (typeof group.deployments_total === 'number') cur.deployments += group.deployments_total;
+    byModel.set(model, cur);
+  }
+  const modelRows = [...byModel.values()].map((m) => ({
+    model: m.model,
+    deployments: m.deployments,
+    estimated_cost: Number(m.estimated_cost.toFixed(4)),
+    priced: m.priced,
+    avg_cost: m.priced > 0 ? Number((m.estimated_cost / m.priced).toFixed(4)) : null,
+  })).sort((a, b) => (a.model < b.model ? -1 : a.model > b.model ? 1 : 0));
+  return { global, byModel: modelRows };
+}

package/lib/core/cost-guard.mjs

@@ -2,30 +2,28 @@
 // 仅引用 lib/core/pure.mjs 的 assertHardLimits；无 @deepseek-ai 依赖。
 //
 // 运行时推导的 cost guard，两部分：
-//   ① always-on hard caps (assertHardLimits, in lib/core/pure.mjs) — maxTokens /
-//      maxDepth are hard delegation caps, independent of the `llm` service, so
-//      they must NOT stop applying when `llm` is absent（历史教训：早期版本在
-//      llm 缺失时直接 return，连带跳过了硬上限，属缺陷——硬上限永远前置）。
-//   ② llm capability — validates provider / model / reasoningEffort against the
-//      live provider directory. When the `llm` service is absent OR its provider
-//      directory is empty (an adapter without discovery), capability cannot be
-//      verified: per `allowFailOpen`（迁移开关）either
-//      fail-open compat (warn + skip; v1 数据迁移中) or fail-loud reject. A
-//      profile that requests none of provider/model/reasoningEffort has nothing
-//      to verify and always passes (valid in a headless deployment).
+//   * always-on hard caps（assertHardLimits，在 lib/core/pure.mjs）——maxTokens /
+//     maxDepth 是硬性委派上限，与 `llm` 服务无关，llm 缺失时绝不能停止生效
+//     （历史教训：早期版本在 llm 缺失时直接 return，连带跳过硬上限，属缺陷——
+//     硬上限永远前置）。
+//   * llm 能力校验——对 live provider 目录校验 provider / model /
+//     reasoningEffort。`llm` 服务缺失或其 provider 目录为空（无发现能力的
+//     adapter）时能力无法核验：按 `allowFailOpen`（迁移开关）二选一——
+//     fail-open 兼容（warn + 跳过；v1 数据迁移中）或 fail-loud 拒绝。profile
+//     若 provider/model/reasoningEffort 都未请求，无校验项，恒通过（无头部署
+//     下合法）。
 //
 // 目录读取改走共享 catalog 快照（lib/core/catalog-cache.mjs）：assertCostGuard 的
 // `catalog` 参数是缓存实例，`catalog.getSnapshot(llm)` 返回缓存过的 providers /
 // modelsByProvider。缓存只提速目录解析、不复检安全门——provider/model/effort 的
 // 校验逻辑与 fail-loud 文案逐字不变；reasoningEffort 走直连 resolveCallConfig
 // （校验调用，非目录读取，不入缓存）。
-// Used by both the provider's authoritative check and the dispatch tool's
-// pre-check. `allowFailOpen`/`logger` are injected because this function is
-// module-scoped and cannot reach the apply closure's `allowFailOpen`/`ctx.logger`.
+// 本函数同时供 provider 权威校验与 dispatch 工具预检使用。`allowFailOpen`/`logger`
+// 经注入传入：函数是模块级作用域，够不到 apply 闭包里的 `allowFailOpen`/`ctx.logger`。
 
 import { assertHardLimits } from './pure.mjs';
 
-// ② 仅当 profile 请求了需核验能力面的字段时才进入 llm 校验（无头/headless 部署下
+// 仅当 profile 请求了需核验能力面的字段时才进入 llm 校验（无头/headless 部署下
 // persona-only / toolFilter-only 的 profile 合法，不应被 fail-loud 拒绝）。
 function needsLlmCheck(profile) {
   return ['provider', 'model', 'reasoningEffort'].some(
@@ -42,23 +40,22 @@ function handleUnverifiable(allowFailOpen, logger) {
   throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
 }
 
-// ④ provider 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
+// provider 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
 function assertProviderRegistered(dir, profile) {
   if (typeof profile.provider !== 'string' || profile.provider.length === 0) return;
-  if (!(dir.providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
-    throw new Error(`dispatch: provider "${profile.provider}" is not a registered provider`);
+  const providers = Array.isArray(dir.providers) ? dir.providers : [];
+  if (!providers.some((provider) => provider && provider.id === profile.provider)) {
+    throw new Error(`dispatch: provider "${profile.provider}" 未注册（不在当前 provider 目录中，可在设置页改用已注册的 provider）`);
   }
 }
 
-// ⑤ model 校验。resolveModelInfo does not reject unknown models (catalog
-//    membership is advisory), so validate against the advertised catalog
-//    instead. An EMPTY catalog (adapter without discovery) cannot be verified
-//    and is skipped — 目录级空集已在 ③ 走 allowFailOpen 分支，此处仅兜底
-//    per-provider 空目录。A non-empty catalog that does not advertise the model
-//    fails loud. An unverifiable lookup (listModels(undefined) when no provider
-//    is known) becomes a clean fail-loud error instead of leaking "undefined".
-//    modelsByProvider 来自快照；快照未覆盖的 provider（undefined / 不在名册）
-//    走直连 listModels 兜底，保持原 fail-loud 文案逐字。
+// model 校验。resolveModelInfo 不拒绝未知模型（目录成员关系只是建议性的），
+// 所以改为对照已发布的目录校验。空目录（无发现能力的 adapter）无法核验，
+// 跳过——目录级空集已在 llm 门走 allowFailOpen 分支，此处仅兜底
+// per-provider 空目录。非空目录未发布该模型则 fail-loud。不可核验的查询
+// （provider 未知时 listModels(undefined)）变成干净的 fail-loud 错误，而不是
+// 泄漏 "undefined"。modelsByProvider 来自快照；快照未覆盖的 provider
+// （undefined / 不在名册）走直连 listModels 兜底，保持原 fail-loud 文案逐字。
 async function assertModelAdvertised(llm, profile, effectiveProvider, modelsByProvider) {
   if (typeof profile.model !== 'string' || profile.model.length === 0) return;
   const cached = modelsByProvider !== undefined ? modelsByProvider[String(effectiveProvider)] : undefined;
@@ -75,48 +72,78 @@ async function assertModelAdvertised(llm, profile, effectiveProvider, modelsByPr
     }
   }
   if (modelsError !== undefined) {
-    throw new Error(`dispatch: cannot validate model "${profile.model}" without a provider: ${modelsError instanceof Error ? modelsError.message : String(modelsError)}`, { cause: modelsError });
+    throw new Error(`dispatch: 无法校验模型 "${profile.model}"：provider 目录查询失败（${modelsError instanceof Error ? modelsError.message : String(modelsError)}），可稍后重试或在设置页关闭模型能力校验`, { cause: modelsError });
   }
   const listed = models ?? [];
   const known = listed.length > 0 && listed.some((model) => model && (model.id === profile.model || model.name === profile.model));
   if (listed.length > 0 && !known) {
-    throw new Error(`dispatch: model "${profile.model}" is not advertised by provider "${String(effectiveProvider)}"`);
+    throw new Error(`dispatch: 模型 "${profile.model}" 不在 provider "${String(effectiveProvider)}" 的目录中（可换用该 provider 已发布的模型）`);
   }
 }
 
-// ⑥ reasoningEffort 校验。
+// reasoningEffort 校验。
 async function assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel) {
   if (typeof profile.reasoningEffort !== 'string' || profile.reasoningEffort.length === 0) return;
   try {
     await llm.resolveCallConfig({ provider: effectiveProvider, model: effectiveModel, reasoningEffort: profile.reasoningEffort });
   } catch (error) {
-    throw new Error(`dispatch: reasoningEffort "${profile.reasoningEffort}" is not supported by provider "${String(effectiveProvider)}" model "${String(effectiveModel)}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    throw new Error(`dispatch: reasoningEffort "${profile.reasoningEffort}" 不受 provider "${String(effectiveProvider)}" 的模型 "${String(effectiveModel)}" 支持（${error instanceof Error ? error.message : String(error)}），可改用一个该模型支持的 effort 值`, { cause: error });
   }
 }
 
-export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog) {
-  // ① 硬上限 always-on（不依赖 llm）。
+// 能力面逐项校验的统一接线：判定通过回调 verdict:'pass'；失败先回调 verdict:'fail'
+// （含 error.message 作 detail）再 rethrow 原错误（文案不变）。
+async function runChecked(check, field, checkedAgainst, fn) {
+  try {
+    await fn();
+    check({ field, checkedAgainst, verdict: 'pass' });
+  } catch (error) {
+    check({ field, checkedAgainst, verdict: 'fail', detail: error.message });
+    throw error;
+  }
+}
+
+// llm 门的逐项记录：verdict 对应实际走向，detail 注明 fail-open/fail-loud。
+function checkLlmGate(check, allowFailOpen, detailFailLoud, detailFailOpen) {
+  check({ field: 'llm', verdict: allowFailOpen === true ? 'pass' : 'fail', detail: allowFailOpen === true ? detailFailOpen : detailFailLoud });
+}
+
+export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog, onCheck) {
+  // 可选逐项回调；onCheck 缺省时归一为 no-op，行为逐字不变（现有调用点不加参数，零漂移）。
+  const check = typeof onCheck === 'function' ? onCheck : () => {};
+
+  // 硬上限 always-on（不依赖 llm）。
   assertHardLimits(profile.maxTokens, profile.maxDepth);
 
-  // ② 无 llm 能力面字段 → 无可核验，直接通过（headless 部署合法）。
-  if (!needsLlmCheck(profile)) return;
+  // 无 llm 能力面字段 → 无可核验，直接通过（headless 部署合法）。
+  if (!needsLlmCheck(profile)) {
+    check({ field: 'llm', verdict: 'pass', detail: '无需核验（未请求 provider/model/reasoningEffort）' });
+    return;
+  }
 
   const llm = parent.ctx.get('llm');
-  // ③ llm 缺失 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
-  if (llm === undefined) return handleUnverifiable(allowFailOpen, logger);
+  // llm 缺失 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
+  if (llm === undefined) {
+    checkLlmGate(check, allowFailOpen, 'llm 缺失：fail-loud 拒绝', 'llm 缺失：fail-open 跳过核验');
+    return handleUnverifiable(allowFailOpen, logger);
+  }
 
   // llm 存在：目录读取走共享 catalog 快照（缓存只提速目录解析，校验逻辑不变）。
   const snapshot = await catalog.getSnapshot(llm);
-  const dir = snapshot.llm;
-  if (dir.providersError !== undefined || dir.providers.length === 0) {
+  // 快照形状守卫——畸形快照（llm 缺失 / providers 非数组）不得被静默放行，
+  // 归一为「目录为空」走同一 fail-loud / fail-open 门。
+  const dir = (snapshot !== null && typeof snapshot === 'object' && snapshot.llm !== null && typeof snapshot.llm === 'object') ? snapshot.llm : {};
+  const providers = Array.isArray(dir.providers) ? dir.providers : [];
+  if (dir.providersError !== undefined || providers.length === 0) {
+    checkLlmGate(check, allowFailOpen, 'provider 目录为空：fail-loud 拒绝', 'provider 目录为空：fail-open 跳过核验');
     return handleUnverifiable(allowFailOpen, logger);
   }
 
-  // ④ provider 注册校验。
-  assertProviderRegistered(dir, profile);
+  // provider 注册校验。
+  await runChecked(check, 'provider', 'catalogProviders', () => assertProviderRegistered(dir, profile));
   const effectiveProvider = profile.provider !== undefined ? profile.provider : parent.options.provider;
   const effectiveModel = profile.model !== undefined ? profile.model : parent.options.model;
-  // ⑤ model 校验 + ⑥ reasoningEffort 校验。
-  await assertModelAdvertised(llm, profile, effectiveProvider, dir.modelsByProvider);
-  await assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel);
+  // model 校验 + reasoningEffort 校验。
+  await runChecked(check, 'model', 'providerModelList', () => assertModelAdvertised(llm, profile, effectiveProvider, dir.modelsByProvider));
+  await runChecked(check, 'reasoningEffort', 'resolveCallConfig', () => assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel));
 }