137 lines
9.4 KiB
Markdown
137 lines
9.4 KiB
Markdown
<div align="center">
|
|
|
|
<img src="assets/readme/hero.svg" width="100%" alt="PiAgentUI: workspace de escritorio y web para sesiones reales de Pi Agent, con chat, tarjetas de tool calls y el panel Files, Changes, MCP y Skills">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [Specs de diseño](docs/superpowers/specs/)
|
|
|
|
[English](README.md) · [Português (BR)](README.pt-BR.md) · **Español** · [日本語](README.ja.md)
|
|
|
|
</div>
|
|
|
|
|
|
|
|
## Qué es
|
|
|
|
PiAgentUI es una interfaz de chat y un workspace para el [agente de código Pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent). Funciona como app web servida por una extensión de Pi o como app de escritorio con Tauri 2, y muestra en una ventana lo que una terminal sola esconde: la lista de sesiones, las tool calls, los servidores MCP, las skills y el uso de contexto.
|
|
|
|
- Transmite sesiones reales de Pi por SSE (`/global/event`) y renderiza Markdown, código (Shiki) y matemáticas (KaTeX).
|
|
- Muestra las tool calls como tarjetas y el uso de contexto de la sesión activa.
|
|
- Cambia de modelo con las capacidades que informa el runtime.
|
|
- Lista los servidores MCP configurados (transporte, comando, URL, origen) y las skills efectivas agrupadas por origen.
|
|
- Expone slash commands integrados y dinámicos, además de controles de Git en el composer.
|
|
- Integra una terminal (xterm.js) y un explorador de archivos junto al chat.
|
|
- Acepta entrada de voz mediante un endpoint STT compatible con OpenAI configurado en settings.
|
|
- Idiomas de la interfaz: `en`, `pt-BR`, `es`, `zh-CN`, `hi`, `bn`, `ar` (`src/locales/`).
|
|
|
|
## Por qué usarlo
|
|
|
|
PiAgentUI no guarda estado propio del agente. Sesiones, modelos, tools, skills y comandos vienen del runtime de Pi a través de la extensión, así que lo que ves es lo que Pi está ejecutando.
|
|
|
|
No lo uses si no ejecutas Pi: sin la extensión, la interfaz solo muestra el diálogo de conexión al servidor. También atiende un runtime por ventana y no tiene demo alojada ni paquete publicado en npm.
|
|
|
|
## Cómo funciona
|
|
|
|
- `extensions/piagentui-server.ts` es la extensión de Pi. Sirve la UI compilada desde `dist/` con `http` + `ws` de Node e inyecta `window.PI_BOOT_DATA` (URL base y token).
|
|
- Al arrancar escucha en el puerto `58785` (o el siguiente libre) y escribe el puerto y un token aleatorio en `~/.pi/agent/piagentui-port.json`.
|
|
- `GET /global/health` es abierto; las demás rutas `/api/*` exigen `Authorization: Bearer <token>`. El socket escucha en `0.0.0.0`, pero cada petición se valida contra loopback salvo que el acceso por LAN en `/api/network/access` esté activado (viene desactivado).
|
|
- La app Tauri lee el mismo archivo de descubrimiento con el comando `get_pi_agent_connection`, así que el build de escritorio se conecta al runtime local sin configuración manual.
|
|
- En contenedores, el router en Rust (`src-router/`, axum) va detrás de Caddy como gateway delante de los servicios de frontend y backend.
|
|
|
|
## Inicio rápido
|
|
|
|
| Herramienta | Versión | Necesaria para |
|
|
|---|---|---|
|
|
| Node.js | `>=22` (`.tool-versions`: 22.22.0) | todo |
|
|
| npm | la que trae Node | todo (`package-lock.json`) |
|
|
| Rust | `1.85.0` (`.tool-versions`) | app de escritorio y router del gateway |
|
|
| Docker Compose | reciente | solo el stack de contenedores |
|
|
| Pi Agent | instalado localmente | sesiones y modelos reales |
|
|
|
|
```bash
|
|
git clone https://git.evandro.dev.br/evandro/PiAgentUI.git
|
|
cd PiAgentUI
|
|
npm ci # el postinstall ejecuta scripts/copy-material-icons.mjs
|
|
npm run build # tsc -b && vite build -> dist/
|
|
npm run dev # servidor Vite en http://localhost:5173
|
|
```
|
|
|
|
`npm run dev` es solo el front end: hace proxy de `/api` a `127.0.0.1:4096` sin el prefijo. Para el flujo con Pi, compila primero y deja que la extensión sirva `dist/` (Pi carga este repositorio como paquete mediante el campo `pi.extensions` de `package.json`):
|
|
|
|
```bash
|
|
npm run build
|
|
cat ~/.pi/agent/piagentui-port.json # {"port": 58785, "token": "..."}
|
|
# abre http://127.0.0.1:58785
|
|
```
|
|
|
|
Escritorio y Android:
|
|
|
|
```bash
|
|
npm run tauri dev # ventana de escritorio sobre el servidor Vite
|
|
npm run tauri build # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json)
|
|
npm run tauri android dev # ver scripts/dev-android.sh
|
|
```
|
|
|
|
Antes de un PR, `npm run validate` ejecuta typecheck, typecheck de la extensión, lint, build y tests; es el gate que corre el CI en `build.yml`.
|
|
|
|
## Configuración
|
|
|
|
El stack de contenedores viene heredado del despliegue de OpenCodeUI. Copia `.env.example` a `.env` primero.
|
|
|
|
| Archivo | Comando | Qué hace |
|
|
|---|---|---|
|
|
| `docker-compose.yml` | `docker compose up -d` | Stack completo: `gateway` (Caddy + router en Rust, `127.0.0.1:6658` y `6659`), `frontend`, `backend` (`opencode serve`, 4096, límite de 4G de memoria). |
|
|
| `docker-compose.standalone.yml` | `docker compose -f docker-compose.standalone.yml up -d` | Solo el front end, para un `opencode serve` existente. Usa `BACKEND_URL` (por defecto `host.docker.internal:4096`) y `PORT` (por defecto `3000`). |
|
|
| `docker-compose.host.yml` | `docker compose -f docker-compose.yml -f docker-compose.host.yml up -d` | Override opcional: el `backend` corre privilegiado, con el socket de Docker y el `/` del host montado en `/host`. |
|
|
| `docker-compose.build.yml` | `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` | Override opcional: compila gateway, frontend y backend localmente desde `docker/`. |
|
|
|
|
<details>
|
|
<summary>Variables de entorno (solo para el stack de contenedores)</summary>
|
|
|
|
| Variable | Obligatoria | Descripción |
|
|
|---|---|---|
|
|
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY` | Al menos una | Claves de proveedores de LLM que se pasan al contenedor del backend. |
|
|
| `GATEWAY_PORT` | No (`6658`) | Puerto del host para el punto de entrada unificado. |
|
|
| `PREVIEW_PORT` | No (`6659`) | Puerto del host para el punto de entrada de previews. |
|
|
| `PREVIEW_DOMAIN` | No | Dominio aparte para previews; el proxy inverso lo reenvía a `PREVIEW_PORT`. |
|
|
| `WORKSPACE` | No (`./workspace`) | Carpeta del host montada en `/workspace` en el backend. |
|
|
| `OPENCODE_SERVER_PASSWORD` | En despliegues públicos | Contraseña del backend y del router. |
|
|
| `OPENCODE_SERVER_USERNAME` | No (`opencode`) | Usuario que acompaña a la contraseña anterior. |
|
|
| `PUBLIC_BASE_URL` | No | URL base pública que usa el router integrado en el gateway. |
|
|
| `ROUTER_SCAN_INTERVAL` | No (`5`) | Intervalo de escaneo del router. |
|
|
| `ROUTER_TOKEN_LENGTH` | No (`12`) | Longitud de los tokens de ruta generados. |
|
|
| `ROUTER_PORT_RANGE` | No (`3000-9999`) | Rango de puertos que atiende el router. |
|
|
| `ROUTER_EXCLUDE_PORTS` | No (`4096`) | Puertos que el router omite. |
|
|
| `DOCKER_API_VERSION` | No (`1.40`) | Versión de la API de Docker para el backend; se define en `docker-compose.yml`, no en `.env.example`. |
|
|
| `USE_CHINA_MIRROR` | No (`1`) | Opción de build de la imagen del backend: usa los mirrors de abajo. |
|
|
| `APT_MIRROR`, `APT_SECURITY_MIRROR`, `NPM_CONFIG_REGISTRY`, `NODEJS_ORG_MIRROR`, `PIP_INDEX_URL`, `PIP_TRUSTED_HOST` | No | Mirrors para el toolchain del backend. |
|
|
| `MISE_INSTALL_URL`, `OPENCODE_INSTALL_URL` | No | URLs de instalación usadas al compilar la imagen del backend. |
|
|
|
|
</details>
|
|
|
|
## Estado del proyecto
|
|
|
|
Beta, antes de la 1.0 (`0.6.10`), mantenido por un desarrollador. Las releases salen de `release.yml` en tags `v*` (artefactos para Windows, macOS, Linux y Android); `deploy.yml` publica el build web con `VITE_BASE_PATH=/PiAgentUI/`.
|
|
|
|
- El nombre OpenCodeUI no ha desaparecido del todo: el crate del router en Rust es `opencodeui-router`, las imágenes son `opencodeui-*`, los APK de Android salen como `OpenCodeUI-*`, los comentarios de `.env.example` están en chino y el backend Docker ejecuta `opencode serve`, que pertenece al despliegue heredado, no al flujo con la extensión de Pi.
|
|
- `docker-compose.yml` y `docker-compose.standalone.yml` todavía descargan la imagen upstream `ghcr.io/lehhair/opencodeui-frontend`.
|
|
- Los tests son de componente y de servidor (Vitest). No hay tests del shell Tauri ni del router en Rust más allá de la compilación, ni test end-to-end en navegador, ni umbral de cobertura.
|
|
- La entrada de voz necesita un endpoint STT compatible con OpenAI y no tiene test automatizado en navegador.
|
|
|
|
Issues y pull requests van al [issue tracker](https://git.evandro.dev.br/evandro/PiAgentUI/issues); ejecuta `npm run validate` antes de abrir un PR.
|
|
|
|
## Licencia
|
|
|
|
GPL-3.0-only, ver [`LICENSE`](LICENSE). PiAgentUI es un fork reelaborado de OpenCodeUI; el autor original figura en `src-tauri/Cargo.toml`.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<sub>Hecho por <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>
|