Registro de comandos y atajos de Pi Agent

Registra comandos personalizados, atajos de teclado e indicadores CLI mediante extensiones para que Pi Agent se adapte mejor a tu flujo de trabajo.


Registrar comandos personalizados

Usopi.registerCommand()Registra comandos que los usuarios pueden invocar con /.

La siguiente extensión muestra tanto comandos básicos como comandos con autocompletado de parámetros:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/stats-command.ts

// Comando básico
pi.registerCommand("stats", {
  description: "Muestra las estadísticas de la sesión actual", // Obligatorio; se muestra en la lista de autocompletado de /
  handler: async (args, ctx) => {
    const count = ctx.sessionManager.getEntries().length;
    ctx.ui.notify(`Total: ${count}mensajes`, "info");
  }
});

// Comando con autocompletado de parámetros
pi.registerCommand("deploy", {
  description: "Desplegar en el entorno especificado",
  // Define el autocompletado de parámetros; prefix es el prefijo del parámetro que el usuario ya ha escrito
  getArgumentCompletions: (prefix) => {
    const envs = ["dev", "staging", "prod"];
    const items = envs
      .filter(e => e.startsWith(prefix))
      .map(e => ({ value: e, label: e }));
    return items.length > 0 ? items : null; // Devuelve null cuando no hay coincidencias
  },
  handler: async (args, ctx) => {
    if (!args) {
      ctx.ui.notify("Uso: /deploy <nombre_del_entorno>", "warning");
      return;
    }
    ctx.ui.notify(`Desplegando en el entorno ${args}...`, "info");
  },
});

Después de guardar, ejecuta /reload para cargar la extensión; escribe /stats en el área de edición para ver el efecto:

/stats
共 42 条消息

Si varias extensiones registran comandos con el mismo nombre, Pi Agent conserva todos los registros y añade un sufijo numérico según el orden de carga, por ejemplo /review:1 y /review:2.

Esto evita conflictos de nombres entre extensiones.


La extensión envía mensajes de forma proactiva

Además de responder pasivamente a comandos y eventos, las extensiones también pueden impulsar la conversación de forma proactiva.

pi.sendMessage(message, deliverAs?)Se usa para inyectar mensajes personalizados;pi.sendUserMessage(text, deliverAs?)simula una entrada de usuario.

deliverAs tiene tres valores posibles: steer es el valor predeterminado e inserta el mensaje en la ronda actual; followUp lo añade después de que termine la ronda actual; nextTurn inicia una nueva ronda (solo compatible con sendMessage).

sendUserMessage siempre activa una ronda de respuesta, porque para la IA es una intervención real del usuario.

Si se llaman estos dos métodos durante la salida en streaming, debe especificarse deliverAs explícitamente; de lo contrario, se lanzará un error directamente.

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/follow-up.ts
// El siguiente fragmento se encuentra dentro del cuerpo de la función de fábrica de la extensión

// Simula una solicitud adicional del usuario: espera a que terminen todas las herramientas actuales antes de añadir
pi.sendUserMessage("Cuando termine el despliegue, revisa de paso los registros del entorno de producción", {
  deliverAs: "followUp",
});

// Solo inserta información de referencia en el contexto, sin simular una intervención del usuario
pi.sendMessage({
  customType: "deploy-context",
  content: "El objetivo de despliegue actual es production",
  display: true,
}, {
  deliverAs: "steer", // Valor predeterminado; se inserta en la ronda actual
});

sendMessage también admite triggerTurn: true, que activa inmediatamente una respuesta del LLM cuando el agente está inactivo.

El criterio para elegir entre ambos es simple: si quieres que la IA responda de verdad, usa sendUserMessage; si solo quieres proporcionar información de referencia, usa sendMessage.


Contexto de comando (ExtensionCommandContext)

El handler del comando recibeExtensionCommandContext, que hereda de ExtensionContext.

Sobre la base del contexto normal, proporciona adicionalmente los siguientes métodos:

