notebooklm-mode

基于 NotebookLM 的研究流水线

从资料来源研究主题——收集原文摘录，为其建立语义搜索索引，然后基于这些资料回答问题并创建交付成果。灵感来自 NotebookLM。

触发条件

• 用户要求“基于资料来源”或“以资料来源为依据”研究某个主题
• 用户提到“notebooklm mode”“source-grounded”或“vault mode”
• 用户希望回答引用已收集的资料，而非一般知识
• 用户要求根据已收集的资料创建交付成果

---

模式

直接模式（默认）

协调器直接运行所有角色，不使用子 Agent。适用于大多数主题。

子 Agent 模式（可选）

仅在确有必要时通过 delegate_task 启动 Agent：针对不同子主题进行并行研究，或用户明确提出要求。不会仅因资料来源数量多而触发；只有工作确实可并行处理或用户要求隔离时才升级。

delegate_task(
  goal="<user's request>",
  context="You are the [Research|Response|Output] Agent in a NotebookLM
           pipeline. Vault path: <vault_path>. Load skill 'notebooklm-mode'.
           Your role: [Research|Response|Output]. Topic: <topic>.
           Grounding mode: [strict|augmented].",
  toolsets=[<appropriate toolsets per role>]
)

按顺序进行：研究 →（用户审核）→ 回答 →（用户提出要求）→ 输出。 在前一个 Agent 返回且文件经过核实之前，绝不派遣依赖其工作的 Agent。

溯源模式

模式	行为
严格（默认）	仅限资料库。如果资料库中没有，就视为未知。指出信息缺口，绝不通过推断填补。
增强	优先使用资料库。允许使用一般知识，但必须明确标记为 [background]，并与源自资料库的主张清楚区分。用户需明确提出此要求。

增强模式示例：

根据资料来源 #3：“LTCI 系统覆盖了 95% 的老年人” [vault]

[background] LTCI 于 2000 年作为日本长期护理保险改革的一部分推出。

---

通用规则（适用于所有角色和两种模式）

• 仅使用原文作为源文件内容——逐字复制。仅在内容设有付费墙且只能获取摘要时标记 [paraphrased]。如果无法获取完整页面，则标记 [reconstructed from search snippets]。
• 所有内容均需引用——资料库中的每项事实性主张都要引用特定源文件，并尽可能附上带有出处的原文引述。
• 如实呈现矛盾——资料来源存在分歧时，注明出处并呈现双方观点。不要擅自裁决。
• 指出信息缺口 ≠ 得出结论——可以说“资料库中缺少关于 X 的信息”；禁止说“因此 X 可能是 Y”（严格模式），或必须标记为 [background]（增强模式）。
• 清除机密信息——在保存到资料库或输出之前，检查源内容中是否包含 API 密钥、令牌或凭据。
• 源文件中不得包含既有知识——按原样记录资料来源，即使你认为其中有误。评估工作由回答角色负责。

---

工作区资料库

资料库是专为用户研究而创建的临时工作区目录，不属于永久资料库。其中保存某个研究主题的资料摘录、按语料库建立的 RAG 索引和输出。研究完成后清理；如果用户希望保留，则归档。

首次交互时务必确认资料库位置：

“应将工作区创建在哪里？默认位置：<project_folder>/research-<topic>/”

工作区是研究会话的工作目录。用户可以通过任何已连接的渠道（Telegram、WhatsApp 等）提供资料；Agent 将其保存到 sources/，并在下次交互时建立索引。用户无需直接访问 VM 文件系统。

输出交付方式相同——Agent 通过用户指定的渠道发回已完成的交付成果（例如，通过 Telegram MEDIA 发送文件，或以行内 Markdown 发送笔记）。

结构

<vault_path>/
├── vault_index.md          # Catalog of sources + outputs
├── sources/                # Verbatim source extracts (one file per source)
│   └── 001_title.md
├── rag_index.db            # Per-corpus sqlite-vec DB (semantic search)
└── outputs/                # Agent-generated deliverables
    └── notes_YYYY-MM-DD.md

