first commit

Author: easterCat

AGENTS_cn.md

@@ -0,0 +1,218 @@
+# AGENTS.md
+
+贡献者和 AI 代理参与本仓库的操作手册。在提交 PR 前请先阅读。
+
+本仓库是一个课程体系，而非 SaaS 应用。课程内容才是核心产品。以下每一条规则都是为了确保 485 门课程长期保持一致性。
+
+---
+
+## 理念
+
+485 门课程，20 个阶段。在引入任何框架之前，每个算法都从原始数学开始构建。你需要用 Python、TypeScript、Rust 或 Julia 手写反向传播、分词器、注意力机制和代理循环。然后用生产库运行同样的操作，让框架不再是黑盒。"从零构建 / 使用框架"是整个课程的脊梁。每门课程都产出一个可复用的制品，你可以直接集成到日常工作中。
+
+---
+
+## 仓库结构
+
+```
+phases/
+  NN-phase-slug/
+    NN-lesson-slug/
+      docs/en.md              # 课程讲解文档
+      code/                   # 实现代码 + 测试
+      quiz.json               # 6 道测验题
+      outputs/                # 可复用制品（技能 / 提示词 / 代理 / MCP 服务器）
+README.md                     # 门面文件；课程数量自动同步
+ROADMAP.md                    # 阶段/课程状态
+glossary/terms.md             # 规范术语定义
+site/
+  build.js                    # 解析 README + ROADMAP + 术语表 -> data.js
+  data.js                     # 自动生成；CI 在 main 分支推送时重建
+scripts/                      # 自动化脚本
+.github/workflows/
+  curriculum.yml              # 不变量检查 + 自动同步工作流
+```
+
+---
+
+## 硬性规则
+
+1. **每个课程目录一个提交。** 绝不将多个课程打包进一个提交。10 个课程的 PR 应有 10 个提交。
+2. **约定式提交信息** 不超过 72 字符：`feat(phase-NN/MM): <slug>`。正文解释原因，而非描述内容。
+3. **图表仅使用 Mermaid 或 SVG。** 禁止 ASCII / Unicode 方框图。
+4. **每个围栏代码块必须标注语言。** 适当使用 `text`、`json`、`python`、`typescript`、`rust`、`julia`、`bash`、`console`、`mermaid`、`yaml`。
+5. **仅限原创实现。** 不要在文档、代码注释或提交信息中引用外部课程仓库。引用 RFC、官方规范和学术论文作为规范来源。
+6. **依赖白名单**（见下文`依赖`）。优先使用标准库。
+7. **绝不提交生成文件**：`catalog.json` 被 gitignore，`site/data.js` 由 CI 重建，`package-lock.json` 永不跟踪。
+
+---
+
+## 依赖
+
+| 语言       | 允许使用的依赖                                                             |
+|------------|---------------------------------------------------------------------------|
+| Python     | `numpy`、`torch`、`h5py`、`zstandard`、`safetensors`、标准库                |
+| TypeScript | `hono`、`zod`、`ws`（仅在需要 WebSockets 时）、`@hono/node-server`、Node 20+ 标准库 |
+| Rust       | 仅标准库（单文件 `rustc --edition 2021`）                                    |
+| Julia      | `Random`、`Statistics`、`LinearAlgebra`、`Printf`（Julia 标准库）             |
+
+如果发现引用了被禁止的依赖，跳过并注明"保持标准库优先以确保教学清晰性"。
+
+---
+
+## 课程规范
+
+### docs/en.md 前置元数据
+
+```markdown
+# <标题>
+
+> <一句话核心观点>
+
+**类型：** <学习 | 构建 | 参考>
+**编程语言：** <与 code/ 中 main.* 文件匹配的逗号分隔列表>
+**前置条件：** <上游课程的逗号分隔列表，或"无">
+**时间：** ~<预计分钟数>
+
+## 学习目标
+- <4-6 个以动词开头的要点>
+```
+
+`**编程语言：**` 字段必须与 `code/` 中拥有 `main.*` 文件的语言匹配。
+
+### quiz.json 结构
+
+```json
+{
+  "lesson": "<目录slug>",
+  "title": "<课程标题>",
+  "questions": [
+    {"stage": "pre",   "question": "...", "options": ["a","b","c","d"], "correct": 0, "explanation": ""},
+    {"stage": "check", "question": "...", "options": ["a","b","c","d"], "correct": 1, "explanation": ""},
+    {"stage": "check", "question": "...", "options": ["a","b","c","d"], "correct": 2, "explanation": ""},
+    {"stage": "check", "question": "...", "options": ["a","b","c","d"], "correct": 1, "explanation": ""},
+    {"stage": "post",  "question": "...", "options": ["a","b","c","d"], "correct": 3, "explanation": ""},
+    {"stage": "post",  "question": "...", "options": ["a","b","c","d"], "correct": 0, "explanation": ""}
+  ]
+}
+```
+
+恰好 6 道题：1 道预测试 + 3 道检查题 + 2 道后测试。`correct` 索引从 0 开始。网站渲染器只识别这种结构——旧版 `q/choices/answer` 结构会静默失败。
+
+### code/
+
+- 使用该语言的规范命令运行后能完整执行并退出码为 0。
+- 自终止演示。无无限 stdin 循环，不会因缺少 API 密钥而挂起。
+- 4-6 行头部注释，引用课程的 `docs/en.md` 路径和任何规范或 RFC 来源。
+
+### code/tests/
+
+- 至少 5 个单元测试。
+- 使用该语言的标准库运行器运行（`python3 -m unittest discover`、`npx tsx --test`、Rust/Julia 内联）。
+
+---
+
+## PR 验证
+
+推送前在本地运行：
+
+```bash
+python3 scripts/audit_lessons.py
+python3 scripts/check_readme_counts.py        # 建议性检查——CI 在合并时修复
+
+# 对每个涉及的课程：
+cd phases/NN-phase/MM-lesson/code
+python3 main.py && python3 -m unittest discover tests -v   # 或对应语言的等效命令
+```
+
+CI 门禁（`.github/workflows/curriculum.yml`）：
+
+| 任务                                | 触发条件     | 行为                                                   |
+|-------------------------------------|-------------|-------------------------------------------------------|
+| `audit`                             | push + PR   | 运行 `audit_lessons.py`。阻塞性检查。                  |
+| `readme-counts-sync`（仅 main）     | 推送到 main  | 重建 catalog + 自动修复 README 计数。                  |
+| `site-rebuild`（仅 main）           | 推送到 main  | 重新运行 `node site/build.js`，提交 `site/data.js`。   |
+| `readme-counts-drift`               | PR          | 仅建议性检查——main 在合并时自动修复。                    |
+
+---
+
+## 自动化契约
+
+**CI 自动处理——请勿在你的 PR 中修改：**
+
+| 表面                 | 机器人                        | 时机                 |
+|----------------------|------------------------------|---------------------|
+| `catalog.json`       | 按需重建（被 gitignore）       | 每次 CI 任务        |
+| `README.md` 计数     | `readme-counts-sync`         | 推送到 main 时       |
+| `site/data.js`       | `site-rebuild`               | 推送到 main 时       |
+
+**你需要处理：**
+
+| 表面                              | 时机                                                              |
+|-----------------------------------|------------------------------------------------------------------|
+| `README.md` 课程链接行             | 添加新课程时——链接 `[标题](phases/NN-phase/MM-lesson/)`           |
+| `ROADMAP.md` 状态                  | 标记课程完成或进行中时                                              |
+| `glossary/terms.md`               | 引入被多门课程使用的术语时                                          |
+
+**常见 bug**：如果合并后 `grep -c 'tree/main/phases/NN-' site/data.js` 为 0，则 Phase NN 的 README 行是纯文本，缺少 `[标题](phases/NN-...)` markdown 链接。`site/build.js` 从该链接派生 URL。
+
+---
+
+## 冲突解决
+
+```bash
+git fetch origin main
+git merge --no-edit origin/main
+
+# Catalog 冲突（仅旧分支——catalog.json 现已被 gitignore）：
+git rm catalog.json
+git commit --no-edit
+
+# README 计数冲突：
+git checkout --theirs README.md
+python3 scripts/build_catalog.py
+python3 scripts/check_readme_counts.py --fix
+git add README.md && git commit --no-edit
+
+# site/data.js 冲突：
+git checkout --theirs site/data.js
+node site/build.js
+git add site/data.js && git commit --no-edit
+
+git push origin <你的分支>
+```
+
+避免对有未解决评审评论的分支执行 `git push --force`。强制推送会使评论与提交脱离关联。
+
+---
+
+## 新课程入门指南
+
+```bash
+mkdir -p phases/NN-phase-slug/MM-new-lesson/{docs,code/tests,outputs}
+
+# 1. 编写 docs/en.md，使用上述前置元数据。
+# 2. 编写 code/main.<lang>，包含 4-6 行头部注释。
+# 3. 编写 code/tests/test_main.*，包含 5+ 个测试。
+# 4. 编写 quiz.json，使用上述结构。
+# 5. （可选）如果课程产出技能文件，添加 outputs/skill-<slug>.md。
+
+# 6. 添加到 README.md：
+#    | MM | [课程标题](phases/NN-phase-slug/MM-new-lesson/) | 类型 | 语言 |
+
+# 7. 更新 ROADMAP.md 状态行。
+
+# 8. 本地验证。
+
+# 9. 原子提交：
+git add phases/NN-phase-slug/MM-new-lesson README.md ROADMAP.md
+git commit -m "feat(phase-NN/MM): add <slug>"
+git push -u origin <你的分支>
+gh pr create --title "feat(phase-NN/MM): add <slug>" --body "<5行摘要>"
+```
+
+`site/data.js` 在合并时重新生成——交给 CI 处理。
+
+---
+
+最后审阅：2026-05-27。

