docs(readme): redesenha o README com hero em SVG [skip ci]
This commit is contained in:
evandro committed
1 parent
8ce05620e0
commit
13b464b4d6
5 files changed
+403
-647
No files matched your search
+94
-172
@@ -1,214 +1,136 @@
|
||||
<p align="center">
|
||||
<img src="./src/assets/images/logo/PiAgentUiBlack%20%283%29.png" alt="PiAgentUI ロゴ" width="760" />
|
||||
</p>
|
||||
<div align="center">
|
||||
|
||||
# PiAgentUI
|
||||
<img src="assets/readme/hero.svg" width="100%" alt="PiAgentUI: 実際の Pi Agent セッションを扱うデスクトップ／Web ワークスペース。チャット、tool call カード、Files・Changes・MCP・Skills パネル">
|
||||
|
||||
[English (US)](./README.md) | [Português (BR)](./README.pt-BR.md) | [Español](./README.es.md) | **日本語**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
> この翻訳は基準となる [メイン README](./README.md) より古い可能性があります。リポジトリ: https://github.com/evandrodevbr/PiAgentUI
|
||||
[Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [設計 spec](docs/superpowers/specs/)
|
||||
|
||||
PiAgentUI は **Pi Agent** のためのモダンな Web / デスクトップ UI です。単なるチャット画面ではありません。最終的には Codex や Claude Desktop のような、エージェント中心の本格的な開発アプリになることを目指しています。
|
||||
[English](README.md) · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · **日本語**
|
||||
|
||||
PiAgentUI は、実際の Pi runtime を信頼できる唯一の情報源として扱います。セッション、モデルメタデータ、コンテキスト使用量、tool call、skills、MCP 設定、slash command は、可能な限り Pi から取得し、UI 側だけの仮の状態として再実装しません。
|
||||
</div>
|
||||
|
||||
> **プロジェクト状態:** アクティブなローカル開発中です。一部は製品に近い品質ですが、まだ高速に変化している領域もあります。
|
||||
|
||||
|
||||
## ソフトウェアプレビュー
|
||||
## 概要
|
||||
|
||||
以下のスクリーンショットは、現在の PiAgentUI の体験を示しています。実際の Pi セッション、モデル選択、MCP メタデータ、settings、ツール対応チャット、サイドパネルを備えた、暗色で集中しやすいエージェント workspace です。
|
||||
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 公開パッケージもありません。
|
||||
|
||||
- **ストリーミング対応チャット** — SSE によるライブ出力、安定したメッセージ同期、Markdown、コードハイライト、reasoning part、ツールカード。
|
||||
- **実際の Pi セッション** — セッション一覧、アクティブセッションへのルーティング、再起動後も安全な履歴読み込み、セッションタイトル生成、選択中セッションへの送信。
|
||||
- **ツール出力のカード表示** — tool calls/results は通常のチャット本文として漏れず、アシスタントメッセージに紐づいたカードとして表示されます。
|
||||
- **実 runtime のコンテキスト使用量** — 利用可能な場合は Pi runtime から取得し、不明または compacted な値は `NaN` ではなく安全に表示します。
|
||||
- **モデルメタデータ** — provider/model の実体は Pi が authoritative であり、ローカル OpenRouter カタログは context、output、modality、pricing、tokenizer などの補助情報としてのみ使います。
|
||||
- **Skills パネル** — 有効な Pi prompt から実際の skills を読み取り、global / project / package / other に分類します。
|
||||
- **MCP パネル** — ローカル/グローバル設定ファイルから MCP サーバーを読み取り、transport、command、URL、lifecycle、direct tools、source を表示します。
|
||||
- **Pi slash commands** — `/api/commands/list` が Pi の built-in commands と、extension / prompt / skill 由来の動的コマンドを公開します。
|
||||
- **マルチモーダル添付** — 選択中モデルの能力に応じて、ファイル、画像、PDF、音声、動画の添付 UI を表示します。
|
||||
- **ターミナルとファイル操作** — 統合ターミナル、ファイルエクスプローラー、syntax highlighting、diff 関連コンポーネント、Tauri デスクトップ連携。
|
||||
- **キーボード中心の UI** — command palette、カスタム keybindings、split panes、モデルセレクター、プロジェクト/セッションナビゲーション、レスポンシブレイアウト。
|
||||
## 仕組み
|
||||
|
||||
## プロダクトの方向性
|
||||
- `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 の前に立ちます。
|
||||
|
||||
PiAgentUI は、完全なエージェントアプリへ進化しています。
|
||||
## クイックスタート
|
||||
|
||||
1. **すべての Pi コマンドに視覚的な操作を提供** — slash commands は残しつつ、よく使う操作はボタン、メニュー、ダイアログ、パネルにします。
|
||||
2. **音声入力とリアルタイム文字起こし** — マイク録音、部分 transcript delta、最終 transcript の composer 挿入、OpenAI-compatible STT provider 設定。
|
||||
3. **より深い MCP 統合** — メタデータ表示だけでなく、接続、認証、ツール確認、MCP workflow 実行を UI から行えるようにします。
|
||||
4. **完全なセッション制御** — fork、clone、tree navigation、import/export/share、branch summary、context management をネイティブ UI として提供します。
|
||||
5. **デスクトップグレードの体験** — Tauri アプリとして、ローカル runtime discovery、安全な settings、通知、より豊かな workspace control を提供します。
|
||||
|
||||
## 音声と文字起こしのロードマップ
|
||||
|
||||
PiAgentUI は、選択中モデルが audio input をサポートしている場合、すでに音声ファイル添付を扱えます。計画中の voice system では、composer にリアルタイム speech-to-text を追加します。
|
||||
|
||||
推奨アーキテクチャ:
|
||||
|
||||
- **デフォルト realtime provider:** 低レイテンシの部分 transcript 用に OpenAI Realtime Transcription と `gpt-realtime-whisper` を使用。
|
||||
- **ファイル fallback:** OpenAI Audio Transcriptions の `gpt-4o-transcribe`、`gpt-4o-mini-transcribe`、または `whisper-1` を使用。
|
||||
- **カスタム provider:** `POST /v1/audio/transcriptions` を実装する OpenAI-compatible STT API をユーザーが設定可能。
|
||||
|
||||
計画中の UX:
|
||||
|
||||
- composer のマイクボタン;
|
||||
- 録音状態と権限状態;
|
||||
- 部分 transcript overlay;
|
||||
- 最終 transcript を input に挿入;
|
||||
- append / replace 動作の設定;
|
||||
- auto-send はデフォルト無効;
|
||||
- 権限、ネットワーク、provider エラーを復旧可能な形で表示。
|
||||
|
||||
provider 設定例:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "openai-compatible",
|
||||
"mode": "file",
|
||||
"baseUrl": "https://api.example.com/v1",
|
||||
"transcriptionEndpoint": "/audio/transcriptions",
|
||||
"transcriptionModel": "openai/whisper-large-v3",
|
||||
"language": "ja"
|
||||
}
|
||||
```
|
||||
|
||||
OpenAI-compatible な HTTP transcription は WebSocket 互換性を保証しないため、realtime support は別 capability として扱います。
|
||||
|
||||
## アーキテクチャ
|
||||
|
||||
```text
|
||||
PiAgentUI
|
||||
├─ React/Vite frontend
|
||||
│ ├─ chat, message rendering, input, panels, settings
|
||||
│ ├─ UI preferences 用の local stores
|
||||
│ └─ PiAgentUI local endpoints 用の SSE/API clients
|
||||
├─ Pi extension backend
|
||||
│ └─ extensions/piagentui-server.ts
|
||||
│ ├─ local /api/* endpoints を公開
|
||||
│ ├─ Pi runtime/session/model APIs への bridge
|
||||
│ ├─ Pi events を browser に stream
|
||||
│ └─ MCP config や skills などの local metadata を読み取り
|
||||
└─ Pi Agent runtime
|
||||
├─ sessions
|
||||
├─ models/providers
|
||||
├─ tools
|
||||
├─ skills
|
||||
├─ MCP
|
||||
└─ slash commands
|
||||
```
|
||||
|
||||
Pi がすでに知っている runtime state を UI が勝手に作るべきではありません。PiAgentUI は UX のために cache や enrichment を行えますが、agent behavior については Pi が authoritative です。
|
||||
|
||||
## 技術スタック
|
||||
|
||||
| 領域 | Stack |
|
||||
| ------------------- | --------------------------------------------- |
|
||||
| UI | React 19, TypeScript |
|
||||
| Build | Vite 8 |
|
||||
| Styling | Tailwind CSS v4 と project design tokens |
|
||||
| Desktop | Tauri 2 |
|
||||
| Markdown | Streamdown / markdown rendering pipeline |
|
||||
| Syntax highlighting | Shiki |
|
||||
| Terminal | xterm.js |
|
||||
| Tests | Vitest, Testing Library |
|
||||
| Local backend | Pi extension, Node HTTP server, WebSocket/SSE |
|
||||
|
||||
## ローカル開発
|
||||
|
||||
依存関係をインストール:
|
||||
| ツール | バージョン | 用途 |
|
||||
|---|---|---|
|
||||
| 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
|
||||
npm install
|
||||
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
|
||||
```
|
||||
|
||||
frontend dev server を起動:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
ビルド:
|
||||
`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 test:run
|
||||
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` もこれを使います。
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run typecheck:extensions
|
||||
```
|
||||
## 設定
|
||||
|
||||
完全な検証:
|
||||
コンテナ構成は OpenCodeUI のデプロイから引き継いだものです。最初に `.env.example` を `.env` にコピーしてください。
|
||||
|
||||
```bash
|
||||
npm run validate
|
||||
```
|
||||
| ファイル | コマンド | 内容 |
|
||||
|---|---|---|
|
||||
| `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 をローカルでビルドします。 |
|
||||
|
||||
## Pi extension runtime
|
||||
<details>
|
||||
<summary>環境変数（コンテナ構成のみ）</summary>
|
||||
|
||||
PiAgentUI は `package.json` で Pi extension として登録されています。
|
||||
| 変数 | 必須 | 説明 |
|
||||
|---|---|---|
|
||||
| `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。 |
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"extensions": ["./extensions/piagentui-server.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
extension 起動時、ローカル discovery metadata が以下に書き込まれます。
|
||||
## プロジェクトの状態
|
||||
|
||||
```text
|
||||
~/.pi/agent/piagentui-port.json
|
||||
```
|
||||
1.0 前のベータ版（`0.6.10`）で、開発者 1 人がメンテナンスしています。リリースは `v*` タグで `release.yml` がビルドし（Windows、macOS、Linux、Android の成果物）、`deploy.yml` が `VITE_BASE_PATH=/PiAgentUI/` で Web 版を公開します。
|
||||
|
||||
Web アプリはこのファイルの port/token を使ってローカル extension server と通信します。一部の backend 変更は、ブラウザに反映される前に Pi extension process の再起動または reload が必要です。
|
||||
- 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 エンドポイントが必要で、ブラウザでの自動テストはありません。
|
||||
|
||||
## 重要なローカル endpoints
|
||||
|
||||
| Endpoint | 目的 |
|
||||
| -------------------------------- | --------------------------------------------------- |
|
||||
| `GET /api/models` | Pi の実モデル一覧と正規化された capability metadata |
|
||||
| `GET /api/sessions` | Pi session files から読み取ったセッション一覧 |
|
||||
| `GET /api/sessions/:id/messages` | UI rendering 用に正規化されたセッション履歴 |
|
||||
| `GET /api/sessions/:id/context` | active session の runtime context usage |
|
||||
| `POST /api/messages/send` | 指定された Pi session にユーザーメッセージを送信 |
|
||||
| `GET /api/skills` | 有効な Pi skills を source ごとに分類 |
|
||||
| `GET /api/mcp/status` | 設定済み MCP servers の metadata |
|
||||
| `GET /api/commands/list` | Pi built-in / dynamic slash commands |
|
||||
| `GET /global/event` | PiAgentUI backend からの SSE event stream |
|
||||
|
||||
## 開発原則
|
||||
|
||||
- UI-only の仮状態よりも、Pi runtime の実データを優先する。
|
||||
- OpenRouter は catalog enrichment としてのみ使い、Pi の provider/model identity を置き換えない。
|
||||
- 不明な runtime 値は明示的に扱う。
|
||||
- 振る舞いを変える場合は、可能な限り先にテストを書く。
|
||||
- tool results は tool cards 内に保持する。
|
||||
- 既存の theme、motion、spacing、panel patterns に合わせる。
|
||||
- 実装済み機能と roadmap を明確に分ける。
|
||||
|
||||
## リポジトリノート
|
||||
|
||||
このプロジェクトには、元の OpenCodeUI ベースから継承した名前が一部残っています。package metadata や古い documentation などです。現在の方向性は PiAgentUI-first であり、将来的な cleanup ではローカル workflow を壊さずに残りの名称を移行する必要があります。
|
||||
Issue と pull request は [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues) へ。PR の前に `npm run validate` を実行してください。
|
||||
|
||||
## ライセンス
|
||||
|
||||
このリポジトリは `package.json` に記載されているライセンス `GPL-3.0-only` に従います。
|
||||
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>
|
||||
Reference in new issue
Block a user