Pi Web

English | 中文文档 | 日本語

Локальный браузерный интерфейс для pi coding agent. Pi Web использует те же локальные настройки и файлы сессий, что и pi, поэтому в браузере можно находить и продолжать диалоги, запускать агента, настраивать модели и ресурсы, а также просматривать файлы проекта.

Возможности

• Рабочее пространство сессий: просмотр, продолжение, переименование, экспорт и удаление диалогов, сгруппированных по проектам, с отображением состояния выполнения, использования контекста, стоимости и сведений о сжатии.
• Два способа создать ветку: New session создаёт независимый файл сессии из более раннего сообщения, а Edit from here создаёт ветку внутри текущей сессии.
• Инструменты для файлов проекта: просмотр и загрузка файлов, проверка Git Diff, предпросмотр исходного кода, Markdown, изображений, аудио, PDF и DOCX с автоматическим обновлением.
• Git worktree: переключение рабочих деревьев в боковой панели с сохранением общей группы сессий одного репозитория.
• Настройка через Web: управление входом в Provider и API Key, моделями, тестами моделей, пакетами плагинов и навыками без выхода из Pi Web.
• Интерфейс на английском и упрощённом китайском: при первом запуске Pi Web учитывает язык браузера, а затем язык можно переключить в верхней панели.

Быстрый старт

Для работы Pi Web требуется Node.js 22.19.0 или новее. Проверьте версию командой node --version, затем выполните:

npx @agegr/pi-web@latest

Когда сервер будет готов, CLI попытается открыть браузер автоматически. Если этого не произошло, откройте http://127.0.0.1:30141. По умолчанию Pi Web прослушивает только 127.0.0.1.

Если Provider модели ещё не настроен, откройте панель Models, войдите в учётную запись или добавьте API Key.

Чтобы установить команду pi-web глобально:

npm install -g @agegr/pi-web@latest
pi-web

Для обновления остановите запущенный процесс с помощью Ctrl+C и повторите ту же команду установки. Для удаления выполните npm uninstall -g @agegr/pi-web.

Настройка

Для порта и имени хоста параметры командной строки имеют приоритет над соответствующими переменными окружения. И --no-open, и PI_WEB_NO_OPEN=1 отключают автоматическое открытие браузера независимо друг от друга.

Параметр или переменная окружения	Назначение	Значение по умолчанию
--port <port>, -p <port> или PORT	Порт сервера	30141
--hostname <host>, -H <host> или PI_WEB_HOSTNAME	Имя хоста для привязки	127.0.0.1
--no-open или PI_WEB_NO_OPEN=1	Не открывать браузер автоматически	Браузер открывается
PI_WEB_ALLOWED_HOSTS	Дополнительные точные имена прокси или пользовательских хостов через запятую	Не задано
PI_WEB_PASSWORD	Включить HTTP Basic Auth; имя пользователя всегда pi	Аутентификация отключена

Пример:

pi-web -p 8080 -H 0.0.0.0 --no-open

Удалённый доступ

Привязка к адресу, отличному от loopback, открывает сетевой доступ к агенту, способному выполнять операции с широкими полномочиями. Даже в доверенной локальной сети используйте длинный случайный пароль:

PI_WEB_PASSWORD='длинный-случайный-пароль' pi-web --hostname 0.0.0.0

Basic Auth не шифрует пароль при передаче. Не публикуйте Pi Web в интернете по обычному HTTP; используйте HTTPS через доверенный обратный прокси или надёжное VPN-подключение. Если обратный прокси передаёт внешнее имя хоста, добавьте это точное имя в PI_WEB_ALLOWED_HOSTS. Этот список разрешённых имён не меняет адрес, к которому привязывается Pi Web.

HTTP-прокси

Для серверных запросов к моделям и API используются стандартные переменные окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY.

В macOS и Linux:

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npx @agegr/pi-web@latest

В Windows PowerShell:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest

Примечания

• Данные агента: по умолчанию Pi Web читает данные pi из ~/.pi/agent, включая файлы сессий в sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl. Чтобы использовать другой каталог агента pi, задайте PI_CODING_AGENT_DIR.
• Доступ к файловой системе: Pi Web должен иметь доступ для чтения к каталогу данных агента и рабочим каталогам, записанным в сессиях. При совместном использовании существующих сессий запускайте Pi Web в той же файловой среде, что и pi.
• Общие настройки: панель Models использует хранилища моделей, настроек и учётных данных pi, поэтому изменения видны в обоих интерфейсах.
• Граница доступа к файлам: файловый браузер ограничен рабочими каталогами, выбранными в Pi Web, и уже известными корнями проектов или сессий; это не универсальный файловый менеджер.
• Git worktree: условия отображения переключателя, создание рабочих деревьев и их удаление описаны в документе Worktrees in Pi Web.

Разработка

npm install
npm run dev

Сервер разработки доступен по адресу http://127.0.0.1:30141. Основные проверки запускаются командами:

npm test
node_modules/.bin/tsc --noEmit
npm run lint

Не запускайте next build или npm run build во время обычной разработки. Эти команды записывают данные в .next/ и могут помешать работе сервера разработки; выполняйте сборку только при подготовке релиза.

Руководства для участников: Internationalization и Release process.

Структура репозитория

app/             UI Next.js и маршруты API
components/      Компоненты интерфейса React
hooks/           Состояние клиента и обработчики взаимодействий
lib/             Логика сессий, агента, моделей, файлов, Git и безопасности
public/          Статические ресурсы и файлы PWA
bin/             Точка входа npm CLI и разбор параметров запуска
docs/            Тематические руководства для пользователей и участников

Описание архитектуры и подробная карта файлов приведены в AGENTS.md.

Лицензия

MIT