dsh-usage-atlas

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

[图片: DSH Usage Atlas hero]

# DSH Usage Atlas

English | [中文](README.zh.md)

A detachable, model-aware usage intelligence layer for the DeepSeek Harness Web UI.

model / day · token buckets · cache health · zero telemetry

  Repository ·
  Architecture ·
  MIT License

Usage Atlas turns the durable session projections already available to DSH into a visual answer to three questions: how much did the workspace use, which model carried it, and when did it happen. It is shipped as one removable bundle with a host projection and a browser settings section, so the upstream repository keeps its original usage surface after extraction.

  [图片: Usage Atlas dashboard screenshot with model-by-day chart, token breakdown, trends, heatmap, and session details]

Real browser capture from the included local demo fixture; production data stays local to the DSH session list.

## Install

The package is designed for the Web profile and is installable because `package.json` declares a `dsh.bundle` patch.

```sh
dsh plugin --profile web add dsh-usage-atlas
dsh plugin --profile web add github:merenguesL/dsh-usage-atlas
dsh plugin --profile web add ./plugins/dsh-usage-atlas
```

Restart `dsh web` after installing so the bundle composition is rebuilt. Pin a published version or commit when using the plugin in a repeatable deployment.

## What it adds

| Surface | What you get |
| --- | --- |
| Hero band | Total tokens, exact value, week-over-week movement, and a fourteen-day sparkline. |
| KPI atlas | Today, seven-day total, cache-hit gauge, four billing buckets, calls, sessions, active days, and subagent share. |
| Model / day | UTC-day columns stacked by provider-reported model, ranked legend, focus/hover composition, and coverage note. |
| Trend studio | Daily, weekly, or monthly token bars, output mode, cache-rate mode, moving average, range filters, and peak marker. |
| Activity map | Daily detail, heuristic context composition, local-hour heatmap, and known-call hints. |
| Drill-down | Workspace and session tabs with filtering, sorting, badges, context occupancy, copy report, and RFC 4180 CSV export. |

The section is read-only. It refreshes on mount, on demand, after a connection reset, and optionally every 30 seconds.

## How it works

```text
request/header + assistant usage events
                    │
                    ▼
       dsh-usage-atlas / modelUsage projection
                    │  totals by model + 90 UTC days
                    ▼
          session.list durable projection rows
                    │
                    ▼
             Usage Atlas browser report
```

The host half registers `modelUsage` through the existing `sessionProjections` seam. The client half aggregates visible `session.list` rows and contributes a `settings.section` slot. The original `tokenUsage` projection remains owned by `dsh-token-meter`; Usage Atlas adds a separate projection so existing consumers do not need a wire-contract migration.

Model days are UTC calendar days for replay stability. The existing local-day trend and heatmap remain separate because they describe session activity rather than provider event time.

## Model Experience

None. The plugin renders a browser configuration UI and does not add prompt fields, tools, model instructions, RPC methods, or provider request fields.

#### KV Cache effect

None. It reads provider-reported usage from durable session projections and sends no model request of its own.

## Privacy and security

Usage Atlas reads the DSH session-list response already available to the Web profile, performs aggregation in the browser, and writes only a user-triggered CSV download. It has no analytics endpoint, no third-party telemetry, no credential access, and no background network destination beyond the host connection.

## Known Limitations and Deferred Work

- **Measured rows only** — a session without a usable `tokenUsage` projection contributes zero and is shown in coverage messaging instead of triggering a full-history read.
- **Model coverage is optional** — the model chart appears only when the host composition includes the `modelUsage` projection; totals still work without the model dimension.
- **Visible list scope** — deleted sessions and sessions omitted by `session.list` cannot appear in a later report.
- **Activity time is indicative** — the current list contract provides cumulative totals and an `updatedAt` marker, not per-request timestamps.
- **Known calls are a lower bound** — a nonzero session counts as one known call because exact request counts are not part of the existing projection.
- **Context data is heuristic** — occupancy and context composition are projection values, not a live provider billing statement.
- **No pricing layer yet** — the dashboard reports tokens and cache health, not currency or provider invoice totals.

## Development

The plugin is intentionally outside the upstream workspace so it can become its own repository without adding a workspace dependency or a web-app roster entry.

```sh
cd plugins/dsh-usage-atlas
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run demo
```

`lib/` is committed on purpose: GitHub installs can consume the prebuilt host and browser entries without executing a repository build. The demo serves a deterministic fixture used to refresh the README screenshot; it does not ship as part of the published package.

Maintainer release steps live in [docs/releasing.md](docs/releasing.md).

## Repository layout

```text
dsh-usage-atlas/
├── .github/workflows/ci.yml      # Node 22/24 install, test, build, and pack gate
├── .github/workflows/publish.yml # semver tag -> npm -> GitHub Release
├── assets/                 # hero artwork and browser-captured dashboard
├── docs/                   # architecture and maintainer release reference
├── lib/                    # committed installable host/client artifacts
├── scripts/                # independent build and screenshot demo entry
├── src/                    # host projection and browser settings section
├── tests/                  # projection, report, UI, and lifecycle coverage
├── pnpm-workspace.yaml     # explicit esbuild build-script approval
├── cordis.patch.yml        # one-row dsh.bundle composition patch
└── package.json            # dsh.bundle and dsh.client declarations
```

## Compatibility

The current package targets the DSH `0.1.2-alpha.1` plugin interfaces and Node.js `^22.19.0 || >=24.0.0`. The package follows the host's pre-release compatibility policy; publish a new plugin version when the DSH projection or browser slot interfaces change.

## License

MIT. The extracted DSH code retains its © 2026 DeepSeek attribution; plugin-specific additions are © 2026 merenguesL.