dsh-usage-atlas

v0.2.0

Published

2 days ago

A detachable usage atlas and model-attributed token projection for the DeepSeek Harness Web UI

0High
0Medium
0Low

merenguesl

deepseek deepseek-harness dsh dsh-plugin token-usage usage-atlas

DSH Usage Atlas

English | 中文

Usage Atlas 把 DSH 已经持久化的会话投影转成三个直观答案：工作区用了多少、由哪个模型完成、发生在哪些日期。它以一个可移除的 bundle 发布，同时包含宿主投影和浏览器设置区块；迁移完成后，上游仓库仍保持原本的用量表面。

Install

插件面向 Web profile；package.json 声明了 dsh.bundle patch，因此可以被 DSH 安装。

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

安装后重启 dsh web，让 bundle 重新组合。需要可重复部署时，请固定已发布版本或 Git commit。

What it adds

| 表面 | 能力 | | --- | --- | | Hero 主视觉 | 总 token、精确值、周环比变化和 14 日迷你走势。 | | KPI 图谱 | 今日、近 7 日、缓存命中率仪表、四个计费桶、调用、会话、活跃天数和子代理占比。 | | 模型 / 日期 | 按 provider 上报模型堆叠的 UTC 日柱图、排名图例、聚焦/悬停构成和覆盖提示。 | | 趋势工作台 | 日/周/月 token 柱图、输出模式、缓存率模式、移动平均、范围筛选和峰值标记。 | | 活跃地图 | 每日明细、启发式上下文构成、本地小时热力图和已知调用提示。 | | 明细下钻 | 工作区与会话标签、过滤、排序、徽标、上下文占用、报告复制和 RFC 4180 CSV 导出。 |

区块是只读的：首次挂载、手动刷新、连接重置后以及可选的每 30 秒自动刷新都会重新读取数据。

How it works

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

宿主部分通过现有 sessionProjections seam 注册 modelUsage。客户端部分聚合可见的 session.list 行，并通过 settings.section 插槽贡献设置区块。原有 tokenUsage 投影仍由 dsh-token-meter 所有；Usage Atlas 使用独立投影，因此不要求已有消费者迁移 wire 契约。

模型日期使用 UTC 日历日，保证重放结果不随时区变化。原有按本地日计算的趋势和热力图保持独立，因为它们描述会话活动时间，而不是 provider 事件时间。

Model Experience

无。插件只渲染浏览器配置页，不增加 prompt 字段、工具、模型指令、RPC 方法或 provider 请求字段。

KV Cache effect

无。插件读取持久化会话投影中的 provider 用量，不自行发送模型请求。

Privacy and security

Usage Atlas 读取 Web profile 已经可用的 DSH 会话列表，在浏览器内完成聚合，并且只在用户点击时写出 CSV。它没有分析端点、第三方遥测、凭据访问，也没有除宿主连接之外的后台网络目标。

Known Limitations and Deferred Work

只统计有投影的行 —— 没有可用 tokenUsage 投影的会话按零处理，并通过覆盖提示展示，不触发完整历史读取。
模型覆盖是可选的 —— 只有宿主组合包含 modelUsage 投影时才显示模型图；没有模型维度时总量仍然可用。
范围受可见列表限制 —— 已删除会话和 session.list 未返回的会话不会出现在后续报告中。
活动时间只是指示值 —— 当前列表契约提供累计总量与 updatedAt 标记，没有逐请求时间戳。
已知调用是下限 —— 现有投影没有精确请求数，因此非零会话只计为一次已知调用。
上下文数据是启发式的 —— 上下文占用与构成来自投影值，不是 provider 的实时计费单据。
暂不计算价格 —— 仪表盘报告 token 与缓存健康度，不报告货币金额或 provider 账单总额。

Development

插件有意位于上游 workspace 之外，以便直接变成独立仓库，不向上游增加 workspace 依赖或 web-app roster 条目。

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

lib/ 会被有意提交：从 GitHub 安装时可以直接消费预构建的宿主与浏览器入口，不需要执行仓库构建。demo 使用确定性的 fixture 刷新 README 截图，不会进入发布包。

维护者发布步骤见 docs/releasing.md；文档内提供中文入口。

Repository layout

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

当前包面向 DSH 0.1.1-rc.2 插件接口和 Node.js ^22.19.0 || >=24.0.0。包遵循宿主的预发布兼容策略；当 DSH 投影或浏览器插槽接口变化时，请发布新的插件版本。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme