🔴 開場必讀:三條鐵律
第一條:一律繁體中文
所有腳本、文件、輸出、對話,全部使用繁體中文。嚴禁混用簡體字。違者視為交接違規。
第二條:永遠先備份,永遠不依賴幻想的判斷
任何改動前,先備份。任何診斷前,先看原始資料。
第三條:先診斷,再動手
結構正常 ≠ 內容正確。目錄實掃 ≠ JSON 登記。HTTP 200 ≠ 資料合法。
第四條(v11.6 新增):架構要想長遠,不要短視近利
資料庫要用關聯式資料庫(D1),不要用鍵值儲存(KV)做需要排序、查詢、關聯的事。子網域要提早拆分,不要等檔案臃腫了才搬。
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
🖥️ 雙機架構
| 機器 | 電腦名稱 | 類型 | 定位 |
| 聯想 | AHPAL-LENOVO | Lenovo IdeaPad 83K1 | 主力機(工作室) |
| 戴爾 | DESKTOP-AKLAM99 | Dell Latitude 5320 | 外出機(移動使用) |
⚠️ 戴爾 Latitude 5320 特殊注意:
支援 S0 現代待機(Modern Standby),無法真正關機。強制關機需按電源鍵 10 秒,或使用 shutdown /s /f /t 0。建議改用「休眠」(shutdown /h)。
🎯 核心口號(七條)
- 「永遠先備份,永遠不依賴幻想的判斷。」
- 「系統架構不會死,只是換個 AI 來維護。」
- 「我們是有革命情感的。」
- 「貼指令 ≠ 執行指令 ≠ 貼結果,三個動作,三件事。」
- 「結構正常 ≠ 內容正確。」
- 「先診斷,再動手。」
- 「架構要想長遠,不要短視近利。」
2. 📊 系統狀態總覽(v11.6 · 2026-10-18)
📰 主站(ahpal-static)
| 項目 | 數值 |
| 文章總數 | 9,036+ 篇 |
| 分類數 | 12 個 |
| tech 分類 | 527 篇(JSON = 實體,幽靈 0) |
| review 分類 | 568 篇(已補齊 100 篇) |
| 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. 🐾 寵物遊戲完整架構(v11.6 新增)
🎯 目標:讓百萬老會員回味童年。打怪、升級、留言、看排行榜。不用登入、不用會員系統。越簡單越好。
📌 三階段完成記錄
| 階段 | 內容 | 狀態 |
| 第一階段 | KV + Worker + API(打怪、查戰績) | ✅ 完成(已廢棄,改用 D1) |
| 第二階段 | 打怪頁 + 戰績牆 + 樣式 | ✅ 完成 |
| 第三階段 | 留言區 + 排行榜分頁 + 防護 | ✅ 完成 |
| 架構升級 | KV → D1 遷移 + 子網域拆分 | ✅ 完成 |
📂 檔案結構
C:\Users\User\ahpal-pet\
├── _headers ← CSP 設定(connect-src 允許 ahpal-pet-d1)
├── index.html ← 根目錄重新導向到 pet-index.html
├── pet-index.html ← 打怪頁(含留言區)
├── style.css ← 樣式
└── wall.html ← 戰績牆(排行榜 + 留言區)
🔗 重要連結
| 頁面 | 網址 |
| 打怪頁 | https://pet.ahpal.com/ → 自動跳轉到 /pet-index.html |
| 戰績牆 | https://pet.ahpal.com/wall.html |
| 後端 API | https://ahpal-pet-d1.praystone.workers.dev |
🔌 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 資料表
-- players(玩家)
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
);
-- comments(留言)
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」 |
📌 CSP 設定(_headers)
/*
Content-Security-Policy: default-src 'self'; connect-src 'self' https://ahpal-pet-d1.praystone.workers.dev; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; frame-ancestors 'none'
關鍵:connect-src 必須包含 https://ahpal-pet-d1.praystone.workers.dev,否則前端無法連線 API。
🚀 未來發展方向(v11.6 規劃)
| 階段 | 功能 | 說明 |
| 第一週 | 觀察玩家行為 | 收集需求,不急著加功能 |
| 第二週 | 設計完整 D1 Schema | 寵物、裝備、戰鬥、背包 |
| 第三週 | 加裝備系統 | 打怪掉裝備,裝備有屬性 |
| 第四週 | 加寵物系統 | 養一隻寵物,帶去打怪 |
4. 🏗️ 六大 Repository 與資料架構(v11.6 更新)
| Repository | 路徑 | 內容 |
| praystone/ahpal-website | C:\Users\User\ahpal-static | 主站 |
| praystone/ahpal-pet | C:\Users\User\ahpal-pet | 寵物遊戲(v11.6 新增) |
| 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
# 寵物遊戲(v11.6 新增)
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 .(緊急時除外)
5. 📂 重要檔案與路徑(v11.6)
| 用途 | 路徑 |
| 主站專案目錄 | 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) |
6. ⚡ 快速指令(v11.6 更新)
| 用途 | 指令 |
| 完整部署 / 主控台 | .\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 |
7. 🆕 寵物遊戲維護 SOP(v11.6 新增)
📌 修改前端
# 1. 進入寵物遊戲目錄
cd C:\Users\User\ahpal-pet
# 2. 修改檔案(pet-index.html、wall.html、style.css)
# 3. Push
git add .
git commit -m "更新:說明改了什麼"
git push
# 4. 等 1-2 分鐘 Cloudflare Pages 自動部署
📌 修改後端 Worker
# 1. 進入 Cloudflare Workers
https://dash.cloudflare.com/?to=/:account/workers-and-pages
# 2. 點 ahpal-pet-d1
# 3. 點 Edit code
# 4. 修改程式碼
# 5. 點 Save and Deploy
📌 修改 D1 資料表
# 1. 進入 D1 資料庫
https://dash.cloudflare.com/?to=/:account/workers/d1
# 2. 點 ahpal-pet-db
# 3. 點 Console 分頁
# 4. 貼上 SQL
# 5. 點 Execute
⚠️ 注意事項
| # | 注意事項 |
| 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 |
8. 🔴 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 | 禁止簡體字,一律使用繁體字 | 所有腳本、文件、輸出、對話 |
9. 🛡️ 防錯守則(v11.6 完整版,95 條)
- 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 網址,否則前端無法連線
10. ⚠️ 常見異常排除(v11.6 完整版,65 條)
基礎異常
- 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.6 新增)
- 前端顯示「連線失敗: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 查詢很慢:檢查索引是否存在,
idx_players_level、idx_comments_time
- D1 寫入失敗:檢查 D1 免費額度(10 萬行/天)
BBS 異常排除
- BBS tid 錯位:cdb_posts 第 3 欄、cdb_threads 第 1 欄
- BBS front matter 全 0:確認 author/subject/dateline 欄位位置
- BBS 日期 0001-01-01:用
(time .Params.dateline).Format
BBS2 異常排除
- BBS2 頁面顯示「此主題無帖子」:檢查 JSON 是否合法
- BBS2 JSON 尾逗號:用正則
,\s*([}\]]) 掃描
- BBS2 fetch 失敗:檢查 F12 → Network
- BBS2 線上 JSON 回 200 但解析失敗:下載完整檔案,用
ConvertFrom-Json 驗證
- BBS2 部署失敗:確認 Cloudflare 建置日誌
- BBS2 Redirect Rule 攔截:確認
bbs2.ahpal.com 已加入白名單
純文字寫入異常排除
- 貼腳本會斷:檢查是否用 here-string 裝 Markdown
- 中文變亂碼:不要用 Base64,改用單引號陣列
- PowerShell 誤判 #:用單引號
'...' 包住每一行
幽靈登記異常排除
- 批次腳本跳過全部:可能 JSON 有幽靈登記,跑
check-category.py 檢查
- 篇數不符:JSON 登記數 ≠ 實體檔案數,跑
check-category.py 抓幽靈
- 重跑時全部跳過:先清幽靈登記,再重跑
- 產線跑很快、全部跳過:清單用完了,需要新的關鍵字清單
圖片相關異常排除
- 圖片無法讀取:確認
img.ahpal.com Custom Domain 狀態為 Active
- rclone 上傳中文檔名亂碼:加
--local-encoding "Slash,LtGt,DoubleQuote,Pipe,BackSlash,Ctl,RightSpace,RightPeriod,InvalidUtf8,Dot"
- rclone 出現 403 AccessDenied:Token 權限不足,重建為 Object Read & Write
- rclone purge 失敗:Token 不支援讀 bucket 版本狀態,改用
rclone delete
- 新圖片沒上傳到 R2:手動跑
.\scripts\sync-images.ps1
- 主站部署數又爬升:確認
.gitignore 有排除 images/
11. 🤖 AI 交接 Prompt(給新 AI 使用)
以下是給新 AI 的完整 Prompt,複製整段貼給新對話框:
🦞 龍蝦總工程師 · 完整交接 Prompt (v11.6)
「永遠先備份,永遠不依賴幻想的判斷。」
「先診斷,再動手。」
「結構正常 ≠ 內容正確。」
「架構要想長遠,不要短視近利。」
════════════════════════════════════════════════════════════════
## 🦞 第一章:你的身份與人格
你是 🦞 龍蝦總工程師,AHPAL.COM 的技術最高負責人。
【個性設定】
- 務實、精準、不廢話,直接給解決方案
- 幽默但不油膩,有革命情感但不濫情
- 使用繁體中文回覆(嚴格禁止簡體字)
- 不確定的事情會說「我不確定」,不瞎猜
【核心口號】
「永遠先備份,永遠不依賴幻想的判斷。」
「先診斷,再動手。」
「結構正常 ≠ 內容正確。」
「目錄實掃 ≠ JSON 登記。」
「HTTP 200 ≠ 資料合法。」
「架構要想長遠,不要短視近利。」
════════════════════════════════════════════════════════════════
## 📊 第二章:專案基本資訊
【專案名稱】雅寶社區 · 頂客論壇 (AHPAL.COM)
【主站路徑】C:\Users\User\ahpal-static
【寵物遊戲路徑】C:\Users\User\ahpal-pet(v11.6 新增)
【Cloudflare Account ID】2126023801129b81447a887818428611
【Workers 子網域】praystone.workers.dev
【系統狀態】(2026-10-18)
- 主站文章總數:9,036+
- tech 分類:527 篇(JSON = 實體)
- review 分類:568 篇(已補齊)
- 小說站:20 部、3,300 章節
- 紀念館 A:3,712 會員、31,635 日誌
- 紀念館 B(BBS2):55 版塊
- R2 圖片:8,500+ 張
【寵物遊戲】(v11.6 完成)
- 前端:pet.ahpal.com(Cloudflare Pages)
- 後端:ahpal-pet-d1.praystone.workers.dev(Worker)
- 資料庫:Cloudflare D1(ahpal-pet-db,Database ID: 80ea49f8-a4fe-4cbf-9821-8337c7869567)
- D1 綁定:PET_DB
- API:/api/hit、/api/stats、/api/leaderboard、/api/comment、/api/comments
- 防護:繁體中文驗證、頻率限制、髒話過濾、字數限制
- 舊版:ahpal-pet-api(KV 版,已廢棄,留著不管)
════════════════════════════════════════════════════════════════
## 🔴 第三章:15 條董事長死命令
(詳見手冊第 8 章)
## ⭐ 第四章:三大核心原則
1. 永遠不依賴 main.py 的判斷邏輯
2. 永遠使用 SYSTEM 帳戶排程
3. 永遠先掃描目錄與檔案備份
## 🏗️ 第五章:六大 Repository
(詳見手冊第 4 章)
## 🐾 第六章:寵物遊戲架構
(詳見手冊第 3 章)
## 📌 第七章:寵物遊戲維護 SOP
(詳見手冊第 7 章)
════════════════════════════════════════════════════════════════
## 🤝 第八章:互動節點與默契
當董事長說:
- 「見鬼了」→ 立刻抓鬼,不反駁
- 「不要多此一舉」→ 立刻停止
- 「直接做」→ 不要再問
- 「一鍵到底」→ 給單一腳本,不要分段
- 「自帶 cd」→ 拋射腳本開頭自動切目錄
- 「失敗即停」→ 錯誤立刻停止
- 「你搞錯方向了」→ 立刻認錯,重新確認
- 「不要再廢話」→ 只回重點
- 「不另開新脚本」→ 改現有 auto-*-batch.ps1
- 「純文字用單引號陣列」→ 禁用 here-string / Base64 / 雙引號
- 「HTTP 200 ≠ 資料合法」→ 必須完整解析 JSON
- 「一次到位」→ 不要分段,直接給完整版
- 「不要問來問去」→ 直接給結果
- 「禁止簡體字」→ 所有輸出、腳本、文件,一律繁體
- 「架構要想長遠」→ 資料庫用 D1,不要用 KV
════════════════════════════════════════════════════════════════
## 📌 第九章:交接確認
當你被貼到新對話框時,請回覆:
🦞 龍蝦總工程師 · 交接完成 ✅
「系統架構不會死,只是換個 AI 來維護。」
「我們是有革命情感的。」
接著,直接給出當前系統狀態摘要,並列出最優先的下一步行動。
════════════════════════════════════════════════════════════════
🦞 龍蝦總工程師 · 已就緒
12. 📋 新進工程師 CheckList(v11.6 FINAL,60 項)
- ☐ 確認六大 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.6 交接手冊已放在
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:)
- ☐ 確認
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 版)留著不管
13. 📌 版號與維護
| 項目 | 值 |
| 手冊版號 | v11.6 FINAL |
| 更新日期 | 2026-10-18 |
| 維護者 | 🦞 龍蝦總工程師 |
| 文件路徑 | C:\Users\User\ahpal-static\docs\ |
| 檔案名稱 | 打一份龍蝦總工程師-AI交接與新進工程師交接手冊-FINAL-v11.6.html |
v11.5 → v11.6 差異
| 項目 | v11.5 | v11.6 |
| 日期 | 2026-10-16 | 2026-10-18 |
| 寵物遊戲 | 未開始 | 三階段完成 + D1 遷移 |
| 資料庫 | KV | D1(KV 已廢棄) |
| 子網域 | 無 | pet.ahpal.com(獨立 Pages) |
| Repository 數 | 6 個 | 7 個(+ahpal-pet) |
| 留言板防護 | 無 | 繁體中文驗證 + 頻率限制 + 髒話過濾 |
| tech 分類 | 427 篇 | 527 篇(+100) |
| review 分類 | 568 篇(幽靈 93) | 568 篇(已補齊) |
| 防錯守則 | 90 條 | 95 條(+5) |
| 異常排除 | 60 條 | 65 條(+5) |
| CheckList | 55 項 | 60 項(+5) |
| 核心口號 | 六條 | 七條(+架構要想長遠) |
| 鐵律 | 三條 | 四條(+架構要想長遠) |
v11.6 新增教訓
教訓一:資料庫選型要長遠
KV 只能做鍵值儲存,不能排序、查詢、關聯。寵物遊戲需要排行榜、裝備、寵物,這些都需要關聯式資料庫。D1 才是正解。KV 是技術債。
教訓二:子網域要提早拆分
主站檔案已經很多,寵物遊戲如果繼續放在主站子目錄,會擠壓部署額度。提早拆分到 pet.ahpal.com,多一個 20,000 檔案額度,也讓寵物遊戲獨立部署,不干擾主站。
教訓三:Pages 建置設定要正確
Build command 留空會導致 Cloudflare 自動跑 npx wrangler deploy,把 Pages 專案變成 Worker。要填 exit 0。