Pi Packages

pi peut vous aider à créer des packages pi. Demandez-lui de regrouper vos extensions, compétences, prompt templates ou thèmes.

Les packages Pi regroupent des extensions, des compétences, prompt templates et des thèmes afin que vous puissiez les partager via npm ou git. Un package peut déclarer des ressources en package.json sous la clé pi, ou utiliser des répertoires conventionnels.

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

Sécurité: Les packages Pi s'exécutent avec un accès complet au système. Extensions exécute du code arbitraire et les compétences peuvent demander au modèle d'effectuer n'importe quelle action, y compris l'exécution d'exécutables. Vérifiez le code source avant d'installer des packages tiers.

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

Ces commandes gèrent les packages pi et pi update peuvent mettre à jour l'installation de pi CLI. Pour désinstaller pi lui-même, voir Quickstart.

Par défaut, install et remove écrivent dans les paramètres utilisateur (~/.pi/agent/settings.json). Utilisez plutôt -l pour écrire dans les paramètres du projet (.pi/settings.json). Les paramètres du projet peuvent être partagés avec votre équipe et pi installe automatiquement tous les packages manquants au démarrage une fois le projet approuvé.

Pour essayer un package sans l'installer, utilisez --extension ou -e. Ceci s'installe dans un répertoire temporaire pour l'exécution en cours uniquement:

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

Pi accepte trois types de sources dans les paramètres et pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• Les spécifications versionnées sont épinglées et ignorées par les mises à jour des packages (pi update --extensions, pi update --all).
• Les installations utilisateur passent sous ~/.pi/agent/npm/.
• Les installations du projet passent sous .pi/npm/.
• Définissez npmCommand dans settings.json pour épingler npm la recherche de package et les opérations d'installation sur une commande wrapper spécifique telle que mise ou asdf.

Exemple:

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

• Sans le préfixe git:, seules les URL de protocole sont acceptées (https://, http://, ssh://, git://).
• Avec le préfixe git:, les formats abrégés sont acceptés, notamment github.com/user/repo et git@github.com:user/repo.
• Les URL HTTPS et SSH sont toutes deux prises en charge.
• Les URL SSH utilisent automatiquement vos clés SSH configurées (respecte ~/.ssh/config).
• Pour les exécutions non interactives (par exemple CI), vous pouvez définir GIT_TERMINAL_PROMPT=0 pour désactiver les invites d'identification et définir GIT_SSH_COMMAND (par exemple ssh -o BatchMode=yes -o ConnectTimeout=5) pour échouer rapidement.
• Les références sont des balises épinglées ou des commits. pi update --extensions et pi update --all ne les déplacent pas vers des références plus récentes, mais ils rapprochent un clone existant avec la référence configurée.
• Utilisez pi install git:host/user/repo@new-ref pour mettre à jour les paramètres et déplacer un package existant vers une nouvelle référence épinglée.
• Cloné à ~/.pi/agent/git/<host>/<path> (global) ou .pi/git/<host>/<path> (projet).
• Lorsque la réconciliation modifie la caisse, pi réinitialise et nettoie le clone, puis exécute npm install si package.json existe.

SSH exemples:

# 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

Les chemins locaux pointent vers des fichiers ou des répertoires sur le disque et sont ajoutés aux paramètres sans copie. Les chemins relatifs sont résolus par rapport au fichier de paramètres dans lequel ils apparaissent. Si le chemin est un fichier, il se charge comme une seule extension. S'il s'agit d'un répertoire, pi charge les ressources en utilisant les règles du package.

Ajoutez un manifeste pi à package.json ou utilisez des répertoires conventionnels. Incluez le mot-clé pi-package pour la découvrabilité.

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

Les chemins sont relatifs à la racine du package. Les tableaux prennent en charge les modèles globaux et !exclusions.

Le package gallery affiche les packages étiquetés avec pi-package. Ajoutez les champs video ou image pour afficher un aperçu:

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

• vidéo: MP4 uniquement. Sur le bureau, lecture automatique au survol. Cliquer ouvre un lecteur en plein écran.
• image: PNG, JPEG, GIF ou WebP. Affiché sous forme d’aperçu statique.

Si les deux sont définis, la vidéo est prioritaire.

Si aucun manifeste pi n'est présent, pi découvre automatiquement les ressources de ces répertoires:

• extensions/ charge les fichiers .ts et .js
• skills/ trouve récursivement SKILL.md dossiers et charge .md fichiers de niveau supérieur en tant que compétences
• prompts/ charge .md fichiers
• themes/ charge .json fichiers

Les dépendances d'exécution tierces appartiennent à dependencies dans package.json. Les dépendances qui n'enregistrent pas d'extensions, de compétences, de prompt templates ou de thèmes appartiennent également à dependencies. Lorsque pi installe un package à partir de npm ou de git, il exécute npm install, donc ces dépendances sont installées automatiquement.

Pi regroupe les packages de base pour les extensions et les compétences. Si vous importez l'un d'entre eux, répertoriez-les dans peerDependencies avec une plage "*" et ne les regroupez pas: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Les autres packages pi doivent être regroupés dans votre archive tar. Ajoutez-les à dependencies et bundledDependencies, puis référencez leurs ressources via les chemins node_modules/. Pi charge les packages avec des racines de modules distinctes, afin que les installations distinctes n'entrent pas en collision ou ne partagent pas de modules.

Exemple:

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

Filtrez ce qu'un package charge à l'aide du formulaire objet dans les paramètres:

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

+path et -path sont des chemins exacts par rapport à la racine du package.

• Omettez une clé pour charger tout ce type.
• Utilisez [] pour ne charger aucun de ce type.
• !pattern exclut les correspondances.
• +path force-inclut un chemin exact.
• -path force-exclut un chemin exact.
• Couche de filtres au-dessus du manifeste. Ils limitent ce qui est déjà autorisé.

Utilisez pi config pour activer ou désactiver les extensions, les compétences, prompt templates et les thèmes des packages installés et des répertoires locaux. pi config démarre dans les paramètres globaux (~/.pi/agent/settings.json); appuyez sur Tab pour basculer entre les modes global et local du projet. Utilisez pi config -l pour démarrer les remplacements de projet (.pi/settings.json) avec les ressources globales héritées grisées.

Les packages peuvent apparaître dans les paramètres globaux et du projet. Si le même package apparaît dans les deux, l'entrée de projet l'emporte sauf si l'entrée de projet a autoload: false, auquel cas elle est appliquée comme un delta sur l'entrée globale. L'identité est déterminée par:

• npm: nom du package
• git: URL du référentiel sans référence
• local: chemin absolu résolu