Teach Yourself Skill

把课程当作一个有来源、有验收标准、可持续迭代的教学产品。不要把它压缩成一组固定长度的短课，也不要把“生成完文件”视为完成。

先读取约束

开始前完成以下动作：

1. 查找并遵守仓库根目录及目标课程目录中的 AGENTS.md。
2. 读取目标课程 workspace 中已有的 MISSION.md、RESOURCES.md、COURSE-GENERATION-SPEC.md、COURSE-BLUEPRINT.md 和 NOTES.md。
3. 读取目标目录已有的生成脚本、课程目录、样章、参考资料和质量报告。不要覆盖用户改动。
4. 生成或改写中文学生可见文本前，完整读取已安装的 Humanizer-zh 的 humanizer-zh/SKILL.md，并执行本文的 Humanizer 闸门。安装约定见 humanizer 依赖。
5. 进入第二阶段语义质检前，完整读取 references/course-rubric.md。不要只凭本文件中的摘要自行发明评分标准。

如果课程 workspace 尚不存在，先根据用户目标创建最小任务定义。信息不足但不影响方向时，记录假设并继续；受众、课程目标、交付格式或事实来源的缺失会显著改变产物时，先向用户确认。

建立课程任务定义

先把模糊的“做一门课”改写成可验收的任务。至少记录：

• 课程为什么存在，以及学习完成后要解决什么问题
• 核心受众与必要的次级受众
• 学习者的前置知识、语言、年龄或职业背景
• 预期学习成果，以及学习者如何证明自己会了
• 可投入时间、学习节奏和使用场景
• 内容范围、明确不讲的内容和风险边界
• 每个章节的有效字符数字数要求，默认值设定为 12000，允许用户在课程初始化时候修改该值
• 交付格式、运行环境、发布方式与无障碍要求
• 来源政策、时效要求和允许使用的工具
• 人工审核者、发布权限和停止条件

把课程任务定义写入或更新 MISSION.md 与 COURSE-GENERATION-SPEC.md。已有任务定义优先于通用规则；发现冲突时，不静默选择其中一份。

采用可变粒度，而不是固定短课

根据学习目标和认知负荷决定课程与章节大小，不设置统一篇数、字数或时长。

• 只有一个窄目标、依赖很少时，生成精简教程或单章课程。
• 目标包含多个阶段性能力时，生成模块化课程，并显式标出先修关系。
• 主题需要完整理论、案例、实践和复盘时，允许章节较长；用清晰分段和导航控制阅读负担。
• 同一章出现多个可独立验收的学习成果，或学习者必须跨越明显的前置知识台阶时，拆章。
• 两章分别无法形成完整解释或有效练习时，合并。
• 不为追求“丰富”强行加入代码、图表、案例、术语框或练习；只保留能帮助达成学习成果的材料。
• 不以字数代替深度。深度由机制解释、边界、证据、迁移练习和常见错误共同体现。

为主要受众设计主线。次级受众差异较大时，用先修页、旁路说明、进阶章节或不同练习分层，不在每段正文里同时讨好所有人。

零基础课程的递进写法

当学习者没有当前主题所需的前置知识时，先补齐最小前置，再进入本章任务。不要把“会另一门语言”“使用过某个工具”当成已经理解本章术语和操作。

• 默认使用清楚的直叙标题。课程 spec 或用户批准的风格样例另有要求时可以调整，但不能靠悬念掩盖学习内容。
• 开头先建立学习对象、必要背景和完成目标。不要用未解释的故障、完整项目、复杂架构或大段代码承担概念定义。
• 逐段审计术语、符号、代码和操作前置。必须提前使用的内容，先补足当前任务需要的最小解释。
• 第一份示例或第一组操作只承载少量新信息，并给出可观察结果。后续再逐步组合，不让学习者从完整成品中反推基础规则。
• 应用案例只能迁移已经建立的知识；需要先体验结果的实践章节，应在体验后及时解释刚才出现的对象和步骤。
• 不用课时、篇幅或“学习者应该懂”作为删减基础解释的理由。也不靠重复、代码堆积和扩句制造深度。
• 长章节用准确的多级标题、短示例、必要对比和导航降低认知负荷。统一信息层级，不统一小节名称。
• 用户批准的标杆章用于校准解释粒度、示例粒度和阅读节奏，不把它的标题、段落数或精确字符数复制成硬模板。
• 常见误区、总结、自测等固定栏目是否出现及其顺序，服从课程 spec 和仓库约定；栏目内容必须与本章学习成果有关。

