制作课程

一门课由配置文件 + 源码快照组成，学生输入课程配置文件的 URL 后，即可打开课程。

快速创建课程

哪怕不清楚课程配置文件需要填写什么信息，你也可以通过本插件提供的 skill 和 AI Agent 来快速生成课程配置文件。

1. 先在 IDE 中打开存放源码快照的文件夹（命令在未打开文件夹时不可用；也不在 Learn By Diff 视图上）。
2. 打开命令面板，运行 LearnByDiff: 安装生成课程 Skill。扩展会在该文件夹安装 课程生成 Skill，并把一段可粘贴的 /generate-course-config 提示词复制到剪贴板。
3. 把提示词贴进 Agent 对话，按需改写其中的占位路径后发送即可生成课程配置：

Snapshot path: ./path/to/chapter/code/root/folder
Target folder: /absolute/path/to/course-config

也可以不经过扩展命令，在快照目录里手动执行：

npx skills add RJiazhen/learn-by-diff@generate-course-config -y

然后再运行 /generate-course-config。

或者在运行时提供源代码的 GitHub 仓库地址，Agent 也会自动去读取源代码并生成课程配置文件。

课程配置文件

每个课程都需要一个课程配置文件 course.jsonc，以及对应的章节配置文件 chapters/*.jsonc。

course.jsonc

首先在你的课程仓库中新建一个 course.jsonc 文件，并粘贴以下内容：

{
  "$schema": "https://raw.githubusercontent.com/RJiazhen/learn-by-diff/refs/heads/main/packages/protocol/schema.json#/$defs/course",
  "id": "demo-course",
  "title": "测试课程",
  "source": {
    "repository": "https://github.com/RJiazhen/learn-by-diff.git",
    "root": "examples/demo-source",
  },
  "chaptersDir": "chapters",
}

一个 course.jsonc 文件中可以包含以下字段：

• id(可选)：课程的稳定标识，也会用作学生本地学习目录的文件夹名。改成适合当路径的 slug（建议只用字母、数字、连字符）。不写则用课程所在文件夹名；若该目录是 git 仓库根，则为 {仓库名}-learn。
• title(可选)：课程显示名。改成给人看的名称即可。默认值为 id。
• source.repository(可选)：源码所在位置，允许以下三种写法：
  • git 仓库地址：例如 https://github.com/org/repo.git，代表源码所属的 git 仓库；
  • 本地路径：本机上的源码目录，可以是绝对路径，也可以是相对于 course.jsonc 所在目录的相对路径；
  • 默认值：空，表示源码就在 course.jsonc 所在目录。
• source.root(可选)：源码在 source.repository 中的相对路径，默认值为空，表示源码就在 source.repository 的根目录。
• chaptersDir(可选)：章节 JSONC 所在目录，相对 course.jsonc 文件的地址。默认值为 chapters，即章节配置文件就在 course.jsonc 所在目录的 chapters 目录下。
• retain(可选)：切换章节快照时留下的路径，写法与 .gitignore 相同（从学习目录根匹配；node_modules 会保留任意位置的同名目录）。省略时为 node_modules。写成 [] 则不额外保留项目路径。工作区 .gitignore 不控制这项。详见 保留文件。

chapters/*.jsonc

在 course.jsonc 所在目录下新建一个 chapters 目录，并在该目录下新建一个 00-start.jsonc 文件，并粘贴以下内容：

{
  "$schema": "https://raw.githubusercontent.com/RJiazhen/learn-by-diff/refs/heads/main/packages/protocol/schema.json#/$defs/chapter",
  "id": "start",
  "title": "开始",
  "fromDir": "start",
  "toDir": "skeleton",
  "entryFiles": ["src/main.js"],
  "docs": "README.md",
}

首先，章节配置文件需要放在 chaptersDir 目录下（默认是 course.jsonc 旁边的 chapters/）。

每一个 .jsonc 文件对应一章，课程顺序和文件名顺序一致，所以建议用数字前缀排课，例如 00-start.jsonc、01-skeleton.jsonc。

同时，当章节配置文件中的 id 为空时，会去掉扩展名和开头的数字前缀作为 id，例如 00-start.jsonc → start。前缀可以是 00-、01_、1. 这种形式。一门课至少要有一个章节文件，各章 id 不能重复。

每个章节配置文件中，包含以下字段：

• id(可选)：章节的稳定标识，进度记录用它，不用于显示。默认为空，此时会从文件名推导（如上，00-start.jsonc → start）。
• title(可选)：章节显示名。默认为空，此时会用 id。
• fromDir(可选)：本章开始时的源码快照目录，相对 source.repository（若写了 source.root，则相对那一层）。默认值为空，表示空目录。不允许 .. 或绝对路径。
• toDir(可选)：本章目标快照目录，相对规则同 fromDir。默认值为空，表示空目录。
• entryFiles(可选)：本章要关注的文件列表，路径相对章节快照树根（toDir）。默认值为所有 toDir 下的文件。
• changedFiles(可选)：从 fromDir 到 toDir 的文件差异（path 加上 U 新增、M 修改、D 删除）。填写后打开课程时不必再对比快照。不写则运行时分类；空列表表示本章没有变化。generate-course-config 脚手架会自动填写。
• docs(可选)：本章文档。可以是 http(s) URL，也可以是快照树里的文件路径（先找 toDir，再找 fromDir），例如 README.md。默认值为空，表示没有文档按钮。

更多详细配置说明见 课程配置。

分享制作好的课程

按照以下步骤将制作好的课程分享给他人：

上传课程仓库到 Git

首先保证课程仓库（包括源代码）已经发布到 Git。

分享课程配置文件地址

如果是托管在 GitHub 上，则可以直接分享 course.jsonc 的地址，对方在 Open Course 里粘贴即可。

例如：

https://github.com/RJiazhen/learn-by-diff/blob/main/packages/courses-config/demo-course/.course-config/course.jsonc

如果课程配置文件是直接放在仓库根目录下，或在根目录的 .course-config/course.jsonc 时，则可以直接分享仓库 git 地址 URL：

https://github.com/RJiazhen/learn-by-diff.git

如果课程配置文件在仓库的子目录下，用 git 地址加 # 再拼上相对路径（相对仓库根，指向 course.jsonc）：

https://github.com/RJiazhen/learn-by-diff.git#packages/courses-config/demo-course/.course-config/course.jsonc

生成一键分享链接

或者可以按照以下规则，将课程配置文件的地址转换为一键分享链接，他人点击链接即可打开课程（会唤醒 IDE 并自动打开课程）。

vscode://RuanJiazhen.learn-by-diff/open?url=<course.jsonc地址或git仓库URL>
cursor://RuanJiazhen.learn-by-diff/open?url=<course.jsonc地址或git仓库URL>

VS Code 用 vscode://，Cursor 用 cursor://。对方需要已安装 LearnByDiff；首次点击时系统可能会询问是否允许打开该协议。

例如仓库 https://github.com/RJiazhen/learn-by-diff.git：

vscode://RuanJiazhen.learn-by-diff/open?url=https://github.com/RJiazhen/learn-by-diff.git
cursor://RuanJiazhen.learn-by-diff/open?url=https://github.com/RJiazhen/learn-by-diff.git