قید زدنِ نسخه‌های وابستگیِ پلاگین

یک پلاگین می‌تواند با فهرست‌کردنِ پلاگین‌های دیگر در plugin.json یا در ورودیِ مارکت‌پلیسش به آن‌ها وابسته باشد. به‌صورتِ پیش‌فرض، یک وابستگی آخرین نسخه‌ی موجود را دنبال می‌کند، پس یک انتشارِ upstream می‌تواند بدونِ هشدار وابستگیِ زیرِ پلاگینت را تغییر دهد. قیدهای نسخه (version constraints) می‌گذارند یک وابستگی را روی یک بازه‌ی نسخه‌ی تست‌شده نگه داری تا وقتی خودت تصمیم بگیری جابه‌جا شوی.

وقتی پلاگینی نصب می‌کنی که وابستگی‌ها را اعلام می‌کند، Claude Code آن‌ها را خودکار resolve و نصب می‌کند و در انتهای خروجیِ نصب فهرست می‌کند که کدام وابستگی‌ها اضافه شدند. اگر بعداً وابستگی‌ای گم شود، /reload-plugins و به‌روزرسانیِ خودکارِ پس‌زمینه‌ی پلاگین آن را دوباره نصب می‌کنند، به شرطی که مارکت‌پلیسش از قبل در مارکت‌پلیس‌های پیکربندی‌شده‌ات باشد. اجرای دوباره‌ی claude plugin install روی پلاگینِ وابسته، یا افزودنِ یک مارکت‌پلیس با claude plugin marketplace add، هم هر وابستگیِ گمشده‌ی باقی‌مانده را resolve می‌کند. وابستگی‌هایی از مارکت‌پلیسی که اضافه‌اش نکرده‌ای، resolve‌نشده باقی می‌مانند.

این راهنما برای نویسندگانِ پلاگین است که وابستگی‌ها را در plugin.json اعلام می‌کنند و برای نگه‌دارندگانِ مارکت‌پلیس که انتشارها را تگ می‌زنند. برای نصبِ پلاگین‌هایی که وابستگی دارند، کشف و نصبِ پلاگین‌ها را ببین. برای اسکیمای کاملِ مانیفست، مرجعِ پلاگین‌ها را ببین.

چرا نسخه‌های وابستگی را قید بزنیم

یک مارکت‌پلیسِ داخلی را در نظر بگیر که دو تیم در آن پلاگین منتشر می‌کنند. تیمِ پلتفرم secrets-vault را نگه می‌دارد، یک سرورِ MCP که یک backendِ اسرار را می‌پیچد. تیمِ deploy deploy-kit را نگه می‌دارد که هنگامِ deploy secrets-vault را برای گرفتنِ اعتبارنامه‌ها صدا می‌زند.

deploy-kit در برابرِ secrets-vault نسخه‌ی v2.1.0 تست شده است. بدونِ قیدِ نسخه، دفعه‌ی بعد که تیمِ پلتفرم انتشاری را تگ بزند که نامِ یک ابزارِ MCP را تغییر می‌دهد، به‌روزرسانیِ خودکار secrets-vault هر مهندس را به نسخه‌ی جدید می‌برد و deploy-kit می‌شکند.

با یک قیدِ نسخه، deploy-kit اعلام می‌کند که به secrets-vault در بازه‌ی ~2.1.0 نیاز دارد. مهندسانی که deploy-kit نصب کرده‌اند روی بالاترین patchِ مطابقِ 2.1.x می‌مانند. تیمِ deploy طبقِ زمان‌بندیِ خودش با انتشارِ نسخه‌ی جدیدی از deploy-kit با قیدِ بازترْ ارتقا می‌دهد.

یک وابستگی با قیدِ نسخه اعلام کن

وابستگی‌ها را در آرایه‌ی dependencies در .claude-plugin/plugin.json پلاگینت فهرست کن. هر ورودی یا نامِ یک پلاگین است یا یک شیء با قیدِ نسخه.

مانیفستِ زیر یک وابستگیِ بدونِ نسخه و یک وابستگیِ قیدشده را اعلام می‌کند:

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

