dsh-subagent-profile 0.3.1 → 0.3.2

package/README.md

@@ -4,7 +4,7 @@
 <div align="center">
   <b style="font-size: 1.15em;">Subagent dispatch, profiled — the right agent for the right task (preset / model / reasoning effort)</b><br /><br />
   <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
-  <img alt="Version: v0.3.1" src="https://img.shields.io/badge/Version-v0.3.1-blue.svg" />
+  <img alt="Version: v0.3.2" src="https://img.shields.io/badge/Version-v0.3.2-blue.svg" />
   <img alt="npm" src="https://img.shields.io/npm/v/dsh-subagent-profile.svg" />
   <img alt="DSH" src="https://img.shields.io/badge/DSH-0.1.0--rc.6%20~%200.1.1--rc.2-blue.svg" />
 </div>

package/README.zh.md

@@ -4,7 +4,7 @@
 <div align="center">
   <b style="font-size: 1.15em;">子 Agent 派发方案化插件 —— 用对的人（预设 / 模型 / 推理强度）干对的事</b><br /><br />
   <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
-  <img alt="Version: v0.3.1" src="https://img.shields.io/badge/Version-v0.3.1-blue.svg" />
+  <img alt="Version: v0.3.2" src="https://img.shields.io/badge/Version-v0.3.2-blue.svg" />
   <img alt="npm" src="https://img.shields.io/npm/v/dsh-subagent-profile.svg" />
   <img alt="DSH" src="https://img.shields.io/badge/DSH-0.1.0--rc.6%20~%200.1.1--rc.2-blue.svg" />
 </div>

package/index.mjs

@@ -106,7 +106,7 @@ function profileSectionText(store, gate, context) {
       return `- ${p.id}: ${desc}${p.preset !== undefined ? ` (preset: ${p.preset})` : ''}`;
     });
   if (rows.length === 0) return '';
-  const note = '- 别把 1-2 步即可自查/可搜完的小事委派出去 —— 几分钟内能自查完的直接做。';
+  const note = '- 选择方案时先匹配任务复杂度与方案描述的能力边界，成本只在能力都胜任的方案之间比较——复杂任务不得为省 token 改用能力不足的便宜方案。\n- 别把 1-2 步即可自查/可搜完的小事委派出去 —— 几分钟内能自查完的直接做。';
   return `Available dispatch profiles (dispatch.profile):\n${rows.join('\n')}\n${note}`;
 }
 

package/lib/client.js

