الفصل 38: إعداد مزامنة GitHub

تحوّل مزامنة GitHub مساحة عمل SeaMeet الخاصة بك إلى شجرة Markdown خاصة خاضعة للتحكم في الإصدارات تعيش في مستودع GitHub الخاص بك. في كل مرة تعدّل فيها ملاحظة أو تعيد تسمية تسجيل أو تعدّل صفحة wiki، يلتزم SeaMeet بهدوء بالتغيير في الخلفية ويدفعه إلى GitHub. افتح SeaMeet على لاب توب مختلف وتُسحب ملاحظاتك عند الإطلاق الأول — لا Dropbox في المنتصف، لا خادم Seasalt في الحلقة. المستودع ملك لك، البيانات ملك لك، ويمكنك تصفحها مباشرة على github.com إن أردت في أي وقت.

النموذج بسيط: مستودع GitHub الخاص بك هو التخزين. لا يدير SeaMeet خدمة مزامنة. يثبّت تطبيق GitHub صغيرًا على حسابك، يحصل على رمز OAuth لكل مستخدم، ويستخدم هذا الرمز لدفع وسحب التزامات Git مباشرة. لأن التخزين هو المستوى المجاني لـ GitHub — الذي يمنحك مستودعات خاصة غير محدودة — المزامنة مجانية فعليًا. ولأن كل مساحة عمل SeaMeet هي مستودعها الخاص، يمكنك إبقاء مساحات عمل العمل والشخصية منفصلة تمامًا.

أهداف الفصل

بعد قراءة هذا الفصل، ستكون قادرًا على:

تثبيت تطبيق SeaMeet GitHub على حسابك أو منظمتك
تخويل SeaMeet عبر OAuth والسماح له بإنشاء مستودع مزامنة خاص لك
قراءة شريط حالة المزامنة وفهم كل حالة في آلة حالة المزامنة
التعرف على متى تم تحديث OAuth تلقائيًا في الخلفية ومتى تحتاج إلى إعادة التخويل يدويًا
حل تعارض المزامنة عندما تم تحرير نفس الملاحظة على جهازين
ضبط لوحة Sync Settings (المزامنة التلقائية وفاصل المزامنة والمزامنة عند بدء التشغيل)
استكشاف أكثر أوضاع الفشل شيوعًا

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

قبل البدء، تأكد من أن لديك:

حساب GitHub — المستوى المجاني مناسب؛ لا تحتاج إلى GitHub Pro
اشتراك مزامنة نشط — مضمّن مع مستويات BYOK Pro وSync Pro. إذا كان مستوى الفوترة الخاص بك لا يتضمن المزامنة، ستظهر شاشة Sync Settings لافتة "Subscribe to enable sync". انظر الفصل 35: الاشتراك والفوترة لتفاصيل الخطة.
مساحة عمل مفتوحة في SeaMeet — تربط المزامنة بمساحة العمل النشطة، وليس بالتطبيق ككل. إذا كان لديك مساحات عمل متعددة، فإن كل واحدة هي مستودع GitHub الخاص بها.
وصول إنترنت يعمل — يفتح تدفق الإعداد GitHub في متصفحك الافتراضي

مستودع واحد لكل مساحة عمل. ينشئ SeaMeet مستودعًا خاصًا منفصلًا لكل مساحة عمل تربطها. يبقي هذا ملاحظات العمل والملاحظات الشخصية معزولة بشكل نظيف ويعني أنه يمكنك فصل واحد دون لمس الآخر.

إعداد خطوة بخطوة

يستغرق الإعداد لأول مرة حوالي 90 ثانية: تخويل SeaMeet على GitHub، السماح له بإنشاء مستودعك، انتظار التحميل الأولي، وأنت منتهٍ.

الخطوة 1: افتح Sync Settings

انقر أيقونة ترس Settings
افتح علامة تبويب Sync في القضيب الأيسر
سترى بطاقة رأس "Sync with GitHub"

إذا لم ترَ علامة تبويب Sync، فإن مستوى اشتراكك لا يتضمن المزامنة — انظر الفصل 35 للترقية.

