dsh-theme-palette 1.3.0 → 1.3.2

package/README.md

@@ -7,6 +7,48 @@ DSH Web / Desktop 的主题配色插件：**4 套配色 × 明暗两模式**，
 
 当前版本 **0.8.2**（0.8.1 按深色专项审计重做深色侧，0.8.2 把强调色换成设计稿标准值；见 §修订记录）。
 
+## 为什么配色会自己跳回默认（v1.3.1）
+
+现象：设了暖砂，用了一阵（跑模型操作、切窗口、长时间放着），**突然变成黑白**，但设置页里
+「暖砂」还是选中的。原因在宿主的 override 生命周期：
+
+```js
+// ThemeRuntime（宿主）
+overrideTokens(source, tokens) {
+  const layer = { seq: this.overrideSeq++, tokens: validateOverrides(source, tokens) }
+  this.overrides.set(source, layer)
+  this.publish()
+  return () => { if (this.overrides.get(source) !== layer) return; this.overrides.delete(source); this.publish() }
+}
+```
+
+而插件侧拿到的是被 runner 包装过的版本 —— **每一层的 disposer 都被挂在调用方的 fiber 上**：
+
+```js
+const dispose = Reflect.apply(method, target, [id, tokens])
+ctx.effect(() => dispose, 'cordis-client-runner: dynamic theme override layer')
+```
+
+也就是说：**这一层的生命周期 = 插件 fiber 的生命周期**。插件被卸载/重载、或 fiber 的
+effect 被清理时，层就没了；`composeActive` 在 `overrides.size === 0` 时直接返回内置主题，
+于是页面**静默**变回默认色 —— localStorage 里的选择还在，设置页自然还显示暖砂。
+
+会触发 fiber 重载的典型情况：动态插件被宿主重载（改过插件文件/profile、宿主自我更新）、
+渲染进程恢复、以及某些"模型操作"引起的插件重载。
+
+**v1.3.1 的处理**：加了一个自愈环。窗口重新可见 / 获焦 / `pageshow` / `theme/change` /
+每 4 秒，回读 `body` 上的 5 个关键 token；不在了就把最后一层重放：
+
+```
+[dsh-theme-palette] 配色层不见了（visibility），已重放第 1 次
+```
+
+设置页顶部会显示"配色层被宿主丢过一次，已自动恢复 N 次"；健康时不产生任何写入。
+
+**另一种可能**（值得先分辨）：如果是 **localStorage 被清**（换 profile、清缓存），设置页会回到
+「黑白」选中态 —— 那种情况自愈救不回来，因为连"你想用哪套"都丢了。判据就是**设置页里选中的
+是不是你原来那套**。
+
 ## 设置页重排（v1.3.0）
 
 原来的设置页是六行"工程参数"堆在一起、每行都是同一种小药丸。v1.3.0 重做成四段：
@@ -496,12 +538,49 @@ alpha **浅色与内置一致、深色压到 0.6 倍**（见下）：
 
 ## 安装
 
+从 npm（推荐）：
+
+```bash
+# 方式 A：装进 DSH profile
+cd ~/.dsh/profiles/desktop
+pnpm add dsh-theme-palette
+
+# 方式 B：用 DSH 的插件命令
+dsh plugin --profile desktop add dsh-theme-palette
+```
+
+从 GitHub Release 的 tarball（npm 不可达时）：
+
+```bash
+pnpm add "https://github.com/zuoyunlai/dsh-theme-palette/releases/download/v1.3.1/dsh-theme-palette-1.3.1.tgz"
+```
+
+从源码（开发调试）：
+
+```bash
+git clone https://github.com/zuoyunlai/dsh-theme-palette.git
+dsh plugin --profile desktop add "$PWD/dsh-theme-palette"
 ```
