infrahub-teaching-concepts

Infrahub 概念辅导

概述

这是一套辅导协议，而不是教科书。它会评估学习者已有的知识，通过学习者自己的架构、对象以及所在的实例讲解每个概念，布置由学习者亲自完成的实践练习，并记录进度，让后续会话可以接着学，而不必从头开始。练习在展示前都会先验证其可解性。

适用场景

• “教我关系是如何运作的”或任何旨在学习而非委派任务的概念问题。
• “为什么我的实例会这样运行？”——当目标是理解时。
• “Infrahub 中的 X 相当于 NetBox/Nautobot 的什么？”——以对照讲解的方式教学（参见 rules/grounding-competitor-mapping.md）。
• “我们学到哪里了？”——从 .infrahub-learning/progress.md 继续学习。

环境检测

每个会话只检测一次，按以下顺序进行，并优先使用信息最丰富的来源：

1. 当前工作目录中的仓库文件（架构 YAML、对象文件、.infrahub.yml）： 通过学习者自己的文件进行讲解。
2. 可访问的 Infrahub 实例（MCP 服务或 infrahubctl）：通过只读查询，以真实数据说明概念。
3. 两者都没有：使用 references/concept-map.md 中的通用示例。

编写第一个 Explain 部分之前，先阅读 rules/grounding-own-artifacts.md — 学习者已有自己的文件时仍使用通用示例，属于违规行为， 不能作为备用方案。

实例安全分为三个级别；完整的安全流程见 rules/safety-instance-writes.md。 执行任何可能写入数据的命令前都要阅读此文件，包括你让学习者运行的命令。简而言之：默认只读，在本地文件中编写内容，并且只有获得明确同意后才写入实例；写入只能发生在 learning-* 分支中，绝不合并，并且始终删除。

工作流

1. 首次联系时，主动提出创建学习工作区，并阅读 references/lesson-protocol.md，了解确切的文件布局和课程结构。继续学习时，先阅读 .infrahub-learning/progress.md。
2. 使用 references/concept-map.md 选择概念：它按前置条件排列概念，并为每个概念提供探测问题、练习规范、验证方法和文档锚点。没有对应条目的主题，通过共享文档备用流程进行讲解 （rules/grounding-off-map-lookup.md）。
3. 编写任何课程文件之前，先阅读 rules/protocol-structured-lessons.md — Probe/Explain/Exercise/Check 的结构和顺序是固定的。
4. 以 Probe 开场，绝不从讲解开始。阅读 rules/protocol-probe-first.md，了解 提问数量以及问题需要确认的内容。
5. 根据学习者自己的文件编写 Explain，并为每项行为说明引用文档页面： rules/grounding-cite-docs.md。对于 “NetBox/Nautobot 中与之对应的是什么？”这类课程，可信度门槛见 rules/grounding-competitor-mapping.md。
6. 展示练习之前，按照 references/exercise-verification.md 和 rules/exercise-verify-solution.md 构建并验证参考解答 — 没有亲自解出练习，就不能发布。布置任务， 不要代为完成： rules/exercise-learner-authors.md。
7. 学习者遇到困难时，先按照 rules/exercise-hint-ladder.md 中的提示阶梯逐步提示，不要提前揭晓答案；每给出一级提示，就将其记录到 .infrahub-learning/hints/<concept>.md。
8. 每节课结束时、回复学习者之前，记录学习进度： rules/protocol-record-progress.md。
9. 结束每个概念的学习时，指出负责在真实项目中完成这项工作的相关技能： rules/handoff-graduation.md。

规则类别

优先级	类别	前缀	描述
严重	协议	protocol-	先探查再教学、固定的课程结构、进度记录
严重	安全	safety-	实例写入：主动选择加入、仅限 learning-* 分支、清理、绝不使用默认分支
高	练习	exercise-	已验证的参考解答、学习者编写的产物、提示阶梯
高	知识依据	grounding-	通过学习者自己的产物进行教学、行为声明需引用文档、地图外查找、基于来源的比较
中	交接	handoff-	指向相关技能的结课指引

各前缀的完整范围见 rules/_sections.md。请阅读与你当前课程阶段相关的规则；这些规则简明且具有约束力。

参考资料

• references/lesson-protocol.md：工作区约定和课程结构。此文件是这些内容的唯一出处。
• references/concept-map.md：课程内容。
• references/exercise-verification.md：如何在展示练习前证明它可解。
• ../infrahub-common/：共享的 GraphQL 语法和 .infrahub.yml 格式。