Pi Packages

pi puede ayudarte a crear paquetes pi. Pídale que agrupe sus extensiones, habilidades, prompt templates o temas.

Los paquetes Pi incluyen extensiones, habilidades, prompt templates y temas para que puedas compartirlos a través de npm o git. Un paquete puede declarar recursos en package.json bajo la clave pi o utilizar directorios convencionales.

• Install and Manage
• Package Sources
• Creating a Pi Package
• Package Structure
• Dependencies
• Package Filtering
• Enable and Disable Resources
• Scope and Deduplication

Seguridad: Pi los paquetes se ejecutan con acceso completo al sistema. Extensions ejecutar código arbitrario y las habilidades pueden indicarle al modelo que realice cualquier acción, incluida la ejecución de ejecutables. Revise el código fuente antes de instalar paquetes de terceros.

pi install npm:@foo/bar@1.0.0
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 --models          # refresh model catalogs 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 administran paquetes pi y pi update pueden actualizar la instalación de pi CLI. Para desinstalar pi, consulte Quickstart.

De forma predeterminada, install y remove escriben en la configuración del usuario (~/.pi/agent/settings.json). Utilice -l para escribir en la configuración del proyecto (.pi/settings.json). La configuración del proyecto se puede compartir con su equipo y pi instala automáticamente los paquetes faltantes al inicio después de que el proyecto sea confiable.

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

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

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

npm:@scope/pkg@1.2.3
npm:pkg

• Las especificaciones versionadas se fijan y omiten mediante actualizaciones de paquetes (pi update --extensions, pi update --all).
• Las instalaciones de usuario van por debajo de ~/.pi/agent/npm/.
• Las instalaciones del proyecto están por debajo de .pi/npm/.
• Establezca npmCommand en settings.json para anclar npm operaciones de búsqueda e instalación de paquetes a un comando contenedor específico como mise o asdf.

Ejemplo:

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

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• Sin el prefijo git:, solo se aceptan URL de protocolo (https://, http://, ssh://, git://).
• Con el prefijo git:, se aceptan formatos abreviados, incluidos github.com/user/repo y git@github.com:user/repo.
• Se admiten HTTPS y SSH URL.
• Las URL SSH utilizan las claves SSH configuradas automáticamente (respeta ~/.ssh/config).
• Para ejecuciones no interactivas (por ejemplo, CI), puede configurar GIT_TERMINAL_PROMPT=0 para deshabilitar las solicitudes de credenciales y configurar GIT_SSH_COMMAND (por ejemplo, ssh -o BatchMode=yes -o ConnectTimeout=5) para que falle rápidamente.
• Las referencias son etiquetas fijadas o confirmaciones. pi update --extensions y pi update --all no los mueven a referencias más nuevas, pero concilian un clon existente con la referencia configurada.
• Utilice pi install git:host/user/repo@new-ref para actualizar la configuración y mover un paquete existente a una nueva referencia fijada.
• Clonado a ~/.pi/agent/git/<host>/<path> (global) o .pi/git/<host>/<path> (proyecto).
• Cuando la conciliación cambia el pago, pi restablece y limpia el clon, luego ejecuta npm install si package.json existe.

SSH ejemplos:

# git@host:path shorthand (requires git: prefix)
pi install git:git@github.com:user/repo

# ssh:// protocol format
pi install ssh://git@github.com/user/repo

# With version ref
pi install git:git@github.com:user/repo@v1.0.0

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

Las rutas locales apuntan a archivos o directorios en el disco y se agregan a la configuración sin copiar. Las rutas relativas se resuelven con respecto al archivo de configuración en el que aparecen. Si la ruta es un archivo, se carga como una única extensión. Si es un directorio, pi carga recursos usando reglas de paquete.

Agregue un manifiesto pi a package.json o use directorios convencionales. Incluya la palabra clave pi-package para mayor visibilidad.

{
  "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. Las matrices admiten patrones globales y !exclusions.

El package gallery muestra los paquetes etiquetados con pi-package. Agregue los 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"
  }
}

• vídeo: solo MP4. En el escritorio, se reproduce automáticamente al pasar el mouse. Al hacer clic se abre un reproductor en pantalla completa.
• imagen: PNG, JPEG, GIF o WebP. Se muestra como una vista previa estática.

Si ambos están configurados, el vídeo tiene prioridad.

Si no hay ningún manifiesto pi presente, pi descubre automáticamente los recursos de estos directorios:

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

Las dependencias de tiempo de ejecución de terceros pertenecen a dependencies en package.json. Las dependencias que no registran extensiones, habilidades, prompt templates o temas también pertenecen a 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 principales para extensiones y habilidades. Si importa alguno de estos, enumerelos en peerDependencies con un rango "*" y no los agrupe: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Otros paquetes pi deben estar incluidos en su tarball. Agréguelos a dependencies y bundledDependencies, luego haga referencia a sus recursos a través de las rutas node_modules/. Pi carga paquetes con raíces de módulos separadas, por lo que las 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"]
  }
}

Filtra lo que carga un paquete usando el formulario 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.

• Omita una clave para cargar todos los de ese tipo.
• Utilice [] para no cargar nada de ese tipo.
• !pattern excluye coincidencias.
• +path fuerza: incluye una ruta exacta.
• -path fuerza: excluye una ruta exacta.
• Capa de filtros encima del manifiesto. Reducen lo que ya está permitido.

Utilice pi config para habilitar o deshabilitar extensiones, habilidades, prompt templates y temas de paquetes instalados y directorios locales. pi config comienza en la configuración global (~/.pi/agent/settings.json); presione Tab para cambiar entre los modos global y local del proyecto. Utilice pi config -l para comenzar en anulaciones de proyectos (.pi/settings.json) con los recursos globales heredados atenuados.

Los paquetes pueden aparecer tanto en la configuración global como en la del proyecto. Si el mismo paquete aparece en ambos, la entrada del proyecto gana a menos que la entrada del proyecto tenga autoload: false, en cuyo caso se aplica como un delta sobre la entrada global. La identidad está determinada por:

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