یک ورودی می‌تواند رشته‌ای ساده فقط با نامِ پلاگین باشد، مثلِ "audit-logger" در مثالِ بالا، که به هر نسخه‌ای که مارکت‌پلیسِ آن پلاگین فراهم می‌کند وابسته است. برای کنترلِ بیشتر، از یک شیء با این فیلدها استفاده کن:

فیلد	نوع	توضیح
`name`	string	نامِ پلاگین. درونِ همان مارکت‌پلیسِ پلاگینِ اعلام‌کننده resolve می‌شود. الزامی.
`version`	string	یک بازه‌ی semver مثلِ `~2.1.0`، `^2.0`، `>=1.4` یا `=2.1.0`. وابستگی در بالاترین نسخه‌ی تگ‌خورده‌ای که این بازه را برآورده می‌کند fetch می‌شود.
`marketplace`	string	یک مارکت‌پلیسِ متفاوت برای resolve کردنِ `name` در آن. وابستگی‌های بین‌مارکت‌پلیسی مسدودند مگر اینکه مارکت‌پلیسِ مقصد در `allowCrossMarketplaceDependenciesOn` در `marketplace.json` مارکت‌پلیسِ ریشه فهرست شده باشد.

فیلدِ version هر عبارتی را که پکیجِ semver در Node پشتیبانی می‌کند می‌پذیرد، شاملِ بازه‌های caret، tilde، hyphen و comparator. نسخه‌های pre-release مثلِ 2.0.0-beta.1 مستثنا هستند مگر اینکه بازه‌ات با یک پسوندِ pre-release مثلِ ^2.0.0-0 صراحتاً واردشان کند.

به یک پلاگین از مارکت‌پلیسی دیگر وابسته شو

به‌صورتِ پیش‌فرض، Claude Code از نصبِ خودکارِ وابستگی‌ای که در مارکت‌پلیسی متفاوت از پلاگینِ اعلام‌کننده زندگی می‌کند خودداری می‌کند. این مانع از آن می‌شود که یک مارکت‌پلیس بی‌سروصدا پلاگین‌هایی را از منبعی که بازبینی نکرده‌ای بکشد.

برای مجازکردنش، نگه‌دارنده‌ی مارکت‌پلیسِ ریشه نامِ مارکت‌پلیسِ مقصد را به allowCrossMarketplaceDependenciesOn در marketplace.json اضافه می‌کند. مارکت‌پلیسِ ریشه همان است که میزبانِ پلاگینی است که کاربر نصب می‌کند؛ فقط allowlistِ آن بررسی می‌شود، پس اعتماد از طریقِ مارکت‌پلیس‌های میانی زنجیر نمی‌شود.

marketplace.json زیر به deploy-kit اجازه می‌دهد به پلاگینی از 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" }
      ]
    }
  ]
}

اگر فیلد وجود نداشته باشد یا مارکت‌پلیسِ مقصد را شامل نشود، نصب با خطای cross-marketplace که نامِ فیلدِ لازم برای تنظیم را نام می‌برد شکست می‌خورد. کاربران هنوز می‌توانند ابتدا وابستگی را به‌صورتِ دستی نصب کنند که قید را بدونِ تغییرِ allowlist برآورده می‌کند.

انتشارهای پلاگین را برای resolveِ نسخه تگ بزن

قیدهای نسخه در برابرِ تگ‌های git روی مخزنِ مارکت‌پلیس resolve می‌شوند. برای اینکه Claude Code بتواند نسخه‌های موجودِ یک وابستگی را پیدا کند، انتشارهای پلاگینِ upstream باید با یک قراردادِ نام‌گذاریِ مشخص تگ بخورند.

هر انتشار را به‌صورتِ {plugin-name}--v{version} تگ بزن، جایی که {version} با فیلدِ version در plugin.json آن کامیت مطابقت دارد. از دایرکتوریِ پلاگین، این را اجرا کن:

claude plugin tag --push

دستورِ claude plugin tag نامِ تگ را از مانیفستِ پلاگین و ورودیِ مارکت‌پلیسِ دربرگیرنده مشتق می‌کند. پیش از ساختنِ تگ، محتوای پلاگین را اعتبارسنجی می‌کند، بررسی می‌کند که plugin.json و ورودیِ مارکت‌پلیس بر سرِ نسخه توافق دارند، یک working tree تمیز زیرِ دایرکتوریِ پلاگین می‌طلبد، و اگر تگ از قبل وجود داشته باشد خودداری می‌کند. --dry-run را اضافه کن تا ببینی چه چیزی تگ می‌خورد بدونِ اینکه ساخته شود. اجرای مستقیمِ git tag secrets-vault--v2.1.0 معادل است، اگر خودت plugin.json و ورودیِ مارکت‌پلیس را همگام نگه داری.

