Gestion des paquets de Pi Agent

Les packages Pi vous permettent de regrouper des extensions, des compétences, des modèles de prompt et des thèmes, et de les distribuer et de les installer via npm ou git.


Commandes de gestion des packages

Toutes les opérations sur les packages s'effectuent via la commande pi, sans avoir besoin de modifier manuellement settings.json.

CommandeFonctionExemple
pi install <source>Installer un package ; -l l'installe au niveau du projetpi install npm:@example/pi-todo-kit
pi remove <source>Supprimer un packagepi remove npm:@example/pi-todo-kit
pi uninstall <source>Identique à removepi uninstall npm:@example/pi-todo-kit
pi listLister les packages installéspi list
pi update --allMettre à jour Pi Agent et tous les paquetspi update --all
pi update --extensionsMettre à jour uniquement les paquets installés (sans inclure Pi Agent lui-même)pi update --extensions
pi update <source>Mettre à jour un paquet spécifiépi update npm:@example/pi-todo-kit

Exemple d'utilisation :

# 安装 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

La sortie d'installation est approximativement la suivante (à titre d'illustration), où le nombre d'extensions et de compétences dépend du champ pi du paquet :

$ 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

Les noms et versions des paquets ci-dessus sont des valeurs indicatives ; remplacez-les par le paquet que vous souhaitez réellement installer.


Sources des paquets

Pi Agent prend en charge trois sources de paquets, chacune avec un comportement d'installation et des emplacements de cache différents.

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

Paquets npm

npm est la méthode de distribution de paquets recommandée :

pi install npm:@scope/pkg@1.2.3
pi install npm:pkg

Les paquets npm avec un numéro de version sont verrouillés, et pi update ne les mettra pas à jour automatiquement.

Emplacement d'installation des paquets : les paquets globaux sont dans~/.pi/agent/npm/, les paquets au niveau du projet sont dans.pi/npm/。

Paquets Git

Prend en charge les protocoles HTTPS et 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

La référence d'un paquet Git est verrouillée, et pi update ne passera pas automatiquement à une nouvelle référence.

Emplacement de clonage : les paquets globaux sont dans~/.pi/agent/git/, les paquets au niveau du projet sont dans.pi/git/。

Chemins locaux

Pointe vers un chemin de système de fichiers local ; les fichiers ne sont pas copiés :

pi install /Users/example/.pi/agent/packages/my-kit
pi install ./packages/my-kit

Création de paquets Pi

Ajoutez lepichamp à package.json :

Exemple

{
  "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"
  }
}

S'il n'y a pas de champpi, Pi Agent découvrira automatiquement les ressources à partir des répertoires conventionnels :

Répertoire conventionnelContenu chargé
extensions/Chargez les fichiers .ts et .js qu'il contient
skills/Recherchez récursivement les dossiers contenant SKILL.md, et chargez également les fichiers .md de premier niveau comme Skills autonomes
prompts/Chargez les fichiers modèles .md qu'il contient
themes/Chargez les fichiers de thème .json qu'il contient

Addingpi-packagecomme mots-clés peut faire apparaître votre paquet dans laPi Agent Package Gallery.

Les champs vidéo et image sont utilisés pour afficher des aperçus dans la galerie.


Filtrage des paquets

Lors de l'installation d'un paquet, vous pouvez contrôler précisément quelles ressources sont chargées, en évitant de tout charger d'un coup.

Le tableau packages ci-dessous est écrit dans~/.pi/agent/settings.json(s'applique globalement) ou.pi/settings.json(s'applique uniquement au projet en cours).

Les packages installés avec pi install -l sont écrits dans le .pi/settings.json du projet ; les deux méthodes aboutissent finalement à la même configuration.

Les entrées du tableau prennent en charge deux formes : la forme chaîne charge toutes les ressources du package, tandis que la forme objet filtre élément par élément selon le type de ressource.

Exemple

{
  "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"]
    }
  ]
}

Dans la documentation officielle, le filtrage des skills utilise à la fois la notation de chemin interne au package et la notation du nom de skill ; en pratique, référez-vous à la documentation du package installé.

Les règles de filtrage sont les suivantes :

SyntaxeSignificationExemple
Omettre une cléCharger toutes les ressources de ce typeNe pas écrire la clé skills = charger toutes les compétences
Définir sur []Ne charger aucune ressource de ce type"prompts": []
!patternExclure les ressources correspondantes"!extensions/legacy.ts"
+pathForcer l'inclusion du chemin spécifié"+themes/legacy.json"
-pathForcer l'exclusion du chemin spécifié"-skills/internal"

Gestion des dépendances

Pi Agent exécuteranpm installpour chaque paquet npm/git installé, en installant automatiquement les dépendances.

Les dépendances locales distribuées avec le paquet peuvent être empaquetées viabundledDependencies.

Les paquets principaux suivants sont fournis par Pi Agent lui-même et doivent être listés commepeerDependencies; ne les empaquetez pas à nouveau dans votre paquet :

Nom du paquetDescription
@earendil-works/pi-aiOutils et types d'IA
@earendil-works/pi-agent-coreCœur de l'agent
@earendil-works/pi-coding-agentPaquet principal de Pi Agent
@earendil-works/pi-tuiComposants TUI
typeboxDéfinitions du schéma de paramètres

Gestion des ressources avec pi config

Utilisezpi configpour activer ou désactiver de manière interactive les extensions, les Skills, les modèles et les thèmes des paquets installés :

# 编辑全局配置
$ pi config

# 编辑项目配置
$ pi config -l

La touche Tab bascule entre les modes global et projet.


Portée et déduplication

Le même paquet peut apparaître à la fois dans la configuration globale et dans la configuration de projet.

Si une entrée de projet existe, elle est prioritaire sur l'entrée globale.

L'exception est le cas où une entrée de projet définitautoload: false, auquel cas elle n'écrase plus entièrement, mais est ajoutée de manière incrémentielle par-dessus l'entrée globale.

L'identité d'un paquet est déterminée de la manière suivante, et Pi Agent utilise cela pour déterminer si deux configurations pointent vers le même paquet :

SourceIdentité
paquet npmNom du paquet (par exemple, @example/pi-todo-kit)
Paquet gitURL du dépôt (sans ref)
Chemin localChemin absolu résolu
Autres extensions