前言¶

DeepSeek Harness（以下简称 dsh）是 DeepSeek 开源的 Agent 运行时，核心理念是「一切皆插件」：模型适配、工具、会话日志、界面都可以按插件装卸。日常用它跑任务之后，会话事件会落在本机日志里。日志本身能回答「刚才做了什么」，但很难直接回答另一类问题：哪些会话最贵、为什么突然开始重试、夜里到底跑了多少、是哪一次任务把成本拉高的。

dsh-whale-report 就是为这类问题准备的社区插件。它从会话事件日志里聚合出日报、周报、月报、年报或任意区间报告，定位是只读的用量与复盘工具，不改写任何历史会话。社区插件目录把它归在「工具与能力」，产品名是「深迹 · DeepTrace」，目录简介里也叫「鲸鱼记事本」。需要说明的是：DeepSeek Harness 官方仓库在 deepseek-ai/deepseek-harness；本文介绍的插件来自社区维护者 SenmuuuuW，收录在独立站点 DeepSeek Harness 插件库，该目录与 DeepSeek / 幻方没有官方从属关系，不能当成官方应用商店。

当前仓库版本为 0.4.0，主要语言是 TypeScript，许可证为 MIT。GitHub 仓库页面截至 2026-08-17 显示 20 star；社区目录页仍显示 9 star，以后者为目录快照，星标以仓库页面为准。

这是什么¶

一句话定位：dsh-whale-report 读取 dsh 的会话事件日志，用本地确定性代码生成可复算的用量报告。

它要解决的不是「把日志再展示一遍」，而是把 session、token、费用、工具调用、风险信号聚合成一份能对照的报告。维护者在 README 里写得很明确：统计和洞察不靠再调一个模型来点评你的数据，而是基于会话事件、确定性聚合和显式规则；同一份输入应对应同一份结论。报告生成本身标注为本地确定性路径，不消耗模型 token。

数据走官方接缝（ctx.sessionQuery 与独立 storage domain）。卸载插件后，装配图里的挂载会摘除；统计还会排除插件自身的 whale/* 事件，避免把「生成报告」记进用量里。

核心功能¶

仓库 README 与架构说明把能力拆成几块，下面按已经交叉核对过的内容说明。

报告周期¶

面板和聊天工具共用同一套预设：

自然周期和滚动 24h 是分开的。周、月、年按日历对齐；24h 从任意时刻往回滚 24 小时。周期 key 带 day- / 24h- / wk- / mo- / yr- 前缀，上一周期的对比基线不会串到另一种口径上。

统计口径¶

报告会汇总这些已经写进 README 的指标：

1. 费用：按 DeepSeek 官方定价页取实时价，缓存 6 小时，抓取失败则用内置价兜底；按模型和按会话分账。0.4.0 起还能从请求头里识别 provider（例如 opencode-go 订阅流量），模型键带 provider 前缀，识别不到时回退官方 DeepSeek 价。
2. Token：input / output / cache read / reasoning，按模型拆开。
3. 会话：会话数、回合数、事件数、活跃天数、最忙日。
4. 活跃分布：24 小时分布、半小时分布、按天序列；另有夜猫指数（0–6 点事件占比）。
5. 工具调用：总量和明细，按工具族归类。
6. 重试风暴：同一命令连续重复不少于 3 次，并附错误摘要样本。
7. 危险操作：红级（不可逆破坏）和黄级（需留意）分开；只匹配命令首行，并剥离引号段，降低 heredoc 或源码文件名误报。
8. 密钥扫描：6 类常见密钥模式的存在性检测，只报有无，不把原文写进报告或导出。
9. 会话钻取：按费用排序的会话轨迹，含成本、重试、危险信号和模型 token 归因；可复制 Session ID。
10. 对比基线：每个周期自动落库，报告带「较上周期」的涨跌（费用、会话、缓存命中率等）。
11. 平台余额：模型平台实时余额，DeepSeek 已实现；密钥只在本机服务端读取，不进浏览器、不进报告、不进导出。

确定性洞察¶

洞察引擎当前是 8 条规则，不是模型自由发挥。README 列出的类别是：深夜消耗、重试风暴、缓存命中率变化、致命级操作、需留意操作、会话碎片化、疑似密钥、费用趋势。每条都带阈值、归因和估算口径。

另外还有一块「协作复盘」（Collaboration Review）：观察人机协作里的需求漂移、迟到约束、上下文碎片化，最多 3 条；样本不足就不展示。文档强调语气是找摩擦、给可尝试的优化，不评价人格，也不把技术 retry 归因为沟通问题。

面板上的 Whale Note（鲸评）和表情状态，走的是同一套确定性触发规则，源码在 src/whale-notes.ts。

只读与导出¶

隐私边界是这条插件反复强调的一点：

• 只读，不改写任何 session 历史。
• 修复建议只输出方案和命令模板，不自动执行。
• Secret Scan 只记录模式标签、时间和来源，报告与导出里都不出现 secret 原文。
• HTTP API 只服务本机 loopback，并带同源标记。

导出有几条路径：面板内的完整报告视图、主报告 PNG、单独的会话轨迹 PNG、可打印 HTML，以及用浏览器打印对话框另存 PDF（A4 排版，与面板同源）。主报告 PNG 不含会话轨迹和索引；轨迹图是追查用的另一份导出。

安装与启用¶

插件声明的客户端平台是 web，需要已经能跑 dsh web 的环境。package.json 里的 Node 约束是 ^22.19.0 || >=24.0.0，和 DeepSeek Harness 官方开发文档的要求一致。

社区目录页给出的安装命令如下，在 DeepSeek Harness 终端里运行即可：

dsh plugin add github:SenmuuuuW/dsh-whale-report

仓库 README 针对 web profile 写的是更完整的一条（插件本身只注入 web 端）：

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

目录页和仓库都提醒：如需可复现安装，应固定 commit 哈希，不要只钉仓库名。写法是在 GitHub 源后面加上哈希，例如：

dsh plugin add github:SenmuuuuW/dsh-whale-report#<commit>

把 <commit> 换成仓库里实际的提交哈希。第一次从 GitHub 安装时，dsh 可能会提示允许构建脚本（allowBuilds），按终端提示确认后再重试即可。

装好之后有两个入口：

1. 面板（主入口）：如果同时装了 DSH-better-sidebar，在「+」菜单里打开「深迹」Tab；没装侧边栏时，右下角会有悬浮按钮兜底。
2. 对话：直接说「给我一份周报」，Agent 会调用 whale_report 工具，输出 markdown 报告。

典型用法¶

在对话里要一份报告¶

whale_report 的预设枚举是 daily、24h、weekly、monthly、yearly、custom。自定义区间需要 ISO 日期，例如 2026-08-01。工具描述里写明：用户说「给我一份周报」「这个月我干了啥」「年报」时就该调用它；拿到结果后把 markdown 原文交给用户，不要编数字。

自定义区间的参数形态如下：

• preset：custom
• from：起始时间，例如 2026-08-01
• to：结束时间，例如 2026-08-14；缺省为当前时刻
• to 必须晚于 from，否则工具会报区间无效

CHANGELOG 0.4.0 还记了一件实现细节：whale_report 不再向会话日志写入 whale/report 自定义事件。原因是核心 harness 不识别插件事件，写入会导致旧版本拒绝加载整段会话历史。报告数据改由插件自己的周期统计表持久化。

不装插件，先用 CLI 看本机日志¶

仓库提供了一条免安装路径，直接读本机会话存档 ~/.dsh/sessions/*/session.jsonl.zstd，和插件共用同一套报告引擎：

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

