نموذج Next

# Sandbox SDK — `@next` (معاينة 1.0)

بيئات Linux معزولة على [Cloudflare Containers](https://developers.cloudflare.com/containers/index.md)، مدفوعة من Workers.

**فضل وثائق المعاينة والأنواع المثبتة `@next` على الذاكرة.** تتغير واجهات برمجة التطبيقات (APIs)؛ هذه المهارة هي بوابة وعقد وخريطة استرجاع—وليست دليلا كاملا.

نوصي ب **المشاريع الجديدة** على هذا الخط. التطبيقات التي لا تزال تستخدم الحزمة الافتراضية تستخدم **`sandbox-stable`**. قم بالترحيل فقط عند الطلب، عبر **`sandbox-migrate-to-next`**.

## 1. البوابة — تأكيد خط الحزمة

قبل كتابة الكود، افحص التطبيق:

| التحقق | يجب أن يتطابق | | ----- | ---------- | | تبعية npm | `@cloudflare/sandbox@next` (أو علامة معاينة أخرى) | | صورة الحاوية | نفس الخط (مثل `cloudflare/sandbox:next`، `next-python`) |

| إذا وجدت… | الإجراء | | ------------ | ------ | | `@cloudflare/sandbox` الافتراضي (بدون `@next`) | **توقف.** حمل **`sandbox-stable`**. لا تطبق واجهات برمجة التطبيقات لهذه المهارة. | | المستخدم يريد ترحيل stable → `@next` | **توقف.** حمل **`sandbox-migrate-to-next`**. | | **bridge** المنشور ذاتيا فقط | Bridge **ليس** على خط معاينة 1.0 بعد. أبق bridge على حزمة + صورة stable. [Bridge (stable)](https://developers.cloudflare.com/sandbox/sdk/bridge/index.md) |

لا تخلط أبدا حزمة Worker من نوع `@next` مع صورة حاوية stable (أو العكس).

تثبيت المهارات: [إعداد Agent](https://developers.cloudflare.com/agent-setup/index.md) · [cloudflare/skills](https://github.com/cloudflare/skills)

## 2. العقد — غير قابل للتفاوض

- `sandbox.exec(argv)` يأخذ قائمة **argv** ويحل عند **بدء** العملية. يعيد **مقبضا (handle)**، وليس نتيجة أمر مكتملة. - اجمع النتائج باستخدام طرق المقبض: `output()`، `logs()`، `waitForExit()`، `waitForPort()`، `waitForLog()`، `kill(signal?)`. - لا يوجد shell ضمني. تحتاج صيغة Shell إلى shell صريح، على سبيل المثال `["/bin/bash", "-lc", script]`. - كل إطلاق مستقل. `cd` / `export` في `exec` واحد غير مرئي ل `exec` التالي. مرر `cwd` و `env` لكل إطلاق، أو سكريبت shell واحد. - مقابض العمليات **لا تحتوي على stdin**. الاستخدام التفاعلي ← terminals (`createTerminal` + `connect`). - `timeout` الانتظار المحلي / `AbortSignal` يلغيان **الانتظار فقط**. لا يقتلان العملية. استخدم `kill` أو `timeout` البعيد ل `exec`. - `getProcess` / `listProcesses` / `getTerminal` / `listTerminals` **لا** تبدأ حاوية؛ تعيد `null` / `[]` عندما لا تكون هناك حاوية قيد التشغيل. - تنتمي معرفات العملية والطرفية إلى **الحاوية الحالية**، وليس إلى معرف sandbox إلى الأبد. للعمل الذي يجب أن يستمر بعد الاستبدال، قم بتخزين الوظيفة الكاملة (argv، cwd، env، حالة التطبيق)—وليس فقط معرفا. - التكوين غير السري فقط في `setEnvVars` / إطلاق `env`. تبقى بيانات الاعتماد الحية في Worker؛ استخدم معالجات الصادر عندما يستدعي sandbox واجهات برمجة التطبيقات الخارجية. - **لا** تخترع واجهات برمجة تطبيقات stable تمت إزالتها (`gitCheckout` على core، إكمال string-`exec`، تنفيذ الجلسة، `sandbox.terminal(request)`). - **لا** تستخدم حلقة إعادة محاولة واحدة لكل خطأ (انظر وثائق الأخطاء).

الشكل الأدنى:

```ts import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123"); const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]); const result = await process.output({ encoding: "utf8" }); // result.stdout, result.exitCode ```

وثائق API الخاصة بالمهام: [references/api-quick-ref.md](references/api-quick-ref.md)

فهرس الأمثلة (فرع `next`): [references/examples.md](references/examples.md)

## 3. الاسترجاع — افتح الوثيقة للمهمة

احضر الصفحة قبل التنفيذ. أنواع `@next` المثبتة تتفوق على التخمينات.

| تحتاج إلى… | افتح | | ------------ | ---- | | التوجيه / اختيار المعاينة | [نظرة عامة على معاينة 1.0](https://developers.cloudflare.com/sandbox/index.md) | | أول Worker، wrangler، Dockerfile | [ابدأ](https://developers.cloudflare.com/sandbox/index.md) | | `exec`، المقابض، الجاهزية، المتانة | [تنفيذ العملية](https://developers.cloudflare.com/sandbox/index.md) | | توقيعات Process API | [Process API](https://developers.cloudflare.com/sandbox/index.md) | | Sandbox ID مقابل الحاوية مقابل النوم/التدمير | [دورة الحياة](https://developers.cloudflare.com/sandbox/index.md) | | `cwd` / `env` / `setEnvVars` | [البيئة](https://developers.cloudflare.com/sandbox/index.md) | | PTY التفاعلي / terminal المتصفح | [Terminals](https://developers.cloudflare.com/sandbox/index.md) · [Terminals API](https://developers.cloudflare.com/sandbox/index.md) | | مفسر كود Python/JS | [Interpreter](https://developers.cloudflare.com/sandbox/index.md) · [Interpreter API](https://developers.cloudflare.com/sandbox/index.md) | | نموذج الإضافات | [Extensions](https://developers.cloudflare.com/sandbox/index.md) | | فئات الأخطاء والاسترداد | [Errors](https://developers.cloudflare.com/sandbox/index.md) · [Errors API](https://developers.cloudflare.com/sandbox/index.md) | | الأعطال الشائعة | [استكشاف الأخطاء وإصلاحها](https://developers.cloudflare.com/sandbox/index.md) | | مركز API | [مرجع API](https://developers.cloudflare