Управление пакетами 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>То же, что и removepi 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 поддерживает три источника пакетов, каждый из которых отличается поведением при установке и местоположением кеша.

Pi 包从 npm、git、本地路径三种来源安装到本地目录并自动发现资源的流程

Пакеты 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-aiAI-инструменты и типы
@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)
Локальный путьРазрешённый абсолютный путь
Другие расширения