Pi Packages

pi kann Ihnen beim Erstellen von Pi-Paketen helfen. Bitten Sie es, Ihre Erweiterungen, Fähigkeiten, prompt templates oder Themen zu bündeln.

Pi-Pakete bündeln Erweiterungen, Fähigkeiten, prompt templates und Themen, sodass Sie sie über npm oder Git teilen können. Ein Paket kann Ressourcen in package.json unter dem Schlüssel pi deklarieren oder herkömmliche Verzeichnisse verwenden.

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

Sicherheit: Pi Pakete werden mit vollem Systemzugriff ausgeführt. Extensions Führen Sie beliebigen Code aus, und Fähigkeiten können das Modell anweisen, jede Aktion auszuführen, einschließlich der Ausführung ausführbarer Dateien. Überprüfen Sie den Quellcode, bevor Sie Pakete von Drittanbietern installieren.

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

Diese Befehle verwalten Pi-Pakete und pi update kann die Pi CLI-Installation aktualisieren. Informationen zur Deinstallation von Pi selbst finden Sie unter Quickstart.

Standardmäßig schreiben install und remove in die Benutzereinstellungen (~/.pi/agent/settings.json). Verwenden Sie stattdessen -l, um in die Projekteinstellungen (.pi/settings.json) zu schreiben. Projekteinstellungen können mit Ihrem Team geteilt werden und pi installiert alle fehlenden Pakete automatisch beim Start, nachdem das Projekt vertrauenswürdig ist.

Um ein Paket auszuprobieren, ohne es zu installieren, verwenden Sie --extension oder -e. Dadurch wird nur für die aktuelle Ausführung ein temporäres Verzeichnis installiert:

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

Pi akzeptiert drei Quellentypen in den Einstellungen und pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• Versionierte Spezifikationen werden von Paketaktualisierungen angeheftet und übersprungen (pi update --extensions, pi update --all).
• Benutzerinstallationen gehen unter ~/.pi/agent/npm/.
• Projektinstallationen gehen unter .pi/npm/.
• Setzen Sie npmCommand in settings.json, um npm Paketsuch- und Installationsvorgänge an einen bestimmten Wrapper-Befehl wie mise oder asdf anzuheften.

Beispiel:

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

