Luồng hệ thống từ đầu đến cuối

1. User journey — hành trình người học

2. Agent 1 — Content Mapper

Vai trò đích: chuẩn bị Knowledge Map và hỗ trợ biên soạn Question Bank ngoại tuyến.

Giáo trình/slide
→ parse và chunk
→ embedding
→ pgvector retrieval
→ AI đề xuất draft
→ Role 1 review
→ Question Bank version chính thức

Agent 1 không được trở thành dependency của đường chấm bài runtime. Node legacy hiện còn làm điều đó và phải được xem là technical debt — nợ kỹ thuật.

3. Agent 2 — Cluster Diagnostic

Đầu vào chính:

student_id, course_id, cluster_id, self_assessment_raw

Đầu ra mỗi lượt:

evidence?
knowledge_state
budget
next_question?

next_question = null không đồng nghĩa verified; client phải đọc knowledge_state.diagnostic_status.

Runtime phát hai loại câu: multiple_choice (exact match, Level 0 vĩnh viễn) và high_information (rubric-AI sau guardrail, mở từ 2026-08-29 theo ADR 15). Điều kiện phát là is_servable_item() ở mức từng item, không phải tên loại câu — xem CAT-lite diagnostic.

4. Agent 3 — Multi-Course Learning Priority Coordinator

Agent 3 giữ độ phân giải Topic/CLO nếu Knowledge State có topic_states. Nếu một Cluster chưa có topic state, coordinator mới tạo một Learning Unit cấp Cluster.

Pipeline:

Candidate Learning Set
→ Need
→ Importance
→ Urgency
→ Priority Score
→ Deterministic Ranking
+ Capacity Context
+ Structured Reasons

Nếu candidate_units trong request rỗng, service dựng candidate từ Knowledge State đã lưu. Nếu request đã cung cấp candidate, upstream là chủ sở hữu scope và Agent 3 tôn trọng tập đó.

5. Agent 4 — Planner

Planner là backend tất định: hàm thuần allocate_plan() (src/agents/planner/allocator.py) phơi qua POST /api/v1/plan/schedule. Frontend chỉ dựng request (buildPlanScheduleRequest) và trình bày kết quả (planToScheduleDays) — không còn thuật toán xếp lịch nào ở browser.

Planner dùng:

• rank đã có (đọc nguyên văn, không tính lại điểm);
• remaining work;
• capacity status;
• quỹ slot morning/afternoon/evening;
• ngày thi.

Planner tạo:

• learn — học;
• practice — luyện tập;
• review — ôn lại;
• session bị hoãn, chỉ khi có shortfall_minutes >= 1 thật kèm một DeferralReasonCode.

Planner V1 không trạng thái: không chạm DB, không đọc đồng hồ server (mốc duy nhất là plan_start_date), và không gửi lịch ngược về Agent 3 để thương lượng nhiều vòng. advisory trong response luôn là null — gate §5.6 còn đóng (ADR 11/16).

6. Study Workspace

Mỗi task lịch có thể mở một workspace gồm:

• document pages — trang tài liệu;
• mind map — sơ đồ tư duy;
• flashcards — thẻ ghi nhớ;
• mini quiz — bài kiểm tra ngắn.

Đây là nội dung hỗ trợ học, không phải evidence của Agent 2 trừ khi một contract chẩn đoán riêng trong tương lai xác định rõ điều đó.

7. Re-coordination — điều phối lại

Agent 3 có thể chạy lại khi có material event — sự kiện đủ quan trọng:

• evidence mới;
• mastery thay đổi;
• deadline thay đổi;
• study capacity thay đổi đáng kể;
• task hoàn thành hoặc bị lỡ;
• remaining work thay đổi đáng kể.

Response hỗ trợ audit bằng:

previous_priority_score
score_delta
re_evaluation_reason

8. Five-course flow — luồng năm môn

“Multi-course” là khả năng, không phải nghĩa vụ. Người dùng có thể chọn một môn. Khi chọn nhiều môn, Agent 3 rank chung các Learning Unit đủ tín hiệu; Capacity Context vẫn được nhóm theo môn và deadline window để không trộn sức chứa sai ngữ cảnh.