SenmuuuuW/dsh-whale-report

深迹 · DeepTrace

你的 Agent，用数字说话。

Agent 可观测 → 诊断 → 改进 → 受控修改 → 回验：把 DSH 的 session、token、cost、tool call 与异常，转成可追踪的事实、确定性诊断、可执行建议，以及真正能被验证的改进。

6 PERIODS
·
DETERMINISTIC
·
4 IMPROVE RULES
·
APPLY + VERIFY
·
HISTORICAL PRICING
·
INCREMENTAL INDEX
·
FAULT ISOLATION
·
READ-ONLY BY DEFAULT

为什么选择 DeepTrace

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

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

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

闭环

TRACE
会话 / token / 成本 / 工具调用都成为可查询的证据。

→

DIAGNOSE
确定性发现定位故障、浪费与成本异常。

→

IMPROVE
建议包含证据与验证方案。

→

APPLY
只有预定义的安全变更才能在明确批准后应用。

→

VERIFY
变更后的证据决定 VERIFIED / NOT IMPROVED / INCONCLUSIVE。

一次报告，走完整个闭环。Apply 只接受用户批准的、allowlisted 的、受控的修改；Apply 不是 autonomous optimization，self-healing 不在范围内。

v0.6.1 — Accounting Correctness

Correct history. Complete sessions.

这一版修的是"数字是否可信"。v0.6.1 release

Historical pricing

DeepSeek pricing 按真实生效日期回溯（Asia/Shanghai）：

- before 2026-08-17：legacy flat pricing
- 2026-08-17 onward：peak / off-peak pricing
- 2026-08-23 onward：weekends fully off-peak

Complete session ingestion

- plugin 启动后新建的 sessions 会被 periodic reconcile 自动发现，不需要 restart
- repeated reconciliation 不重复计数

Resume history

- normal resume 保留完整历史；only true fork inherited seed is excluded
- 升级 v0.6.1 后，旧 v17 index 自动失效并重建（见 Semantic migration）

Semantic migration

v0.6.1 bumps the persisted accounting semantics: INDEX_VERSION 18 · REPORT_SEM 7. Old incompatible index / report state is not silently reused.

Accounting model

DeepTrace cost = complete event history × historically correct pricing。

v0.6.1 同时修正了价格口径、session discovery 与 resume history——因此 affected historical reports may change materially after upgrade（历史报告的数字会按正确口径重算）。

Product

DeepTrace 概览——主视觉、provider 余额、成本、发现项与 whale 备注。

完整的 DeepTrace 报告——发现项、协作评审、活动、资源、风险与会话追踪。

查询引擎

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

Ingest（进入一次）

- session/event firehose = primary incremental path（baseline + seq 去重）；已索引会话保持增量、去重，绝不重复计数
- periodic reconcile = discovery / recovery path：发现插件启动后新建的 session header 并纳入索引，不需要 restart；损坏会话只读 salvage（worker_threads 解压，不阻塞查询）
- resume 的会话保留恢复前的完整历史（仅真实 fork 继承的 seed 事件除外）
- v0.6.1 使用 INDEX_VERSION 18：此前在旧 resume/session 解释下持久化的索引会自动重建
- 持久化：canonical index 用 coalesced checkpoints 落盘，避免反复整库重写

Query（查询多次）

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

Exact accounting（精确对账）

- 窗口边界逐事件精确过滤（无比例近似）；对于完整可读的 event history，integer token accounting 与 raw-event oracle exactly 一致，cost 由同一 canonical 贡献按历史价格边界计算
- 统计与周期口径统一 Asia/Shanghai（不依赖机器时区）
- Source-log gaps 或 truncated session logs 会限制历史完整性——DeepTrace 不虚构缺失事件