إذا رأيت لافتة تقرأ "Back up your notes to a private GitHub repo with BYOK Pro"، فلديك حساب مجاني. انقر اللافتة لفتح بوابة الدفع، أو تخطّى بقية هذا الفصل حتى تشترك.

الخطوة 2: انقر "Set Up GitHub Sync"

تعرض الحالة الفارغة لـ Sync Settings ثلاث بلاطات فوائد ("Free & private" و"Effectively unlimited" و"One repo per workspace") وزر أساسي Set Up GitHub Sync في الأسفل.

انقر عليه. يفتح متصفحك الافتراضي صفحة تخويل GitHub.

الخطوة 3: ثبّت تطبيق SeaMeet GitHub (لمرة واحدة)

في المرة الأولى التي تخوّل فيها SeaMeet، سيطلب GitHub منك تثبيت تطبيق SeaMeet GitHub على حسابك. هذه خطوة لمرة واحدة لكل حساب GitHub (أو لكل منظمة، إذا أردت المزامنة إلى مستودع مملوك لمنظمة).

على صفحة تثبيت GitHub:

اختر الحساب أو المنظمة التي تريد أن يكتب SeaMeet إليها
اختر إما "All repositories" أو "Only select repositories" — يحتاج تطبيق SeaMeet إلى أذونات contents: write وadministration: write ليتمكن من إنشاء مستودع المزامنة نيابة عنك
انقر Install & Authorize

يعيدك GitHub إلى SeaMeet. تعرض لوحة Sync Settings الآن:

┌──────────────────────────────────────────────────────┐
│   ✓ مخوَّل                                            │
│   ⟳ جاري إنشاء المستودع والتحميل...                  │
└──────────────────────────────────────────────────────┘

لماذا تطبيق GitHub وليس رمز OAuth عادي؟ تحتوي تطبيقات GitHub على أذونات دقيقة لكل مستودع ورموز تحديث متناوبة. لدى SeaMeet فقط وصول كتابة إلى المستودعات التي اخترتها صراحة، وينتهي صلاحية رمز وصول OAuth كل 8 ساعات — حتى لو تسرب، ستكون النافذة صغيرة. (انظر قسم التحديث التلقائي لـ OAuth أدناه لكيفية إبقاء SeaMeet ذلك غير مرئي لك.)

الخطوة 4: إنشاء المستودع (تلقائيًا)

يستدعي SeaMeet الآن GitHub API نيابة عنك و:

ينشئ مستودعًا خاصًا باسم مساحة عملك (مثلًا seameet-work-notes)
يهيّئ مستودع Git محلي داخل مجلد مساحة عملك إذا لم يكن موجودًا بالفعل
يشغّل git init، يكتب .gitignore يستبعد ملفات الصوت/الفيديو/لقطات الشاشة، ويُجري التزامًا أوليًا
يضيف مستودع GitHub الجديد كـ origin
يدفع الالتزام الأولي

سترى شريط الحالة في أسفل الشريط الجانبي ينتقل عبر:

جاري إنشاء المستودع...  →  جاري المزامنة...  →  مُزامن · للتو

هذا كل شيء. مساحة عملك الآن مدعومة بـ GitHub.

الخطوة 5: تعمل أول مزامنة تلقائيًا

من الآن فصاعدًا، يلتزم SeaMeet تلقائيًا كل 5 دقائق (افتراضيًا) كلما كانت لديك تغييرات غير محفوظة، ويدفع إلى GitHub فورًا بعد كل التزام. عند الإطلاق التالي لـ SeaMeet، يسحب التطبيق من GitHub قبل أن تبدأ التحرير حتى — لذا تظهر التغييرات التي تمت على جهاز آخر في اللحظة التي يفتح فيها التطبيق.

آلة حالة المزامنة

