文章列表 on Tarragon

驗證導向的 CLI 工具文章：官方 docs 查核放過的落差類型

Mon, 15 Jun 2026 00:00:00 +0000

本文記錄驗證導向生產流程背後的 evidence — 為什麼官方文件查核不夠、實機驗證抓到了什麼。操作步驟維護在 .claude/skills/verification-driven-cli/。

官方文件查核放過的五類落差

content/cli/ 五類終端機工具文章（監控 / 圖表 / 多工器 / 檔案管理 / SQL 客戶端）在實機驗證時抓到、純靠 docs 查核會放過的落差：

1. 旗標改名

zellij web 文件寫有 --bind，實際 0.43.1 是分開的 --ip 與 --port。讀者照文件下指令會得到 unknown flag error、但不知道正確旗標是什麼。

2. 設定鍵 migrate

lazygit 的 pager 設定文件寫 git.paging.pager，新版 0.62.2 改成 git.pagers（list）。舊鍵啟動時會被自動 migrate、改寫設定檔 — 讀者照舊文件設定後發現設定檔被工具自己改掉。

3. 隱含 schema prefix

dblab 的查詢編輯器要 schema 限定（SELECT * FROM public.products），裸 products 會報 relation 不存在。原因是編輯器連線的 search_path 不含 public — 文件沒提。

4. 平台特定 segfault

nvtop 在 Apple Silicon mac 裝得起來，但 snapshot 模式直接 segfault。GPU 後端不穩。裝成功不代表能用 — 文件只說「支援 macOS」。

5. Driver 差異

同一個 Postgres，lazysql（Go pq driver）連無 SSL 的 DB 要 ?sslmode=disable，pgcli / harlequin（Python psycopg）不用。同樣的連線字串在不同工具會有不同行為、文件各自不提對方。

共通模式

這五類落差有個共通點：讀者照文件走會撞牆、卻在文件裡找不到答案。實機跑一次就現形，而且現形的正是文章最該寫的內容 — gotcha 段落省下讀者各自撞一次的時間。

官方文件的 fact-check 只能驗證「文件說的是否正確」，驗不了「文件沒說的是否存在」。實機驗證補的是後者。

Migration Playbook 方法論的演化紀錄：Stage 0 variant 規劃把 collapse 率從 60% 降到 0%

Tue, 19 May 2026 00:00:00 +0000

本文記錄 migration-playbook-methodology 這套寫作方法論前三輪 batch dogfood（實際寫文章驗證方法論）的演化過程（skill 已累積到六輪、本文記錄前三輪）。操作步驟維護在 .claude/skills/migration-playbook-methodology/，本文只保留 retrospective — 每一輪跑出來學到什麼、哪些假設被推翻。

為什麼 migration playbook 需要自己的方法論

Migration playbook 跟 single feature deep article 是不同 content category：

維度	Deep article	Migration playbook
主題形狀	Single feature（pgBouncer / Vault dynamic credential）	Cross-vendor process（Splunk → Elastic）
結構	6-section（problem → concept → config → failure → capacity → integration）	6 種不同 type、各對應不同結構
重點章節	Step-by-step 配置 + 故障演練	視 type 不同：phased flow / parallel streams / hybrid
寫作週期 / 篇	1-2 小時	2-3 小時（diff dimension audit + 結構選擇 + 寫作）
跨篇 cadence 風險	中（章節 1 entry 容易 collapse）	高（migration 主題本質相似、主題語意 attractor「為什麼遷」明顯）

關鍵差異：deep article 是 single direction implementation、migration playbook 是 bidirectional comparison + process。第一輪寫了 5 篇後發現結構完全不同；嘗試套 deep article 的固定結構都只對 1 種情境適用，於是用 diff dimension audit（寫前評估 source/target 在哪些維度差異最大）選對應的結構模板（Type A-F，依主導差異維度決定）。

第一輪 batch（5 篇）：Type A-E 浮現 + cadence collapse 3/5

第一輪寫了 5 篇跨 vendor migration playbook，每篇自然對映到一種 type（結構模板）：

Splunk → Elastic Security — Type A phased translation
Redis → DragonflyDB — Type B drop-in
PostgreSQL → Aurora — Type C operational hybrid
Datadog → Grafana Stack — Type D parallel streams
Kafka ↔ NATS — Type E paradigm shift

Cadence collapse：前 3 篇被動寫作全部同質化

Cadence collapse 指批量寫作時、多篇文章的開場句型不自覺重複同一模式。

篇	Variant 規劃	章節 1 entry framing
1 Splunk → Elastic	被動	「為什麼遷：cost / multi-vendor / cloud-native」
2 Redis → DragonflyDB	被動	「為什麼遷：cost / single-thread / multi-tenancy」
3 Postgres → Aurora	被動	「為什麼遷：operational cost / HA / DR」
4 Datadog → Grafana	主動	「$50K/month bill 拆解」
5 Kafka ↔ NATS	主動	「『Kafka → NATS migration』字面上不成立」

3/5 collapse — 主題語意 attractor「為什麼遷：X / Y / Z driver」在前 3 篇被動寫作下浮現。寫第 4 篇前發現問題、後 2 篇主動換 entry variant。

前 3 篇的 collapse 是 Stage 0 variant 規劃成為硬需求的直接證據。

Type A-E 怎麼浮現

5 篇寫完後比對結構、發現 5 篇結構完全不同，但都可以用「主導差異維度」解釋：schema 差為主 → phased translation、全 Low → drop-in、operational 差為主 → hybrid。Type A-E 從這 5 篇的歸納中浮現，第二輪 dogfood 再加上 Type F（topology re-layout）。

第二輪 batch（5 篇）：漏類驗證 + 多軸 High 實證

第二輪刻意選漏類場景驗證 self-aware limitation：

PostgreSQL major version upgrade (14 → 17) — 漏類驗證（同 vendor）
Redis cluster re-sharding — 漏類驗證（topology 重劃）→ Type F 浮現
PostgreSQL → CockroachDB — 三維 High multi-axis 驗證
MySQL → PostgreSQL — Type A 標準形態（263 行）
MongoDB → Atlas — Type C 標準形態（349 行）

Stage 0 variant 規劃從第二輪開始全面啟用，cadence collapse 從 3/5 降到 0/5。

驗證成立的 4 項預測

5 type 漏類確認：major version upgrade + re-sharding 結構跟 5 type 完全不同
多重歸類 + tie-breaking 規則成立：PostgreSQL → CockroachDB 三維皆 High、按主導維度走 Type E + 高維度獨立段
Type A / Type C 標準形態仍適用：MySQL → PostgreSQL + MongoDB → Atlas 走標準模板
Stage 0 variant 規劃硬需求：第二輪 5 篇全主動 variant、collapse 0/5

浮現的 3 項新議題

新 audit 維度（data topology）：re-sharding 揭露 5 維度沒「topology」軸 → 擴到 6 維
「為什麼這篇不套」是漏類文章標準 frame：major-version-upgrade + cluster-resharding 都用這個 frame 開頭
「高維度獨立段」升級為 multi-axis migration 標準結構元素

第三輪 batch（5 篇）：Type F dogfood + 候選軸驗證

第三輪驗證 data topology audit dimension 的 self-aware limitation 4 條 tripwire：

PostgreSQL partition redesign（246 行）— Type F dogfood #2
MongoDB shard + multi-DC expansion（291 行）— Type F dogfood #3 + parallel run 例外實證
Vault → AWS Secrets Manager（272 行）— Identity axis 候選（45% 工作量）
DynamoDB consistency model optimization（249 行）— Consistency axis 候選（85% 工作量）
PostgreSQL multi-region GDPR rollout（238 行）— Residency axis 候選（40% 工作量）

第三輪維持 collapse 0/5，但 Type F 分裂出 sub-type（F-cluster vs F-multi-region），框架仍在演化。

累積 evidence

Type F sub-type 浮現：F-cluster（單 cluster 內、不需 parallel run）vs F-multi-region（跨 region、需 parallel run）
3 軸候選確認可獨立：identity / consistency / residency 各帶 30-85% 獨立工作量；累積到 3-5 case / 軸後考慮升 audit 7-9 維
Residency 是 cross-cutting constraint：不只是 driver、反向約束 topology + operational + application

三輪對照：方法論的演化軌跡

維度	第一輪（5 篇）	第二輪（5 篇）	第三輪（5 篇）
Type 集合	A-E（5 type）	A-F（+Type F）	A-F + sub-type
Audit 維度	5 維	6 維（+topology）	6 維 + 3 候選軸
Cadence collapse	3/5 (60%)	0/5 (0%)	0/5 (0%)
Variant 規劃	被動 → 主動	全主動	全主動
總行數	~1,200	1,389	1,292
單篇行數	200-300	263-349	238-288

關鍵轉折是第一輪到第二輪：後續批次未再觀察到 collapse。

Self-aware limitation

本 methodology 從 15 篇 migration playbook dogfood 抽出 6 type；已知 limitation：

6 type 非窮盡：major version upgrade / merger consolidation 等情境不在 6 type 內
多重歸類常見：實際 source/target 配對很少完美對映單一 type
「主導維度」需 judgment：優先序是 audience-dependent heuristic、不是 universal 規則
Collapse 歸因有共變因素：第二輪以後 collapse 消失，但同時作者已有第一輪經驗、且知道自己在測量 cadence（Hawthorne effect）。Stage 0 variant 規劃是介入手段之一，無法完全隔離歸因。N=5 的二項信賴區間也無法排除偶然
候選軸未 commit：identity / consistency / residency 各 N=1、累積到 3-5 case / 軸後才考慮升維

本 methodology 接受 evolution、不假裝穩定。

Vendor 深度技術文章方法論的演化紀錄：同 vendor 系列的開場輪替驗證

Mon, 18 May 2026 00:00:00 +0000

Vendor overview 寫完後、往下寫單一功能深度文章時，選題與結構需要不同的方法論。操作步驟維護在 .claude/skills/vendor-deep-article/，本文記錄這套方法論從兩輪 batch 中演化出來的過程，重點是 cadence collapse（批量寫作時開場句型同質化重複）怎麼被寫前的 variant 規劃（每篇預先指定不同開場 framing）解決。

背景

本 blog 的 backend 教學模組已完成多個 vendor overview。overview 層飽和後、自然的下一步是 overview 頁尾「預計實作話題」backlog 的深度文章。

寫了 deep article + migration playbook 後、確認 deep article 跟 overview 是不同產品、需要自己的方法論。差異見 migration playbook 方法論演化紀錄。

第一輪 batch（5 篇）：跨 vendor、5 種 entry framing

篇	Variant	章節 1 entry framing	行數
pgBouncer 配置	A 標準	標準「問題情境」	263
Vault dynamic credential	A 標準	標準「問題情境」	222
K8s graceful shutdown	B 痛點	痛點宣告「沒做對、每次 deploy 都吃 502」	213
Splunk RBA	C 反向	概念反向定義「alert fatigue 是 detection 天花板」	193
Cloudflare Page Shield	D 對照表	對照表驅動「Attack pattern x Defense mechanism」	214

第一輪確認了結構 framework 成立、且章節名可隨主題調整。

6 段 framework 成立但章節名可變

6 段內容指引（問題情境 → 概念 → 配置 → 演練 → 容量 → 整合）在 5 篇都成立。但章節 1 的 framing 因主題本質不同自然分化 — 5 種 entry framing 都成立、章節 1 不必死守「問題情境」標題。

據此小修方法論：6 段 framework 是內容指引、不是章節標題模板。

Cadence collapse 0% — 主動 variant 有效

後 4 篇寫作前主動規劃 4 種 framing variant。跟 backend/07 的 51 vendor batch 對照：

維度	backend/07 51 vendor	deep article 後 4 篇
Cadence「任一缺失」族重複	51/51 (100%)	0/4 (0%)
章節 1 entry framing 種類	1 種	4 種

Reviewer 單人足夠

deep article 焦點窄（單一 feature）、跨章 frame 重複風險低、case 引用密度低（1-2 個對照）。5 篇都採單一 reviewer 流程、未出現需要 multi-axis review 的盲點。

第二輪 batch（5 篇）：同 vendor sub-tool 系列、最高 collapse 風險

第二輪刻意選 cadence collapse 最高風險場景：5 篇 PostgreSQL sub-tool deep article、同 vendor / 同 article type / 同 audience / 同 6-section framework。

篇	Variant	章節 1 entry framing	行數
Patroni HA	E lifecycle-driven	「Failover lifecycle 5 段不是一條曲線」	243
autovacuum tuning	B pain-driven	「你的 autovacuum 永遠追不上 bloat — 為什麼」	202
declarative partitioning	C concept-reversed	「Partition 不是『把大表切小』、是『讓 planner pruning + 縮小 maintenance scope』」	244
logical replication + Debezium	D table-driven	「Replication slot x Failure x Recovery 對照」	227
PITR + WAL archiving	A standard 6-section	「問題情境」	273

第二輪在最高風險場景（同 vendor sub-tool）仍維持 collapse 0%，且新增第五種 variant（lifecycle-driven）。

跨兩輪對照

維度	第一輪 N=4（跨 vendor）	第二輪 N=5（同 vendor sub-tool）
Variant 種類	4（A / B / C / D）	5（A / B / C / D / E）
Cadence collapse	0/4 (0%)	0/5 (0%)
章節 1 entry framing 種類	4	5
共同 context	6-section framework	6-section + 同 vendor + 同讀者

關鍵驗證：

N=5 仍 0% collapse：5 種 variant 在最高風險場景（同 vendor sub-tool）仍完全錯開
5 variant 不耗盡：5 種變體（lifecycle / pain / reverse / table / standard）對應主題自然進入方式、不是強制配對
cadence audit 最佳位置是進度 60-80%：進度 10-20% 只有 1 樣本訊號弱、60-80% 有 4 樣本對照訊號強

方法論演化小結

版本	修改	驅動來源
v0	直覺套 overview 11 章節	第一篇 deep article 不合用
v1	6 段結構 + 200-400 行 sweet spot	第一輪 5 篇 dogfood
v1.1	6 段是內容指引、不是章節標題模板	章節 1 framing 自然分化
v1.2	寫作時間預估 2-4hr → 1-2hr	overview 已建立 context
v1.3	cadence audit 抽樣位置 10-20% → 60-80%	第二輪 N=5 驗證

Case-First + Agent Team Review：教學內容的生產流程

Wed, 13 May 2026 00:00:00 +0000

這篇要說什麼

寫教學文章時、純靠 LLM 自生內容會踩到兩個系統性盲點：

Scope 盲點：內容停在「教科書級」結構、漏掉真實事故才會浮現的失敗模式跟設計取捨。
準確性盲點：把通用 best practice 包裝成「[case] 揭露」、把案例沒講的細節寫成案例事實。

本文整理在 backend/01 至 backend/07 batch 1 七個模組撰寫過程中浮現的五階段流程：

完整閱讀案例庫、抽 findings — 用案例驅動「該寫什麼」、不只是 LLM 自生
基於 findings 建立內容 — findings 分布到章節、避免硬塞模板
Agent team 平行多輪審查 — 用 3 個專責 reviewer 補 LLM 自盲點
修正循環 — 按檔案批次修 high + 重要 medium、reviewer 抓出問題各章節對應修
Polish pass — 跨檔系統性 pattern 集中處理（負向骨架掃描、編號漂移、用語不一、cross-link 補漏）

實作數據：7 個模組（backend/01-07 batch 1）、~45 章 / 385 個 review issue、case fidelity 落在 70-93% 區間、修正後品質升至 0 critical 編造、cross-link 全綠、規範違反 polish pass 後降到單位數低 issue。06 模組後方法論工具化為可觸發 skill、stage 1-5 流程跟 reviewer prompt template、self-scan regex 都封裝成可重用元件。07 模組驗證下「章節已有 routing layer skeleton」的特殊處理（在現有結構內補 case-driven 深化段、不擴成厚重章節）。

問題：LLM 自生內容的兩個盲點

純靠 LLM 寫教學章節、容易產出兩種品質風險：

Scope 盲點：LLM 從訓練資料抽出的內容偏 普遍性、是「教科書 + 部落格 + 文件」的綜合。但真實工程議題的判讀條件常常來自 特定事故揭露、不是普遍知識。例：

「DynamoDB GSI 在 backfill 完成前查不到完整資料」這種具體陷阱
「Super Bowl +50% no sweat 的工程意義是 headroom 提前預留、不是 vendor 神奇」這種反直覺判讀
「99.99% → 99.999% 是指數成本、遠超直覺的 10x 線性想像」這種規模對照

純技術知識推導不出來、要看真實案例才會浮現。

準確性盲點：LLM 寫到「對應 [case]」時、容易把通用 best practice 包裝成案例事實、或把案例沒提到的細節擴寫成「案例揭露」。例（從本文討論的實作中抓出的真實 issue）：

Snowflake 案例描述「異常查詢偵測維度（query 體積 / IP / 跨 schema scan）」、LLM 自生內容寫成「query 體積從 1MB / 天跳到 10GB / 天、來源 IP 從 office network 變 unknown VPS」— 具體數字是 LLM 加上去的、案例沒寫
Tixcraft 案例策略段建議「composite key」、LLM 自生內容寫成「Tixcraft 用 user_id 分散、不是 event_id」— 案例沒揭露 Tixcraft 實際 partition key 設計

這兩類盲點都不容易在 self-review 時抓到、因為 LLM 看不出自己內容是否真的對應案例。

階段 1：完整閱讀案例庫、抽 findings

為什麼要完整閱讀、不能只看 title + description

只看 title + description 能做承接（建立 link）、但無法做 scope 擴展（揭露 LLM 不會自生的議題）。case 的 findings 通常埋在 body 的「判讀」段、不在 description 裡。

實作中的對照：第一輪 audit 6 個 case、每 case 平均揭露 2.3 個 finding；其中約 7 成是 description 跟 title 看不到、要讀完整 body 才能抽出。例如 DraftKings 案例的「讀寫雙峰錯位」（比賽中讀爆量、payout 時寫爆量）— description 只說「financial ledger」、要讀「核心負載形狀」段才看到雙峰結構。

邊際遞減的判斷

不是所有 case 都要讀。實作中觀察到的遞減曲線：

輪次	讀案例數	揭露 findings	平均 / case	純新議題
第一輪	6	14	2.3	~95%
第二輪	5	15	3.0	~85%
第三輪	5	13	2.6	~60%

第三輪開始 純新議題 比例下降、重複 frame 出現（vendor dogfood 在 3 個 case 都揭露、benchmark 對照基準在 3 個 case 都揭露）。這是停止 audit 的訊號。

判讀條件：

繼續 audit：每 case 至少 1.5 個純新議題、且重複 frame 不超過 30%
停止 audit：純新議題 < 1 個 / case、重複 frame > 50%、累積 finding 數已涵蓋目標章節主要議題

實作中 11/94 cases（~12%）時邊際遞減訊號明顯、16/94 cases（~17%）時停止 audit、抽出 ~42 個 unique findings、足以支撐 6 個章節的 scope 擴展。

Findings 抽取方法

讀 case 時、把每個段落看成可能的 finding 來源、問三個問題：

這段揭露什麼判讀條件？（是不是純技術推導不易浮現的議題）
這段揭露什麼數字 / 設計細節？（規模、percentile、partition key 數量、replication lag 量級）
這段揭露什麼失敗模式？（事故當下會出什麼問題、有什麼反直覺結論）

寫進 findings 列表時、要附上 case 來源 跟 該對應到哪個章節。例：

Finding: 線性擴展是 OLTP 設計最高目標、coordinator 是傳統 OLTP 的擴展瓶頸來源: 9.C10 Spanner 案例「2 nodes → 45K reads/sec, 4 nodes → 90K reads/sec」段章節: 1.11 全球分散式 OLTP

不寫來源跟章節定位、findings 會變成抽象列表、寫稿時用不上。

Case 類型的承接策略

不同 case 類型適合不同承接深度、誤判類型會引發 over-extrapolation 問題。實作中觀察到的兩類 case：

Rich case（典型：09/07 案例庫中含具體數字、設計細節、遷移路徑的長篇 case）：

內容深度：50-200 行、含具體數字、業務情境、引用源
承接方式：可直接引用為事實、case 揭露的具體數字（RPS、延遲、TPS、stale window）可放進章節
例：9.C5 Amazon Ads「90M RPS + 5M writes/sec + 99.999%」可直接寫進 1.10 KV 章節
例：9.C6 Tinder「4700 萬 MAU 配對引擎、cache 是主要服務面」可直接做為 2.1 high-concurrency 的判讀依據

Medium case（06 模組新發現的類別、典型：模組內部 case 庫中含結構化「決策機制」+「可觀測訊號」表、但無具體數字的中篇 case）：

內容深度：30-50 行、結構化 5 段（問題場景 / 決策機制 / 可觀測訊號 / 常見陷阱 / 下一步路由）、含 mechanism + 訊號名稱、但不給具體數字
承接方式：用 case 直接列出的 mechanism 名稱 精準引用、比 skeleton 精準、但比 rich 保守
承接句型：「對應 [case]：揭露 N 個機制 — A、B、C、D」
例：6.C1 Amazon Shuffle Sharding 揭露 cell boundary / shuffle sharding / static stability / constant work 四機制、可直接引用機制名稱、但不擴寫到「具體 shard 數量」「具體 cell 大小」等 case 沒提的實作細節

Skeleton case（典型：模組內部 N.Cx 案例庫中只有 frame、無具體數字的短篇 case）：

內容深度：10-30 行、只給方向、無具體數字 / taxonomy
承接方式：作為「視角 / 方向」、可引用為「case 揭露 X 議題」、但不引用為「case 揭露 X 具體場景數量」
例：2.C1 Meta Cache Consistency 只有「promotion、shard move、故障恢復」三個方向、不引用為「具體 inconsistency window 數字」
例：3.C9 反例只給「依賴特定 offset / 重試節奏 / idempotency」三個方向、不引用為「4 個具體誤配場景」

判讀條件：

看 case 行數 + 內容密度判斷類型
skeleton case 的 finding 寫成「對應 [case] — 揭露 X 方向、以下展開基於通用工程知識補充」
medium case 的 finding 寫成「對應 [case]：揭露 N 個機制 — A、B、C、D」、用 mechanism 名稱精準引用
rich case 的 finding 可寫「對應 [case] — XXX 具體數字 / 設計」

實作中（01/02/03 三個模組驗證）、skeleton case 寫成 rich case 對應是 case fidelity reviewer 抓出 over-extrapolation 的主要來源（02 / 03 各 3-4 個 critical 編造都來自此陷阱）。誤判類型 → 編造 case 沒寫的細節 → reviewer 抓出 → 修正成本高。stage 1 抽 findings 時就要 標明 case 類型、stage 2 寫作時依類型決定承接深度。

Rich case 引用的反向風險（04/05 模組新發現）：rich case 雖然可以引用具體數字、但 case 內常含「觀察層」（具體 fact）跟「判讀層」（作者推論）兩段、引用時要分開處理。05 模組驗證時 case fidelity reviewer 抓出 4 個 high issue 都來自把「判讀層作者推論」寫成「case 揭露的 fact」：

9.C12 Riot Games：5.2 寫「揭露 35ms latency 反推 region 部署」、實際 case 的「35ms」是觀察層、「反推 region 部署」是作者判讀層
9.C34 GCP 130K：5.2 寫「揭露 Spanner 替 etcd 才是 K8s 規模極限的關鍵」、實際 case 用更保守的「control plane 極限取決於 storage backend、GCP 用 Spanner 替換 etcd」分兩個點寫
9.C12 Riot：5.2 引用「single-tenant per game 的多 cluster 策略」、漏掉 case 揭露的關鍵歷史轉折「從 multi-tenant cluster 模型改成 single-tenant per game」

修法：rich case 引用時、用「揭露 X 觀察 + 作者判讀 Y」分層標明、避免把推論寫成 fact。或在引用後補一句「（case 中 X 屬作者判讀層、本章引用此推論）」明示分層。

兩類 case 的引用紀律可總結成一個 fact vs derive 分層原則：

