AI 编码计时 Dynesshely/dsh-plugin-wakatime

= 20">

dsh-plugin-wakatime

DeepSeek Harness（DSH）的 Host 插件。它把你在 DSH 里用 AI 写代码的时间，以 category: "ai coding" 心跳的形式上报给 WakaTime，于是这些时间会出现在你的 AI Coding 统计里，和你追踪的其他内容并列。

它不会伪造按文件计的按键心跳。它只回答一个问题——这段时间是不是在跟 AI 一起做这个项目？——而且在后台完成，不阻塞 Host。从 v0.2 起，DSH 里还多了一个 Usage 页面。

功能

- 识别项目 — entity 是会话的工作目录，project 是它的文件夹名，所以 AI 时间在 WakaTime 里按项目拆分。
- AI 形态的心跳 — 每次心跳都带上 DSH 会话 id、输入/输出 token 增量，以及你敲了多少字符。
- 跟随真实 DSH 活动 — 用户消息、助手回复、工具调用、回合边界都计入；15 秒保活覆盖长回合，空闲超时则在你离开时停表。
- 离线不丢数据 — 429/5xx/网络失败会进入本地队列（原子写入，最多 500 条心跳），带退避重放；遇到 401 就停止发送，而不是反复冲击 API。
- 内置 Usage 页面 — 侧边栏入口，显示今天 / 本周 / 累计时间、7 天图表、热门项目、token 与按键计数，外加 WakaTime 侧的视图。
- 没配置也无害 — 没有 api_key 时只在日志里留一条警告，插件保持惰性；DSH 照常启动。

安装

这个 bundle 需要先装好自己的依赖：install_bundle 只是给本地目录建符号链接，不会安装 bundle 依赖的东西。

git clone git@github.com:Dynesshely/dsh-plugin-wakatime.git
cd dsh-plugin-wakatime
pnpm install # or npm install

然后在 DSH 的 Plugin Manager 里，把仓库根目录作为 bundle 安装：

plugin_manager → install_bundle → D:\Projects\Dynesshely\dsh-plugin-wakatime

安装或升级后重启 DSH——Host 代码跑在服务端进程里，刷新页面不够。卸载用 remove_bundle（包名 dsh-plugin-wakatime）。
前提：在 ~/.wakatime.cfg 的 [settings] 下配置 api_key，这个文件你其他 WakaTime 客户端已经在用。其中的 proxy、hostname、debug 值会复用。

配置

配置放在插件自己的行上（cordis.patch.yml 里的 config，或设置里的表单）。优先级：插件 config > ~/.wakatime.cfg > 内置默认值。

| 键 | 默认值 | 用途 |
| enabled | true | 总开关。 |
| minIntervalSeconds | 120 | 两次心跳之间的最小间隔，所有会话合并计算。 |
| idleTimeoutMinutes | 15 | 超过这个间隔就结束当前计时段。 |
| entityType | 'file' | file 上报项目路径；app 上报 DeepSeek Harness。 |
| includeSubagentSessions | false | 单独统计子代理会话（关闭时，同一段实际时间不会重复计入）。 |
| category | 'ai coding' | WakaTime 活动分类。 |
| apiKey | 空 | 覆盖 ~/.wakatime.cfg 里的 api_key。 |
| debug | false | 在日志文件里输出详细诊断信息。 |

空字符串表示「回退」，不是「设为空」。其余键——apiUrl、proxy、hostname、language、userAgent、projectFromCwd——以及所有键的确切语义见 docs/design.md。

用法

v0.2 新增 Usage 页面：侧边栏入口，和 Plugins、Automation tasks、Context insights 并排。数据来自 Host 路由 GET /wakatime/usage.json（Cache-Control: no-store），所以页面上显示的都是本机的真实数据。

| 区块 | 显示内容 |
| 本地时间 | 今天（大字）、本周、累计 |
| 今日用量 | 输入 / 输出 token、输入字符数、会话数、心跳数 |
| 最近 7 天 | 内联 SVG 柱状图，每天一根柱 |
| 项目 | 按跟踪时长排前 5 |
| WakaTime | api_key 是否已配置、hostname、今天的远程 AI Coding 时长、待发送队列长度、上次发送、上次错误 |

页面文案支持双语，跟随 DSH 的语言设置（en / zh）；页面用 Host 的主题变量绘制，所以浅色和深色都能匹配。远程数字由你的心跳推算（GET /users/current/heartbeats?date=…，只取 AI Coding 分类，缓存 60 s）；如果这一个请求失败，只有该区块报错，本地统计照常工作。刷新按钮会重新拉取 JSON。

工作原理

session/event → accumulate activity + token/char deltas → throttle (≥ minIntervalSeconds)
├── ok → WakaTime: single beat, or .bulk (≤ 25 per batch)
└── fail → local queue → backoff replay

- 触发点：user/message、assistant/message（带 usage）、tool/call、tool/result、turn/start、turn/end；靠 15 s 的 tick 让进行中的轮次保持存活。
- 鉴权：对 WakaTime API v1 使用 Authorization: Basic base64(api_key)。每次心跳还会写入本地按天存储（usage.json，保留 30 天），Usage 页面就靠它。
- 诊断日志：<DSH_HOME>/cache/wakatime-dsh/wakatime.log（未设置 DSH_HOME 时用 ~/.dsh/cache/…）。离线队列和状态也放在同一目录。

隐私

发给 WakaTime 的内容：项目工作目录路径、项目名、DSH 会话 id、输入/输出 token 数、键入字符数、时间戳，配置后还会加上 language 和 hostname。

绝不发送：代码、提示词文本、模型输出、文件内容、终端输出。插件只处理事件元数据，从不碰文本本身。用量数据只留在你的磁盘上。

开发

没有构建步骤，纯 ESM。lib/*.js 不依赖 DSH 也能测试：

pnpm install
node --test

index.js Host entry: Config + apply(ctx, config)
lib/tracker.js session/event → activity state → heartbeat scheduling
lib/usage.js per-day aggregation behind the Usage page
lib/client.js WakaTime HTTP client (auth, batching, retry, proxy fallback)
lib/heartbeat.js heartbeat builder (pure)
lib/cfg.js ~/.wakatime.cfg + plugin config merge
lib/queue.js persistent offline queue (atomic writes)
test/ node:test suites

文档

- docs/design.md — 实现约定：设置项、事件、传输格式、v0.2 页面。
- docs/wakatime-api.md — WakaTime API v1 的字段、分类、鉴权，以及实测的重试行为。
- docs/harness-api.md — DSH 插件 API：schema、事件、Web 服务器路由、插槽。

许可证

MIT © 2026 Dynesshely