# learn-python-ai-games

**Repository Path**: smartian123/learn-python-ai-games

## Basic Information

- **Project Name**: learn-python-ai-games
- **Description**: AI辅助小学生学习python入门
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 萌芽 · Python Playground v0.5.3

用真实 Python 完成游戏任务，从理解概念、短练习、主线项目，走到新场景中的独立应用。面向初学者，AI 提供自然语言提示，玩家亲自编写代码。

## 直接体验

打开 `release-v0.5.3/win-unpacked/Python Pet Academy.exe`。请保留整个文件夹；包含 Python 3.13.15，无需另装 Python。原来的发布目录保留，便于对照旧版。

## 学习路线

| 推荐顺序 | 游戏 | 主线能力 | 独立挑战 |
|---|---|---|---|
| 1 | 密室逃脱 | 输出、输入、类型、条件、循环、容器、函数 | 救援背包 |
| 2 | 出城工坊 | 转换、编号、配对、集合、统计与排序 | 训练成绩单 |
| 3 | 时光档案馆 | 文本文件、JSON、追加、异常与存档 | 休息站存档 |
| 4 | 怪兽交易所 | JSON 文件增删改查、输入校验与日志 | 补货提醒 |
| 5 | 情报破译局 | 清理、正则、类型转换、去重、分组汇总 | 玩家收获榜 |
| 6 | 电影寻宝队 | 页面获取、解析、排序与 JSON 片库 | 周末片单 |
| 7 | 星际传令 | TCP、UTF-8、消息边界、JSON 协议与状态 | 空间站回声协议 |

保留 59 个主线任务、7 个热身和 7 个独立挑战，共 73 个练习。沿用 v0.5.1 的短任务估时：主线预计 10 小时，热身和独立挑战共 2 小时 3 分，总计约 12 小时 3 分。热身 3–5 分钟，多数小任务 5–12 分钟，较复杂任务约 15 分钟，综合关 20–30 分钟。时长只是参考，不是倒计时；通过检查即可继续，不需要凑满时间。七个主题仍可以分多个学习日完成。

v0.5.2 补齐首次使用前的变量、赋值、基本类型、数值打印和字符串替换讲解。在背包任务中先比较 list、tuple、dict、set，再使用下标等操作；工坊继续练习删除、合并、拆包与排序。身份、体力和回廊任务不再要求额外的 result 容器。详见 [前置知识与骨架审查](docs/v0.5.2前置知识与骨架审查.md)。

热身分别练习输入、元组解包、函数返回、退出循环、取余巡逻、逐行清理和单个正则捕获组。主题通关需要主线、该主题全部热身、独立挑战以及至少 10 字的复盘全部完成。提示次数照常记录；不点提示本身不能证明独立掌握。

## 游戏与操作

- v0.5.3 知识工具箱只展示本任务知识与函数说明，移除主题总览；代码编辑、运行和结果集中到“当前任务”。
- 示例输出不再额外显示变量，不打印就不会自动产生输出。比较、分支、集合、文件与正则等概念补充了可运行例子和结果解释。
- 缩进可以按 Tab，编辑器自动插入四个空格。函数说明解释参数、返回值与运行效果，明确 input 会等待回车、print 负责显示。

- 第一关只要求三行真实输出和注释，不必先创建列表；输出自动点亮横幅。
- 城堡显示代码产生的体力、钥匙与出口状态；货架显示实际商品和数量。
- 知识工具箱包含当前关知识卡和可展开的主题全景；示例可以运行。
- 热身、主线和独立挑战分别保存代码。切换任务回到页面顶部，任务说明不再套第二个滚动区。
- 编辑器支持行号、Tab 四空格、Ctrl+Enter 运行；运行按钮固定在可见底部，终端文字与代码字体加大。
- TCP 前两关提供完整服务端和接收循环，先补客户端，再自己写指令、协议和共享库存。先写好两端，再启动服务端；交互监听最多等待 90 秒，超时停止后重启。
- 请求以换行结束，响应以连接关闭结束；循环收齐字节后再统一解码，不能假设一次 recv 收到整条消息。

## 实际执行与检查

每个任务有独立练习目录：`missions-v3/day-N/task-N`；新增练习使用同主题的 `practice-ID`。同一任务重新运行保留文件，不同任务不共享存档。素材区显示真实文件；验收使用独立临时副本，不修改练习文件。

检查更换输入和文件，验证完整字段、顺序、输出、数字类型、写入与读回，以及空数据、边界和重复记录。字典键的书写顺序不影响判分。需要函数的任务检查实际调用，单纯定义一个没调用的函数不能满足要求。AI 不参与更改检查结论。

程序使用真实 Python 子进程、真实本机 TCP。课程提供受控的 json、re、socket、urllib.request 适配。文件访问限制在任务目录，TCP 限制在分配的 127.0.0.1 端口；默认单次运行 120 秒、输出 100 KB。它是教学运行器，并非完整 IDE 或操作系统级安全沙箱。

## 电影素材

默认提供三部虚构电影的模拟 HTML，界面明确标记来源，不代表实时评分。点击获取按钮时，客户端检查网站规则并获取一页公开榜单；Python 的 urlopen 读取选定来源的缓存响应。失败可继续用离线素材。检查使用离线变体，避免榜单变化影响判分。

同一来源重跑会保留 page.html；明确切换来源时才更新页面副本。正则只用于本课约定的有限 HTML 结构。v0.5 未重新验证豆瓣实时获取。

## AI 与进度

AI 配置支持服务基础地址、/v1 和完整 Chat Completions 地址；密钥由 Electron safeStorage 加密保存在本机。提问向用户配置的服务发送任务代码、问题、运行结果与近期对话。返回内容经过代码过滤，不会修改编辑器；另有三级离线提示。

v0.5 进度存储键为 `pet-academy-v8`。升级 v7 时保留现有代码、提示次数和运行次数，旧 v7 数据保留作备份；检查规则收紧的关卡重新验收，新练习默认未完成，主题徽章重新按完整条件判定。v6 仍保留原来的文件课程迁移规则。升级不删除练习文件。

明确执行设置中的重置会清除进度及旧版本备份键，把练习目录移入 `mission-archives`，AI 配置保留。

## 开发与验证

```powershell
npm install
./scripts/setup-python.ps1
npm start
npm test
npm run test:desktop
npm run pack
```

`npm run dev` 仅预览界面。参考实现位于 tests，仅开发验证使用，不打包进客户端。

自动测试覆盖全部 73 个练习、11 个试玩回归案例、知识示例、真实文件和 TCP、进度迁移、通关门槛和 AI 提示过滤。桌面测试覆盖基础主线、热身与迁移挑战、货架全流程、存档、双端通信和重启持久化。测试通过说明这些行为符合约定；是否适合真实零基础学习者，仍需后续用户试学验证。

主要实现：`src/curriculum.ts`、`src/learning.ts`、`src/progress.ts`、`src/App.tsx`、`src/AdventureBoard.tsx`；检查逻辑在 `electron/validation.cjs`、`electron/activity-checks.cjs` 与 `electron/file-checks.cjs`。新增练习定义在 `electron/learning-data.json`。

无账号云同步，Windows 包未签名。详见 [v0.5 优化说明](docs/v0.5优化说明.md)。