Preface¶

DeepSeek Harness (hereinafter referred to as dsh) is an Agent runtime open-sourced by DeepSeek, whose core philosophy is “Everything is a plugin”: model adapters, tools, session logs, and interfaces can be installed or uninstalled as plugins. After running tasks daily with it, session events are stored in local logs. The logs themselves can answer the question “What did I just do”, but it is difficult to directly answer another category of questions: Which sessions were the most expensive? Why did retries start suddenly? How many tasks ran overnight? Which task drove up the cost?

dsh-whale-report is a community plugin designed for these types of questions. It aggregates daily, weekly, monthly, annual, or any custom range reports from session event logs, positioning itself as a read-only usage and review tool that does not rewrite any historical sessions. The community plugin directory lists it under “Tools and Capabilities”, with the product name “DeepTrace”, and the directory introduction also calls it “Whale Notebook”. It should be noted that the official repository of DeepSeek Harness is at deepseek-ai/deepseek-harness; the plugin introduced in this article is maintained by community contributor SenmuuuuW and is included in the independent site DeepSeek Harness Plugin Repository. This directory has no official affiliation with DeepSeek / QuantCube and cannot be treated as an official app store.

The current repository version is 0.4.0, the main language is TypeScript, and the license is MIT. As of 2026-08-17, the GitHub repository page shows 20 stars; the community directory page still shows 9 stars. We take the latter as the directory snapshot, and the star count should refer to the repository page.

What is this¶

One-sentence positioning: dsh-whale-report reads dsh’s session event logs and generates reproducible usage reports using local deterministic code.

It does not aim to “just display the logs again”, but aggregates sessions, tokens, costs, tool calls, and risk signals into a comparative report. The maintainer clearly wrote in the README: Statistics and insights do not rely on calling another model to comment on your data, but are based on session events, deterministic aggregation, and explicit rules; the same input should correspond to the same conclusion. Report generation itself is marked as a local deterministic path and does not consume model tokens.

The data uses official interfaces (ctx.sessionQuery and independent storage domain). After uninstalling the plugin, the mounts in the assembly diagram will be removed; statistics will also exclude the plugin’s own whale/* events to avoid counting “report generation” into usage.

Core Functions¶

The repository README and architecture documentation split the capabilities into several sections, which are explained below based on cross-checked content.

Report Periods¶

The panel and chat tool share the same preset options:

Natural periods and rolling 24h are separate. Weekly, monthly, and annual periods are aligned to the calendar; 24h rolls back 24 hours from any moment. Period keys have prefixes like day- / 24h- / wk- / mo- / yr-, and the comparison baseline for the previous period will not be mixed across different calibers.

Statistical Calibers¶

The report will summarize these metrics already listed in the README:

1. Cost: Real-time prices are obtained from DeepSeek’s official pricing page, cached for 6 hours, and fallback to built-in prices if crawling fails; costs are split by model and session. Starting from version 0.4.0, it can also identify the provider from the request header (for example, opencode-go subscription traffic), and the model key will be prefixed with the provider. If it cannot be identified, it will fall back to the official DeepSeek price.
2. Tokens: Input / output / cache read / reasoning tokens, split by model.
3. Sessions: Number of sessions, number of turns, number of events, number of active days, busiest day.
4. Activity Distribution: 24-hour distribution, half-hour distribution, daily sequence; there is also a night owl index (proportion of events between 0-6 AM).
5. Tool Calls: Total volume and details, categorized by tool family.
6. Retry Storms: The same command is continuously repeated no less than 3 times, with a sample of error summaries attached.
7. Risky Operations: Separated into red level (irreversible destruction) and yellow level (needs attention); only matches the first line of the command, and strips quoted segments to reduce false positives from heredoc or source code file names.
8. Key Scanning: Existence detection of 6 common key patterns, only reports presence or absence, and does not write the original text into the report or export.
9. Session Drilldown: Session trajectories sorted by cost, including cost, retries, risk signals, and model token attribution; Session ID can be copied.
10. Comparison Baseline: Each cycle is automatically stored in the database, and the report shows the increase or decrease compared to the previous cycle (cost, sessions, cache hit rate, etc.).
11. Platform Balance: Real-time balance of the model platform, which has been implemented for DeepSeek; the key is only read on the local server, not sent to the browser, report, or export.

Deterministic Insights¶

The insight engine currently has 8 rules, not free-form model generation. The categories listed in the README are: Late-night consumption, Retry storms, Cache hit rate changes, Fatal operations, Operations requiring attention, Session fragmentation, Suspected keys, Cost trends. Each has thresholds, attribution, and estimated calibers.

There is also a section called “Collaboration Review”: observing requirement drift, late constraints, and context fragmentation in human-machine collaboration, up to 3 entries; it will not be displayed if there are insufficient samples. The documentation emphasizes that the tone is to identify frictions and provide optimizations to try, not to evaluate personality, nor to attribute technical retries to communication issues.

The Whale Note and emoji status on the panel follow the same deterministic trigger rules, with the source code in src/whale-notes.ts.

Read-only and Export¶

The privacy boundary is a point repeatedly emphasized by this plugin:

• Read-only, does not rewrite any session history.
• Repair suggestions only output solutions and command templates, and do not execute automatically.
• Secret Scan only records pattern tags, time, and source, and the original secret will not appear in reports or exports.
• HTTP API only serves the local loopback and carries same-origin markers.

There are several export paths: full report view in the panel, main report PNG, separate session trajectory PNG, printable HTML, and PDF saved via the browser print dialog (A4 layout, same origin as the panel). The main report PNG does not include session trajectories and indexes; the trajectory diagram is a separate export for tracing.

Installation and Activation¶

The client platform declared by the plugin is web, and an environment that can already run dsh web is required. The Node constraint in package.json is ^22.19.0 || >=24.0.0, which is consistent with the requirements of DeepSeek Harness’s official development documentation.

The installation command given on the community directory page can be run in the DeepSeek Harness terminal:

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

The more complete command written in the repository README for the web profile (the plugin only injects into the web end) is:

dsh plugin --profile web add "github:SenmuuuuW/dsh-whale-report"
# Restart dsh web to make the host code take effect; the client bundle will be automatically updated with the plugin

Both the directory page and the repository remind that if you need a reproducible installation, you should fix the commit hash, not just pin the repository name. The写法 is to add the hash after the GitHub source, for example:

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

Replace <commit> with the actual commit hash in the repository. When installing from GitHub for the first time, dsh may prompt to allow build scripts, confirm according to the terminal prompt and try again.

After installation, there are two entry points:

1. Panel (main entry): If you have also installed DSH-better-sidebar, open the “DeepTrace” tab in the “+” menu; if the sidebar is not installed, there will be a floating button in the bottom right corner as a fallback.
2. Chat: Directly say “Give me a weekly report”, and the Agent will call the whale_report tool and output a markdown report.

Typical Usage¶

Request a report in chat¶

The preset enumeration of whale_report is daily, 24h, weekly, monthly, yearly, custom. Custom intervals require ISO dates, for example 2026-08-01. The tool description clearly states: it should be called when the user says “Give me a weekly report”, “What did I do this month”, or “Annual report”; after getting the result, hand the markdown text directly to the user, do not fabricate numbers.

The parameter form for custom intervals is as follows:
- preset: custom
- from: Start time, for example 2026-08-01
- to: End time, for example 2026-08-14; defaults to the current moment
- to must be later than from, otherwise the tool will report an invalid interval

CHANGELOG 0.4.0 also records an implementation detail: whale_report no longer writes the whale/report custom event to the session log. The reason is that the core harness does not recognize plugin events, and writing will cause older versions to refuse to load the entire session history. Report data is now persisted by the plugin’s own cycle statistics table.

Do not install the plugin, use CLI to view local logs first¶

The repository provides a no-installation path that directly reads the local session archive ~/.dsh/sessions/*/session.jsonl.zstd and shares the same report engine as the plugin:

