利用 YouTube 留言討論串找出教學影片的不足

收集有明確範圍的留言樣本

公開留言建置版本 1.1.6 接受已知的公開影片網址或影片識別碼。你可在 `startUrls` 提交 1 至 100 個網址。將 `maxCommentsPerVideo` 設為 1 至 1,000。這個數字是上限，即你要求收集的頂層留言最高數量。頂層留言是指不屬於回覆的留言。將 `commentSortMode` 設為 `top`、`newest` 或 `both`。Top 指 YouTube 排在最前的留言。Newest 指最新留言。開啟或關閉 `includeReplies`。開啟回覆時，`maxRepliesPerComment` 接受 1 至 100。回覆是頂層留言下的回應。回覆記錄會額外計算，不佔用頂層留言上限。

已儲存的 Task 仍然使用一段歌曲示範影片，上限為 250，已開啟回覆，最多收集 10 則回覆。判斷教學影片前，請先換掉這段示範影片。

{
  "startUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "maxCommentsPerVideo": 250,
  "commentSortMode": "both",
  "includeReplies": true,
  "maxRepliesPerComment": 10
}

首次檢查時，使用 1 段你已確定為公開的教學影片。將上限設為 2。將 `commentSortMode` 設為 `both`。將 `includeReplies` 設為 false。不要保留舊的回覆上限設定。

{
  "startUrls": ["https://www.youtube.com/watch?v=YOUR_TUTORIAL"],
  "maxCommentsPerVideo": 2,
  "commentSortMode": "both",
  "includeReplies": false
}

另一次小規模對照檢查使用了 1 段教育影片，上限為 2，並使用了 2 種排序模式。該次檢查寫入了 2 則有文字的頂層留言。1 行為 Top，另 1 行為 Newest。每行都有 `commentId`。`publishedAt` 為 null。OUTPUT 顯示 `commentsWritten` 為 2，`repliesWritten` 為 0。`stopReasonCounts` 包含 `requested_comment_limit_reached`。不要尋找單一的 `stopReason` 欄位。

`commentsWritten` 為 2，表示儲存了 2 行留言記錄。`repliesWritten` 為 0，表示儲存了 0 行回覆記錄。這個 0 是該次執行的計數。`publishedAt` 為 null，表示來源沒有提供日期。未知不等於 0。不要將空白日期儲存為 0。

這次對照檢查不能證明能匯出回覆。驗收測試沒有涵蓋自動收集回覆。這個方法不會將該檔案視為重建完成的討論串。如果回覆可能改變意思，請開啟公開影片觀看頁面並閱讀回覆。如果找不到回覆，就保留為缺失。不要編造文字。

在筆記中保留來源排序方式及上限。上限會選出一個小樣本，並不會按教學問題的嚴重程度排序。你的影片傳回的組合，可能不是 1 行 Top 和 1 行 Newest。

每行留言記錄應包含以下欄位：

如果某項輸入無法存取，OUTPUT 會說明。判斷一行記錄前，先閱讀 `status`。如果缺少文字，請將該行另行保留。不要補寫文字。如果缺少 `authorChannelId`，留言者便屬未知。不要編造一個人。缺少留言者資料，不代表觀眾數為 0。

留言數不等於學習者人數，也不是衡量理解程度的分數。如果沒有寫入任何留言，`commentsWritten` 就是 0。這個 0 表示你沒有留言樣本，不代表觀眾理解了教學內容。不要將樣本轉換成情緒分數。

收集同一段教學影片的附時間字幕

公開逐字稿建置版本 0.1.43 接受已知的 `startUrls`、`preferredLanguages` 及 `outputFormats`。使用你收集留言時所用的同一段教學影片。替換整份 `startUrls` 清單。不要在清單中保留歌曲示範影片。需要附時間的字幕分段時，請要求輸出 `json`。一個分段就是一段附有時間的字幕。

{
  "startUrls": ["https://www.youtube.com/watch?v=YOUR_TUTORIAL"],
  "preferredLanguages": ["en"],
  "outputFormats": ["json"]
}

`preferredLanguages` 是偏好設定。範例使用 `en` 代表英語。如果你偏好其他字幕語言，請更改此設定。這個欄位不會翻譯教學內容。