پیشوندِ نامِ پلاگین می‌گذارد یک مخزنِ مارکت‌پلیس میزبانِ چند پلاگین با خط‌های نسخه‌ی مستقل باشد. جداکننده‌ی --v به‌صورتِ یک تطبیقِ پیشوندی روی نامِ کاملِ پلاگین parse می‌شود، پس نام‌های پلاگینی که خط‌فاصله دارند درست مدیریت می‌شوند.

وقتی پلاگینی نصب می‌کنی که { "name": "secrets-vault", "version": "~2.1.0" } را اعلام می‌کند، Claude Code تگ‌های مارکت‌پلیس را فهرست می‌کند، به آن‌هایی که با secrets-vault--v شروع می‌شوند فیلتر می‌کند، و بالاترین نسخه‌ای را که ~2.1.0 را برآورده می‌کند fetch می‌کند. اگر هیچ تگِ مطابقی وجود نداشته باشد، پلاگینِ وابسته با خطایی که نسخه‌های موجود را فهرست می‌کند غیرفعال می‌شود.

semverِ تگِ resolve‌شده جدا از version در plugin.json ثبت می‌شود، پس بررسی‌های قید از تگی که واقعاً fetch شد استفاده می‌کنند، حتی اگر plugin.json در آن کامیت مقداری کهنه داشته باشد. نامِ دایرکتوریِ cache برای یک نصبِ تگ-resolve‌شده شاملِ یک پسوندِ ۱۲ کاراکتریِ commit-SHA است، پس اگر نگه‌دارنده‌ای تگی را به اجبار به کامیتِ دیگری منتقل کند، نصبِ بعدی به‌جای استفاده‌ی دوباره از محتوای کهنه، دایرکتوریِ cacheِ تازه‌ای می‌گیرد.

قیدها چطور با هم تعامل می‌کنند

وقتی چند پلاگینِ نصب‌شده همان وابستگی را قید می‌زنند، Claude Code بازه‌هایشان را اشتراک می‌گیرد و وابستگی را به بالاترین نسخه‌ای که همه‌ی آن‌ها را برآورده می‌کند resolve می‌کند. جدولِ زیر نشان می‌دهد ترکیب‌های رایج چطور resolve می‌شوند.

پلاگینِ A نیاز دارد	پلاگینِ B نیاز دارد	نتیجه
`^2.0`	`>=2.1`	یک نصب روی بالاترین تگِ `2.x` در `2.1.0` یا بالاتر. هر دو پلاگین بار می‌شوند.
`~2.1`	`~3.0`	نصبِ پلاگینِ B با `range-conflict` شکست می‌خورد. پلاگینِ A و وابستگی همان‌طور که بودند می‌مانند.
`=2.1.0`	هیچ‌کدام	وابستگی روی `2.1.0` می‌ماند. تا وقتی پلاگینِ A نصب است، به‌روزرسانیِ خودکار نسخه‌های جدیدتر را رد می‌کند.

به‌روزرسانیِ خودکار یک وابستگیِ قیدشده را در بالاترین تگِ git که بازه‌ی هر پلاگینِ نصب‌شده را برآورده می‌کند fetch می‌کند، نه در آخرین نسخه‌ی مارکت‌پلیس، پس وابستگی همچنان درونِ بازه‌ی مجازش به‌روزرسانی دریافت می‌کند. اگر هیچ تگی همه‌ی بازه‌ها را برآورده نکند، به‌روزرسانی رد می‌شود و این رد در /doctor و تبِ Errors در /plugin ظاهر می‌شود و پلاگینِ قیدگذار را نام می‌برد.

وقتی آخرین پلاگینی را که یک وابستگی را قید می‌زند uninstall کنی، دیگر آن وابستگی نگه‌داشته نمی‌شود و در به‌روزرسانیِ بعدی به دنبال‌کردنِ ورودیِ مارکت‌پلیسش برمی‌گردد.

