Регистрация команд и сочетаний клавиш в Pi Agent
Регистрируйте пользовательские команды, сочетания клавиш и флаги CLI через расширения, чтобы Pi Agent лучше адаптировался к вашему рабочему процессу.
Регистрация пользовательских команд
Использованиеpi.registerCommand()Регистрируйте команды, которые пользователи могут вызывать с помощью /.
Следующее расширение демонстрирует как базовую команду, так и команду с автодополнением параметров:
Пример
// Базовая команда
pi.registerCommand("stats", {
description: "Показать статистику для текущей сессии", // Обязательно, отображается в списке автодополнения /
handler: async (args, ctx) => {
const count = ctx.sessionManager.getEntries().length;
ctx.ui.notify(`Всего ${count}сообщений`, "info");
}
});
// Команда с автодополнением параметров
pi.registerCommand("deploy", {
description: "Развернуть в указанной среде",
// Определить автодополнение параметров; prefix — это префикс параметра, который пользователь уже ввёл
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; // Вернуть null, если нет совпадений
},
handler: async (args, ctx) => {
if (!args) {
ctx.ui.notify("Использование: /deploy <имя окружения>", "warning");
return;
}
ctx.ui.notify(`Развёртывание в ${args}окружение...`, "info");
},
});
После сохранения выполните /reload, чтобы загрузить расширение, затем введите /stats в области редактора, чтобы увидеть результат:
/stats 共 42 条消息
Если несколько расширений регистрируют команды с одинаковым именем, Pi Agent сохраняет все регистрации и добавляет числовые суффиксы в порядке загрузки, например, /review:1 и /review:2.
Это позволяет избежать конфликтов имён между расширениями.
Расширения, проактивно отправляющие сообщения
Помимо пассивного реагирования на команды и события, расширения также могут проактивно вести беседу.
pi.sendMessage(message, deliverAs?)Используется для внедрения пользовательских сообщений,pi.sendUserMessage(text, deliverAs?)имитирует ввод пользователя.
deliverAs имеет три значения: steer — значение по умолчанию, которое вставляет сообщение в текущий ход; followUp добавляет его после этого хода; nextTurn начинает новый ход (поддерживается только sendMessage).
sendUserMessage всегда вызывает ответ, потому что для ИИ это настоящая реплика пользователя.
При вызове этих двух методов во время потокового вывода необходимо явно указать deliverAs, иначе ошибка будет немедленно выброшена.
Пример
// Следующий фрагмент находится внутри тела фабричной функции расширения
// Имитировать дополнительный запрос пользователя: добавить после завершения выполнения всех текущих инструментов
pi.sendUserMessage("После развёртывания также проверьте логи производственной среды", {
deliverAs: "followUp",
});
// Только внедрить справочную информацию в контекст, без имитации высказывания пользователя
pi.sendMessage({
customType: "deploy-context",
content: "Текущая цель развёртывания — production",
display: true,
}, {
deliverAs: "steer", // Значение по умолчанию, вставляемое в текущий ход
});
sendMessage также поддерживает triggerTurn: true, который немедленно вызывает ответ LLM, когда агент простаивает.
Выбор между ними прост: используйте sendUserMessage, если вы хотите, чтобы ИИ действительно отвечал, и sendMessage, если вы хотите только предоставить справочную информацию.
Контекст команды (ExtensionCommandContext)
Обработчик команды получаетExtensionCommandContextExtensionCommandContext, который наследуется от ExtensionContext.
В дополнение к обычному контексту он дополнительно предоставляет следующие методы:
| Метод | Описание |
|---|---|
| ctx.getSystemPromptOptions() | Читает базовые входные данные для построения системного промпта (contextFiles, skills и т. д.), доступно только в контексте команды. |
| ctx.waitForIdle() | Подождать, пока ИИ полностью не перейдёт в состояние простоя (включая завершение повторных попыток, сжатия и последующих сообщений). |
| ctx.newSession(options) | Создать новую сессию с возможностью указать родительскую сессию и логику инициализации. |
| ctx.fork(entryId, options) | Ответвить новую сессию от указанной записи. |
| ctx.navigateTree(targetId, options) | Перейти к указанной позиции в дереве сессии. |
| ctx.switchSession(sessionPath, options) | Переключиться на другой файл сессии. |
| ctx.reload() | Выполнить тот же процесс горячей перезагрузки, что и /reload. |
Следующая команда выводит список всех сессий текущего проекта в виде списка выбора; после выбора одной из них выполняется прямой переход к ней:
Пример
import { SessionManager } from "@earendil-works/pi-coding-agent";
pi.registerCommand("switch", {
description: "Переключиться на другую сессию",
handler: async (args, ctx) => {
// Вывести список всех сессий текущего проекта
const sessions = await SessionManager.list(ctx.cwd);
if (sessions.length === 0) {
ctx.ui.notify("Нет доступных сессий", "warning");
return;
}
// Открыть список выбора
const choice = await ctx.ui.select(
"Выберите сессию для переключения:",
sessions.map(s => s.file),
);
if (choice) {
// Переключиться на выбранную сессию
await ctx.switchSession(choice, {
withSession: async (ctx) => {
ctx.ui.notify("Сессия переключена", "info");
},
});
}
},
});
/switch ┌ 选择要切换的会话: │ > ~/.pi/agent/sessions/my-project/abc123.jsonl │ ~/.pi/agent/sessions/my-project/def456.jsonl └ 已切换会话
Примечания о замене сессии: ctx в колбэке withSession — это совершенно новый контекст.
Не используйте старый объект pi или ctx, захваченный в колбэках команд; после замены сессии они становятся недействительными.
Регистрация сочетаний клавиш
Использованиеpi.registerShortcut()Зарегистрируйте пользовательские сочетания клавиш.
Далее "Toggle Plan Mode" привязывается к сочетанию клавиш, которое ещё не используется ни одной встроенной привязкой:
Пример
pi.registerShortcut("ctrl+shift+g", {
description: "Переключить режим планирования",
handler: async (ctx) => {
ctx.ui.notify("Режим планирования переключён!", "info");
},
});
После запуска нажмите сочетание клавиш, чтобы вызвать его:
已切换 Plan 模式!
Перед выбором сочетания клавиш проверьте таблицу сочетаний клавиш по умолчанию, чтобы не перезаписать встроенные привязки.
Например, ctrl+shift+p уже занято "Переключиться на предыдущую модель"; повторная регистрация того же сочетания клавиш приведёт к конфликту двух действий.
Формат сочетания клавиш:модификатор + клавиша, например, ctrl+shift+g, alt+x и т. д.
Регистрация флагов CLI
Использованиеpi.registerFlag()Добавляет пользовательские аргументы CLI в команду pi.
В следующем примере регистрируется логический флаг --plan, чтобы ИИ сначала составил план, прежде чем действовать:
Пример
pi.registerFlag("plan", {
description: "Запуск в режиме планирования",
type: "boolean",
default: false,
});
// Проверьте значение флага в коде расширения
// Примечание: pi.getFlag() имеет значение только после завершения разбора аргументов командной строки,
// поэтому рекомендуется поместить проверку внутрь обработчика события, а не на верхнем уровне модуля расширения.
// Вычисление модуля верхнего уровня происходит во время загрузки расширения, и в этот момент всегда читается значение по умолчанию false.
pi.on("before_agent_start", async (event, ctx) => {
if (!pi.getFlag("plan")) return; // Если --plan не включён, не вносите изменения
return {
systemPrompt: event.systemPrompt
+ "\n\nРежим планирования: сначала предложите план, затем выполните после подтверждения пользователя.",
};
});
Использование:
$ pi --plan "帮我实现用户认证功能"
Взаимодействие между расширениями
Использованиеpi.eventsОбмен событиями между расширениями.
Отправителю не нужно знать, кто слушает, а слушателю не нужно знать, откуда приходит событие:
Пример
// Расширение A: отправка событий
pi.events.emit("deploy:completed", {
env: "production",
timestamp: Date.now(),
});
// Расширение B: прослушивание событий (обычно записывается в другом файле расширения)
pi.events.on("deploy:completed", (data) => {
console.log(`Развёртывание завершено: ${data.env}`);
});
Получить зарегистрированные команды
Использованиеpi.getCommands()Получить все доступные команды в текущей сессии.
Следующий пример регистрирует команду /my-commands для вывода списка всех команд, зарегистрированных расширениями:
Пример
pi.registerCommand("my-commands", {
description: "Список всех команд, зарегистрированных расширениями",
handler: async (args, ctx) => {
const commands = pi.getCommands();
// Классифицировать по источнику
const extCommands = commands.filter(
c => c.source === "extension"
);
const templates = commands.filter(
c => c.source === "prompt"
);
const skills = commands.filter(
c => c.source === "skill"
);
// Вывести результат, чтобы не ограничиваться вычислением без вывода
ctx.ui.notify(
`Команды расширения ${extCommands.length}:`
+ extCommands.map(c => "/" + c.name).join("、"),
"info"
);
console.table(commands);
},
});
/my-commands 扩展命令 2 个:/stats、/deploy
Каждая запись команды содержит следующие поля:
| Поле | Type | Описание |
|---|---|---|
| name | string | Имя команды, вызывается как /name в области редактора. |
| description | string | Описание команды, отображаемое в списке автодополнения |
| source | string | Тип источника: extension, prompt, skill и т. д. |
| sourceInfo | объект | Подробные метаданные источника, например путь расширения, которое его зарегистрировало |
Динамическое управление инструментами
Включайте и отключайте инструменты во время выполнения.
Типичный вариант использования — временно отключить инструменты операций записи, чтобы ИИ мог только читать, но не изменять данные во время одной задачи:
Пример
// Получить список включенных в данный момент инструментов
const active = pi.getActiveTools();
// Например: ["read", "bash", "edit", "write"]
// Получить метаданные для всех зарегистрированных инструментов
const all = pi.getAllTools();
// Отфильтровать встроенные инструменты
const builtinTools = all.filter(
t => t.sourceInfo.source === "builtin"
);
// Фильтровать инструменты, зарегистрированные расширениями
const extTools = all.filter(
t => t.sourceInfo.source !== "builtin"
&& t.sourceInfo.source !== "sdk"
);
// Динамически включать пользовательские инструменты (сохраняя существующие инструменты)
pi.setActiveTools([...new Set([...active, "my_tool"])]);
// Переключиться в режим только для чтения: оставить только инструменты типа чтения,
// исключая bash / edit / write; в этом состоянии ИИ не может выполнять команды или изменять файлы
pi.setActiveTools(["read", "grep", "find", "ls"]);
Здесь setActiveTools и параметр командной строки--tools / --exclude-toolsдействуют на один и тот же набор инструментов.
Параметр CLI определяет начальный набор при запуске, а setActiveTools динамически корректирует его во время выполнения; их можно использовать вместе.
Изменения, передаваемые в setActiveTools, должны быть аддитивными; удаление уже активированных инструментов в том же вызове лишит оптимизации ленивой загрузки.
Кроме того, активация инструментов с помощью promptSnippet или promptGuidelines приведёт к перестроению системного промпта; даже если модель поддерживает ленивую загрузку, это может аннулировать кэшированный префикс промпта.
Другие расширения