学习路线元数据 v2 规范
目标
旧字段 ai_learning_stage 与 ai_learning_order 只能生成全局课程目录，不能表达稳定课程 ID、真正硬前置或不同角色的顺序。本规范把知识域、目录序、依赖图和角色路径拆成不同字段；57 门课程均须逐页审阅后再声明关系，不能从旧编号或标题批量猜测。
字段合同
# 兼容期保留旧 stage / order；v2 消费者不再用它们排序或分组
ai_learning_schema: 2
ai_learning_id: agent-core
ai_learning_domain: agent-runtime
ai_learning_catalog_order: 3200
ai_learning_hard_prerequisites:
- tool-calling
ai_learning_track_agent_app_order: 600
ai_learning_track_agent_app_kind: core| 字段 | 语义 |
|---|---|
ai_learning_schema | v2 页面固定为整数 2；声明后不允许回退到 legacy |
ai_learning_stage / ai_learning_order | 兼容历史查询暂时保留；构建仍校验合法性与全局唯一性，但 v2 消费者不再用它们排序或分组 |
ai_learning_id | 不随中文标题变化的唯一 kebab-case ID |
ai_learning_domain | 受控知识域，不兼任显示标题 |
ai_learning_catalog_order | 全局目录顺序，正的 JavaScript 安全整数并留插入间隔 |
ai_learning_hard_prerequisites | 角色无关的硬依赖；[] 表示已确认没有普遍硬前置 |
ai_learning_track_<role>_order | 课程在某角色路线中的正的 JavaScript 安全整数顺序 |
ai_learning_track_<role>_kind | core、recommended 或 optional |
首版 domain 固定为 foundations、model-and-context、retrieval-and-data、multimodal、agent-runtime、framework-practice、evaluation-reliability、safety-governance、production-ops、frontier-reference。
首版角色 ID 固定为 agent_app、rag、agent_platform、multimodal_realtime。角色集合由 track 字段推导，不另存一份容易漂移的 roles 列表。
验证规则
- 公开构建要求 57 门顶层课程全部声明
schema: 2；任何课程退回 legacy 都会失败关闭，缺失的 v2 字段也不能从旧字段静默补齐。 - 旧
stage/order仅作短期兼容。删除前还要单独核对外部 vault 查询和历史笔记，不在本阶段机械清理。 - 网站使用 YAML AST 读取元数据，校验受控字段名、ID/domain/order 类型、硬前置存在性、重复、自环、全图环，以及每个角色的 order/kind 配对与顺序唯一性；拼错字段或使用 tag/anchor 等非规范标量会失败关闭。
- 只要一门课程进入某条角色路线，它的每个硬前置也必须出现在同一路线且顺序更早；若该课程为
core，硬前置在该角色中也必须是core。这样不会出现“路线展示了课程，却隐藏其必修前置”的断裂路径。 - 全局 catalog order 与依赖 DAG 是两件事；验证器不以目录先后猜依赖。
- 个人完成状态字段继续只在本地使用，公开构建会剥离，也不作为课程内容质量证据。
- 顶层课程索引不能在公开构建中退化成丢失路线字段的 stub；遇到这种情况构建失败关闭。
全量审阅结果
57 门课程已经全部迁移。当前只有下列课程声明非空硬前置；其余 49 门均以 [] 明确表示“逐页审阅后未发现普遍的完整课程级硬前置”。
| 课程 ID | 硬前置 | 证据边界 |
|---|---|---|
context-engineering | prompt-engineering | 入口明确要求先完成提示词工程 |
document-parsing | data-cleaning、json | 入口明确要求先完成两门完整课程 |
knowledge-base | document-parsing | 入口明确要求先完成文档解析 |
agent-core | tool-calling | Agent 循环依赖已验证的工具调用边界 |
llmops | evaluation | 发布门必须已有可回归的评测合同 |
benchmark-design | evaluation | Benchmark 入口明确要求先掌握 case 与 grader |
synthetic-data | data-cleaning、data-annotation、evaluation | 数据合成入口使用“先学习”强语义 |
multi-agent-collaboration | agent-core | 多 Agent 入口明确要求已完成 Agent 核心 |
当前只落正文使用“先完成”“先学习”等强语义且能在角色路线中闭合的边；“建议先理解”“可并行”“按项目需要”均只通过 track 顺序或人工说明表达，不升级为硬前置。MCP、环境型 Agent、Agent Skills、具体框架，以及 Chunking 到 Reranking 的系统集成顺序都遵守这一边界。
| 角色路径 | 课程总数 | 核心 | 推荐 | 可选 |
|---|---|---|---|---|
agent_app | 32 | 9 | 13 | 10 |
rag | 35 | 17 | 12 | 6 |
agent_platform | 38 | 14 | 16 | 8 |
multimodal_realtime | 29 | 10 | 13 | 6 |
RAG track 用目录内的细粒度顺序表达“摄取—检索—生成—评测”的推荐推进；多模态路线把 OCR 标为推荐、ASR/TTS 标为核心，并不声称端到端 speech-to-speech 运行时必须部署独立 ASR/TTS 服务。完整隐私计算课程位于安全之后，而数据最小化、目的限制和保留期仍应在早期安全 milestone 中先处理。
“安全与评测基础”仍指课程中的部分章节，不是稳定课程级节点；它继续用人工 milestone 表达，不能把整门 AI 安全或整门评测体系误设为所有项目的早期硬前置。完整 AI 安全课程已按角色放在生产发布门附近，完整 AI 治理课程进入 Agent 平台路线；两者的课程级 track 位置不替代早期必读章节。
前沿与参考的进入规则
frontier-reference 不作为资讯聚合箱。主题只有同时满足以下条件才能成为课程：
- 有版本化的一手规范、原始论文或公开治理机制，而不是只有厂商宣称；
- 能交付可测试的工程工件或采用决策证据；
- 与既有课程边界清楚，并记录观察日期、采用条件、迁移与退出条件；
- 在任何角色路径中默认只作为可选内容，除非另有充分的普遍硬依赖证据；
- 稳定原理与快速变化的 SDK、扩展、供应商适配分层表达。
首个进入该域的课程是 A2A。采用依据是 A2A 1.0.0 已提供正式协议模型、版本协商、标准 binding、安全与互操作测试要求，并能形成 Agent Card、Task 合同、负向用例与迁移决策等稳定学习产物。它只进入 agent_app 和 agent_platform 的可选路径，不成为 MCP、多 Agent 或普通 Agent 应用的硬前置。
消费者与同步
总路线 在 Obsidian 中调用唯一的可勾选 Dataview 课程地图，并直接保存四条角色清单。该 view 读取兼容字段 stage/order 来分组，向各课程入口写入本地完成状态；公开构建不依赖 Dataview，而是用同一 YAML AST 解析结果把该调用替换为静态知识域表，并逐字校验角色清单。角色清单的元数据变化而路线未同步时会失败关闭。
网站 Homepage 和 CourseNavigator 只读取 v2 domain/catalog_order/track 字段：前者展示当前 10 个有课程的知识域和四条角色路径统计，后者同时提供按角色排序的入口与按知识域组织的完整课程树。受控 domain 仍为 10 个，frontier-reference 通过上述进入规则保持稀疏，不为凑数创建课程。旧 stage/order 只继续驱动总路线的本地交互地图，不驱动公开首页或课程导航。