آزمایش: به‌روزرسانی‌ها و Pluginها

چک‌لیست اعتبارسنجی به‌روزرسانی و Plugin: اثبات کنید بسته قابل‌نصب می‌تواند وضعیت واقعی کاربر را به‌روزرسانی کند، وضعیت قدیمی و منسوخ را از طریق doctor ترمیم کند و همچنان Pluginها را از همه منابع پشتیبانی‌شده نصب، بارگذاری، به‌روزرسانی و حذف نصب کند.

برای نقشه جامع‌تر اجراکننده آزمون، به آزمایش مراجعه کنید. برای کلیدهای ارائه‌دهنده زنده و مجموعه‌آزمون‌هایی که با شبکه تعامل دارند، به آزمایش زنده مراجعه کنید.

از چه چیزهایی محافظت می‌کنیم

• فایل tarball بسته کامل است، یک dist/postinstall-inventory.json معتبر دارد و به فایل‌های استخراج‌نشده مخزن وابسته نیست.
• کاربر می‌تواند بدون از دست دادن پیکربندی، عامل‌ها، نشست‌ها، فضاهای کاری، فهرست‌های مجاز Plugin یا پیکربندی کانال، از یک بسته منتشرشده قدیمی‌تر به بسته نامزد منتقل شود.
• openclaw doctor --fix --non-interactive مالک مسیرهای پاک‌سازی و ترمیم قدیمی است. راه‌اندازی نباید مهاجرت‌های سازگاری پنهانی برای وضعیت منسوخ Plugin ایجاد کند.
• نصب Plugin از دایرکتوری‌های محلی، مخازن git، بسته‌های npm و مسیر رجیستری ClawHub کار می‌کند.
• وابستگی‌های npm هر Plugin در یک پروژه npm مدیریت‌شده برای همان Plugin نصب می‌شوند، پیش از اعتماد اسکن می‌شوند و هنگام حذف نصب Plugin از طریق npm uninstall حذف می‌شوند تا وابستگی‌های بالاکشیده‌شده باقی نمانند.
• وقتی چیزی تغییر نکرده است، به‌روزرسانی Plugin هیچ عملی انجام نمی‌دهد: رکوردهای نصب، منبع حل‌شده، چیدمان وابستگی‌های نصب‌شده و وضعیت فعال‌بودن دست‌نخورده باقی می‌مانند.

اثبات محلی هنگام توسعه

از محدوده‌ای کوچک آغاز کنید:

pnpm changed:lanes --jsonpnpm check:changedpnpm test:changed

برای تغییرات نصب، حذف نصب، وابستگی یا موجودی بسته Plugin، آزمون‌های متمرکزی را نیز اجرا کنید که مرز ویرایش‌شده را پوشش می‌دهند:

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

پیش از آنکه هر مسیر Docker مربوط به بسته یک tarball را مصرف کند، مصنوع بسته را اثبات کنید:

pnpm release:check

release:check بررسی‌های ناهماهنگی پیکربندی/مستندات/API را اجرا می‌کند (شِمای پیکربندی، خط مبنای مستندات پیکربندی، خط مبنای API و خروجی‌های SDK Plugin، نسخه‌ها/موجودی Plugin)، موجودی توزیع بسته را می‌نویسد، npm pack --dry-run را اجرا می‌کند، فایل‌های بسته‌بندی‌شده ممنوع را رد می‌کند، tarball را در یک پیشوند موقت نصب می‌کند، postinstall را اجرا می‌کند و نقاط ورود کانال‌های همراه را به‌صورت دودآزمایی بررسی می‌کند.

مسیرهای Docker

مسیرهای Docker اثبات در سطح محصول هستند. آن‌ها یک بسته واقعی را درون کانتینرهای Linux نصب یا به‌روزرسانی می‌کنند و رفتار را از طریق فرمان‌های CLI، راه‌اندازی Gateway، کاوشگرهای HTTP، وضعیت RPC و وضعیت سامانه فایل بررسی می‌کنند.

