137 lines
11 KiB
Markdown
137 lines
11 KiB
Markdown
<div align="center">
|
||
|
||
<img src="assets/readme/hero.svg" width="100%" alt="PiAgentUI: 実際の Pi Agent セッションを扱うデスクトップ／Web ワークスペース。チャット、tool call カード、Files・Changes・MCP・Skills パネル">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
[Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [設計 spec](docs/superpowers/specs/)
|
||
|
||
[English](README.md) · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · **日本語**
|
||
|
||
</div>
|
||
|
||
|
||
|
||
## 概要
|
||
|
||
PiAgentUI は [Pi coding agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) 用のチャット UI 兼 workspace です。Pi 拡張機能が配信する Web アプリとして、または Tauri 2 のデスクトップアプリとして動き、素のターミナルでは見えないもの（セッション一覧、tool call、MCP サーバー、skills、コンテキスト使用量）を 1 つのウィンドウにまとめます。
|
||
|
||
- 実際の Pi セッションを SSE（`/global/event`）でストリーミングし、Markdown、コード（Shiki）、数式（KaTeX）を描画します。
|
||
- tool call をカードで表示し、アクティブなセッションのコンテキスト使用量を表示します。
|
||
- ランタイムが返す capability を使ってモデルを切り替えます。
|
||
- 設定済みの MCP サーバー（transport、command、URL、source）と、source ごとにまとめた有効な skills を一覧表示します。
|
||
- 組み込みと動的な slash command、composer の Git 操作を提供します。
|
||
- チャットの横にターミナル（xterm.js）とファイルエクスプローラーを組み込んでいます。
|
||
- settings で指定した OpenAI 互換の STT エンドポイント経由で音声入力を受け付けます。
|
||
- UI の言語: `en`, `pt-BR`, `es`, `zh-CN`, `hi`, `bn`, `ar`（`src/locales/`）。日本語の UI はまだありません。
|
||
|
||
## 使う理由
|
||
|
||
PiAgentUI はエージェントの状態を独自に持ちません。セッション、モデル、tools、skills、コマンドは拡張機能を通じて Pi ランタイムから取得するので、画面に出るものは Pi が実際に動かしているものです。
|
||
|
||
Pi を使っていないなら向きません。拡張機能がないと、UI はサーバー接続ダイアログしか表示しません。また 1 ウィンドウにつき 1 ランタイムで、ホストされたデモや npm 公開パッケージもありません。
|
||
|
||
## 仕組み
|
||
|
||
- `extensions/piagentui-server.ts` が Pi 拡張機能です。Node の `http` + `ws` で `dist/` のビルド済み UI を配信し、`window.PI_BOOT_DATA`（ベース URL とトークン）を注入します。
|
||
- 起動時にポート `58785`（使用中なら次の空きポート）で待ち受け、ポートとランダムなトークンを `~/.pi/agent/piagentui-port.json` に書き込みます。
|
||
- `GET /global/health` は認証なしで、ほかの `/api/*` ルートは `Authorization: Bearer <token>` が必要です。ソケットは `0.0.0.0` にバインドしますが、`/api/network/access` の LAN アクセスが有効（デフォルトは無効）でない限り、各リクエストは loopback かどうか検査されます。
|
||
- Tauri アプリは `get_pi_agent_connection` コマンドで同じ discovery ファイルを読むため、デスクトップ版は手動設定なしでローカルのランタイムに接続します。
|
||
- コンテナでは、Rust の router（`src-router/`、axum）が Caddy の背後で gateway として frontend と backend の前に立ちます。
|
||
|
||
## クイックスタート
|
||
|
||
| ツール | バージョン | 用途 |
|
||
|---|---|---|
|
||
| Node.js | `>=22`（`.tool-versions`: 22.22.0） | すべて |
|
||
| npm | Node に同梱のもの | すべて（`package-lock.json`） |
|
||
| Rust | `1.85.0`（`.tool-versions`） | デスクトップアプリと gateway の router |
|
||
| Docker Compose | 最近のもの | コンテナ構成のみ |
|
||
| Pi Agent | ローカルにインストール済み | 実際のセッションとモデル |
|
||
|
||
```bash
|
||
git clone https://git.evandro.dev.br/evandro/PiAgentUI.git
|
||
cd PiAgentUI
|
||
npm ci # postinstall で scripts/copy-material-icons.mjs が動きます
|
||
npm run build # tsc -b && vite build -> dist/
|
||
npm run dev # Vite 開発サーバー http://localhost:5173
|
||
```
|
||
|
||
`npm run dev` はフロントエンドのみで、`/api` をプレフィックスを外して `127.0.0.1:4096` にプロキシします。Pi で使う場合は先にビルドし、拡張機能に `dist/` を配信させます（Pi は `package.json` の `pi.extensions` フィールドでこのリポジトリをパッケージとして読み込みます）。
|
||
|
||
```bash
|
||
npm run build
|
||
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
|
||
# http://127.0.0.1:58785 を開く
|
||
```
|
||
|
||
デスクトップと Android:
|
||
|
||
```bash
|
||
npm run tauri dev # Vite 開発サーバー上のデスクトップウィンドウ
|
||
npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json)
|
||
npm run tauri android dev # scripts/dev-android.sh を参照
|
||
```
|
||
|
||
PR の前に `npm run validate` を実行してください。typecheck、拡張機能の typecheck、lint、build、テストを順に実行し、CI の `build.yml` もこれを使います。
|
||
|
||
## 設定
|
||
|
||
コンテナ構成は OpenCodeUI のデプロイから引き継いだものです。最初に `.env.example` を `.env` にコピーしてください。
|
||
|
||
| ファイル | コマンド | 内容 |
|
||
|---|---|---|
|
||
| `docker-compose.yml` | `docker compose up -d` | フル構成: `gateway`（Caddy + Rust router、`127.0.0.1:6658` と `6659`）、`frontend`、`backend`（`opencode serve`、4096、メモリ上限 4G）。 |
|
||
| `docker-compose.standalone.yml` | `docker compose -f docker-compose.standalone.yml up -d` | 既存の `opencode serve` 向けのフロントエンドのみ。`BACKEND_URL`（デフォルト `host.docker.internal:4096`）と `PORT`（デフォルト `3000`）を使います。 |
|
||
| `docker-compose.host.yml` | `docker compose -f docker-compose.yml -f docker-compose.host.yml up -d` | 任意の override: `backend` を privileged で動かし、Docker ソケットとホストの `/` を `/host` にマウントします。 |
|
||
| `docker-compose.build.yml` | `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` | 任意の override: `docker/` から gateway、frontend、backend をローカルでビルドします。 |
|
||
|
||
<details>
|
||
<summary>環境変数（コンテナ構成のみ）</summary>
|
||
|
||
| 変数 | 必須 | 説明 |
|
||
|---|---|---|
|
||
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY` | 最低 1 つ | backend コンテナに渡す LLM プロバイダーのキー。 |
|
||
| `GATEWAY_PORT` | いいえ（`6658`） | 統合エントリーポイントのホスト側ポート。 |
|
||
| `PREVIEW_PORT` | いいえ（`6659`） | プレビュー用エントリーポイントのホスト側ポート。 |
|
||
| `PREVIEW_DOMAIN` | いいえ | プレビュー用の別ドメイン。リバースプロキシが `PREVIEW_PORT` に転送します。 |
|
||
| `WORKSPACE` | いいえ（`./workspace`） | backend の `/workspace` にマウントするホストのディレクトリ。 |
|
||
| `OPENCODE_SERVER_PASSWORD` | 公開デプロイ時 | backend と router のパスワード。 |
|
||
| `OPENCODE_SERVER_USERNAME` | いいえ（`opencode`） | 上記パスワードと組になるユーザー名。 |
|
||
| `PUBLIC_BASE_URL` | いいえ | gateway 内蔵の router が使う公開ベース URL。 |
|
||
| `ROUTER_SCAN_INTERVAL` | いいえ（`5`） | router のスキャン間隔。 |
|
||
| `ROUTER_TOKEN_LENGTH` | いいえ（`12`） | 生成するルートトークンの長さ。 |
|
||
| `ROUTER_PORT_RANGE` | いいえ（`3000-9999`） | router が扱うポート範囲。 |
|
||
| `ROUTER_EXCLUDE_PORTS` | いいえ（`4096`） | router が除外するポート。 |
|
||
| `DOCKER_API_VERSION` | いいえ（`1.40`） | backend が使う Docker API のバージョン。`.env.example` ではなく `docker-compose.yml` で設定されています。 |
|
||
| `USE_CHINA_MIRROR` | いいえ（`1`） | backend イメージのビルドオプション。下のミラーを使います。 |
|
||
| `APT_MIRROR`, `APT_SECURITY_MIRROR`, `NPM_CONFIG_REGISTRY`, `NODEJS_ORG_MIRROR`, `PIP_INDEX_URL`, `PIP_TRUSTED_HOST` | いいえ | backend のツールチェーン用ミラー。 |
|
||
| `MISE_INSTALL_URL`, `OPENCODE_INSTALL_URL` | いいえ | backend イメージのビルドで使うインストーラーの URL。 |
|
||
|
||
</details>
|
||
|
||
## プロジェクトの状態
|
||
|
||
1.0 前のベータ版（`0.6.10`）で、開発者 1 人がメンテナンスしています。リリースは `v*` タグで `release.yml` がビルドし（Windows、macOS、Linux、Android の成果物）、`deploy.yml` が `VITE_BASE_PATH=/PiAgentUI/` で Web 版を公開します。
|
||
|
||
- OpenCodeUI の名前はまだ一部に残っています。Rust router の crate は `opencodeui-router`、イメージは `opencodeui-*`、Android の APK は `OpenCodeUI-*`、`.env.example` のコメントは中国語で、Docker の backend が動かす `opencode serve` は Pi 拡張機能のフローではなく引き継いだデプロイのものです。
|
||
- `docker-compose.yml` と `docker-compose.standalone.yml` は、まだ upstream の `ghcr.io/lehhair/opencodeui-frontend` イメージを取得します。
|
||
- テストはコンポーネントとサーバーのレベル（Vitest）です。Tauri シェルと Rust router はコンパイル以外のテストがなく、ブラウザの end-to-end テストもカバレッジの閾値もありません。
|
||
- 音声入力には OpenAI 互換の STT エンドポイントが必要で、ブラウザでの自動テストはありません。
|
||
|
||
Issue と pull request は [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues) へ。PR の前に `npm run validate` を実行してください。
|
||
|
||
## ライセンス
|
||
|
||
GPL-3.0-only。[`LICENSE`](LICENSE) を参照してください。PiAgentUI は OpenCodeUI をフォークして作り直したもので、元の作者は `src-tauri/Cargo.toml` に記載されています。
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>作成: <a href="https://evandro.dev.br">Evandro Fonseca Junior</a> · <a href="https://git.evandro.dev.br/evandro">git.evandro.dev.br</a></sub>
|
||
</div>
|