ML-For-Beginners 工程协作手册：基于 AGENTS.md 的机器学习课程仓库结构与实战指南-二趣网

ML-For-Beginners 工程协作手册：基于 AGENTS.md 的机器学习课程仓库结构与实战指南

【免费下载链接】ML-For-Beginners12 weeks, 26 lessons, 52 quizzes, classic Machine Learning for all项目地址: https://gitcode.com/GitHub_Trending/ml/ML-For-Beginners

ML-For-Beginners仓库的 AGENTS.md（及其孟加拉语等 50 多种语言自动翻译版本，如 translations/bn/AGENTS.md）是面向 AI 编程助手与贡献者的“工程协作说明书”：它定义了 12 周、26 节课双语言课程（Python + R）的仓库结构、环境搭建命令、quiz-app 前端工作流、Docsify 文档站点与 PDF 生成、自动翻译机制以及故障排查方案。读完本文，你可以独立完成该课程仓库的本地环境搭建、运行全部教学 Notebook 与测验应用，并理解其多语言流水线的设计。

项目概览：12 周 26 课的经典机器学习课程

根据 AGENTS.md 的项目概览章节，本仓库是一个自定进度的学习资源，以 Python（主要基于 Scikit-learn）和 R 实现经典机器学习概念的教学，每节课通过来自世界各地不同文化背景的真实数据集展开。核心组成包括：

教学内容：26 节课，覆盖机器学习入门、回归、分类、聚类、NLP、时间序列与强化学习；
测验应用：基于 Vue.js 的 quiz-app，提供课前（pre-）与课后（post-）测验评估；
多语言支持：通过 GitHub Actions 自动翻译到 40+ 种语言；
双语言支持：每节课同时提供 Python（Jupyter Notebook）与 R（R Markdown）版本；
项目式学习：每个主题附带实战项目与作业（assignment）。

从仓库目录结构可以印证这些描述：1-Introduction/至9-Real-World/九大主题目录对应课程主线，quiz-app/为前端测验应用，translations/存放自动生成的翻译内容，sketchnotes/提供概念手绘图（sketchnote）视觉总结。

仓库结构：目录布局与每节课的标准组织

AGENTS.md 给出的仓库结构如下：

ML-For-Beginners/ ├── 1-Introduction/ # ML basics, history, fairness, techniques ├── 2-Regression/ # Regression models with Python/R ├── 3-Web-App/ # Flask web app for ML model deployment ├── 4-Classification/ # Classification algorithms ├── 5-Clustering/ # Clustering techniques ├── 6-NLP/ # Natural Language Processing ├── 7-TimeSeries/ # Time series forecasting ├── 8-Reinforcement/ # Reinforcement learning ├── 9-Real-World/ # Real-world ML applications ├── quiz-app/ # Vue.js quiz application ├── translations/ # Auto-generated translations └── sketchnotes/ # Visual learning aids

每个课程（lesson）文件夹通常包含以下文件：

README.md—— 课程主内容；
notebook.ipynb—— Python Jupyter Notebook；
solution/—— 参考答案代码（Python 与 R 版本）；
assignment.md—— 练习作业；
images/—— 视觉资源。

以 2-Regression/1-Tools/ 为例，其solution/目录下实际包含notebook.ipynb、R/与Julia/子目录——从目录结构看，部分课程的解答版本除 Python、R 之外还提供了 Julia 实现，与文档所述“Python 与 R 双版本”一致且略有超出。

多语言支持的实际规模可以从translations/目录验证：该目录下存在55 个语言子目录（如ar/、bn/、zh-CN/、pt-BR/等），每个子目录镜像了与英文课程相同的 Markdown 与 Notebook 文件树，印证了文档中“40+ 语言自动翻译”的说法。

环境搭建：四类组件的安装命令

Python 课程环境

多数课程使用 Jupyter Notebook，AGENTS.md 给出的安装命令为：

# Install Python 3.8+ if not already installed python --version # Install Jupyter pip install jupyter # Install common ML libraries pip install scikit-learn pandas numpy matplotlib seaborn # For specific lessons, check lesson-specific requirements # Example: Web App lesson pip install flask

其中 Flask 是 3-Web-App/ 课程的专属依赖，用于将训练好的 ML 模型部署为 Web 应用；其余课程按需补充各自依赖。

R 课程环境

R 课程以.rmd（R Markdown）或.ipynb形式存放在各节课的solution/R/子目录中，所需 R 包为：

# 在 R 控制台中执行 install.packages(c("tidyverse", "tidymodels", "caret"))

运行环境可以是 RStudio，或安装了 R kernel（IRkernel）的 Jupyter。

测验应用（quiz-app）

测验应用是一个 Vue.js 项目，位于quiz-app/目录：

cd quiz-app npm install

从 quiz-app/package.json 可以确认其技术栈：依赖vue@^3.5.12、vue-i18n、vue-router，开发工具链为 Vue CLI 5（@vue/cli-service），并在文件内嵌了 ESLint 配置（plugin:vue/essential+eslint:recommended，见 quiz-app/package.json）。src/assets/translations/下还带有 en、es、fr、it、ja、ptbr、tr 七种语言的前端文案资源，说明应用本身也支持多语言界面。

