حوّل وثائق Office إلى Markdown باستعمال anydoc

شنو هو anydoc؟

anydoc هي مكتبة سريعة مكتوبة بـ Rust لتحويل الوثائق إلى Markdown نقي ومتوافق مع GitHub. كتدعم Word وPowerPoint وExcel وOpenDocument وRTF وEPUB وCSV وملفات PDF اللي فيها نص. المشروع كيوفّر حتى واجهة سطر الأوامر وربطيات لـ Node.js وPython وWebAssembly اللي خدام فالمتصفح.

المكتبة مصمّمة للأنابيب البرمجية اللي كتستقبل صيغ متعددة ديال الوثائق ولكن كتحتاج تمثيلاً موحّداً بـ Markdown. كل صيغة مكتبية مدعومة كتتحلّل إلى نموذج مشترك للوثيقة، ومن بعد كتدوز من نفس مُسلسِل Markdown. هاد الشي كيخلي الجداول، والهروب من الرموز، والعناوين، والحواشي، والروابط، واللوائح، وباقي البنيات متناسقة بين الصيغ المختلفة.

التحويلات كتدار محلياً بلا نماذج ديال التعلّم الآلي ولا خدمات خارجية. كيشير README إلى أن الوقت الوسيط للتحويل أقل من خمسة ميليثواني لكل وثيقة فاختباره المعياري. ملفات PDF اللي فيها نص كيتعالجوا محلياً باستعمال pdf-inspector.

anydoc ما كتديرش OCR. ملفات PDF اللي فيها غير الصور أو الممسوحة ضوئياً، واللي ما فيها حتى نص قابل للقراءة، ممكن يتبلّغ عليها بأنها غير مدعومة. Firecrawl Parse هي البديل المستضاف اللي كيذكره المشروع لسير العمل اللي كيحتاج حتى OCR.

أهم المزايا

• Markdown متناسق: جميع الصيغ المكتبية كتستعمل نموذجاً مشتركاً للوثيقة ومُسلسِلاً موحّداً.
• إخراج منظّم: البنيات المدعومة كتشمل العناوين والروابط المرجعية، والروابط، والمراجع الداخلية، واللوائح، والجداول، والاقتباسات المحظّرة، والحواشي، والحواشي الختامية، وملاحظات المتحدث، والكود داخل السطر، وكتل الكود.
• الحفاظ على التنسيق: يمكن تمثيل الخط العريض، والمائل، والمشطوب، ولوائح المهام، واللوائح المتداخلة، وترقيم المصدر، وخلايا الجداول المدمجة، وصفوف العناوين.
• الأصول المضمّنة: الصور والكائنات المضمّنة كيبانو كنص بديل فـ Markdown، بينما البايتات الخام ديالهم وأنواع الوسائط ديالهم كيبقاو متاحين عبر نموذج الوثيقة.
• التعرّف اعتماداً على المحتوى: صيغ PDF وRTF وOLE والوثائق المبنية على ZIP كيتعرّف عليها انطلاقاً من البايتات ديالها، وماشي غير بالاعتماد على امتدادات الملفات.
• ربطيات ما كتوقفش التنفيذ: تحويلات Node.js كتستعمل مسبح خيوط libuv، بينما Python كتحرّر القفل العام للمفسّر أثناء التحويل.
• حزم مهيكلة: أنواع TypeScript وتعريفات Python مضمّنة.
• الاندماج مع الوكلاء: المشروع فيه Agent Skill كيعلم وكلاء البرمجة المتوافقين كيفاش يستعملو anydoc CLI.

صيغ الملفات المدعومة

• Word: .doc و.docx و.docm
• PowerPoint: .ppt و.pps و.pot و.pptx و.pptm و.ppsx و.ppsm
• Excel: .xls و.xlsx و.xlsm و.xlsb
• OpenDocument: .odt و.ods و.odp
• صيغ أخرى: .rtf و.epub و.csv و.pdf

اختار طريقة التثبيت

استعمل CLI للسكربتات ديال الصدفة والتحويلات العرضية. اختار Node.js أو Python ملي يكون تحويل الوثائق جزءاً من تطبيق، وRust للاندماج الأصلي، أو WebAssembly ملي خاص الملفات تتحوّل مباشرة فالمتصفح.

ثبّت CLI

تقدر تشغّل CLI الجاهز بلا تثبيت دائم باستعمال npx:

npx @firecrawl/anydoc report.docx

