dingyi222666/dsh-wakatime

@dingyi222666/dsh-wakatime

npm version
GitHub

为 DeepSeek Harness (dsh) 开发的 WakaTime 插件 —— 统计你的 AI 编码活动、代码行数与耗时。由 opencode-wakatime 适配到 dsh 的插件模型。

安装

从 npm 安装（需要 dsh >= 0.1.3-alpha.2）
dsh plugin --profile web add @dingyi222666/dsh-wakatime
重启 dsh web 生效
dsh web

插件适用于任何运行 agent 循环的 profile —— web、headless、tui 等。每个要用的 profile 都需要安装一次：

dsh plugin --profile headless add @dingyi222666/dsh-wakatime

从源码安装（GitHub）

git clone https://github.com/dingyi222666/dsh-wakatime
cd dsh-wakatime
pnpm install && pnpm run build
dsh plugin --profile web add .
dsh web

说明：

- dsh plugin 等同于向 profile 添加依赖。bundle 插件的完整包名出现在 profile 的 dsh.profile.bundles 列表后即被加载（自动添加）；bundle 补丁（cordis.patch.yml）在下一次启动时生效。
- 更新时重新执行相同命令即可。
- 使用仓库源码启动的 CLI 时，直接通过 bin 传入参数（node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add @dingyi222666/dsh-wakatime）。

配置

插件开箱即用。如需覆盖行为，在 profile 的用户补丁层
（$DSH_HOME/profiles//cordis.patch.yml）或通过 --patch 声明同 id（wakatime）的配置行：

- id: wakatime
config:
heartbeatIntervalMs: 120000  # 每项目限频间隔（默认 60000 毫秒）
debug: true                  # 强制 DEBUG 日志（默认跟随 ~/.wakatime.cfg 的 debug=true）
client: web                  # --plugin 字符串中的客户端限定名（默认 "dsh"）
timeoutMs: 45000             # heartbeat CLI 超时（默认 30000 毫秒）

所有字段均可选，加载时由 schemastery schema 校验。

功能

- 自动管理 CLI —— 自动下载并更新 wakatime-cli；检测到全局安装（brew install wakatime-cli）时直接使用
- 细粒度文件追踪 —— 追踪 agent 执行的文件操作：edit、write、read、read_image，以及 str_replace_editor（view/create/str_replace/insert）
- 解析路径准确性（dsh 0.1.3-alpha.1） —— 优先读取 fs 工具持久化在 tool/result meta 中的信息：沙箱解析后的实际路径与精确 diff hunk；没有 meta 时回退到调用参数
- AI 编码指标 —— 发送 --ai-line-changes 供 WakaTime AI 编码分析使用；行数根据 fs 工具的 diff hunk 精确计算（上下文行已剔除）
- 实时活动 heartbeat（dsh 0.1.3-alpha.1） —— 长时间回合流式输出期间，agent/status 状态切换与 agent/assistant-stream 事件流会以接近实时的节奏对当前文件发送 heartbeat，无需等待持久化结算事件
- 限频 heartbeat —— 每个项目每分钟最多 1 次，状态持久化到磁盘，多个 dsh 进程共享配额（持久化变更与实时活动共用同一配额）
- 会话生命周期 —— 会话销毁与插件树卸载时强制冲刷待发送 heartbeat，单次 dsh --profile headless 运行也能上报
- 批量工具支持 —— 一次编辑涉及多个文件时，通过 --extra-heartbeats 在单次 wakatime-cli 调用中发送
- 零运行时依赖 —— 构建产物只依赖 Node 内置模块与宿主已提供的 @deepseek-ai/* peer 包

前置条件

WakaTime API Key

在 ~/.wakatime.cfg（或设置 WAKATIME_HOME 时的 $WAKATIME_HOME/.wakatime.cfg）中配置：

[settings]
api_key = waka_your_api_key_here

在 WakaTime 设置 页面获取 API Key。

WakaTime CLI（可选）

插件在缺失时会自动下载 wakatime-cli。也可以自行安装：

brew install wakatime-cli

或从 WakaTime releases 下载。

工作原理

插件订阅 dsh 的会话事件流（session/event）：

- tool/call 按 callId 记录工具名与解析后的参数；tool/result 回查并读取 fs 工具持久化的 meta 载荷 —— 解析后的实体路径（read、read_image）与 diff hunk（edit、write），
得到每个 hunk 的精确增删行数；宿主未附加 meta 时回退到参数推导（write 内容、str_replace_editor 字符串）。
- 每个项目每分钟最多发送一次 heartbeat（状态文件位于 ~/.wakatime/dsh-wakatime/）；
触发时机包括聊天活动、工具结果、已提交的模型结算（含 dsh 0.1.3-alpha.1 中无消息的 assistant/attempt 记录）、
实时 agent 活动（agent/status、agent/assistant-stream）、turn 边界、会话销毁与插件卸载。
- --plugin 标签形如 Deepseek Harness[-]/ dsh-wakatime/。

开发

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run build       # 声明文件到 lib/types + tsdown 打包 lib/index.js
pnpm test            # vitest：changes、state、heartbeat、插件接线

目录结构：

- src/index.ts —— 插件入口（name / Config / apply）与事件接线
- src/config.ts —— schemastery Config schema、默认值、--plugin 标签
- src/changes.ts —— 工具事件 → 文件变更、diff 行数统计
- src/state.ts —— 每项目限频
- src/heartbeat.ts —— wakatime-cli 调用、批量发送、冲刷
- src/cli.ts —— wakatime-cli 发现/下载/更新
- src/paths.ts、src/logger.ts —— WakaTime 路径与文件日志
- tests/ —— 单元测试 + 基于真实 cordis Context 的集成测试

已知限制

- 沙箱/远程文件系统中的工具调用按其模型可见的 file_path 参数追踪，除非 tool/result 的 meta 携带解析后的绝对路径（dsh 0.1.3-alpha.1 的 fs 工具会携带）；解析路径与沙箱不一致时可能
以项目相对路径记录。
- bash 命令不归因到具体文件（可能改动任意内容）。
- 当 @deepseek-ai/dsh 无法从插件位置解析时（例如 npm 安装缺少 dev 依赖），--plugin 标签中的
dsh 版本显示为 unknown。
- @deepseek-ai/dsh-session/@deepseek-ai/dsh-agent 的 peer 范围从 0.1.3-alpha.1 起；更老的宿主仍能运行
追踪路径，但没有实时 agent 活动 heartbeat。

许可证

MIT —— 移植逻辑来自 opencode-wakatime（MIT）。