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

دليل المطوّر

💡TL;DR

ابدأ بفرع عمل، وثبّت الاعتمادات المقفلة ونسختي المتصفح ثم نفّذ البناء ومجموعة Jest كاملة. عدّل الوحدة المالكة للعقد، وحدث الوثائق واختبارات المزوّد والأدلة في التطبيقات الأصلية مع السلوك.

تجهيز نسخة العمل​

استنسخ المستودع، واقرأ AGENTS.md، وأنشئ فرعًا. تستخدم اختبارات الإضافة Node 20 في Linux وWindows، ويُتحقق من الموقع بـNode 24. ثبّت اعتماداتهما مستقلًا في الجذر وفي website/.

من الجذر:

npm ci
npx --no-install playwright install --with-deps chromium
node node_modules/playwright-chromium/cli.js install chromium
npm run build
npm test -- --runInBand

قد تثبّت حزمتا Playwright مراجعتين مختلفتين من Chromium؛ تثبيت واحدة لا يكفي لبيئة نظيفة. main.js منتج بناء متجاهل في Git؛ حزمة محلية قديمة لا تثبت صحة commit جديد.

حدد المالك قبل التعديل​

المسؤوليةالمصدر الأساسي
دورة حياة الإضافة والأوامر وتوجيه المضيفsrc/main.ts
إعدادات المزوّد وبيانات البروتوكول والتحققsrc/llmProviders.ts
صياغة الطلبات والنقل والمحاولات والتدفقsrc/llmUtils.ts
العمليات والمخططات واختيار CLI العامsrc/operations/, src/cliContracts.ts
مهام الملفات والبحث والترجمةsrc/fileUtils.ts, src/searchUtils.ts, src/translate.ts
تركيب الأفعال والشريط الجانبيsrc/workflowButtons.ts, src/ui/NotemdSidebarView.ts
مواصفات الرسوم وإظهارهاsrc/diagram/, src/rendering/
نصوص الواجهة ولغاتهاsrc/i18n/
الأدلة العامة والترجماتwebsite/docs/, website/i18n/
دليل الصيانة والأدلة المؤرخةdocs/maintainer/

حزمة الإنتاج ذاتية الاكتفاء وتتضمن مضيف المعاينة المدمج. مسار render-host المنفصل المرشح ليس عقد أصل مشحون. لا تفعله دون مزامنة التغليف وأصول الإصدار والتدقيق والوثائق.

تنفيذ تغيير محدد​

  1. أعد إنتاج السلوك واكتب اختبارًا مركزًا يفشل قبل التغيير.
  2. عدّل مالك الثابت، وتحقق من المدخلات الخارجية عند الحد، دون نسخ معرفة المزوّد أو العملية بين المستدعين.
  3. أعد الاختبارات المستهدفة ثم الكاملة؛ غطّ الإلغاء والأخطاء والتخزين عند الكتابة.
  4. حدث الأصل الإنجليزي واللغات المتأثرة. للخطط والمهام وwalkthrough نسختان كاملتان منفصلتان بالإنجليزية والصينية ضمن docs/.
  5. افحص التطبيق المستهلك عند تغيير العرض أو التصدير الأصلي؛ XML أو صورة أو بناء ناجح لا يثبت التحرير أو التصاق الموصلات.

لإضافة مزوّد، عدّل llmProviders.ts واستخدم النقل القائم عند التوافق، وحدث llmProviders.test.ts وllmUtilsProviderSupport.test.ts وREADME واختبارات الاتصال. حافظ على التدفق وتشخيص الاستجابة المنقطعة.

عرّف مخططات الإدخال والنتيجة والسياق والآثار ووسوم التعامل قبل كشف عملية. التسجيل لا ينشئ تلقائيًا نقطة Agent عامة؛ راجع دليل الوكلاء.

التحقق من التغيير​

npm run build
npm test -- --runInBand
npm run audit:i18n-ui
npm run audit:render-host
npm run lint:regressions -- --base-ref origin/main
git diff --check

يقارن lint كل تشخيص بالمرجع؛ الدين القائم أو انخفاض العدد الإجمالي لا يبرران خطأ جديدًا. استخدم npm run benchmark:local-kb عند تعديل الاسترجاع، واذكر مجموعة البيانات والبيئة بدل ضمان سرعة عام.

للموقع استخدم Node 24:

npm --prefix website ci
npm --prefix website run build
npm --prefix website run audit:build
npm run docs:build

يكتب Codex ترجمات برنامج 1.9.9 ويراجعها مباشرة. لا تشغّل نصوص الترجمة القديمة ولا تستدعِ LM Studio أو API ترجمة لإعداد الوثائق. يمكن للأدوات تنسيق النص المكتوب وفحصه وعرضه.

الاختبار في Obsidian والتطبيقات الأصلية​

استخدم خزنة مؤقتة. تتطلب نصوص المضيف العلامة .notemd-host-verification وتتحقق من الحزمة المنسوخة؛ لا تستخدم خزائن حقيقية. جرّب obsidian help وobsidian-cli help وسجّل غياب الأدوات، ولا تعتبر أمرًا وهميًا دليل مضيف ناجح.

لاختبارات PowerPoint وCircuitikZ والشرائح متطلبات وأصول خاصة. اتبع سجل القبول ودليل الإصدار. أبقِ عدم تحقق المحمول والنسخة الدنيا واضحًا.

المساهمة والإصدار​

صف في PR المشكلة والسلوك النهائي والاختبارات والحدود. استخدم Issues لبلاغ قابل للتكرار. لا تضف مفاتيح أو مواد خزنة خاصة أو منتجات غير مرتبطة.

يمتلك الناشر ودليل المستودع مسار الإصدار: بيانات متفقة، tag رقمي، مصدر نظيف، وصف ثنائي اللغة وأصول مسودة متحققة، ثم نشر وإطلاق Pages صريح. لا تنقل tag عامًا لتبديل حزمته. .trellis/ حالة عمل محلية وليست اعتماد CI.

الخطوات التالية​