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

修改教學影片前，先將 1 則觀眾留言與確切的教學片段對照。閱讀公開回覆，聆聽教學講解，也要觀看畫面。然後記錄你的發現。教學內容可能漏了某項解釋，也可能已經說明該重點。又或者，已核對的事實太少，未足以判斷。

教學不足是指欠缺解釋、用詞不清，或觀眾使用的設定與教學內容不符。教學不足對照表由多行記錄組成。每行將 1 則留言與教學內容、判斷及測試連結起來。

使用 [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper) Actor 收集公開留言。Actor 是在託管環境中執行、用來收集來源資料記錄的程式。Task 是已儲存的輸入預設。公開的[影片留言分析 Task](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis) 只是一組起始輸入設定，不能證明檢查會自行完成。Actor 不會判斷教學內容。這項工作由你負責。

這些限制適用於 2026-10-13 核查過的公開建置版本。之後的版本可能有變。請閱讀你所用版本的執行輸出。

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

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

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

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

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

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

```json
{
  "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。

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

在筆記中保留[來源排序方式及上限](/zh-Hant/articles/youtube-%E7%95%99%E8%A8%80%E7%86%B1%E9%96%80%E8%88%87%E6%9C%80%E6%96%B0%E6%8E%92%E5%BA%8F%E6%8A%BD%E6%A8%A3/)。上限會選出一個小樣本，並不會按教學問題的嚴重程度排序。你的影片傳回的組合，可能不是 1 行 Top 和 1 行 Newest。

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

| 欄位 | 含義 |
| --- | --- |
| `videoId` | 影片的公開識別碼 |
| `videoUrl` | 公開影片連結 |
| `commentId` | 留言的公開識別碼 |
| `sortMode` | 該行的排序模式：Top 或 Newest |
| `text` | 留言文字 |
| `authorChannelId` | 留言者的公開頻道識別碼，前提是來源有提供 |
| `publishedTimeText` | 留言旁顯示的時間文字，如有提供 |
| `publishedAt` | 日期與時間。null 表示未知，不是 0 |
| `scrapedAt` | 收集該行記錄的時間 |
| `status` | 該行記錄的處理結果 |

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

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

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

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

```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. 在影片時間軸上找出相關教學片段。利用附時間的字幕[找出可能相關的時段](/zh-Hant/articles/%E9%95%B7%E7%AF%87-youtube-%E8%AA%B2%E5%A0%82%E5%BD%B1%E7%89%87-%E6%A6%82%E5%BF%B5%E6%9F%A5%E6%89%BE/)。然後播放該時段。以影片秒數記錄開始和結束時間。記錄概念、較早出現而又相關的一句話，以及畫面中的動作。先觀看並聆聽，再作判斷。字幕缺少的一句話，仍可能透過圖解清楚表達。字幕出現某個詞語，不能證明口述內容清楚或正確。請使用影片播放時間，不要使用牆上時鐘的時間。
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 種單位。虛構的字幕分段如下：

```json
[
  {
    "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。留言文字：「我應該量度托盤外側嗎？」 | 沿內邊緣量度寬度。 | 你已開啟討論串。回覆指出，觀眾量度的是外緣。 | 第 20–28 秒。口述內容：「量度托盤內邊緣之間的寬度。」間尺從左側內邊緣開始。口述內容沒有將內邊緣與外緣作對比。 | `possible_wording_gap` | 在第 20 秒展示內外 2 個邊緣，標示內邊緣，並說明不包括外緣。 | 審核者只看新片段，無需閱讀留言討論串，也能準確指出量度的起點邊緣和終點邊緣。 |
| 虛構園藝教學影片中的 C2。留言文字：「我可以混用英吋和厘米嗎？」 | 2 個尺寸均使用同一種單位。 | 已核查的回覆中，沒有任何內容指出這名觀眾錯過了有關單位的句子。 | 第 28–33 秒。口述內容：「2 個尺寸都使用厘米。」 | `explanation_present_question_unresolved` | 僅屬可選修改：在第 28 秒附近加上可見的單位標籤或簡短重點回顧。保留原句。不要將教學內容改寫得像原本沒有說明這項規則一樣。 | 審核者仍能在第 28–33 秒找到原本說明單位的句子。不能單憑該問題，就認定觀眾錯過了解釋。 |
| 虛構園藝教學影片中的 C3。留言文字：「按鈕不見了。」 | 尋找按鈕。留言沒有提供裝置或版本。 | 沒有可供核查的回覆。裝置和版本仍屬未知。 | 無法取得。相關片段時間未知。不要編造。 | `unresolved` | 不修改教學內容。 | 該行記錄維持未解決。審核者不會自行加入裝置、版本、原因或片段時間。 |
| 虛構園藝教學影片中的 C4。留言詢問的是另一款產品型號。 | 這段影片所教型號的操作步驟。 | 你已開啟討論串。回覆確認留言涉及另一款型號。 | 不將目前的教學內容視為問題成因，也不指定片段時間。 | `setup_mismatch` | 不修改這段教學內容。註明留言提到另一款型號。 | 審核者能在已核查的回覆中看到另一款型號，因此保留這段教學的原有步驟。 |

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 名已核實的人。故事沒有說明有多少人觀看，也沒有說明每名觀眾都有同樣問題。字幕時間只用來幫你找到片段，不能取代觀看畫面和聆聽講解。

## 下一步

選擇 1 則說明具體疑惑的留言。播放相關影片時段並觀看畫面，不要只看字幕文字。記錄 1 項建議修改，以及另一人可以重複進行的測試。透過 [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper) Actor 取得留言記錄。在[影片留言分析 Task](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis) 中填入你自己的教學影片。Actor 只會收集記錄。片段仍由你判斷。

## 來源與延伸閱讀

- [YouTube Comments Scraper Actor](https://apify.com/chronometrica/youtube-comments-scraper)
- [影片留言分析 Task](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis)
- [附時間標記的逐字稿 Task](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-timestamped-transcript-json)
- [如何分析你的 YouTube 觀眾](https://www.reddit.com/r/YouTubeCreators/comments/1tdvbvx/how_do_you_analyze_your_youtube_audience_across/)