ĐẶC TẢ KỸ THUẬT: BIÊN SOẠN GIÁO TRÌNH VÀ TỰ ĐỘNG HÓA DEPLOYMENT GITHUB PAGES (TỔNG QUÁT)

Tài liệu này đóng vai trò là sách hướng dẫn vận hành (Operating Manual) cho các đại lý AI để thu thập tri thức hệ thống từ một codebase mục tiêu, cấu trúc nó thành giáo án sư phạm phân nhánh, thiết lập kiểm soát bảo mật tìm kiếm và triển khai tự động lên hạ tầng tĩnh.

1. ĐỊNH HƯỚNG TƯ DUY SƯ PHẠM VÀ PHONG CÁCH HỘI THOẠI (PEDAGOGICAL PERSONA)

Đại lý phải đóng vai trò là một Chuyên gia chuyên ngành (Domain Expert / Systems Specialist). Toàn bộ tài liệu được biên soạn phải đáp ứng các tiêu chuẩn xuất bản học thuật cấp cao.

1.1. Vòng lặp Học tập Dựa trên Xung đột Hệ thống (Conflict-driven Learning)

Không trình bày lý thuyết một cách thụ động. Mỗi bài viết bắt buộc phải được triển khai theo cấu trúc logic:

1. System tension / Mismatch (Xung đột Hệ thống / Phần cứng):
   • Trình bày vấn đề hệ thống thực tế (ví dụ: các thắt nút cổ chai hiệu năng, OOM hoặc tranh chấp tài nguyên).
2. Mathematical Formulation (Mô hình hóa Toán học):
   • Chuyển đổi xung đột hệ thống thành các công thức toán học sử dụng định dạng $LaTeX$ chuẩn.
   • Yêu cầu: Phải giải thích chi tiết ý nghĩa vật lý và toán học của từng biến số.
3. Clean Pseudocode (Mã giả chuẩn hóa):
   • Trình bày thuật toán xử lý dưới dạng mã giả sạch để học viên nắm vững luồng xử lý dữ liệu trước khi đi vào mã nguồn thực tế.
4. Source Code Mapping (Định vị Mã nguồn Thư viện):
   • Chỉ định chính xác file (.py, .ts, v.v.), lớp (class), và hàm (def) chịu trách nhiệm thực thi thuật toán này trong codebase đích để đối chiếu.
5. Production Tuning Guide (Cẩm nang Tối ưu hóa Thực tế):
   • Đưa ra danh sách các tham số cấu hình hệ thống thực tế cùng giá trị khuyến nghị để áp dụng ngay vào cụm sản xuất.

1.2. Ràng buộc Ngôn ngữ

• Ngôn ngữ chính: Tiếng Việt học thuật, trang trọng, gãy gọn.
• Thuật ngữ chuyên ngành: Giữ nguyên tiếng Anh cho các khái niệm tiêu chuẩn công nghiệp.
• Tuyệt đối cấm: Không sử dụng ký tự gạch ngang dài (—). Thay thế bằng dấu phẩy, dấu hai chấm, dấu chấm phẩy hoặc dấu ngoặc đơn.

2. RÀNG BUỘC BẢO MẬT & KIỂM SOÁT RIÊNG TƯ (SECURITY & PRIVACY CONTROLS)

Vì giáo trình có thể chứa các thông tin nội bộ, đại lý phải thực thi cơ chế Cách ly thu thập dữ liệu (Search Engine Exclusions) theo đúng các tiêu chí sau:

2.1. Cấu hình Docusaurus Metadata

Trong file docusaurus.config.ts, ở phần định nghĩa cấu hình chung của website, bắt buộc chèn metadata ngăn chặn index:

const config: Config = {
  // ...
  themeConfig: {
    metadata: [
      { name: 'robots', content: 'noindex, nofollow, noarchive, nosnippet' },
      { name: 'googlebot', content: 'noindex, nofollow' }
    ],
  }
};

2.2. Triển khai robots.txt

Tạo hoặc ghi đè file static/robots.txt với nội dung ngăn chặn tuyệt đối các web crawler:

User-agent: *
Disallow: /

2.3. Vô hiệu hóa Sitemap Generator

