跳到主内容
芝麻园地
← 返回博客
#前端开发#编程教育#互动教程#Astro#React

把「理解程序→做出软件→开发Agent」做成在线互动实验场:三节样板课的MVP开发记录

芝麻园地在线编程互动实验场的首版实现记录:围绕三个真实异常(十份资料只整理出九份、刷新后数据消失、Agent 假完成)设计动手式学习流程,覆盖单步调试可视化、自由变量实验、渐进式 AI 助教与离线 Python 项目导出。分享教学设计与技术实现细节,以及人与 AI 智能体协同从方案到落地的完整过程。

芝麻园地 15 分钟

做编程学习内容久了,我一直有个强烈的想法:不要做「看视频 + 点一下运行」的单向输入课,而是让学生真正上手——看见预期和实际的差异、自由改变条件看系统反应、自己提出猜测再动手修复。

这个想法这次在芝麻园地落地成了第一个 MVP:在线编程互动实验场。

👉 在线体验入口:https://zhimayuandi.com/tutorial/interactive-coding

它不是什么大而全的在线开发平台,而是把「理解程序 → 做出软件 → 开发 Agent」这条主线,浓缩成了三个以真实异常为入口的样板课。这篇文章我想聊聊:它想解决什么问题、三个样板课怎么设计、背后用了哪些技术,以及我是怎么跟 AI 智能体协同,从一份方案文档把它真正做出来的。


一、为什么不用「点击运行」做互动编程?

传统在线编程教程的经典套路是:左边一段讲解,右边一个编辑器,学生点「运行」看输出。它的问题是——运行成功 ≠ 学会。学生只是照着敲,没有遇到意外,也没有做任何需要判断的取舍。

所以我们在方案阶段就定下两条铁律:

  1. 有趣来自探索与掌控感,不是积分徽章。真正的动机是「看到预期与实际的差异」和「自由改变条件看系统反应」。
  2. 必须能离开平台独立开发。每一阶段末尾,都要给学生一份能脱离浏览器、在本地带测试套件运行起来的独立 Python 源码。

围绕这个,整个课程设计成了一条递进的学习链:

体验异常 → 提出猜测 → 单步调试/自由试验 → 动手修复与用例评测 → 即时变式挑战 → 离线独立项目成果

每一个环节都对应一个明确的交互组件,学生在浏览器里就能走完「发现 bug → 定位 bug → 修复 bug → 验证 bug」的完整闭环。


二、三个样板课:用真实异常当入口

首版没有铺开八个知识模块,而是集中打透三个「任务式」样板课——每一课都从一个能直接上手、又有点反常识的真实异常开始。

S01:十份资料,为什么只整理了九份?

核心知识:循环遍历、Off-by-one 边界、变量追踪、单步调试器。

学生进入一个校园资料整理工具,点击「整理」后:前 9 张资料卡依次变绿进入已整理列表,第 10 份《校园二手书交易避坑指南》孤零零留在原处,闪烁红框。

  • 先提出猜测:给 3 个有迷惑性的选项,选错给出详尽的原理剖析;
  • 单步调试可视化:模拟单步解释器,具备「单步执行 / 自动播放 / 重置」,代码行黄色高亮同步跳动,旁边有变量监视区实时展示 len(docs)、range 上限、当前 i、已处理数;
  • 自由试验:把资料数量自由改成 0、1、3、10 份,让学生亲眼证实——无论多少份,最后一项都会被漏掉;
  • 动手修复 + 5 组自动化用例:内嵌代码编辑区,跑空列表、单项、常规、大跨度等边界用例;
  • 即时变式:换成「助教批改 8 份作业」场景,在没有任何步骤指引下独立修复一个 while 循环漏洞。

关键的“aha”藏在 range(len(docs) - 1) 里。Python 的 range(start, stop) 是左闭右开区间 [start, stop),当上界取 len(docs)-1 时,最后一个元素的下标从未被访问。

# 修复前:range(len(docs) - 1) 漏掉最后一个元素
for i in range(len(docs) - 1):
    ...

# 修复后:包含全部 len(docs) 个元素 [0, len(docs))
for i in range(len(docs)):
    ...

S02:明明点了保存,刷新后怎么没了?

核心知识:易失性内存变量 vs 持久化存储(LocalStorage / 文件 / 数据库)、防空防重防御性校验。

学生在收藏夹里添加一条资料,点「模拟刷新页面 (F5)」,内存瞬间重置,数据消失。

  • 存储策略矩阵:直观对比「内存变量」「LocalStorage」「服务端数据库」三种方案,让学生理解“同一浏览器刷新后保留”应该选哪种;
  • 数据流追踪:可视化展示读写闭环与防御性校验;
  • 动手修复:代码修复后,通过防空、防重与持久化三组测试;
  • 变式:实现一个待办便签的本地保存。

S03:资料都没找到,Agent 为什么说完成了?

核心知识:工具调用循环、结果证据核验、虚假完成(False Completion)拦截、有界重试与优雅降级。

这是我最想讲清楚的一课。学生触发 Agent 查询《2026年保研加分细则》,系统追踪日志完整展示:调用检索工具 → 工具返回 [] → Agent 却自信输出「任务完成!已成功为您整理保研细则…」。

  • Agent 循环图解:拆解「指令规划 → 工具调用 → 结果核验 → 决策分支」,树立「依据为先(Evidence-first)」的 Agent 编写准则;
  • 动手修复:增加空结果分支与异常降级分支;
  • 变式:实现一个带一次重试的工具调度器。

