心音（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（開發）」的規劃。
正式環境建議路徑：
- 建置：
pnpm install --frozen-lockfile && pnpm run build（turbo 依序建置packages/shared／packages/db／apps/api，並產出apps/web的 production bundle）。 - 資料庫遷移：
npx prisma migrate deploy（依DATABASE_URL指向的資料庫套用 遷移；R-5 遷移到 PostgreSQL 後流程相同，只是連線字串換成 postgresql）。 - 啟動：
- 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 一起常駐部署。
- api：
- 程序常駐與重啟：用 systemd unit（或 pm2）分別管理 api／web 兩個
Node 行程，設定
Restart=on-failure；健康檢查沿用GET /health（api）與首頁 200（web），與scripts/dev-restart.mjs開發環境用的 檢查邏輯一致。 - 反向代理／TLS：nginx 或雲端負載平衡器終止 TLS 後轉發到 api／web 對應埠號，對外只曝露 443。
這個路徑刻意不假設 K8s 或容器化，只依賴「Node.js 行程 + systemd + nginx」，
因為這台開發主機本身就是照這個模式跑（pnpm run restart 正是這個模式的
開發期簡化版），移植到正式主機時只是把「用 node 直接跑」換成「用 systemd
管理同一組 node 指令」，中間不需要引入額外的容器化工具鏈。