文档站点（Docsify）

文档站点基于 Docsify，无需构建步骤。本地启动方式：

# Install Docsify npm install -g docsify-cli # Serve from repository root docsify serve # Access at http://localhost:3000

仓库根目录的 index.html 即为 Docsify 入口：它通过 CDN 引入 docsify 4 并配置window.$docsify（name: 'Machine Learning for Beginners'、relativePath: true、auto2top: true），侧边栏目录由 docs/_sidebar.md 提供。

开发工作流：从 Notebook 到前端

课程 Notebook 的标准操作

进入课程目录（例如2-Regression/1-Tools/）；
打开 Notebook：jupyter notebook notebook.ipynb；
完成课程内容与练习；
需要时对照solution/目录中的答案核对。

Python 开发约定

课程使用标准 Python 数据科学库（Scikit-learn、Pandas、NumPy、Matplotlib、Seaborn）；
以 Jupyter Notebook 作为交互式教学载体；
每节课的solution/文件夹提供可运行的解答代码。

R 开发约定

R 课程为.rmd（R Markdown）格式，答案位于solution/R/子目录；
使用 RStudio 或带 R kernel 的 Jupyter 运行。

测验应用开发命令

quiz-app/package.json 中定义了三个 npm 脚本，与文档完全对应：

cd quiz-app # Start development server npm run serve # vue-cli-service serve，访问 http://localhost:8080 # Build for production npm run build # vue-cli-service build，产物输出到 dist/ # Lint and fix files npm run lint # vue-cli-service lint，自动检查并修复

测试与验证策略

AGENTS.md 明确说明：这是一个以教学课程为主的仓库，课程内容没有自动化测试。验证方式为：

完成课程练习；
成功运行 Notebook 中的每个代码单元格；
将运行输出与solution/中的期望结果比对。

对于 quiz-app 前端部分，验证手段是 Lint 与构建：

cd quiz-app # Lint code npm run lint # Build to verify no errors npm run build

由于 ESLint 配置直接写在 quiz-app/package.json 的eslintConfig字段中，npm run lint无需额外配置文件即可执行。

代码风格指南

Python 代码

遵循 PEP 8 风格规范；
使用清晰、具描述性的变量命名；
复杂操作须附注释；
Jupyter Notebook 中应使用 Markdown 单元格解释概念。

JavaScript / Vue.js（quiz-app）

遵循 Vue.js 风格指南；
ESLint 配置位于 quiz-app/package.json，npm run lint会自动检查并修复问题。

文档

Markdown 文件应保持清晰、结构良好；
代码示例使用围栏代码块（fenced code block）；
内部引用使用相对链接；
遵循既有的排版约定。

构建与部署

quiz-app 部署到 Azure Static Web Apps

AGENTS.md 给出部署步骤：

前提：Azure 账号；已 fork 的 GitHub 仓库；
部署配置：创建 Azure Static Web App 资源并关联 GitHub 仓库，App location 设为/quiz-app，Output location 设为dist；Azure 会自动生成 GitHub Actions workflow；
Workflow 行为：workflow 文件位于.github/workflows/azure-static-web-apps-*.yml，向 main 分支推送后自动构建并部署。

