我請 AI 幫我把 44 篇舊文重做 SEO：批次 PATCH Firestore、IA 重整、4 個 topic hub 完整覆盤

TL;DR

- 本文解決：「站上 44 篇舊文累積出 IA 一團亂、tags 一團亂、category 一團亂，每篇單獨 SEO 都做了卻撈不到流量」這種典型部落格中期病。

- 推薦給：個人部落格累積 30 篇以上、開始覺得「站內亂、tags 沒在用、SEO 不漲」的人，以及打算用 AI 跑批次資料庫操作的人。

- 讀完你會知道：6 個 category 收斂法、tags 受控詞彙建法、批次 PATCH Firestore 踩到的 schema 雷、4 個 topic hub 怎麼開、AI 跑這種任務為什麼會卡 1.5 小時。

📌 目錄

為什麼會做這次改造

yanchen.app 寫到第 44 篇的時候，我開始注意到一個怪現象：每篇文章我都認真寫了 title、excerpt、FAQ、JSON-LD，但 Google Search Console 上的曝光成長停在某個水位，怎麼發新文都拉不上去。

我一開始以為是「新站沙盒期」，繼續寫。但寫到第 50 篇還是這樣的時候，我請 Claude Code 幫我盤點全站，看到了真相 —

站內 IA（資訊架構）一團亂。 不是文章寫不好，是「站」這個整體看起來像一堆無關的碎片：

• 28 篇 category 寫 AI 工具，吃掉 64% 的文章 → schema.org articleSection 沒有任何主題權威信號
• 同概念 tags 用 3-4 種拼法：AI Agent / AI 代理人 / AI agent / CLI agent 互相分散權重
• 系列文沒有 topic hub 收：Claude Code 17 篇散在站上、Hermes 5 篇沒 hub、Skills 10 篇沒 hub
• tags 過度泛化：AI 工具、工程師日常、開發實錄 收不到任何長尾流量

於是我請 Claude Code 跑了一輪「狠狠的改一次」批次改造：44 篇逐篇盤點 + 改 category + 改 tags + 重寫 30 篇 title + 重寫 30 篇 excerpt + 開 4 個 topic hub + 清 17 個 duplicate doc。整個流程做完，我這邊實際投入時間約 10 分鐘（驗收 + 最終決策），AI 投入時間 1.5 小時。這篇是覆盤。

改造前的 IA 病灶 — 不是文章不好，是站亂

先看數字。改造前我請 AI 對 bob_blog_posts collection 做了 aggregate：

Step 1：定 6 個 category 受控詞彙（為什麼是 6 不是 10）

第一個關鍵決策：整站 category 只能是這 6 個之一。不是 10 個、不是 20 個、就 6 個。

為什麼是這 6 個？ 我盤點完 44 篇之後，發現它們自然分群成 6 個內容簇。不是我先想好分類再硬塞，是先列篇再歸納 — 這順序很重要。先有內容才有分類 ，不是反過來。

這步必須人類拍板。 AI 可以幫你聚類、提建議，但「我的部落格主軸是哪 6 個」是業務層決策，AI 不能代決定。我跟 Claude 來回討論了大概 15 分鐘才確定這 6 個。

Step 2：tags 受控詞彙表 — 哪些禁用、哪些常駐

tags 不能自由發揮。 每次寫 tag 前，先翻受控詞彙表，沒對應的才新增（且要全站一致）。我把這次整理出來的對照表貼下面，可以直接拿走用：

• ❌ AI 工具、工程師日常、開發實錄、AI、教學、分享、筆記
• ❌ 純情緒詞：心得、雜談、隨筆

AI 沒人搜（誰會只搜「AI」），心得 沒人搜（搜尋意圖太散），工程師日常 沒人搜（純自我表達）。這些 tag 寫上去 = 浪費資料庫欄位空間 + Google 看到一團糊。

Step 3：17 個 hermes-agent duplicate 怎麼清

盤點過程中發現了一個埋很久的雷：Hermes Agent 系列在 Firestore 有 22 個 docs，其中 17 個是不同 docid 但同 slug 的重複。原因是之前批次發文時沒做 dedupe，每次重發都另開新 doc。

我考慮過兩個做法：

實際指令：

# 對每個 duplicate docid 跑這個（用 updateMask 只改 published 欄位）
curl -X PATCH \
  "https://firestore.googleapis.com/v1/projects/forbidden-beauty/databases/(default)/documents/bob_blog_posts/$DOCID?updateMask.fieldPaths=published&key=$KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"published":{"booleanValue":false}}}'

跑完之後 Astro src/lib/firestore.ts:145 的 getAllPublishedPosts() 會自動把它們 filter 掉，topic hub 跟首頁列表都看不到。

Step 4：批次 PATCH Firestore — 踩到 publishDate schema 雷

這步是這次改造最費時的環節。理論上「改 44 篇 docs 的 5 個欄位」應該是個 5 行 Python 腳本的事，實際上花了快 30 分鐘 debug。

雷 1：publishDate 用了 timestampValue 整站炸掉

第一次改造的時候，我隨手把 publishDate 寫成：

publishDate: { timestampValue: "2026-05-20T00:00:00Z" }

PATCH 200 OK 看起來沒事。但下一次 npm run build 整站炸：

[ERROR] b.post.publishDate.localeCompare is not a function
  at /src/pages/blog/[slug].astro:50:30

原因是 Firestore SDK 把 timestampValue 反序列化成 JavaScript Date 物件，但 src/lib/firestore.ts:82 預期 data.publishDate as string，[src/pages/blog/[slug].astro:50](https://github.com/yanchen184/ai-lecturer-bob/blob/master/src/pages/blog/[slug].astro#L50) 跑 b.post.publishDate.localeCompare(a.post.publishDate) — Date 物件沒有 .localeCompare() 方法。

而且不只新改的這篇炸，連帶其他文章的 prerender 也都炸（因為排序步驟整個 throw）。

修法是把 schema 改回字串：

publishDate: { stringValue: "2026-05-20" }  // YYYY-MM-DD 字串，不是 ISO timestamp

教訓：Firestore 同一個欄位混用 timestampValue 跟 stringValue 是地獄。一旦某個 doc 寫成 timestampValue，整站排序立刻死。

雷 2：不用 dry-run 直接 PATCH 44 篇 → 萬一格式錯整批爛掉

第一次跑全量前，先寫了一個 patch-seo-single.mjs 對單一篇試跑（Step skill 把它收進 SOP）：

// 先用最複雜的一篇（含 title rewrite + excerpt rewrite）試 PATCH
const post = plan.posts.find((p) => p.new_title);
const url = ${BASE_URL}/${post.docid}?${maskParam}&key=${API_KEY};
const res = await fetch(url, { method: 'PATCH', ... });
// 然後 GET 回來驗證每個欄位都對

確認 schema 對、updateMask 對、欄位回寫成功之後，才跑全量 patch-seo.mjs。這 5 分鐘的 dry-run 救了我一次 — 因為第一次的 timestampValue 就是在 single test 抓到的。

雷 3：updateMask 一定要精確列出要改的欄位

Firestore PATCH 的 updateMask.fieldPaths 決定哪些欄位被替換。沒列在 mask 裡的欄位即使你在 body 寫了也不會動，列在 mask 裡的欄位即使 body 沒寫也會被清空。

const updateMaskFields = ['category', 'tags', 'updateDate'];
if (post.new_title) {
  fields.title = { stringValue: post.new_title };
  updateMaskFields.push('title');  // 動態 push，沒改 title 的篇不會碰
}
const maskParam = updateMaskFields.map((f) => updateMask.fieldPaths=${f}).join('&');

這樣設計可以保證「沒改 title 的 14 篇文章 title 完全不會被動到」。如果 mask 寫 * 或漏列，會發生「我只想改 category，結果 publishDate 被清空」這種事故。

Step 5：開 4 個 topic hub 收散文

44 篇收完 category 跟 tags 還不夠。Google 要看到「這站是一個 X 主題的權威站」需要 topic hub。

我在 src/lib/topics.ts 開了 4 個新 hub：

• 自己的