course-content-authoring

课程内容编写

架构定义权：所有基本字段名称（unit / concept / prompt / task / material / quiz / faq / illustration）均来自 _shared/domain-primitives.md。本技能提及字段时，该文件是唯一依据。

文件名规范（英文优先）：所有生成的文件和目录均使用英文名称。旧版中文名称的对应关系见 _shared/domain-primitives.md §0。

本技能用于产出课程的教学实质内容：学习者阅读、复制、聆听或实践的内容。每项产出都对应 course-outline-design 中的大纲 ID，以便下一阶段（SPA 转换）能够自动完成关联。

交付物（标准布局）

course-package/   (your project's content root)
├── day{n}/
│   ├── outline.md           ← from outline stage (do NOT edit here)
│   └── content.md           ← THIS skill writes: lecture script, prompts, exercises, references
├── shared-scenario.md            ← from outline stage
├── supporting-docs.md            ← THIS skill writes: FAQ, environment setup, pre-reading
└── materials/                  ← THIS skill writes: standalone learner artifacts
    ├── README.md             ← index of materials
    └── *.md, *.csv, *.yaml   ← samples, templates, datasets

教材类型（按课程需要选择）

示例工作坊使用了以下类型——它们只是示例，并非必需项。请根据课程需求自行决定：

类型	格式	使用时机
讲稿	.md	每日教学叙述，嵌入 content.md
示例文档	.md	学习者将要改进的“改进前”材料（例如 FAQ、政策文档）
表格数据集	.csv（UTF-8 BOM！）	用于 AI 处理练习的实践数据
结构化配置	.yaml	练习涉及声明式配置时
PDF 参考资料	.pdf	官方文件（法律、法规）——通常来自外部来源
提示词模板	.md 块	特定领域的可复用提示词（本课程使用 RTFC 框架，其他课程未必适用——请根据课程教学法调整）
测验题目	嵌入 content.md 或单独存放	课前测验、课后测验、理解检查
工作表	.md	供学习者填写的模板

关于提示词模板：本技能不限定使用哪种提示词框架。原始工作坊使用了 RTFC（Role / Task / Format / Context），但如果课程教授其他框架（例如 CRISPE、COSTAR 或普通示例），就使用相应框架。不要在不适用的课程中强行使用 RTFC。该框架是课程内容的一部分，而不是本技能的属性。

CSV 注意事项（容易忽略）

生成供非开发人员学习者在 Excel 中打开的 CSV 文件时，请在文件开头添加 UTF-8 BOM（）：

const content = '' + headerRow + '\n' + dataRows.join('\n');

如果不添加，Windows 上的 Excel 可能会错误识别编码，导致乱码。学习者会以为文件已损坏。这个问题在示例工作坊后期才被发现——请从一开始就处理好。

为所有内容关联大纲 ID

每项产出都必须关联到一个 unit ID。在讲义中使用以下标题格式：

## u-3: {Unit title from outline.md}

**對應任務**: d2-u3-t1, d2-u3-t2
**對應素材**: 客訴處理SOP.md, FAQ官方版.md
**圖片需求 (illustrations)**:
- `day2-u3-hero.png` — hero / 主視覺：{學員角色} 在 {情境} 操作的場景圖（AI 生圖）
- `day2-u3-flow.svg` — 概念流程：{步驟 A → B → C}（手繪 SVG，含中文標籤）
- `day2-u3-example.png` — 結果範例截圖（選填）

{lecture content here}

原因：SPA 转换阶段会读取这些标记，自动关联任务、教材、内容，以及视觉素材占位符。如果省略这些标记，SPA 编写者就必须重新阅读所有内容才能弄清如何关联；而第 5 阶段（web-visual-assets）也没有可据以生成素材的规范——最终网站就只会有一张封面图。

任务 ID 一经发布，永久有效

在 content.md 中编写任务说明时，为每项任务分配一个稳定的 ID（例如 d2-u3-t1）。这些 ID 将成为已部署网站中的 localStorage 键。请遵循以下三条规则：

1. 永远不要重命名已发布任务的 ID。学生的进度与该 ID 关联。
2. 永远不要重复使用已删除任务的 ID。删除任务后，该 ID 永久停用。
3. 实际使用中有两种格式（d{n}-u{m}-t{k} 和 day{n}-u{m}-t{k}）。新内容请选择一种格式，不要混用。

测验题目规范

如果课程包含测验，请按顺序为题目编号（q1、q2……）。请注意，这些编号一旦进入 SPA，就会出现在多个地方：

• 测验数组本身
• qIndexToDay() 风格的辅助函数，用于将每道题映射到其来源章节（这样答错时就能链接回去）
• SPA 中的硬编码字符串："結訓測驗（N題）"、分数显示 — / N、及格阈值 s >= K

支持安全重新编号的编写方式：将测验视为只追加、不删改的内容。如果删除 q3，请在草稿中保留空位，只在最后稳定时刻重新编号，并列出所有需要更新的位置作为检查清单。

隐藏材料模式

某些材料仅供讲师使用（答案、前测／后测评分），或属于条件显示内容（仅在功能标志开启时显示）。请在 materials/README.md 中明确标记：

| 素材 | 對象 | 備註 |
|---|---|---|
| 員工差勤辦法.md | 學員 | Day 2 公開素材 |
| 結訓測驗解答.md | 講師 | 不要納入 SPA materials[]，僅講師端使用 |

SPA 转换阶段会读取此列，并排除仅供讲师使用的项目。

反模式

• 大纲尚未锁定就编写内容——每次回头修改都会波及多个文件。
• 嵌入课程实际并未教授的提示词框架——如果课程不使用 RTFC，就不要仅仅因为示例模板里有它而硬套。
• 测验题目没有来源章节映射——学习者答错时，需要知道该复习哪里。请为每道测验题标注其所属单元。
• 材料列表很长且没有区分讲师／学习者——到了第 4 天，讲师就不知道每个文件是什么了。
• 忘记 CSV BOM——见上文。

完成门槛（硬性规则——交接前必须通过）

在宣布“内容草稿已完成”并建议进行 static-spa-conversion 之前，以下每一项都必须在对应的 .md 文件中有书面材料（不能只口头说“是”）。请逐项引导用户完成；如果材料过于简略或缺失，请提出一个澄清问题，并在继续之前补齐。

1. 每一天都存在 content.md，且涵盖 overview.md 的 每日主題 表中声明的每一天。只有标题的日文件不合格——文件必须包含单元章节。
2. 每个大纲单元 ID 都有对应的 ## u-{id} 章节，且位于当天的 content.md 中。快速对照：day{n}/outline.md 中的单元 ID 列表必须是 day{n}/content.md 中 ## u- 标题列表的子集。缺少章节即不通过。
3. 每个单元章节都包含实质内容——至少满足以下一项：≥约 10 行的讲课稿、列出真实任务 ID 的 **對應任務**、列出真实材料文件名的 **對應素材**。只有标题和 TODO 占位符的单元不合格。
4. 每个单元章节都声明 **圖片需求 (illustrations)**，并包含 1–3 项。每项必须指定：(a) 文件名主体（例如 day2-u3-hero.png），(b) 图片类型（hero／diagram／screenshot／scene），(c) 给视觉资产作者的一行说明。确实不需要图片的单元，必须声明一行豁免说明：- waived: {reason, e.g. 5-min admin slot}。未作说明不合格。
5. 测验题目（如适用）必须标注 sourceUnit——每个 q* 题目都必须指向真实的单元 ID，以便答错时将学生引回来源章节。未标注的题目不合格。
6. 存在 materials/README.md，其中包含材料索引，并区分學員与講師两列（见上文“隐藏材料模式”）。

如果用户在所有项目都有书面材料之前催促“可以了，先转成网页”，请礼貌拒绝：

「Stage 2 還有 N 個單元沒寫實質內容（或沒設圖片需求）。直接進 Stage 3 會生出薄殼網頁，學員看到只有標題 + 沒插圖。先把第 X 項補上，大概 Y 分鐘，比之後重做網頁省好幾倍。」

如果用户明确要求制作精简演示（与 teaching-site 的 Stage 2 Override Policy 条件相同）：请按照 orchestrator 文档中的三个步骤（标注 stub 注释、设置 __thinDemo: true、明确告知学员显示效果）后再放行，不要在 Stage 2 内部暗中放宽要求。

交接

此阶段完成后（通过 Completion Gate），你应当拥有：

• 已填写的每日 content.md，大纲中的每个单元 ID 都对应一个 ## u-{id} 章节
• 每个单元章节：讲稿 + 任务 + 材料引用 + 1–3 条 圖片需求 (illustrations)
• materials/ 中的所有材料文件，以及一份区分学员 / 讲师材料的索引 README
• 测验草稿（如适用），编号为 q1..qN，并带有 sourceUnit 源章节标签
• 每项产出都可追溯到一个大纲单元 ID

告诉用户：“内容草稿已完成。下一阶段（static-spa-conversion）会将其转换为 course-data.js + index.html，并为每个单元添加一个 illustrations: [] 数组，该数组根据你的 圖片需求 区块生成。Stage 3/4 之后，web-visual-assets 会填充这些位置——你的规格行将作为它的提示词输入。从现在起，不要更改单元 ID 或任务 ID——它们将成为 localStorage 键。”