Настройка темы Pi Agent

Pi Agent поддерживает настройку цветов интерфейса терминала.

В этой главе рассказывается, как использовать встроенные темы и создавать пользовательские темы.


Обзор тем

Pi Agent использует файлы тем в формате JSON для определения всех цветов в интерфейсе TUI.

Каждой теме необходимо определить51 обязательный токен + 4 необязательных токена (thinkingMax, scrollbarThumb, searchMatchBg, searchMatchText), охватывающих цвета для различных элементов интерфейса, таких как основной интерфейс, фоны сообщений, отрисовка Markdown, подсветка синтаксиса и границы редактора.


Встроенные темы

Pi Agent поставляется с двумя встроенными темами:

Название темыПрименимый сценарийОписание
darkТёмный фон терминала (по умолчанию)Подходит для тёмных терминалов, используемых большинством разработчиков
lightСветлый фон терминалаПодходит для терминалов со светлыми темами

При первом запуске Pi Agent автоматически определяет цвет фона вашего терминала и выбирает dark или light.

В интерактивном режиме введите /settings и переключитесь прямо в параметрах темы:

/settings

Вы также можете указать поле theme в settings.json и изменить значение theme на имя темы:

Пример

{
  "theme": "light"
}

Создание пользовательских тем

Сначала создайте каталог темы и файл:

mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json

Затем определите файл темы. Ниже приведён полный пример пользовательской темы:

Пример

{
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242,
    "orange": "#ffaa00",
    "green": "#0055AA"
  },
  "colors": {
    "accent": "blue",
    "border": "blue",
    "borderAccent": "#00ffff",
    "borderMuted": "gray",
    "success": "green",
    "error": "#ff0000",
    "warning": "#ffff00",
    "muted": "gray",
    "dim": 240,
    "text": "",
    "thinkingText": "gray",
    "selectedBg": "#2d2d30",
    "userMessageBg": "#2d2d30",
    "userMessageText": "",
    "customMessageBg": "#2d2d30",
    "customMessageText": "",
    "customMessageLabel": "blue",
    "toolPendingBg": "#1e1e2e",
    "toolSuccessBg": "#1e2e1e",
    "toolErrorBg": "#2e1e1e",
    "toolTitle": "blue",
    "toolOutput": "",
    "mdHeading": "orange",
    "mdLink": "blue",
    "mdLinkUrl": "gray",
    "mdCode": "#00ffff",
    "mdCodeBlock": "",
    "mdCodeBlockBorder": "gray",
    "mdQuote": "gray",
    "mdQuoteBorder": "gray",
    "mdHr": "gray",
    "mdListBullet": "#00ffff",
    "toolDiffAdded": "green",
    "toolDiffRemoved": "#ff0000",
    "toolDiffContext": "gray",
    "syntaxComment": "gray",
    "syntaxKeyword": "blue",
    "syntaxFunction": "#00aaff",
    "syntaxVariable": "orange",
    "syntaxString": "green",
    "syntaxNumber": "#ff00ff",
    "syntaxType": "#00aaff",
    "syntaxOperator": "blue",
    "syntaxPunctuation": "gray",
    "thinkingOff": "gray",
    "thinkingMinimal": "blue",
    "thinkingLow": "#00aaff",
    "thinkingMedium": "#00ffff",
    "thinkingHigh": "#ff00ff",
    "thinkingXhigh": "#ff0000",
    "thinkingMax": "#ff0088",
    "bashMode": "orange"
  }
}

Затем включите вашу тему в settings.json:

Пример

{
  "theme": "my-theme"
}

Когда вы редактируете используемый в данный момент файл пользовательской темы, Pi Agent автоматически перезагружает тему, позволяя сразу увидеть изменения без каких-либо действий.


Расположения загрузки файлов тем

Pi Agent ищет файлы тем в следующих расположениях.

Темы, размещённые в разных расположениях, имеют разные области видимости и условия загрузки.

