Investor RPG 開發環境

第一次啟動

需要 Node.js 18 以上版本。在終端機執行：

cd /Users/daniel/Desktop/finance/app
cp .env.example .env  # 已經有 .env 時不要執行這行
npm install
npm run dev:all

啟動完成後開啟 http://localhost:5173。

npm run dev:all 會同時啟動：

• 前端 Vite：http://localhost:5173
• 後端 API：http://localhost:3000
• API 健康檢查：http://localhost:3000/api/health

按 Ctrl+C 會一起關閉前端與後端。

日常啟動

cd /Users/daniel/Desktop/finance/app
npm run dev:all

不要只執行 npm run dev；那只會啟動前端，沒有後端 API 時頁面資料功能不會運作。

Docker 啟動

若要用接近正式環境的方式啟動：

cd /Users/daniel/Desktop/finance/app
docker compose up --build

完成後開啟 http://localhost:8080。

內容管線（YouTube / HyRead）

知識庫

知識庫分為兩層：

• content/raw/emmy/ — 原始 Obsidian 格式筆記（Markdown + frontmatter）
• data/knowledge.json + data/notes.json — npm run build:knowledge 快照產出

匯入的 YouTube / HyRead 內容會自動寫入 content/raw/emmy/，再透過 build:knowledge 輸出到前端。

前端頁面

路由	頁面	說明
/library	Library	知識總覽（全文檢索 + 類型過濾）
/library/:kind/:id	LibraryDetail	單篇知識全文
/content	ContentManager	內容管理（來源列表 / YouTube 擷取 / HyRead 匯入 / 排程）

Library 和 LibraryDetail 的選單項目在 Chrome.tsx 的「修練 → 知識 · 圖書館」。 ContentManager 在「內容 → 內容 · 管理」。

API 端點

所有端點以 /api/content 為前綴：

方法	路徑	說明
GET	/api/content	列舉內容來源（支援 ?kind= ?status= ?limit= ?offset=）
GET	/api/content/stats	來源統計（by kind / by status）
GET	/api/content/:id	單筆來源詳情
DELETE	/api/content/:id	刪除來源
POST	/api/content/youtube/fetch	擷取 YouTube 影片/播放清單（傳 { url }）
POST	/api/content/youtube/process/:id	用 AI 處理 transcript（傳 { transcript, episode? }）
GET	/api/content/youtube/yt-dlp-status	檢查 yt-dlp 是否可用
GET	/api/content/youtube/local-transcripts	列出本地 ~/youtube_transcripts/ 整理檔
GET	/api/content/hyread/scan	掃描 hyread-tools/output/ 目錄
POST	/api/content/hyread/import	匯入指定書籍（傳 { dir }）
POST	/api/content/hyread/upload	上傳 book.html（傳 { title, html }）
GET	/api/content/schedules	列舉排程
POST	/api/content/schedules	新增排程（傳 { kind, name, url, ... }）
DELETE	/api/content/schedules/:id	刪除排程
POST	/api/content/capture	擴充功能接收端（傳 { kind, url, title, transcript/html, ... }）
POST	/api/content/rebuild-knowledge	觸發 npm run build:knowledge

Chrome 擴充功能

位於 extension/ 目錄。

安裝步驟：

1. 打開 Chrome，前往 chrome://extensions
2. 開啟右上角「開發人員模式」
3. 點選「載入未封裝項目」
4. 選擇 path/to/app/extension/ 資料夾

使用方式：

• YouTube 影片頁：擴充功能會在影片標題下方自動加入「📥 擷取此影片」按鈕，點擊後取得字幕並傳送至後端
• HyRead 閱讀器：擴充功能會在頁面右上角加入「📥 匯入此書」按鈕，點擊後擷取 book HTML 並傳送至後端
• Popup 面板：點擊工具列圖示可查看伺服器狀態、偵測當前分頁類型，也可手動擷取

排程器

伺服器啟動後會自動啟動排程器（預設每 5 分鐘檢查一次排程），在內容管理頁面的「排程」分頁中管理 YouTube 頻道 / 播放清單的定期抓取。