ai-tutorials（AI 教程）

AI Course & Tutorial Design Guide

1. 核心理念

产出高质量的 AI 课程，由讲义和项目实战两部分组成。

• 项目是课程的精华和核心。学生通过动手做项目来真正理解概念
• 讲义是项目的铺垫，负责精炼地介绍重点概念，为项目扫清认知障碍

2. 工作流程（严格按顺序执行）

Step 0: 扫描项目目录               ──→  检测当前进度，决定从哪里开始
Step 1: 读取/创建 introduction.md  ──→  了解课程主要信息与学生背景
Step 2: 梳理知识点清单             ──→  输出 knowledge-points.md
Step 3: 用户确认知识点             ──→  ⛔ 未确认前不得生成大纲
Step 4: 生成 syllabus.md           ──→  将知识点组织为课程大纲
Step 5: 用户确认大纲               ──→  ⛔ 未确认前不得编写具体内容
Step 6: 逐节编写讲义 + 项目        ──→  产出课程内容
Step 7: 全面自查与代码验证         ──→  确保正确性与质量
Step 8: 生成 README + 配图         ──→  课程整体包装

Step 0: 扫描项目目录

每次被调用时，第一件事是扫描当前工作目录，根据已有文件判断课程进度，直接跳转到对应步骤。

⚠️ 如果用户显式指定了从哪一步开始，直接按用户指示执行，跳过自动检测。

自动检测规则——按以下顺序从下往上匹配，取最高进度：

跳转后，先向用户简要说明检测到的状态和即将从哪一步继续，再开始执行。

Step 1: 了解课程信息与学生背景

Step 1.1: 了解课程信息

• 读取或创建项目根目录下的 introduction.md
• 必须包含：

- 课程信息：课程名称、课程目标、总课时、授课形式

• 如果用户未提供，主动询问以上信息后写入 introduction.md

Step 1.2: 了解学生背景

• 读取或创建项目根目录下的 studentprofile.md
• 必须包含：

- 学生情况：技术背景、学习目标、可投入时间、已有 AI 经验

• 如果用户未提供，主动询问用户是否需要，如果需要，则询问以上信息后写入 studentprofile.md

Step 2: 梳理知识点清单

根据 introduction.md 中的课程目标、学生背景以及其中提及的关键知识点，全面梳理本课程需要覆盖的所有重要知识点，输出到 knowledge-points.md。

要求：

• 全面覆盖：结合课程主题，系统性地列出所有应覆盖的知识点，不遗漏关键内容
• 分类组织：按主题或模块对知识点进行分组，便于后续编排到大纲中
• 标注优先级：区分「必修/核心」和「选修/进阶」知识点
• 不涉及编排：此阶段只关注"教什么"，不关注"怎么排课"

Step 3: 确认知识点

⛔ 知识点清单必须经用户确认后，才能进入大纲设计阶段。 用户可能会增删或调整知识点。

Step 4: 生成课程大纲

将已确认的知识点组织编排为课程大纲，输出到 syllabus.md。 编排时需考虑：知识点的前后依赖关系、难度递进、每节课的信息量控制（2-3 个核心概念）。

大纲格式：

# 课程名称

## 课程信息
- 目标受众：...
- 总课时：X 节

## 课程目录
### 第 1 节：[标题]
- 核心知识点：...
- 项目任务：[一句话描述做什么]
- 学完能做到：...（可验证的学习成果）

Step 5: 确认大纲

⛔ 在开始编写任何具体讲义和项目之前，必须先让用户确认大纲。

Step 6: 编写课程内容

确认后，按大纲逐节产出讲义和项目。

文件组织

• 每节课一个文件夹：lesson{i}/
• 讲义和项目分开为两个文件：lecture.md 和 project.md
• 注意，项目可能是多个文件，其中project.md主要是项目内容描述。关于项目如果涉及到代码，可以在该课程下新建一个src/目录保存，如果涉及到其他也可以新建目录并保存文件。不鼓励什么都塞到project.md中

执行节奏

• 每次写完一节课后，暂停让用户确认，再继续下一节
• 如果用户明确要求批量生成，可连续产出，但每节仍需保持独立可审阅

断点续写

• 如果 Step 0 检测到部分 lesson*/ 已存在，读取 syllabus.md 确认总节数，只续写缺失的课节

