sharon8811/newsread 產品示範影片

NewsRead README 示範影片

一行指令即可產出標準的示範 mp4 檔案：

.claude/skills/demo-video/scripts/run_demo.sh [output.mp4]
# 預設輸出：docs/assets/newsread-demo.mp4

管線流程：啟動隔離的後端（連接埠 :8010，newsread_test 資料庫）→ 種子化示範內容 → 啟動前端（連接埠 :3010，開發模式）→ 使用系統版 Chrome（無頭模式，注入動畫游標與字幕）錄製腳本化的 Playwright 導覽 → 透過 ffmpeg 轉換為 H.264 mp4 格式。伺服器會在結束時關閉，且只會觸及測試資料庫——使用者位於連接埠 :3000/:8000 的真實 docker-compose 堆疊完全不受影響。

可調整參數：DEMO_SCHEME=dark|light（預設為 dark），DEMO_SPEED=1.15（mp4 中的播放速度倍率），CHROME_PATH（替代瀏覽器執行檔）。

前置需求（此機器上通常都已滿足）

• docker-compose 在連接埠 :5433 上啟動的 Postgres（僅使用 newsread_test 資料庫）
• 已同步 backend/.venv（uv sync），已安裝 frontend/node_modules
• ffmpeg 在 PATH 中，已安裝 Google Chrome
• 網際網路連線——導覽過程會擷取即時 Hacker News 留言、目錄 feed 預覽，以及 picsum 縮圖。離線時影片仍會錄製，但這些區塊的內容會降級。
• 連接埠 8010/3010 空閒；arw worker 不能在測試資料庫上執行（它會嘗試重新整理假的示範 feed——雖然無害但會產生雜訊）。

標準導覽內容（加速前約 80 秒）

1. 載入中的收件匣上顯示標題卡
2. 收件匣滾動——自動閱讀功能會在文章經過時標記為已讀；未讀計數標籤會遞減
3. 主打文章（「SQLite: 比檔案系統快 35%」）——Markdown AI 摘要
4. 相關報導——預先種子化的嵌入向量聚類會產生「同一則故事」與「相關」層級
5. 即時 Hacker News 留言（在真實 HN 討論串上「顯示留言」）
6. 目錄——搜尋「nasa」，開啟 feed 預覽模態框，使用快速設定訂閱
7. 結尾卡

可調整的元件（修改這些以變更示範內容）

• scripts/seed_demo_data.py——示範使用者（demo / demo-pass-1234）、4 個虛構 feed、約 16 篇手寫文章附有 Markdown 摘要、手動製作的 pgvector 嵌入向量（餘弦相似度 ~0.08 →「同一則故事」，~0.50 →「相關」，隨機 ≈ 正交 → 隱藏）。主打文章的 HN 討論串 ID 會透過 Algolia API 即時解析。具有冪等性；拒絕任何不是 newsread_test 的資料庫 URL。
• scripts/record_tour.js——場景列表。會先執行一次不錄製的暖身 pass，讓 Next 開發模式完成編譯並快取圖片，之後才開始錄製。
• scripts/demo_helpers.js——注入的游標/字幕/標題卡覆蓋層，以及類人速度的輸入基本操作。滾動使用真實的滾輪事件，因此 IntersectionObserver 自動閱讀行為與真實使用者操作時一模一樣。
• scripts/convert_to_mp4.sh——webm → H.264/yuv420p/faststart mp4。

驗證結果

在出貨前一定要檢查影片。抽樣檢查影格：

ffmpeg -i docs/assets/newsread-demo.mp4 -vf fps=1/6 /tmp/demo-frames/f%02d.png

並檢視其中幾張——確認字幕清晰可讀、摘要/相關/HN 區塊確實出現、訂閱按鈕已切換為「已訂閱」。如果缺少某個區塊，請檢查錄製器日誌與 $WORK/backend.log（工作目錄會在執行開始時印出）。

放入 README

GitHub 僅能透過其網頁編輯器（在編輯 README.md 時拖放，會產生 github.com/user-attachments/assets/... URL）上傳的 mp4 檔案渲染影片播放器——透過路徑引用的已提交 .mp4 檔案不會內嵌渲染。因此：將完成的 mp4 交給使用者，並告知他們在 github.com 上將其拖入 README。將檔案提交至 docs/assets/ 作為標準副本仍然是可行的。

已知注意事項

• 目錄場景中的訂閱會觸發後端對該 feed 的同步真實擷取——請選擇可靠的 feed（導覽會搜尋「nasa」）；等待時間最長 30 秒。
• 絕不要透過 POST /api/feeds 進行種子化——它會同步擷取 feed URL。種子腳本會直接插入 ORM 資料列。
• 如果 /api/ai/status 回報未設定，前端的 AI 摘要 UI 會完全隱藏；run_demo.sh 會匯出一個預設的 NEWSREAD_OPENAI_API_KEY 佔位符以使其正常顯示。實際上從不會呼叫任何 LLM：摘要已預先填好，而摘要端點會在摘要存在時短路回傳。
• 種子化向量的 model 標籤必須與伺服器的 NEWSREAD_OPENAI_EMBEDDING_MODEL 一致——run_demo.sh 會為兩個程序匯出此變數；請勿在使用與伺服器不同的環境變數下執行種子腳本。