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

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

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

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

تست‌های به‌روزرسانی و Plugin از این قراردادها محافظت می‌کنند:

• یک tarball بسته کامل است، dist/postinstall-inventory.json معتبر دارد، و به فایل‌های بازشده‌ی repo وابسته نیست.
• کاربر می‌تواند از یک بسته‌ی منتشرشده‌ی قدیمی‌تر به بسته‌ی candidate منتقل شود بدون اینکه config، agentها، sessionها، workspaceها، allowlistهای Plugin، یا config کانال را از دست بدهد.
• openclaw doctor --fix --non-interactive مالک مسیرهای پاک‌سازی و ترمیم legacy است. startup نباید migrationهای compatibility پنهان برای وضعیت کهنه‌ی Plugin ایجاد کند.
• نصب Plugin از دایرکتوری‌های محلی، repoهای git، بسته‌های npm، و مسیر registry ClawHub کار می‌کند.
• وابستگی‌های npm مربوط به Plugin در یک پروژه‌ی npm مدیریت‌شده برای هر Plugin نصب می‌شوند، پیش از trust اسکن می‌شوند، و هنگام uninstall از طریق npm حذف می‌شوند تا وابستگی‌های hoist‌شده باقی نمانند.
• به‌روزرسانی Plugin وقتی چیزی تغییر نکرده پایدار است: رکوردهای نصب، منبع resolve‌شده، چیدمان وابستگی نصب‌شده، و وضعیت enabled دست‌نخورده می‌مانند.

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

از محدوده‌ی باریک شروع کنید:

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

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

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

پیش از آنکه هر lane Docker بسته‌ای یک tarball را مصرف کند، artifact بسته را اثبات کنید:

pnpm release:check

release:check بررسی‌های drift مربوط به config/docs/API را اجرا می‌کند، inventory توزیع بسته را می‌نویسد، npm pack --dry-run را اجرا می‌کند، فایل‌های بسته‌بندی‌شده‌ی ممنوع را رد می‌کند، tarball را در یک prefix موقت نصب می‌کند، postinstall را اجرا می‌کند، و entrypointهای کانال bundled را smoke می‌کند.

laneهای Docker

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

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

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

laneهای مهم:

• test:docker:plugins smoke نصب Plugin، نصب از پوشه‌ی محلی، رفتار skip در به‌روزرسانی پوشه‌ی محلی، پوشه‌های محلی با وابستگی‌های از پیش نصب‌شده، نصب بسته‌های file:، نصب‌های git با اجرای CLI، به‌روزرسانی‌های moving-ref در git، نصب‌های registry npm با وابستگی‌های transitive hoist‌شده، no-opهای به‌روزرسانی npm، رد metadata معیوب بسته‌ی npm، نصب fixture محلی ClawHub و no-opهای به‌روزرسانی، رفتار به‌روزرسانی marketplace، و فعال‌سازی/inspect بسته‌ی Claude را اعتبارسنجی می‌کند. برای hermetic/offline نگه‌داشتن بلوک ClawHub، OPENCLAW_PLUGINS_E2E_CLAWHUB=0 را تنظیم کنید.
• test:docker:plugin-lifecycle-matrix بسته‌ی candidate را در یک container خالی نصب می‌کند، یک Plugin npm را از مسیرهای install، inspect، disable، enable، upgrade صریح، downgrade صریح، و uninstall پس از حذف کد Plugin عبور می‌دهد. برای هر phase، معیارهای RSS و CPU را log می‌کند.
• test:docker:plugin-update اعتبارسنجی می‌کند که یک Plugin نصب‌شده‌ی بدون تغییر هنگام openclaw plugins update دوباره نصب نشود یا metadata نصب را از دست ندهد.
• test:docker:upgrade-survivor tarball candidate را روی یک fixture کاربر قدیمی آلوده نصب می‌کند، به‌روزرسانی بسته همراه با doctor غیرتعاملی را اجرا می‌کند، سپس یک Gateway loopback را شروع می‌کند و حفظ وضعیت را بررسی می‌کند.
• test:docker:published-upgrade-survivor ابتدا یک baseline منتشرشده را نصب می‌کند، آن را از طریق recipe پخته‌شده‌ی openclaw config set پیکربندی می‌کند، به tarball candidate به‌روزرسانی می‌کند، doctor را اجرا می‌کند، پاک‌سازی legacy را بررسی می‌کند، Gateway را شروع می‌کند، و /healthz، /readyz، و وضعیت RPC را probe می‌کند.
• test:docker:update-restart-auth بسته‌ی candidate را نصب می‌کند، یک Gateway مدیریت‌شده با token-auth را شروع می‌کند، env مربوط به auth gateway caller را برای openclaw update --yes --json unset می‌کند، و الزام می‌کند فرمان به‌روزرسانی candidate پیش از probeهای معمول Gateway را restart کند.
• test:docker:update-migration lane به‌روزرسانی منتشرشده با پاک‌سازی سنگین است. از وضعیت کاربر پیکربندی‌شده به سبک Discord/Telegram شروع می‌کند، doctor baseline را اجرا می‌کند تا وابستگی‌های Plugin پیکربندی‌شده فرصت materialize شدن داشته باشند، debris وابستگی legacy Plugin را برای یک Plugin بسته‌بندی‌شده‌ی پیکربندی‌شده seed می‌کند، به tarball candidate به‌روزرسانی می‌کند، و post-update doctor را ملزم می‌کند rootهای legacy وابستگی را حذف کند.

