evandro/PiAgentUI
1
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): redesenha o README com hero em SVG [skip ci]

Browse Source
This commit is contained in:
evandro committed 2026-10-24 04:57:55 -03:00
1 parent 8ce05620e0
commit 13b464b4d6
5 files changed
+403 -647
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.es.md
+94 -172
View File
@@ -1,214 +1,136 @@
<p align="center">
<img src="./src/assets/images/logo/PiAgentUiBlack%20%283%29.png" alt="Logo de PiAgentUI" width="760" />
</p>
<div align="center">
# PiAgentUI
<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">
[English (US)](./README.md) | [Português (BR)](./README.pt-BR.md) | **Español** | [日本語](./README.ja.md)
![TypeScript 5.9](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)
![React 19](https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black)
![Tauri 2](https://img.shields.io/badge/Tauri-2-24C8DB?style=flat-square&logo=tauri&logoColor=white)
![Licencia GPL-3.0-only](https://img.shields.io/badge/licencia-GPL--3.0--only-blue?style=flat-square)
![Estado beta 0.6.10](https://img.shields.io/badge/estado-beta%200.6.10-yellow?style=flat-square)
> Esta traducción puede quedar por detrás de la versión de referencia, que es el [README principal](./README.md). Repositorio: https://github.com/evandrodevbr/PiAgentUI
[Issues](https://git.evandro.dev.br/evandro/PiAgentUI/issues) · [Changelog](CHANGELOG.md) · [Specs de diseño](docs/superpowers/specs/)
PiAgentUI es una interfaz moderna web y de escritorio para **Pi Agent**. No es solo una capa visual de chat: el objetivo es convertirse en una aplicación completa de agentes, en la misma categoría de producto que Codex, Claude Desktop y otros entornos de desarrollo agent-first.
[English](README.md) · [Português (BR)](README.pt-BR.md) · **Español** · [日本語](README.ja.md)
PiAgentUI trata el runtime real de Pi como la fuente de verdad. Sesiones, metadatos de modelos, uso de contexto, tool calls, skills, configuración MCP y slash commands vienen de Pi siempre que sea posible, en lugar de recrearse como estado falso de interfaz.
</div>
> **Estado del proyecto:** desarrollo local activo. Algunas áreas ya son cercanas a producto, mientras otras siguen cambiando rápidamente.
![Workspace de chat de PiAgentUI: lista de sesiones a la izquierda, una respuesta en Markdown con un bloque JSON en el centro y el panel de servidores MCP a la derecha](src/assets/images/img1.png)
## Demostración del software
## Qué es
Estas capturas muestran la experiencia actual de PiAgentUI: un workspace oscuro y enfocado para agentes, con sesiones reales de Pi, selección de modelos, metadatos MCP, settings, chat con herramientas y paneles laterales.
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.
![Workspace de chat de PiAgentUI con panel lateral MCP](./src/assets/images/img1.png)
- 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/`).
![Diálogo de settings y conexiones de servidor de PiAgentUI](./src/assets/images/img2.png)
## Por qué usarlo
![Selector de modelos de PiAgentUI dentro de una sesión activa](./src/assets/images/img3.png)
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.
## Qué hace PiAgentUI hoy
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.
- **Chat con streaming** — salida en vivo por SSE, reconciliación estable de mensajes, markdown, resaltado de código, partes de razonamiento y tarjetas de herramientas.
- **Sesiones reales de Pi** — lista de sesiones, enrutamiento a la sesión activa, historial seguro tras reinicio, títulos derivados y envío a la sesión seleccionada.
- **Salida de herramientas en tarjetas** — tool calls/results quedan anexados a los mensajes del asistente, sin filtrarse como texto normal en el chat.
- **Uso real de contexto** — el uso de contexto viene del runtime de Pi cuando está disponible; el contexto desconocido/compactado se muestra de forma segura en lugar de `NaN`.
- **Metadatos de modelos** — la identidad de provider/modelo viene de Pi; el catálogo local de OpenRouter se usa solo como enriquecimiento de detalles.
- **Panel de Skills** — las skills reales se leen del prompt efectivo de Pi y se agrupan por origen: global, project, package y other.
- **Panel MCP** — lee servidores MCP configurados en archivos locales/globales y muestra transporte, comando, URL, lifecycle, direct tools y origen.
- **Slash commands de Pi** — `/api/commands/list` expone comandos built-in de Pi y comandos dinámicos de extensiones, prompts y skills.
- **Adjuntos multimodales** — soporte visual para archivos/imágenes/PDF/audio/video según las capacidades del modelo seleccionado.
- **Terminal y archivos** — terminal integrado, explorador de archivos, syntax highlighting, componentes de diff e integración de escritorio con Tauri.
- **UI keyboard-first** — command palette, atajos configurables, split panes, selector de modelo, navegación por proyecto/sesión y layouts responsivos.
## Cómo funciona
## Dirección del producto
- `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.
PiAgentUI está evolucionando hacia una aplicación completa de agentes:
## Inicio rápido
1. **Acciones visuales para todos los comandos de Pi** — los slash commands siguen disponibles, pero las acciones frecuentes deben convertirse en botones, menús, diálogos o paneles.
2. **Entrada por voz y transcripción en tiempo real** — grabación de micrófono, deltas parciales, inserción de la transcripción final en el composer y configuración de proveedores STT OpenAI-compatible.
3. **Integración MCP más profunda** — más allá de metadatos: conectar, autenticar, inspeccionar herramientas y ejecutar workflows MCP desde la UI.
4. **Control completo de sesiones** — fork, clone, navegación en árbol, import/export/share, branch summaries y gestión de contexto como flujos nativos.
5. **Experiencia de escritorio completa** — app Tauri pulida con descubrimiento local de runtime, settings seguros, notificaciones y controles ricos de workspace.
## Roadmap de audio y transcripción
PiAgentUI ya acepta adjuntos de audio cuando el modelo seleccionado declara soporte de entrada de audio. El sistema de voz planeado añade speech-to-text en vivo directamente en el composer.
Arquitectura recomendada:
- **Proveedor realtime por defecto:** OpenAI Realtime Transcription con `gpt-realtime-whisper` para transcripción parcial de baja latencia.
- **Fallback por archivo:** OpenAI Audio Transcriptions con `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` o `whisper-1`.
- **Proveedores personalizados:** APIs STT OpenAI-compatible configurables por el usuario, como proveedores que implementan `POST /v1/audio/transcriptions`.
UX planeada:
- botón de micrófono en el composer;
- estados de grabación y permisos;
- overlay de transcripción parcial;
- texto final insertado en el input;
- comportamiento configurable de append/replace;
- auto-send desactivado por defecto;
- manejo recuperable de errores de permisos, red y proveedor.
Ejemplo de configuración de proveedor:
```json
{
"kind": "openai-compatible",
"mode": "file",
"baseUrl": "https://api.example.com/v1",
"transcriptionEndpoint": "/audio/transcriptions",
"transcriptionModel": "openai/whisper-large-v3",
"language": "es"
}
```
El soporte realtime se trata como una capability separada, porque la compatibilidad HTTP con OpenAI no garantiza compatibilidad WebSocket.
## Arquitectura
```text
PiAgentUI
├─ Frontend React/Vite
│ ├─ chat, renderizado de mensajes, input, paneles y settings
│ ├─ stores locales para preferencias de UI
│ └─ clientes SSE/API para endpoints locales de PiAgentUI
├─ Backend como extensión Pi
│ └─ extensions/piagentui-server.ts
│ ├─ expone endpoints locales /api/*
│ ├─ conecta con runtime/sesiones/modelos de Pi
│ ├─ transmite eventos de Pi al navegador
│ └─ lee metadatos locales como MCP config y skills
└─ Runtime Pi Agent
├─ sesiones
├─ modelos/providers
├─ herramientas
├─ skills
├─ MCP
└─ slash commands
```
La UI no debe inventar estado de runtime cuando Pi ya conoce la respuesta. PiAgentUI puede cachear y enriquecer datos para UX, pero Pi sigue siendo autoritativo para el comportamiento del agente.
## Stack técnico
| Área | Stack |
| ------------------- | --------------------------------------------- |
| UI | React 19, TypeScript |
| Build | Vite 8 |
| Estilo | Tailwind CSS v4 y design tokens del proyecto |
| Escritorio | Tauri 2 |
| Markdown | Streamdown / pipeline de markdown |
| Syntax highlighting | Shiki |
| Terminal | xterm.js |
| Tests | Vitest, Testing Library |
| Backend local | Extensión Pi, Node HTTP server, WebSocket/SSE |
## Desarrollo local
Instalar dependencias:
| 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
npm install
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
```
Iniciar el frontend en modo dev:
```bash
npm run dev
```
Build:
`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
```
Tests:
Escritorio y Android:
```bash
npm run test:run
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
```
Type checks:
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`.
```bash
npm run typecheck
npm run typecheck:extensions
```
## Configuración
Validación completa:
El stack de contenedores viene heredado del despliegue de OpenCodeUI. Copia `.env.example` a `.env` primero.
```bash
npm run validate
```
| 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/`. |
## Runtime de la extensión Pi
<details>
<summary>Variables de entorno (solo para el stack de contenedores)</summary>
PiAgentUI se registra como extensión Pi en `package.json`:
| 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. |
```json
{
"pi": {
"extensions": ["./extensions/piagentui-server.ts"]
}
}
```
</details>
Cuando la extensión arranca, escribe metadatos de descubrimiento local en:
## Estado del proyecto
```text
~/.pi/agent/piagentui-port.json
```
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/`.
La app web usa el puerto/token de ese archivo para hablar con el servidor local de la extensión. Algunos cambios de backend requieren reiniciar o recargar el proceso de la extensión Pi antes de verse en el navegador.
- 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.
## Endpoints locales importantes
| Endpoint | Propósito |
| -------------------------------- | ---------------------------------------------------------- |
| `GET /api/models` | Lista real de modelos Pi con capacidades normalizadas |
| `GET /api/sessions` | Lista de sesiones leída desde los archivos de sesión de Pi |
| `GET /api/sessions/:id/messages` | Historial normalizado para renderizado en la UI |
| `GET /api/sessions/:id/context` | Uso de contexto runtime para la sesión activa |
| `POST /api/messages/send` | Envía un mensaje a la sesión Pi solicitada |
| `GET /api/skills` | Skills efectivas de Pi agrupadas por origen |
| `GET /api/mcp/status` | Metadatos de servidores MCP configurados |
| `GET /api/commands/list` | Slash commands built-in y dinámicos de Pi |
| `GET /global/event` | Stream SSE de eventos del backend PiAgentUI |
## Principios de desarrollo
- Preferir datos reales del runtime Pi en vez de estado falso solo de UI.
- Mantener OpenRouter como enriquecimiento de catálogo, nunca como sustituto de la identidad provider/modelo de Pi.
- Tratar valores runtime desconocidos explícitamente.
- Escribir tests antes de cambios de comportamiento siempre que sea posible.
- Mantener tool results dentro de tarjetas de herramienta.
- Seguir el sistema visual existente: tema, movimiento, espaciado y patrones de paneles.
- Separar claramente lo implementado del roadmap.
## Notas del repositorio
El proyecto todavía contiene nombres heredados de la base original OpenCodeUI en algunos puntos, incluyendo metadatos del paquete y documentación antigua. La dirección actual es PiAgentUI-first, y una limpieza futura debe migrar esos nombres sin romper los workflows locales.
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
Este repositorio sigue la licencia declarada en `package.json`: `GPL-3.0-only`.
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>