الأدلة

سطر الأوامر: xipdf-cli

أداة xipdf-cli هي XiKey PDF من غير نافذة. تقرأ ملفات PDF وترسم صفحاتها صورا وتبحث فيها وتعدّلها وتقسّمها وتفحصها وتتعرف على نصوصها الممسوحة ضوئيا، من الطرفية أو من نص برمجي أو على خادم أو ضمن مهمة تكامل مستمر، بالمحرك نفسه الذي يعمل به التطبيق. لا تفتح أي نافذة، ولا تحتاج إلى شاشة، ولا ترسل شيئا إلى الإنترنت.

نُفّذ كل مثال في هذه الصفحة فعلا على Windows x64 بالإصدار الحالي من XiKey PDF 0.8.0، على ملفات تجريبية خيالية أعدّتها XiKey لهذا الدليل: تقرير سنوي عربي لمركز أبحاث النخيل والتمور (annual-report-ar.pdf، ست صفحات فيها رسوم بيانية)، ونسخة ممسوحة من صفحة منه (annual-report-ar-scanned.pdf)، وإعلان مكتبة ممسوح ضوئيا (ar-scanned.pdf)، وكتيّب ثنائي اللغة (brochure-bilingual.pdf)، وفاتورة ضريبية بالعربية والإنجليزية (invoice-ar.pdf). ونعرض المخرجات كما طُبعت حرفيا، مع اختصار الطويل منها بعلامة «…». وقد تُظهر رسائل المساعدة والأخطاء في الإصدار 0.8.0 r1 اسما مختلفا للبرنامج، أما الأوامر والخيارات فهي نفسها.

متى تستخدمها

التعرف الضوئي على مجموعات من المسوحات العربية: حوّل مجلدا كاملا من الخطابات أو الفواتير أو صفحات الأرشيف الممسوحة إلى ملفات PDF قابلة للبحث، ودَعْ ذلك يجري ليلا.
استخراج النص للبحث والفهرسة: اسحب نص كل ملف PDF إلى ملفات .txt لمحرك بحث أو قاعدة بيانات أو سلسلة معالجة بالذكاء الاصطناعي.
الخوادم والنصوص البرمجية: قسّم المستندات وادمجها واستخرج صفحاتها ودوّرها وغيّر عناوينها ضمن برنامج آخر.
فحوص البناء والإصدار: أوقف عملية البناء إذا تعذّر فتح ملف PDF أو رسمه، أو إذا كان «الحجب» مجرد مستطيل أسود فوق نص ما زال موجودا تحته.
الأتمتة ووكلاء الذكاء الاصطناعي: استدعِ أيا من أدوات الأتمتة في التطبيق (run)، أو نفّذ نصا من خطوات JSON (run --script)، أو قدّم الأدوات لمساعد ذكي عبر بروتوكول MCP (mcp)، أو تحكّم في نافذة تطبيق مفتوحة (ui).

مكانها بعد التثبيت

النظام	الحزمة	مكان `xipdf-cli`
Windows x64	مثبّت MSI (وهو ما يثبّته XiKey Launcher)	`C:\Program Files\XiKey PDF\xipdf-cli.exe` بجوار `XiKeyPDF.exe`
Windows x64	الملف المحمول `XiKey-PDF-<version>-windows-x64-portable.zip`	في المجلد بعد فك الضغط، بجوار `XiKeyPDF.exe`
macOS	ملف مستقل `XiKey-PDF-cli-<version>-macos-<arch>.zip`	`xipdf-cli` في أعلى المجلد بعد فك الضغط
Linux	حزمة DEB أو RPM	`/usr/bin/xipdf-cli`
Linux	`XiKey-PDF-cli-<version>-linux-<arch>.tar.gz`	`xipdf-cli` في أعلى المجلد بعد فك الضغط
Linux	AppImage	داخل الصورة في `usr/bin/xipdf-cli`، أما تشغيل ملف AppImage نفسه فيفتح التطبيق

ما المنشور اليوم؟ تحمل قناة beta على download.xikey.com الإصدار XiKey PDF 0.8.0 r1 في صورة مثبّت MSI لنظام Windows x64، وملفّي DMG لنظام macOS بمعماريتي x64 وarm64، وملف AppImage لنظام Linux x64. أما الملف المحمول لنظام Windows وحزمتا DEB وRPM وأرشيفا سطر الأوامر المستقلان فتنتجها وصفة الإصدار لكنها لم تُنشر على القناة بعد. ولا تتضمن حزمة التطبيق في ملف DMG أداة سطر الأوامر؛ فهي على macOS في أرشيف سطر الأوامر وحده.

لا يضيف مثبّت Windows مجلده إلى متغير PATH. استدعِ الأداة بمسارها الكامل، أو أضف المجلد إلى الجلسة الحالية:

& "C:\Program Files\XiKey PDF\xipdf-cli.exe" --version
$env:PATH = "C:\Program Files\XiKey PDF;$env:PATH"    # this PowerShell session only
xipdf-cli --version

سلوك مشترك بين جميع الأوامر

رموز الخروج. الرمز 0 يعني النجاح، و1 يعني الإخفاق، ولا رموز غيرهما. وبعض الأوامر يخفق عمدا لتتصرف النصوص البرمجية بناء على ذلك: يخرج audit بالرمز 1 إذا وجد حجبا زائفا، ويخرج batch بالرمز 1 إذا أخفق أي ملف، ويخرج text بالرمز 1 إذا تعذّرت قراءة أي صفحة (بعد أن يطبع الصفحات المقروءة). والاستثناء هو check: فبعد أن يكتمل تشغيله يخرج بالرمز 0 حتى لو أخفقت بعض الملفات، لذا اقرأ تقريره بصيغة JSON (انظر وصفة التكامل المستمر أدناه).
الأخطاء تُكتب في مجرى الخطأ القياسي سطرا واحدا يبدأ باسم البرنامج، مثل xipdf-cli: the password is incorrect. ولا يحمل المخرج القياسي إلا النتائج، فيمكن تحويله إلى ملف أو تحليله بأمان.
صيغ المخرجات. تطبع الأوامر info وtools وrun وbatch وui بيانات JSON منسّقة، ويطبع ocr وaudit سطرا واحدا من JSON، ويطبع text نصا عاديا بترميز UTF-8، ويطبع split أسماء الملفات التي كتبها سطرا لكل ملف. ولا تطبع الأوامر render وedit وcombine وextract شيئا عند النجاح (يكتب render تقريره في مجرى الخطأ). وإغلاق المخرج مبكرا، كما في xipdf-cli tools | head -1، ينتهي بالرمز 0 أيضا.
تُفحص الخيارات قبل قراءة أي ملف. فالخيار المكتوب خطأً يُرفض فورا ولا يُتجاهل: xipdf-cli info samples/invoice-ar.pdf --pasword x تعطي xipdf-cli: info: unknown option --pasword.
ترقيم الصفحات يبدأ من 1. وتُكتب القوائم مفصولة بفواصل (1,3,5)، أما النطاقات مثل 2-4 فتُرفض برسالة bad page number "2-4".
كلمات المرور. تقبل الأوامر info وtext وrender وocr وedit وextract وsplit وaudit الخيار --password PW (كلمة مرور الفتح، أو كلمة مرور المالك حين تكون الأذونات هي المعنية). أما combine فليس له هذا الخيار. وانتبه إلى أن كلمة المرور المكتوبة في سطر الأوامر قد تبقى في سجل الطرفية وقوائم العمليات؛ ففي النصوص البرمجية اقرأها من متغير محمي.
الملفات الموجودة. تكتب الأوامر render وedit وcombine وextract وsplit فوق ملف الإخراج إن وُجد. ويرفض ocr ذلك (ocr: output already exists; choose a new file). ولا يستبدل batch أي ملف أبدا، بل يضيف رقما إلى الاسم.
المساعدة. يطبع xipdf-cli --help (وكذلك -h وhelp وxipdf-cli <command> --help) طريقة الاستخدام كاملة ويخرج بالرمز 0. أما تشغيل xipdf-cli دون أمر فيطبع طريقة الاستخدام بوصفها خطأ ويخرج بالرمز 1.