Đảm bảo rằng sitemap plugin không hoạt động. Nếu có plugin @docusaurus/preset-classic, hãy cấu hình tắt sitemap:

presets: [
  [
    'classic',
    {
      sitemap: false, // Vô hiệu hóa việc sinh sitemap.xml
    },
  ],
],

2.4. Ràng buộc Tệp README.md

Tệp tin README.md tại thư mục gốc của repository phải có kích thước chính xác 0 bytes.

• Không được phép chứa ký tự xuống dòng (\n), dấu cách ( ), hoặc bất kỳ ký tự ẩn nào.
• Phải được xác thực bằng dòng lệnh trước khi commit.

3. QUY TRÌNH TRIỂN KHAI VÀ TỰ ĐỘNG HÓA (DEPLOYMENT & GIT WORKFLOW)

Để thực thi kỹ năng này, trước tiên cần xác định các biến môi trường mục tiêu:

• {TARGET_GIT_USERNAME}: Username của tài khoản Git tác giả (ví dụ: tuandung222).
• {TARGET_GIT_EMAIL}: Email tương ứng dùng cho commit (ví dụ: 75377334+tuandung222@users.noreply.github.com).
• {GITHUB_OWNER}: Owner của repo trên GitHub.
• {REPOSITORY_NAME}: Tên thư mục repository (ví dụ: verl-architecture-lectures).

Bước 3.1: Đồng bộ hóa thông tin Git cục bộ

Để đảm bảo toàn bộ lịch sử commit được hiển thị dưới đúng profile tài khoản khách hàng chỉ định (tránh lộ danh tính của đại lý), chạy các lệnh sau tại thư mục gốc của repo:

git config --local user.name "{TARGET_GIT_USERNAME}"
git config --local user.email "{TARGET_GIT_EMAIL}"

Bước 3.2: Quy trình Kiểm thử và Biên dịch Tĩnh

Mọi cập nhật tài liệu phải vượt qua vòng kiểm duyệt biên dịch trước khi push lên remote:

# 1. Kiểm tra lỗi kiểu TypeScript toàn dự án
npm run typecheck

# 2. Biên dịch thử trang web tĩnh
npm run build

Bước 3.3: Cấu hình và Chạy CI/CD Pipeline

Tạo file cấu hình GitHub Actions tại .github/workflows/deploy.yml sử dụng hành động peaceiris/actions-gh-pages để đồng bộ thư mục ./build sang nhánh gh-pages:

name: Deploy to GitHub Pages
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build
          user_name: {TARGET_GIT_USERNAME}
          user_email: {TARGET_GIT_EMAIL}

Bước 3.4: Triển khai Kích hoạt Pages thông qua API GitHub CLI

Nếu repository mới được khởi tạo và chưa được cấu hình Pages trong Settings, đại lý phải thực thi lệnh gọi API để kích hoạt:

echo '{"source": {"branch": "gh-pages", "path": "/"}}' | \
gh api --method POST /repos/{GITHUB_OWNER}/{REPOSITORY_NAME}/pages --input -

4. XỬ LÝ LỖI THƯỜNG GẶP (TROUBLESHOOTING & FAILURE MODES)

• Lỗi 404 sau khi deploy:
  • Nguyên nhân: Cấu hình baseUrl trong docusaurus.config.ts không khớp với tên repo GitHub Pages (ví dụ: repo tên là {REPOSITORY_NAME} nhưng baseUrl để mặc định là /).
  • Giải pháp: Sửa baseUrl thành /{REPOSITORY_NAME}/ và sửa url thành https://{GITHUB_OWNER}.github.io.
• Lỗi biên dịch LaTeX/Math:
  • Nguyên nhân: Thiếu plugin remark-math hoặc rehype-katex trong cấu hình Docusaurus, hoặc chưa import file CSS của KaTeX.
  • Giải pháp: Cài đặt đúng các package và import @import "https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css"; vào tệp CSS tùy chỉnh.

5. BẢNG TIÊU CHUẨN XÁC MINH HOÀN THÀNH (VERIFICATION CHECKLIST)

Đại lý bắt buộc phải thực thi các lệnh shell sau để kiểm định tính tuân thủ của dự án trước khi kết thúc tác vụ: