利用 YouTube 评论讨论查找教程中的不足

收集有明确范围的评论样本

公开评论程序版本 1.1.6 接受已知的公开视频地址或视频 id。你可以在 `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`。使用收集评论时所用的同 1 个教程。替换整个 `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. 解读样本前，先核查样本。确认视频 id、每个 `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 项技能：学习者测量托盘，并使用同一种单位。虚构的字幕片段如下：

[
  {
    "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`。不要编造当前片段存在的问题，也不要为解答另一种型号的问题而修改本教程。

统计这个故事中的记录。`possible_wording_gap` 有 1 条，`explanation_present_question_unresolved` 有 1 条，`unresolved` 有 1 条，`setup_mismatch` 有 1 条。总共是 4 条评论记录。1 条记录不等于 1 名身份已核实的人。故事没有说明有多少人观看，也没有说明每位观众都遇到了同样的问题。字幕时间只帮助你找到片段，不能代替观看画面和听讲解。