dsh-dynamic-background

一个独立的 DSH Web UI 动态背景插件，采用 CSS 氛围层 + 常驻低密度 Canvas 粒子。

主要特性：

• 视觉层不再随会话状态切换，避免响应式特效与真实状态不同步；
• 多层星空由静态星尘、168+ 微视差远星、银河薄雾和前景星群组成，并提供星芒、彗尾、弧形星链与沿线流光，不使用模糊；
• Canvas 受像素预算、帧率、粒子数和 DPR 四重上限约束；页面隐藏、强制低动态、强度为零或手动关闭时完全暂停；
• auto / eco / balanced / high 四档质量会根据屏幕像素、内存和 CPU 核数自动选择；
• 在 DSH 深色主题下提高正文、次要文字与代码高亮的对比度，并统一半透明深色表面；切换浅色主题时自动暂停并恢复宿主原始外观；
• 背景动画位于隔离的 Shadow DOM，适配样式以 DSH 设计令牌为主，不改写已有插件 DOM。

视觉策略

| 会话状态 | 视觉行为 | | --- | --- | | 所有状态 | 保持同一套常驻环境粒子与 CSS 氛围层 | | reduced motion / 页面隐藏 | 暂停 Canvas 动画，保留静态背景 |

getState() 与 subscribe() 仍会提供会话状态，便于诊断和集成，但不会再改变背景颜色、粒子运动或 CSS 特效。

安装

要求 Node.js 20+ 和可用的 DSH Web profile。正式版本可以直接从 npm 安装：

dsh plugin --profile web add dsh-dynamic-background

安装完成后重启 dsh web，并在浏览器中执行一次强制刷新。插件可以独立安装，不需要修改 dsh-web-ui-all、SSH、梁神模式或右侧面板插件。

更新

dsh plugin --profile web update dsh-dynamic-background

更新后重启 dsh web 并刷新页面。

卸载

dsh plugin --profile web remove dsh-dynamic-background

安装开发版本

git clone https://github.com/JS24588542/dsh-dynamic-background.git
cd dsh-dynamic-background
npm install
dsh plugin --profile web add link:/absolute/path/to/dsh-dynamic-background

link 安装会直接使用工作区中的 lib/client.js，适合本地开发和浏览器验证。

配置

插件默认开启，配置保存在浏览器 localStorage 的 dsh.dynamic-background.settings.v1 中。浏览器控制台可以使用以下命令：

window.__DSH_DYNAMIC_BACKGROUND__.setSettings({
  enabled: true,
  intensity: 0.68,
  reducedMotion: null,
  quality: "auto" // auto / eco / balanced / high
})

排查动态响应时可以读取当前识别到的状态：

window.__DSH_DYNAMIC_BACKGROUND__.getState() // 立即读取：idle / thinking / tool / waiting / done / error
window.__DSH_DYNAMIC_BACKGROUND__.getPerformanceInfo()
// 查看实际质量档、实测/目标帧率、粒子数、Canvas 像素数、主题及渲染状态

const unsubscribe = window.__DSH_DYNAMIC_BACKGROUND__.subscribe((event) => {
  console.log(event.state, event.previous, event.at)
})
// unsubscribe() // 停止监听

也可以派发事件：

window.dispatchEvent(new CustomEvent("dsh-dynamic-background:settings", {
  detail: { intensity: 0.55 }
}))

reducedMotion: null 表示跟随系统 prefers-reduced-motion，默认值为 null。quality 默认 auto；4K、高 DPR、内存不超过 4 GB 或 CPU 不超过 4 线程时自动使用 eco。balanced 的 Canvas 上限为 80 万像素/20 FPS，eco 为 36 万像素/12 FPS。性能信息中的 fps 是最近一秒实测值，targetFps 是档位上限。关闭 enabled 或切换到 DSH 浅色主题时，背景和高对比度适配会停用，恢复宿主原始外观。

开发与验证

npm install
npm run check
npx playwright install chromium
npm run capture

capture 会访问 DSH_CAPTURE_URL（默认 http://127.0.0.1:3080），并将各状态及设置页截图写入 captures/。可以通过 DSH_CAPTURE_WIDTH 和 DSH_CAPTURE_HEIGHT 指定验证分辨率。

发布维护

仓库的 .github/workflows/release.yml 会在推送 v* 标签时运行检查并发布 npm 包。仓库需要配置 NPM_TOKEN secret：

npm version patch   # 或 minor / major
git push origin main --follow-tags

工作流会校验标签与 package.json 版本一致，并使用 npm provenance 发布。