MétodoDescripción
ctx.getSystemPromptOptions()Lee las entradas base para construir el prompt del sistema (contextFiles, skills, etc.); solo disponible en el contexto de comando
ctx.waitForIdle()Espera a que la IA esté completamente inactiva (incluyendo que finalicen los reintentos, la compresión y los mensajes de seguimiento)
ctx.newSession(options)Crea una nueva sesión, pudiendo especificar la sesión principal y la lógica de inicialización
ctx.fork(entryId, options)Crea una nueva sesión bifurcada desde una entrada específica
ctx.navigateTree(targetId, options)Navega a una posición específica en el árbol de sesiones
ctx.switchSession(sessionPath, options)Cambia a otro archivo de sesión
ctx.reload()Ejecuta el mismo proceso de recarga en caliente que /reload

El siguiente comando enumera todas las sesiones del proyecto actual en una lista de selección; al seleccionar una, cambia directamente a ella:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/switch-session.ts
import { SessionManager } from "@earendil-works/pi-coding-agent";

pi.registerCommand("switch", {
  description: "Cambiar a otra sesión",
  handler: async (args, ctx) => {
    // Enumera todas las sesiones del proyecto actual
    const sessions = await SessionManager.list(ctx.cwd);
    if (sessions.length === 0) {
      ctx.ui.notify("No hay sesiones disponibles", "warning");
      return;
    }

    // Muestra la lista de selección
    const choice = await ctx.ui.select(
      "Selecciona la sesión a la que cambiar:",
      sessions.map(s => s.file),
    );

    if (choice) {
      // Cambia a la sesión seleccionada
      await ctx.switchSession(choice, {
        withSession: async (ctx) => {
          ctx.ui.notify("Sesión cambiada", "info");
        },
      });
    }
  },
});
/switch
┌ 选择要切换的会话:
│ > ~/.pi/agent/sessions/my-project/abc123.jsonl
│   ~/.pi/agent/sessions/my-project/def456.jsonl
└
已切换会话

Nota sobre la sustitución de sesiones: el ctx en la devolución de llamada de withSession es un contexto completamente nuevo.

No uses el objeto pi antiguo ni el ctx capturado en la devolución de llamada del comando; después de la sustitución de la sesión quedarán en un estado inválido.


Registrar atajos de teclado

Usapi.registerShortcut()para registrar atajos de teclado personalizados.

A continuación, vincula "Cambiar al modo Plan" a una combinación de teclas que aún no está ocupada de forma integrada:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/plan-shortcut.ts

pi.registerShortcut("ctrl+shift+g", {
  description: "Cambiar al modo Plan",
  handler: async (ctx) => {
    ctx.ui.notify("¡Modo Plan cambiado!", "info");
  },
});

Una vez iniciado, pulsa la combinación de teclas para activarlo:

已切换 Plan 模式!

Antes de elegir la combinación de teclas, revisa la tabla de atajos predeterminados para evitar sobrescribir las vinculaciones integradas.

Por ejemplo, ctrl+shift+p ya está ocupado por "Cambiar al modelo anterior"; registrar la misma combinación hará que los dos comportamientos se disputen la tecla.

El formato del atajo estecla modificadora + tecla, por ejemplo ctrl+shift+g, alt+x, etc.


Registrar indicadores CLI

Usapi.registerFlag()para añadir parámetros CLI personalizados al comando pi.

El siguiente ejemplo registra un indicador booleano --plan, que hace que la IA presente un plan antes de actuar:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/plan-flag.ts

pi.registerFlag("plan", {
  description: "Iniciar en modo Plan",
  type: "boolean",
  default: false,
});

// Verifica el valor del indicador en el código de la extensión
// Nota: pi.getFlag() no tiene valor hasta que se complete el análisis de los argumentos de la línea de comandos;
// Por lo tanto, se recomienda poner la comprobación en la devolución de llamada del evento, en lugar de escribirla en el nivel superior del módulo de la extensión.
// La evaluación del nivel superior del módulo ocurre durante la fase de carga de la extensión; en ese momento siempre se lee el valor predeterminado false.
pi.on("before_agent_start", async (event, ctx) => {
  if (!pi.getFlag("plan")) return; // Si --plan no está habilitado, no se realiza ningún cambio
  return {
    systemPrompt: event.systemPrompt
      + "\n\nModo Plan: primero presenta un plan y, tras la confirmación del usuario, lo ejecuta.",
  };
});

