一、项目定位与核心能力

yt-fts（YouTube Full-Text Search）是一个面向 YouTube 视频字幕的命令行工具，旨在把频道或播放列表的字幕下载到本地，建立可全文检索、可向量检索，并可与大语言模型对话的索引数据库。它使用 yt-dlp 抓取 WebVTT 字幕，用 SQLite 存储结构化元数据，用 ChromaDB 保存语义向量。

项目的核心能力可分为四层：

• 下载层：基于 yt-dlp 拉取频道、播放列表或单视频的字幕文件，支持并行任务与浏览器 cookie。
• 全文检索层：使用 SQLite FTS5 表对字幕进行词项匹配，支持 AND、OR、引号短语、- 排除等查询语法。
• 语义检索层：调用 OpenAI 或 Gemini 的 Embedding 接口，将字幕分块写入 ChromaDB，支持余弦相似度搜索。
• 生成层：在前两层检索结果之上调用 LLM 提供 summarize 与 llm 两种交互式问答。

资料来源：README.md

二、版本演进与变更要点

从版本演进可以看出三个主线：稳定性修复、模型生态扩展（OpenAI → Gemini）、以及下载层的鲁棒性提升。

资料来源：CHANGELOG.md

三、命令行入口与子命令结构

CLI 由 click 框架组织，顶层入口位于 src/yt_fts/yt_fts.py，注册为 cli 命令组，并在模块底部通过 if __name__ == '__main__': cli() 启动。可识别的子命令覆盖了完整的"下载—索引—检索—生成"工作流。

flowchart LR
    A[yt-fts CLI] --> B[download]
    A --> C[search / vsearch]
    A --> D[embeddings]
    A --> E[summarize]
    A --> F[llm]
    A --> G[export / list / delete / config]
    B --> H[(SQLite + ChromaDB)]
    D --> H
    C --> H
    E --> H
    F --> H

主要子命令职责如下：

• download：从频道或播放列表 URL 下载字幕，支持 --language、--jobs、--cookies-from-browser 等参数。
• search / vsearch：前者调用 SQLite FTS5 全文检索，后者查询 ChromaDB 做语义检索；可叠加 --export 输出 CSV。
• embeddings：将字幕按时间窗口切块，调用 Embedding 模型写入 ChromaDB。
• summarize：对单条视频的转录文本做摘要，并在关键节点插入时间戳 URL。
• llm：以检索结果为上下文启动多轮对话，回答不了时自动扩展查询。
• list / delete / export / config：分别用于浏览已索引频道、删除频道、导出字幕、查看配置路径。

资料来源：src/yt_fts/yt_fts.py

四、安装、环境与配置

4.1 依赖与运行要求

运行时依赖主要集中在以下几项：

• yt-dlp：负责抓取字幕与元数据，是下载层的核心。
• webvtt-py：用于解析 WebVTT 文件到词级或句子级时间戳。
• openai：官方 OpenAI SDK，通过自定义 base_url 也能对接 Gemini 等兼容服务。
• chromadb：持久化向量索引。
• rich + click：负责终端 UI 与 CLI 解析。

get_model_config 函数会根据 API Key 前缀自动判定后端：若 Key 以 sk- 开头则使用 OpenAI（https://api.openai.com/v1），以 AIza 开头则切换至 Gemini（https://generativelanguage.googleapis.com/v1beta）。当未显式传入 Key 时，会依次读取 OPENAI_API_KEY、GEMINI_API_KEY 环境变量。

资料来源：src/yt_fts/utils.py

4.2 安装方式

项目以 pyproject.toml 作为构建入口（自 v0.1.43 起从 setup.py 迁移）。标准安装流程为：

1. 克隆仓库并创建虚拟环境。
2. 执行 pip install -e . 或 pip install yt-fts。
3. 在终端中运行 yt-fts --version 验证安装；若打印出版本号即表示 CLI 已注册成功。

4.3 配置路径与 API Key

• 配置文件、SQLite 数据库与 ChromaDB 持久化目录由 config 子命令统一打印。
• 大语言模型与 Embedding 共用同一 API Key，但可在 summarize 中通过 --model 指定 chat 模型。
• 下载层在 v0.1.62 起会随机化 User-Agent 字符串池，降低被 YouTube 风控的概率。

资料来源：src/yt_fts/download/download_handler.py

五、社区常见安装与上手问题

