التطوير
أعد إعداد مستودع Oleafly لسطح المكتب، وجلب أدواته المرافقة المقيّدة الإصدار، وتشغيل التطبيق، وفهم نقاط الامتداد الرئيسية.
Oleafly تطبيق سطح مكتب مبني على Tauri 2 (يفتح في علامة تبويب جديدة). تتواصل واجهته الأمامية المكتوبة بـReact وTypeScript مع Rust عبر Tauri IPC. وتتولى Rust ملفات المشروع والتجميع والأسرار وتوجيه MCP وطلبات مزوّدي الذكاء الاصطناعي.
تخطيط المستودع
قسم بعنوان “تخطيط المستودع”Oleafly/├── src/ React app shell (stores, Tauri client, UI kit, port adapters)│ ├── components/ ui (shadcn-style), layout, editor glue, preview panes, ai│ ├── contributions/ registers rail tabs / commands / AI toolsets into the registry│ ├── features/ compile, synctex, export│ ├── lib/ tauri wrappers, github, spellcheck, utils, package shims│ └── store/ zustand stores├── packages/ @oleafly/* frontend packages consumed as TS source│ ├── latex/ latex-intelligence/ ai-core/ ai-tools/ registry/│ └── editor/ preview/ diagram/ preflight/ pdf-to-latex/ templates/ wysiwyg/├── crates/│ └── oleafly-agent/ provider clients, streaming, and agent orchestration├── src-tauri/│ ├── src/ Tauri commands, engines, config, Git, MCP, paths, projects│ ├── binaries/ fetched Tectonic, Biber, and Typst sidecars│ ├── resources/ templates, dictionaries, TeX data, language servers│ └── tauri.conf.json├── scripts/fetch-tectonic.sh├── scripts/fetch-biber.sh├── scripts/fetch-typst.sh├── scripts/fetch-language-servers.mjs└── docs/الواجهة الأمامية مساحة عمل pnpm. تعيش الميزات القابلة لإعادة الاستخدام في packages/* خلف منافذ محقونة، ويربط غلاف التطبيق بينها. اقرأ بنية الواجهة الأمامية قبل تعديل packages/: فهي تغطي نمط المنافذ وسجل المساهمات وربط الأسماء المستعارة.
المتطلبات المسبقة
قسم بعنوان “المتطلبات المسبقة”- Node.js 22.13+ وpnpm 11.9+ (يُعلَن إصدار pnpm الدقيق في
package.json) - Rust (الإصدار المستقر) عبر rustup (يفتح في علامة تبويب جديدة)
- تبعيات نظام Tauri 2 (يفتح في علامة تبويب جديدة) لنظام التشغيل لديك
- اختياري أثناء الإعداد: pandoc (يفتح في علامة تبويب جديدة) لتجميع PDF من Markdown وتصدير المستندات (يستطيع التطبيق تثبيت نسخته المقيّدة الإصدار عند الطلب)
التشغيل الأول
قسم بعنوان “التشغيل الأول”pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devلمنصة واحدة، مرّر ثلاثية هدف Rust الخاصة بها إلى كل برنامج نصي جلب. استخدم rustc -vV لمعرفة ثلاثية المضيف. ويختار أمر خوادم اللغة المضيف الحالي ما لم تمرّر هدفًا عبر البرنامج النصي الأساسي له.
العمل اليومي
قسم بعنوان “العمل اليومي”pnpm tauri dev # run the app with hot reload (frontend) + cargo incremental (backend)pnpm build # typecheck + build the frontend (tsc -b && vite build)pnpm tauri build # produce a distributable bundleالفحوص قبل فتح طلب سحب
قسم بعنوان “الفحوص قبل فتح طلب سحب”شغّل الفحوص المحلية ذات الصلة قبل فتح طلب سحب:
pnpm build # frontend typecheck (noUnusedLocals/Parameters on)pnpm test # vitest across src/ and packages/pnpm audit --prod --audit-level high # registry-backed npm advisory checkcargo check --workspace --all-targets # Rust workspace compilescargo deny --manifest-path src-tauri/Cargo.toml check # Rust advisories, licenses, and sourcesيتطلب أمرا التدقيق الوصول إلى السجل والشبكة. تسجّل CI نتائجهما الحالية عند كل تغيير في الشفرة. ولا يستطيع تشغيل محلي بلا اتصال أن يوثّق خلو مخطط التبعيات من التحذيرات الأمنية.
للتغييرات التي تظهر للمستخدم، شغّل أيضًا مجموعة الاختبارات الشاملة (end-to-end) مقابل التطبيق والمجمّع الحقيقيين. انظر e2e/README.md (يفتح في علامة تبويب جديدة).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downكيف يعمل التجميع
قسم بعنوان “كيف يعمل التجميع”- تحمّل الواجهة الأمامية واصف
project_engineمن الواجهة الخلفية وعلامات قدراته، ثم تستدعيcompileProject(projectId, mainDoc, offline)عبر Tauri IPC. - توجّه Rust الطلب عبر
DocumentEngine. لا يجوز لشفرة الواجهة أن تستنتج سلوك المحرك من اسم ملف. - يستخدم LaTeX نسخة Tectonic المدمجة افتراضيًا. ويستطيع المشروع بدلًا من ذلك اختيار pdfLaTeX أو XeLaTeX أو LuaLaTeX عبر
latexmk. وتتقدّم تثبيتات TeX النظامية الكاملة على TinyTeX الذي يديره Oleafly. ويشترط الكاشف المشترك وجود المجمّعات الأساسية وlatexmkوkpsewhichوBiber قبل منح تلك الأولوية. - يشغّل Typst الإصدار الذي يقيّده المشروع في
project.jsonتحديدًا: الأداة المرافقة المدمجة، أو تنزيل يُتحقق من مجموعه الاختباري، أو أمرtypstنظامي يعلن ذلك الإصدار. ويجمّع مستند.typالرئيسي المحدد برسائل تشخيص مقروءة ومسار إخراج PDF صريح. وعند تشغيل Auto compile، تحتفظ Rust بعمليةtypst watchواحدة لكل مشروع بدلًا من ذلك (src-tauri/src/typst_watch.rs). ويغطي الملفdocs/typst-toolchain.mdفي مستودع سطح المكتب التحديد والتثبيت وTinymist المطابق. - يستدعي Markdown برنامج Pandoc مباشرة على ملفات
.md/.markdown، مع مسار إخراج صريح وخيار--pdf-engine=<absolute bundled Tectonic path>. ويذكر دليل Pandoc صراحةً دعم مسار محرك PDF كامل. لا تستبدل هذا بمحركpdflatexنظامي ضمني، لأن حزمة Oleafly الموزعة يجب ألا تعتمد على تثبيت TeX غير معلن. وتعمل العملية بجذر المشروع دليل عمل لها حتى تعمل الصور النسبية وملفات قوائم المراجع وملفات CSL للمستندات الرئيسية في الجذر والمستندات الرئيسية المتداخلة معًا.
تُعرّف وثائق الأدوات المرافقة في Tauri (يفتح في علامة تبويب جديدة) مدخلات bundle.externalBin بلواحق ثلاثية الهدف، وتعرض الأداة المرافقة المحزَّمة باسمها دون لاحقة وقت التشغيل. ويحلّ مهايئ Pandoc في Oleafly مسار تنفيذ Tectonic المحزَّم بجوار ملف تنفيذ التطبيق، بما يطابق تخطيط حزمة Tauri لسطح المكتب. وتغطي اختبارات الوحدة مرشحي حزمة تطبيق macOS ومرشحي debug وrelease لـCargo، بينما يفحص سير عمل الإصدار النسخة الشقيقة المُجهَّزة بلا لاحقة على كل هدف.
تنزيلات Tectonic وBiber وTypst وخوادم اللغة مُنسّقة ومقيّدة بالمجاميع الاختبارية. تتحقق برامج الجلب الخاصة بها من بنية الأرشيف ولا تستخرج إلا مسارات التنفيذ أو الموارد المراجَعة. وتستخدم CI وبنيات الإصدار البرامج النصية نفسها.
- تبثّ جميع المحركات أحداث سجلات وأخطاء موحّدة. تعيد Rust بيانات التجميع الوصفية عبر IPC بصيغة JSON. ويُجلب ملف PDF نفسه على حدة عبر IPC ثنائي خام بدلًا من تضمينه بترميز base64 في النتيجة.
- تعرض الواجهة الأمامية بايتات PDF باستخدام pdf.js وتنشر التشخيصات الموحّدة إلى CodeMirror.
تُعبّر واصفات المحركات عن سياسة التجميع، إضافة إلى ملفات تعريف التنسيق والفحص المسبق للمصدر ومجموعات الميزات والتصدير وأنواع القوالب. وتستخدمها الواجهة الأمامية عبر واصف مخزن الملفات المتوقف عند الفشل بدلًا من التخمين من الامتدادات. انظر مصفوفة محركات المستندات (يفتح في علامة تبويب جديدة).
يُعلن Typst القيمتين supports_synctex=true وsupports_offline=true مع supports_isolated_compile=false. وتمرّ مزامنة المصدر وPDF عبر Tinymist المطابق للمشروع وتحتاج Tinymist 0.13.30 أو أحدث؛ لذلك تخفّض typst_toolchain::describe_project قيمة supports_synctex إلى false للمشروع المقيّد بـTypst 0.11 أو 0.12 (typst_sync::supported_for_project). ويحظر وضع عدم الاتصال تنزيل حزم Typst، فيستخدم التجميع حينها ذاكرة الحزم المشتركة ومجلد typst-packages الخاص بالمشروع فقط. ويبقى التجميع المعزول خاصًا بـLaTeX: يرفض مسار أشكال TikZ مشاريع Typst، وتعرض أدوات الأشكال في المساعد مقتطفات Typst، مثل لوحة CeTZ أو مخطط fletcher، عبر render_typst_snippet بدلًا من ذلك. أضف سلوك محرك فقط بعد أن تصبح قدرة الواجهة الخلفية صادقة. ولا تضف استثناءات واجهة قائمة على الامتدادات.
أين تُخزَّن الحالة
قسم بعنوان “أين تُخزَّن الحالة”- الإعدادات:
~/.oleafly/config.json(بصلاحية0600على Unix). تعيش التفضيلات غير السرية هنا. - الأسرار:
~/.oleafly/ai-secrets.jsonو~/.oleafly/app-secrets.json، مشفّرة بالمفتاح~/.oleafly/ai-secrets.keyالذي يخص المالك وحده. يتشارك GitHub وMCP في ملفapp-secrets.json. وتستخدم بيانات اعتماد مزوّدي الذكاء الاصطناعيai-secrets.json. - المشاريع:
~/.oleafly/projects/<id>/، مجلدات عادية تحتوي.git. - سجل التطبيق:
~/.oleafly/app.log.
نقاط الامتداد الرئيسية
قسم بعنوان “نقاط الامتداد الرئيسية”- إضافة مزوّد ذكاء اصطناعي ← حدّث
crates/oleafly-agent/src/provider.rsثم اعكس بياناته الوصفية للعرض فيpackages/ai-core/src/providers.ts. يحافظ اختبار تكافؤ الفهرس على توافق القائمتين. - إضافة أمر Tauri ← صرّح به في
src-tauri/src/*.rs، وسجّله فيsrc-tauri/src/lib.rs، وغلّفه فيsrc/lib/tauri.ts. - إضافة محرك مستندات ← نفّذ
DocumentEngineفيsrc-tauri/src/document_engine.rs، واعرض قدرات صادقة، وأضف مسار جلب واختبار سريع لأداة مرافقة مقيّدة بمجموع اختباري، ثم استخدم الواصف في عناصر تحكم الواجهة. - إضافة قالب مشروع ← ضع مجلدًا يحمل بيان
template.jsonفيsrc-tauri/resources/templates/(تبقى البيانات الوصفية للقوالب العامة عبر المحركات عملًا مخططًا له). - إضافة أداة للذكاء الاصطناعي ←
packages/ai-tools/src/tools.ts. وتمر خدمات التطبيق التي يحتاجها عبرAiToolsHostفيsrc/lib/ai-tools.ts. - إضافة علامة تبويب جانبية أو أمر لوحة أو شريط أوامر أو مجموعة أدوات ذكاء اصطناعي ← سجّلها في
src/contributions/(انظر بنية الواجهة الأمامية).
داخل المزامنة وGitHub
قسم بعنوان “داخل المزامنة وGitHub”يجري تدفق أجهزة OAuth من جهة الخادم في Rust (src-tauri/src/github.rs) لأن نقاط نهاية OAuth لا تدعم CORS. أما استدعاءات الواجهة البرمجية (api.github.com) فتحدث من الواجهة الأمامية.
أسلوب الشفرة
قسم بعنوان “أسلوب الشفرة”- TypeScript: اتبع الموجود بالفعل. لا تعليقات ما لم تُطلب. احترم
noUnusedLocals/noUnusedParameters. - Rust: أسلوب اصطلاحي، أوامر صغيرة، ورسائل خطأ ودّية.
- الواجهة: Tailwind v4 مع رموز Geist. أعد استخدام العناصر الأولية
ButtonوTooltipوSelect.
الإصدار
قسم بعنوان “الإصدار”تستهدف الحزم macOS Apple Silicon وWindows x64 وLinux x64 وLinux ARM64. تجلب كل بنية أدواتها المرافقة للمجمّعات ومورد خوادم اللغة المدمج وتتحقق منها. وتدعم بنيات الإصدار توقيع Apple وتوثيقه على macOS وتوقيع Azure Artifact Signing على Windows. انظر الإصدار والتثبيت للمستخدم.