Pi Packages

pi может помочь вам создавать пакеты pi. Попросите его объединить ваши расширения, навыки, prompt templates или темы.

В пакеты Pi входят расширения, навыки, prompt templates и темы, поэтому вы можете поделиться ими через npm или git. Пакет может объявлять ресурсы в package.json по ключу pi или использовать обычные каталоги.

• Install and Manage
• Package Sources
• Creating a Pi Package
• Package Structure
• Dependencies
• Package Filtering
• Enable and Disable Resources
• Scope and Deduplication

Безопасность: Pi пакеты запускаются с полным доступом к системе. Extensions выполнять произвольный код, а навыки могут поручить модели выполнить любое действие, включая запуск исполняемых файлов. Просмотрите исходный код перед установкой сторонних пакетов.

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw URLs work too
pi install /absolute/path/to/package
pi install ./relative/path/to/package

pi remove npm:@foo/bar
pi list                     # show installed packages from settings
pi update                   # update pi only
pi update --all             # update pi, update packages, and reconcile pinned git refs
pi update --extensions      # update packages and reconcile pinned git refs only
pi update --models          # refresh model catalogs only
pi update --self            # update pi only
pi update --self --force    # reinstall pi even if current
pi update npm:@foo/bar      # update one package
pi update --extension npm:@foo/bar

Эти команды управляют пакетами pi, а pi update могут обновлять установку pi CLI. Чтобы удалить сам pi, см. Quickstart.

По умолчанию install и remove записывают в настройки пользователя (~/.pi/agent/settings.json). Вместо этого используйте -l для записи в настройки проекта (.pi/settings.json). Настройки проекта можно передать вашей команде, и pi автоматически установит все недостающие пакеты при запуске после того, как проект станет доверенным.

Чтобы попробовать пакет, не устанавливая его, используйте --extension или -e. Это устанавливается во временный каталог только для текущего запуска:

pi -e npm:@foo/bar
pi -e git:github.com/user/repo

Pi принимает три типа источника в настройках и pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• Версионные спецификации закрепляются и пропускаются обновлениями пакетов (pi update --extensions, pi update --all).
• Пользовательские установки имеют номер ~/.pi/agent/npm/.
• Установки проекта попадают под .pi/npm/.
• Установите npmCommand в settings.json, чтобы привязать операции поиска и установки пакета npm к определенной команде оболочки, например mise или asdf.

Пример:

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• Без префикса git: принимаются только URL-адреса протоколов (https://, http://, ssh://, git://).
• С префиксом git: принимаются сокращенные форматы, включая github.com/user/repo и git@github.com:user/repo.
• Поддерживаются URL-адреса HTTPS и SSH.
• URL-адреса SSH автоматически используют настроенные вами ключи SSH (с учетом ~/.ssh/config).
• Для неинтерактивных запусков (например, CI) вы можете установить GIT_TERMINAL_PROMPT=0, чтобы отключить запросы учетных данных, и установить GIT_SSH_COMMAND (например, ssh -o BatchMode=yes -o ConnectTimeout=5), чтобы быстро завершить работу.
• Ссылки — это закрепленные теги или коммиты. pi update --extensions и pi update --all не перемещают их на более новые ссылки, но они согласовывают существующий клон с настроенной ссылкой.
• Используйте pi install git:host/user/repo@new-ref, чтобы обновить настройки и переместить существующий пакет в новую закрепленную ссылку.
• Клонируется в ~/.pi/agent/git/<host>/<path> (глобальный) или .pi/git/<host>/<path> (проект).
• Когда сверка изменяет оформление заказа, pi сбрасывает и очищает клон, а затем запускает npm install, если package.json существует.

SSH примеры:

# git@host:path shorthand (requires git: prefix)
pi install git:git@github.com:user/repo

# ssh:// protocol format
pi install ssh://git@github.com/user/repo

# With version ref
pi install git:git@github.com:user/repo@v1.0.0

/absolute/path/to/package
./relative/path/to/package

Локальные пути указывают на файлы или каталоги на диске и добавляются в настройки без копирования. Относительные пути разрешаются по файлу настроек, в котором они указаны. Если путь представляет собой файл, он загружается как одно расширение. Если это каталог, pi загружает ресурсы, используя правила пакета.

Добавьте манифест pi в package.json или используйте обычные каталоги. Включите ключевое слово pi-package для возможности обнаружения.

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

Пути указаны относительно корня пакета. Массивы поддерживают шаблоны glob и !exclusions.

package gallery отображает пакеты, отмеченные pi-package. Добавьте поля video или image, чтобы отобразить предварительный просмотр:

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

• видео: только MP4. На рабочем столе автоматически воспроизводится при наведении. При нажатии открывается полноэкранный проигрыватель.
• изображение: PNG, JPEG, GIF или WebP. Отображается как статический предварительный просмотр.

Если установлены оба параметра, видео имеет приоритет.

Если манифест pi отсутствует, pi автоматически обнаруживает ресурсы из этих каталогов:

• extensions/ загружает файлы .ts и .js
• skills/ рекурсивно находит папки SKILL.md и загружает файлы верхнего уровня .md как навыки
• prompts/ загружает .md файлы
• themes/ загружает .json файлы

Сторонние зависимости времени выполнения относятся к dependencies в package.json. Зависимости, которые не регистрируют расширения, навыки, prompt templates или темы, также относятся к dependencies. Когда pi устанавливает пакет из npm или git, он запускает npm install, поэтому эти зависимости устанавливаются автоматически.

Pi объединяет основные пакеты для расширений и навыков. Если вы импортируете какие-либо из них, перечислите их в peerDependencies с диапазоном "*" и не объединяйте их: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Другие пакеты pi должны быть включены в ваш архив. Добавьте их в dependencies и bundledDependencies, затем ссылайтесь на их ресурсы через пути node_modules/. Pi загружает пакеты с отдельными корнями модулей, поэтому отдельные установки не конфликтуют и не используют общие модули.

Пример:

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "pi": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

Отфильтруйте то, что загружается пакетом, используя форму объекта в настройках:

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

+path и -path — точные пути относительно корня пакета.

• Опустите ключ, чтобы загрузить все элементы этого типа.
• Используйте [], чтобы не загружать ничего из этого типа.
• !pattern исключает совпадения.
• +path принудительное — включает точный путь.
• -path принудительно — исключает точный путь.
• Слой фильтров поверх манифеста. Они сужают то, что уже разрешено.

Используйте pi config, чтобы включить или отключить расширения, навыки, prompt templates и темы из установленных пакетов и локальных каталогов. pi config запускается в глобальных настройках (~/.pi/agent/settings.json); нажмите Tab, чтобы переключиться между глобальным и локальным режимами проекта. Используйте pi config -l, чтобы начать переопределения проекта (.pi/settings.json), когда наследуемые глобальные ресурсы затемнены.

Пакеты могут появляться как в глобальных настройках, так и в настройках проекта. Если один и тот же пакет появляется в обоих, запись проекта выигрывает, если только запись проекта не имеет autoload: false, и в этом случае она применяется как дельта по отношению к глобальной записи. Личность определяется:

• npm: имя пакета.
• git: URL-адрес репозитория без ссылки
• локальный: разрешен абсолютный путь