Pi Packages

pi dapat membantu Anda membuat paket pi. Mintalah untuk menggabungkan ekstensi, keterampilan, prompt templates, atau tema Anda.

Pi mengemas ekstensi bundel, keterampilan, prompt templates, dan tema sehingga Anda dapat membagikannya melalui npm atau git. Sebuah paket dapat mendeklarasikan sumber daya di package.json di bawah kunci pi, atau menggunakan direktori konvensional.

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

Keamanan: Pi paket dijalankan dengan akses sistem penuh. Extensions mengeksekusi kode arbitrer, dan keterampilan dapat menginstruksikan model untuk melakukan tindakan apa pun termasuk menjalankan executable. Tinjau kode sumber sebelum menginstal paket pihak ketiga.

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

Perintah ini mengelola paket pi dan pi update dapat memperbarui instalasi pi CLI. Untuk menghapus instalasi pi itu sendiri, lihat Quickstart.

Secara default, install dan remove menulis ke pengaturan pengguna (~/.pi/agent/settings.json). Gunakan -l untuk menulis ke pengaturan proyek (.pi/settings.json). Pengaturan proyek dapat dibagikan dengan tim Anda, dan pi menginstal paket apa pun yang hilang secara otomatis saat startup setelah proyek dipercaya.

Untuk mencoba suatu paket tanpa menginstalnya, gunakan --extension atau -e. Ini menginstal ke direktori sementara untuk proses saat ini saja:

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

Pi menerima tiga jenis sumber dalam pengaturan dan pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• Spesifikasi berversi disematkan dan dilewati oleh pembaruan paket (pi update --extensions, pi update --all).
• Penginstalan pengguna berada di bawah ~/.pi/agent/npm/.
• Penginstalan proyek berada di bawah .pi/npm/.
• Atur npmCommand di settings.json untuk menyematkan npm pencarian paket dan operasi instalasi ke perintah pembungkus tertentu seperti mise atau asdf.

Contoh:

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

• Tanpa awalan git:, hanya URL protokol yang diterima (https://, http://, ssh://, git://).
• Dengan awalan git:, format steno diterima, termasuk github.com/user/repo dan git@github.com:user/repo.
• URL HTTPS dan SSH keduanya didukung.
• SSH URL menggunakan kunci SSH yang dikonfigurasi secara otomatis (menghormati ~/.ssh/config).
• Untuk proses non-interaktif (misalnya CI), Anda dapat mengatur GIT_TERMINAL_PROMPT=0 untuk menonaktifkan perintah kredensial dan mengatur GIT_SSH_COMMAND (misalnya ssh -o BatchMode=yes -o ConnectTimeout=5) agar gagal dengan cepat.
• Referensi adalah tag atau komitmen yang disematkan. pi update --extensions dan pi update --all tidak memindahkannya ke referensi yang lebih baru, tetapi mereka merekonsiliasi klon yang ada ke referensi yang dikonfigurasi.
• Gunakan pi install git:host/user/repo@new-ref untuk memperbarui pengaturan dan memindahkan paket yang ada ke referensi baru yang dipasangi pin.
• Diklon ke ~/.pi/agent/git/<host>/<path> (global) atau .pi/git/<host>/<path> (proyek).
• Ketika rekonsiliasi mengubah checkout, pi mengatur ulang dan membersihkan klon, lalu menjalankan npm install jika package.json ada.

SSH contoh:

# 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

Jalur lokal menunjuk ke file atau direktori pada disk dan ditambahkan ke pengaturan tanpa menyalin. Jalur relatif diselesaikan berdasarkan file pengaturan tempat jalur tersebut muncul. Jika jalur tersebut berupa file, maka jalur tersebut dimuat sebagai ekstensi tunggal. Jika itu adalah sebuah direktori, pi memuat sumber daya menggunakan aturan paket.

Tambahkan manifes pi ke package.json atau gunakan direktori konvensional. Sertakan kata kunci pi-package agar dapat ditemukan.

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

Jalur relatif terhadap root paket. Array mendukung pola glob dan !exclusions.

package gallery menampilkan paket yang diberi tag pi-package. Tambahkan kolom video atau image untuk menampilkan pratinjau:

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

• video: hanya MP4. Di desktop, putar otomatis saat mengarahkan kursor. Mengklik akan membuka pemutar layar penuh.
• gambar: PNG, JPEG, GIF, atau WebP. Ditampilkan sebagai pratinjau statis.

Jika keduanya disetel, video akan diutamakan.

Jika tidak ada manifes pi, pi otomatis menemukan sumber daya dari direktori berikut:

• extensions/ memuat file .ts dan .js
• skills/ secara rekursif menemukan SKILL.md folder dan memuat file .md tingkat atas sebagai keterampilan
• prompts/ memuat .md file
• themes/ memuat .json file

Dependensi runtime pihak ketiga termasuk dalam dependencies di package.json. Dependensi yang tidak mendaftarkan ekstensi, keterampilan, prompt templates, atau tema juga termasuk dalam dependencies. Saat pi menginstal paket dari npm atau git, ia menjalankan npm install, sehingga dependensi tersebut diinstal secara otomatis.

Pi menggabungkan paket inti untuk ekstensi dan keterampilan. Jika Anda mengimpor salah satu dari ini, cantumkan dalam peerDependencies dengan rentang "*" dan jangan gabungkan: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Paket pi lainnya harus dibundel dalam tarball Anda. Tambahkan sumber daya tersebut ke dependencies dan bundledDependencies, lalu rujuk sumber dayanya melalui jalur node_modules/. Pi memuat paket dengan akar modul terpisah, sehingga instalasi terpisah tidak bertabrakan atau berbagi modul.

Contoh:

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

Filter apa yang dimuat paket menggunakan bentuk objek di pengaturan:

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

+path dan -path adalah jalur persis yang berhubungan dengan root paket.

• Hilangkan kunci untuk memuat semua jenis itu.
• Gunakan [] untuk tidak memuat jenis tersebut.
• !pattern tidak termasuk kecocokan.
• +path kekuatan-termasuk jalur yang tepat.
• -path paksa-tidak termasuk jalur yang tepat.
• Filter lapisan di atas manifes. Mereka mempersempit apa yang sudah diperbolehkan.

Gunakan pi config untuk mengaktifkan atau menonaktifkan ekstensi, keterampilan, prompt templates, dan tema dari paket yang diinstal dan direktori lokal. pi config dimulai dalam pengaturan global (~/.pi/agent/settings.json); tekan Tab untuk beralih antara mode global dan proyek-lokal. Gunakan pi config -l untuk memulai penggantian proyek (.pi/settings.json) dengan sumber daya global yang diwarisi diredupkan.

Paket dapat muncul di pengaturan global dan proyek. Jika paket yang sama muncul di keduanya, entri proyek menang kecuali entri proyek memiliki autoload: false, dalam hal ini diterapkan sebagai delta di atas entri global. Identitas ditentukan oleh:

• npm: nama paket
• git: URL repositori tanpa referensi
• lokal: jalur absolut terselesaikan