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.

CapacidadDescripciónUso típico
Registrarherramientas personalizadasAñadir nuevas funcionalidades invocables para la IAConsultar sistemas internos, leer/escribir bases de datos, encapsular APIs de terceros
Registrarcomandos personalizadosEl usuario los invoca mediante /nombre-de-comandoEncapsular prompts comunes, ejecutar flujos fijos con un clic
Escuchareventos de ciclo de vidaInsertar lógica en varias etapas del trabajo de la IAInterceptar comandos peligrosos, inyectar contexto, escribir registros de auditoría
Registraratajos de tecladoEnlazar teclas en la interfaz de terminalCambiar rápidamente de panel, activar operaciones frecuentes
MostrarUI personalizadaRenderizar interfaces interactivas en la terminalComponentes 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

// Ruta de archivo: ~/.pi/agent/extensions/my-extension.ts
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ónAlcanceDescripción
~/.pi/agent/extensions/*.tsGlobalAplica a todos los proyectos, descubrimiento automático
~/.pi/agent/extensions/*/index.tsGlobalExtensiones con index.ts en subdirectorio
.pi/extensions/*.tsProyectoSolo el proyecto actual, requiere confianza del proyecto
.pi/extensions/*/index.tsProyectoExtensiones 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 paqueteUso
@earendil-works/pi-coding-agentTipos de Extension (ExtensionAPI, ExtensionContext y varios tipos de eventos)
typeboxDefinición de Schema para los parámetros de las herramientas
@earendil-works/pi-aiHerramientas de IA (como StringEnum, para enumeraciones compatibles con Google)
@earendil-works/pi-tuiComponentes 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ácticaMotivo
Coloca la extensión~/.pi/agent/extensions/en el directorioAdmite recarga en caliente con /reload; no necesitas reiniciar la sesión después de los cambios.
pi -e ./path.tsSolo para pruebas temporalesPara 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ónLos 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_shutdownEvita 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