الملف التنفيذي الجاهز للمنصة ديالك كيتحمّل فالتشغيل الأول. باش تولّي anydoc متاحة كأمر دائم، ثبّتها بشكل عام:

npm install -g @firecrawl/anydoc
anydoc --help

ثبّتها لـ Node.js

npm install @firecrawl/anydoc

ثبّتها لـ Python

pip install firecrawl-anydoc

ثبّتها لـ WebAssembly فالمتصفح

npm install @firecrawl/anydoc-wasm

وتقدر حتى تجرّب العرض التجريبي فالمتصفح. العرض كيشغّل مكتبة WebAssembly محلياً، وبهذا الملفات اللي اخترتي ما كتخرجش من الجهاز.

ثبّتها لـ Rust

cargo add anydoc

ثبّت Agent Skill

باش تعلّم وكيل متوافق كيفاش يحوّل الوثائق باستعمال anydoc CLI، ثبّت المهارة المضمّنة:

npx skills add firecrawl/anydoc

README كيسمّي Claude Code وCodex وCursor وOpenCode ضمن العملاء المتوافقين.

حوّل الملفات باستعمال CLI

كتب Markdown فالإخراج المعياري

مرّر الوثيقة المصدر كأول وسيط. Markdown اللي تولّد كيتطبع فالإخراج المعياري:

npx @firecrawl/anydoc report.docx

هاد الطريقة نافعة ملي بغيتي تشوف النتيجة أو تمرّرها لأمر آخر.

حفظ Markdown فملف

استعمل -o باش تحدّد ملف الإخراج:

npx @firecrawl/anydoc slides.pptx -o slides.md

حوّل البيانات من الإدخال المعياري

استعمل - كمسار الإدخال باش تقرا البايتات من الإدخال المعياري. CSV ما عندوش توقيع موثوق فالمحتوى ديالو، لذلك حدّد الصيغة بشكل صريح:

npx @firecrawl/anydoc - --format csv < data.csv

استعمل anydoc فـ Node.js

حزمة Node.js كتوفّر دوال منفصلة لمسارات الملفات، ومصفوفات البايتات، ونموذج الوثيقة المشترك.

حوّل مسار ملف

import { toMarkdown } from '@firecrawl/anydoc';

const markdown = await toMarkdown('report.docx');
console.log(markdown);

حوّل البايتات

استعمل toMarkdownBytes ملي يكون الملف ترفّع أو تحمّل أو تقرا من قبل فالذاكرة:

import { toMarkdownBytes } from '@firecrawl/anydoc';

const markdown = await toMarkdownBytes(bytes);

بالنسبة للصيغ اللي عندها بصمات معروفة، كيتعرّف anydoc على الصيغة انطلاقاً من المحتوى. CSV ما عندهاش هاد البصمة، لذلك خاصك تمرّر اسم الصيغة:

const markdown = await toMarkdownBytes(bytes, 'csv');

حافظ على نموذج الوثيقة والموارد

إلى كنت محتاج أكثر من سلسلة Markdown النهائية، وقف عند نموذج الوثيقة المشترك باستعمال toDocument:

import { toDocument } from '@firecrawl/anydoc';

const document = await toDocument(bytes);

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

استعمل anydoc فـ Python

حوّل مسار ملف

import anydoc

markdown = anydoc.to_markdown("report.docx")
print(markdown)

حوّل بايتات موجودة فالذاكرة

import anydoc

markdown = anydoc.to_markdown_bytes(data)

سمِّ المدخلات اللي ما عندهاش بصمة، بحال CSV، بشكل صريح:

markdown = anydoc.to_markdown_bytes(data, "csv")

وصل لنموذج الوثيقة

document = anydoc.to_document(data)

هاد الطريقة مفيدة ملي التطبيق ديالك كيحتاج الوثيقة المحلَّلة والموارد المضمَّنة ديالها، وماشي غير Markdown المتسلسل.

حوّل الوثائق فالمتصفح

حزمة WebAssembly كتحوّل مصفوفات البايتات محلياً فالمتصفح. هيّئ الوحدة قبل ما تستعمل دوال التحويل:

import init, { toMarkdownBytes, toDocument } from '@firecrawl/anydoc-wasm';

await init();

const markdown = toMarkdownBytes(bytes);

بحال فالربطيات الأخرى، حدّد الصيغة بالنسبة لـ CSV:

const markdown = toMarkdownBytes(bytes, 'csv');

إلى بغيتي تحتافظ بنموذج الوثيقة والموارد المضمَّنة، استعمل toDocument:

const document = toDocument(bytes);

بخلاف واجهة Node.js المبيّنة من قبل، استدعاءات التحويل ديال WebAssembly فـ README كتكون متزامنة من بعد التهيئة.

استعمل anydoc من Rust

حوّل مسار ملف

let markdown = anydoc::to_markdown("report.docx")?;

حوّل البايتات مع التعرّف التلقائي

let markdown = anydoc::to_markdown_bytes(&bytes, None)?;

حدّد CSV بشكل صريح

let markdown = anydoc::to_markdown_bytes(
    &bytes,
    anydoc::Format::Csv,
)?;

رجّع نموذج الوثيقة

let document = anydoc::to_document(&bytes, None)?;

فهم التعرّف على الصيغ

anydoc كيفحص علامات فالمحتوى بحال ترويسة PDF، ومجموعة RTF الافتتاحية، وأسماء تدفقات OLE، وبيانات حزمة ZIP الوصفية. هاد الشي كيعني أن الملف اللي تسمّى بصيغة خاطئة يقدر يبقى قابل للتحويل إلا كانت الصيغة الحقيقية ديالو ممكنة التحديد من البايتات ديالو.

Rust كيوفّر أدوات مساعدة لفحص البايتات والامتدادات والمسارات:

Format::from_bytes(&bytes);
Format::from_extension("pptm");
Format::from_path(Path::new("report.odt"));

الاستدعاء الأول كيرجّع صيغة مكتشفة بحال Some(Format::Docx)، أو None ملي ما كتطابق حتى علامة معروفة فالمحتوى. كاينين أدوات مساعدة مكافئة فـ Node.js بأسماء بحال formatFromBytes، وفـ Python بأسماء بحال anydoc.format_from_bytes.

علاش CSV كتحتاج معالجة خاصة

CSV نص عادي وما عندهاش بصمة قياسية فالبايتات كتحدّدها بشكل فريد. ملي كتكون كتحوّل بايتات CSV بلا اسم أو من الإدخال القياسي، مرّر csv بشكل صريح. إلا كان مسار الملف فيه الامتداد .csv، فالامتداد يقدر يحدّدها.

تعامل مع أخطاء التحويل

التحويل كيرجّع خطأ ملي ما يمكنش إنتاج Markdown مفيد. Rust كيكشف هاد الحالات من خلال ConvertError:

• Unsupported: الصيغة مجهولة أو ما قابلاش للتحويل، بما فيها PDF اللي فيه غير الصور.
• Malformed: الملف غير صالح من الناحية البنيوية وما يمكنش استخراج محتوى مفيد منو.
• Encrypted: الوثيقة مشفّرة أو محمية بكلمة سر.
• ResourceLimit: التحويل تجاوز حدّاً ثابتاً للسلامة مرتبطاً بفك الضغط أو التداخل أو عدد العقد.
• MissingPart: واحد المكوّن الضروري فالوثيقة ناقص.
• Io: ما قدرش يقرا ملف تمرّر لـ to_markdown.

خط أنابيب لمعالجة دفعات يقدر يسجّل الملفات المشفّرة أو غير المدعومة ويكمّل مع المدخلات الباقية:

match anydoc::to_markdown(path) {
    Ok(markdown) => Some(markdown),
    Err(error @ (ConvertError::Encrypted | ConvertError::Unsupported(_))) => {
        unconverted.push((path, error));
        None
    }
    Err(error) => return Err(error),
}

فـ Node.js وWebAssembly، اسم نوع الخطأ متاح من خلال error.code. Python كيرفع فئة فرعية مخصّصة من anydoc.ConvertError لكل نوع من أنواع التحويل، وكيرفع OSError ملي ما يمكنش قراية ملف.

نصائح متقدمة للدمج

فضّل تحويل البايتات فخطوط معالجة الرفع

إلى كان التطبيق ديالك كيتوصل أصلاً ببايتات الوثائق من رفع أو مخزن كائنات أو استجابة HTTP، استعمل toMarkdownBytes أو to_markdown_bytes. هاد الشي كيتفادى الحاجة لمسار ملف وكيخلّي anydoc يفحص المحتوى الفعلي عوض ما يثق فاسم الملف اللي عطاه المستخدم.

استعمل نموذج الوثيقة ملي كتكون الموارد مهمة

Markdown بوحدو ما فيهش البايتات الخام ديال الكائنات المضمَّنة. استعمل toDocument أو to_document ملي كتحتاج تخزّن أو تفحص أو تعالج الموارد المضمَّنة وأنواع الوسائط ديالها بشكل منفصل.