Source file format

# Source Title

| Field    | Value                     |
|----------|---------------------------|
| URL      | https://example.com/page  |
| Author   | Author Name (if known)    |
| Date     | Publication date (if known) |
| Retrieved| YYYY-MM-DD                |
| Type     | web / pdf / user-provided / youtube |

## Extracts

> "Verbatim quote from the source."
> — Section: Introduction

## Key Data Points

- Statistic: 42% of respondents... (Section: Results)

• 对于网站，请提取实际内容，而不只是 URL
• 如果内容太长，请提取相关段落，并注明跳过了哪些内容
• 按顺序为文件编号：001_、002_ 等
• 用户提供的文件：将 Type 设为 user-provided，URL 留空
• 非逐字摘录的标记：[paraphrased]（仅限付费墙后的内容或摘要）、[reconstructed from search snippets]（无法获取完整页面）

vault_index.md

# Workspace Vault Index
**Topic:** [topic] | **Created:** YYYY-MM-DD | **Sources:** N | **Mode:** [strict|augmented]

## Sources
| # | File | Type | Title | Retrieved |
|---|------|------|-------|-----------|
| 1 | 001_title.md | web | Article Title | YYYY-MM-DD |

## Coverage Notes
- Well covered: [list] | Gaps: [list]

## Outputs
| File | Type | Created |
|------|------|---------|
| notes_YYYY-MM-DD.md | notes | YYYY-MM-DD |

用户提供的材料

用户可以随时通过任何已连接的渠道（Telegram、WhatsApp 等）提供文件。Agent 会将文件保存到 sources/，为其编制索引、更新 vault_index.md，并向用户确认——无需直接访问 VM。

---

按语料库进行语义搜索（可选）

每个工作区内都会新建一个 rag_index.db——这是一个独立的 sqlite-vec 数据库，使用与 library-rag 相同的 bge-m3 嵌入，但仅针对当前研究语料库。不同的研究主题会使用不同的工作区文件夹，每个文件夹都有独立的数据库。绝不会将内容索引到 ~/.hermes/library/rag_index.db 中的主库数据库。

此功能为可选项。 不使用它也能正常运行此技能——对于较小的资料库，直接读取文件即可。随着语料库增长（20+ 个来源），语义搜索会更有用。如果 library-rag 不可用，ingest_source.py 只会写入文件，不会编制索引。

原子化导入（一次调用完成写入和索引）

使用捆绑的 ingest_source.py 脚本写入来源文件，并将其原子化地索引到资料库的 RAG 数据库中（如果 RAG 可用）。这避免了先保存再索引的两步操作，后者在较弱的本地模型上可能会静默失败。

Python API：

import sys; sys.path.insert(0, "<skill_dir>/scripts")
from ingest_source import ingest, search_vault, reindex_vault

# Write + index atomically
result = ingest(vault_path, "001_title.md", content)
print(f"Indexed {result['chunks_indexed']} chunks")

# Semantic search over the vault
results = search_vault(vault_path, "your query", top_k=5)
for r in results:
    print(f"[{r['similarity']:.0%}] {r['source_file']} — {r['section_title']}")
    print(f"  {r['chunk_text'][:200]}")

# Reindex all sources (e.g., after user drops files manually)
reindex_vault(vault_path)

CLI：

# Write + index
python3 <skill_dir>/scripts/ingest_source.py \
  --vault <vault_path> --file 001_title.md --content "..."

# Reindex all sources
python3 <skill_dir>/scripts/ingest_source.py --vault <vault_path> --reindex

# Search
python3 <skill_dir>/scripts/ingest_source.py \
  --vault <vault_path> --search "query" --top-k 5

该脚本会按以下顺序查找 library-rag 脚本：LIBRARY_RAG_SCRIPTS 环境变量、Hermes 技能目录结构，然后是相对于仓库的备用路径（例如同级的 library-rag/scripts 或 research/library-rag/scripts）。因此，直接克隆此仓库即可使用，无需设置任何环境变量。无需 MCP 依赖——直接导入即可。

