企业官网建设流程全解析

catalog.json 目录系统：ai-engineering-from-scratch 课程元数据架构完整解析（16大阶段、400+课程）

【免费下载链接】ai-engineering-from-scratchLearn it. Build it. Ship it for others.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-from-scratch

catalog.json 目录系统是 ai-engineering-from-scratch 这套开源 AI 工程课程的中枢神经：一份 JSON 文件，装下 20 个阶段、400 余门课程的课程元数据——哪些课有文档、哪些有代码、产出过哪些 Prompt 与 Skill，全部由脚本从磁盘目录结构自动扫描生成，而非人工维护。对新手来说，看懂这套元数据架构，就等于拿到了整个课程体系的"地图"。

为什么课程需要一套"目录系统"？

想象一下：416 门课散落在 20 个阶段目录里，每门课还带有文档、代码、测验、产出物……网站页面、搜索索引、API 接口、AI Agent 课程索引（llms.txt）都需要同步这些数据。如果靠人工维护一份清单，早晚会和实际内容"脱节"。

这个项目的解法很干脆：文件系统就是唯一的真相源（single source of truth）。

目录里有什么，catalog.json 里就有什么。加一课、删一文件，重跑一次脚本即可，数字永远对得上。

目录命名规范：两级数字编号 + slug

整个课程体系遵循一套严格的目录命名约定，由两个正则表达式守护（数字必须两位、slug 只能用小写字母数字和连字符）：

phases/ └── 00-setup-and-tooling/ # 阶段：NN-主题-slug └── 01-dev-environment/ # 课程：NN-课程-slug

以开发环境第一课为例，打开 phases/00-setup-and-tooling/01-dev-environment/ 就能看到标准的"四件套"结构，完整模板定义在 LESSON_TEMPLATE.md：

其中outputs/里的文件还带 YAML frontmatter（name、description、version、tags），会被完整解析进 catalog——这也是 outputs/index.json 这类索引的数据基础。

catalog.json 元数据是如何生成的

一切由 scripts/build_catalog.py 完成。它不读任何 README，而是直接遍历磁盘：

1. 扫描phases/下所有符合NN-slug规范的两级目录；
2. 读取每门课的docs/en.md的 H1 作为标题（读不到就用 slug 智能转标题，比如lora→LoRA、tfidf→TF-IDF）；
3. 清点代码文件、测验、notebook 与 outputs 产出物；
4. 汇总成一份 schema_version 1 的 JSON 写入仓库根目录。

{ "schema_version": 1, "totals": { "phases": 20, "lessons": 416, "skills": ..., "code_files": ... }, "phases": [ { "num": 0, "slug": "00-setup-and-tooling", "title": "Setup and Tooling", "lessons": [ { "num": 1, "title": "...", "has_docs": true, "has_code": true, "code_files": ["main.py"], "outputs": [ { "type": "skill", ... } ] } ] } ] }

运行方式极简（纯标准库、零依赖）：

python3 scripts/build_catalog.py # 在仓库根目录生成 catalog.json python3 scripts/build_catalog.py --stdout # 只打印，不写文件

谁在消费这份课程元数据？

catalog.json 不是终点，而是整个站点的"数据上游"：

• 📖 课程目录页：site/build.js 每次部署时读取课程数据，生成 site/catalog.html 的可搜索课程索引、站点地图（sitemap）和llms.txt；
• 🔌 课程 API：api/lesson.js 依据元数据动态拼装课程页，课程不存在时会提示"回到课程目录"；
• 🤖 AI Agent：llms.txt让 LLM Agent 也能按元数据检索整套课程；
• ✅ 持续校验：仓库的 GitHub Actions（curriculum 工作流）会自动重建 catalog，防止人工修改造成的计数漂移。

这种"构建时生成、部署时消费"的架构，是大型开源课程保持"数字永远真实"的关键设计。

新手如何使用这套目录系统找课？

三步走：

1. 看阶段：从 phases/ 目录浏览 20 个阶段的 slug，如11-llm-engineering、14-agent-engineering；
2. 看课程元数据：翻到 catalog.json 对应 phase，用has_code/has_quiz/outputs判断这门课的"料"够不够；
3. 按模板自检：动手加课程时，照 LESSON_TEMPLATE.md 的目录结构填空即可被自动收录。

💡 一句话总结：catalog.json 目录系统把"课程内容"变成了"可编程的元数据"——目录结构即文档、脚本即真相、数字即承诺。这正是它能以纯静态站点跑起 400+ 门课而不失控的原因。

【免费下载链接】ai-engineering-from-scratchLearn it. Build it. Ship it for others.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-from-scratch