Pi Packages

pi, pi paketleri oluşturmanıza yardımcı olabilir. Uzantılarınızı, becerilerinizi, prompt templates veya temalarınızı bir araya getirmesini isteyin.

Pi paketleri; uzantıları, becerileri, prompt templates ve temaları bir araya getirir; böylece bunları npm veya git aracılığıyla paylaşabilirsiniz. Bir paket, pi anahtarının altındaki package.json'deki kaynakları bildirebilir veya geleneksel dizinleri kullanabilir.

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

Güvenlik: Pi paketler tam sistem erişimiyle çalışır. Extensions isteğe bağlı kod çalıştırır ve beceriler modele çalıştırılabilir dosyaları çalıştırmak da dahil olmak üzere herhangi bir eylemi gerçekleştirmesi talimatını verebilir. Üçüncü taraf paketleri kurmadan önce kaynak kodunu inceleyin.

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

Bu komutlar pi paketlerini yönetir ve pi update pi CLI kurulumunu güncelleyebilir. Pi'nin kendisini kaldırmak için bkz. Quickstart.

Varsayılan olarak install ve remove kullanıcı ayarlarına (~/.pi/agent/settings.json) yazar. Bunun yerine proje ayarlarına (.pi/settings.json) yazmak için -l tuşunu kullanın. Proje ayarları ekibinizle paylaşılabilir ve pi, projeye güvenildikten sonra eksik paketleri başlangıçta otomatik olarak yükler.

Bir paketi yüklemeden denemek için --extension veya -e tuşlarını kullanın. Bu, yalnızca geçerli çalıştırma için geçici bir dizine yüklenir:

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

Pi ayarlarda üç kaynak türünü kabul eder ve pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• Sürümlü özellikler paket güncellemeleri (pi update --extensions, pi update --all) tarafından sabitlenir ve atlanır.
• Kullanıcı yüklemeleri ~/.pi/agent/npm/'nin altına düşüyor.
• Proje yüklemeleri .pi/npm/'nin altına düşüyor.
• npm paket aramasını sabitlemek ve işlemleri mise veya asdf gibi belirli bir sarmalayıcı komutuna yüklemek için settings.json'deki npmCommand'yi ayarlayın.

Örnek:

{
  "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: öneki olmadan yalnızca protokol URL'leri kabul edilir (https://, http://, ssh://, git://).
• git: önekiyle, github.com/user/repo ve git@github.com:user/repo dahil olmak üzere kısayol formatları kabul edilir.
• HTTPS ve SSH URL'lerin her ikisi de desteklenir.
• SSH URL'ler yapılandırılmış SSH anahtarlarınızı otomatik olarak kullanır (~/.ssh/config'ye saygı duyar).
• Etkileşimli olmayan çalıştırmalarda (örneğin CI), kimlik bilgisi istemlerini devre dışı bırakmak için GIT_TERMINAL_PROMPT=0 ayarını yapabilir ve hızlı başarısız olmak için GIT_SSH_COMMAND (örneğin ssh -o BatchMode=yes -o ConnectTimeout=5) ayarını yapabilirsiniz.
• Referanslar sabitlenmiş etiketler veya taahhütlerdir. pi update --extensions ve pi update --all onları daha yeni referanslara taşımaz, ancak mevcut bir klonu yapılandırılmış referansla uzlaştırırlar.
• Ayarları güncellemek ve mevcut bir paketi yeni sabitlenmiş bir referansa taşımak için pi install git:host/user/repo@new-ref tuşunu kullanın.
• ~/.pi/agent/git/<host>/<path> (global) veya .pi/git/<host>/<path> (proje) olarak klonlandı.
• Mutabakat ödemeyi değiştirdiğinde pi klonu sıfırlar ve temizler, ardından package.json mevcutsa npm install'yi çalıştırır.

SSH örnekler:

# 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

