SpyBara
Go Premium

plugin-dependencies.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 62 additions and 26 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Sun 13 21:00 Fri 18 23:58 Fri 25 23:58

Batasi versi dependensi plugin

Deklarasikan batasan versi pada dependensi plugin, dan bundel satu set plugin yang dikurasi di balik satu instalasi.

Sebuah plugin dapat bergantung pada plugin lain dengan mencantumkannya di plugin.json atau di entri marketplacenya. Secara default, dependensi melacak versi terbaru yang tersedia, sehingga rilis upstream dapat mengubah dependensi di bawah plugin Anda tanpa peringatan. Batasan versi memungkinkan Anda menahan dependensi pada rentang versi yang telah diuji sampai Anda memilih untuk pindah.

Ketika Anda menginstal plugin yang mendeklarasikan dependensi, Claude Code menyelesaikan dan menginstal dependensi tersebut secara otomatis, kecuali untuk dependensi yang entri marketplacenya memiliki command source atau headersHelper, yang Anda instal sendiri terlebih dahulu. Kemudian, /reload-plugins, pembaruan otomatis marketplace plugin yang bergantung, menjalankan kembali claude plugin install pada plugin yang bergantung, dan claude plugin marketplace add masing-masing menginstal dependensi yang dideklarasikan yang belum diinstal, sesuai dengan aturan yang sama; jika salah satu tetap tidak terselesaikan, lihat Selesaikan kesalahan dependensi.

Panduan ini ditujukan untuk penulis plugin yang mendeklarasikan dependensi di plugin.json dan untuk pengelola marketplace yang menandai rilis. Dependensi di sini adalah plugin lain; untuk paket npm dan Bun yang digunakan plugin itu sendiri, lihat Dependensi paket Node.js. Untuk menginstal plugin yang memiliki dependensi, lihat Temukan dan instal plugin. Untuk skema manifes lengkap, lihat Referensi Plugin.

Mengapa membatasi versi dependensi

Pertimbangkan marketplace internal di mana dua tim menerbitkan plugin. Tim platform memelihara secrets-vault, server MCP yang membungkus backend rahasia. Tim deploy memelihara deploy-kit, yang memanggil secrets-vault untuk mengambil kredensial selama deploy.

deploy-kit diuji terhadap secrets-vault v2.1.0. Tanpa batasan versi, saat tim platform menandai rilis berikutnya yang mengganti nama alat MCP, auto-update memindahkan secrets-vault setiap insinyur ke versi baru dan deploy-kit rusak.

Dengan batasan versi, deploy-kit mendeklarasikan bahwa ia memerlukan secrets-vault dalam rentang ~2.1.0. Insinyur dengan deploy-kit yang diinstal tetap berada di patch 2.1.x tertinggi yang cocok. Tim deploy meningkatkan sesuai jadwal mereka sendiri dengan menerbitkan versi deploy-kit baru dengan batasan yang lebih luas.

Deklarasikan dependensi dengan batasan versi

Cantumkan dependensi dalam array dependencies dari plugin.json plugin Anda.

Manifes berikut mendeklarasikan satu dependensi tanpa versi dan satu dependensi terbatas:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Entri dapat berupa string kosong dengan hanya nama plugin, seperti "audit-logger" dalam contoh di atas, yang bergantung pada versi apa pun yang disediakan marketplace plugin tersebut. Untuk kontrol lebih, gunakan objek dengan bidang-bidang ini:

Bidang Tipe Deskripsi
name string Nama plugin. Diselesaikan dalam marketplace yang sama dengan plugin yang mendeklarasikan. Diperlukan.
version string Rentang semver seperti ~2.1.0, ^2.0, >=1.4, atau =2.1.0. Dependensi diambil pada versi tertinggi yang ditandai yang memenuhi rentang ini.
marketplace string Marketplace berbeda untuk menyelesaikan name di dalamnya. Dependensi lintas-marketplace diblokir kecuali marketplace target tercantum dalam allowCrossMarketplaceDependenciesOn di marketplace.json marketplace root.

