悠丝缇亚主题皮肤JacoboJin/dsh-skin-bd2-yustia

棕色尘埃2 · 悠丝缇亚 — DSH 皮肤插件

License: MIT
DeepSeek Harness

以《棕色尘埃2》(Brown Dust 2) 的圣剑骑士 悠丝缇亚（Justia / ユースティア） 为灵感的 DSH Web GUI 皮肤：昼夜双模式、自定义背景库、全界面毛玻璃化，纯展示层、可热插拔（停止即还原）。

预览

| 浅色 · 象牙白 × 圣金 | 深色 · 深夜暖黑 × 烛光金 |
|---|---|
| 悠丝缇亚皮肤浅色预览 | 悠丝缇亚皮肤深色预览 |

特性

- 昼夜双模式：浅色=暖象牙底+圣金主色（白金圣骑士）；深色=深夜暖黑+烛光金（烛火下的骑士团大厅）
- 自定义背景图：背景库/文件名/绝对路径/https URL 均可，附 50%+ 昼夜自适应帷幕保证文字可读
- 全界面毛玻璃：对话区透图、侧栏半透明+毛玻璃、消息/工具卡玻璃、标题栏与输入区毛玻璃
- 签名装饰：圣光晕、星尘微光、金色滚动条/选中/链接/代码块/金色丝线分割线（浓度可调）
- 设置自动记忆：背景选择与各滑杆写入 settings.json，重新运行插件自动恢复

插件面板使用指南（重要）

皮肤安装运行后，在会话中最新一条 cordis_run 卡片（插件的运行卡片，位于对话流底部）内会出现皮肤控制面板：

| 控件 | 作用 |
|---|---|
| 背景库下拉框 | 列出 backgrounds/ 文件夹中所有 bg- 图片，选中即自动应用 |
| 刷新 | 重新扫描背景库（放入新图片后点此） |
| 输入框 | 手动指定背景：文件名（bg-02）/ 绝对路径 / https:// URL |
| 应用背景 | 应用输入框中的背景 |
| 随机 | 从背景库随机换一张 |
| 默认 | 恢复默认背景（bg-default. 优先，其次 bg-01-holy-light.jpg） |
| 移除 | 移除背景图，回到纯色皮肤 |
| 侧栏透明度（30–100%） | 左侧会话栏透明度；标题栏、胶囊按钮、分组条目、session log 按钮同步联动，越透毛玻璃模糊越强 |
| 帷幕深浅（0–85%） | 背景图上的底色帷幕强度（调节文字可读性的主手段） |
| 装饰浓度（0–100%） | 圣光晕/星尘的浓度，0 即完全关闭 |
| 状态行 | 显示每一步的真实结果（成功文件/错误原因），排障时先看这里 |

说明：旧版本的历史 run 卡片按设计只显示版本信息；交互面板只出现在最新一条 run 卡片上。

已知问题（待修复）

以下位置在深色模式下仍有暗色背景残留，已记录待后续版本修复（截至 2026-08-29，插件版本 v31）：

1. 侧边栏工作区标题行右侧的按钮（选择工作区文件夹等）：按钮存在暗色背景，未随侧栏透明度联动；
2. 顶部状态栏「创造模式」按钮：存在暗色背景；
3. 顶部最右侧「session log」按钮：存在暗色矩形（矩阵状）背景。

排查记录：相关按钮自身 CSS 均为透明背景，暗色疑似来自按钮内的 SVG 图标填充或未枚举到的背景图像/伪元素（自诊断当前仅扫描 backgroundColor/boxShadow/backdropFilter，未覆盖 backgroundImage 与 SVG fill）。后续修复方向：扩展自诊断扫描范围（backgroundImage、SVG fill、outline、伪元素），再据实测值精确重映射。

背景图命名约定

- 文件夹：bd2-yustia-skin/backgrounds/（即本仓库 backgrounds/）
- 命名：bg-.，支持 png/jpg/jpeg/webp/gif/avif/bmp/svg，单文件 ≤ 8 MB
- 命名为 bg-default. 的图片即为默认背景，替换后点「默认」即可生效

一、hsr-kafka 皮肤插件原理（逆向分析）

参考仓库：

一个皮肤 = 一个自包含的 DSH 插件包，由 5 层组成：

| 层 | 文件 | 作用 |
|---|---|---|
| 皮肤清单 | skin.json | 注册表元数据：id、accent、bodyAttr（CSS 作用域属性名）、package、wiring.id（插件行 ID）、预览图路径 |
| 组合补丁 | cordis.patch.yml | 把一个插件行 ui-skin-hsr-kafka insert 进 web 插件 roster（dsh plugin add 时由 bundle 机制消费） |
| 包契约 | package.json | dsh.client.platform: "web"、dsh.bundle.patch 指向补丁、入口 ./client |
| Host 半体 | src/index.ts | 空实现（浏览器专用皮肤不提供宿主行为） |
| Client 半体 | src/client/index.ts | 核心：挂载/回收皮肤表面 |
| 样式主体 | src/client/hsr-kafka.module.css | 全部 CSS 以 body 属性为作用域 |
| 契约测试 | tests/apply.spec.ts | 验证「apply 写入的一切在 dispose 时全部收回」 |

Client 半体的三个动作（全部可逆）

export function apply(ctx: Context): void {
const body = document.body
body.dataset.dshHsrKafka = ''              // ① 挂上皮肤作用域属性
const favicon = document.createElement('link') // ② 专属 favicon
favicon.rel = 'icon'; favicon.href = data:image/svg+xml;...
document.head.append(favicon)
document.title = SKIN_TITLE                // ③ 专属标题
ctx.effect(() => () => {                    // ④ 热插拔契约：dispose 全部收回
delete body.dataset.dshHsrKafka
favicon.remove()
if (document.title === SKIN_TITLE) document.title = originalTitle
})
}

CSS 的昼夜双层作用域

- 浅色令牌挂 body[data-dsh-hsr-kafka]
- 深色令牌挂 body[data-dsh-hsr-kafka][data-ds-dark-theme]（外壳的日夜切换按钮直接生效）
- 重映射全套设计令牌：--dsw-static-deepseek-、--dsw-static-neutral-bluish-、--dsw-alias-button-、--dsw-specific-bubble/sidebar-、--color-、--bg- 等
- 签名纹理与动效：body::before/::after 蛛网/星尘图案 + @keyframes（web-sway、btn-sheen 等），作用域隔离不污染其他皮肤

要点：皮肤=纯展示插件（无 Service/Event/模型流量）；所有写入必须通过 ctx.effect 登记回收器，保证热插拔不残留。

二、本会话运行时的适配

本会话的动态 Cordis 插件运行时与 npm 皮肤包不同：

1. 无 document/window 内建符号 → 不能写 body 属性、favicon、标题，改为使用运行时原生能力：
- theme.overrideTokens(source, tokens)：在活动主题上叠加一层 { light, dark } 令牌对（本会话外壳正是消费 --dsw-alias- / --dsw-specific- 令牌的 DSW 体系，与 dsh-themes 同源），昼夜切换由主题系统负责，返回 disposer；
- styles.insert(css)：包私有样式表注入，随 Client run 自动清理。
2. 不写死产品 DOM 选择器 → 装饰 CSS 只用 body、伪元素与通用内容元素（a/code/pre/blockquote/hr、::selection、滚动条），颜色一律 var(--dsw-alias-) 引用令牌，昼夜自动跟随。
3. 可撤销性：令牌层经 ctx.effect 登记、样式表由 styles.insert 管理，插件停止后全部收回。

对应关系：

| hsr-kafka (npm 包) | 本插件 (动态 Cordis) |
|---|---|
| CSS 模块重映射 --dsw- | theme.overrideTokens('bd2-yustia', { light, dark }) |
| 签名纹理 CSS（body 属性作用域） | styles.insert(...)（var() 令牌驱动，无需属性） |
| favicon / title | 不可用（无 document 内建符号），省略 |
| ctx.effect 回收 | ctx.effect(() => overrideTokens(...)) + styles.insert 自动回收 |

三、调色板依据

悠丝缇亚（Justia）视觉参考：GameKee 神圣悠丝缇亚、Gameline 角色页。对官方立绘采样得到的核心色：

- 象牙白 #F0F0F0（礼服主体）
- 圣金/古铜 #D8C048、#786030（金发、金饰与铠甲包边）
- 淡粉腮红 #F0D8D8
- 深炭 #303030（深色部件/描边）

由此设计：浅色=象牙白+圣金 #b0871f，深色=暖黑+烛光金 #d8b25c。

五、自定义背景图（动态插件 v5 能力）

背景库文件夹（推荐用法）

位置：D:\dsh_ai_workspace\bd2-yustia-skin\backgrounds\

命名格式：bg-.，例如：

- bg-01-holy-light.jpg（已内置示例）
- bg-02.jpg、bg-星夜.png、bg-forest.webp …

支持扩展名：png / jpg / jpeg / webp / gif / avif / bmp / svg（单文件 ≤ 8 MB）。

使用方式：把图片按上述格式放入文件夹 → 在 Run 卡片皮肤面板点「刷新」→ 下拉选择即自动应用（无需重载插件）。也可直接在输入框里填文件名（bg-02 或 bg-02.jpg，会自动匹配）。

其他输入方式

| 输入 | 行为 |
|---|---|
| 背景库文件名（bg-02 / bg-02.jpg） | 自动解析到 backgrounds/ 文件夹（Host bg-list 匹配） |
| 本地绝对路径或相对工作区路径 | Host fs.readBytes → base64 data URI（上限 8 MB） |
| https://… URL | 浏览器直连 CSS url()（背景图不受 CORS 限制；防盗链/CSP 拦截时请改用本地路径） |
| 「默认」按钮 | 恢复 assets/default-bg.jpg 圣光背景（挂载时自动应用） |
| 「移除」按钮 | 移除背景图，回到纯色皮肤 |
| 侧栏透明度滑杆 | 30%–100%：左侧会话栏按百分比半透明透出背景图（浅色略高于深色，保证可读性） |

- 背景 CSS 自带一层 50% 底色帷幕（color-mix(var(--dsw-alias-bg-base))，昼夜自适应），保证文字可读；
- 启用背景时会同时把外壳 AppFrame 的不透明背景置透明（body [class='_frame']），否则图片会被外壳容器完全遮挡；装饰层以高 z-index 浮于内容之上；
- 切换背景会先 dispose 上一张的样式表，停止插件时全部回收；
- ⚠️ 已知坑：动态插件宿主上下文里 sandboxPolicy.workspaceRoot 指向 DSH 宿主进程目录（本机为 C:\Windows\System32），不是会话工作区。Host 半体（host.js）因此使用固定会话工作区路径（D:/dsh_ai_workspace）；迁移机器/工作区时改这一处即可；
- 换默认图：把图片命名为 bg-default.* 放入 backgrounds/，或直接替换 assets/default-bg.jpg（16:9，≤ 8 MB）。

说明：静态皮肤包形态（lib/）保持基础皮肤能力；背景图交互依赖动态运行时的 harness RPC，仅动态插件提供。

六、交付物与用法

bd2-yustia-skin/
├── skin.json            # 皮肤清单（对齐 dsh-themes 格式，含 preview 路径）
├── client.js            # 动态运行时版 Client 半体源码（皮肤 + 背景图控制）
├── host.js              # 动态运行时版 Host 半体源码（背景文件读取 RPC）
├── yustia.module.css    # 签名装饰 CSS（独立文件版）
├── lib/index.js         # 静态包 Host 半体（空实现，已预构建）
├── lib/client.js        # 静态包 Client 半体（document 形态，基础皮肤能力）
├── assets/default-bg.jpg# 默认圣光背景图（16:9，可替换）
├── backgrounds/         # ★ 自定义背景库：bg-.，放入即用
│   └── bg-01-holy-light.jpg  # 示例背景
├── preview/light.png    # 浅色预览（脚本生成）
├── preview/dark.png     # 深色预览（脚本生成）
├── cordis.patch.yml     # 静态包组合补丁
├── package.json         # 静态包契约（dsh.client.platform: "web"）
├── LICENSE              # MIT 许可证
└── README.md            # 本文件

本皮肤已作为动态 Cordis 插件挂载进当前会话：插件运行时页面即生效，停止插件即恢复原主题。
运行时额外在 cordis_run 卡片内注册了皮肤信息面板（浅/深调色板一览，注册于 tool.view.cordis Slot、key self，随插件停止自动移除）。
静态皮肤包（lib/ 预构建 + cordis.patch.yml + package.json）也已就绪，可用 dsh-themes 同款命令安装：
dsh plugin --profile  add ./bd2-yustia-skin。