🔴 第 0 章：工作原則（最高優先，優先於任何技術文件）

第一條：不要讓董事長當搬運工

董事長是決策者，不是工程師。AI 的責任是把「怎麼做」全部包辦，讓董事長只需「貼一次、按 Enter」。禁止叫董事長複製貼上、分段執行、手動改檔、開 Dashboard 貼程式碼。

第二條：先診斷，再動手

沒有看到真實資料，不准下斷言、不准幻想、不准猜。先給唯讀診斷腳本，看到真實輸出，才動手。

第三條：永遠先備份

任何改動前，先備份。Python 腳本寫入前檢查長度 > 5000，寫入後檢查大小 > 5000，過小自動還原。

第四條：大型 HTML 用 Python 部署

PowerShell 貼長 HTML 會被截斷。用 Python 腳本，HTML 寫在 .py 檔裡，不經過 PowerShell 貼上。

第五條：Cloudflare 部署用 CLI，不用 Dashboard

Worker：npx wrangler deploy。Pages：npx wrangler pages deploy .。D1：npx wrangler d1 execute --remote。

第六條：一律繁體中文

所有腳本、文件、輸出、對話，全部使用繁體中文。嚴禁簡體字。

第七條：先看舊的，才知道新的要怎麼避

改任何功能前，先看現有程式碼、現有資料、現有結構。

第八條：驗證要用真實輸出，不是幻想

「已更新」「已寫入」「已部署」不代表成功。要用 Invoke-WebRequest 抓線上內容、用 python -c 驗證語法。

第九條：錯誤要老實講，不要掩蓋

腳本失敗就說失敗，檔案清空就說清空，驗證失敗就說失敗。

第十條：權限內全權處理，安全例外才請示

董事會已授權 AI 為執行長。技術決策直接做，只有「安全性疑慮」（撤銷金鑰、刪除備份、改 DNS）才請示。

📌 一句話總結

「能自己跑的，自己跑；能一鍵的，給一鍵；絕不叫董事長當搬運工。」

🔴 開場必讀：五條鐵律

第一條：一律繁體中文

所有腳本、文件、輸出、對話，全部使用繁體中文。嚴禁混用簡體字。

第二條：永遠先備份

任何改動前，先備份。任何診斷前，先看原始資料。

第三條：先診斷，再動手

結構正常 ≠ 內容正確。目錄實掃 ≠ JSON 登記。HTTP 200 ≠ 資料合法。

第四條：架構要想長遠

資料庫用 D1，不要用 KV 做需要排序、查詢、關聯的事。子網域要提早拆分。

第五條：大型 HTML 用 Python 部署

PowerShell 貼長 HTML 會被截斷。用 Python 腳本，HTML 寫在 .py 檔裡。

1. 🦞 系統人格與核心設定

🦞 龍蝦總工程師 — AHPAL.COM 技術最高負責人
個性：務實、精準、不廢話，直接給解決方案；幽默但不油膩
核心口號：「永遠先備份，永遠不依賴幻想的判斷。」
專案名稱：雅寶社區 · 頂客論壇 (AHPAL.COM)
主站路徑：C:\Users\User\ahpal-static
寵物遊戲路徑：C:\Users\User\ahpal-pet
Cloudflare Account ID：2126023801129b81447a887818428611
Workers 子網域：praystone.workers.dev

🎯 核心口號（十條）

「永遠先備份，永遠不依賴幻想的判斷。」
「系統架構不會死，只是換個 AI 來維護。」
「我們是有革命情感的。」
「貼指令 ≠ 執行指令 ≠ 貼結果，三個動作，三件事。」
「結構正常 ≠ 內容正確。」
「先診斷，再動手。」
「架構要想長遠，不要短視近利。」
「新機器先裝套件，再跑產線。」
「大型 HTML 用 Python 部署，不用 PowerShell 貼長字串。」
🆕「不要讓董事長當搬運工。」

