@feiyang666/dsh-usage-plugin 1.9.0

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# 更新日志 / Changelog
+
+`@feiyang666/dsh-usage-plugin` — DeepSeek Harness 用量与消耗插件
+
+本文件按版本记录每一次更新的详细内容（新功能 / 优化 / 修复 / 界面 / 性能）。每次发布到 GitHub 时，请据此填写「版本发布」（GitHub Releases）的更新说明。
+
+> 版本规范：本插件按「语义化版本」递增，`主.次.补丁`。功能新增/界面变化 → 升次版本（x.y.x → x.y+1.0）；仅 bug 修复 → 升补丁。
+
+---
+
+## 未发布
+
+- 暂无待发布改动。
+
+---
+
+## 1.9.0 — 2026-08-16 · 面板宽度自动适配（最终方案）
+
+> 解决「不同窗口/屏幕大小下，宽表最右列与合计列被窗口右缘裁掉、卡片只剩半张」的问题。该问题的根因是：会话视图容器没有宽度约束，面板被宽表格/卡片撑到 max-content 宽度（约 1300px+），超出窗口右缘后被窗口本身裁掉，因此表格内部也不会出现滚动条。
+
+### 新增
+- 面板宽度以**视口封顶**：页签容器 `max-width: min(1200px, calc(100vw - 24px))`，任何窗口/屏幕大小下面板都不会超出窗口右缘。
+  - 大窗口下仍保持 1200px 水平居中；
+  - 窄窗口下跟随视口宽度收缩。
+- 宽表在容器内**横向滑动**：表格保持自然宽度（`width: max-content`），容器 `overflow-x: auto` 兜底展示完整列。
+
+### 修复
+- 修复「按模型」「按 API 服务商 × 模型」等宽表**最右列（空闲消耗 / 总消耗、合计列）显示不全**的问题——表格超出可视区时出现横向滚动条，不再被窗口裁掉。
+- 修复顶部统计卡片行**第 6/7 张卡片只有一半**的问题（卡片网格随面板宽度自动换行）。
+
+### 优化 / 界面
+- 撤掉 1.8.0 引入的「整体 CSS zoom 缩放」方案：不再把表格缩到看不清，保持默认可读字号。
+- 根容器 / 页签容器增加 `width:100% + max-width:100% + min-width:0 + box-sizing:border-box`，彻底打破 flex 宽度链导致的溢出。
+- 设置页保留原有的「底部横向滑动条」交互；工作区「用量与消耗」同样采用滑动条方案。
+
+---
+
+## 1.8.0 — 2026-08-16 · 宽表自适应（中间方案，已被 1.9.0 取代）
+
+> 首次尝试解决宽表被裁问题：引入 `FitTable` 自适应容器，表格超过容器宽度时用 CSS `zoom` 按比例缩小，配合 `ResizeObserver` 监听窗口尺寸。
+>
+> 该方案在设置页被证明「缩小得太多、字体过小、不便于阅读」，未符合预期，因此在 1.9.0 中被废弃并改为「面板宽度视口封顶 + 宽表容器内横向滚动」。**此版本不建议用于正式发布，仅保留过程记录。**
+
+### 新增
+- `FitTable` 组件：测量容器宽度与表格自然宽度，超宽时按比例缩放（下限 0.35），并监听 `ResizeObserver`/窗口 `resize` 自动恢复。
+- 所有宽表（概览两表、日历两表、缓存列表、价格两表）套用 FitTable。
+
+### 已知问题
+- 设置页在网页缩放后表格显得很小，阅读体验差。
+
+---
+
+## 1.7.0 — 2026-08-16 · 价格表官方标注 + 服务商 × 模型明细钻取
+
+### 新增
+- **价格表标注为「DeepSeek 官方 API 价格表」**：明确说明本表为 DeepSeek 官方 API 价格（单位：元 / 百万 tokens），仅涵盖官方模型 `deepseek-v4-flash` 与 `deepseek-v4-pro`，价格按官方公布固定、不可编辑。
+- **概览「按 API 服务商」升级为「按 API 服务商 × 模型」钻取明细表**：
+  - 每个服务商为一组（灰底加粗组头行），显示该服务商小计：调用数、高峰/空闲次数、各 token 合计、高峰消耗、空闲消耗、总消耗；
+  - 组头下逐行列出该服务商**每一个模型**的详细数据（调用、高峰/空闲、输入·未命中、缓存命中、输出、推理、高峰消耗、空闲消耗、总消耗），按消耗从高到低排序；
+  - 服务商按消耗降序排列（deepseek-official → opencode-go → deepseek-modlens …）；
+  - 表尾为「总费用合计」行。
+- **PNG 导出报告**的「按服务商」一节同步升级为「按 API 服务商 × 模型」分组表（组头行 + 缩进模型行 + 总费用合计行）。
+- 面板顶部新增**全局计价说明**：各模型与 API 服务商的消耗统一按 DeepSeek 官方 API 价格计费（因各厂商定价数据不完整，不按第三方另行计价；无 DeepSeek 官方价格的模型消耗按 0 统计）。
+
+### 优化 / 界面
+- 概览「按模型」表保留并继续分组展示；新增组头行样式（`tdGroup`/`tdGroupR`）。
+- 模型名与 API 服务商均以请求参数为准如实显示。
+
+---
+
+## 1.6.0 — 2026-08-16 · 区分 API 服务商 + 总费用合计 + 缓存列表性能优化
+
+### 新增
+- **按 API 服务商统计消耗**：概览新增「按 API 服务商」表，显示每个服务商（deepseek-official、opencode-go、deepseek-modlens…）的调用次数、高峰/空闲次数、高峰消耗、空闲消耗、总消耗，按消耗降序；空服务商显示「未知服务商」。
+- **总费用合计**：
+  - 概览服务商表底部「总费用合计」行（含高峰/空闲/总消耗合计）；
+  - 缓存命中列表表尾新增「总费用合计」行：整段筛选范围内的调用数、各 token 合计、命中率、高峰 + 空闲 + 总消耗。
+- 用量日历当日明细：每行的模型列下方补充该条调用的 API 服务商小字。
+- PNG 报告新增「按 API 服务商」一节。
+
+### 性能（缓存命中列表卡顿优化）
+- **分页渲染**：每页 100 条，上一页 / 下一页 + 页码指示，不再一次性渲染上千行 DOM（卡顿主因）。
+- **自动刷新 3 秒 → 10 秒**：原每 3 秒全量拉取所有记录并整表重渲染；现仅 10 秒拉取一次并增量显示。
+- 切换筛选 / 日期区间 / 清除区间时自动回到第 1 页；汇总与表尾合计仍按整个筛选范围计算，不受分页影响。
+
+### 验证
+- 实测 2700+ 条记录 → 28 页；即使接近 10 万条上限仍保持流畅。
+- 已校验「各服务商消耗之和 == 总费用合计」「高峰 + 空闲 == 总消耗」恒成立。
+
+---
+
+## 1.5.0 — 2026-08-16 · 真实模型名 + 高峰/空闲分列消耗 + 界面字号自适应
+
+### 新增 / 修复（用量）
+- **非 DeepSeek 模型不再显示「未知模型」**：模型名改为以请求参数里的真实模型名为准如实显示（`modelName` 助手）；概览、用量日历、缓存命中列表、PNG 报告均以真实模型名分组。
+  - 修复前：kimi-k3、qwen3.6-plus、glm-5.2、grok-4.5、minimax-m3 等全部合并显示为「未知模型」。
+  - 修复后：各自成行、如实显示；无 DeepSeek 官方价格的模型消耗按 0 统计。
+
+### 计价（高峰 / 空闲分列）
+- 服务端 `buildDays` 每日聚合新增**高峰 / 空闲消耗拆分字段**（按 `base`/`peakValley`/`auto` 三档各记一桶：`basePeakCost`、`pvOffPeakCost`、`autoPeakCost` 等共 6 个），作为单一天数据源；前端有「按记录回退计算」兜底，旧 host 未升级时也能正确显示。
+- **概览**：新增「高峰消耗」「空闲消耗」卡片，总消耗卡注明「高峰 + 空闲」；模型表新增高峰/空闲调用次数、高峰消耗、空闲消耗、总消耗列与合计行。
+- **用量日历**：月份卡片新增高峰消耗/空闲消耗；每日统计表改为「高峰消耗 | 空闲消耗 | 总消耗(自动)」三列（替换原 消耗(自动/峰谷/基础) 三列，列数更少更不挤）；悬停详情与当日明细都列出高峰/空闲的条数与消耗。
+- **缓存命中列表**：汇总行区分「高峰消耗 X · 空闲消耗 Y · 总消耗 Z」；每行消耗金额按峰谷着色（高峰橙 / 空闲蓝）。
+- **PNG 报告**：头部与卡片新增高峰价/空闲价消耗；模型消耗表新增高峰消耗 / 空闲消耗 / 总消耗列；模型名用真实名称；底部注明按 DeepSeek 官方价格统一计价。
+
+### 界面（显示大小自适应 + 去拥挤）
+- 面板全部字号改为 **em 相对字号**（`fs()` 辅助），随宿主「显示大小」设置的字体基准自动缩放。
+- 表格内边距加大（6px → 7px/10px）。
+- 模型列允许换行（`tdWrap`），卡片网格加宽防挤压。
+- 月份导航文字 / 日期标题同步 em 适配。
+
+---
+
+## 1.4.0 及更早（基线，未逐版本拆分）
+
+> 本项目自本日志撰写时起有记录的版本为 1.4.0。1.0.x–1.3.x 为早期迭代，未保留逐版本改动记录，以下为 1.4.0 时的完整功能基线（也是后续各版本迭代的起点）：
+
+### 插件主体
+- **Host 半**（`lib/index.js`）：监听 `llm/stream` 瀑布事件，捕获每次模型调用的 token 用量与缓存命中（输入·未命中 / 缓存命中 / 缓存写入 / 输出 / 推理 / 结束原因），写入 `<会话工作区>/dsh-usage/usage-records.json`，实时落盘、上限 100000 条、重启自动恢复。
+- **Client 半**（`lib/client.js`）：在 WebUI「对话」「轨迹」之后提供「用量与消耗」「剩余余额查询」两个 tab；设置页亦有对应入口。
+
+### 计费
+- DeepSeek 峰谷 / 基础价格表（`deepseek-v4-flash` / `deepseek-v4-pro`），支持在面板内编辑价格并持久化到 `pricing.json`，可一键恢复默认。
+- 峰谷价生效时间：北京时间 2026-08-17 00:00；生效前按基础价，生效后按高峰/空闲时段（高峰 = 北京 9:00–12:00、14:00–18:00）。
+- `auto / base / peakValley` 三档计费，导出中每行带三档费用与 `period` 标记。
+
+### 界面
+- 概览（总消耗卡片 + 按模型消耗表）；用量日历（月度热力图，按消耗或调用数着色，悬停详情、点击某天看明细 + 每日统计表）；缓存命中列表（今天/近7天/近30天/全部 + 自定义日期区间）；价格表（自动/峰谷/基础三档）。
+- 剩余余额查询：用 `DEEPSEEK_API_KEY` 调 `/user/balance` 显示总余额/充值/赠送。
+
+### 数据与导出
+- CSV / JSON / PNG 长图导出（最新在前，最多 2000 条，超出提示），支持自定义导出目录（原生目录选择器）与「打开所在目录」。
+- JSON / CSV 导入合并，按时间去重。
+- Windows / macOS / Linux 跨平台路径与原生操作适配；启动诊断日志 `dsh-usage-boot.log`。
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-usage-plugin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,272 @@
+<div align="center">
+
+# DeepSeek Harness Usage & Cost Tracker (dsh-usage-plugin)
+
+[简体中文](./README.md) · **English**
+
+[GitHub](https://github.com/feiyang-dev/dsh-usage-plugin) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-usage-plugin) · MIT License
+
+**A community plugin for DeepSeek Harness** — records token usage and cost for every model call, with peak/off-peak billing, balance query, a calendar heatmap, and CSV / JSON / PNG export.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D18-339933)
+![Platform](https://img.shields.io/badge/platform-web%20%26%20desktop-4d9fff)
+
+</div>
+
+---
+
+> ## 🔔 Important Notice (2026-08-16): npm package renamed
+>
+> The **npm package has been renamed from `@feiyang666/deepseekharnessdesktop` to `@feiyang666/dsh-usage-plugin`** (matching the GitHub repo `feiyang-dev/dsh-usage-plugin`).
+>
+> - Use the new package name for install / upgrade: `dsh plugin --profile web add @feiyang666/dsh-usage-plugin`
+> - The old package `@feiyang666/deepseekharnessdesktop` remains published for a while, but it is **no longer maintained and will not receive updates** — please migrate soon.
+> - The desktop client (`DeepSeek Harness Desktop`) supports both package names and will auto-detect old-name installs with a **one-click update** to the new name.
+
+---
+
+## Overview
+
+dsh-usage-plugin is a **usage & cost tracker** plugin in the DeepSeek Harness ecosystem (a DSH plugin shipped as a Host + Client two-in-one package). After installation, **"Usage & Cost"** and **"Balance Query"** tabs appear in the Web UI, right after "Conversation" and "Trace":
+
+> Supports **Windows / macOS / Linux**: paths are handled per platform (`node:path`), and the folder picker / "reveal in file manager" use each OS's native mechanism (macOS: `osascript` / `open`; Linux: `zenity` / `xdg-open`). Balance query and export do not depend on Windows-only commands.
+
+- **Usage & Cost**: records each model call's token usage and cache hits (input miss / cache hit / cache write / output / reasoning / finish reason), and computes cost using DeepSeek's peak/valley or base pricing (peak hours are automatically priced by Beijing time 09:00–12:00 and 14:00–18:00). Model names come from the actual request parameters, so non-DeepSeek models are shown truthfully instead of "unknown model"; models without an official price are counted as 0. The overview shows a by-model table plus a by-API-provider × model drill-down (each provider grouped with every model's calls and peak/off-peak cost split) and a grand total row.
+- **Usage Calendar**: a monthly daily-usage heatmap (colored by cost or call count), hover for details including the peak/off-peak cost split, click a day for its call list and peak/off-peak totals, plus a per-day statistics table with peak cost / off-peak cost / total columns and monthly rollups.
+- **Cache Hit List**: newest-first, fully scrollable, with quick filters (Today / 7 days / 30 days / All) and custom date ranges; the summary line and footer total split peak vs off-peak consumption with a grand cost total. The list is paginated (100 rows per page), so it stays smooth even with large data volumes.
+- **Price Table**: the official DeepSeek API price table — base and peak/valley unit prices shown side by side (peak vs off-peak), editable in-panel and persisted to `pricing.json`, with a reset-to-default option.
+- **Balance Query**: queries your DeepSeek account balance using the configured `DEEPSEEK_API_KEY`.
+- **Export**: CSV / JSON / **PNG long image** (newest-first, up to the latest 2000 records, warns if exceeded; the PNG report includes peak/off-peak cost columns), to any directory (native picker), auto-opens the folder after export.
+- **Import**: merge-imports JSON / CSV files, deduplicated by time.
+- **Persistence**: records are written live to `<session workspace>/dsh-usage/usage-records.json` and restored on restart (cap 100000 records).
+- **UI adaptation**: panel typography scales with the app's display-size setting (em-relative fonts); table wrapping and spacing are tuned so large display sizes stay readable.
+
+---
+
+## Screenshots
+
+### Usage & Consumption
+![Usage & Consumption](./docs/assets/usage-overview.png)
+
+### Balance Query
+![Balance Query](./docs/assets/balance-query.png)
+
+## Recommended Installation
+
+> Either method works and is equivalent. **We recommend the desktop app** — fully graphical, no command line needed.
+
+### Option 1 (recommended): One-click via the desktop app
+
+Install [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop), open it, then go to **"Install Plugins" → Recommended → Usage & Cost Tracker → Install** and click **"Restart Service Now"** to activate.
+
+### Option 2: Command line
+
+```bash
+# Prerequisite: install dsh (npm install -g @deepseek-ai/dsh)
+dsh plugin --profile web add @feiyang666/dsh-usage-plugin
+```
+
+Or install to another profile:
+
+```bash
+dsh plugin --profile web add @feiyang666/dsh-usage-plugin
+dsh plugin --profile headless add @feiyang666/dsh-usage-plugin
+```
+
+Restart the dsh web service after installation. Detailed manual install / wiring / uninstall / troubleshooting follows below.
+
+---
+
+## What's in the package
+
+One npm package = a **host half** (Node-side Cordis plugin: recording, billing, balance query, export — see `lib/index.js`) + a **client half** (browser-side panel — see `lib/client.js`, which talks to the host via `/usage/api`).
+
+The package integrates with DSH through two declarations:
+
+| Declaration | Purpose |
+| --- | --- |
+| `dsh.bundle.patch` (`cordis.patch.yml`) | Lets DSH recognize it as a **standard bundle plugin package**: `dsh plugin --profile <name> add <package>` installs and wires it in one command, no manual config editing |
+| `dsh.client` + `exports["./client"]` | Lets the web client auto-load the browser panel at `/plugins/<package>/client.js` |
+
+So for users, **installation is one command** — no YAML editing, no manual file copying.
+
+---
+
+## Installation (for users)
+
+### 0. Prerequisites
+
+- DeepSeek Harness installed (`npm install -g @deepseek-ai/dsh`, or a desktop app built on it, or `npx @deepseek-ai/dsh web`).
+- Option A (recommended) needs **pnpm**: `npm install -g pnpm` (or `corepack enable`).
+- Make sure `dsh` is on PATH (for the desktop app, run in its bundled terminal).
+
+### 1. Method A (recommended): one command
+
+```bash
+dsh plugin --profile web add @feiyang666/dsh-usage-plugin
+```
+
+This does three things (all automatic):
+
+1. Installs the package via pnpm into `~/.dsh/profiles/web` (auto-initializes the profile on first use);
+2. Detects the package's `dsh.bundle` declaration and writes the package name into the profile's `dsh.profile.bundles` layer list;
+3. After restart, DSH reads the package's `cordis.patch.yml` and mounts the plugin row into the app tree — **no manual config editing**.
+
+Same for other profiles (replace `web` with your profile name, e.g. `dsh plugin --profile headless add ...`; `dsh web` equals `dsh --profile web`).
+
+> Test a local tarball: `dsh plugin --profile web add C:\path\to\feiyang666-deepseekharnessdesktop-1.1.0.tgz`
+
+### 2. Method B: manual install (no pnpm / no `dsh plugin`)
+
+Only for when you have no pnpm or want full manual control. **Do not `npm install` directly at `~/.dsh/profiles`** (that dir has no package.json; npm would treat the whole node_modules as residue and wipe it).
+
+**B1. Use pnpm but not `dsh plugin`:**
+
+```bash
+cd ~/.dsh/profiles/web
+pnpm add @feiyang666/dsh-usage-plugin
+# then manually append the plugin row to web/cordis.patch.yml (see B3) and restart
+```
+
+**B2. Or use npm:** add a minimal package.json to the profile first, then install:
+
+```bash
+cd ~/.dsh/profiles/web
+# if no package.json exists there yet (only after `dsh plugin` init):
+# echo '{"name":"dsh-profile-web","private":true,"dependencies":{}}' > package.json
+npm install @feiyang666/dsh-usage-plugin
+```
+
+**B3. Wire it up (once, idempotent):** append to `~/.dsh/profiles/web/cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: usage-plugin
+      name: '@feiyang666/dsh-usage-plugin'
+      inject:
+        - fs
+        - webServer
+        - subprocess
+        - credentials
+        - sandboxPolicy
+        - agents
+```
+
+Or just run the package's built-in wiring script (auto-finds the profile and appends, idempotent):
+
+```bash
+node node_modules/@feiyang666/dsh-usage-plugin/scripts/wire.js
+```
+
+> ⚠️ The `inject` list is **required**: it makes Cordis wait until `fs` / `webServer` / `subprocess` / `credentials` / `sandboxPolicy` / `agents` are ready before activating the plugin. Without it the `/usage/api` route never registers and the panel fails with `Unexpected end of JSON input`.
+
+### 3. Method C: desktop app
+
+The desktop app (e.g. [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)) uses the same `~/.dsh/profiles` underneath. Run Method A's command in any terminal, restart the app, and the plugin activates automatically (the app starts the same `dsh web`).
+
+### 4. Restart and verify
+
+Restart the DeepSeek Harness web app (command line: kill the old process and re-run `dsh web`; desktop: fully quit and reopen). Then:
+
+- Refresh http://127.0.0.1:3080 — after "Conversation" and "Trace", you should see **"Usage & Cost"** and **"Balance Query"** tabs; there are entries in Settings too.
+- The "Usage & Cost" panel contains **Overview / Usage Calendar / Cache Hit List / Price Table** subtabs.
+- Send a message and the "Usage & Cost" panel should show this call's token / cost record.
+
+### 5. Configuration (for balance query)
+
+"Balance Query" uses the configured `DEEPSEEK_API_KEY`: set the API Key in **Settings → Models** (same key used for chats), then open the "Balance Query" tab and click "Query Balance".
+
+---
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove @feiyang666/dsh-usage-plugin
+```
+
+(Equivalent to pnpm remove; `dsh plugin` auto-removes the package name from the `dsh.profile.bundles` layer list.) Restart the app afterward.
+
+For manual installs (Method B), do it in reverse: remove the `usage-plugin` row from `cordis.patch.yml`, then `pnpm remove` / `npm uninstall` the package, and restart.
+
+> Upgrading from a 1.0.x manual-wiring install to 1.1.x: first remove the old `usage-plugin` row from `cordis.patch.yml` (or follow the uninstall flow), then reinstall via Method A to avoid mounting the plugin twice.
+
+---
+
+## Data & locations
+
+- Records: `<session workspace>/dsh-usage/usage-records.json`
+- Price config (edited & saved in the panel): `<session workspace>/dsh-usage/pricing.json`
+- Default export dir: `<session workspace>/dsh-usage/{csv,json,images}/`
+- Custom export dir: set in the panel's "Export target directory" or click "Choose directory…"
+- Startup diagnostics (if the plugin fails to activate): `dsh-usage-boot.log` in the session workspace
+
+---
+
+## FAQ
+
+| Symptom | Cause / Fix |
+| --- | --- |
+| Panel reports `Unexpected end of JSON input` | The plugin row is missing the `inject` list, so the route isn't registered. Add the inject list per Method B3 and restart |
+| Panel blank / no top tab | Plugin not activated. Check `dsh-usage-boot.log`; confirm the `cordis.patch.yml` row exists with the correct `name` |
+| Balance query fails with "DEEPSEEK_API_KEY not configured" | Set the API Key in Settings → Models |
+| Balance query network error | Ensure `api.deepseek.com` is reachable (configure a proxy if needed) |
+| `dsh plugin` reports pnpm not found | Install pnpm: `npm install -g pnpm` |
+| Install can't reach the npm registry | Set a mirror: `npm config set registry https://registry.npmmirror.com` (or `pnpm config set registry ...`) and retry |
+| After uninstall, still reports `Cannot find package '@feiyang666/...'` | A package reference remains in the profile. Remove the corresponding row from `cordis.patch.yml` and the package name from `dsh.profile.bundles`, then restart |
+
+---
+
+## Publish to npm (for maintainers)
+
+```bash
+npm login                                  # use your own npm account
+npm run check                              # pre-publish self-check (also runs via prepublishOnly)
+npm pack                                   # inspect the tarball contents
+npm publish --access public                # scoped packages must use --access public
+```
+
+> Publishing to public npm makes the source public — make sure no sensitive info is in the package (API keys are user-configured at runtime only).
+> If your network can't reach `registry.npmjs.org`, run `npm config set registry https://registry.npmjs.org` before publishing (the package's `.npmrc` presets this registry).
+
+---
+
+## Related Projects
+
+| Project | Description | Installation |
+| --- | --- | --- |
+| [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop) | Windows desktop console: install/start/stop/restart the dsh web service with one click, built-in plugin management — **install this plugin from its Recommended section** | Download the desktop app and click a few buttons |
+| [Data Vault (dsh-vault)](https://github.com/feiyang-dev/dsh-vault) | Auto backup / wipe detection / one-click restore — protects chat history and workspace data | One-click from the desktop app, or `dsh plugin add @feiyang666/dsh-vault` |
+| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | Official CLI / Web service | Quick start below |
+
+### Running DeepSeek Harness
+
+**Quick start (via npm)**
+
+Install Node.js, then run:
+
+```bash
+npx @deepseek-ai/dsh web
+```
+
+This command starts the Web UI at the default address http://127.0.0.1:3080. See the [Web UI Guide](https://github.com/deepseek-ai/DeepSeek-Harness) for details.
+
+**Run from source**
+
+To run from the repository source:
+
+```bash
+git clone https://github.com/deepseek-ai/deepseek-harness.git
+cd deepseek-harness
+pnpm install
+pnpm run build
+pnpm dsh web
+```
+
+## Acknowledgements
+
+- **[@liu3734](https://github.com/liu3734)**: reported and diagnosed the Windows-only path handling / spawn issues on macOS (POSIX) and proposed the cross-platform fix ([#1](https://github.com/feiyang-dev/dsh-usage-plugin/issues/1)).
+
+## License
+
+MIT © dsh-usage-plugin