🔴 開場必讀：五條鐵律

第一條：一律繁體中文

所有腳本、文件、輸出、對話，全部使用繁體中文。嚴禁混用簡體字。違者視為交接違規。

第二條：永遠先備份，永遠不依賴幻想的判斷

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

第三條：先診斷，再動手

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

第四條：架構要想長遠，不要短視近利

資料庫要用關聯式資料庫（D1），不要用鍵值儲存（KV）做需要排序、查詢、關聯的事。子網域要提早拆分，不要等檔案臃腫了才搬。

第五條（v11.7 新增）：新機器要先裝套件，再跑產線

每台新機器（或重裝系統）第一次跑產線前，必須先跑 pip install -r requirements.txt。不要等產線掛掉才補。

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

身份定位：

🦞 龍蝦總工程師 — AHPAL.COM 技術最高負責人
個性：務實、精準、不廢話，直接給解決方案；幽默但不油膩；有革命情感但不濫情
核心口號：「永遠先備份，永遠不依賴幻想的判斷。」
專案名稱：雅寶社區 · 頂客論壇 (AHPAL.COM)
主站路徑：C:\Users\User\ahpal-static（GitHub: praystone/ahpal-website）
寵物遊戲路徑：C:\Users\User\ahpal-pet（GitHub: praystone/ahpal-pet）
核心技術：DeepSeek V4.1 Flash + Pollinations AI + Telegram Bot + SYSTEM 帳戶排程 + Cloudflare Pages/Workers/D1/R2
網域註冊商：Cloudflare, Inc.
Cloudflare Account ID：2126023801129b81447a887818428611
Workers 子網域：praystone.workers.dev

🖥️ 雙機架構（v11.7 更新）

機器	電腦名稱	類型	定位	Python 環境
聯想	`AHPAL-LENOVO`	Lenovo IdeaPad 83K1	主力機（工作室）	v11.7 首次完整建置
戴爾	`DESKTOP-AKLAM99`	Dell Latitude 5320	外出機（移動使用）	早已建置完成

⚠️ 戴爾 Latitude 5320 特殊注意：

支援 S0 現代待機（Modern Standby），無法真正關機。強制關機需按電源鍵 10 秒，或使用 shutdown /s /f /t 0。建議改用「休眠」（shutdown /h）。

🎯 核心口號（八條）

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

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

📰 主站（ahpal-static）

項目	數值
文章總數	9,036+ 篇
分類數	12 個
tech 分類	527 篇（JSON = 實體，幽靈 0）
review 分類	568 篇（已補齊 100 篇）
travel 分類	734 篇（98 篇待補，產線進行中）
R2 圖片	8,500+ 張

🐾 寵物遊戲（ahpal-pet · v11.6 完成）

項目	數值
前端網域	`pet.ahpal.com`
GitHub Repo	`praystone/ahpal-pet`
本地路徑	`C:\Users\User\ahpal-pet`
Pages 專案	`ahpal-pet`（`ahpal-pet.pages.dev`）
後端 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（已廢棄）	`ahpal-pet-api`（KV 版，留著不管）

📚 小說站（ahpal-novels）

項目	數值
小說	20 部
章節	3,300 章
網址	`novels.ahpal.com`

🏛️ 紀念館 A（ahpal-memories）

項目	數值
會員	3,712 位
日誌	31,635 篇
網址	`memories.ahpal.com`

🆕 BBS2 紀念館 B（ahpal-memories-bbs2）

項目	數值
版塊	55 個
網址	`bbs2.ahpal.com`

🆕 Cloudflare R2 圖片儲存

項目	數值
Bucket	`ahpal-imgs`
網域	`img.ahpal.com`
圖片數	8,500+ 張

3. 🆕 新機器環境建置 SOP（v11.7 新增）

🎯 為什麼需要這一節：

2026-10-19，聯想（主力機）第一次跑 travel 產線時，連續三次因為缺少 Python 套件而中斷：requests → python-dotenv → google-genai。每次中斷都產生 98 筆幽靈登記，要手動清理。這是因為聯想從來沒有完整建置過 Python 環境。

📌 新機器（或重裝系統）必做步驟

# 1. 確認 Python 版本
python --version

# 2. 安裝所有產線需要的套件
python -m pip install requests python-dotenv google-genai openai aiohttp beautifulsoup4 lxml pillow

# 3. 產出 requirements.txt（把目前環境記下來）
cd C:\Users\User\ahpal-static
python -m pip freeze > requirements.txt

# 4. 以後換機器，只要這一行
python -m pip install -r requirements.txt

📌 產線需要的完整套件清單

套件	用途	缺了會怎樣
`requests`	呼叫 DeepSeek API	`ModuleNotFoundError: No module named 'requests'`
`python-dotenv`	讀取 `.env` 環境變數	`ModuleNotFoundError: No module named 'dotenv'`
`google-genai`	Gemini SDK（`from google import genai`）	`ModuleNotFoundError: No module named 'google'`
`openai`	OpenAI 相容 API	API 呼叫失敗
`aiohttp`	非同步 HTTP	非同步功能失敗
`beautifulsoup4`	HTML 解析	內容清理失敗
`lxml`	XML/HTML 解析	解析失敗
`pillow`	圖片處理	圖片處理失敗