Versi pra-rilis seperti 2.0.0-beta.1 dikecualikan kecuali rentang Anda memilih dengan sufiks pra-rilis seperti ^2.0.0-0.

Bundel plugin untuk tim

Selain name yang diperlukan, manifes plugin dapat terdiri dari hanya array dependencies. Menginstalnya akan menarik setiap dependensi, yang menjadikannya cara untuk mengemas set plugin yang dikurasi di balik satu instalasi.

Misalnya, tim platform dapat menerbitkan bundel khusus peran di marketplace internal sehingga insinyur menjalankan satu claude plugin install alih-alih menginstal setiap alat secara terpisah:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Menginstal backend-standard menyelesaikan dan menginstal keempat dependensi.

Untuk menambahkan alat ke set standar nanti, terbitkan versi backend-standard baru dengan dependensi tambahan. Auto-update dimatikan secara default untuk marketplace non-Anthropic, jadi insinyur mengambil versi baru dengan salah satu dari dua cara:

  • Aktifkan auto-update untuk marketplace di /plugin. Auto-update berikutnya memindahkan bundel ke versi baru dan menginstal dependensi apa pun yang ditambahkannya.
  • Jalankan claude plugin update backend-standard, kemudian /reload-plugins untuk menginstal dependensi yang baru ditambahkan.

Untuk meluncurkan bundel di seluruh organisasi, tambahkan plugin bundel ke enabledPlugins dalam pengaturan terkelola.

Bergantung pada plugin dari marketplace lain

Secara default, Claude Code menolak untuk auto-install dependensi yang berada di marketplace berbeda dari plugin yang mendeklarasikannya. Ini mencegah satu marketplace secara diam-diam menarik plugin dari sumber yang belum Anda tinjau.

Untuk mengizinkannya, pengelola marketplace root menambahkan nama marketplace target ke allowCrossMarketplaceDependenciesOn di marketplace.json. Marketplace root adalah yang menghosting plugin yang diinstal pengguna; hanya daftar putihnya yang dikonsultasikan, sehingga kepercayaan tidak berantai melalui marketplace perantara.

marketplace.json berikut memungkinkan deploy-kit bergantung pada plugin dari acme-shared:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

Jika bidang hilang atau tidak menyertakan marketplace target, instalasi gagal dengan kesalahan cross-marketplace yang menamai bidang yang akan diatur. Pengguna masih dapat menginstal dependensi secara manual terlebih dahulu, yang memenuhi batasan tanpa mengubah daftar putih.

Uji coba plugin dan dependensinya secara lokal

Jika Anda mengembangkan plugin dan plugin yang menjadi dependensinya pada saat yang bersamaan, muat keduanya dengan --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

Salinan lokal dari dependensi memenuhi entri dependensi plugin Anda, bahkan ketika entri tersebut menamai marketplace, sehingga Anda tidak perlu menginstal dependensi dari marketplacenya. Claude Code tidak memeriksa batasan versi terhadap salinan lokal, jadi plugin.json lokal tidak perlu memiliki version. Sebelum v2.1.242, entri dependensi yang menamai marketplace tidak pernah cocok dengan salinan lokal, dan Claude Code menonaktifkan plugin Anda saat dimuat.

Jika Anda belum menginstal dependensi dari marketplacenya, plugin Anda berhenti dimuat ketika salinan lokal hilang:

  • Anda menonaktifkan salinan lokal: Claude Code menonaktifkan plugin Anda pada pemuatan plugin berikutnya. Untuk entri dependensi yang menamai marketplace, Claude Code melaporkan Dependency "<name>@inline" is disabled — enable it or remove the dependency; untuk entri nama-bare, Claude Code melaporkan dependensi dengan nama-barenya. <name>@inline adalah cara Claude Code mengidentifikasi setiap plugin --plugin-dir dan --plugin-url.
  • Anda memulai sesi tanpa flag --plugin-dir dependensi: Claude Code melaporkan dependensi sebagai tidak terinstal. Berikan flag lagi, atau instal dependensi dari marketplacenya.

