Paquetes Pi

pi puede crear paquetes pi. Pídele que empaquete tus extensiones, habilidades, plantillas de prompts o temas.

Paquetes Pi

Los paquetes Pi agrupan extensiones, habilidades, plantillas de prompts y temas para compartirlos mediante npm o git. Un paquete puede declarar recursos en package.json bajo la clave pi, o usar directorios convencionales.

Instalar y gestionar

Seguridad: Los paquetes Pi se ejecutan con acceso completo al sistema. Las extensiones ejecutan código arbitrario, y las habilidades pueden instruir al modelo a realizar cualquier acción, incluida la ejecución de ejecutables. Revisa el código fuente antes de instalar paquetes de terceros.

pi install npm:@foo/[email protected]
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw URLs work too
pi install /absolute/path/to/package
pi install ./relative/path/to/package

pi remove npm:@foo/bar
pi list                     # show installed packages from settings
pi update                   # update pi only
pi update --all             # update pi, update packages, and reconcile pinned git refs
pi update --extensions      # update packages and reconcile pinned git refs only
pi update --self            # update pi only
pi update --self --force    # reinstall pi even if current
pi update npm:@foo/bar      # update one package
pi update --extension npm:@foo/bar

Estos comandos gestionan paquetes pi y pi update puede actualizar la instalación del CLI pi. Para desinstalar pi, consulta Inicio rápido.

Por defecto, install y remove escriben en la configuración de usuario (~/.pi/agent/settings.json). Usa -l para escribir en la configuración del proyecto (.pi/settings.json). La configuración del proyecto puede compartirse con tu equipo, y pi instala automáticamente los paquetes faltantes al iniciar después de que el proyecto sea de confianza.

Para probar un paquete sin instalarlo, usa --extension o -e. Esto instala en un directorio temporal solo para la ejecución actual:

pi -e npm:@foo/bar
pi -e git:github.com/user/repo

Fuentes de paquetes

Pi acepta tres tipos de fuente en la configuración y en pi install.

npm

npm:@scope/[email protected]
npm:pkg

Las especificaciones con versión se fijan y se omiten en actualizaciones de paquetes (pi update --extensions, pi update --all).
Las instalaciones de usuario van bajo ~/.pi/agent/npm/.
Las instalaciones de proyecto van bajo .pi/npm/.
Establece npmCommand en settings.json para fijar búsqueda e instalación de paquetes npm a un comando contenedor específico como mise o asdf.

Ejemplo:

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

git

git:github.com/user/repo@v1
git:[email protected]:user/repo@v1
https://github.com/user/repo@v1
ssh://[email protected]/user/repo@v1

Sin prefijo git:, solo se aceptan URLs con protocolo (https://, http://, ssh://, git://).
Con prefijo git:, se aceptan formatos abreviados, incluidos github.com/user/repo y [email protected]:user/repo.
Se admiten URLs HTTPS y SSH.
Las URLs SSH usan tus claves SSH configuradas automáticamente (respeta ~/.ssh/config).
Para ejecuciones no interactivas (por ejemplo CI), puedes establecer GIT_TERMINAL_PROMPT=0 para deshabilitar solicitudes de credenciales y GIT_SSH_COMMAND (por ejemplo ssh -o BatchMode=yes -o ConnectTimeout=5) para fallar rápido.
Las refs son tags o commits fijados. pi update --extensions y pi update --all no las mueven a refs más nuevas, pero reconcilian un clon existente con la ref configurada.
Usa pi install git:host/user/repo@new-ref para actualizar la configuración y mover un paquete existente a una nueva ref fijada.
Clonado en ~/.pi/agent/git/<host>/<path> (global) o .pi/git/<host>/<path> (proyecto).
Cuando la reconciliación cambia el checkout, pi resetea y limpia el clon, luego ejecuta npm install si existe package.json.

Ejemplos SSH:

# git@host:path shorthand (requires git: prefix)
pi install git:[email protected]:user/repo

# ssh:// protocol format
pi install ssh://[email protected]/user/repo

# With version ref
pi install git:[email protected]:user/[email protected]

Rutas locales

/absolute/path/to/package
./relative/path/to/package

Las rutas locales apuntan a archivos o directorios en disco y se añaden a la configuración sin copiar. Las rutas relativas se resuelven contra el archivo de configuración donde aparecen. Si la ruta es un archivo, se carga como una sola extensión. Si es un directorio, pi carga recursos usando reglas de paquete.

Crear un paquete Pi

Añade un manifiesto pi a package.json o usa directorios convencionales. Incluye la palabra clave pi-package para descubribilidad.

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

Las rutas son relativas a la raíz del paquete. Los arrays admiten patrones glob y !exclusions.

Metadatos de galería

La galería de paquetes muestra paquetes etiquetados con pi-package. Añade campos video o image para mostrar una vista previa:

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

video: Solo MP4. En escritorio, se reproduce automáticamente al pasar el cursor. Al hacer clic se abre un reproductor a pantalla completa.
image: PNG, JPEG, GIF o WebP. Se muestra como vista previa estática.

Si ambos están definidos, video tiene prioridad.

Estructura del paquete

Directorios convencionales

Si no hay manifiesto pi, pi descubre recursos automáticamente desde estos directorios:

extensions/ carga archivos .ts y .js
skills/ encuentra recursivamente carpetas SKILL.md y carga archivos .md de nivel superior como habilidades
prompts/ carga archivos .md
themes/ carga archivos .json

Dependencias

Las dependencias de runtime de terceros pertenecen a dependencies en package.json. Las dependencias que no registran extensiones, habilidades, plantillas de prompts o temas también van en dependencies. Cuando pi instala un paquete desde npm o git, ejecuta npm install, por lo que esas dependencias se instalan automáticamente.

Pi incluye paquetes core para extensiones y habilidades. Si importas cualquiera de estos, listarlos en peerDependencies con rango "*" y no empaquetarlos: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Otros paquetes pi deben empaquetarse en tu tarball. Añádelos a dependencies y bundledDependencies, luego referencia sus recursos mediante rutas node_modules/. Pi carga paquetes con raíces de módulo separadas, por lo que instalaciones separadas no chocan ni comparten módulos.

Ejemplo:

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "pi": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

Filtrado de paquetes

Filtra lo que carga un paquete usando la forma de objeto en la configuración:

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

+path y -path son rutas exactas relativas a la raíz del paquete.

Omite una clave para cargar todo ese tipo.
Usa [] para no cargar ninguno de ese tipo.
!pattern excluye coincidencias.
+path fuerza la inclusión de una ruta exacta.
-path fuerza la exclusión de una ruta exacta.
Los filtros se superponen al manifiesto. Reducen lo que ya está permitido.

Habilitar y deshabilitar recursos

Usa pi config para habilitar o deshabilitar extensiones, habilidades, plantillas de prompts y temas de paquetes instalados y directorios locales. Funciona para alcance global (~/.pi/agent) y de proyecto (.pi/).

Alcance y deduplicación

Los paquetes pueden aparecer en configuración global y de proyecto. Si el mismo paquete aparece en ambos, gana la entrada del proyecto. La identidad se determina por:

npm: nombre del paquete
git: URL del repositorio sin ref
local: ruta absoluta resuelta