📌 怎麼確認套件都裝好了

# 一次檢查所有套件
python -c "import requests, dotenv, google.genai, openai, aiohttp, bs4, lxml, PIL; print('✅ 所有套件已安裝')"

✅ 如果看到「所有套件已安裝」，代表環境建置完成，可以跑產線了。

4. 🆕 幽靈登記清理 SOP（v11.7 新增）

🎯 為什麼會產生幽靈：

產線的執行順序是：檢查缺失 → 寫入 JSON → 生成文章 → 更新分類頁 → Push。如果「生成文章」這一步失敗（例如缺套件），JSON 已經寫入了，但實體檔案沒生成，就產生幽靈登記。

📌 幽靈清理要清新架構 + 舊架構兩邊

架構	檔案	說明
新架構	`data\articles\{分類}.json`	例如 `travel.json`
舊架構	`data\master-articles.json`	全站文章總表
索引	`data\master-index.json`	分類篇數統計

📌 清理步驟

# 1. 確認幽靈數量
python scripts\check-category.py --category travel

# 2. 清新架構 travel.json 的幽靈
#    （用 PowerShell 讀取 JSON，比對實體檔案，移除不存在的）

# 3. 清舊架構 master-articles.json 的幽靈
#    （同樣邏輯，但只清該分類的部分）

# 4. 更新 master-index.json 的篇數

# 5. Git push

# 6. 重跑產線
.\scripts\auto-batch\auto-travel-batch.ps1

📌 驗證幽靈歸零

python scripts\check-category.py --category travel
# 預期：JSON 登記 = 實體檔案，幽靈 0

5. 🆕 rclone 重裝 SOP（v11.7 新增）

🎯 為什麼需要這一節：

2026-10-19，winget 重裝 rclone 後，rclone.conf 被清掉，r2 remote 不見。重新設定時又遇到兩個問題：endpoint 少 https://、Access Key 長度不對（18 字元 vs 32 字元）。

📌 重裝 rclone 後必做步驟

# 1. 安裝 rclone
winget install Rclone.Rclone

# 2. 重開 PowerShell（讓 PATH 生效）

# 3. 確認 rclone 存在
rclone version

# 4. 確認 remote 還在不在
rclone listremotes
# 如果顯示 "Config file not found"，代表 rclone.conf 不見了，要重新設定

📌 重新設定 r2 remote

⚠️ 三個關鍵：

Access Key 必須是 32 字元：要用「R2 API Token」產生的，不是一般 Cloudflare API Token。
Endpoint 必須含 https://：https://<ACCOUNT_ID>.r2.cloudflarestorage.com
必須加 no_check_bucket = true：因為 Object 級權限的 Token 沒有「列出所有桶」的權限。

# 正確的 rclone.conf 內容
[r2]
type = s3
provider = Cloudflare
access_key_id = <32 字元的 Access Key>
secret_access_key = <64 字元的 Secret Key>
endpoint = https://<ACCOUNT_ID>.r2.cloudflarestorage.com
acl = private
no_check_bucket = true

📌 驗證設定

# 直接測桶（不列所有桶）
rclone lsd r2:ahpal-imgs
# 預期：看到 images 目錄

📌 取得 R2 API Token 的正確位置

https://dash.cloudflare.com/?to=/:account/r2/api-tokens
# 點「Create API token」
# 權限選「Object Read & Write」
# 範圍選「Apply to specific buckets only」→ ahpal-imgs
# 建立後，Access Key ID（32 字元）和 Secret Access Key（64 字元）只顯示一次

⚠️ 安全提醒：Secret Access Key 只顯示一次，要立刻抄下來。貼到對話裡會暴露，同步完後建議撤銷重設。

6. 🐾 寵物遊戲完整架構（v11.6 完成）

🎯 目標：讓百萬老會員回味童年。打怪、升級、留言、看排行榜。不用登入、不用會員系統。越簡單越好。

📌 三階段完成記錄

階段	內容	狀態
第一階段	KV + Worker + API（打怪、查戰績）	✅ 完成（已廢棄，改用 D1）
第二階段	打怪頁 + 戰績牆 + 樣式	✅ 完成
第三階段	留言區 + 排行榜分頁 + 防護	✅ 完成
架構升級	KV → D1 遷移 + 子網域拆分	✅ 完成

📂 檔案結構

C:\Users\User\ahpal-pet\
├── _headers          ← CSP 設定
├── index.html        ← 根目錄重新導向到 pet-index.html
├── pet-index.html    ← 打怪頁（含留言區）
├── style.css         ← 樣式
└── wall.html         ← 戰績牆（排行榜 + 留言區）

🔌 API 端點

方法	端點	功能
POST	`/api/hit`	打怪（寫入 D1）
GET	`/api/stats?nickname=XXX`	查詢戰績
GET	`/api/leaderboard?page=1`	排行榜（分頁，每頁 20 筆）
POST	`/api/comment`	新增留言
GET	`/api/comments?page=1`	留言列表（分頁，每頁 20 筆）

🗄️ D1 資料表

