製作課程

一門課由設定檔 + 原始碼快照組成，學生輸入課程設定檔的 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。預設為空，表示沒有文件按鈕。

保留檔案

切換章節時，retain 使用與 .gitignore 相同的規則留下路徑。省略 retain 時保留任意位置的 node_modules。寫法見 保留檔案。

分享製作好的課程

依下列步驟將課程分享給他人：

上傳課程倉庫到 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 位址：

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