用量报表面板 SJTUMalPan/dsh-usage-dashboard

dsh-usage-dashboard

把 dsh-usage-stats 生成的用量报表挂到 DSH 宿主 Web 服务器的 /usage。

宿主插件，纯 ESM，零依赖，不修改任何其它工程。

为什么是插件

报表属于 dsh-usage-stats 自己。DSH 宿主已经提供了两件正好够用的东西：

| 用途 | 接口 |
| 挂一条自己的 HTTP 路由 | ctx.webServer.register({kind, path, handler}) |
| 复用宿主登录态做鉴权 | ctx.connection.requestRejection(req) → 401 / 403 / undefined |

requestRejection 的文档原话是「Apply Connection's Host/Origin checks and browser authentication to another Web route」——它存在的意义就是给插件自挂的路由复用宿主的 Host/Origin 围栏与会话 Cookie。所以本插件没有自己的令牌体系：能打开 DSH GUI 的浏览器，同一 origin 下就能打开 /usage（会话 Cookie 是 Path=/; SameSite=Strict）。

安装

本插件是独立仓库（仓库根目录就是插件包，插件市场里可直接
dsh plugin --profile web add github:SJTUMalPan/dsh-usage-dashboard）。
它原先住在 dsh-usage-stats 仓库的 dsh-plugin/ 子目录，拆出来时保留了提交历史。

从 GitHub 装（跟 main）
dsh plugin --profile web add github:SJTUMalPan/dsh-usage-dashboard

从 GitHub 装（锁 commit，可复现）
dsh plugin --profile web add "git+https://github.com/SJTUMalPan/dsh-usage-dashboard#"

本机开发（符号链接，改完即生效）
dsh plugin --profile web add "link:$PWD" # 在本仓库根目录执行

dsh plugin 会把包交给 pnpm 装进 profile，然后对账 dsh.profile.bundles——只要包装了
dsh.bundle.patch，就自动把包名追加进层级列表，不需要手改 profile 的任何文件。
装完重启 dsh web 生效。

报表本身由 dsh-usage-stats 生成：

node dsh-usage.mjs --format html --out /usage-dashboard.html

把它的路径填进下面的 reportPath 即可（缺省是本包内的 report/usage-dashboard.html）。

访问

http:///usage

用的是宿主登录态：先在同一个地址登录 GUI，/usage 就直接能开，不用再抄一个令牌。
未登录返回 401，Host/Origin 不通过返回 403。

配置

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（放这里即可零配置）

path 必须是以 / 开头、非根、无尾斜杠且不含查询串/片段的绝对路径——非法值在装载期就抛错，而不是留到请求时才 404。

reportPath 可以是绝对路径，也可以相对本包根目录。

行为

| 情况 | 响应 |
| 未认证 | 401（先于读文件——否则页面会变成文件存在性探针） |
| Host/Origin 不通过 | 403 |
| 方法不是 GET/HEAD | 405 + Allow: GET, HEAD |
| 报表文件不存在 | 404，且响应体不回显配置的路径 |
| 正常 | 200，text/html，Cache-Control: no-store，X-Content-Type-Options: nosniff |

每次请求现读磁盘：重新生成报表后刷新页面即可，不需要重启 dsh web。

刷新数据

cd /path/to/dsh-usage-stats
node dsh-usage.mjs --format html --out usage-dashboard.html

卸载

dsh plugin --profile web remove dsh-usage-dashboard

路由随插件卸载自动注销（ctx.effect 的 disposer）。

测试

node --test test/*.test.mjs

用假 ctx 驱动，覆盖全部响应分支，不需要启动 dsh web——插件跑在宿主进程里，为了测它就重启 GUI 不现实。

已知边界

- 可用性跟着 dsh web 走：DSH 挂了页面就打不开。如果需要一个独立于 DSH 存活的入口，应该由本工程自己起进程，而不是挂进宿主。
- 没有 TLS：与宿主同源，沿用宿主既有的传输边界（宿主 Web 本身不带 TLS）。
- 报表含工程名、会话 id 与花费，属内部信息；不要把它挪到宿主的免鉴权路径上。