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

# مقياس الإصلاح الذاتي (heal-benchmark)

> طريقة قابلة للتكرار لمعرفة ما إذا كان تغيير في الـ harness الخاص بالـ agent قد ساعد. تشغّل أربعة agents على 28 مهمة وتُبلغ عن معدل النجاح والضجيج والـ tokens واستدعاءات الأدوات لكل نسخة من الـ harness.

| الـ agent | ما يختبره |
| - | - |
| `support-desk` | انقطاع لدى شركة الشحن، واسترداد مبلغ ينقل أموالًا، وسياسة تحدّد المبلغ أو ترفض |
| `data-analyst` | أداة معطّلة، وملف مفقود، ومراجع غير مرتبة، وتحويل عملات، وبيانات ناقصة |
| `doc-qa` | خدمة غير مستقرة، ومستند محظور، ومستند قديم، وإجابة موزّعة على مستندين |
| `coding-agent` | أخطاء في مشروع JavaScript صغير: إصلاحات سطحية، وإصلاح مغرٍ يكسر اختبارًا آخر، وأعراف المشروع التي لا تذكرها المهمة، وحالات طرفية لا تفحصها إلا اختبارات مخفية |

كل عطل في الأدوات مزروع عمدًا، وكل فحص هو اختبار حتمي للإجابة
أو لاستدعاءات الأدوات التي جرت. يُقيَّم `coding-agent` بتشغيل اختبارات مخفية، ويفشل
الـ run إذا عدّل اختبارًا أو ملفًا لا تحتاجه المهمة. اعتبر هذه النتائج
مؤشرًا، لأن الـ agents الخاصة بك قد تتصرف بشكل مختلف.

يعدّل `coding-agent` نسخة من مشروعه في الذاكرة. تعمل اختباراته، بما فيها أي كود
كتبه النموذج، في مجلد مؤقت ببيئة فارغة، تحت
نموذج الصلاحيات في Node. يحجب ذلك الملفات خارج المجلد والعمليات
الفرعية (child processes). أما الوصول إلى الشبكة فلا يُحجَب إلا على Node 25 أو أحدث، لذا شغّل
الـ benchmarks الحية على Node 25 أو في بيئة معزولة خاصة بك.

## تشغيله

```bash theme={null}
npx tsx examples/heal-benchmark/index.ts                    # offline, shows the output format
OPENROUTER_API_KEY=... npx tsx examples/heal-benchmark/index.ts --repeats 4 --out runs.jsonl
```

تستخدم الـ runs الحية نماذج OpenRouter المجانية ما لم تمرّر `--model`. هذه الخيارات
تغيّر ما يُقاس:

| الخيار | الأثر |
| - | - |
| `--guard` | يضيف `createProgressGuard()` |
| `--instructions "..."` | يُلحِق نصًا بتعليمات كل agent |
| `--only <task>` | يشغّل مهمة واحدة |
| `--repeats <n>` | يشغّل كل مهمة `n` مرة لكل نموذج |
| `--gap-ms <n>` | ينتظر قبل كل استدعاء للنموذج، بسبب حدود المعدل (rate limits) |

## قراءة لوحة النتائج

* تنشأ نسخة جديدة من الـ harness من أي تغيير في التعليمات أو أسماء الأدوات أو
  الخطّافات.
* `noise` هو التفاوت في معدل النجاح بين التكرارات. التحسّن الأصغر من الضجيج
  ليس دليلًا على شيء.
* فشل المزوّد، مثل تجاوز حد المعدل، يُحسَب `excluded` ولا يُحسَب
  فشلًا أبدًا. وترفض النتائج أن تُدمَج إذا تغيّر مُدخل مهمة بين الـ runs.

## التحسين وإعادة التشغيل

يشغّل `improve.ts` الدالة `improveAgent` على حالات agent واحد. ويعيد `replay.ts` تشغيل الـ harnesses التي سجّلها.

| الخيار | الأثر |
| - | - |
| `--cache <dir>` | يخزّن كل run مُقيَّم حسب الـ harness والحالة والتكرار والنموذج والمحاولة، حتى تعيد إعادة التشغيل استخدامه. تُحفَظ runs النموذج الوهمي دون اتصال منفصلة عن الحية، ولا تعيد البوابة أبدًا استخدام run عُرض على المحرّرين |
| `--confirm-candidates` | يؤكّد harness كل محرّر، لا الاقتراح فقط، بعدد `--confirm` من الـ runs الجديدة. يتطلّب `--confirm` أكبر من 0 |
| `--first-attempt <n>` | يبدأ ترقيم المحاولات من `n`، لمتابعة تشغيل في يوم آخر |
| `--failure-names <real\|none\|shuffled>` | يُري المحرّرين الفحص الفاشل الحقيقي، أو لا شيء، أو فحص مهمة أخرى، لاختبار ما إذا كان الاسم نفسه يساعد |

## تجربة البوابة

يعيد `experiment.ts` تشغيل مخرجات المحرّرين المسجّلة عبر أربع بوابات (A: بلا بوابة، B: البوابة القديمة، C: البوابة الحالية، D: البوابة الحالية مع البديل الاحتياطي)، إضافةً إلى تعديل لا يغيّر شيئًا (N) وتراجع مزروع (P). ويقدّر `simulate.ts` المعدلات نفسها دون اتصال من معدلات النجاح لكل حالة.

لا يملك `experiment.ts` نموذجًا افتراضيًا، فمرّر `--model` و`--editor` في كل مرة. قبل الذراعين N وP، يتحقق من أن كل حالة `--holdout` تنجح 6/6 على الأساس، ويخرج بالكود 2 إذا لم تنجح إحداها. ولا يعيد تشغيل إلا الصفوف التي انتهت باقتراح أو أبقت الأساس. تشغيل الإثبات، بالترتيب:

```bash theme={null}
MODEL=stealth/crouton-alpha EDITOR=stealth/crouton-alpha S=$SCRATCH/m34
npx tsx examples/heal-benchmark/simulate.ts --trials 2000
npx tsx examples/heal-benchmark/experiment.ts --admit --model $MODEL --editor $EDITOR --holdout page-count --holdout dedupe-first --cache $S/cache
npx tsx examples/heal-benchmark/improve.ts --agent coding-agent --case add-months --holdout <admitted> --model $MODEL --editor $EDITOR --attempts 2 --first-attempt <n> --repeats 3 --confirm 6 --confirm-candidates --cache $S/cache --out $S/rows.jsonl
npx tsx examples/heal-benchmark/improve.ts --agent coding-agent --case <first admitted> --holdout <second admitted> --model $MODEL --editor $EDITOR --always-propose --attempts 5 --repeats 3 --confirm 6 --confirm-candidates --cache $S/cache --out $S/healthy.jsonl
npx tsx examples/heal-benchmark/replay.ts --in $S/rows.jsonl --model $MODEL --cache $S/cache --confirm 6 --out $S/truth.jsonl
npx tsx examples/heal-benchmark/experiment.ts --in $S/rows.jsonl --truth $S/truth.jsonl --healthy $S/healthy.jsonl --model $MODEL --editor $EDITOR --cache $S/cache --attempts 10 --holdout <admitted> --out $S/arms.jsonl
```

## اختباره

```bash theme={null}
npx vitest run examples/heal-benchmark
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.