索引版 · 不寫細節 · 只寫去哪查 · 2026-11-22
v1.7

一、這張 HTML 是幹嘛的(先看這段,3 分鐘)

它是「索引」,不是「全文」。細節全部在交接包的 .txt 裡,HTML 不重寫細節,避免兩邊不同步。

交接包在哪:C:\Users\User\ahpal-AI-archive\ai交接-<最新時間戳>\ 裡面有 18 個 .txt,按下面順序讀。

口訣:交接先撈 D1,同步用 git-manager,HTML 用 deploy_handover。動手前先查 SOP 表,不要憑記憶猜。

一之一、給下一個 AI — 我踩過的坑,你不要再踩(將心比心)

我是上一任 AI,我寫這段是因為我今天真的踩過這些坑,方向錯了,寫錯了,還好董事長點我才回來。你一打開這張,先讀這段,3 分鐘,省你 3 小時。

坑 1:SOP 不是手寫的,是掃描器產的。不要手寫 3 個 .txt 放 SOP 資料夾,錯方向。正確是:去 scripts\sop\ 加 sop-*.txt,再跑 ai-handover-scan.ps1 -NoPause,掃描器會自動收進 13-工作SOP-索引.txt。
坑 2:沒過 SOP 檢查鎖,掃描器會直接 exit 1。先建 C:\Users\User\ahpal-static\.sop-locks\.sop-read-modify-scanner.txt,空檔案就好,再跑掃描。
坑 3:不要用 PowerShell here-string 包長內容。here-string 裡的雙引號、$、單引號會被吃掉。用陣列 + -join,SOP 10.8 有寫。
坑 4:.txt 要 UTF-8 有 BOM,不是無 BOM。掃描器 WriteU8 寫得很清楚,.txt 加 BOM,.py / .json / .ps1 才無 BOM。寫錯編碼,下一個 AI 打開會亂碼。
坑 5:檔名不要中文長檔名。中文檔名會 ascii codec 爆掉,v1.5 第一次就是這樣爆的。檔名一定要英文 AHPAL-Handover-FINAL-vX.Y.html,Canonical 也要是英文。
坑 6:不要憑記憶猜路徑。先 Get-ChildItem 撈真實路徑。掃描器路徑在 scripts\,不是 scripts\sop\,在 sop 裡面跑 .\ai-handover-scan.ps1 會找不到。
坑 7:不要兩邊各改各的。交接手冊正式版只改 ahpal-static 那支,改完 copy 到 handover\SOP\,兩支同內容,不要分叉。
坑 8:頂部導航欄絕對不能用 div,要用 nav。v1.6 之前用 div.topnav,人類看得到、GSC 也看得到連結,但語意不對。v1.7 起改成 nav.topnav 加 aria-label,CSS 完全不用動。下一任改任何頁面的頂部導航,都用 nav,不要用 div,不要用 JS 塞導航。

你如果迷路了,照這 3 步回來:1. 先讀 00-總覽-入口.txt;2. 再讀 13-工作SOP-索引.txt 查你的任務對應哪個 SOP;3. 去 scripts\sop\ 找那個 sop-*.txt,抄範本,不要自己造輪子。不要怕問董事長,他點你一句,比你自己猜 3 小時有用。

二、交接包 18 個 .txt,去哪查什麼(照順序讀)

順序檔案去這裡查什麼
100-總覽-入口.txt先讀這個,全站總覽,知道有幾個專案、幾個 repo
211-工作SOP-拋射與驗證.txt / 13-工作SOP-索引.txt動手前必查:你的任務對應哪個 SOP、抄哪支範本
312-工具鏈地圖.txt / 15-腳本清單-全站.txt工具在哪、腳本在哪,不要自己造輪子,先看現成的
409-雙機同步地圖.txt / 11-雙機同步-操作手冊.txt雙機同步怎麼跑,A 電腦 / B 電腦怎麼對
507-主站交接精華.txt / 14-主站-人格口號死命令.txt主站人格、口號、死命令,不能改的在這裡
601-主站-掃描.txt主站 ahpal-static:檔案數、12 分類、關鍵檔案
702-系統工具-掃描.txt系統工具:D1、git-manager 在哪
803-企劃-掃描.txt企劃 AHPAL-Sync:企劃檔在哪
904-小說站-掃描.txt小說站 ahpal-novels
1005-紀念館A-掃描.txt紀念館 A ahpal-memories (UCHome)
1106-紀念館B-BBS2-掃描.txt紀念館 B ahpal-memories-bbs2
1207-寵物遊戲-事實.txt寵物遊戲 ahpal-pet:事實,不要猜
1308-開心農場-事實.txt開心農場 ahpal-farm:事實,不要猜
1409-工具箱-掃描.txt工具箱 ahpal-tools
1510-百科全書-掃描.txt百科 ahpal-wiki
1612-外部儲存-對照表.txt外部儲存、D1、R2 對照
1717-全站部署地圖.txt全站部署:誰部署到哪、Pages / Worker / D1
1820-專案索引-10備忘錄.txt10 個專案備忘錄,projects\ 裡面

三、三支核心腳本,去哪找(不要自己造)

