gbrain 内容与媒体摄入（Content Media Ingestion）：从 YouTube、社交帖子、PDF 到可搜索大脑页面的完整实践指南

• 人工智能
• RAG
• Agent 记忆
• MCP 服务
• 知识管理

导读

本文讲解 gbrain 中"内容与媒体摄入"（Content & Media Ingestion）这一核心数据管线：如何把 YouTube 视频、社交媒体帖子、PDF 与文档，转化为带有 Agent 自身分析、完整实体交叉引用、且可永久全文搜索的大脑页面（brain page）。你将掌握三大摄入模式（视频、社交帖子、PDF/文档）的可执行伪代码与底层 CLI 命令（gbrain put、link、timeline-add、files upload-raw、sync），了解内置media-ingest技能（skills/media-ingest/SKILL.md）的契约、阶段与错误处理，并学会用gbrain get、gbrain call get_links、gbrain search等命令验证摄入是否成功。全文以 docs/guides/content-media.md 为骨架，结合仓库源码与配套文档进行纵深展开。

一、为什么需要内容与媒体摄入：从"腐烂的书签"到"活的档案馆"

在传统的工作流里，人们看到一段有价值的 YouTube 视频或一篇 PDF，通常的做法是把它收藏进书签。gbrain 的视角是：书签会腐烂——你记得自己看过某个视频，却想不起来里面说了什么、是谁说的、为什么重要。

content-media.md给出的承诺是：每一份媒体都是一张永久的大脑页面，Agent 的分析叠加其上，每个被提及的实体都获得反向链接（back-link），全部内容永久可搜索。这正是 docs/GBRAIN_SKILLPACK.md 所描述的"memex 愿景"在媒体摄入层面的实现——Vannevar Bush 设想中的"所有资料都可被快速检索的个人设备"，在这里由 Agent 自动构建：检测实体、丰富页面、建立交叉引用、维护编译真值（compiled truth）。

要理解这一模式在整个技能包中的位置，可参考 docs/guides/content-media.md 结尾的定位——它是 GBrain Skillpack 的组成部分，与 会议摄入（meeting-ingestion.md） 同属"数据管道（Data Pipelines）"章节，服务于同一个目标：让大脑持续自我增殖。

与会议摄入的边界

content-media.md明确指出，会议录音/转录的场景不在本文范围内，而是由 meeting-ingestion.md 单独覆盖。两者的核心逻辑高度相似（拉取完整转录 → Agent 撰写分析 → 传播到所有实体页面 → 双向建链 → sync），但媒体摄入覆盖的格式更广：视频、音频、PDF、图书、截图、GitHub 仓库（见 skills/media-ingest/SKILL.md 的 Phase 1 格式表）。

二、内置设施：media-ingest 技能与 gbrain files

content-media.md在 Implementation 一节给出了两条内置支撑：

1. media-ingest技能（skills/media-ingest/SKILL.md）：仓库内置的、可直接交付给 Agent 执行的摄入工作流，版本 1.1.0，upstream: media-ingest@fc834ee。
2. gbrain files：处理二进制/文件上传，把附件放在页面旁边；gbrain files upload-raw <file> --page <slug>用于保留原始文件（provenance）。

media-ingest 技能契约

技能头部定义了触发词、可用工具与写入范围，这是 Agent 判断"何时该用这个技能"的依据：

• 触发词：watch this video、process this YouTube link、ingest this PDF、save this podcast、process this book、ingest it into my brain、what's in this screenshot、check out this repo等；
• 可用工具：search、query、get_page、put_page、add_link、add_timeline_entry、file_upload——这七个工具正好映射到下文 CLI 命令的底层 op（见 src/core/operations.ts 中add_timeline_entry、add_link等 op 的注册，以及 src/core/minions/tools/brain-allowlist.ts 对add_timeline_entry的许可说明）；
• 输入参数：source（必填，URL/文件路径/上传引用）、title（可选，覆盖自动检测标题）、target_slug（可选，覆盖自动生成的 slug）；
• 写入范围：concepts/、people/、companies/、sources/；
• 契约承诺：每个媒体条目都有带分析的页面（而非转录转储）、转录以 raw 与可读两种格式保存、每个被提及的人/公司都被反向链接、原始文件通过gbrain files upload-raw保留、按主要主题归档而非按媒体格式归档。

技能的 Phases 与content-media.md的三模式伪代码互为表里：识别格式并抓取（Phase 1）→ 上传原始文件（Phase 2）→ 创建大脑页面（Phase 3）→ 实体提取与传播（Phase 4）→ 同步（Phase 5）。

gbrain files命令族

