Многоплатформенное развертывание Pi Agent

Pi Agent поддерживает работу на Windows, macOS, Linux и Android (Termux).

В этой главе рассматриваются основы конфигурации для каждой платформы.


Конфигурация macOS

macOS — полноценно поддерживаемая платформа для Pi Agent, и большинство функций работают из коробки.

Рекомендуемые терминалы

ТерминалСпособ установкиПричина рекомендации
iTerm2brew install --cask iterm2Нативная поддержка True Color, хороший рендеринг изображений, богатые возможности
Kittybrew install --cask kittyРендеринг с ускорением на GPU, быстрый
Warpbrew 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+VCtrl+V
Многострочный вводCtrl+EnterShift+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.

Пример

# 1. Обновите пакеты и установите Node.js и инструмент командной строки termux-api
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:

Пример

# Путь к файлу: ~/.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 или аналогичный файл конфигурации оболочки:

Пример

# Путь к файлу: ~/.zshrc (для пользователей bash — ~/.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
Другие расширения