الانتقال إلى المحتوى الرئيسي

​
من الصفر إلى التشغيل في خمس دقائق

انطلق من الصفر إلى نسخة تطوير تعمل في أقل من خمس دقائق.

​
المتطلبات الأساسية

الأداةالإصدارالسبب
Node.js+20بيئة التشغيل للعملية الرئيسية وأدوات البناء
npm+10إدارة الحزم
Gitأي إصدارالتحكم بالمصادر
Ollamaالأحدثاختبار النماذج المحلية (اختياري لكن موصى به)
الوحدات الأصلية مثل better-sqlite3 تُجمّع أثناء التثبيت عبر electron-rebuild. على macOS تحتاج أدوات سطر أوامر Xcode (xcode-select --install). على Linux تحتاج build-essential و python3.

​
الاستنساخ والتثبيت

git clone https://github.com/thewolffish.git
cd wolffish-app
npm install
يقوم سكريبت postinstall بتشغيل electron-rebuild تلقائيًا لتجميع الوحدات الأصلية وفقًا لواجهة Electron ABI الصحيحة.

​
التشغيل في وضع التطوير

npm run dev
يُشغّل هذا electron-vite الذي يبدأ ثلاث عمليات:
العمليةالدورإعادة التحميل
mainNode.js - معالجات IPC، بيئة التشغيل، الخدماتإعادة تشغيل يدوية
preloadcontextBridge - IPC آمن الأنواعإعادة تشغيل يدوية
rendererReact - واجهة المستخدمHMR (فوري)
تنعكس تغييرات العارض (المكونات، الأنماط، الخطافات) فورًا عبر HMR. تغييرات العملية الرئيسية تتطلب إيقاف وإعادة تشغيل npm run dev.

​
الأوامر المتاحة

npm run dev          # Start dev mode with HMR
npm run typecheck    # Full TypeScript check (all configs)
npm run lint         # ESLint
npm run build        # Production build (current platform)
npm run build:mac    # macOS .dmg
npm run build:win    # Windows .exe
npm run build:linux  # Linux .AppImage / .deb
شغّل دائمًا npm run typecheck بعد التغييرات الهيكلية (ملفات جديدة، استيرادات منقولة، واجهات متغيرة). يمكن أن يخفي HMR في Vite أخطاء الأنواع - تطبيقك يعمل بشكل جيد حتى تحاول البناء.

​
أسماء المسارات المستعارة

يستخدم الكود أسماء مسارات مستعارة في كل مكان. لا تستخدم أبدًا المسارات النسبية عبر حدود العمليات. 
// Good
import { Corpus } from "@main/runtime/corpus/corpus";
import { useFlow } from "@providers/flow/useFlow";
import { Button } from "@components/core/button/Button";

// Bad — never cross folders with relative paths
import { Corpus } from "../../../main/runtime/corpus/corpus";
الأسماء المستعارة المتاحة:
الاسم المستعاريُحلّ إلى
@main/*src/main/*
@preload/*src/preload/*
@renderer/*src/renderer/src/*
@components/*src/renderer/src/components/*
@hooks/*src/renderer/src/hooks/*
@lib/*src/renderer/src/lib/*
@pages/*src/renderer/src/pages/*
@providers/*src/renderer/src/providers/*
@resources/*resources/*
استخدم استيرادات ./ النسبية فقط داخل نفس المجلد. لأي شيء آخر، استخدم الاسم المستعار.
الأسماء المستعارة مُعدّة في ثلاثة أماكن:
  • electron.vite.config.ts - دقة Vite
  • tsconfig.web.json - TypeScript للعارض
  • tsconfig.node.json - TypeScript للعملية الرئيسية + preload

​
بنية العمليات الثلاث

┌──────────────────────────────────────────┐
│  main (Node.js)                          │
│  - IPC handlers                          │
│  - Runtime pipeline (15 brain modules)   │
│  - Services (GitHub, Google, Ollama...)  │
├──────────────────────────────────────────┤
│  preload (contextBridge)                 │
│  - Exposes typed IPC to renderer         │
│  - No direct Node.js access in renderer  │
├──────────────────────────────────────────┤
│  renderer (React)                        │
│  - Pages, components, hooks              │
│  - Communicates with main ONLY via IPC   │
└──────────────────────────────────────────┘
لا يستورد العارض أبدًا من @main/* مباشرة. جميع الاتصالات تمر عبر قنوات IPC المعرّفة في طبقة preload.

هيكل المشروع

فهم كيفية تنظيم الكود.

المساهمة

مستعد لتقديم كود؟ اقرأ دليل المساهمة.