teaching-site

教学网站 — 主入口

架构权威来源：所有基础字段名称（unit / concept / prompt / task / material / quiz / faq / illustration）和规范项目布局均来自 _shared/domain-primitives.md。派发给任何子技能时，都应确保 Agent 先查阅该文件。

文件名约定（英文优先）：所有生成的文件都使用英文名称（course-package/、day{n}/outline.md、materials/ 等）。用户在聊天中说的触发短语可以保留中文，但写入磁盘的内容必须使用英文。完整映射请参阅 _shared/domain-primitives.md §0。

生产参考实现：d:/GitHub/ai-workshop/ 是生产环境参考项目（4 天工作坊、4125 行的 index.html、1728 行的 course-data.js）。将其用作视觉与渲染模式参考；不要复制其中特定课程的内容。

这是用于制作交互式教学网站的顶层技能。它协调 10 个专用子技能，涵盖从空白大纲到交付 PDF 电子书的各个阶段。

何时使用此技能，何时使用子技能

• 在以下情况使用此技能（teaching-site）：

  • 用户的请求比较宽泛（“做一套课程网站”“我想做工作坊”）。
  • 你要从零开始，还不知道从哪里着手。
  • 用户在不同阶段之间切换，需要协调流程。
  • 修改后需要检查各项产物之间的一致性。

• 在以下情况直接使用子技能：

  • 用户明确指定了产物（“做电子书” → course-ebook-publishing）。
  • 你已经深入某个阶段，不需要了解完整流程。
  • 其他技能将此技能调度来执行特定子任务。

两种路径最终都会汇合——子技能既可通过直接触发调用，也可由此技能调度。

生产流程

教学网站分为五个核心层，以及最后两个可选的衍生层：

[Stage 1] outline (.md)
    ↓ produces: meta, day list, unit skeleton, learning goals, shared scenario
[Stage 2] content authoring (.md / .csv / .yaml)
    ↓ produces: lecture notes, sample materials, quiz items, optional prompt templates
[Stage 3] SPA conversion (.js + .html)
    ↓ produces: course-data.js (data) + index.html (renderers), local serve setup
[Stage 4] interactions (.js + .css inside index.html)
    ↓ produces: progress persistence, sidebar/scrollspy, theme, RWD, quiz UX
[Stage 5] visual assets (.png / .svg / scraping scripts)
    ↓ produces: illustrations, screenshots, QR codes, maps
    ▼
─── site is now feature-complete ─── (optional derivatives below)
    ▼
[Stage 5b] Corporate Edition branch   ← optional, parallel to ebook
    ↓ produces: corporate-editions/ folder, condensed units, inlined COURSE, asset fallback chain
[Stage 6]  Ebook Publishing            ← optional, ALWAYS after site is stable
    ↓ produces: dist/{name}.pdf + .docx via single composed master.md

通常会按顺序经过阶段 1–5，但用户常常会回到之前的阶段（添加一个单元 → 必须更新大纲、course-data.js 以及任何相关视觉素材）。发现并处理这些反向依赖，正是此技能的主要价值。

阶段 5b 和 6 是已完成网站的下游使用方。它们会读取规范网站，但绝不会修改它。阶段 1–5 尚未稳定时，不要调用它们——返工成本很高。

子技能调度表

当对应阶段启用时，通过 Agent 的技能激活机制调用匹配的子技能（Claude Code：Skill 工具，Codex：skill 工具，Antigravity / Gemini CLI：activate_skill）：

阶段	子技能	触发短语
1	course-outline-design	“规划课程”“课程大纲”“几天怎么安排”“学习目标”
2	course-content-authoring	“写讲义”“补素材”“出测验题”“提示词模板”
3	static-spa-conversion	“做成网页”“转换为 SPA”“course-data.js”“render 函数”
4	static-spa-interactions	“添加进度勾选”“响应式”“暗色模式”“缩放”“scrollspy”
5	web-visual-assets	“插图”“工具截图”“QR”“讲师卡”“地图”
5b	course-corporate-edition	“企业包班”“浓缩版”“定制化”“压缩成一天”
6	course-ebook-publishing	“做电子书”“生成 PDF”“印给学员”“交付 DOCX”
╳	web-visual-verification	“验证网页”“RWD 验证”“Playwright 测试”“截图比对”
╳	web-content-audit	“盘点内容”“稽核资产”“查找缺图”“三处同步检查”
╳	teaching-site-design-system	“视觉风格”“设计系统”“色板”“字体”“玻璃卡片”

最后三个（以 ╳ 标记）是横向技能——不隶属于任何阶段。前两个（验证 / 审计）是运行时行为和跨文件引用的安全网。第三个（设计系统）是所有阶段都会参照的视觉权威。

