dsh-activity-tracker

Readme

# dsh-activity-tracker

[![樱落生态成员](https://raw.githubusercontent.com/Guyao146/Sakura-EcoSystem-wiki/main/assets/ConnectEcoSystem.svg)](https://mcylyr.cn)
[![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-4c7dff)](https://github.com/deepseek-ai/deepseek-harness)
[![已编写Wiki](https://raw.githubusercontent.com/Guyao146/Sakura-EcoSystem-wiki/main/assets/sakura-wiki.svg)](https://wiki.mcylyr.cn/)

`dsh-activity-tracker` 是一个面向 **DeepSeek Harness（DSH）Web** 的本地活动统计插件。它读取 DSH 已有的会话记录，将用户输入、代码编辑、命令执行、检索阅读、其他工具调用以及 Token 消耗按日期、小时和项目聚合，并在 DSH 侧栏中提供可视化统计面板。

> 默认情况下，所有统计均在运行 DSH 的本机完成。只有主动完成生活看板配对，并授权指定工作区查看会话详情时，插件才会通过 HMAC 签名 HTTPS 向生活看板推送该工作区的最近输出。

## 樱落生态Wiki
该项目已编写Wiki，了解插件更多细节 https://wiki.mcylyr.cn

## 功能特性

- **统计概览**：展示输入 Token、输出 Token、缓存读取 Token、活动事件数和会话数。
- **活跃热力图**：以 GitHub Contributions 风格展示近 26 周的活动强度。
- **24 小时活动分布**：按小时查看不同类型事件的堆叠分布。
- **24 小时 Token 分布**：查看一天中各小时的 Token 使用情况。
- **当日事件时间线**：展示事件发生时间、事件类型、工具名称、内容摘要、项目和模型。
- **每日汇总表**：汇总近 31 个活跃日的事件数与 Token 消耗。
- **费用统计**：按项目、模型、项目 × 模型和日期查看 Sub2API 价格计算结果。
- **Sub2API 账号登录与价格同步**：支持账号密码登录、TOTP 二次验证、Token 自动续期、手动同步、每天首次启动自动同步和每日价格历史快照。
- **Sub2API 账户摘要**：登录后显示中转站名称、当前账号、余额以及已订阅分组的月度使用量/额度。
- **余额卡片**：账户余额直接并入活动概览卡片，不再单独占用顶部提示条。
- **可定制仪表盘**：在“总设置”中开关模块、选择小/中/大三档样式、拖拽模块排序，并拖动面板边缘或使用滑块调整宽度。
- **灵活日期范围**：支持今天、7 天、15 天、30 天、自定义日期和全部；热力图、概览、每日汇总会同步当前范围。
- **长范围翻页**：自定义范围超过 30 天时按 30 天窗口左右翻页。
- **卡片快捷设置**：每个仪表盘模块右上角都有三点菜单，可直接选择小、中、大或关闭。
- **宿主持久化**：模块开关、尺寸、顺序、宽度和筛选同时保存到 DSH 宿主机，重启后自动恢复。
- **容器响应式布局**：根据活动面板自身宽度而不是浏览器窗口宽度自动重排；窄面板会将模块切为整行，概览卡片自动切换为 3 / 2 / 1 列。
- **多项目过滤**：按 DSH 会话的工作目录区分项目，可查看全部或单个项目。
- **会话过滤**：可在全部项目或选定项目下继续选择单个会话，所有概览、图表、热力图和时间线同步过滤。
- **统一筛选栏**：项目、会话与日期选择器使用统一高度和响应式列宽；关闭按钮固定在标题栏右上角。
- **时间范围过滤**：支持今日、近 7 天、近 30 天和全部记录。
- **本地时区统计**：所有日期和小时均按照 DSH 宿主机的本地时区计算。
- **增量解析缓存**：根据会话文件的修改时间和大小复用解析结果，减少重复扫描开销。
- **侧栏入口自恢复**：通过 `MutationObserver` 在 DSH 页面更新后自动恢复“活动统计”入口。
- **明暗主题适配**：统计浮层可跟随浏览器的浅色或深色主题。
- **生活看板实时工作区**：按工作区分组推送会话快照；生活看板每 10 秒获取最新工作区状态、会话和工具输出，管理员可向当前运行中的 DSH 会话发送后续消息。
- **五态状态灯**：工作区与会话统一显示“已完成、遇到错误、需要选择、正在进行任务、休眠中”；错误结果和待批准操作优先识别。
- **最小化输出授权**：未勾选“允许查看会话详情”的工作区只上传汇总统计，不传输会话标题、对话或工具输出。
- **六位码一键配对**：在生活看板生成一次性验证码后，直接在 DSH「活动统计 → 总设置」完成连接，无需手动创建或编辑 JSON 配置文件。
- **归档会话管理**：在“已归档”标签中搜索和查看本机已归档对话，确认后可恢复到 DSH 会话列表；恢复不会移动、覆盖或删除原始会话文件。

## 面板内容

预览：
<img width="1234" height="1269" alt="image" src="https://github.com/user-attachments/assets/46a91d7d-53e8-42bc-93c3-a3896e3701a0" />

## 环境要求

- 已安装并能够正常运行的 DSH Web 环境。
- DSH 能够加载本地插件和 Web 客户端扩展。
- **Node.js 22.15+ 或 24+**，且运行时需要提供 `node:zlib` 的 `zstdDecompressSync`。
- 本机存在可读取的 DSH 会话目录：`~/.dsh/sessions`。

Windows 默认对应：

```text
C:\Users\<用户名>\.dsh\sessions
```

如果设置了 `DSH_HOME` 环境变量，插件会改为读取：

```text
%DSH_HOME%\sessions
```

## 安装

Web版本 DSH
```bash
dsh plugin --profile web add dsh-activity-tracker@latest
```

Desktop版本 DSH
```bash
dsh plugin --profile desktop add dsh-activity-tracker@latest
```

安装后请**重启 DSH **。页面加载完成后，“新会话”按钮下方会出现 **📊 活动统计** 入口。

> `cordis.patch.yml` 会由 DSH 的插件安装流程读取，并自动添加 `activity-tracker` 插件配置。

## 使用方法

1. 启动或重启 DSH Web。
2. 在 DSH 左侧栏找到 **活动统计**。
3. 点击入口打开统计浮层。
4. 使用顶部筛选器选择项目、会话和时间范围。
5. 点击热力图日期或每日汇总表中的日期，查看当天的小时分布和事件时间线。
6. 新会话产生数据后，点击右上角的 **刷新** 重新扫描。
7. 如需连接生活看板，进入“总设置 → 生活看板连接”完成六位码配对；仅对需要在看板查看实时输出的工作区勾选“允许查看会话详情”。
8. 如需找回归档对话，打开“已归档”，搜索并选择会话查看记录，点击“恢复会话”并确认。

## 已归档对话

DSH 归档会话时只会把会话 ID 加入 Workspace Registry 的 `archivedSessionIds`，本地 `~/.dsh/sessions` 日志仍然保留。本插件使用 DSH 官方 `workspaceRegistry` 状态原语读取归档集合，并提供：

- 按标题、项目名称或会话 ID 搜索；
- 查看会话轮次、记录数、最后活动时间和受限记录详情；
- 长会话最多展示最近 500 条、总文本约 1 MiB 的记录，避免界面卡顿；
- 恢复前二次确认；
- 恢复请求串行执行，并在写入后再次校验归档状态；
- 恢复只从 `archivedSessionIds` 移除目标 ID，不修改原始 zstd 日志。

本地接口均要求 `X-DSH-Activity: 1`：

```http
GET  /dsh-activity/api/archives
GET  /dsh-activity/api/archives/detail?session=<session-id>
POST /dsh-activity/api/archives/restore
Content-Type: application/json

{"sessionId":"session-..."}
```

如果归档注册表仍有 ID、但对应会话文件已经被其他工具永久删除，列表会把它计入“记录缺失”，且不会提供虚假的恢复操作。

## 已知限制

- 仅统计当前 DSH 数据目录中仍然存在的会话文件。
- 首次扫描大量历史会话时可能需要一定时间。
- 项目筛选标识基于完整工作目录；项目移动后会被视为不同项目。
- 工具分类采用名称匹配规则，新工具可能暂时显示为“其他工具”。
- 生活看板输出刷新间隔最短为 10 秒，不是逐 Token 流式传输；DSH 本机离线或推送失败时看板会显示离线状态。
- 已授权工作区的最近 120 条会话记录会传输到生活看板；请只对可接受该访问范围的工作区启用详情授权。
- 归档恢复依赖当前 DSH 的 `workspaceRegistry.requireState()` / `setState()`；不提供这些公开状态原语的旧 DSH 版本会显示“不支持恢复”，不会直接修改 `workspace.json`。


## 许可证

本项目采用 [GNU Lesser General Public License v2.1（LGPL-2.1-only）](LICENSE) 发布。

你可以在 LGPL-2.1 的条件下使用、修改和再分发本插件；再分发时应保留许可证文本、版权声明和相应的源码获取方式。插件按“原样”提供，不附带任何担保。