SenmuuuuW/dsh-whale-report

深迹 · DeepTrace

把 DSH 的 session、token、cost、tool call、风险与异常，
转成可以真正读懂的 Agent 报告。

---

Why DeepTrace

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

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

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

The loop

→

→

一次报告，走完整个闭环。

Product

What it measures

Cost	官方峰谷价分段计算（2026-08-17 起：高峰 9–12 / 14–18 为谷时 2 倍，定价页实时抓取、6h 缓存、内置价兜底），按模型与会话分账，报告带峰谷占比（peakShare / peakRatio）与「挪到谷时约省 ¥X」估算
Live session	进行中会话实时计费（30s 刷新）：token 与费用按当前时段价折算，右上角常驻峰/谷徽标 + 双模型价目表
Tokens	input / output / cache read / reasoning，按模型拆分
Sessions	会话数、回合数、事件数、活跃天数、最忙日
Activity	小时级活跃热力图（GitHub contribution 风格，基于 Tokens 的固定 log 阈值分级）；hover 显示每小时 Tokens / 会话 / 回合 / 工具 / 成本；峰值时段、活跃小时、夜猫指数
Tool calls	工具调用总量与明细，按工具族归类
Tool health	高频工具（≥30 次）失败率健康分级，标出最不稳定的工具
Retry bursts	同一命令连续重复 ≥3 次，附错误摘要样本
Dangerous operations	红级（不可逆破坏）/ 黄级（需留意）分级，只对命令首行匹配
Secret scan	6 类常见密钥模式的存在性检测，只报有无，不存原文
Session drilldown	按费用排序的会话轨迹：成本、重试、危险信号、模型 token 归因
Baseline	每周期自动落库，报告带”较上周期 ▲/▼”（费用、会话、缓存命中率等）
Trends	多周期趋势曲线（成本 / 会话 / 缓存命中 / 夜间活跃），hover 显示每周期明细与日期范围，进行中周期标记 LIVE（不与完整周期混比）
Provider balance	模型平台实时余额（DeepSeek 已支持，可扩展）；key 只在本机服务端使用

Deterministic insights

DeepTrace 的统计与洞察不是让另一个 AI 随机点评你的数据。它基于：

• session event logs
• deterministic aggregation
• explicit rules
• reproducible report generation

10 条确定性规则：深夜消耗、峰谷时段成本、重试风暴、缓存命中率变化、致命级操作、需留意操作、会话碎片化、疑似密钥、费用趋势、工具健康。每条都带阈值、归因与估算口径。

协作复盘（COLLABORATION REVIEW）：观察人机协作模式——需求漂移 / 迟到约束 / 上下文碎片化，最多 3 条，样本不足不展示；语气是”找摩擦、给可尝试的优化”，不评价人格、不把技术 retry 归因为沟通问题。

鲸鱼娘的 Whale Note 也建立在同一套确定性触发规则上（src/whale-notes.ts，表情与文案同源）。

同一份数据 → 同一份结论。

报告本身由本地确定性代码生成——REPORT GENERATION · 0 TOKENS · LOCAL DETERMINISTIC，生成报告不消耗模型调用。

Privacy / read-only

• 只读：绝不改写任何 session 历史；统计排除 DeepTrace 自身的 whale/* 事件
• 不自动执行：修复建议只输出方案与命令模板，需要你亲自确认
• Secret Scan 不重印：只记录模式标签、时间与来源，报告与导出里都不出现 secret 原文
• 危险命令只存首行：引号段剥离，防止 grep 模式被误报
• 本机围栏：API 只服务本机 loopback + 同源标记

Reports

Preset	区间	口径
日报	今天 0:00 → 现在	自然日
24h	过去滚动 24 小时	唯一滚动周期
周报	本周一 0:00 → 现在	自然周
月报	本月 1 日 0:00 → 现在	自然月
年报	本年 1 月 1 日 0:00 → 现在	自然年
自定义	任意 from / to	显式区间

自然周期与滚动 24h 的区别：周/月/年按日历对齐（周一、1 号、1 月 1 日），”24h” 则是任意时刻起算的滚动窗口。周期 key 前缀隔离（day- / 24h- / wk- / mo- / yr-），对比基线互不串扰。

Export

• Web report：面板内完整报告视图
• PNG 图片：canvas 按面板同款视觉绘制主报告（报告头 / 鲸评 / Findings / 活跃 / 模型工具 / 风险），不含会话轨迹与索引
• 会话轨迹：单独导出的 PNG，仅含会话轨迹 + 会话索引（追查专用）
• HTML：独立可打印 HTML 页
• PDF：直接打印面板报告（A4 排版），浏览器打印对话框另存为 PDF——与面板逐像素一致

鲸鱼娘与页面形象在导出中使用真实素材（与面板显示一致）。

Installation

需要 DSH（DeepSeek Harness，web 端）环境。两种安装方式，注意区分：

① DSH 插件安装（推荐，完整功能） —— 注册进 dsh web：

dsh plugin --profile web add "github:SenmuuuuW/dsh-whale-report"
# 重启 dsh web 使宿主代码生效；客户端 bundle 随插件自动更新

② npm 包安装（仅依赖） —— 把包装进你的项目：

npm install dsh-whale-report

注意：npm install 只是安装包本身，不会自动注册为 DSH 插件。Web UI、whale_report 工具与实时计费都需要通过方式 ① 注册；方式 ② 适合直接 import 报告引擎 / 用 CLI 生成报告的场景。

两个入口：

• 面板（主入口）：装了 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
        ↓
aggregation / pricing / safety
        ↓
deterministic insights
        ↓
DeepTrace report
        ↓
Web / PDF / PNG

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

Development

pnpm install
pnpm link-dsh   # 软链本地 harness 闭包（typecheck 需要）
pnpm typecheck
pnpm test       # 139 个单测：引擎 / 洞察 / 规则 / 峰谷计价 / 导出
pnpm build      # tsc + tsdown（客户端单文件 bundle）

Status & limitations

当前边界，如实说明：

• 会话跳转：报告提供 Session ID 复制，尚未实现”一键跳回原会话”（待官方 client API 明确）
• 费用为估算：按官方峰谷价分段估算，以平台账单为准

License

MIT

---

Friends

• dsh-tianshu-tui — 超好看的 DSH 终端界面（TUI）
• DSH-better-sidebar — 很实用的 DSH 侧边栏工作台

---

DeepTrace is built to make Agent behavior inspectable, measurable, and easier to improve.