Система событий Pi Agent
Система событий — это основной механизм для расширений.
Слушая события жизненного цикла, вы можете вставлять пользовательскую логику на различных этапах работы ИИ.
Обзор жизненного цикла
Ниже приведены все события, инициируемые в течение жизненного цикла Pi Agent от запуска до завершения:
В рамках каждого хода события контекста, провайдера и инструментов срабатывают последовательно, образуя цикл из нескольких раундов при выполнении вызовов инструментов.
Пунктирные части означают, что этап может запускаться несколько раз несколькими событиями.
О моменте срабатывания других событий, таких как input, before_agent_start, resources_discover и agent_settled, см. полный краткий справочник по событиям ниже.
Объяснение основных событий
В этом разделе выбраны 5 наиболее часто используемых событий и объясняются моменты их срабатывания и соглашения о возвращаемых значениях.
input — Перехват ввода
Срабатывает до обработки пользовательского ввода; вы можете преобразовать, перехватить или напрямую обработать ввод:
Пример
// Следующий фрагмент находится внутри тела фабричной функции расширения
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 — Перехват вызовов инструментов
Срабатывает перед выполнением инструмента; вы можете изменить аргументы или заблокировать выполнение:
Пример
// инструкции 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.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.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.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-специфичные API | custom(), фабрики компонентов, ввод с терминала и т.д. действительны только в интерактивном режиме |
Другие расширенияНе запускайте фоновые ресурсы (процессы, сокеты, таймеры и т. д.) в фабричной функции расширения.
Отложите запуск ресурсов до событияsession_start, а очистку выполняйте вsession_shutdown.