Modo de uso:

$ pi --plan "帮我实现用户认证功能"

Comunicación entre extensiones

Usapi.eventspara compartir eventos entre extensiones.

El emisor no necesita saber quién está escuchando, y el receptor tampoco necesita saber de dónde proviene el evento:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/deploy-events.ts

// Extensión A: envía el evento
pi.events.emit("deploy:completed", {
  env: "production",
  timestamp: Date.now(),
});

// Extensión B: escucha el evento (normalmente se escribe en otro archivo de extensión)
pi.events.on("deploy:completed", (data) => {
  console.log(`Despliegue completado: ${data.env}`);
});

Obtener los comandos registrados

Usapi.getCommands()para obtener todos los comandos disponibles en la sesión actual.

El siguiente ejemplo registra un comando /my-commands para enumerar todos los comandos registrados por extensiones:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/list-commands.ts

pi.registerCommand("my-commands", {
  description: "Enumerar todos los comandos registrados por las extensiones",
  handler: async (args, ctx) => {
    const commands = pi.getCommands();

    // Clasificar por origen
    const extCommands = commands.filter(
      c => c.source === "extension"
    );
    const templates = commands.filter(
      c => c.source === "prompt"
    );
    const skills = commands.filter(
      c => c.source === "skill"
    );

    // Mostrar el resultado para evitar calcular sin generar salida
    ctx.ui.notify(
`Comandos de extensión: ${extCommands.length}`
        + extCommands.map(c => "/" + c.name).join("、"),
      "info"
    );
    console.table(commands);
  },
});
/my-commands
扩展命令 2 个:/stats、/deploy

Cada entrada de comando contiene los siguientes campos:

CampoTipoDescripción
namestringNombre del comando; se invoca como /name en el área de edición
descriptionstringDescripción del comando, que se muestra en la lista de autocompletado.
sourcestringTipo de origen: extension, prompt, skill, etc.
sourceInfoobjectMetadatos detallados del origen, por ejemplo, la ruta de la extensión que lo registró.

Gestión dinámica de herramientas

Gestión en tiempo de ejecución de la habilitación y deshabilitación de herramientas.

Un uso típico es desactivar temporalmente las herramientas de escritura, de modo que la IA solo pueda leer y no modificar durante una tarea:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/manage-tools.ts

// Obtener la lista de herramientas actualmente habilitadas
const active = pi.getActiveTools();
// Por ejemplo: ["read", "bash", "edit", "write"]

// Obtener los metadatos de todas las herramientas registradas
const all = pi.getAllTools();

// Filtrar las herramientas integradas
const builtinTools = all.filter(
  t => t.sourceInfo.source === "builtin"
);

// Filtrar las herramientas registradas por extensiones
const extTools = all.filter(
  t => t.sourceInfo.source !== "builtin"
    && t.sourceInfo.source !== "sdk"
);

// Habilitar dinámicamente herramientas personalizadas (conservando las existentes)
pi.setActiveTools([...new Set([...active, "my_tool"])]);

// Cambiar al modo de solo lectura: conservar solo las herramientas de lectura,
// sin incluir bash / edit / write; en este estado, la IA no puede ejecutar comandos ni modificar archivos.
pi.setActiveTools(["read", "grep", "find", "ls"]);

El setActiveTools de aquí y los de la línea de comandos--tools / --exclude-toolsLos parámetros actúan sobre el mismo conjunto de herramientas.

Los parámetros de CLI determinan el conjunto inicial en el arranque; setActiveTools lo ajusta dinámicamente en tiempo de ejecución, y ambos pueden usarse en conjunto.

Los cambios pasados a setActiveTools deben ser incrementales (additive); eliminar herramientas ya activadas en la misma llamada hará que se pierda la optimización de carga diferida.

Además, activar herramientas con promptSnippet o promptGuidelines reconstruirá el prompt del sistema; incluso si el modelo admite carga diferida, puede invalidar el prefijo de prompt almacenado en caché.

Otras extensiones