الأوامر

الأمر info: ماذا يحوي المستند

xipdf-cli info <file.pdf> [--password PW]

يطبع ملخصا بصيغة JSON: إصدار PDF، وحجم الملف، وعدد الصفحات، وأبعاد الصفحة الأولى بالنقاط، والعنوان والمؤلف والبرنامج المنتج والمنشئ، وهل الملف مشفر أو موسوم، ووجود JavaScript ونماذج XFA، وأعداد الإشارات المرجعية والتعليقات وحقول النماذج والروابط والطبقات والمرفقات، إضافة إلى تسميات الصفحات الثماني الأولى وأي تحذيرات.

$ xipdf-cli info samples/annual-report-ar.pdf
{
  "annotations": 0,
  "attachments": 0,
  "author": null,
  "bookmarks": 0,
  "creator": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) … Edg/155.0.0.0",
  "encrypted": false,
  "fields": 0,
  "file": "samples/annual-report-ar.pdf",
  "file_size": 1658510,
  "first_page_pt": [
    594.9599609375,
    841.9199829101562
  ],
  "javascript": false,
  "layers": 0,
  "links": 0,
  "page_labels": [
    "1",
    "2",
    "3",
    "4",
    "5",
    "6"
  ],
  "pages": 6,
  "pdf_version": "1.4",
  "producer": "Skia/PDF m155",
  "tagged": true,
  "title": "مركز نخلة الواحة لأبحاث التمور — التقرير السنوي ٢٠٢٥",
  "warnings": [],
  "xfa": null,
  "xfa_layout": null
}

رمز الخروج 0. والصفحة التي أبعادها 595 × 842 نقطة هي صفحة A4.

الأمر text: استخراج النص

xipdf-cli text <file.pdf> [--page N] [--password PW]

يطبع النص بترتيب القراءة. وإذا لم يُحدَّد --page طبع جميع الصفحات، يفصل بينها محرف «تغذية الصفحة» (U+000C) في سطر مستقل. ويخرج النص العربي بترتيبه المنطقي جاهزا للبحث أو اللصق.

$ xipdf-cli text samples/annual-report-ar.pdf --page 2
مركز نخلة الواحة لأبحاث التمور
الملخص التنفيذي
EXECUTIVE SUMMARY · ٠١
الملخص التنفيذي
شهد عام ٢٠٢٥ تحوّلًا نوعيًا في عمل المركز؛ إذ انتقلنا من التجارب الحقلية المحدودة إلى برامج إنتاج واسعة تخدم المزارعين في أربع مناطق
زراعية، وركّزنا جهودنا على ثلاثة محاور: تحسين الأصناف، وترشيد مياه الري، ونقل المعرفة إلى المزارع الصغيرة.
٢٤٠ ألف
٢٢٪
…

رمز الخروج 0. وطلب صفحة غير موجودة يخفق:

$ xipdf-cli text samples/annual-report-ar.pdf --page 9
page 9: page 9 does not exist
xipdf-cli: text: page(s) 9 could not be read

رمز الخروج 1. والصفحة الممسوحة ضوئيا لا طبقة نص فيها، فيطبع لها text سطرا فارغا؛ شغّل ocr أولا. وإذا كانت أذونات المستند تمنع النسخ رفض text الاستخراج وطلب كلمة مرور المالك عبر --password.

الأمر render: الصفحة صورةً

xipdf-cli render <file.pdf> --out FILE [--page N] [--dpi 96] [--password PW]

الخيار	معناه	القيمة الافتراضية
`--out`	ملف الصورة، وامتداده يحدد صيغته: `.png` أو `.jpg`/`.jpeg` (بجودة 90) أو `.tif`/`.tiff` أو `.pam` (بكسلات RGBA خام)	إلزامي
`--page`	الصفحة المطلوبة	`1`
`--dpi`	الدقة بالنقاط في البوصة	`96`

$ xipdf-cli render samples/annual-report-ar.pdf --page 3 --dpi 150 --out out/report-p3.png
rendered page 3 at 150 dpi: 1240×1754 px in 13 ms

رمز الخروج 0. أبعاد الصورة 1240 × 1754 بكسل وحجمها 253,593 بايت، ويظهر فيها النص العربي والرسم البياني الشريطي والأرقام العربية الهندية كما تظهر على الشاشة. وبالدقة الافتراضية 96 تعطي xipdf-cli render samples/invoice-ar.pdf --out out/invoice.jpg صورة JPEG أبعادها 794 × 1123 بكسل وحجمها 202,533 بايت. وتُرفض الامتدادات الأخرى (render: --out out/invoice.bmp: use a .png, .jpg, .tif or .pam name)، كما تُرفض الدقة التي تتجاوز حد محرك الرسم: فطلب 2000 نقطة في البوصة لصفحة A4 يخفق برسالة … exceeds renderer limits (maximum scale 9.730141)، أي نحو 700 نقطة في البوصة.

الأمر ocr: جعل المسوحات قابلة للبحث

xipdf-cli ocr <in.pdf> --out out.pdf [--lang ara+eng] [--dpi 300] [--pages 1,3] [--all-pages] [--password PW]

الخيار	معناه	القيمة الافتراضية
`--out`	ملف PDF الجديد القابل للبحث، ويجب ألا يكون موجودا	إلزامي
`--lang` (أو `--language`)	لغات Tesseract: `ara` أو `eng` أو `ara+eng`	اللغة الافتراضية في التفضيلات ← OCR، وإلا فـ`eng`
`--dpi`	الدقة التي تُقرأ بها الصفحات: `200` أو `300` أو `400`	قيمة التفضيلات ← OCR، وإلا فـ`300`
`--pages`	هذه الصفحات وحدها	جميع الصفحات
`--all-pages`	قراءة الصفحات التي فيها نص موثوق أيضا	غير مفعّل

يضيف التعرف الضوئي طبقة نص غير مرئية فوق صورة الصفحة دون أن يغيّرها. ويُكتب الناتج أولا في ملف مؤقت، ولا يُنقل إلى مكانه إلا بعد اكتماله. وفي المستندات العربية مرّر دائما --lang ara+eng.

