# Edulab Việt Nam

Edulab Việt Nam là website học liệu tương tác dành cho giáo viên và học sinh phổ thông. Website hiện có sáu bài học mẫu thật thuộc ba nhóm Toán, Vật lý và Hoá học, cùng một xưởng bài học để giáo viên nhập đề bài và mở bài phù hợp.

## Cơ chế hoạt động

Có hai lớp cần phân biệt:

| Lớp | Cách hoạt động |
|---|---|
| Xưởng bài học trên website | Nhận prompt tiếng Việt trong trình duyệt, dò các từ khoá chủ đề, chọn bài học phù hợp trong thư viện sáu bài mẫu, rồi hiển thị lời giải và mô phỏng theo từng bước. Bản hiện tại không gửi dữ liệu ra máy chủ và chưa gọi mô hình AI trực tiếp. |
| Pipeline Edulab gốc | Agent nhận prompt văn bản, ảnh hoặc yêu cầu ra đề ngẫu nhiên; chuẩn hoá thành problem spec; gọi bộ giải SymPy để tính chính xác; lắp dữ liệu `lesson`, `steps`, `model` vào template; tự kiểm tra rồi sinh một tệp HTML độc lập. |

Nói ngắn gọn, **prompt không chỉ là phần diễn giải**. Trong pipeline đầy đủ, prompt là đầu vào để xác định môn, loại bài, dữ kiện, đại lượng cần tìm và ngôn ngữ. Mô hình hoặc agent chỉ nên tổ chức lời giải và chọn cách trình bày; các con số, tọa độ, hệ số phản ứng và đáp án phải do bộ tính toán chuyên biệt kiểm tra. Với ảnh, hệ thống cần đọc đề rồi hiển thị lại phần nhận diện để giáo viên xác nhận trước khi giải. Với yêu cầu ngẫu nhiên, hệ thống sinh tham số, giải thử và bỏ qua đề có kết quả không đẹp.

Quy trình chuẩn của một bài học đầy đủ là:

1. **Nhận đầu vào:** giáo viên nhập đề bài bằng chữ, tải ảnh đề hoặc yêu cầu tạo đề ngẫu nhiên.
2. **Chuẩn hoá đề:** trích xuất môn học, chủ đề, dữ kiện, điều kiện, đại lượng cần tìm và ngôn ngữ thành một problem spec.
3. **Tính toán có kiểm chứng:** bộ giải chuyên môn tính đáp án và các đại lượng trung gian; không dùng phép tính nhẩm của giao diện.
4. **Dựng bài học:** dữ liệu được đưa vào template để tạo tiêu đề, đáp án, các bước giải, công thức và mô hình trực quan.
5. **Tự kiểm tra:** đáp án trong bộ giải, thẻ kết quả, bước cuối và mô hình phải cùng một nguồn dữ liệu.
6. **Trình chiếu:** giáo viên mở bài học trên trình duyệt, chuyển bước, thao tác mô phỏng và dùng câu hỏi gợi mở để thảo luận trên lớp.

## Sáu bài học hiện có

| Mã bài | Môn | Nội dung | Tương tác |
|---|---|---|---|
| `toan-hinh-khong-gian` | Toán 12 | Hình chóp tứ giác đều, góc giữa đường thẳng và mặt phẳng | Mô hình 3D, bốn bước giải |
| `toan-ham-so-bac-hai` | Toán 10 | Đỉnh, trục đối xứng và nghiệm của parabol | Đồ thị minh hoạ |
| `ly-nem-xien` | Vật lý 10 | Tầm xa lớn nhất của chuyển động ném xiên | Quỹ đạo và công thức |
| `ly-dinh-luat-ii` | Vật lý 10 | Gia tốc theo định luật II Newton | Sơ đồ lực |
| `hoa-dot-chay-metan` | Hoá 10 | Cân bằng phản ứng đốt cháy methane | Đếm nguyên tử |
| `hoa-dien-phan-nuoc` | Hoá 10 | Điện phân nước tạo hydrogen và oxygen | Tỉ lệ phân tử 2 : 1 |

## Chạy cục bộ

Project là website tĩnh, không cần cơ sở dữ liệu hoặc bước build:

```bash
python3 -m http.server 4173
```

Sau đó mở `http://localhost:4173/`. Trang `bai-hoc.html` là xưởng bài học; có thể mở trực tiếp một bài bằng query, ví dụ `bai-hoc.html?bai=ly-nem-xien`.

## Kiểm thử

Bộ smoke test kiểm tra ngôn ngữ tiếng Việt, sáu bài học dữ liệu thật, bộ lọc, luồng phân tích prompt, các query bài học, các liên kết HTTP và việc không còn cấu trúc project cũ:

```bash
python3 tests/smoke_test.py
```

## Cấu trúc project

| Tệp | Mục đích |
|---|---|
| `index.html` | Trang chủ, kho học liệu và điều hướng |
| `bai-hoc.html` | Xưởng nhập prompt, thư viện sáu bài và trình xem bài học |
| `lesson.html` | Bài học mẫu hình học không gian 3D chi tiết |
| `tests/smoke_test.py` | Kiểm thử nhanh nội dung, dữ liệu và liên kết |
| `LICENSE` | Giấy phép Apache-2.0 của mã nguồn gốc |
| `NOTICE` | Thông báo bản quyền và attribution nguồn |

## Giới hạn hiện tại và hướng mở rộng

Bản website hiện tại là bản tĩnh có thư viện bài học mẫu. Xưởng bài học chưa gọi LLM, chưa nhận dạng ảnh và chưa tự sinh HTML mới từ một đề bài bất kỳ. Để trở thành pipeline đầy đủ, cần bổ sung máy chủ an toàn để gọi mô hình, bộ parser problem spec, các kernel tính toán SymPy cho từng môn, cơ chế lưu bài học và kiểm tra đầu ra trước khi cho giáo viên trình chiếu.

## Triển khai

Website có thể triển khai trực tiếp lên Cloudflare Pages, Netlify, GitHub Pages hoặc bất kỳ dịch vụ lưu trữ tệp tĩnh nào. Khi triển khai Cloudflare Pages, chọn thư mục chứa các tệp HTML làm thư mục tài nguyên và không cần lệnh build.

## Bản quyền

Project được phát hành theo Apache-2.0. Các thư viện bên thứ ba được tải từ CDN cần tuân theo giấy phép và điều khoản riêng của chúng.

> Học để hiểu, dạy để chạm.

## Dùng Agent sinh mã

Mở `agent.html` hoặc chọn **Agent sinh mã** trên trang chủ. Nhập API Base URL, tên model và API key. Với DeepSeek, dùng `https://api.deepseek.com` và tên model do tài khoản DeepSeek hỗ trợ. Sau đó nhập prompt càng cụ thể càng tốt, chẳng hạn môn, lớp, dữ kiện, đáp án cần tìm, số bước và loại mô phỏng.

Khi chạy, trình duyệt gửi prompt và API key qua HTTPS tới Pages Function `/api/generate`. Function tạo một harness gọn nhẹ gồm plugin model, parser, validator và session log. Model trả về JSON gồm đặc tả bài học, lời giải và một tài liệu HTML hoàn chỉnh. Validator kiểm tra schema, kích thước HTML và cấm iframe, script ngoài hoặc URL `javascript:`. Preview được mở trong iframe sandbox; mã hợp lệ có thể xem, sao chép hoặc tải về.

API key không được ghi vào Git, không được ghi vào database và không được lưu vào `localStorage`. Tuỳ chọn ghi nhớ chỉ lưu endpoint và tên model trong `sessionStorage`. Hãy dùng API key giới hạn quyền và thu hồi sau khi thử nghiệm.

Thiết kế harness lấy cảm hứng từ DeepSeek Harness, nơi model và các năng lực agent được tổ chức thành plugin có thể thay thế, mỗi lượt chạy có trace. Project này **không nhúng toàn bộ DeepSeek Harness**; nó triển khai một adaptation nhỏ phù hợp Cloudflare Pages Functions để giảm kích thước và dễ kiểm soát.

## Tài liệu tham khảo

- [DeepSeek Harness overview](https://deepseek.com/harness/en/)
- [DeepSeek Harness trên GitHub](https://github.com/deepseek-ai/deepseek-harness)
- [DeepSeek Chat Completions API](https://api-docs.deepseek.com/api/create-chat-completion/)
- [DeepSeek API quickstart](https://api-docs.deepseek.com/)

## Agent v2: endpoint tuỳ biến và runtime server-side

Bản Agent v2 chỉ yêu cầu hai thông tin ban đầu: **API Base URL** và **API key**. Sau khi nhập key, app gọi `GET /models` trên endpoint đó, đọc trường `data[].id` theo hợp đồng OpenAI-compatible và nạp vào dropdown. Vì vậy thầy cô không cần đoán hoặc gõ tên model. Endpoint có thể là DeepSeek, OpenAI hoặc một máy chủ tương thích OpenAI khác dùng HTTPS; prefix `/v1` được giữ nguyên khi ghép đường dẫn.

Khi chọn model và gửi prompt, Pages Function chạy runtime harness server-side. Runtime gồm router skill, gọi `list_skills` và `read_skill` ở host, gọi model một lượt với yêu cầu JSON cuối, sau đó dùng `write_lesson_file` và `validate_lesson` ở host để ghi/kiểm tra mã. State machine này kết thúc cưỡng bức sau pha validate, nên model không thể gọi tool lặp vô hạn. Các tool host-side hiện có là `list_skills`, `read_skill`, `write_lesson_file` và `validate_lesson`. Agent có trace từng pha nhưng không cho model tự gọi tool tuỳ ý trong request này; đây là chủ ý để bảo đảm kết thúc và an toàn trên Cloudflare Pages. Sandbox hiện là bộ nhớ tạm của request, không phải shell tuỳ ý; đây là giới hạn có chủ ý vì Pages Functions không phải máy chủ VM.

Cách này bám sát ý tưởng DeepSeek Harness về plugin, tool, skill, session và vòng lặp, nhưng không đóng gói nguyên runtime `dsh`. Muốn chạy skill có shell, cài package, đọc/sửa workspace thật hoặc chạy tiến trình dài như Standard/Code mode, cần chuyển worker runtime sang Cloudflare Container/VM hoặc một máy chủ riêng. Pages Function phù hợp với agent nhẹ, request ngắn, tool allowlist và sandbox giới hạn.