当前 version：v0.6.1（npm latest；官方兼容基线 DSH 0.1.1-rc.2）· [v0.6.1 release

性能

基于 v0.5.3 验收时使用的真实生产数据集进行基准测试；结果因环境而异。

| 场景 | 之前 | v0.5.3 |
| --- | --- | --- |
| Refresh / Overview | ~31s（重放 + 重新聚合 session） | ~7ms median（纯索引查询） |
| Live session | ~6.5s（每 30s 整读） | =0.1.1-rc.2  注意：npm install 只是安装包本身，不会自动注册为 DSH 插件。Web UI、whale_report 工具与实时计费都需要通过方式 ① 注册；方式 ② 适合直接 import 报告引擎 / 用 CLI 生成报告的场景。

兼容性说明：开发期间已针对 DSH 0.1.2-alpha.1 进行运行时测试，但预发布版本 0.1.2-alpha.1 未包含在当前 npm peer 范围内 —— 官方兼容基线仍是 DSH 0.1.1-rc.2。

两个入口：

- 面板（主入口）：装了 better-sidebar 时在 "+" 菜单里打开「深迹」Tab；未装时右下角悬浮按钮兜底
- 对话：直接说"给我一份周报"——whale_report 工具输出 markdown 报告

数据走官方接缝（ctx.sessionQuery + storage domain），卸载即净。

立即体验（不用装插件）

pnpm install && pnpm build
pnpm report                  # 周报（最近 7 天）
pnpm report -- --daily       # 或 --monthly / --yearly / --all
pnpm report -- --from 2026-08-01 --to 2026-08-14   # 自定义区间

CLI 直接读本机会话存档（~/.dsh/sessions/*/session.jsonl.zstd），与插件共用同一个报告引擎。

架构

DSH session events（firehose + baseline + salvage）
↓  incremental ingest（seq 去重 / fingerprint reconcile；损坏会话 worker_threads 解压）
canonical index（10 分钟分桶 + 精确边界行；coalesced checkpoints 落盘）
↓  query engine（PeriodSpec → 精确窗口 → 纯索引查询，零 session IO）
Overview / Report / History（Web / HTML / PDF / PNG）

细节（数据流、存储结构、兼容性策略）见 docs/ARCHITECTURE.md。

开发

pnpm install
pnpm link-dsh   # 软链本地 harness 闭包（typecheck 需要）
pnpm typecheck
pnpm test       # 409 个单测（38 个文件）：引擎与统计 / 洞察与 Improve 规则 / fault isolation / salvage / usage 口径 / 主题 / 峰谷计价 / 导出 / 客户端刷新韧性 / Query Engine 与周期不变量 / Oracle 对账 / 增量 ingest / 时区矩阵 / persistence
pnpm build      # tsc + tsdown（客户端单文件 bundle）

已知限制

当前边界，如实说明：

- 费用为估算：cost is an estimate, not the provider invoice —— 按官方峰谷价与真实生效日期估算，最终以 DeepSeek Platform 账单为准
- Source-log gaps 可限制历史完整性：单个会话日志存在 seq gap 或截断时，DeepTrace 以官方读取器的保守语义处理，不虚构缺失事件；完整可读历史的对账是 integer-exact 的
- Apply 目前只支持 shell.timeoutMs：唯一受控、用户批准、可回滚的修改；不支持 arbitrary config / shell / code mutation，不自动 rollback，不 self-healing
- 会话跳转：报告提供 Session ID 复制，尚未实现"一键跳回原会话"（待官方 client API 明确）
- IMPROVE 默认只读：只落 DETECTED / DISMISSED 与 VERIFY 计划；自动 Verify 闭环已实现；Repeated User Correction 标记 EXPERIMENTAL（保守阈值 + 首条消息过滤）
- PNG 主报告导出暂不含 IMPROVE 区（HTML / PDF / markdown / 面板已含）
- DSH 官方兼容基线：>=0.1.1-rc.2 DeepTrace is built to make Agent behavior inspectable, measurable, and easier to improve.

…and yes, the whale is watching. She reads every report first.