StudyLings

Project Overview / 项目概述

StudyLings is a unified interactive self-study platform that consolidates 14 independent learning projects under a single shared Python framework. Inspired by the Rustlings model of exercise-driven learning, it delivers 854 fill-in-the-blank exercises spanning economics, classical and quantum physics, generative AI, CUDA GPU programming, reinforcement learning, algorithms, data structures, multi-processor concurrency, Vulkan graphics, and more. The name is a portmanteau of the project family: every sub-project carries the “lings” suffix (Cudalings, Economlings, Genlings, …) to signal its membership in the suite.

StudyLings 是一个统一的交互式自学平台，将 14 个独立学习项目整合在同一个 Python 框架下。受 Rustlings 填空式学习模式的启发，该平台提供了 854 道练习题，覆盖经济学、经典物理与量子物理、 生成式 AI、CUDA GPU 编程、强化学习、算法、数据结构、多处理器并发、Vulkan 图形接口等多个领域。

Situation & Motivation / 背景与动机

Self-directed learners face a common problem: each specialised topic (CUDA, quantum computing, reinforcement learning, …) comes with its own isolated set of exercises, its own runner script, and its own ad-hoc feedback mechanism. Switching between projects means relearning tooling, not just content. The cognitive overhead of managing multiple incompatible CLIs is a genuine barrier to continuous learning.

自学者面临一个普遍问题：每个专业领域（CUDA、量子计算、强化学习等）都有各自独立的练习集、运行脚本和反馈机制。 在项目之间切换意味着要重新适应工具，而非专注于内容本身。管理多个不兼容 CLI 工具的认知负担，是持续学习的真实障碍。

Task & Design Goals / 目标与设计

The goal was to build a single framework that any learning project can plug into with minimal configuration, while preserving the full exercise corpus unchanged. Each project needed to expose exactly the same 9-command CLI surface (list, run, next, verify, watch, hint, progress, solution, reset) so that learners could transfer skills across domains instantly. An aggregate “suite dashboard” would give a birds-eye view of progress across all 14 projects simultaneously.

设计目标是构建一个单一框架，任何学习项目只需少量配置即可接入，同时保持练习文件本身不变。 每个项目需要暴露完全相同的 9 个 CLI 命令（list、run、next、verify、watch、hint、progress、 solution、reset），使学习者能够在不同领域之间无缝切换。一个聚合的“套件仪表板” 提供对所有 14 个项目进度的全局视图。

Action & Implementation / 实施细节

The shared studylings package contains six core modules:

• cli.py — 9 unified Click commands driven by a ProjectConfig object
• exercise.py — discovery and metadata extraction across .py, .cpp, .cu, .ts, and .c files
• checker.py — three pluggable validation modes: test_file (external test runner), verify_func (embedded verify() + # I AM NOT DONE markers), and compile_and_run (cmake/make then execute) for C/C++/CUDA projects
• progress.py — unified JSON progress store with per-chapter granularity
• watcher.py — file-system watch with automatic advance to the next incomplete exercise
• ui.py — Rich terminal output with colour-coded progress bars

Each of the 14 sub-projects is a thin configuration wrapper: a config.py that instantiates a ProjectConfig (name, chapters, validation mode, language, …) and a __main__.py that calls studylings.cli.main(config). The entire exercise corpus — totalling 854 exercises across languages ranging from CUDA C++ to TypeScript — is left completely untouched.

StudyLings/
├── studylings/              # Shared core framework
│   ├── cli.py               # 9 unified Click commands
│   ├── exercise.py          # Discovery & metadata
│   ├── checker.py           # 3 pluggable validators
│   ├── progress.py          # JSON progress tracking
│   ├── watcher.py           # File watch + auto-advance
│   └── ui.py                # Rich terminal output
├── Gen-AI-Study/            # Thin config wrapper (example)
│   ├── genailings/
│   │   ├── config.py        # ProjectConfig(...)
│   │   └── __main__.py      # → studylings.cli.main(config)
│   └── exercises/
└── ... 13 more projects ...

Results & Impact / 成果与影响

The suite covers 14 projects and 854 exercises without a single duplicated runner. Adding a new project requires only two files (config.py + __main__.py) and zero framework changes. The watch mode and progressive hint system (up to N configurable hint levels per exercise) reduce friction for beginners, while the compile-and-run validator handles CUDA/C++ projects that cannot be validated purely in Python. The GitHub Pages project site aggregates all projects into a single browsable catalogue.

该套件涵盖 14 个项目、854 道练习题，且无任何重复的运行器代码。新增一个项目只需两个文件 （config.py + __main__.py），无需修改框架。Watch 模式和渐进式提示系统（每道题可配置 N 个 提示级别）降低了初学者的门槛；compile-and-run 验证器则处理无法纯 Python 验证的 CUDA/C++ 项目。 GitHub Pages 项目网站将所有项目汇聚成一个可浏览的统一目录。

['14 interactive self-study projects unified under a single Python framework — zero duplicated runner code', '854 exercises across economics, physics, GenAI, quantum computing, CUDA, RL, algorithms, TypeScript async, and Vulkan graphics', '9-command unified CLI (list / run / next / verify / watch / hint / progress / solution / reset) shared across all projects', 'Three pluggable validation modes: external test files, embedded verify() functions, and cmake compile-and-run for C/C++/CUDA', 'File-system watch mode with automatic advance to the next incomplete exercise on save', 'Suite dashboard aggregates progress across all 14 projects simultaneously via python -m studylings', 'Adding a new project requires only two files (config.py + __main__.py) — no framework modification needed', 'Multilingual exercise corpus: Python, CUDA C++, C, C++, TypeScript all handled by a single discovery engine']