jasveerai88/podcast-kit

podcast-kit — エージェントスキル

目的

エピソードを公開するということは、いくつかの小さなコピー作業を1つの事実セット（ノート、YouTubeチャプター、Podcasting 2.0チャプターファイル、そしてクリップに値する瞬間の検索）から行うことです。このツールは1つのエピソードJSONを受け取り、これらすべてを生成するため、事実は一度だけ存在すればよいのです。純粋なPython標準ライブラリ、ローカルのみ、エピソードファイルだけを読み取ります。

このツールの正直さの核心： チャプターリストは有効な場合にのみエクスポートされます。プレーヤーは壊れたリストを静かに無視するため、壊れたエクスポートを出力することは何も出力しないよりも悪いのです。また、オーディオグラムスコアは、文字起こしテキストのみから計算された、最初に確認すべき場所のランキングです。瞬間がパフォーマンスするという予測ではなく、計画は決してレンダリングされたオーディオグラムではありません。

使用する場合 / 使用しない場合

使用する場合：

• エピソードが1つのエピソードJSONとして存在する（または書き込める）場合：それを完成させるとは、番組ノート、YouTubeおよびポッドキャストアプリ用のチャプターを作成し、何をクリップするかを決定することを意味します。
• パイプラインがYes/Noのチャプターゲートを必要とする場合：chaptersの終了コード0 = リストが有効でエクスポートが出力にある、終了コード1 = 現状のチャプターを公開しない。
• 編集者が録音全体をスクラブする前に聞く価値のある5つのタイムスタンプを求めている場合。

使用しない場合：

• 文字起こしが必要な場合 — 文字起こしはここへの入力です。最初に文字起こしツールでセグメントを生成してください。
• オーディオやビデオのレンダリングが必要な場合 — audiogram-planは計画（タイムスタンプ + 単語 + 理由）です。それを編集者またはレンダリングツールに渡してください。
• RSS、ホスティング、バッチ処理が必要な場合 — このツールは1度に1つのエピソードファイルを意図的に完成させます。

コマンド

すべてのコマンドはエピソードファイルを位置引数として受け取り、--jsonをサポートします。

# 番組ノート — Markdown（デフォルト）またはプレーンテキスト
python3 src/podcast_kit.py show-notes EPISODE.json \
    [--format md|text]

# チャプターの検証とエクスポート（無効な場合は終了コード1、エクスポートなし）
python3 src/podcast_kit.py chapters EPISODE.json \
    [--format youtube|json|both]

# クリップに値する瞬間のランキング（該当するものがない場合は終了コード1）
python3 src/podcast_kit.py audiogram-plan EPISODE.json \
    [--top 5]

エピソードフィールド：show（省略可）、episode（省略可、整数）、title（show-notesで必須）、published（省略可、そのまま出力）、duration_seconds（chaptersで必須；秒数またはタイムスタンプ文字列）、summary（show-notesで必須）、guests — {"name", "role"?}のリスト、links — {"label", "url"}のリスト、chapters — {"start", "title"}のリスト、transcript — {"start", "end", "speaker"?, "text"}のリスト。タイムスタンプはすべての場所で秒（754）、"M:SS"、"H:MM:SS"を受け付けます。ファイルは読み取りのたびに検証されます。構造上の問題（フィールド欠落、不正なタイムスタンプ、開始前に終了するセグメント、再生時間を超えるセグメント）は、問題のあるチャプターまたはセグメントを特定する終了コード2のエラーです。

チャプター検証（正確）

問題（終了コード1、エクスポートなし）：最初のチャプターが0から始まっていない、開始が前の開始より厳密に後ではない、開始がduration_seconds以上にある（開始がduration − 1は有効）、タイトルが空。

警告（報告されるが、エクスポートは生成される）：チャプターが3つ未満、チャプターが10秒未満。どちらもYouTubeのルールであり、Podcasting 2.0のルールではありません — エクスポートはどちらにせよ有効ですが、YouTubeは無視する可能性があります。

