> **Language / 言語：** [English](../README.md) · [简体中文](./README.zh-CN.md) · **日本語**（現在） · [한국어](./README.ko.md)

# xiao-ui-theme-ts

DeepSeek Harness の**カスタマイズ可能なテーマプラグイン**（初期状態では「魈」の翡翠グリーン風）。DeepSeek Harness の Web インターフェイスにテーマを適用します。配色、マスコットバッジ、背景、音声の注入などがすべて設定可能です。背景は**静的画像、動的 GIF、ループ動画（MP4/WebM/MOV/M4V）**に対応し、アニメーション GIF をアップロードすると自動で動的（ライブ）背景になり、動画をアップロードしても自動で認識され、全画面ループ背景として再生されます。標準では魈風の翡翠／エメラルドのテーマですが、アクセントカラー、バッジの文字、音声、背景などを自由に調整して、自分だけのテーマにできます。

## これは何

DeepSeek Harness の Web インターフェイスに、高度にカスタマイズ可能なテーマを適用します。**標準では魈の翡翠グリーン風**（翡翠パレット＋マスコットバッジ＋魈風音声＋すりガラス背景）ですが、すべて調整可能です。アクセントカラー、バッジの文字、音声のオン／オフ・言語・内容、背景画像と透明度。また、セッションに**魈風の口調**を任意で注入できます。アシスタントに魈のような口調で話させたいときはオン、不要ならオフ。ただし変わるのは口調・文体だけで、回答の内容は一切変わりません。

## プレビュー

<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 の 1 行だけが追加されます）ので、仕事セッションの実能力を犠牲にすることはありません。（profile レベルのプラグインが登録したツールはどのプリセットにも属さず、ロールプレイを含む全セッションに現れます。下の注意書きを参照。）履歴は互いに独立です。ワンクリックでオン／オフでき、オフにするとプリセットは削除されます。
- **すりガラス背景**：背景画像を設定可能（プラグイン相対パス、ローカル絶対パス、または直接アップロード）。ぼかし強度と UI の透明度も調整できます。アニメーション GIF をアップロードすると自動で**動的（ライブ）背景**として扱われます。**MP4 / WebM / MOV / M4V 動画**をアップロードしても自動で認識され、全画面ループ動画背景として再生されます（動画背景では音声のオン／オフも選択可能）。静止画像や単一フレームの GIF は従来どおり静的すりガラス背景として処理されます。
- **複数背景（ローテーション）**：背景リストに 2 つ目を追加すると自動でローテーションします。静止画とアニメーション GIF は設定可能な「切替間隔」で切り替わり、動画は「間隔 ≤ 再生時間」なら最後まで再生してから、「間隔 > 再生時間」ならループ再生して間隔に達してから切り替わります（切替時間 = max(間隔, 動画の長さ)）。切替には約 0.7 秒の固定クロスフェードを使います。背景が 1 枚だけのときは何も変わりません（タイマーなし・フェードなしで従来どおり）。
- **UI・サイドバー透明度制御**：UI 不透明度（0.3–0.9）はメイン領域を、サイドバー不透明度（0–1）は左右のサイドバーを個別に制御。100% 完全に不透明にできつつ、背景は常に一部透けます。
- **アクセントカラー**：標準は魈の翡翠グリーン。カラーホイールで任意のアクセントカラーを選択可能。パネル面・ボーダー・ブランドカラー・サイドバー・背景グラデーションが連動して変化し、変更後は保存されます。「テーマカラーを既定に戻す」で魈の翡翠グリーンに戻せます。
- **テーマ管理（マルチテーマ）**：現在の全設定を名前付きテーマとして保存し、切替・リネーム・削除（内蔵の「魈」テーマは削除不可）、現在のテーマを既定へ戻すことが可能。各テーマを `.json` としてワンクリックでインポート／エクスポートできます。
- **アップロード資産マネージャー（ピッカー）**：背景・アバターのアップロード入口がピッカーウィンドウになり、既にアップロード済みのファイル（サムネイル、サイズ、更新日時、どのテーマが参照しているか）を一覧表示します。既存ファイルを**選んで再利用**するか、その場で**新規アップロード**（成功後に自動選択）できます。下部の「アップロードフォルダを開く」でファイルマネージャー上で直接追加・削除・リネームできます。**ファイルは自動的に削除されません**——アップロードフォルダはユーザー管理です。
- **設定ページ**：マスタースイッチ、アクセントカラー、**口調（仕事セッション）**、テンプレート言語、カスタムプロンプト、**ロールプレイ空間（娯楽）**（オン／オフ・役のシステムプロンプト・プリセットの適用／更新・既定の役に戻す・プリセットフォルダーを開く・インストール状態）、アバターパス、マスコットのタイトル／サブタイトル、テーマ管理、すりガラス背景（オン／パス／アップロード／ぼかし／透明度。GIF または MP4/WebM/MOV/M4V 動画は動的背景として自動認識、動画背景は音声選択可能）、UI とサイドバーの不透明度。