适合想先确认本机是否已有足够会话日志、再决定是否挂进 dsh web 的情况。

面板里看完整报告¶

README 把一次阅读路径写成三步：先看总览（成本、调用、模型、异常），再看 Findings 和 Whale Note 指出的问题，最后用 Session Drilldown 追到具体会话。概览对同一预设有约 5 分钟的新鲜度窗口，过期会原地重算；自定义区间每次重新生成，不复用缓存。

适用场景与注意事项¶

比较适合这几类用法：

1. 自己长期跑 dsh web，想按自然日 / 自然周核对 token 和费用。
2. 需要把「重试风暴、危险命令、疑似密钥」从日志里抽成条目，而不是再翻一遍 jsonl。
3. 团队内部做协作复盘时，只想看需求漂移、迟到约束这类摩擦信号，不想让另一个模型对工作方式做人格评价。

当前仓库自己列出的边界也要看清楚：

• 报告可以复制 Session ID，但还不能一键跳回原会话，要等官方 client API 明确。
• 历史对比目前是「较上一周期」，没有跨多个周期的趋势曲线。
• 费用是按官方定价页估算的，最终以平台账单为准。
• 客户端平台是 web；终端 TUI 场景不在这份插件的声明范围里。
• 架构文档仍有部分段落标注与 v0.2.x 同步，阅读源码时以 package.json 的 0.4.0 和 CHANGELOG 为准。例如预算护栏已在 0.2.0 整条移除，不要按更早的介绍去找每周预算设置。

安装前还有一条社区目录和官方生态都会强调的约束：插件以当前 dsh 进程的权限运行，安装时可能执行代码。它能读取你的会话日志，余额探测还会在本机服务端读取凭证文件。安装前应检查源代码仓库和许可证；不信任的来源不要装，需要可复现环境时固定 commit。工具审批并不能把第三方插件放进沙箱。

小结¶

dsh-whale-report 做的事情比较克制：把已经发生的会话事件聚合成可复算的报告，告诉你钱花在哪、时间去哪、哪些命令值得回看。它不是日志浏览器，也不会改写历史。对已经在用 DeepSeek Harness web 端、并且开始在意用量和风险信号的人，可以按目录页的命令装上，先要一份周报看看本机数据是否对得上。

目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-whale-report/

GitHub：https://github.com/SenmuuuuW/dsh-whale-report