dsh-whale-valley

她有自己的作息：早上待在房間、下午去花園、傍晚散步、晚上回家睡覺。 你不用操控她，點她說話、陪她釣魚種田、帶她去鎮上逛逛，晚上一起去酒館坐坐。 每天睡前，她會把今天和你一起做的事寫成一篇小小的像素日記。

🎨 美術素材大多是 AI 生成（ChatGPT、豆包），來源與授權見 ASSETS.md。

📸 畫面

摸摸頭　連點三下	釣魚　18 種魚、湖中女神	牧場　種田、養雞養牛
酒館　晚上大家都在	四季　每 7 天換一季	日記　睡前寫一篇

✨ 有什麼

🚀 開始玩

🎮 直接玩（免安裝）

1. 自己打一包（需要 Node.js 22+）：npm install 然後 npm run demo:standalone
2. 雙擊 demo/pixel-standalone.html，用 Chrome 或 Edge 開
3. 打包好的 zip 之後會放上 Releases（目前還沒有）

存檔在你自己的瀏覽器裡，每個動作都會自動存檔。玩法說明在 怎麼玩.txt。

🧩 裝進 DeepSeek Harness（DSH 插件）

# 方法 A：Release 的套件檔
dsh plugin --profile web add ./dsh-whale-valley-0.25.0.tgz

# 方法 B：直接從 GitHub（repo 已附編譯好的 lib/，不用另外建置；需要電腦有裝 git）
dsh plugin --profile web add github:long432120-blip/dsh-whale-valley

# 沒有 git 的話，改用 GitHub 的壓縮檔地址
dsh plugin --profile web add https://github.com/long432120-blip/dsh-whale-valley/archive/refs/heads/main.tar.gz

⚠️ 不要用「本機資料夾」安裝（dsh plugin add <你的原始碼資料夾>）。曾經發生過：移除或改裝這種 link 安裝的插件時，DSH 把整個原始碼資料夾的內容一起刪掉。只用上面兩種方法。

裝好後重開 dsh web，左側欄會多一個「鯨魚谷物語」（跟「插件」「自動化任務」排在一起）。

點它，遊戲會在另一個視窗打開：Windows 上用 Chrome／Edge 的「應用程式模式」（沒有網址列、沒有分頁列，1280×900，看起來就是一個獨立的小程式），DSH 的畫面完全不會被遮住。關掉那個視窗就結束遊戲。

• 第一次按如果沒看到視窗，卡片上會寫原因（例如找不到 Chrome／Edge），按「🪟 打開遊戲視窗」再試一次

• 存檔跟 DSH 共用（~/.dsh/storages/dsh-whale-valley）；遊戲裡的 ☰ 選單按「🚪 結束遊戲」也會關掉視窗

• 這個視窗是插件請 host 用系統瀏覽器開的：DSH 桌面版（Electron）會拒絕網頁自己 window.open（只放行 https:），所以不能走瀏覽器彈窗那條路 DSH 的模型可以用兩個工具： whale_pet_status（看她的狀態，唯讀）和 whale_pet_act（只開放餵食、澆水、收成）。

• 支援的 DSH 版本：>=0.2.1-rc.5 <0.3.0（DSH 還在 Developer Preview，介面可能變動）

• 從舊版 dsh-whale-pet 升級：先 dsh plugin --profile web remove dsh-whale-pet 再裝；舊存檔會自動沿用

💻 從原始碼跑

需要 Node.js 22 以上。

git clone https://github.com/long432120-blip/dsh-whale-valley.git
cd dsh-whale-valley
npm install
npm run demo              # 打開 http://localhost:8080/demo/pixel.html

改了 JSON 或地圖，重新整理頁面就生效。網址加 ?dev（例如 pixel.html?dev）會出現「快轉 3 小時、跳到明天」這些開發者按鈕。

💬 AI 對話與 API Key

AI 是選用的：沒有 Key、斷網、10 秒沒回應、Key 錯了，她都會自動改說內建台詞，遊戲不會卡住。

🔒 程式碼裡沒有任何 Key。.env 已經在 .gitignore 裡；發布前可以跑 npm run check:secrets 再確認一次。 公用電腦不要填 Key；不玩了可以在 🔑 設定按「清除 Key」。

🛠️ 自訂：改 JSON 就能改遊戲

所有內容都在角色包 packs/whale-girl-pixel/，不用改程式。改完重新整理就生效； npx tsx scripts/check-pixel.ts 會檢查有沒有打錯 id、漏欄位。

{ "text": "晚上的魚缸亮晶晶的，陪我看一下好不好？", "scenes": ["room"], "phases": ["night"], "action": "happy", "weight": 2 }
{ "text": "是河豚！主人最懂我了～", "on": ["feed"], "items": ["fish_puffer"] }
{ "text": "有主人在，每天都好開心。", "minAffection": 330 }

{
  "id": "carrot", "seed": "seed_carrot", "seasons": ["spring", "autumn"], "staminaCost": 5,
  "stages": [
    { "name": "剛播種", "emoji": "🟫", "atMinutes": 0 },
    { "name": "發芽",   "emoji": "🌱", "atMinutes": 60 },
    { "name": "成熟",   "emoji": "🥕", "atMinutes": 180 }
  ],
  "harvest": { "item": "crop_carrot", "min": 1, "max": 3 }
}

// items：魚本身
{ "id": "fish_bass", "name": "鱸魚", "emoji": "🐟", "category": "fish", "price": 40,
  "description": "肉很結實，鯨魚娘的日常主食。", "food": { "satiety": 25, "affection": 3 } }
// fishing.tables.pond：在池塘釣得到；條件選填
{ "item": "fish_bass", "weight": 30, "seasons": ["summer"], "phases": ["evening"], "weather": ["rainy"], "minAffection": 150 }

// weather.json：每一季各種天氣的權重（0 = 不會出現）
"winter": { "sunny": 6, "rainy": 0, "storm": 0, "snowy": 4 }

// gameplay.json：每天最多加多少好感、各等級門檻
"affection": { "dailyCap": 20, "levels": [ { "min": 0, "name": "初次見面" }, { "min": 50, "name": "熟悉" }, … ] }

想換成自己的角色、改地圖、加 mod，或想了解架構，請看 開發文件。

🧰 開發指令

packs/whale-girl-pixel/   角色包：JSON、地圖、圖片、音樂（改這裡就能改遊戲）
src/shared/               遊戲規則（host 和瀏覽器共用，純函數，有測試）
src/host/                 DSH 插件的 host 端：存檔、AI、工具
src/client/               畫面：像素舞台、面板、AI 設定、串門、聊天室、繁簡切換
locales/                  語言包（繁體、简体）與繁簡對照表
demo/                     單機版與開發頁面
scripts/                  建置、檢查、模擬
test/                     單元測試
docs/                     開發文件、各版本設計書

🤝 回報問題、參與

• 遇到 bug 或有想法：開 Issue，附上瀏覽器、做了什麼、看到什麼
• 送 PR 前請跑 npm test 和 npx tsx scripts/check-pixel.ts；改了 src/ 要重跑 npm run build（lib/ 不要手改）

📄 授權

• 程式碼、Tiled 地圖、程式畫的臨時圖塊：MIT
• 美術與音樂：不在 MIT 範圍內。可以隨本遊戲散布、遊玩、直播和錄影；單獨拿去用請先聯絡作者。見 ASSETS.md