РасположениеОбласть действия
Встроенныйdark, light всегда доступны
~/.pi/agent/themes/*.jsonГлобальные темы, доступные всем проектам
.pi/themes/*.jsonТемы проекта, загружаемые только после подтверждения доверия к проекту
Пакеты Piкаталог themes/ в пакете
--theme путьВременно загружаются через командную строку

Форматы значений цвета

Pi Agent поддерживает четыре формата значений цвета:

ФорматПримерОписание
Шестнадцатеричный цвет"#ff0000"6-значный шестнадцатеричный RGB-цвет
256-цветная палитра39Индекс палитры xterm из 256 цветов (0-255)
Ссылка на переменную"blue"Ссылается на переменную, определённую в vars
Цвет терминала по умолчанию""Использует цвет переднего плана/фона терминала по умолчанию

Секция vars используется для определения повторно используемых переменных цвета, на которые ссылаются по имени в colors.

После вынесения основных цветов в переменные изменение цветовой схемы требует правки только в одном месте, что упрощает поддержку темы.


Категории цветовых токенов

Каждый токен в colors соответствует цвету категории элементов интерфейса.

Ниже все токены разделены на шесть категорий по назначению для удобства использования.

Основной интерфейс (11)

Эта группа управляет цветами базовых элементов интерфейса, таких как редактор и строка состояния.

ТокенНазначение
accentОсновной цвет (логотип, выбранные элементы, курсор)
borderОбычная граница
borderAccentГраница выделения
borderMutedМягкая граница для области редактора
успехСтатус успеха
errorСтатус ошибки
warningСтатус предупреждения
mutedВторичный текст
dimТретичный текст (ещё менее заметный)
textЦвет текста по умолчанию (обычно оставляется пустым)
thinkingTextТекст процесса рассуждения ИИ

Фон и содержимое (11 обязательных + 3 необязательных)

Эта группа управляет фоном и текстом выбранных элементов, пузырей сообщений и областей вывода инструментов.

ТокенНазначение
selectedBgФон выбранного элемента (текущая запись в списке)
userMessageBgФон сообщения пользователя
userMessageTextТекст сообщения пользователя
customMessageBgФон развёрнутого сообщения
customMessageTextТекст развёрнутого сообщения
customMessageLabelЦвет тега заголовка для развёрнутых сообщений
toolPendingBgФон выполнения инструмента
toolSuccessBgФон успешного выполнения инструмента
toolErrorBgФон ошибки выполнения инструмента
toolTitleТекст заголовка карточки инструмента
toolOutputТекст вывода инструмента
scrollbarThumbЦвет бегунка полосы прокрутки в полноэкранном режиме (необязательно, если не задан, используется selectedBg)
searchMatchBgФон совпадения при поиске (необязательно, если не задан, используется selectedBg)
searchMatchTextТекст совпадения при поиске (необязательно, если не задан, используется text)

Отрисовка Markdown (10)

Эта группа управляет цветами элементов Markdown в ответах ИИ.

ТокенНазначение
mdHeadingЗаголовок
mdLinkТекст ссылки
mdLinkUrlURL-адрес ссылки
mdCodeВстроенный код
mdCodeBlockСодержимое блока кода
mdCodeBlockBorderГраница блока кода
mdQuoteТекст блочной цитаты
mdQuoteBorderГраница блочной цитаты
mdHrРазделитель
mdListBulletМаркер списка

Подсветка синтаксиса (9)

Эта группа управляет цветами подсветки синтаксиса внутри блоков кода.

ТокенНазначение
syntaxCommentКомментарий
syntaxKeywordКлючевое слово
syntaxFunctionИмя функции
syntaxVariableИмя переменной
syntaxStringString
syntaxNumberNumber
syntaxTypeType
syntaxOperatorOperator
syntaxPunctuationПунктуация

Границы уровня рассуждений (7)

Эта группа управляет цветом индикатора текущего уровня рассуждений на границе редактора.

ТокенСоответствующий уровень
thinkingOffРассуждения отключены
thinkingMinimalМинимальные рассуждения
thinkingLowНизкий уровень рассуждений
thinkingMediumСредний уровень рассуждений
thinkingHighВысокий уровень рассуждений
thinkingXhighСверхвысокий уровень рассуждений
thinkingMaxМаксимальный уровень рассуждений (необязательно)

thinkingMax — необязательный токен. Если он не определён, используется цвет thinkingXhigh.

Цвета Diff и Bash (4)

Эта группа управляет подсветкой diff и цветами приглашения в режиме bash — теми, которые вы чаще всего видите при редактировании кода.

ТокенНазначение
toolDiffAddedдобавленные строки diff (обычно зелёные)
toolDiffRemovedудалённые строки diff (обычно красные)
toolDiffContextстроки контекста diff (оставить приглушёнными)
bashModeЦвет приглашения в режиме bash

Цвета экспорта HTML

Если вы используете /export для экспорта сессии в HTML, вы можете задать цвета для экспортируемой страницы в теме:

Пример

{
  "export": {
    "pageBg": "#18181e",
    "cardBg": "#1e1e24",
    "infoBg": "#3c3728"
  }
}

Если конфигурация экспорта не указана, экспортируемая страница автоматически берёт цвета из userMessageBg.


Советы по созданию темы

Следующие советы помогут вашей пользовательской теме единообразно вести себя в разных терминалах.

  • Тёмные терминалы: Используйте яркие, насыщенные цвета с достаточно высоким контрастом
  • Светлые терминалы: Используйте более глубокие, мягкие цвета; контраст можно соответствующим образом снизить
  • Гармония цветов: В качестве основы используйте проверенные цветовые схемы, такие как Nord, Gruvbox и Tokyo Night
  • Тщательно протестируйтеОбеспечьте правильное отображение для разных типов сообщений, состояний инструментов, содержимого Markdown и переноса длинного текста
Другие расширения