hatef-escape-room - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #golang #machine-learning #rust #deep-learning #java #windows #awesome #cli #vue #security

hatef-escape-room

(★ 74)

اتاق فرار هاتف — یک بازی اتاق‌فرار آموزشیِ فارسی (RTL) که با فرار از ذهن یک ابرهوش‌مصنوعی، ۵ مفهوم واقعی LLM را تعاملی آموزش می‌دهد. Next.js + TS + Tailwind.

File Explorer

Download Latest Version (.zip)

- - page.tsx
- globals.css
- layout.tsx
- page.tsx
- - Layer1Tokenize.tsx
  - Layer2Embedding.tsx
  - Layer3Attention.tsx
  - Layer4Generation.tsx
  - Layer5Retrieval.tsx
  - Layer6Prompt.tsx
- - Intro.tsx
  - Lose.tsx
  - Win.tsx
- HatefOrb.tsx
- HatefSpeech.tsx
- HintButton.tsx
- Hud.tsx
- LayerShell.tsx
- ProgressLocks.tsx
- RestartButton.tsx
- SceneBackground.tsx
- SoundToggle.tsx
- Timer.tsx
- acrostic.ts
- audio.ts
- puzzles.ts
- scoring.ts
- store.ts
- - README.md
- - hatef-orb.png
  - layer-1.png
  - layer-2.png
  - layer-3.png
  - layer-4.png
  - layer-5.png
  - lose.png
  - README.md
  - room.png
  - win.png
.env.example
.gitignore
CLAUDE.md
next.config.mjs
package-lock.json
package.json
postcss.config.mjs
README.md
tailwind.config.ts
tsconfig.json

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# اتاق فرار هاتف — Hatef's Escape Room

یک بازی اتاق‌فرار آموزشیِ تک‌نفره، مرورگری و کاملاً فارسی (RTL) که با فرار از «ذهن» یک ابرهوش‌مصنوعی، مسیر کامل کار یک مدل زبانی (LLM) را تعاملی آموزش می‌دهد. ساخته‌شده برای کلاس زنده (تا ۶۰ دانشجو، هرکس روی دستگاه خودش).

پنج لایه: **توکن‌سازی → Embedding → Attention → تولید توکن → مهندسی پرامپت**. ده دقیقه، پنج کلید.

**نسخه‌ی آنلاین:** <https://hatef-escape-room.vercel.app>

---

# 🎓 راهنمای دانشجو — اجرا روی کامپیوتر خودت

## پیش‌نیاز: Node.js نسخه ۱۸.۱۸ یا بالاتر

اول چک کن نصب است:

```bash
node -v
```

اگر خطا داد یا عدد کمتر از `v18.18` بود، از <https://nodejs.org> نسخه‌ی **LTS** را نصب کن و ترمینال را ببند و باز کن.

## گام ۱ — گرفتن پروژه

```bash
git clone https://github.com/siavash-smf/hatef-escape-room.git
cd hatef-escape-room
```

## گام ۲ — نصب کتابخانه‌ها

```bash
npm install
```

> پیام `high severity vulnerabilities` را نادیده بگیر — مربوط به ابزارهای build است و روی بازی اثری ندارد.

## گام ۳ — اجرا

```bash
npm run dev
```

بعد در مرورگر برو به **<http://localhost:3000>**

> اگر نوشت `Port 3000 is in use, trying 3001`، اشکالی ندارد — همان شماره‌ای را که خودش نشان می‌دهد باز کن.

**همین‌جا بازی کامل و قابل‌اتمام است.** ادامه فقط برای اینکه لایه ۵ به یک مدل زبانی واقعی وصل شود.

## گام ۴ (اختیاری ولی توصیه‌شده) — وصل‌کردن لایه ۵ به مدل واقعی

لایه ۵ درباره‌ی مهندسی پرامپت است. بدون کلید، یک ارزیاب لوکال فقط چک می‌کند پرامپتت شرط‌ها را دارد یا نه. با کلید، پرامپتت واقعاً به یک مدل زبانی می‌رود و شعرِ تولیدشده بررسی می‌شود — تجربه‌ی خیلی بهتری است.

**الف)** برو به <https://openrouter.ai> و با گوگل ثبت‌نام کن (رایگان).

**ب)** از <https://openrouter.ai/keys> یک کلید بساز و کپی کن (با `sk-or-v1-` شروع می‌شود).

**ج)** در پوشه‌ی پروژه، فایل نمونه را کپی کن:

```bash
cp .env.example .env.local
```

روی ویندوز (PowerShell):

```powershell
Copy-Item .env.example .env.local
```

**د)** فایل `.env.local` را با یک ویرایشگر متن باز کن و کلیدت را جلوی `OPENROUTER_API_KEY=` بگذار:

```
OPENROUTER_API_KEY=sk-or-v1-........
```

**ه)** سرور را ببند (`Ctrl+C`) و دوباره `npm run dev` بزن.

> ⚠️ کلید خودت را در گیت commit نکن. فایل `.env.local` از قبل در `.gitignore` هست، پس اگر همین اسم را استفاده کنی خودکار محافظت می‌شود.

## اگر لایه ۵ گفت «مدل‌ها شلوغ‌اند»

مدل‌های رایگان گاهی شلوغ می‌شوند. چند ثانیه صبر کن و دوباره «ارسال فرمان» را بزن — برنامه خودش پنج مدل رایگانِ مختلف را پشت‌سرهم امتحان می‌کند.

---

# راهنمای توسعه

## پیکربندی

`.env.example` را به `.env.local` کپی کن. لایه ۵ به‌ترتیب این سه حالت را امتحان می‌کند:

1. **`OPENROUTER_API_KEY`** (اولویت اول) — پرامپت بازیکن به یک مدل رایگانِ OpenRouter می‌رود. اگر مدل اول شلوغ (۴۲۹) باشد، خودکار سراغ مدل بعدی می‌رود. زنجیره در [`app/api/oracle/route.ts`](app/api/oracle/route.ts) تعریف شده و با `OPENROUTER_MODEL` می‌توان مدل اول را عوض کرد.
2. **`ANTHROPIC_API_KEY`** — اگر کلید OpenRouter نبود، از Claude API استفاده می‌شود.
3. **حالت آفلاین** — اگر هیچ کلیدی نبود، یک ارزیاب لوکال چک می‌کند پرامپت شرط‌های لازم را پوشش داده یا نه، تا بازی همیشه قابل‌اتمام بماند.

## تصاویر و صدا

تصاویر لایه‌ها در `public/images/` داخل مخزن هستند. اگر فایلی نباشد، به گرادیان fallback می‌شود.
اگر `public/audio/ambient.mp3` وجود داشته باشد، به‌جای موسیقی تولیدشونده‌ی Tone.js پخش می‌شود.

## استک

Next.js 15 (App Router) · TypeScript · Tailwind CSS · Framer Motion · Tone.js · Zustand · `@anthropic-ai/sdk`.

## دیپلوی روی Vercel

پروژه به مخزن گیت‌هاب وصل است؛ هر push روی `master` خودکار دیپلوی می‌شود.
`OPENROUTER_API_KEY` را در Environment Variables تنظیم کن (اختیاری — بدون آن هم کامل کار می‌کند).