يدير SyncManager في SeaMeet آلة حالة صغيرة ويبث حالتها الحالية إلى العارض. يقرأ كل من SyncStatusBar في الشريط الجانبي ولوحة Sync Settings من هذه الحالة. يساعد فهم الحالات في قراءة واجهة المستخدم بدقة.

                      ┌─────────────┐
                      │    idle     │ ◄──────┐
                      └──────┬──────┘        │
                             │ تغيير ملف     │
                             ▼               │
                      ┌─────────────┐        │
                ┌────►│   pending   │        │
                │     └──────┬──────┘        │
       تغيير    │            │ مؤقت الالتزام  │
       ملف      │            ▼               │
                │     ┌─────────────┐        │
                │     │ committing  │        │
                │     └──────┬──────┘        │
                │            ▼               │
                │     ┌─────────────┐        │
                │     │   pushing   │        │
                │     └──────┬──────┘        │
                │            ▼               │
                │     ┌─────────────┐        │
                │     │   synced    │── 5s ──┘
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤   pulling   │  (بدء التشغيل أو دفع مرفوض)
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤  conflict   │  → يحل المستخدم → syncing → synced
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤   offline   │  → الشبكة عادت → إعادة محاولة
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤   timeout   │  → ينقر المستخدم Retry
                │     └─────────────┘
                │
                │     ┌────────────────┐
                └─────┤ token-expired  │ → بطاقة إعادة التخويل
                      └────────────────┘

إليك ما تعنيه كل حالة في واجهة المستخدم:

الحالة	تسمية شريط الحالة	ما تعنيه
idle	"مُزامن · منذ دقيقتين"	لا شيء معلق، آخر التزام كان نظيفًا
pending	"معلق..."	لديك تغييرات غير محفوظة؛ سيطلق مؤقت الالتزام في الفاصل التالي
committing	"جاري المزامنة..."	التزام Git قيد التقدم محليًا
pushing	"جاري الدفع..."	اكتمل الالتزام المحلي؛ جاري الدفع إلى GitHub
pulling	"جاري السحب..."	إما مزامنة بدء التشغيل، أو رُفض الدفع ونحن نسحب أولًا
syncing	"جاري المزامنة..."	إنهاء rebase بعد حل التعارض
synced	"مُزامن · للتو"	نجاح اكتمل للتو؛ يُعرض لمدة 5 ثوانٍ، ثم يعود إلى idle
conflict	"تعارض المزامنة"	عدّل كل من المحلي والبعيد نفس الملف. تطفو واجهة المستخدم تدفق حل التعارض.
error	"خطأ مزامنة"	فشل غير شبكة وغير تعارض (مثلًا فشل git). يعيد المحاولة تلقائيًا بتراجع أسي حتى 5 مرات.
offline	"غير متصل"	الشبكة غير قابلة للوصول. ستعيد المحاولة على تغيير الملف التالي أو بعد 60 ثانية.
timeout	"انتهت مهلة المزامنة"	استغرق أمر git أكثر من 60 ثانية (انظر حماية مهلة المزامنة أدناه)
token-expired	"إعادة التخويل"	فشل تحديث OAuth ويجب على المستخدم إعادة التخويل يدويًا
installing-app	"جاري تثبيت تطبيق GitHub..."	في انتظار إنهاء المستخدم لخطوة تثبيت تطبيق GitHub في متصفحه
creating-repo	"جاري إنشاء المستودع..."	تدفق الإعداد يقوم بإنشاء مستودع GitHub ودفع الالتزام الأولي

إذا كان شريط الحالة يعرض مؤشر دوران، فهذا نشاط خلفية طبيعي. إذا كان كهرمانيًا أو أحمر، فانظر قسم استكشاف الأخطاء وإصلاحها أدناه.

التحديث التلقائي لـ OAuth

تصدر تطبيقات GitHub رموز وصول مستخدم تنتهي صلاحيتها كل 8 ساعات، بالإضافة إلى رمز تحديث صالح لمدة 6 أشهر. يدير SeaMeet هذا لك حتى لا تضطر تقريبًا أبدًا للتفكير فيه.

كيف يعمل:

عندما يكون SeaMeet على وشك الدفع أو السحب، يتحقق SyncManager._refreshTokenIfNeeded() مما إذا كان الرمز الحالي ينتهي خلال 5 دقائق القادمة.
إذا كان نعم، يستدعي SeaMeet نقطة نهاية /login/oauth/access_token في GitHub مع رمز التحديث المخزّن. يعيد GitHub رمز وصول جديدًا ويدوّر رمز التحديث. يكتب SeaMeet كليهما إلى ملف الرمز المشفّر على القرص.
ثم يعمل أمر Git بالرمز المحدّث حديثًا. لا ترى شيئًا على الشاشة — يستغرق التحديث بأكمله أقل من ثانية بكثير.

