AstrBot调色盘

AstrBot调色盘是一个 AstrBot WebUI 美化插件。当前版本聚焦于背景图库、透明界面、Liquid Glass 设置页、文字可读性增强和壁纸主题色联动，让 Dashboard 可以在不修改 AstrBot 源码的前提下换上自定义壁纸。

当前已兼容 AstrBot 4.28.0-beta.1。

当前版本：0.4.16

兼容 AstrBot：>=4.26.0-beta1，已兼容 4.28.0-beta.1

功能

• 分别上传横屏和竖屏 WebUI 背景图片，并通过真实压缩缩略图库一键切换。
• 支持横屏/竖屏设备自动使用对应壁纸，旋转或拖拽改变方向时会叠化切换。
• 支持打开或刷新 WebUI 时从当前方向图库随机切换背景。
• 支持按自定义间隔（1～1440 分钟）定时随机轮换背景，不会连续重复当前图，页面隐藏时自动暂停。
• 调整背景填充方式、位置、遮罩、模糊、灰度、亮度、对比度和饱和度。
• 将 Dashboard 常驻面板透明化，支持完全透明的悬浮文字效果。
• 主要信息框、组件管理页面和侧栏当前选中项支持统一调节毛玻璃强度；设为 0 时关闭新增玻璃装饰，信息框和组件管理表面恢复透明，侧栏仍保留原有选中底色。
• 窄屏浮层侧栏支持独立的毛玻璃强度 mobile_sidebar_glass（默认 18，范围 0–40 px），避免手机或窄窗口下透明侧栏与正文重叠；设为 0 时恢复透明，与界面毛玻璃 stats_card_blur 互不影响。
• 提供文字和图标可读性增强，包括柔和阴影和强力描边。
• 自动读取当前壁纸主题色，并同步 AstrBot 主色与辅色。
• 提供 Apple-like Liquid Glass 风格的分标签插件设置页，可在插件详情页中直接配置。
• 设置页所有标签都带有效果预览，并叠加示例 UI，方便直观看到遮罩、滤镜、界面底色和文字增强效果。
• 可选在 AstrBot 系统统计页追加模型 Token 明细，查看每个模型的输入、输出、缓存命中和命中率。
• 透明化 AstrBot 顶栏、选项卡、插件说明、安装窗口、更新日志、WebChat 等常见深色背景区域。
• 首次注入后自动推荐切换到 AstrBot 深色主题，用户仍可在 AstrBot 设置中改回其他主题。

插件根目录提供符合 AstrBot 插件规范的 logo.png（1:1、256x256 PNG），安装后会自动显示在插件市场和插件列表中。

效果展示

安装

进入 AstrBot 插件目录：

cd /path/to/AstrBot/data/plugins
git clone https://github.com/Sisyphbaous-DT-Project/astrbot_plugin_palette.git

然后在 AstrBot WebUI 中重载插件，或重启 AstrBot。

插件加载后，AstrBot 插件列表中应显示：

• 插件名：astrbot_plugin_palette
• 展示名：AstrBot调色盘
• 版本：0.4.16

使用

1. 打开 AstrBot WebUI。
2. 进入插件管理，找到 AstrBot调色盘。
3. 打开插件设置页。
4. 分别在横屏图库或竖屏图库上传一张或多张背景图片。
5. 在对应缩略图库中点击图片，切换该方向的当前 WebUI 背景。
6. 按喜好调整透明度、遮罩、背景滤镜、文字增强、随机背景、定时轮换和主题色联动。
7. 保存后刷新 WebUI，背景会自动应用到 Dashboard。

支持的背景图片格式：

• jpg
• jpeg
• png
• webp
• gif

单张图片最大 10MB。

配置项

