CodeAlmanac: دليل عملي لتحويل محادثاتك مع AI إلى ويكي كود مفتوح المصدر
Show HN: CodeAlmanac – Karpathy-style codebase wiki from your conversations
خريطة الصفحة
اختر القسم الذي تحتاجه الآن
- ما المشكلة التي يحلها CodeAlmanac؟
- لمن هذا المشروع؟ (ولمن ليس له؟)
- المميزات الرئيسية لـ CodeAlmanac
- المتطلبات التقنية قبل التثبيت
- طريقة تثبيت CodeAlmanac (خطوات تقريبية)
- شرح ملف .env والإعدادات الأساسية
- تشغيل CodeAlmanac لأول مرة
- أخطاء شائعة وحلولها
- استخدامات عملية في السوق السعودي/الخليجي
- هل يستحق CodeAlmanac التجربة الآن؟ (تقييم صادق)
- بدائل مشابهة لـ CodeAlmanac
- أسئلة شائعة (FAQ)
قبل أن تطبق
الفكرة التي تمنع التسرع
تعتقد أن توثيق الكود يدوياً هو الطريقة الوحيدة، لكن هناك أداة جديدة تفعل ذلك تلقائياً من محادثاتك مع AI.
أسئلة التشخيص السريع
قبل أن تطبق، اعرف أين تقف بالضبط
- هل تستخدم ChatGPT أو Claude بانتظام لتوليد الكود؟
- هل تواجه صعوبة في تنظيم محادثاتك البرمجية؟
- هل تفضل التوثيق التلقائي على اليدوي؟
- هل لديك مشروع صغير أو متوسط يحتاج توثيقاً سريعاً؟
- هل أنت مستعد لتجربة أدوات في مرحلة مبكرة؟
- هل لديك مفتاح API من OpenAI؟
- هل تعمل على نظام macOS أو Linux أو Windows مع WSL؟
نظام التشغيل: Input → Process → Output
لوحة قياس النجاح
لا تعتمد على الانطباع؛ اختر مؤشراً تراجعه
إذا كنت مطوراً عربياً وتستخدم ChatGPT أو Claude أو GitHub Copilot لتوليد الكود، فأنت تعلم أن هذه المحادثات تحتوي على حلول قيمة، لكنها غالباً ما تضيع بين آلاف الرسائل. توثيق هذه المعرفة يدوياً مرهق وسرعان ما يصبح قديماً. هنا يأتي دور CodeAlmanac، أداة مفتوحة المصدر ظهرت على Hacker News من فريق Almanac (YC S26)، تهدف إلى تحويل محادثاتك مع مساعدي البرمجة إلى ويكي كود منظم ومتجدد تلقائياً.
في هذا الدليل، سنشرح لك ما هو CodeAlmanac، لمن يفيد، وكيف تثبته محلياً (مع الإشارة إلى أن README غير واضح والخطوات تقريبية)، وما هي حدوده حالياً. الهدف هو تمكينك من تجربة الأداة وتقييمها بنفسك، دون مبالغة أو وعود كاذبة.
ما المشكلة التي يحلها CodeAlmanac؟
المشكلة الأساسية: محادثاتك مع مساعدي البرمجة تحتوي على معرفة قيمة (كود، حلول، شروحات) لكنها غير منظمة وسهلة النسيان. التوثيق اليدوي يستغرق وقتاً ويصبح قديماً بسرعة. CodeAlmanac يحل هذه المشكلة بأتمتة عملية التوثيق.
لمن هذا المشروع؟ (ولمن ليس له؟)
لمن هذا: مطور عربي يستخدم ChatGPT/Claude بانتظام، يعمل على مشاريع صغيرة أو متوسطة، ويريد توثيق معرفته دون جهد إضافي. صاحب مشروع صغير في الخليج لديه قاعدة كود Laravel ويستخدم مساعدي AI. صانع محتوى تقني يشرح مشاريع GitHub ويحتاج توثيقاً سريعاً.
ليس له: من لا يستخدم مساعدي برمجة، أو يفضل التوثيق اليدوي الكامل، أو يحتاج توثيقاً فورياً لمشروع ضخم مع متطلبات CI/CD معقدة.
المميزات الرئيسية لـ CodeAlmanac
- مفتوح المصدر ومجاني بالكامل
- يعمل محلياً على جهازك (خصوصية كاملة)
- يتكامل مع ChatGPT، Claude، GitHub Copilot
- يحدث الويكي تلقائياً مع كل محادثة
- ينتج ملفات Markdown منظمة يمكن تصفحها بأي متصفح
المتطلبات التقنية قبل التثبيت
- Node.js (إصدار 18 أو أحدث) و npm
- Git
- مفتاح API لمساعد البرمجة الذي تستخدمه (مثلاً OpenAI API key)
- نظام تشغيل: macOS، Linux، أو Windows (مع WSL)
- مساحة تخزين كافية للمحادثات والويكي
طريقة تثبيت CodeAlmanac (خطوات تقريبية)
ملاحظة مهمة: README المشروع غير واضح حالياً، والخطوات التالية تقريبية بناءً على بنية المشروع. قد تختلف الخطوات الفعلية عند تحديث README.
- استنساخ المستودع:
git clone https://github.com/AlmanacCode/codealmanac.git - الدخول إلى المجلد:
cd codealmanac - تثبيت الاعتماديات:
npm install - إنشاء ملف .env (انظر القالب أدناه)
- تشغيل الأداة:
npm startأوnode index.js(حسب هيكل المشروع)
شرح ملف .env والإعدادات الأساسية
قم بإنشاء ملف .env في جذر المشروع بالمحتوى التالي:
OPENAI_API_KEY=your-openai-api-key-here
CODEALMANAC_PORT=3000
CODEALMANAC_WIKI_DIR=./wikiOPENAI_API_KEY: مفتاح API من OpenAI (ضروري لتحليل المحادثات). CODEALMANAC_PORT: المنفذ المحلي (اختياري، الافتراضي 3000). CODEALMANAC_WIKI_DIR: مسار حفظ ملفات الويكي.
تشغيل CodeAlmanac لأول مرة
بعد تثبيت الاعتماديات وإعداد .env، شغل الأمر npm start. ستظهر رسالة تفيد بأن الخادم يعمل على المنفذ المحدد. افتح المتصفح على http://localhost:3000 لرؤية الويكي. قد تحتاج لاستيراد محادثاتك السابقة (الطريقة غير موثقة بعد).
أخطاء شائعة وحلولها
استخدامات عملية في السوق السعودي/الخليجي
مثال 1: مطور سعودي يستخدم ChatGPT لكتابة كود API، ثم يستخدم CodeAlmanac لإنشاء صفحة wiki تشرح endpoints تلقائياً. يمكنه مشاركة الويكي مع فريقه دون الحاجة لكتابة يدوية.
مثال 2: صاحب مشروع صغير في الإمارات لديه قاعدة كود Laravel ويستخدم Claude لتعديلها. CodeAlmanac يوثق كل تغيير تلقائياً، مما يسهل تتبع التعديلات.
مثال 3: صانع محتوى تقني عربي يشرح مشروع GitHub، يستخدم CodeAlmanac لتوليد وثائق سريعة للمشاهدين.
هل يستحق CodeAlmanac التجربة الآن؟ (تقييم صادق)
CodeAlmanac فكرة واعدة، لكنه في مرحلة مبكرة جداً. README غير واضح، والتثبيت تقريبي. إذا كنت من عشاق التجارب المبكرة ولا تمانع بعض الصعوبات، جربه. أما إذا كنت تبحث عن حل مستقر وجاهز، فانتظر بضعة أشهر.
بدائل مشابهة لـ CodeAlmanac
- Docusaurus: أداة توثيق تقليدية، لكنها يدوية وتحتاج CI/CD.
- GitBook: خدمة سحابية، ليست مفتوحة المصدر.
- Obsidian: تطبيق ملاحظات محلي، لكنه ليس مخصصاً للكود.
أسئلة شائعة (FAQ)
هل CodeAlmanac مجاني بالكامل؟
نعم، المشروع مفتوح المصدر ومجاني. لكن قد تحتاج لمفتاح API من OpenAI (مدفوع) إذا كنت تستخدم ChatGPT.
هل يمكن استخدامه مع أي مساعد برمجة؟
حالياً يدعم ChatGPT وClaude وGitHub Copilot، لكن قد يتطلب تعديلات بسيطة.
هل يدعم اللغة العربية في الويكي؟
نعم، الويكي يعرض نصوصاً عربية إذا كانت المحادثات بالعربية.
ما هي متطلبات النظام؟
RAM 4GB على الأقل، CPU متوسط. يعمل على معظم الأجهزة الحديثة.
كيف أدمج CodeAlmanac مع مشروعي الحالي؟
يحتاج لتهيئة يدوية حالياً. يمكنك وضع ملفات الويكي في مجلد مشروعك.
هل يمكن نشر الويكي على الإنترنت؟
نعم، يمكنك نشر مجلد الويكي على أي خدمة استضافة ثابتة (مثل GitHub Pages).
ماذا لو كان لدي أكثر من مشروع؟
يمكنك تشغيل نسخ متعددة على منافذ مختلفة.
هل هناك خطة لدعم GitLab أو Bitbucket؟
لم يذكر الفريق ذلك، لكنه ممكن في المستقبل.
Playbook التطبيق
خطوات عملية مرتبة من التشخيص إلى النتيجة
استنساخ المستودع
لماذا؟ للحصول على الكود المصدري للأداة
كيف؟ git clone https://github.com/AlmanacCode/codealmanac.git
الناتج: مجلد codealmanac على جهازك
تثبيت الاعتماديات
لماذا؟ لتجهيز بيئة التشغيل
كيف؟ cd codealmanac && npm install
الناتج: تثبيت جميع الحزم المطلوبة
إعداد ملف .env
لماذا؟ لتزويد الأداة بمفتاح API والإعدادات
كيف؟ أنشئ ملف .env بالمحتوى: OPENAI_API_KEY=your-key CODEALMANAC_PORT=3000 CODEALMANAC_WIKI_DIR=./wiki
الناتج: ملف تكوين جاهز
تشغيل الأداة
لماذا؟ لبدء الخادم المحلي
كيف؟ npm start
الناتج: خادم يعمل على http://localhost:3000
قوالب جاهزة للنسخ
حوّل القراءة إلى تنفيذ سريع
OPENAI_API_KEY=your-openai-api-key-here CODEALMANAC_PORT=3000 CODEALMANAC_WIKI_DIR=./wiki
مصفوفة الأخطاء
اعرف أين يتعثر الناس وكيف تتجنب ذلك
شجرة القرار
ماذا تفعل حسب حالتك؟
إذا: إذا كنت من عشاق التجارب المبكرة ولا تمانع صعوبات التثبيت
إذن: جرب CodeAlmanac الآن
إذا: إذا كنت تبحث عن حل مستقر وجاهز
إذن: انتظر بضعة أشهر أو استخدم بدائل مثل Docusaurus
خطة تطبيق 7 أيام
جدول صغير يمنع التسويف
- اليوم 1: استنساخ المستودع وتثبيت الاعتماديات
- اليوم 2: إعداد .env وتشغيل الأداة
- اليوم 3: استيراد محادثات سابقة (يدوياً)
- اليوم 4: تصفح الويكي وتقييم النتائج
- اليوم 5: اختبار مع محادثة جديدة
- اليوم 6: مشاركة الويكي مع فريق صغير
- اليوم 7: اتخاذ قرار بالاستمرار أو الانتظار
حقائق سريعة تحفظها
نقاط مختصرة ترجع لها لاحقاً
1. مفتوح المصدر ومجاني بالكامل
2. يعمل محلياً على جهازك (خصوصية كاملة)
3. يتكامل مع ChatGPT، Claude، GitHub Copilot
4. يحدث الويكي تلقائياً مع كل محادثة
5. ينتج ملفات Markdown منظمة
6. يتطلب Node.js 18+ و npm
7. README غير واضح حالياً
8. يدعم اللغة العربية في الويكي
9. يمكن نشره على GitHub Pages
أسئلة شائعة
إجابات مباشرة على ما يبحث عنه الزائر
مصطلحات سريعة
تعريفات مختصرة تمنع الالتباس
موقع ويب يسمح للمستخدمين بإضافة وتحرير المحتوى بشكل تعاوني، هنا يشير إلى مجموعة صفحات Markdown منظمة.
مفتاح سري يسمح للتطبيقات بالتواصل مع خدمة معينة، مثل OpenAI.
لغة تنسيق خفيفة تستخدم لكتابة النصوص بتنسيق بسيط، تتحول إلى HTML.
أسئلة مرتبطة يبحث عنها الناس
استخدمها كمسارات متابعة داخل نفس الموضوع
لماذا هذا المرجع يتجاوز الموضوع نفسه؟
تحول القارئ: من مطور يضيع معرفته في محادثات AI إلى مطور يمتلك ويكي كود منظم ومتجدد تلقائياً.
- مشروع Leaves: أداة تحليل مساحة التخزين (لربط أدوات المطورين مفتوحة المصدر)
- ds4: تشغيل نماذج MoE على Mac (لربط أدوات AI المحلية)
- Clawk: عزل وكلاء AI في Linux (لربط أدوات الخصوصية)
كيف تستخدم هذا المرجع لاحقاً؟
القيمة الحقيقية تظهر عند العودة والتطبيق
لا تتعامل معه كمقال يُقرأ مرة واحدة. استخدمه كلوحة تشغيل: ارجع للتشخيص عند ظهور المشكلة، وللقوالب عند التطبيق، ولمؤشرات القياس عند المراجعة.
CodeAlmanac فكرة واعدة، لكنه في مرحلة مبكرة. إذا كنت من عشاق التجارب المبكرة، جربه الآن. وإلا، تابع تطوره. على أي حال، أنت الآن تملك دليلاً عملياً يختصر عليك وقت التجربة. شاركنا تجربتك في التعليقات.
خطة تحديث هذا الدليل
حتى يبقى المرجع صالحاً مع الوقت
- تحقق من تحديثات README شهرياً
- تابع إصدارات المشروع على GitHub
- اختبر مع إصدارات Node.js الجديدة
التعليقات (0)
لا توجد تعليقات بعد. كن أول من يبدأ النقاش 👇