معالجة الفشل العابر: إذا فشلت مكالمة التحديث لأن الشبكة غير مستقرة أو أعاد GitHub 5xx (REFRESH_NETWORK_ERROR)، لا يلقي SeaMeet الرمز الموجود. بدلًا من ذلك تذهب المزامنة إلى حالة offline وتحاول مرة أخرى لاحقًا. هذا مهم لأن الرمز الموجود قد لا يزال صالحًا لعدة دقائق أخرى — التخلص منه على عطل شبكة عابر سيسجل خروجك من المزامنة دون داع.

ضمّ التحديث المتزامن: يدوّر GitHub رمز التحديث في كل مرة تستخدمها، لذا سيتنافس تحديثان متزامنان وسيُبطل أحدهما الآخر. يطوي SeaMeet مكالمات التحديث المتزامنة إلى Promise واحد قيد التشغيل (_refreshPromise) حتى لا تتقاتل مزامنة بدء التشغيل ودفع مع إعادة المحاولة على الرمز الدوار.

عندما يفشل التحديث حقًا: إذا أعاد GitHub REFRESH_TOKEN_EXPIRED — يعني أن رمز التحديث لمدة 6 أشهر قد انتهت صلاحيته أو تم إلغاؤه — يقوم SeaMeet:

حذف ملف الرمز المشفر من القرص
الدخول إلى حالة token-expired النهائية
عرض بطاقة كهرمانية في Sync Settings:

┌──────────────────────────────────────────────────────┐
│ ⚠  انتهت صلاحية تخويل GitHub. يرجى                   │
│    إعادة التخويل لاستئناف المزامنة.                  │
│                                                       │
│  [ ↻ إعادة تخويل GitHub ]                            │
└──────────────────────────────────────────────────────┘

انقر Re-authorize GitHub. تُعاد إرسالك عبر تدفق OAuth — لكن لأن تطبيق GitHub مثبّت بالفعل، فهي نقرة واحدة للتأكيد وأنت منتهٍ في حوالي 10 ثوانٍ. ثم يجرد SeaMeet أي رمز قديم من git config المحلي الخاص بك (قد يكون الرمز القديم مضمنًا في URL origin) قبل الدفع التالي، حتى لا تدور على بيانات اعتماد ميتة.

حماية مهلة المزامنة

يمكن أن تتعلق أوامر Git إلى الأبد إذا توقفت الشبكة في منتصف النقل — قد يجلس قابس TCP في حالة نصف مفتوحة دون أن يثير خطأ أبدًا. يلف SeaMeet كل دفع وسحب Git في مهلة AbortController لمدة 60 ثانية.

إذا لم يكتمل دفع أو سحب في 60 ثانية، يقوم SeaMeet:

إجهاض عملية git الفرعية
الدخول إلى حالة timeout
عرض بطاقة كهرمانية في Sync Settings:

┌──────────────────────────────────────────────────────┐
│ ⚠  انتهت مهلة المزامنة. قد يكون هذا بسبب مشكلة شبكة  │
│    أو تخويل GitHub منتهي الصلاحية.                   │
│                                                       │
│  [ ↻ إعادة محاولة المزامنة ]   [ إعادة تخويل GitHub ]│
└──────────────────────────────────────────────────────┘

Retry Sync يشغّل commitNow مرة أخرى. هذا هو الزر المناسب للنقر إذا كنت تعتقد أن شبكتك سقطت لفترة وجيزة. Re-authorize GitHub يشغّل تدفق OAuth مرة أخرى؛ انقر هذا إذا استمرت المهلة في التكرار، مما يعني عادة أن رمزك هو المشكلة وليس الشبكة.

تعود الحالة إلى idle تلقائيًا بعد حوالي 30 ثانية حتى لو لم تنقر على أي شيء — ستحاول المزامنة على تغيير الملف التالي.

