龍蝦總工程師 AI 交接手冊 v12.17

📖 這份手冊怎麼用（先讀這一章）

三種人看這份手冊

1. 百萬會員：想知道系統現在能做什麼、怎麼玩。

2. 新 AI / 工程師：想接手這套系統，這裡是入口。

3. 搜尋引擎：想知道這是人做的、有價值的內容。

關鍵設計：這份 HTML 是「目錄」，不是「百科全書」

詳細內容全部在 ahpal-AI-archive\ai交接-<時間戳>\ 的 15 個 .txt。

為什麼？因為 AI 讀 HTML 會撞上下文限制，讀純文字檔更省 token。

先讀這份目錄，再按需讀 .txt，才不會讀到一半被截斷。

📂 第 1 步：交接包在哪

交接包位置：

C:\Users\User\ahpal-AI-archive\ai交接-<最新時間戳>\

裡面有 15 個 .txt，按下面順序讀：

00-總覽.txt → 知道有哪些資料
11-工作SOP-拋射與驗證.txt → 知道怎麼改、怎麼驗、怎麼回滾
12-工具鏈地圖.txt → 知道「做什麼事、先跑哪支」
13-文章生成SOP.txt → 知道怎麼新增文章
09-雙機同步地圖.txt → 知道兩台機器怎麼同步
07-主站交接精華.txt → 人格、口號、15 條死命令
08-腳本清單.txt → 所有 .ps1 / .py 腳本
01-主站.txt ~ 06-紀念館B-BBS2.txt → 各專案現況

📖 第 2 步：15 個 txt 索引（按需讀）

檔案	用途
`00-總覽.txt`	六大專案總覽、15 個 txt 清單、閱讀順序
`01-主站.txt`	主站深度掃描（12 分類、9,811 篇、JSON 對帳）
`02-系統工具.txt`	系統工具
`03-企劃.txt`	AHPAL-Sync
`04-小說站.txt`	Hugo 小說站
`05-紀念館A.txt`	UCHome 紀念館
`06-紀念館B-BBS2.txt`	BBS2 紀念館
`07-主站交接精華.txt`	人格、口號、SKILL 清單、15 條死命令
`07-寵物遊戲.txt`	寵物完整事實（11 表、16 API、戰鬥公式）
`08-腳本清單.txt`	所有 .ps1 / .py 腳本
`09-雙機同步地圖.txt`	7 repo 同步
`10-外部儲存對照表.txt`	圖片在 R2、備份在本機
`11-工作SOP-拋射與驗證.txt`	二十一章（含文章批次生成血淚 SOP）
`12-工具鏈地圖.txt`	8 場景
`13-文章生成SOP.txt`	v2.6 十七章（含 filename 格式檢查）

閱讀順序：00 → 11 → 12 → 13 → 09 → 07 → 08 → 01 → 02~06

🔧 第 3 步：三支核心腳本

腳本	路徑	用途
`dump-d1-schema.ps1`	`C:\Users\User\ahpal-AI-archive\system-tools\dump-d1-schema.ps1`	撈 D1 完整結構
`git-manager.ps1`	`C:\Users\User\ahpal-AI-archive\system-tools\git-manager.ps1`	8 repo 管理
`deploy_handover.py`	`C:\Users\User\ahpal-ai-archive-git\handover\SOP\deploy_handover.py`	產交接手冊 HTML

口訣：「交接先撈 D1，同步用 git-manager，HTML 用 deploy_handover」

🚀 第 4 步：新 AI 第一天 SOP（8 步）

讀這份 HTML（本檔）→ 知道有哪些資料
跑 dump-d1-schema.ps1 → 撈 D1 完整結構（1~2 分鐘）
跑 git-manager.ps1 -QuickStatus → 8 repo 狀態
確認三頁 200：www.ahpal.com / game/ / pet.ahpal.com
確認寵物後端 v2.17
確認 D1 有 11 張表
讀 11-工作SOP → 知道怎麼改、怎麼驗、怎麼回滾
全部確認後，回報「交接完成 [OK]」

鐵律：全部確認後，才開始改東西。

💌 給下一個 AI 的信

核心三句話

「先診斷，再動手。」
「永遠先備份。」
「不要讓董事長當搬運工。」

你是 AI，但你的工作有人的溫度。

當你讀到這份手冊時，龍蝦總工程師可能已經換人了，但這套系統還在。
你的任務不是「重寫」，是「接住」。

接住 25 年的歷史，接住百萬會員的期待。

先診斷，再動手。永遠先備份。不要讓董事長當搬運工。

這三句話，是這套系統的靈魂。
你守住這三句話，這套系統就不會死。

⚠️ 教訓：交接手冊 HTML 要用 deploy_handover.py 產，不要手寫

2026-10-24 實戰教訓

2026-10-24，AI 手動用 $h += '...' 寫了 179 行 HTML，繞過 deploy_handover.py，被董事長糾正。

手寫是錯的，因為：

手寫版沒有「版本疊加」（deploy_handover.py 有 --version 參數）
手寫版沒有「自動 push」（deploy_handover.py 會 git add + commit + push）
手寫版沒有「線上驗證」（deploy_handover.py 會等 40 秒驗證 URL）
手寫版沒有「失敗回滾」（deploy_handover.py 會建議 git reset --hard HEAD~1）
手寫版只寫 docs\，deploy_handover.py 會寫 docs\ + 複製到 strategy\

正確做法：

跑 python deploy_handover.py --version v12.13 --no-deploy（先只產檔）
確認產出的 HTML OK
跑 python deploy_handover.py --version v12.13（正式部署，含 push + 驗證）

SOP 的用處

「SOP 不是參考文件，是操作手冊。它告訴你：這件事有現成的工具，不要自己重寫。」

詳細見 11-工作SOP 第十五章（deploy_handover 版本疊加與備份紀律）。

✅ AI 交接前必讀清單（9 項）

動手前，逐項確認

讀 00-總覽，知道 15 個 txt
讀 11-工作SOP，知道怎麼改、怎麼驗、怎麼回滾
讀 12-工具鏈地圖，知道「做什麼事、先跑哪支」
讀 13-文章生成SOP，知道怎麼新增文章
跑 git-manager.ps1 -QuickStatus，8 repo 綠燈
確認三頁 200：www.ahpal.com / game/ / pet.ahpal.com
確認 D1 有 14 張表
讀 scripts\lib\README-SOP.md，知道三支工具
讀「教訓章節」，知道「手寫 HTML 是錯的」

⚠️ AI 常見錯誤 10 條（從 5 次擦屁股提煉）

這些坑，我踩過，你不要重踩

#	錯誤	正確做法
1	用正則砍多層巢狀	用行號切片
2	只改函數，沒改選單	改之前，全文搜尋
3	桌面捷徑載入舊版	新開 PowerShell，手動執行
4	沒先算索引，用範圍炸	先算 `$startIdx`、`$endIdx`
5	手寫 HTML，繞過 SOP	用 `deploy_handover.py`
6	用 `$total` 當變數，被覆蓋	用 `$totalLines`
7	用當正則，抓不到	用字串比對
8	寫入前沒檢查 `$after.Count`	加防呆「為 0 就中止」
9	沒先確認工具在不在	先 `Test-Path`，再動手
10	改產出，沒改生成器	改生成器，才是永續

🤔 AI 動手前的三問

每次動手前，先問三題

「SOP 上有沒有現成工具？」（如果有，用工具，不要手寫）
「我要改的是『生成器』還是『產出』？」（改生成器，才是永續）
「我有沒有先備份、先診斷、先算索引？」（先診斷，再動手）

三問過了，才動手。