الانتقال إلى المحتوى الرئيسي
عندما تعيد قاعدة جدار حماية حكم pending_approval، يُـعلَّق استدعاء أداة الوكيل بدلاً من إرساله — إنه الآن ينتظر إنساناً. هذه الصفحة للمراجِع: كيف توافق على تعليقات استدعاء أداة الوكيل (أو ترفضها) من وحدة التحكم، وماذا يُظهر لك الطابور، وكيف يمنع OrcaRouter مراجِعَين من الاصطدام على نفس القرار. إنها نصف الحل من الإنسان في الحلقة. لـ لماذا يُعلَّق استدعاء وكيف يعيد الوكيل المُعلَّق التقديم بعدها، انظر الأحكام و مرجع الموافقات الأعمق. للحل من نظامك الخاص بدلاً من وحدة التحكم، انظر webhooks الموافقة.

​
1. دورة حياة الاستدعاء المُعلَّق، من مقعد المراجِع

استدعاء مُعلَّق حلقة قصيرة خارج النطاق. مهمتك هي الخطوة الوسطى:
1

يُعلَّق الاستدعاء

تُحَل قاعدة إلى pending_approval. يعيد الترحيل HTTP 400 برمز firewall_approval_pending ومعرّف موافقة؛ لا يصل الاستدعاء إلى الأداة أبداً. يبدأ الوكيل في الاستطلاع على ذلك المعرّف.
2

تحلّه

تفتح طابور Approvals، تقرأ لماذا عُلِّق الاستدعاء، وتـوافق أو تـرفض — محور هذه الصفحة.
3

يمضي الوكيل (أو يتوقف)

عند الموافقة، يعيد الوكيل تقديم الاستدعاء الأصلي بترويسة X-OrcaRouter-Firewall-Approval أحادية الاستخدام وتدعه البوابة يمر تلك المرة الواحدة. عند الرفض، يبقى الاستدعاء محجوباً.
حل تعليق محكوم بـ Developer+ — نفس بوابة تغذية أحداث جدار الحماية. الأدوار الأدنى يمكنها قراءة سياسة جدار الحماية والإعدادات والأدوات المكتشفة، لكن أدوار Developer-فما-فوق فقط يمكنها سرد طابور الموافقة أو موافقة/رفض استدعاء أداة مُعلَّق. انظر الأدوار والنطاق.

​
2. اسرد الطابور المُعلَّق