这一课想传递的价值观很直接:AI 的输出不等于正确性证据,工具的真实返回才是。这是面向大模型时代最重要的工程素养之一。


三、技术实现:轻量、安全、确定的浏览器沙箱

整站基于 Astro 5 + TypeScript (strict),交互层用 React 19 Islands(client:load,客户端毫秒级响应、零网络延迟),样式走 Tailwind CSS 全适配深浅色。

最核心的技术决策,是实现了一套轻量、安全、确定的微型代码评估器(在浏览器内安全地分析学生写的代码,而不是真的去执行任意 Python):

课程 评估器检测内容
S01 识别 range(len-1)(差一漏项)、range(len+1)(模拟越界 IndexError)、range(len) 与 for item in docs:(完美通过),并对 0/1/3/10/11 份五种边界数据独立推演
S02 检查 localStorage.setItem 持久化调用、标题非空校验、查重防重分支
S03 检查工具返回空列表的分支判定,严防 status: "COMPLETED" 的假完成

这套方案的好处是确定性:它不依赖真实执行,而是对代码做结构化判断,因此既能给学生可靠的用例反馈,又完全没有安全风险。

课程数据全部集中在 data/interactive-coding-lessons.ts,组件层在 components/interactive-coding/ 下分层清晰:

InteractiveCodingWorkbench.tsx   # 主工作台:样板课切换、步骤调度、进度存储
LessonS01Runner.tsx              # S01 交互器:资料卡流、单步解释器、测试套件
LessonS02Runner.tsx              # S02 交互器:收藏夹、F5模拟刷新、存储策略矩阵
LessonS03Runner.tsx              # S03 交互器:Agent执行追踪链、依据核验、重试调度
AiTutorCard.tsx                  # 阶梯式3级渐进提示 + 启发式追问助教
LocalProjectExporter.tsx         # 本地Python项目一键查看、复制与下载

两个细节值得一提:

AI 助教不做「代答先生」。 方案明确要求助教“优先追问学生看到了什么、怀疑哪里、打算怎样验证,不直接代写答案”。所以 AiTutorCard 做了三级阶梯展开:

  1. 观察方向:只提示聚焦位置,不泄露语法;
  2. 概念解析:讲透底层原理(比如 range(stop) 的左闭右开);
  3. 参考修改:才给示例语句。

再加一个对话追问栏,学生输入自己的思考,助教做启发式引导。

每课都能带走独立项目。 LocalProjectExporter 为三门课分别配了 3 个完整的 Python 独立单文件工程,内嵌测试套件与离线运行说明,支持一键复制、一键下载 .py 源码。这保证学生离开网页后,依然能真正地把“这门课的东西”跑在自己电脑上。

页面本身是中文单语配置(getStaticPaths 只输出 zh,hasEn={false} 不污染英文路由),配了完整的 SEO meta 与 Course / SoftwareApplication 双 JSON-LD,教程大厅首页也加了一张直达入口卡片。


四、人机协同:我是怎么让 AI 把方案变成产物的?

这次开发我想分享一个更值得记住的协作过程。很多人用 AI 写代码的挫败感是“一上来就让 AI 写,改十轮越改越乱”。这次我走的是**「先有文档契约,再让 Agent 流水线落地」**的路线:

  1. 先把方案聊透:docs/在线编程互动教程-方案.md 里已经写清了定位、受众、八个知识模块、三层课程路径、首版边界和验收标准——这是人与 AI 共同的需求契约;
  2. 让 Agent 拆解实施:AI 在 .gemini/ 下建立带时间戳的实施计划与任务清单,把“做 3 个样板课”拆成可追踪的步骤;
  3. 按文档写代码:AI 依据既定方案实现数据模型、沙箱评估器、6 个 React 交互组件群、Astro 页面与索引集成;
  4. 闭环验证:执行 astro check(0 errors, 0 warnings)与 pnpm build(588 个页面全部成功构建),再交付。

关键体会是:把思考留在文档阶段,编码落地就会顺畅。方案文档越清楚,AI 越不会跑偏,返工越少。这也正是 S01 想教给学生的道理——先拆清楚问题,再写代码。


五、验证与工程质量

遵循芝麻园地项目规范,做了完整验证:

  • 类型检查:pnpm exec astro check,1371 个文件 0 errors、0 warnings;
  • 静态构建:pnpm build,搜索索引生成完毕,588 个页面全部编译成功,dist/tutorial/interactive-coding/index.html 正常生成,零警告零报错,耗时 45 秒。

六、写在最后

这次 MVP 不是终点,而是验证“互动实验场”这条路的起点。首版只打透三个样板课,是为了先检验三件事:学生能不能快速进入任务?会不会主动改条件、反复尝试?换了场景后能不能独立完成?

后续的选题池里还排着「两个列表,为什么改一个另一个也变了?」「资料变多后,搜索怎么卡住了?」「点了按钮,为什么一直在等待?」…… 它们都遵循同一个原则:用一个有后果的真实异常,把编程思想讲明白。

欢迎你来体验这三节样板课,也欢迎提出建议:

🔗 在线编程互动实验场:https://zhimayuandi.com/tutorial/interactive-coding