阶段 1 门槛（硬性规则 — 派发前请阅读）

派发到任何阶段（包括阶段 2–6、5b 及跨领域技能）之前，确认阶段 1 的交付物已存在于磁盘上：

• 一份已填写 對象 / 總時數 / 每日主題 字段的概览文件（例如 overview.md）——不能只有标题。
• 至少一份按天划分的大纲文件（例如 day1/outline.md），其中列出单元 ID 和学习目标。

共享场景（shared-scenario.md）为可选项——这是由 course-outline-design 的完成门槛处理的后续决策，不是此处的准入要求。

**如果上述两项中任意一项缺失或只是空壳：**不要派发到后续阶段，即使用户明确指定了较后的阶段（“做电子书”“帮我写 quiz”）也不行。先派发到 course-outline-design，并告知用户：

「我看到还没有完整的课程大纲 — 直接跳到阶段 N 会让后续每次修改大纲时，都要连带重做多个文件。先用 course-outline-design 锁定大纲，大约花 10 分钟做决策，就能省下后续数小时的返工。」

阶段 1 覆盖策略（3 条要点的例外通道）

如果用户明确坚持跳过门槛（“我知道，先做就好”“跳过大纲，直接做 X”），请在以下条件下继续：

1. 在采取任何后续操作之前，要求用户在聊天中粘贴3 条要点：
   • 对象：用一句话描述学员是谁，以及他们的先备知识
   • 总时数 + 每日时段：例如“2 天 × 6 小时”
   • 每日主题：Day 1 / Day 2 / ... 各占一行
2. 将这 3 条要点原文不动地保存到一个存根 overview.md 中（标记 ``），然后再派发到用户指定的阶段。
3. 如果用户连这 3 条要点的存根也拒绝提供，则回到严格流程 — 拒绝覆盖请求，并派发到 course-outline-design。

这个存根是审计记录：今后阅读此站点的会话可以立即看出阶段 1 曾被绕过，并据此恢复上下文。

阶段 2 门槛（硬性规则 — 派发到阶段 3+ 前请阅读）

通过阶段 1 门槛后，在派发到阶段 3（static-spa-conversion）、阶段 5b 或阶段 6 之前，确认阶段 2 的交付物已存在于磁盘上：

• 每个 day{n}/content.md 都已存在（overview.md 中列出的每一天各有一个）。
• 每个 content.md 都包含 ## u-{id} 章节，涵盖对应 day{n}/outline.md 中声明的每个单元 ID — 不能只有一个。
• 每个单元章节都有实质内容：至少包含以下之一：(a) ≥ ~10 行的讲课稿，(b) 任務 (tasks) 列表，(c) 素材需求 参考内容。只有标题的单元不合格。
• 每个单元章节都声明 **圖片需求 (illustrations)**，列出 1–3 项内容，并包含文件名 + 简要说明 — 参见下方阶段 5 图片覆盖最低要求。

**如果任意一项不合格：**不要派发到阶段 3+，即使用户明确指定了较后的阶段也不行。先派发到 course-content-authoring，并告知用户：

「大纲已经有了，但第 {n} 天的 content.md {缺失/是空壳/单元 u-{id} 没有内容}。直接做网页只会生成一个薄薄的外壳 — 学员看到的只有标题清单，没有实质教学内容。先用 course-content-authoring 补全每个单元的讲课稿 / tasks / 图片需求，比之后重做整套网页省好几倍时间。」

阶段 2 覆盖策略（精简演示例外通道）

如果用户明确坚持只做精简演示（“先做个壳就好”“我只要做个 demo 给客户看版型”“跳过内容”），请在以下条件下继续：

1. 在聊天中明确说明他们将放弃什么：精简演示将只有单元标题，没有讲课正文，插图会用占位符 <div> 代替，任务则是空复选框。
2. 在每个受影响的 day{n}/content.md 中添加头部注释 ``（如果文件不存在，则创建存根）。
3. 生成 course-data.js 时，在每个受影响的单元上设置 __thinDemo: true，以便 SPA 显示“本单元尚未填内容”徽章 — 即使学员不知怎么进入了演示版，也能看出这不是真正的内容。

缺少上述任意一项，都不要继续。拒绝请求并派发到 course-content-authoring。

Stage 5 图片覆盖率下限（硬性规则——在宣布“网站功能完备”之前适用）

仅有封面图片和简单文字的网站会显得内容空洞，学员第一次向下滚动时就会失去兴趣。在宣布 Stage 1–5 已完成（因此符合派发到 Stage 5b / 6 的条件）之前，请确认：