Step 7: 全面自查与代码验证

所有内容产出完毕后，进行系统性自查，重点检查两个维度：

正确性检查

• 逐节核查讲义中的概念、术语、API 用法，确保无事实性错误
• 为每个项目亲自编写完整可运行代码，放入对应课节的 answer/ 文件夹
• 如需测试，在 test/ 文件夹中编写测试代码并实际运行，确认输出符合预期
• 发现错误立即回头修正项目文档中的对应内容

文件结构示例：

lesson1/
├── lecture.md
├── project.md
├── answer/        ← 完整参考实现，自己写并验证通过
│   └── main.py
└── test/          ← 测试代码（如有需要）
    └── test_main.py

可读性与质量检查

• 讲义：逻辑是否顺畅？概念是否解释清楚？是否为初学者写？
• 项目：脚手架是否完整？Task 拆分是否合理？验收标准是否可自检？
• 整体：各节难度是否递进？前后知识点是否衔接？

Step 8: 生成 README + 配图

生成课程 README

在课程根目录生成 README.md，内容包括：

• 课程简介与目标受众
• 课程目录（每节标题 + 一句话描述项目）
• 环境配置说明（统一的依赖安装）
• 学习建议（如何使用本课程）

询问用户是否生成配图

⛔ 必须先询问用户，再决定是否生成配图。

询问时需要确认两件事：

1. 是否需要配图
2. 如果需要，使用什么方式生成（例如：代码生成（matplotlib/PIL）、调用图片生成 API/MCP、生成 prompt 由用户自行生成等）

确认后，为每节课生成一张配图，要求：

• 文字部分：体现该节课的核心主题和关键知识点
• 图像部分：示意该节项目的实际效果或核心场景
• 配图风格统一，与课程整体调性一致
• 存放于对应 lesson{i}/ 文件夹下，命名为 cover.png

3. 讲义编写原则 (Lectures)

讲义的定位是为项目做铺垫，不是百科全书。

• 精炼克制：每节课聚焦 2-3 个核心概念，讲清楚就停，不堆砌
• 给出路标：底层原理和进阶内容附上补充链接，不在讲义中展开
• 服务项目：每个概念的讲解都应指向"你马上要在项目中用到这个"

4. 项目实战设计原则 (Projects)

项目是学生真正学会东西的地方，需要精心设计。

基本原则

• 每节必有动手任务：不能只有理论没有实践
• 项目安排灵活：可以一节一个小项目，也可以多节组合成一个大项目
• 紧扣知识点：项目必须直接运用本节讲义中的核心概念

项目模板

## 项目：[项目名称]

### 你将学到什么
通过这个项目，你将亲手体验 [核心概念] 在实际场景中的应用。

### 环境准备
- 运行环境：...
- 安装依赖：`pip install ...`
- 需要的 API Key / 账号：...

### 背景介绍
[用 2-3 句话描述项目场景和为什么要做这个项目，让学生理解上下文]

### 任务分解
#### Task 1：[子任务名称]
**目标：** [这一步要实现什么]
**提示：** [关键思路或需要用到的 API/函数]
**脚手架代码：**

给出起始代码框架，标注需要学生填写的部分

def your_function(): # TODO: 在这里实现 xxx pass

#### Task 2：[子任务名称]

...

#### Task 3：[子任务名称]

...

### 参考实现

完整的参考实现

### 验收标准

- [可自行检验的完成标准 1]
- [可自行检验的完成标准 2]
- [可自行检验的完成标准 3]

### 挑战任务（选做）

基础任务之上的进阶挑战，供学有余力的同学尝试：

- 挑战 1：[描述]
- 挑战 2：[描述]

设计要点

• 脚手架先行：给出起始代码框架，学生填核心逻辑，不要从空白文件开始
• 任务要拆细：大项目拆成 3-5 个小 Task，每个 Task 有明确目标，逐步推进
• 渐进式难度：前几节侧重"跟着做"，后期逐步转向"自己想、自己查、自己设计"
• 参考实现折叠：提供完整参考代码但默认折叠，鼓励学生先独立尝试
• 验收可自检：学生不需要老师就能判断"我做对了没有"
• 代码必须能跑：所有代码（脚手架和参考实现）必须完整可运行，含依赖和环境说明

5. 常见错误