## 必要環境

- 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` は DSH ネイティブの右サイドバーにタブを登録する方式（`data-sidebar-right-panel`）です。新版が `data-dsh-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 リリースの tgz から直接インストール：
```bash
dsh plugin --profile web add https://github.com/jinxlux/xiao-theme-dsh-ui-plugin/releases/latest/download/xiao-ui-theme-ts.tgz
```

## ソースからインストール（クローン）

```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 プラグイン契約を満たすか検証
```

その後、バンドルとして DSH プロファイルに追加します：

```bash
# 相対パス（リポジトリと同階層で実行）
dsh plugin --profile web add "./xiao-ui-theme-ts"
# または絶対パス
dsh plugin --profile web add "D:/.../xiao-ui-theme-ts"
```

> `dsh plugin add` はパッケージをプロファイルにインストールし、`dsh.bundle` 宣言により**バンドルスタックに自動的に組み込まれます** — 手動設定は不要です。
> テーマを反映するには DSH Web を更新／再起動してください。

## 使い方と設定

- DSH Web → **設定 → 魈テーマ**：マスタースイッチ、アクセントカラー、**口調（仕事セッション）**、テンプレート言語、カスタムプロンプト、**ロールプレイ空間（娯楽）**、アバターパス、マスコットのタイトル／サブタイトル、テーマ管理、すりガラス背景（オン／パス／アップロード／ぼかし／透明度。GIF または MP4/WebM/MOV/M4V 動画は動的背景として自動認識、動画背景は音声選択可能）、UI 不透明度、サイドバー不透明度。
- **口調（仕事セッション）**：内蔵の中国語／英語テンプレートは話し方だけを変えます（内容・ツール・実行方法は不変、キャラクターの人格も書き込みません）。ただし**カスタムプロンプトは別物**です：**すべての**仕事セッションのシステムプロンプトにそのまま挿入され、書いた内容は実際に効きます。口調だけを書いてください。ツール／権限／人格／「必ず断れ」といった指示を書くと、通常の作業セッションが壊れます。
- **ロールプレイ空間（娯楽）**：口調とは別の独立した設定グループです。
  - **オン／オフ**（既定オフ）：オンにすると下の役テキストからプリセットを生成／更新し、オフにすると削除します（実行中のロールプレイセッションはそのまま続行されます）。マスタースイッチ（**魈テーマを有効化**）にも従います：マスターがオフの間は何もインストールされず、プリセットは削除されます。
  - **ネット検索を許可**（既定オフ）：オンにするとロールプレイのプリセットに DSH のネットツール（web_search / web_fetch）を 1 行だけ追加し、演じる前に関連する最新のあらすじ・デザイン・設定を調べられます。ファイル／コマンド／タスク権限は依然としてありません。役テキストにツールの指示は書かないでください：入力した役テキストはそのまま使われ、その末尾にプラグインが短いルール節（このスイッチのツール遮断＋「出典を名乗らない」）を**必ず追記**します。役テキストで上書き・無効化はできないため、書いても衝突するだけです。（profile レベルのネットプラグインを入れている場合、検索 provider はそれが提供します。下の注意書きを参照。）調べた内容はあくまでキャラクターの背景知識として扱われ、キャラクターは「ネットで調べた」「出典は」といったメタ発言やリンク提示をしません。オフ（既定）のときは単純に禁止です：役テキストが「一切ツールを使うな」と命じます——この遮断はプロンプト側にあり、ツール自体を外しているわけではありません。
  - **役のシステムプロンプト**：空欄なら内蔵の英語「魈」設定。任意のキャラ設定を貼り付けると役を差し替えられます（保存でプリセットへ自動同期）。
  - **プリセットを適用／更新**：手動で強制的に書き直します（生成ファイルを手で編集した後の復元に便利）。
  - **既定の役（魈）に戻す**／**プリセットフォルダーを開く**：役テキストの復元、または `~/.dsh/.agent-presets/xiao-roleplay/` をファイルマネージャーで開きます。
  - **キャラクターに入る方法**：**新しいセッション**を開始し、上部のプリセット選択で「角色空间（娱乐） / Roleplay (entertainment)」を選びます。DSH はまだ何も出力していないセッションしかプリセットを切り替えられないため、既存セッションをロールプレイ化することはできません。
