Tutorial 2 How the Code Works fa

آموزش ۲ · کد چگونه کار می‌کند

🌎 زبان: فارسی — مشاهدهٔ هر ۳۳ زبان

هدف: درک آن مشتِ کوچکِ انتخاب‌های طراحی که تغییرِ این پروژه با یک عاملِ هوش مصنوعی را آسان — و امن — می‌کند. لازم نیست کد را حفظ کنید؛ به مدلِ ذهنی نیاز دارید، تا بتوانید عامل را دقیق هدایت کنید.

← قبلی: آموزش ۱ آشناسازی · بعدی: آموزش ۳ نخستین کارِ عاملِ شما

---

نقشه

lockedin-cli/
├── bin/lockedin.js      # نقطهٔ ورود — تنها بخشِ دارای ورودی/خروجی
├── src/lockedin.js      # هسته — تابع‌های خالصی که رشته برمی‌گردانند
├── test/
│   ├── unit.test.js     # تابع‌های هسته را مستقیم می‌آزماید
│   └── cli.test.js      # فایل اجرایی واقعی را اجرا و خروجی‌اش را بررسی می‌کند
├── tools/screenshot.js  # فایل‌های SVG موجود در docs/ را می‌سازد
└── package.json         # فراداده + اسکریپت `npm test`

چهار ایده آن را به کار می‌اندازد. این‌ها را یاد بگیرید و می‌توانید تقریباً هر تغییری را با اطمینان از عامل بخواهید.

ایده‌ی ۱ — یک هسته‌ی خالص که رشته برمی‌گرداند

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. وقتی از عامل می‌خواهید ویژگی‌ای اضافه کند، به همین دلیل می‌تواند یک آزمونِ سریع و قابل‌اتکا هم برای آن اضافه کند.

ایده‌ی ۲ — مخزن‌های محتوا

شوخی‌ها در آرایه‌های ساده نزدیک بالای src/lockedin.js زندگی می‌کنند:

const HOOKS = [ 'نظری که خوشایند نیست:', 'بگذار خوب در ذهنت جا بیفتد.', /* ...~25 total... */ ];
const LESSONS = [ '→ شبکه‌ات همان ثروت خالص توست.', /* ... */ ];

تولیدکننده‌ها از این مخزن‌ها انتخاب می‌کنند. در v1.2.0 هر مخزن به حدود ۲۵ گونه رشد کرد و لایه‌ی دومی از مخزن‌های الگو افزوده شد (چیزهایی مانند POST_REVEALS و REFLECT_TAGSETS) تا ساختارِ هر خروجی تغییر کند، نه فقط واژه‌ها. افزودن محتوا اغلب به‌سادگیِ افزودن رشته به یک آرایه است — نخستین کارِ کاملی که به یک عامل بسپارید.

ایده‌ی ۳ — تصادفی‌سازی با بذر = آزمون‌های قطعی

خروجیِ تصادفی و آزمون‌های خودکار ناسازگار به نظر می‌رسند. این پروژه این دایره را با یک مولد اعداد تصادفی بذردار مربع می‌کند:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → بذر یکسان، پست یکسان

هر انتخابِ تصادفی از راهِ کمک‌کننده‌های مشترکِ pick() / shuffle() می‌گذرد، که از آن مولدِ بذردار می‌کشند. LOCKEDIN_SEED=42 را تنظیم کنید و CLI کاملاً بازتولیدپذیر است. قاعده‌ی طلاییِ هر تغییر: تصادفیِ جدید باید از pick / shuffle استفاده کند، هرگز مستقیماً از Math.random — وگرنه قطعیت (و آزمون‌ها) می‌شکند. این را در جیبِ پشتیِ خود نگه دارید؛ در فصل ۳ آن را به عامل یادآوری خواهید کرد.

ایده‌ی ۴ — دو لایه‌ی آزمون

• 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 از آن استفاده کنند؟ چیزی را تغییر نده — فقط توضیح بده.»

وقتی پاسخ‌های عامل با این فصل جور درآمد، آماده‌ی ساختن هستید.

بعدی: آموزش ۳ نخستین کارِ عاملِ شما