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.
| Comando | Función | Ejemplo |
|---|---|---|
| pi install <source> | Instalar paquete; el parámetro -l lo instala a nivel de proyecto | pi install npm:@ejemplo/pi-todo-kit |
| pi remove <source> | Eliminar paquete | pi remove npm:@ejemplo/pi-todo-kit |
| pi uninstall <source> | Igual que remove | pi uninstall npm:@ejemplo/pi-todo-kit |
| pi list | Listar los paquetes instalados | pi list |
| pi update --all | Actualizar Pi Agent y todos los paquetes | pi update --all |
| pi update --extensions | Actualizar solo los paquetes instalados (sin incluir Pi Agent) | pi update --extensions |
| pi update <source> | Actualizar un paquete específico | pi 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é.
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 convenido | Contenido 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:
| Sintaxis | Significado | Ejemplo |
|---|---|---|
| Omitir una clave | Cargar todos los recursos de ese tipo | No escribir la clave skills = cargar todos los Skills |
| Establecer como [] | No cargar ningún recurso de ese tipo | "prompts": [] |
| !pattern | Excluir los recursos coincidentes | "!extensions/legacy.ts" |
| +path | Forzar la inclusión de la ruta especificada | "+themes/legacy.json" |
| -path | Forzar 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 paquete | Descripción |
|---|---|
| @earendil-works/pi-ai | Herramientas y tipos de IA |
| @earendil-works/pi-agent-core | Núcleo del agente |
| @earendil-works/pi-coding-agent | Paquete principal de Pi Agent |
| @earendil-works/pi-tui | Componentes TUI |
| typebox | Definició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:
| Origen | Identificador |
|---|---|
| Paquete npm | Nombre del paquete (p. ej., @ejemplo/pi-todo-kit) |
| Paquete git | URL del repositorio (sin ref) |
| Ruta local | Ruta absoluta resuelta |