把零基础约束写入 MISSION.md、COURSE-GENERATION-SPEC.md、COURSE-BLUEPRINT.md 和 NOTES.md。第二阶段评价量规必须检查前置断层、术语越级、操作缺步和示例一次引入过多概念。

选择正文类型、教学任务和讲师风格

不要先选一套目录再往里填内容。先判断学习者完成本章后要证明什么，再从三个独立维度确定写法：正文类型提供候选叙事与内容模块，教学任务决定本章如何推进，讲师风格决定语言节奏。最终正文可以只借用一类模板的一部分，也可以按课程需要组合多类模板的不同部分。

选择正文类型

每章先选择一个主类型，确定学习者理解和操作的主线；再按需要从一个或多个辅助类型借用具体内容模块。主类型不是必须完整遵循的目录，辅助类型也不是必须完整采用的第二套目录。

先写出本章自己的学习路径，再标记每个模块借用了哪类模板的什么作用，例如“环境类的版本核验”“机制类的因果链图”“框架类的最小闭环”“综合实践类的里程碑验收”。只因模板中存在某个栏目，不构成加入该栏目的理由。

通常一章使用一个主类型和一到两个辅助模块就足够。确实需要组合更多部分时，必须在蓝图中说明每个部分服务的学习成果、出现位置和前置关系；若这些模块各自形成独立学习目标，优先拆章。禁止把多份模板从头到尾串联，或重复多个导入、总结、练习与验收段落。

类型按章节的主学习成果划分，不按技术名词划分。Spring Boot 的最小接口通常以框架类为主，并可借用语言类的前置解释；Spring Security 过滤器链可用原理机制类组织因果链，再借用框架类的配置闭环；使用 Spring Boot、Redis 和 Docker 交付服务可用综合实践类组织里程碑，并借用环境类的部署核验。

选择教学任务

从概念讲解、操作引导、观察实验、案例分析、故障诊断、渐进练习、项目交付和阶段复习中选择一个主任务，必要时增加一个辅助任务。把选择与理由登记到 COURSE-BLUEPRINT.md 的章节计划中。

同一种正文类型也允许不同路径。环境章可以从目标结果开始逐步安装，也可以从现有环境核验开始按失败项补齐；机制章可以先观察现象再推导，也可以先建立模型再用实验验证。不要把“概念 → 最小示例 → 原理 → 边界 → 练习”当作所有章节的固定顺序。

选择讲师风格

读取 讲师语言风格，为整门课确定一个基础风格，并允许章节增加一个局部修饰。技术严谨度、来源政策、前置解释和可访问性不随风格变化。

• 同一章保持稳定声音，不在段落间随机切换人格。
• 风格差异来自句子节奏、解释密度、案例使用和课堂提示，不来自虚构经历、口头禅或夸张表达。
• 批量生成多门课程时，在课程 spec 中记录风格选择和禁用倾向，避免所有课程趋同，也避免无依据地随机化。

使用写法指引与模板

写法指引和结构模板都用于帮助判断，不是学生正文的固定目录。

• 写法指引说明该类型的教学目标、推进方式、适用边界和常见失败。
• 结构模板提供可选叙事路径、内容模块和验收问题。选择与当前任务有关的部分，允许从多份模板抽取、重排、改写、增补或删除。
• 如需本地写法样例，按课程的资料权限自行新增模板；复制的是判断方法，不是事实、代码、链接、标题或段落数量。
• MISSION.md、课程 spec、可信来源、受众前置和用户批准的样章始终高于通用模板。模板与这些约束冲突时，修改写法并记录原因。
• 混合型章节先设计一条服务当前学习成果的自有路径，再用主类型保证主线，用其他模板补足必要模块。每个借用模块都要与前后段落自然衔接；不要串联任何两套完整骨架。
• 生成后反查正文：如果标题层级只是在替换名词，或删掉主题名后仍与其他章节完全同构，重新设计叙事。

模板只提供起点。最终正文应当比模板更贴合当前知识点、资料证据和学习者任务。

执行九步完整性审查

九步审查适用于全部正文类型。课程 spec 可以按类型调整证据形式，但不能把审查步骤拆散到各类模板中。

