dsh-theme-mediascape

dsh plugin --profile web add dsh-theme-mediascape

dsh-theme-mediascape

媒体景观主题 —— DeepSeek Harness（DSH）Web UI 主题插件：立绘/视频壁纸 × 基底配色 × 开屏动画 × 氛围粒子 × 背景音乐 × 打字音效。

界面预览：theme-studio/ 独立预览环境（真实前后端，见「theme-studio/ 预览环境」）

• [功能总览](#功能总览)
• [一、壁纸系统](#一壁纸系统)
• [二、基底配色](#二基底配色)
• [三、开屏动画](#三开屏动画)
• [四、氛围粒子与字号调节](#四氛围粒子与字号调节)
• [五、背景音乐](#五背景音乐)
• [六、打字音效](#六打字音效)
• [七、界面操作（dock 工具条）](#七界面操作dock-工具条)
• [八、在线资源与自定义素材](#八在线资源与自定义素材)
• [目录结构](#目录结构)
• [媒体加载与鉴权代理](#媒体加载与鉴权代理视频开屏加载不出来时看这里)
• [安装与要求](#安装与要求)
• [theme-studio/ 预览环境](#theme-studio-预览环境)
• [配色盘独立分发调研](#配色盘独立分发调研设计前置考量保持内置的理由)
• [演进总结（提交消息归纳）](#演进总结提交消息归纳)
• [版本记录](#版本记录)
• [注意事项](#注意事项)

功能总览

功能块 · 做什么 · 入口

mht 快照还原预览 · preview.html 直接解析 DSH 界面 .mht 快照还原为静态预览（聊天框+侧边栏+壁纸背景+dock），叠加假数据（操作日志→模拟用户消息、任务列表「预览页加载」自动完成、工作区一个文件夹一个会话）、侧边栏收起按 DSH 真实行为（会话列表 DOM 移除）、操作日志/顶部提示默认隐藏+「日志」开关 · theme-studio/preview.html

宿主元素配色 · 胶囊配方外置 JSON（选择器/背景源/透明度/圆角/padding）+ 层级注入（按 parent 拓扑排序：父先子后、子级自然覆盖父级）+ 品牌区 sidebar-brand 独立键（lPcGpa_brand 背景+文字一体），取色器胶囊 tab 可编辑保存并自动 build · theme-studio/capsules.json

启动播放策略 · 视频壁纸/背景音乐启动时是否自动播放独立配置 · theme-studio/playback.json

开屏动画 · 启动页 gif/图片/视频多画面轮换 + 渐显式无黑屏窗口（浮层立即盖界面，等待期氛围粒子+呼吸光圈、媒体首帧就绪后渐变淡入）+ 可配置标题副标题 + 视频 Range 流式 + HTTP 缓存（ETag+If-Range 重播省 80% 流量）；file:"auto" 时开屏即当前视频壁纸（与壁纸层同一份流，播完移交、不重复加载） · boot/boot.json 配置

字号调节 · 会话区与状态文字四档缩放（小/标准/大/特大），点击「字」循环切换、按钮不显示大小（大小自行感知） · dock「字」按钮

壁纸系统 · 图片/视频壁纸铺底、上传持久化、本地在线共存。背景氛围粒子 · dock「景」按钮

上传体系 · 中途不落盘（上传数据先攒内存缓冲，上限=可用内存 20% 动态，超限转 .tmp 保底）、暂停落盘 .part + 继续从 .part 续传（?offset= 追加续写，取消 DELETE /upload/part 清理快照）、上传前「文件名+大小」去重预检（重复的文件在二级面板提示「已跳过」，不发送请求）、dock「传」统一上传入口（按文件后缀天然识别壁纸/音乐，一次多选统一分发）、上传进度二级面板（多行对齐/进度条/大小/速度 EMA/暂停/继续/取消）、上传开始前与结束后各刷新一次列表（内置在公共函数）、上传完释放连接（串行上传不占满浏览器同源 6 连接） · dock「传」按钮

打字音效 · 输入框打字按键音 + 壁纸音量调节 · dock「声」按钮

背景音乐 · 播放器（旋转唱片/封面/进度条可拖动）、歌单选择/随机、本机添加 · dock「乐」按钮

一、壁纸系统

• 全屏 cover 铺底；中间画面全透明（壁纸区域不铺底色：--dsw-alias-bg-base: transparent、html 深色兜底 #0a0c12、无蒙雾遮罩层；主题色只作用于侧边栏/对话框/按钮等组件）
• 双层结构（图片常驻 + 视频可选覆盖）：图片壁纸一直存在（无类型切换按钮）；「视频：开/关」开关决定是否加载视频，开则视频覆盖在图片之上显示（图片仍在，仅被完全挡住），关则只显示图片。图片层与视频层各自独立记忆当前壁纸
• 选择：弹出缩略图网格（正方形预览、固定三行、可滚动），点卡片直接应用——按视频开关只显示一层：关=图片列表，开=视频列表
• 模式切换（面板「模式」一行）：按钮标题跟随状态——亮=「视频」/ 暗=「图片」（标题实时切换，不再固定显示「视频壁纸」）；dock「景」按钮悬停标题也只显示当前层（视频模式→视频名 / 图片模式→图片名），不再并列两个标题
• 移除：勾选后移除 = 真实删除服务器文件（壁纸/音乐统一同一份删除逻辑：开始前/结束后各刷新一次列表，音乐封面随歌曲一并删除）
• 随机：随机模式走面板模式单按钮（循环/顺序/随机单按钮切换；选择器已去掉随机按钮）——进入随机后按当前层轮换，随机间隔自定义分钟（默认 5 分钟）；随机/顺序作用于最上层（视频开→视频层内切换，视频播完自动切下一张；关→图片层分钟定时切换）；随机池跨层兼容——池在图片模式勾选而当前是视频层（或反之）时自动回退当前层全部，视频播完仍会切换、不会停住
• 切换日志：每次壁纸切换（视频 ended 切下一张 / 图片定时随机 / 手动切壁纸 / 模式切换）自动上报一行到运行态 $DSH_HOME/theme-mediascape/logs/wallpaper.log（GET /theme-mediascape-assets/wallpaper/log?lines=50 可回读最近 N 行，自检/排查切换是否发生用）
• 视频无缝切换预加载（2026-09-29）：顺序/随机模式多视频轮换时，当前视频播放剩余 3s（timeupdate 阈值）即预创建并预缓冲下一视频（隐藏元素、preload=auto、未挂 DOM）；ended 切换时若预载目标命中且已就绪（readyState≥2）直接复用该元素（已缓冲数据，播放即出画面）——切换无加载间隙黑屏；未命中/未就绪照常新建不阻塞；关闭视频层/切换不匹配时自动清理预载（不占用连接）。
• 添加壁纸：dock「传」按钮统一入口（按文件后缀天然识别壁纸/音乐，一次多选统一分发）——上传立即生效并服务器磁盘持久化（$DSH_HOME/theme-mediascape/wallpaper/，刷新/重启/换浏览器都在）——上传视频（mp4/webm，浏览器原生可播）自动开视频层并加载它；上传图片更新图片层（视频开关状态不变）
• 落盘 = 原始文件名（不做 SHA 重命名；同名同大小视为重复复用，同名不同大小自动加 (1)(2)… 后缀）；前端直接显示文件名（去扩展名）
• 中途不落盘：上传数据先攒内存缓冲（上限=可用内存 20% 动态，os.freemem()），超限自动转写 .upload-<traceId>.tmp 保底（超大文件不 OOM）；上传过程中素材目录不出现 .part 中间态，end 后正式文件落定（finalizeUpload 按「文件名+大小」去重)；上传完成落定后自动清理同名孤儿 .part 快照（上次中断/暂停未续传的残留，不留盘）
• 暂停落盘 .part + 继续从 .part 续传：点「⏸」abort 当前请求 → 服务端把已收内存缓冲落盘为 <正式名>.part 暂停快照（内存即刻释放）；点「▶」带 ?offset=<已传字节> 续传 —— 服务端校验 .part 存在且大小一致（不匹配返回 409，前端从头重传，杜绝残缺落盘），对 .part 追加续写，收完 rename 落定，不重传已传部分；「✕」取消 → DELETE /upload/part?name=<文件> 清理快照
• 上传前「文件名+大小」去重预检：重复的文件在二级面板提示「已跳过」（不请求）；去重基准/移除目标只认「真实可用」项（列表 stat 失败的文件已从服务端列表剔除，前端 isItemUsable 只认 file/name + size 数字）
• 上传进度：上传时 dock 二级面板自动弹出（dock.__mediascapeDshCenter 定位靠 dock，点外自动收起）——每任务一行（文件名 + 进度条 + 叠加「已传/总 · 速度」），多任务动态多行且各列对齐，无任务自动隐藏；速度读数 EMA 平滑（progress 事件间隔不均不跳变）
• 开始前/结束后各刷新一次列表（内置在公共上传/移除函数内）：上传前刷新保证去重基准最新，结束后刷新保证新文件即时入列表；移除同理（删除前刷新、删除后刷新）
• 上传完释放连接：串行上传（一次一个请求，不占满浏览器同源 6 连接），每个 XHR 完成即释放引用
• 上传不关闭二级面板：input.click() 打开系统选择器的 click 冒泡不再触发「点外关闭」（捕获阶段 stopPropagation）
• 跨设备即时可见：打开壁纸面板自动刷新列表，其他设备上传的壁纸无需手动刷新网页
• 上传上限：按服务器剩余磁盘空间动态计算（默认单文件最多占剩余空间 80%，底线 512MB），快满自动收紧
• 默认壁纸：首次安装（无历史记录）时展示真实数据目录第一张壁纸（本地/在线均可）
• 面板点右上角「—」或再点「选择」收起；「确定」收起设置面板，设置实时生效并持久化

二、基底配色

• 覆盖 100+ 个 --dsw-* 设计令牌，随主题即时生效；正式基底 = 左侧「应用」写入真源 json 的当前值（以 lib/client-parts/foundation/tokens.js 与取色器为准，文档不写死）
• 单 json 真源 + 预设包（V2 架构，json 化）：应用配色只读一个 json——真源 theme-studio/json/theme-colors.json（label/badge + bg 系层级 bg/bgSoft/bgLayer + colors 全部元素色，每个颜色带不透明度 alpha {hex, alpha}，是唯一写盘目标）；预设包是 theme-studio/json/preset/*.json（只承载颜色集合 + 显示名，不含 bg 系），用于把真源快速改成预设配色；没有预设也能纯手改（左侧输入颜色值）。apply 自始至终只跟真源 json 相关
• 取色器 theme-studio/theme-swatch.html（双 tab：配色 / 胶囊）：配色 tab 顶部 = 背景层级区块（bg→bgSoft→bgLayer 缩进展示，改 bg 系 → dock/面板/胶囊 layer 跟随层联动），左侧 = 当前主题元素 class 控件列表（json 数据驱动，每行 6 列：元素名/类键/色号手输/色块/真实元素样子分片/不透明度滑块，滑块先预览第 5 列、点「应用」才写盘），「重置」还原真源，「应用」真正写入真源 json 并自动 build（POST /api/theme-apply { items:[{key,hex,alpha}] }，原子写真源 → identity.js/tokens.js → build）；右侧 = 预设包（下拉选择 + 逐行显示该预设颜色，「套到左侧全部」全量套 / 每行「应用」= 单项套该预设该键色到左侧，键缺失→无色透明行且不可应用；「存为新预设」POST /api/theme-export；「改名」写回预设 json 的 label，改/导出只作用预设包）。键 = 元素 class：15 键各自唯一（btn-primary/text-primary/gold-glow/status-capsule/sidebar-left/sidebar-brand…），无独立语义键，应用/写回按同名键直取；不透明度滑块读取真源 json 的 alpha 现值（非默认 1），拖滑先预览第 5 列真实元素样子、点「应用」才写盘
• 品牌区单独控制：sidebar-brand 键驱动左侧边栏品牌区（lPcGpa_brand，CSS Modules 尾缀 _brand/_brandName 稳定不随 hash 变）——背景 + 品牌名文字一体（--dsw-specific-sidebar-brand / --dsw-specific-sidebar-brand-text 令牌）；层级注入：sidebar-left（整体，--dsw-specific-sidebar-fill）先注入 → 品牌区后注入，同特异性自然覆盖整体底
• 胶囊层级注入：capsuleCSS() 渲染时按 parent 关系拓扑排序（深度优先、父先子后）——外层胶囊先注入、内层后注入，同特异性选择器后写覆盖先写（子级自然覆盖父级）；同层保持原数组顺序（

…(truncated)