让任何 AI 都能为任何语言生成可信编程课程的框架——AI 填内容，验证器保真，反糊弄机制保证学会而不是感觉学会。
克隆这个仓库，把它交给你手边任何一个 coding agent（CLI 的、IDE 里的都行），它就能照着仓库里的规范， 为任何编程语言生成一门经过机器验证的交互式编程课：题目、教材、判题、复习调度全部齐活。
AI 生成的教学内容不可信？这正是本框架要解决的问题。每道题的参考解必须真跑全绿， 每个故意写错的「变异解」必须真跑全红，教材里每个代码块必须真跑出声明的输出—— 不过验证器的内容，一道也进不了课程。而在学习端，一套反糊弄机制确保学习者「学会了」， 而不是「感觉学会了」。
git clone <本仓库地址> codegym
cd codegym
python3 server.py零依赖、零构建：只用 Python 标准库（Python 3.9+）。然后浏览器打开 http://localhost:8775，内置的示例课程已经在那里了。
[CodeGym] 内容: 13 模块 / 200 题
[CodeGym] 0.0.0.0:8775 就绪
- 端口默认 8775，可用环境变量改：
CODEGYM_PORT=9000 python3 server.py - 学习进度存在本目录的
progress.db（SQLite），删掉即重置 - 判 JavaScript 题需要系统装有
node命令；Python 课程什么都不用装
内置示例课程：Python 从零到独立写小系统——13 个模块、68 道题、132 个变体、53 篇课文。
- AI 填内容：你的 coding agent 按 CONTENT_SPEC.md（内容格式规范）和 AUTHORING_GUIDE.md（作业指南）产出课程——题目、变体、教材，任何语言。
- 验证器保真：
python3 tools/validate.py把每道题真跑一遍——参考解必须全绿、变异解必须全红、 教材代码块必须逐块真跑。任何一条不过，内容禁止上线：烂题比没题更害人。 - 反糊弄学习机制：子进程沙箱判题（10 秒超时强杀）、冷启动门槛（看过提示或参考解就不算学会）、 渐进披露（提示按失败次数解锁）、1/3/7/14/30 天变体回访（对抗遗忘）、模块门（随机抽变体闭卷重考）。
第 1 步：把仓库交给 AI，让它读规范、交大纲。
对它说（示例）：
读这个仓库的 CONTENT_SPEC.md 和 AUTHORING_GUIDE.md，再读示例课程 courses/python/m00 当样板。 为 Go 写一门零基础课程，先只交课程大纲（模块划分 + 每模块课题数），不要开始写内容。
Python / JavaScript 开箱即判；其他语言需要 AI 顺手写一个判题适配器——
adapters/ 目录下约 100 行，照着 python_adapter.py 的三个函数接口写即可。
第 2 步：按模块生产，每完成一个模块就验证一次。
按 AUTHORING_GUIDE.md 的七步工作流写 m00 的全部题目和课文，然后跑
python3 tools/validate.py m00，按报错修到全绿，再继续下一个模块。
第 3 步：全绿后重启服务。
内容在启动时加载，重启 python3 server.py 即可看到新课。验证器全绿 = 参考解全绿 + 变异全红 +
schema 完整 + 教材代码块逐块真跑通过。
server.py 引擎：判题调度、进度库（SQLite）、渐进披露、变体回访、模块门、口令门
adapters/ 判题适配器：python_adapter.py、javascript_adapter.py（新语言=新文件）
courses/python/ 示例课程：13 模块 / 68 题 / 132 变体 / 53 篇课文
web/index.html 单文件前端
tools/validate.py 内容验证器（参考解必绿、变异必红、教材代码块逐块真跑）
CONTENT_SPEC.md 内容格式规范（唯一事实源）
AUTHORING_GUIDE.md 写给内容生产 AI 的作业指南（七步工作流 + 十大陷阱）
PITFALLS.md 本框架已预解决的坑档案（每个机制背后是一个真实失败模式）
| 机制 | 规则 |
|---|---|
| 判题 | 子进程沙箱运行，10 秒超时强杀并判红；func 模式跑隐藏断言测试，io 模式比对 stdin/stdout |
| 冷启动通过 | 零提示、没看过参考解、自己写出的代码跑绿——三条全满足才算「学会」这道题（允许失败重试） |
| 渐进披露 | 第 1 次失败只告知哪条挂；满 4 次可解锁提示（共 3 条，用了即失冷启动资格）；满 6 次或用完提示可看参考解（该题永不算冷启动通过） |
| 变体回访 | 冷启动通过后第 1/3/7/14/30 天，换一个同技能变体题重新闭卷通过 |
| 模块门 | 本模块全部题目冷启动通过后开考：随机抽 2 个变体，全部冷启动通过才解锁下一模块 |
| 口令门 | 局域网可用：config.json 里写 {"code": "你的口令"}，请求带 X-Code 头；连错 5 次锁 120 秒 |
- CONTENT_SPEC.md — 内容格式规范：课程/模块/题目/教材的完整 schema 与验证器检查项
- AUTHORING_GUIDE.md — 作业指南：内容生产 AI 的七步工作流、十大陷阱、完工定义
- PITFALLS.md — 坑档案：框架每个机制背后预解决的真实失败模式
A framework that lets any AI generate trustworthy programming courses in any language — the AI writes the content, the validator keeps it honest, and anti-fooling mechanics make sure learners actually learn instead of feeling learned.
Clone this repo, hand it to any coding agent you already use, and it can produce a machine-verified, interactive programming course in any language: challenges, lessons, a judging sandbox, and a review schedule, all included.
Distrust AI-generated teaching content? That is exactly what this framework solves. Every reference solution must actually run green, every deliberately-broken mutant must actually run red, and every code block in the lessons must actually produce its stated output. Content that fails the validator never ships. On the learning side, a set of anti-fooling mechanics ensures the learner truly learned — not just feels learned.
git clone <this repository> codegym
cd codegym
python3 server.pyZero dependencies, zero build steps — Python standard library only (Python 3.9+). Open http://localhost:8775 and the bundled sample course is already there.
- Default port 8775; override with
CODEGYM_PORT=9000 python3 server.py - Progress lives in a local
progress.db(SQLite); delete it to reset - Judging JavaScript requires a system
node; Python courses need nothing extra
Bundled sample course: Python, from zero to writing small systems on your own — 13 modules, 68 challenges, 132 variants, 53 lessons.
- AI fills the content: your coding agent produces courses — challenges, variants, lessons, in any language — following CONTENT_SPEC.md and AUTHORING_GUIDE.md.
- The validator keeps it honest:
python3 tools/validate.pyactually runs every challenge — the reference solution must pass all tests, mutants must fail them, and every lesson code block must run. Anything that fails is barred from shipping: a bad challenge is worse than no challenge. - Anti-fooling learning mechanics: sandboxed judging (10s hard timeout), a cold-start bar (peeking at hints or the reference solution disqualifies "learned"), progressive disclosure, variant re-testing at 1/3/7/14/30 days, and module gates that re-test random variants.
Step 1 — Hand the repo to your agent and ask for an outline first:
Read CONTENT_SPEC.md and AUTHORING_GUIDE.md in this repo, plus the sample module courses/python/m00. Plan a zero-to-hero Go course. Deliver only the outline (modules + challenge counts) — do not write content yet.
Python and JavaScript are judged out of the box; other languages need a ~100-line adapter in
adapters/, modeled on python_adapter.py.
Step 2 — Produce module by module, validating each:
Write all challenges and lessons for module m00 following the seven-step workflow in AUTHORING_GUIDE.md. Run
python3 tools/validate.py m00and iterate until green.
Step 3 — Restart the server. Content loads at startup.
- CONTENT_SPEC.md — the content format specification (single source of truth)
- AUTHORING_GUIDE.md — the working guide for authoring agents
- PITFALLS.md — the archive of pitfalls this framework already solved