# DeepSeek Monitor Plugin (Peak/Valley Edition) · DSH Native

A DSH-native plugin that monitors real-time token usage and cost from your DSH
conversations, calculated using **DeepSeek's official peak/valley pricing**,
with a floating glassmorphism panel at the top-right corner of the DSH web UI.

![Plugin Screenshot](docs/panel.png)

---

## 1. Feature Overview

| Feature | Description |
|---------|-------------|
| 🧾 Today's Tokens | Real-time cumulative token consumption (input + cache read + output) |
| 💰 Today's Cost | Cost calculated with official pricing + peak/valley tier (valley = 50% off) |
| 💬 Sessions | Number of user messages sent today (`turn/start` events — one turn per interaction, excludes tool-call steps) |
| 📈 Avg / Session | Average tokens per call today |
| 🔴🟢 Status Ring | 48px breathing ring: green = valley (half price), red = peak (full price) |
| 🕐 Real-time Clock | Beijing time (UTC+8, no DST), shows HH:MM:SS + weekday |
| 📊 Quota Bar | Today's cost vs limit (default ¥10, turns yellow ≥70%, red ≥90%) |
| 🟢🔴 Legend | Valley 0.5× / Peak 1.0× with official time windows |
| 📋 Copy Report | One-click copy of today's usage summary to clipboard |
| 🔄 Refresh | Immediate data refresh (auto-polls every 2 seconds) |
| 🖱️ Drag | Drag by the header bar to reposition the panel |
| ➖ Collapse | Collapse into a pill showing current cost + tier |
| ✕ Hide | Permanently hide (state remembered in localStorage) |

---

## 2. Peak/Valley Schedule & Pricing (Official)

> Source: <https://api-docs.deepseek.com/quick_start/pricing/>

### Peak/Valley Windows (official rules, effective 2026-08-23)

| Period | Rule | Multiplier |
|--------|------|:----------:|
| **Weekdays** | Peak: 09:00–12:00, 14:00–18:00 Beijing; Valley: rest | Peak 1.0× / Valley 0.5× |
| **Weekends (Sat & Sun)** | **All-day valley pricing, no peak/valley split** | 0.5× (half) |

### Official Pricing (CNY per 1M tokens)

| Model | Item | Peak 1.0× | Valley 0.5× |
|-------|------|----------:|----------:|
| **deepseek-v4-flash** | cache hit | 0.10 | 0.05 |
| | cache miss (input) | 3.00 | 1.50 |
| | output | 9.00 | 4.50 |
| **deepseek-v4-pro** | cache hit | 0.30 | 0.15 |
| | cache miss (input) | 9.00 | 4.50 |
| | output | 27.00 | 13.50 |

> The tier is determined by the event timestamp — no splitting within a single request.

---

## 3. Data Source (Real, Not Simulated)

The plugin listens on the DSH server-side event stream:

```
DSH session events (session/event)
  └─ assistant/message event (carries TokenUsage: inputTokens / outputTokens / cacheReadTokens / cacheWriteTokens)
       └─ dsh-monitor accumulates into today's statistics
            ├─ in-memory state (served via API)
            └─ ~/.dsh/dsh-monitor.json (persisted, daily rollover at 00:00)
```

- Data comes from DSH's internal event system — **no browser extension needed**
- Counted once per completed model call (`assistant/message` event) for tokens/cost, no duplicate counting
- Sessions count `turn/start` events (agent-loop opens one turn per user interaction) — a conversation with multiple tool-call steps still counts as 1; restored from the persistence file on restart (natural-day accumulation, same as tokens)
- On restart, the plugin recovers from the persisted file and continues

---

## 4. Installation (Skip if already installed)

### 4.1 Plugin Source

```
dsh-monitor\
├── package.json          # Plugin manifest
├── lib\
│   ├── index.js          # Server: event listener, pricing, API, UI injection
│   ├── ui.js             # Client: floating panel (polls /api/dsh-monitor)
│   └── types\index.d.ts
└── README.md
```

### 4.2 Register in DSH Web Profile

1. **`~/.dsh/profiles/web/package.json`** — add dependency:

```json
{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {
    "dsh-monitor": "file:./dsh-monitor"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app"
      ]
    }
  }
}
```

> ⚠️ The `bundles` array holds bundle packages only (`@deepseek-ai/dsh-base`,
> `@deepseek-ai/dsh-web-app`). **Do not** put a single plugin in `bundles`,
> or DSH will hang on startup.

2. **`~/.dsh/profiles/web/cordis.patch.yml`** — load via `insert`:

```yaml
# Your profile patch layer (append to the end)
- insert:
    - id: dsh-monitor
      name: 'dsh-monitor'
      config:
        quotaLimit: 50   # optional: today's quota cap in CNY, default 10
```

3. **Install dependencies** (in the profile directory):

```powershell
cd ~/.dsh/profiles/web
corepack pnpm install
```

4. **Restart DSH**: `dsh web` (or however you usually start DSH)

### 4.3 Verify

- Open <http://127.0.0.1:3080/> and press **F5**
- The floating panel should appear at the top-right
- Directly visit <http://127.0.0.1:3080/api/dsh-monitor> — should return JSON

---

## 5. Usage

1. **Open**: After starting DSH, press F5 to show the panel
2. **Drag**: Grab the header bar ("DEEPSEEK · Monitor") to reposition
3. **Collapse**: Click `–` to collapse into a pill (shows cost + tier)
4. **Hide**: Click `✕` to hide permanently (state saved in localStorage)
5. **Copy Report**: Click "📋 Copy Report" for a clipboard-ready summary:

```
【DEEPSEEK Usage Report】2026-08-21 · Valley · Half Price
Tokens: 270,647 (Input 2,849 / Cache Hit 266,112 / Output 1,686)
Cost: ¥0.0252 (Peak ¥0 / Valley ¥0.0252)
Sessions: 3
Avg: 90,216 tokens/session
Quota: 0% (¥0.0252 / ¥10)
Peak/Valley: Peak 09:00-12:00/14:00-18:00 ×1.0 | Valley rest ×0.5 (daily)
Model: deepseek-v4-flash · Current rate: cache hit ¥0.05/1M · miss ¥1.5/1M · output ¥4.5/1M
```

6. **Refresh**: Click "🔄 Refresh" to poll immediately (auto-polls every 2 s)

---

## 6. Data & Persistence

### 6.1 File Structure (`~/.dsh/dsh-monitor.json`)

```json
{
  "date": "2026-08-21",
  "tokens": 270647,
  "cost": 0.0252,
  "sessions": 3,
  "inputTokens": 2849,
  "outputTokens": 1686,
  "cacheReadTokens": 266112,
  "peakCost": 0,
  "valleyCost": 0.0252,
  "history": {
    "2026-08-20": { "...": "..." }
  }
}
```

### 6.2 Daily Rollover

- At **00:00 Beijing time**, yesterday's data moves into `history`, today resets
- History keeps **90 days**, auto-prunes older entries
- System clock changes do not affect (event timestamps are used)

### 6.3 Cost Formula

```
cost = cacheRead/1e6 × cacheUnitPrice + input/1e6 × missUnitPrice + output/1e6 × outputUnitPrice
(unit prices are chosen by the event timestamp's peak/valley tier)
```

---

## 7. REST API

The frontend polls this endpoint; it can also be used by other tools.

```
GET /api/dsh-monitor
```

Example response:

```json
{
  "ok": true,
  "isValley": true,
  "tier": "valley",
  "stats": {
    "date": "2026-08-21",
    "tokens": 270647,
    "cost": 0.0252,
    "sessions": 3,
    "avgPerSession": 90216,
    "inputTokens": 2849,
    "outputTokens": 1686,
    "cacheReadTokens": 266112,
    "peakCost": 0,
    "valleyCost": 0.0252
  },
  "quota": { "used": 0.0252, "limit": 10, "pct": 0 },
  "prices": {
    "model": "deepseek-v4-flash",
    "peak":    { "cached": 0.10, "uncached": 3.0, "output": 9.0 },
    "offpeak": { "cached": 0.05, "uncached": 1.5, "output": 4.5 }
  },
  "demoMode": false,
  "updatedAt": 1787286745749,
  "peakHours": "Beijing 09:00-12:00, 14:00-18:00 (daily)",
  "valleyHours": "Rest of the day (50% off)"
}
```

---

## 8. Configuration

Built-in defaults — modify `lib/index.js` to adjust:

| Setting | Location | Default | Notes |
|---------|----------|---------|-------|
| Price table | `PRICING` constant | flash/pro official | Update when DeepSeek changes prices |
| Quota limit | `buildPayload()` → `quota.limit` | `10` (CNY) | Progress bar denominator |
| Report model | `buildPayload()` → `model` | `deepseek-v4-flash` | Model name in report |
| Poll interval | `lib/ui.js` → `pollTimer` | 2000 ms | Panel refresh rate |
| History window | `maybeRollover()` → `90` | 90 days | Rolling window |

---

## 9. FAQ

**Q1: The panel does not appear.**
A: Press F5 to refresh. Verify the index.html source contains `dsh-monitor/ui.js`. Check that DSH is the newly restarted instance.

**Q2: All numbers are 0.**
A: Send a message first. Visit `/api/dsh-monitor` and check the `_diag` field:
- `eventsSeen = 0` → event listener not active (plugin not loaded; check cordis.patch.yml)
- `eventsSeen > 0` but `assistantMessages = 0` → no assistant message completed
- `withUsage = 0` → LLM adapter did not report usage
- `accumulated > 0` → working normally

**Q3: Is data lost after restart?**
A: No. It is restored from `~/.dsh/dsh-monitor.json` on startup. Manual deletion resets to 0.

**Q4: Is the cost simulated?**
A: No. It is computed from real `TokenUsage` (input/output/cacheRead) in DSH session events, multiplied by the official price table and peak/valley tier.

**Q5: Difference from the browser extension?**
A: The browser extension injects into the page's network layer, which cannot intercept DSH model calls (they go through the Node backend). The DSH-native plugin reads the event stream directly on the server side, making it more accurate. The browser extension is still useful for `chat.deepseek.com` usage.

---

## 10. Uninstallation

1. Remove the `- insert: [...] dsh-monitor` block from `cordis.patch.yml`
2. Remove `"dsh-monitor": "file:..."` from `package.json` → `dependencies`
3. Run `corepack pnpm install` (cleans up the node_modules link)
4. Restart DSH

---

## 11. Development & Debugging

```powershell
# Syntax check
node --check lib/index.js
node --check lib/ui.js

# Start a test instance (port 3090, does not affect the production 3080 instance)
dsh web --port 3090 --no-open
# Then visit http://127.0.0.1:3090/api/dsh-monitor

# Sync source changes to profile (file: link):
cd ~/.dsh/profiles/web
corepack pnpm install
# Then restart DSH
```

> ⚠️ Changes to `lib/index.js` require `corepack pnpm install` + DSH restart to take effect. `lib/ui.js` is read at runtime, but the injection logic in `index.js` also needs a restart.

---

## Changelog

| Version | Date | Notes |
|---------|------|-------|
| 1.3.0 | 2026-08-23 | Official peak/valley rule update: weekends (Sat/Sun) now all-day valley pricing, weekdays keep original windows |
| 1.2.1 | 2026-08-21 | Fixed sessions resetting to 0 on restart; switch to `turn/start` counting (one turn per interaction, reliable for direct web messages too) |
| 1.2.0 | 2026-08-21 | Quota cap now configurable (`config.quotaLimit`, default 10) — no code changes needed |
| 1.1.0 | 2026-08-21 | Sessions count changed to user messages (`user/message` + `source.kind=user` filter), fixed multi-step tool call inflation |
| 1.0.0 | 2026-08-21 | First DSH-native release: real event accumulation, official peak/valley pricing, floating panel UI, daily rollover |