حل التعارضات

يحدث تعارض عند تحرير نفس الملف على جهازين منذ آخر مزامنة. مثال: كتبت فقرة في meetings/2026-06-03-standup.md على لاب توبك، ثم عدّلت لاحقًا نفس الفقرة على جهاز صديق. عندما يدفع الجهاز الثاني، يرفض GitHub الدفع لأن التواريخ تتباعد.

يتعامل SeaMeet مع هذا من خلال:

سحب التغييرات البعيدة بـ rebase
اكتشاف علامات تعارض الدمج
الدخول إلى حالة conflict
إظهار التعارض في شريط حالة الشريط الجانبي (الذي يصبح قابلًا للنقر) وفي لوحة تعارض Sync Settings

نموذج حل التعارضات

النقر على شريط الحالة عند المزامنة في conflict يفتح نموذج حل التعارضات:

┌──────────────────────────────────────────────────────────┐
│  ⚠  تعارض المزامنة                  1 / 2          [×]  │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  تم تغيير "2026-06-03-standup.md" على جهاز آخر.          │
│                                                          │
│  ┌────────────────────────┐  ┌────────────────────────┐  │
│  │ ✎  تحرير يدويًا         │  │ ✦  دمج بواسطة الوكيل   │  │
│  └────────────────────────┘  └────────────────────────┘  │
│                                                          │
└──────────────────────────────────────────────────────────┘

لديك خياران:

تحرير يدويًا — يفتح ملف التعارض في محرر النظام الافتراضي الخاص بك مع علامات Git القياسية <<<<<<< / ======= / >>>>>>> في مكانها. عدّل الملف لحلها، احفظ، ثم عد إلى SeaMeet وانقر Done. يضع SeaMeet الملف المحلول ويستمر في rebase.

دمج بواسطة الوكيل (BYOK Pro فقط، يتطلب تكوين AI Agent) — يرسل كلا الإصدارين إلى AI Agent المُكوّن لديك (GitHub Copilot أو Claude Code، انظر الفصل 36: دليل إعداد BYOK) ويطلب منه إنتاج إصدار مدمج يحتفظ بنوايا الجانبين. يتم وضع إخراج الوكيل تلقائيًا؛ سترى مؤشر دوران "إنهاء المزامنة..." بينما يكتمل rebase.

إذا كانت هناك تعارضات متعددة في وقت واحد، يعرض النموذج عدّادًا (1 / 2 و2 / 2) وأسهم سهام في لوحة تعارض Sync Settings حتى تتمكن من الخطو من خلالها واحدة في كل مرة.

"احتفظ بمنجم" / "احتفظ بهم" / "احتفظ بكليهما" خيارات تأتي كاختيارات طبيعية عندما تكون داخل المحرر اليدوي: اترك نص إصدارك فقط بين العلامات أو نص الإصدار البعيد فقط أو تشابك كليهما. زر الدمج بواسطة الوكيل يفعل فعليًا "احتفظ بكليهما، بذكاء."

ماذا لو ارتكبت خطأ؟ تعارضات المزامنة غير مدمرة. يحتفظ Git بمحتوى "ours" و"theirs" الأصلي في الفهرس، ويمكن لـ getConflictVersions(filePath) استرداد أي منهما في أي نقطة أثناء الحل. لن تفقد العمل عن طريق الخطأ.

لوحة Sync Settings

بمجرد اتصالك، تمنحك Sync Settings (Settings → Sync) شاشة واحدة بكل شيء في مكان واحد:

┌─────────────────────────────────────────────────────────────┐
│  ✓ المزامنة والنسخ الاحتياطي                                │
│  ملاحظاتك وويكي يتم مزامنتها تلقائيًا إلى GitHub.            │
│  لا تتم مزامنة التسجيلات الصوتية والمرئية ولقطات الشاشة.   │
├─────────────────────────────────────────────────────────────┤
│  ⓘ  https://github.com/you/seameet-work-notes                │
│  🕒 آخر مزامنة: منذ 4 دقائق                                  │
├─────────────────────────────────────────────────────────────┤
│  المزامنة التلقائية                              [ تشغيل ◉ ]│
│  فاصل المزامنة                                  [ 5 دقائق ▾]│
│  الفرع                                              main    │
│  آخر مزامنة                                منذ 4 دقائق      │
├─────────────────────────────────────────────────────────────┤
│  مزامنة تلقائية على التغييرات                  [ تشغيل ◉ ] │
│  مزامنة عند بدء التشغيل                          [ تشغيل ◉ ]│
├─────────────────────────────────────────────────────────────┤
│  [ ⤓ المزامنة الآن ]                                        │
├─────────────────────────────────────────────────────────────┤
│  [ ↗ عرض على GitHub ]    [ قطع الاتصال ]                    │
└─────────────────────────────────────────────────────────────┘

عناصر التحكم، من الأعلى إلى الأسفل:

Auto-sync — مفتاح رئيسي لمؤقت الالتزام الخلفي. الإيقاف يعني أن SeaMeet يلتزم فقط عند النقر على Sync Now.
Sync interval — كم مرة يطلق مؤقت الالتزام. الخيارات هي 1 / 5 / 10 / 30 دقيقة. الافتراضي 5 دقائق. فاصل دقيقة واحدة مناسب لتدوين الملاحظات النشط؛ 30 دقيقة جيدة لمساحات العمل قليلة التحرير حيث تفضل تجميع الالتزامات.
Branch — فرع Git الذي يزامنه SeaMeet. تقريبًا دائمًا main. للقراءة فقط في واجهة المستخدم.
Last synced — طابع زمني نسبي لآخر دفع ناجح.
Auto-sync on changes — عند التشغيل، تحدث الدفعات فورًا بعد كل التزام محلي (الحالة النموذجية). عند الإيقاف، يلتزم SeaMeet محليًا لكن يدفع فقط عند النقر على Sync Now. مفيد إذا أردت تجميع الدفعات (مثلًا على اتصال مقنّن).
Sync on startup — عند التشغيل، يسحب SeaMeet من GitHub لحظة إطلاق التطبيق. موصى به ما لم يكن لديك اتصال بطيء جدًا.
Sync Now — فرض دورة التزام-ودفع فورية. لا تنتظر المؤقت. مفيد قبل إغلاق لاب توبك.
View on GitHub — يفتح المستودع في متصفحك.
Disconnect — يمسح رمز OAuth المخزّن ويحذف ملف الرمز المشفر ويزيل origin من مستودع Git المحلي. ملفات Markdown المحلية وتاريخ Git غير ملموسين — فقط الرابط إلى GitHub مقطوع.

ما يتم مزامنته (وما لا يتم)

هذا موثّق في فهرس الجزء، لكنه يستحق التكرار هنا:

مُزامن	غير مُزامن
الملاحظات (ملفات `.md`)	التسجيلات الصوتية (`.webm` و`.mp3`)
صفحات Wiki (ملفات `.md`)	التسجيلات المرئية (`.webm` و`.mp4`)
بيانات التسجيلات الوصفية (JSON البيانات الوصفية)	لقطات الشاشة (`.png` و`.jpg`)
ملخصات ونسخ الذكاء الاصطناعي	توليدات الذكاء الاصطناعي المخزّنة مؤقتًا
رسم الروابط الويكية	إعدادات التطبيق
`.gitignore`	حالة المسودة للمحرر

يستبعد .gitignore الذي يكتبه SeaMeet جميع فئات الثنائيات الكبيرة. هذا متعمد: تصل المستودعات الخاصة المجانية لـ GitHub إلى 1 جيجابايت، وسيلتهم فيديو لمدة 30 دقيقة ذلك بمفرده. يبقي SeaMeet الوسائط على قرصك المحلي ويزامن فقط Markdown الخفيف.

إذا أردت مزامنة وسائط كاملة، فهذا هو مستوى Sync Pro — انظر الفصل 35.

استكشاف الأخطاء وإصلاحها

"فشل التخويل" مباشرة بعد النقر على Set Up GitHub Sync

الأسباب والإصلاحات:

