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 端仅提取标量字段聚合，避免内部活数据序列化

License

MIT