DeepTrace — read-only agent reports for DeepSeek Harness: daily/weekly/monthly/yearly/custom reports from session logs with deterministic insights (cost, tokens, retry, dangerous commands, secret scan), collaboration review, tool health, live provider balance, multi-period trends and hourly activity heatmap; PDF/PNG/HTML export.
- Language
- TypeScript
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add dsh-whale-reportRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin SenmuuuuW/dsh-whale-report for me: review the repository at https://github.com/SenmuuuuW/dsh-whale-report first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
一句话定位
把 DeepSeek Harness 的会话事件聚合成年/月/周/日报告,展示成本、工具健康、危险命令、协作模式,并给出只读的改进建议;所有报告都由本地确定性代码生成,0 额外模型 token。
核心能力
- 多周期报告:日报、24 小时滚动、周报、月报、年报,以及任意起止时间的自定义报告
- 成本估算:按官方峰谷价(北京 9-12、14-18 高峰,谷时 2:1)分段计算,含峰谷占比与「挪到谷时约省多少」提示
- 工具调用健康度:按工具族统计失败率,高频工具(≥30 次)标出健康级别与最不稳定项
- 危险命令分级:红级(删库 / rm -rf / fork 炸弹 / dd 写设备 / 关机重启 / 格式化)和黄级(force push / 硬重置 / 777 / curl|sh),只匹配命令首行,引号段剥离防误报
- 密钥扫描:6 类常见密钥模式的存在性检测,只标记有无,不保存命中原文
- 重试风暴识别:同一命令连续重复 ≥3 次视为重试风暴,附带错误摘要
- 协作复盘:观察人机协作模式(需求漂移 / 迟到约束 / 上下文碎片化),最多 3 条,样本不足不展示
- IMPROVE 建议:跨会话的只读改进建议(Repeated Tool Failure / Retry Workflow Waste / Peak Cost Opportunity),带证据和 VERIFY 基线→目标
- 会话钻取:按费用排序的 Top 20 会话,含模型 token 归因
- 实时计费:进行中会话 30 秒刷新 token 与费用,右上角峰谷徽标 + 双模型价目表
- 历史趋势:多周期曲线(成本 / 会话 / 缓存命中 / 夜间活跃),进行中周期标 LIVE,不与完整周期混比
- Provider 余额:DeepSeek 官方余额查询,API key 只在本机服务端使用,缓存 60 秒
- 三视图导出:Web / HTML / PDF / PNG 主报告 / PNG 会话轨迹,导出全程本地
- 报告历史:每次生成的报告保存到 whale 域,可在面板历史列表复用
技术实现
- 语言: TypeScript(服务端 + React 客户端),TSX 单文件浏览器 bundle
- 关键依赖: @deepseek-ai/cordis(宿主插件装配)、@deepseek-ai/dsh-tools(注册聊天工具)、@deepseek-ai/dsh-session-query(会话查询)、@deepseek-ai/dsh-storage-domain(whale 域持久化)、zod(schema 校验)
- 架构模式: cordis 三件套双端插件 —— 宿主 half
src/index.ts注入 tools + sessionQuery + storageDomain,注册whale_report聊天工具与/whale/apiHTTP 路由;客户端 halfsrc/client/index.tsx通过window.__ModuleLoader__注册 React 面板,优先接入 better-sidebar(registerTab),无 sidebar 时悬浮球抽屉兜底 - 入口文件: 宿主端
src/index.ts(导出name="whale-report-core"、inject=["tools","sessionQuery","storageDomain"]、apply),客户端src/client/index.tsx(导出name="whale-report-client"、apply);npm 包提供lib/index.js(宿主)+lib/client.js(浏览器)双入口
适用场景
DSH 长期用户想了解自己的 Agent 到底干了什么、花了多少、有什么可改进的。比如想知道这周哪些 session 最贵、深夜跑的任务占多少成本、哪些工具频繁失败、有没有误删风险的操作。报告是数据新闻官式的,数字先说、事实直陈,不做主观评价;改进建议是只读的,不自动改任何 skill 或工作流。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH(DeepSeek Harness) | >= 0.1.0-rc.7 | peerDependencies 声明;会话查询、存储域、工具注册都依赖宿主 half |
| Cordis | ^4.0.1 | peerDependencies;插件按 cordis 三件套注入 |
| Node | >= 22.19.0(支持 24.x) | engines 声明 |
| 运行平台 | macOS / Windows / Linux | 浏览器 half 走 React,宿主 half 走 Node;不依赖平台原生能力 |
| 系统调用 | 无 | 没有原生模块依赖(peerDependencies 全部为宿主已装的 npm 包) |
| DSH-better-sidebar | 可选 | 安装后深迹 Tab 接入侧栏工作台;未装时悬浮球兜底 |
| API key | 可选 | 用于面板余额查询;缺失时显示 NOT CONFIGURED,不影响报告生成 |
安装方式
dsh plugin --profile web add github:SenmuuuuW/dsh-whale-report
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 安装方式 | 字符串 | DSH 插件安装(dsh plugin add)= 完整功能(含 Web UI + 聊天工具 + 实时计费);npm install dsh-whale-report 仅安装 npm 包,需手动 import 报告引擎 | 推荐 DSH 插件安装 |
OPENCODE_GO_CACHE_READ_PRICE_PER_M / OPENCODE_GO_INPUT_PRICE_PER_M / OPENCODE_GO_OUTPUT_PRICE_PER_M | 数字(CNY/百万 token) | 覆盖 opencode-go 订阅的缓存命中价、输入价、输出价;非法值(NaN/负数/空)回退内置价 | flash: 0.02/1/2,pro: 0.025/3/6 |
DEEPSEEK_API_KEY | 字符串 | Provider 余额查询用;优先从 ~/.dsh/.credentials.yaml 读取,其次 ~/.dsh/.env,最后进程环境变量 | 从 DSH 凭据文件自动读取 |
| 主题(面板) | 枚举 | 面板主题:跟随系统 / 浅色 / 深色;选择持久化到 localStorage whale.theme | 跟随系统 |
| DSH-better-sidebar | 安装状态 | 已装时深迹作为侧栏原生 Tab;未装时悬浮球抽屉 | 面板自适应 |
本插件没有 DSH 域内的 Config 配置项 —— 所有行为由确定性规则 + 用户聊天时的工具参数控制;上述环境变量和主题仅在用户希望覆盖默认值时设置。
常见问题
Q: 装好后能立刻出第一份报告吗?
A: 能,但首次打开面板或调用聊天工具时会先读取本机会话日志并建索引(src/tools.ts:206-226);启动 3 秒后会后台预热全部会话,再次生成报告 0.1-0.3 秒返回(src/tools.ts:206-226,README.md:189-191)。
Q: 数据来源是自己的还是云端?
A: 完全本地,只读。插件通过 ctx.sessionQuery 读取本机 DSH 会话存档,不写回任何会话历史,卸载即净(src/index.ts:26-34,README.md:206)。
Q: 报告里的费用是怎么算的?准吗?
A: 按官方峰谷价(北京 9-12/14-18 高峰、空闲 2:1)从 DeepSeek 定价页实时抓取,6 小时缓存,抓不到自动回退内置价;这是估算口径,以平台账单为准(src/pricing.ts:22-232,README.md:251)。
Q: 报告生成会调用模型吗?
A: 不会。所有统计、洞察、IMPROVE 建议都是本地确定性规则,生成报告 mode=local,input/output/cache/total token 全为 0;任何视图都不会因为打开报告而额外消耗模型额度(src/tools.ts:320-327,README.md:147)。
Q: 某个会话日志坏了会影响整份报告吗?
A: 不会。损坏会话被跳过并标记为 corrupt-log 或 read-failed,跳过数计入 partial 数据,markdown/HTML/面板三处都有 DATA PARTIAL 提示,被跳过会话不计入 sessions/subagentSessions 也不进 Improve 证据(src/tools.ts:182-198,README.md:117)。
Q: 卸载插件后数据会留下吗?
A: 不在 DSH 主数据里留下。插件把报告历史放在自己的 whale 域(reports / session_index / period_stats 三张表),卸载插件会随域一起清除;主会话历史插件从不动(src/state.ts:83-91,src/index.ts:31-33)。
Q: 报告支持哪几种周期?
A: 日报(今天 0:00 起)、24 小时滚动、周报(本周一 0:00 起)、月报(本月 1 日起)、年报(本年 1 月 1 日起)、自定义任意 from/to(ISO 格式)。自然周期 key 用 day- / 24h- / wk- / mo- / yr- 前缀隔离,互不串扰(src/report.ts:36-80,README.md:162-170)。
Q: 报告能导成什么格式?
A: 面板 Web 视图(含 IMPROVE 区)、HTML 可打印页、PDF(浏览器打印)、PNG 主图(不含 IMPROVE 区)、PNG 会话轨迹图(仅会话轨迹与会话索引);导出全程本地完成(README.md:174-178,docs/ARCHITECTURE.md)。
上手难度
入门 — 安装后直接打开面板或对话里说"给我一份周报"就能用;要改高级行为只需调整三个环境变量。
已知问题与限制
- 报告提供 Session ID 复制,但尚未实现"一键跳回原会话"(待官方 client API 明确),
README.md:250 - 费用按官方峰谷价分段估算,最终以平台账单为准,
README.md:251 - IMPROVE 引擎为只读建议:v0.5 只落 DETECTED / DISMISSED 与 VERIFY 计划,Apply / self-healing 未实现(路线图下一步),
README.md:252 - Repeated User Correction 标记为 EXPERIMENTAL:保守阈值 + 首条消息过滤(首条用户消息不计入纠正),
README.md:252 - PNG 主报告导出暂不含 IMPROVE 区(HTML / PDF / markdown / 面板已含),
README.md:253 - 损坏会话的跳过数计入 partial,但错误原文与堆栈永不写入报告(fault isolation 设计),
src/tools.ts:182-198 - 协作复盘在周/月/年报才易触发(样本门槛:会话 ≥5 且用户消息 ≥30),日报/24h 多数不展示,
src/collaboration.ts:22-24 - 插件版本号
0.4.0,REPORT_SEM=6/INDEX_VERSION=14,旧报告在结构变更时会自动重建,src/state.ts:11/src/tools.ts:103
深迹 · DeepTrace
Your Agent, in numbers.
把 DSH 的 session、token、cost、tool call、风险与异常,
转成可以真正读懂的 Agent 报告。
| 6 PERIODS · 10 FINDINGS · 4 IMPROVE RULES · VERIFY-READY · PEAK / OFF-PEAK · FAULT ISOLATION · READ-ONLY · DETERMINISTIC |
Why DeepTrace
Agent 跑完之后,真正难回答的问题不是"它做了什么",而是:
- 哪些 session 最贵?
- 为什么突然开始 retry?
- 哪些操作值得注意?
- 夜里到底跑了多少?
- 是哪次任务把成本拉高的?
- 这周有什么值得改的?
DeepTrace 不是 log viewer,也不是普通 dashboard——它把会话事件日志聚合成报告,让这些问题有答案。
The loop
|
SEE 总览成本、调用、模型与异常 | → |
NOTICE Findings + Whale Note 指出值得看的问题 | → |
TRACE Session Drilldown 追到具体会话复盘 | → |
IMPROVE 只读建议 + 证据 + VERIFY 计划(v0.5) |
一次报告,走完整个闭环;IMPROVE 的输出带 VERIFY 基线 → 目标,为后续自动回验(Apply / self-healing)预留。
Product
DeepTrace overview — hero, provider balance, cost, findings and the whale note.
The full DeepTrace report — findings, collaboration review, activity, resources, risks and session trace.
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 只在本机服务端使用 |
| Improve(v0.5) | 值得改的行为建议:Repeated Tool Failure / Retry Workflow Waste / Repeated User Correction(EXPERIMENTAL)/ Peak Cost Opportunity;每条带 metrics、受影响会话、置信度与 VERIFY 基线 → 目标;stable id 跨周期不变,只读、不自动修改任何配置 |
| Data partial | 单个会话日志损坏/不可读 → 跳过并披露(只存会话 id + 粗分类原因,不含错误原文);其余健康会话照常聚合,缺失数据不按 0 计;markdown / HTML / Web 三处非阻断提示 |
Deterministic insights
DeepTrace 的统计与洞察不是让另一个 AI 随机点评你的数据。它基于:
- session event logs
- deterministic aggregation
- explicit rules
- reproducible report generation
10 条确定性 Finding 规则:深夜消耗、峰谷时段成本、重试风暴、缓存命中率变化、致命级操作、需留意操作、会话碎片化、疑似密钥、费用趋势、工具健康。每条都带阈值、归因与估算口径。
IMPROVE 引擎(v0.5):Finding 回答"发生了什么",Improve 回答"值不值得改、怎么改"。4 条确定性规则:
| 规则 | 触发证据(跨 session 重复性) | 输出 |
|---|---|---|
| Repeated Tool Failure | 工具失败跨 ≥3 会话、失败率 ≥8%、单一错误码占失败 ≥40% | 建议 + 主错误码 + P95 |
| Retry / Workflow Waste | 同一归一化命令在 ≥2 会话重复重试且伴随失败 | 建议 + 重试次数 |
| Repeated User Correction(EXPERIMENTAL) | 同类纠正跨 ≥2 会话(只在第 2+ 条用户消息统计,首条消息是初始需求不算) | 建议 + 类别 + 计数 |
| Peak Cost Opportunity | 高峰占 ≥50% 且 ≥¥3,且有夜间批量负载证据 | 建议 + 可省金额 |
每条建议都带 evidence(metrics / affectedSessions / 置信度)与 verificationPlan(目标指标、基线 → 目标、窗口),排序 severity → score → occurrences → category;同一目标跨周期 id 稳定。全部本地确定性规则,0 额外 LLM token;Apply / self-healing 为后续版本预留(v0.5 只落 DETECTED / DISMISSED)。
协作复盘(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 模式被误报
- 纠正信号只存类别与计数:Repeated User Correction 的匹配基于归一化白名单(去引号、数字、路径),绝不保存用户原句
- 损坏日志不泄错误:fault isolation 只披露会话 id 与粗分类原因(corrupt-log / read-failed),错误消息 / 堆栈从不进报告
- 本机围栏: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:面板内完整报告视图(含 IMPROVE 区与 DATA PARTIAL 提示)
- PNG 图片:canvas 按面板同款视觉绘制主报告(报告头 / 鲸评 / Findings / 活跃 / 模型工具 / 风险),不含会话轨迹、索引与 IMPROVE 区
- 会话轨迹:单独导出的 PNG,仅含会话轨迹 + 会话索引(追查专用)
- HTML:独立可打印 HTML 页,含 02 / IMPROVE 章节(severity 色标 + 证据 + VERIFY 行)与 DATA PARTIAL 横幅
- 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
(损坏会话跳过 → partial,缺失 ≠ 0)
↓
deterministic findings + improve rules
↓
DeepTrace report(DATA PARTIAL 披露 + VERIFY-ready 建议)
↓
Web / HTML / PDF / PNG
细节(数据流、存储结构、兼容性策略)见 docs/ARCHITECTURE.md。
Development
pnpm install
pnpm link-dsh # 软链本地 harness 闭包(typecheck 需要)
pnpm typecheck
pnpm test # 183 个单测:引擎 / 洞察 / Improve 规则 / fault isolation / 峰谷计价 / 导出
pnpm build # tsc + tsdown(客户端单文件 bundle)
Status & limitations
当前边界,如实说明:
- 会话跳转:报告提供 Session ID 复制,尚未实现"一键跳回原会话"(待官方 client API 明确)
- 费用为估算:按官方峰谷价分段估算,以平台账单为准
- IMPROVE 为只读建议:v0.5 只落 DETECTED / DISMISSED 与 VERIFY 计划,Apply / self-healing 未实现(路线图下一步);Repeated User Correction 标记 EXPERIMENTAL(保守阈值 + 首条消息过滤)
- PNG 主报告导出暂不含 IMPROVE 区(HTML / PDF / markdown / 面板已含)
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.
…and yes, the whale is watching. She reads every report first.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/SenmuuuuW/dsh-whale-report)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.