تعامل مع ملفات PDF الممسوحة ضوئياً بشكل منفصل

الدعم المدمج ديال anydoc لملفات PDF مخصص لملفات PDF اللي فيها نص، وما فيهش OCR. وجّه ملفات PDF اللي غير فيها الصور لسيرورة خدامة بـ OCR، بلا ما تعاود تحاول التحويل المحلي بشكل متكرر.

خلي اختيار صيغة CSV واضح

ملي كتعاالج مدخلات مختلفة مخزّنة فالذاكرة، ربط بيانات CSV الوهمية بمعلومات واضحة على الصيغة. الصيغ الأخرى المدعومة غالباً يمكن اكتشافها من المحتوى ديالها، ولكن CSV خاصها اسم، ولا الامتداد، ولا وسيط صيغة صريح.

استافد من سلوك بيئة التشغيل

التحويل فـ Node.js كيتشغل فـ تجمع خيوط libuv بلا ما يوقف حلقة الأحداث. وPython كتطلق GIL أثناء التحويل، وهاد الشي كيخلي خيوط Python الأخرى تكمل الخدمة. هاد الخصائص مفيدة ملي كتدمج التحويل فالتطبيقات المتزامنة.

استعمل مخرجات موحّدة فالأنظمة اللاحقة

حيت صيغ المكتب كتشارك نفس المُسلسِل، تقدر الأنظمة اللاحقة تتعامل مع بنية وحدة ديال Markdown بلا ما تحافظ على قواعد تنظيف منفصلة لـ Word وPowerPoint وExcel وRTF وOpenDocument. وهاد الشي كيخلي anydoc مناسب بزاف لفهرسة البحث، وسيرورات الاستخراج، وتحضير نص منظم للنماذج اللغوية.

كيفاش كتخدم سيرورة التحويل

1. anydoc كيتفقد بايتات الوثيقة ولا معلومات اسم الملف المتاحة باش يحدد الصيغة.
2. محلّل خاص بكل صيغة كيقرا محتوى Word أو PowerPoint أو Excel أو OpenDocument أو RTF أو EPUB أو CSV.
3. المحلّل كينشئ نموذج مشترك للوثيقة فيه الكتل، والعناصر المضمّنة، والجداول، والحواشي، والموارد.
4. مُسلسِل مشترك كيحوّل هاد النموذج لـ Markdown بصيغة GitHub-Flavored.
5. PDF كيتعالج عبر pdf-inspector وكيتحوّل مباشرة لـ Markdown.

هاد البنية كتعني أن أي تحسين فالمُسلسِل يقدر يفيد صيغ كثيرة فآن واحد. مثلاً، إصلاح تهريب محارف الجدول ما كيبقاش محدود بمحلّل إدخال واحد.

الأداء والاستعمال الأنسب

المستودع كيعرض اختبار أداء على 100 وثيقة حقيقية من أربعة عشر صيغة مجرّبة. anydoc غطّى الصيغ الأربعة عشر كاملين، وحقق مدة تحويل وسطية قدرها 4.4 ميلي ثانية، وحصل على نقطة جودة إجمالية قدرها 81 فهاد المقارنة. الجودة تقيمات من ناحية الاكتمال، والبنية، والتنسيق، والنظافة.

نتائج اختبار الأداء كتبدل حسب مجموعة البيانات، والعتاد، والمنهجية، لذلك استعمل الاختبار المرفق كدليل خاص بالمشروع، ماشي كضمان لكل أعباء العمل. الاستعمال الأنسب اللي كيوصفو المشروع هو سيرورة كتستقبل مجموعة متنوعة ديال وثائق المكتب وكتحتاج Markdown سريع، منظم، وموحّد.

الخلاصة

anydoc كيوفر سيرورة تحويل وحدة عبر Rust وNode.js وPython والمتصفح وسطر الأوامر. بدا بواجهة سطر الأوامر باش تدير اختبار سريع، ومن بعد اختار الربط اللي مناسب للتطبيق ديالك. استعمل التحويل المعتمد على البايتات للملفات المرفوعة، وحدد CSV بشكل صريح، وخلي نموذج الوثيقة ملي كتكون الموارد المضمّنة مهمة، وتعامل مع الوثائق المشفّرة، أو المعطوبة، أو غير المدعومة، أو الممسوحة ضوئياً كحالات منفصلة.