針對同一段教育影片進行的逐字稿對照檢查成功了。它傳回了一條內容非空的英語人工字幕軌，以及附時間的字幕分段。人工字幕軌是由人製作的字幕檔案。這次對照檢查顯示，只要字幕軌存在，這個建置版本便能傳回字幕文字及時間資料。這不能證明你的影片有字幕。本文沒有抄錄真實字幕的文字。

使用公開分段欄位 `startSeconds`、`endSeconds`、`durationSeconds` 及 `text`。從分段讀取 `endSeconds`。如果有 `durationSeconds`，將 `startSeconds` 與 `durationSeconds` 相加。總和所代表的時間範圍應與 `endSeconds` 一致。如果缺少 `durationSeconds`，就保留為未知。不要填寫 0。

字幕可能有錯，也可能略過圖解或無聲動作。字幕中缺少某項內容，不能證明畫面沒有呈現該重點。如果沒有字幕軌，請觀看並聆聽影片。不要編造字幕文字。逐字稿 Actor 不會閱讀留言，不會分配教學不足分類標籤，也不能證明學習者未能理解。

按 8 個步驟進行檢查

1. 收集留言前，先寫明教學目標。用 1 句淺白文字寫出概念。寫出學習者完成教學後應能做到甚麼。選擇 1 段公開教學影片。閱讀留言前，先訂明上限。首次檢查的上限為 2。只根據觀眾實際寫出的內容判斷。不要猜測年齡、技能或動機。
2. 解讀樣本前，先檢查樣本。確認影片識別碼、每個 `commentId`，以及 `text` 是否可用。閱讀 OUTPUT，包括 `commentsWritten`、`repliesWritten` 及 `stopReasonCounts`。在筆記中清楚保留來源排序方式及上限。將缺失的留言者資料或值為 null 的 `publishedAt` 標示為未知。不要將未知轉換為 0。2 行記錄就是樣本中的 2 則留言，不是 2 名學習者，也不是全班的成績。
3. 選擇 1 則提到具體任務或具體疑惑的留言。保留來源連結。只引用你自己的筆記所需的文字。用淺白文字寫出解讀，不要自行加入原因。單憑一個問題，不能視為理解有誤。單憑笑話、不同意見或重複用語，也不能視為理解有誤。判斷教學內容前，先為筆記加上 `stated_confusion`、`possible_gap` 或 `insufficient_context` 標籤。`stated_confusion` 表示留言指出了具體任務或問題。`possible_gap` 表示文字可能指向教學問題，但你尚未核對相關片段。`insufficient_context` 表示留言缺少你需要的某項事實。
4. 如果回覆可能改變意思，請閱讀公開討論串。開啟影片頁面，閱讀該留言下的回覆。回覆可能說明觀眾使用的設定，也可能顯示問題來自另一款產品。記錄你核查過甚麼，也記錄哪些內容無法開啟。小規模對照檢查沒有儲存任何回覆。不要將匯出檔案描述為完整討論串。如果找不到回覆，請註明無法取得回覆的背景資料。不要寫出你沒有讀過的回覆。
5. 在影片時間軸上找出相關教學片段。利用附時間的字幕找出可能相關的時段。然後播放該時段。以影片秒數記錄開始和結束時間。記錄概念、較早出現而又相關的一句話，以及畫面中的動作。先觀看並聆聽，再作判斷。字幕缺少的一句話，仍可能透過圖解清楚表達。字幕出現某個詞語，不能證明口述內容清楚或正確。請使用影片播放時間，不要使用牆上時鐘的時間。
6. 將留言與已核查的教學內容比較。先問 3 個問題：教學內容有沒有漏了這項解釋？教學內容是否已經說明該重點？還是仍然缺少某項所需事實？然後儲存 1 個狀態。證據包括留言、你開啟過的回覆，以及你觀看過的片段。`explanation_missing` 表示該片段沒有教授觀眾所問的重點。`explanation_present_question_unresolved` 表示該片段已說明重點，而你核查過的內容沒有顯示這名觀眾錯過了該說明。之後提出問題，不能證明他錯過了說明。不要說教師教學失敗。除非已核查的回覆顯示觀眾確實錯過了說明，否則請使用這個狀態。`possible_wording_gap` 表示教學內容展示了重點，但講解從未將正確做法與觀眾的錯誤作對比。`setup_mismatch` 表示留言涉及不同的設定、產品或型號。`unresolved` 表示某項所需事實尚未核查，因此你不指出原因。將證據儲存在狀態旁邊。1 則表達疑惑的留言，不能顯示每名觀眾都有同樣問題。
7. 只有在證據支持修改教學內容時，才寫出 1 項修改。你可以補充先備知識、展示 1 個解題步驟、說明單位、放慢跳躍較大的講解，或在該片段旁加上簡短重點回顧。先備知識是學習者需要先知道的事實。說明甚麼內容應變得更清楚，並說明測試方法。不要承諾觀眾會觀看更久，也不要承諾增加觀看次數。修改該片段的解釋。修改選單或總結整段影片，是另一項工作。如果狀態是 `unresolved` 或 `setup_mismatch`，不要勉強修改這段教學內容。
8. 儲存 1 行可供另一人審核的教學不足記錄。包括留言及討論串來源、已核查的背景資料、片段時間、預期教授的概念、狀態、建議修改及驗收檢查。驗收檢查是一項測試，用來顯示修改達到目的，或沒有充分理由作出修改。另一人應能開啟相同來源，並理解判斷過程。如果缺少背景資料，該行記錄應維持 `unresolved`。不要編造確切原因。

