dsh-visualization 0.1.2 → 0.1.3

package/README.md

@@ -75,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 |
@@ -146,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
 
@@ -225,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 帧解析、
@@ -248,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.2",
+  "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",
@@ -27,7 +27,8 @@
     "icon.svg",
     "LICENSE",
     "README.md",
-    "FAQ.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
+}