-dsh plugin --profile desktop add "E:\Documents\deepseek-harness\default-workspace\dsh-theme-palette"
+
+装完**必须重启 GUI**（运行中的进程仍持旧模块）。
+
+> 开发时注意：`node_modules/dsh-theme-palette` 是**副本**，改源码后要
+> `rm -rf node_modules/dsh-theme-palette && pnpm install` —— `pnpm add` 对已存在的
+> `file:` 目录不会刷新内容。
+
+安装后：左下角头像 → 设置 → 左侧「**主题色**」。
+
+## 发版
+
+```bash
+node tools/release.mjs --dry      # 本地检查：语法 / 工作区 / 打包内容 / 版本是否已存在
+node tools/release.mjs            # 真发布（npm 已登录）+ 等 registry 放出 + 校验 latest
+node tools/release.mjs --tag      # 发布后再打 tag 并推 main + tag
 ```
 
-装完**必须重启 GUI**。`node_modules/dsh-theme-palette` 是**副本**，改源码后要删掉副本再 `pnpm install`
-（`pnpm add` 对已存在的 `file:` 目录不会刷新内容）。
+脚本要处理三件容易出错的事：本机 npm 默认源是 npmmirror（**必须显式指官方源**）；
+新包名的首次发布会进**暂存审核**（CLI 照打印 `+ pkg@ver`，但 registry 要过几分钟才 200）；
+`latest` 不保证自动前移。2026-10-21 实测：提交到放出约 **8 分钟**。
 
 ## 结构
 
@@ -570,6 +649,14 @@ dsh plugin --profile desktop add "E:\Documents\deepseek-harness\default-workspac
 - 苔绿强调 `155°→165°` —— 与底色（h≈152）从 2° 拉开到 13°，链接不再只靠明度识别
 - 深色对比度：正文 14.40–14.98、三级 4.79 起、链接 4.65 起（0 处低于下限）
 
+**1.3.2**
+- README 安装说明改为 npm / Release tarball / 源码三条路径，去掉本机绝对路径
+- 新增 `tools/release.mjs`：一键发版（检查 → 发布 → 等 registry → 校验 latest → 可选打 tag）
+
+**1.3.1**
+- 自愈：override 层被宿主丢掉时（插件 fiber 重载等）自动重放，设置页显示恢复次数
+- 触发点：visibilitychange / focus / pageshow / theme/change / 4s 定时；健康时零写入
+
 **1.3.0**
 - 设置页重排：2×2 缩略图卡片（随明暗切换）+ 段落式设置行 + 分段控件 + 版本徽标
 - 样式从内联改为独立注入的 `settings.css`（支持 hover / 窄屏 / `body[data-ds-dark-theme]`）

package/client.js

