📖 目錄

1. 📋 本次對話核心問題與解決方案
2. 📊 系統架構與版本狀態 (v8.4)
3. 📋 本次重要決策完整清單
4. 📜 死命令完整彙整 (3條)
5. ⚡ 快速指令完整參考
6. 📋 待辦事項與未來規劃
7. ✅ 交接檢查清單
8. 📌 簽核與文件生效

1. 📋 本次對話核心問題與解決方案

1.1 CSS 版面修復完整紀錄

項目	內容
事件日期	2026-08-08
問題描述	首頁右側邊欄消失，下方索引標籤全部連在一起，版面散架
根本原因	`style/main.css` 缺少關鍵樣式定義
解決方案	重寫完整 CSS v1.2，補齊所有版面樣式
狀態	✅ 已解決並部署

1.2 本地測試 SOP

🚫 避免錯誤的測試方式

❌ 不建議：直接雙擊 index.html（file:// 協定無法正確解析絕對路徑）

✅ 正確的本地測試方式

# 方法 1：使用 Wrangler（推薦）
cd C:\Users\User\ahpal-static
npx wrangler pages dev .

# 方法 2：使用 Python HTTP 伺服器
cd C:\Users\User\ahpal-static
python -m http.server 8000
# 瀏覽器訪問 http://localhost:8000
            

1.3 表格結構異常問題（`<p><table>`）

項目	內容
問題	AI 生成表格時使用 `<p><table>` 包裹，導致版面錯亂
影響文章	`rainy-night-flower-lo-fi-cover.html`
根本原因	AI 輸出格式不規範，且系統未攔截
解決方案	在 `article_generator.py` 新增 `_normalize_tables()` 函數，自動修正
版本	v8.4
狀態	✅ 已修復

# _normalize_tables 函數會自動修正以下無效結構： #

→

#

→ #

→

#

→

1.4 `add-articles.ps1` 與 `pending-articles.json` 的正確使用

🚨 關鍵發現

問題：add-articles.ps1 對 pending-songs.json 強制要求 video_id 欄位，導致一般文章被跳過。

解決方案：一般文章（無 YouTube 影片）應寫入 data/pending-articles.json，而非 pending-songs.json。

情境	正確 JSON 路徑	說明
音樂文章（含 YouTube 影片）	`data/pending-songs.json`	需含 `video_id`
一般文章（無影片）	`data/pending-articles.json`	無需 `video_id`

1.5 中文檔名違反死命令問題

📌 現狀

music/打工人心酸語錄.html 違反死命令 2（英文檔名強制規範）
政策：不咎既往（2026-08-08 前已生成檔案維持原樣）
建議：未來所有新文章檔名必須為英文

2. 📊 系統架構與版本狀態 (v8.4)

元件	版本	狀態	備註
`main.css`	v1.2	✅ 已部署	10813 bytes
`html_builder.py`	v6.7	✅ 已部署	Giscus 留言系統統一
`article_generator.py`	v8.4	✅ 已部署	表格標準化 (`_normalize_tables`)
`api_client.py`	v4.1	✅ 已部署	Responses API + Reasoning
`add-articles.ps1`	v3.3	✅ 已部署	UTF-8 無 BOM 寫入
`preflight-check.ps1`	v2.1	✅ 已部署	含中文檔名檢查
`meme-to-song.ps1`	v1.2	✅ 已上線	強制英文檔名

📊 系統核心指標（截至 2026-08-08）

總文章數：470+ 篇
最高品質分數：90 分（Responses API + Reasoning）
平均品質分數：82.4 分
配圖成功率：100%
品質未達標：0 篇
核心腳本：18 個

3. 📋 本次重要決策完整清單

#	決策	說明	狀態
1	Responses API + Reasoning 正式啟用	文章品質從 82.4 分提升至 90 分	✅ 已啟用
2	英文檔名死命令	即日起所有新文章檔名強制使用英文	✅ 已生效
3	`article_generator.py` 升級至 v8.4	新增 `_normalize_tables()` 自動修正表格結構	✅ 已部署
4	`html_builder.py` 升級至 v6.7	統一 Giscus 留言系統樣式	✅ 已部署
5	一般文章改寫入 `pending-articles.json`	避免 `add-articles.ps1` 的 `video_id` 驗證阻擋	✅ 已修正

4. 📜 死命令完整彙整 (3條)

📜 死命令 1：文章變更後強制檢查與推送規範

生效日期：2026-08-07

階段一：檔案完整性檢查（文章數量、檔案大小 ≥ 5KB、首頁/分類頁/Sitemap 更新）
階段二：內容品質檢查（網頁標題、品牌名稱、AdSense 程式碼）
階段三：Git 狀態檢查（無未追蹤檔案、無機密檔案）
強制執行：.\scripts\preflight-check.ps1

📜 死命令 2：文章檔名強制使用英文

生效日期：2026-08-08

規範：所有新增文章檔名必須為英文（含數字、中線），不得包含中文
正確範例：worker-blues-original-song.html
錯誤範例：打工人心酸語錄.html
檢查指令：Get-ChildItem -Recurse -Filter "*.html" | Where-Object { $_.Name -match '[\u4e00-\u9fa5]' }
不咎既往：2026-08-08 前已生成檔案維持原樣

📜 死命令 3：本地測試強制規範

生效日期：2026-08-08

規範：任何 HTML/CSS 變更後，必須使用 npx wrangler pages dev . 或 python -m http.server 8000 啟動本地伺服器測試
禁止：直接雙擊 index.html 進行測試

5. ⚡ 快速指令完整參考

用途	指令
本地測試	`npx wrangler pages dev .`
完整部署	`.\scripts\ahpal-master.ps1 → [1]`
快速部署	`.\scripts\ahpal-master.ps1 → [6]`
新增一般文章	編輯 `data/pending-articles.json` → `.\scripts\add-articles.ps1 -Force`
新增音樂文章	編輯 `data/pending-songs.json` → `.\scripts\add-articles.ps1 -Force`
死命令檢查	`.\scripts\preflight-check.ps1`
全面系統檢查	`.\scripts\check-all.ps1 -Report`
檢查中文檔名	`Get-ChildItem -Recurse -Filter "*.html" \| Where-Object { $_.Name -match '[\u4e00-\u9fa5]' }`

6. 📋 待辦事項與未來規劃

#	事項	優先級	說明
1	將 `music/打工人心酸語錄.html` 重新命名為英文	🟡 中	建議修正為 `worker-blues-original-song.html`
2	清理測試檔案	🟢 低	`test-schema-fix.html`、`test-lyrics-style.html` 可刪除
3	確認兩篇新文章已生成	✅ 已完成	NAS 相片備份 & Suno AI 指南

7. ✅ 交接檢查清單

📋 請逐項確認

☐ 已閱讀三大件文件（白皮書、紅皮書、交接手冊）
☐ 已閱讀本附錄與備忘錄（補足三大件未涵蓋事項）
☐ 已記住 3 條死命令（檢查、英文檔名、本地測試）
☐ 了解 pending-articles.json 與 pending-songs.json 的差異
☐ 了解 add-articles.ps1 的正確使用方式
☐ 了解 article_generator.py v8.4 的表格標準化功能
☐ 確認 Responses API + Reasoning 已啟用

8. 📌 簽核與文件生效

📌 撰寫

龍蝦總工程師

✅ 已簽核

✅ 核定

董事會執行長