variantهای مفید published-upgrade survivor:

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، feishu-channel، bootstrap-persona، plugin-deps-cleanup، configured-plugin-installs، stale-source-plugin-shadow، tilde-log-path، و versioned-runtime-deps. در اجراهای تجمیعی، OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues به همه‌ی سناریوهای شکل‌گرفته از issueهای گزارش‌شده گسترش می‌یابد، از جمله migration نصب Plugin پیکربندی‌شده.

migration کامل به‌روزرسانی عمدا از Full Release CI جدا است. وقتی پرسش release این است که «آیا هر release پایدار منتشرشده از 2026.4.23 به بعد می‌تواند به این candidate به‌روزرسانی شود و debris وابستگی Plugin را پاک کند؟»، از workflow دستی 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

Package Acceptance

Package Acceptance گیت native بسته در GitHub است. یک بسته‌ی candidate را به یک tarball package-under-test resolve می‌کند، version و SHA-256 را ثبت می‌کند، سپس laneهای Docker E2E قابل استفاده‌ی مجدد را علیه همان tarball دقیق اجرا می‌کند. ref harness workflow از ref منبع بسته جدا است، بنابراین منطق تست فعلی می‌تواند releaseهای trusted قدیمی‌تر را اعتبارسنجی کند.

منابع candidate:

• source=npm: openclaw@beta، openclaw@latest، یا یک version دقیق منتشرشده را اعتبارسنجی کنید.
• source=ref: یک branch، tag، یا commit trusted را با harness فعلی انتخاب‌شده pack کنید.
• source=url: یک tarball عمومی HTTPS را با package_sha256 الزامی اعتبارسنجی کنید. این مسیر credentialهای URL، portهای HTTPS غیرپیش‌فرض، hostnameها یا نتایج DNS/IP خصوصی/داخلی، فضای IP با کاربری ویژه، و redirectهای ناامن را رد می‌کند.
• source=trusted-url: یک tarball HTTPS را با package_sha256 و trusted_source_id الزامی علیه policy متعلق به maintainer در .github/package-trusted-sources.json اعتبارسنجی کنید. برای mirrorهای enterprise/private به‌جای ضعیف‌کردن source=url با یک switch سطح ورودی allow-private، از این استفاده کنید. Bearer auth، وقتی توسط policy پیکربندی شده باشد، از secret ثابت OPENCLAW_TRUSTED_PACKAGE_TOKEN استفاده می‌کند.
• source=artifact: از tarball بارگذاری‌شده توسط یک اجرای دیگر Actions دوباره استفاده کنید.

Full Release Validation به‌صورت پیش‌فرض از source=artifact استفاده می‌کند، که از SHA release resolve‌شده ساخته شده است. برای اثبات پس از انتشار، package_acceptance_package_spec=openclaw@YYYY.M.PATCH را پاس دهید تا همان ماتریس upgrade به‌جای آن بسته‌ی npm ship‌شده را هدف بگیرد.

بررسی‌های release، Package Acceptance را با مجموعه‌ی package/update/restart/plugin فراخوانی می‌کنند:

doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update