$ xipdf-cli ocr samples/ar-scanned.pdf --lang ara+eng --out out/ar-searchable.pdf
{"growth_percent":2.5210255990505193,"input_bytes":146607,"output":"out/ar-searchable.pdf","output_bytes":150303,"pages":[{"low_confidence":false,"mean_confidence":89.24462890625,"page":1,"skipped":null,"words":56}],"seconds":1.0661024000000001,"seconds_per_page":1.0661024000000001,"words":56}

رمز الخروج 0: ست وخمسون كلمة في نحو ثانية، بمتوسط ثقة 89 من 100، وزاد حجم الملف 2.5٪. وصار في الناتج نص عربي:

$ xipdf-cli text out/ar-searchable.pdf
مواعيد مكتبة الحى
تفتح المكتبة أبوابها من الساعة التاسعة صباحا حتى الخامسة elas
ويمكن للأعضاء استعارة BW كتب Baa) أسبوعين.
قاعة المطالعة هادئة ومكيفة, وتتوفر فيها خدمة Wi-Fi مجانية, ولا
يسمح بإدخال الطعام إليها.
آخر موعد لإعادة الكتب قبل الإغلاق بنصف ساعة.
…

التعرف جيد لكنه ليس كاملا: فقد خرجت في هذا المسح بضع كلمات بحروف لاتينية (elas وBW وBaa)). راجع الأسماء والأرقام والتواريخ في كل مستند مهم.

ويعرض تقرير JSON لكل صفحة: عدد الكلمات words، ومتوسط الثقة mean_confidence (من 0 إلى 100)، والمؤشر low_confidence الذي يصبح true إذا قلّ المتوسط عن 70 أو قُرئ رقمٌ بثقة دون 60، وهي علامة على ضرورة مراجعة الصفحة، ثم skipped مع السبب إذا تُركت الصفحة دون قراءة. أما الصفحة الممسوحة من التقرير السنوي، وفيها رسوم بيانية ونص، فأعطت 312 كلمة مع "low_confidence":true ومتوسط ثقة 73.5: تصلح للبحث، لكنها تستحق المراجعة.

وهذا أثر اختيار اللغة:

$ xipdf-cli ocr samples/ar-scanned.pdf --out out/ar-default.pdf
{… "pages":[{"low_confidence":true,"mean_confidence":29.60999298095703,"page":1,"skipped":null,"words":60}] …}
$ xipdf-cli text out/ar-default.pdf
> cso seglo
elas duaBl Lis loo deli] dell yo Lgoolldeisel] pay
…

إذا لم تحدد --lang ولم تضبط لغة افتراضية في التفضيلات، قرأ سطر الأوامر بالإنجليزية (eng)، فتخرج الصفحة العربية حروفا لاتينية بثقة لا تتجاوز 30. ويكفي --lang ara وحده للصفحات العربية الخالصة، أما ara+eng فيحفظ كذلك الكلمات الإنجليزية والرموز والأرقام اللاتينية.

الأمر edit: التدوير والحذف والنقل والإدراج وتغيير العنوان

xipdf-cli edit <in.pdf> --out out.pdf [--rotate PAGES:DEGREES] [--delete PAGES] [--move PAGES:TO]
               [--insert-blank N] [--title T] [--author A] [--full] [--password PW]

الخيار	معناه
`--rotate 1,3:90`	تدوير الصفحات باتجاه عقارب الساعة بمضاعفات 90 درجة
`--delete 2,4`	حذف الصفحات
`--move 5:1`	نقل الصفحات لتبدأ من الموضع 1
`--insert-blank 1`	إدراج صفحة فارغة بمقاس US Letter (612 × 792 نقطة) لتصبح الصفحة 1
`--title` و`--author`	ضبط عنوان المستند واسم مؤلفه
`--full`	كتابة ملف جديد كامل بدل إلحاق التعديلات ببايتات الملف الأصلية (وهو السلوك الافتراضي)

تُنفَّذ الخيارات بالترتيب الذي تكتبه، ويشير كل رقم صفحة إلى المستند كما تركته الخيارات السابقة. ويجوز تكرار الخيارات.

$ xipdf-cli edit samples/annual-report-ar.pdf --out out/report-edited.pdf --rotate 3:90 --delete 6 --move 5:1 --insert-blank 1 --title "التقرير السنوي ٢٠٢٥ — نسخة المراجعة" --author "قسم الاتصال المؤسسي"
$ xipdf-cli info out/report-edited.pdf
…
  "author": "قسم الاتصال المؤسسي",
…
  "pages": 6,
…
  "title": "التقرير السنوي ٢٠٢٥ — نسخة المراجعة",
…

ينتهي الأمران بالرمز 0. وإليك ما جرى خطوة خطوة: دُوّرت الصفحة 3، ثم حُذفت الصفحة 6 (التطلعات) فبقيت خمس صفحات، ثم انتقلت الصفحة 5 (البرامج والمشروعات) إلى البداية، ثم أُدرجت صفحة فارغة قبل الجميع. فأصبحت الصفحة 1 فارغة، وتبدأ الصفحة 2 بعبارة البرامج والمشروعات. والحفظ الافتراضي يُلحق التعديلات بالأصل (1,667,248 بايت)، أما --full فيعيد كتابة الملف كله (1,456,269 بايت لنسخة غُيّر عنوانها فقط).

وتخفق الأخطاء قبل كتابة أي شيء:

$ xipdf-cli edit samples/annual-report-ar.pdf --out out/x.pdf --rotat 3:90
xipdf-cli: edit: unknown option "--rotat" (expected one of: --out, --password, --full, --rotate, --delete, --move, --insert-blank, --title, --author)
$ xipdf-cli edit samples/annual-report-ar.pdf --out out/x.pdf --delete 7
xipdf-cli: --delete: page 7 does not exist; after the earlier options the document has 6 pages
$ xipdf-cli edit samples/invoice-ar.pdf --out out/x.pdf --rotate 1:45
xipdf-cli: rotation must be a multiple of 90 degrees

الأمر combine: دمج الملفات

xipdf-cli combine <a.pdf> <b.pdf> … --out combined.pdf

يدمج ملفين أو أكثر بالترتيب المكتوب. ويحصل كل ملف مصدر على إشارة مرجعية عليا تحمل اسمه، وتنتقل معه الروابط وحقول النماذج والطبقات والمرفقات.

$ xipdf-cli combine samples/invoice-ar.pdf samples/brochure-bilingual.pdf samples/annual-report-ar.pdf --out out/combined.pdf
$ xipdf-cli info out/combined.pdf
…
  "bookmarks": 3,
…
  "pages": 9,
…

رمز الخروج 0: صفحة واحدة وصفحتان وست صفحات، وثلاث إشارات مرجعية. أما تمرير ملف واحد فيخفق برسالة combine: give at least two input files.

الأمر extract: نسخ صفحات إلى ملف جديد

xipdf-cli extract <in.pdf> --pages 1,3,5 --out out.pdf [--password PW]

$ xipdf-cli extract samples/annual-report-ar.pdf --pages 1,3,5 --out out/report-highlights.pdf

رمز الخروج 0، والملف الجديد من ثلاث صفحات. وتحافظ الصفحات على الترتيب الذي تكتبه، فالخيار --pages 6,1 يضع صفحة التطلعات قبل الغلاف.