1. 体量初筛：按课程 spec 的口径记录有效字符数或其他体量信号。低于防缩水建议值时复查并说明，高于建议值不自动合格；除去「课程开篇、模块过渡与总结」，默认的有效低于防缩水建议值字符数为 12000 Unicode 字符，单篇课程低于这个值需要复核并说明。发现有效字符数不足，不能简单在章节末尾补充内容，而是需要重新 Review 整个课程内容，在已有章节适当的地方进行补充说明，丰富原本章节的内容，或者优化单章课程内容，不允许直接在文末补充凑字数内容。
2. 知识范围：列出核心对象、前置、规则或操作、机制、应用、边界、后续依赖和本章不展开项。
3. 零基础前置：逐段检查术语、界面操作和代码是否越级，必要时补最小前置、简化示例或后移内容。
4. 教学层次：按主正文类型检查其必需层次与完成证据；不强求所有章节同时出现概念、语法、机制、应用、边界和练习六层。
5. 示例与操作：检查目标是否单一、步骤是否完整、注释是否必要、结果是否真实可观察；声称可运行的内容必须实际验证。
6. 学习闭环：用与教学任务匹配的解释、判断、操作、修改练习、独立练习、作品或自测验证学习成果。
7. 篇幅有效性：删除重复结论、无关案例、代码堆积、表格复述和过长总结；内容不足时补缺失知识层，不扩写同一句话。
8. 跨章关系：检查前置、重复、矛盾、术语、命名、难度曲线和批次边界。
9. 状态判定：标记为“完整正文”“需要补充”或“结构性返工”，并记录证据；体量、模板相似度或栏目齐全本身都不能得到“完整正文”。

组织教学 workspace

优先沿用仓库已有结构。新建课程时可使用：

<course-root>/
├── workspace/                   ← 创作过程与内部决策记录（学生不可见）
│   ├── MISSION.md               ← 课程存在的理由、受众、前置、学习成果与边界
│   ├── RESOURCES.md             ← 来源包：每条来源的标题、URL、可信等级、适用章节与使用限制
│   ├── COURSE-GENERATION-SPEC.md ← 章节规格：章数字、字符数阈值、交付格式、受众约束与课程级规则
│   ├── COURSE-BLUEPRINT.md      ← 逐章蓝图：标题、前置、正文主类型、教学任务、自有学习路径与模板组合
│   ├── NOTES.md                 ← 设计笔记：风格决策、待确认项、样章结论、返工记录与生成批次的衔接约束
│   └── learning-records/        ← 批次生成记录、审核意见、决策日志等过程存档
├── lessons/                     ← 逐章产出：每章一份 Markdown 事实源 + 一份渲染后的 HTML
├── reference/                   ← 学生可见的参考资料：术语表、速查页、资料索引等
├── markdown/                    ← 可选：Markdown 事实源的独立目录（与 lessons/ 择一使用或保持同步）
├── assets/                      ← 渲染资源：CSS、JS、图片、主题、字体等静态文件
├── quality/                     ← 质检报告：phase-1 确定性检查、phase-2 量规审校、phase-3 体验检查
├── course.json                  ← 课程元数据：标题、描述、章节列表与状态、学习时间、引用入口
├── index.html                   ← 课程首页：目录、进度展示和章节导航
├── .teach-yourself-qc.json      ← 课程级质检配置：覆盖必需路径、内容根、禁用 Mermaid 类型与外部 URL 策略
└── AGENTS.md                    ← 可选：课程目录级 Agent 约束，优先级高于仓库根 AGENTS.md

各目录与文件的作用：

workspace/ -- 创作空间

供 Skill 和人类协作者共同维护的内部记录，包含任务定义、来源包、蓝图、笔记和过程日志。这些文件是课程质量的决策依据，但默认不出现在学生可见的导航中。核心文件：