Yerel yollar diskteki dosyalara veya dizinlere işaret eder ve kopyalanmadan ayarlara eklenir. Göreli yollar, göründükleri ayarlar dosyasına göre çözümlenir. Yol bir dosyaysa tek bir uzantı olarak yüklenir. Eğer bu bir dizin ise pi, kaynakları paket kurallarını kullanarak yükler.

package.json'ye bir pi bildirimi ekleyin veya geleneksel dizinleri kullanın. Keşfedilebilirlik için pi-package anahtar kelimesini ekleyin.

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

Yollar paket köküne göredir. Diziler glob desenlerini ve !exclusions'yi destekler.

package gallery, pi-package ile etiketlenen paketleri görüntüler. Önizlemeyi göstermek için video veya image alanlarını ekleyin:

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

• video: yalnızca MP4. Masaüstünde fareyle üzerine gelindiğinde otomatik olarak oynatılır. Tıklandığında tam ekran oynatıcı açılır.
• resim: PNG, JPEG, GIF veya WebP. Statik önizleme olarak görüntülenir.

Her ikisi de ayarlandığında video öncelikli olur.

pi bildirimi mevcut değilse pi, şu dizinlerdeki kaynakları otomatik olarak keşfeder:

• extensions/ .ts ve .js dosyalarını yükler
• skills/ yinelemeli olarak SKILL.md klasörleri bulur ve üst düzey .md dosyalarını beceri olarak yükler
• prompts/ .md dosya yükler
• themes/ .json dosya yükler

Üçüncü taraf çalışma zamanı bağımlılıkları package.json'deki dependencies'ye aittir. Uzantıları, becerileri, prompt templates veya temaları kaydetmeyen bağımlılıklar da dependencies'ye aittir. Pi, npm veya git'ten bir paket kurduğunda npm install'yi çalıştırır, böylece bu bağımlılıklar otomatik olarak yüklenir.

Pi uzantılar ve beceriler için temel paketleri bir araya getirir. Bunlardan herhangi birini içe aktarırsanız, bunları "*" aralığıyla peerDependencies olarak listeleyin ve bunları gruplandırmayın: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Diğer pi paketlerinin tarball'ınızda paketlenmesi gerekir. Bunları dependencies ve bundledDependencies'ye ekleyin, ardından node_modules/ yolları aracılığıyla kaynaklarına başvurun. Pi paketleri ayrı modül kökleriyle yükler, böylece ayrı kurulumlar çakışmaz veya modülleri paylaşmaz.

Örnek:

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

Ayarlardaki nesne formunu kullanarak bir paketin yüklediklerini filtreleyin:

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

+path ve -path paket köküne göre tam yollardır.

• Bu türün tamamını yüklemek için bir anahtarı atlayın.
• Bu türden hiçbirini yüklememek için [] tuşunu kullanın.
• !pattern eşleşmeleri hariç tutar.
• +path kuvvet-tam bir yol içerir.
• -path kesin bir yolu zorla hariç tutar.
• Bildirimin üst kısmındaki filtreler katmanı. Zaten izin verileni daraltıyorlar.

Yüklü paketlerdeki ve yerel dizinlerdeki uzantıları, becerileri, prompt templates ve temaları etkinleştirmek veya devre dışı bırakmak için pi config tuşunu kullanın. pi config genel ayarlarda başlar (~/.pi/agent/settings.json); küresel ve proje yerel modları arasında geçiş yapmak için Sekme tuşuna basın. Devralınan global kaynaklar solukken proje geçersiz kılmalarını (.pi/settings.json) başlatmak için pi config -l tuşunu kullanın.

Paketler hem genel hem de proje ayarlarında görünebilir. Her ikisinde de aynı paket görünüyorsa, proje girişi autoload: false olmadığı sürece proje girişi kazanır; bu durumda global giriş üzerinde delta olarak uygulanır. Kimlik şu şekilde belirlenir:

• npm: paket adı
• git: referanssız depo URL'si
• yerel: çözümlenmiş mutlak yol