dsh-whale-report

dsh plugin --profile web add dsh-whale-report

<p align="center">

<img src="assets/whale/whale-happy.svg" alt="" width="56">

</p>

<h1 align="center">深迹 · DeepTrace</h1>

<p align="center"><b>Your Agent, in numbers.</b></p>

<p align="center">Agent 可观测（observability）→ 诊断（diagnosis）→ 改进（improvement）：<br/>把 DSH 的 session、token、cost、tool call、风险与异常，转成可以真正读懂的诊断结论与可验证的改进建议。</p>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-whale-report"><img src="https://img.shields.io/npm/v/dsh-whale-report?label=npm&color=4d6bfe" alt="npm version"></a>

<a href="https://github.com/SenmuuuuW/dsh-whale-report/releases"><img src="https://img.shields.io/github/v/release/SenmuuuuW/dsh-whale-report?label=version&color=4d6bfe" alt="version"></a>

<a href="https://github.com/SenmuuuuW/dsh-whale-report/actions/workflows/ci.yml"><img src="https://github.com/SenmuuuuW/dsh-whale-report/actions/workflows/ci.yml/badge.svg" alt="CI"></a>

<a href="https://github.com/Anil-matcha/awesome-dsh-plugin"><img src="https://img.shields.io/badge/awesome--dsh--plugin-listed-4d6bfe" alt="awesome dsh plugin"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-4d6bfe.svg" alt="license"></a>

</p>

<table align="center">

<tr>

<td align="center" style="background:#0b1733;border-radius:12px;padding:10px 30px">

<span style="color:#4d6bfe;font-weight:700;font-family:ui-monospace,Menlo,monospace">6 PERIODS</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">10 FINDINGS</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">4 IMPROVE RULES</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">VERIFY-READY</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">PEAK / OFF-PEAK</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">FAULT ISOLATION</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">READ-ONLY</span>

<span style="color:#33445f"> · </span>

<span style="color:#cbd5e1;font-family:ui-monospace,Menlo,monospace">DETERMINISTIC</span>

</td>

</tr>

</table>

<br/>

<img src="docs/images/deeptrace-overview.png" alt="DeepTrace inside DSH" width="100%" style="border:1px solid #d9e3e8;border-radius:14px">

---

Why DeepTrace

Agent 跑完之后，真正难回答的问题不是"它做了什么"，而是：

• 哪些 session 最贵？
• 为什么突然开始 retry？
• 哪些操作值得注意？
• 夜里到底跑了多少？
• 是哪次任务把成本拉高的？
• 这周有什么值得改的？

DeepTrace 不是 log viewer，也不是普通 dashboard——它把会话事件日志聚合成报告，让这些问题有答案。

The loop

<table align="center">

<tr>

<td align="center" width="22%" style="background:#f5f8f9;border:1px solid #d9e3e8;border-radius:12px;padding:16px 10px">

<b style="color:#4d6bfe">SEE</b><br/>

<span style="color:#33445f;font-size:13px">总览成本、调用、模型与异常</span>

</td>

<td align="center" width="4%" style="color:#94a2b3">→</td>

<td align="center" width="22%" style="background:#f5f8f9;border:1px solid #d9e3e8;border-radius:12px;padding:16px 10px">

<b style="color:#4d6bfe">NOTICE</b><br/>

<span style="color:#33445f;font-size:13px">Findings + Whale Note 指出值得看的问题</span>

</td>

<td align="center" width="4%" style="color:#94a2b3">→</td>

<td align="center" width="22%" style="background:#f5f8f9;border:1px solid #d9e3e8;border-radius:12px;padding:16px 10px">

<b style="color:#4d6bfe">TRACE</b><br/>

<span style="color:#33445f;font-size:13px">Session Drilldown 追到具体会话复盘</span>

</td>

<td align="center" width="4%" style="color:#94a2b3">→</td>

<td align="center" width="22%" style="background:#f5f8f9;border:1px solid #d9e3e8;border-radius:12px;padding:16px 10px">

<b style="color:#4d6bfe">IMPROVE</b><br/>

<span style="color:#33445f;font-size:13px">只读建议 + 证据 + VERIFY 计划（v0.5）</span>

</td>

</tr>

</table>

一次报告，走完整个闭环；IMPROVE 的输出带 VERIFY 基线 → 目标。v0.6 起，用户批准后可 Apply 唯一受控修改（Repeated bash timeout → shell.timeoutMs），随后自动回验；self-healing 不在范围内。

Product

<img src="docs/images/overview.png" alt="DeepTrace overview" width="100%" style="border:1px solid #d9e3e8;border-radius:14px">

_{DeepTrace overview — hero, provider balance, cost, findings and the whale note.}

<img src="docs/images/report.png" alt="Full report" width="100%" style="border:1px solid #d9e3e8;border-radius:14px">

_{The full DeepTrace report — findings, collaboration review, activity, resources, risks and session trace.}

Query Engine

DeepTrace 架构是一句话：INGEST ONCE → QUERY MANY。会话事件只在进入时被读取、聚合、落库一次，此后 Overview / Report / History 全部只查询建好的 canonical index——不再重放 Session、不再解压、不再重新聚合。

Ingest（进入一次）

• DSH session/event firehose 逐事件增量摄入（baseline + seq 去重 + fingerprint reconcile 兜底）
• 损坏会话只读 salvage：重解压移入 worker_threads，不阻塞查询
• 会话索引增量补录：插件启动后新建的会话由周期 reconciliation 自动发现并入索引（无需重启）；resume 的会话保留恢复前的完整历史（仅真实 fork 继承的 seed 事件除外）
• 持久化：canonical index 用 coalesced checkpoints 落盘，避免反复整库重写

Query（查询多次）

• 所有页面把 PeriodSpec 解析成窗口后直接查询 canonical index（10 分钟分桶 + 精确边界行），零 readSession / 零解压
• rolling 24h 是精确窗口 [now-24h, now)；PeriodSpec 是唯一时间窗口真相源，周期之间绝不串数据

Exact accounting（精确对账）

• 窗口边界逐事件精确过滤（无比例近似），Raw Oracle 对账 costDiff = 0.0000
• 统计与周期口径统一 Asia/Shanghai（不依赖机器时区）

当前 version：v0.6.1（官方兼容基线 DSH 0.1.1-rc.2）

Performance

Benchmarked on the real production dataset used during v0.5.3 acceptance; results vary with environment.

场景 · 之前 · v0.5.3

Refresh / Overview · ~31s（重放 + 重新聚合 session） · ~7ms median（纯索引查询）

Live session · ~6.5s（每 30s 整读） · <1ms steady state（增量维护）

Refresh ×100 压测 · — · p95 8.3ms / max 11.3ms

Apply & Verify

DeepTrace 不再只告诉你哪里有问题。对于少量、明确、可回滚的安全修改，它可以在用户批准后执行改变，然后用之后的新会话数据验证是否真的改善。

IMPROVE → REVIEW CHANGE → APPLY → OBSERVE → VERIFY → OPTIONAL REVERT

…(truncated)