配置项	说明	默认值
enabled	是否启用 WebUI 美化	true
background_image	当前背景图片文件名	""
background_images	背景图库文件名列表	[]
landscape_background_image	横屏当前背景图片文件名	""
landscape_background_images	横屏背景图库文件名列表	[]
portrait_background_image	竖屏当前背景图片文件名	""
portrait_background_images	竖屏背景图库文件名列表	[]
background_fit	背景填充方式，可选 cover、contain、stretch、auto	cover
background_position	背景位置	center center
background_blur	背景模糊强度，单位 px	0
background_dim	全局暗色遮罩强度	0.5
surface_opacity	常驻面板底色强度，0 为透明	0.0
stats_card_blur	主要信息框、组件管理页面和侧栏当前选中项的毛玻璃强度，范围 0–40 px；0 表示关闭新增的模糊与玻璃装饰，让信息框和组件管理表面恢复透明，同时保留侧栏原有选中底色	14
mobile_sidebar_glass	窄屏浮层侧栏的毛玻璃强度，范围 0–40 px，作用于手机或窄窗口下的主侧栏和聊天页侧栏；0 表示关闭侧栏的底色、模糊和阴影并恢复透明，独立于 stats_card_blur	18
text_enhancement_mode	文字增强模式，可选 off、soft_shadow、stroke	soft_shadow
text_enhancement_strength	文字增强强度	1.0
background_grayscale	背景灰度	0.0
background_brightness	背景亮度	1.0
background_contrast	背景对比度	1.0
background_saturation	背景饱和度	1.0
random_background_on_load	打开或刷新 WebUI 时随机背景	false
background_rotation_enabled	是否按间隔定时随机轮换背景	false
background_rotation_interval_minutes	定时轮换间隔，单位分钟，范围 1–1440	30
auto_theme_enabled	是否自动同步壁纸主题色	true
detailed_token_stats_enabled	是否在系统统计页显示模型 Token 明细	false
theme_primary	自动生成的 AstrBot 主色，格式为 #RRGGBB	""
theme_secondary	自动生成的 AstrBot 辅色，格式为 #RRGGBB	""
advanced_css	追加到主题 CSS 末尾的高级自定义 CSS	""

主题色联动

0.3.0 会在当前壁纸切换后读取图片主题色，生成一组适合 UI 使用的主色和辅色。主题色联动开启时，插件会把这两个颜色写入 AstrBot 已有的浏览器本地配置：

themePrimary
themeSecondary

同时，插件会注入一小段运行时样式，让按钮、强调色和部分 Vuetify 主题变量无需刷新也能马上跟随壁纸变化。

关闭“主题色联动”或禁用调色盘时，插件会恢复启用联动前保存的 AstrBot 主色和辅色。没有上传壁纸时，主题色联动不会主动改色。

如果更换了图片但想手动重新读取颜色，可以在设置页点击“重新读取壁纸主题色”。

背景图库

上传图片会加入对应方向图库；如果该方向还没有当前背景，第一张上传图片会自动作为当前方向背景。已有当前背景时，上传不会打断正在使用的壁纸。点击缩略图后，插件会把该图片保存为对应方向的当前背景，并重新读取主题色。

0.4.4 起，背景图库分为横屏壁纸和竖屏壁纸。上传到横屏分区的图片会在电脑或横屏视口优先显示；上传到竖屏分区的图片会在手机或竖屏视口优先显示。插件不会按图片尺寸自动分类，图片属于哪个方向完全由上传入口决定。

旧版单图库配置会默认显示在横屏图库里；竖屏图库为空时仍会自动回退到旧背景。删除背景图片会删除这个文件在横屏、竖屏和旧图库里的所有引用，避免配置里留下已经不存在的图片。

AstrBot 4.27.3 及更高版本的插件配置页支持逐项“恢复默认值”。这个操作只会清空配置引用，不会替调色盘删除数据目录中的背景原图和缩略图；如果要彻底清理图片，请优先在调色盘图库中删除，已经恢复默认后留下的文件需要手动清理插件数据目录里的 backgrounds 文件夹。

Dashboard 会监听视口方向变化。浏览器从竖屏切到横屏时，会预加载横屏当前壁纸并以叠化方式切换；横屏切回竖屏时同理。如果某个方向还没有壁纸，会自动回退到旧背景或另一方向壁纸，避免黑屏。

0.4.5 起，方向切换会先等待目标壁纸加载和解码，再用双层背景进行更明显的叠化过渡。如果横屏和竖屏最终回退到同一张图片，视觉上可能不会出现明显变化，这是正常情况。

0.4.1 起，图库缩略图会在上传时或首次访问时生成最大边 320px 的压缩缓存。设置页图库和效果预览只加载小图，不再把原图 base64 当缩略图或预览图使用，因此云端部署和多张 4K 壁纸场景下打开设置页会更轻。Dashboard 实际背景仍使用原图，不影响最终壁纸质量。

开启“打开或刷新时随机背景”后，Dashboard 每次重新打开或整页刷新都会从当前方向图库随机选一张，并写回该方向当前背景。页面内路由切换和横竖屏旋转不会触发再次随机，避免使用过程中频繁换图。

开启“定时轮换”后，Dashboard 会按设定间隔（默认 30 分钟，可设 1～1440 分钟）从当前视口方向的图库随机切换背景，沿用与“打开或刷新时随机”相同的选池和回退顺序，且不会连续选中正在使用的图片；图库只剩当前一张图时会静默跳过。轮换结果会写回全局配置，其他已打开的 WebUI 页面会同步叠化到新壁纸；开启主题色联动时主题色随新壁纸一起更新。页面隐藏（切后台、最小化）时轮换暂停，恢复可见后重新等待一个完整间隔，不会补播错过的次数。

