generate-course-materials

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate exercode course materials

生成 Exercode 课程材料

Read these references before authoring any file:

references/course-format.md — course directory layout,
```
course.yaml
```
, and material frontmatter schemas.
references/material-authoring.md — pedagogical writing rules for lecture materials.
references/question-authoring.md — how to write embedded quiz questions.

Confirm the course parameters with the user: topic, target audience, number of lectures, target programming language(s), and the output directory. If any are missing, ask before generating when the user is available; otherwise choose reasonable values from the context and list them as open decisions in the final report.
Write an outline first: a nested markdown bullet list covering all lectures, each bullet ending with a one-line summary. Show it to the user for approval when the user is available; otherwise proceed with your best outline.
Create the course directory structure per references/course-format.md:
- ```
<courseId>/course.yaml
```
  listing every lecture (
```
id
```
  ,
```
name
```
  ,
```
description
```
  ).
- One
```
<courseId>/<lectureId>/
```
  directory per lecture. Prefix lecture IDs with zero-padded sequence numbers in course order (
```
01_
```
  ,
```
02_
```
  , ...), followed by a descriptive name.
- Course-scoped coding problems under
```
<courseId>/problems/<problemId>/
```
  .
Write markdown material files inside each lecture directory, prefixing them with zero-padded sequence numbers that restart at
```
01_
```
in every lecture (
```
01_
```
,
```
02_
```
, ...), following references/material-authoring.md. Write material bodies in Japanese unless the user requests another language.
Embed quiz questions in the material bodies as fenced
```
yaml question
```
blocks per references/question-authoring.md. Insert questions right after each newly introduced concept, not in a batch at the end.
Decide whether writing, modifying, or executing code is part of the course's learning objective. If it is, create one or more course-scoped Judge problems at meaningful checkpoints with generate-judge-problems. Each problem must require learners to apply concepts already introduced in the course; embedded questions and complete code examples do not satisfy this requirement. Link each problem near its prerequisite material as
```
[表示名](problems/<problemId>)
```
. Every linked problem directory must exist under the same course's
```
problems/
```
directory. For a course without executable coding objectives, create Judge problems only when the request requires them. Never reference another course's problems.
Validate with the
```
exercode-problem
```
CLI (it ships with
```
@exercode/problem-utils
```
, which must be a declared repository dependency — see setup-exercode-course-repository) and fix until clean:
bash
```
bunx exercode-problem validate-course <courseDir> --problems-dir <problemsDir>
```
For a course without Judge problems, omit
```
--problems-dir
```
(an explicitly given directory must exist); the validator then resolves problem references against the problems inside the course directory, so a dangling reference is an error. Fix every reported error and rerun. Repeat until the command reports success. Address warnings too unless they are intentional; if you keep a warning, tell the user why in the final report.
Report the created course directory, the lecture list, and any open decisions (e.g., outline items you chose without user confirmation, intentionally kept warnings).

编写任何文件前，请先阅读以下参考资料：

references/course-format.md — 课程目录布局、
```
course.yaml
```
以及材料 frontmatter schema。
references/material-authoring.md — 讲义材料的教学写作规则。
references/question-authoring.md — 如何编写嵌入式测验问题。

与用户确认课程参数：主题、目标受众、讲义数量、目标编程语言和输出目录。如果缺少任何参数，且可以与用户沟通，请在生成前询问；否则根据上下文选择合理值，并在最终报告中将其列为待决事项。
先编写大纲：使用嵌套 Markdown 列表覆盖所有讲义，每个列表项末尾附上一行摘要。如果可以与用户沟通，请将大纲展示给用户审批；否则按照最佳大纲继续执行。
按照 references/course-format.md 创建课程目录结构：
- ```
<courseId>/course.yaml
```
  ，列出所有讲义（
```
id
```
  、
```
name
```
  、
```
description
```
  ）。
- 每份讲义对应一个
```
<courseId>/<lectureId>/
```
  目录。讲义 ID 按课程顺序添加补零的序号前缀（
```
01_
```
  、
```
02_
```
  ……），后接描述性名称。
- 课程范围内的编程题放在
```
<courseId>/problems/<problemId>/
```
  下。
在每个讲义目录内编写 Markdown 材料文件，文件名前缀使用从
```
01_
```
重新开始的补零序号（
```
01_
```
、
```
02_
```
……），并遵循 references/material-authoring.md。除非用户要求使用其他语言，否则材料正文使用日语编写。
按照 references/question-authoring.md 将测验问题嵌入材料正文，使用围栏式
```
yaml question
```
代码块。每引入一个新概念后立即插入问题，不要集中放在末尾。
判断编写、修改或执行代码是否属于课程的学习目标。如果是，则在有意义的阶段检查点创建一个或多个课程范围内的 Judge 题目，使用 generate-judge-problems。每道题都必须要求学习者应用课程中已经介绍的概念；嵌入式问题和完整代码示例不能满足这一要求。将每道题链接到其相关前置材料附近，格式为
```
[显示名称](problems/<problemId>)
```
。每个被链接的题目目录都必须存在于同一课程的
```
problems/
```
目录下。对于不包含可执行代码学习目标的课程，仅在用户要求时创建 Judge 题目。绝不引用其他课程的题目。
使用
```
exercode-problem
```
CLI 进行验证（该 CLI 随
```
@exercode/problem-utils
```
一起提供；后者必须声明为仓库依赖项，参见 setup-exercode-course-repository），并持续修复直至通过：
bash
```
bunx exercode-problem validate-course <courseDir> --problems-dir <problemsDir>
```
对于不含 Judge 题目的课程，省略
```
--problems-dir
```
（如果显式提供目录，该目录必须存在）；此时验证器会根据课程目录内的题目解析题目引用，因此悬空引用会报错。修复每个报告的错误并重新运行。重复此操作，直到命令报告成功。除非警告是有意保留的，否则也应处理警告；如果保留警告，请在最终报告中说明原因。
报告已创建的课程目录、讲义列表以及所有待决事项（例如，未经用户确认而自行选定的大纲项，以及有意保留的警告）。