Управление пакетами Pi Agent
Пакеты Pi позволяют объединять расширения, навыки, шаблоны промптов и темы, а также распространять и устанавливать их через npm или git.
Команды управления пакетами
Все операции с пакетами выполняются через команду pi, без необходимости вручную редактировать settings.json.
| Команда | Функция | Пример |
|---|---|---|
| pi install <source> | Установить пакет; -l устанавливает его на уровне проекта | pi install npm:@example/pi-todo-kit |
| pi remove <source> | Удалить пакет | pi remove npm:@example/pi-todo-kit |
| pi uninstall <source> | То же, что и remove | pi uninstall npm:@example/pi-todo-kit |
| pi list | Список установленных пакетов | pi list |
| pi update --all | Обновить Pi Agent и все пакеты | pi update --all |
| pi update --extensions | Обновить только установленные пакеты (не включая сам Pi Agent) | pi update --extensions |
| pi update <source> | Обновить указанный пакет | pi update npm:@example/pi-todo-kit |
Пример использования:
# 安装 npm 包 $ pi install npm:@example/pi-todo-kit@1.0.0 # 安装 git 包 $ pi install git:github.com/example/pi-todo-kit@v1 # 安装本地包 $ pi install ./packages/pi-todo-kit $ pi install ~/projects/pi-share-kit # 安装为项目级(写入 .pi/settings.json) $ pi install -l npm:@example/pi-todo-kit # 临时试用包(不安装到配置中) $ pi -e npm:@example/pi-todo-kit $ pi -e git:github.com/example/pi-todo-kit
Вывод установки примерно следующий (для примера), где количество расширений и навыков зависит от поля pi пакета:
$ pi install npm:@example/pi-todo-kit Resolving @example/pi-todo-kit@1.2.0 Downloading @example/pi-todo-kit (12.4 kB) Running npm install in ~/.pi/agent/npm/@example/pi-todo-kit Installed @example/pi-todo-kit@1.2.0 extensions: 2 skills: 1 prompts: 3 Saved to ~/.pi/agent/settings.json
Имена пакетов и версии выше — иллюстративные значения; замените их на пакет, который вы действительно хотите установить.
Источники пакетов
Pi Agent поддерживает три источника пакетов, каждый из которых отличается поведением при установке и местоположением кеша.
Пакеты npm
npm — рекомендуемый способ распространения пакетов:
pi install npm:@scope/pkg@1.2.3 pi install npm:pkg
Пакеты npm с номером версии фиксируются, и pi update не будет автоматически их обновлять.
Место установки пакетов: глобальные пакеты находятся в~/.pi/agent/npm/, пакеты уровня проекта — в.pi/npm/。
Пакеты Git
Поддерживаются протоколы HTTPS и SSH:
# HTTPS pi install https://github.com/user/repo@v1 # SSH(git@host:path 需要 git: 前缀) pi install git:git@github.com:user/repo@v1 # SSH 协议 pi install ssh://git@github.com/user/repo@v1
Ref Git-пакета фиксируется, и pi update не будет автоматически переходить на новый ref.
Место клонирования: глобальные пакеты находятся в~/.pi/agent/git/, пакеты уровня проекта — в.pi/git/。
Локальные пути
Указывает на локальный путь в файловой системе; файлы не копируются:
pi install /Users/example/.pi/agent/packages/my-kit pi install ./packages/my-kit
Создание пакетов Pi
Добавьте полеpiв package.json:
Пример
"name": "@example/pi-todo-kit",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"],
"prompts": ["./prompts"],
"themes": ["./themes"],
"video": "https://example.com/demo.mp4",
"image": "https://example.com/screenshot.png"
}
}
Если полеpiотсутствует, Pi Agent автоматически обнаружит ресурсы в стандартных каталогах:
| Стандартный каталог | Загруженное содержимое |
|---|---|
| extensions/ | Загружает файлы .ts и .js из неё |
| skills/ | Рекурсивно находит папки, содержащие SKILL.md, а также загружает .md файлы верхнего уровня как отдельные навыки |
| prompts/ | Загружает .md файлы-шаблоны из неё |
| themes/ | Загружает .json файлы тем из неё |
Добавление ключевых словpi-packageможет сделать ваш пакет видимым вPi Agent Package Gallery.
Поля video и image используются для отображения превью в галерее.
Фильтрация пакетов
При установке пакета вы можете точно управлять тем, какие ресурсы загружаются, избегая загрузки всего сразу.
Массив packages ниже записывается в~/.pi/agent/settings.json(применяется глобально) или.pi/settings.json(применяется только к текущему проекту).
Пакеты, установленные с помощью pi install -l, записываются в .pi/settings.json проекта; оба способа в конечном итоге приводят к одной и той же конфигурации.
Элементы массива поддерживают две формы: строковая форма загружает все ресурсы пакета, а форма объекта фильтрует поэлементно в соответствии с типом ресурса.
Пример
"packages": [
"npm:simple-pkg",
{
"source": "npm:@example/pi-todo-kit",
"extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
"skills": ["skills/brave-search"],
"prompts": [],
"themes": ["+themes/legacy.json"]
}
]
}
В официальной документации фильтрация skills использует как нотацию пути внутри пакета, так и нотацию имени skill; на практике обращайтесь к документации установленного пакета.
Правила фильтрации следующие:
| Синтаксис | Значение | Пример |
|---|---|---|
| Не указывать ключ | Загрузить все ресурсы этого типа | Не указывать ключ skills = загрузить все Skills |
| Установить в [] | Не загружать ресурсы этого типа | "prompts": [] |
| !pattern | Исключить соответствующие ресурсы | "!extensions/legacy.ts" |
| +path | Принудительно включить указанный путь | "+themes/legacy.json" |
| -path | Принудительно исключить указанный путь | "-skills/internal" |
Управление зависимостями
Pi Agent выполнитnpm installдля каждого установленного npm/git-пакета, автоматически устанавливая зависимости.
Локальные зависимости, распространяемые вместе с пакетом, могут быть объединены в бандл с помощьюbundledDependencies.
Следующие основные пакеты предоставляются самим Pi Agent и должны быть указаны какpeerDependencies; не включайте их повторно в свой пакет:
| Название пакета | Описание |
|---|---|
| @earendil-works/pi-ai | AI-инструменты и типы |
| @earendil-works/pi-agent-core | Ядро агента |
| @earendil-works/pi-coding-agent | Основной пакет Pi Agent |
| @earendil-works/pi-tui | Компоненты TUI |
| typebox | Определения схемы параметров |
Управление ресурсами с помощью pi config
Используйтеpi config, чтобы интерактивно включать или отключать расширения, навыки, шаблоны и темы установленных пакетов:
# 编辑全局配置 $ pi config # 编辑项目配置 $ pi config -l
Клавиша Tab переключает между глобальным и проектным режимами.
Область действия и дедупликация
Один и тот же пакет может присутствовать как в глобальной, так и в проектной конфигурации.
Если запись проекта существует, она имеет приоритет над глобальной записью.
Исключение — когда запись проекта устанавливаетautoload: false, в этом случае она больше не перезаписывает полностью, а добавляется поверх глобальной записи.
Идентичность пакета определяется следующими способами, и Pi Agent использует это, чтобы определить, указывают ли две конфигурации на один и тот же пакет:
| Source | Идентичность |
|---|---|
| пакет npm | Имя пакета (например, @example/pi-todo-kit) |
| git-пакет | URL репозитория (без ref) |
| Локальный путь | Разрешённый абсолютный путь |