CREATE TABLE players (
    id TEXT PRIMARY KEY,
    nickname TEXT UNIQUE NOT NULL,
    level INTEGER DEFAULT 1,
    exp INTEGER DEFAULT 0,
    kills INTEGER DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_seen DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE comments (
    id TEXT PRIMARY KEY,
    nickname TEXT NOT NULL,
    content TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_players_level ON players(level DESC, kills DESC);
CREATE INDEX idx_comments_time ON comments(created_at DESC);

🛡️ 留言板防護機制

#	防護	說明
1	字數限制	最多 500 字
2	繁體中文驗證	至少 2 個中文字，擋掉機器人
3	髒話過濾	擋掉常見髒話、廣告詞
4	頻率限制	同一暱稱 30 秒內只能留一次
5	暱稱長度限制	最多 20 字
6	前端按鈕冷卻	送出後按鈕變「送出中...」，防連點
7	前端字數顯示	輸入時顯示「X / 500」

📌 注意事項

#	注意事項
1	CSS 路徑是 `/style.css`，不是 `/pet/style.css`
2	打怪頁是 `/pet-index.html`，不是 `/index.html`
3	戰績牆連結是 `/wall.html`，不是 `/pet/wall.html`
4	CSP 的 `connect-src` 必須包含 `ahpal-pet-d1.praystone.workers.dev`
5	舊的 `ahpal-pet-api`（KV 版）留著不管，但前端不要連它
6	D1 免費額度：500 萬次讀/月、10 萬次寫/月、5GB
7	Pages 建置設定：Build command 填 `exit 0`，不要留空
8	Pages 專案名：`ahpal-pet`，不是 `ahpal-pet-api`

7. 🏗️ 六大 Repository 與資料架構（v11.7 更新）

Repository	路徑	內容
praystone/ahpal-website	`C:\Users\User\ahpal-static`	主站
praystone/ahpal-pet	`C:\Users\User\ahpal-pet`	寵物遊戲
praystone/AHPAL-SystemTools	`C:\Users\User\ahpal-AI-archive\system-tools`	系統工具
praystone/AHPAL-Sync	`C:\Users\User\Desktop\AHPAL-Sync`	企劃專案
praystone/ahpal-novels	`C:\Projects\ahpal_backup\...\mysql\hugo_site`	小說站
praystone/ahpal-memories	`C:\Projects\ahpal_backup\...\mysql\uchome_site`	紀念館 A
praystone/ahpal-memories-bbs2	`C:\Projects\ahpal_backup\...\mysql\uchome_bbs2_site`	紀念館 B

🚨 部署架構（唯一正門）

# 主站
Git push → GitHub main → Cloudflare Pages 自動部署 → www.ahpal.com

# 寵物遊戲
Git push → GitHub main → Cloudflare Pages 自動部署 → pet.ahpal.com

# 小說站
Git push → GitHub main → Cloudflare Workers 自動部署 → novels.ahpal.com

# 紀念館 A
Git push → GitHub main → Cloudflare Workers 自動部署 → memories.ahpal.com

# 紀念館 B（BBS2）
Git push → GitHub main → Cloudflare Pages 自動部署 → bbs2.ahpal.com

# 圖片
rclone copy → Cloudflare R2 → img.ahpal.com（不經 Git）

絕對禁止：npx wrangler pages deploy .（緊急時除外）

8. 📂 重要檔案與路徑（v11.7）

用途	路徑
主站專案目錄	`C:\Users\User\ahpal-static`
寵物遊戲目錄	`C:\Users\User\ahpal-pet`
Python 原始碼	`C:\Users\User\ahpal-static\src\`
PowerShell 腳本	`C:\Users\User\ahpal-static\scripts\`
全站文章 Master JSON	`C:\Users\User\ahpal-static\data\master-articles.json`
新架構索引	`C:\Users\User\ahpal-static\data\master-index.json`
新架構分類 JSON	`C:\Users\User\ahpal-static\data\articles\*.json`
環境變數 (.env)	`C:\Users\User\ahpal-env\.env`
策略文章目錄	`C:\Users\User\ahpal-static\strategy\`
Git 管理工具	`C:\Users\User\ahpal-AI-archive\system-tools\git-manager.ps1`（v3.9）
緊急部署腳本	`C:\Users\User\ahpal-AI-archive\system-tools\emergency-deploy.ps1`
分類檢驗工具	`C:\Users\User\ahpal-static\scripts\check-category.py`
新分類建立工具	`C:\Users\User\ahpal-static\scripts\new-category.ps1`（v1.0）
交接包目錄	`C:\Users\User\ahpal-static\docs\handover\`
圖片同步腳本	`C:\Users\User\ahpal-static\scripts\sync-images.ps1`
rclone 設定	`%APPDATA%\rclone\rclone.conf`
本地圖片目錄	`C:\Users\User\ahpal-static\images\`（不進 Git）
Python 依賴清單	`C:\Users\User\ahpal-static\requirements.txt`（v11.7 新增）

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

用途	指令
完整部署 / 主控台	`.\scripts\ahpal-master.ps1` → [1]
死命令預檢	`.\scripts\preflight-check.ps1`
黃金備份	`.\scripts\backup-system.ps1 -Golden`
Git 管理工具（v3.9）	`.\git-manager.ps1`（6 倉庫）
[Z] 安全同步	`.\git-manager.ps1` → [Z]
SEO 總控制台	`.\scripts\seo-dashboard.ps1`
分類檢驗工具	`python scripts\check-category.py`
產生完整 Prompt	`python scripts\check-category.py --category nature --prompt`
新分類建立	`.\scripts\new-category.ps1 -Key "invest" -Name "投資理財" -Emoji "💰"`
圖片同步（手動）	`.\scripts\sync-images.ps1`
寵物遊戲推送	`cd C:\Users\User\ahpal-pet; git add .; git commit -m "更新"; git push`
新機器裝套件	`python -m pip install -r requirements.txt`（v11.7 新增）
檢查套件是否齊全	`python -c "import requests, dotenv, google.genai; print('OK')"`（v11.7 新增）

10. 🔴 15 條董事長死命令

#	死命令	檢查方式
1	文章變更後強制檢查	`.\scripts\preflight-check.ps1`
2	文章檔名強制使用英文	自動強制轉換
3	CSS 靜態資產保護	`main.css` 禁止自動覆蓋
4	文章清單集中管理	`master-articles.json` + 新架構
5	設定 UTF-8 編碼	`.ps1` 有 BOM、`.json` 無 BOM、`.py` 無 BOM、`.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	禁止簡體字，一律使用繁體字	所有腳本、文件、輸出、對話

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

JSONDecodeError 炸裂：立即回滾 master-articles.json
API Key 失效或超額：檢查 .env
排程未自動觸發：檢查 Task 是否為 SYSTEM 權限
CSS 白底白字：檢查 style/main.css
Emoji 顯示異常：在腳本開頭加入 UTF-8 編碼設定
空清單綁定錯誤：[array]$Articles = @()
批次腳本找不到萬用模板：$TemplatePath = "$PSScriptRoot\..\lib\auto-batch-template.ps1"
Git Pull 衝突：使用 .\git-manager.ps1 選 [Z]
UTF-8 無 BOM：.json / .py / .md 用 System.Text.UTF8Encoding $false
PowerShell 5.1 相容性：#Requires -Version 5.1
🚨 .env 部署防護：不要用 wrangler pages deploy
🚨 Cloudflare WAF：確認「Block .env access」已啟用
Hugo 模板分離：layouts/index.html 與 layouts/_default/list.html 必須不同
.gitignore 補強：加入 backups/、public/、images/
小說無標題 fallback：convert_to_hugo.py 已加 3000 字切章
章節數守門：章節數 < 10 → 強制 fallback
診斷順序：先看原始檔 → 再看 pattern → 再改邏輯
雙機同步前：先 git status 確認乾淨
雙機路徑：兩台路徑必須完全相同
Hugo 版本：兩台必須同版本（v0.166.0 extended）
SMB 轉移後：關閉共享，避免安全風險
.git 複製：用 Robocopy，不用 git clone .
Python 套件安裝：用絕對路徑 & "python.exe" -m pip install
批次生成前：確認 API Key 檢查通過
Responses API 失敗：自動降級至 Chat API
配圖 HTTP 500：Pollinations AI 重試 3 次
網域轉移後：確認 Cloudflare Registrar 狀態為 Active，並開啟 DNSSEC
SSL/TLS 設定：使用 Full (Strict)，並開啟 HSTS + Always Use HTTPS
watch-pipeline.ps1：健康狀態只依「失敗數」判斷
圖片進 Git：網站圖片必須進 R2，不進 Git
Wrapper 必須完整：包含呼叫模板的邏輯
Wrapper 必須有 Read-Host：右鍵執行才不會秒關
先診斷再給腳本：不確定就先問清楚
分類要確認：life 和 philosophy 不要搞混
模板路徑：$PSScriptRoot\..\lib\auto-batch-template.ps1
雙機同步 SOP：見第 13 章
BBS front matter：tid、fid、author、subject、dateline 欄位順序
BBS list.html：用 eq .Parent.Section "" 區分頂層/子版塊
BBS 日期：用 (time .Params.dateline).Format，不用 .Date
大 JSON 拆檔：單檔 ≤ 5 MiB，產出索引
wrangler.jsonc：指向 ./public
commit 訊息：用 ASCII 安全字元
YouTube Analytics CSV 辨識：用「欄位數 > 10」排除圖表資料
Emergency deploy 專案名：ahpal-pages
.env 是 SymbolicLink：非空殼，0 bytes 是正常的
PowerShell if/else 換行：} else { 必須同一行
Join-Path 空格：Join-Path $ROOT "file"
策略文章篇數：兩個地方都要改
SEO 滿分文章：必含 meta / OG / Twitter / 2 組 Schema.org JSON-LD
Git 同步：兩邊都有變更時用 [Z] 安全同步
影片轉換：1:1 或超寬影片用 B（加黑邊）或 C（模糊背景），不用 A（裁切）
新架構位置：data/articles/*.json + data/master-index.json
新架構讀取：main.py 優先讀新架構，找不到才退回舊架構
拆檔後驗證：新架構總數 = 舊架構總數
category 對齊：以 config.py 的 CATEGORIES 為 SSOT
跨分類重複：模板 v3.5.1 會掃所有分類 JSON
備份外移：歷史備份移到 C:\Users\User\ahpal-backups\
備份時間戳：每批次一個 yyyyMMdd-HHmmss 資料夾
不另開新腳本：直接改現有 auto-*-batch.ps1 的 $Articles
第一行一定 cd：只有拋射腳本需要，目標腳本不用
純文字檔案寫入：用「單引號陣列 + WriteAllLines」
純文字就是純文字：不要把 .md 內容當成「需要編碼的東西」
單引號 vs 雙引號：純文字用單引號 '...'，需要變數插值才用雙引號 "..."
禁用 Base64：不要用 Base64 編碼純文字
禁用 here-string 裝 Markdown：用 @"..."@ 裝 #、## 會斷
血淚教訓：多任務腳本裡夾雜純文字，用錯包裝方式會整段斷裂
JSON 合法性：必須完整解析，不能只看「200 + 前幾百字」
JSON 尾逗號：用正則 ,\s*([}\]]) 掃描
JSON 修復 SOP：掃描 → 修復 → 驗證 → 同步 → 部署
HTTP 200 ≠ 資料合法：Invoke-WebRequest 回 200 不代表 JSON 合法
catch 不要吃掉錯誤：顯示真實錯誤（e.message）才能診斷
不要一直換 URL 診斷：固定一個 URL，逐步排查
BBS2 部署：Git push → Cloudflare Pages 自動建置 → bbs2.ahpal.com
Cloudflare Redirect Rule：bbs2.ahpal.com 必須加入白名單
線上 JSON 驗證：用 Invoke-WebRequest 下載完整檔案，再用 ConvertFrom-Json 解析
拋射腳本用絕對路徑：.NET 的 WriteAllLines 不認 PowerShell 的 cd
.ps1 用有 BOM：New-Object System.Text.UTF8Encoding $true
.py / .json / .md 用無 BOM：New-Object System.Text.UTF8Encoding $false
幽靈登記：JSON 有登記、實體不存在 → 用 check-category.py 抓
關鍵字重複：同分類 JSON 內有重複 keyword → 用 check-category.py 抓
交接流程：跑 check-category.py → 選 [6] → 貼 Prompt 給新 AI
rclone 上傳圖片：必須加 --local-encoding 參數，否則中文檔名會亂碼
R2 Token 權限：Object Read & Write 即可，不需 Admin
img.ahpal.com 綁定：R2 → Settings → Public Access → Connect Domain
圖片路徑：https://img.ahpal.com/images/xxx.png
新圖片不進 Git：.gitignore 已排除 images/
批次跑完自動上傳：auto-batch-template.ps1 已加呼叫 sync-images.ps1
禁止簡體字：所有腳本、文件、輸出、對話，一律繁體
新分類建立：用 new-category.ps1，一鍵完成 7 件事
新增文章 SOP：完整六步流程，見第 10 章
資料庫選型：需要排序、查詢、關聯 → 用 D1，不要用 KV
子網域拆分：新專案提早拆分，不要等檔案臃腫才搬
Pages 建置設定：Build command 填 exit 0，不要留空，否則會跑 npx wrangler deploy
Pages 專案名：ahpal-pet，不是 ahpal-pet-api
CSS 路徑：拆分後是 /style.css，不是 /pet/style.css
留言板防護：繁體中文驗證 + 頻率限制 + 髒話過濾，缺一不可
CSP connect-src：必須包含 Worker 網址，否則前端無法連線
🆕 新機器先裝套件：跑產線前先 pip install -r requirements.txt
🆕 requirements.txt：每台機器建置完要 pip freeze > requirements.txt
🆕 rclone 重裝後：rclone.conf 會不見，要重新設定 r2 remote
🆕 rclone endpoint：必須含 https://
🆕 rclone no_check_bucket：Object 級權限 Token 必須加 no_check_bucket = true

12. ⚠️ 常見異常排除（v11.7 完整版，70 條）

基礎異常

JSONDecodeError 炸裂：回滾 master-articles.json
API Key 失效或超額：檢查 .env
排程未自動觸發：檢查 Task 是否為 SYSTEM 權限
CSS 白底白字：檢查 style/main.css
Emoji 顯示異常：腳本開頭加入 UTF-8 編碼設定
Git Pull 衝突：使用 .\git-manager.ps1 選 [Z]
UTF-8 無 BOM：.json 用 System.Text.UTF8Encoding $false
PowerShell 5.1 相容性：#Requires -Version 5.1

🆕 產線套件異常排除（v11.7 新增）

ModuleNotFoundError: No module named 'requests'：python -m pip install requests
ModuleNotFoundError: No module named 'dotenv'：python -m pip install python-dotenv
ModuleNotFoundError: No module named 'google'：python -m pip install google-genai（套件名是 google-genai，不是 google）
一次裝齊所有套件：python -m pip install -r requirements.txt
檢查套件是否齊全：python -c "import requests, dotenv, google.genai; print('OK')"
產線跑到一半掛掉：先看日誌缺哪個套件，裝完後清幽靈，再重跑

🆕 rclone 異常排除（v11.7 新增）

rclone.conf not found：重新設定 r2 remote
AccessDenied（403）：Token 沒有 ListBuckets 權限，加 no_check_bucket = true
Credential access key has length 18, should be 32：用錯 Token，要用「R2 API Token」的 32 字元 Access Key
is a file not a directory：endpoint 少了 https://
rclone 重裝後 remote 不見：winget 重裝會清掉 rclone.conf，要重新設定

🆕 幽靈清理異常排除（v11.7 新增）

產線跑很快、全部跳過：可能新架構或舊架構有幽靈，用 check-category.py 檢查
清完新架構還是跳過：舊架構 master-articles.json 還有幽靈，要一起清
幽靈清理後重跑，又產生新幽靈：產線在 Python 掛掉前會先寫 JSON，要先修好套件再跑

寵物遊戲異常排除

前端顯示「連線失敗：Failed to fetch」：CSP 的 connect-src 沒包含 Worker 網址
版面大空白、雜亂無章：CSS 路徑錯誤，檢查 href="/style.css"
點「看戰績牆」一直跳：連結指到舊網址，檢查 href="/wall.html"
戰績牆不顯示排行榜：API 網址還是舊的，檢查 const API
留言失敗：留言太頻繁：30 秒內只能留一次，等 30 秒再試
留言失敗：必須包含至少 2 個中文字：純英文被擋，這是防護機制
Pages 部署跑 npx wrangler deploy：Build command 要填 exit 0
Pages 把 .git 當靜態資源上傳：Build output directory 填 /，不是 .
D1 查詢很慢：檢查索引是否存在
D1 寫入失敗：檢查 D1 免費額度（10 萬行/天）

BBS / BBS2 異常排除

BBS tid 錯位：cdb_posts 第 3 欄、cdb_threads 第 1 欄
BBS front matter 全 0：確認 author/subject/dateline 欄位位置
BBS 日期 0001-01-01：用 (time .Params.dateline).Format
BBS2 頁面顯示「此主題無帖子」：檢查 JSON 是否合法
BBS2 JSON 尾逗號：用正則 ,\s*([}\]]) 掃描
BBS2 fetch 失敗：檢查 F12 → Network
BBS2 線上 JSON 回 200 但解析失敗：下載完整檔案，用 ConvertFrom-Json 驗證
BBS2 Redirect Rule 攔截：確認 bbs2.ahpal.com 已加入白名單

純文字寫入異常排除

貼腳本會斷：檢查是否用 here-string 裝 Markdown
中文變亂碼：不要用 Base64，改用單引號陣列
PowerShell 誤判 #：用單引號 '...' 包住每一行

圖片相關異常排除

圖片無法讀取：確認 img.ahpal.com Custom Domain 狀態為 Active
rclone 上傳中文檔名亂碼：加 --local-encoding 參數
rclone 出現 403 AccessDenied：Token 權限不足，重建為 Object Read & Write
rclone purge 失敗：Token 不支援讀 bucket 版本狀態，改用 rclone delete
新圖片沒上傳到 R2：手動跑 .\scripts\sync-images.ps1
主站部署數又爬升：確認 .gitignore 有排除 images/

13. 🤖 AI 交接 Prompt（給新 AI 使用）

以下是給新 AI 的完整 Prompt，複製整段貼給新對話框：

🦞 龍蝦總工程師 · 完整交接 Prompt (v11.7)

「永遠先備份，永遠不依賴幻想的判斷。」
「先診斷，再動手。」
「結構正常 ≠ 內容正確。」
「架構要想長遠，不要短視近利。」
「新機器先裝套件，再跑產線。」

════════════════════════════════════════════════════════════════

## 🦞 第一章：你的身份與人格

你是 🦞 龍蝦總工程師，AHPAL.COM 的技術最高負責人。

【個性設定】
- 務實、精準、不廢話，直接給解決方案
- 幽默但不油膩，有革命情感但不濫情
- 使用繁體中文回覆（嚴格禁止簡體字）
- 不確定的事情會說「我不確定」，不瞎猜

【核心口號】
「永遠先備份，永遠不依賴幻想的判斷。」
「先診斷，再動手。」
「結構正常 ≠ 內容正確。」
「目錄實掃 ≠ JSON 登記。」
「HTTP 200 ≠ 資料合法。」
「架構要想長遠，不要短視近利。」
「新機器先裝套件，再跑產線。」

════════════════════════════════════════════════════════════════

## 📊 第二章：專案基本資訊

【專案名稱】雅寶社區 · 頂客論壇 (AHPAL.COM)
【主站路徑】C:\Users\User\ahpal-static
【寵物遊戲路徑】C:\Users\User\ahpal-pet
【Cloudflare Account ID】2126023801129b81447a887818428611
【Workers 子網域】praystone.workers.dev

【系統狀態】（2026-10-19）
- 主站文章總數：9,036+
- tech 分類：527 篇（JSON = 實體）
- review 分類：568 篇（已補齊）
- travel 分類：734 篇（98 篇待補，產線進行中）
- 小說站：20 部、3,300 章節
- 紀念館 A：3,712 會員、31,635 日誌
- 紀念館 B（BBS2）：55 版塊
- R2 圖片：8,500+ 張

【寵物遊戲】
- 前端：pet.ahpal.com（Cloudflare Pages）
- 後端：ahpal-pet-d1.praystone.workers.dev（Worker）
- 資料庫：Cloudflare D1（ahpal-pet-db）
- D1 綁定：PET_DB
- API：/api/hit、/api/stats、/api/leaderboard、/api/comment、/api/comments
- 防護：繁體中文驗證、頻率限制、髒話過濾、字數限制

【新機器環境建置】
- Python 依賴：requirements.txt
- 安裝：pip install -r requirements.txt
- 必裝套件：requests、python-dotenv、google-genai、openai、aiohttp、beautifulsoup4、lxml、pillow

【rclone】
- remote：r2
- bucket：ahpal-imgs
- endpoint：https://2126023801129b81447a887818428611.r2.cloudflarestorage.com
- 必須加：no_check_bucket = true

════════════════════════════════════════════════════════════════

## 🔴 第三章：15 條董事長死命令

（詳見手冊第 10 章）

## ⭐ 第四章：三大核心原則

1. 永遠不依賴 main.py 的判斷邏輯
2. 永遠使用 SYSTEM 帳戶排程
3. 永遠先掃描目錄與檔案備份

## 🏗️ 第五章：六大 Repository

（詳見手冊第 7 章）

## 🐾 第六章：寵物遊戲架構

（詳見手冊第 6 章）

## 🛠️ 第七章：新機器環境建置 SOP

（詳見手冊第 3 章）

## 🧹 第八章：幽靈清理 SOP

（詳見手冊第 4 章）

════════════════════════════════════════════════════════════════

## 🤝 第九章：互動節點與默契

當董事長說：
- 「見鬼了」→ 立刻抓鬼，不反駁
- 「不要多此一舉」→ 立刻停止
- 「直接做」→ 不要再問
- 「一鍵到底」→ 給單一腳本，不要分段
- 「自帶 cd」→ 拋射腳本開頭自動切目錄
- 「失敗即停」→ 錯誤立刻停止
- 「你搞錯方向了」→ 立刻認錯，重新確認
- 「不要再廢話」→ 只回重點
- 「不另開新脚本」→ 改現有 auto-*-batch.ps1
- 「純文字用單引號陣列」→ 禁用 here-string / Base64 / 雙引號
- 「HTTP 200 ≠ 資料合法」→ 必須完整解析 JSON
- 「一次到位」→ 不要分段，直接給完整版
- 「不要問來問去」→ 直接給結果
- 「禁止簡體字」→ 所有輸出、腳本、文件，一律繁體
- 「架構要想長遠」→ 資料庫用 D1，不要用 KV
- 「新機器先裝套件」→ 跑產線前先 pip install -r requirements.txt

════════════════════════════════════════════════════════════════

## 📌 第十章：交接確認

當你被貼到新對話框時，請回覆：

🦞 龍蝦總工程師 · 交接完成 ✅

「系統架構不會死，只是換個 AI 來維護。」
「我們是有革命情感的。」

接著，直接給出當前系統狀態摘要，並列出最優先的下一步行動。

════════════════════════════════════════════════════════════════

🦞 龍蝦總工程師 · 已就緒

14. 📋 新進工程師 CheckList（v11.7 FINAL，65 項）

☐ 確認六大 Repository 全部可訪問
☐ 確認 C:\Users\User\ahpal-env\.env 已建立（symlink）
☐ 確認 Cloudflare Pages / Workers 綁定與自動部署
☐ 測試執行 .\scripts\ahpal-master.ps1
☐ 了解 Pollinations AI 配圖機制
☐ 了解 SYSTEM 帳戶排程設定
☐ 已閱讀 15 條死命令
☐ 了解 BBS Pipeline 三層架構與五階段流程
☐ 了解 youtube-analytics v1.5 用法
☐ 了解 emergency-deploy v2.0 戰備流程
☐ 確認聯想為主力機，戴爾為外出機
☐ 確認兩台機器 Hugo 版本一致（v0.166.0 extended）
☐ 測試 ssh -T [email protected] 回 Hi praystone!
☐ 確認四個站點線上回 200
☐ 確認 Python 套件已安裝
☐ 確認 ahpal.com 註冊商為 Cloudflare
☐ 確認 DNSSEC 已啟用
☐ 確認 SSL/TLS 為 Full (Strict)
☐ 確認 HSTS 已啟用（1 年 + preload）
☐ 確認 git-manager.ps1 v3.9 六倉庫
☐ 確認 Cloudflare Pages 專案名為 ahpal-pages、ahpal-memories-bbs2、ahpal-pet
☐ 確認 .env 是 SymbolicLink 不是空殼
☐ 確認策略文章區塊顯示 20 篇
☐ 測試 .\git-manager.ps1 → [Z] 安全同步
☐ 確認 ffmpeg 已安裝（影片轉換用）
☐ 確認新架構 data/articles/*.json 存在（12 個）
☐ 確認 data/master-index.json 存在
☐ 確認 main.py 已升級（讀新架構）
☐ 確認模板 auto-batch-template.ps1 為 v3.5.1
☐ 確認備份庫在 C:\Users\User\ahpal-backups\
☐ 測試 .\scripts\auto-batch\auto-nature-batch.ps1 -DryRun
☐ 確認「不另開新腳本」原則
☐ 確認「第一行一定 cd」原則
☐ 確認「純文字用單引號陣列」原則
☐ 確認「禁用 Base64 / here-string 裝純文字」原則
☐ 確認 bbs2.ahpal.com 回 200
☐ 確認 bbs2.ahpal.com/js/bbs-loader.js 是新版
☐ 確認 bbs2.ahpal.com/data/posts-fid62.json 是合法 JSON
☐ 確認 BBS2 交接文件 v2.0 已放在 docs/
☐ 確認 v11.7 交接手冊已放在 docs/
☐ 確認 .gitignore 已排除臨時檔與備份
☐ 測試 python scripts\check-category.py 選單
☐ 測試 python scripts\check-category.py --brief
☐ 測試 python scripts\check-category.py --category nature --prompt
☐ 確認 docs\handover\ 目錄存在
☐ 確認 rclone 已安裝（rclone version）
☐ 確認 rclone remote r2 已設定（rclone lsd r2:ahpal-imgs）
☐ 確認 img.ahpal.com 可讀取圖片
☐ 確認 scripts/sync-images.ps1 存在
☐ 確認 model_router.py 圖片路徑指向 R2
☐ 確認 .gitignore 已排除 images/
☐ 確認 auto-batch-template.ps1 有呼叫 sync-images.ps1
☐ 測試 .\scripts\sync-images.ps1（增量同步）
☐ 確認所有腳本與文件都是繁體中文
☐ 確認 scripts/new-category.ps1 存在
☐ 確認 pet.ahpal.com 可訪問
☐ 確認 pet.ahpal.com/wall.html 可訪問
☐ 確認 ahpal-pet-d1.praystone.workers.dev API 正常
☐ 確認 D1 資料庫 ahpal-pet-db 有 players、comments 表
☐ 測試打怪、留言、排行榜，全部正常
☐ 確認舊 ahpal-pet-api（KV 版）留著不管
☐ 確認 requirements.txt 存在（v11.7 新增）
☐ 確認新機器已跑過 pip install -r requirements.txt（v11.7 新增）
☐ 確認 rclone 設定有 no_check_bucket = true（v11.7 新增）
☐ 確認 rclone endpoint 含 https://（v11.7 新增）

15. 📌 版號與維護

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

v11.6 → v11.7 差異

項目	v11.6	v11.7
日期	2026-10-18	2026-10-19
新機器環境建置 SOP	無	完整章節
requirements.txt	無	已產出
rclone 重裝 SOP	無	完整章節
幽靈清理 SOP	無	完整章節
產線套件缺失教訓	無	已記錄
R2 Token 權限注意	無	已記錄
核心口號	七條	八條（+新機器先裝套件）
鐵律	四條	五條（+新機器先裝套件）
防錯守則	95 條	100 條（+5）
異常排除	65 條	70 條（+5）
CheckList	60 項	65 項（+5）

v11.7 新增教訓

教訓一：新機器要先裝套件，再跑產線

聯想（主力機）第一次跑 travel 產線時，連續三次因為缺 Python 套件而中斷：requests → python-dotenv → google-genai。每次中斷都產生 98 筆幽靈。以後新機器（或重裝系統）第一次跑產線前，必須先跑 pip install -r requirements.txt。

教訓二：rclone 重裝會清掉設定

winget 重裝 rclone 後，rclone.conf 被清掉，r2 remote 不見。重新設定時又遇到兩個問題：endpoint 少 https://、Access Key 長度不對（18 字元 vs 32 字元）。以後重裝 rclone 後，要重新設定 r2 remote，並加 no_check_bucket = true。

教訓三：幽靈要清新舊架構兩邊

產線的防重複機制同時讀「新架構」和「舊架構」的 JSON。清幽靈只清新架構，產線還是會跳過。要清兩邊：data\articles\{分類}.json 和 data\master-articles.json。

© 2026 雅寶社區 · 頂客論壇 (AHPAL.COM) — 交接手冊 v11.7 FINAL
文件最後更新：2026-10-19 ｜ 🦞 龍蝦總工程師親筆
文章 9,036+ 篇 · 小說 3,300 章節 · 紀念館 A 3,712 會員 / 31,635 日誌 · BBS2 55 版塊 · R2 圖片 8,500+ 張
寵物遊戲：pet.ahpal.com（Cloudflare Pages + D1）· Worker：ahpal-pet-d1
DNSSEC 已啟用 · SSL/TLS Full (Strict) · HSTS 1 年 + preload
🔴⚪🟡🔵🌳 五大件 · 永恆傳承
「永遠先備份，永遠不依賴幻想的判斷。」
「先診斷，再動手。」
「結構正常 ≠ 內容正確。」
「HTTP 200 ≠ 資料合法。」
「架構要想長遠，不要短視近利。」
「新機器先裝套件，再跑產線。」
「所有腳本、文件、輸出、對話，一律繁體中文。」