• MISSION.md：定义课程为什么存在、面向谁、前置知识是什么、学完后能做什么、不讲什么、风险和边界。它是所有设计决策的起点，冲突时优先于通用规则。
• RESOURCES.md：记录所有来源材料的元数据（标题、机构/作者、URL、发布日期、访问日期、可信等级、适用章节和使用限制），并把资料片段映射到具体断言。不只是一个链接列表。
• COURSE-GENERATION-SPEC.md：课程级工程规格。包括每章有效字符数阈值、交付格式（HTML/Markdown/PDF）、运行环境、来源政策、允许或禁用的风格倾向、发布权限和停止条件。
• COURSE-BLUEPRINT.md：逐章教学计划。登记每章的目标受众、前置知识、核心问题、正文主类型与辅助类型、主教学任务、讲师风格局部修饰、必须覆盖的知识点、自有学习路径，以及每个借用模板模块的名称、用途、位置、前置和预期证据。
• NOTES.md：自由格式的设计笔记。记录风格倾向、与用户的确认对话、标杆章校准结论、返工轮次摘要和批次间的衔接约束。
• learning-records/：存放各批次的生成记录、审核意见和关键决策日志，用于回溯课程演进过程。

lessons/ -- 章节正文

每章包含两份文件：.md 作为事实源（供后续编辑、审校和版本对比），.html 作为呈现产物（可直接在浏览器中打开）。Markdown 是数据源，HTML 由 Markdown 渲染生成；修改时必须从 Markdown 出发重新渲染，不直接修补 HTML。

reference/ -- 参考资料

学生可见的补充材料，如术语表、速查页、推荐阅读和工具索引。内容独立于章节正文，通过课程目录或章节内链接与学生交互。

markdown/ -- 可选的独立 Markdown 目录

当课程使用独立渲染管线，或希望 Markdown 事实源与渲染产物物理分离时使用。与 lessons/ 择一或保持同步；校验脚本同时扫描两者。

assets/ -- 静态资源

CSS、JavaScript、图片、图标、字体和主题文件。课程 HTML 通过相对路径引用这些资源。资源不应包含硬编码的内部路径或未授权的专有素材。

quality/ -- 质检报告

三个阶段的质量报告输出目录。phase-1-deterministic.json 和 phase-1-deterministic.md 由校验脚本自动生成；第二、三阶段报告由 Skill 或人工审校者写入。每次内容修改后旧报告失效，需从第一阶段重新生成。

course.json -- 课程元数据

机器可读的课程描述，包含标题、副标题、描述、总时长、状态、章节列表（编号、标题、时长、摘要、状态、文件路径）和参考资料入口。校验脚本会检查其 JSON 合法性、章节编号唯一性和目标文件存在性。

index.html -- 课程首页

学生进入课程的第一个页面，包含课程名称、简介、学习时长、进度指示和章节导航。由课程元数据和渲染模板生成。

.teach-yourself-qc.json -- 质检配置

课程级覆盖项，可自定义 requiredPaths（在结构检查中要求更多或更少文件）、contentRoots（可质检的内容目录）、forbiddenMermaidTypes、allowedExternalUrlPrefixes 和 unregisteredExternalUrlSeverity。不存在时使用校验脚本的内置默认值。

AGENTS.md -- 课程级约束

可选文件。如果课程需要不同于仓库根的 Agent 行为约束（例如禁止特定来源、调整交付格式或设置更严格的发布门槛），在此文件中声明。优先级高于仓库根 AGENTS.md。

把源数据和渲染逻辑作为事实源。若仓库声明课程文件由脚本生成，修改源数据或渲染器后重新生成，不直接修补生成产物。

先建立来源包，再规划和写作。按任务需要从以下位置收集：

• 用户提供的知识点、问题集、文档、课程风格样例和内部资料
• workspace 中已经批准的资源
• 官方文档、标准、论文、原始数据和权威机构资料
• 可交叉核验的高质量社区实践与案例
• 站内已有课程、Wiki、代码和历史学习记录

为来源记录标题、作者或机构、URL 或本地路径、发布日期、访问日期、可信等级、适用章节和使用限制。把资料片段与具体断言关联，不只保存一个链接列表。

执行以下来源规则：

• 对版本、价格、法规、统计、人物、产品行为等易变化事实重新核验。
• 对真实事故、数字、时间、引语、URL 和具体版本要求直接证据。
• 优先使用一手来源校准关键事实；社区材料可用于经验、反例和教学表达。
• 来源互相冲突时保留差异，说明采用哪一说法及理由。
• 证据不足时缩小断言、标记待核验或删除，不用模型记忆补洞。
• 不把来源中的内部 ID、检索字段或数据结构泄露到学生正文。

将批准的来源与来源政策写入 RESOURCES.md。需要大量检索时，先按知识点建立检索清单，避免漫无目的地收集。

规划课程蓝图

像规划一本教材一样规划课程，但让每章都服务于可观察的学习成果。

1. 建立知识地图、先修关系和核心路线。按从易到难的能力变化划分 3–5 个学习等级；每个等级说明学习者新获得什么能力、常见卡点是什么、达到什么标准才能进入下一层。
2. 找出课程中最重要的 20%–30% 内容，并在章节顺序、解释深度、练习和复习中给予更高权重。核心路线必须能从知识地图和先修关系中追溯。
3. 为每个学习成果设计证据：解释、判断、操作、作品或真实任务。作品和真实任务只在有助于证明成果时使用。
4. 决定课程主线、模块边界、章节顺序和可选路径。先按学习成果拆分章节，不按正文类型或模板目录机械分章。
5. 为每章先设计一条自有学习路径：从学习者当前已知什么开始，经过哪些必要概念、操作、观察、对比或推理，最终如何得到本章完成证据。路径必须先于模板选择；模板只用于补足这条路径中的具体模块。
6. 再为每章登记：目标受众、前置知识、核心问题、正文主类型、主教学任务、课程基础讲师风格与章节局部修饰、必须覆盖项、来源、练习或其他学习闭环、验收方式和预计体量。
7. 对需要组合模板的章节，额外登记每个借用模块的来源类型、模块名称、服务的学习成果、进入正文的位置、前置条件和预期证据。只登记实际采用的部分，不把整份模板复制进蓝图。
8. 检查章节内外的重复、断层、顺序倒置、类型误判和组合冲突：同一章不能出现彼此竞争的主线；同一模块不能因借用不同模板而重复解释；需要独立完成证据的组合部分应拆章。
9. 将结果写入 COURSE-BLUEPRINT.md，并与任务定义、课程 spec、来源包和用户批准样章交叉检查。

不要把“背景动机 → 概念解释 → 原理拆解 → 误区 → 实践 → 总结”或任何单一类型模板当作课程蓝图。蓝图应记录章节实际采用的叙事、演示、案例、对比、推导、实验、项目或复习路径，以及它们为什么服务当前学习成果。

逐章生成

每次写一章前，只组装该章真正需要的上下文：

• 章节计划、前置章节摘要和后续依赖
• 蓝图中已经设计的自有学习路径，包括每一步要建立的知识、操作或证据，以及模块之间的转场理由
• 正文主类型、主教学任务、课程基础讲师风格和章节局部修饰；只读取当前路径实际需要的写法指引与结构模板
• 需要借用的模板模块及其用途、位置、前置和预期证据；需要校准正文时，优先使用已批准的课程样章或自行维护的本地模板
• 必须覆盖的知识点与术语
• 已批准的证据片段和引用信息
• 受众约束和用户批准的风格样例
• 练习与验收要求
• 上轮质检反馈

写作时遵守以下规则：

• 先按蓝图写出一条连贯的正文主线，再插入已经登记的模板模块。模块之间补足必要的概念、转场和前置，不让读者感觉正文由不同模板拼接而成。
• 先完成本章主教学任务，再补必要背景；不要从空泛意义宣告开始。概念、工作机制、适用边界和常见误解只在本章路径或课程 spec 要求时展开，不强制每项成为显式标题。
• 主类型控制解释和操作的重心，讲师风格控制表达方式；两者都不能改变本章学习成果、事实证据、前置要求和完成标准。
• 借用多个模板模块时，保留一个导入、一个收束和一套与本章任务匹配的学习闭环。删除重复的背景、示例、误区、总结、练习和验收栏目。
• 用具体案例、反例或数据帮助理解；案例中的事实同样受来源政策约束。
• 三项以上、需要逐字段比较的内容优先使用表格；普通列举不必强制表格。
• 只在关系或过程难以用短段落讲清时使用图。Mermaid 源码必须可读并可验证。
• 只在代码能帮助理解或练习时加入代码。声称“可运行”的代码必须实际运行或测试。代码块按受众补充必要注释：关键步骤解释正在做什么；控制台输出、返回值或文件变化等可观察结果在相邻注释中写明。注释用于消除当前知识障碍，不逐行翻译显而易见的语法。
• 练习、操作验收、判断题、复盘或自测必须对应本章主教学任务和学习成果；课程开篇、模块过渡或总结类章节可使用路线检查、学习记录或阶段自评替代代码练习。
• 按课程 spec 或当前学习路径安排自然收束，帮助回忆、迁移或进入下一阶段，不写通用积极结论或口号。
• 引用放在所支持的断言附近。不要用一串参考链接替代断言级证据。