pnpm install && pnpm build
pnpm report                  # Weekly report (last 7 days)
pnpm report -- --daily       # or --monthly / --yearly / --all
pnpm report -- --from 2026-08-01 --to 2026-08-14

It is suitable for situations where you want to confirm whether there are sufficient session logs on the local machine before deciding whether to install it into dsh web.

View the full report in the panel¶

The README writes a reading path in three steps: first look at the overview (cost, calls, models, exceptions), then look at the issues pointed out by Findings and Whale Note, and finally use Session Drilldown to trace to specific sessions. The overview has a freshness window of about 5 minutes for the same preset, and will recalculate in place when expired; custom intervals are regenerated each time and do not reuse cache.

Applicable Scenarios and Notes¶

It is more suitable for these types of usage:

1. You have been running dsh web for a long time and want to check tokens and costs by natural day / natural week.
2. You need to extract “retry storms, dangerous commands, suspected keys” from logs into entries instead of flipping through jsonl again.
3. When doing team internal collaboration reviews, you only want to see friction signals such as requirement drift and late constraints, and do not want another model to make personality evaluations of the working style.

You should also pay attention to the boundaries listed by the current repository itself:

• The report can copy the Session ID, but cannot jump back to the original session with one click yet, and needs to wait for the official client API to clarify.
• The current historical comparison is only “compared to the previous cycle”, and there is no trend curve across multiple cycles.
• The cost is estimated based on the official pricing page, and the final amount shall prevail based on the platform bill.
• The client platform is web; terminal TUI scenarios are not within the scope of this plugin’s declaration.
• Some paragraphs of the architecture documentation are still marked to be synchronized with v0.2.x. When reading the source code, refer to 0.4.0 in package.json and CHANGELOG. For example, the budget guardrail was completely removed in 0.2.0, do not look for weekly budget settings according to earlier introductions.

There is also a constraint emphasized by both the community directory and the official ecosystem before installation: The plugin runs with the permissions of the current dsh process, and may execute code during installation. It can read your session logs, and the balance detection will also read credential files on the local server. You should check the source code repository and license before installation; do not install untrusted sources, and fix the commit when you need a reproducible environment. Tool approval cannot sandbox third-party plugins.

Summary¶

What dsh-whale-report does is relatively restrained: it aggregates already occurring session events into a reproducible report, telling you where the money was spent, where the time went, and which commands are worth reviewing. It is not a log browser and will not rewrite history. For people who are already using the DeepSeek Harness web side and are starting to care about usage and risk signals, you can install it according to the commands on the directory page, first ask for a weekly report to see if the local data matches.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-whale-report/

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