dsh-subagent-profile 0.3.4 → 0.5.0

package/lib/core/decision-trace.mjs

@@ -99,12 +99,19 @@ export function requestedOf(args, opts = {}) {
   const unknownKeys = args !== null && typeof args === 'object' && !Array.isArray(args)
     ? Object.keys(args).filter((key) => args[key] !== undefined && !DISPATCH_PARAMETER_KEYS.includes(key))
     : [];
+  // 字段双名：requested 对外显示补官方名 reasoning_effort（与官方 subagent 工具
+  // 字段对齐）；内部记录键 reasoningEffort 保持（台账/客户端读取方不动，后续 UI
+  // 批次迁移读取方后可移除旧键）。内部键记录归一后值（camel 优先），官方键记录
+  // 调用方实际使用的名（snake 优先）——同送两义时两值并留、交由 fail-loud 拒绝。
+  const internalEffort = args.reasoningEffort !== undefined ? args.reasoningEffort : args.reasoning_effort;
+  const officialEffort = args.reasoning_effort !== undefined ? args.reasoning_effort : args.reasoningEffort;
   return {
     profile: args.profile,
     preset: args.preset,
     provider: args.provider,
     model: args.model,
-    reasoningEffort: args.reasoningEffort,
+    reasoningEffort: internalEffort,
+    ...(officialEffort !== undefined ? { reasoning_effort: officialEffort } : {}),
     tokenTier: args.tokenTier,
     persona_present: typeof args.persona === 'string' && args.persona.length > 0,
     toolFilter_present: args.toolFilter !== undefined,
@@ -119,6 +126,18 @@ export function requestedOf(args, opts = {}) {
   };
 }
 
+// 生效来源判定（per-call > profile > parent > default）：回答「这次生效的
+// provider/model 路由是谁决定的」。call=per-call 显式指定任一模型字段；
+// profile=方案绑定；parent=继承父会话路由；default=provider 默认或符号默认。
+// 与官方 README 的解析优先级语义对齐；写入 requested.source 与派发台账
+// effectiveModelSource 共用同一判定。
+export function effectiveModelSourceOf(args, merged, parent) {
+  if (args?.provider !== undefined || args?.model !== undefined) return 'call';
+  if (merged?.provider !== undefined || merged?.model !== undefined) return 'profile';
+  if (parent?.options?.provider !== undefined || parent?.options?.model !== undefined) return 'parent';
+  return 'default';
+}
+
 // 生效值（与 buildMeta 同源字段 + ignored 列表）。ignored 与结果块的 ignored
 // 列表同源：continuable 为 ['preset','reasoningEffort']，前/后台为空数组。
 export function effectiveMeta(meta, ignored = []) {

package/lib/core/delegation.mjs

@@ -4,6 +4,7 @@
 // lib/core/profile-provider.mjs 的前台结果闭包使用）；无 @deepseek-ai 依赖。
 
 import { stopReasonError, withPartialText, textFrom, trustLabel, trustAudit } from './pure.mjs';
+import { readSessionEvents } from './session-read.mjs';
 
 // 子 Agent 会话的真实计费 token 五段分解：累加 session.events 里每条
 // assistant/message 事件携带的 provider usage（inputTokens / outputTokens /
@@ -20,7 +21,7 @@ import { stopReasonError, withPartialText, textFrom, trustLabel, trustAudit } fr
 // 前缀匹配或累加 chunk，此守卫必须同步改并补测试）。
 export function collectChildUsage(session) {
   if (session === undefined || session === null) return undefined;
-  const events = session.events;
+  const events = readSessionEvents(session);
   if (!Array.isArray(events)) return undefined;
   const totals = { inputTokens: 0, outputTokens: 0 };
   const optionalTotals = { cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
@@ -65,7 +66,7 @@ export function collectChildUsage(session) {
 // 若需更严可继续下调 maxCalls。
 export function collectChildCalls(session, maxCalls = 6) {
   if (session === undefined || session === null) return undefined;
-  const events = session.events;
+  const events = readSessionEvents(session);
   if (!Array.isArray(events)) return undefined;
   const calls = [];
   let totalCalls = 0;

package/lib/core/dispatch-gates.mjs

@@ -2,13 +2,16 @@
 // 从 dispatch-tool.mjs 拆出以守文件行门。闸逻辑与 fail-loud 文案逐字不变；
 // 这里只「应用闸并就地记录 decisionTrace 的 pass/fail」，不改变任何派发行为。
 //
-// 依赖边界（无 @deepseek-ai 依赖）：只 import lib/core 纯模块——cost-guard
-// （assertCostGuard）、decision-trace（recordGate / hardLimitChecks）、pure
-// （MAX_TOKENS / MAX_DEPTH）。
+// 依赖边界（无 @deepseek-ai 依赖）：只 import lib/core 模块——cost-guard
+// （assertCostGuard）、decision-trace（recordGate / hardLimitChecks /
+// effectiveModelSourceOf）、pure（MAX_TOKENS / MAX_DEPTH）、model-policy
+// （官方模型选择投影读取与路由断言）、escape（放行审计快照口径）。
 
 import { assertCostGuard } from './cost-guard.mjs';
-import { recordGate, hardLimitChecks } from './decision-trace.mjs';
+import { recordGate, hardLimitChecks, effectiveModelSourceOf } from './decision-trace.mjs';
 import { MAX_TOKENS, MAX_DEPTH, computeContinuableAllow } from './pure.mjs';
+import { assertOfficialModelRoute, readModelSelectionPolicy } from './model-policy.mjs';
+import { escapeGatesSnapshot } from './escape.mjs';
 
 // 预检：显式具体 preset 必须在运行时推导的白名单内；与父 composed 预设相同的
 // preset 改写为 'inherit'（不换装）。纯函数化：whitelist / parentComposed 由调用方
@@ -34,6 +37,64 @@ export function applyWhitelistGate(trace, merged, whitelist, parentComposed) {
   }
 }
 
+// 治理审计（official-model-reject）：dispatch 渠道带决策轨迹快照（escapeGatesSnapshot），
+// provider 渠道带渠道口径快照（whitelist/cost 已过、intersection deferred、approval never）。
+function recordOfficialModelReject(deps, effective) {
+  deps.evoLedger.recordGovernanceAudit({
+    kind: 'official-model-reject',
+    provider: effective.provider ?? null,
+    model: effective.model ?? null,
+    session_id: deps.sessionId ?? null,
+    gates_snapshot: deps.gatesSnapshot ?? { whitelist: 'pass', cost: 'pass', intersection: 'deferred', approval: 'never' },
+  });
+}
+
+// 官方模型选择闸：policy 未配置（投影缺失）→ 静默跳过——轨迹不新增闸条目，
+// 行为与 0.4.0 完全一致；配置后对生效路由（解析链完成后的最终 provider/model，
+// 含继承带出的模型）精确成对校验，越界 fail-loud 三层中文错误 + 治理审计。
+// fail 时先记 fail 闸再 rethrow。
+export function applyOfficialModelGate(deps, { policy, effective }) {
+  if (policy === undefined || policy.configured !== true) return;
+  const input = {
+    policy: { enabled: policy.enabled, allowedModels: [...policy.allowedModels] },
+    effective: { provider: effective.provider, model: effective.model },
+  };
+  try {
+    assertOfficialModelRoute(policy, effective.provider, effective.model);
+    recordGate(deps.trace, { name: 'official-model', input, output: { allowed: true }, verdict: 'pass' });
+  } catch (error) {
+    recordGate(deps.trace, { name: 'official-model', input, output: { allowed: false }, verdict: 'fail', reason: error.message });
+    recordOfficialModelReject({ ...deps, gatesSnapshot: escapeGatesSnapshot(deps.trace) }, effective);
+    throw error;
+  }
+}
+
+// dispatch 渠道官方模型预检：一次完成「生效来源判定（写入 requested 快照供台账
+// 与派发台账共用）→ 投影读取 → 生效路由判定 → 闸记录/审计」，调用方只需一行接线。
+// 投影缺失时闸静默跳过；source 值 call/profile/parent/default 恒写入 requested。
+export function runOfficialModelPreflight(deps, parent, merged, args) {
+  deps.trace.requested.source = effectiveModelSourceOf(args, merged, parent);
+  const policy = readModelSelectionPolicy(parent?.ctx, parent?.session);
+  const effective = {
+    provider: merged.provider ?? parent?.options?.provider,
+    model: merged.model ?? parent?.options?.model,
+  };
+  applyOfficialModelGate(deps, { policy, effective });
+}
+
+// provider 渠道执行（宿主直连 start 的路径无 decisionTrace）：只写治理审计 +
+// 抛同一三层中文文案；判定输入为 resolveChildAgentOptions 解析后的最终
+// agentOptions provider/model（含父继承）。
+export function applyOfficialModelProviderGate(deps, policy, effective) {
+  if (policy === undefined || policy.configured !== true) return;
+  try {
+    assertOfficialModelRoute(policy, effective.provider, effective.model);
+  } catch (error) {
+    recordOfficialModelReject(deps, effective);
+    throw error;
+  }
+}
+
 // 成本闸：硬上限（maxTokens/maxDepth）在调 assertCostGuard 前自行预判（不重复
 // throw，真 throw 仍在 assertHardLimits）；llm 能力面各检查项经 assertCostGuard
 // 的 onCheck 回调逐项回填。预判读 merged（profile 合并后的实际判定值）而非原始
@@ -98,15 +159,67 @@ export function applyIntersectionGate(trace, mode, intersectionInput, merged, pa
   }
 }
 
+// --- 预算余量三态与低位封顶 ---------------------------------------------------
+// 阈值常量（后续校准只改这里）：可用比例 ≥50% 充足 / ≥15% 紧张 / 其余告警。
+export const BUDGET_AMPLE_RATIO = 0.5;
+export const BUDGET_TIGHT_RATIO = 0.15;
+
+// 剩余 token 与可用比例（剩余按 0 兜底；上限非正数时比例按 0 = 告警）。
+export function budgetRemaining(snapshot) {
+  const max = snapshot !== null && typeof snapshot === 'object' && typeof snapshot.maxParentTokens === 'number' ? snapshot.maxParentTokens : 0;
+  const tokens = snapshot !== null && typeof snapshot === 'object' && typeof snapshot.tokens === 'number' ? snapshot.tokens : 0;
+  const remaining = Math.max(0, max - tokens);
+  return { remaining, ratio: max > 0 ? remaining / max : 0 };
+}
+
+// dispatch:budget section 三态文案（与 index.mjs 共用）。
+export function budgetSectionText(snapshot) {
+  const { remaining, ratio } = budgetRemaining(snapshot);
+  const max = snapshot !== null && typeof snapshot === 'object' && typeof snapshot.maxParentTokens === 'number' ? snapshot.maxParentTokens : 0;
+  if (ratio >= BUDGET_AMPLE_RATIO) return `派发预算：充足（剩余 ${remaining} token / 上限 ${max}）`;
+  if (ratio >= BUDGET_TIGHT_RATIO) return `派发预算：紧张（剩余 ${remaining} token / 上限 ${max}），优先 cheap 方案`;
+  return `派发预算：告警（剩余 ${remaining} token / 上限 ${max}），仅允许 cheap 方案；当前可用最高档=cheap`;
+}
+
+// 请求档位是否超出 cheap（tokenTier 或 model/effort 推定）：tokenTier 缺省
+// balanced；tokenTier=cheap 但 reasoningEffort 显式高于 off、或显式模型名非 flash
+// 系 → 推定超出。不做 tokenTier→effort 映射（禁止事项），flash 名称启发式只拦
+// 显式重负载。
+export function requestedTierBeyondCheap(merged) {
+  const tier = merged !== null && typeof merged === 'object' && typeof merged.tokenTier === 'string' && merged.tokenTier !== '' ? merged.tokenTier : 'balanced';
+  if (tier !== 'cheap') return true;
+  const effort = merged !== null && typeof merged === 'object' ? merged.reasoningEffort : undefined;
+  if (typeof effort === 'string' && effort !== '' && effort !== 'off') return true;
+  const model = merged !== null && typeof merged === 'object' ? merged.model : undefined;
+  return typeof model === 'string' && model !== '' && !model.toLowerCase().includes('flash');
+}
+
+// 低位封顶预检：余量 <15% 且请求档位超出 cheap → 记 budget fail 闸 + fail-loud。
+function assertBudgetTierCap(deps, trace, parentSessionId, budget, merged) {
+  if (typeof parentSessionId !== 'string' || parentSessionId === '' || budgetRemaining(budget).ratio >= BUDGET_TIGHT_RATIO || !requestedTierBeyondCheap(merged)) return;
+  const message = '预算不足：当前可用最高档=cheap，请改用 cheap 方案或为会话增加预算';
+  recordGate(trace, {
+    name: 'budget',
+    input: { parentSessionId, current: budget, requestedTier: merged?.tokenTier ?? 'balanced（缺省）' },
+    output: { allowed: false },
+    verdict: 'fail',
+    reason: message,
+  });
+  deps.logger.warn(`[dsh-subagent-profile] ${message}`);
+  throw new Error(message);
+}
+
 // 总预算闸（并发上限 + 每父累计 token）：前/后台在派发入口占并发额度（continuable
-// 不占——持久会话启动、非在途 one-shot）。拒绝时记一道 budget fail 闸 + warn + 抛
-// 可行动中文错误（只拦新增派发，数值内零影响）；无父 sessionId 时 acquire 内部跳过
-// 守卫。返回 { parentSessionId, finish }：finish(key, childTotalTokens) 是结算共用
-// 钩子（untrack + recordTokens + release），前/后台 settle 时恰好调用一次。
-export function applyBudgetGate(deps, parent, args, trace) {
+// 不占——持久会话启动、非在途 one-shot）。低位封顶在 acquire 之前（fail-loud 不占
+// 并发槽）。拒绝时记一道 budget fail 闸 + warn + 抛可行动中文错误（只拦新增派发，
+// 数值内零影响）；无父 sessionId 时 acquire 内部跳过守卫。返回
+// { parentSessionId, finish }：finish(key, childTotalTokens) 是结算共用钩子
+// （untrack + recordTokens + release），前/后台 settle 时恰好调用一次。
+export function applyBudgetGate(deps, parent, args, merged, trace) {
   if (args.continuable === true) return { parentSessionId: undefined, finish: () => {}, release: () => {} };
   const parentSessionId = parent.session?.header?.id;
   const budget = deps.guard.snapshot(parentSessionId);
+  assertBudgetTierCap(deps, trace, parentSessionId, budget, merged);
   const acquired = deps.guard.acquire(parentSessionId);
   if (!acquired.ok) {
     const message = acquired.reason === 'concurrency'

package/lib/core/dispatch-schema.mjs

@@ -14,20 +14,23 @@ export const DISPATCH_PARAMETERS = {
   // 参数轴归属与约束（能力轴 / 预算轴 / 防护 / 模式）：
   //   能力轴 preset→whitelist 闸；model/provider→llm 目录核验；persona→仅 shadow
   //   order 0（不进任何闸）；toolFilter→工具交集闸（只减不增）。
-  //   预算轴 reasoningEffort→resolveCallConfig；maxTokens→MAX_TOKENS 硬上限；
+  //   预算轴 reasoningEffort/reasoning_effort（双名，官方名经 normalizeReasoningEffort
+  //   归一为 camel）→resolveCallConfig；maxTokens→MAX_TOKENS 硬上限；
   //   tokenTier→档位元数据（估算口径）。
   //   防护 maxDepth→MAX_DEPTH 硬上限。
   //   模式字段（run_in_background/continuable/envelope）是派发方式选择，不入配置覆盖。
   // 新增字段时须按上列轴归类，并同步键集测试（percall-spec）的 WHITELIST_KEYS。
   // per-call 规范化清单闭合：宿主 dsh-tools 的 DSL 参数解析**默认拒绝
   // 未知键**（2026-08 实测：参数级 additionalProperties 只接受 value schema 对象、
-  // 不接受 boolean，故无法显式声明；键集闭合由 percall-spec 测试「键集恰为 14 键」
-  // 锁定，mergeProfileArgs 只透传白名单 9 键，未知字段到不了子请求）。
+  // 不接受 boolean，故无法显式声明；键集闭合由 percall-spec 测试「键集恰为 15 键
+  // （含双名键 reasoningEffort/reasoning_effort）」锁定；mergeProfileArgs 只透传
+  // 白名单 9 键（merge 前经 normalizeReasoningEffort 归一官方名），未知字段到不了子请求）。
   profile: { type: 'string', description: '容器选择（profile 注册表 id：内建 swap-standard/researcher，或设置页自建）；省略则该 subagent 原样继承父预设与工具集，不加配置覆盖。' },
   preset: { type: 'string', description: '能力轴·目标预设强制覆盖；必须是本运行时 system-trust 预设（白名单内的受信任预设），否则 fail-loud 拒绝；与父 composed 预设相同时改写为 inherit（不换装）。' },
-  model: { type: 'string', description: '能力轴·子 Agent 显式模型覆盖，per-call 优先于 profile；必须在该 provider 目录中已发布，否则 fail-loud 拒绝（无发现能力的空目录 adapter 无法校验时按兼容模式开关决定）。' },
+  model: { type: 'string', description: '能力轴·子 Agent 显式模型覆盖，per-call 优先于 profile；必须在该 provider 目录中已发布，否则 fail-loud 拒绝（无发现能力的空目录 adapter 无法校验时按兼容模式开关决定）。派发已遵循官方模型选择白名单（本会话启用时；未启用则继承父模型）。' },
   provider: { type: 'string', description: '能力轴·子 Agent 显式 provider 覆盖，per-call 优先于 profile；必须已注册在其 provider 目录中，否则 fail-loud 拒绝。' },
-  reasoningEffort: { type: 'string', description: '预算轴·注入每个子请求的推理档位覆盖，per-call 优先于 profile；经 resolveCallConfig 校验该档受显式 provider/model 支持，否则 fail-loud 拒绝；continuable 模式忽略本字段（子会话不支持）。' },
+  reasoningEffort: { type: 'string', description: '预算轴·注入每个子请求的推理档位覆盖，per-call 优先于 profile；经 resolveCallConfig 校验该档受显式 provider/model 支持，否则 fail-loud 拒绝；continuable 模式忽略本字段（子会话不支持）。（弃用别名，请用 reasoning_effort）' },
+  reasoning_effort: { type: 'string', description: '预算轴·与 reasoningEffort 同义的官方字段名（与官方 subagent 工具字段同名）：注入每个子请求的推理档位覆盖，per-call 优先于 profile；经 resolveCallConfig 校验该档受显式 provider/model 支持，否则 fail-loud 拒绝；continuable 模式忽略本字段（子会话不支持）。与 reasoningEffort 同送（两义即歧义）时 fail-loud 拒绝，请二选一。' },
   tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '预算轴·成本/深度档位（估算口径，非计费）：cheap 省 token、balanced 均衡、premium 高成本。覆盖 profile 的 tokenTier；缺省 balanced。' },
   persona: { type: 'string', description: '能力轴·覆盖子 Agent 的部署 persona 段（只 shadow order 0 的 persona 影子段，不进 descriptor）；per-call 优先于 profile。' },
   toolFilter: {
@@ -45,7 +48,7 @@ export const DISPATCH_PARAMETERS = {
   maxTokens: { type: 'number', description: '预算轴·子 Agent 显式 token 预算覆盖，per-call 优先于 profile；超过部署硬上限（MAX_TOKENS）fail-loud 拒绝。' },
   maxDepth: { type: 'number', description: '防护·子 Agent 显式绝对递归深度上限覆盖，per-call 优先于 profile；超过部署硬上限（MAX_DEPTH）fail-loud 拒绝。' },
   run_in_background: { type: 'boolean', description: '模式选择·异步 one-shot：走 jobs.start 包 start()，返回 jobId；仍单轮即弃，非 continuable。不入配置覆盖。' },
-  continuable: { type: 'boolean', description: '模式选择·启动持久可 continuation 的 subagent 而非 one-shot：立即返回 subagentId 并经 send_message 工具在后续轮次延续对话；默认 false。不入配置覆盖；与 run_in_background 同真时本字段优先，忽略 preset 换用与 reasoningEffort。' },
+  continuable: { type: 'boolean', description: '模式选择·启动持久可 continuation 的 subagent 而非 one-shot：立即返回 subagentId 并经 send_message 工具在后续轮次延续对话；默认 false。不入配置覆盖；与 run_in_background 同真时本字段优先，忽略 preset 换用与 reasoningEffort。失败经结算通知回报；超时可 send_message 追问。' },
   // 信封模式 = opt-in（仅「中段即交付物」的任务用）：true 时把信封骨架追加进
   // 子 persona（systemPrompt 影子段，模型可见），子 Agent 按结构化信封汇报；
   // 默认 false 走结果剪枝回收。
@@ -55,9 +58,27 @@ export const DISPATCH_PARAMETERS = {
 
 // 已知 per-call 参数键集（单一事实来源）：decisionTrace 的 requested 快照据此把
 // 未知字段记录为 unknown_keys（fail-visible，不静默吞）。宿主 dsh-tools DSL 对
-// 参数默认拒绝未知键，此处是插件侧决策轨迹的可观测兜底。
+// 参数默认拒绝未知键，此处是插件侧决策轨迹的可观测兜底。双名键（reasoningEffort /
+// reasoning_effort）均在其中，任一名的请求都不会误报 unknown_keys。
 export const DISPATCH_PARAMETER_KEYS = Object.freeze(Object.keys(DISPATCH_PARAMETERS));
 
+// 字段双名归一（mergeProfileArgs 合并前调用）：官方名 reasoning_effort 与内部旧名
+// reasoningEffort 等效（同值同行为）。只传官方名时归一为 reasoningEffort（下游
+// 只读 camel）；同送两义即歧义 → fail-loud 拒绝（与「未知键拒绝」同风格，绝不
+// 静默二选一）。旧名保留为弃用别名（description 已标），后续 major 移除。
+export function normalizeReasoningEffort(args) {
+  if (args === null || typeof args !== 'object') return args;
+  const snake = args.reasoning_effort;
+  const camel = args.reasoningEffort;
+  if (snake !== undefined && camel !== undefined) {
+    throw new Error('dispatch: reasoning_effort 与 reasoningEffort 不得同送（两义即歧义，请二选一）');
+  }
+  if (snake === undefined) return args;
+  const normalized = { ...args, reasoningEffort: snake };
+  delete normalized.reasoning_effort;
+  return normalized;
+}
+
 export const DISPATCH_OUTPUT_SCHEMA = {
   // 每个结果上的可观测元数据。oneOf 覆盖 background 变体（kind/jobId）与
   // foreground 变体（output），两者闭合且都携带生效的委派值。`ignored` 必须
@@ -78,6 +99,7 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         model: { type: 'string' },
         reasoningEffort: { type: 'string' },
         tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        imageText: { type: 'string', description: '一句话生效画像（方案/模型路由/档位），经 presentationMeta 供决策卡片展示；不进 render 行。' },
         childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；后台结算经 job 结果携带，dispatch 结果不带。' },
         childUsage: {
           type: 'object',
@@ -109,6 +131,7 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         model: { type: 'string' },
         reasoningEffort: { type: 'string' },
         tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        imageText: { type: 'string', description: '一句话生效画像（方案/模型路由/档位），经 presentationMeta 供决策卡片展示；不进 render 行。' },
         childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台/后台结算时携带，continuable 实际省略。' },
         childUsage: {
           type: 'object',
@@ -139,6 +162,7 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         model: { type: 'string' },
         reasoningEffort: { type: 'string' },
         tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        imageText: { type: 'string', description: '一句话生效画像（方案/模型路由/档位），经 presentationMeta 供决策卡片展示；不进 render 行。' },
         childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台 completed 结算时携带。' },
         childUsage: {
           type: 'object',
@@ -161,6 +185,20 @@ export const DISPATCH_OUTPUT_SCHEMA = {
   ]
 };
 
+// 一句话生效画像（imageText）：有 profile → `方案 X；provider/model 或继承父；
+// 档位 Y`；无 profile（继承父）→ `继承父方案；provider/model；档位 Y`。字段随
+// presentationMeta 投影进决策卡片，不进 render 行（UI 展示留后续版本）。
+export function imageTextOf(meta) {
+  const tier = meta !== null && typeof meta === 'object' && typeof meta.tokenTier === 'string' && meta.tokenTier !== '' ? meta.tokenTier : 'balanced';
+  const profile = meta !== null && typeof meta === 'object' ? meta.profile : undefined;
+  const hasProfile = typeof profile === 'string' && profile !== '' && profile !== '(inline)';
+  const provider = meta !== null && typeof meta === 'object' && typeof meta.provider === 'string' ? meta.provider : '(parent)';
+  const model = meta !== null && typeof meta === 'object' && typeof meta.model === 'string' ? meta.model : '(parent)';
+  const routeKnown = provider !== '(parent)' && model !== '(parent)';
+  if (hasProfile) return `方案 ${profile}；${routeKnown ? `${provider}/${model}` : '继承父'}；档位 ${tier}`;
+  return `继承父方案；${provider}/${model}；档位 ${tier}`;
+}
+
 // 结果 render 行（从 dispatch-tool.mjs 逐字移入以守文件行门）：continuable 丢弃
 // preset 换用与 reasoningEffort —— 渲染行把 `ignored` 列表回显出来
 // （`reasoningEffort=<值>(ignored)`，再加 ignored 项明细），让模型「看见」被丢弃项；

package/lib/core/dispatch-tool.mjs

@@ -1,29 +1,20 @@
 // lib/core/dispatch-tool.mjs — `dispatch` 工具（defineTool schema + execute）、
 // 结果 schema 一致性锁与 syncTool 注册/注销逻辑，从 index.mjs 逐字拆出。
-// 仅引用 lib + shims；无 @deepseek-ai 依赖（shims 是唯一入口）。
-//
-// 注入：所有 apply 闭包 / ctx 依赖都是显式参数——
-//   register    ctx.tools.register（工具由 syncTool 注册/注销，设置开关可运行时移除），
-//   store       profile store（resolveProfile 取基方案、getAllowFailOpen 供 cost guard），
-//   getEnabled  读取 apply 闭包 `enabled` 标志（continuable fail-loud 门 + syncTool 注册条件），
-//   getService  请求时服务 getter（ctx.get('toolResultPruner') / ctx.get('jobs')
-//               按次读取，绝不在 apply 时读），
-//   logger      ctx.logger（决策级派发日志 + continuable 告警），
-//   subagents   ctx.subagents（start / startContinuable 驱动子 Agent），
-//   guard       dispatch guard（execute 入口 acquire / 结算 release+记账 / syncTool 禁用时 cancelAll+reset）。
-// 工厂返回 { syncTool, dispose }：syncTool 交给 HTTP 路由（/set-enabled），dispose 在插件卸载时运行。
-//
-// execute 按预检段 + 三分支拆为模块级私有函数；parameters/output schema 拆至 dispatch-schema.mjs，预检闸拆至 dispatch-gates.mjs（守文件行门），零漂移。
+// 仅引用 lib + shims；无 @deepseek-ai 依赖（shims 是唯一入口）。注入全是显式参数
+// （register/store/getEnabled/getService/logger/subagents/guard/catalog/ledger/
+// evoLedger/backgroundLedger/adoptionTracker/getEscapeSet/getEvolutionAdvice）。
+// 工厂返回 { syncTool, dispose }；execute 按预检段 + 三分支拆为模块级私有函数，
+// parameters/output schema 拆至 dispatch-schema.mjs，预检闸拆至 dispatch-gates.mjs。
 
 import { defineTool } from './shims.mjs';
 import { textFrom, stopReasonError, withPartialText, pruneBlocks, assertResultSchemaConsistency, trustLabel, trustAudit, dispatchLabel } from './pure.mjs';
 import { resolveWhitelist } from './whitelist.mjs';
 import { recordEscapeAllow } from './escape.mjs';
 import { settleStart, collectChildUsage, collectChildCalls } from './delegation.mjs';
-import { DISPATCH_OUTPUT_SCHEMA, DISPATCH_PARAMETERS, DISPATCH_RENDER } from './dispatch-schema.mjs';
+import { DISPATCH_OUTPUT_SCHEMA, DISPATCH_PARAMETERS, DISPATCH_RENDER, imageTextOf, normalizeReasoningEffort } from './dispatch-schema.mjs';
 import { createDecisionTrace, finalizeTrace, assertTraceSize, parentContextOf, requestedOf, effectiveMeta, recordApprovalGate, recordFailure, profileSnapshotOf } from './decision-trace.mjs';
 import { profileDirectoryRows } from './profile-directory.mjs';
-import { applyWhitelistGate, applyCostGuardGate, applyIntersectionGate, assertContinuableEnabled, readParentToolNames, applyBudgetGate } from './dispatch-gates.mjs';
+import { applyWhitelistGate, applyCostGuardGate, applyIntersectionGate, assertContinuableEnabled, readParentToolNames, applyBudgetGate, runOfficialModelPreflight } from './dispatch-gates.mjs';
 import { trackForegroundInflight, trackBackgroundInflight, trackContinuableInflight } from './dispatch-guard.mjs';
 import { finishForegroundLedger, finishBackgroundLedger, finishContinuableLedger } from './evolution-ledger.mjs';
 import { profileKeyOf } from './evolution-summary.mjs';
@@ -36,6 +27,7 @@ const ENVELOPE_SKELETON = '完成前按以下骨架输出：## 结论（1-2 句
 
 // 解析基方案（旁路），再叠加显式参数。
 function mergeProfileArgs(args, store) {
+  args = normalizeReasoningEffort(args); // 字段双名归一（merge 前）：官方名 reasoning_effort→reasoningEffort；同送两义 fail-loud。
   const base = args.profile !== undefined ? store.resolveProfile(args.profile) : {};
   const merged = { ...base };
   for (const key of ['preset', 'model', 'provider', 'reasoningEffort', 'persona', 'toolFilter', 'maxTokens', 'maxDepth', 'tokenTier']) {
@@ -154,6 +146,7 @@ async function runContinuable(args, merged, meta, parent, exec, deps, trace, eff
     model: meta.model,
     reasoningEffort: meta.reasoningEffort,
     tokenTier: meta.tokenTier,
+    imageText: imageTextOf(meta),
     ignored: ['preset', 'reasoningEffort']
   };
   finalizeTrace(trace, {
@@ -208,7 +201,7 @@ async function runBackground(args, merged, meta, request, parent, deps, pruneRes
   });
   trackBackgroundInflight(deps.guard, jobs, jobId, parent);
   deps.adoptionTracker?.register({ parentSessionId: parent.session?.header?.id, id: jobId, ledgerKey: profileKeyOf(base.effective), mode: 'background', dispatchedAt: t0, promptExcerpt: promptExcerptOf(args?.prompt), requestedModel: merged.model, parentModel: parent.options?.model }); // 后台结算经 job 结果携带，不入会话块。
-  const out = { kind: 'background', jobId, ...meta };
+  const out = { kind: 'background', jobId, ...meta, imageText: imageTextOf(meta) };
   finalizeTrace(trace, { effective: effectiveMeta(meta, []), execution: { kind: 'background', parentSessionId: parent.session?.header?.id, jobId, mode: 'one-shot' } });
   out.decisionTrace = assertTraceSize(trace);
   return out;
@@ -268,6 +261,7 @@ async function runForeground(meta, request, parent, deps, pruneResultOutput, t0,
   if (failure !== undefined) throw new Error(withPartialText(failure, result.output));
   const metaOut = {
     ...meta,
+    imageText: imageTextOf(meta),
     ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
     ...(childUsage !== undefined ? { childUsage } : {}),
     elapsedMs,
@@ -304,7 +298,7 @@ async function prepareTrace(args, parent, deps) {
   // enabled、cheap-first）——「模型当时看到哪些候选」是回答「为什么这么选」的记录面。
   const rows = profileDirectoryRows(deps.store);
   const snapshot = profileSnapshotOf(rows, { chosenId: args.profile });
-  const advicePresent = typeof deps.getEvolutionAdvice === 'function' && deps.getEvolutionAdvice() === true && parentComposed === 'orchestrator';
+  const advicePresent = false; // advice 模型侧下架，trace 门控恒 false（保留埋点键与面板数据源，勿恢复注入）。
   const trace = createDecisionTrace(
     parentContextOf({
       parentPreset: parentComposed,
@@ -334,14 +328,14 @@ async function runDispatch(args, exec, deps) {
   let guardHandle = { release: () => {} };
   try {
     const merged = mergeProfileArgs(args, deps.store);
-    // 信封模式 opt-in：三分支创建子 Agent 前，把信封骨架追加进子 persona（systemPrompt
-    // 影子段、模型可见），不触碰 descriptor；既有 persona 非空时以空行衔接追加。
+    // 信封模式 opt-in：把信封骨架追加进子 persona（systemPrompt 影子段、模型可见），不触碰 descriptor；既有 persona 非空时空行衔接。
     if (args.envelope === true) {
       const hasPersona = merged.persona !== undefined && merged.persona.trim() !== '';
       merged.persona = hasPersona ? `${merged.persona}\n\n${ENVELOPE_SKELETON}` : ENVELOPE_SKELETON;
     }
     assertContinuableEnabled(deps, args);
     applyWhitelistGate(trace, merged, whitelist, parentComposed, escapeSet, baseWhitelist);
+    runOfficialModelPreflight({ trace, evoLedger: deps.evoLedger, sessionId: parent.session?.header?.id }, parent, merged, args);
     // Cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控）。
     await applyCostGuardGate(trace, merged, parent, deps);
     // 交集闸（三分支统一闸序，见 dispatch-gates.mjs）；continuable 的 effectiveAllow
@@ -357,9 +351,9 @@ async function runDispatch(args, exec, deps) {
     logDispatchDecision(deps.logger, args, merged, parent);
     // 总预算守卫：前/后台在 execute 入口占并发额度（continuable 不占），结算处 release
     // + recordTokens。guardHandle 传入分支用于释放与父 sessionId 记账。
-    guardHandle = applyBudgetGate(deps, parent, args, trace);
+    guardHandle = applyBudgetGate(deps, parent, args, merged, trace);
     // 派发台账静态元数据（双栏 cfg/task 指纹），分支结算处补 child_id+outcome 写盘。
-    const base = deps.evoLedger.baseEntry({ parent, args, merged, mode });
+    const base = deps.evoLedger.baseEntry({ parent, args, merged, mode, effectiveModelSource: trace.requested.source });
     recordEscapeAllow(deps, parent, merged, trace);
     if (args.continuable === true) return await runContinuable(args, merged, meta, parent, exec, deps, trace, effectiveAllow, base);
     if (args.run_in_background === true) return await runBackground(args, merged, meta, request, parent, deps, pruneResultOutput, t0, trace, guardHandle, base, exec);
@@ -375,13 +369,18 @@ export function createDispatchTool({ register, store, getEnabled, getService, lo
   const deps = { store, getEnabled, getService, logger, subagents, catalog, ledger, guard, evoLedger, backgroundLedger, adoptionTracker, getEscapeSet, getEvolutionAdvice };
   const dispatchTool = defineTool({
     name: 'dispatch',
-    description: '派发子任务给派生子 Agent，可逐个覆盖其 preset、model、provider、推理档位、persona、工具白名单、token 预算或递归深度。优先使用已保存的 profile，仅少数字段需要临时覆盖时才传 per-call 参数；未指定 model 时子代理继承父模型，查资料/汇总/读文件等轻任务请优先考虑 cheap 方案或显式 model=flash。前台等待结果；run_in_background: true 启动后台任务（单轮即弃）；continuable: true 启动持久子 Agent，后续轮次经 send_message 工具延续对话。前瞻：continuable 模式忽略 preset 换用与 reasoningEffort（结果以 ignored 提示）。',
+    description: '派发子任务给派生子 Agent，可逐个覆盖其 preset、model、provider、推理档位、persona、工具白名单、token 预算或递归深度。优先使用已保存的 profile，仅少数字段需要临时覆盖时才传 per-call 参数；未指定 model 时子代理继承父模型，查资料/汇总/读文件等轻任务请优先考虑 cheap 方案或显式 model=flash。细粒度路由/授权发现请用官方 subagent 工具 + list_subagent_models（provider/model 成对、受本会话官方模型选择白名单）；dispatch 只管方案（profile）及方案内覆盖。前台等待结果；run_in_background: true 启动后台任务（单轮即弃）；continuable: true 启动持久子 Agent，后续轮次经 send_message 工具延续对话；失败经结算通知回报；超时可 send_message 追问。失败动作映射：stopReason=max-tokens→用 profiles_query 降档或 profile 加 maxTokens；error→换 profile/preset；refusal→重述任务；连续失败→告知用户。前瞻：continuable 模式忽略 preset 换用与 reasoningEffort（结果以 ignored 提示）。',
     parameters: DISPATCH_PARAMETERS,
     output: {
       schema: DISPATCH_OUTPUT_SCHEMA,
       render: DISPATCH_RENDER,
-      // 决策轨迹经 presentationMeta 投影进会话块 meta（客户端台账数据源），不进 render 行。
-      presentationMeta: (_args, value) => value.decisionTrace,
+      // 决策轨迹经 presentationMeta 投影进会话块 meta（客户端台账数据源），不进
+      // render 行；imageText（一句话生效画像）随轨迹一起投影，卡片可见、UI 留后续。
+      presentationMeta: (_args, value) => {
+        const trace = value.decisionTrace;
+        if (trace === undefined) return undefined;
+        return { ...trace, ...(typeof value.imageText === 'string' ? { imageText: value.imageText } : {}) };
+      },
     },
     isConcurrencySafe: () => true,
     execute: (args, exec) => runDispatch(args, exec, deps),