从 src/cli.ts 的帮助文本可以看到完整的文件子命令：

FILES files list [slug] List stored files files upload <file> --page <slug> Upload file to storage files upload-raw <file> --page <s> Smart upload (size routing + .redirect.yaml) files signed-url <path> Generate signed URL (1-hour) files sync <dir> Bulk upload directory files verify Verify all uploads

其中upload-raw是"智能上传"，会根据文件大小自动路由存储后端，并按 skills/_brain-filing-rules.md 中的"大小路由（size routing）"规则处理大文件（例如超长图书全文不必内联进页面，而是链接到 raw 上传）。典型用法：

gbrain files upload-raw <file> --page <page-slug> --type <type>

--type用于标注文件类型；CHANGELOG 中记录过upload-raw在重复上传同一文件时不覆盖已存储的 metadatatype的行为修复（见 CHANGELOG.md），说明该命令对文件元数据是"合并式"更新。另外，Agent 场景下的原始文件上传建议直接走工具file_upload而非 CLI（见 plugin/skills/ingest/SKILL.md 的说明）。

三、模式一：YouTube 视频摄入（完整转录 + Agent 分析 + 实体交叉引用）

这是content-media.md中最完整的模式。核心信念只有一句话：永远使用带说话人分离（speaker diarization）的完整转录，绝不使用 YouTube 自动摘要或 AI 摘要。自动摘要丢失了"纹理"：谁说了什么、确切的措辞、语气、以及没说什么。

3.1 完整工作流

原文档给出的伪代码骨架如下：

on user_shares_media(url_or_file): # PATTERN 1: YouTube Video Ingestion if media.type == "youtube": # Step 1: Get FULL transcript with speaker diarization # WHO said WHAT -- not just a wall of text # Use Diarize.io or equivalent service transcript = diarize(video_url) # speaker-attributed transcript # Step 2: Agent writes OWN analysis (this is the value) # NOT a summary. NOT regurgitation. The agent's TAKE: # - What matters and why (given the user's worldview) # - Key quotes attributed to specific speakers # - Connections to existing brain pages # - Implications and follow-up angles analysis = agent_analyze(transcript, user_context) # Step 3: Create brain page slug = f"media/youtube/{video_slug}" gbrain put <slug> --content """ # {title} **Channel:** {channel} | **Date:** {date} | **Link:** {url} ## Analysis {agent_analysis} ## Key Quotes - **{Speaker}** ({timestamp}): "{quote}" -- {why_it_matters} --- ## Full Transcript {diarized_transcript} """ # Step 4: Extract and cross-reference entities for person in transcript.mentioned_people: gbrain link <slug> <person_slug> gbrain link <person_slug> <slug> gbrain timeline-add <person_slug> {date} \ "Discussed in {video_title}: {what_was_said}" \ --source "YouTube: {url}"

3.2 关键命令逐条解析

• gbrain put <slug> --content "..."：写入/更新页面。src/cli.ts 的帮助文本为put <slug> [< file.md]，即除--content外也可通过管道读入 Markdown 文件。这里用media/youtube/{video_slug}作为 slug 前缀，属于原文档明确认可的格式前缀路径（见下文"归档规则的微妙之处"）。
• gbrain link <from> <to>：创建带类型的链接（别名link-add），可选参数--link-type T与--link-source S，provenance 默认manual（src/cli.ts）。反向链接的"双向铁律"要求link <slug> <person_slug>与link <person_slug> <slug>都要执行。
• gbrain timeline-add <slug> <date> <text>：追加一条带日期的时间线条目（src/cli.ts）。原文档在每条timeline-add上都加了--source "YouTube: {url}"，这里需要特别注意一个语义细节（meeting-ingestion.md 有更完整的说明）：--source是引文文本（citation text），不是来源路由（source routing）。因为timeline-addop 声明了自己的source参数，CLI 会把--source绑定到该参数；若要写入不同的已注册来源，应改用.gbrain-source点文件或GBRAIN_SOURCE环境变量进行路由。

3.3 归档规则的微妙之处

表面上看，"按主要主题归档而非按媒体格式归档"（skills/media-ingest/SKILL.md）与media/youtube/、media/social/这样的格式前缀路径存在张力。事实上两者并不矛盾，skills/_brain-filing-rules.md 给出了清晰的裁定：

• 对原始摄入（raw ingest），按主要主题归档，media/前缀的格式路径是反模式；
• 对合成输出（synthesis output），即针对单一来源 + 特定读者的"一对一"产物（如 book-mirror 生成的media/books/<slug>-personalized.md），格式前缀路径是受认可的例外（sanctioned exception）。