@@ -27,7 +27,7 @@ window.__ModuleLoader__.load({
     const React = require('react')
     const h = React.createElement
 
-    const PLUGIN_VERSION = '1.3.0'
+    const PLUGIN_VERSION = '1.3.2'
     const STORE_KEY = 'dsh-theme-palette.v1'
     const OVERRIDE_SOURCE = 'dsh-theme-palette'
 
@@ -1119,6 +1119,11 @@ body[data-ds-dark-theme] .dsh-tp-check{background:var(--t-accent-d);color:var(--
         row(txt.sidebar, txt.sidebarSub, seg(SIDEBAR_MODES, sidebarMode, props.setSidebarMode)),
         row(txt.rightbar, txt.rightbarSub, seg(RIGHTBAR_MODES, rightbarMode, props.setRightbarMode)),
         health && !health.ok && h('p', { className: 'dsh-tp-status is-bad' }, txt.bad),
+        health && health.ok && health.reapplies > 0 && h(
+          'p',
+          { className: 'dsh-tp-status' },
+          (isZh() ? '配色层被宿主丢过一次，已自动恢复 ' : 'Palette layer was dropped by the host; restored ') + health.reapplies + (isZh() ? ' 次' : 'x'),
+        ),
         h('button', {
           type: 'button',
           className: 'dsh-tp-more',
@@ -1210,7 +1215,13 @@ body[data-ds-dark-theme] .dsh-tp-check{background:var(--t-accent-d);color:var(--
 
         let disposeLayer = () => {}
         /** 按当前配色 + 侧栏档位重建覆盖层（换配色与换侧栏档位走同一条路）。 */
-        const applyAll = () => {
+        // 最近一次成功应用的 token 表与原因：自愈时据此重放，也用来解释"为什么又变回去了"。
+        let lastTokens = null
+        let lastAppliedAt = 0
+        let lastReason = 'init'
+        let reapplyCount = 0
+
+        const applyAll = (reason) => {
           const scheme = SCHEMES.find((s) => s.id === current) || SCHEMES[0]
           const tokens = buildTokens(scheme, sidebarMode, textMode, rightbarMode, scrollMode, controlMode, mdMode)
           let next = () => {}
@@ -1226,8 +1237,38 @@ body[data-ds-dark-theme] .dsh-tp-check{background:var(--t-accent-d);color:var(--
           const prev = disposeLayer
           disposeLayer = next
           prev()
+          if (reason !== undefined) lastReason = reason
+          lastTokens = tokens
+          lastAppliedAt = Date.now()
           scheduleProbe(tokens)
         }
+        /**
+         * 自愈。
+         *
+         * 宿主的 theme.overrideTokens 把每一层的 disposer 挂在**调用方 fiber** 上
+         * （`ctx.effect(() => dispose, ...)`）：插件被卸载/重载、或 fiber 的 effect 被清理时，
+         * 这一层就没了 —— 表现正是"配色自己跳回默认"，而 localStorage 里的选择还在。
+         * 这里定期（以及窗口重新可见/获焦时）回读 body：token 不在了就把最后一层重放。
+         */
+        const ensureApplied = (reason) => {
+          if (lastTokens === null) return
+          if (Date.now() - lastAppliedAt < 900) return
+          let missing = false
+          try {
+            const style = getComputedStyle(document.body)
+            for (const name of TOKEN_PROBE) {
+              if (!(name in lastTokens)) continue
+              if (style.getPropertyValue(name).trim() === '') { missing = true; break }
+            }
+          } catch (err) {
+            missing = true
+          }
+          if (!missing) return
+          reapplyCount += 1
+          console.info('[dsh-theme-palette] 配色层不见了（' + reason + '），已重放第 ' + reapplyCount + ' 次')
+          applyAll('self-heal:' + reason)
+        }
+
         let health = null
         const healthListeners = new Set()
         const getHealth = () => health
@@ -1243,7 +1284,7 @@ body[data-ds-dark-theme] .dsh-tp-check{background:var(--t-accent-d);color:var(--
             const next = probeApplied(tokens)
             if (next === null) return
             if (health !== null && health.ok === next.ok && health.checked === next.checked) return
-            health = next
+            health = { ...next, reapplies: reapplyCount }
             if (!next.ok) console.warn('[dsh-theme-palette] 有 token 没写进 body，宿主可能改名了')
             emitHealth()
           }
@@ -1321,11 +1362,36 @@ body[data-ds-dark-theme] .dsh-tp-check{background:var(--t-accent-d);color:var(--
           console.warn('[dsh-theme-palette] dev hook attach 失败：', err)
         }
 
+        // 自愈的触发点：窗口回前台、获焦、页面恢复、主题事件、以及一个低频定时器。
+        const heal = (why) => () => { try { ensureApplied(why) } catch (err) { /* 自愈失败不影响主流程 */ } }
+        const healOnVisible = heal('visibility')
+        const healOnFocus = heal('focus')
+        const healOnShow = heal('pageshow')
+        const healOnTheme = heal('theme-change')
+        let healTimer = null
+        try {
+          document.addEventListener('visibilitychange', healOnVisible)
+          window.addEventListener('focus', healOnFocus)
+          window.addEventListener('pageshow', healOnShow)
+        } catch (err) { /* 无 DOM 时跳过 */ }
+        try { ctx.on('theme/change', healOnTheme) } catch (err) { /* 事件名变了就只靠定时器 */ }
+        try { healTimer = setInterval(() => ensureApplied('interval'), 4000) } catch (err) { /* 无定时器环境 */ }
+
         ctx.effect(() => {
-          applyAll()
+          applyAll('boot')
           const removeStyle = installRightbarStyle()
           const removeSettings = installSettingsStyle()
-          return () => { disposeLayer(); removeStyle(); removeSettings() }
+          return () => {
+            disposeLayer()
+            removeStyle()
+            removeSettings()
+            try {
+              document.removeEventListener('visibilitychange', healOnVisible)
+              window.removeEventListener('focus', healOnFocus)
+              window.removeEventListener('pageshow', healOnShow)
+            } catch (err) { /* 同上 */ }
+            if (healTimer !== null) { clearInterval(healTimer); healTimer = null }
+          }
         }, 'dsh-theme-palette: token layer + 右栏样式')
 
         ctx.slots.inject('settings.section', () =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-theme-palette",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "DSH 主题配色：4 套配色 × 明暗两模式，OKLCH 色域安全重建 + 真实承载面对比度求解，可调强度与面板表面。",
   "type": "module",
   "main": "index.js",
@@ -22,7 +22,8 @@
     "tools/shoot-html.mjs",
     "tools/preview-settings.mjs",
     "tools/shoot-desktop.mjs",
-    "tools/compare.mjs"
+    "tools/compare.mjs",
+    "tools/release.mjs"
   ],
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.0"

package/tools/release.mjs

@@ -0,0 +1,117 @@
+/**
+ * 一键发版：npm publish + 等 registry 出现该版本 + 校验 dist-tag + 可选打 tag 推 Git。
+ *
+ * 用法：
+ *   node tools/release.mjs --dry            # 只做本地检查（语法、打包内容、版本可用性）
+ *   node tools/release.mjs                  # 真发布（需要 npm 登录态）
+ *   node tools/release.mjs --tag            # 发布后再打 tag 并推 main + tag
+ *   node tools/release.mjs --skip-publish   # 只打 tag（版本已经在 registry 上了）
+ *
+ * 为什么需要它：本机 npm 默认源是 npmmirror，publish 必须显式指官方源；而 npm 对新包名
+ * 会走「暂存审核」，CLI 照样打印 `+ pkg@ver`，必须回查 registry 才知道有没有真的放出来。
+ * 另外 latest 不保证自动前移，得验一次。
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const root = path.resolve(here, '..')
+const args = process.argv.slice(2)
+const has = (f) => args.includes('--' + f)
+
+const REGISTRY = 'https://registry.npmjs.org'
+// Windows 上 `npm` 实际是 npm.cmd，execFileSync 不做 PATHEXT 解析，必须写全名。
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const CURL = process.platform === 'win32' ? 'curl.exe' : 'curl'
+const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'))
+const { name, version } = pkg
+const tag = 'v' + version
+
+const run = (cmd, cmdArgs, opts = {}) => {
+  const out = execFileSync(cmd, cmdArgs, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts })
+  return typeof out === 'string' ? out.trim() : ''
+}
+const sh = (cmd) => run(process.platform === 'win32' ? 'cmd' : 'sh', process.platform === 'win32' ? ['/c', cmd] : ['-c', cmd])
+const ok = (m) => console.log('  ✓ ' + m)
+const die = (m) => { console.error('  ✗ ' + m); process.exit(1) }
+
+console.log(`\n发版 ${name}@${version}${has('dry') ? '（dry run）' : ''}\n`)
+
+// 1. 本地检查
+try { run(process.execPath, ['--check', 'client.js']); ok('client.js 语法') } catch { die('client.js 语法错误') }
+const dirty = sh('git status --porcelain')
+if (dirty) die('工作区不干净，先提交：\n' + dirty)
+ok('工作区干净')
+
+const packed = run(process.platform === 'win32' ? 'cmd' : 'sh',
+  process.platform === 'win32' ? ['/c', 'npm pack --dry-run --json'] : ['-c', 'npm pack --dry-run --json'])
+try {
+  const info = JSON.parse(packed.slice(packed.indexOf('[')))[0]
+  ok(`打包 ${info.entryCount} 个文件 / ${(info.size / 1024).toFixed(1)} KB`)
+} catch { die('读不出 npm pack --dry-run 的结果') }
+
+// 2. 版本是否已在 registry
+let remote = null
+try { remote = JSON.parse(sh(`${NPM} view ${name} versions --json --registry=${REGISTRY}`)) } catch { remote = null }
+const remoteList = Array.isArray(remote) ? remote : remote ? [remote] : []
+if (remoteList.includes(version)) {
+  ok(`registry 上已有 ${version}`)
+  if (!has('skip-publish')) die('该版本已发布，先改 package.json 的 version')
+} else {
+  ok(`registry 上没有 ${version}（当前 ${remoteList.length} 个版本）`)
+}
+
+if (has('dry')) { console.log('\n干跑结束，没有发布。\n'); process.exit(0) }
+
+// 3. 发布
+if (!has('skip-publish')) {
+  console.log('\n发布中…')
+  try {
+    // Node 20+ 在 Windows 上不允许直接 spawn .cmd（CVE-2024-27980 的缓解），
+    // 必须走 shell；所以统一用 sh()，而不是 execFileSync。
+    const out = sh(`${NPM} publish --registry=${REGISTRY}`)
+    if (out) console.log(out)
+  } catch (err) {
+    die('npm publish 失败：' + (err.stderr || err.message))
+  }
+}
+
+// 4. 回查 registry（新包会进暂存审核，CLI 打印成功不代表已放出）
+console.log('\n等 registry 出现该版本（最多 10 分钟，暂存审核通过前会一直 404）…')
+const started = Date.now()
+let live = false
+while (Date.now() - started < 10 * 60 * 1000) {
+  try {
+    const code = sh(`${CURL} -s -o ${process.platform === 'win32' ? 'NUL' : '/dev/null'} -w "%{http_code}" ${REGISTRY}/${name}/${version}`)
+    if (code.trim() === '200') { live = true; break }
+  } catch { /* 网络抖动继续等 */ }
+  await new Promise((r) => setTimeout(r, 15000))
+}
+if (!live) die('10 分钟内没出现在 registry —— 可能仍在审核，稍后手动跑 npm view ' + name + ' versions')
+ok(`registry 上已可下载 ${version}`)
+
+// 5. dist-tag
+const latest = sh(`${NPM} view ${name} dist-tags.latest --registry=${REGISTRY}`).trim()
+if (latest === version) ok(`latest = ${version}`)
+else {
+  console.log(`  ! latest 指向 ${latest}，手工前移：npm dist-tag add ${name}@${version} latest --registry=${REGISTRY}`)
+  try {
+    sh(`${NPM} dist-tag add ${name}@${version} latest --registry=${REGISTRY}`)
+    ok(`已前移 latest → ${version}`)
+  } catch { console.log('  ! 前移失败，需要人工处理') }
+}
+
+// 6. Git tag（可选）
+if (has('tag')) {
+  try {
+    sh(`git tag -a ${tag} -m "${name} ${version}"`)
+    sh(`git push origin main ${tag}`)
+    ok(`已打 tag 并推送 ${tag}`)
+  } catch (err) {
+    console.log('  ! tag/推送失败：' + (err.stderr || err.message))
+  }
+}
+
+console.log(`\n完成：https://www.npmjs.com/package/${name}/v/${version}\n`)