> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# التدقيقات — كشف تحسينات موجهة بالوكيل

> توثيق AgentEye Audits — كشف تحسينات موجهة بالوكيل.

التدقيقات عبارة عن مهام متكررة تستخرج من سجلات الوكيل الخاص بك **عبر الجلسات** للعثور على أشياء تستحق التحسين. بينما تراقب التنبيهات مقياساً واحداً تعرفه بالفعل في الوقت الفعلي تقريباً، يقوم التدقيق *بالتحقيق*: وفقاً لجدول زمني تحدده، يقوم بتنفيذ نقطة سياسة حتمية عبر النافذة، ثم يحرر **وكيل موثوقية موجه بالذكاء الاصطناعي** على جلساتك — يستعلم الوكيل عن البيانات بنفسه، ويقرأ النسخ المريبة، وعند الحاجة يقوم بتشغيل نصوص تحليل صغيرة، ثم يكتب **توصيات تحسين** مع الأدلة وراء كل منها.

استخدم التدقيقات للإجابة على "ما الذي يجب أن أصلحه أو أحسنه في الوكلاء الخاصين بي؟" — واستخدم التنبيهات ليتم إخطارك في اللحظة التي يتم فيها تجاوز حد معين. يرتبط كل تحسين بالجلسات والاستعلامات الدقيقة وراءه، وبنقرة واحدة يتم إنشاء تنبيه معبأ مسبقاً للتقاط التكرارات.

سطح لوحة المعلومات هو **`/<org-slug>/audits`** (الشريط الجانبي → *تحليل* → *التدقيقات*)، محمي بصلاحيات `audits:read` / `audits:write`.

***

## كيفية عمل التشغيل

لكل تشغيل طبقتان — حد أدنى حتمي وتحقيق موجه بالوكيل.

### 1. نقطة السياسة (حتمية)

قبل تشغيل أي نموذج، ينفذ التدقيق كتالوغ صغير من **فحوصات سياسة SQL** عبر النافذة: استعلامات إجمالية محدودة تضع علامة على الأنماط السيئة المعروفة وتبلغ عن *عدد* الأحداث / *أي* الجلسات المطابقة — لا تبلغ أبداً عن النص المطابق نفسه. يتضمن الكتالوغ:

* **تسريب السرية / بيانات الاعتماد** في حمولات الأحداث — مفاتيح وصول AWS، مفاتيح API `sk-…`، مفاتيح خاصة PEM، رموز JWT / Bearer، وتعيينات بيانات الاعتماد `KEY=…`.
* **علامات حقن الموجه** — "تجاهل الإرشادات السابقة"، "اكشف عن موجه النظام الخاص بك"، وما شابه.
* **معلومات شخصية قابلة للتحديد** — أرقام على شكل SSN (استكشافي).
* **رفض أذونات الأداة** و**حلقات استدعاء الأداة الجامحة**.

يتم الاحتفاظ بضربات السياسة كنتائج (نوع `policy`) و**تظهر دائماً** (لا تتم إزالتها أبداً بواسطة الحد الأقصى لكل تشغيل)، وتُسلّم إلى وكيل الذكاء الاصطناعي كخيوط بداية. لأن هذه الطبقة لا تحتاج إلى نموذج، فإن التدقيق لا يزال ينتج عن أهم إشارات الأمان الخاصة به حتى لو كان وكيل الذكاء الاصطناعي غير متاح.

### 2. التحقيق الموجه بالوكيل (الذكاء الاصطناعي)

ثم ينفذ التدقيق **وكيل موثوقية مستقل** (نفس خدمة Claude Agent SDK التي تشغل مساعد لوحة المعلومات، مع موجه خاص بالتدقيق). بالنظر إلى **نطاق** التدقيق (الوكلاء المختارون × البيئات) و**نافذة زمنية**، يقوم الوكيل بـ:

* تشغيل استعلامات SQL للقراءة فقط على جداول التحليلات الخاصة بك،
* قراءة حفنة من نسخ جلسة ممثلة،
* كتابة وتشغيل **نصوص Python قصيرة في برنامج sandbox مقفول داخل القرن** (بدون شبكة، بدون وصول نظام الملفات، بيانات سرية محظاة) للتحليل الذي لا يمكن لـ SQL التعبير عنه — تجميع الأخطاء، حساب التوزيعات، كنس الحمولات التي استرجعها بالفعل،
* وتسجيل كل **تحسين** موثق بشكل جيد يجده.