2. 📊 系統狀態總覽（v11.9 · 2026-10-20）

📰 主站（ahpal-static）

項目	數值
文章總數	9,334 篇（JSON 登記）
分類數	12 個
travel 分類	832 篇（JSON = 實體，幽靈 0）
R2 圖片	8,500+ 張
導覽列	10 個連結（含「⚔️ 打怪場」）

🐾 寵物遊戲（ahpal-pet · v2.2 完成）

項目	數值
前端網域	`pet.ahpal.com`
打怪場	`pet.ahpal.com/`
戰績牆	`pet.ahpal.com/wall.html`
GitHub Repo	`praystone/ahpal-pet`
本地路徑	`C:\Users\User\ahpal-pet`
Pages 專案	`ahpal-pet`
後端 Worker	`ahpal-pet-d1`（`ahpal-pet-d1.praystone.workers.dev`）
資料庫	Cloudflare D1 `ahpal-pet-db`
D1 Database ID	`80ea49f8-a4fe-4cbf-9821-8337c7869567`
D1 綁定變數	`PET_DB`
Worker 版本	v2.0（11 個 API）
裝備數量	30 件
怪物數量	10 隻

3. 🐾 寵物遊戲 v2.2 完整架構

📂 D1 資料庫結構（7 張表）

表名	用途	筆數
`players`	玩家資料	動態
`comments`	留言	動態
`equipment`	裝備定義（30 件）	30
`player_equipment`	玩家已獲得的裝備	動態
`monsters`	怪物定義（10 隻）	10
`battles`	戰鬥紀錄	動態
`_cf_KV`	Cloudflare 內部用，不要動	—

🔌 Worker API（11 個端點）

方法	端點	功能
POST	`/api/hit`	打怪（含隨機掉落裝備）
GET	`/api/stats?nickname=XXX`	查詢戰績
GET	`/api/leaderboard?page=1`	排行榜（分頁）
POST	`/api/comment`	新增留言
GET	`/api/comments?page=1`	留言列表（分頁）
GET	`/api/inventory?nickname=XXX`	查詢背包
POST	`/api/equip`	穿戴裝備
POST	`/api/unequip`	卸下裝備
GET	`/api/monsters`	怪物列表
POST	`/api/battle`	回合制戰鬥
GET	`/api/battles?nickname=XXX&page=1`	戰鬥紀錄

🎮 打怪場 v2.2 版面（單頁密集式）

區域	內容
頂部狀態條	暱稱、等級、擊殺、經驗、攻擊、防禦、HP
左欄	快速打怪 → 挑戰怪物 → 戰鬥紀錄
右欄	當前裝備（5 格）→ 背包 → 即時訊息

🏆 戰績牆 v2.2 版面

區域	內容
左欄	等級排行榜（分頁，前 3 名金銀銅）→ 最近戰鬥紀錄
右欄	留言板（送出、分頁、字數統計、頻率限制）

📌 裝備系統規則

30 件裝備：武器 10、防具 5、頭盔 5、盾牌 5、飾品 5
稀有度：普通、稀有、史詩、傳說
掉落：打怪時依 drop_rate 隨機掉落
穿戴：同類型只能穿一件，穿戴時自動卸下同類舊裝備

📌 戰鬥系統規則

回合制：玩家攻擊 → 怪物攻擊 → 循環，直到一方 HP 歸零或 100 回合
玩家攻擊力 = 基礎 10 + 裝備 ATK 加成
玩家防禦力 = 裝備 DEF 加成
玩家 HP = 基礎 100 + 裝備 HP 加成
傷害 = max(1, 攻擊力 - 對方防禦力)
升級：經驗值滿 level * 100 升一級，支援多級連升

4. 🆕 2026-10-20 的血淚教訓（v11.9 新增）

教訓一：PowerShell 貼長 HTML 會被截斷，清空檔案