یک پلاگینِ دارای وابستگی را فعال یا غیرفعال کن

فعال‌کردنِ یک پلاگین، پلاگین‌هایی را که به آن‌ها وابسته است هم فعال می‌کند، و غیرفعال‌کردنِ یک پلاگین مسدود می‌شود اگر پلاگینِ فعالِ دیگری هنوز به آن نیاز داشته باشد. هر دو رفتار به Claude Code نسخه‌ی v2.1.143 یا بالاتر نیاز دارند. نسخه‌های قدیمی‌تر فقط پلاگینِ نام‌برده را فعال یا غیرفعال می‌کنند و در بارگذاریِ بعدی خطای dependency-unsatisfied را نمایان می‌کنند.

وقتی پلاگینی را فعال می‌کنی، Claude Code وابستگی‌هایش را هم در همان scope فعال می‌کند. اگر وابستگی‌ای وابستگی‌های خودش را داشته باشد، Claude Code آن‌ها را هم فعال می‌کند. پیامِ موفقیت فهرست می‌کند که علاوه بر پلاگینی که نام بردی، چه چیزِ دیگری فعال شد. اگر وابستگی‌ای نتواند فعال شود، دستور خودداری می‌کند و به تو می‌گوید چه چیزی مانع است و چطور برطرفش کنی:

شرط	نتیجه
یک وابستگی نصب نیست	فعال‌سازی شکست می‌خورد و دستورِ `claude plugin install` را برای هر وابستگیِ گمشده چاپ می‌کند.
یک وابستگی توسطِ سیاستِ پلاگینِ سازمانت مسدود است	فعال‌سازی شکست می‌خورد و وابستگیِ مسدودشده را نام می‌برد.
یک وابستگی در scopeای با تقدمِ بالاتر از scopeِ هدف روی `false` تنظیم شده است	فعال‌سازی شکست می‌خورد. وابستگی را در آن scope فعال کن، یا `--scope` بده تا آنجا بنویسد.
همه‌ی وابستگی‌ها نصب و مجازند	فعال‌سازی موفق می‌شود و برای پلاگین و هر وابستگی که از قبل در scopeِ هدف فعال نبوده `true` می‌نویسد.

این حتی وقتی صادق است که یک وابستگی defaultEnabled: false را در مانیفستش تنظیم کند، چون Claude Code یک true صریح برایش می‌نویسد. همین در زمانِ نصب هم اعمال می‌شود: وابستگی‌ای که برای برآورده‌کردنِ یک پلاگینِ فعال کشیده شده، صرفِ‌نظر از پیش‌فرضِ خودش با true نصب می‌شود.

وقتی پلاگینی را غیرفعال می‌کنی، Claude Code خودداری می‌کند اگر پلاگینِ فعالِ دیگری هنوز به آن وابسته باشد. خطا پلاگین‌هایی را که به آن وابسته‌اند نام می‌برد و دستوری زنجیره‌ای به تو می‌دهد که آن‌ها را به ترتیبِ درست غیرفعال می‌کند و به همانی که خواسته بودی ختم می‌شود.

برای مثال، اگر deploy-kit به secrets-vault وابسته باشد، غیرفعال‌کردنِ secrets-vault به‌تنهایی با خروجی‌ای شبیه به این شکست می‌خورد:

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

دستورِ زنجیره‌ای را از خطا کپی کن تا کلِ مجموعه را در یک گام غیرفعال کنی.

وابستگی‌های خودکار-نصب‌شده‌ی یتیم را حذف کن

وابستگی‌های خودکار-نصب‌شده پس از uninstall شدنِ پلاگین‌هایی که نصبشان کرده‌اند روی دیسک می‌مانند، برای صورتی که پلاگینِ وابسته‌ای را دوباره نصب کنی یا بخواهی همچنان مستقیماً از وابستگی استفاده کنی. برای پاک‌سازیشان، claude plugin prune را اجرا کن تا وابستگی‌های خودکار-نصب‌شده‌ای را که دیگر هیچ پلاگینِ نصب‌شده‌ای به آن‌ها نیاز ندارد فهرست کند و پس از یک پرامپتِ تأیید حذفشان کند. این به Claude Code نسخه‌ی v2.1.121 یا بالاتر نیاز دارد.