حاجب النوافذ المنبثقة — إذا لم تفتح نافذة متصفح، فقد يكون نظام التشغيل أو المتصفح قد حجب الإطلاق. انقر Set Up GitHub Sync مرة أخرى وأكّد أي مطالبات النوافذ المنبثقة.
رفضت أذونات تطبيق GitHub — ارجع عبر التدفق واقبل نطاقات contents: write + administration: write. بدون administration: write لا يمكن لـ SeaMeet إنشاء المستودع لك.
خطأ عدم تطابق الحالة — أغلق أي نوافذ SeaMeet أخرى قد تتسابق على نفس تدفق OAuth، ثم أعد المحاولة.

خطأ "أذونات المستودع" أثناء الإعداد

يقرأ الخطأ شيئًا مثل "تطبيق GitHub لديه إذن 'contents: read'، لكنه يحتاج إلى 'contents: write'." هذا يعني أنك ثبّت إصدارًا أقدم من التطبيق.

الإصلاح:

افتح github.com/settings/installations
ابحث عن SeaMeet في القائمة وانقر Configure
تحت أذونات المستودع، غيّر Contents وAdministration إلى Read and write
احفظ، ثم إلغ التثبيت وأعد التثبيت للتطبيق — يطبق GitHub الأذونات الجديدة فقط عند إعادة التثبيت
أعد تشغيل Set Up GitHub Sync في SeaMeet

"تعذّر الوصول إلى GitHub" / المزامنة عالقة في "Offline"

فشل الشبكة. سيعيد SeaMeet المحاولة تلقائيًا عندما:

تجري أي تغيير ملف (يطلق محاولة إعادة فورية)
ينقضي 60 ثانية من آخر إعادة محاولة

إذا عادت شبكتك وما زالت المزامنة تعرض Offline بعد بضع دقائق:

انقر Sync Now لفرض إعادة محاولة
إذا انتهت مهلة ذلك: تحقق من أن جدار الحماية لا يحجب github.com
كملاذ أخير، أعد تشغيل SeaMeet — ستطلق مزامنة بدء التشغيل عند الإطلاق

المزامنة عالقة في "Pending"

هذا يعني عادة أن مؤقت الالتزام التلقائي لم يطلق بعد. افتراضيًا يطلق كل 5 دقائق. لا تريد الانتظار؟ انقر Sync Now.

إذا لم ينقل Sync Now المزامنة بعد Pending، تحقق:

هل أنت على مستوى فوترة يتضمن المزامنة؟ افتح Sync Settings — إذا رأيت لافتة الاشتراك، فإن المزامنة معطلة في طبقة الاشتراك.
هل توجد تغييرات غير ملتزم بها خارج شجرة Markdown؟ يطلق مؤقت الالتزام التلقائي فقط عندما يكون _pendingChanges غير فارغ.

"أرى بطاقة token-expired"

هذه هي النهاية المتوقعة لدورة حياة تحديث OAuth — انتهت صلاحية رمز التحديث لمدة 6 أشهر، أو ألغيت تطبيق GitHub، أو غيّرت كلمة مرور GitHub (مما يبطل جميع رموز OAuth).

الإصلاح: انقر Re-authorize GitHub في البطاقة. التدفق هو نفسه الإعداد الأولي لكن يتخطّى خطوة تثبيت تطبيق GitHub (لديك بالفعل مثبّت). يستغرق حوالي 10 ثوانٍ.

لوحة حل التعارضات لن تغلق

تغلق اللوحة فقط بمجرد حل جميع التعارضات في القائمة. إذا رأيت العدّاد (1 / 3)، استخدم أسهم الأسهم في لوحة تعارض Sync Settings للخطو عبر الملفات المتبقية. تحتاج كل واحدة إلى حل صريح (تحرير يدوي + Done، أو دمج بواسطة الوكيل).

إذا أصرت اللوحة على وجود تعارضات لكنك لا ترى أي علامات في ملفاتك، انقر Sync Now — ستُمسح حالة conflict القديمة في محاولة المزامنة الناجحة التالية.

حلقات "رفض الدفع"

إذا تبدّلت المزامنة بين pushing وpulling بشكل متكرر، فإن GitHub يرفض دفعاتك لأن البعيد يستمر في التحرك للأمام. يمكن أن يحدث هذا إذا:

