Tutorial 2 How the Code Works ar

الدرس 2 · كيف تعمل الشيفرة

🌎 اللغة: العربية — شاهد كل اللغات الـ33

الهدف: افهم قلة قرارات التصميم التي تجعل تعديل هذا المشروع سهلا — وآمنا — بوكيل ذكاء اصطناعي. لست بحاجة إلى حفظ الشيفرة؛ بل تحتاج إلى النموذج الذهني، حتى توجّه الوكيل بدقة.

← السابق: الدرس 1 التوجيه · التالي: الدرس 3 مهمتك الأولى مع الوكيل

---

الخريطة

lockedin-cli/
├── bin/lockedin.js      # نقطة الدخول — الجزء الوحيد الذي يجري الإدخال/الإخراج
├── src/lockedin.js      # النواة — دوال نقية تعيد سلاسل نصية
├── test/
│   ├── unit.test.js     # يختبر دوال النواة مباشرة
│   └── cli.test.js      # يشغّل الملف التنفيذي الحقيقي ويتحقق من خرجه
├── tools/screenshot.js  # يرسم ملفات SVG الظاهرة في docs/
└── package.json         # البيانات الوصفية + سكربت `npm test`

أربع أفكار تجعلها تعمل. تعلّمها، وتستطيع أن تطلب من الوكيل أي تغيير تقريبا بثقة.

الفكرة 1 — نواة نقية تُرجع سلاسل نصية

افتح src/lockedin.js. لاحظ أن دوال العرض لا تطبع — بل تُرجع سلاسل نصية:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...يبني مصفوفة من الأسطر...
  return out.join('\n');   // يعيد نصا؛ لا يطبع شيئا
}

كل الطباعة الفعلية (وقراءة ضغطات مفاتيحك) يجري في bin/lockedin.js. هذا الفصل «النواة تُرجع بيانات، والحافة تؤدي الإدخال/الإخراج» هو أهم شيء هنا، لأن دالة لا تفعل سوى إرجاع سلسلة نصية تافهة الاختبار:

const out = app.renderConnect();
assert.ok(out.includes("“يسعدني أن أضيفك إلى شبكتي المهنية.” — أُرسلت إلى "));

لا محاكاة لطرفية، ولا التقاط لـstdout. حين تطلب من الوكيل إضافة ميزة، هذا هو السبب في أنه يستطيع أيضا إضافة اختبار سريع وموثوق لها.

الفكرة 2 — مجمّعات المحتوى

النكات تقيم في مصفوفات بسيطة قرب أعلى src/lockedin.js:

const HOOKS = [ 'رأي غير شائع:', 'دع ذلك يستقر في ذهنك.', /* ...~25 total... */ ];
const LESSONS = [ '→ شبكتك هي صافي ثروتك.', /* ... */ ];

المولّدات تنتقي من هذه المجمّعات. في v1.2.0 نما كل مجمّع إلى ~25 نسخة، وأُضيفت طبقة ثانية من مجمّعات القوالب (أشياء مثل POST_REVEALS و REFLECT_TAGSETS) حتى يتغير هيكل كل مخرَج، لا الكلمات فحسب. غالبا ما تكون إضافة المحتوى بسيطة كإضافة سلاسل نصية إلى مصفوفة — مهمة أولى مثالية لتسليمها لوكيل.

الفكرة 3 — العشوائية المُبَذَّرة = اختبارات حتمية

يبدو أن المخرجات العشوائية والاختبارات المؤتمتة غير متوافقة. يحل هذا المشروع تلك المعضلة بـمولّد أرقام عشوائية قابل للتبذير:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → البذرة نفسها، المنشور نفسه

كل اختيار عشوائي يمر عبر المساعدَين المشتركَين pick() / shuffle()، اللذين يسحبان من ذلك المولّد المُبَذَّر. اضبط LOCKEDIN_SEED=42 فتصبح الأداة قابلة للاستنساخ بالكامل. القاعدة الذهبية لأي تغيير: أي عشوائية جديدة يجب أن تستخدم pick / shuffle، لا Math.random مباشرة — وإلا فستنكسر الحتمية (والاختبارات). احتفظ بهذا في جيبك؛ ستذكّر الوكيل به في الفصل 3.

الفكرة 4 — طبقتان من الاختبارات

• test/unit.test.js يستدعي دوال النواة ويؤكد على السلاسل النصية التي تُرجعها (سريع ودقيق).
• test/cli.test.js يشغّل فعليا bin/lockedin.js ويفحص مخرجاته الحقيقية على stdout ورمز الخروج (يثبت أن كل شيء يعمل من البداية إلى النهاية).

معا هما البوابة. وهما أيضا يرمّزان الثوابت — الوعود التي يقطعها التطبيق. مثلا، يبدأ المنشور دائما بخطّاف معروف ويحوي دائما ثلاثة دروس → على الأقل؛ وشاشة «connect» تقول دائما incalculable. حين يغيّر وكيل الشيفرة، تلتقط هذه الاختبارات أي شيء كسر وعدا بهدوء.

---

لماذا يهم هذا في العمل مع وكيل

اجمع الأفكار الأربع فتحصل على شيفرة يستطيع فيها الوكيل أن:

1. يضيف ميزة كدالة نقية تُرجع سلسلة نصية،
2. يضيف اختبارا لها بلا أي مناورات إدخال/إخراج،
3. يبقي المخرجات قابلة للاستنساخ عبر مولّد الأرقام المُبَذَّر، و
4. يثبت أنه لم يكسر شيئا بتشغيل البوابة القائمة.

تلك هي الحلقة التي ستشغّلها في الفصل التالي.

✅ جرّبه مع وكيلك

اطلب من وكيلك أن يتحقق من فهمك — بالقراءة، لا التعديل:

1. «اسرد كل مجمّع محتوى في src/lockedin.js وكم مدخلة في كل واحد.»
2. «أرني ثابتا واحدا يفرضه test/unit.test.js على generatePost، واشرح ما الذي سيكسره.»
3. «أين عُرِّف مولّد الأرقام المُبَذَّر، وأي دوال يجب أن تستخدمه بدلا من Math.random؟ لا تغيّر شيئا — اشرح فحسب.»

حين تطابق إجابات الوكيل هذا الفصل، تكون جاهزا للبناء.

التالي: الدرس 3 مهمتك الأولى مع الوكيل