研讀一份虛構的教學不足對照表

本節的園藝教學、留言、回覆及時間均屬原創虛構內容，僅用作教學範例。它們不是 Actor 輸出，也不是產品成果。

這段虛構教學教授 1 項技能：學習者量度托盤，並統一使用 1 種單位。虛構的字幕分段如下：

[
  {
    "startSeconds": 20,
    "endSeconds": 28,
    "durationSeconds": 8,
    "text": "Measure the width inside the tray edges"
  },
  {
    "startSeconds": 28,
    "endSeconds": 33,
    "durationSeconds": 5,
    "text": "Use centimeters for both dimensions."
  }
]

用簡單加法核對第 1 個時段。20 加 8 等於 28，與 `endSeconds` 相符。再核對第 2 個時段。28 加 5 等於 33，與 `endSeconds` 相符。這些加法只確認虛構的時間資料，並不判斷教學內容。

字幕文字沒有提到間尺。在這個故事中，你播放第 20–28 秒並觀看畫面。間尺從左側內邊緣開始。你是因為看過畫面才知道這一點。字幕沒有提到間尺，不代表畫面一片空白。字幕文字也不能證明口述內容已足夠。

外緣是托盤外側的邊框。教學內容展示了內邊緣，卻從未說明不應包括外緣。

C1 起初標示為 `stated_confusion`，因為它提出了一個具體的量度問題。該片段已說明應在托盤內邊緣之間量度。畫面也與說明一致，因為間尺從左側內邊緣開始。解釋並非不存在，因此狀態不是 `explanation_missing`。已核查的回覆指出，觀眾使用了外緣。教學內容從未將外緣與內邊緣作對比。因此，合適的狀態是 `possible_wording_gap`。回覆沒有說明觀眾為何選擇外緣。不要編造動機。修改是在第 20 秒直接作出對比。測試只使用新的畫面和新的句子。

C2 起初也標示為 `stated_confusion`。第 28–33 秒的句子已經給出規則：2 個尺寸都使用厘米。已核查的討論串沒有任何內容顯示這名觀眾錯過了該句。清楚說明後有人提問，不能證明對方錯過了說明。狀態是 `explanation_present_question_unresolved`。單位標籤可能有助之後的觀眾看見這項規則。這項修改並非必須，也不得取代原句，或假裝原本沒有說明規則。

尋找片段前，C3 屬於 `insufficient_context`。「按鈕不見了」沒有提供裝置或版本。也沒有回覆補充這些事實。你無法選定影片時間，也無法指出原因。未知的背景資料應保留為未知。狀態維持 `unresolved`，而驗收檢查不允許勉強作出修改。

C4 起初是一個具體問題，因此核查討論串前，你可以標示為 `stated_confusion`。已核查的回覆指出，該型號並非這段教學使用的型號。因此，狀態改為 `setup_mismatch`。不要編造目前片段的缺失，也不要為了解答另一款型號的問題而修改這段教學。

數一數故事中的記錄行數。1 行是 `possible_wording_gap`，1 行是 `explanation_present_question_unresolved`，1 行是 `unresolved`，1 行是 `setup_mismatch`。合共 4 行留言記錄。1 行記錄不等於 1 名已核實的人。故事沒有說明有多少人觀看，也沒有說明每名觀眾都有同樣問題。字幕時間只用來幫你找到片段，不能取代觀看畫面和聆聽講解。