• 请求格式不可用（#183）：通常是 yt-dlp 版本过旧导致。可升级 yt-dlp 至 v0.1.60 指定的 2025.6.30 或更高版本。
• 下载到错误频道（#46）：早期版本在 @handle 解析上存在歧义，v0.1.59 起改用 RSS Feed 提取频道名称，建议保持工具为最新。
• 搜索仅返回单条命中（#189）：这是 search.py 中排序键缺失 video_id 导致的边界 bug，升级到修复版本即可。
• 缺少 Cookie 被限流：可使用 download --cookies-from-browser firefox 让 yt-dlp 复用浏览器登录态。
• 仅想下载一段引用的音视频（#60）：当前工作流需要先用 search 找到时间戳，再用 yt-dlp -x 与 ffmpeg 手动裁剪；该特性尚未集成进 CLI。

资料来源：CHANGELOG.md

六、See Also

• 下载与字幕抓取：见 DownloadHandler 与 src/yt_fts/download/ 模块。
• 全文与语义检索：见 SearchHandler 与 ChromaDB 持久化目录。
• LLM 对话与摘要：见 LLMHandler 与 SummarizeHandler。
• 项目资助入口：FUNDING.yml

概览

下载、列表、更新与导出 是 yt-fts 工作流中最常用的数据生命周期入口,承担"获取字幕—管理频道—同步更新—输出数据"四类职责。CLI 入口全部由 src/yt_fts/yt_fts.py 基于 Click 注册命令,核心实现则由 DownloadHandler、数据库工具模块以及导出模块共同完成,数据最终落到本地 SQLite 数据库中供后续搜索/语义检索使用。

flowchart LR
    A[yt-dlp 抓取] --> B[DownloadHandler]
    B --> C[(SQLite 数据库)]
    C --> D[list 列表]
    C --> E[update 更新]
    C --> F[export 导出]
    F --> G[vtt / csv / txt]
    D --> H[用户查看 ss 标记]
    E --> B

概述

yt-fts 提供了两种互补的字幕检索路径：全文搜索（基于 SQLite FTS5 的关键字匹配）与语义搜索（基于 ChromaDB 向量数据库的相似度检索）。两者在 yt-fts 项目中扮演“内容检索入口”的角色：前者用于精确查找字幕中出现的字面词句，后者用于在意思相近的语段之间做模糊匹配。两条路径都通过统一的 SearchHandler 类与 Click 命令 search、vsearch 对外暴露，使用户既可以快速定位一段被引用的台词，也可以基于自然语言问题在视频语料库中寻找答案。

资料来源：src/yt_fts/search.py:1-46

全文搜索（`search` 命令）

搜索范围与参数

SearchHandler 在构造时接收四个核心参数：scope、channel、video_id、limit，用以决定检索的边界。scope 接受三种取值：

CLI 入口位于 yt_fts.py 中的 search 命令，使用 -c/--channel、-v/--video-id、-l/--limit、-e/--export 四个选项控制检索范围与导出行为。--limit 默认值为 10。资料来源：src/yt_fts/yt_fts.py:1-30、src/yt_fts/search.py:14-46

工作流程

full_text_search 方法根据 scope 调度到 db_utils 中对应的查询函数，并将查询字符串以 self.query 保存，结果再交给后续渲染与导出逻辑。utils.py 中提供的 bold_query_matches 用于在终端中以加粗形式高亮命中片段，使阅读结果时关键词一目了然。

flowchart LR
    A[search 命令] --> B{Self.scope}
    B -- all --> C[search_all]
    B -- channel --> D[search_channel]
    B -- video --> E[search_video]
    C --> F[SQLite FTS5 命中]
    D --> F
    E --> F
    F --> G[终端高亮输出]
    F -.--export.-> H[CSV 导出]

社区曾报告一个在 search.py:174 附近的 Bug（Issue #189），错误地在字典 key 中遗漏了 video_id，导致按视频去重后只返回一行结果。该问题已在新版本中修复。资料来源：CHANGELOG.md:1-60

语义搜索（`vsearch` 命令）

前置条件：Embeddings

vsearch 依赖 ChromaDB 中预先计算的向量索引，使用前必须对目标频道执行 yt-fts embeddings --channel <name>。EmbeddingsHandler.add_embeddings_to_chroma 会按 interval（默认 30 秒）将每段字幕切片，并把视频元数据（频道名、标题、发布日期、开始/结束时间）一同写入文本，再通过 OpenAI 或 Gemini 的 embedding 模型生成向量，存入 ChromaDB。资料来源：src/yt_fts/llm/get_embeddings.py:1-60、README.md:1-60

检索与上下文增强

SearchHandler 接受可选的 openai_client 参数；当使用语义搜索时，会先调用 embedding 接口将用户查询向量化，再从 ChromaDB 中拉取最相似的若干段字幕作为上下文。llm/chatbot.py 中的 LLMHandler 进一步复用此能力：它在对话首轮用相似度检索为问题构建上下文，若模型回答以 i don't know 开头，会调用 get_expand_context_query 让 LLM 改写查询词，再次执行向量检索以扩展上下文，从而提升回答质量。资料来源：src/yt_fts/llm/chatbot.py:1-90