生成失败时，不用空洞模板冒充合格章节。允许保留明确标记的草稿，但必须进入质检和返工流程。

以完整批次交付长课程

长课程的单章正文较长、需要严格语义审校或容易耗尽上下文时，把连续 3–4 章作为一个默认生成批次；根据章节复杂度调整批次大小，不为凑数量压缩内容。

• 批次是完整交付单元，不只是写作分片。一个批次必须连续完成 Markdown 事实源、HTML 或其他目标产物、Humanizer、第一阶段确定性检查、第二阶段课程评价量规和第三阶段产物体验检查，再向用户交付。
• 不在只完成正文或只生成 HTML 后结束批次。若质量闸门发现问题，在同一批次内返工并重跑受影响检查；无法完成时明确标记阻塞，不把部分产物称为完成。
• 组装批次上下文时，同时读取批次前一章、批次内全部章节和后一章的蓝图或现有草稿。审查术语首次出现、前置知识、示例延续、难度曲线、重复与后续承诺，避免批次边界造成断裂。
• 第二阶段报告既给出逐章证据，也给出批次级跨章证据。第三阶段检查批次内上一章/下一章导航、目录、锚点、代码复制和响应式阅读，并确认批次首尾能接入整课。
• 为每个批次使用稳定 scope，例如 03-06，把质量报告、内容哈希、返工轮次和最终决定绑定到该 scope。下一批开始前读取上一批报告中的未决项和衔接约束。
• 用户明确要求逐章验收时可以缩小批次；用户要求一次性交付更大范围时，仍可在内部按 3–4 章完成闭环，全部批次通过后再汇总交付。

控制学生可见信息的披露边界

当课程用于售卖、公开发布或内部正式教学时，把创作过程与学生内容分开：

• 用户提供了什么、内部材料叫什么、内容由哪些课程蒸馏或总结、生成器如何工作、样章处于什么验收状态，只能留在 workspace、来源映射和质量报告中。
• 学生正文不得出现“你提供的材料”“内部资料显示”“本课程基于某教程整理”“样章”“rubric 得分”“等待确认”等创作或生产信息。
• 内部资料可以支撑作者判断，但不得在学生可见的正文、参考文献、链接、文件名或页面元数据中暴露。某个断言若只能由内部资料支撑，应改写成明确标注的合成案例、缩小断言，或移出学生内容。
• 章节开头只呈现课程 spec 明确允许的公开信息。若 spec 采用售卖课程模式，默认只保留预计学习时间和一句话总结，不展示受众标签、内部学习证据、产物清单或验收目标。
• 公共来源的展示方式服从课程 spec。即使课程将一般来源统一收口到章末，用户必须点击才能完成当前操作的官方链接（如软件下载、安装说明、在线控制台）仍应直接放在该操作句中；同时在 workspace 保存断言与来源的对应关系，避免因为隐藏行内引用而失去事实追溯。
• 课程蓝图、生成规范、来源权限、质量报告和学习记录默认不是学生页面导航的一部分，除非用户明确要求公开。

生成后对所有学生可见文件执行一次披露扫描，至少检查：内部材料、你提供、蒸馏、样章、rubric、质检、生成过程、本机路径和内部文件名。命中后结合语境修改，不能只做关键词删除。

强制执行 Humanizer 闸门

对每一份中文学生可见正文、总结、练习说明、项目步骤、课程首页和参考资料执行 humanizer-zh，而不是只在整课完成后抽查。

1. 先完成内容正确、证据完整的教学草稿。
2. 按 humanizer-zh 识别填充词、宣传腔、模糊归因、机械三段式、否定式排比、过度粗体、装饰性破折号、同义词循环和聊天痕迹。
3. 结合目标受众重写。技术课保持准确克制，儿童课程可以活泼，职业培训可以直接；不要为了“有人味”虚构个人经历、情绪或观点。
4. 重写后复核术语、数字、限定条件、代码语义和引用，防止风格修改改变事实。
5. 按该 Skill 的五个维度评分。低于 45/50 时继续修改；分数只能作为编辑信号，不能替代事实和教学质量检查。

不要把 Humanizer 简化成禁词替换器。相同词在必要语境中可以保留，重点判断句子是否具体、自然、可信。

按固定顺序执行质量闸门