- **複数背景**：設定 → 魈テーマ の背景グループにすべての背景が一覧表示されます。「アップロード済みから追加」をクリックすると**サムネイル付きのピッカー**が開くので、追加したい画像／動画をクリックします（そのウィンドウから新規アップロードも可能）。リストの各項目にはプレビューが付きます。2 枚以上でローテーションが始まり、上へ／下へ／削除のコントロールと「切替間隔」スライダーが表示されます。「背景を選択／アップロード」は従来どおり**1 枚目**を置き換えます。
- **アクセントカラー**：カラーホイールでアクセントカラーを選択（標準は魈の翡翠グリーン `#2E8B72`）。パネル面・ボーダー・ブランドカラー・サイドバー・背景グラデーションが連動して変化します。意味を持つ状態色（エラー／警告／成功）は固定され、アクセントに追従しません。
- **マスコット**：バッジのタイトル（標準「靖妖傩舞」）とサブタイトル（標準「别挡路」）は任意の文字列に変更できます。タイトルを空にすると標準に戻ります。アバターパスはプラグイン相対パスまたはローカルの絶対パスを受け付け、画像を直接アップロードしてアバターを置き換えることもできます。アバターは GIF アニメーションにも対応し、GIF をアップロードすると専用の切り替えなしで動画として再生されます。
- **アップロード（ピッカー）**：「選択／アップロード背景」または「選択／アップロードアバター」をクリックすると資産ウィンドウが開きます。既存のアップロードを選んで再利用（背景は動的フラグを自動再計算）するか、その場で新規アップロードして自動選択できます。「アップロードフォルダを開く」で直接管理でき、「テーマカラーを既定に戻す」「マスコットを既定に戻す」で初期値に戻せます。
- **UI 不透明度**：メイン領域を制御。範囲 0.3–0.9 で、背景が常に約 10% 以上見えるよう上限が設定されています。
- **サイドバー不透明度**：左右のサイドバーを個別に制御。範囲 0–1、100% 完全に不透明にできます。左は DSH 標準のサイドバー、右は DSH ネイティブの右サイドバーパネル（安定アンカー `data-sidebar-right-panel`）で、**better-sidebar ≥ 0.19** のタブもこのパネルに載るため 1 つのスライダーで両方を制御できます。旧版 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/` はビルド成果物で、コミットされません。クローン後は `pnpm install && pnpm run build` を先に実行してください。未ビルドのディレクトリを `dsh plugin 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` は非対応です。
- **動画背景の音声は「ページ読み込みごとに 1 回の操作」が必要です**：ブラウザ（Chrome / Edge / Firefox）は**ミュートの自動再生を常に許可**しますが、ユーザーがページを操作するまでは**音声付きの自動再生を必ずブロック**します——これはページ読み込み単位のブラウザポリシーであり、本プラグインの設定ではありません。そのため「動画背景の音声」をオンにしたまま DSH を起動（またはページを再読み込み）すると、背景動画は**まずミュートで再生**され、UI のどこかをクリックするかキーを押した瞬間に音声が自動で戻ります（**テーマを選び直す必要はありません**）。このスイッチは「音声を望むか」を表すだけで、ブラウザの判断を覆すことはできません。最初のフレームから音を出したい場合は、そのオリジン（`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` も互換のため残しています。新版 better-sidebar の**下部ワークベンチ**パネルも `data-dsh-panel` を持ちますが、`:not([data-dsh-bottom-panel])` で明示的に除外し、不透明のままにしています。better-sidebar 未インストール時も右側のルールは DSH 標準の右サイドバーに作用し、メイン UI には影響しません。
- **アップロードはユーザー管理（自動削除なし）**：アップロードしたファイルは自動的に削除されず、フォルダが大きくなることがあります。ピッカーの「アップロードフォルダを開く」で自分で追加・削除・リネームしてください。
- **口調のセクションはプリセットに捨てられることがあります**：`xiao-voice` はスコープを持たない普通の system prompt セクションであり「モード」ではありません。プロンプト組み立てを persona だけに絞るプリセットや、persona に `complete: true` を設定したプリセットはこれを落とします——特定のプリセットで口調が消えるのはそのプリセットの挙動で、スイッチの故障ではありません。
- **ロールプレイ空間は agent preset を書き込みます**：オンにすると、`~/.dsh/.agent-presets/xiao-roleplay/` に `agent.cordis.yml` と `preset.yml` を維持します（`agent.cordis.yml` は自動生成物なので手で編集しないでください。役の変更は設定ページのテキスト欄で行います）。オフにするとこの 2 ファイルを削除します（非再帰削除なので、そのフォルダーに置いた他のものは消しません）。プリセットの persona は完全な system prompt そのもの（`complete: true`、ランタイムコンテキストなし）で、このプリセット自身は**仕事用ツール（ファイル／シェル／サブエージェント／タスク／プラン）をマウントしません**（**ネット検索を許可**をオンにすると web_search / web_fetch の 1 行だけが追加されます）。**注意**：これはプリセット自身の層だけの話です——profile レベル（host 面）で登録されたサードパーティプラグインのツール（例：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 ライセンスは**本リポジトリのコードのみ**をカバーし、miHoYo のキャラクターの容姿／設定／オリジナルアートを**カバーしません**。関連素材（`resource/` およびテーマ表示）を含むものは、許可なく**商用利用や流用を禁じます**。再配布・商用利用の際は先に miHoYo のライセンスを取得してください。`resource/` 内の素材を削除・差し替えればこの制約を回避できます。詳細は `LICENSE` の「Character Image & Setting Intellectual Property Notice」を参照してください。