适用场景

• 响应——对资料库进行语义查询，而不是将所有来源文件都载入上下文。对于大型资料库（20+ 个来源）尤其有用。
• 输出——在创建交付内容之前，找出所有与某个主题相关的段落。

对于较小的资料库（来源少于 5 个、文档较短），直接读取文件即可——语料库越大，语义搜索越有价值。

---

角色

研究（Gatherer）

目的： 在线研究、查找来源、提取原文段落并填充知识库。

工具： web_search、web_extract、browser、terminal（用于 ingest_source.py）

行为：

1. 如果主题范围过广，先明确研究范围
2. 制定研究计划 — 将主题拆分为 3-6 个子问题，并定义成功标准（怎样才算全面覆盖？）。此计划将指导搜索策略，并作为差距分析步骤中的停止检查依据。
3. 日期校准（必须） — 搜索前，先校准真实的当前日期：注入“今天的日期是 {current date as 'DD Month YYYY'}。当搜索查询需要年份或提及‘最新’、‘当前’或‘今年’时，使用 {current year} — 绝不要使用根据训练数据推断出的年份。”这样可以避免查询中出现过时的训练截止年份。
4. 搜索权威、多元且近期的来源 — 根据第 2 步中的子问题生成目标查询
5. 质量筛选 — 提取前，剔除低质量结果：
   • 内容单薄：落地页、聚合页占位内容、少于 100 个实质性文本词语
   • 不相关：只有关键词重合，没有主题相关性（按词边界匹配，而非子字符串）
   • 重复 URL：同一页面出现在多个结果中
   • 非文本内容：只有视频的页面、图片论坛，以及没有预览内容的登录墙
6. 获取完整内容，挑选相关段落，并将其原文复制到来源内容中
7. 原子化导入 — 使用 ingest_source.py 在一次调用中写入并索引每个来源。每新增一个来源后更新 vault_index.md。
8. 差距分析 — 完成第一轮后，对照研究计划审查发现：
   • 哪些子问题尚未得到回答？哪些覆盖不足？
   • 针对差距生成后续查询，并再进行一轮搜索
   • 总计最多重复 3 轮。在 vault_index.md 的 Coverage Notes 下记录任何剩余差距
9. 停止标准 — 在以下情况下停止搜索：
   • 所有子问题均至少有 1 个来源涉及，或
   • 已完成 3 轮搜索，或
   • 已收集 20 个来源（广度上限）
   • 如果仍有差距时停止：在 Coverage Notes 中明确记录 — 绝不要用推断掩盖差距
10. 报告发现的主题（而非内容），询问用户是否希望深入研究
11. 收集 5–20 个来源后停止（视主题广度而定）；确认覆盖是否充分

回答（基于资料的回答者）

目的： 根据知识库回答问题。知识库即资料库。

工具： read_file、terminal（用于 search_vault）

行为：

1. 首先读取 vault_index.md。对于大型资料库，使用 search_vault()，而非加载所有文件。
2. 使用知识库中的内容作答。引用格式：“根据来源 #3：……”
3. 每次回复前检查用户提供但尚未索引的文件（如果发现新文件，则运行 reindex_vault）
4. 如果知识库未涵盖问题：
   • 严格模式：说明资料缺口，并建议一个研究提示词。绝不暗示结论。
   • 增强模式：说明资料缺口，建议一个研究提示词，并可选择提供与知识库内容明确分开的 [background] 背景信息。
5. 如果来源之间存在矛盾，则同时呈现双方观点 — 不要自行裁定
6. 将较详尽的回答连同引用保存到 outputs/notes_YYYY-MM-DD.md

输出（创建者）

目的： 使用可用工具，根据知识库内容创建交付物。

工具： file、terminal，以及输出格式所需的任何工具

行为：