@@ -89,6 +89,10 @@ const CSS = [
   '.sap-switch input:checked::before{left:18px}',
   '.sap-toolview{flex-direction:column;align-items:flex-start;gap:6px;padding:4px 8px;display:flex}',
   '.sap-toolText{font-size:12px;line-height:18px;color:var(--dsw-alias-label-secondary);white-space:pre-wrap;word-break:break-word}',
+  '.sap-toolSummary{align-items:center;gap:6px;flex-wrap:wrap;display:flex}',
+  '.sap-detailToggle{box-sizing:border-box;border:1px solid var(--dsw-alias-border-l3);color:var(--dsw-alias-label-secondary);background:0 0;border-radius:10px;font:inherit;font-size:11px;line-height:16px;height:20px;padding:0 8px;cursor:pointer;flex:none;align-items:center;display:inline-flex}',
+  '.sap-detailToggle:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}',
+  '.sap-toolDetail{font-size:12px;line-height:18px;color:var(--dsw-alias-label-tertiary);display:flex}',
   '.sap-toolModes{flex-wrap:wrap;gap:4px 16px;display:flex}',
   '.sap-toolGroups{flex-direction:column;gap:8px;display:flex}',
   '.sap-toolLayerCard{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 10px}',
@@ -119,6 +123,8 @@ const ZH = {
   chipDisabled: '已禁用',
   ignoredMark: '已忽略',
   toolLabel: '派发子 Agent',
+  detailOpen: '详情',
+  detailClose: '收起',
   cont: 'continuable 子 Agent',
   canContinue: '可续跑',
   toolBackground: '后台任务',
@@ -126,6 +132,12 @@ const ZH = {
   toolRunning: '运行中',
   tierZh: { cheap: '省 token（cheap）', balanced: '均衡（balanced）', premium: '高成本（premium）' },
   stopReasonZh: { completed: '完成', 'max-tokens': '超出预算', aborted: '已中止', refusal: '已拒绝', error: '出错' },
+  cacheHit: '缓存命中',
+  usageInput: '输入',
+  usageOutput: '输出',
+  usageCacheRead: '缓存读',
+  usageCacheWrite: '缓存写',
+  usageReasoning: '推理',
   persistFail: '已保存但未持久化',
   persistFailHint: '（磁盘写入未成功，重启 dsh web 后该改动可能丢失）'
 }
@@ -229,7 +241,7 @@ function readDispatchRequest(block) {
 // 生效值来源——结构化 value 只存在于执行局部（dsh-tools 约定），且宿主未
 // 定义 output.presentationMeta（block.meta 为空）。解析成功返回
 // {kind, id, fields, ignored}；任何一步不符预期返回 null，调用方回退请求值。
-const DISPATCH_RESULT_KEYS = ['profile', 'preset', 'provider', 'model', 'reasoningEffort', 'tokenTier', 'childTotalTokens', 'elapsedMs', 'stopReason']
+const DISPATCH_RESULT_KEYS = ['profile', 'preset', 'provider', 'model', 'reasoningEffort', 'tokenTier', 'childTotalTokens', 'childUsage', 'elapsedMs', 'stopReason']
 function parseDispatchText(text) {
   if (typeof text !== 'string') return null
   const firstLine = text.split('\n')[0] ?? ''
@@ -322,6 +334,65 @@ function observabilitySuffix(result, block) {
   return out
 }
 
+// 把 childUsage 的（render 行 JSON 字符串或 block.meta 对象）归一为五段对象；
+// 非 object / 非 number 段忽略，无任何有效段返回 null。可选字段（缓存读/写/推理）
+// 缺值省略键，与 host 侧 collectChildUsage 输出对齐。
+function parseChildUsage(raw) {
+  if (raw === undefined || raw === null || raw === '') return null
+  let usage = raw
+  if (typeof raw === 'string') {
+    try { usage = JSON.parse(raw) } catch { return null }
+  }
+  if (typeof usage !== 'object' || Array.isArray(usage)) return null
+  const out = {}
+  let any = false
+  for (const key of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+    const value = usage[key]
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+      out[key] = value
+      any = true
+    }
+  }
+  return any ? out : null
+}
+
+// 读取真实计费五段分解：result.fields.childUsage（render 行 JSON 串）优先，回退
+// block.meta.childUsage（对象，向前兼容旧结果/未来 presentationMeta 投射）。
+function usageFrom(result, block) {
+  if (result && result.fields && result.fields.childUsage !== undefined && result.fields.childUsage !== '') {
+    const parsed = parseChildUsage(result.fields.childUsage)
+    if (parsed !== null) return parsed
+  }
+  if (block && block.meta && typeof block.meta === 'object' && block.meta.childUsage !== undefined) {
+    return parseChildUsage(block.meta.childUsage)
+  }
+  return null
+}
+
+// 缓存命中后缀：childUsage.cacheReadTokens 存在且 >0 时追加「 · 缓存命中 M」到
+// ≈N tokens 之后（前导分隔符与 tokensSuffix/observabilitySuffix 同口径，即使
+// tokens 段缺失也不会粘在一起）；无分解或缓存读为 0/缺失时返回空串。
+function cacheHitSuffix(usage) {
+  if (usage === null) return ''
+  const cacheRead = usage.cacheReadTokens
+  return typeof cacheRead === 'number' && cacheRead > 0 ? ` · ${ZH.cacheHit} ${cacheRead}` : ''
+}
+
+// 五段分解行文案（纯函数，供卡片详情区渲染）；无任何有效段返回空串。
+function usageBreakdownText(usage) {
+  if (usage === null || typeof usage !== 'object') return ''
+  const parts = []
+  const push = (label, value) => {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) parts.push(`${label} ${value}`)
+  }
+  push(ZH.usageInput, usage.inputTokens)
+  push(ZH.usageOutput, usage.outputTokens)
+  push(ZH.usageCacheRead, usage.cacheReadTokens)
+  push(ZH.usageCacheWrite, usage.cacheWriteTokens)
+  push(ZH.usageReasoning, usage.reasoningTokens)
+  return parts.join(' · ')
+}
+
 // ── dispatch 工具卡（React 依赖经参数注入）─────────────────────────────────
 
 // 生效值：结果解析成功用结果（优先），字段缺失回退请求值。
@@ -409,7 +480,7 @@ function makeChip(el) {
   return chip
 }
 
-function makeDispatchToolview(el, chip) {
+function makeDispatchToolview(el, chip, useState) {
   function DispatchToolview(props) {
     const block = props && props.block
     const request = readDispatchRequest(block)
@@ -417,12 +488,33 @@ function makeDispatchToolview(el, chip) {
     const settled = !!(block && typeof block === 'object' && 'kind' in block)
     const { eff, ignored, kindLabel } = resolveDispatchState(request, result, settled)
     const chips = buildDispatchChips(el, chip, eff, result, block, ignored, request)
-    const p = rawOrInherit(eff.provider)
-    const m = rawOrInherit(eff.model)
-    const text = `${ZH.toolLabel}：${kindLabel} · 方案=${profileZh(eff.profile)} · 预设=${presetZh(eff.preset)} · 提供方=${p} · 模型=${m} · 推理强度=${effortZh(eff.reasoningEffort)}${tokensSuffix(result, block)}${observabilitySuffix(result, block)}`
+    const usage = usageFrom(result, block)
+    const [open, setOpen] = useState(false)
+    // 摘要行只承载动态结果（成本/耗时/结束原因/缓存命中）；静态配置（方案/预设/
+    // 提供方/模型/推理强度/档位）全部在 chip 行——避免同一组信息重复两遍。
+    const text = `${ZH.toolLabel}：${kindLabel}${tokensSuffix(result, block)}${cacheHitSuffix(usage)}${observabilitySuffix(result, block)}`
+    // 详情折叠入口：仅当存在真实计费分解（childUsage）时渲染；无分解数据
+    // （旧结果/无 usage 会话）不显示折叠区，向前兼容。
+    const detailToggle = usage === null ? null : el('button', {
+      type: 'button',
+      className: 'sap-detailToggle',
+      'aria-expanded': open,
+      onClick: () => setOpen((prev) => !prev)
+    }, open ? ZH.detailClose : ZH.detailOpen)
+    // 无分解数据时保持原摘要行结构（零漂移）；有分解时才加折叠入口与详情行。
+    const summary = usage === null
+      ? el('div', { className: 'sap-toolText' }, text)
+      : el('div', { className: 'sap-toolSummary' },
+          el('div', { className: 'sap-toolText' }, text),
+          detailToggle
+        )
+    const detailBody = open && usage !== null
+      ? el('div', { className: 'sap-toolDetail' }, usageBreakdownText(usage))
+      : null
     return el('div', { className: 'sap-toolview' },
       el('div', { className: 'sap-chips' }, chips),
-      el('div', { className: 'sap-toolText' }, text)
+      summary,
+      detailBody
     )
   }
   return DispatchToolview
@@ -904,7 +996,7 @@ window.__ModuleLoader__.load({
     const inject = ['slots']
 
     const chip = makeChip(el)
-    const DispatchToolview = makeDispatchToolview(el, chip)
+    const DispatchToolview = makeDispatchToolview(el, chip, useState)
     const ProfilesSection = makeProfilesSection(el, api, chip, useState, useEffect, useCallback)
 
     function apply(ctx) {

package/lib/core/delegation.mjs

@@ -7,6 +7,52 @@
 
 import { stopReasonError, withPartialText, textFrom } from './pure.mjs';
 
+// 子 Agent 会话的真实计费 token 五段分解：累加 session.events 里每条
+// assistant/message 事件携带的 provider usage（inputTokens / outputTokens /
+// cacheReadTokens / cacheWriteTokens / reasoningTokens）。这是宿主 dsh-llm
+// assembler 产出、dsh-session-stats 同源读取的真实计费口径，与
+// childTotalTokens（tokenMeter 对 surface 的字符密度启发式估算）并存：前者是
+// provider 实际报告的用量，后者是估算值，二者语义不同、互不替代。任何字段缺失
+// 按 0 累加；可选字段（缓存读/写/推理）全程无一条事件报告时省略该键；无任何
+// 事件带 usage 时返回 undefined（调用方不写 meta，向前兼容）。非 object / 非
+// number 一律忽略（fail-soft），使累加绝不阻断派发结算。
+//
+// 只累加 assistant/message：assistant/chunk 的 usage 是同一 step 的早期分片、
+// 随后会被该 step 的 message 事件替换——两者都累加会重复计数（若未来改成
+// 前缀匹配或累加 chunk，此守卫必须同步改并补测试）。
+export function collectChildUsage(session) {
+  if (session === undefined || session === null) return undefined;
+  const events = session.events;
+  if (!Array.isArray(events)) return undefined;
+  const totals = { inputTokens: 0, outputTokens: 0 };
+  const optionalTotals = { cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+  const seenOptional = new Set();
+  let anyUsage = false;
+  for (const event of events) {
+    if (event === null || typeof event !== 'object' || event.type !== 'assistant/message') continue;
+    const usage = event.data?.usage;
+    if (usage === null || typeof usage !== 'object' || Array.isArray(usage)) continue;
+    anyUsage = true;
+    for (const key of ['inputTokens', 'outputTokens']) {
+      const value = usage[key];
+      if (typeof value === 'number' && Number.isFinite(value) && value >= 0) totals[key] += value;
+    }
+    for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+      const value = usage[key];
+      if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+        optionalTotals[key] += value;
+        seenOptional.add(key);
+      }
+    }
+  }
+  if (!anyUsage) return undefined;
+  const out = { inputTokens: totals.inputTokens, outputTokens: totals.outputTokens };
+  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+    if (seenOptional.has(key)) out[key] = optionalTotals[key];
+  }
+  return out;
+}
+
 // Settle one background one-shot run into a job outcome with the same
 // observability metadata the foreground path reports. Non-completed stop reasons
 // become failed (aborted => killed, shipped vocabulary) with partial output
@@ -34,11 +80,15 @@ export async function settleStart(start, signal, meta, prune = (blocks) => block
       };
     }
     // 仅 completed 结算时测量（非 completed 走上方失败分支，不测）；在 dispose
-    // 之前读子 session。measureChild 缺失/失败返回 undefined → 省略字段（fail-soft）。
-    const childTotalTokens = measureChild(run.localAgent?.session);
+    // 之前读子 session，保证测量拿到完整事件流。measureChild 缺失/失败返回
+    // undefined → 省略字段（fail-soft）；childUsage 同样只在可累加时携带。
+    const childSession = run.localAgent?.session;
+    const childTotalTokens = measureChild(childSession);
+    const childUsage = collectChildUsage(childSession);
     const metaOut = {
       ...meta,
       ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+      ...(childUsage !== undefined ? { childUsage } : {}),
       elapsedMs: Date.now() - t0,
       stopReason: 'completed'
     };

package/lib/core/dispatch-schema.mjs

@@ -27,6 +27,18 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         reasoningEffort: { type: 'string' },
         tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
         childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；后台结算经 job 结果携带，dispatch 结果不带。' },
+        childUsage: {
+          type: 'object',
+          additionalProperties: false,
+          description: '真实计费 token 五段分解（缓存读/写为可选）；后台结算经 job 结果携带，dispatch 结果不带。',
+          properties: {
+            inputTokens: { type: 'number' },
+            outputTokens: { type: 'number' },
+            cacheReadTokens: { type: 'number' },
+            cacheWriteTokens: { type: 'number' },
+            reasoningTokens: { type: 'number' }
+          }
+        },
         elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；后台结算经 job 结果携带，dispatch 结果不带。' },
         stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；后台结算经 job 结果携带，dispatch 结果不带。' },
         ignored: { type: 'array', items: { type: 'string' } }
@@ -45,6 +57,18 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         reasoningEffort: { type: 'string' },
         tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
         childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台/后台结算时携带，continuable 实际省略。' },
+        childUsage: {
+          type: 'object',
+          additionalProperties: false,
+          description: '真实计费 token 五段分解（缓存读/写为可选）；仅前台/后台 completed 结算时携带，continuable 实际省略。',
+          properties: {
+            inputTokens: { type: 'number' },
+            outputTokens: { type: 'number' },
+            cacheReadTokens: { type: 'number' },
+            cacheWriteTokens: { type: 'number' },
+            reasoningTokens: { type: 'number' }
+          }
+        },
         elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；continuable 不结算，实际省略。' },
         stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；continuable 不结算，实际省略。' },
         ignored: { type: 'array', items: { type: 'string' } }
@@ -62,6 +86,18 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         reasoningEffort: { type: 'string' },
         tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
         childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台 completed 结算时携带。' },
+        childUsage: {
+          type: 'object',
+          additionalProperties: false,
+          description: '真实计费 token 五段分解（缓存读/写为可选）；前台 completed 结算时携带。',
+          properties: {
+            inputTokens: { type: 'number' },
+            outputTokens: { type: 'number' },
+            cacheReadTokens: { type: 'number' },
+            cacheWriteTokens: { type: 'number' },
+            reasoningTokens: { type: 'number' }
+          }
+        },
         elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；前台 completed 结算时携带。' },
         stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；前台 completed 结算时携带。' },
         ignored: { type: 'array', items: { type: 'string' } }

package/lib/core/dispatch-tool.mjs

@@ -25,7 +25,7 @@ import { defineTool } from './shims.mjs';
 import { computeContinuableAllow, textFrom, stopReasonError, withPartialText, pruneBlocks, assertResultSchemaConsistency } from './pure.mjs';
 import { resolveWhitelist } from './whitelist.mjs';
 import { assertCostGuard } from './cost-guard.mjs';
-import { settleStart } from './delegation.mjs';
+import { settleStart, collectChildUsage } from './delegation.mjs';
 import { DISPATCH_OUTPUT_SCHEMA } from './dispatch-schema.mjs';
 
 // --- 工具声明纯数据（从工厂提到模块级；defineTool 只读不改）----------------------
@@ -85,11 +85,17 @@ const DISPATCH_RENDER = (_args, value) => {
   const stopReason = typeof value.stopReason === 'string' && value.stopReason !== ''
     ? ` · stopReason=${value.stopReason}`
     : '';
+  // childUsage 是嵌套对象，render 行是扁平的 key=value，故 JSON 序列化为单段
+  // 供 client 侧 parseDispatchText 解析回对象（五段分解）。仅前台 completed 结算
+  // 携带；后台结算经 job 结果携带，continuable 不携带，故该段只在 foreground 行。
+  const usage = value.childUsage !== undefined && value.childUsage !== null && typeof value.childUsage === 'object'
+    ? ` · childUsage=${JSON.stringify(value.childUsage)}`
+    : '';
   const text = value.kind === 'background'
     ? `[dispatch] background job ${value.jobId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}`
     : value.kind === 'continuable'
       ? `[dispatch] started subagent ${value.subagentId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}`
-      : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}${tokens}${elapsed}${stopReason}\n\n${value.output}`;
+      : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}${tokens}${usage}${elapsed}${stopReason}\n\n${value.output}`;
   return [{ type: 'text', text }];
 };
 
@@ -292,25 +298,27 @@ async function runForeground(meta, request, parent, deps, pruneResultOutput, t0)
   const run = await deps.subagents.start('profile', request);
   let result;
   let childTotalTokens;
+  let childUsage;
   try {
     result = await run.result;
-    // 仅 completed 结算时测量（stopReason 非 completed 走失败路径，不测）；
-    // 在 dispose 之前读子 session，保证 measure 拿到完整 surface。
+    // 仅 completed 结算时测量；dispose 前读子 session 保证事件流完整。
     if (result.stopReason === 'completed') {
-      childTotalTokens = measureChildTokens(deps.getService, run.localAgent?.session);
+      const childSession = run.localAgent?.session;
+      childTotalTokens = measureChildTokens(deps.getService, childSession);
+      childUsage = collectChildUsage(childSession);
     }
   } finally {
     await run.dispose().catch(() => {});
   }
-  // A non-'completed' stop reason is a failure; attach the child's
-  // partial output text (withPartialText style).
+  // 非 completed 视为失败，附子输出部分文本。
   const failure = stopReasonError(result);
   if (failure !== undefined) throw new Error(withPartialText(failure, result.output));
-  // 结算 meta：elapsedMs 从 execute 入口 t0 计；stopReason 取底层结算值
-  // （此分支已达 return 必为 completed）。childTotalTokens 仍仅测量时携带。
+  // 结算 meta：elapsedMs 自 t0；stopReason 取底层值（此分支必 completed）；
+  // childTotalTokens / childUsage 仅可测量时携带。
   const metaOut = {
     ...meta,
     ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+    ...(childUsage !== undefined ? { childUsage } : {}),
     elapsedMs: Date.now() - t0,
     stopReason: result.stopReason
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-profile",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Dispatch one-shot subtasks to derived subagents with per-task overrides (preset/model/provider/reasoningEffort/persona/tool whitelist), a runtime-derived cost guard, a subagent-profiles service, observability metadata, and a web-GUI settings page plus a dispatch tool-call card.",
   "repository": {
     "type": "git",