# DeepSeek Harness 用 Pixel Companions

[English](README.md) | [中文](README.zh.md) | [Русский](README.ru.md) | [Tiếng Việt](README.vi.md) | 日本語 | [한국어](README.ko.md)

dsh のセッションをもっと人間味のあるものにしたくて、Pixel Companions を作りました。
これは [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）Web GUI の
**全体の上に**浮かび、エージェントが何をしているかを追随するアニメーション付きの
ピクセルコンパニオンです。入力中、作業中、承認待ち、完了、休眠を表示します。
フレーム全体を覆うオーバーレイに描画しているので、会話・設定・プラグインのどのページでも
見え、ウィンドウ内のどこへでもドラッグできます。UI をフォークせず、コアにパッチを当てず、
プロンプトや応答を傍受しない、通常のオプトイン方式の dsh **バンドル**として作りました。
kappyra です。これは dsh のための私のサイドプロジェクトです。

![プレビュー](demo/preview.webp)

私が描いたキャラクターは 2 体で、それぞれ 15 のアニメーションシーンを持ちます：

- **Lumi** — ワークステーションで作業するピクセル少女。
- **Deepy** — ピクセルのクジラ。

**アートワーク。** Deepy には私が選んだ v3 のマットピクセルセットを使い、Whale Girl は
パックの v2 スタイルを保っています。スプライトはすべて 192×128 で透明です。

私のコンパニオンは、公式のフレーム全体用 `shell.overlay` スロットへのブラウザ側からの
寄与です。`conversation.input.dock` にある非表示のブリッジエントリが、セッションの
ファクトをプラグイン自身のモジュールストアへ公開し、オーバーレイがそれを読み取ります。
歯車ボタンを押すと小さな設定ポップオーバーが開き、設定はこのブラウザ専用として私が
`localStorage` に保持しています（「設定」を参照）。

## 機能

- **どのページにも浮かびます。** オーバーレイをすべての列より上に置いているので、
  コンパニオンは会話・設定・プラグインの各ページで表示されたままです。コンポーザーの隣
  だけではありません。
- **どこへでもドラッグ。** マウス（左ボタン）、タッチ、ペンで、コンパニオンをウィンドウ内の
  任意の場所へ動かせます。ドラッグとクリックを区別するために、小さなドラッグしきい値を
  設けました。位置はビューポート内にクランプされ、リサイズ時に再クランプされ、
  `kappy.pixel-companions.ui.v1` に `position: {x, y}` としてリロードをまたいで保存されます
  （最初のドラッグまでは `null`）。それまでは、コンポーザー領域の上にある右下へ自動で
  配置し、ウィンドウのリサイズに追随させています。
- **モデル自身の作業に追随します。** 私が追跡するのは、実行中のツール呼び出し、
  ストリーミング中の推論、ストリーミング中の回答テキスト、またはライブストリームのない
  実行中のターンです。プロンプトのテキストを読むことはなく、あなた自身の入力で変わる
  こともありません。詳しくは [docs/ja/scenes.md](docs/ja/scenes.md) を参照してください。
- **ホバーでメッセージ入力欄。** ホバー時のメッセージ入力欄も私が追加しました。
  コンパニオン、または完了レポートにポインタを合わせると、現在のセッションへメッセージを
  入力して送信できます。送信後はコンポーザーの下書きが復元されます。レポートが表示されて
  いる間はその直下に積み重なり、レポートを閉じるとコンパニオンの下へ移動します。開いている
  会話が必要で、ドラッグ中または設定パネルを開いている間は非表示です。
- **固定表示される完了レポート。** レポートは固定表示にしました。ターンが終わると、最終回答
  の 1 行目と**詳細**ボタンが、コンパニオンにホバーするか新しいターンが始まるまで
  コンパニオンの下に残ります。**詳細**はスクロール可能なパネルで完全な回答をプレーンテキスト
  として開きます。ホバーするとレポートは閉じ、パネルは ✕、Escape、外側のクリックで閉じます。
- **30 のアニメーション WebP シーン**（キャラクターごとに 15）と、アニメーションをオフに
  したとき用の静止 PNG。Deepy にはドラッグ中に机のない `roaming` アニメーションも
  あります。スプライトはプラグイン自身のアセットルートから配信し、シーンごとに取得して
  いるので、JS バンドルは小さく保たれます。
- **6 つの UI 言語。** キャプションと設定ラベルは、私が English、Русский、中文、
  Tiếng Việt、日本語、한국어 に翻訳しました。初回起動は `navigator.language` に従い、
  一致しなければ English になります。
- **自己完結した設定。** 設定はすべて、ペットの歯車ポップオーバーに私がまとめています：
  キャラクター、**サイズ**スライダー（50–200% を 5% 刻み、−/+ ボタン、リアルタイムの
  パーセント表示、50/100/150/200% のプリセットチップ付き）、言語、アニメーションの
  オン/オフ、表示のオン/オフ、位置のリセット、15 シーンの手動プレビューグリッド、自動、
  閉じる。同じサイズ操作は**設定 → 一般 → コンパニオンの大きさ**にも登録されています。
  コンパニオンは実際のスケール後のピクセルサイズ（100% で 152×98）で描画しているので、
  ヒットエリア、キャプションと歯車、レポート/入力の列、詳細パネルも選択したサイズに
  追随します。
- **オプションのデスクトップウィンドウ。** 小さなコンパニオンも作りました。同じマシン上の
  フレームなし・常に手前の Python ウィンドウでブラウザの外にも表示でき、状態は localhost
  専用のブリッジから供給されます。設定行にプレビューが表示され、ウィンドウが動いていない
  ときは起動コマンドとともに警告が出ます。既定ではオフです。詳しくは
  [docs/ja/desktop.md](docs/ja/desktop.md) を参照してください。
- **構造的に安全。** オーバーレイ層はクリック透過にしました。ポインタイベントを受け取るのは
  コンパニオン、その歯車、パネルだけです。プラグインは Host コードを持たず、自身の
  アセットルートとオプトインの localhost デスクトップブリッジ以外にネットワーク呼び出しを
  行わず、公開スロットの props だけを読み取ります。
- **オプトインで元に戻せます。** 設定 → プラグインで私のプラグインを無効化するか
  バンドルを削除すれば、UI は素の状態に戻ります。

## 動作要件

- dsh Web プロファイル（`dsh web`）。私が対象にしているのは公式 Web クライアントだけです。
- `PATH` 上の `pnpm`。`dsh plugin` がパッケージ操作を pnpm に転送するためです。
- Node.js 22.6+ はソースから再ビルドする場合にのみ必要です。インストール済みのパッケージには
  すでに `client.js` が含まれています。

## インストール

このパッケージはビルド済みバンドルとして配布しています。`client.js` と `assets/` 以下の
アートワークはコミット済みなので、インストールにビルド手順は不要です。

### ローカルチェックアウトから

```sh
git clone https://github.com/kappyra/dsh-pixel-companions.git
cd dsh-pixel-companions
dsh plugin --profile web add link:"$PWD"
```

`link:` はプロファイルをあなたの作業コピーに向けたままにするため、後から `assets/` や
`src/` を編集すると（`npm run build` の実行後）すぐに反映されます。

### Git アドレスまたは tarball から

```sh
dsh plugin --profile web add github:kappyra/dsh-pixel-companions
# or, after `npm pack` in the checkout:
dsh plugin --profile web add /path/to/dsh-pixel-companions-0.1.0.tgz
```

その後、**Web ページを再読み込み**してください。バンドルを追加するとプロファイル内で有効に
なり、コンパニオンはどのページ（会話・設定・プラグイン）でも右下付近に現れ、ページ移動を
またいで残ります。クライアントの HMR トランスポートが通常 1〜2 秒で新しいバンドルに
差し替えるので、再読み込みは常に安全です。

詳しい流れ（プラグインページ、有効化、無効化、アンインストール、トラブルシューティング）：
[docs/ja/installation.md](docs/ja/installation.md)。ドラッグ、ホバー時のメッセージ欄、
固定表示のレポートと詳細、サイズ、言語、デスクトップウィンドウなど日常の使い方は
[docs/ja/usage.md](docs/ja/usage.md) にまとめています。

## 設定

設定はすべて、コンパニオンまたはその歯車ボタン（⚙）から開くパネルに私がまとめています：

| 項目 | 内容 | 保存先 |
| --- | --- | --- |
| キャラクター | Lumi または Deepy | `kappy.pixel-companions.ui.v1` |
| サイズ | 50–200% のスライダー（5% 刻み、−/+ ボタン、リアルタイム表示、50/100/150/200% のプリセットチップ付き）。スプライトは実際のピクセルサイズで描画 | 同じキー |
| コンパニオンの大きさ（設定 → 一般） | 歯車ポップオーバーと同じスライダー、−/+ ボタン、表示、プリセット。どちらも共有の設定を編集し、同期を保つ | 同じキー |
| 言語 | English、Русский、中文、Tiếng Việt、日本語、한국어 | 同じキー |
| アニメーション | アニメーション WebP または静止 PNG | 同じキー |
| 表示 | コンパニオンを表示または非表示 | 同じキー |
| デスクトップウィンドウ | シーンをオプションのデスクトップウィンドウへミラーリング。状態は**オフ** / **未起動** / **接続済み** | 同じキー |
| 位置をリセット | コンパニオンを自動の右下既定位置へ戻す | 同じキー |
| シーンのプレビュー | 15 シーンのいずれかを強制表示、または自動（**自動**）へ戻す | セッション状態のみ |
| 閉じる | パネルを閉じる。**Escape** または外側のクリックでも閉じる | — |

パネルはコンパニオンを基準に配置し、自動的に上下へ反転させ、ビューポート内にクランプして
います。設定とドラッグ後の位置はブラウザごと・プロファイルごとに保持され、Host の設定
サービスへ書き込まれることはありません。プラグインは独立した設定ページを追加せず、その
サイズ行が「設定 → 一般」に現れます。

## デスクトップウィンドウ（オプション）

同じコンパニオンは、デスクトップウィンドウとしても私が作りました。同じマシン上の
フレームなし・常に手前・ピクセル単位で透明なウィンドウで、ブラウザの外にも表示できます。
既定ではオフです。

```sh
sudo apt install python3-gi gir1.2-gtk-3.0 python3-cairo
python3 -m pip install --user Pillow
python3 desktop/companion.py        # or ./desktop/run.sh
```

歯車パネルで**デスクトップウィンドウ**にチェックを入れます。行には**接続済み**、
**未起動**、**オフ**が表示されます。localhost ブリッジを通過するのはシーン id、
キャラクター、スケール、アニメーションのフラグだけで、プロンプトのテキスト、下書き、
メッセージ、セッション id、ファイルパス、モデル出力は一切流れません。詳しくは
[docs/ja/desktop.md](docs/ja/desktop.md) を参照してください。

## シーン

| 観測される信号 | シーン | 正確な意味 |
| --- | --- | --- |
| プロンプト送信（`input.phase` = sending/submitting/adjudicating） | `typing` | メッセージを送信中 |
| ツール呼び出しの実行中 | `working` | ツールが実行中 |
| アシスタントが推論をストリーミング中 | `thinking` | モデルが推論中 |
| アシスタントが回答テキストをストリーミング中 | `typing` | モデルが回答を執筆中 |
| ターン実行中でライブストリームなし（リクエスト進行中） | `thinking` | モデルの応答待ち |
| ライブ信号なしで 75 秒超の実行 | `tired` | 長いタスクであり、モデルの疲労ではない |
| ライブ信号なしで 180 秒超の実行 | `coffee` | 見た目だけの演出 |
| 承認待ち / 質問 | `waiting` | あなたの入力を待機中 |
| `promptError`、`lastAgentError`、または `openState = error` | `error` | 本物のエラー信号 |
| 実行 → エラーなしで停止 | `success`（固定） | コンパニオンにホバーするか新しいターンが始まるまでレポートとともに残る。キャンセルを含む場合がある |
| 110 秒間アクティビティなし | `sleeping` | 表示専用のアイドルタイマー |
| それ以外 | `idle` | — |

ルールは言語に依存しないように作りました。ローカライズされるのはコンパニオンの下に表示
されるキャプションだけです。`thinking` はアシスタントが推論中であることを意味し、
コンポーザーでメッセージの下書きを書いても何も変わりません。`planning`、`reading`、
`searching`、`debugging`、`offline` は、クライアントが型付きの信号を公開するまで
**手動プレビュー専用**です。プラグインがプロンプトの語句から推測することはありません。
完全なルール：[docs/ja/scenes.md](docs/ja/scenes.md)。

## 互換性

稼働中の dsh `0.2.2-alpha.2` Web プロファイルに対して私が検証しました。バンドルが
インストールされ、Client モジュールが Harness のモジュールローダー経由で読み込まれ、
エントリが `shell.overlay`（コンパニオン）と `conversation.input.dock`（非表示ブリッジ）に
登録され、配信されるバンドルのバイト列がリポジトリと一致し、コンポーネントが実際の
スロット props で描画されます。[docs/ja/compatibility.md](docs/ja/compatibility.md) には、
正確な API、ブリッジ → オーバーレイのデータフロー、6 言語の辞書、オプションのデスクトップ
ブリッジが記載されています。見た目の確認（ライト/ダーク、ドラッグの感触、正確な配置）は、
あなた自身のウィンドウで確認してください。

## 開発

```sh
npm install            # esbuild, dev-only
npm run build          # build the asset manifest, then bundle client.js
npm test               # unit tests (Node 22.6+)
```

ブラウザ側のコード：`src/client/bridge.ts`（ファクトストア）、`Pet.tsx`（オーバーレイ、
ドラッグと roaming、非表示ブリッジ、ホバー入力欄、レポート）、`state.ts`（シーンルール）、
`signals.ts` と `asset-url.ts`（純粋なヘルパーとアセットルートの解決）、`text.ts`（6 言語）、
`desktop.ts`（オプションのデスクトップブリッジ）。パイプライン、パッケージング、レイアウト
は [docs/ja/development.md](docs/ja/development.md) に私がまとめました。

## ライセンスと素材

- **プラグインのコードは MIT** で公開しています。詳しくは [LICENSE](LICENSE) を参照して
  ください。
- `assets/`、`source-art/`、`demo/`、およびプラグインが配信するコピーに含まれる**マスコット
  のアートワーク**は、このプロジェクトのために私が制作したものです。プロジェクトとともに
  配布されますが、コードに対する MIT 許諾の対象ではなく、権利は私が保持します。
  [ASSETS_NOTICE.md](ASSETS_NOTICE.md) を参照してください。
- DeepSeek および DeepSeek Harness は、それぞれの所有者の商標です。これは非公式の
  コミュニティプラグインであり、DeepSeek と提携しているわけでも、承認を受けているわけでも
  ありません。Harness が文書化している公開プラグイン API のみを使用しています。

## トラブルシューティング

| 症状 | 確認事項 |
| --- | --- |
| どこにもコンパニオンが表示されない | 設定 → プラグイン：バンドルは有効ですか？ページを再読み込みしてください。開いている会話は必要ありません。 |
| コンパニオンは表示されるが動かない | 静止 PNG が選ばれている（アニメーションオフ）か、OS が動きの低減を要求している可能性があります。 |
| ドラッグしてもコンパニオンが動かない | 離す前に数ピクセル動かしてください（ドラッグしきい値があります）。また、空のオーバーレイではなくスプライト自体をドラッグしてください。 |
| リサイズやモニター変更の後、コンパニオンが画面外にある | 歯車 → **位置をリセット**。自動の右下既定位置に戻ります。 |
| スプライトが大きすぎる、または小さすぎる | 歯車ポップオーバーまたは**設定 → 一般 → コンパニオンの大きさ**にある **50/100/150/200%** のプリセットチップをクリックするか、**サイズ**スライダー（50–200%）をドラッグします。保存された位置は自動で再クランプされ、**位置をリセット**で自動の右下位置に戻ります。 |
| サイズ操作が見つからない | **設定 → 一般 → コンパニオンの大きさ**と、コンパニオンの ⚙ ポップオーバーの両方にあります。どちらも同じ設定を編集します。両方とも表示されない場合は、ハードリロードが必要です（ページが古いクライアントバンドルで動作しています）。 |
| 言語が正しくない | 歯車 → **言語**。初回起動はブラウザの言語に従います。それ以外は English です。 |
| 設定ポップオーバーが切れている | パネルは反転してビューポート内にクランプされます。**位置をリセット**してから、ウィンドウサイズを報告してください。 |
| デスクトップウィンドウがオフラインのまま、または不透明な箱になる | ページが開いていて**デスクトップウィンドウ**がチェックされていること。透明化には `python3-cairo` をインストールします。`curl http://127.0.0.1:37421/health` を確認してください。詳しくは [docs/ja/desktop.md](docs/ja/desktop.md)。 |
| アートワークを変更した後、スプライトが古い、または 404 になる | `npm run build` を実行してください（`?v=` のコンテンツハッシュが各スプライト URL の一部です）。その後ページを再読み込みします。 |
| `client.js` の読み込みに失敗する | プロファイルがパッケージを配信できる必要があります。`dsh plugin --profile web add` を再実行し、`$DSH_HOME/profiles/web/.plugin-manager/logs/` 以下の pnpm ログを確認してください。 |

その他は [docs/ja/troubleshooting.md](docs/ja/troubleshooting.md) を参照してください。