الأمر split: ملف واحد إلى عدة ملفات

xipdf-cli split <in.pdf> (--every N | --before PAGES) [--out-dir DIR] [--password PW]

يبدأ --every N جزءا جديدا كل N صفحة، ويبدأ --before 3,7 جزءا جديدا عند كل صفحة مذكورة. ويجب تحديد أحدهما فقط. وتُسمّى الأجزاء <name>-p<first>-<last>.pdf (أو -p<n>.pdf للجزء ذي الصفحة الواحدة) داخل --out-dir (المجلد الحالي افتراضيا، ويُنشأ إن لم يكن موجودا)، ويُطبع مسار كل ملف يُكتب.

$ xipdf-cli split samples/annual-report-ar.pdf --every 2 --out-dir out/split-every
out/split-every\annual-report-ar-p1-2.pdf
out/split-every\annual-report-ar-p3-4.pdf
out/split-every\annual-report-ar-p5-6.pdf
$ xipdf-cli split samples/annual-report-ar.pdf --before 2,6 --out-dir out/split-chapters
out/split-chapters\annual-report-ar-p1.pdf
out/split-chapters\annual-report-ar-p2-5.pdf
out/split-chapters\annual-report-ar-p6.pdf

ينتهي الأمران بالرمز 0. وتحديد الخيارين معا يخفق برسالة split: give either --every N or --before PAGES.

الأمر check: هل يمكن فتح كل ملف ورسمه؟

xipdf-cli check <files or folders…> [--timeout 20] [--dpi 36] [--json report.json]

يجمع كل ملف .pdf من الملفات والمجلدات المذكورة (ويبحث داخل المجلدات الفرعية)، ثم يفتح كل ملف ويفحصه ويرسمه كاملا (حتى 500 صفحة، صورةً ونصا) في عملية مستقلة لها مهلة زمنية، فيُبلَّغ عن الملف الذي يتجمد أو ينهار بدل أن يوقف الفحص كله.

الخيار	معناه	القيمة الافتراضية
`--timeout`	الثواني المسموح بها لكل ملف	`20`
`--dpi`	دقة الرسم أثناء الفحص	`36`
`--json`	كتابة التقرير الكامل في هذا الملف	لا شيء

تُكتب المشكلات والملخص في مجرى الخطأ القياسي:

$ xipdf-cli check samples
checked 5 files: {"ok": 5}
$ xipdf-cli check out/ci --json out/ci-check.json
[1/2] open-error:the-file-is-not   out/ci\broken.pdf  the file is not a readable PDF: no readable page tree or cross-reference data was found

checked 2 files: {"ok": 1, "open-error": 1}

ينتهي الأمران بالرمز 0، حتى الثاني منهما (والملف broken.pdf هنا ملف نصي غُيّر امتداده إلى .pdf). ويسرد التقرير كل ملف:

[
  {
    "detail": "the file is not a readable PDF: no readable page tree or cross-reference data was found",
    "failed_pages": 0,
    "file": "out/ci\\broken.pdf",
    "ms": 0,
    "pages": 0,
    "status": "open-error:the-file-is-not",
    "warnings": 0
  },
  {
    "detail": "",
    "failed_pages": 0,
    "file": "out/ci\\invoice-ar.pdf",
    "ms": 12,
    "pages": 1,
    "status": "ok",
    "warnings": 0
  }
]

قيمة status إحدى هذه: ok، أو page-errors (أخفقت بعض الصفحات، ويبيّن detail أيها)، أو open-error:<reason>، أو timeout، أو crash، أو harness-error. ولا يخرج check بالرمز 1 إلا إذا تعذّر تشغيله أصلا، مثل check: no PDF files found.

الأمر audit: كشف الحجب الزائف

xipdf-cli audit <file.pdf> [--password PW]

الحجب الزائف يخفي النص بصريا فقط: مستطيل أسود مرسوم فوق نص ما زال ممكنا تحديده أو نسخه أو استخراجه. ويبلّغ audit عن نوعين:

covered-text: مستطيل معتم مملوء، داكن بما يكفي لإخفاء النص، رُسم بعد النص الذي يغطيه؛
unapplied-mark: علامة حجب وُضعت ولم تُطبَّق، فبقي النص تحتها كما هو.

يطبع النتيجة بصيغة JSON ويخرج بالرمز 1 إذا وجد أي شيء، فيستطيع النص البرمجي أو مهمة التكامل المستمر التوقف عنده. أما الحجب الحقيقي الذي يزيل المحتوى فلا يُبلَّغ عنه أبدا. ويخفق الفحص كذلك إذا تعذّرت قراءة جزء من الملف، بدل أن يعلن «لا شيء». وله حدود معروفة: قد يفوته الغطاء المرسوم بأشكال حرة أو بتدرجات لونية أو أنماط، والغطاء شبه الشفاف، والنص داخل كائنات Form XObject، وقد تختل المواضع في الصفحات التي تحمل /Rotate.

الملف السليم يجتاز الفحص:

$ xipdf-cli audit samples/invoice-ar.pdf
{"count":0,"file":"samples/invoice-ar.pdf","findings":[]}

رمز الخروج 0. أما نسخة من الفاتورة عُلِّم فيها الرقم الضريبي للبائع للحجب دون تطبيقه (أُعدّت بمثال run --script أدناه بلا خطوة redact_apply) فتخفق:

$ xipdf-cli audit out/invoice-marked-only.pdf
{"count":2,"file":"out/invoice-marked-only.pdf","findings":[{"covered_text":"VAT 310987654300003","kind":"unapplied-mark","page":1,"rect":[55.2976188659668,763.0709838867188,127.25257873535156,771.0659790039062]},{"covered_text":"310987654300003","kind":"unapplied-mark","page":1,"rect":[427.0898132324219,624.9105224609375,495.1648254394531,633.7080078125]}]}
xipdf-cli: audit: 2 faux redaction(s) found

رمز الخروج 1. والنسخة نفسها بعد redact_apply تجتاز الفحص بقيمة "count":0.

الأمر batch: تحويل مجلد كامل والتعرف عليه وضغطه

xipdf-cli batch <files or folders…> --steps convert,ocr,optimize --out-dir DIR
               [--recursive] [--root DIR] [--stop-on-error]
               [--ppi 150] [--quality 60] [--dpi 300] [--language en] [--ocr-all-pages]

ينفّذ من خطوة إلى ثلاث خطوات على كل ملف، ملفا بعد ملف، ويكتب كل نتيجة في --out-dir بالمسار النسبي نفسه وبامتداد .pdf. ولا تتغير الملفات المصدر أبدا، ولا يُستبدل أي ملف إخراج موجود، بل يُستخدم اسم مرقّم مثل report (2).pdf.

