dsh-visualization 0.1.2 → 0.1.4

package/README.md

@@ -75,6 +75,36 @@ 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.
+
+![How to set it as a wallpaper](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/howto.png)
+
+**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 +176,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 +256,34 @@ DSH 装在别处时用环境变量 `DSH_HOME` 或 `DSHVIZ_SESSIONS_ROOT` 指过
 | 某个格子暗、没有线 | 它不在「连线轮数」范围内 |
 | 格子亮、没有线 | 这一步没有工具调用（纯文字步） |
 
+## 当桌面壁纸用（Wallpaper Engine）
+
+这个面板也能放进 **Wallpaper Engine**（Steam）当桌面壁纸。插件会在本机开一个**固定端口**——
+`http://127.0.0.1:8799/`——因为 DSH 的 Web 端口每次启动都会变，壁纸没法猜。
+
+**前提**：装了插件，且 DSH 正在运行。DSH 关掉时壁纸显示提示并每 5 秒重试；DSH 换了端口重启，
+壁纸会自己重新找到。
+
+![How to set it as a wallpaper](https://raw.githubusercontent.com/peilopielo/dsh-Visualization/main/assets/howto.png)
+
+**导入步骤**
+
+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 +307,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.4",
   "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/howto.html

@@ -0,0 +1,97 @@
+<!doctype html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<style>
+  :root{
+    --bg:#0b0d11; --panel:#141922; --line:#232b38; --txt:#e6edfa; --dim:#8d97ab;
+    --amber:#ffc46b; --mint:#8fe0c8; --coral:#ff7a5c; --violet:#b28cff; --sky:#7fb2ff;
+  }
+  *{box-sizing:border-box}
+  html,body{margin:0;background:var(--bg);font:13px/1.6 "Segoe UI","Microsoft YaHei",sans-serif;color:var(--txt)}
+  .wrap{width:1400px;padding:28px 30px 30px}
+  h1{margin:0 0 4px;font-size:19px;letter-spacing:.04em}
+  .sub{color:var(--dim);font-size:12.5px;margin-bottom:22px}
+  .row{display:flex;gap:18px}
+  .card{flex:1;background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px 16px 18px;position:relative}
+  .n{position:absolute;top:-11px;left:16px;background:var(--bg);border:1px solid var(--line);color:var(--amber);
+     font-size:11px;letter-spacing:.14em;padding:2px 9px;border-radius:20px}
+  .t{font-size:13.5px;margin:6px 0 12px;font-weight:600}
+  .muted{color:var(--dim)}
+  .kbd{border:1px solid var(--line);background:#0f141c;border-radius:4px;padding:1px 6px;font-size:11.5px;color:var(--txt)}
+  .mock{border:1px solid var(--line);border-radius:7px;overflow:hidden;background:#0f141c}
+  .mock .bar{height:22px;background:#111721;border-bottom:1px solid var(--line);display:flex;align-items:center;padding:0 8px;gap:5px}
+  .dot{width:7px;height:7px;border-radius:50%;background:#2b3444}
+  .mock .body{padding:10px}
+  .opt{display:flex;align-items:center;gap:8px;padding:6px 8px;border-radius:5px;border:1px solid transparent}
+  .opt.sel{background:#1a2433;border-color:#2f4straight}
+  .opt.sel{border-color:#3a4a63}
+  .opt .ico{width:16px;height:16px;border-radius:3px;background:#2a3342}
+  .opt.sel .ico{background:var(--sky)}
+  .foot{margin-top:14px;display:flex;justify-content:space-between;align-items:center}
+  .btn{background:#1d2634;border:1px solid var(--line);border-radius:5px;padding:5px 12px;font-size:12px;color:var(--dim)}
+  .btn.on{background:var(--amber);border-color:var(--amber);color:#1a1206;font-weight:600}
+  .path{font-family:Consolas,monospace;font-size:11.5px;color:var(--mint);background:#0f141c;border:1px solid var(--line);
+        border-radius:4px;padding:5px 8px;display:block;margin-top:8px;word-break:break-all}
+  .flow{margin-top:14px;display:flex;align-items:center;gap:8px;flex-wrap:wrap;font-size:11.5px}
+  .node{border:1px solid var(--line);border-radius:5px;padding:4px 8px;background:#0f141c;color:var(--dim)}
+  .node.hot{border-color:var(--amber);color:var(--amber)}
+  .arw{color:#3d4757}
+  .note{margin-top:12px;font-size:11.5px;color:var(--dim);border-left:2px solid var(--violet);padding-left:8px}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>把 DSH Visualization 设成桌面壁纸</h1>
+  <div class="sub">前提：已安装 dsh-visualization 插件，并且 DSH 正在运行 · Wallpaper Engine（Steam）</div>
+
+  <div class="row">
+    <div class="card">
+      <div class="n">STEP 1</div>
+      <div class="t">在 Wallpaper Engine 里新建壁纸</div>
+      <div class="mock">
+        <div class="bar"><span class="dot"></span><span class="dot"></span><span class="dot"></span></div>
+        <div class="body">
+          <div class="opt"><span class="ico"></span>场景 Scene</div>
+          <div class="opt"><span class="ico"></span>视频 Video</div>
+          <div class="opt sel"><span class="ico"></span><b>网页 Web</b></div>
+          <div class="opt"><span class="ico"></span>应用程序 Application</div>
+        </div>
+      </div>
+      <div class="note">点左下角 <span class="kbd">创建壁纸</span>，类型选 <b>网页</b>。</div>
+    </div>
+
+    <div class="card">
+      <div class="n">STEP 2</div>
+      <div class="t">选中仓库里的壁纸入口</div>
+      <div class="mock" style="padding:12px 12px 14px">
+        <div class="muted" style="font-size:11.5px">选择文件</div>
+        <span class="path">wallpaper&#92;index.html</span>
+        <div class="muted" style="font-size:11.5px;margin-top:10px">同目录还有（不用选）</div>
+        <span class="path" style="color:var(--dim)">project.json · preview.jpg</span>
+      </div>
+      <div class="note">路径来自你安装插件的目录，通常在<br><span style="color:var(--dim)">…/profiles/desktop/node_modules/dsh-visualization/wallpaper/</span></div>
+    </div>
+
+    <div class="card">
+      <div class="n">STEP 3</div>
+      <div class="t">直接应用，不用配置</div>
+      <div class="flow">
+        <span class="node">DSH 随机端口<br><span style="opacity:.6">:1233 :7632 …</span></span>
+        <span class="arw">→</span>
+        <span class="node hot">插件固定端口<br>127.0.0.1:8799</span>
+        <span class="arw">→</span>
+        <span class="node">壁纸</span>
+      </div>
+      <div class="note">壁纸只会访问 <b>8799</b>；插件在内部转发到这次 DSH 的真实端口。
+        连不上时壁纸显示提示，每 5 秒重试一次，DSH 换端口后会自动找到。</div>
+    </div>
+  </div>
+
+  <div class="sub" style="margin-top:20px;margin-bottom:0">
+    端口 8799 被占用时插件会依次退到 8798 / 8797 / 8796 / 8795；要固定成别的，在插件配置里写
+    <span class="kbd">wallpaperPort</span>，同时改 <span class="kbd">wallpaper/index.html</span> 里的 PORTS 数组。
+  </div>
+</div>
+</body>
+</html>

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
+}