同一浏览器（同源）打开多个 WebUI 标签页时，只有一个标签页负责触发轮换：优先使用 Web Locks 持续持有领导权，不支持时降级为 localStorage 租约（15 秒有效期、定时续租）；其余标签页通过 BroadcastChannel 和 storage 事件同步刷新。不同浏览器、不同域名或端口之间不做协调，各自独立轮换。

“拉伸铺满”会让图片完整铺满窗口且不裁切，但可能改变原图比例。

插件设置页

0.4.0 将设置页重构为分标签布局：

• 图库：上传、切换、删除背景，并设置打开或刷新时随机背景与定时轮换。
• 外观：调整背景填充、位置、遮罩、模糊、界面底色、信息框模糊和基础滤镜。
• 可读性：调整文字增强、灰度、亮度、对比度和饱和度。
• 主题：查看壁纸主题色联动状态，并手动重新读取主题色。
• 高级：追加自定义 CSS。

每个标签都带有当前壁纸效果预览。预览图上会叠加一套小型示例 UI，用来直观看到界面底色、文字阴影、按钮和标签在当前壁纸上的实际可读性。

系统统计增强

0.4.3 起，可以在设置页“高级”标签里开启“系统统计模型 Token 明细”。开启后，调色盘会在 AstrBot 系统统计页的模型调用区域追加一个明细面板，展示总计以及每个模型的输入 token、输出 token、缓存命中 token 和缓存命中率。

该功能只读取 AstrBot 已有的 ProviderStat 统计记录，不改变模型调用、token 采集或 AstrBot 原生统计接口。关闭开关后，增强面板会从 Dashboard 移除。

工作方式

本插件不会修改 AstrBot 源码。

为了让 Dashboard 主页面能加载插件主题，本插件会在运行时向 AstrBot 当前实际服务的 WebUI 入口注入一段带标记的启动脚本。插件会优先跟随 --webui-dir 指定目录；AstrBot 4.27.x 起跟随其公开 resolve_dashboard_dist 的目录选择结果，4.26.x 则沿用旧版辅助函数判断，从而同时覆盖兼容的 data/dist 和内置 astrbot/dashboard/dist。

使用 --webui-dir 时建议传入实际存在的绝对路径，不要依赖 ~ 展开；如果自定义启动器直接通过程序接口传入目录，也应同时保留命令行参数，否则插件无法自动获知该目录。

如果内置 WebUI 目录不可写，插件会复制一份内置 WebUI 到 data/dist 并完成注入，设置页会提示需要重启 AstrBot 后生效。注入前会在插件数据目录中备份原始 index.html，之后重复注入会替换已有标记块，避免重复写入。

注入标记如下：

<!-- astrbot_plugin_palette:start -->
...
<!-- astrbot_plugin_palette:end -->

背景图片保存在插件数据目录下：

data/plugin_data/astrbot_plugin_palette/backgrounds

图库缩略图缓存在：

data/plugin_data/astrbot_plugin_palette/thumbnails

Dashboard 入口备份保存在：

data/plugin_data/astrbot_plugin_palette/dashboard_backups

Web API

插件通过 AstrBot 插件 Web API 暴露接口。实际访问路径由 AstrBot 转发到 /api/v1/plugins/extensions/...。

方法	路径	说明
GET	/astrbot_plugin_palette/status	获取插件版本、路径和注入状态
GET	/astrbot_plugin_palette/config	获取当前公开配置
POST	/astrbot_plugin_palette/config	保存配置
GET	/astrbot_plugin_palette/theme.css	获取运行时主题 CSS
GET	/astrbot_plugin_palette/background-preview	获取当前背景预览
GET	/astrbot_plugin_palette/background-thumbnail	获取图库压缩缩略图
GET	/astrbot_plugin_palette/token-stats	获取模型 Token 明细统计
POST	/astrbot_plugin_palette/upload-background	上传背景图片到图库
POST	/astrbot_plugin_palette/upload-background/<orientation>	上传背景图片到横屏或竖屏图库
POST	/astrbot_plugin_palette/backgrounds/select	切换当前背景图片
POST	/astrbot_plugin_palette/backgrounds/delete	删除图库背景图片
POST	/astrbot_plugin_palette/backgrounds/random-select	随机切换并写回当前背景
POST	/astrbot_plugin_palette/theme-colors/recalculate	重新读取当前壁纸主题色
GET	/astrbot_plugin_palette/backgrounds/<filename>	读取背景图片

深色主题提示

透明背景更适合搭配 AstrBot 深色模式。插件注入脚本第一次运行时，会向浏览器 localStorage 写入：

themeMode=dark
uiTheme=PurpleThemeDark
astrbot_palette_dark_theme_bootstrapped=1

这只执行一次。用户之后在 AstrBot WebUI 中手动改回浅色或跟随系统，插件不会反复覆盖。

安全边界

• 不修改 AstrBot 源码。
• 只写入 AstrBot 当前使用的 WebUI 入口和插件自己的数据目录；内置 WebUI 不可写时才会准备 data/dist 降级副本。
• 高级 CSS 会拦截 @import 和外链 url()，避免引入外部资源。
• 背景文件名会被限制为插件生成的本地文件名，避免路径穿越。
• 上传图片会检查扩展名、大小和文件头。

开发检查

在插件仓库根目录运行：

PYTHONPATH=/path/to/AstrBot python -m py_compile main.py palette/*.py
node --check pages/settings/app.js
node --check pages/settings/liquid-glass.js
python -m json.tool _conf_schema.json
python -m unittest discover -s tests -p "test_*.py"
git diff --check

如果要在本地 AstrBot 中测试，建议复制插件目录到 data/plugins/astrbot_plugin_palette，不要使用软链接或 bind mount。

更新日志

完整更新日志见 CHANGELOG.md。版本化记录保存在 changelogs 目录。

版本计划

0.1.0 已提供背景图上传、运行时注入、透明化和可读性增强。

0.2.0 新增壁纸主题色联动，可以自动读取壁纸颜色并同步 AstrBot 主色与辅色。

0.3.0 新增多背景图库、缩略图切换、刷新随机背景和拉伸铺满。

0.4.0 将插件设置页重构为 Apple-like Liquid Glass 分标签界面，并补齐全标签效果预览、示例 UI、选项卡可读性和顶栏黑线修复。

0.4.1 将图库缩略图改为后端生成并缓存的 320px 小图，优化云端部署和多张 4K 壁纸场景下的设置页加载速度。

0.4.2 修复桌面端和内置 WebUI 部署下的注入路径兼容问题，不再只依赖 data/dist/index.html。

0.4.3 新增系统统计模型 Token 明细增强，可选展示每个模型的输入、输出、缓存命中和缓存命中率。

0.4.4 新增横屏/竖屏两套背景图库，并按视口方向自动选择对应壁纸。

0.4.5 优化横竖屏方向切换的叠化过渡，减少旋转或窗口变化时的硬切感。

0.4.6 确认兼容 AstrBot 4.26.4，核心插件 API、设置页桥接、WebUI 注入路径和统计页增强均保持可用。

0.4.7 确认兼容 AstrBot 4.26.5，核心插件 API、设置页桥接、WebUI 注入路径和系统统计增强均保持可用。

0.4.8 已测试兼容 AstrBot 4.26.6，核心插件 API、设置页桥接、WebUI 注入路径和系统统计增强均保持可用。

0.4.9 为主要信息框增加可配置毛玻璃效果，支持用 stats_card_blur=0 恢复全透明，并已测试兼容 AstrBot 4.26.7。

0.4.10 将毛玻璃效果扩展到组件管理页面和侧栏当前选中项，并修复配置页切换标签时新旧页面短暂同时显示的问题；固定按钮定位保持不变。

0.4.11 修复 AstrBot 4.27.x 下 Dashboard 路径识别问题，跟随 AstrBot 公开解析结果注入实际服务的 WebUI 入口，保留 4.26.x 旧接口兼容，并已确认兼容 AstrBot 4.27.1。

0.4.12 新增定时自动轮换壁纸，支持自定义分钟间隔、页面隐藏暂停、同源多标签页单领导协调和跨标签叠化同步，并为长时间轮换加入有界 object URL 缓存。

0.4.13 按 AstrBot 插件规范新增 logo.png 图标，并同步更新插件市场与 README 展示信息。

0.4.14 完成 AstrBot 4.27.4 兼容性验证，补充运行时验证结果、恢复默认后的壁纸文件清理说明和自定义 Dashboard 路径使用边界，并同步版本文案。

0.4.15 修复窄屏下透明浮层侧栏与主内容文字重叠的问题，新增独立的移动端侧栏毛玻璃强度配置，主侧栏和聊天页侧栏一并适配，并更换插件图标与 README 主视觉图。

0.4.16 适配 AstrBot 4.28.0-beta.1：覆盖配置页滚动工作区、全新会话工作区、平台/提供商工作台和数据页路由合并后的新结构，配置页粘性工具栏改为玻璃条，未保存提示与界面毛玻璃强度联动。

后续版本会继续补齐更多页面的透明化细节，并探索更完整的主题色板推导。

作者

C₂₂H₂₅NO₆