dsh-visualization 0.1.1 → 0.1.3

package/FAQ.md

@@ -0,0 +1,85 @@
+# FAQ / 常见问题
+
+## 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.
+
+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.
+
+**中文** — 这是刻意的，不是疏漏。视觉语言（环、配色、分层布局）来自
+[HALOFLUX](https://github.com/Ryder191/haloflux)，它使用 PolyForm Noncommercial 1.0.0。
+该许可要求衍生作品同为非商业并保留署名。这里挂 MIT/Apache 就等于是本项目兑现不了的承诺，
+所以插件沿用同一许可：个人使用、学习、研究、教学、兴趣项目免费；不授予商业用途。
+
+代码本身（宿主折叠、zstd 帧解析、SSE、页面）是为本插件新写的，没有复制 HALOFLUX 的源码；
+借用的是设计语言，LICENSE 与页面右下角都写明了出处。
+
+> Marketplace listings do not require an OSI-approved license — other listed plugins in this catalog
+> also ship non-OSI terms.
+> 插件市场并不要求 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.
+
+**中文** — 不会。宿主侧只读 `~/.dsh/sessions/**`，在内存里折叠，通过 `/dsh-visualization/*`
+提供给本地页面。前后两端都不发起任何对外网络请求，也不写任何文件（浏览器自身的页面缓存除外）。
+
+## Why can it only be reached from localhost? / 为什么只能本机访问？
+
+**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.
+
+**中文** — 会话日志里有你执行过的每条命令和输入的每句话。路由只响应回环地址，所以把 Web 界面暴露到
+局域网并不会顺带暴露仪表盘。确实需要远程访问时，在插件配置里写 `allowRemote: true`——
+但要清楚：任何能访问该端口的人都能读到这些日志。
+
+## The panel is blank / says "no session log" / 面板空白、提示没有会话
+
+| 提示 | 原因 |
+|---|---|
+| `这个运行环境不支持 zstd 解压（需要 Node ≥ 22.15）` | 宿主 Node 太老 |
+| `会话目录是空的 —— 先在这个 profile 里跑一轮对话` | 这个 profile 还没聊过 |
+| `还没找到 DSH 会话目录（…），确认 DSH_HOME 是否正确` | DSH 数据不在默认位置；设 `DSH_HOME` 或 `DSHVIZ_SESSIONS_ROOT` |
+| 面板空白 + 网络面板 403 | 不是本机访问；见上一节 |
+
+## 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).
+
+**中文** — 折叠是增量的：只解新追加的 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? / 能在公司用吗？
+
+**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.
+
+**中文** — 不行。PolyForm Noncommercial 排除了在营利性公司内部或代表公司的使用。个人学习、
+以及慈善、教育、公共研究机构等非商业组织，按许可条文是允许的。

package/README.md

@@ -36,6 +36,8 @@ rings, turns, tools and background jobs.
 
 A ring icon appears in the left rail; click it to open the instrument.
 
+Or from npm: pm i dsh-visualization (package: https://www.npmjs.com/package/dsh-visualization).
+
 ## Reading the panel
 
 | Area | What it tells you |
@@ -73,6 +75,34 @@ Direction matters: on ②–⑦ the newest data sits at 12 o'clock and older dat
 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`.
 
+## Using it as a desktop wallpaper
+
+The panel can also run inside **Wallpaper Engine** (Steam). The plugin opens a small fixed-port
+endpoint — `http://127.0.0.1:8799/` — because the DSH Web port changes on every launch and a
+wallpaper cannot guess it.
+
+**Requirements**: the plugin installed, and DSH running. If DSH is off the wallpaper shows a hint
+and retries every 5 seconds; when DSH comes back on a different port the wallpaper finds it again.
+
+**Install the wallpaper**
+
+1. In Wallpaper Engine: **Create Wallpaper** → pick **Web** as the type
+2. When it asks for a file, choose the `wallpaper/index.html` from this repository (or
+   `wallpaper/project.json` if your version of WE asks for a project)
+3. Save the project somewhere permanent and preview it. It connects to `127.0.0.1:8799` by itself.
+
+**Changing the port**: the plugin tries 8799, then 8798, 8797, 8796, 8795. To use a different base
+port, set `wallpaperPort` in the plugin config; set it to `0` to turn the endpoint off.
+
+**If it stays on the "not connected" screen**
+
+| Cause | Fix |
+|---|---|
+| DSH is not running | start it |
+| the plugin is disabled | enable `dsh-visualization` on the Plugins page |
+| 8799–8795 are all taken | set `wallpaperPort` to a free port and edit `PORTS` in `wallpaper/index.html` |
+| CPU spikes while gaming | in Wallpaper Engine, enable "pause when a fullscreen app runs" |
+
 ## When something looks wrong
 
 | Symptom | Cause |
@@ -144,6 +174,7 @@ list and key the dictionaries by code.
 |---|---|---|
 | `basePath` | `/dsh-visualization` | route prefix |
 | `allowRemote` | `false` | allow non-loopback peers. **This exposes session logs to anyone who can reach the port.** |
+| `wallpaperPort` | `8799` | fixed local port for the wallpaper entry; tries 8799 down to 8795. `0` disables it |
 
 ## Routes
 
@@ -223,6 +254,32 @@ DSH 装在别处时用环境变量 `DSH_HOME` 或 `DSHVIZ_SESSIONS_ROOT` 指过
 | 某个格子暗、没有线 | 它不在「连线轮数」范围内 |
 | 格子亮、没有线 | 这一步没有工具调用（纯文字步） |
 
+## 当桌面壁纸用（Wallpaper Engine）
+
+这个面板也能放进 **Wallpaper Engine**（Steam）当桌面壁纸。插件会在本机开一个**固定端口**——
+`http://127.0.0.1:8799/`——因为 DSH 的 Web 端口每次启动都会变，壁纸没法猜。
+
+**前提**：装了插件，且 DSH 正在运行。DSH 关掉时壁纸显示提示并每 5 秒重试；DSH 换了端口重启，
+壁纸会自己重新找到。
+
+**导入步骤**
+
+1. Wallpaper Engine 里点 **创建壁纸（Create Wallpaper）** → 类型选 **网页（Web）**
+2. 选文件时指向本仓库的 `wallpaper/index.html`（如果你的版本要选工程，就选 `wallpaper/project.json`）
+3. 存到固定位置，应用即可。它会自己连上 `127.0.0.1:8799`
+
+**改端口**：插件会依次尝试 8799 → 8798 → 8797 → 8796 → 8795。想换起始端口，在插件配置里写
+`wallpaperPort`；写 `0` 就是关掉这个入口。
+
+**一直显示"没有连上"怎么办**
+
+| 原因 | 处理 |
+|---|---|
+| DSH 没开 | 启动 DSH |
+| 插件被禁用了 | 在插件页启用 `dsh-visualization` |
+| 8795–8799 都被占用 | 配置里换个端口，同时改 `wallpaper/index.html` 里的 `PORTS` 数组 |
+| 玩游戏时卡顿 | 在 Wallpaper Engine 里打开"其他应用全屏时暂停" |
+
 ## 给 agent / 开发者的编辑说明
 
 **文件**：`index.js`（宿主入口，注册路由 + 注入 origin/策略）、`fold.cjs`（会话发现、zstd 帧解析、
@@ -246,7 +303,8 @@ DSH 装在别处时用环境变量 `DSH_HOME` 或 `DSHVIZ_SESSIONS_ROOT` 指过
 `showDetail()` 的详情分支；新语言 = `EN` 词典 + `EN_RULES` 正则 + `EN_FN` 逻辑替换，并把 `LANG`
 从 `'zh'|'en'` 改成列表；新工具配色 = `toolColor()`。
 
-**配置**：`basePath`（默认 `/dsh-visualization`）、`allowRemote`（默认 `false`，打开等于把会话日志暴露给能访问该端口的人）。
+**配置**：`basePath`（默认 `/dsh-visualization`）、`allowRemote`（默认 `false`，打开等于把会话日志暴露给能访问该端口的人）、
+`wallpaperPort`（默认 `8799`，壁纸用的固定端口，写 0 关闭）。
 
 **已知限制**：内存随会话线性增长（十万条时每帧 `result()` 约 10~20ms）；界面只有中英两门语言；
 仪表只读，从不写会话文件。

package/fold.cjs

@@ -658,6 +658,40 @@ function setPolicy(policy) {
   if (policy && typeof policy.allowRemote === 'boolean') ALLOW_REMOTE = policy.allowRemote
 }
 
+
+/* ---------------- 固定端口的"壁纸入口" ----------------
+   DSH 的 Web 端口每次启动都会变，壁纸里写死端口就必然失效。
+   这里在 127.0.0.1 上开一个固定端口（默认 8799，被占用就依次退），
+   只转发到本进程的 handle()，所以壁纸永远访问同一个地址。 */
+let HELPER = null
+
+function startHelper(preferredPort) {
+  if (HELPER) return HELPER
+  const http = require('node:http')
+  const base = Number(preferredPort) || 8799
+  let attempt = 0
+  const tryListen = () => {
+    if (attempt > 4) return null
+    const port = base - attempt
+    attempt++
+    const srv = http.createServer((rq, rs) => {
+      /* 把根路径映射成插件前缀，handle() 内部按 /dsh-visualization 路由 */
+      rq.url = '/dsh-visualization' + (rq.url || '/')
+      handle(rq, rs)
+    })
+    srv.on('error', () => { try { srv.close() } catch (e) { } tryListen() })
+    srv.listen(port, '127.0.0.1', () => {
+      HELPER = { port: port, server: srv }
+      try { console.log('[dsh-visualization] wallpaper entry: http://127.0.0.1:' + port + '/') } catch (e) { }
+    })
+    return srv
+  }
+  tryListen()
+  return HELPER
+}
+
+function helperPort() { return HELPER ? HELPER.port : 0 }
+
 function handle(req, res) {
   if (!ALLOW_REMOTE && !isLoopback(req)) {
     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
@@ -677,11 +711,16 @@ function handle(req, res) {
         'cache-control': 'no-store',
         'content-encoding': 'gzip',
         vary: 'accept-encoding',
+        'access-control-allow-origin': '*',
       })
       res.end(zlib.gzipSync(body))
       return
     }
-    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+    res.writeHead(200, {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+      'access-control-allow-origin': '*',
+    })
     res.end(body)
   }
   /* 救急：把浏览器里还开着的那一页 DOM 存回磁盘（instrument.html 被误覆盖时用） */
@@ -832,4 +871,7 @@ function handle(req, res) {
   res.writeHead(404); res.end('not found')
 }
 
-module.exports = { handle, listSessions, pickSession, refresh, fold, makeFolder, setOrigin, setPolicy, hasZstd: HAS_ZSTD }
+module.exports = {
+  handle, listSessions, pickSession, refresh, fold, makeFolder,
+  setOrigin, setPolicy, startHelper, helperPort, hasZstd: HAS_ZSTD,
+}

package/index.js

@@ -27,4 +27,11 @@ export function apply(ctx, config = {}) {
     path: prefix,
     handler: (req2, res) => core.handle(req2, res),
   }))
