dsh-subagent-profile 0.4.0 → 0.5.1

package/lib/core/cleanup.mjs

@@ -0,0 +1,33 @@
+// lib/core/cleanup.mjs — 启动与卸载清理辅助（从 index.mjs 移出以守装配文件行门）。
+// 卸载清理：本插件 3 个数据文件 + orchestrator-v2 预设目录改名备份（effect 清理器
+// 在禁用/热重载/退出时都可能触发；硬删除会静默丢用户数据）。启动清理：删上个
+// 生命周期留下的 .removed-* 备份残留（只清本插件前缀，防热重载反复产生新备份
+// 积累）；卸载后用户手动改回原名的场景不受影响。全部 fail-soft（改名/删除失败
+// 不抛）。import-free（仅 node 内置），可被裸 CI 单测。
+
+import { readdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function removeOwnedData(home) {
+  const stamp = Date.now();
+  for (const file of ['subagent-profiles.json', 'subagent-profiles.state.json', 'subagent-profiles.failed-traces.json']) {
+    try { renameSync(join(home, file), join(home, `${file}.removed-${stamp}`)); } catch { /* 源不存在（正常首启）等：best effort */ }
+  }
+  try { renameSync(join(home, '.agent-presets', 'orchestrator-v2'), join(home, '.agent-presets', `orchestrator-v2.removed-${stamp}`)); } catch { /* best effort */ }
+}
+
+export function cleanRemovedBackups(home) {
+  for (const dir of [home, join(home, '.agent-presets')]) {
+    let names;
+    try { names = readdirSync(dir); } catch { continue; }
+    for (const name of names) {
+      try {
+        if (name.startsWith('subagent-profiles.') && name.includes('.removed-')) {
+          rmSync(join(dir, name), { force: true });
+        } else if (name.startsWith('orchestrator-v2.removed-')) {
+          rmSync(join(dir, name), { recursive: true, force: true });
+        }
+      } catch { /* best effort */ }
+    }
+  }
+}

package/lib/core/data-maintenance.mjs

@@ -0,0 +1,139 @@
+// lib/core/data-maintenance.mjs — 设置页数据维护（四区清理 + 快照管理路由）。
+// 一个入口四区（避免多按钮）：① 候选/建议清理（进化资产域全清）② 快照清理
+// （snapshots/ 一键清理）③ 提醒中心已处理归档（只移出活动列表，存储与
+// governance-audit 保留——提醒=审计记录，绝不物理删除）④ 重置统计（dispatch.jsonl
+// 封存为 dispatch-archive-<ts>.jsonl，历史台账归档保留、统计从零开始；summaries.json
+// 置空重建）。每次清理记一条治理审计（kind: data-cleared / reminder-archived /
+// stats-reset，字段 target/count/ts）。快照列表/开关/单条查看路由同驻本模块
+// （快照域装配与清除口径单一来源）。CSRF 与 loopback 守卫由 createHttpRoutes
+// 入口统一完成，本模块只做解析与执行。
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { json, readBody, persistOk } from './http-helpers.mjs';
+import { writeSummaries } from './evolution-summary.mjs';
+import { SNAPSHOT_CAP } from './snapshots.mjs';
+
+// ④ 重置统计执行：活动台账封存（rename，内容字节不变）+ 空台账重建 + summaries
+// 置空。归档名有意不匹配轮转封存件模式（dispatch-<seq>-<ts>.jsonl）：金丝雀基线
+// 不再读入（统计从零开始），后续自动轮转也不会淘汰（决策留痕保留）。
+function resetStats(deps) {
+  const dir = dirname(deps.dispatchFile);
+  let count = 0;
+  let archivedFile = null;
+  if (existsSync(deps.dispatchFile)) {
+    try {
+      count = readFileSync(deps.dispatchFile, 'utf8').split('\n').filter((line) => line.trim() !== '').length;
+    } catch { count = 0; }
+    if (count > 0) {
+      const stamp = Date.now();
+      let archive = join(dir, `dispatch-archive-${stamp}.jsonl`);
+      let attempt = 0;
+      while (existsSync(archive)) {
+        attempt += 1;
+        archive = join(dir, `dispatch-archive-${stamp}-${attempt}.jsonl`);
+      }
+      try {
+        mkdirSync(dir, { recursive: true });
+        renameSync(deps.dispatchFile, archive);
+        archivedFile = basename(archive);
+      } catch (error) {
+        deps.logger.warn(`[dsh-subagent-profile] 台账封存失败（${error instanceof Error ? error.message : String(error)}），统计未重置`);
+        return { count: 0, error: '台账封存失败，统计未重置' };
+      }
+    }
+  }
+  try {
+    writeFileSync(deps.dispatchFile, '', 'utf8');
+    writeSummaries(deps.summariesFile, { l1: {}, l2: {} });
+  } catch (error) {
+    deps.logger.warn(`[dsh-subagent-profile] 统计重建失败（${error instanceof Error ? error.message : String(error)}）`);
+    return { count, archivedFile, error: '统计重建失败' };
+  }
+  deps.recordAudit({ kind: 'stats-reset', target: 'stats', count, ts: Date.now(), ...(archivedFile !== null ? { archivedFile } : {}) });
+  return { count, archivedFile };
+}
+
+export function createDataMaintenance({ dispatchFile, summariesFile, snapshots, reminderStore, evolution, logger, store, recordAudit = () => {} } = {}) {
+  const deps = { dispatchFile, summariesFile, snapshots, reminderStore, evolution, logger, store, recordAudit };
+  return {
+    // 四区清理：非法 zone 返回 null（调用方 400）；成功返回 { count, ... }。
+    // 审计一次清理一条（target/count/ts），快照清理沿用 B8 口径 kind=data-cleared。
+    clean(zone) {
+      if (zone === 'candidates') {
+        const count = deps.evolution !== undefined && typeof deps.evolution.purgeCandidates === 'function' ? deps.evolution.purgeCandidates() : 0;
+        deps.recordAudit({ kind: 'data-cleared', target: 'candidates', count, ts: Date.now() });
+        return { count };
+      }
+      if (zone === 'snapshots') {
+        const count = deps.snapshots !== undefined && typeof deps.snapshots.clear === 'function' ? deps.snapshots.clear() : 0;
+        deps.recordAudit({ kind: 'data-cleared', target: 'snapshots', count, ts: Date.now() });
+        return { count };
+      }
+      if (zone === 'reminders') {
+        const count = deps.reminderStore !== undefined && typeof deps.reminderStore.archiveActed === 'function' ? deps.reminderStore.archiveActed() : 0;
+        deps.recordAudit({ kind: 'reminder-archived', target: 'reminders', count, ts: Date.now() });
+        return { count };
+      }
+      if (zone === 'stats') return resetStats(deps);
+      return null;
+    },
+  };
+}
+
+// ── 路由处理（快照管理 + 数据维护 + 提醒归档视图）─────────────────────────────
+
+function handleSnapshotsList(deps, res) {
+  if (deps.snapshots === undefined) return json(res, 404, { ok: false, error: '配置快照域未装配' });
+  return json(res, 200, {
+    ok: true,
+    snapshotEnabled: typeof deps.store.loadSnapshotEnabled === 'function' ? deps.store.loadSnapshotEnabled() : false,
+    count: deps.snapshots.count(),
+    cap: SNAPSHOT_CAP,
+    entries: deps.snapshots.list(),
+  });
+}
+
+async function handleSnapshotsSetEnabled(deps, req, res) {
+  const body = await readBody(req);
+  const next = !!(body && body.snapshotEnabled === true);
+  const persist = deps.store.persistSnapshotEnabled(next);
+  return persistOk(res, { snapshotEnabled: deps.store.loadSnapshotEnabled() }, persist);
+}
+
+function handleSnapshotView(deps, url, res) {
+  const id = url.searchParams.get('id') ?? '';
+  const snapshot = deps.snapshots !== undefined ? deps.snapshots.view(id) : null;
+  if (snapshot === null) return json(res, 404, { ok: false, error: '快照不存在或已损坏' });
+  return json(res, 200, { ok: true, snapshot });
+}
+
+async function handleMaintenanceClean(deps, req, res) {
+  const body = await readBody(req);
+  const zone = typeof body.zone === 'string' ? body.zone : '';
+  if (zone === '') return json(res, 400, { ok: false, error: 'zone 不能为空' });
+  if (deps.maintenance === undefined) return json(res, 404, { ok: false, error: '数据维护入口未装配' });
+  const result = deps.maintenance.clean(zone);
+  if (result === null) return json(res, 400, { ok: false, error: 'zone 无效（candidates/snapshots/reminders/stats）' });
+  if (result.error !== undefined) return json(res, 500, { ok: false, error: result.error });
+  return json(res, 200, { ok: true, zone, count: result.count, ...(result.archivedFile !== undefined ? { archivedFile: result.archivedFile } : {}) });
+}
+
+function handleRemindersArchived(deps, url, res) {
+  const offset = Number.parseInt(url.searchParams.get('offset') ?? '0', 10);
+  const limit = Number.parseInt(url.searchParams.get('limit') ?? '20', 10);
+  const page = deps.reminderStore !== undefined && typeof deps.reminderStore.listArchived === 'function'
+    ? deps.reminderStore.listArchived({ offset, limit })
+    : { reminders: [], total: 0, offset: 0, limit: 20 };
+  return json(res, 200, { ok: true, ...page });
+}
+
+// 数据维护域路由分发：只处理本域路径，未知交给统一 404。
+export async function routeDataMaintenance(deps, req, res, url, sub) {
+  if (req.method === 'GET' && sub === '/snapshots') return handleSnapshotsList(deps, res);
+  if (req.method === 'POST' && sub === '/snapshots/set-enabled') return handleSnapshotsSetEnabled(deps, req, res);
+  if (req.method === 'GET' && sub === '/snapshot') return handleSnapshotView(deps, url, res);
+  if (req.method === 'POST' && sub === '/maintenance/clean') return handleMaintenanceClean(deps, req, res);
+  if (req.method === 'GET' && sub === '/reminders/archived') return handleRemindersArchived(deps, url, res);
+  return json(res, 404, { ok: false, error: `未知路由 ${sub}` });
+}

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

@@ -91,6 +91,22 @@ export function collectChildCalls(session, maxCalls = 6) {
   return { calls, truncated: totalCalls > maxCalls, totalCalls };
 }
 
+// childTotalTokens：宿主 tokenMeter 启发式估算（surface 口径，非计费 usage）；仅
+// completed 结算时测量，服务缺失/非函数/抛错均返回 undefined（fail-soft）。
+export function measureChildTokens(getService, session) {
+  if (session === undefined || session === null) return undefined;
+  const meter = getService('tokenMeter');
+  if (meter === undefined || typeof meter.measure !== 'function') return undefined;
+  try {
+    const measured = meter.measure(session);
+    return measured !== null && typeof measured === 'object' && typeof measured.totalTokens === 'number'
+      ? measured.totalTokens
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // 把一个后台 one-shot run 结算为带前台同等可观测元数据的任务结果。非 completed
 // 停因转 failed（aborted => killed，官方词汇表）并附部分输出；硬失败绝不 reject
 // 任务。

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 项明细），让模型「看见」被丢弃项；