Repo Mini Practice

目的

将一个真实仓库转化为一个小型、可运行的学习项目。目标并非概括每个文件，而是提取其中一项核心机制，并在目标仓库内重建为一个清晰的 mini-practice/ 目录。

适用场景

• 用户希望超越 README 的使用说明，深入理解某个 GitHub 仓库或本地代码库。
• 用户请求构建一个迷你版、MVP 版、VIP 版、极简克隆版、源码学习版，或可运行的实践实现。
• 用户希望掌握某个库、框架、CLI、SDK、agent、编译器工具、服务或应用背后的核心原理。

除非用户明确以最小化复现作为学习手段，否则请勿将本流程用于普通代码审查、缺陷修复或功能开发。

核心原则

产出一个可运行的教学制品（teaching artifact），而不仅是一段解释性文字。若真实项目依赖外部服务、数据库、模型 API、消息队列、浏览器或基础设施，请对这些依赖进行模拟（mock），同时保留核心逻辑流程。

默认文档为中英双语：学习指南需同时提供中文与英文版本，除非用户明确要求仅使用单一语言。

代码注释语言需与用户的提问语言一致。若用户用中文提问，则函数注释使用中文；若用户用英文提问，则注释使用英文；若提问混合多种语言，则以主要语言或用户明确指定的语言为准。

工作流程

1. 确认目标仓库

   • 若提供了本地路径，则检查该仓库。
   • 若提供了 GitHub URL，则使用可用的 git 或 GitHub 工具获取或检查该仓库。若当前环境需要网络权限，请先征得用户同意。
   • 若目标不明确，请向用户询问仓库路径或 URL。

2. 阅读公开契约（public contract）

   • 阅读 README、示例（examples）、文档（docs）、包清单（package manifests）、CLI 帮助信息（CLI help）、演示入口（demo entry points）等。
   • 用一至两句话概括该项目的功能定位。

3. 梳理源码结构

   • 识别入口点（entry points）、核心模块（core modules）、关键数据结构（important data structures）以及主调用链（main call chain）。
   • 优先使用快速搜索工具（如 rg）或语言原生符号查找工具（language-native symbol tools）。
   • 忽略生成文件（generated files）、锁文件（lockfiles）、构建产物（build output）、第三方依赖（vendored dependencies）及无关示例（unrelated examples），除非它们是唯一可用的使用线索（usage signal）。

4. 选择一项机制

   • 选取一项高价值、可在小型可运行形式中重建的机制。
   • 示例包括：中间件管道（middleware pipeline）、状态更新循环（state update loop）、路由匹配（router matching）、SQL 生成（SQL generation）、重试调度器（retry scheduler）、解析-转换-生成链（parser-transformer-generator chain）、工具调用循环（tool-calling loop）、缓存失效（cache invalidation）、插件加载（plugin loading）等。
   • 若存在多个合理选项，可简要列出两到三个并选择最适合作为默认项的一个。

5. 设计 mini-practice

   • 说明将复现哪些内容。
   • 说明将模拟（mock）或省略哪些部分。
   • 在可行前提下，使用该仓库所采用的主要编程语言及其生态体系。
   • 确保实现足够精简，可单次通读完成理解。

6. 创建 mini-practice/ 目录

   • 若已存在 mini-practice/ 目录，在覆盖前须先检查其内容，并保留用户已有工作成果。
   • 包含一个最小化的可运行演示（demo）、测试（test）或命令行示例。
   • 为关键学习函数添加函数级注释：说明该函数在机制中的作用、期望的输入结构、返回值或副作用（mutation），以及它对应原始源码中的哪个概念。
   • 代码注释语言应与用户请求 mini-practice 时使用的语言一致，除非用户明确指定其他语言。
   • 注释应聚焦于底层原理及其与原始源码概念的映射关系，避免冗余语法说明（如“将 i 加 1”之类）。

7. 验证可运行性

   • 运行 demo 或测试用例。
   • 若因依赖缺失或网络不可达导致无法验证，请准确说明已尝试的操作，并提供最接近的本地校验方式。

8. 编写学习指南

   • 在 mini-practice/README.md 中包含以下内容：
     • 所选核心机制
     • 运行命令
     • 按文件逐个阅读的顺序（file-by-file reading order）
     • mini 文件与原始源码文件或概念之间的对应关系
     • 被模拟或省略的部分
     • 两到三个面向学习者的练习题
   • 默认包含中英文两个版本。两版内容应等价且简洁。

输出结构

优先采用如下结构，名称可根据语言生态适当调整：

mini-practice/
├── README.md
├── src/
├── tests/ 或 demo/
├── mocks/ 或 fixtures/
└── minimal package/config 文件

注释与 README 要求

• 为公共函数、工厂函数、核心回调函数以及非显而易见的数据转换逻辑添加详细注释。
• 注释应体现架构思想：说明函数存在的原因、在整体流程中的位置，以及修改它将如何影响行为。
• 注释语言需与用户请求语言一致。默认不使用双语注释；双语注释会使 mini 实现变得嘈杂（noisy）。
• 避免逐行注释，优先在函数或重要代码块前添加一段有力的说明性注释。
• README.md 默认应包含以下结构：
  • 中文概述、运行命令、阅读路径、原始概念映射、练习题
  • 英文概述、运行命令、阅读路径、原始概念映射、练习题
  • 若用户指定仅需一种语言，请严格遵循其偏好。

质量标准

• 完整实现一个核心闭环，优于零散实现多个不完整功能。
• 代码必须实际可执行，禁止使用伪代码（pseudo-code）。
• mini 版本应在保留关键原理的前提下，比原始源码更易于理解。
• 使用直白的命名与注释，清晰表达原理、边界与数据流。
• README 默认为中英双语，且应能脱离本次对话上下文独立阅读。
• 除新增或更新 mini-practice/ 目录外，不得改动原始仓库其余部分。
• 如实报告所执行的具体命令及其结果。

常见错误

• 仅阅读 README 而未查阅实际实现即进行概括。
• 构建出一个已偏离原始源码核心原理的玩具项目（toy）。
• 直接复制过多原始代码，而非为学习目的重构机制本身。
• 试图覆盖整个仓库的所有功能。
• 因 mini 版本“看起来很简单”就跳过运行验证步骤。