Система событий Pi Agent

Система событий — это основной механизм для расширений.

Слушая события жизненного цикла, вы можете вставлять пользовательскую логику на различных этапах работы ИИ.


Обзор жизненного цикла

Ниже приведены все события, инициируемые в течение жизненного цикла Pi Agent от запуска до завершения:

Pi Agent 扩展事件生命周期:启动、项目信任、会话启动、turn 循环与会话关闭

В рамках каждого хода события контекста, провайдера и инструментов срабатывают последовательно, образуя цикл из нескольких раундов при выполнении вызовов инструментов.

Пунктирные части означают, что этап может запускаться несколько раз несколькими событиями.

О моменте срабатывания других событий, таких как input, before_agent_start, resources_discover и agent_settled, см. полный краткий справочник по событиям ниже.


Объяснение основных событий

В этом разделе выбраны 5 наиболее часто используемых событий и объясняются моменты их срабатывания и соглашения о возвращаемых значениях.

input — Перехват ввода

Срабатывает до обработки пользовательского ввода; вы можете преобразовать, перехватить или напрямую обработать ввод:

Пример

// Путь к файлу: ~/.pi/agent/extensions/quick-input.ts
// Следующий фрагмент находится внутри тела фабричной функции расширения
pi.on("input", async (event, ctx) => {
  // event.text - необработанный текст ввода
  // event.images - прикреплённые изображения
  // event.source - "interactive" | "rpc" | "extension"

  // Преобразовать ввод: добавить инструкцию перед вводом
  if (event.text.startsWith("?quick ")) {
    return {
      action: "transform",
      text:`Краткий ответ: ${event.text.slice(7)}`
    };
  }

  // Обработать напрямую: ответить, не обращаясь к LLM
  if (event.text === "ping") {
    ctx.ui.notify("pong", "info");
    return { action: "handled" };
  }

  // Пропустить сообщения, внедрённые расширением
  if (event.source === "extension") {
    return { action: "continue" };
  }

  return { action: "continue" };  // По умолчанию: обрабатывать как обычно
});
значение действияЭффект
"continue"Не изменяет входные данные; продолжает обычный поток обработки
"transform"Продолжает обработку после изменения входных данных; преобразования от нескольких обработчиков объединяются в цепочку
"handled"Полностью берёт управление на себя, пропуская вызов LLM (вступает в силу первый обработчик, вернувший это значение)

Фактические эффекты двух типичных реализаций таковы.

При вводе?quick hello worldтекст, фактически отправленный в LLM, был переписан:

简短回复:hello world

При вводеpingLLM не вызывается; в терминале появляется только уведомление:

pong

Событие ввода срабатывает до раскрытия Skill и шаблонадо, поэтому вы видите необработанный ввод.

/skill:foo и /template на данный момент ещё не раскрыты.


tool_call — Перехват вызовов инструментов

Срабатывает перед выполнением инструмента; вы можете изменить аргументы или заблокировать выполнение:

Пример

// Путь к файлу: ~/.pi/agent/extensions/guard-bash.ts
// инструкции import должны находиться в начале модуля; приведённый ниже фрагмент pi.on находится внутри тела фабричной функции расширения
// isToolCallEventType — это защитник типа, и его необходимо импортировать из официального пакета
import { isToolCallEventType } from "@earendil-works/pi-coding-agent";

pi.on("tool_call", async (event, ctx) => {
  // Блокировать опасные команды bash
  if (isToolCallEventType("bash", event)) {
    // event.input — это { command: string; timeout?: number }
    const dangerous = ["rm -rf /", "mkfs.", "dd if=", "> /dev/sda"];
    // Сначала проверь, опасно ли это, затем реши, разрешать ли это
    if (dangerous.some(cmd =>
        event.input.command.includes(cmd))) {
      return { block: true, reason: "Опасная команда была заблокирована" };
    }
    // Добавляй загрузку переменных окружения только после прохождения проверки
    event.input.command = `source ~/.profile\n${event.input.command}`;
  }

  // Логировать все операции чтения файлов
  if (isToolCallEventType("read", event)) {
    // event.input — это { path: string; offset?: number; limit?: number }
    ctx.ui.notify(`Чтение файла: ${event.input.path}`, "info");
  }
});

Если ИИ попытается выполнитьrm -rf /, инструмент не запустится, и терминал покажет причину блокировки:

Dangerous command has been blocked.

event.inputявляется изменяемым — изменение его напрямую влияет на выполнение инструмента.


tool_result — Изменение результатов инструмента

Срабатывает после завершения выполнения инструмента; вы можете изменить результат, возвращённый LLM:

Пример

// Путь к файлу: ~/.pi/agent/extensions/read-linenum.ts
// Следующий фрагмент находится внутри тела фабричной функции расширения
pi.on("tool_result", async (event, ctx) => {
  // event.toolName — имя инструмента
  // event.content — содержимое, возвращаемое LLM
  // event.details — подробные данные
  // event.isError — является ли это ошибкой

  // Пример: добавление номеров строк к результатам read
  if (event.toolName === "read" && !event.isError) {
    const lines = event.content
      .filter(c => c.type === "text")
      .map(c => c.text)
      .join("\n")
      .split("\n")
      .map((line, i) => `${i + 1}: ${line}`)
      .join("\n");

    return {
      content: [{ type: "text", text: lines }],
    };
  }
});

Исходное содержимое файла из двух строк превращается в форму с нумерацией строк, когда передаётся LLM:

1: import { readFile } from "node:fs/promises";
2: export async function load() {

context — Изменение контекста LLM

Срабатывает перед каждым вызовом LLM; можно фильтровать или изменять сообщения:

Пример

// Путь к файлу: ~/.pi/agent/extensions/context-filter.ts
// Следующий фрагмент находится внутри тела фабричной функции расширения
pi.on("context", async (event, ctx) => {
  // event.messages - глубокая копия текущих сообщений контекста; можно безопасно изменять

  // Отфильтровать сообщения определённого типа
  const filtered = event.messages.filter(m => {
    // Удалить сообщения с пользовательским типом "debug"
    if (m.type === "custom" && m.customType === "debug") {
      return false;
    }
    return true;
  });

  return { messages: filtered };
});

before_agent_start — Внедрение сообщений

Срабатывает до того, как ИИ начинает обрабатывать пользовательский ввод; вы можете внедрить дополнительные сообщения или изменить системный запрос:

Пример

// Путь к файлу: ~/.pi/agent/extensions/context-inject.ts
// Следующий фрагмент находится внутри тела фабричной функции расширения
pi.on("before_agent_start", async (event, ctx) => {
  // event.prompt - текст запроса пользователя
  // event.systemPrompt - текущий настроенный системный запрос

  return {
    // Внедрить постоянное сообщение (хранится в сессии и отправляется LLM)
    message: {
      customType: "my-context",
      content:`Текущее время: ${new Date().toISOString()}`,
      display: true,
    },
    // Добавить в системный промпт
    systemPrompt: event.systemPrompt
      + "\n\nПожалуйста, используйте китайский язык во всех ответах.",
  };
});

Полный краткий справочник по событиям

Несколько событий также были показаны на ASCII-диаграмме в предыдущем разделе; здесь они перечислены вместе в порядке срабатывания для удобства.

EventМомент срабатыванияИзменяемыйБлокируемое
project_trustПеред загрузкой ресурсов проекта; подтвердите, доверять ли текущему проектунетДа (расширения проекта не загружаются при отказе)
session_startКогда сеанс запускается или возобновляетсянетнет
resources_discoverСрабатывает после session_start (при запуске/перезагрузке)Да (можно только добавлять Skills, шаблоны промптов и пути тем; нельзя добавлять или удалять расширения)нет
inputПеред обработкой пользовательского вводаДа (может преобразовывать ввод)Да (handled перехватывает управление)
before_agent_startПеред тем как ИИ начнёт обрабатывать пользовательский вводДа (может внедрять сообщения, изменять системный промпт)нет
agent_startКогда запускается цикл агентанетнет
message_start / message_updateВо время генерации сообщения (message_update — это потоковая дельта ассистента)нетнет
message_endКогда сообщения user, assistant и toolResult финализируютсяДа (можно вернуть { message }, чтобы заменить финальное сообщение; role должен совпадать)нет
turn_startВ начале каждого ходанетнет
contextПеред каждым вызовом LLMДа (можно фильтровать сообщения)нет
before_provider_headersПеред отправкой заголовков HTTP-запросаДа (можно добавлять или изменять заголовки запроса)нет
before_provider_requestПеред отправкой тела запроса моделиДа (возврат значения, отличного от undefined, заменяет всю полезную нагрузку запроса, а не прерывает запрос)нет
after_provider_responseПосле получения HTTP-ответа, до того как потоковое тело будет прочитаноНет (можно только читать статус/заголовки для наблюдения)нет
tool_execution_startКогда инструмент начинает выполнятьсянетнет
tool_callПеред выполнением инструментаДа (event.input можно изменять)Да (block: true)
tool_execution_updateКогда во время выполнения инструмента генерируется прогресснетнет
tool_resultПосле завершения выполнения инструментаДа (возвращаемое содержимое можно изменить)нет
tool_execution_endКогда выполнение инструмента завершаетсянетнет
turn_endВ конце каждого ходанетнет
agent_endКогда цикл агента завершаетсянетнет
agent_settledПосле полного завершения раунда взаимодействиянетнет
session_before_switchПеред выполнением /new или /resumeнетДа (return { cancel: true })
session_before_forkПеред выполнением /fork или /cloneнетДа (return { cancel: true })
session_before_compactПеред выполнением сжатия (ручной /compact, пороговое значение, переполнение контекста)Да (настраиваемая сводка сжатия)Да (return { cancel: true })
session_shutdownСрабатывает перед уничтожением сессии; quit, /new, /resume, /fork, /reload — все они запускают его (причина — quit/reload/new/resume/fork)нетнет

Ключевые моменты обработки событий

При написании обработчиков событий следующие моменты определяют, будет ли код надёжным.

МетодНазначение
Несколько расширений прослушивают одно и то же событиеВыполняются последовательно в соответствии с порядком загрузки расширений; предыдущее возвращаемое значение влияет на последующие обработчики
Вернуть{ block: true, reason: "..." }Заблокировать операцию; причина будет показана пользователю и ИИ
Вернуть{ cancel: true }Отменить операции, такие как переключение сессии
Использоватьctx.signalРеагировать на сигналы отмены в асинхронных операциях; прерывать, когда пользователь нажимает Escape
Использоватьctx.uiСерия методовВзаимодействовать с пользователем, например: notify, confirm, select и т.д.
использоватьctx.hasUIЗащищать вызовы диалоговВ режимах Print/JSON/RPC методы типа dialog недоступны или не выполняют никаких действий; проверяйте перед вызовом
использоватьctx.mode === "tui"Защищать TUI-специфичные APIcustom(), фабрики компонентов, ввод с терминала и т.д. действительны только в интерактивном режиме

Не запускайте фоновые ресурсы (процессы, сокеты, таймеры и т. д.) в фабричной функции расширения.

Отложите запуск ресурсов до событияsession_start, а очистку выполняйте вsession_shutdown.

Другие расширения