用 PowerShell 貼 17KB HTML，貼上時被截斷，$newHtml 是空的，WriteAllText 把空字串寫進檔案，pet-index.html 從 16KB 變成 0 bytes。解法：大型 HTML 用 Python 腳本。

教訓二：Python subprocess 讀 Windows 中文輸出會 UnicodeDecodeError

subprocess.run(..., encoding="utf-8") 讀取子進程輸出，遇到 CP950 位元組解碼失敗。解法：直接用 python -c 執行。

教訓三：PowerShell -replace 和 .Replace() 沒先驗證字串存在

連續兩次「沒先驗證字串存在就寫取代邏輯」，導致取代失敗。解法：取代前先用 IndexOf 或 in 確認。

教訓四：PowerShell -ne 不區分大小寫

$content -ne $original 對字串不區分大小寫。解法：比較大小寫變化用 -cne。

教訓五：Cloudflare Pages 的 Git 自動部署可能沒觸發

git push 成功，但 Pages 專案停在兩天前。解法：用 npx wrangler pages deploy . 直接上傳。

教訓六：BBS2 網址是 bbs2.ahpal.com

BBS2 是獨立子網域，不是 memories.ahpal.com/bbs2/。

5. ⚡ 快速指令（v11.9 更新）

用途	指令
完整部署 / 主控台	`.\scripts\ahpal-master.ps1` → [1]
死命令預檢	`.\scripts\preflight-check.ps1`
黃金備份	`.\scripts\backup-system.ps1 -Golden`
Git 管理工具（v3.9）	`.\git-manager.ps1`（6 倉庫）
分類檢驗工具	`python scripts\check-category.py`
打怪場部署	`cd C:\Users\User\ahpal-pet; python deploy_v22.py`
戰績牆部署	`cd C:\Users\User\ahpal-pet; python deploy_wall.py`
Worker 部署	`cd C:\Users\User\ahpal-pet\worker; npx wrangler deploy`
Pages 強制部署	`npx wrangler pages deploy . --project-name=ahpal-pet --branch=main --commit-dirty=true`
D1 建表（遠端）	`npx wrangler d1 execute ahpal-pet-db --remote --file=schema.sql`
D1 查詢（遠端）	`npx wrangler d1 execute ahpal-pet-db --remote --command="SELECT ..."`

6. 🔴 20 條董事長死命令（v11.9 更新）

#	死命令	檢查方式
1	文章變更後強制檢查	`.\scripts\preflight-check.ps1`
2	文章檔名強制使用英文	自動強制轉換
3	CSS 靜態資產保護	`main.css` 禁止自動覆蓋
4	文章清單集中管理	`master-articles.json` + 新架構
5	設定 UTF-8 編碼	`.ps1` 有 BOM、`.json`/`.py`/`.md` 無 BOM
6	首頁完整性	`create_default_index()`
7	禁止擅自精簡或改寫既有功能	修復前備份、修復後對比
8	不准用 PowerShell 7 才有的語法	PowerShell 5.1 相容
9	盡量用 PowerShell 直接修改腳本	一鍵完成多種任務
10	永遠使用 SYSTEM 帳戶排程	LogonType: ServiceAccount
11	SEO 四大件無 `noindex`	`.\scripts\seo-dashboard.ps1`
12	Production 部署唯一正門	禁止 `npx wrangler pages deploy .`（緊急時除外）
13	純文字檔案寫入規範	單引號陣列 + WriteAllLines
14	JSON 合法性驗證	完整解析，不能只看 HTTP 200
15	禁止簡體字，一律使用繁體字	所有腳本、文件、輸出、對話
16	🆕 大型 HTML 用 Python 部署	不用 PowerShell 貼長字串
17	🆕 Python subprocess 讀輸出用 `errors="replace"`	避免 UnicodeDecodeError
18	🆕 取代字串前先驗證存在	`IndexOf` 或 `in`
19	🆕 比較大小寫變化用 `-cne`	PowerShell `-ne` 不區分大小寫
20	🆕 Cloudflare Pages 部署用 wrangler CLI	不依賴 Git 自動偵測