يعمل من خلال عدة خطوط تحقيق — تجميع الأخطاء، الانجراف مقابل خط الأساس، فشل الهدف في النسخ، سوء استخدام الأداة، مقايضات الجودة/التكلفة، وفجوات التغطية — عند **حساسية** التدقيق (منخفضة / متوسطة / عالية). يجب أن يستشهد كل تحسين **بالأدلة**: معرفات الجلسة التي فحصها الوكيل بالفعل و/أو SQL الذي قام بتشغيله. يتحقق الخادم من أن الجلسات المستشهد بها موجودة و**يتخلص من أي تحسين بدون دليل باقٍ**، لذا يحقق الوكيل لكن لا يبتكر أبداً.

يحمل كل تحسين:

* **توصية** (التغيير الملموس المراد إجراؤه — تعديل موجه، إصلاح مخطط أداة، سياسة إعادة محاولة، حاجز، تغطية تقييم أكثر)،
* **تأثير متوقع** و**تقدير جهد** (منخفض / متوسط / عالي)،
* **حجم** — `big` (يجب إخطار المشغل)، `medium` (ينتمي إلى تقرير التشغيل)، أو `small` (سياق لوحة المعلومات)،
* **بصمة** مستقرة (من فئة المشكلة + النطاق، *ليس* جلسات هذا التشغيل) بحيث يتم تتبع نفس المشكلة من تشغيل إلى تشغيل حتى عندما تتغير الأدلة،
* وعند الحاجة، حيث يمكن لمراقب حتمي بسيط أن يلتقط التكرار، **تنبيه مقترح** يمكنك إنشاؤه بنقرة واحدة.

> **طبقة الذكاء الاصطناعي اختيارية لكن موصى بها.** إذا لم يتم تكوين وكيل ذكاء اصطناعي لخط أنابيب التدقيق، فإن التشغيلات لا تزال تُنفذ، وتحتفظ بنتائج السياسة، وتُبلغ بصراحة عن "التحليل غير متاح" للطبقة الموجهة بالوكيل بدلاً من السكوت.

### أوضاع الفشل

تصنف التحسينات إلى **كتالوغ وضع فشل** دائم في المؤسسة (أو تقترح وضعاً جديداً). تعطي الأوضاع الأنماط هوية مستقرة عبر التشغيلات وتتبع التكرار على الأفق الطويل.

## دورة حياة الفرز

على صفحة البحث (`/audits/<id>/findings/<finding-id>`):

| الإجراء                | التأثير                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **acknowledge**        | يحافظ على ظهور البحث لكن يخفض أولويته إلى النصف.                                                                                            |
| **resolve**            | يضع علامة عليه كمصحح. إذا عادت النمط فعلاً لاحقاً، فإنه **يُعاد فتحه كـ** جديد — لذا يكون الانحدار بصوت مرتفع، وليس مطوياً صامتاً في السجل. |
| **mute** / **dismiss** | قمع دائم: يتم تذكر بصمة النمط ولا تظهر أبداً مجدداً، حتى عبر التشغيلات. استخدم mute لـ "معروف، مقبول"؛ dismiss لـ "غير مفيد".               |
| **reopen**             | يمسح القمع / الحل ويصنف النمط مرة أخرى.                                                                                                     |

يتم التحكم في ضوضاء الإشارة المنخفضة لكل تدقيق بحد أقصى من البحث لكل تشغيل (`top_k`) على التحسينات الموجهة بالوكيل. تتجاوز نتائج السياسة الحد الأقصى (فهي ذات صلة بالأمان وتُظهر دائماً). أي شيء يتم قطعه بواسطة الحد الأقصى يتم عده في إحصائيات التشغيل — لا يتم إسقاط أي شيء صامتاً.

## الجدولة