1. 接收：要创建的内容、范围、格式，以及要参考的来源
2. 阅读相关知识库来源（对于大型知识库，使用 search_vault()）
3. 使用适当的工具创建输出——调用 Agent 运行时安装的任何专用技能（本仓库不包含这些技能）：
   • .md → 直接写入文件
   • .docx/.pptx/.xlsx → 如有可用的办公文档技能，则使用该技能
   • 信息图 / 幻灯片 / 杂志版式 / 数据报告 / 海报 → 如有可用的相应设计或创作技能，则使用该技能；否则生成结构化 Markdown，供用户交由自己的工具处理
4. 添加来源引文（脚注或行内引文）和“Sources”部分
5. 保存到 outputs/，更新 vault_index.md
6. 验证输出文件存在且有效

---

来源馈送器

其他技能可以将来源文件馈送到知识库：

技能	馈送方式	来源类型
youtube-topic-research	--export-vault 标志会将经过审核的视频导出为 NNN_youtube_*.md 来源文件，其中包含转录摘录、视觉内容 / 演示说明和元数据	youtube
手动研究	Agent 将网页摘录直接保存到 sources/	web、pdf、user-provided

馈送器技能写入来源后，运行 reindex_vault()，以便在 Response / Output 角色使用知识库前将这些来源编入知识库的 RAG 数据库。

编排器路由

用户意图	角色	模式
“研究 [主题]”、“查找关于……的来源”	Research	直接
“知识库对……怎么说？”、“总结……”	Response	直接
“根据知识库创建幻灯片 / 笔记 / 信息图”	Output	直接
“查看知识库中有什么”	Response	直接
“查找 YouTube 视频并添加到知识库”	youtube-topic-research → feeder	直接
“研读 John 3:16”、“与 Calvin 一起研读 Genesis 5”、“{commentator} 对 {passage} 有何看法”	Research → Response	直接 + references/book-study.md
意图不明确——研究还是回答	询问：查找新来源，还是根据现有知识库回答？	—

默认使用直接模式。只有当工作确实可并行处理，或用户明确要求隔离时，才升级为子 Agent 模式。

注意事项

• 每次新会话都必须确认资料库路径 — 切勿假定其位置
• 资料库是临时的 — 不属于永久资料库。完成后请清理；如果用户想保留，则将其归档。除非用户明确要求，否则切勿将资料库来源编入主资料库的 RAG。
• 子 Agent 写入文件不可靠 — 子 Agent 返回后，务必对来源目录运行 ls；如果文件缺失，请自行重新创建
• 许多网站会拦截机器人 — 优先使用 Wikipedia、政府网站；使用 browser_console 提取内容；将重构的摘录标记为 [reconstructed from search snippets]
• 大型资料库 — 使用 search_vault()，而不是将所有来源文件加载到上下文中
• 逐字引用就是逐字引用 — 保留来源中的错字；如果有影响，请添加 [sic]
• 增强模式规范 — 对任何非资料库知识，都必须添加 [background] 标签。如有疑问，请使用严格模式。
• 查询中的年份过时 — 搜索前务必注入日期依据。模型默认采用训练截止年份，导致时效性主题的搜索结果无关。
• 跳过研究计划 — 没有子问题和成功标准，资料收集阶段就没有方向，差距分析也没有基准。务必先制定计划再搜索。
• 跳过差距分析 — 仅进行一轮搜索会遗漏后续问题。首轮搜索后，务必根据计划检查覆盖情况，并针对缺口运行有针对性的后续查询。
• 掩盖缺口 — 如果无法从来源回答某个子问题，请在 vault_index.md 的 Coverage Notes 中将其记录为缺口。切勿用推断（严格模式）或未标记的背景知识（增强模式）填补缺口。
• 研读书籍需要 parse_reference.py — 将 “John 3:16” 解析为精确文本，需要参考文献解析脚本（scripts/parse_reference.py）。如果脚本缺失，请改用语义搜索（精确度较低，可能返回错误的章节或经文范围）。完整工作流请参阅 references/book-study.md。