Skeleton case：絕大多數內容是 derive（方向 / 議題）、引用時不擴寫成 fact
Rich case：含 fact（具體數字 / 設計）跟 derive（作者判讀）、引用時分層標明、避免把 derive 升級成 fact

階段 2：基於 findings 建立內容

Findings 分布到章節

抽完 findings 後、按章節主題分類、看哪個章節缺口最大、哪個 finding 該寫去哪。實作中的分布：

1.1 高併發：7 findings
1.5 紅隊：8 findings
1.9 reconciliation：4 findings
1.10 KV：6 findings
1.11 全球分散式：10 findings（最大缺口）
1.6+1.12 migration：5 findings

涉及多軸取捨的章節（1.11 一致性 / 可用性 / 成本 / 延遲）暴露最多缺口、純流程章節（1.9）暴露最少。這是 章節結構性質 的差異、不是寫得好壞。

Stage 2 寫作前先定 SSoT 對應

當同一 finding 或 frame 在 多個章節 都有用、要在開始寫之前 先定 SSoT 對應、否則 case-driven 擴章必然出現 frame 重複展開。

實作中觀察到的反例（02 / 03 模組都遇到過）：

02 cache：「cache 角色變化」frame 在 2.1 主寫但實際屬模組層級、應在 _index；Tubi 案例在 2.1 / 2.2 / 2.8 三章各自展開 mini-finding；Snap KeyDB 在 2.1 / 2.7 / 2.8 三章重複
03 message-queue（最嚴重）：「三層語意（delivery / processing / recovery）」在 3.4 / 3.6 / 3.8 三章各自定義；「Slack Kafka+Redis 拓樸」在 3.4 跟 3.8 兩章逐字重複；「規模對照（小 / 中 / 大型）」在 3.4 / 3.6 / 3.8 三章拆用、結論散落讀者拼不出總圖

SSoT 對應的判讀順序：

列出所有 cross-chapter findings（出現在多章的 frame）
每個 frame 指定一個主寫章節（SSoT）
其他章節 只 link、不展開
SSoT 章節要有完整論述、被引用章節保留簡述跟 cross-link

SSoT 選擇標準：

frame 涉及 跨模組層級概念 → 寫進 _index.md
frame 涉及 單章核心責任 → SSoT 為該章
frame 涉及 跨章交接點 → 選最相關章節為 SSoT、其他章節 link

漏掉這步、reviewer 跨章一致性會抓出 5-10 個 frame 重複 issue、修正成本高（要把已展開內容收斂回 SSoT）。Stage 2 前花 30 分鐘做 SSoT 對應、能省下 Stage 3 數小時的重構工。

避免硬塞模板

最大的反模式是把多個 findings 硬塞成同一個 table、每 row 一短語、失去情境敘事。

實作中的反例：1.9 章新增「Dual-track IC 5 個角色表」、本來想用表格整齊呈現、但 reviewer 抓出「5 角色平鋪、責任只一行、未展開每角色在真實事故的決策樣態」。修正後拆成：

主表格（5 個角色快速對照）
Overall IC 跟 Tech IC 的差異獨立段（300 字）
Data IC 的特殊角色獨立段（300 字、含「為什麼不能讓 Tech IC 兼任」的失誤對照）
事先準備 4 項各自延伸（不只列項目、解釋失效樣態）

這樣 每個項目都是情境 而非 硬塞的欄位、符合 AGENTS.md「表格不是終點」原則。

情境敘事的判讀條件

每段內容寫完後、問三個檢查問題：

首句是不是核心原則？（不是「某 case 揭露 X」、是「X 是什麼、承擔什麼責任」）
是不是用否定句主導？（「不是 X」「不只 X」開段要回到正向陳述）
這個 finding 在不同情境下是否會變義？（一個 finding 套到多個情境、要分情境寫、不是套同模板）

案例引用的準確性

寫「對應 [case] — XXX」時、要回 case 原文驗證 XXX 是否真的出現。實作中常見的失分：

把 case 沒提到的數字補進去（「30-90 天 baseline」、「1MB→10GB / 天」）
把通用 best practice 寫成案例事實（「Snowflake 之後改為預設強制 MFA」— case 只說「資料平台應預設強制 MFA」、不是描述後續行動）
公開事實但 case 沒寫（「MOVEit 跨上百家客戶」、「LastPass master password 弱可被離線爆破」）

寫稿當下不容易抓、要靠階段 3 的 case fidelity reviewer 對照。

階段 3：Agent team 平行多輪審查

為什麼要 agent team、不能交給單一 reviewer

單一 reviewer 有兩個限制：

維度盲點：一個 reviewer 同時看寫作規範、案例準確性、跨章一致性、容易 維度互相干擾、最後每個維度都看不深
Context 污染：reviewer 讀完整 commit + 所有案例 + 所有章節後、自身 context 就被佔滿、給的建議會 對應主 context 也跟著沉重

解法是用 3 個專責 reviewer、平行 background 跑、各自獨立報告、主 context 只看精煉摘要。

三個維度 reviewer 分工

實作中使用的三個 reviewer：

Reviewer A：寫作規範審查（AGENTS.md 核心原則）

對照核心原則先行、正向陳述優先、商業邏輯先於 case、表格不是終點、情境優先於模板、可操作判準等八原則
找首句用否定句切入、表格 / bullet 平鋪沒延伸、表格項硬塞模板等
實作中抓出 25 個 issue

Reviewer B：案例引用準確性

對照原始 case 內容、驗證「對應 [case] — XXX」斷言是否真的來自案例
識別編造數字、過度推論、把通用 best practice 寫成案例事實
實作中抓出 9 個 issue、包含 3 個 critical 編造

Reviewer C：跨章一致性

跨多章找重複 frame、矛盾說法、失效 cross-link、章節邊界錯位
識別「該在 A 章卻寫在 B 章」、「frame 重複展開沒整併」
實作中抓出 13 個 issue

平行 background 跑、不佔主 context

關鍵設計是 3 個 reviewer 並行、各自 background、各自寫 output file、不污染主 context：

主 context 只看到「啟動 reviewer」跟「reviewer 完成的彙整報告」
Raw output 跟 reviewer 的 deep dive 留在 output file、需要時 SendMessage 繼續對話
3 個 reviewer 完成時間 ~5-15 分鐘、可以同時跑、不必等

實作中 3 個 reviewer 平均 2-3 分鐘完成、主 context 增量 ~3K tokens（彙整 + 47 issue 清單）、相比把所有案例跟章節塞進主 context 做 review 節省 ~80% context。

Reviewer issue 數量的 baseline

7 個模組（01 / 02 / 03 / 04 / 05 / 06 / 07 batch 1）驗證後、每模組 reviewer 抓到的 issue 數量在 standards reviewer 抓 pattern 越來越細的趨勢下持續擴大、可作為流程預期：

Reviewer 維度	01	02	03	04	05	06	07 b1	baseline
Standards reviewer	25	20	20	31	28	45	31	20-45 issue
Case fidelity reviewer	9 (88%)	20 (78%)	15 (70%)	6 (92.9%)	13 (80%)	11 (88%)	8 (81%)	6-20 issue
Consistency reviewer	13	15	15	14	18	15	13	13-18 issue
總計	47	55	50	51	59	71	52	47-71 issue

模式觀察：

每模組 issue 數隨 standards reviewer 抓 pattern 越來越細而擴大：01-03 穩定在 47-55、04/05 推到 51-59、06 推到 71、07 batch 1 回到 52（章節已有 routing skeleton、擴章規模小）。趨勢來自 standards reviewer 抓的 pattern 越來越廣（從負向骨架 → 「核心責任不是」變體 → 「沒有 X 會 Y」鏈式 → 「case 引用段首」框架 → 「case 引用句構同質化」）。
Case fidelity 準確率分布更廣：04 的 92.9% 來自 skeleton case 嚴守「揭露方向、通用補充」紀律；05 的 80% 因引用 09 rich case 加入「fact vs derive 分層」新失分模式；06 的 88% 屬 medium case 紀律首次套用、揭露「實作層擴寫過頭」失分；07 batch 1 的 81% 揭露「跨 case 合成 frame」新失分類型（reviewer B 2 high 都屬此類）
Consistency reviewer 抓到的 frame 重複跟章節數成正比：02 / 03 / 04 都有 ~13-18 個一致性 issue、05/06 跨模組 cross-link 密度高仍維持在 baseline 內、07 batch 1 因 7 章規模、issue 13 個落在 baseline 下緣

Stage 3 修正成本估算：

Critical（編造、矛盾）：~每個 5-10 分鐘修正、佔 0-5 個（04/05 都 0 critical、紀律已成熟）
High（重複 frame、章節邊界、判讀層 vs fact）：~每個 10-20 分鐘修正、佔 5-14 個
Medium / Low（規範細節、cross-link 補）：~每個 2-5 分鐘修正、佔 35-45 個
總計 ~1.5-2.5 小時 / 模組

Stage 4 修正後仍會有 ~30-40% issue 殘留（low / medium 的 cross-link、編號漂移、用語不一）、屬於系統性 pattern、適合在 Stage 5 polish pass 集中處理（見後段）。

為何要多輪 review、不是一次到位

第一輪 review 的目的是 找問題、不是 修問題。問題清單列出後、要做兩件事：

分類優先序：critical / high / medium / low、按嚴重度跟修改成本排序
修正循環：批次修正、避免一個一個改散開、修完再跑驗證

修正後可選擇性做第二輪 review、檢查：

修正本身有沒有引入新問題
之前 reviewer 漏掉的維度（例：教學性、讀者路徑、實作可行性）
跨 commit 一致性

實作中第一輪足夠處理 47 個 issue、第二輪沒進行、留到未來模組（02 cache、03 message queue）累積經驗後再評估是否必要。

修正循環的執行原則

47 個 issue 分布到 6 個章節、修正時 按檔案批次、不是按 issue 編號順序。每個檔案一次修完所有相關 issue、減少切換成本：

1.5 紅隊章（12 issue）：含 2 個 critical 編造、優先處理
1.10 KV（7 issue）：含 1 個 critical 編造
1.11 全球分散式（5 issue）
1.12 大規模遷移（10 issue）：表格密度最高、最多延伸
1.1 高併發（4 issue）
1.9 reconciliation（5 issue）

每個檔案修完後跑一次 mdtools fmt --fix + mdtools cards + mdtools lint、確認該檔內部一致、再進下一檔。最後跑一次跨檔驗證、確認 cross-link 全部對齊。

階段 5：Polish pass（04/05 模組後新增）

Stage 4 修完 high + 重要 medium 後、仍有 ~30-40% 的 low / medium 殘留、屬於系統性 pattern（負向骨架、編號漂移、cross-link 缺漏、模板化）。這些 issue 不適合按章節批次修、適合用「跨檔系統性掃描」處理 — 這是 polish pass 的核心責任。

Polish pass 的觸發條件

Stage 4 後出現以下任一訊號、就該排 polish pass：

Standards reviewer 抓出的「不是 X、而是 Y」段首結構超過 5 處（屬寫作習慣、單章修改無效率）
Consistency reviewer 抓出「編號漂移」「失效 link」「用語不一」多處（屬跨檔規範問題）
自掃描漏掉的 pattern 出現在 reviewer report（例：04 自掃描說 pass、reviewer A 抓出 31 個 issue、暴露自掃描 regex 不夠寬）

Polish pass 不該做的事

不重寫章節結構：polish pass 是把現有內容修得更貼合規範、不是重新組織。重寫的觸發條件應該回到 stage 2、不是 polish pass。
不擴大 scope：原本 4.20 / 5.4 等不在擴充範圍的章節、polish pass 也不動。Polish pass 邊界 = stage 4 修改過的章節集合。
不追求 0 issue：reviewer 抓的 ~15 個 low 通常可保留為下次擴章節時自然處理。Polish pass 處理「系統性 pattern」、不處理「孤立 issue」。

Polish pass 的標準工序

按系統性 pattern 分批處理、每批跑一次自掃描確認：

負向骨架掃描修正：用更寬泛的 regex 不是 |而不是|沒有.*[，、]會 掃描、把「不是 X、而是 Y」「而不是 X」改成正向陳述 + 後置邊界提醒。技術約束敘述（「多人共用 IP 無法區分」）保留。
編號漂移統一：把 04.X 風格 plain text 改成 [4.X title](url) markdown link、跟 _index 對齊。
表格延伸段補強（關鍵段）：選 2-3 個最高 impact 表格（判讀訊號表的爭議列、Buffer / Sampling 等選型表）補延伸子段、不全部補（避免擴展超出 scope）。
模板化拆敘事（代表性段）：選 1-2 個最明顯的「四步驟模板套不同情境」段、拆成情境化敘事、其他保留為下次。
Cross-link 補漏 + ownership 邊界補強：reviewer C 報告的所有 cross-link 缺漏一次補完、用同一個批次跑 mdtools 驗證。
用語不一統一 + 失效 link 修正：簡轉繁、/knowledge-cards/ vs /section/ URL 統一、失效 link 改規劃中或正確路徑。
最終驗證 + commit：跑 mdtools fmt --fix && mdtools cards && mdtools lint、確認全綠、commit。

Polish pass 的實作成本

實作中（04 / 05 polish pass 合併 commit 1072087）：

處理範圍：11 個檔案、+44 / -29 行
修正項目：~35 個 issue（10 個負向骨架、2 個模板化、3 個編號漂移、3 個表格延伸段、3 個 cross-link、1 個 case 引用結構）
時間：~30-45 分鐘（不重寫、只 pattern match）
剩餘 ~15 個 low 保留下次

Polish pass 的 ROI 來自「系統性 pattern 一次處理 vs 散在各章一個個改」的效率差異。每個 pattern 在多章重複出現時、用 grep / rg 跨檔修一輪比每章單獨修快 3-5 倍。

自掃描盲點更新

04 流程暴露了一個 self-scan 盲點：原 regex 不行|不可以|不要|無法|不能 漏掉「核心責任不是 X、而是 Y」這個變體段首。修正建議：

加 ^[^|].*責任(不是|並非) 抓「核心責任不是 X」變體
加 ^[^|].*[，,]而是 抓「X、而是 Y」結構（已是正常陳述、但段首位置仍是負向骨架）
加 ^[^|].*[，,]不是 抓「X、不是 Y」結構

把自掃描 regex 視為持續演進的工具、每個 reviewer 抓出新 pattern 就更新一次、避免在下個模組重蹈覆轍。

適用情境跟限制

適用情境

長期累積的教學模組：6+ 章、跨章引用密集、規範遵循重要
有現成 case 庫：07/09 累積的 100+ 案例是這套流程的前提、沒案例庫做不到 case-first
品質高於速度：完整三階段約 3-4 小時 / 模組（stage 2 寫作 ~1.5-2hr + reviewer ~15 分鐘 + stage 3 修正 ~1.5-2hr）、適合長期累積的內容、不適合 one-off 文章
主 context 容量敏感：reviewer 平行 background 是節省 context 的關鍵設計

不適用情境

新主題沒案例庫：要先建案例庫、不能直接套這流程
單篇短文：流程的固定成本（讀案例 + 跑 reviewer）對短文 ROI 低
快速迭代原型：流程偏向 寫一次寫好、不是 快速修改
Routing layer / 導讀性質章節：已含完整 threat scope + 引用標準 + 問題節點表、case 庫不對應或缺位、應跳過本流程、用標準引用 + 通用工程知識補充承接（07 LLM / 治理章節驗證）
Standard framework 比 case 庫成熟的領域：見下段「Standard-driven 取代 case-driven」

Standard-driven 取代 case-driven（07 LLM 章節驗證）

在標準框架比 case 庫成熟的領域、case-driven 不是預設選擇。LLM 安全章節跑完 5 章驗證後浮現一個 finding：當該領域的 標準框架（如 OWASP LLM Top 10 2025 / NIST AI RMF 1.0 / MITRE ATLAS）已涵蓋 threat 分類、且 case 維護半衰期短於 standard、章節應 用 standard-driven 取代 case-driven。Standard-driven 跟 case-driven 是平行選項、依領域特性選用 — 兩者沒有退化 / 進階關係。

判斷該用哪種策略的四維度：

維度	Case-driven 適用	Standard-driven 適用
議題穩定度	高（5+ 年穩定）	低（< 1 年快速演進）
Case 公開度	高（充分的事故公告）	中或低（vendor disclosure 偏 marketing）
Standard 成熟度	中（多用 case 而非 standard）	高（standard framework 已成型）
維護半衰期	長	短（6 個月過時）

典型對照：

Case-driven 領域：分散式系統 / 安全控制面 / 可靠性 / 訊息佇列（backend/01-07 batch 1 都屬此類、案例公開充分、半衰期 5+ 年）
Standard-driven 領域：LLM 安全（OWASP LLM Top 10 / MITRE ATLAS 已成型、案例 6 個月過時）、新興 compliance（NIST AI RMF）、cloud-native 標準（CNCF baseline）

Standard-driven 章節的寫作策略：

章節對齊 standard framework 分類：用 framework 章節 ID 標明（如 OWASP LLM01 / NIST AI-1.1）取代「對應 [case] —」斷言
加 Last reviewed cadence：每 quarter 重評估 standard 版本跟章節對應、寫進 frontmatter
「案例觸發參考」段標明「公開案例累積中、值得追蹤的方向」：不寫「對應 [case] 揭露」斷言、避免引用源不穩定
引用標準時用版本號：OWASP LLM Top 10 2025 / NIST AI RMF 1.0 / MITRE ATLAS continuous — framework 改版要 trigger 章節重審

實證：07 LLM 章節 5 章已套用 standard-driven 策略：

章節 113-137 行、含完整 threat scope + 問題節點表 + 風險邊界
引用 OWASP LLM Top 10 + NIST AI RMF + MITRE ATLAS 取代個別 case 引用
加 Last reviewed: 2026-05-12 cadence
「案例觸發參考」段寫「公開案例累積中、值得追蹤的方向」+「事實查核註」
完全不寫「對應 [case] —」斷言、不存在 case fidelity reviewer 該抓的準確性問題

對照 backend/01-07 batch 1 的 case-driven 章節、LLM 章節是 用不同方法達到同樣品質 — scope 涵蓋真實 production 議題（KV cache 跨租戶、shared prefix optimization、batch 推論順序敏感）、不停在教科書級內容。

何時要從 standard-driven 轉回 case-driven：

該領域累積 5+ 個高可信度 case（vendor disclosure + academic paper + CVE 三來源交叉）
跨章 frame 重複出現、case-driven mechanism 深化能解 SSoT 衝突
出現「等級類似 SolarWinds」的 incident、案例本身夠重、單一 case 即可支撐章節擴章
讀者反饋章節太抽象、需要具體 case 才能理解 mechanism

不滿足任一條件時、繼續走 standard-driven、不勉強建 case 庫。

對 case-first-module-workflow skill 的補強：

skill 之前的「不適用情境」寫「沒 case 庫的新主題（要先建 case 庫）」— 這暗示缺 case 庫一定要先補。07 LLM 章節驗證了第三條路：用 standard-driven 取代、適用 standard framework 比 case 庫成熟的領域。這個 finding 已補進 skill 的「不適用情境」段。

限制

Reviewer 維度有限：當前 3 個 reviewer 沒覆蓋「教學性」「讀者路徑」「實作可行性」、若主題需要這些維度、要加 reviewer
修正可能引入新 issue：第一輪 review 後修正、修正本身可能違反規範、若大量修正最好做第二輪
Case 庫品質決定 findings 品質：case 寫得淺、findings 也淺；case fidelity reviewer 也只能驗證「跟 case 一致」、不能驗證「case 本身對不對」
依賴 LLM agent 平台能力：流程預設可平行跑 background agent、不是所有 LLM 平台都支援

7 個模組驗證後的反覆陷阱

01 / 02 / 03 / 04 / 05 / 06 / 07 七個模組執行下來、以下陷阱在 多數模組都重複出現、屬於 LLM case-driven 寫作的系統性失分點。本流程下次套用前要 主動防範、不能依賴 stage 3 reviewer 補救（雖然 reviewer 都會抓到、但修正成本高）。

陷阱 1：Skeleton case 擴寫成 case 事實

當 case 內容簡短（10-30 行、只有 frame 沒有具體數字 / taxonomy）、LLM 寫作時容易把通用知識（具體數字、攻擊向量列表、設計細節）寫成「對應 [case] —」斷言。實際 case 沒寫的。

實證：

01 紅隊：Snowflake「30-90 天 baseline」編造、Tixcraft「partition key 用 user_id」編造
02 cache：Tubi 三層 cache 具體 latency（L1 < 1ms、L2 < 10ms、L3 10-100ms）編造、Redis「100K-200K ops/sec」無來源、KeyDB「5-10x throughput」其實是 case 判讀段非引用源
03 messaging：PayPay「broker 寫入 3K msg/sec」實際 case 寫的是「DynamoDB 寫入 3K msg/sec」（PayPay 用 DynamoDB 不是傳統 broker）、3.C9 case 三個方向被擴寫成「4 個誤配場景」、3.C10 case 「大型服務 DLQ 是診斷入口」完全編造

防範：

Stage 1 抽 findings 時 標明 case 類型（rich vs skeleton）
Stage 2 寫 skeleton case finding 時、用「對應 [case] — 揭露 X 方向、以下展開基於通用工程知識補充」這種 fact vs derive 標記
不要為了「整齊的 4 個攻擊面」「3 個攻擊向量」「5 個誤配場景」這種數字感、把 case 沒寫的 taxonomy 寫成 case 揭露

陷阱 2：Frame 重複展開（SSoT 不清）

同一概念在多章 case-driven 擴章時各自展開、形成 frame 重複。讀者跨章讀會踩到重述、結論散落拼不出總圖。

實證：

01：容量三口徑 frame 在 1.1 跟 1.12 重複展開、storage / compute 分離 frame 在 1.1 跟 1.11 重複
02：cache 角色變化 frame 在 2.1 主寫但屬模組層級、應在 _index；Tubi 案例在 2.1 / 2.2 / 2.8 三章 mini-展開
03（最嚴重）：三層語意（delivery / processing / recovery）在 3.4 / 3.6 / 3.8 三章各自定義；Slack Kafka+Redis 拓樸在 3.4 跟 3.8 兩章逐字重複；規模對照在 3.4 / 3.6 / 3.8 三章拆用

防範：

Stage 2 寫作前花 30 分鐘做 SSoT 對應（見前面「Stage 2 寫作前先定 SSoT 對應」段）
列出 cross-chapter frames、指定唯一主寫章節、其他章節只 link
寫每章前問「這個 frame 主寫在哪？我現在寫的是主寫還是 link？」

陷阱 3：負向陳述 + 模板化（規範系統性失分）

「不是 X、是 Y」推進論證、L1/L2/L3 三層平鋪、三選一表格、四步驟流程。這兩個原則違反在每模組都重複出現、是 LLM 寫作的反覆模式、stage 3 standards reviewer 每模組會抓 10-20 處。

實證：

01 規範 violation：表格不延伸（7 處）、負向陳述（5 處）、首句結構（4 處）
02 規範 violation：原則 8 模板化（6 處）、原則 2 負向陳述（6 處）、原則 4 表格不延伸（4 處）
03 規範 violation：原則 2 負向陳述（12 處最嚴重）、原則 1 首句結構（5 處）、原則 6 用語節制（2 處）
04 規範 violation：原則 2 負向陳述（12 處最嚴重、含「核心責任不是 X、而是 Y」變體段首）、原則 1 首句結構（9 處）、原則 4 表格不延伸（9 處）
05 規範 violation：原則 2「不是 X、而是 Y」+「沒有 X、會 Y」（10 處）、原則 8 四步驟 / 四層並列模板（7 處）、原則 3 case 引用框架取代商業邏輯先行（6 處）

防範：

