Herramientas de desarrollo

Pi Web en Windows: gestiona sesiones, modelos y worktrees de Pi Coding Agent

Instala Pi Web en Windows, configura el proxy y el puerto, y gestiona sesiones, modelos, Skills, archivos de proyecto y Git worktrees de Pi Coding Agent.

Pi Web es la interfaz web nativa de Pi Coding Agent. No transforma a Pi en otro agente de la nube. En cambio, lee archivos de sesión Pi existentes en la máquina local y muestra conversaciones, llamadas de herramientas, uso de contexto, configuración del modelo, habilidades y archivos de proyecto en el navegador.

Dirección del proyecto:

https://github.com/agegr/pi-web

El escenario para el que es adecuado es claro: ya estás usando el Pi, pero no quieres desplazarte por el historial de sesiones en el terminal todo el tiempo, o quieres continuar con la misma tarea del Agente mientras miras el archivo del proyecto.

Confirmar antes de la instalación

En Windows, prepare:

  • Node.js y npm;
  • Agente de codificación Pi que ya se encuentra en uso normal;
  • PowerShell o Terminal de Windows;
  • Un directorio de proyectos gestionado por Git.

Verifique Node.js:

1
2

node --version
npm --version

Pi Web lee por defecto:

1

~/.pi/agent/sessions

Si el Pi no ha generado ninguna sesión, se puede iniciar la página web, pero la lista de sesiones puede estar vacía.

Ejecutar directamente sin instalación

La forma más sencilla es utilizar npx:

1

npx @agegr/pi-web@latest

Una vez iniciado el servicio, intentará abrir el navegador automáticamente. La dirección predeterminada es:

1

http://localhost:30141

Este método es adecuado para la primera experiencia. No es necesario instalar permanentemente el comando en el directorio global npm.

Instalación global

Se puede ejecutar con frecuencia:

1
2

npm install -g @agegr/pi-web
pi-web

Si PowerShell indica que no se puede encontrar pi-web, verifique si el directorio global npm está en PATH:

1
2

npm config get prefix
Get-Command pi-web -ErrorAction SilentlyContinue

Después de modificar PATH, debe volver a abrir la terminal.

Modificar puerto y dirección de escucha

Cuando se usa solo en esta máquina de forma predeterminada, se recomienda vincular explícitamente la dirección de bucle invertido:

1

pi-web --hostname 127.0.0.1

Modificar puerto:

1

pi-web --port 8080

Uso en combinación:

1

pi-web -p 8080 -H 127.0.0.1

Como servicio en segundo plano, no desea que el navegador se abra automáticamente:

1

pi-web --no-open

No vincule directamente 0.0.0.0 y abra el puerto de red pública solo para acceder desde su teléfono móvil. Pi Web puede leer sesiones del Agente, archivos de proyectos y configuraciones de modelos, que pueden incluir código fuente, rutas de archivos, palabras de aviso y resultados de herramientas.

Configurar el proxy HTTP

Pi Web lee variables de entorno de proxy estándar. Ejemplo de Windows PowerShell:

1
2
3
4

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest

Estas variables solo tienen efecto dentro de la sesión actual de PowerShell. NO_PROXY es muy importante; de ​​lo contrario, también puede enviarse al proxy al acceder al servicio local.

¿Qué hacer si no se puede encontrar la sesión Pi?

Pi Web lee sesiones JSONL de ~/.pi/agent/sessions de forma predeterminada. Si su directorio de datos Pi no está en la ubicación predeterminada, configure:

1
2

$env:PI_CODING_AGENT_DIR = "D:\pi-data"
pi-web

Primero verifique si el directorio realmente existe:

1
2

Test-Path "$HOME\.pi\agent\sessions"
Get-ChildItem "$HOME\.pi\agent\sessions" -Directory

Las sesiones están organizadas por directorio de trabajo del proyecto. Si el mismo repositorio se ha abierto desde diferentes letras de unidad, enlaces suaves o rutas WSL, es posible que se reconozca como proyectos diferentes.

¿Qué se puede gestionar en la página web?