تبويب Approvals يقرأ GET /api/workspace/firewall/approvals. بلا فلتر يعيد طابور pending، الأقدم أولاً — فالاستدعاء الأطول انتظاراً يجلس في الأعلى وتعمل على المتراكم بالترتيب. 
GET /api/workspace/firewall/approvals?state=pending
state هو الفلتر الوحيد المهم. تتطابق القيم مع دورة حياة الموافقة:
stateالموافقات المُعادة
pending (الافتراضي)مُعلَّقة، بانتظار قرار — طابور عملك.
approvedمُمرَّرة بالفعل.
rejectedمحجوبة بالفعل.
هذا مسار وحدة تحكم على جلستك — اضبطه وراجعه من لوحة المعلومات، وليس بمفتاح ترحيل sk-orca-…. مفاتيح الترحيل لاستدعاءات نموذج /v1/*؛ إدارة جدار الحماية تعمل تحت تسجيل دخول وحدة التحكم لديك.

​
3. اقرأ لماذا عُلِّق الاستدعاء

يحمل كل صف مدخلات القرار التي يحتاجها مراجِع — اسم الأداة (tool_name)، وبصمة وسائط (args_hash، تجزئة SHA-256 لوسائط الاستدعاء المعيارية — قيم الوسائط الخام لا تُخزَّن في الموافقة)، ومعرّف الطلب، وسطر أصل بلغة بسيطة يسمّي السياسة، والقاعدة، والعبارة التي أُطلقت:
السياسة المسمّاة التي تنتمي إليها القاعدة المطابقة، مُحَلّة ضمن نطاق مساحة العمل فلا يمكن أبداً لمعرّف قديم أن يُظهر اسم سياسة مستأجر آخر.
علامة القاعدة وواصف “لماذا” من سطر واحد — مثل command contains rm -rf، أو tool matches "http_fetch" لقاعدة glob فقط. هذا يُصيّر سطر “عُلِّق لأن…” في الطابور.
true عندما حُرِّرت القاعدة المطابقة عند أو بعد إنشاء هذه الموافقة. عندها تُكبَت العلامة والعبارة الحية (قد لا تعكسان ما علّق الاستدعاء فعلاً)، ويُظهر الطابور ملاحظة “القاعدة تغيّرت منذ ذلك الحين” بدلاً من أصل قديم. اسم الأداة والوسائط — مدخلات القرار الحقيقية — تُعرَض دائماً.
rule_changed إشارة صدق متعمّدة، وليست خطأ. إذا حرّر أحد قاعدة جدار الحماية بينما استدعاء جالس في الطابور، يفضّل OrcaRouter إخفاء سبب ربما-خاطئ على أن يُظهر لك أصلاً لم يعد يطابق. قرّر بناءً على اسم الأداة واسم السياسة (لا يزالان معروضين) في تلك الحالة.

​
4. وافق أو ارفض

الحل يرسل PATCH /api/workspace/firewall/approvals/:id بـ decision بقيمة approved أو rejected وreason اختياري. تفعل وحدة التحكم هذا لك عندما تنقر الزر؛ الشكل: 
PATCH /api/workspace/firewall/approvals/507f1f77bcf86cd799439011
Content-Type: application/json

{ "decision": "approved", "reason": "verified target host with the on-call" }
  • approved ← قد يمضي الاستدعاء المُعلَّق. إعادة تقديم الوكيل التالية، حاملةً ترويسة الموافقة أحادية الاستخدام، تُمرَّر مرة واحدة.
  • rejected ← يبقى الاستدعاء محجوباً. يرى الوكيل الرفض ويمكنه اختيار مسار آخر، أو سؤال المستخدم، أو التوقف.
decision يُتحقَّق منه مقابل المجموعة المغلقة {approved, rejected} — أي شيء آخر يُرفض. يُسجَّل reason مع القرار ويُكتَب إلى سجل تدقيق جدار الحماية جنباً إلى جنب مع الفاعل واسم الأداة ومعرّف الطلب.
كل حل يكتب صف تدقيق مساحة عمل يسمّي من قرّر، والقرار، والسبب. حلول وحدة التحكم تسجّل الفاعل البشري؛ حلول webhook تسجّل فاعلاً نظامياً. أصل الحل لا يُسقَط أبداً صامتاً.

​
5. أول-كاتب-يفوز: لا حل مزدوج

موافقة مُعلَّقة يمكن أن تُسبَق — مراجِعان في وحدة التحكم، أو نقرة وحدة تحكم و استدعاء webhook يصلان معاً. يحل OrcaRouter هذا بقاعدة أول-كاتب-يفوز واحدة:
  • القرار تحديث شرطي ذرّي يُطلق فقط بينما لا تزال الموافقة pending. أول كاتب يفوز ويطبّق القرار.
  • كل كاتب لاحق يرصد “محلولة بالفعل” ويُعامَل كـ عملية عديمة الأثر تكرارياً — يحصل على HTTP 200 بالوثيقة المحلولة بالفعل، وليس خطأً.
تخبرك الاستجابة بأي جانب كنت: 
{
  "resolved": false,
  "already_resolved": true,
  "approval": { "state": "approved", "decision": "approved", "...": "..." }
}
resolved: true يعني أن استدعاءك طبّق القرار؛ وalready_resolved: true يعني أن أحداً (أو webhook ما) وصل أولاً وأنت ترى نتيجته. في كلتا الحالتين يتصالح الطابور إلى حالة متسقة واحدة.
لأن الحل عديم الأثر تكرارياً، شبكة متقطعة أو نقرة مزدوجة لا يمكنها إفساد تعليق أو قلب قرار. أول موافقة/رفض هو الوحيد الذي يُحسَب؛ كل شيء بعده يقرأ النتيجة فحسب.

​
6. مرور ملموس عبر الطابور

مساحة عمل باستقلالية متوازنة تعلّق استدعاء shell.exec لوكيل لأن قاعدة طابقت command contains rm -rf. كمراجِع أنت:
  1. تفتح Approvals — shell.exec المُعلَّق يجلس في أعلى قائمة pending الأقدم-أولاً.
  2. تقرأ الصف: الأداة shell.exec، بصمة args_hash، معرّف الطلب، وسطر “عُلِّق لأن… command contains rm -rf” (مُصيَّر من عبارة القاعدة المطابقة). لا علامة rule_changed، فالأصل حالي.
  3. الهدف دليل مؤقت، فتـوافق بسبب.
  4. يعيد PATCH الخاص بك resolved: true؛ استطلاع الوكيل التالي يرى approved، يعيد التقديم بترويسته أحادية الاستخدام، ويعمل الأمر مرة واحدة بالضبط.
لو وافق زميل عليه قبل ثانية، لأعادت نقرتك already_resolved: true بقراره — لا ضرر، لا تشغيل مزدوج.

​
أين تذهب بعد ذلك

مرجع الموافقات

حلقة HITL الكاملة: التعليق، الاستطلاع، إعادة التقديم، والترويسة أحادية الاستخدام.

webhooks الموافقة

احلل التعليقات من نظامك الخاص باستدعاء موقَّع بـ HMAC.

الأحكام

أين يقع pending_approval بين أحكام جدار الحماية الستة.

سجل الأحداث

أكّد النتيجة اللاحقة لاستدعاء محلول في التغذية.
للمخاطر التي يُقصَد بهذه التعليقات اصطيادها، انظر استدعاءات الأدوات الخطرة و الوكالة المفرطة.