前言¶
用 DSH 跑智能体时，token 与花费往往分散在日志或单独脚本里。dsh-usage-stats 可以把用量汇总成 HTML 报表，但报表文件本身不会自动出现在你日常打开的 DSH GUI 同一站点里。若再单独起一个静态文件服务或复制链接，就多一层入口，鉴权也要自己接。
下面介绍 dsh-usage-dashboard：一个 DSH 宿主插件，把 dsh-usage-stats 生成的 HTML 挂到宿主 Web 的 /usage，鉴权复用宿主登录态，包体纯 ESM、零依赖，不修改其它工程。
这是什么¶
- 名称：
dsh-usage-dashboard（npm 包名同插件名） - 维护者：SJTUMalPan
- 分类：客户端（DSH 插件目录归类）
- 版本（package.json）：0.1.0；许可证：MIT；Node：>=22
- 仓库：github.com/SJTUMalPan/dsh-usage-dashboard
插件只做一件事：在 DSH 宿主进程里注册一条 HTTP 路由，按配置路径返回本地 HTML 报表文件；未登录或 Host/Origin 不通过时，走宿主已有的 requestRejection，不引入独立令牌体系。
为什么是插件而不是改 stats 工程¶
报表数据与生成逻辑仍属于 dsh-usage-stats。DSH 宿主已提供插件挂路由与复用浏览器会话的两项能力：
| 用途 | 接口 |
|---|---|
| 挂一条自己的 HTTP 路由 | ctx.webServer.register({ kind, path, handler }) |
| 复用宿主登录态做鉴权 | ctx.connection.requestRejection(req) → 401 / 403 / undefined |
文档说明 requestRejection 用于对「另一条 Web 路由」应用 Connection 的 Host/Origin 检查与浏览器认证。能打开 DSH GUI 的浏览器，在同一 origin 下通常也能打开 /usage（会话 Cookie 为 Path=/; SameSite=Strict）。
核心功能¶
- 路由挂载：默认路径
/usage，可在配置里改（须合法：以/开头、非根、无尾斜杠、无查询串/片段；非法值在装载期抛错）。 - 鉴权：先鉴权再读文件，避免未授权请求变成「文件是否存在」的探针。
- 静态 HTML 服务：支持 GET/HEAD；正常响应为
200、text/html，带Cache-Control: no-store与X-Content-Type-Options: nosniff。 - 现读磁盘：每次请求读报表文件；在 stats 侧重生成 HTML 后刷新页面即可，不必重启
dsh web。 - 与 profile 集成：包内带
dsh.bundle.patch，dsh plugin安装后会自动对账dsh.profile.bundles，一般无需手改 profile 文件。
响应行为摘要：
| 情况 | 响应 |
|---|---|
| 未认证 | 401 |
| Host/Origin 不通过 | 403 |
| 方法不是 GET/HEAD | 405，Allow: GET, HEAD |
| 报表文件不存在 | 404（响应体不回显配置路径） |
| 正常 | 200，HTML |
安装与启用¶
插件为独立仓库，在 web profile 下安装。安装后需重启 dsh web 生效。
从 GitHub 安装（跟 main）：
dsh plugin --profile web add github:SJTUMalPan/dsh-usage-dashboard
锁 commit、可复现安装：
dsh plugin --profile web add "git+https://github.com/SJTUMalPan/dsh-usage-dashboard#<sha>"
本机开发（在仓库根目录执行，符号链接，改完即生效）：
dsh plugin --profile web add "link:$PWD"
卸载：
dsh plugin --profile web remove dsh-usage-dashboard
路由随插件卸载通过 ctx.effect 的 disposer 自动注销。
典型用法¶
1. 生成报表¶
报表由 dsh-usage-stats 生成，例如：
node dsh-usage.mjs --format html --out <某个路径>/usage-dashboard.html
将输出路径填进插件配置的 reportPath。缺省时使用包内 report/usage-dashboard.html，把生成文件放到该位置可零配置。
刷新数据示例（在 stats 工程目录）：
cd /path/to/dsh-usage-stats
node dsh-usage.mjs --format html --out usage-dashboard.html
2. 配置（可选）¶
在 cordis.patch.yml 对应插件项的 config 中，两项均可省略：
- insert:
- id: usage-dashboard
name: dsh-usage-dashboard
config:
path: /usage # 挂载路径，默认 /usage
reportPath: /abs/path/to/report.html
# 默认 <本包>/report/usage-dashboard.html
reportPath 可为绝对路径，或相对本包根目录。
3. 访问¶
在浏览器先登录 DSH Web GUI，再打开：
http://<你的 dsh web 地址>/usage
未登录为 401；Host/Origin 不通过为 403。无需再抄单独令牌。
适用场景与注意¶
适合：已在用 DSH Web GUI，并希望用量报表与 GUI 同站、同登录态的内部查看；报表更新频率不高、可接受「stats 生成 HTML + 浏览器刷新」的流程。
边界与风险（README 已写明）：
- 页面可用性依赖
dsh web；DSH 未运行时/usage不可用。若需要独立于 DSH 进程的入口，应自行起服务，而不是挂进宿主。 - 无独立 TLS，传输边界与宿主 Web 一致（宿主 Web 本身不带 TLS 时，报表亦同）。
- 报表可能含工程名、会话 id、花费等内部信息；不要把挂载路径改成宿主免鉴权路由。
安装前：插件在 DSH 宿主进程内运行，权限与当前 dsh 进程一致。安装前应阅读仓库源码与 MIT 许可证，确认路径与报表内容符合你的安全策略。DeepSeek Harness 社区插件目录（如 SkillHub 上的条目）为独立生态站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-usage-dashboard 把 dsh-usage-stats 的 HTML 报表接到宿主 /usage，复用 GUI 登录态，零依赖、不改其它工程。装好插件、配置或放置报表文件、重启 dsh web 后即可在同源浏览器里查看用量。
