Многоплатформенное развертывание Pi Agent
Pi Agent поддерживает работу на Windows, macOS, Linux и Android (Termux).
В этой главе рассматриваются основы конфигурации для каждой платформы.
Конфигурация macOS
macOS — полноценно поддерживаемая платформа для Pi Agent, и большинство функций работают из коробки.
Рекомендуемые терминалы
| Терминал | Способ установки | Причина рекомендации |
|---|---|---|
| iTerm2 | brew install --cask iterm2 | Нативная поддержка True Color, хороший рендеринг изображений, богатые возможности |
| Kitty | brew install --cask kitty | Рендеринг с ускорением на GPU, быстрый |
| Warp | brew install --cask warp | Современный терминал, встроенные функции ИИ |
Проверка поддержки True Color
$ echo $COLORTERM truecolor
Псевдонимы Shell
Pi Agent по умолчанию запускает bash в неинтерактивном режиме (т.е.bash -c), он не выполняет автоматическое раскрытие ваших псевдонимов Shell.
Основной механизм: научить Pi распознавать псевдонимы Shell. Чтобы использовать пользовательские псевдонимы в Pi, запишите следующую конфигурацию в ~/.pi/agent/settings.json (или ~/.atomic/agent/settings.json), чтобы при запуске он активно загружал файл конфигурации вашей оболочки (например, ~/.zshrc или ~/.bashrc):
{
"shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
}Примечание:Пожалуйста, измените путь ~/.zshrc на фактический путь к вашему файлу конфигурации Shell.
Конфигурация Windows
В Windows вы можете запускать Pi Agent через нативный терминал или WSL2. Ключевой момент — выбрать подходящий терминал и устранить конфликты сочетаний клавиш.
Рекомендуемый способ установки
В Windows рекомендуется использоватьWindows Terminalс WSL2 или напрямую использовать Node.js.
Установите Git for Windows
Pi по умолчанию использует Git Bash для выполнения команд в Windows.
При запуске он выполняет поиск по порядку, включая путь по умолчаниюC:\Program Files\Git\bin\bash.exe。
Если Git for Windows не установлен, bash не будет найден при запуске; просто установите Git for Windows, чтобы решить эту проблему.
Если вы не хотите использовать Git Bash, вы также можетеshellPathнастроить другой bash или черезdefaultToolsпереключиться на инструмент PowerShell.
Установите Node.js
сnodejs.orgскачайте установщик или используйте winget:
# PowerShell > winget install OpenJS.NodeJS.LTS
Установите Pi Agent
Выполните следующее в PowerShell или CMD в Windows Terminal:
# PowerShell > npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Сочетания клавиш для Windows
| Функция | Сочетание клавиш Windows | Сочетание клавиш macOS/Linux |
|---|---|---|
| Вставить изображение | Alt+V | Ctrl+V |
| Многострочный ввод | Ctrl+Enter | Shift+Enter |
| Отправить последующее сообщение | Ctrl+Q (отправить), Alt+Q (извлечь) | Alt+Enter |
В Windows Ctrl+Q отправляет дополнительные сообщения, а Alt+Q по умолчанию извлекает сообщения из очереди; переназначение не требуется.
Настройка требуется только в том случае, если вы хотите переключиться на Alt+Enter.
В Windows Terminal Alt+Enter по умолчанию является сочетанием клавиш для полноэкранного режима.
Если вы хотите, чтобы Pi Agent получал это сочетание клавиш, нужно удалить или переназначить сочетание клавиш полноэкранного режима в настройках Windows Terminal.
Найдите "toggleFullscreen" в настройках и измените его сочетание клавиш на другое.
Затем установите привязку pi'sapp.message.followUpна alt+enter.
Поведение при приостановке
Нативные терминалы Windows не поддерживают управление заданиями Unix.
В нативной Windows Ctrl+Z назначен на отмену редактирования; вам нужно назначить собственное сочетание клавиш для приостановки.
В WSL используйте Alt+Z для приостановки; Ctrl+Z по-прежнему может приостанавливать процессы, а fg может вернуть их в обычное состояние.
Конфигурация Termux (Android)
Pi Agent можно запускать на устройствах Android через Termux.
Шаги установки
Сначала установите сам Termux. Скачайте последний установочный пакет из F-Droid, затем выполните следующие команды в Termux.
Пример
pkg update && pkg upgrade
pkg install nodejs termux-api
# 2. Установите Pi Agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 3. Проверьте установку
pi --version
# 4. Перед первым использованием общего хранилища выполните её один раз, чтобы предоставить доступ к таким путям, как каталог Downloads
termux-setup-storage
Помимо самого Termux, вам также нужно установить приложение Termux:API на телефон.
Это приложение также можно получить из F-Droid; от него зависят такие возможности интеграции с устройством, как буфер обмена.
Если установить только пакет командной строки termux-api, не устанавливая приложение Termux:API, соответствующие команды не будут работать.
Примечания
Среда Termux отличается от обычного Linux; обратите внимание на следующие моменты.
| Item | Описание |
|---|---|
| Путь хранения | Путь доступа к хранилищу в Termux отличается от обычного Linux; используйте ~/storage/shared/ для доступа к общему хранилищу и перед первым использованием запустите termux-setup-storage. |
| Отображение изображения | Отображение изображений может быть ограничено на некоторых терминалах |
| Буфер обмена | Интеграция буфера обмена Termux поддерживает только текст; вставка изображений недоступна |
| Удобство ввода | Для лучшего опыта редактирования рекомендуется использовать Bluetooth-клавиатуру или OTG-клавиатуру |
Интеграция с tmux
Pi Agent нормально работает в сессиях tmux.
Преимущества
Запуск Pi Agent в tmux в основном нужен для сохранения сессий и возможностей нескольких окон.
| Преимущество | Описание |
|---|---|
| Сохранение сессий | Даже если SSH отключится, Pi Agent продолжит работать в фоновом режиме |
| Многооконный макет | Запустите Pi Agent в одном окне, а код просматривайте в другом |
| Удалённая разработка | Используйте Pi Agent после подключения к серверу по SSH |
Рекомендуемая конфигурация
Добавьте следующее в ~/.tmux.conf:
Пример
# Обеспечьте поддержку True Color
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"
# Включить расширенное сообщение о клавишах и пересылку комбинаций клавиш в формате CSI-u
# Без этих двух строк Shift+Enter в tmux превращается в обычный Enter
set -g extended-keys on
set -g extended-keys-format csi-u
# Увеличьте буфер прокрутки (полезно при просмотре больших выводов ИИ)
set -g history-limit 50000
Среди них две строки extended-keys — ключевая конфигурация; они гарантируют, что такие комбинации клавиш, как Shift+Enter и Ctrl+Enter, правильно передаются в pi.
extended-keys-format csi-u требует tmux 3.5 или выше; вы можете использоватьtmux -V, чтобы проверить версию.
$ tmux -V tmux 3.5a
Без этих двух строк Shift+Enter в tmux превращается в обычный Enter, и многострочный ввод отправит сообщение сразу.
Если версия tmux от 3.2 до 3.4, пропустите строку csi-u; pi по-прежнему поддерживает формат xterm по умолчанию в tmux.
Оптимизация настроек терминала
Независимо от того, какой терминал вы используете, следующие настройки напрямую влияют на качество отображения Pi Agent.
| Настройка | Рекомендуемое значение | Описание |
|---|---|---|
| True Color | Включить | Убедитесь, что терминал поддерживает 24-битный цвет |
| Font | Моноширинный шрифт (например, JetBrains Mono, Fira Code) | Обеспечьте выравнивание кода и отображение специальных символов |
| Буфер прокрутки | Не менее 10000 строк | Просмотр больших объёмов вывода ИИ и исторических сообщений |
| Терминал VS Code | Установите minimumContrastRatio в 1 | Обеспечьте точное отображение цветов темы |
Настройка встроенного терминала VS Code
Добавьте следующую конфигурацию в файл settings.json VS Code; путь к файлу:~/Library/Application Support/Code/User/settings.json(macOS):
Пример
"terminal.integrated.minimumContrastRatio": 1,
"terminal.integrated.fontFamily": "JetBrains Mono",
"terminal.integrated.fontSize": 13
}
Рекомендации по псевдонимам командной оболочки
Ниже приведён полный набор псевдонимов Pi Agent, совместимый с разными платформами. Вы можете добавить их в ~/.zshrc, ~/.bashrc или аналогичный файл конфигурации оболочки:
Пример
# Общие псевдонимы Pi Agent
alias pin='pi --name' # Запустить именованную сессию
alias pic='pi -c' # Продолжить последнюю сессию
alias pir='pi -r' # Возобновить сессию из истории
alias piq='pi -p' # Быстрый разовый вопрос-ответ
alias pip='pi --print' # Режим печати (то же, что -p)
alias pif='pi --fork' # Форк сессии
alias pii='pi --no-session' # Временный режим (не сохраняется)
alias piro='pi --tools read,grep,find,ls' # Режим только для чтения
alias pirev='pi -p "Проверьте проиндексированные изменения кода (git diff --cached)"'
Если вы используете fish shell, замените alias на abbr или используйте синтаксис alias в fish.
# fish shell 使用 abbr 定义缩写 abbr -a pic pi -cДругие расширения