Preface¶

Harness defaults to writing sessions as local logs only. It won’t tell you how many tokens were burned, what the cache hit rate is, which models are consuming the budget, or where the P50 of output speed has dropped. To know these, you can only dig through session.v*.jsonl.zstd yourself or simply look at the bill—which is often delayed and lacks process data like cache hits and model speed.

The dsh-token-lens introduced below is a plugin designed to address this gap. It reads local session logs, and all statistics are calculated locally. It requires no internet connection, no data upload, and no API Key. It is maintained by muxili87-art and is categorized in the community as “Model Inference.” The plugin is named “TokenLens · Usage Lens,” and its function is to fold logs into a dashboard showing Tokens / Requests / Cost / Cache Hits / Model Speed.

Core Features¶

The plugin performs “Local Logs → Daily Aggregation → Dashboard Display,” covering the following information types:

• Multi-metric Overview: Today / 7 days / 30 days / All / Custom intervals, with comparable KPI cards.
• Trend Charts: Five metrics: Tokens, Requests, Cost, Model Duration, and Output Speed; supports Bar / Line toggles; filterable by model.
• Automatic Aggregation Granularity: Today: Hourly; 7 days / 30 days: Daily; Longer intervals: Weekly (Monday anchored) or Monthly.
• Heatmap: Last 53 weeks, one cell per day; colored by Requests / Tokens / Cost / Duration; click a cell to filter that day.
• Model Distribution: Proportion bars ranking by Requests / Tokens / Cost / Duration; click legend to filter.
• Speed Panel: Speed distribution (P25 / P50 / P75) and speed trend lines; supports comparison of multiple models.
• Request Details: Sortable by Time / Duration / Tokens; supports search by model and keywords; failed requests have a dedicated view.
• Privacy Mode: One-click hiding of session names, accounts, error details, and sensitive model names. Numbers remain unchanged, suitable for screenshots and sharing.
• Update Check: Top bar checks for the latest release on GitHub.
• Peak-Valley Pricing: Estimated based on Beijing Time weekday peak / off-peak tiers; built-in DeepSeek / OpenAI / Anthropic / Google public price lists.

After installation, the plugin automatically scans ~/.dsh/sessions, incrementally aggregates them into daily buckets, and caches them to ~/.dsh/usage-dashboard/cache.v1.json. Subsequent openings only perform incremental updates.

Installation and Activation¶

Prerequisites: DeepSeek Harness Desktop (development and verification version 0.2.1-rc.5).

1. Download dsh-token-lens-<version>.zip from the Release page, unzip it to any directory, and note the absolute path.
2. In the Harness session, execute:

plugin_manager install_bundle target=<absolute path to unzipped directory>

3. Fully exit and reopen DeepSeek Harness (restarting is mandatory for first load / plugin replacement, as browser-side client modules will be reassembled).
4. A “Usage Analysis” icon will appear in the left sidebar; click to enter.

To upgrade, use the new version zip to run plugin_manager install_bundle again, then fully exit and restart.

Note: The v1.0.0 zip is broken; its package.json is missing the exports["./client"] mapping, which causes Harness to throw an error during startup and fail the entire plugin assembly chain. Please use v1.0.1 or a later version.

If the application fails to start after installation, troubleshoot in this order:

1. Open the plugin directory and run the self-check:

npm run doctor

An error stating ✗ Declared dsh.client, but package.json has no exports mapping indicates the issue mentioned above; switch to v1.0.1+.

2. Uninstall and reinstall: Delete ~/.dsh/profiles/<profile>/node_modules/dsh-token-lens and delete the corresponding line in cordis.patch.yml, then restart to confirm the application is restored, and run install_bundle again.

3. If it still fails, send the error messages starting with client-modules: in the Harness startup logs to Issues.

Windows Users Note: The plugin itself is OS-agnostic (all paths use homedir() / path.join). If Harness silently exits after starting from the command line, it is usually due to environment variables HTTPS_PROXY and https_proxy existing simultaneously (case duplication); clear one of them or launch directly by double-clicking the desktop icon.

