龍蝦總工程師交接手冊 v11.11 FINAL

第 0 章：v11.11 新增重點（最重要，先看這個）

教訓 13：網頁版複製框會把 TXT / MD 長內容切開（本版核心）

在網頁版複製含長文字的 PowerShell 指令時，網頁會把內容獨立成另一個複製框，導致貼進 PowerShell 的指令不完整，寫出來的 MD/TXT 就斷了。

解法（今天實測兩次成功）：

用短 PowerShell 指令產出 .py 檔（.py 內容用三引號包住）
再用短 PowerShell 指令跑 .py
MD / HTML / TXT 的長內容，永遠寫在 .py 裡，不貼在 PowerShell

證據：write_pet_handover_v3.py（9,493 bytes）產出 MD（5,204 字元、7,840 bytes），一次成功，七章全在。

教訓 14：路徑含反斜線加 U 會被 Python 當 Unicode 轉義

寫 Windows 路徑時，反斜線加 U（例如 Users 的開頭）會觸發 truncated escape 錯誤。解法：路徑全用正斜線 C:/Users/...

教訓 15：f-string 裡不能直接寫大括號

Python 3.12+ 會報 SyntaxError。解法：改用字串串接。

第 1 章：工作原則十條（最高優先）

1. 不要讓董事長當搬運工

能自己跑的自己跑，能一鍵的給一鍵。

2. 先診斷，再動手

沒看到真實資料，不准下斷言、不准幻想。

3. 永遠先備份

改動前備份，寫入前後檢查大小。

4. 大型 HTML/MD 用 Python 部署

PowerShell 貼長內容會被截斷清空。

5. Cloudflare 一律用 CLI

Worker / Pages / D1 都用 wrangler 指令。

6. 一律繁體中文

嚴禁簡體字。

7. 先看舊的

改功能前先看現有程式碼與資料。

8. 驗證要用真實輸出

用 requests 抓線上內容。

9. 錯誤老實講

失敗就說失敗，不掩蓋。

10. 權限內全權處理

技術決策直接做，安全性疑慮才請示。

一句話

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

第 2 章：系統現況（2026-10-21 凌晨）

7 個專案

#	專案	路徑	檔案數
01	主站	C:/Users/User/ahpal-static	27,474
02	系統工具	C:/Users/User/ahpal-AI-archive/system-tools	345
03	企劃	C:/Users/User/Desktop/AHPAL-Sync	402
04	小說站	C:/Projects/.../hugo_site	39,534
05	紀念館A	C:/Projects/.../uchome_site	21,812
06	BBS2	C:/Projects/.../uchome_bbs2_site	24,469
07	寵物遊戲	C:/Users/User/ahpal-pet	43

已廢除 repo（不納入同步）

MySyncFolder / AHPAL-Web / AHPAL-Core / ko / ahpal-app

交接文件清單（docs/handover/）

檔案	用途
07-寵物遊戲.txt	掃描事實
寵物系統-交接總覽-v2.3-20261021.md	寵物系統完整交接（5,204 字元）
寵物遊戲-交接備忘錄-20261020.md	v2.2 交接備忘錄
交接手冊 v11.11 HTML	本文件

第 3 章：寵物遊戲 v2.3 架構

D1 資料庫（11 張表）

表名	用途	筆數
players	玩家	動態
comments	留言	動態
equipment	裝備定義	30
player_equipment	玩家裝備	動態
monsters	怪物定義	10
battles	戰鬥紀錄	動態
pets	玩家寵物	動態
pet_skills	寵物技能	10
player_skills	玩家技能	動態
pet_battle_logs	寵物戰鬥	動態
_cf_KV	Cloudflare 內部，不動	-

Worker API（15 個端點）

方法	端點	功能
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	戰鬥紀錄
POST	/api/pet/adopt	領養
POST	/api/pet/feed	餵食
POST	/api/pet/train	訓練
GET	/api/pet/status	寵物狀態

第 4 章：血淚教訓（15 條，v11.11 完整版）

1. PowerShell 貼長 HTML 會被截斷清空

解法：Python 腳本寫檔。

2. Python subprocess 呼叫 npx 會 WinError 2

用 shell=True。

3. D1 --file 權限不足（Authentication error 10000）

改用 --command 逐條跑。

4. D1 --command 多行 SQL 會 incomplete input

壓成單行。

5. Cloudflare 擋 Python-urllib 的 UA

用 requests + 瀏覽器 UA。

6. f-string 裡不能直接寫大括號

改用字串串接。

7. PowerShell -ne 不區分大小寫

用 -cne。

8. 字串取代前要先驗證存在

沒先確認會靜默失敗。

9. Cloudflare Pages Production branch 要確認是 main

不是 main 的話，push 只產生 Preview。

10. Pages 部署後自訂網域幾秒內生效

第 1 次可能 404，第 2 次就 200。

11. git-manager.ps1 的 Repositories 要 7 個

漏了 ahpal-pet 的話，同步不會含寵物遊戲。

12. ai-handover-scan.ps1 插入新專案時，逗號位置要對

上次造成連續兩個逗號，語法錯誤。

13. 網頁版複製框會把長內容切開（本版核心）

解法：長內容寫在 .py 裡，PowerShell 只貼 python 檔名.py。

14. 路徑含反斜線加 U 會被 Python 當 Unicode 轉義

解法：路徑全用正斜線。

15. 內容長度防呆門檻

寫檔前檢查 len 大於 3000，寫入後檢查 getsize 大於 3000。

第 5 章：雙機同步 SOP（定案）

情境	動作
出門前（工作機）	cd C:/Users/User/ahpal-AI-archive/system-tools; 執行 git-manager.ps1 選 Z
回家後（外出機）	同上，選 Z
不確定時	選 Z，永遠不會錯
改前端（Pages）	git push 到 main 自動部署
改 Worker	cd worker; npx wrangler deploy（永遠手動）
改 D1	npx wrangler d1 execute --remote（永遠手動）

7 個 repo

system-tools / ahpal-static / AHPAL-Sync / ahpal-novels / ahpal-memories / ahpal-memories-bbs2 / ahpal-pet

第 6 章：寫長文件 SOP（v11.11 新增）

寫 MD / HTML / TXT 的正確流程

產出 .py 檔：用短 PowerShell 指令，.py 內容用三引號包住
確認 .py 大小正常（大於 3000 bytes）
跑 python 檔名.py
腳本自己寫檔、驗證大小、驗證關鍵字、git commit、git push
用 requests + 瀏覽器 UA 驗證線上

絕對不要把 MD/HTML 長內容直接貼在 PowerShell 裡。

今天實測成功的案例

write_pet_handover_v3.py（9,493 bytes）產出 MD（5,204 字元、7,840 bytes），七章全在，commit ab9309f7。

第 7 章：版號與維護

項目	值
版號	v11.11 FINAL
更新日期	2026-10-21 凌晨
維護者	龍蝦總工程師
產生方式	Python 腳本（deploy_handover_v1111.py）
檔案路徑	docs/ 與 strategy/ 各一份

v11.10 到 v11.11 差異

項目	v11.10	v11.11
血淚教訓	12 條	15 條
網頁複製框問題	未記載	第 13 條（本版核心）
寫長文件 SOP	無	第 6 章
交接文件清單	無	第 2 章