深迹 · DeepTrace

Your Agent, in numbers.

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 inside DSH

Why DeepTrace

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

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

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

The loop

  TRACE

  Sessions / tokens / cost / tools become queryable evidence.

→

  DIAGNOSE

  Deterministic findings locate failures, waste and cost anomalies.

→

  IMPROVE

  Recommendations include evidence and a verification plan.

→

  APPLY

  Only predefined safe changes can be applied after explicit approval.

→

  VERIFY

  Post-change evidence determines 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 overview

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

Full report

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（进入一次）

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 uses INDEX_VERSION 18：previously persisted indexes built under the old resume/session interpretation are automatically rebuilt
持久化：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

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 整读）	=0.1.1-rc.2 注意：`npm install` 只是安装包本身，不会自动注册为 DSH 插件。Web UI、`whale_report` 工具与实时计费都需要通过方式 ① 注册；方式 ② 适合直接 import 报告引擎 / 用 CLI 生成报告的场景。

兼容性说明：Runtime-tested against DSH 0.1.2-alpha.1 during development, but prerelease 0.1.2-alpha.1 is not included in the current npm peer range —— 官方兼容基线仍是 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），与插件共用同一个报告引擎。

Architecture

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。

Development

pnpm install
pnpm link-dsh   # 软链本地 harness 闭包（typecheck 需要）
pnpm typecheck
pnpm test       # 409 个单测（38 个文件）：引擎与统计 / 洞察与 Improve 规则 / fault isolation / salvage / usage

dsh-whale-report

インストール

ドキュメント