هنگام تکرار و اصلاح، از مسیرهای متمرکز استفاده کنید:

pnpm test:docker:pluginspnpm test:docker:plugin-lifecycle-matrixpnpm test:docker:plugin-updatepnpm test:docker:upgrade-survivorpnpm test:docker:published-upgrade-survivorpnpm test:docker:update-restart-authpnpm test:docker:update-migration

مسیرهای مهم:

• test:docker:plugins دودآزمایی نصب Plugin، نصب از پوشه محلی، رفتار ردکردن به‌روزرسانی پوشه محلی، پوشه‌های محلی دارای وابستگی‌های ازپیش‌نصب‌شده، نصب بسته‌های file:، نصب از git همراه با اجرای CLI، به‌روزرسانی ارجاع متحرک git، نصب از رجیستری npm با وابستگی‌های انتقالی بالاکشیده‌شده، بی‌عملی به‌روزرسانی npm، رد فراداده ناقص بسته npm، نصب از فیکسچر محلی ClawHub و بی‌عملی به‌روزرسانی، رفتار به‌روزرسانی بازارگاه و فعال‌سازی/بازرسی بسته Claude را پوشش می‌دهد. OPENCLAW_PLUGINS_E2E_CLAWHUB=0 را تنظیم کنید تا بلوک ClawHub خودبسنده/آفلاین بماند.
• test:docker:plugin-lifecycle-matrix بسته نامزد را در یک کانتینر خام نصب می‌کند و یک Plugin مبتنی بر npm را از مراحل نصب، بازرسی، غیرفعال‌سازی، فعال‌سازی، ارتقای صریح، تنزل صریح و حذف نصب پس از حذف کد Plugin عبور می‌دهد. این مسیر برای هر مرحله معیارهای RSS و CPU را ثبت می‌کند.
• test:docker:plugin-update اعتبارسنجی می‌کند که یک Plugin نصب‌شده بدون تغییر، هنگام openclaw plugins update دوباره نصب نشود یا فراداده نصب خود را از دست ندهد.
• test:docker:upgrade-survivor فایل tarball نامزد را روی یک فیکسچر کاربر قدیمی و آلوده نصب می‌کند، به‌روزرسانی بسته به‌همراه doctor غیرتعاملی را اجرا می‌کند، سپس یک Gateway در local loopback راه‌اندازی می‌کند و حفظ وضعیت را بررسی می‌کند.
• test:docker:published-upgrade-survivor ابتدا یک خط مبنای منتشرشده را نصب می‌کند، آن را از طریق دستورالعمل ازپیش‌تعبیه‌شده openclaw config set پیکربندی می‌کند، به فایل tarball نامزد به‌روزرسانی می‌کند، doctor را اجرا می‌کند، پاک‌سازی موارد قدیمی را بررسی می‌کند، Gateway را راه‌اندازی می‌کند و /healthz، /readyz و وضعیت RPC را می‌آزماید.
• test:docker:update-restart-auth بسته نامزد را نصب می‌کند، یک Gateway مدیریت‌شده با احراز هویت توکنی راه‌اندازی می‌کند، متغیر محیطی احراز هویت Gateway فراخوان را برای openclaw update --yes --json حذف می‌کند و الزام می‌کند فرمان به‌روزرسانی نامزد پیش از کاوش‌های عادی Gateway را مجدداً راه‌اندازی کند.
• test:docker:update-migration مسیر به‌روزرسانی منتشرشده با تمرکز سنگین بر پاک‌سازی است. این مسیر از وضعیت کاربری پیکربندی‌شده به سبک Discord/Telegram آغاز می‌کند، doctor خط مبنا را اجرا می‌کند تا وابستگی‌های Plugin پیکربندی‌شده فرصت ایجادشدن داشته باشند، بقایای قدیمی وابستگی Plugin را برای یک Plugin بسته‌بندی‌شده پیکربندی‌شده ایجاد می‌کند، به فایل tarball نامزد به‌روزرسانی می‌کند و الزام می‌کند doctor پس از به‌روزرسانی ریشه‌های قدیمی وابستگی را حذف کند.

