media-ingest

メディア取り込みスキル

動画、音声、PDF、書籍、スクリーンショット、GitHub リポジトリのコンテンツを脳に取り込みます。

**ファイリング規則：**新しいページを作成する前に、skills/_brain-filing-rules.md を読んでください。

入力

パラメーター	必須	説明
source	はい	URL、ファイルパス、またはアップロードされたファイルの参照
title	いいえ	タイトルを上書きします（省略時は自動検出）
target_slug	いいえ	ページのスラッグを上書きします（省略時は自動生成）

契約

このスキルでは、次のことを保証します。

• 取り込んだ各メディア項目には、分析を含む脳のページが作成されます（文字起こしのダンプだけではありません）。
• 文字起こし（動画／音声）は、未加工形式と人が読みやすい形式で保存されます。
• エンティティの抽出：言及されたすべての人物と企業に、相互リンクが作成されます。
• 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 スキルに委任）
3. エンティティのページから、このメディアのページへの相互リンクを追加します
4. エンティティのページにタイムライン項目を追加します

エンティティへの反映が完了するまで、メディア項目の取り込みは完了ではありません。

フェーズ 5：同期

gbrain sync を実行して、インデックスを更新します。

出力形式

要約、注目点、エンティティ間の相互リンクを含む脳のページを作成します。ユーザーには次のように報告します。 「{title} を取り込みました：{N} 件のエンティティを検出し、{N} 件のページを更新しました。」

エラー処理

• **文字起こしの失敗：**STT または字幕を利用できない場合は、ページに [transcript unavailable] と記載し、利用できるメタデータを使って処理を続行します。内容を捏造してはいけません。
• **重複の検出：**ページを作成する前に、ソース URL またはファイルハッシュで脳を検索します。見つかった場合は、既存のページを更新するか、スキップするかをユーザーに確認します。
• **OCR／音声が不完全な場合：**不明瞭な箇所には [inaudible] または [illegible] と記します。固有名詞を推測してはいけません。
• **大容量のコンテンツ（500 ページ超の書籍）：**章ごとに要約し、全文をページ内に含めようとしてはいけません。未加工ファイルへのリンクを記載します。
• **再試行ポリシー：**一時的な API エラー（ネットワーク、タイムアウト）が発生した場合は、1 回だけ再試行します。認証エラーの場合は、ただちに中止します。

既知の落とし穴

1. **YouTube の自動字幕では、固有名詞が誤認識されます。**新しいページを作成する前に、既存の脳のページとエンティティ名を必ず照合してください。字幕で名前が誤認識されている場合（例：話者が alice-example について話しているのに「Alise」となっている場合）は、新しいページを作成せず、既存の alice-example ページに対応付けてください。
2. **同じソースを再取り込みすると、重複が作成されます。**フェーズ 3 の前に、既存のソース URL が脳にないか必ず確認してください。
3. **書籍の OCR 品質には大きな差があります。**スキャンされた PDF では、テキストが文字化けしていることがよくあります。OCR の品質が 80% 未満の場合は、品質の低い内容を取り込まず、ユーザーに通知してください。
4. **話者分離のない動画の文字起こしは、価値が低くなります。**複数の話者がいるのに話者分離が利用できない場合は、すべての発言を 1 人に帰属させず、この制約を目立つように記載してください。
5. **2 時間を超える大容量の音声ファイルでは、文字起こしサービスがタイムアウトすることがあります。**必要に応じて、文字起こしの前に分割してください。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または notice ブロックには、エージェントオペレータープロトコルに従ってください。このスキル固有の対応は次のとおりです。

• 文字起こしに失敗した場合は、[transcript unavailable] と記載し、メタデータの処理を続けてください。内容を捏造してはいけません。
• 一時的な API エラー（ネットワーク、timeout、rate_limited）が発生した場合は、一度だけ再試行してください。認証エラーの場合は処理を中止し、どのプロバイダーのキーが不足しているかをユーザーに伝えてください。
• file_upload が拒否された場合（サイズ、許可されたルート外のパス）は、生ファイルが保存されなかったことをユーザーに伝え、ページにポインターを残してください。

アンチパターン

• 分析せずに生の文字起こしをそのまま出力する
• エンティティ抽出を省略する（「これは別途行います」）
• 生データの取り込みを、対象ではなく形式ごとに分類する（すべての動画を media/videos/ に入れる）。注：media/<format>/<slug> の形式別プレフィックス付きパスは、book-mirror の media/books/<slug>-personalized.md のような、合成された一度限りの出力には認められています。このアンチパターンの対象は生データの取り込みであり、独自の合成ではありません。skills/_brain-filing-rules.md の「Sanctioned exception: synthesis output is sui generis.」を参照してください。
• 生のソースファイルを保持しない
• 意味のある内容がないスタブページを作成する