Rilis plugin tag untuk resolusi versi

Claude Code menyelesaikan batasan versi terhadap git tags pada repositori yang menghosting dependensi: repositori plugin itu sendiri untuk github, url, dan git-subdir sumber plugin, atau repositori marketplace untuk plugin yang direferensikan marketplace melalui jalur relatif. Agar Claude Code dapat menemukan versi yang tersedia dari dependensi, rilis plugin upstream harus diberi tag menggunakan konvensi penamaan tertentu.

Beri tag setiap rilis sebagai {plugin-name}--v{version}, di mana {version} cocok dengan field version dalam plugin.json commit tersebut. Dari direktori plugin, jalankan:

claude plugin tag --push

Perintah claude plugin tag menurunkan nama tag dari manifest plugin dan entri marketplace yang melingkupinya. Sebelum membuat tag, perintah ini memvalidasi konten plugin, memeriksa bahwa plugin.json dan entri marketplace setuju tentang versi, memerlukan pohon kerja yang bersih di bawah direktori plugin, dan menolak jika tag sudah ada.

  • --push mendorong tag ke remote origin, jadi repositori memerlukan remote origin yang dikonfigurasi. Lewatkan --remote untuk mendorong ke yang berbeda.
  • Jika push gagal, tag masih dibuat secara lokal dan perintah keluar dengan kesalahan.
  • Dengan --push, jalankan yang berhasil berakhir dengan Created tag secrets-vault--v2.1.0 dan Pushed to origin, di mana baris terakhir menamai remote yang didorong. Tanpa --push, perintah mencetak perintah git push untuk dijalankan sebagai gantinya.
  • --dry-run mencetak apa yang akan diberi tag tanpa membuatnya.

Menjalankan git tag secrets-vault--v2.1.0 secara langsung setara jika Anda menjaga plugin.json dan entri marketplace tetap sinkron sendiri.

Awalan nama plugin memungkinkan satu repositori marketplace menghosting beberapa plugin dengan jalur versi independen. Pemisah --v diuraikan sebagai pencocokan awalan pada nama plugin lengkap, jadi nama plugin yang berisi tanda hubung ditangani dengan benar.