• Ohne das Präfix git: werden nur Protokoll-URLs akzeptiert (https://, http://, ssh://, git://).
• Mit dem Präfix git: werden Kurzformate akzeptiert, einschließlich github.com/user/repo und git@github.com:user/repo.
• HTTPS- und SSH-URLs werden beide unterstützt.
• SSH URLs verwenden automatisch Ihre konfigurierten SSH Schlüssel (respektiert ~/.ssh/config).
• Für nicht interaktive Ausführungen (z. B. CI) können Sie GIT_TERMINAL_PROMPT=0 festlegen, um Anmeldeaufforderungen zu deaktivieren, und GIT_SSH_COMMAND (z. B. ssh -o BatchMode=yes -o ConnectTimeout=5) festlegen, um schnell fehlzuschlagen.
• Refs sind angeheftete Tags oder Commits. pi update --extensions und pi update --all verschieben sie nicht auf neuere Referenzen, aber sie gleichen einen vorhandenen Klon mit der konfigurierten Referenz ab.
• Verwenden Sie pi install git:host/user/repo@new-ref, um Einstellungen zu aktualisieren und ein vorhandenes Paket in eine neue angeheftete Referenz zu verschieben.
• Geklont auf ~/.pi/agent/git/<host>/<path> (global) oder .pi/git/<host>/<path> (Projekt).
• Wenn der Abgleich den Checkout ändert, setzt pi den Klon zurück und bereinigt ihn und führt dann npm install aus, wenn package.json vorhanden ist.

SSH Beispiele:

# 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

Lokale Pfade verweisen auf Dateien oder Verzeichnisse auf der Festplatte und werden ohne Kopieren zu den Einstellungen hinzugefügt. Relative Pfade werden anhand der Einstellungsdatei aufgelöst, in der sie erscheinen. Wenn es sich bei dem Pfad um eine Datei handelt, wird sie als einzelne Erweiterung geladen. Wenn es sich um ein Verzeichnis handelt, lädt pi Ressourcen mithilfe von Paketregeln.

Fügen Sie ein pi-Manifest zu package.json hinzu oder verwenden Sie herkömmliche Verzeichnisse. Fügen Sie zur besseren Auffindbarkeit das Schlüsselwort pi-package ein.

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

Pfade sind relativ zum Paketstamm. Arrays unterstützen Glob-Muster und !exclusions.

Die package gallery zeigt Pakete an, die mit pi-package markiert sind. Fügen Sie video oder image Felder hinzu, um eine Vorschau anzuzeigen:

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

• Video: Nur MP4. Auf dem Desktop erfolgt die automatische Wiedergabe beim Schweben. Durch Klicken wird ein Vollbild-Player geöffnet.
• Bild: PNG, JPEG, GIF oder WebP. Wird als statische Vorschau angezeigt.

Wenn beides eingestellt ist, hat Video Vorrang.

Wenn kein pi-Manifest vorhanden ist, erkennt pi automatisch Ressourcen aus diesen Verzeichnissen:

• extensions/ lädt .ts und .js Dateien
• skills/ findet rekursiv SKILL.md Ordner und lädt .md Dateien der obersten Ebene als Fertigkeiten
• prompts/ lädt .md Dateien
• themes/ lädt .json Dateien

Laufzeitabhängigkeiten von Drittanbietern gehören in dependencies in package.json. Abhängigkeiten, die keine Erweiterungen, Fähigkeiten, prompt templates oder Themen registrieren, gehören ebenfalls zu dependencies. Wenn pi ein Paket von npm oder Git installiert, führt es npm install aus, sodass diese Abhängigkeiten automatisch installiert werden.

Pi bündelt Kernpakete für Erweiterungen und Fertigkeiten. Wenn Sie eines davon importieren, listen Sie es in peerDependencies mit einem "*"-Bereich auf und bündeln Sie es nicht: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Andere Pi-Pakete müssen in Ihrem Tarball gebündelt sein. Fügen Sie sie zu dependencies und bundledDependencies hinzu und verweisen Sie dann über node_modules/-Pfade auf ihre Ressourcen. Pi lädt Pakete mit separaten Modulstämmen, sodass separate Installationen nicht kollidieren oder Module gemeinsam nutzen.

Beispiel:

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

Filtern Sie mithilfe des Objektformulars in den Einstellungen, was ein Paket lädt:

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

+path und -path sind genaue Pfade relativ zum Paketstamm.

• Lassen Sie einen Schlüssel weg, um alles dieses Typs zu laden.
• Verwenden Sie [], um nichts von diesem Typ zu laden.
• !pattern schließt Übereinstimmungen aus.
• +path Force – beinhaltet einen genauen Pfad.
• -path erzwingt den Ausschluss eines genauen Pfads.
• Filterebene über dem Manifest. Sie schränken ein, was bereits erlaubt ist.

Verwenden Sie pi config, um Erweiterungen, Fähigkeiten, prompt templates und Themes aus installierten Paketen und lokalen Verzeichnissen zu aktivieren oder zu deaktivieren. pi config startet in den globalen Einstellungen (~/.pi/agent/settings.json); Drücken Sie die Tabulatortaste, um zwischen dem globalen und dem projektlokalen Modus zu wechseln. Verwenden Sie pi config -l, um in Projektüberschreibungen (.pi/settings.json) mit abgeblendeten geerbten globalen Ressourcen zu beginnen.

Pakete können sowohl in globalen als auch in Projekteinstellungen angezeigt werden. Wenn in beiden das gleiche Paket vorkommt, gewinnt der Projekteintrag, es sei denn, der Projekteintrag hat autoload: false. In diesem Fall wird es als Delta über den globalen Eintrag angewendet. Die Identität wird bestimmt durch:

• npm: Paketname
• git: Repository-URL ohne Referenz
• local: aufgelöster absoluter Pfad