​

Background Exec + أداة Process

​

أداة exec

• command (مطلوب)
• yieldMs (الافتراضي 10000): التحويل التلقائي إلى الخلفية بعد هذا التأخير
• background (منطقي): التشغيل في الخلفية فورًا
• timeout (بالثواني، الافتراضي 1800): إنهاء العملية بعد هذه المهلة
• elevated (منطقي): التشغيل خارج sandbox إذا كان الوضع المرتفع ممكّنًا/مسموحًا (gateway افتراضيًا، أو node عندما يكون هدف exec هو node)
• هل تحتاج إلى TTY حقيقي؟ اضبط pty: true.
• workdir وenv

• تعيد عمليات التشغيل الأمامية المخرجات مباشرة.
• عند تشغيلها في الخلفية (صراحةً أو بسبب المهلة)، تعيد الأداة status: "running" + sessionId وذيلًا قصيرًا.
• يتم الاحتفاظ بالمخرجات في الذاكرة حتى يتم استطلاع الجلسة أو مسحها.
• إذا كانت أداة process غير مسموح بها، يعمل exec بشكل متزامن ويتجاهل yieldMs/background.
• تتلقى أوامر exec التي تم إنشاؤها المتغير OPENCLAW_SHELL=exec لاستخدامه في قواعد shell/profile المعتمدة على السياق.
• بالنسبة إلى العمل طويل التشغيل الذي يبدأ الآن، ابدأه مرة واحدة واعتمد على تنبيه الإكمال التلقائي عند تمكينه وعندما يصدر الأمر مخرجات أو يفشل.
• إذا لم يكن تنبيه الإكمال التلقائي متاحًا، أو كنت تحتاج إلى تأكيد نجاح صامت لأمر انتهى بنجاح من دون مخرجات، فاستخدم process لتأكيد الاكتمال.
• لا تحاكِ التذكيرات أو المتابعات المؤجلة باستخدام حلقات sleep أو الاستطلاع المتكرر؛ استخدم cron للأعمال المستقبلية.

​

ربط العمليات الفرعية

• PI_BASH_YIELD_MS: مهلة yield الافتراضية (مللي ثانية)
• PI_BASH_MAX_OUTPUT_CHARS: الحد الأقصى للمخرجات في الذاكرة (أحرف)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: الحد الأقصى المعلق لـ stdout/stderr لكل تدفق (أحرف)
• PI_BASH_JOB_TTL_MS: مدة بقاء الجلسات المكتملة (مللي ثانية، ومقيدة بين 1m–3h)

• tools.exec.backgroundMs (الافتراضي 10000)
• tools.exec.timeoutSec (الافتراضي 1800)
• tools.exec.cleanupMs (الافتراضي 1800000)
• tools.exec.notifyOnExit (الافتراضي true): يضيف حدث نظام إلى الطابور + يطلب heartbeat عند خروج exec الذي يعمل في الخلفية.
• tools.exec.notifyOnExitEmptySuccess (الافتراضي false): عند ضبطه على true، يضيف أيضًا أحداث اكتمال لعمليات الخلفية الناجحة التي لم تنتج أي مخرجات.

​

أداة process

• list: الجلسات الجارية + المكتملة
• poll: سحب المخرجات الجديدة لجلسة ما (ويبلغ أيضًا عن حالة الخروج)
• log: قراءة المخرجات المجمعة (يدعم offset + limit)
• write: إرسال stdin ‏(data، مع eof اختياري)
• send-keys: إرسال رموز مفاتيح أو بايتات صريحة إلى جلسة مدعومة بـ PTY
• submit: إرسال Enter / carriage return إلى جلسة مدعومة بـ PTY
• paste: إرسال نص حرفي، مع إمكانية تغليفه بوضع اللصق المحاط
• kill: إنهاء جلسة خلفية
• clear: إزالة جلسة مكتملة من الذاكرة
• remove: الإنهاء إذا كانت قيد التشغيل، وإلا المسح إذا كانت مكتملة

• يتم عرض/الاحتفاظ في الذاكرة فقط بالجلسات التي تعمل في الخلفية.
• تُفقد الجلسات عند إعادة تشغيل العملية (لا يوجد حفظ على القرص).
• لا تُحفَظ سجلات الجلسة في سجل الدردشة إلا إذا شغّلت process poll/log وتم تسجيل نتيجة الأداة.
• يكون process ضمن نطاق كل وكيل؛ فهو لا يرى إلا الجلسات التي بدأها ذلك الوكيل.
• استخدم poll / log للحالة، والسجلات، وتأكيد النجاح الصامت، أو تأكيد الاكتمال عندما لا يكون تنبيه الإكمال التلقائي متاحًا.
• استخدم write / send-keys / submit / paste / kill عندما تحتاج إلى إدخال أو تدخل.
• يتضمن process list حقل name مشتقًا (فعل الأمر + الهدف) للفحص السريع.
• يستخدم process log القيمتين offset/limit على أساس الأسطر.
• عند حذف كل من offset وlimit، يعيد آخر 200 سطر ويتضمن تلميحًا للتصفح.
• عند توفير offset وحذف limit، يعيد من offset حتى النهاية (ولا يُقيد بـ 200).
• الاستطلاع مخصص للحالة عند الطلب، وليس لجدولة حلقات الانتظار. إذا كان العمل يجب أن يحدث لاحقًا، فاستخدم cron بدلًا من ذلك.

​

أمثلة

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }

{ "tool": "exec", "command": "npm run build", "background": true }

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }