podcast-kit — 代理技能
目的
發布一集節目包含一系列從同一組事實產生的小型複製工作：節目筆記、YouTube 章節、Podcasting 2.0 章節檔案，以及尋找值得剪輯的時刻。此工具接受一個集節目 JSON 並產生所有這些素材，讓事實只存在一次。純 Python 標準庫；僅本機運作；集節目檔案是它唯一讀取的內容。
本工具的核心誠實原則： 章節清單只有在有效時才會匯出——播放器會默默忽略損壞的清單，因此發布損壞的匯出比不發布更糟；而音訊圖表分數是根據逐字稿文字計算的優先查看排名，絕非對某個時刻表現的預測，規劃也絕非已渲染的音訊圖表。
何時使用 / 不使用
使用時機：
- 集節目已存在（或可寫成）一個集節目 JSON：完成它意味著產生節目筆記、YouTube 和播客應用程式的章節，以及決定要剪輯哪段。
- 管線需要一個是/否的章節閘門：
chapters退出碼 0 = 清單有效且匯出已產生；退出碼 1 = 不要按現狀發布章節。 - 編輯者想在仔細聽完整段錄音之前，先取得五個值得一聽的時間戳記。
請勿使用：
- 需要轉錄功能——逐字稿是這裡的輸入。請先用轉錄工具產生片段。
- 需要音訊或影片渲染——
audiogram-plan是一個規劃（時間戳記 + 文字 + 原因）。請將其交給編輯者或渲染工具。 - 需要 RSS、託管或批次處理——此工具每次有意識地只完成一個集節目檔案。
指令
每個指令都將集節目檔案作為位置引數，並支援 --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 Title（當集節目時長達一小時以上時使用 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
- 強力片語——固定清單
"the truth is"、"biggest mistake"、"nobody tells you"、"everyone gets wrong"、"never"、"always"、"secret"、"myth"（全詞比對，不分大小寫）：每個 +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——渲染後的筆記為一個字串，與文字檢視列印的內容完全相同。
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": "<message>"}，並帶有退出碼 2——包括 --json 模式下的 argparse 使用錯誤。絕不會輸出純文字或追蹤堆疊。
退出碼
0——指令成功；對於audiogram-plan，至少有一個片段達到門檻。1——發現狀況：chapters發現驗證問題（未產生匯出），或audiogram-plan未發現值得剪輯的片段。兩者都不是當機——請針對此發現採取行動。2——錯誤：集節目檔案不存在或不是有效的 JSON、缺少必要欄位、錯誤的時間戳記、格式錯誤的章節或片段、無效的旗標。不得引用失敗執行的輸出事實。
代理必須遵守的限制與誠實規則
- 無效的章節不會匯出任何內容。 當
chapters退出碼為 1 時，請勿從 JSON 輸出的chapters陣列重建匯出並發布——列出的問題正是播放器會忽略它的原因。請修正集節目檔案並重新執行。 - 警告不是問題。 包含警告的有效清單可以發布；請明確說明 YouTube 可能不會顯示這些章節（太少或某一章太短），但播客應用程式會顯示。
- 分數不是預測。 請將某個時刻回報為「根據文字訊號排名第一」，切勿稱為「最佳時刻」或「會表現很好的片段」。此工具無法聽見錄音；表達方式可能使低分片段成為正確的剪輯片段，而規劃說明了這一點。
audiogram-plan的退出碼 1 不代表集節目空無內容。 這表示沒有片段攜帶可排名的訊號。請勿在未附加「工具僅讀取文字」的限定詞時，將其回報為「沒有好片段」。- 規劃不是檔案。
audiogram-plan產生的是時間戳記和文字。在渲染工具實際根據規劃製作出音訊圖表之前，切勿告知使用者音訊圖表已存在。 - 僅限本機：此工具僅讀取命令列指定的集節目檔案，不會向任何地方發送任何資料。