claude plugin prune

به‌صورتِ پیش‌فرض، prune در scopeِ user عمل می‌کند. از --scope project یا --scope local برای هدف‌گیریِ scopeِ متفاوت استفاده کن. --dry-run را بده تا آنچه حذف می‌شود فهرست شود بدونِ اینکه چیزی تغییر کند. -y را بده تا از پرامپتِ تأیید رد شوی. وقتی stdin یا stdout یک ترمینال نیست، prune یتیم‌ها را فهرست می‌کند و بدونِ حذفشان خارج می‌شود مگر اینکه -y داده شود.

برای prune به‌عنوانِ بخشی از یک uninstall، --prune را به claude plugin uninstall بده. پس از حذفِ پلاگینِ نام‌برده، Claude Code هر وابستگیِ خودکار-نصب‌شده‌ای را که حالا یتیم شده اسکن و حذف می‌کند. پلاگین‌هایی که خودت نصب کرده‌ای هرگز prune نمی‌شوند، فقط آن‌هایی که خودکار از طریقِ آرایه‌ی dependencies پلاگینِ دیگری نصب شده‌اند.

برای مثال، برای uninstall کردنِ deploy-kit و پاک‌سازیِ وابستگی‌هایی که جا می‌گذارد:

claude plugin uninstall deploy-kit --prune

خطاهای وابستگی را برطرف کن

مشکلاتِ وابستگی در claude plugin list، در رابطِ /plugin و در /doctor نمایان می‌شوند. پلاگینِ متأثر تا برطرف‌کردنِ خطا غیرفعال می‌ماند. رایج‌ترین خطاها و رفعِ آن‌ها در زیر فهرست شده‌اند.

خطا	معنی	چطور برطرف کنیم
`dependency-unsatisfied`	یک وابستگیِ اعلام‌شده نصب نیست، یا نصب است ولی غیرفعال.	دستورِ `claude plugin install` نشان‌داده‌شده در پیامِ خطا را اجرا کن. اگر مارکت‌پلیسِ وابستگی هنوز پیکربندی نشده، آن را با `claude plugin marketplace add` اضافه کن و Claude Code وابستگی را خودکار resolve می‌کند. اگر وابستگی غیرفعال است، فعالش کن.
`range-conflict`	الزاماتِ نسخه برای یک وابستگی قابلِ ترکیب نیستند. پیامِ خطا علت را نام می‌برد: هیچ نسخه‌ای همه‌ی بازه‌ها را برآورده نمی‌کند، یک بازه نحوِ معتبرِ semver نیست، یا بازه‌های ترکیب‌شده برای اشتراک‌گیری پیچیده‌اند.	یکی از پلاگین‌های متعارض را uninstall یا به‌روز کن، هر رشته‌ی `version` نامعتبر را اصلاح کن، زنجیره‌های طولانیِ `\|\|` را ساده کن، یا از نویسنده‌ی upstream بخواه قیدش را بازتر کند.
`dependency-version-unsatisfied`	نسخه‌ی وابستگیِ نصب‌شده بیرونِ بازه‌ی اعلام‌شده‌ی این پلاگین است.	`claude plugin install <dependency>@<marketplace>` را اجرا کن تا وابستگی در برابرِ همه‌ی قیدهای جاری دوباره resolve شود.
`no-matching-tag`	مخزنِ وابستگی هیچ تگِ `{name}--v*` که بازه را برآورده کند ندارد.	بررسی کن که upstream انتشارها را با قراردادِ بالا تگ زده، یا بازه‌ات را شل‌تر کن.

برای بررسیِ این خطاها به‌صورتِ برنامه‌نویسی، claude plugin list --json را اجرا کن و فیلدِ errors را روی هر پلاگین بخوان.

همچنین ببین

ساختِ پلاگین‌ها: پلاگین‌هایی با skillها، agentها و hookها بساز
ساخت و توزیعِ یک مارکت‌پلیسِ پلاگین: پلاگین‌ها را برای تیمت میزبانی کن
مرجعِ پلاگین‌ها: اسکیمای کاملِ plugin.json
مدیریتِ نسخه: چطور نسخه‌ی خودِ یک پلاگین resolve می‌شود و به‌عنوانِ کلیدِ cache استفاده می‌شود