content-media.md三模式中使用的media/youtube/、media/social/正是这类"单来源、单读者"的合成页面——它们带有 Agent 的专属分析，是 sui generis 的产物。仓库中book-mirror命令（src/commands/book-mirror.ts）同样将输出写到media/books/<slug>-personalized.md，印证了这一归档约定的实现。

3.4 实际运行入口：book-mirror 的工程化启示

对于"PDF/图书 → 大脑页面"这类长文档摄入，仓库提供了工程化的命令级实现gbrain book-mirror（src/commands/book-mirror.ts）。其设计思路可以作为 YouTube/PDF 摄入的参考架构：

• 预提取章节文本 + 上下文 → 按章节扇出（fan-out）N 个只读子 Agent（每个子 Agent 的allowed_tools仅限get_page、search）→ 收集各章节分析 → CLI 在最后以操作员级信任调用一次put_page；
• 这样做的安全收益是：未受信任的 EPUB 内容无法通过提示注入污染任何people/*页面，因为子 Agent 根本没有写权限（src/commands/book-mirror.ts）。

这套"技能准备输入、CLI 作为可信运行时"的分工，正是媒体摄入在长文档场景下的最佳实践模板。

四、模式二：社交媒体帖子束（Social Media Bundles）

第二类模式的洞察是：一条推文不是孤立的文本，而是一个"束"（bundle）。没有上下文线程、引用推文、链接文章和互动数据的推文只是碎片。因此摄入前必须先重建完整上下文：

# PATTERN 2: Social Media Bundles elif media.type == "tweet" or media.type == "social": # Don't just save a tweet -- reconstruct FULL context bundle = { "original": fetch_tweet(url), "thread": reconstruct_thread(url), # quoted tweets, replies "linked_articles": fetch_linked_urls(), # fetch and summarize "engagement": get_engagement_data(), # what resonated } slug = f"media/social/{platform}-{author}-{date}" gbrain put <slug> --content """ # {author}: {topic} {agent_analysis_of_full_bundle} ## Thread {reconstructed_thread} ## Linked Articles {article_summaries} --- ## Raw {original_tweet_text} """ # Extract entities and cross-reference for entity in bundle.mentioned_entities: gbrain link <slug> <entity_slug> gbrain link <entity_slug> <slug>

Bundle 的四个组成要素各有分工：

slug 使用media/social/{platform}-{author}-{date}，随后对 bundle 中每个被提及实体执行双向建链。注意：这里的"实体"不仅指人，也包括公司、产品、概念——与 skills/media-ingest/SKILL.md 中"每个被提及的人与公司都必须反向链接"的 Iron Law 一致（skills/conventions/quality.md："An unlinked mention is a broken brain"）。

五、模式三：PDF 与文档摄入（含 OCR 与长文档策略）

第三类模式处理 PDF 与普通文档，重点解决两个问题：扫描件的 OCR与长文档（图书）的分章处理：

# PATTERN 3: PDFs and Documents elif media.type == "pdf" or media.type == "document": # OCR if needed (scanned PDFs) content = ocr_if_needed(file) or extract_text(file) # For books and long-form: slug = f"sources/{document_slug}" gbrain put <slug> --content """ # {title} **Author:** {author} | **Date:** {date} ## Chapter Summaries {per_chapter_summary} ## Key Quotes - p.{page}: "{quote}" -- {why_it_matters} ## Cross-References {links_to_brain_pages_for_people_and_concepts} --- ## Source {full_text_or_key_sections} """ for entity in document.mentioned_entities: gbrain link <slug> <entity_slug> gbrain link <entity_slug> <slug> # Always sync after ingestion gbrain sync

5.1 长文档的容量策略

原文档将页面结构设计为"摘要在上、源文本在下"：## Chapter Summaries承载逐章摘要，## Key Quotes保留带页码的关键引语，## Cross-References指向大脑中既有的个人与概念页面，## Source只放全文或关键章节。这一点与 skills/media-ingest/SKILL.md 的错误处理规则呼应：

Large content (books > 500 pages):Summarize by chapter; do not attempt to inline the full text. Link to the raw upload.

也就是说，超过 500 页的图书不要尝试内联全文，应逐章摘要并链接到 raw 上传（gbrain files upload-raw），这也正是大小路由（size routing）存在的意义。对于"逐章深度分析"的需求，可直接使用gbrain book-mirror（见 3.4 节）。

5.2 归档位置：sources/的边界

注意模式三的 slug 是sources/{document_slug}，而模式一/二是media/youtube/、media/social/。skills/_brain-filing-rules.md 明确界定了sources/的用途：只存放批量数据导入（API 转储、CSV 导出、快照）、喂养多个页面的原始数据、周期性捕获。而如果内容有明确的主要主题（人物、公司、概念、政策议题），就不应进sources/。

因此sources/{document_slug}适用于"作为原始文档档案"的摄入场景；若文档实质是"关于某人的文章"或"关于某公司的研究报告"，按归档规则应分别归档到people/、companies/等主题目录，并在相关目录间交叉链接。

六、实体传播与时间线：让媒体页面"活"起来

6.1 为什么传播是摄入的完成条件

content-media.md的 Tricky Spots 第 3 条指出：没有反向链接的媒体页面是死档案（dead archive）。一个 YouTube 页面如果没有指向它所提及的人物与公司的反向链接，就没有进入大脑的知识图谱。skills/media-ingest/SKILL.md 的 Phase 4 把这一要求写得更加绝对：

A media item is NOT fully ingested until entity propagation is complete.

即：实体传播完成之前，媒体条目不算完成摄入。Phase 4 的具体步骤是：① 检查大脑是否已有该实体页面；② 若无则创建/丰富（可委托给 enrich 技能）；③ 从实体页面添加指向本媒体页面的反向链接；④ 在实体页面上添加时间线条目。三条模式伪代码末尾的for ... : gbrain link ... / gbrain timeline-add ...循环，正是对这个阶段的逐字实现。

6.2 时间线条目的引文规范

quality.md的引用要求（skills/conventions/quality.md）规定每个事实都要携带内联[Source: ...]引用，媒体场景的引文格式可以是：

• 视频/播客：[Source: YouTube: {url}, YYYY-MM-DD]
• 社交帖子：Source: X/@handle, YYYY-MM-DD
• 网页内容：[Source: {publication}, {URL}, YYYY-MM-DD]

时间线条目位于证据层的最高优先级之下（skills/conventions/quality.md 的优先级：用户直接陈述 > 编译真值 > 时间线条目 > 外部来源），因此它是"原始证据"，而页面上方的 Agent 分析则是"编译真值"——这正是 compiled-truth.md 描述的"上方当前综合、下方只增不改证据"的双区结构在媒体页面的体现。

6.3 双向链接的工程保障

gbrain check-backlinks命令为"双向铁律"提供了兜底工具（src/commands/backlinks.ts）：

gbrain check-backlinks check [dir] # 报告缺失的反向链接 gbrain check-backlinks fix [dir] # 创建缺失的反向链接 gbrain check-backlinks fix --dry-run # 预览修复

它可定期扫描大脑页面、找出"提及了某实体却没有反向链接"的缺口并补齐，是媒体摄入长期运行后的体检与自愈手段。

七、易错点（Tricky Spots）深度解读

content-media.md列出五点易错点，结合仓库文档与实现逐一展开：

1. 永远使用完整转录，绝不用 AI 摘要。YouTube 自动摘要与 AI 摘要会丢失"谁说了什么、确切措辞、语气、以及没说什么"。完整的分说话人转录是证据底座（evidence base），Agent 的分析叠加其上。这与 meeting-ingestion.md 的告诫一致：AI 摘要会幻觉化"框架"（例如虚构"会议决定/达成一致"），转录才是 ground truth。media-ingest技能进一步要求转录以 raw 与可读两种格式保存，并且如果无法获得转录，应在页面中标注[transcript unavailable]，绝不捏造内容（skills/media-ingest/SKILL.md Error Handling）。

2. Agent 自己的分析才是价值，而非复述。原文档的对比极具说服力："The video discussed AI safety"（无用）vs."演讲者就算力扩展提出了一个具体主张，与另一位研究者在 NeurIPS 演讲中的说法矛盾——见 media/youtube/a-researcher-neurips-2025"（有用）。分析必须把新媒体与既有大脑连接起来：结合用户的世界观判断什么重要及为何重要、把关键引语归到具体说话人、指出对既有页面的影响与后续可跟进的角度。

3. 社交媒体是一个束，不是单条推文。没有线程、引用推文、链接文章与互动上下文的推文只是碎片。必须先重建完整上下文再建页面（见第四节）。

4. 交叉引用让媒体页面活起来。提及的每个实体都要有链接与时间线条目。这与 skills/_brain-filing-rules.md 的 Iron Law 完全一致："Every mention of a person or company with a brain page MUST create a back-link...An unlinked mention is a broken brain. The graph is the intelligence."（未链接的提及是损坏的大脑；图谱即智能。）

5. 长期积累下，media/会成长为可搜索的档案。用户消费过的每一个视频、播客、演讲、访谈、文章与推文，都叠加着 Agent 的评论——这就是 memex 全功率运转的样子（"the memex at full power"）。

技能层补充的易错点

skills/media-ingest/SKILL.md 的 Known Pitfalls 还补充了几个媒体摄入特有的坑：

• YouTube 自动字幕会误认专有名词：字幕可能把alice-example听成 "Alise"。创建实体前务必先与既有大脑页面交叉核对，命中既有页面而非新建；
• 对同一来源重复摄入会产生重复：Phase 3 前必须先按源 URL 或文件哈希搜索大脑，命中后询问用户"更新既有页面还是跳过"；
• 图书 OCR 质量参差：扫描 PDF 常出现乱码文本，若可读性 <80% 应向用户标记，而不是摄入垃圾；
• 无说话人分离的多说话人转录价值很低：若无法分离，要显著标注此局限，而不是把所有发言归给一个人；
• 超过 2 小时的音频可能令转录服务超时：必要时先切块再转录。

八、如何验证摄入成功（How to Verify）

content-media.md提供了五步验证清单，这也是媒体摄入模式的"验收测试"。结合 CLI 帮助文本（src/cli.ts），每步对应的具体命令如下：

1. 验证视频页面结构完整。摄入 YouTube 视频后：

gbrain get media/youtube/{slug}

确认页面包含：Agent 的分析（不只是摘要）、带说话人归属的关键引语、完整的分说话人转录。

2. 验证反向链接存在。用gbrain call直接调用get_links工具（call <tool> '<json>'是原始工具调用入口，见 src/cli.ts）：

gbrain call get_links '{"slug": "media/youtube/{slug}"}'

确认每个被提及的人物与公司都有指向其大脑页面的反向链接。也可用gbrain backlinks <slug>查看某个页面的入链（src/cli.ts）。

3. 验证实体时间线已更新。挑一个视频中提及的人物：

gbrain get <person_slug>

确认其时间线出现新条目，引用该视频并给出具体上下文（而不只是"出现在某视频中"）。

4. 验证推文摄入包含完整上下文。摄入推文后，确认页面包含线程上下文、链接文章摘要与实体交叉引用——而不仅是推文文本本身。

5. 验证可搜索性（内容已索引）。用视频中的主题词搜索：

gbrain search "{topic_from_video}"

确认媒体页面出现在搜索结果中（src/cli.ts 的search <query>走 tsvector 关键词搜索；对语义查询可用gbrain query <question>走混合检索）。这一步同时验证了gbrain sync是否正确执行——原文档在三个模式末尾都强制要求sync，因为只有同步后新页面才会立即进入索引。

九、与相邻模式的配合

媒体摄入并非孤立管线，它在 Skillpack 中与多个模式协同：

• meeting-ingestion.md：会议录音的摄入走同一套"完整转录 → Agent 分析 → 实体传播 → 双向建链 → sync"逻辑，且共享"--source是引文而非路由"的语义坑（docs/guides/meeting-ingestion.md#L74）；
• entity-detection.md：负责在对话中捕获实体提及，媒体摄入则在离线侧做同样的实体提取与页面丰富；两者共同支撑"大脑复合增长"；
• enrichment-pipeline.md：实体传播阶段需要创建/丰富实体页面时，media-ingest技能明确委托给 enrich 技能；
• compiled-truth.md：媒体页面"上方分析、下方转录"的结构，正是编译真值 + 时间线双区模式的实例化；
• source-attribution.md：[Source: ...]引文规范贯穿所有媒体页面的事实写入。

在技能路由层面，media-ingest经由 ingest 路由器分发（见 src/core/check-resolvable.ts 中对ingest路由器的注释：它委托给idea-ingest、media-ingest、meeting-ingestion），因此"ingest it into my brain"这类触发词会被正确路由到本文所讲的媒体摄入流程。

结语：媒体摄入的本质

回顾整个模式，content-media.md想传递的最终信息是：媒体摄入的本质不是"存档"，而是"增值"。完整转录提供证据，Agent 分析提供判断，实体传播提供连接，全文索引提供可检索性——四者叠加，才把一个会腐烂的书签变成大脑中一个永久的、被充分引用的节点。正如原文档所言：这才是"memex at full power"。对希望在 gbrain 上构建生产级内容管线的开发者，建议以 skills/media-ingest/SKILL.md 为执行规范、以本文三种模式为流程骨架、以第八节的验证清单为验收标准，从摄入第一条 YouTube 视频开始，让大脑开始自我增殖。

本文基于 docs/guides/content-media.md 编写，属于 GBrain Skillpack 文档体系的一部分。

• 人工智能
• RAG
• Agent 记忆
• MCP 服务
• 知识管理