Foreword¶

Running Agents in DSH (DeepSeek Harness) often leaves only a pile of event logs after the session ends. Reviewing logs reveals “what was done,” but it’s hard to quickly answer questions like: which sessions were the most expensive, why there were sudden retries, how many ran at night, or what’s worth improving this week.

Common approaches include using a log viewer or building a custom dashboard. The former requires manual filtering, while the latter often involves further model calls for “commentary,” leading to unstable conclusions and additional token costs. dsh-whale-report (DeepTrace) takes a different path: it only reads local session event logs, uses deterministic aggregation and explicit rules to generate daily, weekly, monthly, annual, or custom-interval reports. Report generation itself consumes no model calls.

This section introduces the plugin’s positioning, capabilities, and installation usage.

What This Is¶

dsh-whale-report is a memory-type plugin within the DSH ecosystem, maintained by SenmuuuuW, with its GitHub repository at SenmuuuuW/dsh-whale-report (approximately 28 stars). The npm package name is dsh-whale-report, currently at version 0.5.2, under the MIT license.

One-line positioning: Your Agent, in numbers—transforming DSH sessions, tokens, costs, tool calls, risks, and anomalies into readable Agent reports. It is not a log viewer or a standard dashboard; its core lies in deterministic insights and collaborative review, read-only and does not alter history.

What the Report Answers¶

A single report follows the closed loop: SEE → NOTICE → TRACE → IMPROVE:

1. SEE: Overview of costs, calls, models, and anomalies.
2. NOTICE: 10 Finding rules + Whale Note highlighting issues worth attention.
3. TRACE: Session Drilldown to specific sessions.
4. IMPROVE (v0.5): Read-only suggestions + evidence + VERIFY plan, reserved for future automated re-verification.

Supported preset periods are as follows:

Core Capabilities¶

Measurement and Cost¶

The report covers dimensions such as fees, tokens, session activity, tool calls, and risk signals. Key points include:

• Cost: Calculated in segments based on DeepSeek’s official peak/off-peak pricing (effective from 2026-08-17, peak hours 9–12 / 14–18 are 2x off-peak rates; pricing page is fetched in real-time, cached for 6h, with built-in price fallback). Fees are allocated by model and session, with peak/off-peak ratios and an estimate of “approximately ¥X saved by moving to off-peak hours.”
• Live session: In-progress sessions refresh real-time billing every 30s, with a peak/off-peak badge in the top right corner.
• Tokens: Input / output / cache read / reasoning, broken down by model.
• Activity: Hourly heatmap (GitHub contribution style), including peak periods and night-owl index.
• Tool calls & Tool health: Call details and failure rate classification for high-frequency tools (≥30 calls).
• Retry bursts: Same command repeated consecutively ≥3 times, with error summary samples.
• Dangerous operations: Red level (irreversible damage) / yellow level (needs attention), matching only the command’s first line.
• Secret scan: Detection of 6 common key patterns, reporting only presence/absence without storing the original text.
• Baseline & Trends: Comparison with the previous period, multi-period trend curves; in-progress periods are marked LIVE.
• Provider balance: Real-time DeepSeek platform balance (keys are used only locally on the server side).

From v0.5.0 onward, usage accounting follows: total = input(miss) + cacheRead(hit) + output, with reasoning only as an output breakdown; cost = miss×input price + hit×cache price + output×output price.

Deterministic Insights, Zero Additional LLM Tokens¶

Statistics and insights are not randomly commented on by another AI; they are based on session event logs, deterministic aggregation, explicit rules, and reproducible report generation. The same data → the same conclusions; report generation is labeled as REPORT GENERATION · 0 TOKENS · LOCAL DETERMINISTIC.

10 Finding rules: Late-night consumption, peak/off-peak period costs, retry storms, cache hit rate changes, fatal-level operations, operations needing attention, session fragmentation, suspected keys, fee trends, and tool health. Each rule includes thresholds, attribution, and estimation methodology.

4 IMPROVE rules (v0.5, read-only, no automatic configuration changes):