エクスポート：YouTube行はMM:SS タイトル（エピソードが1時間以上の場合はH:MM:SS）。Podcasting 2.0は{"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} — 各チャプターのendTimeは次のチャプターのstartTimeであり、最後のチャプターのendTimeは再生時間です。

オーディオグラムスコア（正確）

文字起こしセグメントごとに、テキストのみから：

• 疑問符：各+2、上限+4
• 数字（数字の連続、例：18、1,900）：各+2、上限+4
• 感嘆符：各+1、上限+2
• 強いフレーズ — 固定リスト "真実は"、"最大の間違い"、"誰も教えてくれない"、"誰もが間違っている"、"決して"、"常に"、"秘密"、"神話"（単語全体、大文字小文字を区別しない）：各+3、上限+6
• セグメント長15〜60秒：+2

下限：セグメントはリストに表示されるために合計5が必要です。順序：スコア降順、同点は最も早い開始順。--top Nでリストを制限（0以下 = すべての該当セグメント）。リストされたすべての瞬間は、実際に見つかったシグナルとともにその理由を出力します — 理由のないスコアはこのツールには存在しません。

出力JSONスキーマ（--json）

共通フィールド：tool（"podcast-kit"）、version、command、episode_file（ファイル名）。

show-notes：title、format（"markdown" または "text"）、notes — テキストビューが出力するものとまったく同じ、レンダリングされたノートの1つの文字列。 chapters：title、duration_seconds、valid（ブール値）、problems（文字列のリスト）、warnings（文字列のリスト）、chapters — 各{start_seconds, start, title, end_seconds, end, length_seconds} — youtube（エクスポートテキスト、無効な場合はnull）、podcasting20（エクスポートオブジェクト、無効な場合はnull）。 audiogram-plan：title、segments_scanned、floor（5）、moments — 各{rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}。該当するセグメントがない場合、momentsは[]であり、noteフィールドが下限に達しなかったことを説明します（終了コード1）。

エラー時は、stdoutは単一のオブジェクト：{"error": "<メッセージ>"}、終了コード2 — --jsonモードでのargparse使用法エラーを含む。プレーンテキストではなく、トレースバックもありません。

終了コード

• 0 — コマンド成功。audiogram-planの場合、少なくとも1つのセグメントが下限を超えました。
• 1 — 発見：chaptersが検証問題を発見（エクスポートは生成されなかった）、またはaudiogram-planがクリップに値するセグメントを発見しなかった。どちらもクラッシュではありません — 発見に基づいて行動してください。
• 2 — エラー：エピソードファイルがないか有効なJSONでない、必須フィールドがない、不正なタイムスタンプ、不正なチャプターまたはセグメント、無効なフラグ。失敗した実行からの出力ファクトを引用してはいけません。

エージェントが尊重すべき制限と正直ルール

• 無効なチャプターは何もエクスポートしません。 chaptersが終了コード1で終了した場合、JSON出力のchapters配列からエクスポートを再構築して公開しないでください — リストされた問題こそが、プレーヤーがそれを無視する理由です。エピソードファイルを修正して再実行してください。
• 警告は問題ではありません。 警告のある有効なリストは公開しても構いません。YouTubeがチャプターを表示しない可能性がある（少なすぎる、または1つが短すぎる）一方で、ポッドキャストアプリでは表示されることを明確に伝えてください。
• スコアは予測ではありません。 瞬間を「テキストシグナルで1位にランク付けされた」と報告し、「最高の瞬間」や「パフォーマンスするクリップ」とは決して言わないでください。ツールは録音を聞くことができません。配信によって低スコアのセグメントが適切なクリップになる可能性があり、計画はそのように述べています。
• audiogram-planからの終了コード1は空のエピソードではありません。 ランク付けされたシグナルを運ぶセグメントがなかったことを意味します。ツールがテキストのみを読み取るという限定条件なしに「良い瞬間がなかった」と報告しないでください。
• 計画はファイルではありません。 audiogram-planはタイムスタンプとテキストを生成します。レンダリングツールが実際に計画からオーディオグラムを作成するまで、オーディオグラムが存在するとユーザーに伝えないでください。
• ローカルのみ：ツールはコマンドラインで指定されたエピソードファイルのみを読み取り、どこにも何も送信しません。