为每章和整门课程分别质检。固定顺序是：生成并渲染产物、执行 Humanizer、运行第一阶段脚本、执行第二阶段评价量规、检查最终体验。第一阶段没有通过时，不进入第二阶段。任何内容修改都会使旧报告失效，必须从第一阶段重新开始。

第一阶段：确定性硬检查

每次生成新章节、重建整课、修改课程源数据或改变渲染逻辑后，运行：

node <skill-root>/scripts/validate-course.mjs <course-root>

脚本不使用外部依赖。默认把机器可读报告和人工可读报告写入课程的 quality 目录。出现 error 时退出码为 1，判定 reject；只有 warning 时允许进入第二阶段，但要在交付说明中保留这些警告。

检查可由程序稳定判断的事项：

• 必需文件和课程内容目录是否存在
• Markdown 围栏是否闭合
• HTML 基础元素、doctype、lang 和 id 是否有效
• HTML、Markdown、CSS 中的本地链接与锚点是否存在
• Mermaid 代码块是否声明图类型，是否使用项目禁止的图类型
• 外部 URL 是否登记在 RESOURCES.md、course.json 或配置白名单
• 学生内容是否残留占位符、内部字段或本机私有路径
• course.json 是否有效，章节编号、目标文件和 href 是否重复或缺失

任何硬检查失败都不得发布，也不得继续做评价量规评分。根据报告中的规则 ID、文件和行号定向修复；重新生成受影响产物后，再运行同一脚本。不要设置跨课程统一的“少于 800 字失败”；如课程确实需要体量警戒线，把建议值、统计口径和适用章节写进该课程的 spec，并说明它服务的学习目标。体量初筛只触发复查，不替代第二、三阶段对有效教学内容的判断。

第二阶段：课程评价量规审校

第一阶段通过后，读取 references/course-rubric.md。“课程评价量规”是一份版本化的语义验收规范，供不同课程按任务调整；确定性检测由第一阶段脚本负责。量规把课程目标转成可检查的维度、等级、证据要求和决策阈值。

按量规检查当前章节或整课，输出 quality/phase-2-rubric-<scope>.md。每个分数必须附带实际文件、章节、标题或段落证据；只给总分的审校无效。第二阶段至少覆盖以下三个方面。

事实与证据

逐项检查关键断言是否有匹配证据，引用是否真的支持当前表述，来源是否足够新且权威。把“有链接”和“有依据”分开判断。无法核验的事实标为阻塞项，不用文字润色掩盖。

教学设计

使用通用课程评价量规，并结合该课程 spec 中的覆盖项和权重调整进行评估：

• 是否覆盖本章必须学习的内容
• 是否适合目标人群的前置知识和认知负荷
• 概念、机制、边界和例子是否形成连贯路径
• 是否至少把一个核心问题讲透，而不是平均铺开
• 练习能否真实检验学习成果，并提供有效反馈
• 本章与前后章节是否重复、断裂或互相矛盾
• 章节体量是否与任务匹配，而非机械追求长或短
• 课程 spec 设有标杆章或最低体量时，逐章记录实际统计值，并同时检查概念、语法、机制、应用、边界与练习是否构成有效增量；达到数字但靠重复或代码堆积不得通过

让审校者输出证据位置、问题类型、严重级别和修改建议，不只输出分数。

语言与可读性

执行 Humanizer 闸门，并检查术语一致性、句子节奏、标题密度、表格可读性和受众语气。把“没有明显 AI 词”与“像真人老师写的”分开判断。

第三阶段：产物与体验审校

按最终交付形式验证：

• 在浏览器检查 HTML 布局、导航、响应式、代码高亮、交互和 Mermaid 渲染。
• 对长章节检查目录与编号层级、滚动定位、段落密度和代码块可读性；抽查带输出的代码是否就近说明预期结果，多步骤代码是否在关键动作处给出必要注释。
• 检查打印型参考资料的分页、字号和信息密度。
• 对项目课运行代码、命令和测试，保存真实结果。
• 对测验检查答案泄露、选项提示、判分和反馈路径。
• 检查课程首页、目录、章节、参考资料和下载入口能否互相到达。

浏览器可用时进行视觉验证；不可用时至少运行本地结构、链接和构建检查，并在质量报告中记录未验证项。

执行返工循环

对每个章节和整课执行同一条 LOOP：