يعمل مثيل SeaMeet آخر مقابل نفس المستودع ويدفع أسرع مما يمكن لهذا أن يلحق — أغلق المثيل الآخر.
يلتزم شخص ما (أو أداة ما) بمستودع GitHub من خارج SeaMeet — أوقف الأداة الخارجية حتى يلحق نسختك المحلية.

ملاحظات الأمان

أين يُخزّن رمز OAuth: في keychain نظام تشغيلك عبر API safeStorage الخاص بـ Electron. على Windows هو DPAPI، على macOS هو Keychain Services، على Linux هو libsecret. يُكتب الكتلة المشفّرة إلى <userData>/github-token.enc بوضع ملف 0o600. يحمل الملف رمز الوصول ورمز التحديث وطابع وقت انتهاء الصلاحية ومعرّف عميل تطبيق GitHub وسرّ العميل وslug.

ما لا يُخزّن في argv: لا يُمرَّر رمز OAuth أبدًا كوسيطة -c http.extraHeader=... إلى git، لأن argv مرئية للمستخدمين الآخرين عبر ps aux. بدلًا من ذلك يُحقن رأس Authorization عبر متغير بيئة GIT_CONFIG_PARAMETERS، الذي هو خاص بالعملية. لا يمكن للمستخدمين الآخرين على نفس الجهاز رؤية رمزك.

ما ينتهي على القرص في المستودع: ملفات Markdown عادية. لا رموز، لا أسرار، لا بيانات اعتماد. يستبعد .gitignore ملفات الوسائط، لكن يجب أن تتجنب لصق الأسرار في أجسام الملاحظات — ستتم مزامنتها.

إلغاء الوصول: لقطع وصول SeaMeet إلى مستودع فورًا، ألغِ تثبيت تطبيق SeaMeet GitHub على github.com/settings/installations. ستفشل محاولة المزامنة التالية بـ token-expired وسيمسح SeaMeet رمزه المحلي. ملاحظاتك المحلية غير ملموسة.

مرجع سريع

┌─────────────────────────────────────────────────────────────┐
│                   مزامنة GitHub                              │
│                   مرجع سريع                                  │
├─────────────────────────────────────────────────────────────┤
│  افتح Sync Settings    │ Settings → Sync                    │
│  الإعداد لأول مرة      │ انقر "Set Up GitHub Sync"          │
│  النطاقات المطلوبة     │ contents: write, admin: write      │
│  تسمية المستودع        │ مستودع خاص واحد لكل مساحة عمل      │
├─────────────────────────────────────────────────────────────┤
│  فاصل المزامنة الافتراضي│ 5 دقائق (1 / 5 / 10 / 30)         │
│  فرض مزامنة            │ زر "Sync Now"                      │
│  مزامنة تلقائية على دفع│ تشغيل (تبديل في Sync Settings)     │
│  مزامنة عند بدء التشغيل│ تشغيل (تبديل في Sync Settings)     │
├─────────────────────────────────────────────────────────────┤
│  هامش تحديث OAuth      │ 5 دقائق قبل انتهاء الصلاحية         │
│  مهلة أمر Git          │ 60 ثانية (AbortController)         │
│  حد إعادة المحاولة     │ 5 محاولات، تراجع أسي                │
│  تخزين الرمز           │ keychain نظام التشغيل (safeStorage)│
├─────────────────────────────────────────────────────────────┤
│  واجهة التعارض         │ انقر شريط الحالة عند التعارض       │
│  حل يدوي               │ عدّل العلامات → Done                │
│  دمج بواسطة الوكيل      │ BYOK Pro + AI Agent مكوّن          │
├─────────────────────────────────────────────────────────────┤
│  قطع الاتصال           │ Sync Settings → Disconnect         │
│  إلغاء من GitHub       │ github.com/settings/installations  │
│  عرض المستودع          │ رابط "View on GitHub"               │
└─────────────────────────────────────────────────────────────┘

آخر تحديث: 2026-06-05

← الفصل 37: مزود GitHub Copilot | (نهاية الدليل — العودة إلى الفهرس)