---
name: ocr-transcription
description: >
  Orchestrates end-to-end OCR text extraction from PDF books and documents.
  Use this skill ALWAYS when the user requests text extraction, OCR, transcription,
  book processing, or document conversion from PDF files, even if they don't
  explicitly name this skill.
disable-model-invocation: true
---

# مهارة استخلاص النصوص وتنسيق الأجزاء (OCR Transcription Skill)

- **المرساة المفاهيمية (Leading Word)**: الـ **chunk** (جمعها **chunks**) هي الوحدة الأساسية للتقسيم والمعالجة (20 صفحة كحد أقصى).
- **المرجعيات التفصيلية**:
  - قواعد النسخ والأمانة العلمية وحظر المكتبات الخارجية: **[references/transcription_rules.md](references/transcription_rules.md)**
  - بروتوكولات الفشل والتعافي والتحقق الفردي: **[references/execution_rules.md](references/execution_rules.md)**

---

## ١. استراتيجية المعالجة وإدارة الوكلاء (Orchestration & Processing)

- **الوكيل الرئيسي**: يدير سير العمل الإجرائي، ويتحقق من صفحات الملف للتفريع، ويستخلص الملفات الصغيرة مباشرة، ويطلق الوكلاء الفرعيين للملفات الكبيرة ويجري دمجها.
- **تعدد الملفات**: عند وجود عدة ملفات PDF في مجلد المصدر، يستشير المستخدم تفاعلياً لتحديد طريقة المعالجة (ملف واحد أم بالتتابع).
- **حظر الاستخلاص الخارجي**: يُحظر استخدام أي أدوات خارجية أو مكتبات OCR؛ القراءة حصرية عبر أداة `view_file` للنموذج (انظر تفصيل الحظر في `transcription_rules.md`).
- **حجم الـ chunk الثابت**: 20 صفحة كحد أقصى لكل **chunk**.
- **المخرجات الافتراضية**: تُكتب مخرجات الدمج النهائي والتحويل إلى مجلدي `md/` و`word/` افتراضياً للحفاظ على نظافة جذر المشروع (ويتم إنشاؤهما تلقائياً).
- **حظر قراءة السكربتات المساعدة**: يُمنع على الوكيل قراءة الأكواد المصدرية الكاملة للسكربتات المساعدة (مثل `splitt_pdf.py` أو `convert_to_docx.py`)؛ فالمعاملات وتعليمات التشغيل موضحة بالكامل في هذه المهارة، ولا تجوز قراءتها إلا عند حدوث أخطاء برمجية أو استثناءات أثناء التشغيل تتطلب التنقيب (Debugging).


---

## ٢. بروتوكول التنفيذ التتابعي (Sequential Execution Pipeline)

### الخطوة الأولى: التحقق من عدد الصفحات والتفريع
1. يقرأ الوكيل الرئيسي عدد صفحات ملف الـ PDF أولاً بتشغيل السكربت بالمعامل `--info_only` (مع إمكانية تحديد الصفحات المخصصة عبر معامل `--pages` إن طلب المستخدم ذلك):
   ```bash
   # معالجة كاملة
   python scripts/splitt_pdf.py "pdf/input.pdf" --info_only

   # معالجة صفحات مخصصة
   python scripts/splitt_pdf.py "pdf/input.pdf" --pages "5,8,10-12" --info_only
   ```
2. **التفريع الإلزامي**:
   - **إذا كان إجمالي عدد الصفحات المحددة للمعالجة هو 20 صفحة أو أقل**: يسلك الوكيل **المسار السريع (Fast Track)** الموثق في القسم (٣).
   - **إذا كان إجمالي عدد الصفحات المحددة للمعالجة أكثر من 20 صفحة**: يسلك الوكيل **المسار القياسي المجزأ (Chunked Pipeline)** الموثق في القسم (٤).

---

## ٣. المسار السريع (Fast Track) - للملفات الصغيرة (<= 20 صفحة)

1. **التجهيز والاستخلاص**:
   - في حال تحديد صفحات مخصصة، يجب تشغيل سكربت التقسيم أولاً لتجهيز نطاقات الصفحات الخام في مجلد الأجزاء:
     ```bash
     python scripts/splitt_pdf.py "pdf/input.pdf" --pages "5,8,10-12"
     ```
     ثم يقوم الوكيل الرئيسي بقراءة صفحات أجزاء الـ PDF الناتجة في `output_parts/` باستخدام `view_file` (التي ستحتوي فقط على الصفحات المطلوبة ولكن بأرقامها الحقيقية).
   - في حال المعالجة الكاملة لكامل الملف (<= 20 صفحة)، يقرأ الوكيل الصفحات مباشرة من ملف الـ PDF الأصلي باستخدام `view_file`.
2. **الكتابة والتطبيق**: يكتب الوكيل النص المستخلص مباشرة في ملف Markdown نهائي داخل مجلد `md/` مع إلحاق لاحقة الصفحات الآمنة للملف المخصص (مثال: `md/Assignment 1_p5_8_10-12.md` أو `md/Assignment 1.md` للملف الكامل)، مع الالتزام التام بقواعد النسخ وفواصل الصفحات `--- Page [Number] ---` بالترقيم الأصلي الموثقة في `references/transcription_rules.md`.
3. **التحويل المباشر لـ Word**: فور الانتهاء، يشغل الوكيل سكربت التحويل لملف Word تلقائياً:
   ```bash
   python scripts/convert_to_docx.py "md/filename_p5_8_10-12.md" "word/filename_p5_8_10-12.docx"
   ```
   *ملاحظة للوكيل*: إذا فشل التحويل بسبب عدم وجود أداة `pandoc` وتعذر تثبيتها صامتاً، يجب عليك إبلاغ المستخدم فوراً بالخطأ وعرض أمر التثبيت اليدوي التالي: `winget install JohnMacFarlane.Pandoc`.


---

## ٤. المسار القياسي المجزأ (Chunked Pipeline) - للملفات الكبيرة (> 20 صفحة)

### الخطوة الأولى: التهيئة والتقسيم
1. تشغيل أداة التقسيم والتهيئة للملف النشط:
   ```bash
   python scripts/splitt_pdf.py "pdf/input.pdf"
   ```
2. قراءة ملف المتابعة `output_parts/progress.json` لمعرفة نطاق الـ **chunks** والصفحات المطلوبة.

### الخطوة الثانية: استخلاص الـ chunks
1. يحدد الوكيل الرئيسي الـ **chunks** ذات الحالة `"pending"` في ملف المتابعة، ويستبعد أي **chunk** له ملف مؤقت `output_parts/part_N_temp.md` متواجد على القرص تفادياً للتكرار.
2. يُطلق الوكلاء الفرعيون من نوع `"self"` بالتوازي (بحد أقصى 10 وكلاء في الدفعة الواحدة) لاستخلاص النصوص.
3. **معيار الإتمام**: التأكد من إتمام كافة الوكلاء الفرعيين لمهامهم وعودتهم بتقرير النجاح في المحادثة.

### الخطوة الثالثة: التحقق المؤجل (Deferred Validation)
1. بعد اكتمال عمل كافة الوكلاء الفرعيين وولادة الملفات المؤقتة، يُشغل الوكيل الرئيسي سكربت التحقق:
   ```bash
   python scripts/validate_chunk.py --all
   ```
2. يُحدّث السكربت حالة الـ **chunks** تلقائياً في `progress.json` إلى `"completed"` في حال النجاح مع توليد ملف المخرجات المعتمد، أو `"failed"` في حال الإخفاق.

### الخطوة الرابعة: التعافي من الأخطاء (Error Recovery)
- إذا فشل أي **chunk** في التحقق (حالة `"failed"`):
  1. الالتزام الصارم بـ **[references/execution_rules.md](references/execution_rules.md)**.
  2. حذف الملف المؤقت الفاشل وإعادة الاستخلاص والتحقق الفردي له قبل الانتقال للخطوة التالية.

### الخطوة الخامسة: الدمج والتدقيق والتحويل إلى Word
1. عند اكتمال كافة الأجزاء ووسمها بـ `"completed"`، يُشغل الوكيل الرئيسي سكربت الدمج:
   ```bash
   python scripts/merge_parts.py
   ```
2. إذا اجتاز المستند فحص التكرار (Duplication Check) بنجاح (علماً بأن الفحص يتم تخطيه تلقائياً وصامتاً في حال معالجة صفحات مخصصة)، يُتم السكربت تنظيف وحذف الملفات الوسيطة وملف المتابعة، ويُسلم المستند النهائي في مجلد `md/`.
3. تشغيل سكربت التحويل لملف Word تلقائياً:
   ```bash
   python scripts/convert_to_docx.py "md/filename_p5_8_10-12.md" "word/filename_p5_8_10-12.docx"
   ```
   *(يقوم السكربت بإنشاء مجلد المخرجات تلقائياً في حال إدراجه بالمسار).*
   *ملاحظة للوكيل*: إذا فشل التحويل بسبب عدم وجود أداة `pandoc` وتعذر تثبيتها صامتاً، يجب عليك إبلاغ المستخدم فوراً بالخطأ وعرض أمر التثبيت اليدوي التالي: `winget install JohnMacFarlane.Pandoc`.