> **语言 / Language：** [English](./README.md) · **简体中文**（当前） · [日本語](./README.ja.md) · [한국어](./README.ko.md)

# xiao-ui-theme-ts

> ✅ **已适配最新桌面版（DSH Desktop，实测 `0.1.7-rc.2`）与 Web 版（实测 `0.1.5-rc.3`）。** 只要 DSH 是 `v0.1.5-alpha.1` 及更新（自带官方右栏的版本）即可；更早的版本请用主题 `0.11.x` —— 见[版本兼容](#版本兼容)。

DeepSeek Harness 的**可自定义主题插件**（默认带一套「魈」青玉风）—— 给 DeepSeek Harness 的
Web 界面做主题：配色、吉祥物徽章、背景、注入语气都能自己调。背景同时支持**静态图片、动态 GIF 与循环视频（MP4/WebM/MOV/M4V）**——上传动画 GIF 会自动识别为动态背景，上传视频也会自动识别并作为全屏循环背景播放。默认是一套魈的青玉/翠青风格，但主色、徽章文字、语气、
背景等都可配置，改出来就是你的专属主题。

## 这是什么

把 DeepSeek Harness 的 Web 界面换上一套可高度自定义的主题视觉。**默认是魈的青玉风**（青玉配色 +
吉祥物徽章 + 魈式语气 + 磨砂背景），但每一样都能改：主色、徽章上的文字、语气开关/语言/内容、
背景图与透明度。也支持在会话里可选注入「魈式语气」——想让助手带魈的口吻就开着，不带就关掉，
且仅改变语气风格，绝不改变回答内容。另有一个**独立的「角色空间」（娱乐）**：一个不挂工作工具（可选联网检索）、可以真正
以角色身份聊天的独立 agent 预设，与工作会话刻意分开——工作会话永远只拿语气，不拿角色身份。

## 示例

<details open>
<summary><b>桌面版（DSH Desktop，最新版适配）</b></summary>

<img width="1279" height="739" alt="魈主题——桌面版适配示例（徽章里可见声音按钮）" src="./resource/screenShortsReadMe/desktopExample.png" />

</details>

<details open>
<summary><b>浅色模式（魈，默认）</b></summary>

<img width="2515" height="1288" alt="魈主题——浅色模式（默认）" src="https://github.com/user-attachments/assets/3998f58b-53db-4349-80f3-3d993c6ad3c3" />

</details>

<details>
<summary><b>深色模式</b></summary>

<img width="1873" height="912" alt="魈主题——深色模式" src="./resource/screenShortsReadMe/xiaoDarkMode.png" />

</details>

<details>
<summary><b>切换其它主题</b></summary>

<img width="1864" height="936" alt="切换到其它主题" src="./resource/screenShortsReadMe/otherThemeSwitch.png" />

</details>

<details>
<summary><b>设置页</b></summary>

<img width="1183" height="871" alt="主题设置页——上半" src="./resource/screenShortsReadMe/settingPageCNUp.png" />

</details>

<details>
<summary><b>设置页（下半）</b></summary>

<img width="1195" height="856" alt="主题设置页——下半" src="./resource/screenShortsReadMe/settingPageCNButtom.png" />

</details>

## 功能

- **可自定义配色（默认青玉/翠青）**：浅色 / 深色两套青玉色板，主色先用圆形色盘自定义，设置页可一键关闭。
- **吉祥物徽章**：可拖动、可收起的小徽章（底部右侧），标题 / 副标可改成任意文字，头像图也可直接上传替换。头像同样支持 GIF 动图，上传 GIF 即以动图播放。另有「恢复吉祥物默认」一键把头像路径、标题、副标都还原到出厂默认。**视频背景时，徽章里会多出 🔊/🔇 按钮与一根音量滑杆**（在关闭按钮左侧），点喇叭即可静音 / 取消静音，拖滑杆即可当场调音量 —— 它们和设置页的「视频背景声音 / 视频背景音量」是同一组字段，两边随时同步；静态图与 GIF 背景不显示这两个控件。
- **魈式语气（工作会话）**：向系统提示注入一段魈式语气说明（可开关），语言可选中文 / 英文模板，也可填自定义提示词。**只改语气**：内容、工具与执行方式完全不变，不注入任何角色身份。
- **角色空间（娱乐，默认关闭）**：一个**独立的角色扮演会话**，与你干活的工作会话彻底分开——**不打开开关就什么都不装**，所以升级不会凭空多出一个 agent preset。开启后插件会把「角色系统提示词」变成一个独立的 DSH agent preset（显示名「角色空间（娱乐） / Roleplay (entertainment)」）：**DSH ≥ 0.1.7 用 `agentPresets` 注册表声明**，**≤ 0.1.6 写成 `~/.dsh/.agent-presets/xiao-roleplay/` 目录**；开一个新会话、在顶部选中该预设即可进入角色。默认角色是**英文的「魈」设定**，把文本框改成任意角色的完整设定即可换角色。该预设自己**不挂文件 / 命令 / 子代理 / 任务这些工作工具**（打开「允许网络检索」后只多挂 web_search / web_fetch 两个网络工具），所以它拿不到你的工作能力，也**不需要牺牲工作会话的真实能力**；两边历史互不相通。（注意：以 host 面 / profile 级挂载的第三方插件工具不属于任何预设，会出现在所有会话里——包括角色会话，见下方「注意事项」。）一键开关，关掉即移除该预设。
- **磨砂背景**：可配置背景图（支持相对插件目录或本地绝对路径，也可直接上传），并调节模糊强度与界面的不透明度。上传 **GIF 动图** 会自动识别并作为 **动态背景**（动画铺满）；上传 **MP4 / WebM / MOV / M4V 视频** 也会自动识别并作为全屏循环视频背景播放（视频背景可选是否播放声音，并可用音量滑杆调大小）；静态图片或单帧 GIF 仍按静态磨砂背景处理。
- **多背景轮播**：在背景列表里加上第 2 项即自动轮播。静态图与 GIF 按可调的「切换间隔」到点即切；视频在「间隔 ≤ 时长」时播完才切、「间隔 > 时长」时循环播到点再切（即切换时间 = max(间隔, 视频时长)）。切换用固定约 0.7 秒的交叉渐变。只有 1 张背景时行为完全不变：无定时器、无渐变，与旧版单背景一致。
- **界面与侧栏透明控制**：界面不透明度（0.3–0.9）控制主内容区；侧栏不透明度（0–1）单独控制左右侧栏，可拉到 100% 完全不透明，且无论怎么调背景图都始终透出一部分。
- **主题颜色**：默认魈的青玉绿，也可用圆形色盘任意自定义主色；整套青玉色板（面板底色、边框、品牌色、侧栏、背景渐变）会随主色协调变化，设置后持久保存。也可一键「恢复主题颜色默认」回到魈的青玉绿。
- **主题管理（多主题）**：把当前所有设置另存为命名主题，可切换 / 重命名 / 删除（内置「魈」主题不可删除）、一键恢复当前主题为默认，并支持对任一主题一键导入 / 导出 `.json`。设置页左侧的分区标题现在会跟随当前主题名：显示为「当前主题名 + 界面语言后缀」（中文「主题」、英文「 Theme」），因此切换到别的主题、或重命名当前主题后，左侧标题会立即同步。主题名原样使用、不做翻译，只有后缀随界面语言变化；内置「魈」主题保持双语的「魈主题」/「Xiao Theme」不变。
- **上传文件管理（选择器）**：背景/头像的上传入口改为一个选择器窗口，列出所有已上传文件（缩略图、大小、修改时间、被哪些主题引用），既可**点选已有文件直接复用**，也可**在窗口内上传新文件**（上传成功后自动选中）。底部「打开上传文件夹」用系统文件管理器打开该目录，可直接增删改。**不会自动删除任何文件**——上传目录完全由用户自己管理。
- **设置页**：总开关、主题颜色、**语气（工作会话）**、模板语言、自定义提示词、**角色空间（娱乐）**（开关 / 允许网络检索 / 角色系统提示词 / 应用更新预设 / 恢复默认角色 / 打开预设文件夹 / 安装状态）、头像路径、吉祥物标题/副标、主题管理、磨砂背景（开关/路径/上传/模糊/透明度，GIF 或 MP4/WebM/MOV/M4V 视频自动识别为动态背景，视频背景可选声音并调音量）、界面与侧栏不透明度。

## 环境要求

- DeepSeek Harness（`dsh` 可用）—— **DSH `v0.1.5-alpha.1` 及更新（即自带官方右栏的版本）推荐优先使用本版本及之后版本**；**`v0.1.5-alpha.1` 之前请使用本版本之前的 `0.11.x`**（见[版本兼容](#版本兼容)）
- better-sidebar（可选第三方插件）—— **仅 `0.19.x`**；旧版 `≤ 0.18`（自绘右栏）不再适配
- Node.js（建议 ≥ 18）
- [pnpm](https://pnpm.io/)

## 版本兼容

**按你的 DSH 版本选主题版本 —— 分界线是「有没有官方右栏」（`dsh-client-ui-sidebar-right`，`v0.1.5-alpha.1` 引入）：**

| 你的环境 | 建议装的主题版本 | 说明 |
| --- | --- | --- |
| **DSH `v0.1.5-alpha.1` 及更新**（已自带官方右栏） | **本版本 `0.12.0` 及之后版本（优先推荐）** | 着色模型覆盖官方右栏的两种形态：面板自绘（`v0.1.5-alpha.1` ~ `0.1.6-alpha.2`）、面板不画而由内部表面画（`0.1.7-alpha.1` 起） |
| **DSH `v0.1.5-alpha.1` 之前**（还没有官方右栏） | **本版本之前的 `0.11.x`** | 那一代的右栏列与锚点和本版本对不上，旧版更稳 |

> ⚠️ **不按上表选也不会崩溃**：插件照常加载、DSH 照常启动，但**可能出现界面 bug** —— 例如侧边栏 / 右栏的底色与透明度不对（偏平、偏不透、左右不一致，或整块透出背景）。
> - 自带官方右栏（`v0.1.5-alpha.1` 及更新）→ 本版本及之后版本。
> - `v0.1.5-alpha.1` 之前 → 本版本之前的 `0.11.x`。
> - CSS 里保留了旧锚点（`data-dsh-panel` / `data-dsh-pane`），所以旧组合不会报错或崩溃，只是**观感不保证**。

## 在线安装（在线快速安装）

1. 确保安装 dsh 命令
2. 按包名安装（npm，推荐）：
```bash
dsh plugin --profile web add xiao-ui-theme-ts
```
   或直接从 GitHub release 安装 tgz：
```bash
dsh plugin --profile web add https://github.com/jinxlux/xiao-theme-dsh-ui-plugin/releases/latest/download/xiao-ui-theme-ts.tgz
```

## 克隆源代码后安装（从 git clone 开始）

```bash
git clone <copied-repo-url>
cd xiao-ui-theme-ts

pnpm install       # 安装构建所需依赖
pnpm run build     # 生成 lib/（ESM Host + ModuleLoader Client + 声明文件）
pnpm run check     # 可选：校验产物是否符合 DSH 插件契约
```

然后把它作为 bundle 挂到 DSH profile：

```bash
# 相对路径（在仓库同级目录执行）
dsh plugin --profile web add "./xiao-ui-theme-ts"
# 或绝对路径
dsh plugin --profile web add "D:/.../xiao-ui-theme-ts"
```

> `dsh plugin add` 会把包装进 profile，并因其 `dsh.bundle` 声明**自动接入 bundle 层栈**，无需手动改配置。
> 刷新 / 重启 DSH Web 后主题生效。

## 使用与配置

- 打开 DSH Web → **设置 → 魈主题** 页：总开关、主题颜色、**语气（工作会话）**、模板语言、自定义提示词、
  **角色空间（娱乐）**、头像路径、吉祥物标题/副标、主题管理、磨砂背景（开关 / 路径 / 上传 / 模糊 / 透明度，
  GIF 或 MP4/WebM/MOV/M4V 视频自动识别为动态背景，视频背景可选声音并调音量）、界面不透明度、侧栏不透明度。
- **语气（工作会话）**：内置中 / 英模板只改说话方式（内容、工具、执行方式一律不变，也不写入角色身份）。但**自定义提示词不一样**：它会被原样插进**每一个**工作会话的系统提示，写什么就真的生效——请只写语气；在里面写工具 / 权限 / 身份 /「一律拒绝某事」这类指令，会把正常工作会话带坏。
- **角色空间（娱乐）**：独立的角色扮演设置块，与语气分组分开：
  - **开关**（默认关）：打开后按下面的角色文本生成 / 更新预设，关闭时移除该预设（已在角色会话里进行中的会话不受影响）。
  - **允许网络检索**（默认关）：开启后角色预设只多挂一行 DSH 的网络工具（web_search / web_fetch），让角色开演前能先查最新的剧情、形象与设定；文件 / 命令 / 任务权限仍然没有。角色卡里**不要**写工具指令：你填的角色文本会原样使用，插件随后在末尾**必定追加**一小段自己的规则（本开关的工具闸门 +「不许公示来源」），这段**无法被角色文本覆盖或关闭**，写了只会和它冲突。（若你装了 profile 级的网络插件，搜索 provider 由它提供，见「注意事项」。）查到的资料只作为角色的背景知识：它不会说「网上说」「查到的」这类出戏话，也不会给链接或来源。关着（默认）时就是直接不允许：角色提示词命令它「不要用任何工具」——这道闸门写在提示词里，不是把工具从会话里拿掉。
  - **受总开关约束**：「启用魈主题」关闭时不安装、并移除该预设——总开关关了就是真的关了，不会出现"界面上还在但其实没生效"。此时本组控件会置灰，状态行会注明原因。
  - **角色系统提示词**：留空使用内置的英文「魈」设定；改成任意角色的完整设定即可换角色（保存后自动同步到预设）。
  - **应用 / 更新预设**：手动强制重写一次（在你手改过预设文件后想恢复时用）。
  - **恢复默认角色（魈）**、**打开预设文件夹**：一键还原角色文本 / 用系统文件管理器打开预设目录（≤0.1.6 的落点 `~/.dsh/.agent-presets/xiao-roleplay/`；0.1.7+ 的预设由注册表提供，目录不存在时会先建好再打开）。
  - **如何进入角色**：开一个**新会话**，在顶部的新会话预设选择器里选「角色空间（娱乐） / Roleplay (entertainment)」——DSH 只允许空会话切换预设，所以必须新开一个会话；已有会话不会被改成角色会话。
- **多背景**：设置 → 魈主题 的背景分组会列出所有背景。点「从已上传文件添加」打开**缩略图选择器**，直接点要加入的图片 / 视频即可（也能在该窗口里上传新文件）；列表里每一条都带自己的预览图。达到 2 张及以后自动轮播，并出现上移 / 下移 / 移除控件与「切换间隔」滑杆。原来的「选择/上传背景图」仍然只替换**第 1 张**。
- **主题颜色**：点圆形色盘自定义主色（默认魈的青玉绿 `#2E8B72`）；面板底色、边框、品牌色、侧栏与背景渐变
  都会随主色协调变化。语义状态色（错误 / 警告 / 成功）保持固定，不随主色。
- **吉祥物**：徽章标题（默认「靖妖傩舞」）与副标（默认「别挡路」）可改成任意文字，留空标题会回落默认。头像路径支持相对插件目录或本地绝对路径，也可直接上传图片替换头像。头像同样支持 GIF 动图，上传 GIF 即以动图播放（无需单独开关）。
- **上传（选择器）**：点「选择/上传背景图」或「选择/上传头像」打开资产窗口——点选已有上传即可复用（背景会自动重算动态标志），也可在窗口内上传新文件并自动选中。「打开上传文件夹」可直接管理这些文件；「恢复主题颜色默认」「恢复吉祥物默认」一键还原到出厂默认。
- **界面不透明度**：控制聊天主内容区的底色，范围 0.3–0.9，上限留 10% 让背景恒透出。
- **侧栏不透明度**：单独控制左右侧栏，范围 0–1，可拉到 100% 完全不透明。左侧为 DSH 自带的侧栏；
  右侧为 DSH 原生右栏面板（稳定锚点 `data-sidebar-right-panel`）——**better-sidebar ≥ 0.19** 的 tab 正是挂进这块面板，
  所以同一个滑杆同时覆盖两者。旧版 better-sidebar（< 0.19）自绘的面板仍经 `data-dsh-panel` / `data-dsh-pane` 命中。
  两者都不存在时规则自动失效、不影响主界面。
- 改动**即时生效**，无需重启 DSH。
- 设置保存在 DSH 数据根下的 `xiao-theme.json`——默认 `~/.dsh`，设了 `$DSH_HOME` 时就是它；上传的背景图/视频保存在它旁边的 `xiao-theme-uploads/`（用户级，不随仓库走）。已经在 `~/.dsh` 有数据的老安装会**继续用老位置**，所以升级不会看起来像"设置被重置"（详见[注意事项](#注意事项)）。上传为流式写盘，并按用途分档上限：头像/图片限 20MB，背景（含视频）放宽至 200MB。不支持或格式不匹配的文件会被拒绝，并在设置页显示明确提示（不再静默失败）。

## 注意事项

- **本地安装切到远程安装**：若一开始是用本地路径装的（`dsh plugin add ./xiao-ui-theme-ts`，DSH 会记成 `link:` 依赖），
  后来改按包名 / tgz 远程安装，需先清掉残留的 link，否则 pnpm 会顺着 link 回到你本地 `node_modules`，
  报符号链接 `EPERM`（`@types/node`）。先移除再重试：
  ```bash
  dsh plugin --profile web remove xiao-ui-theme-ts
  dsh plugin --profile web add xiao-ui-theme-ts
  ```
- **先构建再挂载**：`lib/` 是构建产物、不入库。clone 后务必先执行 `pnpm install && pnpm run build`，
  再 `dsh plugin add`；直接 add 未构建的目录会因缺少 `lib/` 而加载失败。
- 默认头像 / 背景使用**包内相对路径**（`resource/avatar.png`），跨机器可读；
  构建后请保持 `resource/` 与 `lib/` 同层（当前结构成立）。`resource/bg.svg` 系早期遗留、已不再使用。
- **视频背景兼容性**：跨浏览器最稳的是 H.264 (AVC) + AAC 的 `.mp4`，或 VP8/VP9 的 `.webm`。部分浏览器无法解码 HEVC(H.265) 的 `.mp4`/`.mov`；`.avi`/`.mkv` 不受支持。
- **视频背景的声音需要「每次页面加载后交互一次」**：浏览器（Chrome / Edge / Firefox）**恒允许静音自动播放**，但在你与页面交互之前**一律拦截带声自动播放**——这是页面加载级别的浏览器策略，不是本插件的开关。因此开着「视频背景声音」时，启动 DSH（或刷新页面）后背景视频会**先静音播放**；你在界面上任意点击一下、或按一次键，声音就自动接上，**不必重新选主题**。该开关只能表达「想要声音」，命令不动浏览器。若希望第一帧就有声：给该来源（`http://127.0.0.1:3080`）配置企业策略 `AutoplayAllowlist`，或用 `--autoplay-policy=no-user-gesture-required` 启动浏览器（仅调试用）；否则干脆关掉声音开关，让背景纯静音。**「视频背景音量」只在未静音时生效**：0% 即完全无声；拖动滑杆（设置页或徽章里的那根）会自动取消静音，方便你拖到合适大小立刻听到。详见 [Autoplay policy in Chrome](https://developer.chrome.com/blog/autoplay/)。
- 魈式语气提示词依赖 DSH 的 `systemPrompt` 组装。若所用 agent 预设会把提示**过滤成只剩 persona**，
  或使用了 **complete persona**，该语气在对应会话可能不出现（这是预设行为，不是插件故障）。
- 「侧栏不透明度」通过 DSH 布局的 `sidebarCol` 列与原生右栏面板 `data-sidebar-right-panel` 生效。
  旧版 DSH 的右栏列名 `detailsCol`、旧版 better-sidebar 自绘面板的 `data-dsh-panel` / `data-dsh-pane` 仍保留兼容
  （新版更好的侧栏把 `data-dsh-panel` 挪到了「底部工作台面板」上，已用 `:not([data-dsh-bottom-panel])` 明确排除，
  避免底部面板涂透后透出对话文字）。未安装 better-sidebar 时，右栏规则照常作用于 DSH 自带右栏，不影响主界面。
- **上传文件为用户自管理（不会自动删除）**：上传的文件永远不会被自动清理，目录可能逐渐变大。请用选择器的「打开上传文件夹」自行增删改。
- **语气段可能被预设丢掉**：`xiao-voice` 只是一条普通的、无 scope 的系统提示段，不是某个"模式"。把提示组装裁到只剩 persona、或给 persona 开了 `complete: true` 的预设会把它丢掉——所以某个预设下语气突然不见了，是那个预设的行为，不是开关失效。
- **角色空间会注册一个 agent preset**：开关打开时，插件按 DSH 版本自动选路线——**DSH ≥ 0.1.7** 用 `agentPresets` 注册表声明（开关 / 改角色 / 切「允许网络检索」都会即时重新注册）；**DSH ≤ 0.1.6（例如 web 0.1.5）** 在 `~/.dsh/.agent-presets/xiao-roleplay/` 下维护 `agent.cordis.yml` 与 `preset.yml`（`agent.cordis.yml` 是自动生成的，请勿手改；改角色请用设置页的文本框）。两条路线产出**完全一致**的预设内容（同一份 persona、同一组行）。关闭开关会释放注册并删除这两个文件（非递归删除，不会动你放进该目录里的其它东西）。该预设的 persona 就是完整 system prompt（`complete: true` + 不注入运行时上下文），它自己**不挂任何工作工具**（文件 / 命令 / 子代理 / 任务 / 计划），打开「允许网络检索」后只多挂一行 `@deepseek-ai/dsh-tool-web`（web_search / web_fetch）。**注意**：这只约束预设自己那一层——以 host 面（profile 级）注册的第三方插件工具（例如 modsearch 的 `read_page` / `x_search`、plugin-vet 的 `scan_plugin` 等）不属于任何预设，会出现在**所有**会话里，角色会话也不例外。这是受支持的用法：想用就留着——插件自己的工具在角色会话里能用，打开「允许网络检索」后 `web_search` 也会走它提供的搜索 provider（modsearch 就是这种）。只有确实不想让角色会话拿到它时，才需要从 profile 卸载 / 停用。该根目录按 DSH 的用户级规则解析——`$DSH_HOME` 非空时优先于 `~/.dsh`——所以文件路线的预设始终落在 DSH 会扫描的位置（0.1.7+ 走注册表，与目录无关）。主题自身的设置与上传文件则刻意留在 `~/.dsh`，升级时不会看起来像「设置被重置」。
- **角色空间与工作会话互不影响**：工作会话只保留「语气」注入，永不注入角色身份；角色会话不继承工作会话的文件 / 命令 / 子代理 / 任务工具（联网检索要打开「允许网络检索」），所以不存在「角色扮演把真实能力带坏」的问题——代价是角色会话也不能帮你干活，这正是娱乐模式该有的边界。两边会话历史与主题设置互不相通。
- **角色扮演内容免责**：角色会话里模型会按设定演绎，**不要把它的话当作技术结论或事实依据**；娱乐模式默认不内置任何受版权保护的台词原文，角色文本由你自定义（插件仍会在末尾追加自己那一小段规则，见上方设置说明）。
- 本插件**不读取环境变量**做配置；设置只来自 `xiao-theme.json` 与编译期默认值。（`$DSH_HOME` 只用来定位这个数据根，与主题配置无关。）

## 版权与免责声明

- **代码**：本仓库源码以 **MIT 许可证**开源（见 `LICENSE`），可依法学习、修改与分发。
- **图片**：`resource/`（bg.svg、avatar.png，及用户上传的背景图）来自**网络公开来源**，仅作本主题的
  演示 / 自定义用途。
- **人物形象 / 设定**：魈（Xiao）、《原神》（Genshin Impact）的角色形象、名称、相关设定与美术素材的
  **版权归米哈游（miHoYo）所有**。MIT 许可证**仅覆盖本仓库代码**，**不涉及**米哈游拥有的角色形象 / 设定 /
  原创美术；含关联素材（`resource/` 及主题展示）**禁止私自商用或挪作他用**。如需商用或再分发，请先取得
  米哈游授权许可；移除或替换 `resource/` 中的相关素材即可避开该版权约束。详见 `LICENSE` 中的
  “Character Image & Setting Intellectual Property Notice”。