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

# xiao-ui-theme-ts

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

## 这是什么

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

## 示例

<img width="2515" height="1288" alt="Screenshot 2026-08-23 181933" src="https://github.com/user-attachments/assets/3998f58b-53db-4349-80f3-3d993c6ad3c3" />

## 功能

- **可自定义配色（默认青玉/翠青）**：浅色 / 深色两套青玉色板，主色先用圆形色盘自定义，设置页可一键关闭。
- **吉祥物徽章**：可拖动、可收起的小徽章（底部右侧），标题 / 副标可改成任意文字，头像图也可直接上传替换。头像同样支持 GIF 动图，上传 GIF 即以动图播放。另有「恢复吉祥物默认」一键把头像路径、标题、副标都还原到出厂默认。
- **魈式语气（工作会话）**：向系统提示注入一段魈式语气说明（可开关），语言可选中文 / 英文模板，也可填自定义提示词。**只改语气**：内容、工具与执行方式完全不变，不注入任何角色身份。
- **角色空间（娱乐，默认关闭）**：一个**独立的角色扮演会话**，与你干活的工作会话彻底分开——**不打开开关就什么都不装**，所以升级不会凭空多出一个 agent preset。开启后插件会把「角色系统提示词」写成一个独立的 DSH agent preset（`~/.dsh/.agent-presets/xiao-roleplay/`，显示名「角色空间（娱乐） / Roleplay (entertainment)」）；开一个新会话、在顶部选中该预设即可进入角色。默认角色是**英文的「魈」设定**，把文本框改成任意角色的完整设定即可换角色。该预设自己**不挂文件 / 命令 / 子代理 / 任务这些工作工具**（打开「允许网络检索」后只多挂 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`。
- **上传文件管理（选择器）**：背景/头像的上传入口改为一个选择器窗口，列出所有已上传文件（缩略图、大小、修改时间、被哪些主题引用），既可**点选已有文件直接复用**，也可**在窗口内上传新文件**（上传成功后自动选中）。底部「打开上传文件夹」用系统文件管理器打开该目录，可直接增删改。**不会自动删除任何文件**——上传目录完全由用户自己管理。
- **设置页**：总开关、主题颜色、**语气（工作会话）**、模板语言、自定义提示词、**角色空间（娱乐）**（开关 / 允许网络检索 / 角色系统提示词 / 应用更新预设 / 恢复默认角色 / 打开预设文件夹 / 安装状态）、头像路径、吉祥物标题/副标、主题管理、磨砂背景（开关/路径/上传/模糊/透明度，GIF 或 MP4/WebM/MOV/M4V 视频自动识别为动态背景，视频背景可选声音）、界面与侧栏不透明度。

## 环境要求

- DeepSeek Harness（`dsh` 可用）—— 已在 `0.1.1-rc.2` 与 `0.1.5-rc.1` 上实测（见[版本兼容](#版本兼容)）
- Node.js（建议 ≥ 18）
- [pnpm](https://pnpm.io/)

## 版本兼容

上次升级的**两端都兼容**——升级前的版本与当前版本都能用：

| 组件 | 实测 / 支持范围 | 主题如何适配 |
| --- | --- | --- |
| DeepSeek Harness | `0.1.1-rc.2`（升级前）→ `0.1.5-rc.1`（当前） | 左侧栏：类名后缀 `sidebarCol`。右侧栏：老列名 `detailsCol` 与新版原生面板 `data-sidebar-right-panel` 两条锚点同时保留，任一版本 DSH 都生效。 |
| better-sidebar（第三方） | `0.17.1`（升级前）→ `0.19.0`（当前） | `0.17.1` 是它自绘的右侧面板，走 `data-dsh-panel` / `data-dsh-pane`；`0.19.0` 改为把每个 tab 注册进 DSH 原生右栏，走 `data-sidebar-right-panel`。新版把 `data-dsh-panel` 挪到了「底部工作台面板」上（同元素带 `data-dsh-bottom-panel`），已明确排除、保持不透明。 |

2026-09-10 实测：`dsh 0.1.1-rc.2 + better-sidebar 0.17.1` 与 `dsh 0.1.5-rc.1 + better-sidebar 0.19.0` 两套组合下，「侧栏不透明度」对左右侧栏均生效；所有兼容锚点都保留着，升级或回退都不会失效。更老的 better-sidebar（0.14.x / 0.16.x）用的是同一套 `data-dsh-panel` 锚点，预期同样可用，但未实测。

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

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 由它提供，见「注意事项」。）查到的资料只作为角色的背景知识：它不会说「网上说」「查到的」这类出戏话，也不会给链接或来源。关着（默认）时就是直接不允许：角色提示词命令它「不要用任何工具」——这道闸门写在提示词里，不是把工具从会话里拿掉。
  - **受总开关约束**：「启用魈主题」关闭时不安装、并移除该预设——总开关关了就是真的关了，不会出现"界面上还在但其实没生效"。此时本组控件会置灰，状态行会注明原因。
  - **角色系统提示词**：留空使用内置的英文「魈」设定；改成任意角色的完整设定即可换角色（保存后自动同步到预设）。
  - **应用 / 更新预设**：手动强制重写一次（在你手改过预设文件后想恢复时用）。
  - **恢复默认角色（魈）**、**打开预设文件夹**：一键还原角色文本 / 用系统文件管理器打开 `~/.dsh/.agent-presets/xiao-roleplay/`。
  - **如何进入角色**：开一个**新会话**，在顶部的新会话预设选择器里选「角色空间（娱乐） / 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` 启动浏览器（仅调试用）；否则干脆关掉声音开关，让背景纯静音。详见 [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/.agent-presets/xiao-roleplay/` 下维护 `agent.cordis.yml` 与 `preset.yml`（`agent.cordis.yml` 是自动生成的，请勿手改；改角色请用设置页的文本框）。关闭开关会删除这两个文件（非递归删除，不会动你放进该目录里的其它东西）。该预设的 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 会扫描的位置。主题自身的设置与上传文件则刻意留在 `~/.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”。