Primeros pasos con las Extensiones de Pi Agent
Las Extensiones son la forma más potente de personalizar Pi Agent: puedes escribir herramientas personalizadas, comandos y listeners de eventos en TypeScript.
Qué es una Extension
Una Extension es un módulo de TypeScript que puede hacer lo siguiente.
| Capacidad | Descripción | Uso típico |
|---|---|---|
| Registrarherramientas personalizadas | Añadir nuevas funcionalidades invocables para la IA | Consultar sistemas internos, leer/escribir bases de datos, encapsular APIs de terceros |
| Registrarcomandos personalizados | El usuario los invoca mediante /nombre-de-comando | Encapsular prompts comunes, ejecutar flujos fijos con un clic |
| Escuchareventos de ciclo de vida | Insertar lógica en varias etapas del trabajo de la IA | Interceptar comandos peligrosos, inyectar contexto, escribir registros de auditoría |
| Registraratajos de teclado | Enlazar teclas en la interfaz de terminal | Cambiar rápidamente de panel, activar operaciones frecuentes |
| MostrarUI personalizada | Renderizar interfaces interactivas en la terminal | Componentes como barras de progreso, listas, diálogos de confirmación |
Primera Extension: Hello World
La siguiente extensión demuestra de una sola vez tres capacidades: escucha de eventos, registro de herramientas y registro de comandos.
Ejemplo
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
export default function (pi: ExtensionAPI) {
// Se activa al iniciar la sesión
pi.on("session_start", async (_event, ctx) => {
ctx.ui.notify("¡Mi extensión se ha cargado!", "info");
});
// Interceptar comandos peligrosos
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command?.includes("rm -rf")) {
const ok = await ctx.ui.confirm("¡Operación peligrosa!", "¿Confirmar ejecución de rm -rf?");
if (!ok) return { block: true, reason: "Bloqueado por el usuario" };
}
});
// Registrar una herramienta personalizada
pi.registerTool({
name: "greet",
label: "Saludar",
description: "Saludar a una persona específica",
parameters: Type.Object({
name: Type.String({ description: "Nombre de la persona a la que saludar" }),
}),
async execute(toolCallId, params) {
return {
content: [{ type: "text", text:`Hola, ${params.name}!` }],
details: {},
};
},
});
// Registrar un comando personalizado
pi.registerCommand("hello", {
description: "Saludar al mundo",
handler: async (args, ctx) => {
ctx.ui.notify(`Hola ${args || "mundo"}!`, "info");
},
});
}
La comprobación de eventos en la línea 13 usa la forma más simpleevent.toolNamede escribir; también se puede usar una guarda de tipos para reducir event a un tipo de evento específico, consulta el capítulo «Sistema de eventos».
Usa el parámetro pi -e para iniciar Pi Agent y así cargar esta extensión para probarla:
$ pi -e ~/.pi/agent/extensions/my-extension.ts Loading extension: /Users/ejemplo/.pi/agent/extensions/my-extension.ts my-extension 加载成功(1 个工具、1 个命令) 我的扩展已加载!
La última línea es la notificación que aparece con ctx.ui.notify en el evento session_start, lo que indica que la extensión ya está activa.
Ubicaciones de carga de las Extensiones
Pi Agent descubre automáticamente las Extensiones en varios directorios fijos, y también se puede especificar una ruta explícita.
| Ubicación | Alcance | Descripción |
|---|---|---|
| ~/.pi/agent/extensions/*.ts | Global | Aplica a todos los proyectos, descubrimiento automático |
| ~/.pi/agent/extensions/*/index.ts | Global | Extensiones con index.ts en subdirectorio |
| .pi/extensions/*.ts | Proyecto | Solo el proyecto actual, requiere confianza del proyecto |
| .pi/extensions/*/index.ts | Proyecto | Extensiones en subdirectorios del proyecto |
Además de los argumentos de línea de comandos, también puedes escribir una matriz de rutas en el campo extensions de settings.json; las rutas de directorio se expandirán según las reglas de directorio de extensiones.
Ejemplo
"extensions": [
"/Users/ejemplo/.pi/agent/extensions/quick-notify.ts",
"/Users/ejemplo/.pi/agent/extensions/team-tools"
]
}
El primer elemento es una extensión de archivo único, el segundo es una extensión de directorio; al usarlo, simplemente reemplázalo con la ubicación de tu propia extensión.
Estructura de archivos de la Extension
Una Extension puede ser un único archivo .ts o un directorio con un archivo de entrada.
Extensión de archivo único
La forma más simple, adecuada para extensiones pequeñas:
~/.pi/agent/extensions/ └── my-extension.ts
Extensión de directorio (con index.ts)
Adecuada para extensiones de múltiples archivos:
~/.pi/agent/extensions/
└── my-extension/
├── index.ts # 入口文件(导出默认函数)
├── tools.ts # 辅助模块
└── utils.ts # 工具函数
Extensión con dependencias
Adecuada para extensiones grandes que necesitan paquetes npm:
~/.pi/agent/extensions/
└── my-extension/
├── package.json # 声明依赖和入口
├── node_modules/ # npm install 后生成
└── src/
└── index.ts
Las Extensiones se ejecutan con los permisos de tu sistema y pueden ejecutar código arbitrario.
Instala solo Extensiones de fuentes confiables。
Mecanismo de carga de las Extensiones
Las Extensiones se cargan mediantejitiimport; el código TypeScript se puede ejecutar directamente sin compilación.
Si tu función de fábrica devuelve una Promise, Pi Agent esperará a que se complete antes de continuar con el proceso de inicio.
Esto significa que puedes realizar operaciones asíncronas durante la inicialización de la extensión, como obtener configuración remota.
Paquetes de importación disponibles
Pi Agent proporciona estos paquetes de forma incorporada; puedes importarlos directamente en la extensión.
| Nombre del paquete | Uso |
|---|---|
| @earendil-works/pi-coding-agent | Tipos de Extension (ExtensionAPI, ExtensionContext y varios tipos de eventos) |
| typebox | Definición de Schema para los parámetros de las herramientas |
| @earendil-works/pi-ai | Herramientas de IA (como StringEnum, para enumeraciones compatibles con Google) |
| @earendil-works/pi-tui | Componentes TUI, para renderizado personalizado |
Estos paquetes centrales integrados los proporciona el propio Pi; solo debes listarlos como peerDependencies y no empaquetarlos en tu extensión.
Las dependencias de tiempo de ejecución propias deben escribirse en el campo dependencies de package.json.
Al instalar paquetes de extensión, Pi ejecuta una instalación de producción por defecto (npm install --omit=dev); las devDependencies no están disponibles en tiempo de ejecución.
También se pueden usar otros paquetes npm: solo agrega un package.json en el directorio de la extensión y ejecuta npm install.
Consejos de desarrollo
Estos consejos te ayudarán a evitar rodeos, especialmente en la elección del método de carga.
| Práctica | Motivo |
|---|---|
| Coloca la extensión~/.pi/agent/extensions/en el directorio | Admite recarga en caliente con /reload; no necesitas reiniciar la sesión después de los cambios. |
| pi -e ./path.tsSolo para pruebas temporales | Para uso a largo plazo, coloca la extensión en el directorio ~/.pi/agent/extensions/, donde Pi Agent la descubrirá automáticamente |
| No inicies recursos en segundo plano dentro de la función de fábrica de la extensión | Los procesos, sockets, observadores de archivos, temporizadores, etc., deben iniciarse en el evento session_start |
| Limpia los recursos a nivel de sesión en el evento session_shutdown | Evita que queden manejadores y listeners residuales después de cambiar de sesión |
Integración adicional
Además de escribir Extensiones, el equipo oficial ofrece dos rutas de integración mediante programación.
Los proyectos Node o TypeScript pueden usar directamente@earendil-works/pi-coding-agentel SDK exportado: usa createAgentSession para crear sesiones, subscribe para suscribirse a eventos y prompt para enviar mensajes.
Este método se ejecuta en el mismo proceso que Pi y tiene definiciones de tipos completas.
Para llamadas entre lenguajes o cuando se requiere aislamiento de procesos, cambia api --mode rpcel protocolo JSONL, para comunicarte con el proceso de Pi a través de JSONL.
Ambas rutas comparten el mismo modelo de eventos con las Extensiones; cuál elegir depende principalmente de si necesitas un proceso independiente.
Otras Extensiones