xinkeZhou-byte
dsh-usage-stats-dashboard
No description
- Stars
- 0
- Language
- JavaScript
- Created
- Aug 16, 2026
- Updated
- Aug 16, 2026
Introduction
DSH 使用统计数据看板（Usage Stats Dashboard）
为 DeepSeek Harness Web UI 开发的动态 Cordis 插件：在设置面板新增「使用统计」分区，聚合展示全部会话的使用数据，界面风格与 Web UI 原生设计一致。
目录
功能特性
在设置面板左侧导航中新增 「使用统计」 分区（位于「Agent 预设」下方），点击后内容区直接展示完整统计看板：
| 模块 | 说明 |
|---|---|
| Tokens 用量 | 全部会话累计 Token（输入 / 输出 / 缓存细分） |
| 会话数量 | 逻辑语料库中的全部会话数 |
| 消息数量 | 用户消息 + 助手消息总数（含细分） |
| 活跃天数 | 有过消息活动的本地自然日数（含工具调用次数） |
| 当前连续天数 | 截止今天（若今天暂无消息则回溯昨天）的连续活跃天数 |
| 最常使用模型 | 按消息数排名第一的模型及其消息量 |
| 活跃热力图 | 最近 30 周 GitHub 风格日历图；按当日 Tokens 用量四档着色，右上角「较少 → 较多」色阶图例；悬浮显示 日期：X Tokens · Y 轮对话 |
| 按天 Token 趋势 | 最近 30 天 SVG 柱状图，悬停显示精确值 |
| 模型用量饼图 | 环形图 + 图例，按模型 Token 用量占比（超出 Top5 聚合为「其他」） |
| 常用模型 | Top 5 横向条形排行，按 Token 数量显示 |
性能：打开即显示，无加载等待——Host 端在插件激活时后台预热统计并缓存 60 秒，客户端保留上次数据即时渲染、后台静默刷新；右上角刷新按钮可强制重算。
安装
本插件为 DSH 动态 Cordis 插件（Host + Client 双端），有两种安装路径：动态插件（会话级，即装即用） 或 官方 profile bundle（持久化，随 dsh 启动自动加载）。
环境要求：DeepSeek Harness Web UI（
dsh命令行）。bundle 方式另需 pnpm。
方式一：动态插件（推荐，零配置）
在 DSH 会话中让 Agent 使用 Cordis 动态插件工具，将 src/host.js 与 src/client.js 的内容分别作为 code.host 与 code.client 定义并运行：
@cordis 使用统计
会话级插件，无需修改任何配置；插件运行后，在设置面板左侧导航（
navList）「Agent 预设」下方即可看到「使用统计」入口。
方式二：官方 profile bundle（持久化）
将本插件以官方 bundle 形式安装进 DSH profile，随 dsh --profile web 启动自动加载：
# 从 GitHub 直接安装（推荐）
dsh plugin --profile web add "github:xinkeZhou-byte/dsh-usage-stats-dashboard#main&path:/"
# 或本地源码安装
git clone https://github.com/xinkeZhou-byte/dsh-usage-stats-dashboard.git
cd dsh-usage-stats-dashboard
dsh plugin --profile web add .
安装后启动 Web UI，设置面板左侧导航「Agent 预设」下方即可看到「使用统计」入口。
说明：bundle 方式要求插件包声明
dsh.bundle并导出cordis.patch.yml。本仓库当前以动态插件形态为主，若需正式 bundle 化（补package.json/dsh.bundle/cordis.patch.yml脚手架），欢迎提交 Issue 或 PR，或参考官方 plugin scaffold 讨论。
使用方法
- 点击左侧边栏底部的 设置 按钮；
- 在设置面板左侧导航中找到 「使用统计」（位于「Agent 预设」下方）；
- 点击进入，看板内容立即显示；
- 右上角 刷新 按钮可强制重新统计最新数据。
统计口径
| 指标 | 计算方式 |
|---|---|
| Tokens 用量 | 对每条 assistant/message 事件中 provider 上报的 usage 求和：input + output + cacheRead + cacheWrite（含缓存 Token） |
| 会话数量 | sessionQuery.listSessions() 返回的会话记录数 |
| 消息数量 | user/message + assistant/message 事件数 |
| 活跃天数 | 出现过消息事件的本地自然日数（按 YYYY-MM-DD 归日） |
| 当前连续天数 | 从今天（无消息则从昨天）向前连续有消息的天数 |
| 轮对话 | 每日 turn/start 事件数 |
| 模型归属 | assistant/message 事件 message.source 的 provider / model |
| 热力图着色 | 当日 Tokens 用量（无 Token 上报时回退为消息数），按最大值分 4 档 |
技术架构
┌────────────────────────────── 浏览器 (Client) ──────────────────────────────┐
│ settings.section 槽注册（id: usage-stats, order: 21） │
│ React + 原生 SVG 图表（零第三方依赖） │
│ 样式使用 Web UI design tokens（--dsw-alias-* / --dsw-shadow-lv3 等） │
│ │ host.call('usage-stats', { force }) │
└──────┼──────────────────────────────────────────────────────────────────────┘
▼
┌────────────────────────────── Node (Host) ──────────────────────────────────┐
│ harness.handle('usage-stats') ← Package 私有 RPC │
│ sessionQuery.listSessions() + readSession(id) 读取全部会话日志 │
│ 后台预热（激活即启动）+ 60s 缓存 + force 强制重算 │
│ 聚合：Tokens / 消息 / 轮数 / 模型 / 按天序列 │
└─────────────────────────────────────────────────────────────────────────────┘
- Host 端（
src/host.js）：通过sessionQuery服务读取逻辑语料库全部会话日志，仅提取所需标量字段聚合为 JSON，不序列化内部活数据。 - Client 端（
src/client.js）：注册settings.section槽（id: 'usage-stats',order: 21，位于 Agent 预设 order 20 之后）；所有图表（热力图 / 柱状图 / 环形图）为手写 SVG，无第三方图表库；样式变量与 Web UI 主题完全一致，自动适配明暗主题。
目录结构
dsh-usage-stats-dashboard/
├── README.md # 本文档
├── CHANGELOG.md # 版本历史（v1.0.0）
├── LICENSE # MIT 许可证
└── src/
├── host.js # Host 端代码（统计聚合 + RPC）
└── client.js # Client 端代码（设置分区 + 看板 UI）
版本历史
v1.0.0（2026-08-16）
首个正式发布版本，整合了全部开发迭代与打磨：
新增
- 设置面板左侧导航新增「使用统计」分区（位于「Agent 预设」下方），内容区内嵌展示看板
- 六项 KPI 卡片：Tokens 用量、会话数量、消息数量、活跃天数、当前连续天数、最常使用模型
- 活跃热力图（最近 30 周）：独立区块、右上角「较少→较多」色阶图例、悬浮显示「日期：Tokens · 轮对话」
- 按天 Token 趋势（最近 30 天 SVG 柱状图，日期标签完整显示）
- 模型用量饼图（环形图 + 图例，Top5 + 其他）
- 常用模型排行（按 Token 数量显示）
体验优化
- 打开即显示：Host 激活即后台预热统计 + 60 秒缓存，客户端保留上次数据即时渲染
- 支持强制刷新重算
- 入口演进：侧边栏页脚 → 设置通用页行 → 设置左侧导航项（最终形态）
技术打磨
- 手写 SVG 图表，零第三方依赖
- 样式全面使用 Web UI design tokens，自动适配明暗主题
- Host 端仅提取标量字段聚合，避免内部活数据序列化