learning-scout

把“我想学 X”变成一组能读进去的笔记 + 一个能反复打开的入口。

交付物不是一个漂亮页面，而是：

<workspace>/
  index.html          # 入口：篇目、进度、视频、动手任务、复习卡
  print.html          # 全部篇目合并的打印/导出页
  plan.json           # 计划源文件
  README.md           # 篇目与路径清单
  notes/
    01-xxx.md         # 原文：独立成篇，可导入知识库或直接发布到博客/公众号
    01-xxx.html       # 渲染页：带目录、视频、自测
    02-xxx.md
    02-xxx.html

判断这次做到没做到，用一句话：读者能不能只靠这一篇理解本篇目标，不需要回看同系列其他篇？ 不要求每篇把前置知识补全；用不到的基础可以省略。

先定四件事

尽量从上下文推断；缺什么问什么，不要审问：

1. 想达到什么结果？（能做什么，而不是“学会”）
2. 现在什么水平？（新手 / 会一点 / 想进阶）
3. 有多少时间？（30 分钟 / 一周 / 一个月）
4. 偏好什么形式？（中文/英文、文档/视频/动手）

用户不回答就写明假设，先给一版可调整的。

一、研究：先找证据，再找视频

用可用的搜索、抓取和官方文档工具并行找：

• 官方文档、规范、原始论文、维护者文章
• 一线工程博客、生产复盘、会议演讲
• 可运行 repo、lab、课程练习
• 中文资料，单独标注来源层级
• 视频：只从官方频道、会议频道、作者本人或可信课程找

规则：

• 主路线优先一手 + 实践来源；社区文章只做补充。
• 每个主资源写一句“为什么是它”；写不出来就不要放。
• 至少核验标题、URL、作者/频道、日期、语言、时长、收费与地区限制。
• 没完整看过的视频，只写“元数据核验”，不评价讲得好不好。
• 不用内容农场、翻译农场、无作者 SEO 聚合页作为主来源。

来源分层与平台池见 来源质量，视频的核验与内嵌规则见 视频。

研究阶段就要把视频链接和元数据收集齐，不要等写完笔记再补——补的时候通常只会补标题。

二、设计系列：一篇一个目标

先交大纲，再写正文。 超过 4 篇的系列，先给出每篇的 id / 标题 / goal / kind / 预计行数 清单，让使用者确认方向；确认后再逐篇写。这样可以避免八篇写完才发现主线偏了。

系列通常 4–10 篇；短计划 2–3 篇，系统学习 8–12 篇。每篇只回答一个问题。

好的顺序不是章节目录：

先看到一次真实失败 → 建立最小闭环 → 补关键机制 → 做一次真实迭代

每篇必须独立成篇：不引用同系列其他篇，不假设读者读过前一篇。导航由 index.html 负责。 独立性指不依赖其他篇，不是从零讲起；用不到的前置知识不必补。

详细节奏与拆篇方法见 学习设计；每类笔记的起步骨架见 笔记骨架。

三、写笔记：按深度规范来

每篇的默认结构、示例标准、源码要求，按 笔记深度规范； 写什么、覆盖哪些概念按 内容质量；frontmatter 键、编号章节与 参考资料收尾按 成文风格。 摘要版：

长度看内容，不凑行数：主题窄可以更短，材料多可以更长；偏离参考区间时， 说明是“主题窄”还是“缺了示例/失败模式/边界”。

默认检查项：开场故障或问题（结尾回收）、完整示例、故障矩阵、三条边界或反例、 版本敏感点、核验声明。它们不是每篇必须凑齐的模板；主题窄或没有对应场景时， 可以省略并说明原因，不为结构注水。核验声明保留，用来说明依据和未验证部分。

写作纪律：

• 示例里的人名、路径、密钥、主机名用占位符，不写自己的环境。
• 代码与配置标 tested / illustrative / pseudo；没跑过就写清楚。
• 外部事实带版本与日期；源码结论带文件与行号。
• 不写“众所周知”“显然”“性能更好”这类无依据判断。
• 不引用同系列其他篇，不把“去看这篇”当讲解；链接放依据位，正文负责解释。
• 机制篇不能把多层压成一句。写“由 X 计算/持有/注入”时，交代源数据、派生视图、 持久化增量、请求投影，以及谁在什么时点写/读；只贴构造函数不够。
• 写“唯一/只/都/从不/纯函数/每次”前先对账所有回调、注册点和异常路径； 依赖注入不等于纯函数，一个订阅不等于唯一反向通道。

四、写 plan.json

按 计划合同 的 v2 形状写。正文只留骨架，字段表、videos 与 quiz 的完整对象、v1 兼容说明都在那份文档里：