الخطوة	عملها	خياراتها
`convert`	تحويل الصور (`png` و`jpg` و`jpeg` و`tif` و`tiff` و`gif` و`bmp` و`jp2` و`j2k` و`jpx`) والملفات النصية (`txt` و`text`) إلى PDF، ويجب أن تكون الخطوة الأولى. ومن دونها تُعالَج ملفات PDF وحدها وتُتخطى غيرها.	لا خيارات
`ocr`	إضافة طبقة نص بـأداة التعرف المدمجة للإنجليزية (الحروف اللاتينية)	`--dpi` (من 72 إلى 600، والافتراضي 300)، و`--language` (القيمة `en` وحدها)، و`--ocr-all-pages`
`optimize`	تقليل حجم الملف: تُخفَّض دقة الصور التي تتجاوز 1.5 ضعف الهدف ويُعاد ضغطها بصيغة JPEG، ويُحتفظ بالبايتات الأصلية إن لم يصغر الناتج	`--ppi` (من 9 إلى 1600، والافتراضي 150، أي الصور التي تتجاوز 225)، و`--quality` (من 1 إلى 100، والافتراضي 60)

ومن الخيارات الأخرى: --recursive للدخول إلى المجلدات الفرعية (غير مفعّل افتراضيا)، و--stop-on-error لتخطي الملفات الباقية بعد أول إخفاق، و--root DIR لحصر كل المسارات داخل ذلك المجلد. ويقتصر البحث على 10,000 عنصر و64 مستوى من المجلدات، ولا يتجاوز الملف المدخل 512 ميبيبايت، وتُتخطى الروابط والملفات الخاصة. ويطبع الأمر تقريرا بصيغة JSON، ويخرج بالرمز 1 إذا أخفق أي ملف.

$ xipdf-cli batch samples --steps optimize --ppi 100 --quality 50 --out-dir out/batch-small
{
  "completed": 5,
  "failed": 0,
  "files": [
    {
      "bytes": 69075,
      "output": "\\\\?\\V:\\…\\out\\batch-small\\annual-report-ar-scanned.pdf",
      "path": "\\\\?\\V:\\…\\samples\\annual-report-ar-scanned.pdf",
      "status": "ok",
      "steps": [
        {
          "bytes_after": 69075,
          "bytes_before": 330442,
          "step": "optimize"
        }
      ]
    },
    …
  ],
  "skipped": 0,
  "stopped": false
}

رمز الخروج 0. صغر التقرير الممسوح من 330,442 إلى 69,075 بايت، وإعلان المكتبة من 146,607 إلى 27,919 بايت. وتحويل مجلد من الصور يجري بالطريقة نفسها: فقد حوّل xipdf-cli batch out/images --steps convert,optimize --out-dir out/batch-converted الملف invoice.jpg إلى invoice.pdf (رمز الخروج 0).

تنبيه مهم للعربية: تستخدم خطوة ocr في batch أداة التعرف الإنجليزية المدمجة وحدها. فالخيار --language ara+eng مرفوض (unsupported language "ara+eng")، وعلى المسح العربي تعلن الخطوة نجاحها بينما تُنتج حروفا لاتينية بلا معنى (283 «كلمة» في التقرير الممسوح). فللمسوحات العربية استخدم الأمر ocr داخل حلقة، كما في الوصفة أدناه. وتأتي نماذج أداة التعرف المدمجة مع التطبيق المثبّت، فإن غابت أخفقت الخطوة برسالة the text recognition models are not installed (reinstall XiKey PDF, …).

وتُرفض الإعدادات التي تحتاج إلى خطوة غير مطلوبة، مثل --dpi دون ocr: dpi/language/skip_text_pages settings need the ocr step.

الأمران tools وrun: كل أدوات الأتمتة من سطر الأوامر

xipdf-cli tools
xipdf-cli run <tool> [key=value …] [--root DIR] [--out image.png]
xipdf-cli run --script steps.json [--root DIR]

يطبع tools كل أدوات الأتمتة بصيغة JSON: الاسم name، والوصف description، وread_only، وأمر التطبيق المقابل command، ومخطط المدخلات input_schema بصيغة JSON Schema. وفي هذا الإصدار 163 أداة، من doc_open وtext_find وpage_render إلى الحجب والنماذج والتواقيع والتعليقات وإمكانية الوصول وPDF/A والمقارنة.

ويستدعي run أداة واحدة. يصبح كل زوج key=value وسيطا، وتُقرأ القيمة بصيغة JSON متى أمكن (pages=[1,3] وdegrees=90 وfull=true) وإلا فهي نص. والأداة التي تعيد صورة تحفظها في --out. وكل استدعاء لـrun جلسة جديدة، فالاستدعاء المفرد يناسب الأدوات التي تأخذ مسارات ملفات:

$ xipdf-cli run doc_combine 'paths=["samples/invoice-ar.pdf","samples/brochure-bilingual.pdf"]' out=out/run-combined.pdf
{
  "bytes": 231589,
  "path": "out/run-combined.pdf"
}

رمز الخروج 0. أما الأدوات التي تعمل على مستند مفتوح (doc) فتحتاج إلى نص خطوات، لأن رقم المستند لا يعيش إلا في جلسة واحدة.

ينفّذ run --script مصفوفة JSON من الخطوات في جلسة واحدة. كل خطوة على صورة {"tool": …, "args": {…}}، ومعها "out" إذا أعادت صورة. أول مستند يُفتح رقمه 1، والذي يليه 2، وهكذا. يبحث هذا النص عن عبارة «الرقم الضريبي» في الفاتورة، ثم يحجب الرقمين الضريبيين حجبا نهائيا، ويحفظ نسخة، ويرسمها صورة:

[
  {"tool": "doc_open", "args": {"path": "samples/invoice-ar.pdf"}},
  {"tool": "text_find", "args": {"doc": 1, "query": "الرقم الضريبي"}},
  {"tool": "redact_mark", "args": {"doc": 1, "words": ["310987654300003", "300123456700003"]}},
  {"tool": "redact_apply", "args": {"doc": 1}},
  {"tool": "doc_save", "args": {"doc": 1, "path": "out/invoice-redacted.pdf"}},
  {"tool": "page_render", "args": {"doc": 1, "page": 1, "dpi": 72}, "out": "out/invoice-redacted.png"}
]

$ xipdf-cli run --script out/redact-invoice.json
{
  "dirty": false,
  "doc": 1,
  …
  "name": "invoice-ar.pdf",
  "pages": 1,
  …
}
{
  "complete": true,
  "count": 2,
  "matches": [
    {
      "page": 1,
      "rects": [
        [
          499.8208312988281,
          208.2119903564453,
          543.5091552734375,
          217.00949096679688
        ]
      ],
      "text": "الرقم الضريبي"
    },
    …
  ],
  …
}
{
  …
  "marked": 3,
  "marks_pending": 3,
  "matched_words": [
    {
      "marked": 2,
      "word": "310987654300003"
    },
    {
      "marked": 1,
      "word": "300123456700003"
    }
  ],
  …
}
{
  "applied": 3,
  …
  "marks_pending": 0,
  …
}
{
  "bytes": 75952,
  …
  "incremental": false,
  "path": "out/invoice-redacted.pdf"
}
{"height":842,"image":"out/invoice-redacted.png","width":595}

رمز الخروج 0. تطبع كل خطوة نتيجتها. ولم يعد أي من الرقمين موجودا في ناتج text للنسخة المحفوظة، واجتازت فحص audit، وتظهر في الصورة مستطيلات سوداء مكانهما. وإذا أخفقت خطوة توقف النص برسالة step N (tool): <message> ورمز الخروج 1.

تُقاس الإحداثيات في وسائط الأدوات ونتائجها بالنقاط ابتداء من الزاوية العليا اليسرى للصفحة. ومع --root DIR يجب أن يقع كل مسار تذكره أداة أو خطوة، بما فيها "out"، داخل DIR، وتُحسب المسارات النسبية داخله:

$ xipdf-cli run doc_combine 'paths=["invoice-ar.pdf","brochure-bilingual.pdf"]' out=../out/rooted.pdf --root samples
xipdf-cli: ../out/rooted.pdf is outside the allowed directory \\?\V:\…\samples

وتستخدم أداتا الأتمتة ocr_recognize وocr_status أداة التعرف الإنجليزية المدمجة، مثل batch. فللتعرف على العربية استخدم الأمر ocr.

الأمر mcp: تقديم الأدوات لمساعد ذكي

xipdf-cli mcp [--root DIR] [--compact]

يشغّل خادم بروتوكول سياق النموذج (Model Context Protocol) عبر المدخل والمخرج القياسيين (أسطر JSON؛ إصدارات البروتوكول 2025-06-18 و2025-03-26 و2024-11-05). لا يفتح أي منفذ شبكي، ولا يبدأ من تلقاء نفسه، ويتوقف عند إغلاق مدخله. ويقدّم الأدوات نفسها التي يقدمها run؛ ومع --compact يسرد مجموعة أساسية من 15 أداة (doc_open وdoc_info وdoc_save وdoc_close وpage_render وtext_extract وtext_find وdoc_combine وdoc_split وedit_undo وcommand_list وcommand_run وcommand_batch وdoc_inspect وrender_preview)، ومعها tool_search وtool_call للوصول إلى بقية الأدوات، بدل سرد الأدوات الـ163 كلها. وحدّد --root دائما كي لا يصل المساعد إلا إلى مجلد واحد. ويُكتب سطر بدء التشغيل في مجرى الخطأ القياسي.

خادم MCP موجود في الإصدارات القياسية (Windows وmacOS وLinux). أما الإصدار المبني دون ميزة mcp فيجيب برسالة mcp: this build leaves out the MCP server.

وهذا إعداد نموذجي للعميل:

{
  "mcpServers": {
    "xikey-pdf": {
      "command": "C:\\Program Files\\XiKey PDF\\xipdf-cli.exe",
      "args": ["mcp", "--root", "D:\\Documents\\PDF", "--compact"]
    }
  }
}

تبادل جرّبناه فعلا (--root samples --compact): بعد initialize وtools/list (17 أداة)، أعاد الاستدعاء doc_open {"path": "invoice-ar.pdf"} المستند رقم 1، وأعاد text_find {"doc": 1, "query": "فاتورة ضريبية"} نتيجة واحدة في الصفحة 1. وانتهى الخادم بالرمز 0 عند إغلاق المدخل.

الأمر ui: التحكم في نافذة تطبيق مفتوحة

xipdf-cli ui --control FILE <method> [key=value …] [--out shot.png]

يتحدث ui إلى نافذة XiKey PDF شُغّلت بالخيار --control FILE. عندها يستمع التطبيق على منفذ عشوائي في 127.0.0.1 وحده، ويكتب رقم المنفذ ورمزا سريا عشوائيا في FILE، ولا يُقبل أي اتصال لا يقدّم هذا الرمز. احفظ الملف في مجلد لا يكتب فيه أحد غيرك. ويرفض الأمر ملف تحكم يكون رابطا أو ليس ملفا عاديا، ويرفض على Linux وmacOS كذلك الملف الذي يملكه مستخدم آخر أو يستطيع غيرك الوصول إليه.

# Windows: start the app with a control file
& "C:\Program Files\XiKey PDF\XiKeyPDF.exe" --control "$env:LOCALAPPDATA\xipdf-control.json" samples\annual-report-ar.pdf
# then, from another terminal
xipdf-cli ui --control "$env:LOCALAPPDATA\xipdf-control.json" state
xipdf-cli ui --control "$env:LOCALAPPDATA\xipdf-control.json" screenshot --out window.png
xipdf-cli ui --control "$env:LOCALAPPDATA\xipdf-control.json" set key=language value=ar
xipdf-cli ui --control "$env:LOCALAPPDATA\xipdf-control.json" quit

واسم التطبيق على Linux هو xipdf، وعلى macOS هو "XiKey PDF.app/Contents/MacOS/XiKeyPDF".

لم يُنفَّذ في هذا الدليل. لم تُشغَّل أمثلة التحكم في النافذة أعلاه، لأن نافذة XiKey PDF على جهاز الاختبار كانت مشغولة باختبار آخر وقتها. فهي مكتوبة من مرجع قناة التحكم في التطبيق، وليست نسخة مسجلة من جلسة فعلية. أما ما نُفّذ فهو معالجة الأخطاء: إذا لم يكن التطبيق مفتوحا خرج ui --control FILE state بالرمز 1 مع الرسالة can't reach the app on port …: … (is it still running?)، وإذا لم تُذكر طريقة سرد الأمر الطرق المتاحة.

الطرق المتاحة (البادئة ui. اختيارية، والوسائط على صورة key=value وتُقرأ بصيغة JSON متى أمكن):

الطريقة	عملها
`state`	المستندات المفتوحة والمستند النشط والصفحة والتكبير والوضع واللوحات والحوار وأبعاد النافذة
`inspect query=… role=… limit=…`	عناصر الواجهة مع معرّفها ودورها وتسميتها وقيمتها وموضعها وحالتها
`commands` و`command id=…`	سرد أوامر التطبيق، أو تنفيذ أحدها كما تفعل القائمة
`open path=…`	فتح ملف
`set key=… value=…`	خيارات العرض والتفضيلات، مثل `language` و`theme` (`light` أو `dark` أو `system`) و`panel` و`select` و`default-mode`
`click id=…` أو `label=…` أو `x=… y=…`، و`focus`	النقر على عنصر أو نقطة، أو نقل التركيز إليه
`type text=…` و`key key=… modifiers=…`	إدخال من لوحة المفاتيح
`move` و`drag from=[x,y] to=[x,y]`	تحريك المؤشر والسحب
`resize width=… height=…`	أبعاد النافذة (من 320 إلى 8192 نقطة)
`screenshot` (مع `--out shot.png`)	صورة PNG للنافذة؛ ومن دون `--out` تُعاد الصورة بترميز base64
`quit`	إغلاق عادي؛ وإذا وُجدت تعديلات غير محفوظة سأل التطبيق أولا بدل الإغلاق

ينتظر كل طلب حتى 40 ثانية. ويحتاج الإدخال ولقطات الشاشة إلى أن تكون النافذة مرسومة؛ فالنافذة المصغّرة أو المخفية تجيب بخطأ يطلب إحضارها إلى المقدمة.

عرض الإصدار (`--version`)

$ xipdf-cli --version
xipdf-cli 0.8.0
Community: https://xikey.com  (help and feedback)
Website: https://desktop.xikey.com/products/xipdf/

رمز الخروج 0.

التعرف الضوئي بالتفصيل