گونه‌های مفید برای بازمانده ارتقای منتشرشده:

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \pnpm test:docker:published-upgrade-survivor OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \pnpm test:docker:published-upgrade-survivor

سناریوهای موجود: base، acpx-openclaw-tools-bridge، feishu-channel، bootstrap-persona، channel-post-core-restore، plugin-deps-cleanup، configured-plugin-installs، stale-source-plugin-shadow، tilde-log-path و versioned-runtime-deps. در اجراهای تجمیعی، OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (نام مستعار far-reaching) به همه سناریوها، از جمله مهاجرت نصب Plugin پیکربندی‌شده، گسترش می‌یابد.

مهاجرت کامل به‌روزرسانی عمداً از CI انتشار کامل جدا است. وقتی پرسش انتشار این است که «آیا همه انتشارهای پایدار منتشرشده از 2026.4.23 به بعد می‌توانند به این نامزد به‌روزرسانی شوند و بقایای وابستگی Plugin را پاک کنند؟»، از گردش‌کار دستی Update Migration استفاده کنید:

gh workflow run update-migration.yml \  --ref main \  -f workflow_ref=main \  -f package_ref=main \  -f baselines=all-since-2026.4.23 \  -f scenarios=plugin-deps-cleanup

پذیرش بسته

پذیرش بسته، دروازه بسته بومی GitHub است. این فرایند یک بسته نامزد را به فایل tarball با نام package-under-test تبدیل می‌کند، نسخه و SHA-256 را ثبت می‌کند و سپس مسیرهای Docker E2E قابل‌استفاده مجدد را دقیقاً روی همان tarball اجرا می‌کند. ارجاع چارچوب گردش‌کار از ارجاع منبع بسته جدا است؛ بنابراین منطق آزمون فعلی می‌تواند انتشارهای قابل‌اعتماد قدیمی‌تر را اعتبارسنجی کند.

منابع نامزد:

• source=npm: اعتبارسنجی openclaw@extended-stable، openclaw@beta، openclaw@latest یا یک نسخه دقیق منتشرشده.
• source=ref: بسته‌بندی یک شاخه، برچسب یا commit قابل‌اعتماد با چارچوب فعلی انتخاب‌شده.
• source=url: اعتبارسنجی یک tarball عمومی HTTPS با package_sha256 الزامی. این مسیر اطلاعات اعتبارسنجی در URL، پورت‌های HTTPS غیراستاندارد، نام میزبان یا نتایج DNS/IP خصوصی/داخلی، فضای IP با کاربرد ویژه و تغییرمسیرهای ناامن را رد می‌کند.
• source=trusted-url: اعتبارسنجی یک tarball از طریق HTTPS با package_sha256 و trusted_source_id الزامی بر پایه سیاست تحت مالکیت نگه‌دارنده در .github/package-trusted-sources.json. برای آینه‌های سازمانی/خصوصی از این گزینه استفاده کنید، نه اینکه source=url را با یک کلید سطح ورودی برای اجازه‌دادن به منابع خصوصی تضعیف کنید. احراز هویت Bearer، در صورت پیکربندی در سیاست، از secret ثابت OPENCLAW_TRUSTED_PACKAGE_TOKEN استفاده می‌کند.
• source=artifact: استفاده مجدد از یک tarball بارگذاری‌شده توسط اجرای دیگری از Actions.

اعتبارسنجی کامل انتشار به‌طور پیش‌فرض از source=artifact استفاده می‌کند که از SHA حل‌شده انتشار ساخته شده است. برای اثبات پس از انتشار، package_acceptance_package_spec=openclaw@YYYY.M.PATCH را ارسال کنید تا همان ماتریس ارتقا بسته npm عرضه‌شده را هدف قرار دهد.

بررسی‌های انتشار، پذیرش بسته را با مجموعه بسته/به‌روزرسانی/راه‌اندازی مجدد/Plugin فراخوانی می‌کنند:

doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape

وقتی دوره پایش انتشار فعال باشد (برای release_profile=stable و full اجباری است)، این موارد نیز ارسال می‌شوند:

published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15published_upgrade_survivor_scenarios=reported-issuestelegram_mode=mock-openai

این کار مهاجرت بسته، تعویض کانال به‌روزرسانی، تحمل Plugin مدیریت‌شده خراب، پاک‌سازی وابستگی‌های منسوخ Plugin، پوشش آفلاین Plugin، رفتار به‌روزرسانی Plugin و تضمین کیفیت بسته Telegram را روی همان مصنوع حل‌شده نگه می‌دارد، بدون آنکه دروازه پیش‌فرض بسته انتشار را مجبور کند همه انتشارهای منتشرشده را پیمایش کند.

last-stable-4 به چهار انتشار پایدار اخیر OpenClaw که در npm منتشر شده‌اند حل می‌شود. پذیرش بسته انتشار، 2026.4.23 را به‌عنوان نخستین مرز سازگاری به‌روزرسانی Plugin، 2026.5.2 را به‌عنوان مرز تغییرات گسترده معماری Plugin و 2026.4.15 را به‌عنوان خط مبنای قدیمی‌تر به‌روزرسانی منتشرشده از سری 2026.4.1x تثبیت می‌کند؛ حل‌کننده موارد تثبیت‌شده‌ای را که از قبل در چهار نسخه اخیر هستند حذف می‌کند. برای پوشش جامع مهاجرت به‌روزرسانی‌های منتشرشده، به‌جای CI انتشار کامل از all-since-2026.4.23 در گردش‌کار جداگانه Update Migration استفاده کنید. وقتی نمونه‌برداری دستی گسترده‌تری را می‌خواهید که لنگر قدیمی پیش از تاریخ را نیز شامل شود، release-history همچنان در دسترس است.

وقتی چند خط مبنای بازمانده ارتقای منتشرشده انتخاب شوند، گردش‌کار Docker قابل‌استفاده مجدد هر خط مبنا را در یک کار اجراکننده هدفمند مستقل شارد می‌کند. هر شارد خط مبنا همچنان مجموعه سناریوهای انتخاب‌شده را اجرا می‌کند، اما گزارش‌ها و مصنوعات به تفکیک خط مبنا باقی می‌مانند و زمان کلی به کندترین شارد محدود می‌شود، نه یک کار سریالی بزرگ.

هنگام اعتبارسنجی یک نامزد پیش از انتشار، نمایه بسته را به‌صورت دستی اجرا کنید:

gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=package \  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \  -f published_upgrade_survivor_scenarios=reported-issues \  -f telegram_mode=mock-openai

برای یک نسخه قناری extended-stable منتشرشده، package_spec=openclaw@extended-stable را تنظیم کنید. پذیرش بسته پیش از اجرای مسیرهای Docker، آن انتخاب‌گر را به یک tarball دقیق حل می‌کند.

وقتی پرسش انتشار شامل کانال‌های MCP، پاک‌سازی cron/زیرعامل، جست‌وجوی وب OpenAI یا OpenWebUI است، از suite_profile=product استفاده کنید. تنها وقتی به پوشش کامل مسیر انتشار Docker نیاز دارید، از suite_profile=full استفاده کنید.

پیش‌فرض انتشار

برای نامزدهای انتشار، پشته اثبات پیش‌فرض چنین است:

1. pnpm check:changed و pnpm test:changed برای پسرفت‌های سطح منبع.
2. pnpm release:check برای یکپارچگی مصنوع بسته.
3. نمایه package پذیرش بسته یا مسیرهای سفارشی بسته در بررسی انتشار برای قراردادهای نصب/به‌روزرسانی/راه‌اندازی مجدد/Plugin.
4. بررسی‌های انتشار چندسیستم‌عاملی برای نصب‌کننده، راه‌اندازی اولیه و رفتار مختص پلتفرم.
5. مجموعه‌آزمون‌های زنده فقط زمانی که سطح تغییرکرده، رفتار ارائه‌دهنده یا سرویس میزبانی‌شده را تحت تأثیر قرار می‌دهد.