仓库内的静态部署配置也与此呼应：quiz-app/public/routes.json 将/*全部路由回退到/index.html，这是典型的前端单页应用（SPA）路由配置，配合vue-router保证客户端路由刷新时不 404。

文档 PDF 生成

根目录的 package.json 定义了convert脚本：

npm install npm run convert

该脚本实际执行node_modules/.bin/docsify-to-pdf，其配置在 docsifytopdf.js 中：

contents: ['docs/_sidebar.md']—— 以侧边栏目录作为 PDF 内容大纲；
pathToPublic: 'pdf/readme.pdf'—— 输出路径（仓库中已存在生成产物 pdf/readme.pdf）；
pdfOptions.margin设置上下 100px 页边距；
emulateMedia: 'print'—— 以打印媒体类型渲染。

翻译工作流：GitHub Actions + Co-op Translator

AGENTS.md 对翻译机制给出了几条硬性约定：

翻译由 GitHub Actions 中的Co-op Translator自动完成，调用 Azure AI / OpenAI 服务；
向main分支推送变更后自动触发翻译，支持 40+ 种语言；
严禁手动编辑翻译文件——translations/下的内容全部由系统生成；
workflow 定义于.github/workflows/co-op-translator.yml。

一个可以直接观察到的证据链：本文所依据的 translations/bn/AGENTS.md 本身就是这条流水线的产物——它与英文原版 AGENTS.md 章节一一对应，且文末保留了机器翻译免责声明（自动翻译可能存在错误或不一致，英文原文为权威版本，重要场景建议人工翻译）。translations/下 55 个语言目录、每个目录约 150 个文件（99 个.md+ 51 个.ipynb）的镜像结构，也说明该机制覆盖了课程正文与 Notebook 双内容类型。

课程结构：每节课的七个环节

AGENTS.md 指出每节课遵循统一的七段式模式：

课前测验（Pre-lecture quiz）——测试基础认知；
课程内容（Lesson content）——文字讲解与说明；
代码演示（Code demonstrations）——Notebook 中的实操示例；
知识检查（Knowledge checks）——过程中的理解验证；
挑战（Challenge）——独立应用所学概念；
作业（Assignment）——延伸练习；
课后测验（Post-lecture quiz）——评估学习成果。

课前/课后双测验正是 quiz-app 中 pre/post-lesson 评估功能在教学法层面的落点。

常用命令速查

以下为 AGENTS.md 提供的完整命令参考：

# Python/Jupyter jupyter notebook # Start Jupyter server jupyter notebook notebook.ipynb # Open specific notebook pip install -r requirements.txt # Install dependencies (where available) # Quiz App cd quiz-app npm install # Install dependencies npm run serve # Development server npm run build # Production build npm run lint # Lint and fix # Documentation docsify serve # Serve documentation locally npm run convert # Generate PDF # Git workflow git checkout -b feature/my-change # Create feature branch git add . # Stage changes git commit -m "Description" # Commit changes git push origin feature/my-change # Push to remote

核心技术栈

技术	用途
Python（Scikit-learn、Pandas、NumPy、Matplotlib）	ML 课程的主语言
R（tidyverse、tidymodels、caret）	替代实现
Jupyter	Python 课程的交互式 Notebook
R Markdown	R 课程的文档载体
Vue.js 3	quiz-app 测验应用框架
Flask	ML 模型部署的 Web 应用框架
Docsify	无构建步骤的文档站点
GitHub Actions	CI/CD 与自动翻译

贡献流程要点

AGENTS.md 对内容贡献者给出六步流程：fork 仓库并创建 feature 分支 → 修改课程正文 →不修改自动生成的翻译文件→ 验证所有 Notebook 单元格可成功运行 → 检查链接与图片有效 → 提交附清晰说明的 PR。

PR 规范：

标题格式[Section] 变更简述，例如[Regression] Fix typo in lesson 5、[Quiz-App] Update dependencies；
提交前须确认：Notebook 单元格全部无错运行；修改 quiz-app 时执行npm run lint；Markdown 格式正确；新增代码示例已实测；
PR 须包含变更说明、变更原因，涉及 UI 变更时附截图；
行为准则遵循 CODE_OF_CONDUCT.md（Microsoft Open Source Code of Conduct），并需签署 CLA。

文档另列出了配套学习资源（仅列名称，不含外部链接）：Microsoft Learn 课程模块合集、在线测验应用（quiz-app 的部署版）、GitHub Discussions 讨论区、YouTube 视频讲解系列。

安全注意事项

AGENTS.md 的安全章节包含四条约定：

代码中不存放机密：永不提交 API key 或凭据；
依赖维护：保持 npm 与 pip 包更新；
用户输入：Flask Web 应用示例包含基础输入校验；
敏感数据：示例数据集均为公开、非敏感数据（如data/下的南瓜价格、菜系、能源消费等 CSV）。

故障排查手册

Jupyter Notebook 问题

症状	处理方式
单元格卡死（Kernel 问题）	Kernel → Restart 重启内核
导入错误（Import errors）	用 pip 安装缺失包
路径问题	从 Notebook 所在目录运行

测验应用问题

症状	处理方式
`npm install`失败	`npm cache clean --force`清理缓存
端口冲突	`npm run serve -- --port 8081`换端口
构建错误	删除`node_modules`后重新安装

R 课程问题

症状	处理方式
找不到包	`install.packages("package-name")`
RMarkdown 渲染失败	确认已安装 rmarkdown 包
内核问题	为 Jupyter 安装 IRkernel

项目定位：它是课程，不是生产代码

AGENTS.md 末尾的项目专用备注明确了本仓库的边界与定位：

这是一个学习课程而非生产代码，重心是通过动手练习理解 ML 概念；
代码示例优先清晰度而非性能优化；
多数课程相互独立，可单独完成；
虽提供参考答案，但学习者应先自行练习；
文档通过 Docsify 直接生成 Web 文档，无构建步骤；
sketchnotes/目录提供概念的手绘视觉总结（如 sketchnotes/README.md 所示的公平性、回归、强化学习等主题速写）；
多语言支持（55 个translations/语言子目录）让内容面向全球学习者可访问。

对 AI 编程 Agent 而言，这份文档的价值在于：它以机器可读的结构声明了“哪些目录自动生成不可手改（translations/）”“哪些命令是验证手段（lint / build / notebook 运行）”“哪些产物是流水线输出（pdf/readme.pdf、Azure workflow）”，使 Agent 在协作维护该仓库时不会误改翻译文件或遗漏课程七段式结构。

【免费下载链接】ML-For-Beginners12 weeks, 26 lessons, 52 quizzes, classic Machine Learning for all项目地址: https://gitcode.com/GitHub_Trending/ml/ML-For-Beginners

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析