project-learninglisted

# 交互式项目学习 用课堂式节奏带用户学习一个代码项目：先建立心智模型，再逐层读入口、配置、核心模块、数据流、测试和扩展点。每节课只讲一个可消化主题，并把高价值内容沉淀为 lesson 文档。 ## 目标 帮助用户真正掌握项目，而不是只得到一次性摘要。 交付物包括： - 学习路线图：按章节说明先学什么、后学什么。 - 课堂讲解：图、代码地图、调用链、数据流、关键函数解释。 - 互动检查：每节提出少量问题，确认用户是否理解。 - lesson 文档：把图、关键结论、用户困惑和已确认理解写入文档。 ## 适用场景 - 用户说“从小白角度理解项目”。 - 用户说“带着我读代码”。 - 用户说“交互式学习”。 - 用户说“把你讲的图/文字/总结写进 lesson/usebook”。 - 用户希望理解模块、函数调用、数据流、CLI 入口、配置、测试执行链路。 ## 基本原则 1. **先建地图，再读代码**：不要一上来逐行解释。先说明系统边界、入口、主链路和目录职责。 2. **每节只讲一个主题**：一次只学一个模块或一条调用链，避免信息过载。 3. **以真实文件为准**：讲解必须指向实际代码、配置和文档，不凭记忆编造。 4. **从调用链解释函数**：解释函数时说清楚它被谁调用、输入是什么、输出给谁、失败如何处理。 5. **把抽象概念落到数据流**：优先画 `输入 -> 处理 -> 输出`。 6. **互动优先**：每节结束前问 1-3 个检查问题；用户回答后纠偏，再进入下一节。 7. **课堂笔记只记高价值内容**：不做聊天全文转录，只记录图、代码地图、关键结论、易错点和用户已确认的理解。 8. **不顺手改业务代码**：学习过程默认只读代码和写 lesson；除非用户明确要求，不修改项目实现。 ## 文档位置 默认 lesson 目录按以下顺序选择： 1. 用户显式指定的 `$lesson_dir`。 2. 如果存在 `docs/usebook/lessons/`，使用它。 3. 如果存在 `docs/lessons/`，使用它。 4. 否则创建 `docs/lessons/`。 lesson 文件命名： ```text lesson-1.md lesson-2.md lesson-3.md ... ``` 如果已有 lesson，继续追加或创建下一节；不要覆盖用户已有笔记。 ## 执行流程 ### 第一步：建立学习路线 读取最小必要上下文： - `README*` - `AGENTS.md` / `CLAUDE.md` / 项目协作说明 - `pyproject.toml` / `package.json` / 主配置文件 - 顶层目录结构 - 主要入口文件 输出 5-10 节学习路线。每节应包含： - 主题 - 要读的文件 - 要理解的问题 - 预期产出的 lesson 内容 不要在第一步就深入解释所有代码。 ### 第二步：每节课的固定结构 每节课按这个顺序讲： 1. **学习目标**：本节要解决什么问题。 2. **一张图**：用 Mermaid 或 ASCII 画出调用链/数据流/模块关系。 3. **最小代码地图**：列出 3-8 个关键文件/函数及职责。 4. **关键路径讲解**：顺着真实调用链解释，不跳到无关模块。 5. **重要代码点**：解释关键函数、参数、返回值、错误处理和副作用。 6. **理解检查**：问用户 1-3 个问题。 7. **课堂笔记沉淀**：用户确认后，把