KoroLiu/auto-news-shorts

auto-news-shorts 是做什麼的？

你正在協助使用者（通常是初學者）在自己的電腦上執行此儲存庫。請在儲存庫根目錄中操作。以使用者的語言，用白話解釋每個步驟。

基本規則

• 絕不列印或輸出機密資訊。 API 金鑰應放在 .env 或 config.local.json（兩者皆已加入 .gitignore）。檢查金鑰是否存在時，僅回報「已設定／未設定」，絕不顯示其值。
• 絕不為使用者上傳或發布影片。 本專案刻意不含上傳程式碼。若使用者要求，請引導他們閱讀 docs/publishing-guide.md 並說明帳號風險。除非使用者閱讀後明確堅持，否則請勿撰寫上傳自動化程式。
• 請勿將使用者的私人素材加入 Git： 語音樣本、角色美術、Cookie、runs/ 目錄等。請將這些資料保留在已加入 .gitignore 的資料夾中。
• 優先使用使用者現有的工具：他們的 Python 環境管理工具、他們的瀏覽器。在安裝大型元件（如 CUDA PyTorch 或 TTS 模型）前先取得同意。
• 在聲明前先確認：執行指令並讀取輸出結果。

1. 檢查機器

執行 node -v（需 ≥ 22.9）、ffmpeg -version、ffprobe -version，並找到 Chrome/Edge 與 Python 3。接著：

npm ci
npm run setup

npm run setup 會針對每個項目顯示 ✅/❌。對於每個 ❌，請參閱 docs/setup.md。常見的修正方式：

• ffmpeg 缺失：安裝它，或將建置檔案解壓縮至 tools/ffmpeg/。
• Python 缺失：安裝 Python 3.10+，或在 config.local.json 中將 tts.python 指向現有的 Python 環境。

2. 設定

1. 將 .env.example 複製為 .env，並請使用者將他們的 LLM 金鑰貼入 LLM_API_KEY。請勿自行輸入金鑰。預設的提供商是 DeepSeek。其他相容 OpenAI 的 API 可透過 LLM_BASE_URL / LLM_MODEL 設定；將 LLM_VISION_MODEL 設為該提供商的視覺模型，或留空。
2. 僅在需要機器特定值（路徑、視覺模型、本地 TTS）時，才將 config.local.example.json 複製為 config.local.json。
3. 在 config.json 中，將 channel.name 與 channel.titleSign 設為使用者的頻道。
4. 選用：
   • 透過 OpenCLI 設定 X/Reddit 來源（docs/setup.md#x-and-reddit-sources-opencli）
   • Qwen3-TTS 或 GPT-SoVITS 語音複製（需要 NVIDIA GPU，以及使用者有權使用的語音）
   • 自訂主播角色（docs/custom-host.md，內含權利警告）

3. 製作一集

• 全自動模式：npm run daily -- --auto（新聞）或 npm run weekly -- --auto（GitHub 專案）。
• 需審閱模式：執行 npm run workbench 會開啟 http://127.0.0.1:3220。使用者可在此審閱主題、劇本、語音及預覽畫面。
• 結果位於 runs/<date>-<column>/package/：包含影片、兩張封面圖、metadata.txt。請告知使用者結果位置及各檔案用途。

執行過程可能因以下原因暫停：

• 在某個審閱步驟（status.json 中的 review-* 階段）
• 當某則新聞內容看起來涉及政治（select.politicsFilter）

請告知使用者有什麼正在等待他們處理。請勿繞過這些暫停點。

4. 當發生錯誤時

1. 讀取 runs/<run>/run.log 與 runs/<run>/status.json 的結尾內容。
2. 在 docs/troubleshooting.md 中查詢錯誤症狀。
3. 從失敗的階段恢復執行，而非從頭開始：node src/main.mjs run --column news --from <stage>，其中 stage 可以是 collect、select、enrich、write、voice、render、export 其中之一。
4. 若修改了程式碼，請在事後執行 npm test 與 npm run check。

5. 自訂功能

• 主題規則、新聞數量、畫面文字：config.json → columns.<id>（詳見 docs/configuration.md）。
• 新聞來源：sources.json（詳見 docs/sources.md）。
• 影片版面：remotion/Portrait/*.tsx。在執行完成並產生 public/ep/<run>/ 目錄後，可使用 npm run studio 進行預覽。
• 在使用者發布他們自己的分支前，請執行 npm run audit 並協助將他們的私人詞彙放入 .audit-private.txt。