وقتی release soak فعال باشد، این‌ها را هم پاس می‌دهند:

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

این کار migration بسته، switching کانال به‌روزرسانی، تحمل Plugin مدیریت‌شده‌ی خراب، پاک‌سازی وابستگی کهنه‌ی Plugin، پوشش Plugin آفلاین، رفتار به‌روزرسانی Plugin، و QA بسته‌ی Telegram را روی همان artifact resolve‌شده نگه می‌دارد بدون اینکه گیت پیش‌فرض بسته‌ی release را مجبور کند همه‌ی releaseهای منتشرشده را طی کند.

last-stable-4 به چهار release پایدار آخر OpenClaw که در npm منتشر شده‌اند resolve می‌شود. release package acceptance مقدار 2026.4.23 را به‌عنوان نخستین مرز compatibility به‌روزرسانی Plugin، 2026.5.2 را به‌عنوان مرز churn معماری Plugin، و 2026.4.15 را به‌عنوان یک baseline قدیمی‌تر به‌روزرسانی منتشرشده‌ی 2026.4.1x pin می‌کند؛ resolver pinهایی را که از قبل در چهار مورد آخر هستند dedupe می‌کند. برای پوشش exhaustive migration به‌روزرسانی منتشرشده، به‌جای Full Release CI از all-since-2026.4.23 در workflow جداگانه‌ی Update Migration استفاده کنید. وقتی anchor قدیمی پیش از تاریخ را هم می‌خواهید، release-history همچنان برای نمونه‌گیری دستی گسترده‌تر در دسترس است.

وقتی چند baseline published-upgrade survivor انتخاب شود، workflow قابل استفاده‌ی مجدد Docker هر baseline را به job هدفمند runner خودش shard می‌کند. هر baseline shard همچنان مجموعه سناریوی انتخاب‌شده را اجرا می‌کند، اما logها و artifactها per-baseline می‌مانند و زمان wall به‌جای یک job serial بزرگ با کندترین shard محدود می‌شود.

هنگام اعتبارسنجی candidate پیش از release، یک profile بسته را دستی اجرا کنید:

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

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

پیش‌فرض release

برای release candidateها، stack اثبات پیش‌فرض چنین است:

1. pnpm check:changed و pnpm test:changed برای regressionهای سطح source.
2. pnpm release:check برای integrity artifact بسته.
3. profile package مربوط به Package Acceptance یا laneهای package سفارشی release-check برای قراردادهای install/update/restart/plugin.
4. بررسی‌های release بین سیستم‌عامل‌ها برای installer، onboarding، و رفتار platform وابسته به OS.
5. مجموعه‌تست‌های زنده فقط وقتی surface تغییرکرده رفتار provider یا hosted-service را لمس می‌کند.

روی ماشین‌های maintainer، gateهای گسترده و اثبات product مربوط به Docker/package باید در Testbox اجرا شوند مگر اینکه صراحتا اثبات محلی انجام شود.

compatibility legacy

leniency مربوط به compatibility باریک و زمان‌دار است:

• بسته‌ها تا 2026.4.25، شامل 2026.4.25-beta.*، ممکن است gapهای metadata بسته که قبلا ship شده‌اند را در Package Acceptance تحمل کنند.
• بسته‌ی منتشرشده‌ی 2026.4.26 ممکن است برای فایل‌های stamp مربوط به metadata build محلی که قبلا ship شده‌اند warn کند.
• بسته‌های بعدی باید قراردادهای مدرن را رعایت کنند. همان gapها به‌جای warning یا skipping شکست می‌خورند.

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

افزودن پوشش

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

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

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

تریاژ شکست

با هویت artifact شروع کنید:

• خلاصه resolve_package در Package Acceptance: منبع، نسخه، SHA-256 و نام artifact.
• artifactهای Docker: .artifacts/docker-tests/**/summary.json، failures.json، لاگ‌های مسیر و فرمان‌های اجرای مجدد.
• خلاصه upgrade survivor: .artifacts/upgrade-survivor/summary.json، شامل نسخه baseline، نسخه candidate، سناریو، زمان‌بندی‌های phase و گام‌های recipe.

اجرای مجدد همان مسیر دقیقِ شکست‌خورده با همان artifact بسته را به اجرای مجدد کل چتر انتشار ترجیح دهید.