已知问题与社区反馈

社区中围绕搜索功能集中出现过几类诉求与故障：

• Issue #189：搜索结果在某些情况下“每个视频仅返回一条引用”，根因在 search.py 的去重 key 缺失字段。
• Issue #47：希望在 search 与 vsearch 中支持对视频标题使用正则，以仅检索频道中的一部分视频（例如播客合集）。该特性目前尚未在源码中实现，需要通过 vsearch 的 channel + 多次查询、或在外层脚本中预先过滤来模拟。
• Issue #60：用户希望将 search 命中的引用一键导出为音视频片段（yt-dl + ffmpeg 截取）。该功能不在 yt-fts 当前实现范围内，但 --export 标志已支持将字幕结果落盘为 CSV，方便下游脚本处理。

资料来源：CHANGELOG.md:1-80

See Also

• yt-fts 项目主页与命令一览
• CHANGELOG.md
• src/yt_fts/llm/chatbot.py
• src/yt_fts/llm/get_embeddings.py

概览

yt-fts 在本地 SQLite 全文检索的基础上，提供了一层 AI 能力，覆盖"向量化、问答、摘要"三件事。这三项功能共享同一套模型配置和凭据解析逻辑，分别对应 CLI 中的 embeddings、vsearch、llm 与 summarize 四个子命令（资料来源：README.md）。

• embeddings：把字幕切片并调用嵌入模型，结果写入 ChromaDB。
• vsearch：在 ChromaDB 中按相似度检索字幕段落。
• llm：以向量检索结果作为上下文，驱动多轮对话式问答。
• summarize：对单条视频字幕生成带时间戳链接的总结。

下图展示从字幕到 AI 回答的整体数据流：

flowchart LR
    A[下载字幕<br/>download] --> B[SQLite 全文索引]
    A --> C[EmbeddingsHandler<br/>按 interval 切分]
    C --> D[OpenAI / Gemini<br/>Embedding API]
    D --> E[ChromaDB Collection]
    E --> F[vsearch<br/>相似度检索]
    E --> G[llm<br/>RAG 多轮对话]
    A --> H[SummarizeHandler<br/>单视频摘要]
    H --> I[OpenAI / Gemini<br/>Chat Completion]
    H --> J[带时间戳的总结文本]

模型配置与凭据解析

所有 AI 命令入口都通过 get_model_config 解析模型与 API Key（资料来源：src/yt_fts/utils.py:1-40）。该函数内部维护两个模型档案：

Key 的解析顺序为：(1) 显式传入参数时按前缀判断；(2) 否则回退到 OPENAI_API_KEY / GEMINI_API_KEY 环境变量；(3) 都没有则抛 ValueError("No model configuration found...")（资料来源：src/yt_fts/utils.py:1-40）。

这套设计使得四个命令可以使用统一的 --api-key 参数；CLI 中 get_model_config(api_key) 返回的字典会直接传给后续 handler 用于构造 OpenAI 客户端（资料来源：src/yt_fts/llm/chatbot.py:27-35、src/yt_fts/llm/summarize.py:17-25）。

Embeddings 与 ChromaDB 写入

EmbeddingsHandler.add_embeddings_to_chroma 负责把某个 channel 的全部字幕生成嵌入并存入 Chroma（资料来源：src/yt_fts/llm/get_embeddings.py:19-55）。主要流程：

1. 通过 get_vid_ids_by_channel_id 拉取该 channel 下所有视频 ID；
2. 对每条视频调用 split_subtitles，按 --interval（默认 30 秒，可通过 embeddings -i 调整）切分字幕；
3. 用 add_meta_data_to_text 把频道名、标题、日期拼接到文本，提升检索相关性；
4. 过滤空段落后统一送入 get_model_config 指定的 embedding 模型；
5. 写入 Chroma collection（路径由 get_or_make_chroma_path() 提供，资料来源：src/yt_fts/yt_fts.py:1-30）。

vsearch 命令复用同一 Chroma 客户端，将查询文本嵌入后按余弦相似度排序，默认返回前 10 条（资料来源：README.md:1-30）。channel 在生成 embeddings 后，list 时会在名称后追加 (ss) 标记，提示该 channel 可被向量检索。

LLM 聊天机器人 (RAG)

LLMHandler 实现 llm 命令背后的多轮对话（资料来源：src/yt_fts/llm/chatbot.py:27-80）。init_llm 接收初始 prompt 后做三件事：