Pi Web proporciona principalmente estas funciones:

  • Explorar sesiones anteriores de Pi por proyecto;
  • Continuar, bifurcar o crear nuevas ramas a partir de mensajes antiguos;
  • Ver Markdown, llamadas de herramientas y estado de compresión contextual;
  • Ver el código fuente del proyecto, documentos, imágenes, audio y PDF;
  • Administrar modelos, información de inicio de sesión, clave API y pruebas de modelos;
  • Activar o desactivar Habilidades;
  • Cambiar entre árboles de trabajo de Git.

Lee y escribe la configuración y la sesión de Pi local, no una copia separada del estado de la nube. Antes de modificar la configuración del modelo o las ramas de la sesión, es una buena idea hacer una copia de seguridad del directorio .pi.

¿Cuál es la diferencia entre bifurcación y bifurcación intrasesión?

Fork en Pi Web crea un nuevo archivo de sesión JSONL, adecuado para probar otra ruta de implementación desde un nodo mientras se conserva la sesión original.

“Editar desde aquí” crea una rama dentro del mismo archivo de sesión. Es más liviano, pero menos intuitivo de organizar y migrar que los archivos independientes.

Si desea comparar dos implementaciones o transferirlas a diferentes árboles de trabajo, bifurque primero; solo para corregir un mensaje o volver al paso anterior, utilice la bifurcación dentro de la sesión.

Cooperar con Git Worktree

Worktree es adecuado para permitir que diferentes sesiones de Agente procesen diferentes ramas en directorios de trabajo independientes para evitar modificar el mismo archivo al mismo tiempo.

Primero cree un Worktree en el repositorio principal:

1
2

git worktree add ..\my-project-feature -b feature/pi-test
git worktree list

La barra lateral de Pi Web puede alternar entre los árboles de trabajo reconocidos y permitir que nuevas sesiones y exploradores de archivos sigan los directorios correspondientes.

Una vez completado, primero confirme que se haya enviado el contenido de la rama y luego elimínelo:

1
2

git worktree remove ..\my-project-feature
git branch -d feature/pi-test

No fuerce la eliminación de Worktree cuando existan modificaciones no confirmadas.

Preguntas frecuentes

La página se abre pero no hay historial.

Compruebe que PI_CODING_AGENT_DIR, el directorio de sesiones predeterminado y el usuario actual de Windows sean correctos. Ejecutarlo una vez como administrador y otra vez como usuario normal también puede producir dos conjuntos diferentes de directorios de usuarios.

El puerto está ocupado

Cambiar un puerto:

1

pi-web --port 30142

O consultar procesos ocupados:

1

Get-NetTCPConnection -LocalPort 30141 -ErrorAction SilentlyContinue

Error en la solicitud de modelo

Primero confirme que se puede usar el mismo modelo en Pi CLI y luego verifique si el proceso web de Pi hereda las variables de proxy y la clave API. Si se puede abrir la página web, solo significa que el servicio local es normal, pero no significa que el proveedor del modelo se haya conectado correctamente.

El archivo del proyecto no se puede ver

El alcance de la vista previa del archivo está limitado por el directorio del proyecto seleccionado y el directorio de trabajo de la sesión. Confirme que la sesión realmente se inició desde el repositorio de destino y no ingrese al proyecto mediante una asignación de letras de unidad inconsistente o enlaces suaves.

Recomendaciones de seguridad

Pi Web toca configuraciones de modelos, sesiones de agentes y archivos de proyectos. sugerencia:

  1. Enlace predeterminado 127.0.0.1;
  2. No asigne el puerto directamente a la red pública;
  3. No exponga la clave API, las palabras clave ni el código fuente privado en capturas de pantalla;
  4. Haga una copia de seguridad del directorio de sesiones de Pi con regularidad;
  5. Verifique las modificaciones no confirmadas antes de cambiar o eliminar Worktree;
  6. Confirme primero las políticas de uso de datos de código y modelo en los proyectos de la empresa.

Pi Web es más adecuado para que los usuarios existentes de Pi mejoren la gestión de sesiones. Si solo está buscando un agente que pueda escribir código, primero debe ejecutar el modelo CLI de Pi, los permisos y el flujo de trabajo básico antes de instalar la interfaz web.