XHR666/dsh-mpkg-wallpaper ↗★ 7
dsh-mpkg-wallpaper
DSH Web 壁纸引擎 Wallpaper Engine mpkg 背景插件:浏览器内直接解析 .mpkg(preview.gif 动态背景/内嵌 mp4 视频/多时段切换),整屏统一虚化/对话框/弹层/遮罩独立虚化、镜头缩放平移、时钟、冲突检测。 适合需要为 Web 界面添加动态视频、网页或多时段切换壁纸的用户。
설치
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:XHR666/dsh-mpkg-wallpaperdsh-mpkg-wallpaper — DSH 壁纸引擎背景插件
给 DeepSeek Harness Web 界面(dsh web)添加背景壁纸的插件:Wallpaper Engine .mpkg 解析、Steam 创意工坊目录、视频/网页/图片壁纸、时间变化壁纸的多时段切换、整屏虚化体系、主题色与玻璃外观、本地壁纸库、定时轮换、Now playing 控件、一键更新。外观细节几乎全部可调。
版本口径:本文件描述的是
package.json里3.10.1这一版实现。发布面共 15 个文件(lib/8 个运行时文件 +package.json、icon.svg、cordis.patch.yml、README.md、README.en.md、THIRD-PARTY.md、LICENSE;npm pack --dry-run实测 15 文件 / unpacked 2 088 240 B);lib/liquid-glass/**、lib/liquid-glass-bundle.js、dist/、tools/、docs/都不进 npm 包(package.json:8-21)。本轮的默认档变化:npNowPlaying关 → 开(3.8.0 起)与powPauseHidden关 → 开(3.9.0 起,只迁移"从没设过"的存量档;详见这一版新增/变更)。
下载 · 安装
插件已发布到 npm(dsh-mpkg-wallpaper)。四种装载方式——先按这张表选一条,再看对应小节:
| 方式 | 适合谁 | 更新怎么做 | 客户端界面 |
|---|---|---|---|
一 dsh plugin add(推荐) | 默认选择;市场能识别「已安装」 | dsh plugin --profile web update … | 完整 |
| 二 pnpm 手动装 | 自己管 profile 的依赖表 | 同上(走依赖表) | 完整 |
| 三 GitHub 克隆 | 开发者 / 离线 / 要改代码 | git pull | 完整 |
| 四 单文件 bundle | 离线应急;给非 DSH 宿主复用路由 | 重新生成并替换那个 .mjs | 只有宿主端 |
⚠ 桌面版(DSH Desktop)怎么装(2026-10-02 补)
DSH 桌面包目前只有 macOS / Windows。官方 README 写明:desktop 这个 profile 名由 Electron 壳独占,
CLI 会拒绝它的 boot / config-dump / 插件管理请求 ⇒ 桌面上不能照抄 dsh plugin --profile desktop add …。
桌面档请按下面两条之一走(按你手上那个桌面版本的界面为准):
- 桌面 App 自带的插件入口(若有):在设置/插件页添加 npm 包名
dsh-mpkg-wallpaper; - 手动装进桌面 profile 的依赖树:把包放进该 profile 的
node_modules/(或在其package.json里加依赖后装), 并在该 profile 的cordis.patch.yml里保留本包的挂载行(与「方式三」同形,只是 profile 换成一个由桌面壳管理的目录)。
桌面档还有一条与网页档不同的前提:宿主页面源可能不是回环 HTTP(Electron 用 file:// + IPC)。
3.11.0 起客户端已按 DSH 第一方口径兜底(location.origin 缺失或为 "null" ⇒ http://dsh.internal),
所以宿主路由在桌面档也能解析;若仍然连不上宿主,请跑 window.__mpwCompat() 与 GET /api/mpkg-wallpaper/compat
把两段 JSON 发给我们(见 docs/TRANSLUCENT-THEME.md 同级的排查说明)。
方式一:dsh plugin add(推荐,市场可识别)
dsh plugin --profile web add dsh-mpkg-wallpaper
# 重启 dsh web 后浏览器 Ctrl+F5 生效
方式二:pnpm 手动安装
pnpm --dir $DSH_HOME/profiles/
add dsh-mpkg-wallpaper
# 重启 dsh web,浏览器 Ctrl+F5 生效
与方式一同源,只是不经 dsh plugin 包装。
方式三:GitHub 克隆(开发者 / 离线)
git clone https://github.com/XHR666/dsh-mpkg-wallpaper.git $DSH_HOME/profiles/
/node_modules/dsh-mpkg-wallpaper
# 然后在 profile 的 cordis.patch.yml 注册:
# - insert:
# - id: dsh-mpkg-wallpaper
# name: dsh-mpkg-wallpaper
# 重启后生效
方式三不写依赖表 ⇒ 市场不显示「已安装」(只影响显示,不影响功能)。
方式四:单文件 bundle(离线 / 拷文件即装;只装宿主端)
把宿主端内联成一个自包含 ESM 再登记:
cd /path/to/dsh-mpkg-wallpaper
node tools/build-bundle.mjs # 产物:dist/dsh-mpkg-wallpaper.bundle.mjs(实测 449 671 B / 439.1KB;以 bundle-equivalence-test 的输出为准)
node tools/build-bundle.mjs --check # 与源码对拍:导出面 / 路由表 / ping JSON 形状(20 条断言)
node tools/bundle-equivalence-test.mjs # 更全的等价性门禁(38 条断言;门禁第 11 步)
把 dist/dsh-mpkg-wallpaper.bundle.mjs 拷到任意目录(例如 ~/.dsh/plugins/),在 profile 的 cordis.patch.yml 里按绝对路径登记,然后重开 dsh web:
# $DSH_HOME/profiles/
/cordis.patch.yml
- insert:
- id: dsh-mpkg-wallpaper
name: /绝对路径/dsh-mpkg-wallpaper.bundle.mjs # ← 指向那个 .mjs 文件本身
这条路装载了什么 / 没装载什么(都是代码与门禁事实):
| 项 | 方式四的行为 | 依据 |
|---|---|---|
| 宿主端(上传/Range 流式播放、场景提取、音频清单、设置持久化、诊断上报等 41 条路由) | 完整(lib/index.js + pkg-extract.js + web-wallpaper.js + web-interaction.js 全部内联;外部依赖只有 node 内建) | node tools/bundle-equivalence-test.mjs:路由表(kind + path)逐条相同 [41 条] |
/api/mpkg-wallpaper/ping | {ok, version, betterSidebar, betterSidebarVersion} 键集合与源码一致 | 同上 + build-bundle.mjs --check |
| 客户端半(设置面板 / 壁纸层 / 磨砂 / Now playing) | 不装载。单文件里只有宿主端导出面(apply / inject / __mpwTest) | 客户端半由 DSH 客户端模块系统按包发现:扫描宿主 Loader 条目里声明了 dsh.client 的包并解析其 exports["./client"];裸 .mjs 没有 package.json ⇒ 没有 dsh.client 声明 |
GET /api/mpkg-wallpaper/lg/*(遗留 WebGL 托管路由,客户端已不调用) | bundle 旁边没有 liquid-glass/ 时 404;cp -r lib/liquid-glass / 即与源码逐字节一致 | 该路由以 import.meta.url 定位同目录 liquid-glass/(lib/index.js:3453);门禁两种布局都断言过 |
ping.version | 上一级目录没有 package.json 时返回 null(只影响版本号显示) | new URL('../package.json', import.meta.url)(lib/index.js:1622) |
| 「检查更新 / 一键更新」 | 无伴生 package.json 时 update-check 返回 500,update-apply 会往 bundle 同级/上级目录写文件 ⇒ 不建议在方式四下使用 | lib/index.js:1792-1860 |
| 卸载 | 删掉那个 .mjs 与 cordis.patch.yml 里那一行即可 | — |
结论:方式四是"宿主端能力"的降级装载(离线/应急/给非 DSH 宿主复用路由时好用);要完整界面请用方式一/二/三。产物不入库(
dist/在.gitignore里:它是lib/*.js的纯派生物,两次构建 sha256 逐字节相同,tools/bundle-equivalence-test.mjs第②节;发布时现生成并公布哈希)。
更新
# 方式一 / 二:走 npm 的 latest 标签
dsh plugin --profile web update dsh-mpkg-wallpaper
# 方式三:在克隆目录里
git pull
# 方式四:重新生成并替换那个 .mjs
node tools/build-bundle.mjs
更新后都要:重启 dsh web → 浏览器 Ctrl+F5。
卸载
方式一/二/三:dsh plugin --profile web remove dsh-mpkg-wallpaper。
方式四:删 .mjs + cordis.patch.yml 里那一行。
残留数据(可选清理):浏览器 localStorage['dsh.mpkg-wallpaper.v2']、宿主端 ~/.dsh-mpkg-wallpaper/(settings.json、web-store.json、media-audio.json、上传的 mpkg、转码缓存、diag-*.json)。
30 秒快速开始
这节给最短路径:装完到看见壁纸,只走三步。
- 装好并重启:按上一节任选一种方式装完,重启
dsh web,浏览器Ctrl+F5。 - 打开面板:左侧栏「设置」→「壁纸引擎背景」。
- 选一张壁纸,任选其一:
- 拖入
.mpkg文件(视频类直接播;场景类走静态帧/图层合成) - 选本地图片 / 视频,或填一个图片链接
- 「自定义目录」选一个文件夹(可直接选 Steam 的
steamapps/workshop/content/431960,每个子文件夹算一张)
- 拖入
默认档就已经能用:总开关开、大文件混合模式开、整屏虚化开(30px)、Now playing 挂在左侧栏。 想微调,先动这三处就够:壁纸设置 → 磨砂模糊(0–40)、界面统一 → 整屏虚化程度(0–40)、壁纸设置 → 镜头缩放(10–2000%)。
没反应时先去「其他」tab 点一次 一键诊断上报(宿主不可用会自动下载 JSON),再带上它去反馈。
核心能力
这节按你能感知到的东西分组(来源、时间变化、虚化、外观、播放、库与轮换、安全、备份),不按代码模块。
📦 壁纸来源
- Wallpaper Engine
.mpkg:浏览器内直接解析容器(不上传第三方);视频类播放内嵌 mp4 / 视频纹理;场景类解析容器提取素材;时间变化按系统时间选时段素材 - Steam 创意工坊目录:自动发现 WE 安装(注册表 +
libraryfolders.vdf,支持非默认盘),列出video / web / scene三类;也可把 workshop 主目录(steamapps/workshop/content/431960)直接设为自定义目录——每个子文件夹自动识别为一张壁纸 - 视频:
.mp4/.webm/.mov/.m4v直接播放;网页:HTML 在沙箱 iframe 中加载(带风险预检);图片/动图/链接:本地图片或 URL(含data:image) - 自定义目录:任意文件夹,
.mpkg、workshop 子目录、图片/视频/scene.pkg混放都能识别
⏰ 时间变化壁纸(Time Variation)
- 识别 WE 的时间变化属性(
morningtime / daytime / dusktime / nighttime / timevarying,默认 5/8/17/20 时,lib/client.js:10419-10423) - 按需懒加载:只提取当前时段素材(单槽峰值几十 MB),切换时段时才读,避免一次导入全部时段导致 OOM
- 手动锁定时段:时段按钮只在容器里真的有该时段素材时出现(
lib/client.js:12797-12813),键名timeOverride;点「自动」恢复随时间切换 - 不串台:切换壁纸时清空上一张的时段缓存
🌊 整屏虚化(磨砂)体系
- 统一虚化:一条滑条控制整屏壁纸模糊度 + 侧边栏/标题栏白雾厚度;聊天区是否跟随、新会话按钮是否跟随各自独立
- 界面虚化(各自独立开关 + 程度):对话框(通用居中窗口 + 聊天输入框)、设置面板、下载/确认弹窗、弹层(菜单/下拉/提示)、遮罩(全屏背景)、左侧边栏磨砂
- 透出壁纸:左侧边栏 / 标题栏 / 右侧边栏 dock 各自独立,标题栏磨砂可单独指定半径
🎨 主题色与玻璃外观(Aqua 实验默认全关)
- 主题颜色(
themeColor):取色盘 + 预置,驱动侧栏/标题栏/新会话按钮/设置弹窗底色;**配色(accent)**驱动品牌交互色(按钮/滑条/选中/链接/发送键) - 面板颜色匹配壁纸(
aquaTint):自动采样壁纸主色(视频/GIF 每 2 秒刷新);统一雾(全屏色调雾罩)、自适应文字色 + 蓝色清理、深底文字可读增强、任务列表磨砂 - 液态玻璃(CSS/SVG 版):
lgCss+ 折射强度,作用于输入框/左侧边栏/标题栏;lib/liquid-glass/的 WebGL 运行时不参与生成(见文件结构)
🧩 dsh-better-sidebar 适配(检测到该插件后显示)
- 已安装时「其他」tab 出现适配分类:总开关
bsCompat(默认开)+bsFloat(悬浮双层修复:14px 圆角外壳 + 内层透明 + 零外边距 + resize strip 挪进面板)/bsFont/bsReveal+bsRevealAlpha/bsAqua - 宿主
/ping返回{ok, version, betterSidebar, betterSidebarVersion};客户端写body[data-mpw-bs-version],版本专属规则用[data-mpw-bs-version^="…"]门控(lib/index.js:1626-1643、lib/client.js:255-269) - 详见
docs/BETTER-SIDEBAR-COMPAT.md、docs/BETTER-SIDEBAR-DOM-CONTRACT-0.19.1.md,回归node tools/better-sidebar-compat-test.mjs
⏯️ 播放控制与省电
- 视频/网页壁纸可暂停/播放(设置页「壁纸设置」下的按钮),暂停状态实时反映视频实际状态;调整无关设置不会触发重播(
video.src判等已修) - 省电三档:页面隐藏/切页暂停、窗口失焦暂停、电池供电暂停(
getBattery缺失则静默跳过);任一档触发即暂停,全部恢复才继续;与手动暂停共用一套门控
🚀 大文件混合模式(hybrid,默认开)
- mpkg 流式上传到 DSH 宿主 → 磁盘存储 → HTTP Range 流式播放(
lib/index.js:1688-1728、:1730-1790);>600MB 也能放,因为流不进内存;关掉则回纯浏览器模式(600MB 上限)
🖼️ 本地壁纸库与轮换
- Steam 自动发现 + 自定义目录(跨平台目录选择器);WE 原生播放列表(
config.json的general.playlists)导入为轮换列表 - 上一个/下一个一键切换、定时自动轮换(
rotate+rotateMin,1–120 分钟);列表勾选后滚动不跳顶
🛡️ 安全与共存
- 冲突检测:检测到其他壁纸/主题插件时自动关闭本功能(可手动强开,写
forceEnabled) .exe/application壁纸完全排除(lib/web-wallpaper.js:101、:199);自定义目录只读媒体文件;宿主路由有路径穿越校验;网页壁纸 iframe 沙箱隔离
💾 备份与恢复 / 设置持久化
- 「其他」tab 的备份与恢复导出外观类设置为可分享 JSON(
BACKUP_FIELDS,lib/client.js:11979-11993),导入即还原 - 设置除浏览器
localStorage(键dsh.mpkg-wallpaper.v2,lib/client.js:48)外另存宿主端~/.dsh-mpkg-wallpaper/settings.json,换端口/清浏览器数据不丢
支持的壁纸类型与边界
这节回答「我手上的素材能不能用、能用到什么程度」;表后的边界清单说明为什么有些事做不到。
| 类型 | 表现 | 能控制什么 / 做不到什么 |
|---|---|---|
| mpkg(视频类) | ✅ 完整 | 内嵌 mp4/视频纹理直接播放;静音、倍速、暂停、模糊/缩放/亮度全可调 |
| mpkg(场景类) | 🟡 折中 | 容器素材提取:静态帧 / 图层合成 / 内嵌视频时段;Live2D 木偶、shader、脚本做不到(见下) |
| 时间变化壁纸 | ✅ 多时段 | 自动切换 + 手动锁定;只提取当前时段 |
| 视频(mp4/webm/mov/m4v) | ✅ 完整 | 直接播放;解码帧率上限/分辨率上限需 ffmpeg 转码 |
| 网页(HTML) | 🟡 实验性 | 沙箱 iframe + WE API shim;只读设置项的 Live2D 类可改;外网 SDK / 重交互类未适配 |
| scene.pkg 原始目录 | 🟡 折中 | 同 mpkg 场景类 |
| preview.gif / 图片 / 动图 | ✅ 完整 | 场景壁纸无更多素材时回退作者预览图(lib/client.js:887、:12272) |
| Application(exe) | ❌ 排除 | 内容判定即 unknown/excluded-application,绝不读取/执行(lib/web-wallpaper.js:199) |
| 自定义目录(混合) | ✅ 完整 | mpkg 与 workshop 子目录混放;深度 ≤4、条数 ≤4000 的有界扫描(lib/web-wallpaper.js:213-232) |
明确的边界(都不是"以后再说",是当前实现的事实):
- 场景壁纸的完整动态还原做不到——MDL 木偶骨架无公开格式文档、shader/脚本无 Web 端运行时(见场景适配)
- 纯 Scene 渲染方式选择器目前未接线:「其他」tab 的
sceneRender(webgl/static/elysia)有按钮、有写入,但全仓没有读取点;实际路径由渲染器可用性决定(在线走:8899iframe,离线回退静态帧,lib/client.js:3133-3138) - 网页壁纸的 CSS
:hover/:active、isTrusted:true、帧内contextmenu、指针锁定/全屏/下载弹窗做不到(合成事件的固有边界,docs/WEB-WALLPAPER.md§11.4) - 超过 600MB 的素材只在 hybrid 模式下可用;纯浏览器模式另有 250MB(视频纹理)/200MB(图片)/100MB(本地图片文件)上限
设置项总表(7 个 tab)
这是全部设置项的权威表:每行 = 面板文案 + 内部键名 + 默认值 + 作用 + 关闭/回退。tab 顺序与面板一致,固定为 TAB_ORDER = ["source","wallpaper","appearance","unify","blur","other","liquid"](lib/client.js:10730),界面文案:背景来源 / 壁纸设置 / 外观 / 界面统一 / 界面虚化 / 其他 / 测试项。
1. 背景来源(source)
| 面板文案 | 内部键 | 默认 | 作用 | 关闭 / 回退 |
|---|---|---|---|---|
| 启用壁纸引擎背景功能 | enabled | 开 | 总开关;关闭即不应用任何背景 | 关 |
| 上传到 dsh 进程流式播放 | hybrid | 开 | 大文件混合模式(上传宿主 → 磁盘 → Range 播放,无 600MB 上限) | 关 = 纯浏览器模式 |
| mpkg 文件 / 图片 / 视频 / 图片链接 | — | — | 文件选择与 URL 输入(http(s) 或 data:image) | 「清除壁纸」按钮 |
| 自定义目录 | customDirPath | 空 | 任意目录;可指 workshop 主目录,每个子文件夹识别为一张壁纸 | 清空输入 |
| 本地壁纸库(Steam 扫描) | — | — | 扫描 WE 安装与创意工坊,导入壁纸与 config.json 播放列表 | 重新扫描覆盖 |
| 轮换(定时自动切换) | rotate / rotateMin | 关 / 5 分钟 | 到点切换下一个壁纸(1–120 分钟) | 关 |
| 时段 | timeOverride | 自动 | 手动锁定清晨/白天/黄昏/夜晚;按钮只列容器里真实存在的时段 | 点「自动」 |
| 当前壁纸卡片 | — | — | 预览图、显示名、容器内文件名、类型;暂停/播放、刷新、清除 | — |
2. 壁纸设置(wallpaper)
含「壁纸画面」与「省电」两个子分组。
| 面板文案 | 内部键 | 默认 | 作用 | 关闭 / 回退 |
|---|---|---|---|---|
| 静音(网页壁纸) | mute | 开 | 网页壁纸音频;关 = 放壁纸声音 | 关 |
| Now playing(左侧栏「设置」上方) | npNowPlaying | 开 | 左侧栏挂可展开播放器(传输行 = 壁纸声音控制);关掉仍是零注入;同一位置被别的插件占用时自动让位(data-mpw-np-yield) | 关 / 恢复默认 |
| 播放/暂停同时控制壁纸 | npLinkWallpaper | 开 | Now playing 的播放/暂停与进度同时驱动壁纸自身;关 = 只驱动本插件播放器(壁纸媒体是唯一声源时控件如实 disabled) | 关 |
| Web 帧模式(网页壁纸) | webFrameMode | auto | 网页壁纸 iframe 的三档:auto = 隔离沙箱,被浏览器策略挡住 / shim 没报到时只在沙箱内降档(去掉 shim 标记重载,仍是不透明源),不会自动升同源(默认);sandbox = 强制隔离,不自动降档(原因写进状态,可查);compat = 兼容档(同源 + 不带 shim 标记,只有用户显式选它才到得了)。判定表只有一份(lib/web-wallpaper.js),状态见 window.__mpwWebFrame 与 #mpw-bgWrap[data-mpw-webframe-mode|-reason|-attr|-fallback|-autocompat|-degraded],台账 window.__mpwWebFrameGuard(详见 docs/WEB-WALLPAPER.md §3.0) | 选 auto;也可用 ?webframe=auto|sandbox|compat 临时覆盖(不改设置) |
| 自动降级到兼容档(高风险) | webFrameAutoCompat | 关 | 风险回退口:打开后 auto 档才允许在"被策略挡住"时自动降 compat —— 那意味着这张第三方壁纸的脚本与 DSH 同源(可读宿主界面/本地存储、可带 cookie 打插件路由)。关着时只记账 + 面板提示手动切。判据 tools/web-frame-origin-guard-test.mjs(详见 docs/SECURITY-ROUTES.md F5) | 关 |
| 渲染器上游白名单 | sceneUrlWhitelist | 空 | 跨源回退口:sceneRendererUrl/sceneExtUrl 默认只允许 http(s) 回环(127.0.0.1/localhost/::1)与"和页面同主机的字面 IP";跨源上游必须把它的 origin 填在这里(逗号/空格分隔)才会被使用,否则一律拒绝并回落 127.0.0.1:8902(记账 + 日志,不静默)。⚠ 登记进来的上游会连同场景令牌 st 一起放行(详见 docs/SECURITY-ROUTES.md F6) | 清空 = 只允许回环 |
| 水平翻转(镜像) | flipX | 关 | 壁纸左右镜像 | 关 |
| 垂直翻转(镜像) | flipY | 关 | 壁纸上下镜像 | 关 |
| 解码帧率上限 | fpsCap | 无限制 | 源帧率超限时宿主 ffmpeg 抽帧转码(24/30/48/60) | 选「无限制」 |
| 分辨率上限 | resMax | 原始分辨率 | ffmpeg 缩放(720p/1080p/2K,保持宽高比) | 选「原始分辨率」 |
| 视频倍速 | playbackRate | 1x | 0.5–2x(档位 0.5/0.75/1/1.25/1.5/2) | 1x |
| ffmpeg 状态 | — | — | 显示系统/缓存/环境变量来源;未装可下载,缓存装的可卸载(不动系统) | — |
| 可调参数(折叠区) | propEdits | 空 | 可改且改完即生效:mpkg 场景壁纸走 P-203 跨源属性通道(mpw-user-props,渲染器回执确认;见 docs/WE-USER-PROPS.md §3);网页壁纸走 shim 同源通道(分辨率/语言/音量等,见下) | 壁纸级重置 |
| 磨砂模糊 | blur | 12px | 壁纸层模糊(0–40) | 0 |
| 镜头缩放 | zoom | 100% | 10–2000% | 100% |
| 画面亮度 | brightness | 100% | 50–150% 滤镜 | 100% |
| 镜头位置(平移) | lensX / lensY | 0 / 0 | 水平/垂直平移,各自 ±2000 | 0 |
| 省电·页面隐藏/切页暂停 | powPauseHidden | 关 | visibilitychange | 关 |
| 省电·失焦暂停 | powPauseBlur | 关 | blur/focus | 关 |
| 省电·电池供电暂停 | powPauseBattery | 关 | getBattery;API 缺失静默跳过 | 关 |
3. 外观(appearance)
含「透出壁纸」子分组。
| 面板文案 | 内部键 | 默认 | 作用 | 关闭 / 回退 |
|---|---|---|---|---|
| 悬浮效果 | float | 关 | 左侧边栏/标题栏变悬浮卡片(圆角+阴影+透出) | 关 |
| 主题颜色 | themeColor | 空 | 侧栏/标题栏/新会话/设置弹窗底色 tint(取色盘 + 预置) | 空 = 不启用 |
| 面板颜色匹配壁纸 | aquaTint | 关 | 自动采样壁纸主色作面板底色(视频/GIF 每 2s 刷新) | 关 = 用取色盘 |
| 配色 | accent | 空 | 品牌交互色(按钮/滑条/选中/链接/发送键) | 空 = DSH 默认 |
| 遮罩自定义色 | aquaColor | 空 | 统一雾/面板的自定义色 | 空 = 灰色 |
| 自定义灰字颜色 | fontColorGray | 关 | 灰字走自定义色(配 fontColorGrayColor) | 关 |
| 左侧边栏透出壁纸 | sidebar | 开 | 关 = 侧栏纯色不透明 | 关 |
| 左侧边栏磨砂 | sidebarBlur | 关 | 侧栏自身 backdrop-filter;弹窗打开时自动摘除 | 关(需先开侧栏透出) |
| 左侧边栏磨砂程度 | sidebarBlurAmount | 14px | 0–40;统一虚化开启时被接管 | — |
| 标题栏透出壁纸 | headerBg | 开 | 关 = 标题栏纯白 | 关 |
| 标题栏磨砂 | headerBlur | 开 | 统一虚化开启时被接管 | 关 |
| 标题栏磨砂程度 | headerBlurAmount | 0% | 白雾厚度 0–100%(默认 0 = 透明) | 0 |
| 单独调节标题栏磨砂 | headerFrostOwn | 关 | 开 = 用 headerFrostAmount 覆盖磨砂半径 | 关 |
| 标题栏磨砂强度 | headerFrostAmount | 30px | 0–60 | 0 |
4. 界面统一(unify)
| 面板文案 | 内部键 | 默认 | 作用 | 关闭 / 回退 |
|---|---|---|---|---|
| 统一虚化 | unifyTint | 开 | 整屏模糊感由一个条控制;开启后接管侧边栏/标题栏/右栏磨砂 | 关 |
| 整屏虚化程度 | unifyAmount | 30px | 0–40(控制壁纸层 blur) | — |
| 界面透明度 | sidebarAlpha | 65% | 0% = 完全不透明(正常界面)、100% = 完全透明(看到壁纸);同时驱动左栏/标题栏/右栏·dock;与模糊互不影响 | — |
| 聊天区跟随整屏虚化 | chatFollow | 开 | 关 = 聊天区由「磨砂模糊」条控制 | 关 |
| 新会话按钮跟随面板不透明度 | sessionFollow | 开 | 关 = 回到宿主原色 | 关 |
| 统一雾(全屏遮罩) | aquaMask | 关 | 所有表面共享一种雾色(原 Aqua 实验项) | 关 |
| 统一雾强度 | aquaMaskAlpha | 82% | 0–100% | — |
两个条的语义(2026-10-02 起口径固定,判据
tools/fog-model-test.mjs): 「整屏虚化程度」= 模糊半径(0 = 完全不虚化); 「界面透明度」= 整个界面外壳的透明程度(0% = 完全不透明(正常界面,用宿主自己的表面色)、100% = 完全透明(看到壁纸))—— 它与模糊互不影响:模糊 0 时照样按它透出,只是背后壁纸是清晰的。 另外:透明度 = 0 时插件完全不覆盖宿主(不写背景/不写模糊/不动宿主 token)。 两者对整个界面外壳生效(左栏/标题栏/右栏/dock 共用同一套表面 token)。
5. 界面虚化(blur)
| 面板文案 | 内部键 | 默认 | 程度键 / 默认 | 关 |
|---|---|---|---|---|
| 跟随统一虚化 | blurFollowUnify | 开 | 开 = 被接管的项(左栏磨砂/标题栏磨砂/右侧边栏·dock)与统一值一致;其中任一项你自己调过之后就独立;关 = 全部独立;重新打开 = 清空独立标记 | — |
| 虚化对话框 | dialogBlur | 开 | dialogAmount 14px | 关 |
| 虚化设置面板 | settingsBlur | 开 | settingsAmount 14px | 关 |
| 虚化下载/确认弹窗 | confirmBlur | 开 | confirmAmount 12px | 关 |
| 虚化弹层 | popoverBlur | 开 | popoverAmount 10px;另有 popoverAlpha 94% 表面不透明度 | 关 |
| 虚化遮罩(全屏背景) | maskBlur | 开 | maskAmount 8px | 关 |
| 右侧边栏/dock 虚化 | rightSidebarBlur | 开 | rightSidebarBlurAmount 14px + rightSidebarAlpha 45%;跟随统一虚化时两项都被接管 | 关 |
6. 其他(other)
| 面板文案 | 内部键 | 默认 | 作用 | 关闭 / 回退 |
|---|---|---|---|---|
| 轻度锐化 | sharp | 开 | 提升低清 GIF 观感;卡顿请关 | 关 |
| Deep diving 背景方框 | thinkBg | 关 | 开 = 思考状态显示模糊背景方框 | 关 |
| 任务列表磨砂 | todoBlur | 关 | todo 卡片背景模糊 | 关 |
| 第三方 UI 圆角兼容 | roundCompat |