Kokorone/README.md

心音（Kokorone）

以人腦「記憶／情緒／關係」架構為引擎基礎的戀愛陪伴系統。

開發環境

Monorepo 採 pnpm workspace + Turborepo（pnpm-workspace.yaml / turbo.json）。

pnpm install       # 安裝所有 workspace 套件
pnpm run build     # turbo run build（依相依順序建置 shared/db/api，並建置 web 的 production bundle）
pnpm run restart   # 停止舊的 api／web 行程、重建 TypeScript（tsc -b）、重新啟動並等待健康檢查
pnpm run smoke A   # 執行 A 群組冒煙測試；all 表示依序執行 A~R 全部群組

對外指令介面（restart / smoke）維持與遷移前相同的腳本名稱；唯一差異是 pnpm 不會像 npm 一樣吃掉 -- 分隔符，pnpm run smoke -- A 會把字面上的 -- 一起傳給腳本而找不到群組，要執行子指令請直接接在腳本名稱後面 （pnpm run smoke A），不要加 --。

環境變數

複製 .env.example 為 .env 後依需要調整；apps/web/.env.local 另外可設定 NEXT_PUBLIC_API_URL（瀏覽器端呼叫 api 用，預設 http://localhost:3001）。

變數	預設值	說明
DATABASE_URL	file:./prisma/dev.db	Prisma 連線字串。R-5 若遷移到 PostgreSQL，改為 postgresql://user:password@host:5432/db 並將 prisma/schema.prisma 的 provider 由 sqlite 換成 postgresql。
PORT	3001	api（NestJS）監聽埠。
PORT_API / PORT_WEB	3001 / 3100	pnpm run restart（scripts/dev-restart.mjs）啟動 api／web 時使用的埠號。
WEB_ORIGIN	http://localhost:3100	api 的 CORS 允許來源之一；http://localhost:8081（Expo web 開發伺服器）已固定加入，不受此變數影響。
NEXT_PUBLIC_API_URL	http://localhost:3001	web（Next.js）呼叫 api 的位址，build time 注入，正式環境需在建置時設定。
LLM_PROVIDER	mock	mock（模板庫，冒煙測試固定用這個）／claude（呼叫真實 API，見下）。
CLAUDE_BASE_URL	http://localhost:3000/api/v1	OpenAI 相容的 chat completions 端點基底路徑。本專案的部署方式是透過 CLIProxy（分散式派工代理，本機 3000 埠）轉發到真實 Claude，而非直連 api.anthropic.com；若要直連官方 API，把這個值換成 https://api.anthropic.com/v1 並確認金鑰／請求格式相容即可，ClaudeProvider 的呼叫端程式碼不需要改動。
CLAUDE_API_KEY	（無）	呼叫 CLAUDE_BASE_URL 用的金鑰，LLM_PROVIDER=claude 時必填。
CLAUDE_MODEL	claude-sonnet-4-5	要求 Provider 使用的模型名稱；CLIProxy 端需要有對應的 Worker 已註冊、能接這個模型的派工，否則會回報「沒有任何可用的 {模型}-{執行者}-{工具} 組合」。
TTS_PROVIDER	mock	mock／real（P-4 空殼，尚未接上真實供應商，人工確認後才實作）。
PUSH_PROVIDER	mock	mock／expo（Q-3，expo 直接可用，不需金鑰）。

部署路徑

開發環境：以上服務直接用 node／next dev／expo start 跑在同一台 Linux 主機上 （pnpm run restart 一鍵重啟 api／web），不使用 Docker——這是本專案的實際 部署選擇，取代原先技術選型草案中「Docker Compose（開發）」的規劃。

正式環境建議路徑：

1. 建置：pnpm install --frozen-lockfile && pnpm run build（turbo 依序建置 packages/shared／packages/db／apps/api，並產出 apps/web 的 production bundle）。
2. 資料庫遷移：npx prisma migrate deploy（依 DATABASE_URL 指向的資料庫套用 遷移；R-5 遷移到 PostgreSQL 後流程相同，只是連線字串換成 postgresql）。
3. 啟動：
   • api：node apps/api/dist/main.js（讀取上表環境變數）。
   • web：apps/web 下 npx next start -p <PORT_WEB>（讀取建置時注入的 NEXT_PUBLIC_API_URL）。
   • mobile：apps/mobile 透過 eas build 產出實際的 App Store／Google Play 安裝檔，不隨 api／web 一起常駐部署。
4. 程序常駐與重啟：用 systemd unit（或 pm2）分別管理 api／web 兩個 Node 行程，設定 Restart=on-failure；健康檢查沿用 GET /health （api）與首頁 200（web），與 scripts/dev-restart.mjs 開發環境用的 檢查邏輯一致。房間自走（T37 起）需要 api 常駐——排程與 api 同行程 （node-cron，見 apps/api/src/room/room-scheduler.service.ts），api 停機 期間房間不會推進，重啟後只會補推進一次接上目前時間，不會補齊停機期間 錯過的輪數；因排程未加分散式鎖，api 只能起一個實例，多實例會讓同一 房間被重複推進。
5. 反向代理／TLS：nginx 或雲端負載平衡器終止 TLS 後轉發到 api／web 對應埠號，對外只曝露 443。

這個路徑刻意不假設 K8s 或容器化，只依賴「Node.js 行程 + systemd + nginx」， 因為這台開發主機本身就是照這個模式跑（pnpm run restart 正是這個模式的 開發期簡化版），移植到正式主機時只是把「用 node 直接跑」換成「用 systemd 管理同一組 node 指令」，中間不需要引入額外的容器化工具鏈。