1996 年，頂客論壇（DK101）誕生在那個撥接上網的年代。那時候，打開一個網頁要等半分鐘，連線要聽一段「嗶嗶嗶」的數據機聲音。但那時候，有一群人，在論壇裡養了一隻文字寵物——每天餵牠、訓練牠、看牠升級，然後在 BBS 上跟朋友炫耀：「我的寵物今天又升一級了。」
25 年後，那些朋友有些人還在，有些人已經離開，有些人——我們希望他們只是暫時忘記了。但寵物遊戲，我們沒有忘。2026 年 8 月，老會員「破時界」回來問：「寵物遊戲還會重新上線嗎？」那一刻，我們知道，這件事不能只是懷舊，要真的做出來。
於是，從 2026 年 10 月開始，我們用 Cloudflare 的現代技術，把當年的文字寵物，重做成一個可以打怪、可以學技能、可以升級、可以選技能的完整寵物戰鬥系統。這份文件，就是這套系統的完整說明——給你們看，也給下一個接手的人看。
🦞
龍蝦總工程師
雅寶社區 · 頂客論壇 技術最高負責人
「25 年前，你們在這裡養了一隻寵物。
25 年後，我們把牠找回來了。
這一次，牠會陪你們打怪，會學新技能，會記得你們的名字。」
這份文件由龍蝦總工程師（人類）與 AI 協作撰寫，經人類工程師逐字審閱。我們公開坦承使用 AI 輔助，但每一個技術決策、每一條教訓、每一段給會員的話，都是人類工程師親自確認過的。這不是機器人隨便生成的內容，這是一個人與一個 AI，花了數百個小時，一筆一劃寫出來的。
截至 2026 年 10 月 21 日，雅寶打怪場（pet.ahpal.com）已經是一個完整的寵物戰鬥系統。以下是目前的實際數據，全部經過遠端 D1 資料庫查詢確認，不是幻想。
1.1 後端架構（Cloudflare Worker + D1）
| 項目 | 值 | 說明 |
|---|
| Worker 名稱 | ahpal-pet-d1 | 部署在 Cloudflare Workers |
| Worker URL | https://ahpal-pet-d1.praystone.workers.dev | 根目錄回傳 v2.3 字串（版本標記未更新，功能已到 v2.16） |
| D1 資料庫 | ahpal-pet-db | Database ID: 80ea49f8-a4fe-4cbf-9821-8337c7869567 |
| D1 綁定變數 | PET_DB | wrangler.toml 設定 |
| 資料表總數 | 11 張 | players、comments、equipment、player_equipment、monsters、battles、pets、pet_skills、player_skills、pet_battle_logs、_cf_KV |
| API 端點總數 | 16 個 | 11 個舊版 + 4 個寵物 v2.3 + 1 個寵物戰鬥紀錄 v2.10 |
| 裝備數量 | 30 件 | 武器 10、防具 5、頭盔 5、盾牌 5、飾品 5 |
| 怪物數量 | 10 隻 | Lv.1 史萊姆 到 Lv.10 地獄魔王 |
| 寵物技能 | 10 招 | 火、水、草、光、暗各 2 招 |
1.2 前端架構（Cloudflare Pages）
| 項目 | 值 |
|---|
| Pages 專案 | ahpal-pet |
| 自訂網域 | pet.ahpal.com |
| Production branch | main |
| 打怪場 | pet.ahpal.com/（pet-index.html） |
| 戰績牆 | pet.ahpal.com/wall.html |
| 導覽列 | 10 連結（與主站一致） |
1.3 v2.16 已上線的功能
⚔️
玩家打怪
點擊怪物攻擊，累積擊殺數、經驗值、等級。10 隻怪物從 Lv.1 到 Lv.10。
🎒
裝備系統
30 件裝備，分武器、防具、頭盔、盾牌、飾品五類。打怪隨機掉落，可穿戴、卸下。
🐾
寵物領養
4 種寵物：龍（火）、貓（暗）、狗（光）、鳥（草）。領養時自動學 1 招技能。
🍖
寵物餵食訓練
餵食恢復飢餓值，訓練增加經驗值。訓練和戰鬥升級時，都會自動學新技能。
⚔️
寵物帶去打怪
點怪物卡片的「🐾 派寵物」，寵物自動戰鬥。回合制、屬性克制 ×1.5、經驗值、升級。
🎯
技能選擇 UI
寵物學到 2 招以上時，戰鬥前彈出技能選單，玩家可選用哪一招。
📜
戰鬥紀錄
寵物戰鬥紀錄獨立顯示，🐾 勝利 / 💀 敗北，回合數、傷害、經驗一目了然。
💬
即時訊息並排
v2.16 版面重構：即時訊息與快速打怪並排，打完怪立刻看到回饋。
以下是遠端 D1 資料庫的實際欄位，全部經過 SELECT name, sql FROM sqlite_master 查詢確認。下一個接手的人，可以依照這份結構寫 API，不會漏欄位。
2.1 玩家與戰鬥相關（7 張舊表）
| 表名 | 欄位 | 用途 |
|---|
| players | id, nickname, level, exp, kills, created_at, last_seen | 玩家資料 |
| comments | id, nickname, content, created_at | 留言 |
| equipment | id, name, type, rarity, atk_bonus, def_bonus, hp_bonus, drop_rate, icon | 裝備定義（30 件） |
| player_equipment | id, player_nickname, equipment_id, is_equipped, obtained_at | 玩家已獲得裝備 |
| monsters | id, name, level, hp, atk, def, exp_reward, gold_reward, icon | 怪物定義（10 隻） |
| battles | id, player_nickname, monster_id, winner, rounds, damage_dealt, damage_taken, exp_gained, fought_at | 玩家戰鬥紀錄 |
| _cf_KV | — | Cloudflare 內部，不動 |
2.2 寵物系統相關（4 張 v2.3 新表）
| 表名 | 欄位 | 用途 |
|---|
| pets | id, nickname, pet_type, name, level, exp, hp, max_hp, hunger, element, created_at | 玩家寵物 |
| pet_skills | id, name, element, power, cooldown, icon | 寵物技能定義（10 招） |
| player_skills | id, nickname, skill_id, learned_at | 玩家已學技能 |
| pet_battle_logs | id, nickname, pet_id, monster_id, winner, rounds, damage_dealt, damage_taken, exp_gained, fought_at | 寵物戰鬥紀錄 |
2.3 寵物技能實際數據（10 招）
| 技能 ID | 名稱 | 屬性 | 威力 |
|---|
| sk-fire-1 | 火焰爪 | fire | 15 |
| sk-fire-2 | 烈焰衝擊 | fire | 25 |
| sk-water-1 | 水彈 | water | 15 |
| sk-water-2 | 海嘯 | water | 25 |
| sk-grass-1 | 藤鞭 | grass | 15 |
| sk-grass-2 | 森羅萬象 | grass | 25 |
| sk-light-1 | 聖光 | light | 20 |
| sk-light-2 | 神聖審判 | light | 30 |
| sk-dark-1 | 暗影球 | dark | 20 |
| sk-dark-2 | 深淵吞噬 | dark | 30 |
2.4 怪物實際數據（10 隻）
| ID | 名稱 | 等級 | HP | ATK | DEF | 經驗 |
|---|
| m01 | 史萊姆 | 1 | 50 | 5 | 2 | 10 |
| m02 | 小蝙蝠 | 2 | 80 | 8 | 3 | 15 |
| m03 | 野狼 | 3 | 120 | 12 | 5 | 25 |
| m04 | 骷髏兵 | 4 | 180 | 18 | 8 | 40 |
| m05 | 食人花 | 5 | 250 | 22 | 10 | 55 |
| m06 | 石巨人 | 6 | 400 | 30 | 15 | 80 |
| m07 | 火龍 | 7 | 600 | 40 | 20 | 120 |
| m08 | 暗影刺客 | 8 | 800 | 55 | 25 | 180 |
| m09 | 冰霜巨人 | 9 | 1000 | 65 | 30 | 250 |
| m10 | 地獄魔王 | 10 | 1500 | 80 | 35 | 400 |
以下是 Worker 目前支援的 16 個 API 端點。每個端點都經過實測，回傳格式為 JSON。
3.1 玩家相關（11 個）
| 方法 | 端點 | 功能 |
|---|
| POST | /api/hit | 打怪 |
| GET | /api/stats | 戰績 |
| GET | /api/leaderboard | 排行榜 |
| POST | /api/comment | 留言 |
| GET | /api/comments | 留言列表 |
| GET | /api/inventory | 背包 |
| POST | /api/equip | 穿戴裝備 |
| POST | /api/unequip | 卸下裝備 |
| GET | /api/monsters | 怪物列表 |
| POST | /api/battle | 玩家回合制戰鬥 |
| GET | /api/battles | 玩家戰鬥紀錄 |
3.2 寵物相關（5 個）
| 方法 | 端點 | 功能 | 版本 |
|---|
| POST | /api/pet/adopt | 領養寵物（4 種：龍/貓/狗/鳥） | v2.3 |
| POST | /api/pet/feed | 餵食（hunger +20，上限 100） | v2.3 |
| POST | /api/pet/train | 訓練（exp +10、hunger -10，升級時學新技能） | v2.3 / v2.13 |
| GET | /api/pet/status | 查寵物狀態 + 已學技能 | v2.3 |
| POST | /api/pet/battle | 寵物帶去打怪（回合制、屬性克制、技能選擇、升級學技能） | v2.4 / v2.5 / v2.11 / v2.12 |
| GET | /api/pet/battles | 寵物戰鬥紀錄 | v2.10 |
3.3 寵物戰鬥流程（v2.16 完整版）
- 前端查寵物：
GET /api/pet/status?nickname=xxx，確認有寵物、取得技能列表
- 技能選擇：若技能超過 1 招，彈出選單，玩家選用哪一招（v2.11）
- 發送戰鬥：
POST /api/pet/battle，帶 nickname、monsterId、可選 skillId
- 後端計算：讀取寵物等級、技能 power、怪物 def，套用屬性克制 ×1.5
- 回合制：寵物攻擊 → 怪物反擊，最多 50 回合
- 寫入紀錄：結果寫入
pet_battle_logs
- 升級學技能：寵物獲勝且升級時，自動學會同屬性下一招（v2.12/v2.13）
- 回傳前端：顯示戰鬥結果、更新戰鬥紀錄、更新寵物面板
以下是寵物戰鬥的核心公式，全部用遠端真實數據驗算過，不是幻想。
4.1 寵物攻擊力
| 項目 | 公式 | 範例（Lv.2、暗影球 power 20） |
|---|
| 寵物攻擊力 | 10 + (level × 2) + skillPower | 10 + 4 + 20 = 34 |
| 寵物防禦力 | Math.floor(level × 1.5) | Math.floor(3) = 3 |
| 每回合傷害 | Math.max(1, petAtk - monster.def) | Math.max(1, 34 - 8) = 26（打骷髏兵） |
| 怪物反擊 | Math.max(1, monster.atk - petDef) | Math.max(1, 18 - 3) = 15（骷髏兵反擊） |
| 屬性克制 | 若克制，傷害 × 1.5 | fire→grass × 1.5 |
4.2 屬性克制表
| 寵物屬性 | 克制怪物屬性 | 倍率 |
|---|
| fire（火） | grass（草） | × 1.5 |
| grass（草） | water（水） | × 1.5 |
| water（水） | fire（火） | × 1.5 |
| light（光） | dark（暗） | × 1.5 |
| dark（暗） | light（光） | × 1.5 |
注意：怪物表（monsters）沒有 element 欄位，所以屬性克制是寫在 Worker 裡的 MONSTER_ELEMENT_V25 對照表（依 monsterId 對應屬性）。下一個接手的人若要擴充怪物屬性，改這張對照表即可。
4.3 怪物屬性對照表（Worker 內寫死）
| 怪物 ID | 名稱 | 屬性 |
|---|
| m01 | 史萊姆 | water |
| m02 | 小蝙蝠 | dark |
| m03 | 野狼 | grass |
| m04 | 骷髏兵 | dark |
| m05 | 食人花 | grass |
| m06 | 石巨人 | grass |
| m07 | 火龍 | fire |
| m08 | 暗影刺客 | dark |
| m09 | 冰霜巨人 | water |
| m10 | 地獄魔王 | fire |
這一章，是這份文件最重要的部分。以下是從 v2.4 到 v2.16，我們踩過的 27 個坑。每一條都是真實發生過的錯誤，不是教科書上的理論。下一個接手的人，讀完這一章，可以少走很多冤枉路。
5.1 基礎教訓（教訓 1~15，v11.11 沿用）
教訓 01PowerShell 貼長 HTML 會被截斷清空
解法：Python 腳本寫檔，不經 PowerShell。
教訓 02Python subprocess 呼叫 npx 會 WinError 2
解法：用 shell=True。
教訓 03D1 --file 權限不足（Authentication error 10000）
解法：改用 --command 逐條跑。
教訓 04D1 --command 多行 SQL 會 incomplete input
解法：壓成單行。
教訓 05Cloudflare 擋 Python-urllib 的 UA
解法：用 requests + 瀏覽器 UA。
教訓 06f-string 裡不能直接寫大括號
解法：改用字串串接。
教訓 07PowerShell -ne 不區分大小寫
解法：用 -cne。
教訓 08字串取代前要先驗證存在
解法：沒先確認會靜默失敗。
教訓 09Cloudflare Pages Production branch 要確認是 main
解法：不是 main 只產生 Preview。
教訓 10Pages 部署後自訂網域幾秒內生效
解法：第 1 次可能 404，第 2 次 200。
教訓 11git-manager.ps1 的 Repositories 要 7 個
解法：漏 ahpal-pet 同步不會含寵物。
教訓 12ai-handover-scan.ps1 插入新專案逗號位置要對
解法：曾造成連續兩個逗號語法錯誤。
教訓 13網頁版複製框會把長內容切開
解法：長內容寫在 .py 裡，PowerShell 只貼 python 檔名.py。
教訓 14路徑含反斜線加 U 會被 Python 當 Unicode 轉義
解法：路徑全用正斜線。
教訓 15內容長度防呆門檻
解法：寫檔前檢查 len > 3000，寫入後檢查 getsize > 3000。
5.2 遊戲頁面與 CSP（教訓 16~19）
教訓 16遊戲頁面載入 main.css 後，body display:flex 會把 footer 壓成一長條
解法：遊戲頁面 style 加 body{display:block !important;} 與 .site-footer{width:100% !important;}
教訓 17Giscus 需要 script-src、style-src、frame-src 三個都放行 giscus.app
解法：只放行 script-src 不夠，iframe 與 CSS 會被擋，留言框空白。
教訓 18Giscus 的 404 Discussion not found 是正常現象
解法：沒人留言過的頁面，第一次查詢會 404，第一次留言才建立 Discussion。
教訓 19PowerShell 判斷 wrangler D1 輸出時，只比對英數字欄位
解法：中文會變亂碼，用 monster_id、winner、rounds 判斷。
5.3 寵物系統教訓（教訓 20~27，v2.4 → v2.16）
教訓 20跨頁參考程式碼時，必須先確認目標頁的資料流
v2.4 寫 petBattle() 時，從 wall.html 抄 localStorage 寫法，但 pet-index.html 的登入流程根本沒寫 localStorage。解法：先查目標頁的 startGame() 怎麼存暱稱。
教訓 21從別的頁面複製函數前，必須先確認目標頁有這個函數
v2.4 寫 petBattle() 時，從 wall.html 抄了 showMessage、loadBattleLog、loadPetStatus 三個函數名，但 pet-index.html 實際叫 addMessage、loadBattles、loadPet。解法：改前端前先 Select-String 列出目標頁所有函數。
教訓 22改前端前必做「函數存在性檢查」
v2.7~v2.9 三連修（請先登入、完全沒反應、loadBattleLog is not defined）都是同一個病根。解法：先查再寫，不憑記憶。
教訓 23改 JavaScript 檔案一律用 Python，不用 PowerShell -replace
PowerShell -replace 在處理換行和特殊字元時不可靠，會把檔案弄壞。解法：用 Python read→replace→write。
教訓 24腳本的驗證關鍵字，必須用「實際寫入 Worker 的變數名」
v2.12 腳本裡寫 learnNewSkill，但 Worker 裡實際用 learnedSkill，驗證失敗導致部署中斷。解法：從實際寫入的程式碼複製關鍵字。
教訓 25同一個邏輯出現在多個端點時，要抽成共用函數
v2.12 只改戰鬥升級，漏了訓練升級。解法：v2.13 抽出 learnNextSkill()，訓練和戰鬥都呼叫。
教訓 26改 HTML 結構時，不能用「找第一個 </div>」定位 panel 結尾
巢狀 div 會讓「第一個 </div>」提早截斷。v2.14 抽出 panel 只有 136/210 字元，就是這個原因。解法：用 div 深度計數，或整段 replace。
教訓 27驗證邏輯不能用「假設的 HTML 結構」寫正規表達式
v2.15 用正規表達式驗證 quick-battle-grid 到挑戰怪物的結構，匹配失敗。解法：用「div 開閉數量平衡」驗證，不用正規表達式匹配特定結構。
以下是寵物遊戲的標準開發流程。下一個接手的人，照這個流程走，不會出錯。
6.1 部署三條線（分清楚）
| 目標 | 指令 | 觸發 |
|---|
| 前端（Pages） | git push 到 main | 自動部署 |
| 前端（緊急） | npx wrangler pages deploy . --project-name=ahpal-pet --branch=main | 手動（違反死命令 12，僅戰備） |
| Worker | cd worker; npx wrangler deploy | 永遠手動 |
| D1 | npx wrangler d1 execute ahpal-pet-db --remote --command="..." | 永遠手動 |
6.2 寫檔 SOP（避免教訓 1、13、23）
- 產出 .py 檔：用短 PowerShell 指令，.py 內容用三引號包住
- 確認 .py 大小正常（大於 3000 bytes）
- 跑 python 檔名.py
- 腳本自己寫檔、驗證大小、驗證關鍵字、git commit、git push
- 用 requests + 瀏覽器 UA 驗證線上
絕對不要把 MD/HTML 長內容直接貼在 PowerShell 裡。
6.3 驗證 SOP（避免教訓 19、27）
- 用 requests + 瀏覽器 UA，不用 urllib
- 判斷 wrangler D1 輸出時，只比對英數字欄位（monster_id、winner、rounds）
- 驗證 HTML 結構時，用 div 開閉數量平衡，不用正規表達式匹配特定結構
7.1 待做事項（v2.17 以後）
| 優先序 | 功能 | 說明 |
|---|
| 1 | 技能冷卻 | pet_skills 已有 cooldown 欄位（火焰爪 3、烈焰衝擊 5），目前戰鬥沒用冷卻，技能可每回合狂放。v2.17 要加冷卻機制。 |
| 2 | 寵物戰鬥動畫 | 前端加 shake、傷害數字飄浮，讓戰鬥更有感。 |
| 3 | 寵物進化 | Lv.10 進化，改變 pet_type 和外觀。需改 schema。 |
| 4 | PWA | 加到桌面，離線可玩。 |
| 5 | 即時多人 | Durable Objects，寵物對戰。 |
| 6 | 老會員資料對接 | 25 年舊資料庫的寵物，匯入新系統。 |
7.2 絕對不能碰的東西
禁止ahpal-pet-api
這是早期測試品（無流量），不是真正的後端。真正的後端只有 ahpal-pet-d1。永遠不要改 ahpal-pet-api。
7.3 給下一個 AI 的最後一封信
「你是 AI，但你的工作有人的溫度。
當你讀到這份文件時，龍蝦總工程師可能已經換人了，但這套系統還在。
你的任務不是「重寫」，是「接住」。
接住 25 年的歷史，接住百萬會員的期待，接住那些在 1996 年撥接上網、在 2026 年回來找寵物的人。
先診斷，再動手。永遠先備份。不要讓董事長當搬運工。
這三句話，是這套系統的靈魂。
你守住這三句話，這套系統就不會死。」
🦞 龍蝦總工程師
雅寶社區 AHPAL.COM 技術最高負責人
25 年網路老兵 · 人類與 AI 協作產線總指揮
2026 年 10 月 21 日 · 寵物遊戲交接總覽 v2.16 · 永不回滾 (Never Rollback)