Ketika Anda menginstal plugin yang mendeklarasikan { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code mencantumkan tag pada repositori yang menghosting secrets-vault, memfilter ke yang dimulai dengan secrets-vault--v, dan mengambil versi tertinggi yang memenuhi ~2.1.0. Jika tidak ada tag pada repositori plugin itu sendiri yang memenuhi rentang, instalasi gagal dengan Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, yang menamai dependensi bersama dengan marketplacenya. Untuk plugin jalur relatif tanpa tag yang cocok, Claude Code menginstal salinan marketplace saat ini sebagai gantinya dan memeriksa batasan saat plugin dimuat.

Untuk plugin yang direferensikan marketplace melalui jalur relatif, marketplace yang ditambahkan sebagai jalur folder lokal menyelesaikan tag dengan cara yang sama ketika folder adalah repositori git. Ini memerlukan Claude Code v2.1.196 atau lebih baru. Dalam dua kasus Claude Code menginstal dependensi dari konten folder saat ini sebagai gantinya:

  • Versi sebelumnya tidak membaca tag dari marketplace folder lokal, jadi dependensi terkendala dimuat hanya jika salinan itu memenuhi rentang.
  • Folder lokal yang bukan repositori git tidak memiliki tag, terlepas dari versi.

Semver tag yang diselesaikan dicatat secara terpisah dari version plugin.json, jadi pemeriksaan batasan menggunakan tag yang benar-benar diambil bahkan jika plugin.json pada commit itu memiliki nilai basi. Nama direktori cache untuk instalasi yang diselesaikan tag mencakup akhiran SHA commit 12 karakter, jadi jika pengelola memaksa memindahkan tag ke commit yang berbeda, instalasi berikutnya mendapatkan direktori cache segar alih-alih menggunakan kembali konten basi.

Bagaimana batasan berinteraksi

Ketika beberapa plugin yang diinstal membatasi dependensi yang sama, Claude Code memotong rentang mereka dan menyelesaikan dependensi ke versi tertinggi yang memenuhi semuanya. Tabel di bawah menunjukkan bagaimana kombinasi umum diselesaikan.

Plugin A memerlukan Plugin B memerlukan Hasil
^2.0 >=2.1 Satu instalasi pada tag 2.x tertinggi pada atau di atas 2.1.0. Kedua plugin dimuat.
~2.1 ~3.0 Instalasi plugin B gagal dengan range-conflict. Plugin A dan dependensi tetap seperti sebelumnya.
=2.1.0 tidak ada Dependensi tetap di 2.1.0. Auto-update melewati versi yang lebih baru saat plugin A diinstal.

Auto-update mengambil dependensi terbatas pada tag git tertinggi yang memenuhi rentang setiap plugin yang diinstal, bukan pada versi terbaru marketplace, sehingga dependensi terus menerima pembaruan dalam rentang yang diizinkan. Jika tidak ada tag yang memenuhi semua rentang, auto-update melewati dependensi tersebut dan mencantumkan pelewatan di tab Errors /plugin, menamai plugin yang membatasi.

Ketika Anda mencopot plugin terakhir yang membatasi dependensi, dependensi tidak lagi ditahan dan melanjutkan pelacakan entri marketplacenya pada pembaruan berikutnya.

Aktifkan atau nonaktifkan plugin dengan dependensi

Bagian ini mencakup plugin yang diinstal dari marketplace. Untuk salinan yang Anda muat dengan --plugin-dir, lihat Uji plugin dan dependensinya secara lokal.

Mengaktifkan plugin juga mengaktifkan plugin yang bergantung padanya, dan menonaktifkan plugin diblokir jika plugin yang diaktifkan lain masih membutuhkannya.

Ketika Anda mengaktifkan plugin, Claude Code juga mengaktifkan dependensinya pada cakupan yang sama. Jika dependensi memiliki dependensinya sendiri, Claude Code mengaktifkan yang tersebut juga. Pesan kesuksesan mencantumkan apa lagi yang diaktifkan bersama plugin yang Anda namai. Jika dependensi tidak dapat diaktifkan, perintah menolak dan memberi tahu Anda apa yang memblokir dan cara memperbaikinya:

Kondisi Hasil
Dependensi tidak diinstal Aktifkan gagal dan mencetak perintah claude plugin install untuk setiap dependensi yang hilang.
Dependensi diblokir oleh kebijakan plugin organisasi Anda Aktifkan gagal dan menamai dependensi yang diblokir.
Dependensi diatur ke false pada cakupan dengan prioritas lebih tinggi dari cakupan target Aktifkan gagal. Aktifkan dependensi pada cakupan tersebut, atau lewatkan --scope untuk menulis di sana.
Semua dependensi diinstal dan diizinkan Aktifkan berhasil dan menulis true untuk plugin dan setiap dependensi yang belum diaktifkan pada cakupan target.

Ini berlaku bahkan ketika dependensi menetapkan defaultEnabled: false dalam manifestnya, karena Claude Code menulis true eksplisit untuk itu. Hal yang sama berlaku saat instalasi: dependensi yang ditarik untuk memenuhi plugin aktif diinstal dengan true terlepas dari defaultnya sendiri.

Ketika Anda menonaktifkan plugin, Claude Code menolak jika plugin yang diaktifkan lain masih bergantung padanya. Kesalahan menamai plugin yang bergantung padanya dan memberikan Anda perintah berantai yang menonaktifkannya dalam urutan yang benar, diakhiri dengan yang Anda minta.

Misalnya, jika deploy-kit bergantung pada secrets-vault, menonaktifkan secrets-vault saja gagal dengan output serupa dengan berikut:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

Salin perintah berantai dari kesalahan untuk menonaktifkan set lengkap dalam satu langkah.

Hapus dependensi auto-install yang yatim piatu

Dependensi auto-install tetap di disk setelah plugin yang menginstalnya dicopot, untuk berjaga-jaga jika Anda menginstal ulang plugin dependen atau ingin terus menggunakan dependensi secara langsung. Untuk membersihkannya, jalankan claude plugin prune untuk mencantumkan dependensi auto-install yang tidak lagi memiliki plugin yang diinstal yang memerlukan mereka dan menghapusnya setelah prompt konfirmasi.

claude plugin prune

Jika tidak ada yang memenuhi syarat untuk dihapus, perintah mencetak Nothing to prune dengan alasannya dan keluar. Ini adalah output yang diharapkan pada instalasi baru, bukan kesalahan.

Secara default, prune beroperasi pada cakupan pengguna dan meminta konfirmasi sebelum menghapus apa pun:

  • --scope project atau --scope local menargetkan cakupan berbeda.
  • --dry-run mencantumkan apa yang akan dihapus tanpa mengubah apa pun.
  • -y melewati prompt konfirmasi. Ketika stdin atau stdout bukan terminal, prune mencantumkan yatim piatu dan keluar tanpa menghapusnya kecuali Anda meneruskan -y.

Untuk prune sebagai bagian dari uninstall, teruskan --prune ke claude plugin uninstall. Setelah menghapus plugin bernama, Claude Code memindai dan menghapus dependensi auto-install apa pun yang sekarang yatim piatu. Plugin yang Anda instal sendiri tidak pernah dipangkas, hanya yang diinstal secara otomatis melalui array dependencies plugin lain.

Perilaku konfirmasi yang sama berlaku. Ketika stdin atau stdout bukan terminal, uninstall masih selesai, tetapi langkah prune mencantumkan yatim piatu dan tidak menghapus apa pun kecuali Anda meneruskan -y.

Misalnya, untuk mencopot deploy-kit dan membersihkan dependensi yang ditinggalkannya:

claude plugin uninstall deploy-kit --prune

Selesaikan kesalahan dependensi

Masalah dependensi muncul di claude plugin list dan di antarmuka /plugin, sebagai pesan kesalahan deskriptif daripada kode literal dalam tabel ini. Claude Code menonaktifkan plugin yang terpengaruh sampai Anda menyelesaikan kesalahan. Tabel di bawah mencantumkan kesalahan paling umum dan cara menyelesaikannya.

Kesalahan Arti Cara menyelesaikan
dependency-unsatisfied Dependensi yang dideklarasikan tidak diinstal, atau diinstal tetapi dinonaktifkan. Jalankan perintah claude plugin install yang ditampilkan dalam pesan kesalahan. Jika marketplace dependensi belum dikonfigurasi, tambahkan dengan claude plugin marketplace add dan Claude Code menyelesaikan dependensi secara otomatis. Jika dependensi dinonaktifkan, aktifkan.
range-conflict Persyaratan versi untuk dependensi tidak dapat digabungkan. Pesan kesalahan menamai penyebabnya: tidak ada versi yang memenuhi semua rentang, rentang bukan sintaks semver yang valid, atau rentang gabungan terlalu kompleks untuk dipotongan. Copot atau perbarui salah satu plugin yang bertentangan, perbaiki string version yang tidak valid, sederhanakan rantai || panjang, atau minta penulis upstream untuk memperluas batasannya.
dependency-version-unsatisfied Versi dependensi yang diinstal berada di luar rentang yang dideklarasikan plugin ini. Jalankan claude plugin install <dependency>@<marketplace> untuk menyelesaikan kembali dependensi terhadap semua batasan saat ini.
no-matching-tag Repositori dependensi tidak memiliki tag {name}--v* yang memenuhi rentang. Periksa bahwa upstream telah menandai rilis menggunakan konvensi di atas, atau relakskan rentang Anda.

Untuk memeriksa kesalahan ini secara terprogram, jalankan claude plugin list --json. Plugin dengan masalah menyertakan bidang errors yang mencantumkan kesalahan tersebut. Plugin yang dimuat dengan bersih menghilangkan bidang tersebut.

Lihat juga