* **التكرار** (`schedule_interval_secs`): بالساعة إلى أسبوعي؛ **يومي هو الافتراضي**. التدقيقات أكثر خشونة بقصد من التنبيهات — يفحص التحقيق الموجه بالوكيل النوافذ الكاملة ويعمل لدقائق.
* **النافذة**: إما نظرة خلفية دوارة ثابتة (مثل "كل تشغيل يفحص آخر 7 أيام") أو **منذ آخر تشغيل** (الافتراضي) — يختار كل تشغيل من حيث انتهى التشغيل الناجح السابق، مع تداخل صغير حتى لا تُفتقد أحداث الحدود.
* يتم جدولة التشغيل التالي فترة زمنية كاملة بعد انتهاء التشغيل السابق **يكتمل**، لذا فإن التشغيل البطيء لن يكدس أبداً تشغيل ثانٍ متزامن من نفس التدقيق.
* **تشغيل الآن** على صفحة التدقيق يجعله مستحقاً على الفور.

## اختيار النموذج

عند إنشاء تدقيق، يمكنك اختيار النموذج الذي يستخدمه التحقيق، من **قائمة النماذج التي قام المشغل بتكوينها** لخدمة الوكيل. مع تكوين نموذج واحد، يُظهر المنتقي اسمه كعنوان; مع عدة، تختار. عدم تعيينه يستخدم الافتراضي المكون.

## الإخطارات

عندما يظهر التشغيل **نتائج جديدة**، يخطر التدقيق قنوات المؤسسة المكونة — نفس بوابة `alerts.enabled_channels` والإعدادات التي يستخدمها خط أنابيب التنبيهات:

* **Slack** — ملخص للعناصر الجديدة الهامة (`big`) مع رابط عميق.
* **البريد الإلكتروني** — **تقرير تدقيق** مصمم يسرد التحسينات الجديدة (أعلى خطورة، توصيات لكل عنصر، رابط عميق)، مرسل عندما يكون لديه التدقيق قناة **بريد إلكتروني** مرفقة وهناك نتيجة واحدة على الأقل جديدة.

لا تعيد الإخطار للنتائج المتكررة المعروفة.

## مرجع التكوين

يتم إدارة تعريفات التدقيق في لوحة المعلومات (`/audits/new`) أو عبر واجهة برمجية التطبيقات. تتضمن الإعدادات لكل تدقيق جدول التكرار والنافذة والنطاق (`{"environments": [...], "agent_ids": [...]}`)، والحساسية (`low` / `medium` / `high`)، وقنوات الإخطار، وحد البحث لكل تشغيل (`top_k`)، والنموذج (عبر `llm_budget.model`). يتم توثيق إعدادات الخادم على مستوى المشغل (المهل الزمنية، sandbox، URL خدمة الوكيل) في [deployment.md](/ar/agenteye/deployment).

## واجهة برمجية التطبيقات

جميع نقاط النهاية محدودة بالمؤسسة وتتبع المصادقة القياسية للمفتاح الحامل (انظر [api-keys.md](/ar/agenteye/api-keys)).

| نقطة النهاية                         | الصلاحية                       | الغرض                                                                                   |
| ------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------- |
| `GET /audits` · `POST /audits`       | `audits:read` / `audits:write` | قائمة / إنشاء تعريفات التدقيق.                                                          |
| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write           | فحص، تعديل، حذف تدقيق.                                                                  |
| `POST /audits/:id/run`               | `audits:write`                 | اجعل التدقيق مستحقاً على الفور.                                                         |
| `GET /audits/:id/runs`               | `audits:read`                  | سجل التشغيل (النافذة، الحالة، الإحصائيات، عدد البحث).                                   |
| `GET /audits/findings`               | `audits:read`                  | البحث على مستوى المؤسسة، قابل للتصفية حسب `audit_id`، `status`؛ مرتب حسب الأولوية.      |
| `GET /audits/findings/:fid`          | `audits:read`                  | تفاصيل البحث الكاملة (توصية، أدلة، أولوية).                                             |
| `POST /audits/findings/:fid/status`  | `audits:write`                 | الفرز: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. |

لـ "تم تشغيل التدقيق لكن لم يجد شيئاً"، "sandbox الكود معطل"، و"بريد التدقيق الإلكتروني لم يتم تسليمه"، انظر [troubleshooting.md](/ar/agenteye/troubleshooting#audits).