المحرك واللغات. يستخدم الأمر ocr محرك Tesseract 5.3.0 مع نماذج tessdata_best 4.1.0 للعربية (ara) والإنجليزية (eng). اجمع اللغات بعلامة +؛ فالخيار ara+eng هو الأنسب للمستندات العربية التي تتخللها كلمات إنجليزية أو رموز أو أرقام لاتينية. ويجري التعرف كله على جهازك.
Windows x64: يُثبَّت Tesseract ونموذجا اللغتين مع XiKey PDF في C:\Program Files\XiKey PDF\ocr\tesseract\، فيعمل التعرف دون اتصال منذ التشغيل الأول.
Linux: ثبّت Tesseract وحزم اللغات من توزيعتك. وتعلن حزمتا DEB وRPM عنها بوصفها اعتماديات، أما AppImage فلا يتضمنها.

# Debian / Ubuntu
sudo apt install tesseract-ocr tesseract-ocr-ara tesseract-ocr-eng
# Fedora / RHEL
sudo dnf install tesseract tesseract-langpack-ara tesseract-langpack-eng
# openSUSE
sudo zypper install tesseract-ocr tesseract-ocr-traineddata-ara tesseract-ocr-traineddata-eng

macOS: لا يأتي Tesseract مع التطبيق. ثبّته عبر Homebrew، والعربية موجودة في tesseract-lang لا في الحزمة الأساسية. ثم تأكد أن tesseract --list-langs يسرد ara وeng كلتيهما.

brew install tesseract tesseract-lang

كيف يُعثر على Tesseract: أولا المسار المختار في التفضيلات ← OCR ← Locate، ثم المجلد ocr/tesseract/ بجوار xipdf-cli، ثم مجلد التعرف الضوئي الخاص بـXiKey PDF في ملفك الشخصي، ثم متغير PATH. وتُقرأ بيانات اللغات من المجلد tessdata داخل ذلك المجلد الشخصي، ومن مجلد بيانات Tesseract نفسه، ومن TESSDATA_PREFIX إذا كان مضبوطا. والمجلد الشخصي هو %APPDATA%\XiPDF\ocr على Windows، و~/.local/share/XiPDF/ocr على Linux وmacOS (أو $XDG_DATA_HOME/XiPDF/ocr إذا كان هذا المتغير مضبوطا).
الإعدادات الافتراضية من التطبيق. يقرأ سطر الأوامر اللغة الافتراضية والدقة اللتين ضبطتهما في تفضيلات التطبيق ← OCR. فإن لم تحفظ لغة افتراضية استخدم eng بدقة 300. (أما التطبيق نفسه فيختار العربية والإنجليزية للمسوحات تلقائيا، بينما لا يخمّن سطر الأوامر، فمرّر --lang.)
الخيار --dpi هو الدقة التي تُقرأ بها الصفحات: 200 أو 300 أو 400. ولا تُقرأ الصفحة الممسوحة بدقة أعلى من دقة صورتها الأصلية، لأن تكبير المسح لا يزيد الحروف إلا ضبابية.
الصفحات التي فيها نص. يترك ocr افتراضيا كل صفحة طبقة نصها موثوقة، ويسجّلها "skipped": "the page already contains text". أما الصفحات التي نصها تالف أو مشوّه أو مفقود فتُقرأ في كل الأحوال. وإذا تُركت كل الصفحات المحددة أخفق الأمر ولم يكتب شيئا:

$ xipdf-cli ocr samples/annual-report-ar.pdf --lang ara+eng --out out/report-text-ocr.pdf
xipdf-cli: ocr: no pages recognized: the page already contains text; the page already contains text; …

الخيار --all-pages يقرأ كذلك الصفحات التي فيها نص سليم، لالتقاط الكلمات المرسومة داخل الصور مثل تسميات الرسوم البيانية. ولا تُضاف الكلمات الموجودة في الصفحة مرة ثانية. ففي الصفحة 3 من التقرير السنوي، وفيها نص عربي ورسمان بيانيان، أضاف تسع كلمات:

$ xipdf-cli ocr samples/annual-report-ar.pdf --lang ara+eng --pages 3 --all-pages --out out/report-p3-all.pdf
{"growth_percent":0.19149718723432407,"input_bytes":1658510,"output":"out/report-p3-all.pdf","output_bytes":1661686,"pages":[{"low_confidence":true,"mean_confidence":76.6895751953125,"page":3,"skipped":null,"words":9}],"seconds":3.0978103,"seconds_per_page":3.0978103,"words":9}

الخيار --pages يحصر التعرف في الصفحات المذكورة، والصفحة التي تتجاوز نهاية المستند تُرفض برسالة ocr: page number is outside this document.

وصفات جاهزة

التعرف الضوئي على مجلد كامل من المسوحات العربية

بلغة Bash (على Linux وmacOS، أو Git Bash على Windows). يتخطى الملفات المنجزة، فيمكن إعادة تشغيله بعد أي انقطاع، ويحتفظ بتقرير كل ملف بصيغة JSON:

#!/usr/bin/env bash
# Make every scanned PDF in scans/ searchable, into searchable/.
set -u
mkdir -p searchable
status=0
for f in scans/*.pdf; do
  out="searchable/$(basename "$f")"
  if [ -e "$out" ]; then echo "skip    $f (already done)"; continue; fi
  if xipdf-cli ocr "$f" --lang ara+eng --out "$out" > "$out.json"; then
    echo "ok      $f"
  else
    echo "FAILED  $f" >&2
    rm -f "$out.json"
    status=1
  fi
done
exit $status

$ bash ocr-folder.sh
ok      scans/annual-report-ar-scanned.pdf
ok      scans/ar-scanned.pdf
$ bash ocr-folder.sh
skip    scans/annual-report-ar-scanned.pdf (already done)
skip    scans/ar-scanned.pdf (already done)

انتهى التشغيلان بالرمز 0. وبلغة PowerShell على Windows:

# Make every scanned PDF in scans\ searchable, into searchable-ps\.
New-Item -ItemType Directory -Force searchable-ps | Out-Null
$failed = 0
Get-ChildItem scans -Filter *.pdf | ForEach-Object {
    $out = Join-Path searchable-ps $_.Name
    if (Test-Path $out) { "skip    $($_.Name) (already done)"; return }
    xipdf-cli ocr $_.FullName --lang ara+eng --out $out | Set-Content "$out.json"
    if ($LASTEXITCODE -eq 0) { "ok      $($_.Name)" } else { Write-Warning "FAILED  $($_.Name)"; $failed++ }
}
exit [int]($failed -gt 0)

PS> .\ocr-folder.ps1
ok      annual-report-ar-scanned.pdf
ok      ar-scanned.pdf

رمز الخروج 0. وتوقّع ما بين ثانية وثلاث ثوانٍ ونصف تقريبا للصفحة على حاسوب مكتبي.

استخراج نص كل ملفات PDF إلى ملفات .txt

#!/usr/bin/env bash
# Write the text of every PDF in the given folder to text/<name>.txt (UTF-8).
set -u
src="${1:-.}"
mkdir -p text
for f in "$src"/*.pdf; do
  name="$(basename "${f%.*}")"
  xipdf-cli text "$f" > "text/$name.txt" || echo "FAILED  $f" >&2
done

# Write the text of every PDF in the given folder to text-ps\<name>.txt (UTF-8).
param([string]$Source = '.')
# xipdf-cli writes UTF-8; tell PowerShell, so Arabic stays intact whatever the console code page.
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
New-Item -ItemType Directory -Force text-ps | Out-Null
Get-ChildItem $Source -Filter *.pdf | ForEach-Object {
    $txt = Join-Path text-ps ($_.BaseName + '.txt')
    xipdf-cli text $_.FullName | Set-Content -Encoding UTF8 $txt
    if ($LASTEXITCODE -ne 0) { Write-Warning "FAILED  $($_.Name)" }
}

شُغّلت النسختان على مجلد العينات (رمز الخروج 0). ويبدأ الملف النصي للفاتورة بعبارة مشغل السدو للحرف التراثية، أما المسحان فيعطيان ملفين فارغين: تعرّف عليهما ضوئيا أولا. ويكتب Windows PowerShell 5.1 بترميز UTF-8 مع علامة ترتيب البايتات ونهايات أسطر CRLF، بينما تكتب نسخة Bash مخرجات الأداة كما هي.

تقسيم تقرير إلى فصوله

اعرف أين يبدأ كل فصل (مثلا بالأمر xipdf-cli text <file> --page N)، ثم قسّم المستند قبل تلك الصفحات. ففي التقرير السنوي تبدأ الفصول من ٠١ إلى ٠٥ في الصفحات من 2 إلى 6 بعد الغلاف:

$ xipdf-cli split samples/annual-report-ar.pdf --before 2,3,4,5,6 --out-dir chapters
chapters\annual-report-ar-p1.pdf
chapters\annual-report-ar-p2.pdf
chapters\annual-report-ar-p3.pdf
chapters\annual-report-ar-p4.pdf
chapters\annual-report-ar-p5.pdf
chapters\annual-report-ar-p6.pdf

رمز الخروج 0. وللمستندات التي فيها إشارات مرجعية تستطيع الأداة doc_split كذلك التقسيم عند الإشارات العليا ("bookmarks": true) من خلال run --script.

بوابة تكامل مستمر بالأمرين check وaudit

#!/usr/bin/env bash
# CI gate: fail the build if any PDF in $1 is unreadable or has a faux redaction.
set -u
dir="${1:?usage: pdf-gate.sh DIR}"
fail=0

# 1. Robustness: check always exits 0 once it has run, so read its JSON report.
xipdf-cli check "$dir" --timeout 30 --json check.json || exit 1
python3 - check.json <<'PY' || fail=1
import json, sys
bad = [r for r in json.load(open(sys.argv[1], encoding="utf-8")) if r["status"] != "ok"]
for r in bad:
    print(f'check: {r["status"]}: {r["file"]}: {r["detail"]}')
sys.exit(1 if bad else 0)
PY

# 2. Redactions: audit exits 1 when it finds a faux redaction (or cannot read the file).
for f in "$dir"/*.pdf; do
  xipdf-cli audit "$f" > /dev/null || fail=1
done
exit $fail

على مجلد فيه الفاتورة المحجوبة والكتيّب تنجح البوابة (رمز الخروج 0). وعلى مجلد فيه الفاتورة الأصلية والنسخة المعلَّمة غير المطبَّقة وملف تالف تخفق (رمز الخروج 1):

$ bash pdf-gate.sh release-bad
[1/3] open-error:the-file-is-not   release-bad\broken.pdf  the file is not a readable PDF: …

checked 3 files: {"ok": 2, "open-error": 1}
check: open-error:the-file-is-not: release-bad\broken.pdf: the file is not a readable PDF: …
xipdf-cli: release-bad/broken.pdf: not a PDF file (no %PDF- header)
xipdf-cli: audit: 2 faux redaction(s) found

حل المشكلات

يخفق التعرف الضوئي برسالة «Tesseract is not installed» أو «OCR language … is not installed». المحرك أو حزمة لغة غير موجودة. على Windows أصلح تثبيت XiKey PDF أو أعد تثبيته، فمكان المحرك هو ocr\tesseract\ بجوار xipdf-cli.exe. وعلى Linux ثبّت حزم التوزيعة المذكورة أعلاه، وعلى macOS نفّذ brew install tesseract tesseract-lang. ثم تحقق بالأمر tesseract --list-langs. وطلب لغة غير مثبتة يعطي مثلا ocr: no pages recognized: text recognition failed: OCR language fra is not installed; download it in Preferences → OCR.

أداة التعرف المدمجة غير موجودة (تخفق batch --steps ocr أو --lang en برسالة the text recognition models are not installed (reinstall XiKey PDF, …)). تأتي هذه النماذج في المجلد models داخل التطبيق المثبّت، ونسخة منفردة من xipdf-cli لا تحملها. أعد التثبيت، أو شغّل الأمر من مجلد التثبيت.

ملف محمي بكلمة مرور. دون كلمة المرور:

$ xipdf-cli info out/invoice-protected.pdf
xipdf-cli: the document is protected by a password
$ xipdf-cli info out/invoice-protected.pdf --password wrong
xipdf-cli: the password is incorrect
$ xipdf-cli text out/invoice-protected.pdf --password demo-open-2025
مشغل السدو للحرف التراثية
…

يخرج الأولان بالرمز 1 والثالث بالرمز 0. وإذا قال text إن الأذونات لا تسمح بالنسخ فمرّر كلمة مرور المالك (كلمة مرور الأذونات). ولا يستطيع combine فتح ملفات محمية، فاستخرج صفحاتها أولا بالأمر extract مع --password.

نص التعرف الضوئي حروف لاتينية بلا معنى على مسح عربي. استُخدمت لغة خاطئة: فمن دون --lang يقرأ سطر الأوامر بالإنجليزية. أعد التشغيل مع --lang ara+eng، أو اجعل العربية والإنجليزية اللغة الافتراضية في التفضيلات ← OCR. أما خطوة OCR في batch فلا تقرأ العربية أصلا، فاستخدم الأمر ocr.

كلمات خاطئة رغم صحة اللغة. راجع mean_confidence وlow_confidence في تقرير JSON. فأفضل النتائج من المسوحات الواضحة المستقيمة بدقة 300، ويكثر الخطأ في النص الباهت أو المائل أو المكتوب بخط اليد أو بالخطوط الزخرفية. ولا تجرّب --dpi 400 إلا للحروف الصغيرة في مسوحات بلغت دقتها ذلك فعلا.

على Linux: لا يبدأ التطبيق ويظهر خطأ عن libxkbcommon-x11. هذه المكتبة تحتاج إليها النافذة وحدها. أما xipdf-cli فلا يستخدم نظام النوافذ، فيعمل على الخوادم التي لا شاشة فيها ولا مكتبات لوحة مفاتيح. ولتشغيل التطبيق ثبّت libxkbcommon-x11-0 (على Debian وUbuntu) أو libxkbcommon-x11 (على Fedora وRHEL).

تظهر العربية علامات استفهام في طرفية Windows. تكتب الأداة بترميز UTF-8. ففي PowerShell نفّذ [Console]::OutputEncoding = [System.Text.Encoding]::UTF8، أو حوّل المخرجات إلى ملف وافتحه في محرر نصوص.