media-ingest

媒体导入 Skill

将视频、音频、PDF、书籍、截图和 GitHub 仓库内容导入到知识库（brain）中。

归档规则： 在创建任何新页面之前，请先阅读 skills/_brain-filing-rules.md。

输入

参数	是否必填	说明
source	是	URL、文件路径或已上传文件的引用
title	否	覆盖标题（省略时自动检测）
target_slug	否	覆盖页面 slug（省略时自动生成）

约定

本 skill 保证：

• 每个导入的媒体条目都有一个包含分析内容的知识库页面（而不仅仅是转录文本堆砌）
• 转录文本（视频/音频）同时以原始格式和便于阅读的格式保存
• 实体提取：提及的每个人物和公司都会建立反向链接
• 通过 gbrain files upload-raw 保留原始源文件
• 按主要主题而非媒体格式归档

约定： 有关 Iron Law 反向链接的说明，请参阅 skills/conventions/quality.md。

每当提及一个已有知识库页面的人物或公司时，都必须创建一条反向链接。

阶段

阶段 1：识别格式并获取内容

格式	操作
YouTube/视频 URL	获取转录文本（Whisper、转录服务或字幕）
音频文件	使用可用的 STT 服务进行转录
PDF	提取文本（如有需要使用 OCR）
书籍 PDF	提取文本，识别章节/小节
截图/图片	通过视觉模型进行 OCR，提取文本和实体
GitHub 仓库	克隆，阅读 README 和关键文件，总结架构

阶段 2：上传原始源文件

保存原始文件以便溯源：gbrain files upload-raw <file> --page <slug>

阶段 3：创建知识库页面

按主要主题（而非格式）归档。使用以下模板：

# {Title}

**Source:** {URL or file path}
**Format:** {video/audio/PDF/book/screenshot/repo}
**Created:** {date}

## Summary
{Key points, not a transcript dump}

## Key Segments / Highlights
{For video/audio: timestamped highlights. For books: chapter summaries.}

## People Mentioned
{List with links to brain pages}

## Companies Mentioned
{List with links to brain pages}

阶段 4：实体提取与传播

对于提及的每个人物和公司：

1. 检查知识库中是否已有对应页面
2. 如需要则创建/补充（委托给 enrich skill）
3. 在实体页面上添加指向本媒体页面的反向链接
4. 在实体页面上添加时间线条目

只有完成实体传播后，媒体条目才算完整导入。

阶段 5：同步

运行 gbrain sync 更新索引。

输出格式

创建的知识库页面包含摘要、要点和实体交叉链接。向用户报告： "已导入 {title}：检测到 {N} 个实体，更新了 {N} 个页面。"

错误处理

• 转录失败： 如果 STT 或字幕不可用，请在页面中标注 [transcript unavailable]，并基于现有元数据继续处理。切勿捏造内容。
• 重复检测： 创建页面之前，请在知识库中搜索源 URL 或文件哈希。如果已存在，请询问用户是更新现有页面还是跳过。
• OCR/音频部分失败： 用 [inaudible] 或 [illegible] 标记不清晰的片段。切勿猜测专有名词。
• 大型内容（超过 500 页的书籍）： 按章节进行摘要；不要尝试内嵌全文。请链接到原始上传文件。
• 重试策略： 遇到临时性 API 故障（网络、超时）时重试一次。遇到认证失败时立即中止。

常见陷阱

1. YouTube 自动字幕会误识别专有名词。 在创建新页面之前，务必将实体名称与已有知识库页面进行交叉比对。如果字幕将名称识别错误（例如，讨论的是 alice-example 时字幕写成 "Alise"），应匹配到已有的 alice-example 页面，而不是新建页面。
2. 对同一源重复执行导入会产生重复项。 在阶段 3 之前，务必检查知识库中是否已有相同源 URL 的记录。
3. 书籍 OCR 质量差异很大。 扫描版 PDF 常出现乱码文本。如果 OCR 可读率低于 80%，应告知用户，而不是导入垃圾内容。
4. 没有说话人分离的视频转录价值较低。 如果存在多个说话人但没有可用的说话人分离功能，应醒目地注明此限制，而不是将所有发言都归到同一人名下。
5. 超过 2 小时的大型音频文件可能导致转录服务超时。 如有需要，请在转录前将其切分为若干片段。

失败时如何处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循 agent operator protocol。针对本技能的具体说明如下：

• 转录失败：写入 [transcript unavailable]，并继续处理元数据；绝不编造内容。
• 临时性 API 故障（网络、timeout、rate_limited）：重试一次。若出现认证失败，则中止并告知用户缺少哪个提供商密钥。
• file_upload 被拒绝（大小超限、路径位于允许的根目录之外）：告知用户原始文件未被存储，并在页面中保留一个指向该文件的指针。

反模式

• 直接转存原始转录内容而不做分析
• 跳过实体提取（“我稍后单独处理”）
• 按格式归档原始导入（例如把所有视频放进 media/videos/），而不是按主题归档。注意：对于合成的独一无二输出，例如 book-mirror 的 media/books/<slug>-personalized.md，按格式前缀的路径 media/<format>/<slug> 是被认可的。该反模式针对的是原始导入，而非独一无二的合成内容。参见 skills/_brain-filing-rules.md 中的“认可的例外：合成输出属于独一无二内容”。
• 不保留原始源文件
• 创建没有实质内容的占位页面