{
  "version": 2,
  "topic": "可靠队列入门",
  "promise": "从一次丢消息的故障出发，做出一个重启不丢的最小队列。",
  "learner": {"level": "会一点 Python", "time_per_day": "40 分钟"},
  "notes": [
    {
      "id": "01", "title": "先看一次真实失败",
      "goal": "能指出消息在哪一段丢的", "depth": "L2",
      "kind": "concept", "minutes": 25, "file": "notes/01-what.md",
      "videos": [{"title": "原视频标题", "url": "https://www.youtube.com/watch?v=XXXXXXXX",
                  "channel": "频道名", "duration": "12:30", "lang": "en",
                  "why": "补队列的基本直觉。", "verified_at": "2026-10-23"}],
      "quiz": [{"q": "入队成功代表消息安全了吗？", "options": ["是", "还要看落盘"], "answer": 1, "explain": "入队只在内存里。"}]
    }
  ],
  "practice": {"title": "做一个不丢消息的队列", "brief": "50 行代码。", "steps": []},
  "review": [{"front": "为什么先写临时文件？", "back": "保证替换原子。", "source": "POSIX rename"}],
  "sources": {"verified_at": "2026-10-23", "note": "视频只核验元数据。"}
}

自测题的题型搭配、干扰项怎么写、why 与 explain 的分工见 自测设计。

五、构建

首次使用装一次渲染依赖（可选；不装会回退到内置渲染器，嵌套列表会被拍平）。 环境装在项目家目录，不写进 skill：

sh scripts/setup.sh   # → ${AGENT_SKILLS_HOME:-~/.agent-skills}/data/learning-scout/venv

构建默认会跑质量检查；也可以单独跑一遍看完整报告：

python3 scripts/check_notes.py --plan plan.json
python3 scripts/build_series.py build --input plan.json
python3 scripts/build_series.py build --input plan.json --out ./dist --force --open

check_notes.py 按 kind 检查默认节、源码证据、跨篇引用与个人路径，并检查编号章节与参考资料节；长度只在明显偏离参考区间时提示； --force 覆盖已存在的输出目录，--open 构建后直接打开入口页，--no-check 跳过质量检查（仅用于临时草稿）。

默认输出到 ~/Downloads/learning-scout/<topic>-<date>/。构建会：

• 渲染每篇 Markdown 为 notes/<id>-<slug>.html，并复制原文 .md；
• 生成 index.html：篇目卡、进度、视频墙、动手任务、复习卡、来源与核验日期；
• 复制 plan.json 与一份列出全部路径的 README.md。

视频内嵌是点击后加载：页面先显示按钮，点击才请求播放器；断网时正文仍可读。 不支持内嵌的平台只保留外链。

六、验收

内容：

• python3 scripts/check_notes.py 通过（或只剩可解释的警告）。
• 每篇长度偏离参考区间时能说清原因，开场问题在结尾有答案。
• 按主题需要给了完整示例、故障矩阵和边界；省略时说明原因，不为凑结构补节。
• 没有跨篇引用，没有个人环境信息。
• 视频元数据完整，没看过的没有评价。
• 每篇有核验声明，sources.verified_at 已更新。

页面：

• index.html 能打开，篇目链接都能跳到对应页。
• 桌面 1440px 与手机 390px 都没有横向溢出。
• 点一次视频按钮能加载播放器；断网时正文仍可读。
• 勾选进度、答题、复习卡“记得/忘了”、搜索过滤、上一篇/下一篇都实际点过。
• 深色模式下正文、表格、代码块都可读。
• 打印预览不出现导航和播放器；print.html 能连续读完所有篇目。

七、可选：把笔记回流到知识库

notes/*.md 是普通 Markdown，带 frontmatter（title、depth、kind 可选）。是否导入、 导入到哪个目录，由使用者决定；这个 skill 不做假设，也不依赖任何特定知识库工具。

需要时，把以下信息交给执行导入的 agent 即可：

• 输出目录路径（构建结束时打印）；
• 目标知识库路径与目标子目录；
• 是否保留原文件名、是否改写 frontmatter。

如果使用者不打算回流，就停在交付目录：HTML 入口 + Markdown 原文已经能独立使用。

常见失败

• 把搜索结果的标题和摘要当正文，编出不存在的链接。
• 每篇只有两三行提纲，读者看完只知道名词。
• 链接堆成 20 个，没有“先做哪一步”。
• 跨篇引用“见上一篇”，拆开任何一篇都读不懂。
• 视频只核验标题就写“讲得很好”。
• 示例里带作者自己的路径、密钥、会话数据。
• 只交付 HTML，没有 Markdown 原文，无法回流与二次编辑。
• 页面很漂亮，但手机上横向溢出，或篇目链接点不开。
• 忘记写核验日期和“哪些没有验证”。

边界

• 不自动把笔记写进任何知识库；是否回流由使用者决定。
• 不下载、转录或重新分发付费课程和视频。
• 不声称看过没有看过的内容。
• 不把学习系列包装成“保证学会”或“7 天精通”。
• 不把 localStorage 说成云同步；换设备或清缓存就丢失。
• 不把 1 / 3 / 7 天说成完整 FSRS；它只是轻量间隔复习。
• 资源服务于路线；路线服务于“读完能做什么”。