Pi Agent Gestión de paquetes

Los Pi Packages (paquetes) te permiten empaquetar Extensions, Skills, plantillas de avisos (prompts) y temas, y distribuirlos e instalarlos a través de npm o git.


Comandos de gestión de paquetes

Todas las operaciones de paquetes se realizan mediante el comando pi, sin necesidad de editar manualmente settings.json.

ComandoFunciónEjemplo
pi install <source>Instalar paquete; el parámetro -l lo instala a nivel de proyectopi install npm:@ejemplo/pi-todo-kit
pi remove <source>Eliminar paquetepi remove npm:@ejemplo/pi-todo-kit
pi uninstall <source>Igual que removepi uninstall npm:@ejemplo/pi-todo-kit
pi listListar los paquetes instaladospi list
pi update --allActualizar Pi Agent y todos los paquetespi update --all
pi update --extensionsActualizar solo los paquetes instalados (sin incluir Pi Agent)pi update --extensions
pi update <source>Actualizar un paquete específicopi update npm:@ejemplo/pi-todo-kit

Ejemplo de uso:

# 安装 npm 包
$ pi install npm:@ejemplo/pi-todo-kit@1.0.0

# 安装 git 包
$ pi install git:github.com/ejemplo/pi-todo-kit@v1

# 安装本地包
$ pi install ./packages/pi-todo-kit
$ pi install ~/projects/pi-share-kit

# 安装为项目级(写入 .pi/settings.json)
$ pi install -l npm:@ejemplo/pi-todo-kit

# 临时试用包(不安装到配置中)
$ pi -e npm:@ejemplo/pi-todo-kit
$ pi -e git:github.com/ejemplo/pi-todo-kit

La salida de la instalación es aproximadamente la siguiente (ilustrativa), donde la cantidad de extensions y skills depende del campo pi del paquete:

$ pi install npm:@ejemplo/pi-todo-kit
Resolving @ejemplo/pi-todo-kit@1.2.0
Downloading @ejemplo/pi-todo-kit (12.4 kB)
Running npm install in ~/.pi/agent/npm/@ejemplo/pi-todo-kit
Installed @ejemplo/pi-todo-kit@1.2.0
  extensions: 2
  skills:     1
  prompts:    3
Saved to ~/.pi/agent/settings.json

Los nombres de paquetes y versiones anteriores son valores ilustrativos; en la práctica, reemplázalos por el paquete que quieras instalar.


Origen de los paquetes

Pi Agent admite tres orígenes de paquetes, cada uno con diferente comportamiento de instalación y ubicación de caché.

Pi 包从 npm、git、本地路径三种来源安装到本地目录并自动发现资源的流程

Paquetes npm

npm es el método recomendado de distribución de paquetes:

pi install npm:@scope/pkg@1.2.3
pi install npm:pkg

Los paquetes npm con número de versión quedan bloqueados; pi update no los actualiza automáticamente.

Ubicación de instalación del paquete: global en~/.pi/agent/npm/, a nivel de proyecto en.pi/npm/。

Paquetes Git

Admite los protocolos HTTPS y SSH:

# HTTPS
pi install https://github.com/user/repo@v1

# SSH(git@host:path 需要 git: 前缀)
pi install git:git@github.com:user/repo@v1

# SSH 协议
pi install ssh://git@github.com/user/repo@v1

La ref de los paquetes Git queda bloqueada; pi update no se mueve automáticamente a una nueva ref.

Ubicación de clonación: global en~/.pi/agent/git/, a nivel de proyecto en.pi/git/。

Ruta local

Apunta a una ruta del sistema de archivos local; no copia archivos:

pi install /Users/ejemplo/.pi/agent/packages/my-kit
pi install ./packages/my-kit

Crear paquetes Pi

Agrega en package.json elpicampo:

Ejemplo

{
  "name": "@ejemplo/pi-todo-kit",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

Si no haypicampo, Pi Agent descubre automáticamente los recursos desde los directorios convenidos:

Directorio convenidoContenido cargado
extensions/Carga los archivos .ts y .js que contiene
skills/Busca recursivamente carpetas que contengan SKILL.md y, además, carga los archivos .md de nivel superior como Skills independientes
prompts/Carga los archivos de plantilla .md que contiene
themes/Carga los archivos de tema .json que contiene

Agregarpi-packagepalabras clave puede hacer que tu paquete aparezca en elPi Agent Package Gallery (Galería de paquetes de Pi Agent).

Los campos video e image se usan para mostrar vistas previas en la galería.


Filtrado de paquetes

Al instalar un paquete, puedes controlar con precisión qué recursos se cargan, evitando traer todo el contenido de una sola vez.

La matriz packages siguiente se escribe en~/.pi/agent/settings.json(tiene efecto global) o.pi/settings.json(solo tiene efecto en el proyecto actual).

Los paquetes instalados con pi install -l se escriben en .pi/settings.json del proyecto; ambos métodos terminan en la misma configuración.

Las entradas de la matriz admiten dos formas de escritura: la forma de cadena carga todos los recursos del paquete, y la forma de objeto filtra por tipo de recurso uno a uno.

Ejemplo

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:@ejemplo/pi-todo-kit",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": ["skills/brave-search"],
      "prompts": [],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

En la documentación oficial, el filtrado de skills incluye tanto la escritura por ruta dentro del paquete como por nombre de habilidad; en la práctica, prevalece la descripción del paquete instalado.

Las reglas de filtrado son las siguientes:

SintaxisSignificadoEjemplo
Omitir una claveCargar todos los recursos de ese tipoNo escribir la clave skills = cargar todos los Skills
Establecer como []No cargar ningún recurso de ese tipo"prompts": []
!patternExcluir los recursos coincidentes"!extensions/legacy.ts"
+pathForzar la inclusión de la ruta especificada"+themes/legacy.json"
-pathForzar la exclusión de la ruta especificada"-skills/internal"

Gestión de dependencias

Pi Agent ejecuta, para cada paquete npm/git instalado,npm install, instalando las dependencias automáticamente.

Las dependencias locales distribuidas con el paquete se puedenbundledDependenciesempaquetar.

Los siguientes paquetes principales son proporcionados por el propio Pi Agent y deben aparecer comopeerDependencies, no los vuelvas a empaquetar dentro del paquete:

Nombre del paqueteDescripción
@earendil-works/pi-aiHerramientas y tipos de IA
@earendil-works/pi-agent-coreNúcleo del agente
@earendil-works/pi-coding-agentPaquete principal de Pi Agent
@earendil-works/pi-tuiComponentes TUI
typeboxDefinición de Schema de parámetros

pi config gestiona recursos

Usapi configpara habilitar o deshabilitar interactivamente las extensiones, Skills, plantillas y temas de los paquetes instalados:

# 编辑全局配置
$ pi config

# 编辑项目配置
$ pi config -l

La tecla Tab alterna entre el modo global y el modo de proyecto.


Ámbito y deduplicación

El mismo paquete puede aparecer tanto en la configuración global como en la del proyecto.

Si existe una entrada de proyecto, esta tiene prioridad sobre la entrada global.

La excepción es cuando la entrada de proyecto estableceautoload: false; entonces ya no se sobrescribe por completo, sino que se superpone de forma incremental a la entrada global.

La identidad del paquete se determina de las siguientes maneras; Pi Agent lo usa para decidir si dos configuraciones apuntan al mismo paquete:

OrigenIdentificador
Paquete npmNombre del paquete (p. ej., @ejemplo/pi-todo-kit)
Paquete gitURL del repositorio (sin ref)
Ruta localRuta absoluta resuelta
Otras extensiones