Pricing Configuration and Privacy Mode¶

Pricing is ready out of the box: a built-in general price list is provided. Models not configured will automatically match and estimate based on the Model Name. The matching order is: providers.<name> exact hit → that provider’s price list; otherwise, fall back to fallbacks using the model name (both openai/gpt-4o and gpt-4o are recognized); only if neither exists is it considered “Unpriced.” providers always take precedence over the built-in price list.

The top-level structure of pricing.json is as follows:

{
  "fx": { "USD": 7.2 },            // Convert non-CNY prices to CNY
  "peak": {
    "offsetMinutes": 480,
    "weekdays": [1, 2, 3, 4, 5],
    "windows": [["09:00", "12:00"], ["14:00", "18:00"]]
  },
  "books": { "openai-usd": { "currency": "USD", "models": {} } },
  "providers": { "official": { "book": "deepseek-official", "models": {} } },
  "fallbacks": [
    { "match": "gpt-4o-mini", "book": "openai-usd", "model": "gpt-4o-mini" },
    { "match": "gpt-4o", "book": "openai-usd", "model": "gpt-4o" }
  ]
}

Common pitfalls to watch out for:

• The key for providers.<p> must match the first part of provider/model in the session logs; only if it doesn’t match will fallbacks be used.
• fallbacks[].match defaults to prefix matching (mode can be set to prefix / contains / exact). It compares model, provider/model, and the last segment of the model name in sequence, so gpt-4o-mini must be written before gpt-4o.
• If books.<b>.currency is not CNY, it is converted via fx; the interface displays CNY uniformly.
• For models that only have an offPeak tier, they are calculated at the same tier during peak hours.
• Models estimated via the built-in price list are labeled separately in the footer and will not be mistaken for bill amounts.

After clicking the top-right button in Privacy Mode: session titles become Session 01, Session 02; accounts become Account A, Account B; error messages and search keywords are hidden; sensitive model names like /Users/..., https://..., sk-... are displayed as “Model Hidden.” Statistics numbers, charts, and costs remain unchanged.

Metrics Definition and Aggregation Granularity¶

Metrics are defined as follows:

Aggregation Granularity: Today: Hourly; 7 days / 30 days: Daily; Custom intervals ≤1 day: Hourly; ≤45 days: Daily; ≤315 days: Weekly (Monday anchored); Longer: Calendar Month. The P50 of speed is recalculated within each bucket using request-level samples, not the “average of daily P50.”

Data Accuracy¶

The single source of data is the session log file ~/.dsh/sessions/<workspace>/<session>/session.v*.jsonl.zstd. The plugin is read-only and does not write. It statistics locally recorded usage, which may differ from vendor bills (due to retries, failed requests, cache billing definitions, free quotas, etc.). “Seed” requests from forked/duplicate sessions are deduplicated to avoid counting the same historical data twice. The cache file can be deleted at any time; it will be fully rebuilt upon the next opening.

The plugin exposes two authenticated routes:

• GET /usage-dashboard/summary?from&to&tz&mode
• GET /usage-dashboard/requests?from&to&tz&view&sort&order&offset&limit&model&q

Applicable Scenarios and Notes¶

Suitable for developers who use Harness locally and want to review their token and cost expenses; also suitable for scenarios where usage data needs to be screenshot-shared but session content must not be leaked—use Privacy Mode in this case.

Three points to keep in mind:

1. The plugin runs with the permissions of the current DSH process; check the source code and license (MIT) before installing.
2. It statistics local logs, not vendor bills, and cannot be used directly as financial evidence.
3. Pricing estimates use public price lists by default. Third-party proxies or custom models with modified names need to be added in pricing.json or covered by fallbacks.

Conclusion¶

dsh-token-lens reutilizes the session logs that Harness has already recorded, filling the gaps for “process dashboards” like Tokens, Cache Hits, Cost, and Model Speed. It is entirely calculated locally, and Privacy Mode allows for sharing.

Directory: https://www.skillhub.cn/plugins/muxili87-art/dsh-token-lens

GitHub: https://github.com/muxili87-art/dsh-token-lens