# dsh-usage-stat

<p align="center">
  <strong>简体中文</strong> · <a href="README.en.md">English</a>
</p>

<p align="center">
  <a href="https://github.com/oujnit/dsh-usage-stat/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/oujnit/dsh-usage-stat/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/oujnit/dsh-usage-stat/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/oujnit/dsh-usage-stat"></a>
  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>

DSH Desktop 的本机主页概览插件。在没有打开其他会话时自动显示主页，也可以从“新会话”下方的顶部导航入口随时打开。

插件只读汇总 DSH 本机会话日志，不修改会话，也不会把统计数据发送到外部服务。

## 功能

- 今天、本周、本月的活跃项目、会话、模型调用和 Token 用量；
- 近 30 天 Token 趋势、活跃天数和峰值日期；
- 缓存复用率、平均输出量、主力模型与模型分布；
- 最近使用的会话和项目活动记录；
- 会话扫描耗时、读取失败数量和数据生成时间；
- 5 分钟内存缓存，以及“立即刷新”强制重算。

统计服务最多并发读取 4 个会话，避免一次打开大量历史日志时压垮本机。单个损坏或无法读取的会话会被隔离，并在主页显示失败数量。

## 安装

推荐安装固定版本到 DSH Desktop 使用的 `desktop` profile：

```sh
dsh plugin --profile desktop add https://github.com/oujnit/dsh-usage-stat/releases/download/v0.2.3/dsh-usage-stat-0.2.3.tgz
```

也可以跟随 `main` 分支安装：

```sh
dsh plugin --profile desktop add github:oujnit/dsh-usage-stat
```

安装后检查最终配置：

```sh
dsh --profile desktop --dump-config
```

完全退出并重新打开 DSH Desktop。进入 **设置 → 插件 → 插件**，确认 `usage-stat` 显示“运行中 / 已启用”。

卸载：

```sh
dsh plugin --profile desktop remove dsh-usage-stat
```

## 统计口径

- 模型调用来自会话日志中的 `assistant/message` 模型消息，包含子代理产生的调用；
- Token 数值采用 provider 写入日志的上报值，普通输入、输出、缓存读取和缓存写入分别统计；
- 自然日使用运行 DSH Desktop 的本机时区，一周从周一开始；
- 缓存复用率 = 缓存读取 ÷（普通输入 + 缓存读取）；
- 项目按会话记录的工作目录汇总；最近使用记录按最后一条事件排序。

如果 provider 没有上报某类 Token，该项会显示为 0。这是日志统计，不是账单金额，也不能替代服务商的官方计费记录。

## 隐私与安全

插件不接入遥测服务，不上传统计结果，也不写入会话。浏览器通过同源的 `/api/usage/state` 读取本机聚合结果。

接口响应包含会话标题、工作目录和模型名称。如果你把 DSH Web 服务暴露给其他设备或网络，请沿用 DSH 自身的访问控制，不要把未受保护的服务开放给不可信用户。

## 兼容性

`v0.2.2` 已在以下环境完成真实运行验证：

- DSH Desktop 2.0.2；
- Desktop 内置 DSH 0.1.1-rc.2；
- macOS arm64；
- 浅色界面下的主页、任务看板、SSH 和技能中心并存场景。

客户端入口使用 DSH Desktop 当前提供的侧边栏和中央面板扩展位置。DSH Desktop 大幅调整 Web UI 结构后，旧版插件可能需要同步升级。

## 本地开发

需要 Node.js `^22.19.0 || >=24.0.0` 和 pnpm 11.7.0：

```sh
pnpm install --frozen-lockfile
pnpm run check
pnpm pack --dry-run
```

本地安装当前 checkout：

```sh
dsh plugin --profile desktop add .
```

`lib/` 构建产物会提交到仓库，GitHub 安装不需要在用户机器上执行构建脚本。

## 许可证

[MIT](LICENSE)