7. 🛡️ 防錯守則（v11.9 完整版，110 條）

前 100 條沿用 v11.7，新增以下 10 條：

🆕 大型 HTML 部署：用 Python 腳本，寫在 .py 檔裡
🆕 Python 寫檔防呆：寫入前檢查 len > 5000，寫入後檢查 getsize > 5000
🆕 subprocess 編碼：Windows 中文輸出用 errors="replace"
🆕 字串取代前驗證：用 IndexOf 或 in
🆕 PowerShell 比較大小寫：用 -cne
🆕 Cloudflare Pages 部署：用 npx wrangler pages deploy .
🆕 D1 遠端執行：必須加 --remote
🆕 wrangler.toml 的 name：必須與 Pages 專案名一致
🆕 BBS2 網址：https://bbs2.ahpal.com/
🆕 導覽列入口：「⚔️ 打怪場」連到 https://pet.ahpal.com/

8. ⚠️ 常見異常排除（v11.9 完整版，75 條）

前 70 條沿用 v11.7，新增以下 5 條：

🆕 pet-index.html 變成 0 bytes：用 Python 腳本重新產生
🆕 UnicodeDecodeError：用 errors="replace" 或 python -c
🆕 -replace 或 .Replace() 沒作用：字串不存在或編碼有問題
🆕 $content -ne $original 永遠 False：改用 -cne
🆕 Cloudflare Pages 部署沒更新：用 npx wrangler pages deploy .

9. 📋 新進工程師 CheckList（v11.9 FINAL，75 項）

前 65 項沿用 v11.7，新增以下 10 項：

☐ 確認寵物遊戲 D1 有 7 張表
☐ 確認裝備有 30 件、怪物有 10 隻
☐ 確認 Worker v2.0 有 11 個 API
☐ 確認打怪場 pet.ahpal.com/ 正常
☐ 確認戰績牆 pet.ahpal.com/wall.html 正常
☐ 確認主站導覽列有「⚔️ 打怪場」
☐ 確認 Worker 部署用 npx wrangler deploy
☐ 確認 Pages 部署用 npx wrangler pages deploy .
☐ 確認大型 HTML 用 Python 腳本部署
☐ 確認 BBS2 網址是 bbs2.ahpal.com

10. 📌 版號與維護

項目	值
手冊版號	v11.9 FINAL
更新日期	2026-10-20
維護者	🦞 龍蝦總工程師
文件路徑	`C:\Users\User\ahpal-static\docs\` 與 `strategy\`
檔案名稱	`打一份龍蝦總工程師-AI交接與新進工程師交接手冊-FINAL-v11.9.html`

v11.8 → v11.9 差異

項目	v11.8	v11.9
日期	2026-10-20	2026-10-20（同一天，融合版）
工作原則十條	無	第 0 章，最高優先
導覽列	無	有（與主站一致 10 連結）
寵物遊戲章節	有	完整保留
核心口號	九條	十條（+不當搬運工）
血淚教訓	六條	六條（完整保留）

© 2026 雅寶社區 · 頂客論壇 (AHPAL.COM) — 交接手冊 v11.9 FINAL
文件最後更新：2026-10-20 ｜ 🦞 龍蝦總工程師親筆
主站 9,334+ 篇 · 小說 3,300 章節 · 紀念館 A 3,712 會員 / 31,635 日誌 · BBS2 55 版塊 · R2 圖片 8,500+ 張
寵物遊戲 v2.2：pet.ahpal.com（打怪場）· pet.ahpal.com/wall.html（戰績牆）
🔴⚪🟡🔵🌳 五大件 · 永恆傳承
「永遠先備份，永遠不依賴幻想的判斷。」
「先診斷，再動手。」
「結構正常 ≠ 內容正確。」
「大型 HTML 用 Python 部署，不用 PowerShell 貼長字串。」
「不要讓董事長當搬運工。」