---
name: learn-by-running-code
description: 将一个 Python 学习主题设计成按 01_、02_ 编号的渐进式可运行代码仓库，通过阅读、运行和修改极简示例掌握知识。用户只要提到“做一个学习仓库”“按章节用代码学”“边运行边学”“把某个 Python 主题拆成可运行示例”或希望用项目化方式系统学习 Python 库、框架、协议和工程概念，就应使用本 Skill。它负责从主题调研、课程大纲确认到 uv 仓库生成与逐章验证；不用于单纯讲解已有仓库或把现有项目改造成作业课程。
---

# Learn by Running Code

把一个待学习的 Python 主题变成一套小而完整的代码课程。学习者先看到可运行结果，再从代码中理解概念；每章只增加一个认知负担。

## 边界

使用本 Skill：

- 从一个知识主题创建新的教学仓库；
- 把 Python 库、框架、协议或工程概念拆成渐进章节；
- 生成能够独立运行、便于修改和观察的极简代码。

不要使用本 Skill：

- 用户只想理解一个现有仓库：改用项目学习类 Skill；
- 用户要从现有源码提炼讲义、作业和判题：改用课程化或 ProMentor 类 Skill；
- 用户只问一个可以直接回答的概念问题，不需要创建仓库。

## 按需加载的资源

- 规划大纲前读取 [references/curriculum-design.md](references/curriculum-design.md)。
- 创建文件前读取 [references/repository-contract.md](references/repository-contract.md)。
- 生成仓库时复用 `assets/` 中的模板，但要按主题替换占位符，不要原样复制。
- 生成后运行 `scripts/validate_learning_repo.py <repo>` 做确定性检查。

## 工作流

### 1. 明确学习任务

先从对话中提取以下信息，已有答案就不要重复询问：

- 主题和明确排除的内容；
- 学习者已有知识；
- 学完后希望能构建、解释或调试什么；
- 是否允许联网、调用付费 API、使用数据库或安装本地服务；
- 目标目录。

只有会改变课程结构的信息缺失时才提问。默认值为：懂基础 Python、不熟悉目标主题、Python 3.12、uv、5～7 章、中文教学说明、英文代码标识符、优先离线免费示例。

### 2. 用一手资料校准内容

第三方库和快速变化的 API 不能只凭记忆设计课程：

1. 查看官方文档、官方仓库、发布说明或当前安装版本；
2. 确认推荐 API、最低 Python 版本和安装包名；
3. 区分“官方事实”“根据资料做出的课程设计”和“尚未验证的假设”；
4. 记录资料链接、核对日期和最终选用版本，供根 README 使用。

不要为了堆砌资料扩大主题。调研的目的只是保证示例不过时、命令能运行。

### 3. 先提交课程大纲

创建任何仓库文件之前，先在对话中给出：

- 一句话课程目标；
- 学习者画像和完成标准；
- 统一贯穿案例；
- 章节表：序号、章节名、本章唯一新增概念、前置章节、运行后能观察到什么、是否需要网络或凭据；
- 最终项目和明确不包含的内容；
- 计划采用的 Python 与关键依赖版本。

必要时用 Mermaid 表示非线性依赖，不要用字符树。等待用户明确确认这份具体大纲。用户只说“帮我创建一个学习仓库”不等于确认；用户已经提供并明确确认过完整大纲时可以直接进入下一步。

### 4. 安全地创建仓库

用户确认后再写文件：

1. 检查目标路径；目标不存在时创建，目标为空时使用，目标非空时先报告冲突，不覆盖已有文件；
2. 按仓库契约创建 uv 项目和连续编号的章节目录；
3. 用同一个小型场景贯穿课程，但每章必须能从仓库根目录直接运行，不能依赖先执行上一章产生的状态；
4. 代码先展示核心机制，再解释抽象。保留能帮助理解“为什么”的注释，删除逐字复述语法的注释；
5. 不在关键路径使用 `...`、伪代码或未定义占位函数；
6. 仅把真正跨章稳定的配置和假数据放入 `shared/`，不要为了追求目录层次拆散小示例；
7. 需要密钥时只提交 `.env.example`，示例值必须是假值；在 README 标注网络、费用和数据外发风险。

### 5. 验证而不是声称

从干净状态验证：

1. 运行 `uv lock` 和 `uv sync`；
2. 运行本 Skill 自带的结构验证脚本；
3. 逐章运行所有不需要凭据或外部服务的命令，并核对 README 中的预期现象；
4. 对在线章节至少完成 Python 语法、导入和缺少配置时的错误提示检查；
5. 不把“读过代码”写成“运行通过”。分别报告已运行、仅静态检查和因何未验证。

遇到失败时先修复最小示例或文档，再交付。不要把失败命令留给学习者自行猜测。

### 6. 交付学习路线

最终简洁报告：

- 仓库位置；
- 30 秒启动命令；
- 推荐从哪一章开始；
- 实际运行通过的章节；
- 需要用户自行提供凭据或服务的章节；
- 采用的主要资料与版本。

不要一次性把所有章节重新讲一遍，仓库本身就是主要教学产物。

## 完成标准

只有同时满足以下条件才算完成：

- 用户确认过课程大纲；
- 章节编号连续，每章只承担一个主要新增概念；
- 根 README 中的每条章节运行命令都存在；
- `uv.lock` 已生成，离线章节在同一干净环境中实际运行通过；
- 外部依赖、费用、凭据和未验证项均已明确说明；
- 没有覆盖用户原有文件，也没有写入真实密钥。