Stage 2 寫完後 寫稿端就跑掃描、不等 reviewer：
- rg -n "不行|不可以|不要|無法|不能" 找負向骨架（技術約束敘述例外）
- rg -n "^[^|].*責任(不是|並非)" 找「核心責任不是 X」變體段首（04 模組新發現的 pattern）
- rg -n "^[^|].*[，,]而是|^[^|].*[，,]不是" 找對比骨架開段
- 自查表格：每個 bullet 是否有後文延伸？
- 自查首句：是否「核心原則先行」而非「對應 [case] 揭露」
模板化（L1/L2/L3、三選一）出現時、先問「這三項是真的對等？還是業務情境不同？」— 不同情境的話拆敘事段、不用表格

陷阱 4：Rich case 判讀層被當 case fact 引用（04/05 模組新發現）

引用 09 / 07 等 rich case 時、case 內常含「觀察層」（具體 fact）跟「判讀層」（作者推論）兩段。LLM 寫作時容易把兩層壓縮成「揭露 X」、把作者判讀升級為 case fact。

跟陷阱 1（skeleton case 擴寫成 case 事實）的差別：

陷阱 1：case 沒提的細節（具體數字、taxonomy）被寫成 case 揭露
陷阱 4：case 有提、但屬作者判讀層的內容被寫成 case fact

實證：

05 / 9.C12 Riot：5.2 寫「揭露 35ms latency 反推 region 部署」、實際 case 的「35ms」是觀察層、「反推 region 部署」是作者判讀層
05 / 9.C34 GCP：5.2 寫「揭露 Spanner 替 etcd 才是 K8s 規模極限的關鍵」、實際 case 用更保守的「control plane 極限取決於 storage backend、GCP 用 Spanner 替換 etcd」分兩個點寫、章節壓縮 + 強化成硬性結論
05 / 9.C12 Riot：漏掉 case 揭露的關鍵歷史轉折「從 multi-tenant cluster 模型改成 single-tenant per game」

防範：

引用 rich case 前、先把 case 內的「觀察段」跟「判讀段」分開讀、抽 finding 時各自標明來源層
引用時用「揭露 X 觀察 + 作者判讀 Y」分層寫、或在引用後補一句「（case 中 X 屬作者判讀層、本章引用此推論）」
避免使用「才是 / 必須 / 一定」這類強化詞、保留 case 原文的條件性表述
Stage 3 case fidelity reviewer 的 prompt 要特別點出「判讀層 vs 觀察層」的分界、把這當作 high 級 issue 抓取

陷阱 5：自掃描盲點累積（04/05/06 模組持續顯現）

自掃描的 regex 跟 reviewer 抓的 pattern 會逐漸脫節。每個模組 reviewer 會發現新 pattern、self-scan regex 跟著演進、但 reviewer 仍會發現下一個。

實證：

04 自掃描用 不行|不可以|不要|無法|不能 跟「不是 X、是 Y」掃描通過、但 reviewer A 抓出「核心責任不是 X、而是 Y」變體段首（佔 12 處）
05 自掃描通過、但 reviewer A 仍抓出「沒有 X、會 Y」鏈式負向句構 + 「四步驟模板」+ 「case 引用框架取代商業邏輯先行」三類新 pattern
06 self-scan 加了「不是 X、而是 Y」變體 + 「沒有 X 會 Y」、仍漏掉「對應 [case]：揭露 N 個機制」段首取代核心概念句的 pattern（reviewer A 抓 45 issue、其中 11/12 新段都犯這個錯）

防範：

每個模組 reviewer 抓出新 pattern 後、回頭更新 self-scan regex
把 self-scan 視為持續演進的工具、不是固定 checklist
Stage 5 polish pass 是處理自掃描盲點累積的標準入口（見前段）
06 模組後 self-scan 加 rg -n "^對應 \[" 抓段首 case 引用框架

陷阱 6：Case 引用段首取代核心概念句（06 模組新發現）

LLM 從 case 反推內容時、容易把 case 揭露當概念出發點、寫成「對應 [case]：揭露 N 個機制 — …」段首結構。讀者尚未理解概念就被丟入案例細節、且跨章讀同句構會感同質。

實證：

06 模組 12 個新段中 11 個用「對應 [case]：揭露 N 個機制」相同句構作為 section 第二段
概念定義句被推到第二段或更後、商業邏輯先於 case 的原則被推翻

防範：

把 case 引用視為「三段式」結構：概念定義句 → case 引用 → 通用展開
寫每段時、先確認段首是「該概念是什麼、承擔什麼責任」、case 引用退到第二位置
Case 引用句構應變化：寫多章時刻意避免同句構連續超過 3 次
詳見 skill 內部原則卡 principles/case-citation-three-part（對應檔案 .claude/skills/case-first-module-workflow/references/principles/case-citation-three-part.md、屬 skill 內部 reference、不對外暴露）

陷阱 7：Medium case 實作層擴寫過頭（06 模組新發現）

Medium case（30-50 行、結構化但無具體數字）首次套用時、容易把 case 沒提的具體實作層擴寫進章節、把通用工程知識掛到 case 名下。

實證：

06 模組 6.12 idempotency-replay 從 S1「key 設計要跟業務邊界一致」一條方向擴寫成「key 來源 / TTL / fallback / 偽造防護 / 5 個 observability 欄位」5 條實作判讀、case 沒提這些細節
06 模組 6.14 dependency-reliability-budget 從 M1 region failover 擴寫成「thundering herd」機制名 + 「先恢復核心 region 最小集合」具體步驟、case 沒提這兩個

防範：

Medium case 引用用 mechanism 名稱 精準引用、不擴寫到 case 沒提的具體實作細節
引用後若要展開實作層、用「以下實作層判讀屬通用工程知識展開、case 本身只給 X 方向」明示分層
Case fidelity reviewer 的 prompt 要特別點出 medium case 的「實作層擴寫」失分類型

陷阱 8：跨 case 合成 frame 升級成 case 揭露（07 模組新發現）

當段落把多個 case 的失效訊號抽象為更高層 frame（如「跨工具回查壓力」「平台責任切分」）、LLM 會把章節合成的 frame 包裝成 case 揭露。讀者回查 case 時會發現章節說的「case 揭露 X」實際是章節 derive、不是 case 原文框架。

跟陷阱 1（skeleton case 擴寫成 case 事實）跟陷阱 4（rich case 判讀層當 fact）的差別：

陷阱 1：case 沒提的細節（具體數字、taxonomy）被寫成 case 揭露
陷阱 4：case 有提、但屬作者判讀層的內容被寫成 case fact
陷阱 8：case 單獨寫的訊號被章節 跨 case 合成 抽象為更高層 frame、frame 本身不在任一 case 原文

實證（07 batch 1 reviewer B 抓的 2 個 high issue）：

7.7 跨工具回查壓力：Uber 失效控制面寫「告警串接不足」、Slack 寫「訊號未匯流」— 都是單工具內訊號、章節合成「跨工具回查」axis
7.7 平台責任切分：SolarWinds 失效控制面寫「更新來源信任過於單點」「行為監測難以區分合法元件」— 都是供應鏈信任議題、章節合成「平台 vs 產品 audit 責任分離」frame

防範：

段落把多 case 抽象為更高層 frame 時、要 explicit 標明「frame 是本章合成、case 原文沒有此 frame」
修法範例：「兩個案例分別在 X 層揭露同類失效訊號 — A case 標明 B、C case 標明 D。本章把兩者抽象為『XXX』是 YYY 視角的合成 frame、非 case 原文框架。」
Stage 3 reviewer B prompt 要明示「跨 case 合成 frame 必須標為本章合成」是 high 級 issue 抓取項

陷阱 9：Case 引用句構同質化（07 模組新發現）

即使遵守 case 引用三段式紀律、跨章節 case 引用仍會出現句構同質化。13 處 case 引用 11 處用同一句構「揭露 N 層失效控制面 — A、B、C。案例『可落地檢查點』標明 mechanism 為 X、前提是 Y」。讀者跨章連讀時、會把 case 引用當儀式而非論證。

實證：07 batch 1 reviewer A 抓出 systemic medium issue (Issue 8.1)、13 段 case 引用 11 段用相同句構。Stage 5 polish pass 主動分流 4 處後狀況改善。

防範：

句構選擇要 跟著 case 類型走、不是隨機變化（case 直接列 N mechanism → 「揭露 N 層」；case 揭露單一壓力 → 「補的失效訊號是 X」；case 揭露對比 → 「揭露兩個層次的對照」）
Stage 5 polish pass 加句構分流為標準工序之一（跟負向骨架同層級）
自掃描 regex ^對應 \[ 抓不到此類問題（這是符合三段式的引用、只是句構單一）、要靠 stage 5 主動 scan：rg -c "揭露[^。]*失效控制面" 看同句構出現次數、超過 5 處要分流

「章節已有 routing skeleton」的特殊處理（07 模組新發現）

07 模組跟 06 / 09 不同之處：章節在 stage 2 前已有完整 routing layer 結構（threat scope / 從本章到實作 / 問題節點表 / 風險邊界 / 案例觸發 / 路由）— stage 2 是在現有結構內補 case-driven 深化段，而非空白擴章。

這個情境下：

SSoT 衝突更容易發生：新段落要跟既有章節結構協調、不只是新增內容。07 batch 1 三個 H issue（C-H1/H2/H3）都是 frame 跟既有章節 / 其他章節新增段衝突
章節寫作邊界要先確認：補強段聚焦在「現有問題節點表的 mechanism 深化」、不擴成厚重 case-driven 章節（避免章節結構失衡）
Cross-link 密度顯著上升：補強段要明示「本節聚焦 X 視角、canonical 在 Y 章」、否則 reviewer C 會抓 frame 重複展開

判讀條件：

章節已有 threat scope / 問題節點表 / 案例觸發段 → 走「補強段」策略、不空白擴章
章節是 routing layer / 導讀性質、不適合 case-driven 深化 → 跳過本流程
章節有 case 庫但 case 主要是 skeleton 型（30 行 frame） → 補強段嚴守「揭露 X 方向、通用補充」紀律、不擴寫實作層

衍生 insight：reviewer 維度沒覆蓋的部分

3 個模組跑下來、發現現有 3 reviewer 維度（規範 / 案例準確性 / 跨章一致性）有未覆蓋的問題：

教學性 / 讀者路徑：章節之間的閱讀順序是否合理？讀者讀完 A 章能不能銜接 B 章？目前沒 reviewer 檢查
判讀條件可操作性：寫了判讀訊號、但實際工程師能不能用這些訊號做決策？沒 reviewer 驗證
實作可行性：建議的設計是否真的能落地？跨團隊協調是否現實？需要懂業務的 reviewer

未來 6 / 7 / 8 模組執行時、可以考慮加第 4 個 reviewer 維度（教學性 + 實作可行性）。

跟其他寫作流程的差異

跟「LLM 自生 + 人工 review」比、本流程的差異：

維度	LLM 自生 + 人工 review	Case-first + Agent team
Scope 來源	訓練資料 + 提示詞	真實案例 findings
準確性檢查	人工讀完對比	Case fidelity reviewer 自動對照
規範遵循	人工 checklist	Standards reviewer 自動掃描
跨章一致性	人工跨檔 grep	Consistency reviewer 自動檢查
Context 成本	低（人工不佔 LLM context）	中（reviewer 各自佔自己 context、主 context 輕）
時間成本	高（人工逐段讀）	中（reviewer 平行）
真實事故揭露	受限於 reviewer 經驗	受限於案例庫覆蓋

跟「LLM 自生 + 自我 review」比：

自我 review 抓不到自生內容的盲點（self-blindness）
Agent team 是 不同 instance、不共享 context、能扮演獨立 reviewer

下一步

本流程在 backend/01 至 backend/07 batch 1 七個模組驗證後（共 ~45 章 / 385 review issue / case fidelity 70-93% 區間）、方法論已工具化為 case-first-module-workflow skill（內部檔 .claude/skills/case-first-module-workflow/、含 stage 1-5 流程、reviewer prompt template、self-scan regex 跟 5 個原則卡）、後續套用到：

backend/07 batch 2 LLM 安全：case 庫缺位（OWASP LLM Top 10 + agent injection 公開事件未累積成模組 case）、要先建 LLM case 庫再走 case-first
backend/07 batch 3 治理章節：routing 層 / 導讀性質、case-driven 深化適用度低、做標準 polish pass 即可
backend/08 incident response：跟 04 / 06 / 07 cross-link 密度最高、SSoT 對應規劃壓力最大
其他模組依此類推

06 模組是首次套用工具化 skill 的模組、驗證 skill 對 stage 1-2 加速有效、但 reviewer A 仍抓出 45 issue（高於 05 之前 baseline 20-30、推動 v1.2 把 standards reviewer baseline 擴大到 20-45）— 揭露 skill 改進方向（self-scan regex 需要持續演進、case 引用段首結構是 LLM 系統性傾向）。

07 batch 1 驗證下「章節已有 routing skeleton」情境的處理策略：補強段不擴成厚重 case-driven 章節、聚焦 mechanism 深化 + cross-link 對齊。揭露兩個新陷阱（跨 case 合成 frame 升級成 case 揭露、case 引用句構同質化）、補進 skill 跟方法論。

流程本身會在每個模組後 retrospective、看 reviewer 維度是否該調整、findings 抽取方法是否該強化、polish pass 處理 pattern 是否該擴充。目前已知改進方向：

加 reviewer：教學性審查（讀者路徑是否清楚、判讀順序是否合理）
強化 findings 抽取：標註 finding 的 泛化程度、避免把 case-specific 細節推為通用結論
Rich / Medium case 引用紀律：把「fact vs derive」分層 + 「mechanism 名稱精準引用」寫進 stage 1 抽 findings 模板、stage 3 case fidelity reviewer prompt 也明示此分界
自掃描 regex 持續演進：每個模組 reviewer 抓出新 pattern 後、回頭加進 self-scan 工具、避免在下個模組重蹈覆轍。06 模組後加 ^對應 \[ 抓段首 case 引用框架。07 模組後標明 ^對應 \[ 在三段分離結構下會 false positive、要靠 awk 看 prev line context
Case 引用三段式：把「概念定義 → case 引用 → 通用展開」當段落結構紀律、避免段首被 case 引用取代（06 模組最大宗 systemic 違規）
Case 引用句構分流：07 模組後 stage 5 polish pass 加句構分流為標準工序、避免跨章 13+ 段同句構讀感儀式化
跨 case 合成 frame 紀律：07 模組後 reviewer B prompt 明示「跨 case 合成 frame 必須標為本章合成」是 high 級 issue
加修正後自動 lint：修完不只跑 mdtools、加跑「找首句否定句」「找表格沒延伸」「找模板化並列點」「找段首 case 引用」的自動掃描

跟其他寫作協議的整合：本流程跟 compositional-writing skill 互補（後者管單篇寫作的原子化跟意圖、本流程管 跨章模組 的 scope 跟一致性）、跟 requirement-protocol skill 互補（後者管 對話協議、本流程管 內容生產）。

Blog 文章模板設計：作者品質閘門與正文分工

Sat, 02 May 2026 00:00:00 +0000

問題定位

文章模板的責任是穩定作者流程，正文的責任是承載技術文章本身。讀者進入文章時，需要看到概念、判讀、取捨與路由；作者在寫作時，需要一組欄位檢查文章是否具備可維護的最低結構。

本 blog 同時由人類作者、Claude Code 與 Codex 協作產生內容。模板若只放在單一 agent 的設定裡，就會形成工具分岔；模板若直接放進 backend 正文，又會把作者工作流暴露成讀者負擔。因此模板的單一真實來源放在 content/posts/，作為本 blog 專屬的寫作設定記錄。

放置決策

模板放置位置的核心判準是讀者與維護者是否一致。backend 文章面向技術讀者，report 面向可重用事後檢討，posts 面向 blog 自身的規範、設計與工具鏈紀錄。

位置	適合內容	本議題判斷
`content/backend/`	技術文章正文、概念推導、案例分析	保持讀者主線，作者模板留在上游
`content/report/`	從具體 case 抽出的工程原則	可寫抽象原則，操作模板留在 posts
`content/posts/`	blog 規範、設計決策、工具鏈契約	作為模板設計的 SSoT
`.claude/`	Claude Code 執行規則	可引用本文，本文維持語意來源
`.codex/`	Codex 執行規則	可引用本文，本文維持語意來源

這個分工讓模板同時支援 Claude Code 與 Codex，也保留文章對讀者的自然技術敘事。

模板責任

模板是品質閘門，責任是讓文章保留關鍵判準。它要檢查文章是否具備責任、判讀、風險、邊界與下一步路由，正文仍用技術文章的推導順序排列。

模板欄位	作者要回答的問題	正文呈現方式
責任	這篇文章解決哪一類工程問題	概念定位或開頭原則段
判讀	讀者如何知道自己遇到這個問題	核心判讀、判讀訊號、表格
風險	判讀錯誤或缺漏會造成什麼代價	風險段、反模式、情境段
邊界	這篇文章處理到哪裡，交給誰接續	交接路由、與其他章節分工
回寫	案例或事故教訓應回寫到哪個章節	下一步路由、復盤段

模板欄位可以出現在文章大綱、作者檢查清單或 agent brief 裡。正文要以技術文章方式展開，讓讀者看到推導，作者填表痕跡留在工作流內部。

Backend 技術文章最小模板

Backend 技術文章的最小模板是「概念定位 → 核心判讀 → 判讀訊號 → 風險與邊界 → 交接路由」。這組欄位適合 04 / 06 / 08 這類語言無關的後端能力文章。

 1## 概念定位
 2
 3{概念} 是 {能力 / 流程 / 控制面}，責任是 {它在系統中承擔什麼問題}。
 4
 5這一頁處理的是 {抽象層級}。它跟 {相鄰章節} 的分工是 {邊界}。
 6
 7## 核心判讀
 8
 9判讀 {概念} 時，先看 {第一判準}，再看 {第二判準}。
10
11重點訊號包括：
12
13- {訊號 1}
14- {訊號 2}
15- {訊號 3}
16
17| 判讀面向 | 最小可用判準 | 常見失真 |
18| --- | --- | --- |
19| {面向} | {判準} | {失真} |
20
21## 判讀訊號
22
23- {真實服務中會看到的徵兆}
24- {工程團隊會踩到的操作問題}
25- {事故或演練會暴露的缺口}
26
27## 交接路由
28
29- {上游章節}：{承接內容}
30- {下游章節}：{下一步處理}

這份模板只定義文章最低結構。若某篇文章需要完整案例、方案比較或實作步驟，正文可以增加章節；增加章節時仍要保留責任、判讀、風險與路由。

案例前置欄位

案例前置欄位的責任是讓服務案例能回寫到文章系統。它屬於作者拆案例時的內部欄位，正文只吸收欄位背後的判讀與取捨。

欄位	用途	例子
來源	案例來自事故、演練或公開實踐	post-incident review、SRE case
觸發	事件如何被發現	alert、customer ticket、vendor status
Evidence	判讀使用哪些證據	log、metric、trace、audit log
Decision	當時做了什麼取捨	rollback、degradation、containment
Impact	影響到誰與什麼功能	tenant、region、feature、financial impact
回寫	教訓回到哪個章節	04.17、6.20、8.19

04 / 06 / 08 的案例拆解可共用這組欄位，但正文仍要用技術文章敘事。欄位幫作者維持可比性，文章幫讀者理解機制。

Agent 共用方式

Claude Code 與 Codex 共用模板時，本文是 blog 內的穩定契約。.claude/ 與 .codex/ 可以引用本文的欄位與判準，但實際模板語意以本文為準。

使用者	使用方式
人類作者	寫作前確認文章是否需要這組欄位
Claude Code	依本文判斷正文與作者模板的分工
Codex	依本文建立、補寫與檢查 content 文章
mdtools	檢查 Markdown 結構與連結，語意模板交給作者流程

這個安排避免 .claude/ 與 .codex/ 各自演化成不同模板，也避免把 agent 操作細節寫進 backend 讀者正文。

使用邊界

模板適合用在多篇系列文章、跨模組路由與案例回寫。單篇短文、事故紀錄或工具使用筆記可以採較輕的結構，只要仍能說清楚核心責任與下一步。

情境	使用方式
Backend 能力章節	使用完整最小模板
服務案例拆解	使用案例前置欄位，正文呈現案例判讀與取捨
Blog 工具鏈規範	依主題調整，保留 posts 的規範與工具鏈定位
Report 原則卡	依 report 固有結構，維持 case-driven 原則抽象
Skill reference	使用 skill 自身 portable 結構，維持跨專案可移植

模板開始主導正文時，需要降級成作者檢查清單。文章完成後的檢查重點是讀者能否理解技術推導，並確認欄位已在文章背後支撐判讀。

完稿檢查

完稿檢查的責任是確認技術文章維持主線。檢查時先看正文是否能獨立閱讀，再看欄位是否完整支撐交接。

首段是否先說概念責任
判讀訊號是否來自真實服務情境
表格項目是否有延伸說明
交接路由是否指向具體章節
案例欄位是否能回寫到 04 / 06 / 08
正文是否保留技術推導，並把欄位轉成讀者可理解的判讀

Mermaid gitGraph：自訂 commit type 顏色不渲染的配置補洞

Tue, 28 Apr 2026 00:00:00 +0000

背景：本文是「Hugo 部落格支援 Mermaid 流程圖完整實現指南」的補洞紀錄。原指南建立了 Mermaid 整合的基礎、但 gitGraph 的自訂 commit type 顏色設定沒包含進去、文章用到才發現渲染失效。

問題情境

部落格用 Hugo + Mermaid 10.6.1 畫 gitGraph，文章裡寫了 type: HIGHLIGHT 和 type: REVERSE 想標出特定 commit、但渲染出來全部是預設灰色、type 標記沒生效。

gitGraph
 commit id: "A" type: HIGHLIGHT
 commit id: "C" type: REVERSE

期望：HIGHLIGHT 綠色、REVERSE 紅色實際：兩個都跟普通 commit 一樣灰

根本原因

layouts/partials/custom_head.html 的 mermaid.initialize() 裡 themeVariables 只設了通用顏色（primaryColor、secondaryColor 等）、沒給 gitGraph 專用的顏色變數。Mermaid 找不到 HIGHLIGHT / REVERSE 對應的顏色就 fallback 到預設值。

 1// 原本的配置（不完整）
 2themeVariables: {
 3 primaryColor: '#2d3748',
 4 primaryTextColor: '#2d3748',
 5 primaryBorderColor: '#4a5568',
 6 lineColor: '#4a5568',
 7 secondaryColor: '#e2e8f0',
 8 tertiaryColor: '#f7fafc'
 9 // 缺：git0 / git1 / git2 等 gitGraph 變數
10}

Mermaid 的 themeVariables 對不同圖表類型有不同的命名空間 — flowchart 用 primaryColor、gitGraph 用 git0 / git1 / git2。原本的配置只覆蓋到通用 / flowchart 的命名空間。

解法

兩層補洞：JS 層補 themeVariables、CSS 層補 selector 規則做雙保險。

1. themeVariables 加 gitGraph 顏色

1themeVariables: {
2 // 原本的通用顏色保留
3 // ...
4
5 // 補 gitGraph 顏色
6 git0: '#90ee90', // HIGHLIGHT
7 git1: '#ffb6c6', // REVERSE
8 git2: '#4a5568' // 其他
9}

2. CSS selector 補強

光靠 themeVariables 在某些 Mermaid 版本仍不穩定（命名規則隨版本改變、見下方注意事項）、加 CSS 直接針對渲染後的 SVG 元素：

1.mermaid svg [id$="_HIGHLIGHT"] circle {
2 fill: #90ee90;
3 stroke: #2d7a2d;
4}
5
6.mermaid svg [id$="_REVERSE"] circle {
7 fill: #ffb6c6;
8 stroke: #d32f2f;
9}

Mermaid 渲染 gitGraph 時、會在每個 commit 的 SVG node 加上 id="..._HIGHLIGHT" / id="..._REVERSE"、用 attribute selector [id$="_TYPENAME"] 命中。

注意事項

顏色變數命名隨 Mermaid 版本變動：10.6.1 用 git0 / git1 / git2、更早版本可能是 gitInv0 / gitInv1。升級 Mermaid 版本時要驗證一次顏色設定還生效。
CSS selector 是防禦性的：themeVariables 配對的話 CSS 不會生效、但 themeVariables 失靈時 CSS 接住。雙保險、不重複設值。
這篇只解決「顏色沒出來」這個視覺問題：寫文章引用 gitGraph 的過程中還發現另一個議題 —「用 emoji 圖例區分 HIGHLIGHT / REVERSE」本身是語意混淆、不是視覺問題、修 CSS 解不了。那個議題見 report #92 視覺手段對齊錯誤層次。

驗證

修改後在本地 Hugo dev server 預覽包含 gitGraph 的文章、確認：

Cards-Skills 系統的活案例：從一個 search bug 到 14 張新卡的閉環

Sun, 26 Apr 2026 00:00:00 +0000

這篇要說什麼

content/report/ 累積了 70+ 張原子化事後檢討卡片、.claude/skills/ 收錄三個 protocol skill。這些是用來指導下一輪實作、又會被下一輪實作的學習回流修正的活基礎建設。

本文把這套系統實際跑一輪的歷程紀錄下來、當未來「想用這套系統的人」的 onboarding case study。主軸是修一個 search filter bug — 看似一週工作、實際走完八輪迭代、產出 14 張新卡片 + 兩個 skill 的 v0.2 + 4 個 CI test、過程中還抓到自己的 dogfooding 失敗、回頭修一次。

起點：使用者問題

“我們搜尋頁的標題/內文篩選功能現在雖然做出來了、但是還是有一個很嚴重的 BUG”

具體：Pagefind 分批 load、view 層 post-filter；切到 title-only 後、第二批 load more 的 8 筆全部 title 不含 query → 全 hidden、畫面閃但內容沒變、使用者看到「load more 沒效果」silent 失敗。

User 還明確補了一句：「所以除了用 JS 取巧解決畫面、但是實際功能面上怎麼配合跟實作我們並沒有解決」— 這已經點到核心：問題不在畫面、在抽象層。

第一輪：拆卡片之前先想清楚

直接修 bug 是可選但不是 user 要的。User 強調：「先思考我的需求、然後思考各種狀況的邊界」。

依當時的兩個 skill — requirement-protocol（對話協議）跟 frontend-with-playwright（前端執行協議）— 把問題分解：

Bug 的結構性根因：filter 寫在視覺層、source 在資料層分批、兩層的「一筆」定義不一致 → silent 缺口
解法策略空間：5 個合理選項（推進 query / 自動續抓 / 多 index / 誠實 UX / 明示縮小）— 每個機會成本不同
跨領域通用性：這結構不只前端有 — 後端 middleware filter、map-reduce、SQL view 都同模式

User 的關鍵回應：「這部份可以補充 SKILL 中演算法不足的原因 … 卡片是經過多次迭代、擴充、然後分拆、再擴充、最後做連結」。

明確了協作方式：先建卡片、再灌進 skill、最後才修。卡片本身要走原子化拆解 → 補充 → 反向擴充 → 連結的多輪迭代。

14 張卡片的拆解（第一冷啟）

依 user 對 atomic 的標準（一卡一議題、一個議題多面向 OK、議題太多就拆），列出 10 張卡片提案：

分組	卡片
問題分析	#55 層錯位 / #56 視覺完成 ≠ 功能完成 / #57 三狀態區分
指令澄清	#58 篩選類指令的澄清時機
解法策略	#59 五策略對照 + #60-62 三張 pattern 卡（自動續抓 / 推進 query / 誠實 UX）
抽象原則	#63 資料源形狀 / #64 同層合成

冷啟版本一次寫完不求完美 — 約 1700 行、各卡 self-contained。

七輪迭代

迭代 1：抽 Pattern + 瘦身

寫完 #59 五策略後、發現 A/B/C/D/E 中 C（多 index）、E（明示縮小）沒對應 pattern 卡。抽出 #65 / #66 補完 pattern 卡組。同時瘦身 #59 → 純路由（細節留 pattern 卡）、#55 + #57 移除跟 #63 重複的「四類資料源」段。

迭代 2：補概念深度

回頭讀 #56 / #63 / #64、補抽象層的「為什麼」：

#56 加「驗收的時間軸：四個 checkpoint」概念
#63 加「形狀識別 protocol」+「形狀混合」+「形狀的可改造性」
#64 加「跨領域通用的本質 = 資訊可見範圍」+「上推代價」

迭代 3：跨卡連結

新卡跟 #1-#54 既有卡互相補連結。例如 #55 ↔ #11 playwright、#57 ↔ #38 aria-live、#58 ↔ #21 decide-vs-confirm、#64 ↔ #43 minimum-scope + #44 SSOT。整個 collection 從兩個獨立輪次變一張互連網。

迭代 4：抽更高層原則

重讀新卡發現兩個議題夠 abstract、值得抽獨立卡：

#67 寫作便利度跟意圖對齊反相關 — 從「為什麼層錯位 bug 容易寫出來」抽出。發現它是 #43 / #44 / #45 / #64 的共同上位原則：便利位置 vs 對齊位置永遠反相關
#68 驗收的時間軸：四個 checkpoint — 從 #56 抽出獨立成卡

迭代 5：跨輪共骨

系統性掃 #1-#54 找跟新系列共骨的、加連結。例：#6 filter-order ↔ #58 / #59、#10 placeholder ↔ #68、#15 layout-test ↔ #68、#14 selector / #20 failure / #28 class-toggle ↔ #67。

迭代 6：#67/#68 加深

再讀兩張抽象卡、補「為什麼人會違反這條規則」的結構性解釋：

#67 加「便利度的時間維度：當下便利 vs 未來便利反向」+「我等下會 refactor 是個謊言」
#68 加「為什麼 Ship 前 checkpoint 最常被跳過」（沒便利路徑）+「瀑布原則：漏一層代價指數放大」

從「規則陳述」進到「結構性解釋」 — 不只說「該怎麼做」、也說「為什麼人會違反」。

迭代 7：compositional-writing 規範稽核

User 提醒「再做一次 compositional-writing 的檢查」。發現兩類違規：

Rule 7 違規：26 處「X 才合理的情境：實務上幾乎不存在」假反模式 — 改成「X 是反模式：理由」格式
結構違規：#67/#68 是抽象層原則卡、不該寫設計取捨 ABCD（情境檢討卡的格式）— 改成「不該套用本原則的情境」（適用邊界）

修完 31 張卡片（含既有 #1-#54）。整個 collection 對齊 v0.6 規範。

灌進 Skills

把 #55-#68 系列接進兩個 skill：

requirement-protocol v0.2：clarifying-ambiguous-instructions 加第 5 類「篩選類」+ 三問模板（呼應 #58）；SKILL.md 加「相關抽象層原則」段路由 #42-45 + #67-68
frontend-with-playwright v0.2：新增第 7 份 reference data-flow-and-filter-composition（涵蓋 #55-#66 跨領域範例）；強調「不只前端、適用後端 / 演算法 / DB」

Skill 的角色 = 路由器、Reports = 深度內容 — 兩層分工不重述。

實作：策略 C + Phase 1-4

依 #59 + Pagefind 1.5.2 capabilities：

A 推進 query：不可行（Pagefind 無 native title filter API）
C 多 index：採用（最對齊意圖）
B / D / E 是 fallback

Phase 1-4：

Makefile 跑 3 輪 pagefind（all / title / content）
single.html →
search.html 移除 view 層 post-filter、改 destroy + new PagefindUI(bundlePath)
4 個 Playwright tests 固化

跑出來：make site 三 index 成功、make test 4/4 PASS、live 驗證 sparse case 顯示 explicit empty。看起來完工。

User 抓到 dogfooding 失敗 — 第 8 輪

User 問：「剛剛的過程我不確定、你開始修改之前有先寫測試確保符合預測狀態、然後才調整嗎？」

沒有。流程是：先修 → 才補測試 → 4/4 GREEN。沒走 RED。

這是 #67「便利驅動」+ #68「Checkpoint 2/3 內部協議」的 dogfooding 失敗。我寫了 #67/#68 教這些原則、自己卻違反。

依 user 規範：先建卡片再修。抽 #69 Test-First：先看到 RED 才相信 GREEN：

測試本身是程式、會有 bug（5 種失敗模式）
沒看過 RED = 不知道測試有沒有 catch 能力
RED → GREEN 兩個訊號都看到 = 測試 + 修復都被驗證

retrospective 補驗證流程：checkout pre-fix commit → cherry-pick test → build → run（看 RED）→ restore → run（看 GREEN）。

跑下去 — 結果震撼：4 個測試只有 1 個真的 catch 到 bug、其他 3 個對 buggy code 也 PASS（placebo）。如果不做 retrospective、會帶著 3/4 placebo 測試 ship。

強化測試（network-level + structural assertion 替換弱 invariant）：buggy code 1 PASS / 3 FAIL、fixed code 4 PASS。RED-GREEN 真的 catch 到 bug + 真的解掉。

User 抓到第二個 dogfooding 失敗 — Checkpoint 1

我問 user 還有什麼該迭代。User 列了 7 項、選 1+2：

補 Checkpoint 1（列使用者意圖完整集）
跟 user 確認 known limitations

跑 Checkpoint 1 retrospective — 用 Playwright MCP 系統性測 5 維度（data / interaction / URL / a11y / performance）。發現 3 個 silent 缺口：

維度	漏掉的 case	結論
URL state	`?q=X&scope=Y` 持久化	完全沒實作
A11y	Tab order: scope 在 search input 之前	反 mental model
Filter UX	type/tag filter 在 sub-mode 完全消失	Silent 限制

依 user 規範：先建卡片再修。抽：

#70 URL 是 stateful UI 的儲存層 — 5 個儲存層特性對照 + 三問判準
#71 Tab Order = DOM Order = Mental Model 三者對齊 — DOM 順序 = tab 順序、不對齊時優先重排 DOM
更新 #68 加「為什麼 Checkpoint 1 也常被跳過」段、用本次任務當 self-case

然後實作 — 依 #69 RED-GREEN 順序：

寫 4 個 RED tests
跑 → 4 個 fail（confirms RED）
修 search.html（URL persist + DOM reorder + UI hint）
跑 → 8/8 GREEN

CI + 自動化

最後補 CI 防護：

.github/workflows/playwright.yml — push / PR 自動跑 8 個 tests
deploy.yml 修 critical bug — production 一直只 build 單 index、現在 build 三份對齊本地
make test + make verify-red-green PRE_FIX= — codify retrospective 流程、不需手動 stash / checkout / restore

數字總結

維度	數字
Commits	30+
新卡片	17（#55-#71）
既有卡修改	31 張（rule 7 稽核）
新 skill reference	1（data-flow-and-filter-composition）
Skill 版本	requirement-protocol v0.1 → v0.2、frontend-with-playwright v0.1 → v0.2
Playwright tests	8
RED-GREEN cycles	2（初版測試 + 強化版）
CI workflows 加 / 修	2（新增 playwright + 修 deploy multi-index）

學到什麼

1. Cards-skills 系統是雙向的

不是「先寫卡片、再用卡片」。是「卡片指導實作、實作問題回流卡片」。每一輪迭代都把學到的東西反饋。本次 14 張新卡有 8 張是修過程中實際遇到的問題抽出來的、不是預先想的。

2. User 提問是「外部觸發」

我自己跑 #67 / #68 / Checkpoint 1 的機率低 — 因為這些都是「沒便利路徑」的工作。User 的兩次提問（「有先寫測試嗎」+「需求確認最重要功能」）剛好對應 #69 + Checkpoint 1 的觸發。結構性偏差需要外部觸發來修正、不能靠自我提醒。

3. Test 過 ≠ 對齊使用者意圖

第一輪修完、跑 4/4 GREEN、看起來完工。實際漏了：

3 個測試是 placebo（沒做 RED 不知道）
3 個 silent 缺口（沒做 Checkpoint 1 不知道）

任何「跑得通就 OK」的訊號都低資訊量。Real 訊號 = 對照「使用者意圖完整集合」逐一驗收。

4. 一個 bug 修完 = 一個 case study 起點

如果停在「bug 修了、test 過了」、這次任務 5 個 commits 結束。User 的兩次提問把它變成 30+ 個 commits 的 case study、產出 17 張新卡 + 兩個 skill 升級 + CI 補強。修 bug 是 trigger、不是終點。

適合 reuse 這個流程的條件

不是每個 bug 都該走這套。適合的訊號：

Bug 修法不直觀、會碰到多種策略選項（→ 需要 #59 類取捨架構）
修法可能影響其他 feature 或產生新案例（→ 需要 Checkpoint 1）
需要長期 regression 防護（→ 需要 #69 RED-GREEN 驗證）
修的過程中發現新原則（→ 抽卡片）

不適合：純 typo / config / build 失敗 — 直接修。

對未來想用這套系統的人

進入點：

讀 content/skills/_index.md — 三個 skill 的 routing table
從你的問題情境找對應 skill：
- 不確定怎麼跟 user 溝通 → requirement-protocol
- 前端 / 資料流實作 → frontend-with-playwright
- 寫文件 / 註解 / log → compositional-writing
Skill 路由你到 specific reference、reference 路由你到 content/report/ 深度卡片
修問題過程中發現新原則 → 抽卡片回流

「卡片不是在實作之前一次寫完、是在實作之中持續累積」 — 這套系統的 leverage 在於「下一個類似問題能直接用、不用重新發明」。

結語

content/report/ 從 54 張長到 71 張、.claude/skills/ 從 v0.1 進到 v0.2、CI 從假 pass 變真防護、search bug 從 silent 失敗變到 8/8 regression test 守護。

過程不是線性。是「先做 → 抓到 dogfooding 失敗 → 抽卡片 → 回頭修 → 再被抓失敗 → 再抽卡片 → 再修」。每一輪都讓系統往對齊使用者意圖的方向多走一點。

User 的角色關鍵：兩次提問都不在「指出 bug」、是在「指出我跳過的 checkpoint」。這是純執行者看不到的盲點 — 自己的 dogfooding 失敗。外部 reviewer 是 cards-skills 系統的必要組件、不是 optional。

下次有類似情境的人 — 不需要把這條路再走一遍、直接用 #55-#71 + 三個 skill 起步。如果發現新 case、抽新卡回流。系統的價值在每次使用都會變強。

決策對話協議的浮現：從 #74 到 #81 的多層迭代

Sun, 26 Apr 2026 00:00:00 +0000

這篇要說什麼

前一篇 case study 紀錄的是「實作驅動」的閉環 — 從一個 bug 出發、逼出新卡片。

本篇紀錄的是 「對話驅動」的閉環 — 不修任何 production code、純粹從對話中浮現新卡。觸發點是 user 的一句反思：「剛剛提出很多不同方向的決策做選擇、這些選擇應該被做成卡片然後分析或者分拆細節研究」。

接下來六輪 spiral 迭代、產生 8 張新卡（#74-#81）+ 1 份 SKILL reference + skill v0.5。本文紀錄這條路徑、當作 #81 卡片系統的迭代浮現的具體實例。

起點：對話中的反思訊號

對話到第 N 回合時、agent 已經在多次出現「決策呈現」的場景：

「Content mode 三選一」 → user 答 (a)
「一次 ship 全部 vs 分批」 → user 答「一次」
「五策略選一」 → user 答「C 主 + D 補」
「ship D 還是 B/C」 → user 答「先 D、B/C 下輪」
「反省選哪幾個」 → user 答「1+2」

每次 agent 都呈現得不一樣、user 也每次回得不一樣。反覆出現但形式各異 = 抽 meta 的訊號（#42 2 次門檻 + #81 迭代浮現）。

User 的「這些選擇應該被做成卡片」就是 meta-訊號的明確化 — 不是 agent 自己浮現的、是 user 點出來的。External trigger（#72）才能逼出抽 meta 這個高 ROI 但無觸發的工作。

迭代過程：六輪 spiral

輪 1：列候選、不寫卡

User 的「應該被做成卡片」沒指定要寫幾張、寫什麼。Agent 列五個候選（A-E）+ 推薦 B+C 組合。User 回「每個都做成卡片」+ 給出迭代原則：「先拓展知識庫、然後才整理成上層的抽象決策依據、最後才做決策」。

這個原則 = [#81] 的 process explicit form：先原子卡 → 後 meta-卡 → 最後決策（套用）。

輪 2：寫五張原子卡（#74-#78）

每張一個維度：

#74 呈現格式（選項表 + 推薦 + 開放修改）
#75 主策略 + 補強疊加（不必互斥）
#76 分批 ship（三軸切分）
#77 「現在不決定」是合法選項
#78 反省任務預設複選

寫的時候各自獨立、沒明確意識到「這五張其實是同一回事的五個面向」。在第 5 張寫到一半才開始覺得「好像每張都在打開一個固定的 default」。

訊號：[#81] 「寫第 N 張卡、發現大段內容跟前一張重複」 → 抽 meta。

輪 3：抽 meta-卡 #79

User 接著問「都做、用多層迭代去拓展卡片」、agent 回應時自己浮現了 meta-發現：這五張其實對應五個獨立維度、可組合成 2^5 = 32 種對話形態。

寫 #79 時、把五張卡的「打開的 default」歸納成五個維度 + 五步判讀。Meta-卡讓五張原子卡從「平行五張」變成「有結構的網」。

回頭給每張原子卡補上「跟 #79 的對應」 cross-link、迭代結束。

輪 4：沉澱成 reference

光有卡還不夠 — 實作中要翻 5 張卡才能完整 apply、太貴。

寫 references/decision-dialogue.md、把五步判讀 + 完整模板 + self-check 沉澱成一份可直接套用的 protocol。同時更新 SKILL.md 加 trigger route（「呈現決策 / 開放問 / 反省題」）+ Directory Index + 抽象層原則段。

訊號：[#81] 「實作中要回查 ≥ 3 張卡」 → 沉澱 reference。

輪 5：dogfood + 反向補卡（#80-#81）

User 的「我們想得到的都作、直到推演到極限」逼 agent 自查：

自查 1：回頭看 agent 在這輪對話的回應、找 collapse 反模式。發現 4 處：

「需要我繼續嗎？」 = yes/no（最隱形的 collapse）
「下一層候選」用 bullet 沒適配欄
推薦騎牆「A 比較好不過 B 也行」
反省題列點未明示「互不衝突」

→ 寫 #80 Yes/No 二選、把 dogfood 4 例寫進 reference 作為「Bad/Good 對照」。

自查 2：「這套迭代過程本身是不是 cardable？」是 — 寫 #81 卡片系統的迭代浮現、紀錄「原子 → meta → reference」的 spiral 結構。

訊號：[#81] 「meta-卡寫太早、新 case 一直破壞」的反面 — 寫得剛好、反而能容納新 case（#80、#81 自己）。

輪 6：跨連 + 補強

把 #75（主+補強疊加）展開到 selector pattern：[#46-#49] 看似互斥（每個元件選一個起點）、實際在同一份 code 內可疊加（document + closest 共用）。Meta-原則的價值之一就是回頭發現舊卡之間有新關係。

更新 #59（五策略選擇矩陣）加「並用」段落、引用 #75 + #76。

過程中的觀察

1. User 的 prompt 直接決定 spiral 深度

User 的三句話分別觸發三層深度：

User 的話	觸發深度
「應該被做成卡片」	寫原子卡（layer 1）
「先拓展知識庫、再整理上層、最後決策」	抽 meta-卡（layer 2）+ reference（layer 3）
「都作、推演到極限」	dogfood + 反向補卡（layer 4-5）

每句話都是 [#72] L4 外部觸發 — 沒這些話、agent 不會自己走到第 5 層。Spiral 深度由 trigger 決定、不由 agent 紀律決定。

2. Dogfood 回饋的 ROI 比新卡高

#80（yes/no）的內容比 #74 短得多、但 ROI 可能更高 — 因為它捕捉的是「最常見、最隱形」的反模式。同樣 reference 的「dogfood Bad/Good 4 例」比抽象描述有用 — 將來 agent 看到自己寫類似格式、能直接認出來。

訊號：具體例子（特別是反例）的 ROI 通常 > 抽象描述。

3. Meta-卡跟 reference 的職責不同

寫完 #79 還不夠、需要 reference — 因為：

卡片回答「為什麼」、reference 回答「怎麼做」
卡片是讀爽的、reference 是被翻的
卡片可選、reference 在實作中是 must

兩者缺一不可：只寫卡 → 知道但忘記用；只寫 reference → 知道做但不知道為什麼、難 maintain。

4. 真實的 spiral 不是線性

寫 #74 時不知道有 #79、寫 #79 時回頭改 #74-#78、寫 reference 時又發現 #80 漏了、寫 #80 時補 reference 的 dogfood 段。每一層完成後都會反過來修上一層。

線性思維（「先寫完 layer 1 才寫 layer 2」）會卡住、spiral 思維（「來回修、每輪都加深」）才能浮現完整結構。

跟既有原則的關係

既有原則	在本次 spiral 中的角色
#42 2 次門檻	第 N 次出現決策呈現 = 抽 meta 的訊號
#43 最小必要範圍	先窄後寬：原子卡（窄）→ meta（寬）、不要直接寫 meta
#67 寫作便利度反相關	「直接寫 meta」容易、「迭代浮現」難 — 真實結構不對齊容易寫的格式
#72 高 ROI 無觸發	抽 meta + 寫 reference 沒外部觸發不會做、user 的話是 L4 觸發
#79 決策對話的五維度	本次 spiral 的 output、也是元素之一
#81 卡片系統的迭代浮現	本次 spiral 的 process-level 抽象

本次 spiral 的 output 清單

類型	數量	內容
原子卡	5	#74-#78（呈現 / 疊加 / 分批 / 延後 / 複選）
Meta-卡	1	#79 五維度
反向補卡	2	#80 yes/no、#81 迭代浮現
Reference	1	`decision-dialogue.md`（runtime + blog）
Skill 整合	2	requirement-protocol v0.5、frontend-with-playwright v0.4
跨連	多處	#59 加疊加段、#46-#49 加 #75 跨連
Case study	1	本文

整輪迭代的成本：純對話、無 production code 改動、無新測試。整輪迭代的價值：未來 agent 在每次「決策呈現」場景都有 reference 可翻、有 self-check 可用、有 dogfood 例子可對照。

結語

本系統的成型不是「用心寫文件」、是接受**「對話會浮現結構、原子卡會自我串連、meta-卡會回頭修原子卡」這個 spiral 真相**、然後讓每輪迭代都加深一點。

下一次 user 在對話中又出現「這個應該被做成卡片」訊號時、流程已經是現成的 — 套 [#81] 的三層展開 + [#72] 的 L4 觸發、就能繼續長新卡。真正的 knowledge infrastructure 不是寫一次的文件、是長期 spiral 的 living system。

Blog Markdown 寫作規範與 mdtools 檢查

Fri, 24 Apr 2026 00:00:00 +0000

這篇要解決什麼

隨著 blog 文章與知識卡片成長，純靠寫作紀律維持排版一致性越來越不可靠。反覆踩到的問題橫跨兩個層級：

結構與安全層級（這是工具鏈存在的主要理由）：

裸 URL 在段落與表格中爆版（MD034），降低閱讀體驗。
表格管線風格混用（MD060），同一張表格有的有空白、有的沒有。
平行模板章節重複標題（MD024），例如多案例文章的 ### 弱點環節 出現 13 次。
顯示文字與實際 href 不一致（反釣魚）— 不在標準 markdownlint 規則內，但紅隊教材脈絡下必要。
卡片雙向完整性（orphan 卡片、斷連結、K4 合規）— 跨文件檢查，現成工具做不到。
Front matter schema — Hugo 依賴 YAML front matter 提供 title / date / weight 等欄位，缺失會破壞列表渲染、排序、SEO。

基礎格式層級（容易被忽略但影響 parser 穩定性或語義結構）：

正文禁止使用 H1（嚴於 MD025）— Hugo front matter title 已產生 H1。
標題前後需保留空行（MD022），parser 才能正確識別標題邊界。
標題結尾禁止標點（MD026）— 例如 ## 常見問題： 應改為 ## 常見問題。
禁止用 **bold** 段落當標題（MD036）— 破壞語義階層與 TOC 產生。
程式碼區塊需註明語言（MD040），影響 syntax highlighting 與 accessibility。
列表前後需空行（MD032）、fenced code block 前後需空行（MD031）— 否則部分 parser 會把列表吃進段落。
有序列表編號風格一致（MD029）— 全部 1. 或全部 1./2./3.。
檔案結尾需有換行（MD047），POSIX 規範。
行長度上限（MD013）— 預設關閉，中英混用技術寫作不適用 80-char 慣例。

前兩類混合在同一份寫作規範裡，因為都由同一個工具鏈檢查、都要落地到相同的 pre-commit hook。純靠紀律記住這十幾條在大型 repo 上不可行，純 regex 又無法穩定處理「平行結構下的標題重複」「卡片段落歸屬」這類語意判斷。因此 blog 專案採用 Go + goldmark AST 做自訂 linter：scripts/mdtools。本文是 linter 與寫作規範的對齊文件；AGENTS.md 引用本文作為排版規範來源。

1. 工具總覽

子命令	職責	改檔	觸發時機
`mdtools fmt [--fix\|--check]`	格式正規化（URL、表格、空行、列表間距、trailing newline）	`--fix` 會改	pre-commit（`--fix`）、pre-push / CI（`--check`）
`mdtools lint`	結構檢查（標題、反釣魚、code block 語言、front matter schema）	否	pre-commit、pre-push、CI
`mdtools cards`	跨文件完整性（連結、orphan、K4）	否	pre-commit、pre-push、CI

工具原始碼在 scripts/mdtools/，binary build 到 bin/mdtools（已 gitignore）。

作用範圍是 content/**/*.md。public/、themes/、node_modules/ 等輸出或第三方資源不檢查。

2. 標題規則

2.1 標題結構與格式規則

正文禁止使用 H1。Hugo 的 front matter title 會自動產生 H1，若正文再寫 # ... 會出現兩個 H1 並列，破壞語義階層與 SEO 訊號。正文一律從 H2 開始，最深到 H6。
同一父標題（直接上層）底下，子標題文字必須唯一（MD024 siblings_only 模式）。
不同父標題底下，子標題允許重名。
標題前後需保留空行（MD022），mdtools fmt --fix 自動補。
標題結尾禁止標點（MD026）— 禁用字元：.、,、:、;、。、，、：、；。允許 ?、！、？、! 作為語氣結尾。mdtools fmt --fix 自動去除結尾禁用標點。
禁止用粗體當標題（MD036）— 若段落整段只由 **文字** 或 *文字* 組成，視為視覺性標題濫用。mdtools lint 只報警、不自動修；作者需手動判斷正確的標題層級（通常是 H3 / H4）並改寫。

2.2 補充範例：MD026 與 MD036 的典型誤用

MD026（標題尾標點）常見誤用：

1#### 字型選擇說明：        ← 違規（結尾 `：`）
2#### 字型選擇說明          ← 合法

中文寫作習慣用冒號引入後續內容，這個模式在「段首句」合理、在「標題」就不合理 — 標題本身的存在就暗示了後續有內容，冒號變成冗餘訊號。

MD036（粗體當標題）常見誤用：

1**字型選擇說明**           ← 違規：整段只有粗體，視覺像標題但不是真標題
2
3這段內容...
4
5### 字型選擇說明           ← 合法：用正式的 H3 取代

差異看起來微小，實際影響包含：Hugo TOC 不會抓到、卡片反向連結失效、screen reader 無法跳轉。這是「語義 vs 視覺」錯位的典型案例，AST linter 容易檢出（Paragraph 節點唯一子節點為 Strong/Emph）。

2.3 為什麼採 siblings_only 而非全域唯一

平行結構（多案例、多模板章節）的複用語義來自上層標題賦予的脈絡。例如：

1## 【案例一】Uber 2022
2### 弱點環節        ← 合法
3### 攻擊路徑
4
5## 【案例二】Okta 2023
6### 弱點環節        ← 合法，因為在不同的父層下
7### 攻擊路徑

重名只有在同層並列時才代表結構錯誤。強制全域唯一會逼作者寫 ### 【案例二】弱點環節，破壞平行結構的視覺一致性，收益並不大。

3. URL 與連結規則

3.1 裸 URL 轉換（`mdtools fmt --fix` 自動處理）

段落或表格儲存格內的裸 URL 會自動包成 markdown 連結。顯示文字依路徑可識別性分級：

情境	顯示文字	範例（before → after）
路徑含識別碼（例如 CVE）	`domain.com/識別碼`	`https://nvd.nist.gov/vuln/detail/CVE-2023-34362` → `[nvd.nist.gov/CVE-2023-34362](https://nvd.nist.gov/vuln/detail/CVE-2023-34362)`
路徑冗長但無識別性	`domain.com`	`https://www.cisa.gov/news-events/alerts/2024/06/03/snowflake-recommends-...` → `[cisa.gov](https://www.cisa.gov/news-events/alerts/2024/06/03/snowflake-recommends-...)`
已是 markdown 連結	不動	—

識別碼偵測用 regex 白名單，初始清單專注在高頻識別碼格式（例如 CVE-YYYY-N），其他格式以「遇到再加」原則擴充。清單維護在 scripts/mdtools/internal/rules/identifiers.go。

3.2 反釣魚校驗（`mdtools lint` 強制檢查）

Markdown 語法允許顯示文字與實際 href 完全不符，這是釣魚攻擊的結構基礎。本規則在 AST 層阻擋此模式。

R-URL-1（URL 樣顯示文字一致性）：若顯示文字含 .com / .org / .gov / .net / .io / .dev / .tw 等 TLD 字樣，則顯示文字的 domain 必須等於 href 的 domain（含子網域比對）。
R-URL-2（描述型顯示文字自由）：顯示文字不含 TLD 字樣時，視為人類可讀描述，不做 domain 比對。

違規範例（會被 lint 阻擋）：

1[nvd.nist.gov](https://malicious.example.com/fake)     ← 顯示文字暗示 NVD，href 卻不是
2[cisa.gov/advisory](https://cisa-gov.evil.example)     ← 顯示文字抄 CISA 格式，domain 不符

合法範例：

1[Uber 事件公告](https://www.uber.com/newsroom/security-update/)
2[nvd.nist.gov/CVE-2023-34362](https://nvd.nist.gov/vuln/detail/CVE-2023-34362)

這條規則在紅隊 / 安全相關教材中特別重要：讀者本來就該對來源警戒，排版規則不該削弱這個警戒訊號。縮短顯示文字提升可讀性，反釣魚校驗守住安全底線，兩者互補。

3.3 例外情境

程式碼區塊（fenced code block，``` 包圍）內的 URL 不做任何處理（不縮短、不校驗）。代碼範例經常需要展示完整 URL 給讀者複製執行。
引用區塊（> 開頭）內的 URL 比照段落處理，會縮短也會做反釣魚校驗。

4. 表格規則

統一使用 aligned 風格：每欄內容用空白補齊到該欄的最大寬度，使 | 在 monospace 渲染下垂直對齊。
欄位分隔線使用 | --- | 形式，不含對齊冒號 :（分隔線內的 - 數量跟隨該欄寬度自動填足）。
寬度計算使用顯示寬度（display width）— CJK 字元佔 2 欄寬、ASCII 佔 1 欄寬，分隔列與資料列按同一套寬度對齊。
mdtools fmt --fix 自動正規化：插入新行或改動欄寬時會全表重算，作者不需手工維持對齊。

選 aligned 而非 compact 的理由是原始檔可讀性：技術教材的表格常需在 code review 裡對照，aligned 風格讓 reviewer 直接看出哪些欄位對應哪些內容，不用在腦中解析鋸齒狀的 pipes。手工對齊在長表格反覆編輯時確實會失效（新增一行就全表要重對齊），但這正是 mdtools fmt --fix 接手的地方。

5. 基礎格式細節

這節整理容易被忽略、但會影響 parser 正確性或渲染品質的小規則。

5.1 程式碼區塊必須註明語言（MD040）

由 mdtools lint 檢查。未註明語言的 fenced code block 會被報警：

 1```                   ← 違規：缺語言標示
 2func main() {
 3    fmt.Println("hi")
 4}
 5```
 6
 7```go                 ← 合法
 8func main() {
 9    fmt.Println("hi")
10}
11```

純文字輸出（例如 terminal output、log 片段）使用 text 或 plain：

1```text
2Error: permission denied
3```

Shell 範例統一用 bash（即使是 zsh 語法，讓 syntax highlighter 有合理預設）；純設定檔依實際格式（toml、yaml、json、ini）。

5.2 fenced code block 前後需空行（MD031）

由 mdtools fmt --fix 自動處理。缺空行會讓前後段落被 parser 併入 code block 或反之。

5.3 列表前後需空行（MD032）

由 mdtools fmt --fix 自動處理。

 1上一段結束。
 2- 列表項一           ← 違規：列表前無空行，會被部分 parser 當段落延續
 3- 列表項二
 4
 5上一段結束。
 6
 7- 列表項一           ← 合法
 8- 列表項二
 9
10下一段開始。

5.4 有序列表編號一致性（MD029）

由 mdtools fmt --fix 正規化。本專案採 ordered 風格（全部遞增編號）：

11. 第一步
22. 第二步           ← 合法
33. 第三步
4
51. 第一步
61. 第二步           ← 違規：混用風格（fmt --fix 會改成 1./2./3.）
72. 第三步

選擇 ordered 的理由：原始檔可讀性高，作者直接看到步驟數；插入新項目的對齊代價比全部重新渲染低。

5.5 段落間空行

段落之間、標題前後、列表與段落之間都需空行。mdtools fmt --fix 會自動規範化多餘 / 缺失的空行，作者不需手工維護。

5.6 檔案結尾需有換行（MD047）

POSIX 文字檔規範；缺失時 git diff 會出現 \ No newline at end of file。mdtools fmt --fix 自動補。

5.7 Tab 字元（MD010）— 僅限 fenced code block

由 mdtools lint 檢查（warn 等級）。Prose / 列表 / 表格 / 引用等非 code-block 行內若出現 tab 字元，會被標記並建議改成空白；fenced code block 內的 tab 保留（Go 原始碼依 gofmt 慣例用 tab，文章要讓讀者能直接複製貼用）。

Repo 根目錄的 .markdownlint.json 用 "MD010": { "code_blocks": false } 告知 IDE 的 markdownlint extension 採用同一套 policy，讓編輯器跟 CI 的警告保持一致。

5.8 行長度上限（MD013）— 預設關閉

本規則預設關閉。中英混用的技術寫作不適用 80-char 慣例：

中文每字元算 1 個寬度時，80-char ≈ 40 個中文字，寫到一半就要斷行，嚴重影響可讀性。
中文每字元算 2 個寬度時，80-char 相當於 20-30 個中文字，更離譜。
Markdown 編輯器普遍支援軟斷行與 IDE word wrap，實體行長度對閱讀體驗影響小。

若未來需要打開（例如發現真的有人寫出 2000-char 單行段落），建議上限 400 字元（軟上限，warn 不阻擋）。設定在 scripts/mdtools/internal/rules/config.go 的 LineLengthLimit 欄位。

5.9 裝飾符號禁用（emoji / 視覺記號）

本節本身豁免：規範要描述「哪些符號禁用」必然要列舉這些符號（use-mention distinction）。本節舉例的 emoji 屬 mention（指稱）、非 use（裝飾使用）、不違反規則。掃描指令會 hit 到本節、判讀時跳過。

content/** 正文不可使用 emoji（如 ✅ ❌ ⚠️ 🚨 🟡 🟢 ⭐ 📌 💡 ⚡ 🎯）與裝飾性 unicode 符號（✓ ✗ ✘）。表格、列表、行內標記都不行。

替換策略（emoji 承載的語意要回到文字結構、不是純粹刪除符號）：

原寫法	改成
表格 status `\| ✅ 解了 \|`	純文字描述：「解了」/「是」/「適用」
表格 status `\| ❌ 漏 \|`	純文字描述：「漏」/「否」/「不適用」
列表優缺點 `- ✅ 簡單` / `- ❌ 慢`	拆成 `優點：簡單` / `缺點：慢` 段落或標題段
列表錯誤示範 `- ❌ 把 key 寄 email` / `- ✅ 用 CSR`	拆成 `錯誤做法：` / `正確做法：` 標題段
行內視覺強調 `🚨 critical`	markdown 粗體 `critical` 或引用塊 `> critical：...`

理由：

Grep-ability：emoji 無法用 plain text grep 命中；視覺結構容易掩蓋語意結構、reviewer 看不出「優 / 缺」是用 emoji 區分還是用標題段區分
CLI parser 相容性：部分 multi-byte emoji 在 Rust-based CLI 工具（如某些 mdtools / pagefind / lint pipeline）觸發 char-boundary panic
跨語境穩定：emoji 在不同字型 / 平台 / 終端機渲染差異大、容易斷行或顯示為框

掃描指令（提交前自己跑一次、有 hit 就替換）：

1rg "✅|❌|⚠️|🚨|🟡|🟢|🔴|🟠|🔵|⭐|📌|💡|⚡|🎯|✨|📝|🔍|🛠|⛔|✓|✗|✘" content/

本規則目前未進 mdtools lint 自動掃描、靠人工 grep。未來會加進 lint pipeline。

5.10 位置引用與數量命名候選掃描（REF1 / REF2、警告層）

mdtools lint 對 content/** 跑兩個警告層掃描、來源是引用紀律卡（#155 引用章節用語意標題、#156 集合命名用角色）：

REF1-positional-anchor：正文中的位置式引用候選 —「見第 3 點」「詳見第五章」「§4」。位置編號是當下排列的衍生值、目標是活文件時、結構重排會讓引用 silent 指向錯的內容。
REF2-count-in-name：標題與 front matter title 中內嵌成員數的集合命名 —「六大原則」「遷移五階段流程」。成員增減時名稱先失真、且名稱是被複製最多次的字串。

兩個規則都停在警告層、命中是候選、不是判決 — 回報前要做語意判定：

命中情境	判定
引用發布方凍結的編號（RFC 段號、法條條號）	合規、編號是 fact
數字緊鄰它描述的清單（「確認三件事：」）	合規、漂移在編輯當下可見
外部凍結品牌名（SOLID 五原則）	合規、數量由發布方凍結
目標是內部活文件 / 內部活集合	改語意標題引用 / 角色命名

掃描器內建兩個自動豁免：被 「」 包住的命中視為反例引用、直接跳過；「第」開頭的序數（第三階段）不屬 REF2 的集合命名。既有內容的命中屬歷史基線、依「changed-set scoped lint」原則處理 — 新增與修改的檔案要判讀、存量警告分開回報。

5.11 否定起手候選掃描（POS-negation-lead、警告層）

mdtools lint 對 content/** 跑否定起手掃描、來源是 #166 重點優先陳述是跨語言的資訊結構原則（搭配 #165 register 違規要文體異源）：

POS-negation-lead：正文中「不是 X、而是 Y」「不是 X — 是 Y」「與其 X、不如 Y」的重點後置候選。核心概念（Y）被擠到「而是 / 不如」之後、讀者要先處理一個被否定的 X 才拿到重點。這是資訊結構效率問題、跨語言成立（英文「not X but Y」、日文「X ではなく Y」）、不是中文特有句型 — 偵測可機械化、判定不可。pattern 涵蓋的連接詞（而是 / 「— 是」/ 不如）枚舉不完、判準是「核心概念在不在句首」而非哪個連接詞 — 漏掉的變體只是讓候選 silent 到有人讀到（規則第一版就漏了「不是 X — 是 Y」、靠人發現才補）。

判定用「重點位置」、命中是候選、不是判決：

命中情境	判定
核心概念第一次正面出現在句首（「有深度、不是非黑即白的二元」）	合規、重點先行
明示反例 / 對照段落內的否定（見 #94）	合規、否定是對照本體
核心概念被擠到「而是」之後（「不是二元、而是有深度」）	改正向、把核心概念移到句首

掃描器豁免兩類命中：被 「」 包住的引用（反例引用 / 句型佔位符）、以及 backtick 行內程式碼內的 pattern（grep regex / 技術識別碼）。講這個句型的 meta 卡（#165 / #166）與本規範段落會大量自我觸發 — 屬候選人判定豁免、跟 REF1 / REF2 對 #155 / #156 一致。既有內容的命中（全 content/ 約數百個）屬歷史基線、依「changed-set scoped lint」原則處理 — 偵測把候選池曝光、判定漸進進行、存量警告分開回報。

6. Front matter schema（`mdtools lint`）

Hugo 依賴 YAML front matter 提供 title / date / weight 等欄位給 render pipeline。缺欄位會讓列表頁、排序、SEO 壞掉，但 Hugo 本身不會失敗（靜默接受不完整資料），所以必須由 linter 守住。

6.1 通用層（`content/**/*.md`）

所有內容文章必須有：

title：字串，不可空。
date：YYYY-MM-DD 格式（ISO 8601 date）。

Hugo _index.md section 頁面例外：這類檔案是 Hugo 的 section 列表 landing page，不是內容文章，沒有語意上的「日期」。只要求 title，不強制 date。

6.2 推薦層（警告，不阻擋）

推薦填寫（mdtools lint warn level）：

description：字串，建議 30–150 字，影響 SEO 與列表頁預覽。
tags：陣列，至少 1 個標籤。

推薦層是歷史內容的緩衝區，不是新增內容的放行條件。新增文章必須同時填寫 description 與 tags；修改既有文章時，若同一檔案缺少推薦欄位，應在同次變更補齊，避免每次驗證都被舊 warning 淹沒。

驗證時先跑 changed-set scoped lint 判斷本次變更品質，再視需要跑 full lint 觀察整體基線。回報 full lint 結果時，要把歷史 warning、已知 warning 與本次新增問題分開描述。

6.3 卡片嚴格層（`content/backend/knowledge-cards/**`）

知識卡片額外要求（對應 .codex/briefs/knowledge-cards.md K2）：

title、date、description 必填。
weight：整數，決定在 _index.md 主題表格中的排序位置。

6.4 禁止欄位

以下欄位存在時 mdtools lint 警告（避免語義混淆）：

author：本專案為單作者 blog，統一於 Hugo 設定。
permalink：使用 Hugo 預設路徑規則，避免手動覆蓋。

若未來需要鬆綁，在 scripts/mdtools/internal/rules/frontmatter.go 的 DisallowedFields 清單調整。

6.5 slug 必填、跟檔名對齊

所有 content 文章 frontmatter 必須有 slug 欄位，值跟檔名（不含 .md）對齊。

1---
2title: "視覺手段對齊錯誤層次"
3slug: "visual-tool-error-layer-alignment"   # 跟檔名對齊
4date: 2026-04-28
5---

為什麼必填：

slug 是 URL 的核心識別、跨多個工具共用（Hugo build、mdtools lint、跨檔 markdown link、search index）。若不顯式定義，slug 散落在三處推導鏈：

來源	推導值
Hugo 預設（從 title 用 urlize）	runtime 推導、隨 hugo 版本變化
mdtools 字面比對	檔名 stem
跨檔連結時的引用	寫作者手動算 / 複製

三個推導鏈不一致時 = silent broken link（mdtools pass 但 hugo build 後 404、或反過來）。把 slug 升成 frontmatter 顯式 fact、所有工具基於同一 source、消除 derivation 鏈。

詳細論述見 report #93 URL slug 必須顯式定義為 fact。

檔名對齊規則：

檔名命名建議：英文小寫、kebab-case 或 snake_case、不含中文（避免 hugo urlize 規則跨版本變動）
slug 值 == 檔名 stem（不含 .md）
修檔名時必須同步修 slug；修 slug 時必須同步 rename 檔案

Hugo _index.md 例外：section 列表頁已有 slug: 欄位指定資料夾路徑、不適用本規則。

7. 卡片雙向完整性（`mdtools cards`）

作用範圍：content/**/*.md，重點關注 content/backend/knowledge-cards/。

層級	規則	實作
L1 連結有效性	所有相對連結 `[...](/posts/markdown-writing-spec/path)` / `[...](/posts/path)` 的目標檔案必須存在	AST 抽 Link node → 解析相對路徑 → stat 檔案
L2 卡片 orphan 偵測	每張卡片至少被 `content/**` 中一篇非卡片正文引用	建反向索引 → 找無 incoming edge 的卡片
L4 卡片 K4 結構合規	卡片首段與「概念位置」段各至少 1 個相鄰卡片連結	AST 定位段落節點 → 統計子樹 Link 數

L3（正文首次出現術語必須連結到卡片）暫不納入，待術語字典（.codex/briefs/knowledge-web-expansion.md）啟動後再開。

為什麼要做跨文件檢查

知識卡片是 blog 的核心知識資產。隨著卡片數量增加：

Orphan 卡片（沒有正文連結進來）會變成知識死角，讀者無法發現。
斷掉的相對連結（檔案被改名或移動）肉眼難以發現，只有讀者點擊失敗才暴露。
K4 合規（首段 + 概念位置段要有鄰卡連結）保證卡片間的知識網不會鬆散。

這些檢查用 regex 做都卡在「段落歸屬怎麼判斷」。AST 天生知道節點的父子結構，做起來自然。

8. 執行時機

Pre-commit hook（`.githooks/pre-commit`）

mdtools fmt --fix — 自動修格式；改動會 git add 回 staged，避免改完又沒進 commit。
mdtools lint — 結構檢查；失敗阻擋 commit。
mdtools cards — 完整性檢查；失敗阻擋 commit。

Pre-push hook（`.githooks/pre-push`）

pre-push 的責任是把 CI 同款全量檢查提前到本機。pre-commit 為了速度只處理 staged markdown；pre-push 會跑 make check，也就是 mdtools fmt --check content/、mdtools lint content/、mdtools cards content/，讓整個 content/ 的格式與連結 drift 在推送前被攔下。

啟用 hook：

1git config core.hooksPath .githooks
2# 或：make install-hooks

CI（`.github/workflows/md-check.yml`）

三個子命令都跑 --check / 嚴格模式，任何違規 fail CI。

9. 寫作者使用指引

寫作時優先遵循本規範。pre-commit / pre-push 報錯時讀訊息修正；不可用 git commit --no-verify 或跳過 hook 的方式繞過檢查。
新增案例平行章節（例如多個「工具評測」「事件時序」）時不需登記到任何白名單 — siblings_only 自動判讀。
新增 URL 時優先採用裸 URL 轉換段的分級形式；若顯示文字含 TLD 字樣，確認 domain 與 href 完全一致。
新增卡片時確認首段與「概念位置」段各有至少一個相鄰卡片連結（L4 要求）；確認 front matter 含 title / date / description / weight（卡片嚴格層）。
程式碼區塊養成習慣先寫語言標示再填內容；純文字輸出用 text。

10. 規則擴充流程

新規則進入本文的路徑：

先在 scripts/mdtools/internal/rules/ 實作為可開關的 rule（預設關）。
在代表性檔案上測試誤判率。
誤判率 < 1% 且有明確教材品質收益時，預設開啟並更新本文。
預設開啟後同步修正既有違規；若違規數量大，可分批 PR。

11. 為什麼自訂而不是用現成 markdownlint

markdownlint-cli2 的 MD022 / MD024 / MD026 / MD029 / MD031 / MD032 / MD034 / MD036 / MD040 / MD047 / MD060 這些基礎規則都有（MD013 預設關閉、MD025 本規範嚴於原版），為什麼還要自寫？

關鍵差在卡片雙向完整性、反釣魚校驗、Front matter schema 這三類檢查，屬於跨文件 / AST 層 / 業務邏輯層的自訂邏輯，現成 linter 無法表達。這些檢查是 blog 品質的核心訊號，必須跟基礎格式檢查放在同一個工具鏈、同一次 AST parse 內處理，避免多個工具重複解析、重複維護。

另外 goldmark 是 Hugo 內建的 markdown parser。用同一個 parser 做 lint 保證「lint 通過 → Hugo render 一致」，杜絕兩套 parser 解讀不同的長尾 bug。

本文為 blog 專案 Markdown 寫作規範的單一真實來源。repo 根目錄的 AGENTS.md 引用本文作為排版規範權威，規則與 scripts/mdtools 實作保持同步。

Fuse.js / MiniSearch：客戶端載入索引的搜尋方案

Fri, 24 Apr 2026 00:00:00 +0000

客戶端搜尋的問題空間

靜態站搜尋必須在 build 時或 client runtime 完成。選擇整包序列化 + client 載入這條路時，核心設計軸是：

設計軸	意義
索引內容	由作者在 build time 明確決定要搜哪些欄位、哪些 section
索引結構	扁平 JSON 陣列，每筆一個頁面，欄位直寫
runtime 處理	在瀏覽器內建索引、記憶體內匹配

Fuse.js 與 MiniSearch 是這條路上的兩個主要實作。差異在匹配策略（fuzzy vs 全文），共享的是「一包索引載入瀏覽器、之後所有查詢不再出站」這個骨幹。

核心設計：build 時序列化 + runtime in-memory

商業邏輯：把搜尋放在 client runtime 的關鍵是搜尋不再跨網路來回。第一次載入索引之後，每次打字的匹配都在使用者的 RAM 內完成，不受網路延遲影響、不受後端服務狀態影響、甚至不需要網路連線。

此設計把「索引存放」從伺服端或 CDN 移到了訪客自己的瀏覽器，換得 runtime 的完全獨立。

CASE：整個流程兩個時點：

Build time（Hugo 階段）：Hugo 用 custom output format 產出一份 JSON，每筆一個頁面。

1{ "title": "WAF", "url": "/backend/knowledge-cards/waf/",
2  "description": "說明 WAF 如何在入口層過濾攻擊",
3  "content": "完整內文…" }

Runtime（瀏覽器階段）：使用者打開搜尋頁，browser fetch JSON → library 在 memory 中建索引 → 使用者打字 → library 匹配 → 結果渲染。

第一次 fetch + build index 通常 100-500ms；之後的每次查詢在 memory 內匹配，一般 <10ms。

架構選擇：作者定義索引內容

商業邏輯：索引的範圍與欄位由誰決定，這件事決定了搜尋結果的邊界。Fuse.js / MiniSearch 採「作者顯式宣告」的路線 — Hugo template 明確列出哪些 section 進索引、每筆要哪些欄位。

這個選擇讓搜尋結果成為作者設計決策的產物：想排除 work-log 類別就不列入 range；想讓 tag 也可搜就加一個 tags 欄位到 JSON；想降低索引大小就只存 title + description 而不存 content。

CASE：layouts/index.json 決定 JSON 內容：

 1{{- $pages := where .Site.RegularPages "Section" "in" (slice "posts" "backend" "go" "python") -}}
 2[
 3{{- range $i, $p := $pages -}}
 4  {{- if $i }},{{ end }}
 5  { "title": {{ .Title | jsonify }},
 6    "url": {{ .RelPermalink | jsonify }},
 7    "description": {{ .Description | jsonify }},
 8    "content": {{ .Plain | jsonify }} }
 9{{- end -}}
10]

配套在 hugo.toml：

1[outputs]
2  home = ["HTML", "RSS", "JSON"]
3
4[outputFormats.JSON]
5  mediaType = "application/json"
6  baseName = "index"
7  isPlainText = true

Build 後 public/index.json 就是整站可搜內容的權威來源。

整合步驟（以 Fuse.js 為例）

1. Hugo 產生 index.json

核心動作：設定 custom output format，寫 template 輸出 JSON。

見上方「架構選擇」段落的 hugo.toml 與 layouts/index.json。

2. 搜尋頁載入 library + index

核心動作：前端一個、一段 script，完成 fetch + 建索引 + 匹配 + 渲染。

 1{{ define "main" }}
 2<input id="q" placeholder="搜尋…">
 3<ul id="results">ul>
 4
 5<script src="https://cdn.jsdelivr.net/npm/fuse.js@7/dist/fuse.min.js">script>
 6<script>
 7  fetch('{{ "index.json" | relURL }}')
 8    .then(r => r.json())
 9    .then(data => {
10      const fuse = new Fuse(data, {
11        keys: ['title', 'description', 'content'],
12        threshold: 0.3,
13        includeMatches: true
14      });
15      document.getElementById('q').addEventListener('input', e => {
16        const results = fuse.search(e.target.value).slice(0, 20);
17        document.getElementById('results').innerHTML = results
18          .map(r => `${r.item.url}">${r.item.title}
19                     ${r.item.description}
`)
20          .join('');
21      });
22    });
23script>
24{{ end }}

30 行內可以跑起來。

3. MiniSearch 的 API 差異

核心動作：選 MiniSearch 時，API 形狀相近、配置項不同。

 1const mini = new MiniSearch({
 2  fields: ['title', 'description', 'content'],
 3  storeFields: ['title', 'url', 'description'],
 4  searchOptions: {
 5    boost: { title: 3, description: 2 },
 6    prefix: true,
 7    fuzzy: 0.2
 8  }
 9});
10mini.addAll(data);
11const results = mini.search(query);

boost 決定各欄位命中的權重：title 命中比 content 命中重 3 倍
prefix: true 讓 “WA” 命中 “WAF”
fuzzy: 0.2 開啟 approximate match，容錯程度可調

方案的內在屬性

維度	Fuse.js / MiniSearch 的特徵
覆蓋完整性	由作者顯式宣告索引範圍 — 要搜什麼完全可控
可逆性	移除只需刪除 `index.json` output、搜尋頁、script reference
維護成本	無額外 build step；索引 schema 改動要同步改 template 與 client code
可理解性	library 原始碼規模可讀（Fuse.js ~10KB、MiniSearch ~6KB gzipped），API 面積小
依賴前提	要求 Hugo 支援 custom output format（所有版本皆支援）；要求 client 能跑 JS
擴展性	單次查詢發生在 memory 內 — 查詢效能不受網路或站規模影響；索引載入是首次一次性

與 runtime 獨立相關的延伸特徵：

離線可用：索引載入後所有查詢不需要網路；PWA 加 Cache API 讓索引也能離線快取
自託管：索引資料不離開你的網域；敏感內容或私有文件特別適合
隱私：訪客查詢字串不會送到任何第三方服務

與 UI 獨立相關的延伸特徵：

樣式與互動 100% 可控：搜尋框位置、結果卡排版、modal 與否、鍵盤操作 — 每一項都由作者決定
與 theme 緊密整合：UI 可以直接套用站上其他元件的 CSS variable 與設計 token

兩家 library 的定位差異

Fuse.js 與 MiniSearch 共享核心架構，設計重心不同：

面向	Fuse.js	MiniSearch
匹配策略	以 fuzzy / approximate match 為主軸	傳統全文檢索（詞項匹配 + 評分）
擅長情境	錯字容錯、近似詞匹配 — 搜 “kubernates” 命中 “kubernetes”	精確詞匹配、field boosting、prefix 搜尋
Gzipped 大小	~10KB	~6KB

兩者的 API 形狀相近，切換成本低。決定用哪一個，主要看希望怎麼對待 query：可能有錯字的模糊輸入偏向 Fuse.js，結構化的技術關鍵字偏向 MiniSearch。

運作特徵

Index 在首次載入

核心定義：索引是一份 JSON，使用者打開搜尋頁時由瀏覽器一次性 fetch。

含義：首次延遲 = 下載 JSON + library 建索引。常見做法是在 DOMContentLoaded 就 preload JSON，讓使用者看到搜尋框時索引已建好、第一次打字即可查詢。

規模適合度：幾百到一兩千頁、索引 JSON 幾百 KB 到 1-2MB 的站，體驗最穩定。索引大小由作者在 Hugo template 內決定 — 只索引 title + description 可以把 size 壓到很小。

索引範圍由作者決定

核心定義：Hugo template 明確列出要進索引的 section 與欄位。

含義：搜尋結果的邊界是作者設計決策。增減 section、增減 field、調整儲存策略，都在 template 這一層直接生效。

Tokenization 依 library 而異

核心定義：Fuse.js 採 character-level 匹配；MiniSearch 預設用空白分詞。

含義：

Fuse.js 對中文天然能搜，不需要斷詞設定
MiniSearch 對中文需要傳自訂 tokenize function，可以一個字一 token，或接 Intl.Segmenter 做詞界切分

UI 由作者自己寫

核心定義：library 只提供搜尋 API，不提供視覺組件。

含義：排版、鍵盤操作、focus management、ARIA 這些 UI 層責任由作者顯式實作。收穫是與 theme 完全融合的客製體驗。

適合的場景

站的規模穩定在幾百到一兩千頁
UI 需要深度客製、與 theme 風格緊密整合
想要最單純的 build pipeline（無 post-build step、無額外工具）
內容敏感、希望索引不離開自家網域
希望搜尋在離線狀態仍可用
需要 fuzzy match（Fuse.js）或精細 field boost + prefix（MiniSearch）

mdtools：Go + goldmark 的 markdown 工具鏈設計

Fri, 24 Apr 2026 00:00:00 +0000

背景：為什麼要自訂工具

Blog 專案的 markdown 規範有三類不同性質的檢查需求：

基礎格式（MD022 / MD024 / MD034 / MD060 等）— 市面 linter 都有，但規則細節不一致，我們對 MD024 要特殊處理（siblings_only 模式允許平行結構下的同名標題）。
反釣魚校驗（R-URL-1/2）— 顯示文字含 TLD 字樣時必須與 href 的 domain 一致，避免釣魚型連結。這條規則不在 markdownlint 標準集內。
卡片雙向完整性（L1/L2/L4）— 跨文件的圖論檢查：每張卡片至少被一篇正文引用、相對連結目標存在、卡片首段含鄰卡連結。

三類檢查共享兩個技術需求：AST 層的語法理解、goldmark 與 Hugo render 的一致性。詳細原因寫在什麼是 AST。

Markdownlint-cli2 涵蓋第一類、無法表達第二、三類。現成方案湊不出來，就自己寫。

語言選擇：Go vs Python 的 tripwire 式決策

這是實際討論過的決策，值得留下紀錄。

表面的直覺：Blog 用 Hugo（Go 寫的），所以用 Go 最自然

這個推論有個破口：Hugo 雖然用 Go 寫，但我們用的是 pre-built binary。hugo server 本地跑的是下載好的執行檔，CI 用 peaceiris/actions-hugo 這類 action，整個 blog 的 build 流程完全不碰 Go toolchain。

「專案已有 Go 依賴」這個前提不成立。真正要問的是：我是否願意為這組工具引入 Go toolchain 這個新依賴？

務實的對比

面向	Python	Go
Pre-commit 啟動速度	~50ms（interpreter 啟動）	`go run` ~500ms/次；pre-build binary 則要 commit 進 repo
CI 新增依賴	`setup-python`（runner 通常自帶）	`setup-go` + build step
開發速度（regex / 字串處理）	快	慢 2-3x，boilerplate 較多
AST 解析選擇	mistune / markdown-it-py	goldmark（與 Hugo 同源）

Go 唯一的決定性優勢是 goldmark — 跟 Hugo 用同一個 parser 可以保證「lint 通過 ↔ Hugo render 成功」等價。

關鍵一問：現在需要 AST 嗎？

我們最初傾向的是 tripwire 策略：現在用 Python + regex 先頂著，等 rule 複雜度超過臨界就升級 Go + goldmark。Tripwire 條件大致是：

Rule 數量超過 5 條。
任一規則需要「這段文字在 code block 內嗎」這類上下文判斷。
Hugo render 結果跟 lint 判讀開始不一致。

但事實是：

MD024 的 siblings_only 已經需要父子關係追蹤 — 條件 2 馬上命中。
卡片雙向完整性是當前任務（不是未來可能）— 跨文件檢查 regex 做不到。

兩個條件當下已經滿足，delay migration 反而要兩次寫工具。所以直接選 Go + goldmark。

這個決定的邏輯層面是：當需求已在手上而非 speculative，延遲決策的代價 > 直接上的代價。

為什麼選 goldmark

三個具體理由：

1. 解析結果與 Hugo 一致

Hugo 的 content render pipeline 走 goldmark。用同一個 parser 寫 lint，可以杜絕「lint 通過但 Hugo render 失敗」或「Hugo 看得懂但 lint 誤判」這類長尾 bug。

2. AST API 直觀

Goldmark 的 AST 節點型別設計貼近 CommonMark spec：Document / Heading / Paragraph / Link / Table / FencedCodeBlock。要寫 rule 時幾乎不需要翻對照表，直接比對心中的 markdown 結構。

3. 活躍且嵌入在主流 Go 生態

Goldmark 是 Hugo 使用的 parser，社群活躍、bug fix 持續進來。不會變成 abandoned dependency。

架構設計：單一 binary + 子命令

三個檢查功能分開寫比較好懂，但如果寫成三個 binary，每次 pre-commit 都要 parse markdown 三次，對大型 repo（我們這個已經超過 300 個 markdown）會明顯拖慢。

折衷方案是單一 binary + 子命令：

 1scripts/mdtools/
 2├── go.mod
 3├── main.go                    # subcommand dispatcher
 4├── cmd/
 5│   ├── fmt.go                 # mdtools fmt [--fix|--check]
 6│   ├── lint.go                # mdtools lint
 7│   └── cards.go               # mdtools cards
 8├── internal/
 9│   ├── astutil/               # goldmark 封裝（parse, walk, parent chain）
10│   ├── rules/                 # 規則定義（可被三個子命令共用）
11│   │   ├── config.go          # 全域開關與參數
12│   │   ├── headings.go        # 標題規則
13│   │   ├── urls.go            # URL + 反釣魚
14│   │   ├── tables.go          # 表格正規化
15│   │   ├── frontmatter.go     # front matter schema
16│   │   └── identifiers.go     # 識別碼白名單（CVE、KB、...）
17│   └── report/                # 統一錯誤輸出格式
18└── README.md

三個子命令共享 internal/astutil 和 internal/rules，同一個 parse 結果可以在不同規則間重用。

實際走訪：MD024 siblings_only 在 goldmark 上怎麼寫

這段是示範 AST-based rule 的可讀性，不是最終實作版本。

 1package rules
 2
 3import (
 4    "bytes"
 5
 6    "github.com/yuin/goldmark/ast"
 7    "github.com/yuin/goldmark/text"
 8)
 9
10// CheckSiblingsOnlyHeadings walks the document and flags headings
11// that share the same text with a sibling under the same parent heading.
12func CheckSiblingsOnlyHeadings(doc ast.Node, src []byte) []Violation {
13    var violations []Violation
14
15    // parentMap[level] 保留目前走到的各層 heading，作為後續 H(n+1) 的 parent context
16    parentMap := map[int]*ast.Heading{}
17    // 每個 parent context 下，收集已見過的子 heading 文字
18    seenUnderParent := map[*ast.Heading]map[string]ast.Node{}
19
20    ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
21        if !entering {
22            return ast.WalkContinue, nil
23        }
24
25        h, ok := n.(*ast.Heading)
26        if !ok {
27            return ast.WalkContinue, nil
28        }
29
30        text := string(h.Text(src))
31        parent := parentMap[h.Level-1] // 直接上層 heading
32        seen, exists := seenUnderParent[parent]
33        if !exists {
34            seen = map[string]ast.Node{}
35            seenUnderParent[parent] = seen
36        }
37
38        if prev, dup := seen[text]; dup {
39            violations = append(violations, Violation{
40                Rule:    "MD024-siblings_only",
41                Node:    h,
42                Message: "duplicate heading under the same parent: " + text,
43                Prev:    prev,
44            })
45        } else {
46            seen[text] = h
47        }
48
49        parentMap[h.Level] = h
50        // 進到更深層時，清空下層的舊狀態
51        for lv := h.Level + 1; lv <= 6; lv++ {
52            delete(parentMap, lv)
53        }
54
55        return ast.WalkContinue, nil
56    })
57
58    return violations
59}

對比 regex 版本要自己寫「目前 H2 是誰」狀態機 + 「切回上層時清狀態」— goldmark 的 walker pattern 把階層邏輯外部化到樹結構，rule 本身只處理「同一 parent 下有沒有重複」的核心語義。

幾百行 regex 才能穩定做到的事，AST 版本大概 30 行。規則越多，這個倍率越明顯。

Pre-commit 與 CI 整合

本地開發：`.githooks/pre-commit` 與 `.githooks/pre-push`

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4# 確保 binary 最新
 5if [[ ! -x bin/mdtools ]] || [[ scripts/mdtools/main.go -nt bin/mdtools ]]; then
 6    echo "Rebuilding mdtools..."
 7    (cd scripts/mdtools && go build -o ../../bin/mdtools .)
 8fi
 9
10# 三段式檢查
11bin/mdtools fmt --fix   # 自動修格式；改動會 re-stage
12git add $(git diff --name-only --cached --diff-filter=AM | grep '\.md$' || true)
13
14bin/mdtools lint        # 結構檢查，失敗即阻擋
15bin/mdtools cards       # 跨文件檢查，失敗即阻擋

pre-push 補上全量 gate：

1make check

關鍵設計：

mdtools fmt --fix 會改檔，改完後要 git add 回 staged，否則 commit 進去的還是舊內容。
lint 和 cards 不改檔，只讀與報告。
pre-commit 保持 staged-file scoped，讓 commit 回饋夠快；pre-push 跑全量 make check，讓本機結果和 CI 同步。
Binary mtime 檢查避免每次 commit 都 rebuild。
bin/mdtools 本身 gitignore，不 commit 進 repo。

CI：`.github/workflows/md-check.yml`

 1name: md-check
 2on: [push, pull_request]
 3
 4jobs:
 5  check:
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v4
 9      - uses: actions/setup-go@v5
10        with: { go-version: 'stable' }
11      - name: Build mdtools
12        run: (cd scripts/mdtools && go build -o ../../bin/mdtools .)
13      - name: Format check
14        run: bin/mdtools fmt --check
15      - name: Structural lint
16        run: bin/mdtools lint
17      - name: Cross-file completeness
18        run: bin/mdtools cards

CI 用 --check 而非 --fix — 任何格式偏差都 fail，不自動修（避免 CI 把修復 commit 推回去造成誤會）。

安裝 hook

1git config core.hooksPath .githooks
2# 或用 Makefile target：
3make install-hooks

維運成本的長期考量

誤判率是規則生命週期的關鍵

每條規則都可能誤判。我們的處理策略寫在規範的規則擴充流程段：

新規則先在 internal/rules/ 實作為可開關（預設關）。
在代表性檔案上測試誤判率。
誤判率 < 1% 且有明確教材品質收益時，預設開啟。
預設開啟後，同步修正既有違規。

關鍵在「預設關閉」這一步 — 給規則一個試水期，不會直接擋 commit。

規則與 spec 文件的同步

Rule config 在 internal/rules/config.go，spec 文件在 content/posts/markdown-writing-spec.md。兩者修改時必須同步，否則會出現「spec 寫的規則跟工具實際跑的規則不同步」的沉默 bug。

這是目前靠紀律維持的部分。未來如果發現同步偏差重複發生，可以考慮從 config.go 產生 spec 的片段（或反過來）。目前手動同步的成本還可接受。

規則數量的預期曲線

當前覆蓋 22 條 rule-config 條目。接下來加規則的收益會遞減 — 大部分重要的基礎格式 + 結構 + 跨文件檢查都已在內。未來新增應該集中在：

新內容類型帶來的 schema 擴充（例如做 podcast 或者 video posts）。
術語字典完成後的 L3 術語覆蓋（正文首次出現術語自動連卡片）。
特定領域的品質檢查（例如紅隊教材「每個案例必須有 3 來源」）。

基礎 markdownlint 規則能加的都加完了，再追規則就是在吸邊際收益極低的條目，不值得。

Pagefind：靜態站搜尋的 build-time 索引方案

Fri, 24 Apr 2026 00:00:00 +0000

靜態站搜尋的問題空間

靜態站沒有後端可以接查詢，所有搜尋工作必須在兩個時點之一完成：build 時產生索引、client runtime 執行匹配。這個前提決定了所有靜態站搜尋方案共同面對的兩個設計軸：

設計軸	意義
索引產生時機	build 時靜態產生，或 client 載入後動態建立
索引交付方式	一次全量下載，或按查詢 lazy-load

方案差異來自這兩軸的組合。Pagefind 選的是「build 時產生、按需載入」，它的所有設計決策都是這個選擇的延伸。

核心設計：索引切片與按需載入

商業邏輯：搜尋索引的 scaling 關鍵是單次查詢需要下載多少資料，而非壓縮率或演算法效率。若索引是一整包、每次查詢都要先整包載入，訪客體驗與站的大小線性綁定 — 站大 10 倍，首次搜尋延遲 10 倍。

要脫離這條綁定，索引必須能以「與查詢相關」的粒度切片、按需傳輸。這把「索引多大」的問題從訪客手上移回 build pipeline。

CASE：Pagefind 的索引是三層結構：

層次	內容	大小
`pagefind-entry.json`	索引目錄，記載有哪些 chunk 與 fragment	<10KB
`index/*.pf_index`	倒排索引切片，依 term 前綴分片	10-50KB / chunk
`fragment/*.pf_fragment`	每篇文章的 metadata、URL、摘要	2-5KB / fragment

查「WAF」時，client 下載路徑是：entry（10KB）→ 涵蓋 “W” 的 index chunk（~30KB）→ 命中文章的 fragment（每筆 3KB）。總傳輸量與全站大小幾乎脫鉤 — 站擴大 10 倍，單次搜尋仍然只下載「W」那個 chunk 與少數 fragment。

架構選擇：爬 rendered HTML

商業邏輯：索引內容的來源有兩種可能：source 層（markdown、frontmatter、結構化資料）或 output 層（render 後的 HTML）。選哪一層決定工具與 framework 的耦合程度 — source 層要求工具懂特定 framework 的內容模型；output 層只要求結果是 HTML。

Pagefind 選 output 層。含義是：它跟 Hugo、Jekyll、Zola、Next.js static export 完全解耦，只要該 framework 產出的是 HTML，Pagefind 都能索引。

CASE：此選擇在 blog 端的具體要求：希望被搜到的內容必須出現在 rendered HTML 上。frontmatter 的 description 欄位若只存在於 markdown source、沒被 theme 輸出成或可見文字，就不會進索引。

這個 blog 天然滿足 — theme 把 description 寫進，render hook 也用它做 tooltip。移植到任何其他 static site generator，只要目標的 output HTML 有這些欄位，搜尋整合不用重寫。

整合步驟

1. Build pipeline

核心動作：Hugo build 後加一步 Pagefind。

1hugo --minify
2npx -y pagefind --site public

兩步，沒有中間檔。Pagefind 自行讀取 public/ 的 HTML，將索引寫回 public/pagefind/。

2. 搜尋頁路由

核心動作：建立 Hugo 單頁，指向專屬 layout。

1---
2title: "搜尋"
3layout: search
4sitemap:
5  disable: true
6---

sitemap.disable 避免搜尋頁自己被 Hugo sitemap 收錄。

3. UI 掛載

核心動作：在 layout 中載入 Pagefind UI 資源，指定 mount point。

 1{{ define "main" }}
 2<div data-pagefind-ignore>
 3  <link href="{{ "pagefind/pagefind-ui.css" | relURL }}" rel="stylesheet">
 4  <div id="search">div>
 5  <script src="{{ "pagefind/pagefind-ui.js" | relURL }}">script>
 6  <script>
 7    window.addEventListener('DOMContentLoaded', function () {
 8      new PagefindUI({
 9        element: "#search",
10        showSubResults: true,
11        translations: { placeholder: "搜尋卡片或文章…" }
12      });
13    });
14  script>
15div>
16{{ end }}

兩個細節：

data-pagefind-ignore 告訴 Pagefind 這頁本身不要進索引（避免搜「搜尋」出現搜尋頁）。
relURL 處理 baseURL 的 subpath（例如 /blog/），讓 UI 自動推斷 chunk 相對位置。

4. CI workflow

核心動作：GitHub Actions 在 Hugo build 步驟後插入 Pagefind。

1- name: Build Pagefind search index
2  run: npx -y pagefind --site public

ubuntu-latest runner 內建 node，npx -y 首次執行會下載並 cache binary，後續執行直接從 cache 取用。

方案的內在屬性

評估 Pagefind 不看「比較快」「比較省事」這類時間維度，用下列內在屬性：

維度	Pagefind 的特徵
覆蓋完整性	索引全站 HTML；不需要逐 section 註冊
可逆性	產物是檔案，移除就是刪除 `public/pagefind/` 與搜尋頁，無殘留依賴
維護成本	build pipeline 多一步；無 runtime 服務、無 key 管理、無版本相依性
可理解性	UI drop-in、filter 用 HTML 屬性宣告、三層索引結構直觀
依賴前提	要求目標 framework 能產出 HTML（絕大多數 static generator 滿足）
擴展性	單次查詢下載量與全站大小脫鉤 — scaling 由 build time 吸收，不轉嫁到訪客

內建的一等公民特性：

Filter by facet：data-pagefind-filter="type:card" 標在 HTML 元素上，UI 自動出現對應 filter checkbox
Snippet highlighting：命中的關鍵字在結果摘要中高亮
無障礙：Component UI（1.5.0+）內建 keyboard navigation、ARIA label、screen reader 公告

這些特徵都源自「build 時產生 + 按需載入」這個核心選擇的延伸，不是外掛功能。

運作特徵

zh-tw 走 character n-gram

核心定義：Pagefind 對非空白分詞語言採 n-gram — 以字元序列作為匹配單位，而非詞。

行為：搜「負載平衡」能命中「負載平衡器」、「負載平衡器測試」等任何包含該字元序列的頁面。啟動時會印一行 stemming note，那是針對屈折變化語言（英文、德文）的 stemming 提示，對中文無意義也無限制。

邊界：少數情境下跨詞邊界的字元組合會誤命中（例如搜「負載過」可能命中「負載過高」與「負載過往」）。在名詞為主的技術站影響極小。

索引來自 rendered HTML

核心定義：索引內容 = Pagefind 在 public/*.html 看到的可見文字與 meta tag。

含義：想加入索引的欄位必須出現在 output HTML 上。想排除的區塊用 data-pagefind-ignore 標記。想作為 filter 的屬性用 data-pagefind-filter="name:value"。

Default UI 的樣式是 Pagefind 自家風格

核心定義：PagefindUI component 有固定的視覺設計，透過 CSS variable 可微調顏色、圓角、spacing。

含義：想要與 theme 完全融合有兩條路 — 覆寫 CSS variable（官方 docs 列出可覆寫清單），或改用 Pagefind JS API 自己組 UI（更完整客製）。

Build pipeline 多一步

核心定義：Pagefind 是 Hugo build 外的獨立步驟。

含義：CI 與本地都要記得跑 npx pagefind。這個 blog 以 Makefile 的 make site 封裝 hugo + pagefind 兩步，把「記得」轉成 infrastructure 強制項。

適合的場景

靜態站、內容持續成長
部署在 GH Pages / Netlify / Cloudflare Pages 等純靜態平台
希望零外部依賴、完全自託管
內容以文字為主（blog、docs、knowledge base）
未來可能換 framework — 希望搜尋整合不隨之重寫

什麼是 AST — 從字串到語法樹的視角轉換

Fri, 24 Apr 2026 00:00:00 +0000

為什麼會碰到這個詞

最初的問題很小：blog 文章數量成長後，每次 commit 都會收到 markdownlint 的同類警告反覆出現。有三個代表性的：

MD034/no-bare-urls — 裸 URL 散落在段落與表格。
MD024/no-duplicate-heading — 平行結構章節（例如 13 個案例各自有 ### 弱點環節）全部被判重複。
MD060/table-column-style — 表格管線前後空白不一致。

前兩個用現成工具 --fix 不一定修得乾淨，因為 MD024 的「重複」在我們的語境下是合法的平行結構（不同父標題下重名其實是特色），而「裸 URL 轉換」要處理表格儲存格、程式碼區塊等特殊情境，單純 regex 會誤判。

討論到後來關鍵字出現：要做得精確，可能要用 AST 工具，而不是 regex 工具。

那麼 AST 到底是什麼？跟我們熟悉的 regex / 字串處理差在哪？

Regex 工具看世界的方式：字元序列

Regex 工具處理 markdown 的方式是「逐行掃描 + pattern matching」。它看到的是字元流，沒有語法結構的概念。

舉個例子：

1## 【案例一】Uber 2022
2
3事件中攻擊者取得 `session_token`，參考：
4https://www.uber.com/newsroom/security-update/
5
6| 事件      | 來源             |
7| --------- | ---------------- |
8| Uber 2022 | https://uber.com |

Regex 工具看到的是：

1Line 1: "## 【案例一】Uber 2022"            ← ^#{1,6} match  → heading
2Line 3: "事件中攻擊者取得 `session_token`..."  ← 無 pattern 命中
3Line 4: "https://www.uber.com/..."            ← ^https?:// match → bare URL!
4Line 7: "| Uber 2022 | https://uber.com |"   ← ^\| match     → table row

每一行獨立判讀，沒有上下文。Regex 工具不知道 line 4 到底是「段落的一部分」、「引用區塊裡的連結」、還是「程式碼範例」。它只看 pattern。

AST 工具看世界的方式：語法樹

AST = Abstract Syntax Tree，抽象語法樹。AST 工具先把整段 markdown 用 parser 解析成結構化的樹，然後工具在樹上走訪（traverse），操作「節點」而不是「行」。

同一段 markdown，goldmark（Hugo 內建的 markdown parser）解析後的樹大致是：

 1Document
 2├── Heading (level=2)
 3│   └── Text: "【案例一】Uber 2022"
 4├── Paragraph
 5│   ├── Text: "事件中攻擊者取得 "
 6│   ├── CodeSpan: "session_token"            ← 知道這是 inline code
 7│   ├── Text: "，參考："
 8│   └── AutoLink: "https://www.uber.com/..."  ← 知道這是段落中的裸 URL
 9└── Table
10    ├── TableHeader: [事件, 來源]
11    └── TableRow
12        ├── TableCell: "Uber 2022"
13        └── TableCell: AutoLink "https://uber.com"  ← 知道這是表格儲存格中的 URL

對同一個 URL，AST 工具能分辨「它在段落裡」還是「它在表格儲存格裡」還是「它在程式碼區塊裡」— 因為節點的父子關係已經是樹的一部分。

這個差異乍看像技術細節，實際影響的是能寫出什麼樣的規則。

典型意外情境：regex 會誤判的三個 case

程式碼區塊內的 URL

1## 測試範例
2
3```bash
4curl https://example.com/api  # 這是程式碼範例，不該報 MD034
5```

Regex 看到 https:// 開頭就標記裸 URL。AST 知道這一行在 FencedCodeBlock 子樹內，跳過。

Front matter 裡的 `#` 被當 heading

1---
2title: "Python 的 # 註解語法"
3---
4
5真正的文章內容...

Regex 看到 ^# 就當 heading 記一筆（title 裡面有 # 字元）。AST 知道 ---...--- 區塊是 YAML front matter，title 的值是字串。

平行結構標題被誤判為重複

在多案例教材裡：

1## 【案例一】Uber 2022
2
3### 弱點環節 ← 第 1 次出現
4
5### 攻擊路徑
6
7## 【案例二】Okta 2023
8
9### 弱點環節 ← 第 2 次出現，regex 會直接報重複

要用 regex 實作「不同父標題下允許重複」這種 siblings_only 規則，需要自己維護狀態機追蹤「目前 H2 是誰」「遇到 H3 時算哪個 H2 底下」。遇到 H4/H5 階層更複雜。

用 AST，父子關係已經內建在樹結構裡：

1// 偽代碼，實際用 goldmark walker 取代
2for _, h2 := range allHeadingsAtLevel(doc, 2) {
3    children := childrenOfType(h2, Heading)
4    checkDuplicates(children)  // 自動只比對同一 H2 下的子標題
5}

不用追蹤狀態，邏輯上直接表達。

為什麼對我們特別重要：goldmark = Hugo 的 parser

Hugo（blog 的 static site generator）內建的 markdown parser 就是 goldmark。用 goldmark 寫 lint 有個平凡但關鍵的保證：lint 的判讀跟 Hugo render 的判讀完全一致。

如果用不同的 parser 寫 lint（例如 Python 的 mistune、JavaScript 的 markdown-it），很可能遇到這種尷尬：

Lint 通過，但 Hugo 解析不出來，render 失敗或跑版。
Lint 報錯，但 Hugo 看得懂、實際沒有問題。

兩套 parser 解讀差異是長尾 bug 的溫床。用同一個 parser 可以從源頭杜絕這類不一致。

什麼時候 AST 不是必要的

不要為了「比較先進」就上 AST。Regex 在下列情境完全夠用：

檢查每行開頭字元（^#、^|、^- ）。
簡單字串替換（例如 URL 前後加 <> 包裹）。
不需要知道上下文的格式正規化（行尾空白、tab 轉空白）。

需要 AST 才能穩定做到的是：

判斷「這段文字在 code block 內嗎？」
判斷「這個 heading 的父 heading 是誰？」
追蹤跨文件的連結關係（卡片 backlink 完整性）。
檢查「這個 Strong 節點是不是整個段落的唯一子節點？」（MD036 粗體當標題濫用）

一個實務判準：如果 rule 需要「知道這段文字處在什麼結構中」，regex 會卡住；AST 天生就有這個資訊。

我們的判斷：什麼時機該升級到 AST

blog 專案一開始也考慮過用 Python + regex 先頂著，等規則變複雜再升級 Go + goldmark。後來有兩件事讓我們直接選 AST：

MD024 siblings_only 已經是「需要上下文」的規則，regex 做得到但會寫得脆弱。
知識卡片雙向完整性是當前在做的工作（每張卡片要被正文連到、每張卡片首段要有鄰卡連結），這類跨文件 + 段落歸屬的檢查，regex 做不出來。

當需求已經在手上，延遲決策反而更貴。對我們來說，AST 不是超前部署，是現在的 blocker。

技術文章撰寫規範

Fri, 17 Apr 2026 00:00:00 +0000

適用範圍

本規範適用於團隊內部各類型技術文章，包含：

概念說明：技術原理、系統架構、協定規格
實作教學：操作步驟、範例、API 用法
架構決策：方案比較、選型紀錄、設計文件
除錯復盤：事故紀錄、疑難排解
技術評估：工具調研、可行性評估

核心目標：讓讀者能複製思考過程，不只複製結論。結論一行就能給，思考過程才是文章的主體。

本規範四條規則各自後方附有正反例，來源標註：

正例多引自 /work-log/ 目錄下的已成文文章
反例多引自同系列文章修改前的版本（實際寫作過程中踩到過的問題）

一、階段分層

規則的商業邏輯

技術文章的內容從「事實或需求」推導到「動作或結論」，這個過程有四個功能不同的階段。每個階段處理的問題不同、失敗模式不同：

觀察：描述現況、需求、事實或訊息
判讀：說明本質、原理、問題所在
策略：列出可選方案並比較
執行：具體操作或實作

四階段若混著寫，讀者無法區分「這一段失敗是哪個階段」，也無法判斷自己的類似情境卡在哪一步。文章只能被原封不動複製，不能被理解後套用。

做法

每個主題段落應包含四階段。不同類型文章中四階段的對應：

階段	概念說明	實作教學	架構決策	除錯復盤
觀察	需求或背景	使用情境	現況限制	錯誤訊息
判讀	概念本質	工具的位置與功能	需求本質	問題根因
策略	不同用法	不同操作路徑	可選方案	可行解法
執行	程式碼範例	操作步驟	選定實作	修復動作

實例對照

反例（跳過判讀，觀察直接進執行）：

1## 錯誤
2flutter_broadcasts_4m：Kotlin 1.8 vs Java 17 mismatch
3
4## 解法
5在 subprojects 加上：
6tasks.withType(KotlinCompile).configureEach { jvmTarget = '17' }

問題：讀者能複製貼上，但無法回答「為什麼是 configureEach 不是其他方式」「遇到下一個類似問題怎麼想」。思考過程沒有被保存。

正例：gradle_reasoning_traps 的節點 A 結構，每個節點顯式展開成「當下看到 → 判讀 → 可選策略 → 選擇與理由 → 結果 → 事後檢視」六個子段落。讀者看完後即使遇到不同錯誤訊息，也能套用同一個四階段推導。

禁止事項

從觀察直接跳執行，省略判讀與策略
判讀留下未解問題就進策略
文章中出現「選擇」卻只列一個選項

例外

純介紹性段落（例如 API 參數說明）可以省略「策略」階段，但不得省略判讀。

二、商業邏輯先於 CASE

規則的商業邏輯

技術文章的內容包含兩種資訊層次：

商業邏輯：系統層的概念（為什麼這件事存在、在體系中代表什麼）
CASE：實例層的資料（具體的數值、路徑、屬性、設定）

CASE 單獨存在沒有意義。「jvmTarget = 17」這個值需要「為什麼 JVM target 要一致」這個概念當容器才能被理解。

順序顛倒（先 CASE 後商業邏輯）等於讓讀者先記一組沒有脈絡的資料，再倒推抽象概念。這條認知路徑是反向的，多數讀者在倒推失敗後會放棄，即使專業讀者能勉強跟上也會覺得閱讀成本偏高。

做法

每個主題段落包含兩層，順序不得顛倒：

商業邏輯層

主題涉及的系統層概念
該概念為什麼存在、解決什麼問題
該類內容的共通本質

此層不討論具體數值、路徑、屬性名。

CASE 層

訊息或規格中的關鍵字對應商業邏輯的哪個位置
具體數值或內容
從 CASE 推論的結論

實例對照

反例（直接給 CASE，預設讀者懂背景）：

1### 判讀
2
3- 這個子專案的 Java task 產出 bytecode target = 17
4- 同一個子專案的 Kotlin task 產出 bytecode target = 1.8
5- 兩者不一致觸發 Kotlin 2.2 的 strict validation

專業人士看了懂，但讀者若不知道「bytecode target」「strict validation」在系統中代表什麼，只能抓到字面字串，無法建立模型。

正例（加上商業邏輯層當容器）：

 1### 判讀
 2
 3**這類錯誤的本質（商業邏輯）**：
 4
 5Android 每個 module 會分別編譯 Java 跟 Kotlin 原始碼，各自產出
 6JVM bytecode。每個 bytecode 有 target version，決定能在哪些 JVM
 7runtime 上跑。同 module 內若兩種語言產出不同 target，runtime
 8可能踩到 API 相容性問題。Kotlin 2.2 把這個從 warning 提升為 error。
 9
10**這次訊息具體說了什麼（CASE）**：
11
12- compileDebugJavaWithJavac (17) → Java 產出 target 17
13- compileDebugKotlin (1.8) → Kotlin 產出 target 1.8
14- 符合上面「module 內不一致」的 pattern

（出自 gradle_reasoning_traps 節點 A 修改後的版本。修改前是反例那種寫法，修改後加入商業邏輯層。）

完成標準

段落結束前，讀者應能回答：

這個主題在系統中為什麼重要？
這個主題的具體案例對應商業邏輯的哪個位置？

若只能回答第二題，商業邏輯層不足。

三、評估用內在屬性

規則的商業邏輯

技術文章經常包含選擇或比較：選 A 不選 B、用 X 不用 Y、選這個架構不選另一個。選擇的優劣取決於方案的內在屬性，不取決於執行者的時間消耗：

內在屬性：覆蓋完整性、風險、可逆性、維護成本、可理解性、依賴前提
時間消耗：實作要多久、多少人工時

時間消耗是執行者的資源考量，跟方案本身的正確性無關。用時間當評估維度會造成結構性偏差：投資型方案（擴大影響、建立基礎）看起來總是比消費型方案（解當前問題）差，但兩者能力的性質不同，不應以同一量度比較。

讀者讀到時間評估會誤以為「這個方案比較好」，但真正該學到的是「兩個方案各自適合什麼情境」。

做法

每個方案比較必須包含下列維度中至少三項：

維度	評估內容
覆蓋完整性	處理所有同類情境，還是只處理當前
風險	失敗機率與代價
可逆性	出錯能否回滾
維護成本	長期需要多少精力
可理解性	未來接手者能否理解
依賴前提	建立在什麼假設上，前提變了會如何

實例對照

反例（用時間成本換算划不划算）：

1節點 A 事後回顧：
2這一步多 2 分鐘掃一遍 pub-cache，但可以省下後來約 30 分鐘的
3build-炸-修循環。明顯划算。

讀者學到的是「划不划算」這個執行層結論，沒學到兩個方案的結構性差異。

正例（用內在屬性列出方案差異）：

 1節點 A 事後檢視：
 2
 3若當下選擇「A2 + 同步盤點 pub-cache」：
 4
 5- 優點：一次盤點所有同類地雷，修復範圍完整；避免之後
 6  遇到一個修一個的反應式除錯
 7- 缺點：盤點結果可能含假陽性；擴大修復範圍可能引入新變數
 8
 9當下漏掉這個選項的本質問題是：
10單點錯誤修復後沒有主動擴大搜尋同類問題。
11這是決策是否涵蓋完整問題面的問題，不是執行層的快慢考量。

（出自 gradle_reasoning_traps 節點 A 事後檢視。修改前是反例版本，修改後改用「覆蓋完整性」「範圍完整」這類內在屬性。）

禁止事項

不得以時間成本作為主要評估維度，包含：

「這方案比較快」
「多花 X 分鐘省下 Y 分鐘」
「立即可完成」

四、事後檢視看判讀品質

規則的商業邏輯

技術文章的品質檢視（review、事故檢討、復盤）常只看「結論對不對」，但多數失敗的根源在判讀階段：

判讀未確認的推論被當結論
判讀觀察範圍不足（只看單點）
判讀用類比代替機制驗證

這類問題會表現成「結論失敗」的樣子，但改善方向完全不同：

結論失敗 → 下次多列幾個選項
判讀失敗 → 下次判讀要更嚴謹、更廣、更實證

兩者混為一談會得到「要更仔細」這種無法行動的結論。

做法

文章或決策完成後，必須回答下列四題：

判讀階段的「需要確認」項目是否全部解答？
觀察範圍是否涵蓋同類情境，或僅處理當前一個？
推論中的類比假設是否驗證？
策略列舉是否完整？

任一題答「否」，對應失敗類型必須明確標示：

答「否」的題	失敗類型	改善方向
題 1	未確認推論帶入結論	判讀完成標準要收緊
題 2	觀察範圍不足	擴大搜尋類似情境
題 3	類比代替驗證	機制差異需實證
題 4	策略列舉不足	至少列兩個選項

實例對照

反例（只檢視結論，歸因模糊）：

1這次修復走了彎路，下次應該更仔細。

無法行動。下次遇到類似情境仍會犯同樣錯誤。

正例（分類失敗類型，對應不同改善方向）：

 1七個節點中四個失敗，分類：
 2
 3| 節點 | 失敗類型 | 根本來源 |
 4|---|---|---|
 5| 節點 C | 需要新資訊（toolchain 時機） | 節點 B 判讀留下「需要確認」但沒補 |
 6| 節點 D1 | 對稱假設 | 節點 D 判讀用「結構對稱」取代「機制驗證」 |
 7| 節點 F | 方法呼叫時機 | 節點 E 判讀沒展開 API 的兩階段行為 |
 8
 9三個失敗都源自判讀未完成就進策略。不是策略選錯，是判讀階段
10進入策略時，還帶著未解決的問題。

（出自 gradle_reasoning_traps 的「整個過程的決策品質檢視」段落。）

這樣的檢視產出具體改善方向：「判讀完成標準要收緊」、「機制差異需實證」，而不是模糊的「要更仔細」。

五、判讀徵兆對照

技術文章撰寫中常見的徵兆與對應的判讀要求。看到徵兆時，作者必須回答對應問題。

徵兆：單一位置指向（檔案、行號、屬性名）

該位置是「現場」，不一定是「根因」。必須追問：

為什麼是這個位置出問題？
是目標的狀態錯了，還是呼叫的時機錯了？

徵兆：同類情境第二次出現

前次處理範圍不完整。必須追問：

還有哪些同類情境？
是否有共通原因？

徵兆：修改看似合理但未生效

時機或機制假設錯誤。必須追問：

修改的生效時機是否晚於覆蓋對象？
覆蓋機制是否真的能蓋過目標？

徵兆：「final」「already」「cannot」這類字眼

目標已進入不可修改狀態。必須追問：

目標何時進入該狀態？
修改能否提前到狀態轉換之前？

徵兆：「inconsistent」「mismatch」這類字眼

兩部分不一致。必須追問：

哪一邊是正確的目標值？
不一致的方向決定治理施加在哪一邊？

實例

這組徵兆對照表的完整應用案例見 gradle_evaluation_order_traps，該文將三種 Gradle 時序錯誤（already evaluated、is final、覆寫沒生效）各自對應到同一個底層問題（時機錯位），並給出對應的解法方向。這就是「看到徵兆 → 查表 → 推出判讀結論」的標準路徑。

六、術語

術語	定義
商業邏輯	系統層次的概念說明，不涉及具體值
CASE	具體內容（數值、路徑、屬性名）
判讀	從事實推導本質的過程
策略	可選方案
現場	訊息直接指向的位置
根因	底層原因，不一定等於現場
投資型策略	有長期回報的方案（擴大覆蓋、建立認知）
消費型策略	只處理當前問題的方案

七、提交自檢

提交文章前自檢：

四階段（觀察／判讀／策略／執行）完整，或已說明可省略的階段
每個主題段落先商業邏輯後 CASE
判讀中所有「需要確認」項目已解答或註明可暫不確認
每個方案比較至少三個評估維度
未以時間成本為主要評估維度
事後檢視四題已回答
失敗類型已標示（若有）

參考範例

本規範四條規則的完整應用案例：

Gradle JVM target 除錯復盤：七個節點的策略權衡 — 全四條規則的完整應用，每個節點皆含觀察／判讀／策略／結果／事後檢視五層
Gradle 強制覆寫 plugin 的 JVM target：Kotlin 與 Java 的切入點不對稱 — 商業邏輯先於 CASE 的範例（先講 Kotlin plugin 與 AGP 的機制差異，再講具體寫法）
Gradle Configuration 時序陷阱：afterEvaluate、evaluationDependsOn、finalized properties — 判讀徵兆對照的完整應用
為什麼 Bug 在合併後才爆：Gradle Cache 掩蓋潛伏問題的邏輯 — 事後檢視看判讀品質的範例（將「合併造成」重新歸因為「判讀時把觸發條件當根因」）

用 Claude Code GitHub Actions 自動除錯 CI 建置失敗

Wed, 04 Mar 2026 00:00:00 +0000

這是什麼

Claude Code GitHub Actions 讓 Claude 直接參與你的 GitHub 工作流程，主要功能：

互動式助手 — 在 PR/Issue 留言 @claude，Claude 會分析程式碼並回覆
自動 Code Review — PR 開啟時自動審查變更
CI 除錯修復 — build 失敗時自動分析錯誤並修復

完整功能說明參考官方文件。

設定方式

`/install-github-app`（推薦）

在 Claude Code 終端執行 /install-github-app，它會引導你完成所有設定。

流程中的關鍵步驟：

選擇 repo — 指定要安裝的 GitHub repository
安裝 Claude GitHub App — 自動安裝到指定 repo，授予 Contents、Issues、Pull requests 的 Read & Write 權限
選擇認證方式 — 選擇 long-life token 會產生 OAuth token，自動寫入 GitHub Secrets 為 CLAUDE_CODE_OAUTH_TOKEN
建立 workflow 檔案 — 自動建立並 push 兩個 workflow：
- claude.yml — @claude 互動回覆
- claude-code-review.yml — PR 自動 code review

完成後不需要額外設定。

手動設定（使用 Anthropic API Key）

如果不想用 /install-github-app，可以手動操作：

前往 github.com/apps/claude 安裝 App 到你的 repo
到 repo 的 Settings → Secrets and variables → Actions，新增 ANTHROPIC_API_KEY
手動建立 workflow 檔案到 .github/workflows/

兩種認證方式的差異：

認證方式	Secret 名稱	適用對象
OAuth Token	`CLAUDE_CODE_OAUTH_TOKEN`	Pro/Max 用戶，`/install-github-app` 自動設定
API Key	`ANTHROPIC_API_KEY`	直接使用 Anthropic API，需手動到 console.anthropic.com 取得

加入 CI 自動除錯

/install-github-app 建立的 workflow 只處理 @claude 互動和 code review。如果你想在 build 失敗時自動觸發 Claude 修復，需要修改既有的 deploy workflow。

首先，補上 Claude 需要的權限（原本可能只有 contents: read）：

1permissions:
2  contents: write        # Claude 需要寫入修復後的檔案
3  pull-requests: write   # Claude 可能需要建立 PR
4  issues: write          # Claude 回報結果
5  pages: write           # 原本的 deploy 權限
6  id-token: write        # 原本的 deploy 權限

然後在 build 步驟加入 Claude 除錯邏輯：

 1# 在原本的 build step 加上 continue-on-error 和 id
 2- name: Build
 3  id: hugo-build
 4  run: hugo --minify 2>&1 | tee hugo-build-output.txt
 5  continue-on-error: true
 6
 7# Build 失敗時觸發 Claude 除錯
 8- name: Claude Debug on Build Failure
 9  if: steps.hugo-build.outcome == 'failure'
10  uses: anthropics/claude-code-action@v1
11  with:
12    # 依你的認證方式擇一
13    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
14    # anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
15    prompt: |
16      Hugo build failed. Here is the error output:
17
18      $(cat hugo-build-output.txt)
19
20      Please analyze the error, find the problematic file(s),
21      fix the YAML front matter or content issue, and commit the fix.
22    claude_args: "--max-turns 10"
23
24# 修復後重新 build 驗證
25- name: Retry build after fix
26  if: steps.hugo-build.outcome == 'failure'
27  run: hugo --minify

核心設計：

continue-on-error: true — build 失敗不中斷流程，讓後續 Claude 步驟有機會執行
if: steps.hugo-build.outcome == 'failure' — 只在失敗時觸發，正常 build 不消耗 API 額度
修復後重新 hugo --minify 驗證是否成功

計費方式

計費取決於你使用哪種認證方式：

認證方式	計費來源	說明
OAuth Token	訂閱額度（Pro/Max）	跟 claude.ai 網頁、Claude Code CLI、Claude Desktop 共用同一個額度池
API Key	獨立 API 計費	按 token 用量付費，與訂閱額度完全分開

OAuth token 的額度是共用的，GitHub Actions 跑多了會擠壓你日常在 claude.ai 和 CLI 的使用額度。如果 CI 觸發頻繁，建議改用 API Key 避免互相影響。

詳細的費率可參考 Claude 定價頁面。

降低成本的設定

設定	說明
`--max-turns 10`	限制迭代次數，避免無限循環
只在 `failure` 時觸發	正常 build 不消耗 API 額度
`@claude` 觸發詞	互動模式只在明確呼叫時才啟動

搭配 CLAUDE.md

在 repo 根目錄建立 CLAUDE.md，Claude 會自動讀取作為上下文，提升修復準確度。

參考資料

Hugo Shortcode 實現可折疊區塊

Thu, 09 Oct 2025 00:00:00 +0000

問題背景

在撰寫技術文章時，我們會在文章中加入程式碼範例。但是 blog 的目標是分享我處理問題的思路，而不是提供解決方案，所以我希望預設把程式碼隱藏。

最初的解決方案

使用 HTML5 的 <details> 和 <summary> 標籤：

1<details>
2<summary>點擊查看程式碼</summary>
3
4\```javascript
5console.log('Hello World');
6\```
7
8</details>

這個方案雖然功能正常，但會觸發 MD033 Markdown Linter 警告：

1MD033/no-inline-html: Inline HTML [Element: details]

為什麼會有這個警告？

Markdown 設計哲學

Markdown 的設計理念是：

保持純文字的可讀性
避免直接使用 HTML 標籤
使用語義化的標記語法

MD033 規則的目的

MD033 規則旨在：

維持 Markdown 的純淨性：避免 HTML 與 Markdown 混用
提升可維護性：純 Markdown 更容易閱讀和維護
確保相容性：不同的 Markdown 渲染器對 HTML 的支援程度不同

Hugo Shortcode 解決方案

什麼是 Shortcode？

Hugo Shortcode 是 Hugo 靜態網站生成器提供的一個強大功能，允許你：

在 Markdown 中使用自定義的簡短標記
封裝複雜的 HTML 結構
保持 Markdown 文件的整潔

優勢分析

特性	HTML 標籤	Hugo Shortcode
Markdown Linter	觸發警告	無警告
可維護性	分散在各處	集中管理
可讀性	較差	優秀
彈性	固定結構	可自定義
Hugo 最佳實踐	不推薦	官方推薦

實現步驟

步驟 1：創建 Shortcode 檔案

在專案根目錄創建 layouts/shortcodes/details.html：

點擊查看 Shortcode 程式碼

 1{{/* 
 2 Details shortcode - 用於創建可折疊的內容區塊
 3 
 4 使用方式:
 5 
 6
 7<details>
 8 <summary>點擊展開</summary>
 9 
10 內容...
11 
12</details>
13 
14 參數:
15 - summary: 摘要文字（可選，預設為 "點擊展開"）
16*/}}
17<details>
18 <summary>{{ .Get "summary" | default "點擊展開" }}</summary>
19 {{ .Inner | markdownify }}
20</details>

程式碼說明：

註解區塊：{{/* ... */}} 用於說明 shortcode 的用途和使用方式
參數獲取：.Get "summary" 獲取 summary 參數
預設值：default "點擊展開" 提供預設文字
內容處理：.Inner 獲取標籤內的內容
Markdown 渲染：markdownify 將內容中的 Markdown 語法轉換為 HTML

步驟 2：在 Markdown 中使用

舊方式（會觸發 MD033）

 1<details>
 2<summary>點擊查看程式碼</summary>
 3
 4\```toml
 5[markup]
 6 [markup.tableOfContents]
 7 startLevel = 2
 8\```
 9
10</details>

新方式（符合 Markdown 規範）

1


 點擊查看程式碼
 

\```toml
[markup]
 [markup.tableOfContents]
 startLevel = 2
\```

步驟 3：添加 CSS 樣式

在 layouts/partials/custom_head.html 中添加樣式：

Hugo 部落格支援 Mermaid 流程圖完整實現指南

Wed, 08 Oct 2025 00:00:00 +0000

概述

本文詳細說明如何在 Hugo 部落格中實現 Mermaid 流程圖支援，包含：

Mermaid.js 整合與初始化
Markdown 語法轉換處理
自定義樣式設計
響應式圖表適配
多種圖表類型支援

1. 問題分析

1.1 Hugo Markdown 渲染問題

Hugo 的 Markdown 渲染器會將 Mermaid 程式碼區塊包裝在 <pre><code> 標籤中：

1<pre><code class="language-mermaid">
2graph TD
3 A[開始] --> B{判斷條件}
4 B -->|是| C[執行動作]
5 B -->|否| D[結束]
6</code></pre>

但 Mermaid.js 需要的是 <div class="mermaid"> 標籤：

1<div class="mermaid">
2graph TD
3 A[開始] --> B{判斷條件}
4 B -->|是| C[執行動作]
5 B -->|否| D[結束]
6</div>

1.2 解決方案

使用 JavaScript 動態轉換 Markdown 渲染的程式碼區塊為 Mermaid 所需的格式。

2. 實現步驟

2.1 引入 Mermaid.js

在 layouts/partials/custom_head.html 中添加 Mermaid.js：

點擊查看引入程式碼

```html ```

2.2 語法轉換腳本

添加 JavaScript 來轉換 Markdown 渲染的程式碼區塊：

點擊查看語法轉換 JavaScript 程式碼

```html ```

2.3 自定義樣式

添加 Mermaid 圖表的 CSS 樣式：

點擊查看 CSS 樣式程式碼

```html ```

3. 完整實現程式碼

3.1 custom_head.html 完整程式碼

點擊查看完整實現程式碼

```html ```

4. 使用方式

4.1 基本語法

在 Markdown 文件中使用 Mermaid 語法：

Hugo 部落格側邊章節導航 (TOC) 完整實現指南

Wed, 08 Oct 2025 00:00:00 +0000

概述

因為文章太長，閱讀困難，所以看到別人部落格有的TOC功能，就找AI復刻

需求

使用TOC快速定位
TOC隨著本文滾動定位當前位置
手機寬度下不顯示TOC，改用回到頁首的懸浮按鈕取代

1. Hugo 配置設定

1.1 啟用 TOC 功能

在 hugo.toml 中啟用 TOC 功能：

點擊查看配置程式碼

```toml [markup] [markup.tableOfContents] startLevel = 2 endLevel = 4 ordered = false ```

參數說明：

startLevel = 2：從 H2 標題開始生成 TOC
endLevel = 4：到 H4 標題結束
ordered = false：使用無序列表格式

2. 自定義文章佈局

2.1 建立自定義 single.html

在 layouts/_default/single.html 中實現新的佈局結構：

點擊查看完整 HTML 佈局程式碼

```html {{ define "main" }}

{{ .Date.Format (default "2006-01-02" .Site.Params.dateFormat) }} {{ with .Params.author }}· {{.}}{{ end }}

{{ range (.GetTerms "tags") }} #{{ lower .LinkTitle }} {{ end }}

{{ i18n "email-reply" }} ↪

{{ end }} ```

3. CSS 樣式設計

3.1 側邊欄樣式

在 layouts/partials/custom_head.html 中添加 CSS：

在文章中加入圖片的語法

Wed, 17 Sep 2025 00:00:00 +0000

在文章中引用assets的圖片

我現在的做法是assets第一層資料夾是大分類，第二層資料夾一個文章一個資料夾，然後每個文章使用的圖片集中那個資料夾

語法

1.使用 Hugo 的圖片處理功能

2.使用標準 Markdown 語法

![ToggleButtons 樣式](/work-log/flutter_toggle_button/ToggleButtons.png)

3.使用 Hugo 的圖片 shortcode


      Flutter ToggleButtons 元件樣式展示

重要注意事項

1.圖片路徑：在 Hugo 中，assets 資料夾的內容會被處理並放在網站根目錄下，所以路徑是 /work-log/flutter_toggle_button/ToggleButtons.png

2.圖片優化：Hugo 會自動處理圖片優化，但你可以透過 shortcode 參數來控制大小和品質

3.響應式設計：使用

shortcode 可以確保圖片在不同裝置上都能正確顯示

在部落格中設置文章資訊與tag

Tue, 09 Sep 2025 00:00:00 +0000

使用YAML格式撰寫以下資訊放在文章開頭，title部分取代＃大標題

1---
2title: "Flutter 可以使用的 ToggleButton 樣式" #設訂文章標題後不需再使用#大標題
3date: 2025-09-09
4draft: false #是否設為草稿
5tags: ["Markdown", "blog心得",]
6---

Hugo + Bear Cub 主題設定完整教學

Fri, 22 Aug 2025 20:41:50 +0800

Hugo + 主題設定完整教學

這篇文章記錄了我從零開始建立 Hugo 部落格並安裝 Bear Cub 主題的完整過程，包含常見的設定問題和解決方案。

為什麼選擇 Hugo ？

特點：Go 語言寫的，速度極快

優點

生成速度最快（

單一 binary → 不需要安裝 Node/Ruby 環境，跨平台好用

主題多

部署方便（build → 靜態檔 → push）

缺點

需要本地 build，再 push 結果到 GitHub Pages（不像 Jekyll 原生）

模板語法（Go Template）對新手稍有難度

Plugin 擴展性不如 Node.js 生態

基本安裝與設定

1. 初始化 Hugo 專案

1# 在現有的 GitHub 專案中初始化 Hugo
2hugo new site . --force

2. 安裝 Bear Cub 主題

1# 使用 git submodule 安裝（推薦）
2git submodule add https://github.com/clente/hugo-bearcub.git themes/hugo-bearcub

3. 基本設定檔案 (hugo.toml)

 1# 基本設定
 2baseURL = 'https://你的用戶名.github.io/blog'
 3theme = 'hugo-bearcub'
 4copyright = '你的名字 (CC BY 4.0)'
 5defaultContentLanguage = 'zh-tw'
 6
 7# 產生 robots.txt 以利於 SEO
 8enableRobotsTXT = true
 9
10# 設定語法高亮
11[markup]
12  [markup.highlight]
13    lineNos = true
14    lineNumbersInTable = false
15    noClasses = false
16  [markup.goldmark]
17    [markup.goldmark.renderer]
18      unsafe = true
19
20# 多語言模式設定
21[languages]
22  [languages.zh-tw]
23    title = '我的部落格'
24    languageName = 'zh-TW 🇹🇼'
25    LanguageCode = 'zh-TW'
26    contentDir = 'content'
27    [languages.zh-tw.params]
28      madeWith = '使用 [Bear Cub](https://github.com/clente/hugo-bearcub) 製作'
29
30[params]
31  # 網站描述
32  description = '我的個人部落格，分享技術與生活'
33  
34  # 網站標題
35  title = '我的部落格'
36  
37  # 日期格式
38  dateFormat = '2006-01-02'
39  
40  # 主題樣式 (original 或 herman)
41  themeStyle = 'original'
42  
43  # 自動產生社群媒體卡片
44  generateSocialCard = true
45  
46  # 作者資訊
47  [params.author]
48    name = '你的名字'
49    email = 'your.email@example.com'

首頁內容自訂

建立首頁內容檔案

在 content/_index.md 建立檔案：

 1---
 2title: "首頁"
 3---
 4
 5# 歡迎來到我的個人部落格
 6
 7嗨！我是 **你的名字**，歡迎來到我的數位天地。
 8
 9## 關於這個部落格
10
11這裡是我分享想法、學習心得和生活點滴的地方。你可以在這裡找到：
12
13- **技術文章**：程式開發經驗分享
14- **學習筆記**：新技術的學習過程
15- **專案記錄**：有趣的專案開發歷程
16- **生活感悟**：日常生活的思考與體驗
17
18## 最新文章
19
20歡迎查看我的[最新文章](/posts/)，或者透過[標籤](/tags/)來瀏覽特定主題的內容。
21
22## 聯絡我
23
24如果你想要與我交流或合作，歡迎透過以下方式聯絡：
25
26- Email: your.email@example.com
27- 有任何問題或建議，也歡迎在文章下方留言
28
29---
30
31*感謝你的造訪，希望這些內容對你有所幫助！*

建立文章

快速建立新文章

1# 建立新文章
2hugo new content posts/文章標題.md

文章格式範例

 1---
 2title: "文章標題"
 3date: 2025-08-22T20:41:50+08:00
 4draft: false
 5description: "文章描述，用於 SEO 和社群分享"
 6tags: ["標籤1", "標籤2"]
 7---
 8
 9文章內容寫在這裡...
10
11## 小節標題
12
13- 列表項目
14- 另一個項目
15
16### 程式碼範例
17\`\`\`bash
18echo "Hello Hugo!"
19\`\`\`

文章摘要與繼續閱讀設定

摘要顯示功能

為了避免文章列表頁面顯示完整內容，我們可以設定文章摘要功能，讓列表只顯示文章摘要並提供「繼續閱讀」按鈕。

1. 自動摘要設定

在 hugo.toml 中設定摘要長度：

1# 摘要設定
2summaryLength = 200  # 摘要字數限制

說明

當文章沒有手動設定摘要時，Hugo 會自動截取前 200 個字元
對於中文內容，200 個字元大約是 100-150 個中文字
對於英文內容，200 個字元大約是 30-40 個英文單詞

2. 手動摘要設定

方法一：使用標記

在文章中插入來精確控制摘要位置：

 1---
 2title: "文章標題"
 3date: 2025-01-XX
 4tags: ["標籤1", "標籤2"]
 5---
 6
 7這是文章的開頭部分，會顯示在列表中。
 8
 9這裡是更多內容...
10
11
12
13這裡是文章的其餘部分，只會在單篇文章頁面中顯示。

方法二：使用 `description` 參數

在文章的 front matter 中設定 description：

1---
2title: "文章標題"
3date: 2025-01-XX
4description: "這是文章的摘要，會顯示在列表中"
5tags: ["標籤1", "標籤2"]
6---
7
8文章內容...

3. 摘要優先順序

Hugo 的摘要顯示優先順序：

標記 - 最高優先級
description 參數 - 第二優先級
自動截取 - 使用 summaryLength 設定

4. 列表頁面樣式

設定完成後，文章列表會以卡片式設計顯示：

文章標題：可點擊進入完整文章
發布日期：顯示在標題旁邊
文章摘要：只顯示摘要內容
繼續閱讀按鈕：當文章被截斷時顯示
標籤：顯示文章相關標籤

GitHub Actions 自動部署

設定工作流程

在 .github/workflows/hugo.yml 建立自動部署設定：

 1name: Deploy Hugo site to GitHub Pages
 2
 3on:
 4  push:
 5    branches: ["main"]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13jobs:
14  deploy:
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v4
18        with:
19          submodules: recursive
20      
21      - name: Setup Hugo
22        uses: peaceiris/actions-hugo@v2
23        with:
24          hugo-version: 'latest'
25          
26      - name: Build
27        run: hugo --minify
28        
29      - name: Deploy to GitHub Pages
30        uses: peaceiris/actions-gh-pages@v3
31        with:
32          github_token: ${{ secrets.GITHUB_TOKEN }}
33          publish_dir: ./public

常見問題與解決方案

社群媒體預覽卡片顯示亂碼問題

當你在 Discord、Facebook 等社群媒體分享文章時，如果預覽卡片中的中文顯示為問號（？），這是因為預設字型不支援中文字符。

問題表現

分享連結時，預覽卡片的標題顯示為問號
作者名稱顯示為 map[name:作者名稱] 而不是純文字

解決方案

1. 建立客製化的社群媒體卡片檔案

首先，在你的專案根目錄建立目錄並複製檔案：

1# 建立 layouts/partials 目錄
2mkdir -p layouts/partials
3
4# 複製主題的 social_card.html 到你的專案中
5cp themes/hugo-bearcub/layouts/partials/social_card.html layouts/partials/

2. 修改字型設定

編輯 layouts/partials/social_card.html 檔案（注意這是你專案中的檔案，不是主題檔案）：

1
2{{ $font := resources.GetRemote "https://github.com/adobe-fonts/source-han-sans/raw/release/OTF/TraditionalChinese/SourceHanSansTC-Bold.otf" }}

3. 修正作者名稱顯示

在同一個檔案中，找到第 27 行並修改：

1
2{{ $author := (default $.Site.Params.author.name ($.Param "author") ) }}
3
4
5{{ $author := (or ($.Param "author") $.Site.Params.author.name) }}

重要說明：我們將檔案複製到專案的 layouts/partials/ 目錄而不是直接修改主題檔案，這樣做的好處是：

保持主題的 git submodule 乾淨

未來更新主題時不會遺失客製化設定

Hugo 會優先使用專案中的檔案覆蓋主題檔案

4. 確保社群媒體卡片功能開啟

在 hugo.toml 中確認設定：

1[params]
2  # 自動產生社群媒體卡片
3  generateSocialCard = true

字型選擇說明

Source Han Sans TC：Adobe 思源黑體繁體中文版本，支援完整中文字符集
替代方案：也可以使用 Google 的 Noto Sans CJK 字型
檔案大小：中文字型檔案較大，但現代瀏覽器會快取字型檔案

修改完成後，重新建立並部署網站，社群媒體預覽就會正確顯示中文內容了。

實用技巧與其他設定

本地開發

1# 啟動開發伺服器
2hugo server
3
4# 包含草稿
5hugo server --buildDrafts
6
7# 指定 IP 和 Port
8hugo server --bind 0.0.0.0 --port 1313

不同電腦上的工作流程

主要開發電腦

安裝 Hugo 進行完整開發
可以本地預覽和測試

其他電腦/緊急更新

只需要 Git 和文字編輯器
直接編輯 Markdown 檔案推送即可
GitHub Actions 會自動編譯和部署

常見檔案位置

設定檔：hugo.toml
首頁內容：content/_index.md
文章：content/posts/
主題：themes/hugo-bearcub/
靜態檔案：static/

總結

透過這個設定流程，我們成功建立了：

快速載入的靜態部落格
支援繁體中文的介面
自動化的 GitHub Pages 部署

現在你可以專注於寫作，讓 Hugo 和 GitHub Actions 處理其他的技術細節！

這篇教學記錄了我的實際設定過程，希望對其他想要建立 Hugo 部落格的朋友有所幫助。

文章列表 on Tarragon

驗證導向的 CLI 工具文章：官方 docs 查核放過的落差類型

官方文件查核放過的五類落差

1. 旗標改名

2. 設定鍵 migrate

3. 隱含 schema prefix

4. 平台特定 segfault

5. Driver 差異

共通模式

相關連結

Migration Playbook 方法論的演化紀錄：Stage 0 variant 規劃把 collapse 率從 60% 降到 0%

為什麼 migration playbook 需要自己的方法論

第一輪 batch（5 篇）：Type A-E 浮現 + cadence collapse 3/5

Cadence collapse：前 3 篇被動寫作全部同質化

Type A-E 怎麼浮現

第二輪 batch（5 篇）：漏類驗證 + 多軸 High 實證

驗證成立的 4 項預測

浮現的 3 項新議題

第三輪 batch（5 篇）：Type F dogfood + 候選軸驗證

累積 evidence

三輪對照：方法論的演化軌跡

Self-aware limitation

相關連結

Vendor 深度技術文章方法論的演化紀錄：同 vendor 系列的開場輪替驗證

背景

第一輪 batch（5 篇）：跨 vendor、5 種 entry framing

6 段 framework 成立但章節名可變

Cadence collapse 0% — 主動 variant 有效

Reviewer 單人足夠

第二輪 batch（5 篇）：同 vendor sub-tool 系列、最高 collapse 風險

跨兩輪對照

方法論演化小結

相關連結

Case-First + Agent Team Review：教學內容的生產流程

這篇要說什麼

問題：LLM 自生內容的兩個盲點

階段 1：完整閱讀案例庫、抽 findings

為什麼要完整閱讀、不能只看 title + description

邊際遞減的判斷

Findings 抽取方法

Case 類型的承接策略

階段 2：基於 findings 建立內容

Findings 分布到章節

Stage 2 寫作前先定 SSoT 對應

避免硬塞模板

情境敘事的判讀條件

案例引用的準確性

階段 3：Agent team 平行多輪審查

為什麼要 agent team、不能交給單一 reviewer

三個維度 reviewer 分工

Reviewer A：寫作規範審查（AGENTS.md 核心原則）

Reviewer B：案例引用準確性

Reviewer C：跨章一致性

平行 background 跑、不佔主 context

Reviewer issue 數量的 baseline

為何要多輪 review、不是一次到位

修正循環的執行原則

階段 5：Polish pass（04/05 模組後新增）

Polish pass 的觸發條件

Polish pass 不該做的事

Polish pass 的標準工序

Polish pass 的實作成本

自掃描盲點更新

適用情境跟限制

適用情境

不適用情境

Standard-driven 取代 case-driven（07 LLM 章節驗證）

限制

7 個模組驗證後的反覆陷阱

陷阱 1：Skeleton case 擴寫成 case 事實

陷阱 2：Frame 重複展開（SSoT 不清）

陷阱 3：負向陳述 + 模板化（規範系統性失分）

陷阱 4：Rich case 判讀層被當 case fact 引用（04/05 模組新發現）

陷阱 5：自掃描盲點累積（04/05/06 模組持續顯現）

陷阱 6：Case 引用段首取代核心概念句（06 模組新發現）

陷阱 7：Medium case 實作層擴寫過頭（06 模組新發現）

陷阱 8：跨 case 合成 frame 升級成 case 揭露（07 模組新發現）

陷阱 9：Case 引用句構同質化（07 模組新發現）

「章節已有 routing skeleton」的特殊處理（07 模組新發現）

衍生 insight：reviewer 維度沒覆蓋的部分