در دستگاه‌های نگه‌دارندگان، دروازه‌های گسترده و اثبات محصول Docker/بسته باید در Testbox اجرا شوند، مگر آنکه اثبات محلی صراحتاً مدنظر باشد.

سازگاری قدیمی

مدارا برای سازگاری محدود و زمان‌بندی‌شده است:

• بسته‌ها تا نسخه 2026.4.25، از جمله 2026.4.25-beta.*، می‌توانند کمبودهای فراداده بسته‌ای را که پیش‌تر عرضه شده‌اند در پذیرش بسته تحمل کنند.
• بسته منتشرشده 2026.4.26 ممکن است برای فایل‌های مهر فراداده ساخت محلی که قبلاً عرضه شده‌اند هشدار دهد.
• بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند. همان کمبودها به‌جای هشدار یا ردشدن، باعث شکست می‌شوند.

برای این شکل‌های قدیمی، مهاجرت راه‌اندازی جدید اضافه نکنید. یک ترمیم doctor اضافه کنید یا گسترش دهید، سپس آن را با upgrade-survivor، published-upgrade-survivor یا، وقتی فرمان به‌روزرسانی مالک راه‌اندازی مجدد است، با update-restart-auth اثبات کنید.

افزودن پوشش

هنگام تغییر رفتار به‌روزرسانی یا Plugin، پوشش را در پایین‌ترین لایه‌ای اضافه کنید که بتواند به دلیل درست شکست بخورد:

• منطق صرفاً مربوط به مسیر یا فراداده: آزمون واحد در کنار کد منبع.
• فهرست محتوای بسته یا رفتار فایل‌های بسته‌بندی‌شده: آزمون بررسی‌کننده‌ی package-dist-inventory یا tarball.
• رفتار نصب/به‌روزرسانی CLI: بررسی در مسیر Docker یا فیکسچر.
• رفتار مهاجرت نسخه‌ی منتشرشده: سناریوی published-upgrade-survivor.
• رفتار راه‌اندازی مجدد تحت مالکیت به‌روزرسانی: update-restart-auth.
• رفتار منبع رجیستری/بسته: فیکسچر test:docker:plugins یا سرور فیکسچر ClawHub.
• رفتار چیدمان یا پاک‌سازی وابستگی‌ها: هم اجرای زمان‌اجرا و هم مرز سامانه‌ی فایل را بررسی کنید. وابستگی‌های npm ممکن است درون پروژه‌ی npm مدیریت‌شده‌ی Plugin بالاکشیده شوند؛ بنابراین آزمون‌ها باید ثابت کنند که آن پروژه اسکن/پاک‌سازی می‌شود، نه اینکه فرض کنند فقط درخت node_modules محلیِ بسته‌ی Plugin بررسی می‌شود.

فیکسچرهای جدید Docker را به‌طور پیش‌فرض خودبسنده نگه دارید. مگر اینکه هدف آزمون، رفتار زنده‌ی رجیستری باشد، از رجیستری‌های فیکسچر محلی و بسته‌های ساختگی استفاده کنید.

تریاژ خرابی

از هویت آرتیفکت شروع کنید:

• خلاصه‌ی resolve_package در پذیرش بسته: منبع، نسخه، SHA-256 و نام آرتیفکت.
• آرتیفکت‌های Docker: .artifacts/docker-tests/**/summary.json، failures.json، گزارش‌های مسیر و فرمان‌های اجرای مجدد.
• خلاصه‌ی بازمانده‌ی ارتقا: .artifacts/upgrade-survivor/summary.json، شامل نسخه‌ی مبنا، نسخه‌ی نامزد، سناریو، زمان‌بندی مراحل و پوشش دستورالعمل پیکربندی.

اجرای مجدد دقیق همان مسیر ناموفق با همان آرتیفکت بسته را به اجرای مجدد کل مجموعه‌ی انتشار ترجیح دهید.