dsh-visualization 0.1.3 → 0.1.5

package/AGENTS.md

@@ -0,0 +1,240 @@
+# AGENTS — changing dsh-visualization
+
+For DSH agents and developers. English first, **[中文](#中文)** at the bottom.
+For using the plugin see [GUIDE.md](GUIDE.md).
+
+---
+
+# English
+
+## 1. Three commands
+
+```powershell
+node build.cjs                  # standalone/instrument.html → web/index.html
+node make-wallpaper.cjs         # web/index.html → wallpaper/index.html (adds <base>, drops -webkit-line-clamp)
+node make-wallpaper-full.cjs    # full page with minimal CSS (WE experiment, see §9)
+```
+
+Changing anything under `fold.cjs` / `index.js` (the host half) **requires a DSH restart** — the
+plugin toggle only remounts routes, it does not re-evaluate loaded ESM.
+
+## 2. File map
+
+| Path | Role |
+|---|---|
+| `standalone/instrument.html` | **the single source of the page.** Edit this, then build. |
+| `web/index.html` | **generated** — never edit by hand |
+| `standalone/bridge.cjs` | standalone dev server (port 8787), not shipped |
+| `fold.cjs` | host: session discovery, zstd frames, incremental fold, HTTP/SSE, fixed-port helper |
+| `index.js` | host entry: registers the route, injects origin/policy, starts the helper |
+| `client.js` | client half: sidebar icon + main-panel iframe |
+| `build.cjs` | regenerates `web/index.html` from the source page |
+| `wallpaper/` | wallpaper pages + Lively package |
+| `wallpaper-live.cjs` | persistent-capture pipeline (Edge + CDP, JPEG, ~4.9 fps) |
+| `wallpaper-capture.cjs` | crop pipeline: full shot → three strips (top/right/bottom) |
+| `we-deploy.ps1` | deploy a page into Wallpaper Engine's project (handles the file lock) |
+| `we-cdp.cjs` | turns on WE's CEF devtools port |
+| `we-css-keep.cjs` | CSS bisect helper (`we-css-split.cjs` is the older variant) |
+| `screenshots.json` | storefront screenshots declared in-repo |
+
+## 3. Rules that bite
+
+1. **One source.** Change `standalone/instrument.html`, run `node build.cjs`. Hand-editing
+   `web/index.html` gets overwritten.
+2. **Host changes need a restart.** `fold.cjs` / `index.js` are ESM; a plugin toggle is not enough.
+3. **Never overwrite the page with a one-liner.** It has been destroyed that way once — use edits or a
+   small `.cjs` patch script. Recovery is documented at the end of this file.
+4. **Wait for the wallpaper file lock.** WE keeps `projects/.../index.html` open; copy silently fails
+   while it runs. Kill WE, delete the file, then copy (`we-deploy.ps1` does exactly this).
+
+## 4. Data flow
+
+```
+~/.dsh/sessions/<ws>/<session>/session.v<N>.jsonl.zstd
+  └─ zstdFrames()   parse RFC 8878 headers+blocks → exact frame boundaries
+  └─ unzstdAll()    decode only frames appended since the last read
+  └─ makeFolder()   reducer: push(newEvents) → result(); never re-scans history
+  └─ /dsh-visualization/state   (one-shot, gzip, `?session=` to pin)
+      /dsh-visualization/events (SSE, pushes only on change, 250 ms check)
+  └─ page: applyState() → render() (DOM) + draw() (canvas)
+```
+
+Measured at ~8.7 k events: first fold 240–260 ms, then 7–12 ms per change. Idle SSE = zero bytes.
+
+## 5. Adding things
+
+**A ring** — three places in `standalone/instrument.html`: `RINGVIS` / `RING_NAME` / `RING_COL`, the
+`if (RINGVIS[n])` block in `draw()`, and `hitReg({...})` so hover/click works. Add a branch in
+`showDetail()` if the card needs fields.
+
+**A language** — `EN` (whole-string matches), `EN_RULES` (templated phrases), `EN_FN` (logic). `LANG`
+is `'zh' | 'en'`; to add a third, turn it into a list and key the dictionaries by code.
+
+**A colour** — `toolColor(name)`.
+
+## 6. Debugging
+
+| Flag / tool | What it gives |
+|---|---|
+| `?debug=1` (or `#debug`, `localStorage.dshviz.debug=1`) | `window.__M` / `__HIT` / `__CHAIN` |
+| `http://127.0.0.1:8799/state` | the fixed-port helper the wallpapers use |
+| `node standalone/shot.cjs <url> out.png W H` | screenshot any page (CDP over pipes) |
+| `SHOT_EVAL=...` | evaluate JS in the page and print the result |
+| `node we-cdp.cjs` | opens WE's CEF devtools port (8080) |
+| `node we-cdp-probe.cjs` | reads runtime state / console from the WE wallpaper page |
+
+## 7. Release flow
+
+```powershell
+# 1. bump
+node -e "const p=require('./package.json');p.version='0.1.5';require('fs').writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
+# 2. build the page first (web/index.html is what ships)
+node build.cjs
+# 3. publish (2FA-bypass token is configured on this machine)
+npm publish --access public
+# 4. push
+git add -A; git commit -m "..."; git push
+# 5. the marketplace entry needs no change unless fields changed:
+#    data/plugins/peilopielo__dsh-Visualization.yml in awesome-dsh-plugin
+```
+
+## 8. Known traps
+
+1. **WE's renderer crashes on the full page.** Reproduced on Chrome 146; independent of protocol
+   (`file://` and `http://` both crash) and of the CSS file (a minimal stylesheet still crashes). The
+   crash correlates with compositing the `.rings` subtree. Do not spend more time on it — use Lively.
+2. **`-webkit-line-clamp` is an independent crash trigger** in WE. `make-wallpaper.cjs` strips it.
+3. **Multi-frame zstd.** The log is append-only multi-frame; older Node decodes only frame 1. Split on
+   the magic `28 B5 2F FD`… **only as a fallback**: the correct path is `zstdFrames()`, which parses
+   headers and blocks. Magic-scanning is wrong (the real log contains 4838 magic occurrences).
+4. **File lock, WE running** — see rule 4.
+5. **`pointer-events` on overlay layers.** A full-screen overlay without `pointer-events:none` kills
+   all canvas hover/click. `elementFromPoint` returning the overlay instead of `#net` is the symptom.
+6. **Init order.** `M.sSteps/sJobs/sTools/sLog/sStats` must be `[]` before the first `draw()`, or the
+   canvas freezes. `DEBUG` must be module-scope, not inside `render()`.
+7. **`CN.turns = 0` means "all"** — guard with `turnLimit = CN.turns || 999`, else no lines are drawn.
+8. **`tool/result` id lives at `message.source.callId`**, not `data.toolCallId`.
+9. **Zoom-dependent layout** — the rings measure `.rings.getBoundingClientRect()`; if that element is
+   hidden or zero-sized, `G.base` is 0 and `draw()` returns early (blank panel with no error).
+
+## 9. Wallpaper routes (and why)
+
+| Route | Frame rate | Notes |
+|---|---|---|
+| Lively + `wallpaper/lively/index.html` | full | WebView2 (Edge) — renders fine, mouse input forwarded |
+| WE + `wallpaper/live.html` + `wallpaper-live.cjs` | ~4.9 fps | JPEG 200 KB/frame, persistent Edge via CDP |
+| WE + three strips (`wallpaper/hybrid.html`) | native rings, 8 s text | hybrid: canvas rings + screenshot panels |
+| WE + full page (`make-wallpaper-full.cjs`) | — | dead end: crashes (trap 1) |
+
+## 10. Recovering the page
+
+If `standalone/instrument.html` is ever clobbered:
+
+1. Check `instrument.bak.html` and the working tree (`git status`, `git diff`)
+2. If the browser still has the page open, run in its console:
+   `fetch('/savehtml',{method:'POST',body:document.documentElement.outerHTML})`
+   → the host writes `instrument.recovered.html`
+3. Re-apply the last edits, then `node build.cjs`
+
+---
+
+# 中文
+
+## 1. 三个命令
+
+```powershell
+node build.cjs                  # standalone/instrument.html → web/index.html
+node make-wallpaper.cjs         # 生成壁纸页（加 <base>、去掉 -webkit-line-clamp）
+node make-wallpaper-full.cjs    # 原版页面 + 极简 CSS（WE 实验用，见 §9）
+```
+
+改 `fold.cjs` / `index.js`（宿主侧）**必须重启 DSH**——插件开关只重挂路由，不会重新求值已加载的 ESM。
+
+## 2. 文件地图
+
+| 路径 | 作用 |
+|---|---|
+| `standalone/instrument.html` | **页面唯一源文件**，改它再 build |
+| `web/index.html` | **生成物**，不要手改 |
+| `fold.cjs` | 宿主：会话发现、zstd 帧解析、增量折叠、HTTP/SSE、固定端口服务 |
+| `index.js` | 宿主入口：注册路由、注入 origin/策略、启动固定端口 |
+| `client.js` | 客户端：侧栏图标 + 主面板 iframe |
+| `build.cjs` | 从源页面重新生成 `web/index.html` |
+| `wallpaper/` | 壁纸页 + Lively 包 |
+| `wallpaper-live.cjs` | 常驻截图流水线（Edge + CDP，JPEG，约 4.9 fps） |
+| `wallpaper-capture.cjs` | 裁切流水线：整页截图 → 三块（顶/右/底） |
+| `we-deploy.ps1` | 部署页面到 WE 工程（处理文件锁） |
+| `we-cdp.cjs` | 打开 WE 的 CEF 调试端口 |
+
+## 3. 会咬人的规矩
+
+1. **单一源**：只改 `standalone/instrument.html`，然后 `node build.cjs`。手改 `web/index.html` 会被覆盖。
+2. **改宿主必须重启 DSH**。
+3. **绝不用单行命令整篇覆盖页面**——它被这样毁过一次。
+4. **等文件锁**：WE 运行时锁着 `projects/.../index.html`，直接复制会静默失败。先关 WE → 删文件 → 再复制。
+
+## 4. 数据流
+
+```
+日志 → zstdFrames()（按 RFC 8878 精确切帧）→ 只解新帧 → makeFolder().push(新事件)
+     → /state（一次性、gzip）或 /events（SSE，变化才推）→ applyState() → render() + draw()
+```
+
+实测（约 8.7k 事件）：首次折叠 240~260 ms，之后每次变化 7~12 ms；空闲 SSE 零字节。
+
+## 5. 加东西的落点
+
+**新环** —— `RINGVIS`/`RING_NAME`/`RING_COL`、`draw()` 里的绘制块、`hitReg(...)` 登记、`showDetail()` 分支。
+
+**新语言** —— `EN` 词典 + `EN_RULES` 正则 + `EN_FN` 逻辑；`LANG` 现在写死两门，要加就把字典按语言代码分键。
+
+**新配色** —— `toolColor(name)`。
+
+## 6. 调试手段
+
+| 手段 | 作用 |
+|---|---|
+| `?debug=1` | 挂出 `window.__M` / `__HIT` / `__CHAIN` |
+| `http://127.0.0.1:8799/state` | 壁纸用的固定端口 |
+| `node standalone/shot.cjs <url> out.png W H` | 截图任意页面（CDP over pipes） |
+| `SHOT_EVAL=...` | 在页面里求值并打印 |
+| `node we-cdp.cjs` / `we-cdp-probe.cjs` | 打开/读取 WE 的 CEF 调试端口 |
+
+## 7. 发布流程
+
+```powershell
+node build.cjs                      # 先构建，web/index.html 才是要发的
+# 改 package.json 的 version
+npm publish --access public
+git add -A; git commit -m "..."; git push
+# 市场条目一般不用动（字段没变的话）
+```
+
+## 8. 坑表
+
+1. **WE 渲染器跑不动完整页**：Chrome 146 复现，与协议无关（file:// 和 http:// 都崩）、与 CSS 文件无关（换极简 CSS 也崩）；崩溃与合成 `.rings` 子树相关。别再花时间，用 Lively。
+2. **`-webkit-line-clamp` 是独立崩溃点**，`make-wallpaper.cjs` 会去掉它。
+3. **多帧 zstd**：日志是追加写的多帧；别扫魔数（真实日志里有 4838 处魔数），用 `zstdFrames()` 解析帧头块头。
+4. **文件锁**：见规矩 4。
+5. **覆盖层的 `pointer-events`**：全屏遮罩若没有 `pointer-events:none`，canvas 的悬停/点击全部失效。
+6. **初始化顺序**：`M.sSteps/sJobs/sTools/sLog/sStats` 必须在首帧前是 `[]`，否则画布卡死；`DEBUG` 要在模块作用域。
+7. **`CN.turns = 0` 表示「全部」**：用 `turnLimit = CN.turns || 999` 兜底，否则一条线都不画。
+8. **`tool/result` 的 id 在 `message.source.callId`**，不在 `data.toolCallId`。
+9. **`.rings` 尺寸为 0 会让 `draw()` 直接 return**：面板空白但无报错，先查这个元素的包围盒。
+
+## 9. 壁纸方案与取舍
+
+| 方案 | 帧率 | 说明 |
+|---|---|---|
+| Lively + `wallpaper/lively/index.html` | 满帧 | WebView2（Edge），渲染正常，鼠标可交互 |
+| WE + `wallpaper/live.html` + `wallpaper-live.cjs` | 约 4.9 fps | JPEG 200 KB/帧，常驻 Edge |
+| WE + 三块截图（`wallpaper/hybrid.html`） | 环原生 + 文字 8 秒 | 混合方案 |
+| WE + 完整页 | — | 死路：崩（坑 1） |
+
+## 10. 页面被覆盖后怎么救
+
+1. 先看 `instrument.bak.html` 和 `git status` / `git diff`
+2. 浏览器里还开着页面时，在控制台执行：
+   `fetch('/savehtml',{method:'POST',body:document.documentElement.outerHTML})`
+   → 宿主写出 `instrument.recovered.html`
+3. 重新补最后的改动，然后 `node build.cjs`

package/FAQ.md

@@ -1,85 +1,72 @@
-# FAQ / 常见问题
+# FAQ
+
+Short answers to the questions that are not "how do I use it" — for usage see [GUIDE.md](GUIDE.md),
+for changing the code see [AGENTS.md](AGENTS.md).
 
 ## Why is the license not OSI-approved? / 为什么不用 OSI 许可？
 
-**EN** — By design, not by accident. The visual language — the rings, the palette, the layered
-layout — derives from [HALOFLUX](https://github.com/Ryder191/haloflux), which is licensed under
-PolyForm Noncommercial 1.0.0. Those terms require any derivative to stay noncommercial and to keep
-the attribution. An MIT/Apache/BSD badge here would be a promise this project cannot keep, so the
-plugin adopts the same license: free for personal use, study, research, teaching and hobby
-projects; commercial use is not granted.
+**EN** — Because HALOFLUX is not. The visual language — rings, palette, layered layout — derives from
+[HALOFLUX](https://github.com/Ryder191/haloflux), which is licensed under PolyForm Noncommercial 1.0.0.
+Those terms require derivatives to stay noncommercial and to keep the attribution, so an MIT/Apache
+badge here would be a promise this project cannot keep.
 
-The *code* (host folding, zstd frame parsing, SSE, the page) is original, written for this plugin.
-Nothing was copied from HALOFLUX's source; what it borrows is the design language, and that is
-credited in both the LICENSE and the page footer.
+The **code** is original (host folding, zstd frame parsing, SSE, the page). What it borrows is the
+design language, credited in the LICENSE and in the page footer.
 
-**中文** — 这是刻意的，不是疏漏。视觉语言（环、配色、分层布局）来自
-[HALOFLUX](https://github.com/Ryder191/haloflux)，它使用 PolyForm Noncommercial 1.0.0。
-该许可要求衍生作品同为非商业并保留署名。这里挂 MIT/Apache 就等于是本项目兑现不了的承诺，
-所以插件沿用同一许可：个人使用、学习、研究、教学、兴趣项目免费；不授予商业用途。
+**中文** — 因为 HALOFLUX 不是。视觉语言（环、配色、分层布局）来自
+[HALOFLUX](https://github.com/Ryder191/haloflux)，它是 PolyForm Noncommercial 1.0.0。
+该许可要求衍生作品同为非商业并保留署名，所以这里挂 MIT/Apache 就是兑现不了的承诺。
 
-代码本身（宿主折叠、zstd 帧解析、SSE、页面）是为本插件新写的，没有复制 HALOFLUX 的源码；
-借用的是设计语言，LICENSE 与页面右下角都写明了出处。
+**代码**是为本插件新写的（宿主折叠、zstd 帧解析、SSE、页面）；借用的是设计语言，
+已在 LICENSE 和页面右下角注明。
 
-> Marketplace listings do not require an OSI-approved license — other listed plugins in this catalog
-> also ship non-OSI terms.
-> 插件市场并不要求 OSI 许可——本目录里已有其他非 OSI 许可的插件。
+> The plugin market does not require an OSI license — other listed plugins ship non-OSI terms too.
+> 插件市场并不要求 OSI 许可，目录里已有其他非 OSI 许可的插件。
 
 ## Does it send my data anywhere? / 会把数据发出去吗？
 
-**EN** — No. The host half reads `~/.dsh/sessions/**` read-only, folds it in memory, and serves it on
-`/dsh-visualization/*` to the local page. No outbound network request is made by either half, and no
-file is written except the OS-level cache the browser keeps for the page itself.
+**EN** — No. The host reads `~/.dsh/sessions/**` read-only, folds it in memory, and serves it on
+`/dsh-visualization/*` to the local page. Neither half makes an outbound request, and no session file
+is written.
 
-**中文** — 不会。宿主侧只读 `~/.dsh/sessions/**`，在内存里折叠，通过 `/dsh-visualization/*`
-提供给本地页面。前后两端都不发起任何对外网络请求，也不写任何文件（浏览器自身的页面缓存除外）。
+**中文** — 不会。宿主只读 `~/.dsh/sessions/**`，在内存里折叠，通过 `/dsh-visualization/*`
+提供给本地页面。前后两端都不对外发请求，也不写任何会话文件。
 
-## Why can it only be reached from localhost? / 为什么只能本机访问？
+## Why loopback only? / 为什么只能本机访问？
 
 **EN** — Session logs contain every command you ran and every prompt you typed. The routes answer
-loopback addresses only, so exposing the Web UI on a LAN does not expose the instrument. If you
-really need remote access, set `allowRemote: true` in the plugin config and understand that anyone
-who can reach the port can read those logs.
+loopback addresses only, so exposing the Web UI on a LAN does not expose the instrument. If you really
+need remote access, set `allowRemote: true` — and understand that anyone who can reach the port can
+read those logs.
+
+**中文** — 会话日志里有你执行过的每条命令和说过的每句话。路由只响应回环地址，所以把 Web 界面
+暴露到局域网不会顺带暴露仪表盘。确实要远程访问时写 `allowRemote: true`——但要清楚：能访问该端口的人
+都能读到这些日志。
 
-**中文** — 会话日志里有你执行过的每条命令和输入的每句话。路由只响应回环地址，所以把 Web 界面暴露到
-局域网并不会顺带暴露仪表盘。确实需要远程访问时，在插件配置里写 `allowRemote: true`——
-但要清楚：任何能访问该端口的人都能读到这些日志。
+## Can I use it at work? / 能在公司用吗？
 
-## The panel is blank / says "no session log" / 面板空白、提示没有会话
+**EN** — No. PolyForm Noncommercial excludes use by a for-profit company, including internal use and
+use on behalf of a company. Personal study, and noncommercial organisations (charities, educational and
+public research institutions), are permitted by the license text.
 
-| 提示 | 原因 |
-|---|---|
-| `这个运行环境不支持 zstd 解压（需要 Node ≥ 22.15）` | 宿主 Node 太老 |
-| `会话目录是空的 —— 先在这个 profile 里跑一轮对话` | 这个 profile 还没聊过 |
-| `还没找到 DSH 会话目录（…），确认 DSH_HOME 是否正确` | DSH 数据不在默认位置；设 `DSH_HOME` 或 `DSHVIZ_SESSIONS_ROOT` |
-| 面板空白 + 网络面板 403 | 不是本机访问；见上一节 |
+**中文** — 不行。PolyForm Noncommercial 排除了在营利性公司内部或代表公司的使用。个人学习，以及慈善、
+教育、公共研究机构等非商业组织，按许可条文是允许的。
 
 ## Does it slow the session down? / 会拖慢会话吗？
 
-**EN** — The fold is incremental: only newly appended zstd frames are decoded, and only new events
-are pushed into the accumulator. At ~8.7k events the first fold costs 240–260 ms; afterwards each
-change costs 7–12 ms. When nothing changes, the SSE connection sends zero bytes (except a 15 s
-heartbeat).
+**EN** — The fold is incremental: only newly appended zstd frames are decoded, and only new events are
+pushed into the accumulator. At ~8.7 k events the first fold is 240–260 ms; afterwards each change is
+7–12 ms. When nothing changes the SSE connection sends zero bytes (apart from a 15 s heartbeat).
 
 **中文** — 折叠是增量的：只解新追加的 zstd 帧，只把新事件 push 进累加器。约 8.7k 事件时首次
-240~260ms，之后每次变化 7~12ms。没有变化时 SSE 一个字节都不发（只有 15 秒一次的心跳）。
-
-## How do I uninstall it? / 怎么卸载？
-
-```powershell
-# DSH 插件页里关掉，或：
-dsh plugin remove dsh-visualization
-# npm 装的：
-npm uninstall -g dsh-visualization
-```
-
-仪表盘不写任何持久状态；删除后 `~/.dsh/sessions` 里的日志原样不动。
-
-## Can I use it at work? / 能在公司用吗？
+240~260 ms，之后每次变化 7~12 ms。没有变化时 SSE 一个字节都不发（15 秒一次心跳除外）。
 
-**EN** — No. PolyForm Noncommercial excludes use by a for-profit company, including internal use
-and use on behalf of a company. Personal study and noncommercial organisations (charities,
-educational and public research institutions) are permitted by the license text.
+## Known limits
 
-**中文** — 不行。PolyForm Noncommercial 排除了在营利性公司内部或代表公司的使用。个人学习、
-以及慈善、教育、公共研究机构等非商业组织，按许可条文是允许的。
+- **Memory grows with the session**: the reducer keeps derived state for every event. Steps, tools and
+  the log are capped; counters are cumulative. At ~100 k events `result()` still sorts 1.2 k steps and
+  1.5 k tools — roughly 10–20 ms per frame.
+- **Two UI languages** (zh/en).
+- **Read-only**: the instrument never writes session files.
+- **Wallpaper Engine cannot render the page** — its CEF crashes on it; use Lively instead
+  (see [GUIDE.md §8](GUIDE.md#8-as-a-desktop-wallpaper)).

package/GUIDE.md

@@ -0,0 +1,270 @@
+# GUIDE — using dsh-visualization
+
+The user guide. English first, **[中文](#中文)** at the bottom.
+For changing the code see [AGENTS.md](AGENTS.md); for "why is it like this" see [FAQ.md](FAQ.md).
+
+---
+
+# English
+
+## 1. What this is
+
+A DeepSeek Harness plugin that turns the **current session** into an instrument panel: a sidebar icon,
+and a full panel showing seven concentric layers — session, steps, skills, tools, jobs, approvals,
+file changes — plus a turn timeline and an event log.
+
+Everything comes from `~/.dsh/sessions/**` (read-only). Nothing is sent anywhere.
+
+![Overview](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/shot-overview.png)
+
+![The panel in motion](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/demo.gif)
+
+## 2. Install
+
+```powershell
+# marketplace / Plugins page: search "dsh-visualization"
+npm i dsh-visualization
+```
+
+After installing, a ring icon appears in the left rail. Click it; the panel takes the main area.
+Nothing else to configure — it follows whichever session you have open.
+
+**Requirement**: Node ≥ 22.15 in the host. Without it the panel says so explicitly instead of
+rendering blank.
+
+## 3. First look
+
+The panel is split in three:
+
+| Area | Content |
+|---|---|
+| Centre | the rings; the number in the middle is the current **turn** |
+| Right column | session flow, context usage, background jobs, turn timeline |
+| Bottom | event log, grouped by turn, newest on top |
+
+![The rings](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/part-rings.png)
+
+Direction matters: on the rings, **12 o'clock is the newest data**, older data runs clockwise.
+
+## 4. Reading the rings
+
+| Ring | What it shows |
+|---|---|
+| ① Session | context-window usage + the last 12 turn ticks |
+| ② Steps | time buckets; thicker segment = more time spent in that slice |
+| ③ Skills | 16 slots; one lights up per loaded skill, and a link runs to when it was last used |
+| ④ Tools | composition by call count (or by time — see `share`) |
+| ⑤ Jobs | one arc per background job, length ∝ runtime |
+| ⑥ Approvals | one tick per approval, colour = outcome |
+| ⑦ Changes | one tick per file change; deliverables are taller |
+
+Each ring can be switched off independently (see the controls below); the remaining rings re-space
+themselves to fill the gap.
+
+![Controls](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/part-controls.png)
+
+## 5. Controls (bottom left)
+
+| Control | What it does |
+|---|---|
+| `①…⑦` | toggle each layer |
+| `spin` | slow rotation of ②③④ |
+| `lines` | `ladders` (per-step chains), `beams` (from the core), or `both` |
+| `share` | size the tool ring by call `count` or by `time` |
+| `line turns` | how many turns get connectors |
+| `show turns` | how many turns the whole panel covers (or `all`) |
+| `⧉ window` | open a separate window you can drag to another monitor |
+| `中 / EN` | switch language |
+
+`line turns` is always clamped to `show turns` — a connector can never point at a turn the panel is
+not showing.
+
+Bright vs dim segments on ②: a **dim** segment has no connector because it is outside `line turns`;
+a **bright** segment with no line is a text-only step that called no tools.
+
+## 6. Hover and click
+
+Every node on every ring answers:
+
+- **hover** — a tooltip with the name and a one-line summary
+- **click** — a detail card; for tools it lists the last six actual commands with timings
+
+![Detail card](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/shot-detail.png)
+
+## 7. Language
+
+The UI ships in Chinese and English. It starts from `navigator.language`, remembers your choice, and
+can be forced per page with `?lang=en` / `?lang=zh`.
+
+## 8. As a desktop wallpaper
+
+Two routes. **Lively is recommended** — it renders the page natively at full frame rate.
+
+### Lively Wallpaper (full frame rate, interactive)
+
+1. Install [Lively Wallpaper](https://github.com/rocksdanister/lively) (free, open source)
+2. Download [`wallpaper/lively-package.zip`](wallpaper/lively-package.zip)
+3. Drag the zip into Lively — or **Add Wallpaper → open file** → the extracted `index.html`
+
+The page finds the plugin on `127.0.0.1:8799` by itself. If DSH is not running it shows a hint and
+retries every 5 seconds.
+
+**The panel stays clickable on the desktop** — Lively forwards mouse input, so ring toggles, turn
+pickers and detail cards work directly on the background. If that makes desktop icons hard to click,
+turn off icon display in Lively's settings.
+
+### Wallpaper Engine (screenshot mode, ~5 fps)
+
+Wallpaper Engine's own renderer crashes on this page (reproduced on its Chrome 146, independent of
+protocol). The workaround is a screenshot pipeline:
+
+```powershell
+node wallpaper-live.cjs 200 78     # ≈4.9 fps, 200 KB/frame
+```
+
+Then set `wallpaper/live.html` as a Wallpaper Engine web wallpaper. A low-CPU variant (`node
+wallpaper-capture.cjs 8`) refreshes every 8 seconds instead.
+
+![Event log](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/part-log.png)
+
+## 9. Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| Panel says "this runtime does not support zstd" | host Node < 22.15 |
+| Panel says the session directory is empty | no conversation has run in this profile yet |
+| Blank panel + 403 in the network tab | you are not on loopback; `allowRemote: true` if you really need remote access |
+| A dim ring segment has no line | it is outside `line turns` |
+| A bright segment has no line | that step called no tools |
+| Wallpaper says "not connected" | DSH is not running, or the plugin is disabled |
+
+## 10. Privacy and uninstall
+
+- The host reads `~/.dsh/sessions/**` and folds it **in memory**. It writes no session files.
+- No outbound network requests from either half; routes answer loopback only.
+- Uninstall: disable the plugin on the Plugins page, or `dsh plugin remove dsh-visualization`.
+  Your session logs are untouched.
+
+---
+
+# 中文
+
+## 1. 这是什么
+
+一个 DeepSeek Harness 插件，把**当前会话**画成一台仪表盘：侧栏一个环图标，点开是七层同心环
+（会话、步骤、技能、工具、任务、审批、文件变更）+ 轮次时间线 + 事件表。
+
+数据全部来自 `~/.dsh/sessions/**`（只读），不发往任何地方。
+
+## 2. 安装
+
+```powershell
+# 插件市场 / 插件页搜索 "dsh-visualization"
+npm i dsh-visualization
+```
+
+装好后左侧栏出现环图标，点开占满主面板。不用配置——它跟随你当前打开的那个会话。
+
+**要求**：宿主 Node ≥ 22.15。不满足时面板会直接说明，不会给你一个空白页。
+
+## 3. 第一眼看到的
+
+面板分三块：
+
+| 区域 | 内容 |
+|---|---|
+| 中间 | 环；正中的数字是当前**轮次** |
+| 右栏 | 会话逻辑链、上下文占用、后台任务、轮次时间线 |
+| 底部 | 事件表，按轮分组，最新的在最上面 |
+
+![环](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/part-rings.png)
+
+方向很重要：环上**12 点方向是最新的数据**，越旧越顺时针。
+
+## 4. 怎么读环
+
+| 环 | 表示什么 |
+|---|---|
+| ① 会话 | 上下文占用 + 最近 12 轮刻度 |
+| ② 步骤 | 时间分格；格子越粗 = 那段时间花得越久 |
+| ③ 技能 | 16 格；加载一个技能亮一格，并连一条线到"最近一次使用"的时刻 |
+| ④ 工具 | 按调用次数（或耗时）分扇区 |
+| ⑤ 任务 | 每个后台任务一段弧，弧长 ∝ 运行时长 |
+| ⑥ 审批 | 每次审批一根刻度，颜色表示结果 |
+| ⑦ 变更 | 每次文件改动一根刻度，交付物更高 |
+
+每层都能单独关掉（见下面的控件），剩下的环会自动重新分布填满空间。
+
+![控件](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/part-controls.png)
+
+## 5. 控件（左下角）
+
+| 控件 | 作用 |
+|---|---|
+| `①…⑦` | 开关每一层 |
+| `环旋转` | ②③④ 缓慢自转 |
+| `连线` | `阶梯`（逐步链）/ `光束`（从核心射出）/ `两者都有` |
+| `占比` | 工具环按调用**次数**还是按**耗时** |
+| `连线轮数` | 多少轮画连线 |
+| `显示轮数` | 整个面板覆盖多少轮（可选「全部」） |
+| `⧉ 新窗口` | 开一个独立窗口，可以拖到副屏 |
+| `中 / EN` | 切换语言 |
+
+`连线轮数` 永远被 `显示轮数` 钳制——不可能连到面板没显示的轮次上。
+
+② 环上亮与暗的区别：**暗**的格子表示它不在 `连线轮数` 范围内；**亮**但没线，说明那一步没有调用任何工具（纯文字步）。
+
+## 6. 悬停与点击
+
+环上每个节点都有反应：
+
+- **悬停** —— 提示卡，显示名称和一句摘要
+- **点击** —— 详情卡；工具还会列出**最近 6 次真实执行的命令**和耗时
+
+## 7. 语言
+
+界面中英双语。默认跟随 `navigator.language`，选择会记住，也可以用 `?lang=en` / `?lang=zh` 强制指定。
+
+## 8. 当桌面壁纸用
+
+两条路，**推荐 Lively**——它用原生内核满帧渲染。
+
+### Lively（满帧、可交互）
+
+1. 装 [Lively Wallpaper](https://github.com/rocksdanister/lively)（免费开源）
+2. 下载 [`wallpaper/lively-package.zip`](wallpaper/lively-package.zip)
+3. 把 zip 拖进 Lively，或者 **添加壁纸 → 打开文件** → 选解压后的 `index.html`
+
+页面会自己找到插件的 `127.0.0.1:8799`；DSH 没开时显示提示并每 5 秒重试。
+
+**桌面上可以直接操作面板**——Lively 会转发鼠标事件，环开关、轮次选择、详情卡都能在桌面上点。
+如果这样导致桌面图标不好点，在 Lively 设置里关掉图标显示。
+
+### Wallpaper Engine（截图模式，约 5 fps）
+
+WE 自己的渲染器跑不动这个页面（在它的 Chrome 146 上复现，与协议无关）。替代方案是截图流水线：
+
+```powershell
+node wallpaper-live.cjs 200 78     # ≈4.9 fps，每帧 200 KB
+```
+
+然后把 `wallpaper/live.html` 设为 WE 的网页壁纸。低 CPU 版用 `node wallpaper-capture.cjs 8`（8 秒一帧）。
+
+![事件表](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/part-log.png)
+
+## 9. 排错
+
+| 现象 | 原因 |
+|---|---|
+| 面板说"不支持 zstd" | 宿主 Node < 22.15 |
+| 面板说会话目录是空的 | 这个 profile 还没聊过 |
+| 空白 + 网络面板 403 | 不是本机访问；确实要远程才开 `allowRemote: true` |
+| 暗格子没有线 | 不在「连线轮数」范围内 |
+| 亮格子没有线 | 那一步没有工具调用 |
+| 壁纸显示"未连接" | DSH 没开，或插件被禁用 |
+
+## 10. 隐私与卸载
+
+- 宿主只读 `~/.dsh/sessions/**`，在**内存里**折叠，不写任何会话文件
+- 前后两端都不发起对外网络请求；路由只响应本机回环
+- 卸载：插件页禁用，或 `dsh plugin remove dsh-visualization`；你的会话日志原样不动