Hệ thống luyện thi IELTS 4 kỹ năng (Writing, Reading, Listening, Speaking)
chạy trên DeepSeek Harness (dsh web) — khép kín vòng lặp "tạo test → làm
test → chấm điểm" trong một màn hình duy nhất tại http://127.0.0.1:3080:
Bạn: "tạo bài writing test 1 cambridge 2 cho tôi"
→ agent (skill ielts-teacher) tạo test HTML
→ tool ielts_open_test → GUI render iframe bài test NGAY TRONG khung chat
→ bạn làm bài + bấm Submit trong iframe
→ plugin ielts-grader phát hiện bài nộp → tự đánh thức agent
→ agent chấm điểm, trả feedback + band, cập nhật hồ sơ học viên
→ KHÔNG cần gõ "chấm bài", KHÔNG mở tab trình duyệt riêng
- 4 kỹ năng + full mock: test HTML tự tạo từ Cambridge JSON hoặc web research; full mock 4 tab, chấm cross-skill.
- Embedded test panel: bài test hiện ngay trong khung chat (iframe), không rời GUI.
- Auto-grade: nộp bài xong ~1.5s, agent tự thức dậy chấm điểm, trả
feedback chi tiết + điểm band, cập nhật
student-profile.json. - Speaking: ghi âm trong iframe, chấm phát âm bằng Azure Speech (continuous recognition, per-word + intonation).
- Hồ sơ học viên: theo dõi tiến độ, SRS từ vựng/ngữ pháp, lesson library, diagnostic + calibration theo chuẩn điểm.
- Chạy bằng Python stdlib-only (không cần pip/venv) + plugin JS ESM không cần build (server plugin).
┌────────────────────────── dsh web (127.0.0.1:3080) ──────────────────────────┐
│ GUI chat │
│ └─ client plugin @dsh-ielts/test-panel (Conversation Node) │
│ └─ iframe ──► http://localhost:8765/test-html/xxx.html │
│ │
│ Host (cùng process dsh web) │
│ ├─ server plugin @dsh-ielts/grader │
│ │ ├─ tool ielts_open_test (model-facing) │
│ │ └─ watcher .ielts/{skill}/latest.json → agent.followup() (auto-grade) │
│ └─ skill registry (standard preset) — .dsh/skills/* (10 skills) │
└───────────────────────────────────────────────────────────────────────────────┘
│ POST /save, /check-text-answers ▲ followup (plugin)
▼ │
python3 .dsh/skills/ielts-teacher/server.py ───────► agent chấm điểm
(File Bridge, cổng 8765 — stdlib-only, chạy nền) (latest.json +
phases/evaluate-*.md)
Cơ chế chính: plugin client dùng ConversationNodeDefinition để render iframe
từ event tool/call của ielts_open_test; plugin host dùng
agent.followup() với marker [ielts:submit] để đánh thức agent đang idle.
Plugin nạp qua profile layer của dsh (không sửa checkout deepseek-harness).
Bộ cài đặt chính thức nằm ở setup/ — dùng khi cài máy
mới hoặc sau khi clone repo về.
| Bạn cần | Đọc / dùng |
|---|---|
| Cài từ đầu (máy mới) | setup/01-INSTALL.md |
| Cài nhanh một lèo | ./setup/install.sh |
| Nhờ AI cài giúp (vibe-code) | setup/03-VIBE-INSTALL.md |
| Lỗi gặp phải / fix đã biết | setup/02-FIXES.md |
| Cách dùng sau khi chạy | setup/04-USAGE.md |
| Cài lại plugin sau khi build lại dsh (upgrade) | setup/05-REINSTALL.md |
Điều kiện: Node ≥ 20, pnpm ≥ 9, Python 3 ≥ 3.10, git (+ uv nếu dùng
Speaking — xem mục 2 của setup/01-INSTALL.md).
Bắt buộc: cài DeepSeek Harness (dsh) trước. Toàn bộ hệ thống chạy trên dsh — plugin IELTS nạp qua profile layer (
$DSH_HOME/profiles/web/), repo này không tự chạy độc lập được. Cách A (khuyên dùng): clone +pnpm install+pnpm run buildnhư bước 1 bên dưới. Cách B: chạy thẳngnpx @deepseek-ai/dsh web— path config giữ nguyên (xem setup/01-INSTALL.md mục 0, Cách B).
# 1. DeepSeek Harness (nền chạy toàn bộ — BẮT BUỘC cài trước):
# clone tại ~/ → tạo thành thư mục ~/deepseek-harness
cd ~ && git clone https://github.com/deepseek-ai/deepseek-harness.git
(cd ~/deepseek-harness && pnpm install && pnpm run build)
# 2. Clone repo này: phải vào ~/work/ (tạo nếu chưa có) rồi mới clone
mkdir -p ~/work && cd ~/work
git clone https://github.com/chauvanphuoc/ielts-deepseek.git
cd ~/work/ielts-deepseek
# 3. Cài đặt một lần: tạo profile, link 2 plugin, cài cordis.patch.yml, .env
cp .env.example .env # điền key: AZURE_SPEECH_KEY/REGION, LLM_API_URL/KEY/MODEL
./setup/install.sh
# 4. Chạy
cd ~/deepseek-harness && pnpm dsh web # mở http://127.0.0.1:3080,
# chọn workspace ielts-deepseek trong GUIClone không nằm ở
~/work/ielts-deepseek? ExportIELTS_DIR=/đường/dẫn/tới/ielts-deepseek/.ieltstrước khi chạy dsh — xemsetup/cordis/README.md.
Cách nhanh nhất trên máy mới: mở thư mục clone trong VSCode (dùng
Claude Code
hoặc Cursor), rồi dán prompt bên dưới — AI sẽ tự cài
đặt, tự kiểm tra và báo cáo. Prompt đầy đủ (tiếng Anh) ở
setup/03-VIBE-INSTALL.md; bản rút gọn:
Cài giúp ielts-deepseek trên máy này theo setup/01-INSTALL.md (đã có đủ docs
trong repo). Tóm tắt: clone deepseek-harness về ~/deepseek-harness rồi
pnpm install && pnpm run build; clone repo này về ~/work/ielts-deepseek; chạy
./setup/install.sh; điền key vào .env (hỏi user, đừng in ra); kiểm tra
smoke-test plugins/ielts-grader; khởi động bằng cd ~/deepseek-harness && pnpm dsh web
và xác nhận http://127.0.0.1:3080 (workspace ielts-deepseek). Nếu gặp lỗi, đọc
setup/02-FIXES.md trước khi tự sửa. Báo cáo ngắn gọn cuối cùng.
Lưu ý khi cài bằng AI: mở assistant tại thư mục clone của ielts-deepseek
(workspace root phải là project này — nếu không, skill .dsh/skills và dữ
liệu .ielts sẽ trỏ sai); không dán key vào prompt (có thể bị log) — cứ để
.env trống rồi tự điền sau.
Xem setup/01-INSTALL.md — kiểm tra điều kiện tiên
quyết, cài DeepSeek Harness, clone repo, chạy installer, điền key vào .env,
verify (plugin rows + smoke test), khởi động.
Sau khi chạy pnpm dsh web và mở http://127.0.0.1:3080 (chọn workspace
ielts-deepseek — bắt buộc):
- Gõ: "tạo bài writing test 1 cambridge 2 cho tôi" (hoặc reading/listening/ speaking/full mock — đủ 4 kỹ năng).
- Agent tạo test HTML, chạy
python3 server.pynền (nếu chưa chạy), gọiielts_open_test→ iframe hiện ngay trong chat. - Làm bài trong iframe → bấm Submit (writing: Submit & Get Claude Evaluation; speaking: record từng câu rồi Save All Results).
- Sau ~1.5s: agent tự thức dậy, chấm bài, trả feedback + điểm band — không cần gõ gì thêm.
Hướng dẫn chi tiết: setup/04-USAGE.md.
ielts-deepseek/
├── .dsh/skills/ # skill roots của dsh (rank 100, project-local)
│ ├── ielts-teacher/ # skill chủ: SKILL.md + server.py + templates/ + phases/
│ └── … # 10 skills: writing/reading/listening/speaking/…
├── shared/ # ielts_cli.py, generate_test_html.py, dữ liệu test JSON
├── .ielts/ # dữ liệu runtime (chỉ seed được track: profile, kc-graph…)
├── plugins/
│ ├── ielts-grader/ # server plugin: tool ielts_open_test + watcher + followup
│ └── ielts-test-panel/ # client plugin: Conversation Node iframe
├── setup/ # ★ bộ cài đặt chính thức (README.md là index)
├── scripts/
│ ├── link-plugins.sh # symlink 2 plugin vào $DSH_HOME/profiles/web
│ └── sync-skills.py # đồng bộ skills + tái áp chuyển đổi dsh
└── textbook/ # tài liệu gốc (mp3, ảnh, markdown)
Các lỗi đã fix + cách xử lý đầy đủ ở setup/02-FIXES.md.
Nhanh gọn:
- "plugin not found" khi boot: chạy lại
./scripts/link-plugins.sh, kiểm trals -la ~/.dsh/profiles/web/node_modules/@dsh-ielts/. - Iframe trắng / không nạp CSS: server.py chưa chạy —
lsof -i :8765 | grep LISTEN || python3 server.py &. - Không tự chấm sau submit: kiểm tra
.ielts/writing/latest.jsoncó_savedAtmới; xem log dsh web cho dòng[ielts-grader]. - Không thấy tool
ielts_open_test: session phải thuộc preset có tools (standard mặc định).
- Đã test đầy đủ trên GUI: writing + auto-grade loop (13/13 smoke test); listening/reading/speaking/full mock đã chứng minh phía host qua smoke test nhưng chưa chạy hết trên GUI thật.
- Speaking cần
AZURE_SPEECH_KEY+ góiazure-cognitiveservices-speech(uv pip install azure-cognitiveservices-speech) +afconvert(macOS, có sẵn) hoặcffmpeg(Linux/Windows — xem hướng dẫn cài từng OS ở setup/01-INSTALL.md mục 2). - Khi sửa code client plugin: build lại bundle rồi restart dsh web.
MIT — xem LICENSE.