CHANGELOG_cn.md

@@ -0,0 +1,46 @@
+# 更新日志
+
+本课程的最新更新内容，按时间倒序排列。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/)。每条记录注明阶段、课程和变更内容，方便学习者直接查看差异。
+
+## [未发布]
+
+### 新增
+- `scripts/scaffold-lesson.sh` — 课程脚手架脚本，可创建 `phases/NN-phase/NN-lesson/` 完整目录结构，并从 `LESSON_TEMPLATE.md` 预填充 `docs/en.md` 骨架。
+- `.github/PULL_REQUEST_TEMPLATE.md` — 贡献者检查清单（代码可运行、无代码注释、从零构建优先、每课程原子提交、markdown 链接 ROADMAP 行）。
+- `.github/ISSUE_TEMPLATE/bug_report.md` 和 `new_lesson_proposal.md` — 用于 bug 报告和课程提案的结构化模板。
+- 本 `CHANGELOG.md` 文件。
+
+## 2026-04 — 阶段 4：计算机视觉 完成
+
+### 新增
+- 阶段 4 全部 28 门课程，涵盖图像基础到多模态视觉（VLM、3D、视频、自监督学习）。
+- `ROADMAP.md` 中的阶段 4 行已链接为 markdown 链接指向课程目录，使网站能够正确展示。
+
+### 修复
+- 阶段 4 跨 15+ 门课程的精度修正：
+  - `phase-4/02`：形状计算器指定自适应池化、展平和线性层的 RF/步幅处理。
+  - `phase-4/03`：骨干网络选择器描述列出所有覆盖的系列；为 OCR、医疗、工业场景添加了头部指导。
+  - `phase-4/04`：分类诊断使用量化阈值针对每种失败模式；`n/a` 用于未定义指标；对少于 3 个类别的情况增加防护。
+  - `phase-4/06`：检测指标读取器使用 `AP@0.5`（而非 `mAP@0.5`）；逐类召回率声明为可选；锚点设计器澄清步幅截断和每层单锚点路径。
+  - `phase-4/10`：采样器选择器声明 `unet_forward_ms` 作为输入；ControlNet 防护提升为规则 0。
+  - `phase-4/14`：ViT 检查器与拒绝规则对齐——端口尝试被审计而非背书。
+  - `phase-4/24`：开放词汇堆栈选择器具有显式规则优先级和许可证过滤语义；概念设计器解决步骤-5/规则-80 冲突。
+  - `phase-4/25`：VLM 文档中 `_merge` 在占位符不匹配时抛出描述性 `ValueError`；CMER 内部进行归一化。
+  - `phase-4/27`：`synthetic_frames` 将 GT 边界框裁剪到帧的高/宽。
+  - `phase-4/28`：`rope_3d` 验证维度拆分；从 DiT 块示例中移除了未使用的 `F` 导入。
+
+## 2026-Q1 及更早
+
+### 新增
+- 阶段 0（环境搭建与工具）：全部 12 门课程。
+- 阶段 1（数学基础）：全部 22 门课程。
+- 阶段 2（机器学习基础）：全部 18 门课程。
+- 阶段 3（深度学习核心）：涵盖感知机、反向传播、优化器的核心课程。
+- 内置 Claude Code 技能：`find-your-level`（分班测试）和 `check-understanding`（逐阶段测验）。
+- 网站 aiengineeringfromscratch.com：课程目录、逐课程页面、路线图、277 条术语表。
+- 所有 20 个阶段的初始脚手架（`phases/00-*` 到 `phases/19-*`）。
+- `LESSON_TEMPLATE.md`、`CONTRIBUTING.md`、`ROADMAP.md`、`README.md`。
+
+[未发布]: https://github.com/rohitg00/ai-engineering-from-scratch/compare/HEAD...HEAD

CODE_OF_CONDUCT_cn.md

@@ -0,0 +1,30 @@
+# 行为准则
+
+## 我们的承诺
+
+我们致力于让每个人都能参与本项目，不受年龄、体型、残疾、种族、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、外貌、肤色、宗教、性取向的骚扰影响。
+
+## 我们的标准
+
+**积极行为：**
+
+- 使用友好和包容的语言
+- 尊重不同的观点和经验
+- 虚心接受建设性批评
+- 以社区的最佳利益为重
+- 对其他社区成员表现出同理心
+
+**不可接受的行为：**
+
+- 挑衅、侮辱/贬损性评论以及人身或政治攻击
+- 公开或私下的骚扰
+- 未经明确许可发布他人的私人信息
+- 其他可能被合理认为不当的行为
+
+## 执行
+
+如遇虐待、骚扰或其他不可接受的行为，请联系项目维护者 ghumare64@gmail.com 进行举报。所有投诉都将被审查和调查。
+
+## 来源
+
+本行为准则改编自 [Contributor Covenant](https://www.contributor-covenant.org) 2.1 版。