Pi Coding Agent: руководство по началу работы
Pi — это ИИ-агент для программирования, работающий в терминале, похожий на такие инструменты, как Claude Code и OpenAI Codex CLI.
Официальная философия Pi такова:«Есть много агентных обвязок, но эта — ваша»(Есть много инструментов для агентов, но этот — ваш).
Дайте Pi одну фразу, и он сможет читать файлы, записывать файлы и выполнять команды в каталоге вашего проекта, повторно вызывая большую языковую модель, пока задача не будет выполнена.
Основная философия — минимальное ядро плюс предельная расширяемость, позволяющая вам подстраивать инструмент под себя, а не наоборот — адаптироваться под инструмент.
Полное руководство по Pi Agent:https://www.example.com/pi-agent/pi-agent-tutorial.html
Что включает Pi
Pi — это не одна программа, а набор инструментов, состоящий из четырёх npm-пакетов.
Обычным пользователям достаточно установить только пакет верхнего уровня@earendil-works/pi-coding-agent, и вы получите готовый к использованию агент командной строки.
Для кого это
Pi особенно подходит для следующих сценариев и пользователей:
- Разработчики, которые предпочитают работу в терминале и не хотят переключаться туда-сюда между IDE и командной строкой
- Продвинутые пользователи, которым нужен глубоко настраиваемый инструмент — даже такой, который позволяет Агенту переписывать самого себя
- Люди, которым нужно одновременно подключаться к нескольким большим языковым моделям (Anthropic, OpenAI, Google и т. д.)
- Разработчики, которые хотят встроить возможности Агента в свои программы (через SDK или режим RPC)
Примечание: Pi по умолчанию работает с вашими пользовательскими правами и не имеет встроенной песочницы. Перед использованием его в недоверенных репозиториях, пожалуйста, прочитайте раздел «Заметки по безопасности» этой статьи.
Основная философия дизайна: примитивы, а не возможности
Понимание философии дизайна Pi поможет вам понять, почему он намеренно не «встраивает» многие возможности, которые есть у других Агентов.
Pi называет эту концепциюПримитивы, а не возможности(предоставление примитивов, а не возможностей).
Возможности, намеренно не встроенные
Pi не включает следующие возможности; вместо этого он позволяет реализовать их по мере необходимости через расширения или внешние инструменты:
| Функции, не включённые в состав | Альтернатива от Pi |
|---|---|
| Интеграция протокола MCP | Напишите инструмент в виде CLI с README или установите расширение MCP |
| Субагенты | Используйте tmux для открытия нескольких сессий или напишите собственное расширение |
| Всплывающее окно подтверждения разрешения | Запустите его в контейнере или напишите собственное расширение для потока подтверждения |
| Режим планирования | Запишите план в файл или напишите расширение |
| Встроенные задачи | Используйте файл TODO.md или установите расширение |
| Фоновый bash | Используйте tmux для полной наблюдаемости |
Зачем это делать
Pi считает, что эти возможности сильно различаются в разных командах, и принудительное их встраивание сделало бы инструмент раздутым и плохо приспособленным к реальным рабочим процессам.
Поэтому его подход таков: сохранять чистое минимальное ядро, а все "функции" превращать в устанавливаемые, доступные для написания, разделяемые расширения, навыки, шаблоны промптов и темы.
Вы даже можете попросить Pi написать эти функции за вас, и после того как они написаны, используйте/reloadreload, и это сразу работает.
Эту фразу стоит запомнить:Адаптируйте Pi под свои рабочие процессы, а не наоборот(Заставьте Pi адаптироваться к вашему рабочему процессу, а не вам адаптироваться к Pi).
Архитектура и основные пакеты
Pi состоит из четырёх чётко разделённых на слои пакетов, где верхние слои зависят от нижних.
Тот, который вы обычно используетеpicommand — это всего лишь точка входа, предоставляемая самым верхним пакетом.
Четыре основных пакета
| Название пакета | Назначение | Когда его использовать отдельно |
|---|---|---|
@earendil-works/pi-coding-agent | Интерактивный CLI агента для программирования — точка входа, которую пользователи устанавливают и используют напрямую | В большинстве случаев нужен только этот |
@earendil-works/pi-agent-core | Среда выполнения агента, отвечающая за цикл вызовов инструментов и управление состоянием | Когда вы хотите сами создать агента, не связанного с программированием |
@earendil-works/pi-ai | Унифицированный API LLM от нескольких поставщиков (OpenAI, Anthropic, Google и т. д.) | Когда вам нужен всего один унифицированный интерфейс для вызова нескольких моделей |
@earendil-works/pi-tui | Библиотека терминального UI с поддержкой отрисовки diff | Когда вы хотите написать собственное терминальное приложение |
Четыре режима работы
Pi не ограничивается интерактивным режимом; он предлагает четыре режима для разных сценариев:
| Mode | Описание | Типичный сценарий |
|---|---|---|
| Интерактивный | Полноценный терминальный интерфейс | Ежедневное программирование, диалоговая разработка |
| Print / JSON | pi -p "提问"Одноразовый вывод;--mode jsonПоток событий вывода | Автоматизация скриптов, конвейерная обработка |
| RPC | Обмен данными по протоколу JSON через stdin/stdout | Интеграция программ, не использующих Node |
| SDK | Встраивание в качестве библиотеки в ваше приложение | Интеграция возможностей Agent в ваши собственные продукты |
Установка
Pi предлагает несколько методов установки, охватывающих macOS, Linux и Windows.
Наиболее распространённый подход — глобальная установка через npm, но вы также можете использовать официальный скрипт для установки в один клик.
Способ 1: Скрипт в один клик (рекомендуется для начинающих)
Пользователи macOS и Linux используют curl:
curl -fsSL https://pi.dev/install.sh | sh
Пользователи Windows используют PowerShell:
powershell -c "irm https://pi.dev/install.ps1 | iex"
Способ 2: Глобальная установка npm
Если у вас уже установлен Node.js, просто установите его глобально с помощью менеджера пакетов.
Обратите внимание на--ignore-scriptsпараметр: он пропускает скрипты жизненного цикла установки зависимостей. Pi не нужны эти скрипты для обычного использования, и его добавление безопаснее.
# npm 安装 npm install -g --ignore-scripts @earendil-works/pi-coding-agent # pnpm 安装 pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent # bun 安装 bun add -g --ignore-scripts @earendil-works/pi-coding-agent
Проверка установки
После установки проверьте номер версии, чтобы убедиться, что установка прошла успешно:
pi --version
Например:
$ pi --version 0.80.6
Удаление
Способ удаления зависит от того, как вы изначально установили его:
# curl 装的或 npm 装的 npm uninstall -g @earendil-works/pi-coding-agent # pnpm 装的 pnpm remove -g @earendil-works/pi-coding-agent # bun 装的 bun uninstall -g @earendil-works/pi-coding-agent
Примечание: удаление Pi не удалит вашу конфигурацию. Настройки, учётные данные, записи сеансов и установленные пакеты Pi хранятся в
~/.pi/agent/каталоге и требуют ручной очистки.
Настройка поставщика моделей
Сам Pi не включает большую языковую модель; он требует, чтобы вы предоставили учётные данные для доступа как минимум к одному поставщику моделей.
Есть два способа настройки: вход по подписке или API Key.
Способ 1: вход по подписке (самый простой)
Если у вас уже есть подписка Claude Pro/Max, ChatGPT Plus/Pro или GitHub Copilot, вы можете войти напрямую и использовать её.
После запуска Pi выполните/login, затем выберите поставщика:
# 启动 pi pi # 在 pi 里执行登录命令 /login
Есть три необязательных поставщика по подписке:
| Provider | Требование | Описание |
|---|---|---|
| Claude Pro / Max | Подписка Anthropic | Использование сторонних инструментов оплачивается за Token и не учитывается в квоте вашей подписки. |
| ChatGPT Plus / Pro（Codex） | Подписка OpenAI | Официально признано OpenAI через Codex для OSS |
| GitHub Copilot | Подписка Copilot | Если появляется сообщение, что модель не поддерживается, сначала нужно включить соответствующую модель в VS Code |
После входа учётные данные сохраняются в~/.pi/agent/auth.json, и автоматически обновляются по истечении срока. Для выхода используйте/logout。
Способ 2: API Key (наиболее гибкий)
Передача API Key через переменные окружения — самый универсальный подход. Например, с использованием ключа Anthropic:
# 设置环境变量后启动 export ANTHROPIC_API_KEY=sk-ant-... pi
Вы также можете запустить в Pi/loginи выбрать провайдера типа API Key, и сохранить ключ вauth.json。
Переменные окружения для популярных провайдеров
Pi поддерживает более 15 провайдеров; наиболее распространённые из них перечислены ниже:
| Provider | Переменная окружения | Имя ключа в auth.json |
|---|---|---|
| Anthropic | ANTHROPIC_API_KEY | anthropic |
| OpenAI | OPENAI_API_KEY | openai |
| Google Gemini | GEMINI_API_KEY | |
| DeepSeek | DEEPSEEK_API_KEY | deepseek |
| Groq | GROQ_API_KEY | groq |
| Mistral | MISTRAL_API_KEY | mistral |
| xAI | XAI_API_KEY | xai |
| OpenRouter | OPENROUTER_API_KEY | openrouter |
| Hugging Face | HF_TOKEN | huggingface |
Примечание:
auth.jsonУчётные данные в ... имеют приоритет над переменными окружения. Если настроены и те и другие, первыеauth.jsonимеют преимущество.
Структура auth.json
Если вы хотите управлять учётными данными вручную, вы можете напрямую редактировать~/.pi/agent/auth.json. При создании этому файлу устанавливаются права 0600 (доступен для чтения и записи только текущему пользователю):
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." },
"openai": { "type": "api_key", "key": "sk-..." },
"google": { "type": "api_key", "key": "..." }
}
Поле Key также поддерживает три расширенных синтаксических формы для удобного получения значений из менеджера паролей или переменных окружения:
| Синтаксис | Значение | Пример |
|---|---|---|
"!command" | Начинается с восклицательного знака, выполняет команду и берёт stdout в качестве Key | "!op read 'op://vault/item/cred'" |
"$variable name" | Получает значение переменной окружения | "$MY_ANTHROPIC_KEY" |
| Обычный литерал | Используется напрямую как Key | "sk-ant-..." |
Облачные платформы-провайдеры
Если вы используете облачные сервисы моделей, Pi также поддерживает Azure OpenAI, Amazon Bedrock, Google Vertex AI, Cloudflare и др.
Обычно для них требуется дополнительная настройка endpoint, региона или имени развёртывания. Рассмотрим Azure OpenAI в качестве примера:
# Azure OpenAI 所需的环境变量 export AZURE_OPENAI_API_KEY=... export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com # 可选：API 版本与部署名映射 export AZURE_OPENAI_API_VERSION=2024-02-01 export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4o=my-gpt4o
Настройка провайдера DeepSeek
Pi поддерживает пользовательские провайдеры через models.json. Путь к файлу конфигурации:
- Linux / macOS：~/.pi/agent/models.json
- Windows：%USERPROFILE%\.pi\agent\models.json
Сначала получите API Key на открытой платформе DeepSeek:https://platform.deepseek.com/api_keys。
{
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com",
"api": "openai-completions",
"apiKey": "$DEEPSEEK_API_KEY",
"models": [
{
"id": "deepseek-v4-pro",
"name": "DeepSeek V4 Pro",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 1.74,
"output": 3.48,
"cacheRead": 0.145,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
},
{
"id": "deepseek-v4-flash",
"name": "DeepSeek V4 Flash",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 0.14,
"output": 0.28,
"cacheRead": 0.028,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
}
]
}
}
}
Задайте переменные окружения:
Пользователи Linux / Mac:
export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Пользователи Windows:
$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Перейдите в каталог проекта и выполните команду pi:
cd /path/to/my-project pi
Введите/model, чтобы открыть переключатель моделей, выберите deepseek, затем выберите DeepSeek-V4-Pro или DeepSeek-V4-Flash.
Дополнительные параметры конфигурации см. здесь:https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md。
Порядок разрешения учетных данных
Когда Pi нужны учетные данные для провайдера, он ищет их в следующем порядке и использует первые найденные:
| Приоритет | Source |
|---|---|
| 1 (наивысший) | Командная строка--api-keyАргументы |
| 2 | auth.jsonЗаписи в ... (API-ключ или OAuth-токен) |
| 3 | Переменная окружения |
| 4 | models.jsonКлюч пользовательского провайдера в ... |
Первый запуск
После настройки учетных данных перейдите в каталог проекта и запустите напрямую.piЗапуск.
# 进入项目目录 cd /path/to/project # 启动 pi pi
После запуска сразу введите предложение и нажмите Enter, например попросите проанализировать этот репозиторий:
Summarize this repository and tell me how to run its checks.
Pi автоматически прочитает файлы, выполнит команды, а затем даст сводку и способы проверки.
Запрос доверия к проекту
Если в текущем каталоге или родительском каталоге есть.piКонфигурация, расширения, навыки и другие ресурсы уровня проекта — Pi сначала спросит, доверяете ли вы этому проекту, во время интерактивного запуска.
Это нужно, чтобы репозиторий не мог незаметно загружать свои расширения или изменять настройки без вашего ведома.
Примечание: решение о доверии сохраняется в
~/.pi/agent/trust.json. Неинтерактивный режим (-p、--mode json) не будет появляться, и по умолчанию используетdefaultProjectTrusthandle.
Как работает агент
Каждый раз, когда вы отправляете сообщение, Pi запускает цикл агента. Понять этот цикл — значит понять, как работает Pi.
В центре — цикл хода: модель может вызывать инструменты на каждом ходу, Pi выполняет инструменты и вставляет результаты обратно в контекст, затем позволяет модели продолжить, пока модель больше не вызывает инструменты и не даёт окончательный ответ.
Четыре встроенных инструмента
По умолчанию Pi даёт модели только четыре инструмента, охватывающих основные возможности чтения, записи и выполнения в программировании.
| Инструмент | Назначение | Включено по умолчанию |
|---|---|---|
read | Чтение содержимого файла | Да |
write | Создание или перезапись файлов | Да |
edit | Применение частичных патч-изменений к файлам | Да |
bash | Запуск shell-команд | Да |
grep | Поиск по содержимому файлов | Нет (нужно включить через параметры инструментов) |
find | Поиск файлов по критериям | Нет (нужно включить через параметры инструментов) |
ls | Список содержимого каталога | Нет (нужно включить через параметры инструментов) |
Управление доступными инструментами
Вы можете точно управлять тем, какие инструменты может использовать модель, с помощью аргументов командной строки.
Это полезно, когда нужно ограничить возможности Агента, например, позволить ему только проверять код, не внося изменений:
# 只读模式：只允许读取和搜索类工具 pi --tools read,grep,find,ls -p "审查这段代码" # 禁用某个工具，其余保留 pi --exclude-tools ask_question # 关闭所有内置工具，只保留扩展提供的工具 pi --no-builtin-tools -e ./my-extension.ts # 完全禁用工具，纯对话 pi --no-tools -p "解释一下这个概念"
Напоминание: Pi работает в вашем текущем рабочем каталоге и может изменять ваши файлы. Рекомендуется использовать его вместе с системой контроля версий, например git, чтобы в любой момент можно было легко откатить изменения.
Задайте инструкции для проекта с помощью AGENTS.md
AGENTS.md — это файл инструкций проекта для Pi, который сообщает модели, какие правила есть в проекте, как его запускать и на что следует обращать внимание.
Он работает аналогично CLAUDE.md из Claude Code — и Pi поддерживает оба имени файла.
Напишите AGENTS.md
Создайте его в корневом каталоге проектаAGENTS.md, напишите правила, которым должна следовать модель:
# 项目指令 - 改完代码后运行 `npm run check`。 - 不要在本地跑生产环境的数据库迁移。 - 回答尽量简洁。
Откуда Pi загружает инструкции
Pi загружает файлы инструкций из нескольких мест при запуске, в порядке убывания области действия:
| Расположение | Область действия | Описание |
|---|---|---|
~/.pi/agent/AGENTS.md | Глобальный | Общие инструкции, которые применяются ко всем вашим проектам |
Родительского каталогаAGENTS.md | Уровень проекта | Выполняет поиск вверх уровень за уровнем от текущего каталога |
Текущей директорииAGENTS.md | Уровень проекта | Самые конкретные инструкции с наивысшим приоритетом |
Для имён файлов,AGENTS.mdилиCLAUDE.mdлюбой из них работает; Pi распознаёт все.
Изменение системного промпта
AGENTS.md — это дополнительные инструкции, добавляемые к системному промпту по умолчанию. Если вы хотите более тщательный контроль, вы можете заменить весь системный промпт.
Размещение его в проекте.pi/SYSTEM.mdзаменит системный промпт по умолчанию; размещение.pi/APPEND_SYSTEM.mdозначает добавление (глобально соответствующее~/.pi/agent/одноимённому файлу в).
Примечание: после изменения файлов инструкций не забудьте выполнить в Pi
/reloadreload, или перезапустите Pi, чтобы новые инструкции вступили в силу.
Основные операции в интерактивном режиме
Интерактивный режим — самая часто используемая форма Pi; освоив несколько ключевых операций, вы сможете эффективно им пользоваться.
Ссылка на файл: @
Введите в редакторе@Появится нечёткий поиск файлов проекта; после выбора содержимое файла отправляется модели в качестве контекста.
Вы также можете прикреплять файлы напрямую при запуске из командной строки:
# 启动时带上一个文件 pi @README.md "总结一下这个文件" # 带上多个文件一起审查 pi @src/app.ts @src/app.test.ts "一起审查这两个文件"
Запуск команды оболочки: !
В редакторе, если начать с!ввода команды, она выполнится напрямую, а вывод отправится модели:
# 运行命令，输出会进入模型上下文 !npm run lint # 两个感叹号：运行但不把输出加进模型上下文 !!npm run build
Переключение модели и усилий на размышление
Pi поддерживает переключение моделей и усилий на размышление в середине сеанса, чтобы адаптироваться к сложности различных задач.
| Действие | Горячая клавиша / Команда | Описание |
|---|---|---|
| Открыть выбор модели | /modelили Ctrl+L | Выбрать одну из всех доступных моделей |
| Переключить уровень размышлений | Shift+Tab | Циклически переключаться между off / minimal / low / medium / high / xhigh / max |
| Переключаться между избранными моделями | Ctrl+P / Shift+Ctrl+P | Быстро переключаться между несколькими предварительно выбранными моделями |
Вы также можете указать модель и уровень размышлений непосредственно при запуске:
# 指定厂商和模型 pi --provider openai --model gpt-4o "帮我重构" # 用 厂商/模型 的写法 pi --model openai/gpt-4o "帮我重构" # 用 名称:思考强度 的简写 pi --model sonnet:high "解决这个复杂问题" # 限定可在 Ctrl+P 里循环的模型 pi --models "claude-*,gpt-4o"
Советы по вводу и редактированию
| Действие | Метод | Описание |
|---|---|---|
| Многострочный ввод | Shift+Enter (Ctrl+Enter в Windows Terminal) | Вставить перенос строки в сообщение |
| Дополнение пути | Вкладка | Дополнение путей к файлам |
| Вставить изображение | Ctrl+V (используйте Alt+V в Windows) | Вы также можете перетаскивать изображения в терминал. |
| Копировать ответ | Ctrl+X | Копировать последнее сообщение ассистента |
| Внешний редактор | Ctrl+G | Открыть $VISUAL / $EDITOR для редактирования длинного текста |
Прервать во время выполнения
Пока агент работает, вам не нужно ждать; вы можете в любое время вставить сообщение.
| Клавиша | Поведение | Сценарий использования |
|---|---|---|
| Enter | Управляющее сообщение: доставляется сразу после завершения текущего инструмента, прерывая остальные инструменты. | Когда вы заметите, что он сбивается с курса, сразу же исправьте это. |
| Alt+Enter | Последующее сообщение: доставляется после полного завершения работы агентом. | Когда вы хотите добавить новое требование. |
| Escape | Прервать текущую работу и вернуть сообщения из очереди обратно в редактор. | Когда вы хотите остановиться и переорганизовать. |
Совет: В Windows Terminal Alt+Enter по умолчанию переключает полноэкранный режим; привязки клавиш для управления и последующих сообщений можно изменить в настройках,
steeringModeиfollowUpModeизменив их.
Краткий справочник по распространённым слэш-командам
Введите в редакторе/Появится автодополнение команд. Ниже приведены наиболее распространённые слэш-команды.
| Команда | Функция |
|---|---|
/login / /logout | Управление учётными данными OAuth или API Key |
/model | Переключить модель |
/scoped-models | Настроить, какие модели участвуют в цикле Ctrl+P |
/settings | Настроить усилие обдумывания, тему, доставку сообщений и т. д. |
/resume | Выбрать сессию из истории для продолжения |
/new | Начать новую сессию |
/name <名称> | Задать отображаемое имя текущей сессии |
/session | Просмотреть файл сессии, ID, количество сообщений, использование токенов и стоимость |
/tree | Перейти к любому узлу в дереве сессии и продолжить оттуда |
/fork | Создать форк новой сессии из исторического сообщения |
/clone | Скопировать текущую ветку как новую сессию |
/compact [提示] | Вручную сжать контекст, при необходимости с пользовательскими инструкциями |
/copy | Скопировать последнее сообщение ассистента в буфер обмена |
/export [文件] | Экспортировать сессию в формате HTML или JSONL |
/import <文件> | Импортировать и восстановить сессию из файла JSONL |
/share | Загрузить как приватный GitHub Gist, чтобы создать HTML-ссылку, которой можно поделиться |
/reload | Перезагрузить привязки клавиш, расширения, навыки, промпты, темы и файлы контекста |
/trust | Сохранить решение о доверии для текущего проекта |
/hotkeys | Показать все привязки клавиш |
/changelog | Просмотреть историю обновлений версии |
/quit | Выйти из Pi |
Управление сессиями: древовидная история
Сессии Pi — не прямая линия; они представляют собой дерево.
Это означает, что если вы ответвляетесь в любом историческом узле, исходная ветвь не теряется; все ветви существуют в одном файле сессии.
Где хранятся сессии
Сессии автоматически сохраняются в~/.pi/agent/sessions/, сгруппированные по рабочему каталогу.
Восстановить или просмотреть исторические сессии из командной строки:
# 继续最近一次会话 pi -c # 浏览并选择一个历史会话 pi -r # 给会话起个名字，方便日后查找 pi --name "my task" # 打开指定的会话文件或 ID pi --session <path|id> # 临时会话，不保存 pi --no-session
Навигация по дереву сессий
использовать/treeВы можете открыть древовидное представление сессии и перейти к любому историческому узлу, чтобы продолжить.
Продолжение оттуда создаёт новую ветку, при этом исходная ветка остаётся без изменений.
Форкинг и клонирование
| Команда | Поведение | Разница |
|---|---|---|
/fork | Создать форк новой сессии из более раннего сообщения пользователя | Перезапустить с определённого момента в истории |
/clone | Клонировать текущую активную ветку в новую сессию | Создать копию на основе последнего состояния |
Сжатие контекста
Когда разговор становится длинным и приближается к лимиту контекста модели, Pi автоматически сжимает предыдущие сообщения в сводку.
Вы также можете запустить это вручную с помощью/compact, и вы можете добавить пользовательскую инструкцию, указывающую, что сохранять при сжатии:
# 在 pi 里手动压缩，并要求保留最近改动 /compact 重点保留最近的改动和错误处理
Экспорт и совместное использование
Экспортируйте сеанс в HTML для архивирования или презентации:
# 导出为 HTML 文件 /export my-session.html # 上传为私有 GitHub Gist，得到分享链接 /share
Неинтерактивный режим и интеграция
Pi предназначен не только для интерактивных бесед; его также можно использовать как инструмент командной строки, поток событий, RPC-сервис и библиотеку SDK.
Разовый вопрос: режим print
использовать-pПусть Pi ответит, а затем завершит работу; подходит для вызова из скриптов:
# 直接提问 pi -p "总结一下这个代码库" # 配合管道，把内容喂给 Pi cat README.md | pi -p "总结这段文字" # 带图片提问 pi -p @screenshot.png "这张图里是什么？"
Поток событий: режим JSON
--mode jsonВыводит все события в виде строк JSON для удобного программного разбора:
# 输出 JSON 事件流 pi --mode json -p "列出 src 下所有 .ts 文件"
Интеграция процессов: режим RPC
--mode rpcИспользует протокол JSON через stdin/stdout, подходит для программ, не использующих Node (например, Python, Go), чтобы управлять Pi.
Экспорт существующего сеанса
Не запуская новую сессию, напрямую экспортируйте существующий файл сессии в HTML:
# 把会话文件导出为 HTML pi --export session.jsonl output.html
Режим SDK
Если вы хотите встроить возможности Pi в собственное приложение Node, вы можете использовать режим SDK, чтобы подключить его как библиотеку.
Это более тесная интеграция, чем RPC; см. раздел SDK в официальной документации:https://pi.dev/docs/latest/sdk。
Расширения
Расширения — основа расширяемости Pi. Это модули TypeScript, которые могут подписываться на события жизненного цикла, регистрировать пользовательские инструменты и добавлять команды и сочетания клавиш.
Расширения загружаются через jiti, поэтому можно писать на TypeScript напрямую без компиляции.
Куда помещать расширения
| Расположение | Область действия |
|---|---|
~/.pi/agent/extensions/*.ts | Глобально, применяется ко всем проектам |
.pi/extensions/*.ts | На уровне проекта, действует только для текущего проекта |
Это также может быть в форме подкаталога (扩展名/index.ts), или сpackage.jsonполноценный пакет.
Минимальный пример расширения
Следующее расширение демонстрирует три вещи: уведомление при запуске, перехват опасных команд и регистрацию пользовательского инструмента и команды.
// 文件路径：~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
// 扩展导出一个默认工厂函数，接收 ExtensionAPI
export default function (pi: ExtensionAPI) {
// 1. 监听 session_start 事件：会话启动时弹个通知
pi.on("session_start", async (_event, ctx) => {
ctx.ui.notify("扩展已加载！", "info");
});
// 2. 监听 tool_call 事件：拦截危险的 bash 命令
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
// 弹确认框，用户拒绝就阻止执行
const ok = await ctx.ui.confirm("危险操作！", "允许执行 rm -rf 吗？");
if (!ok) return { block: true, reason: "被用户阻止" };
}
});
// 3. 注册一个自定义工具，模型可以调用它
pi.registerTool({
name: "greet",
label: "打招呼",
description: "按名字向某人打招呼",
parameters: Type.Object({
name: Type.String({ description: "要打招呼的名字" }),
}),
async execute(toolCallId, params, signal, onUpdate, ctx) {
return {
content: [{ type: "text", text: `你好，${params.name}！` }],
details: {},
};
},
});
// 4. 注册一个斜杠命令 /hello
pi.registerCommand("hello", {
description: "打个招呼",
handler: async (args, ctx) => {
ctx.ui.notify(`你好 ${args || "world"}！`, "info");
},
});
}
После написания используйте-eпараметр для временной загрузки для тестирования:
# 临时加载一个扩展来测试 pi -e ./my-extension.ts
Что могут делать расширения
Возможности расширений выходят далеко за пределы вышеперечисленного; они могут вмешиваться почти в каждую часть рабочего процесса Pi:
| Способность | Соответствующий метод | Типичное использование |
|---|---|---|
| Регистрация пользовательских инструментов | pi.registerTool() | Предоставление модели возможности вызывать ваш бизнес-интерфейс |
| Регистрация команд | pi.registerCommand() | Добавление собственных слэш-команд |
| Регистрация сочетаний клавиш | pi.registerShortcut() | Привязка пользовательских сочетаний клавиш |
| Перехват вызовов инструментов | tool_callEvent | Подтверждение разрешений, перезапись команд |
| Изменение контекста | contextEvent | Фильтрация истории, внедрение RAG-контента |
| Внедрение сообщений | pi.sendMessage() | Динамическое дополнение контекста |
| Регистрация провайдеров | pi.registerProvider() | Доступ к приватным шлюзам моделей |
| Пользовательский интерфейс | ctx.uiСерия | Диалоги, строка состояния, компоненты |
Совет: В репозитории Pi более 50 примеров расширений, охватывающих субагентов, режим планирования, шлюзы разрешений, выполнение по SSH, песочницу и т. д. Это лучший справочник для изучения разработки расширений.
Навыки
Навыки — это ещё один тип переиспользуемых пакетов возможностей. Отличие от расширений в том, что навыки в основном представляют собой инструкции и скрипты для модели, загружаемые по требованию.
Pi реализует стандарт Agent Skills, поэтому может напрямую использовать навыки из таких инструментов, как Claude Code и OpenAI Codex.
Как работают навыки
Навыки используют принцип постепенного раскрытия.
При запуске Pi помещает в системную подсказку только имя и описание каждого навыка; когда задача совпадает, модель используетreadинструмент для загрузки полного описания навыка.
Таким образом, можно установить много навыков, не заполняя контекст с самого начала.
Куда помещать навыки
| Расположение | Область действия |
|---|---|
~/.pi/agent/skills/ | Глобальный |
~/.agents/skills/ | Глобально (общие для инструментов) |
.pi/skills/ | Уровень проекта (требуется доверие к проекту) |
.agents/skills/ | Уровень проекта (общий для инструментов) |
Структура навыка
Навык — это каталог, содержащийSKILL.mdкаталог, а остальные файлы можно организовывать свободно.
my-skill/
├── SKILL.md # 必需：前置信息 + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 按需加载的详细文档
│ └── api-reference.md
└── assets/
└── template.json
Как писать SKILL.md
В верхней части SKILL.md находится frontmatter, а под ним — тело инструкций для модели:
--- name: my-skill description: 这个技能做什么、什么时候用。要写具体。 --- # My Skill ## Setup 首次使用前运行一次： ```bash cd /path/to/skill && npm install ``` ## Usage ```bash ./scripts/process.sh <input> ```
Два самых важных поля в frontmatter:
| Поле | Обязательно? | Описание |
|---|---|---|
name | Обязательный | До 64 символов, только строчные буквы, цифры и дефисы |
description | Обязательный | До 1024 символов, определяет, когда модель загружает этот навык. Будьте конкретны. |
Напоминание:
descriptionТо, насколько хорошо он написан, напрямую определяет, будет ли модель использовать этот навык в нужный момент. Написать «Обрабатывать PDF-файлы, извлекать текст и таблицы, заполнять формы, объединять несколько PDF» гораздо лучше, чем написать «Помочь обработать PDF».
Ручной вызов навыков
Модель не всегда может загрузить навык самостоятельно. Вы можете использовать/skill:名称Принудительно загрузить и выполнить:
# 加载并执行技能 /skill:brave-search # 带参数加载技能 /skill:pdf-tools extract
Управление пакетами Pi
Расширения, навыки, шаблоны промптов и темы можно упаковать в пакеты Pi и делиться ими или устанавливать их через npm или git.
Pi имеет встроенный набор команд управления пакетами, позволяющий расширять возможности так же, как при установке плагинов.
Установка и удаление
# 从 npm 安装一个包 pi install npm:@foo/pi-tools # 从 git 仓库安装 pi install git:github.com/badlogic/pi-doom # 项目本地安装（加 -l） pi install npm:@foo/pi-tools -l # 卸载 pi remove npm:@foo/pi-tools
Обновления и просмотр
| Команда | Функция |
|---|---|
pi list | Список установленных пакетов |
pi update | Обновить только сам Pi |
pi update --all | Обновить Pi и все пакеты |
pi update --extensions | Обновлять только пакеты, не изменяя сам Pi |
pi update --extension <源> | Обновить указанный пакет |
pi config | Включить или отключить ресурсы в пакете |
Примечания по безопасности
Безопасность — это важная часть, которую необходимо понять перед использованием Pi. Модель безопасности Pi отличается от многих инструментов Agent и требует вашего активного сотрудничества.
Нет встроенной песочницы
Pi Не включает встроенную песочницу, он работает от имени пользователя, который его запустил, и обладает всеми правами этого пользователя.
Встроенные инструменты могут читать и записывать файлы и выполнять команды оболочки; расширения — это модули TypeScript с теми же разрешениями, что и у процесса Pi.
Это сделано намеренно: Pi должен работать с локальным исходным кодом, вызывать проектные инструментальные цепочки и интегрироваться в среду разработки. Неполная внутрипроцессная песочница вводила бы людей в заблуждение, заставляя думать, что это граница безопасности, тогда как в действительности она всё ещё зависит от оболочки, файловой системы и учётных данных хоста.
Важно: настоящая изоляция должна обеспечиваться операционной системой или границами контейнера/виртуализации, а не изнутри Pi.
Доверие к проекту
Доверие к проекту определяет, загружает ли Pi настройки, ресурсы, расширения и пакеты уровня проекта.
Когда каталог содержит.pi/settings.json、.pi/extensions、.pi/skills、.pi/SYSTEM.mdи подобное содержимое, Pi потребует доверия перед загрузкой.
| Уровень доверия | Поведение | Способ настройки |
|---|---|---|
ask(По умолчанию) | Интерактивный запрос; игнорировать ресурсы проекта в неинтерактивном режиме | из settings.jsondefaultProjectTrust |
always | Всегда доверять ресурсам проекта | То же, что выше, или используйте-a / --approve |
never | Никогда не доверять, игнорировать ресурсы проекта | То же, что выше, или используйте-na / --no-approve |
Решения о доверии сохраняются в~/.pi/agent/trust.json, записываются по пути каталога, при этом приоритет имеет решение ближайшего родительского каталога.
Примечание: доверие к проекту — это лишь «загрузка ввода», которая не позволяет репозиториям незаметно изменять ваши настройки или расширения, ноне может сделать недоверенный код, промпты или выводы модели безопасными. Внедрение промптов в файлах репозитория, комментариях и документации — неотъемлемый риск локальных агентов, и Pi не может надёжно предотвратить его.
Обработка недоверенных задач или задач без присмотра
Для недоверенных репозиториев, сгенерированного кода, требующего тщательного контроля, или автоматизации без присмотра официальная рекомендация — запускать Pi в изолированной среде.
Рекомендуемые практики
- Поместите весь
piпроцесс в контейнер, виртуальную машину или песочницу - Монтируйте только те пути рабочей области, к которым должен иметь доступ агент
- Без необходимости не монтируйте каталог хоста
~/.pi/agent(который содержит ваши учётные данные и сеансы) - Передавайте только минимально необходимый код или используйте краткосрочные учётные данные
- Ограничивайте сетевой доступ, когда задача не требует интернета
- Проверяйте диффы и выходные данные перед копированием результатов обратно в доверенную систему
Напоминание: если вы монтируете рабочее пространство хоста в контейнер в режиме чтения-записи, записи внутри контейнера всё равно будут изменять файлы хоста. Для более надёжной защиты от случайных записей используйте монтирование только для чтения или копируйте файлы в песочницу и из неё.
Ресурсы и сообщество
Официальные ресурсы
- Репозиторий GitHub:github.com/earendil-works/pi
- Официальный сайт:pi.dev
- Официальная документация:pi.dev/docs/latest
- Пакет npm:@earendil-works/pi-coding-agent