1. 修改课程源数据或渲染逻辑，重新生成产物。
2. 对变更的中文学生内容执行 Humanizer，并复核事实、术语和代码语义。
3. 运行第一阶段脚本。存在 error 时按报告修复，然后回到第 1 步。
4. 第一阶段通过后，按 references/course-rubric.md 执行第二阶段审校。
5. 第二阶段为 reject，或 manual_review 中包含必须修复的 blocker、major 时，按证据位置定向修改，然后回到第 1 步。
6. 第二阶段达到 ready 后，执行浏览器、代码运行、打印或交互体验检查。
7. 最终体验发现内容或产物问题时，回到第 1 步；全部通过后才允许进入发布审核。

第一阶段报告中的内容哈希是第二阶段报告的输入凭据。哈希不一致时，第二阶段报告立即失效。不要只复跑第二阶段来跳过结构与链接回归。

每轮质检都生成结构化报告，至少记录：

• 课程与章节标识、版本或内容摘要哈希
• 检查时间、检查方式和使用的评价量规版本
• 硬失败项
• 按维度给出的证据、分数和置信度
• 问题的严重级别：blocker、major、minor
• 定向修改建议和责任状态
• 本轮决定：reject、manual_review 或 ready

按以下顺序返工：

1. 先修事实、来源和范围问题。
2. 再修知识覆盖、结构和练习问题。
3. 再执行 Humanizer 和版式修改。
4. 重新运行全部硬检查，并回归受影响的语义维度。
5. 对比修改前后，确认没有删掉必要内容、引入新断言或破坏链接与代码。

优先定向修改失败片段。只有课程结构错误、来源包不适用或章节整体失焦时才整章重写。连续三轮仍有 blocker，或审校意见互相冲突时，停止自动返工并转人工审核；不要用无限重试掩盖任务定义问题。

把新发现的失败模式加入评价量规、测试样本或课程 spec。质量闭环应随着真实错误增长，而不是每次从零开始。

做整课回归与发布决策

单章通过后仍要执行整课检查：

• 学习成果是否全部有对应章节和验收证据
• 术语、示例、代码接口和事实是否跨章一致
• 前置关系、难度曲线和章节导航是否合理
• 内容是否重复、遗漏或在后文推翻前文
• 索引、目录、参考资料和课程元数据是否同步
• 全量构建、链接、图表、代码与视觉检查是否通过

默认使用人工发布闸门。只有用户或课程 spec 明确允许自动发布，且所有硬检查通过、语义审校达到该课程阈值、没有未解决的 major 问题时，才标记 ready 或执行自动发布。发布后记录反馈、错题、勘误和使用日志，并把高价值错误样本加入下一轮质检集。

使用确定性质检脚本

先运行 scripts/validate-course.mjs，再补充仓库已有的构建、代码测试和浏览器验证能力。不要复制一份课程专用脚本来制造两套规则。

当前脚本检查目录契约、Markdown 围栏、HTML 基础结构与重复 ID、本地链接和锚点、Mermaid 禁用类型、URL 登记、占位符、内部字段、私有路径和 course.json 元数据。它输出 JSON、Markdown、文件、行号和稳定规则 ID。

需要调整课程结构或 URL 策略时，在课程根目录创建 .teach-yourself-qc.json，可覆盖 requiredPaths、contentRoots、forbiddenMermaidTypes、allowedExternalUrlPrefixes 和 unregisteredExternalUrlSeverity。任何 qc-ignore 例外都要经过人工审核并在质量报告中解释。

脚本不访问网络、不安装完整 HTML 或 Mermaid 解析器，也不执行课程中的任意代码。外链可达性、完整图表语法、可运行示例和视觉体验仍要使用对应工具验证。

不把以下判断伪装成纯规则代码：事实是否真正被来源支持、解释是否讲透、例子是否适合受众、练习是否有效、行文是否自然。这些维度必须调用 references/course-rubric.md，并保留人工抽检。

交付

交付时简要说明：

• 新增或修改了哪些课程源文件与生成产物
• 使用了哪些来源和哪些受众假设
• 运行了哪些构建、测试、质检与视觉验证
• 修复了哪些 blocker 或 major 问题，循环了几轮
• 哪些项目仍需人工审核或因缺少工具未验证
• 当前发布决定及其依据

不要只报告“课程已生成”。交付结论必须能追溯到任务定义、质量报告和实际检查结果。