腳本路徑用途
dump-d1-schema.ps1ahpal-AI-archive\system-tools\dump-d1-schema.ps1撈 D1 完整結構,交接先撈這個
git-manager.ps1ahpal-AI-archive\system-tools\git-manager.ps18 個 repo 管理,同步用這支
deploy_handover.pyahpal-ai-archive-git\handover\SOP\deploy_handover.py產這張交接手冊 HTML,正式版是 deploy_handover_official.py
有現成的範本,就抄現成的範本,不要自己造輪子。範本在 scripts\sop\_tools\,6 支範本先看。

四、動手前,先查 SOP 表(查到你的任務,就讀對應 SOP + 抄對應範本)

任務必讀 SOP抄哪支範本
改掃描器(加專案)10.8 + 10.32split-output2.py
改掃描器(加 SOP 章節)10.8 + 10.17補modify-handover-*.py
加 SOP 章節(sop-*.txt)10.3.1add-readme.py
改 PowerShell 腳本(長內容)10.8 + 10.15PowerShell 陣列 + 絕對路徑
新增文章 / 批次生成21 + 22 + 23auto-batch-*
部署 / Cloudflare Pages31GitHub Actions
改 sitemap34update_sitemap()
改 canonical33 + 35三刀 SOP
tools ↔ wiki 切割33六刀 SOP
一條龍(拋射)49.3一條龍模板

四之一、頂部導航欄稽核 — 2026-11-21 查過,6 頁 OK,1 頁 v1.7 已改

董事長死命令:公告割著,底部割著,底部是補足用的。頂部才是重點,尤其是手機頂部,絕對不能用 JS 塞導航,JS 塞導航 GSC / SEO 會很差。

頁面結果備註
首頁 /OK第 20 行實體 <nav>,11 個 a,手機跟電腦同一支,只有 1 個 @media,沒有 hamburger / menu-toggle
categories.htmlOK假警報過一次:沒加 -L 的 curl 抓到空檔會誤判沒有 nav。正確是 HTTP 200、大小 11369、有 <nav>,跟首頁同一支
curated /OK有 <nav> + <header>。只算第一行 a 數會算成 0,因為 nav 跨多行,要算整支 nav,不要只算第一行
strategy /OK實體 <nav>,11 個 a
tools.ahpal.com /OK實體 <nav>,10 個 a,工具箱自己的導航,10 個是正常的
search.htmlOK有 <nav> + <header>
交接手冊 v1.6已改v1.6 用 <div class=topnav>,v1.7 起改成 <nav class=topnav aria-label=交接手冊導覽>。連結不要寫死 v1.6,要用 {VERSION},不然每版都要手改

下一個 AI 查導航欄,要這樣查:curl 要加 -L,要看 HTTP + 檔案大小,不要只看第一行。首頁 fetch / .json / innerHTML 只有 3 行,全部是公告的(第 64、65、82 行),公告割著不用管。站長精選 100 是實體的,Count 100,不是 JS 抓的。

下一個 AI 改導航欄,要這樣改:只改 ahpal-static 那支 deploy_handover_official.py,改完 copy 到 handover\SOP\ 兩支同內容,不要分叉。改完跑 --no-deploy 先看,再 push。

五、五個絕對不能做(前面的龍踩過的坑)

1. 不用 Python 跳脫產 PowerShell 字串 → 用 PowerShell 陣列 + 絕對路徑
2. 不用相對路徑 → 一律用 C:\Users\User\ahpal-static\...
3. 不用字串替換改 .ps1 → 用 split-output2.py 行號切片
4. 不自己造輪子 → 先看 _tools\ 的 6 支範本(SOP 66.3)
5. 不憑記憶猜路徑 → 先 Get-ChildItem 撈真實路徑

變數命名鐵律:PowerShell 變數大小寫不敏感,迴圈變數會覆蓋函數參數。解法:函數參數用一個名字,迴圈變數用另一個名字,永遠不撞名。詳細去 13-工作SOP-索引.txt 查。

五之一、公告管理 — 下一個 AI 必學

工具:C:\Users\User\ahpal-announcements-worker\公告管理-announcements-D1.ps1,資料庫 ahpal-announcements-db,表 announcements

流程:先 List,再 Get,再 Update,不要直接 Update。ID 是 GUID,用 List 抄。

換文案:不要換行,用 5 個半形空格分隔;連結用完整 https://,AI 靈感卡一定要是 https://tools.ahpal.com/ai-inspiration-card/

換圖標:圖標就是 emoji 放最前面,例如 🛠 📖 ✨,不要用圖片圖標,換完手機看一次。

wrangler:底層 npx wrangler d1 execute ahpal-announcements-db --remote --command=SQL --json,--remote 不能拿掉,SQL 單引號變兩個。

速查表:C:\Users\User\ahpal-announcements-worker\WRONGLER語法.txt

改完等 1 分鐘再 Ctrl+R,不要連續 Update 3 次。

六、部署流程(這支腳本做的事)

1. 備份 AHPAL-Handover-FINAL- 舊版(只備一次,不備 .bak)→ 2. 寫 docs/ 新版 → 3. copy 到 strategy/ → 4. git add docs strategy → 5. commit → 6. push → 7. 等 40 秒,帶 User-Agent 驗證線上是不是 200。

如果線上驗證不是 200,先看 Cloudflare 部署紀錄,不要馬上 git reset。403 通常是沒帶 User-Agent,404 才是檔案不見。