dsh-wakatime 0.0.0-stage → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en.md +331 -0
- package/README.md +333 -2
- package/cordis.patch.yml +24 -0
- package/icon.svg +9 -0
- package/lib/build-stamp.d.ts +4 -0
- package/lib/build-stamp.js +23 -0
- package/lib/cache.d.ts +67 -0
- package/lib/cache.js +206 -0
- package/lib/category.d.ts +50 -0
- package/lib/category.js +231 -0
- package/lib/client.js +720 -0
- package/lib/config-value.d.ts +89 -0
- package/lib/config-value.js +255 -0
- package/lib/diff.d.ts +14 -0
- package/lib/diff.js +33 -0
- package/lib/index.d.ts +75 -0
- package/lib/index.js +578 -0
- package/lib/language.d.ts +5 -0
- package/lib/language.js +13 -0
- package/lib/project.d.ts +56 -0
- package/lib/project.js +305 -0
- package/lib/tracker.d.ts +159 -0
- package/lib/tracker.js +313 -0
- package/lib/types.d.ts +148 -0
- package/lib/types.js +151 -0
- package/lib/user-agent.d.ts +110 -0
- package/lib/user-agent.js +274 -0
- package/lib/wakatime.d.ts +191 -0
- package/lib/wakatime.js +510 -0
- package/package.json +94 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 wujue
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="assets/logo.svg" width="128" alt="dsh-wakatime logo"/>
|
|
4
|
+
|
|
5
|
+
# dsh-wakatime — WakaTime heartbeats for DSH
|
|
6
|
+
|
|
7
|
+
[中文](./README.md) | **English**
|
|
8
|
+
|
|
9
|
+
[](https://github.com/dsh-plugin-collection/dsh-wakatime)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## What this is
|
|
18
|
+
|
|
19
|
+
Activity inside DSH never reaches WakaTime on its own: [WakaTime](https://wakatime.com) is fed by editor plugins, while your work here happens in a terminal and in AI conversations. This plugin bridges that gap — it listens to DSH events and turns them into WakaTime heartbeats.
|
|
20
|
+
|
|
21
|
+
- a `write` / `edit` → one heartbeat with line counts and language
|
|
22
|
+
- a `bash` command → one `app` heartbeat whose category comes from the command itself
|
|
23
|
+
- an AI turn → one `ai coding` heartbeat carrying token usage
|
|
24
|
+
|
|
25
|
+
What it does not do: patch DSH internals, bundle host components, or store anything beyond the local retry cache.
|
|
26
|
+
|
|
27
|
+
## Preview
|
|
28
|
+
|
|
29
|
+
The WakaTime dashboard after installing:
|
|
30
|
+
|
|
31
|
+
<p align="center">
|
|
32
|
+
<img src="docs/media/screenshot-dashboard.png" width="900" alt="WakaTime dashboard with DSH-fed project, category, language and editor stats"/>
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
All four panels are fed by this plugin:
|
|
36
|
+
|
|
37
|
+
| Panel | Source |
|
|
38
|
+
|---|---|
|
|
39
|
+
| **Projects** | Each heartbeat's `project`, inferred from git / `package.json` / directory name |
|
|
40
|
+
| **Categories** | Tool → category mapping (see [Category mapping](#category-mapping)) |
|
|
41
|
+
| **Languages** | Inferred from file extensions |
|
|
42
|
+
| **Editors** | Derived from the heartbeat `User-Agent`, so "working in DSH" shows up as its own editor |
|
|
43
|
+
| **Operating Systems** | Also from the `User-Agent` parenthesised section `(linux-<kernel>-<arch>)` |
|
|
44
|
+
| **Models** | Also from the model token inside `User-Agent` (e.g. `deepseek/4.1-flash-eco`) — WakaTime has **no** `ai_model` heartbeat field; this panel reads the UA only |
|
|
45
|
+
|
|
46
|
+
> **Why the UA follows the official template**: the Editors, Operating Systems and Models panels are all derived from `User-Agent`. This plugin emits `wakatime/<ver> (<OS>-<core>-<platform>) <runtime> <model?> <editor>`; the model comes from the host message's `message.source.model` and is normalised with the official `aiModelUserAgentToken` rules. A real sample: `wakatime/1.2.0 (linux-6.18.58-x86_64) node/24.22.0 deepseek/4.1-flash-eco dsh/0.2.2-rc.5`. When a model id has no recognisable version segment (`dsh-opendesign-go`), that part is omitted rather than polluting the `user_agents` table.
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
dsh plugin --profile web add dsh-wakatime
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Restart `dsh web`** afterwards. Then open **Settings → WakaTime** and paste your [API key](https://wakatime.com/settings/api-key).
|
|
55
|
+
|
|
56
|
+
<details>
|
|
57
|
+
<summary>Other install methods</summary>
|
|
58
|
+
|
|
59
|
+
From GitHub:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
dsh plugin --profile web add github:dsh-plugin-collection/dsh-wakatime
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Local development (from the plugin directory):
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
dsh plugin --profile web add /path/to/dsh-wakatime
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
From source:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
cd dsh-wakatime && pnpm install && pnpm build
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Internal distribution: also mirrored on a private Gitea for internal use — ask the maintainer for the URL and pin a commit:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
dsh plugin --profile web add <internal-repo-url>#<commit-sha>
|
|
81
|
+
```
|
|
82
|
+
</details>
|
|
83
|
+
|
|
84
|
+
## Configuration
|
|
85
|
+
|
|
86
|
+
Everything lives in **Settings → WakaTime** and takes effect on save — no restart.
|
|
87
|
+
|
|
88
|
+
| Setting | Description |
|
|
89
|
+
|---|---|
|
|
90
|
+
| **API Key** | WakaTime API key (masked input). When empty it falls back to `WAKATIME_API_KEY`, then `~/.wakatime.cfg`, then `cordis.patch.yml` |
|
|
91
|
+
| **API URL** | Service endpoint, default `https://wakatime.com`; set your own for a self-hosted [WakaTime](https://wakatime.com) |
|
|
92
|
+
| **Proxy URL** | `http://host:port`. Empty falls back to `HTTPS_PROXY`, then `proxy` in `~/.wakatime.cfg`; `none` forces a direct connection |
|
|
93
|
+
| **No-proxy hosts** | Comma separated, empty inherits `NO_PROXY`. e.g. `wakatime.com` connects that host directly |
|
|
94
|
+
| **Heartbeat interval** | 60000–300000 ms |
|
|
95
|
+
| **Project name / Language** | Empty = auto-detect; a value overrides it |
|
|
96
|
+
| **Terminal app name** | The entity for command heartbeats, default `Terminal`; set it to e.g. `DSH` |
|
|
97
|
+
| **Track switches ×3** | Tool calls / user messages / AI messages |
|
|
98
|
+
| **Cache** | Enable local cache + limit (10–1000 entries) |
|
|
99
|
+
| **Debug mode** | More verbose logging |
|
|
100
|
+
|
|
101
|
+
**API key precedence**: settings page → `WAKATIME_API_KEY` → `cordis.patch.yml` → `~/.wakatime.cfg`. Every layer only accepts a non-empty string; a malformed value is skipped with a warning and resolution continues.
|
|
102
|
+
|
|
103
|
+
## Verify
|
|
104
|
+
|
|
105
|
+
Four steps to confirm it works:
|
|
106
|
+
|
|
107
|
+
1. **Check the log** — after restart you should see `loaded with API key waka_****xxxx`;
|
|
108
|
+
2. **Make DSH do something** — read a file, run a command;
|
|
109
|
+
3. **Wait one heartbeat cycle** (120 s by default) until a flush succeeds;
|
|
110
|
+
4. **Open the [WakaTime dashboard](https://wakatime.com/dashboard)** — today's time, projects and languages should show the activity.
|
|
111
|
+
|
|
112
|
+
If step 3 stays quiet, check the local cache first:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
wc -l ~/.dsh/wakatime/heartbeat-cache.jsonl
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
- `0` lines or no file = healthy (the cache is only written on failure);
|
|
119
|
+
- **growing** = sends are failing — look for `上报失败…` in the log.
|
|
120
|
+
|
|
121
|
+
## Compatibility
|
|
122
|
+
|
|
123
|
+
| Side | Notes |
|
|
124
|
+
|---|---|
|
|
125
|
+
| **DSH** | Supported range is `engines.dsh` in `package.json`; currently covers generations `0.1.2` – `0.2.3` (prereleases included). The host validates it at startup and disables the plugin on a mismatch |
|
|
126
|
+
| **Node** | >= 22.19 (including 24+) |
|
|
127
|
+
| **Platform** | Windows / macOS / Linux |
|
|
128
|
+
| **WakaTime** | [wakatime.com](https://wakatime.com), or any WakaTime-compatible self-hosted server |
|
|
129
|
+
| **Other telemetry plugins** | One heartbeat backend per profile — do not run codetime or similar alongside |
|
|
130
|
+
|
|
131
|
+
## Category mapping
|
|
132
|
+
|
|
133
|
+
| DSH tool | WakaTime category | is_write |
|
|
134
|
+
|---|---|---|
|
|
135
|
+
| `write` / `edit` | `coding` | ✅ |
|
|
136
|
+
| `read` / `grep` / `glob` | `browsing` | — |
|
|
137
|
+
| `bash` / `pwsh` | **Derived from the command** (below) | — |
|
|
138
|
+
| `web_search` | `researching` | — |
|
|
139
|
+
| `mcp__codegraph__codegraph_explore` | `code reviewing` | — |
|
|
140
|
+
| `mcp__langfuse__*` | `debugging` | — |
|
|
141
|
+
| `subagent` / `subagent_fork` / `workflow` / `todo_write` | `coding` | — |
|
|
142
|
+
| `ask_user_question` / user messages | `communicating` | — |
|
|
143
|
+
| AI replies | `ai coding` | — |
|
|
144
|
+
| `skill` | `learning` | — |
|
|
145
|
+
| Anything else | `coding` | — |
|
|
146
|
+
|
|
147
|
+
**Shell categories** are no longer a blanket `building` — an earlier implementation did that, and replaying 5290 shell heartbeats from a real account showed 98.7% of the reported "build time" was not building. Categories now come from the command:
|
|
148
|
+
|
|
149
|
+
| Command | Category |
|
|
150
|
+
|---|---|
|
|
151
|
+
| `ls` / `cat` / `grep` / `sed` / `head` … | `browsing` |
|
|
152
|
+
| `git` / `pnpm build` / `docker build` … | `coding` / `building` |
|
|
153
|
+
| `pnpm test` / `vitest` | `running tests` |
|
|
154
|
+
| Unrecognised | `coding` |
|
|
155
|
+
|
|
156
|
+
Only the **bare subcommand** is examined, never trailing arguments (`test` inside `grep -n foo test/a.py` does not count as a test run), and wrappers like `cd … &&`, `sudo` and `npx` are stripped first.
|
|
157
|
+
|
|
158
|
+
## Known limitations
|
|
159
|
+
|
|
160
|
+
- **File-level granularity** — DSH tool calls carry no cursor position, so line-level detail is coarser than an IDE plugin provides;
|
|
161
|
+
- **AI token accounting differs from IDE plugins**: the host reports uncached and cache-hit input as disjoint components, and the plugin sends them as separate fields, so the numbers are not directly comparable;
|
|
162
|
+
- **No historical backfill** — changing `entity` / `category` shape breaks cross-version comparisons on those dimensions;
|
|
163
|
+
- **Read endpoints are closed** to plugin keys (see [Development](#development)), so the plugin cannot read its own data back for validation.
|
|
164
|
+
|
|
165
|
+
## Development
|
|
166
|
+
|
|
167
|
+
<details>
|
|
168
|
+
<summary>Build, test and layout</summary>
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
pnpm install
|
|
172
|
+
pnpm build # clears lib/ then rebuilds host + client
|
|
173
|
+
pnpm typecheck
|
|
174
|
+
pnpm test # vitest, 169 cases
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
src/
|
|
179
|
+
├── index.ts # entry: event listeners, timers, config migration
|
|
180
|
+
├── config-value.ts # volatile-ref unwrapping and per-field validation
|
|
181
|
+
├── wakatime.ts # HTTP client: proxy, bulk upload, per-item parsing
|
|
182
|
+
├── tracker.ts # event → heartbeat conversion and merging
|
|
183
|
+
├── cache.ts # local JSONL cache with time-based trimming
|
|
184
|
+
├── project.ts # git / package.json project inference
|
|
185
|
+
├── category.ts # shell command → category
|
|
186
|
+
├── language.ts # extension → language
|
|
187
|
+
├── diff.ts # write/edit line counts
|
|
188
|
+
└── types.ts # types and constants
|
|
189
|
+
```
|
|
190
|
+
</details>
|
|
191
|
+
|
|
192
|
+
<details>
|
|
193
|
+
<summary>Bulk contract: outer 2xx + per-item statuses</summary>
|
|
194
|
+
|
|
195
|
+
The `heartbeats.bulk` response is **always 202 at the outer level**; real results live in per-item status codes inside `responses`. An implementation that only checks `response.ok` reads a fully rejected batch as a full success — rejected heartbeats neither enter the cache nor raise an error, which is plain data loss.
|
|
196
|
+
|
|
197
|
+
| Per-item status | Handling |
|
|
198
|
+
|---|---|
|
|
199
|
+
| `2xx` | Stored |
|
|
200
|
+
| `4xx` (except 429) | Permanent failure — dropped with a warning carrying the server's reason |
|
|
201
|
+
| `429` / `5xx` | Back to cache for retry |
|
|
202
|
+
|
|
203
|
+
String fields are pre-trimmed to the server's hard limits: `entity` ≤ 2083, `project` / `branch` ≤ 1024; an empty string is rejected too. A trimmed `entity` ends with `...`.
|
|
204
|
+
</details>
|
|
205
|
+
|
|
206
|
+
<details>
|
|
207
|
+
<summary>Cache policy</summary>
|
|
208
|
+
|
|
209
|
+
- Written **only on failure**, drained on success;
|
|
210
|
+
- Concurrent flushes are serialised, and only heartbeats that **truly did not land** are written back (an earlier version wrote stored ones back too, causing duplicates);
|
|
211
|
+
- Over the limit, the oldest are trimmed **by time** with a warning `缓存超过上限(N 条),最旧的 M 条心跳已被丢弃(from → to)` — that line means data is genuinely being lost.
|
|
212
|
+
</details>
|
|
213
|
+
|
|
214
|
+
<details>
|
|
215
|
+
<summary>AI token accounting</summary>
|
|
216
|
+
|
|
217
|
+
The host's `TokenUsage` input components are **disjoint**: `inputTokens` is the uncached part only, cache hits are reported separately in `cacheReadTokens`, and billed input is the sum of the three.
|
|
218
|
+
|
|
219
|
+
This plugin sends the uncached part as `ai_input_tokens` and cache hits as `ai_cached_input_tokens`, and **never adds them together**; `cacheWriteTokens` has no WakaTime counterpart and is not reported.
|
|
220
|
+
|
|
221
|
+
Measured sample: one session billed 80.1M input of which 78.7M (98%+) was cache hits. Reporting only the uncached part makes WakaTime's Tokens two orders of magnitude smaller than a local dashboard.
|
|
222
|
+
</details>
|
|
223
|
+
|
|
224
|
+
<details>
|
|
225
|
+
<summary>Version gate and peer ranges</summary>
|
|
226
|
+
|
|
227
|
+
The host's `evaluatePluginCompatibility` reads only the plugin's `package.json`:
|
|
228
|
+
|
|
229
|
+
| Condition | Behaviour |
|
|
230
|
+
|---|---|
|
|
231
|
+
| `engines.dsh` present | **Only that range is compared**; `peerDependencies` are ignored |
|
|
232
|
+
| Absent | Every `@deepseek-ai/dsh*` peer must be satisfied by the running version |
|
|
233
|
+
| Comparison | `semver.satisfies(running, range, { includePrerelease: true })` |
|
|
234
|
+
| Failure | Logs `Plugin … is incompatible with dsh …` and disables the row |
|
|
235
|
+
|
|
236
|
+
**Write peers as an explicit range list, not `^` prefixes, and never exact versions.** Under node-semver's default semantics (no `includePrerelease`) a prerelease range only matches when a comparator carries an anchor for the same `[major.minor.patch]` tuple: `^0.2.1-rc.2` expands to `>=0.2.1-rc.2 <0.3.0-0`, whose anchors are `0.2.1` and `0.3.0` only — so `satisfies('0.2.2-rc.1', '^0.2.1-rc.2')` is **false** and the plugin gets disabled once the host moves to 0.2.2-rc.1. Spelling out `>=0.2.2-alpha.2 <0.2.3-0` is what covers it.
|
|
237
|
+
|
|
238
|
+
Host 0.2.1 packages pin their dsh peers exactly to one version; copying that makes a plugin disappear on the next rc — on this machine `webhook-runtime` and `webhook-github` vanished that way.
|
|
239
|
+
|
|
240
|
+
**Adding a peer entry is ongoing**: one entry only covers that generation's rc plus its stable release; the next generation needs another.
|
|
241
|
+
</details>
|
|
242
|
+
|
|
243
|
+
<details>
|
|
244
|
+
<summary>Four version-sensitive wiring points (still true on 0.2.2)</summary>
|
|
245
|
+
|
|
246
|
+
| Wiring point | Rule |
|
|
247
|
+
|---|---|
|
|
248
|
+
| WebUI slot `plugins.bundle.config` key | Is the **package name** — not the settings namespace and not the profile entry id; a mismatch means no settings card |
|
|
249
|
+
| `@deepseek-ai/dsh-client-ui-primitives` | Must stay **external**; bundling it duplicates the whole icon set |
|
|
250
|
+
| Automatic settings projection | Requires `.volatile()` on Config; projection lives in the host's `dsh-app-boot` |
|
|
251
|
+
| `.volatile()` fields arrive as **ref objects** | `apply()` receives `Object.freeze({ get })`, not values. They **must be unwrapped**, otherwise `api_url` produces an invalid URL, `heartbeat_interval_ms` becomes 1 ms, booleans stay truthy, string fields are dropped entirely and `cache_limit` never trims. Handled centrally in `src/config-value.ts` |
|
|
252
|
+
</details>
|
|
253
|
+
|
|
254
|
+
<details>
|
|
255
|
+
<summary>Shell category measurement</summary>
|
|
256
|
+
|
|
257
|
+
Replaying 5290 shell heartbeats from a real account:
|
|
258
|
+
|
|
259
|
+
| Category | Before | After |
|
|
260
|
+
|---|---|---|
|
|
261
|
+
| `building` | 100.0% | 1.3% |
|
|
262
|
+
| `coding` | — | 50.6% |
|
|
263
|
+
| `browsing` | — | 46.4% |
|
|
264
|
+
| `researching` | — | 0.8% |
|
|
265
|
+
| `running tests` | — | 0.5% |
|
|
266
|
+
| `debugging` | — | 0.3% |
|
|
267
|
+
|
|
268
|
+
Categories use only WakaTime's authoritative set (`wakatime-cli`, `pkg/heartbeat/category.go`): there is no `deployment` and no `testing` (the right value is `running tests`), and invented words do not aggregate in the dashboard.
|
|
269
|
+
</details>
|
|
270
|
+
|
|
271
|
+
<details>
|
|
272
|
+
<summary>The command heartbeat entity</summary>
|
|
273
|
+
|
|
274
|
+
`bash` / `pwsh` heartbeats have `type: app`. Per wakatime-cli's definition (*"AppType represents an app entity"*) the entity should be an **app name**, not a command line. Treating the whole command as the entity scattered 5281 shell heartbeats into **5158 distinct entities, 98.2% of them seen exactly once** — no aggregation value, and one keystroke away from the 2083-character limit and per-item 400s.
|
|
275
|
+
|
|
276
|
+
It now comes from the "Terminal app name" setting (default `Terminal`); what the command does is expressed by `category`. The merge key inside the 5-second window is `entity + category`, otherwise an `ls` would overwrite a `pnpm test` from four seconds earlier under the same app name.
|
|
277
|
+
|
|
278
|
+
User message / AI reply heartbeats **deliberately keep** `dsh-session-<id>` as the entity: its cardinality is bounded by the session count and it is the only dimension that drills down by session.
|
|
279
|
+
</details>
|
|
280
|
+
|
|
281
|
+
<details>
|
|
282
|
+
<summary>Proxy precedence</summary>
|
|
283
|
+
|
|
284
|
+
The outbound proxy is taken from **settings page → env vars → `~/.wakatime.cfg` → direct**, first match wins. A layer that is not a valid `http(s)` URL is **ignored with a warning** and resolution continues.
|
|
285
|
+
|
|
286
|
+
With debug on, startup logs a line `网络出口 经代理 http://…(来源:设置页)` that answers which route is actually in use. Credentials in a proxy URL are masked to `***:***` before logging.
|
|
287
|
+
|
|
288
|
+
`NO_PROXY` / "No-proxy hosts" accept `*`, exact hosts and `.suffix` entries (`example.com` also matches its subdomains).
|
|
289
|
+
|
|
290
|
+
Why the plugin must read the cfg: measured on the same machine, curl direct, curl via proxy and node direct were all 20/20 while the plugin intermittently got `fetch failed` — because it was the only link not going through the proxy that was already configured in `~/.wakatime.cfg`.
|
|
291
|
+
</details>
|
|
292
|
+
|
|
293
|
+
<details>
|
|
294
|
+
<summary>Read endpoints return 403</summary>
|
|
295
|
+
|
|
296
|
+
Since 2026-10 WakaTime answers read endpoints (`/users/current`, `/users/current/projects`, `/users/current/heartbeats`) with:
|
|
297
|
+
|
|
298
|
+
```
|
|
299
|
+
403 API Keys are only for plugins, use your personal oauth token
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
while the **write endpoint `heartbeats.bulk` still accepts plugin keys**. This is an upstream policy change, not an auth bug in this plugin.
|
|
303
|
+
|
|
304
|
+
One consequence: the "Project name" dropdown in settings depended on `/users/current/projects`, so it was permanently empty and has been removed — the field is free text now. Also, do not read that 403 as a dead key: judge the key by the write endpoint or by the failure warnings.
|
|
305
|
+
</details>
|
|
306
|
+
|
|
307
|
+
<details>
|
|
308
|
+
<summary>Troubleshooting</summary>
|
|
309
|
+
|
|
310
|
+
**Plugin not loaded**: does `lib/` exist? Run `pnpm build`. Any incompatibility line in the log?
|
|
311
|
+
|
|
312
|
+
**No settings card**: confirm the plugin is in the profile's bundles; fully restart `dsh web`; check the browser console.
|
|
313
|
+
|
|
314
|
+
**Heartbeats not sending**, in this order (an earlier version went silent for a full week):
|
|
315
|
+
|
|
316
|
+
1. **Cache before logs** — `~/.dsh/wakatime/heartbeat-cache.jsonl` is only written on failure. Persistent growth or pinning at the limit means sends are failing and older heartbeats are being pushed out; that activity is unrecoverable.
|
|
317
|
+
2. **Read the warnings; debug is not required** — failures always warn with a reason and are written to **both the logger and console** (this host's `ctx.logger` never reaches the stdout capture file, so logger-only means no log at all — the direct reason two silent outages went unnoticed). Key lines: `上报失败…`, `缓存超过上限…已被丢弃`, `N/M 条心跳被逐条拒绝并已丢弃…`, `cache flush failed…`.
|
|
318
|
+
3. **After a host upgrade, look for the "config field is not a usable value" warning** — a volatile ref used as a value fails silently in several ways (see the wiring points above).
|
|
319
|
+
4. **Confirm the key** — `未配置 WakaTime API Key` = no usable value in any layer; `WakaTime API Key 无效` = the server returned 401; `上报失败…(cause: …)` = transport. Diagnostics carry `cause` (`ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND`…), not just `fetch failed`.
|
|
320
|
+
5. **Suspect you are not running your code? Check the build fingerprint** — `apply called; artifact mtime=… pid=…` answers which build this process loaded. Hot reload can leave an old fiber sending with old code; restart DSH fully when behaviour disagrees with the source.
|
|
321
|
+
6. **Payload length is hard-validated** — if "per-item rejection" warnings persist, some field is outside the trimming coverage; paste the server's reason from the warning into an issue.
|
|
322
|
+
</details>
|
|
323
|
+
|
|
324
|
+
## References
|
|
325
|
+
|
|
326
|
+
- [WakaTime API docs](https://wakatime.com/developers)
|
|
327
|
+
- [wakatime-cli](https://github.com/wakatime/wakatime-cli) — authoritative source for categories and field semantics
|
|
328
|
+
|
|
329
|
+
## License
|
|
330
|
+
|
|
331
|
+
MIT © wujue
|