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

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

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

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

• یک تاربال بسته کامل است، 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 مربوط به بسته یک تاربال را مصرف کند، مصنوع بسته را اثبات کنید:

pnpm release:check

release:check بررسی‌های انحراف پیکربندی/مستندات/API را اجرا می‌کند (شِمای پیکربندی، خط مبنای مستندات پیکربندی، مانیفست و خروجی‌های قرارداد API مربوط به SDK ‏Plugin، نسخه‌ها/موجودی Plugin)، موجودی توزیع بسته را می‌نویسد، npm pack --dry-run را اجرا می‌کند، فایل‌های بسته‌بندی‌شدهٔ ممنوع را رد می‌کند، تاربال را در یک پیشوند موقت نصب می‌کند، 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 را پوشش می‌دهد. برای بسته‌نگه‌داشتن بخش ClawHub به‌صورت خودبسنده/آفلاین، OPENCLAW_PLUGINS_E2E_CLAWHUB=0 را تنظیم کنید.
• test:docker:plugin-lifecycle-matrix بستهٔ نامزد را در یک کانتینر خالی نصب می‌کند، یک Plugin ‏npm را در مراحل نصب، بازرسی، غیرفعال‌سازی، فعال‌سازی، ارتقای صریح، تنزل صریح و حذف پس از پاک‌کردن کد Plugin اجرا می‌کند. برای هر مرحله معیارهای RSS و CPU را ثبت می‌کند.
• test:docker:plugin-update اعتبارسنجی می‌کند که یک Plugin نصب‌شدهٔ بدون تغییر، هنگام openclaw plugins update دوباره نصب نشود یا فرادادهٔ نصب خود را از دست ندهد.
• test:docker:upgrade-survivor تاربال نامزد را روی یک فیکسچر کاربر قدیمیِ نامرتب نصب می‌کند، به‌روزرسانی بسته و سپس doctor غیرتعاملی را اجرا می‌کند، بعد یک Gateway حلقه‌بازگشت راه می‌اندازد و حفظ وضعیت را بررسی می‌کند.
• test:docker:published-upgrade-survivor ابتدا یک خط مبنای منتشرشده را نصب می‌کند، آن را از طریق دستورالعمل ازپیش‌تعبیه‌شدهٔ openclaw config set پیکربندی می‌کند، آن را به تاربال نامزد به‌روزرسانی می‌کند، 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 بسته‌بندی‌شدهٔ پیکربندی‌شده ایجاد می‌کند، به تاربال نامزد به‌روزرسانی می‌کند و الزام می‌کند 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 است. این فرایند یک بستهٔ نامزد را به تاربال package-under-test تبدیل می‌کند، نسخه و SHA-256 را ثبت می‌کند و سپس مسیرهای E2E قابل‌استفادهٔ مجدد Docker را روی دقیقاً همان تاربال اجرا می‌کند. ارجاع چارچوب گردش‌کار از ارجاع منبع بسته جدا است، بنابراین منطق آزمون فعلی می‌تواند نسخه‌های قدیمی‌تر مورداعتماد را اعتبارسنجی کند.

منابع نامزد:

• source=npm: اعتبارسنجی openclaw@extended-stable، openclaw@beta، openclaw@latest یا یک نسخهٔ دقیق منتشرشده.
• source=ref: بسته‌بندی یک شاخه، برچسب یا کامیت مورداعتماد با چارچوب فعلی انتخاب‌شده.
• source=url: اعتبارسنجی یک تاربال عمومی HTTPS با package_sha256 الزامی. این مسیر اعتبارنامه‌های URL، درگاه‌های غیراستاندارد HTTPS، نام‌های میزبان یا نتایج DNS/IP خصوصی/داخلی، فضای IP با کاربرد ویژه و تغییرمسیرهای ناامن را رد می‌کند.
• source=trusted-url: اعتبارسنجی یک تاربال HTTPS با package_sha256 و trusted_source_id الزامی طبق خط‌مشی تحت مالکیت نگه‌دارندگان در .github/package-trusted-sources.json. برای آینه‌های سازمانی/خصوصی به‌جای تضعیف source=url با یک کلید allow-private در سطح ورودی، از این مسیر استفاده کنید. احراز هویت Bearer، وقتی در خط‌مشی پیکربندی شده باشد، از راز ثابت OPENCLAW_TRUSTED_PACKAGE_TOKEN استفاده می‌کند.
• source=artifact: استفادهٔ مجدد از تاربال بارگذاری‌شده توسط یک اجرای دیگر 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 تثبیت می‌کند؛ حل‌کننده تثبیت‌هایی را که از قبل در چهار نسخهٔ اخیر وجود دارند حذف تکراری می‌کند. برای پوشش جامع مهاجرت به‌روزرسانی منتشرشده، در گردش‌کار جداگانهٔ مهاجرت به‌روزرسانی از all-since-2026.4.23 به‌جای CI انتشار کامل استفاده کنید. 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، آن گزینشگر را به یک تاربال دقیق رفع می‌کند.

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

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

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

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 یا fixture.
• رفتار مهاجرت نسخه منتشرشده: سناریوی published-upgrade-survivor.
• رفتار راه‌اندازی مجدد تحت مالکیت به‌روزرسانی: update-restart-auth.
• رفتار منبع رجیستری/بسته: fixture مربوط به test:docker:plugins یا سرور fixture مربوط به ClawHub.
• رفتار چیدمان یا پاک‌سازی وابستگی: هم اجرای زمان اجرا و هم مرز سیستم فایل را بررسی کنید. وابستگی‌های npm ممکن است درون پروژه npm مدیریت‌شده Plugin بالاکشیده شوند، بنابراین آزمون‌ها باید ثابت کنند که آن پروژه اسکن/پاک‌سازی می‌شود، نه اینکه فرض کنند فقط درخت node_modules محلی بسته Plugin بررسی می‌شود.

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

عیب‌یابی شکست

با هویت مصنوع آغاز کنید:

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

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