+
+  /* 固定端口的壁纸入口（默认 8799）：桌面壁纸没法知道 DSH 每次随机分配的端口。
+     config.wallpaperPort 可以改，写 0 关闭。 */
+  try {
+    const port = config && config.wallpaperPort !== undefined ? Number(config.wallpaperPort) : 8799
+    if (port > 0) ctx.effect(() => (core.startHelper(port), () => { }))
+  } catch (e) { /* 端口被占之类的情况不影响主路由 */ }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-visualization",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "DSH Visualization — a session instrument: rings, turns, tools and background jobs of a live DeepSeek Harness session.",
   "type": "module",
   "main": "index.js",
@@ -26,7 +26,9 @@
     "locale",
     "icon.svg",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "FAQ.md",
+    "wallpaper"
   ],
   "keywords": [
     "dsh",

package/wallpaper/index.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<title>DSH Visualization</title>
+<style>
+  html, body { margin: 0; height: 100%; background: #0b0d11; overflow: hidden; }
+  iframe { width: 100vw; height: 100vh; border: 0; display: block; }
+  #off {
+    position: fixed; inset: 0; display: none; flex-direction: column;
+    align-items: center; justify-content: center; gap: 14px;
+    color: #8d97ab; font: 15px/1.7 "Segoe UI", "Microsoft YaHei", sans-serif;
+    background: radial-gradient(circle at 50% 45%, #141a24, #0b0d11 70%);
+    text-align: center;
+  }
+  #off b { color: #e6edfa; font-size: 19px; font-weight: 600; letter-spacing: .04em; }
+  #off code { color: #ffc46b; background: #1a1f29; padding: 2px 7px; border-radius: 4px; font-size: 13px; }
+</style>
+</head>
+<body>
+<iframe id="frame" allow="cross-origin-isolated"></iframe>
+<div id="off">
+  <b>DSH Visualization</b>
+  <div>没有连上 DeepSeek Harness。</div>
+  <div>请确认：装了 <code>dsh-visualization</code> 插件，并且 DSH 正在运行。</div>
+  <div style="opacity:.65">每 5 秒自动重试</div>
+</div>
+<script>
+/* 插件的壁纸入口固定在这个区间（8799 起，被占用依次往下） */
+var PORTS = [8799, 8798, 8797, 8796, 8795];
+var frame = document.getElementById('frame');
+var off = document.getElementById('off');
+var chosen = 0;
+
+function probe() {
+  var i = 0;
+  function next() {
+    if (i >= PORTS.length) { frame.style.display = 'none'; off.style.display = 'flex'; chosen = 0; return; }
+    var p = PORTS[i++];
+    var ctl = new AbortController();
+    var timer = setTimeout(function () { ctl.abort() }, 1200);
+    fetch('http://127.0.0.1:' + p + '/state', { signal: ctl.signal, cache: 'no-store' })
+      .then(function (r) { return r.ok ? r.json() : null })
+      .then(function (j) {
+        clearTimeout(timer);
+        if (!j) return next();
+        chosen = p;
+        off.style.display = 'none';
+        frame.style.display = 'block';
+        if (frame.src.indexOf(':' + p + '/') < 0) frame.src = 'http://127.0.0.1:' + p + '/';
+      })
+      .catch(function () { clearTimeout(timer); next(); });
+  }
+  next();
+}
+
+probe();
+/* 断线后自动重连：DSH 重启会换端口，所以每次都重新探测 */
+setInterval(function () { if (!chosen) probe(); }, 5000);
+</script>
+</body>
+</html>

package/wallpaper/project.json

@@ -0,0 +1,13 @@
+{
+  "contentrating": "Everyone",
+  "description": "A live session instrument for DeepSeek Harness: seven rings, a turn timeline, per-step ladders. Needs the dsh-visualization plugin installed and DSH running — the wallpaper talks to http://127.0.0.1:8799/, which the plugin opens on a fixed port. Noncommercial; visual language derived from HALOFLUX by Ryder191.",
+  "file": "index.html",
+  "preview": "preview.jpg",
+  "tags": [
+    "Abstract",
+    "Technology"
+  ],
+  "title": "DSH Visualization",
+  "type": "web",
+  "version": 1
+}

package/web/index.html

@@ -979,6 +979,21 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--ink);
       for (var cq = 0; cq < CHAIN_PREV.length; cq++) {
         var ce = CHAIN_PREV[cq], cps = ce.pts;
         for (var cp = 1; cp < cps.length; cp++) segLine(cps[cp - 1], cps[cp], ce.bright, ce.fr);
+        /* 用到技能的那一步：③ 上加发光环 + 两段高亮，否则技能环上永远是个空环 */
+        if (ce.skill) {
+          var sp = ce.skill, si = cps.indexOf(sp);
+          var hg = X.createRadialGradient(sp.x, sp.y, 0, sp.x, sp.y, 15);
+          hg.addColorStop(0, 'rgba(150,200,255,.42)');
+          hg.addColorStop(1, 'rgba(150,200,255,0)');
+          X.fillStyle = hg; X.beginPath(); X.arc(sp.x, sp.y, 15, 0, TAU); X.fill();
+          X.strokeStyle = 'rgba(160,205,255,.9)'; X.lineWidth = 1.8;
+          X.beginPath(); X.arc(sp.x, sp.y, 3.6, 0, TAU); X.stroke();
+          X.strokeStyle = 'rgba(150,200,255,.6)'; X.lineWidth = 2;
+          X.beginPath();
+          if (si > 0) { X.moveTo(cps[si - 1].x, cps[si - 1].y); X.lineTo(sp.x, sp.y); }
+          if (si >= 0 && si < cps.length - 1) { X.moveTo(sp.x, sp.y); X.lineTo(cps[si + 1].x, cps[si + 1].y); }
+          X.stroke();
+        }
         /* 移动光点：按路径长度插值 */
         var lens = [], tot = 0;
         for (var cl = 1; cl < cps.length; cl++) {
@@ -1130,6 +1145,32 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--ink);
         });
       }
     }
+    /* 技能是被调用的稀疏事件：给它一条自己的连线，别指望"某一步用了 skill"那条阶梯 */
+    if (M.skills.length) {
+      var nowSk = clockNow();
+      var spanSk = RSPAN[1] || (M.sSteps && M.sSteps.length
+        ? Math.max(120000, nowSk - M.sSteps[0].t) : 120000);
+      for (i = 0; i < M.skills.length && i < 16; i++) {
+        var skI = M.skills[i];
+        var aSk = rotOf(2, t) - Math.PI / 2 + TAU * i / 16;
+        var px = ox + Math.cos(aSk) * rr, py = oy + Math.sin(aSk) * rr;
+        var age = nowSk - (skI.last || 0);
+        if (age >= 0 && age <= spanSk) {
+          var aTo = -Math.PI / 2 + (age / spanSk) * TAU + rotOf(1, t);
+          var qx = ox + Math.cos(aTo) * R[1], qy = oy + Math.sin(aTo) * R[1];
+          X.strokeStyle = rgba(COL.skill, 0.8); X.lineWidth = 2.6;
+          X.beginPath(); X.moveTo(px, py); X.lineTo(qx, qy); X.stroke();
+          X.beginPath(); X.arc(qx, qy, 3, 0, TAU);
+          X.fillStyle = rgba(COL.skill, 0.95); X.fill();
+        }
+        var hgS = X.createRadialGradient(px, py, 0, px, py, 19);
+        hgS.addColorStop(0, rgba(COL.skill, 0.75));
+        hgS.addColorStop(1, rgba(COL.skill, 0));
+        X.fillStyle = hgS; X.beginPath(); X.arc(px, py, 19, 0, TAU); X.fill();
+        X.beginPath(); X.arc(px, py, 4.2, 0, TAU);
+        X.fillStyle = rgba(COL.skill, 0.95); X.fill();
+      }
+    }
     }
 
     /* ④ 工具环：不看时间，看「构成」
@@ -1404,15 +1445,20 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--ink);
             return x5.turn === s5.turn && x5.step === s5.step;
           });
           var usedSkill = stepTools.some(function (x5) { return x5.name === 'skill'; });
+          var skillPt = null;
+          if (usedSkill) {
+            /* ③ 技能环只落一个点，再向 ④ 扇开（原来每个工具都插一个 ③ 点，会来回跳） */
+            var aK0 = (SKILL_ANG == null)
+              ? (segMap['skill'] != null ? segMap['skill'] : -Math.PI / 2)
+              : SKILL_ANG;
+            skillPt = { x: ox + Math.cos(aK0) * R[2], y: oy + Math.sin(aK0) * R[2] };
+            path.push(skillPt);
+          }
           var used = 0;
           for (var tj = 0; tj < stepTools.length && used < 12; tj++) {
             var tl5 = stepTools[tj];
             var aT5 = segMap[tl5.name];
             if (aT5 == null) continue;
-            if (usedSkill) {
-              var aK = (SKILL_ANG == null) ? aT5 : SKILL_ANG;
-              path.push({ x: ox + Math.cos(aK) * R[2], y: oy + Math.sin(aK) * R[2] });
-            }
             path.push({ x: ox + Math.cos(aT5) * R[3], y: oy + Math.sin(aT5) * R[3] });
             used++;
           }
@@ -1443,7 +1489,7 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--ink);
           /* 这里只攒几何，真正的绘制在下一帧开头（画环之前）完成 —— 线在环下面 */
           if (path.length > 1) {
             CHAIN_PREV.push({
-              pts: path, bright: bright, fr: fr5,
+              pts: path, bright: bright, fr: fr5, skill: skillPt,
               phase: (i / Math.max(1, arr3.length)) * 0.8
             });
           }