1. 调用 start_llm，使用 system prompt 指示模型"根据用户问题生成一个适合向量检索的查询串"；
2. 把生成的查询送入 Chroma 检索上下文；
3. 用 format_context 把检索到的 video_title / date_posted / link / subs 拼成一段上下文，喂给 chat 模型得到首条回答。

随后进入 REPL 循环：每次用户输入追加到 messages，调用 continue_llm 重新生成向量查询并刷新上下文（资料来源：src/yt_fts/llm/chatbot.py:50-80）。get_completion 调用 chat.completions.create，temperature=0.5、max_tokens=2000，并对非 OpenAI 模型传 NotGiven() 跳过 stop 等不兼容字段（资料来源：src/yt_fts/llm/chatbot.py:65-80）。

CLI 入口要求必须传 -c/--channel 并给出问题文本（资料来源：README.md:1-30）。channel 必须先执行过 embeddings，否则 Chroma 中无数据可用。

视频摘要

SummarizeHandler 是 summarize 命令的核心（资料来源：src/yt_fts/llm/summarize.py:17-50）。其特色在于：

• 输入既支持完整 URL（含 https）也支持裸 video ID，由 get_video_id_from_url 解析；
• 若 video_in_database(video_id) 返回 True，直接从 SQLite 读取字幕并用 video_title / channel_name 渲染 prompt，避免重复抓取；
• 否则调用 download_transcript() 用 yt-dlp 临时下载 VTT 字幕；
• summarize_video 的 system prompt 明确要求"以 timestamp 形式给出关键时间戳链接"，因此输出天然包含可点击定位（资料来源：README.md:1-30、src/yt_fts/llm/summarize.py:35-50）。

--model 选项允许用户覆盖默认 chat_model，但底层仍走同一个 OpenAI 客户端，只是改 model 字段（资料来源：src/yt_fts/yt_fts.py:1-30）。

常见失败模式

• 未生成 embeddings 就跑 vsearch 或 llm：Chroma collection 为空，检索不到任何上下文。须先 yt-fts embeddings --channel "<name>"（资料来源：README.md:1-30）。
• API Key 未配置：get_model_config 会抛 ValueError。OPENAI_API_KEY 与 GEMINI_API_KEY 是唯二被识别的环境变量（资料来源：src/yt_fts/utils.py:1-40）。
• 下载时 "Requested format is not available"：属于 yt-dlp 与频道默认格式不匹配，与 AI 子系统无关，但 v0.1.60 之后通过 --jobs 与 User-Agent 随机化已大幅缓解（资料来源：CHANGELOG.md:1-20、社区 Issue #183）。
• 速率限制：可使用 --cookies-from-browser 让 yt-dlp 携带登录态 cookie，缓解抓取字幕时的 429（资料来源：CHANGELOG.md:1-20）。

See Also

• README.md
• CHANGELOG.md
• config：通过 yt-fts config 查看数据库与 Chroma 路径（资料来源：src/yt_fts/yt_fts.py:1-30）
• 社区 Issue #189：已知 search.py 在旧版中仅返回单条引用，AI 子系统不受该 bug 影响

Pitfall Log / 踩坑日志

项目：NotJoeMartinez/yt-fts

摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Crash due to unicode decode error while getting video title from vtt。

1. 安装坑 · 来源证据：Crash due to unicode decode error while getting video title from vtt

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Crash due to unicode decode error while getting video title from vtt
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Help installing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Help installing
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/180 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Requested Format Not Available

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Requested Format Not Available
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/183 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：yt-dlp update required

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：yt-dlp update required
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/192 | 来源类型 github_issue 暴露的待验证使用条件。

5. 配置坑 · 来源证据：AttributeError: 'NoneType' object has no attribute 'string'

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AttributeError: 'NoneType' object has no attribute 'string'
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/184 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/NotJoeMartinez/yt-fts | README/documentation is current enough for a first validation pass.

7. 运行坑 · 来源证据：I got messge to sign in

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：I got messge to sign in
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/182 | 来源类型 github_issue 暴露的待验证使用条件。

8. 运行坑 · 来源证据：Search results show only one quote per video

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Search results show only one quote per video
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/189 | 来源类型 github_issue 暴露的待验证使用条件。

9. 维护坑 · 来源证据：'NoneType' object has no attribute 'decode'

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：'NoneType' object has no attribute 'decode'
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/181 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/NotJoeMartinez/yt-fts | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/NotJoeMartinez/yt-fts | no_demo; severity=medium

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/NotJoeMartinez/yt-fts | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：User Agent Randomization, Proxies and Youtube API

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：User Agent Randomization, Proxies and Youtube API
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/NotJoeMartinez/yt-fts/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。

14. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/NotJoeMartinez/yt-fts | issue_or_pr_quality=unknown

15. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/NotJoeMartinez/yt-fts | release_recency=unknown