Each suggestion includes evidence (metrics / affectedSessions / confidence) and a verificationPlan (baseline → target, window). v0.5 only supports DETECTED / DISMISSED; Apply / self-healing are reserved for future versions.

Additionally, Collaboration Review (COLLABORATION REVIEW): Observes requirement drift, delayed constraints, and context fragmentation, with up to 3 items; not displayed if insufficient data.

Read-Only and Safety Boundaries¶

• Never alters session history; statistics exclude DeepTrace’s own whale/* events.
• Repair suggestions only output plans and command templates, requiring manual confirmation.
• Secret Scan, dangerous commands, and user correction signals do not save the original text.
• Corrupted logs are salvaged read-only first; if unrecoverable, only session IDs and coarse classification reasons are disclosed.
• APIs only serve the local loopback.

Export¶

• Web report panel (includes IMPROVE and DATA PARTIAL prompts).
• PNG main report (excludes session traces and IMPROVE section).
• Session traces as a separate PNG.
• HTML (includes IMPROVE section).
• PDF (browser print of the panel report).

Installation and Enabling¶

Requires a DSH web environment. v0.5.0 is verified against DSH 0.1.1-rc.2 (peer range >=0.1.1-rc.2 <0.2.0); after upgrading DSH, restart the web instance. Node requirement: ^22.19.0 || >=24.0.0.

Recommended: DSH Plugin Installation (registers with DSH web, full functionality):

dsh plugin --profile web add "github:SenmuuuuW/dsh-whale-report"

After installation, restart dsh web to activate the host code; the client bundle updates automatically with the plugin.

Alternative: npm Package Installation (dependency only, does not automatically register the plugin):

npm install dsh-whale-report

npm install does not automatically register as a DSH plugin; the Web UI, whale_report tool, and real-time billing require the plugin installation method above. The npm method is suitable for directly importing the report engine or using the CLI to generate reports.

The plugin runs with the current dsh process permissions. Before installation, it’s recommended to review the source code and MIT license to confirm that the read-only boundaries meet your security requirements.

Typical Usage¶

Panel and Dialog¶

Two entry points:

1. Panel: When better-sidebar is installed, open the “DeepTrace” tab in the “+” menu; if not installed, a floating button in the bottom-right corner serves as a fallback.
2. Dialog: Simply say “Give me a weekly report”—the whale_report tool outputs a Markdown report.

Data uses official seams (ctx.sessionQuery + storage domain), and uninstallation leaves it clean.

CLI Local Experience (No Plugin Installation Required)¶

After cloning the repository, the CLI can directly read local session archives (~/.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       # Daily report; or --monthly / --yearal / --all
pnpm report -- --from 2026-08-01 --to 2026-08-14   # Custom interval

Use Cases and Notes¶

Suitable for: Developers who frequently run Agents in DSH and need periodic reviews of costs, tool health, risk signals, and collaboration frictions; teams seeking reproducible reports without additional LLM token costs.

Current Boundaries (as stated in the README):

• Session navigation: The report provides Session ID copying but does not yet support one-click back to the original session.
• Costs are estimates: Calculated based on official peak/off-peak pricing; the platform bill is authoritative.
• IMPROVE is read-only suggestions: Apply / self-healing / automated Verify loops are not yet implemented.
• PNG main report export currently excludes the IMPROVE section (HTML / PDF / Markdown / panel already include it).

The DSH community directory SkillHub is an independent site with no official affiliation to DeepSeek /幻方; the plugin follows DSH’s “everything is a plugin” ecosystem philosophy and is not distributed via an official app store.

Conclusion¶

dsh-whale-report transforms Agent actions into inspectable, measurable, and improvable digital reports: deterministic rules replace random commentary, read-only boundaries protect historical data, and six periodic categories cover everything from daily reports to custom intervals. If you’ve accumulated extensive sessions in DSH, it’s worth installing for periodic reviews.

• Directory page: https://www.skillhub.cn/plugins/SenmuuuuW/dsh-whale-report
• GitHub: https://github.com/SenmuuuuW/dsh-whale-report