• course-data.js 中的每个单元都有 illustrations[] 数组，且包含 1–3 个条目。（旧版单数 illustration: 'foo.png' 字段计为 1 个；进行此项检查时，将其视为 illustrations: [{ name: 'foo.png', kind: 'hero' }]。）
• 每个单元至少有一个条目能解析到 assets/ 下的现有文件（Stage 5 进行期间，其他条目可以仍是 SVG 后备占位图）。
• 如果某个单元确实不需要插图（很少见——例如 5 分钟的行政事务时段、仅有测验的单元），请明确记录豁免：illustrations: [{ kind: 'waived', reason: '...' }]。不作说明不算通过。
• assets/illustrations/（或项目中的对应目录）包含封面 以及 每个单元的图片——不能只有封面。

若未达标： 派发给 web-visual-assets，并告知用户：

「目前有 N 個單元沒插圖（或全站只有封面）。學員一打開會覺得內容很空、像草稿。建議先用 web-visual-assets 跑一輪批次生圖（每單元 1–3 張，搭配 PNG-first / SVG-fallback），再進入電子書／企業包班分支 — 否則 PDF 一印出來就是大片留白。」

此下限在 Stage 4 完成（交互功能接通）后、派发到 Stage 5b 或 6 之前检查。Stage 5b / 6 会沿用已有图片；如果跳过此项检查，企业宣传册和 PDF 电子书都会内容空缺。

如何判断当前阶段

Stage 1 Gate 和 Stage 2 Gate 均通过后，查看以下信号，选择合适的后续阶段：

• 大纲 .md 存在，但 day{n}/content.md 缺失或内容单薄 → Stage 2（course-content-authoring）。跳过 Stage 2 进入后续阶段需要通过门控——见上文 Stage 2 Gate。
• 内容 .md 已完成，但没有 course-data.js → Stage 3（static-spa-conversion）。
• course-data.js 存在，但 index.html 没有渲染器 / 无法本地运行 → Stage 3。
• SPA 可以渲染，但进度未持久化 / 页面不响应式 / 没有主题 → Stage 4。
• 网站可以运行，但图片仍是占位 <div> / 缩略图 404 / 单元缺少插图 → Stage 5（web-visual-assets）。
• 网站看似功能完备，但未达到 Stage 5 图片覆盖率下限 → 先执行 Stage 5；暂勿派发到 5b/6。
• 网站功能完备（所有门控和下限均已通过），用户提到企业版 / 内训 / 精简版 → Stage 5b。
• 网站功能完备（所有门控和下限均已通过），用户需要可打印 / 归档 / 分享的文件 → Stage 6。

不确定？先问一个简短的问题，然后再派发。不要试图一次性完成所有阶段——跨阶段返工的代价很高。

操作原则

1. 绝不跳过阶段。 不要根据粗制滥造的 Stage 1 大纲生成 Stage 3 SPA——结构不匹配会不断累积。如果用户想跳过，请明确说明。

2. 始终追溯反向引用。 用户修改下游产物时（例如“将单元 u-6 添加到第 2 天”），请在同一项修改中更新上游内容（outline.md）和下游内容（course-data.js、相关视觉素材）。只更新一部分会让网站很快累积技术债。

3. 课程专属知识应属于用户的内容，而非技能。 各子技能有意不绑定课程的主题（AI 工作坊 / 烹饪课 / 会计培训——都走同一流程）。如果某个子技能似乎在硬编码特定领域的示例，就说明存在问题。

4. 验证命令也是交付内容的一部分。 派发到 Stage 3 或更高阶段时，请提醒用户如何验证（运行 npm run serve，然后访问 http://localhost:3000）。静态网站通过 file:// 打开时常会悄无声息地失效（localStorage 被阻止）。

参考文件（需要时阅读）

当你需要比本入口提供的更深入的信息时，请阅读相应的参考文件：

• references/consistency-checklists.md — 每次阶段转换后都要阅读。包含各阶段的完整跨产物检查清单（Stage 1、2、3……6、5b 后分别需要核查什么），可避免“我改了 X，却忘了更新 Y”之类的问题。

• references/scenarios.md — 用户意图不明确时阅读。包含十几种典型用户提示（“我有講義 .md 了”、“客戶要濃縮版 + PDF”），并映射到准确的子技能调度流程。

• references/troubleshooting.md — 有问题报告时阅读。将症状（“素材連結 404”、“進度勾選跑掉”、“PDF 沒頁碼”）映射到最可能的子技能、审计或验证流程。

• references/design-rationale.md — 解释技能架构本身，或判断新功能是否值得单独创建子技能、还是应纳入现有子技能时阅读。记录了整个流程如此设计的原因。

此技能不做什么

• 不会自行编写代码——始终调度子技能。
• 不会选择 CSS 框架或构建工具——默认采用原生 HTML/JS（原因见 static-spa-conversion）。
• 不会决定课程主题、受众或教学法——这些由用户决定。