本章以 scripts/mdtools（blog 自己的 markdown 工具鏈，repo 內檔案）作為 concrete instance。讀者不需要事先熟悉 mdtools — 每段會先講通用 pattern，再用對應 code 示範一種可行實作。

基礎：為什麼需要 flag.NewFlagSet 而非 flag.Parse()

flag.Parse() 只解析一次全域 flag set。對只有一個命令的小工具（如 tool --input foo）夠用；但一旦進入 tool fmt --fix 這種 <tool> <subcommand> [flags] 結構，全域 flag set 就擋路：

• --fix 對 fmt 命令有意義，對 lint 命令沒有。
• 各子命令可能共享 name（例如 --verbose）但預設值或語意不同。
• help 輸出需要分子命令各自列自己的 flags。

flag.NewFlagSet 讓每個子命令擁有獨立的 flag 命名空間：

1fs := flag.NewFlagSet("fmt", flag.ExitOnError)
2fix := fs.Bool("fix", false, "apply fixes in place")
3check := fs.Bool("check", false, "report-only")
4_ = fs.Parse(args) // args = os.Args[2:]，已經跳過了子命令本身

fs.Parse(args) 只看傳進去的片段，不碰 os.Args 全域。這是撐起 subcommand CLI 的核心 API。

專案 Layout：main → cmd/ → internal/

Go 慣例的 CLI 專案結構是三層，對應三種責任：

 1scripts/mdtools/
 2├── main.go             ← 層 1：dispatcher，只做「看第一個參數分派到哪裡」
 3├── cmd/
 4│   ├── fmt.go          ← 層 2：每個子命令一個檔案，負責 flag 解析與呼叫 internal
 5│   ├── lint.go
 6│   ├── cards.go
 7│   └── migrate.go
 8└── internal/
 9    ├── mdfmt/          ← 層 3：純邏輯，不碰 flag、os.Args、os.Exit
10    ├── mdlint/
11    └── mdcards/

分層的目的是支援每層獨立的測試策略：

• layer 1：幾乎不測，因為只是 switch。
• layer 2：integration test（給定 argv、確認 exit code 與 stdout）。
• layer 3：unit test，純函式輸入輸出。後續模組的所有實作技術 — AST 整合、idempotent 改寫、graph 分析 — 都落在這層。

把 os.Exit / os.Args / os.Stderr 都擋在 layer 1-2，layer 3 就能用一般 table-driven test 測，不用起 subprocess。

Layer 1：main.go dispatcher

 1// scripts/mdtools/main.go
 2package main
 3
 4import (
 5	"fmt"
 6	"os"
 7
 8	"blog/scripts/mdtools/cmd"
 9)
10
11func main() {
12	if len(os.Args) < 2 {
13		usage()
14		os.Exit(2)
15	}
16
17	sub := os.Args[1]
18	args := os.Args[2:]
19
20	var exitCode int
21	switch sub {
22	case "fmt":
23		exitCode = cmd.Fmt(args)
24	case "lint":
25		exitCode = cmd.Lint(args)
26	case "cards":
27		exitCode = cmd.Cards(args)
28	case "migrate":
29		exitCode = cmd.Migrate(args)
30	case "-h", "--help", "help":
31		usage()
32	case "version":
33		fmt.Println("mdtools 0.1.0-dev")
34	default:
35		fmt.Fprintf(os.Stderr, "unknown subcommand: %q\n\n", sub)
36		usage()
37		exitCode = 2
38	}
39
40	os.Exit(exitCode)
41}

注意幾個 pattern：

• dispatcher 不做 flag 解析。args := os.Args[2:] 把剩下交給子命令。
• 每個子命令回傳 int，dispatcher 統一呼叫 os.Exit。這讓子命令本身容易測（不會直接 kill 測試 process）。
• -h / --help / help 三種寫法都接受。Unix 慣例。
• unknown subcommand 進 exit code 2，保留 exit 1 給「有違規」的語義。

Layer 2：子命令入口

每個子命令一個檔案，結構類似：

 1// scripts/mdtools/cmd/fmt.go
 2package cmd
 3
 4import (
 5	"flag"
 6	"fmt"
 7	"os"
 8
 9	"blog/scripts/mdtools/internal/files"
10	"blog/scripts/mdtools/internal/mdfmt"
11	"blog/scripts/mdtools/internal/rules"
12)
13
14func Fmt(args []string) int {
15	fs := flag.NewFlagSet("fmt", flag.ExitOnError)
16	fix := fs.Bool("fix", false, "apply fixes in place")
17	check := fs.Bool("check", false, "report-only; non-zero on pending changes")
18	_ = fs.Parse(args)
19
20	if *check && *fix {
21		fmt.Fprintln(os.Stderr, "mdtools fmt: --fix and --check are mutually exclusive")
22		return 2
23	}
24	if !*check && !*fix {
25		*check = true // safe default
26	}
27
28	paths := fs.Args()
29	if len(paths) == 0 {
30		paths = []string{"content"}
31	}
32
33	cfg := rules.Default()
34	mdFiles, err := files.WalkMarkdown(paths)
35	if err != nil {
36		fmt.Fprintf(os.Stderr, "mdtools fmt: walk error: %v\n", err)
37		return 2
38	}
39
40	changed := 0
41	for _, path := range mdFiles {
42		result, err := mdfmt.FormatFile(path, cfg)
43		if err != nil {
44			fmt.Fprintf(os.Stderr, "mdtools fmt: %s: %v\n", path, err)
45			return 2
46		}
47		if !result.Changed() {
48			continue
49		}
50		changed++
51		if *fix {
52			if err := os.WriteFile(path, result.Fixed, 0o644); err != nil {
53				fmt.Fprintf(os.Stderr, "write %s: %v\n", path, err)
54				return 2
55			}
56			fmt.Printf("fixed: %s\n", path)
57		} else {
58			fmt.Printf("would fix: %s\n", path)
59		}
60	}
61
62	if *check && changed > 0 {
63		return 1 // CI-friendly: exit 1 means "things need fixing"
64	}
65	return 0
66}

要注意幾個設計決策：

• flag 定義就在入口函式裡，不抽成 package 常數。每個子命令的 flag 獨立演化。
• ExitOnError 讓 fs.Parse 遇到不合法 flag 直接 exit — 對 CLI 工具 OK，因為 parse 失敗本來就無法繼續。測試時要用 ContinueOnError 避免殺測試。
• positional args 從 fs.Args() 取，不是 os.Args。fs.Parse 會把非 flag 的留在 fs.Args()。
• 預設值走安全側（*check = true when neither given）— 防止使用者意外執行破壞性動作。
• exit code 分層語意：0 = 成功、1 = 有違規、2 = 工具本身失敗。CI script 能用 [[ $? -eq 1 ]] 區分。

Layer 3：internal 實作

Layer 3 是純邏輯，不知道任何 os / flag 的存在。這讓它能被 layer 2 呼叫、被 test 呼叫、也能在未來被其他 binary 或 library 重用：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2package mdfmt
 3
 4import (
 5	"bytes"
 6	"os"
 7
 8	"blog/scripts/mdtools/internal/rules"
 9)
10
11type FixResult struct {
12	Path     string
13	Original []byte
14	Fixed    []byte
15}
16
17func (r FixResult) Changed() bool {
18	return !bytes.Equal(r.Original, r.Fixed)
19}
20
21func FormatFile(path string, cfg rules.Config) (FixResult, error) {
22	data, err := os.ReadFile(path)
23	if err != nil {
24		return FixResult{}, err
25	}
26	fixed := applyAll(data, cfg)
27	return FixResult{Path: path, Original: data, Fixed: fixed}, nil
28}

FormatFile 回傳 (FixResult, error)，不 os.Exit、不印訊息、不碰全域狀態。Test 可以直接給一個記憶體 []byte 跑 applyAll 驗結果。

什麼時候該上 cobra

升級到 cobra 的判準是stdlib 能處理的負面複雜度已經超過 cobra 的學習成本。下表列五個實際觸發過團隊升級的訊號，每個都附展開說明。

命令層級超過 3 層：kubectl get pods 只有兩層還撐得住；到 gh api repos owner/repo/pulls list --limit 10 就是四層（含 api 這個 namespace），dispatcher 裡巢狀 switch 開始難讀。信號：dispatcher 的 switch case 超過十個，或 case 裡面又呼叫另一個 switch。反例：即使只有兩層，若每層未來會繼續加，早上 cobra 可省後來重構。

需要自動 shell completion：end-user 會反覆打命令、需要 tab 補齊子命令與 flag 名稱時，這功能差很多。手寫 completion 腳本要處理三種 shell 的語法差異，成本高；cobra 一行 cobra.GenBashCompletion 就產生。信號：工具有外部使用者、或團隊已經裝 shell completion。反例：只在 CI 跑、人不會互動輸入。

man-page 形式的 help 輸出：Unix 社群期待工具有 man tool 級的文件。stdlib 只輸出簡單的 usage 字串，排版樸素；cobra 的 doc package 能生成 markdown / reStructuredText / man。信號：工具要 package 進系統（Homebrew、apt），或對外發佈。反例：公司內部用、README 夠用。

多 end-user 讀 help：工程師忍受樸素的 -h 輸出，但產品經理、SRE on-call 看不下。cobra 有明確的 long description、example 欄位，排版比 stdlib 好。信號：使用者包含非程式設計角色。反例：user 是同團隊工程師。

大量共用 flag：--verbose、--log-level、--config 這類 flag 每個子命令都要用。stdlib 要在每個子命令重複 fs.Bool("verbose", ...)；cobra 的 PersistentFlags 能繼承到所有 subcommand。信號：重複 flag 超過三個、或要 enforce 某個 flag 在所有 subcommand 都有。反例：flag 在每個子命令語意不同，共用反而製造混淆。

以上五個訊號在 mdtools 都沒命中（內部工具、單層 subcommand、工程師使用者），所以繼續走 stdlib。若未來 mdtools 對外釋出給讀者下載，就值得重新評估。判讀時機是設計當下，不是感覺「stdlib 開始髒」時 — 髒時通常已經晚。

常見陷阱

在 layer 3 直接呼叫 os.Exit

會破壞 test：test runner 呼叫 TestXxx 時，如果 subject code 裡 os.Exit(1)，整個 test process 退出，其他 test 不跑。Layer 3 應回傳 error，讓 layer 2 決定怎麼退出。

用全域 var fs = flag.NewFlagSet(...) 宣告 flag

每次呼叫會累積狀態（flag 已經被定義過會 panic），並且兩個 test 同時跑會 race。定義 flag 要在函式裡。

忘記 ContinueOnError 就跑 test

ExitOnError 是 production 預設，但測試時會讓測試 process 整個退出。Table-driven test 要用：

1fs := flag.NewFlagSet(name, flag.ContinueOnError)
2fs.SetOutput(io.Discard) // 測試時不要印 usage 到 stderr

太早抽出「所有子命令共用的 flag」

PersistentFlags 概念在 stdlib 沒有，手動在每個子命令重複 fs.Bool("verbose", false, ...) 看似重複但其實可讀。一旦抽成共用 helper，就開始維護一個小框架 — 這時候用 cobra 反而更乾淨。

擴充路徑

• 命令太多時分組：tool fmt check、tool fmt fix 的兩層 subcommand 可以用「每層一個 switch」展開，main → cmd.Fmt → cmd.FmtCheck。mdtools 的 migrate fix-links 就是這個模式（見 cmd/migrate.go）。
• 共用 config loading：rules.Default() 這類邏輯放在 internal 裡，每個子命令呼叫；不要每個子命令自己 parse 配置檔。
• 測試 layer 2：用 buffer 捕獲 stdout/stderr，傳入自定 args。參考 Go stdlib 的 testing/iotest 跟 bytes.Buffer。

下一步

9.2 goldmark AST 入門 會看 mdtools 怎麼把 markdown 解析成可操作的結構，layer 3 內部怎麼組織 parser 整合。

本章目標

學完本章後，你將能夠：

1. 看懂 go.mod 的三個核心欄位
2. 理解 module path 與 import path 的關係
3. 知道為什麼 Go 指令要在 module 根目錄執行
4. 分辨標準庫與第三方依賴

【觀察】go.mod 定義 module

go.mod 的核心用途是宣告目前 module 的身份、Go 版本與外部依賴。一個 Go 專案通常會在 module 根目錄放 go.mod：

1module example.com/notify-service
2
3go 1.25.1
4
5require (
6    github.com/gorilla/websocket v1.5.3
7)

這份檔案表達三件事：module 名稱、Go 語言版本、外部依賴。

【判讀】module 是 Go 編譯與依賴解析的單位

module 的核心規則是：Go 工具鏈以 go.mod 所在目錄作為依賴解析與 package 掃描的根。Go 工具鏈需要知道「目前這批程式碼」的根在哪裡；go.mod 就是這個根。

當你在 module 根目錄執行：

1go test ./...

./... 的意思是測試目前 module 底下所有 package。實務上要先找到 go.mod 所在目錄，再從那裡執行 Go 指令。

【策略】先分辨三種 import

閱讀 import 的核心規則是：先分辨能力來源，再決定去哪裡查。讀 Go 檔案時，先把 import 分成三類：

這個分類會告訴你：問題應該去查標準庫文件、第三方套件文件，還是目前 module 的其他目錄。

【執行】用 module 模型閱讀 main.go

閱讀入口程式 import 的核心方法是：先把 import 依來源分群，再判斷程式依賴哪些能力。main.go 的 import 可以整理成這樣：

 1import (
 2    "context"
 3    "fmt"
 4    "log/slog"
 5    "net/http"
 6    "os"
 7    "time"
 8
 9    "example.com/notify-service/messages"
10)

前面是標準庫，最後一個是專案內部 package。這表示入口程式主要依賴 Go 標準庫，只有日誌訊息常數被拆到內部 messages package。

Go 的慣例是封一層薄 wrapper — 不讓呼叫端直接看到第三方 API 的完整型別空間，保留未來換 parser 的彈性。加上 Go 的 AST 節點通常區分 block 跟 inline 兩種型別（對應到 CommonMark spec），走訪時需要配合型別判讀，以免呼叫到只存在於 block 節點的 method（Lines() 就是典型例子，對 inline 節點呼叫會 panic）。

本章以 scripts/mdtools/internal/astutil 跟 internal/mdcards/graph.go 為 concrete instance 示範整合流程。更廣泛的 AST 概念背景在 什麼是 AST；本章聚焦 Go 層面的整合 pattern。

為什麼選 goldmark

Markdown parser 在 Go 有多個選項。選 goldmark 的理由：

• Hugo 內建用它 — 同一個 parser 解析，lint 結果跟 render 結果一定一致。其他 parser 可能判讀差異導致「lint 過了但 Hugo render 壞」的長尾 bug。
• 完整 CommonMark 支援 + GFM 擴充。table、strikethrough、task list 都在。
• AST 節點設計貼近 CommonMark spec：心智負擔小，節點型別直接對應 spec 用語。
• 純 Go、零 CGO、穩定。build 不會踩奇怪的 C 依賴。

類似選擇邏輯可套用到其他格式：Go 原始碼用 go/parser，YAML 用 gopkg.in/yaml.v3，protobuf 用 google.golang.org/protobuf/encoding/prototext。

最小整合：parse 一份 markdown

 1// scripts/mdtools/internal/astutil/parser.go
 2package astutil
 3
 4import (
 5	"github.com/yuin/goldmark"
 6	"github.com/yuin/goldmark/ast"
 7	"github.com/yuin/goldmark/extension"
 8	"github.com/yuin/goldmark/parser"
 9	"github.com/yuin/goldmark/text"
10)
11
12type Parser struct {
13	md goldmark.Markdown
14}
15
16func NewParser() *Parser {
17	md := goldmark.New(
18		goldmark.WithExtensions(
19			extension.GFM, // Table, Strikethrough, Linkify, TaskList
20		),
21	)
22	return &Parser{md: md}
23}
24
25func (p *Parser) Parse(src []byte) ast.Node {
26	reader := text.NewReader(src)
27	return p.md.Parser().Parse(reader, parser.WithContext(parser.NewContext()))
28}

為什麼包一層 Parser 而不是直接呼叫 goldmark.New(...).Parser().Parse(...)：

• 第三方 API 面積大，工具只需要其中一部分。封裝讓呼叫端看不到 goldmark.Markdown、parser.NewContext 這些細節。
• 未來換 parser 成本低：如果有天換 mistune-for-go 或自寫 parser，呼叫端的 astutil.NewParser().Parse(src) 不用改。
• 測試替身容易：unit test 可以 mock Parser interface。

三個 struct / package / extension 配置的預設值：

• Extensions：extension.GFM 涵蓋 blog 需要的全部；只啟用實際用到的 extension 讓 parser 行為可預測。
• Context：每次 Parse 都建新 context — goldmark context 儲存 parse 狀態，不能跨 parse 共用。

AST 節點階層：Block 跟 Inline 的分野

goldmark 的 AST 節點有兩大類，型別系統直接區分：

1// goldmark/ast/ast.go
2type NodeType int
3const (
4	TypeDocument NodeType = iota
5	TypeBlock
6	TypeInline
7)

Block 節點：段落、heading、list、table、blockquote、fenced code block — 在來源檔案中占據完整的行。這類節點帶有 source line segments，能用 n.Lines() 取得起訖位置。

Inline 節點：link、emphasis、text、code span、image — 存在於 block 節點內部。Inline 節點沒有獨立的 line segments；它們的位置由父 block 管理。

這個區分有個實戰後果。第一次寫 AST 走訪的人經常這樣寫：

1// WRONG: 對 inline 節點呼叫 Lines() 會 panic
2ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
3	link, ok := n.(*ast.Link) // Link 是 inline
4	if !ok {
5		return ast.WalkContinue, nil
6	}
7	segs := link.Lines() // panic: "can not call with inline nodes"
8	...
9})

Link 節點沒有 Lines()。正確做法是走上去找最近的 block 節點：

 1// scripts/mdtools/internal/mdcards/graph.go
 2func nodeLine(n ast.Node, src []byte) int {
 3	for p := n; p != nil; p = p.Parent() {
 4		if p.Type() != ast.TypeBlock {
 5			continue
 6		}
 7		segs := p.Lines()
 8		if segs != nil && segs.Len() > 0 {
 9			return lineNumber(src, segs.At(0).Start)
10		}
11	}
12	return 0
13}

這個 walk-up-to-block 模式在每個會操作 inline 節點的工具裡都會出現。初學者的第一個 goldmark panic 幾乎必然是這個。

ast.Walk visitor 模式

goldmark 用標準 visitor pattern 走 AST：

1ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
2	// entering == true：進入節點（DFS 下行）
3	// entering == false：離開節點（DFS 回溯）
4	return ast.WalkContinue, nil
5})

Walk status 三個常見值：

• ast.WalkContinue — 繼續深度優先走訪。
• ast.WalkSkipChildren — 跳過子樹，繼續走同層。適合當「處理完整個 Paragraph 就不用再進去找子 Link」。
• ast.WalkStop — 整個走訪中止。適合「找到第一個就結束」。

實戰中幾乎只處理 entering == true 的情境 — DFS 下行足以覆蓋多數規則。entering == false 的 post-order 位置保留給需要聚合子樹資訊的場景（例如計算子樹裡的 link 數量）。

實戰：抽出所有 Link 節點並計算位置

mdtools cards 要找所有相對連結。這是一個完整的 ast.Walk 應用：

 1// scripts/mdtools/internal/mdcards/graph.go
 2func (g *Graph) extractEdges(fn FileNode) {
 3	ast.Walk(fn.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
 4		if !entering {
 5			return ast.WalkContinue, nil
 6		}
 7		link, ok := n.(*ast.Link)
 8		if !ok {
 9			return ast.WalkContinue, nil
10		}
11		dest := string(link.Destination)
12		if isExternalOrAnchor(dest) {
13			return ast.WalkContinue, nil
14		}
15		target := resolveTarget(fn.Path, dest)
16		if target == "" {
17			return ast.WalkContinue, nil
18		}
19		g.Edges = append(g.Edges, Edge{
20			SourcePath:  fn.Path,
21			SourceLine:  nodeLine(n, fn.Src),
22			Destination: dest,
23			Target:      target,
24			DisplayText: string(link.Text(fn.Src)),
25		})
26		return ast.WalkContinue, nil
27	})
28}

關鍵操作：

• Type assertion 提前 filter：link, ok := n.(*ast.Link)。不是 Link 就直接 continue，不做無用工。
• 判讀早退：isExternalOrAnchor(dest) 先過濾 http:// 與 #anchor 這類不屬於 graph 的邊。
• 對 inline 節點取行號走 walk-up（上節講的 nodeLine）。
• text 要透過 link.Text(fn.Src) 取 — inline 節點的文字儲存為 source 的 byte segment，不是 string。link.Text() 需要帶 src 才能反推。

Byte offset 定位到行號

goldmark 的 source segment 用 byte offset 標註起訖。要轉成 1-based line number：

 1// scripts/mdtools/internal/mdcards/graph.go
 2func lineNumber(src []byte, offset int) int {
 3	if offset < 0 || offset > len(src) {
 4		return 0
 5	}
 6	line := 1
 7	for i := 0; i < offset && i < len(src); i++ {
 8		if src[i] == '\n' {
 9			line++
10		}
11	}
12	return line
13}

O(offset) scan。對 300-檔 / 每檔 500 行的 blog repo 夠快；若是幾千萬行的 codebase 才需要預建 line-offset table。

text.Segment 跟 byte slice 的對應

每個 block 節點的 Lines() 回傳 *text.Segments，裡面是多個 text.Segment{Start, Stop int}：

1// 取段落第一行的原始 byte 內容
2segs := paragraph.Lines()
3firstSeg := segs.At(0)
4lineBytes := src[firstSeg.Start:firstSeg.Stop]

這個 API 讓你能回頭看原始 source，而不是透過 AST 重新渲染。對 lint 工具（要報告精確位置、甚至 rewrite）很重要。

常見陷阱

對 inline 節點呼叫 Lines()

已經講過，補一句：不只 Link，還有 Text、CodeSpan、Emphasis、Image — 凡是 n.Type() == ast.TypeInline 都不能 Lines()。寫 rule 時永遠用 nodeLine helper。

忘記 GFM extension，Table 節點會少

預設 goldmark.New() 沒開 GFM。content 裡的表格會被當成普通段落 parse，ast.Walk 根本找不到 *extension.ast.Table 節點。永遠在 goldmark.WithExtensions(extension.GFM)。

用 string(src) 當作可變字串操作

goldmark 預期 src 在 Parse 過程中 保持不變。若要改動，應先讀 src、parse、收集位置、產生新 byte slice；以不可變輸入 + 新輸出替代 in-place mutation。

ast.Walk 忘記回傳 continue

1ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
2	if someCondition {
3		processNode(n)
4		// 忘記 return，編譯失敗；但加 return 0 會提前終止
5	}
6	return ast.WalkContinue, nil
7})

預設要回 ast.WalkContinue, nil。早退用 ast.WalkSkipChildren 或 ast.WalkStop，別用 bare return。

擴充路徑

• 解析自己的 Go 原始碼：改用 go/parser + go/ast。語法樹更複雜（型別、scope、import），但 visitor pattern 本質一樣。參考 gopls 或 stringer 的原始碼。
• 寫自訂 extension：goldmark 允許註冊 parse-time 與 render-time 的 extension（自己的 block / inline 語法、或接管某個節點的 render 行為）。但除非你的 markdown 有特殊語法（Hugo shortcode 之類），大多數工具不用走這層。
• AST 快照比對測試：用 go-cmp 比對 ast.Walk 抓出的節點序列；新版 goldmark 升級時能快速發現相容性問題。

下一步

9.3 AST 驅動的 idempotent 文字改寫 會接著看怎麼從「讀 AST」走到「改原檔案」— 這是 mdtools fmt --fix 的核心。

壓測工具選型的核心不是「哪個工具最強」、是「哪個工具最貼合本團隊的 workload model 表達能力跟 CI 整合需求」。沒有絕對最好的工具、只有最匹配當前場景的工具。

跟 9.2 Workload Modeling 的關係：9.2 定義 workload 長什麼樣、9.3 找能複製這個樣子的工具。工具選對、壓測結果可信；工具選錯、壓測結果誤導。

本章不是工具教學、是 選型維度 + 主流工具的 適用情境。讀者讀完後能回答「我現在這個 workload 該用哪個工具」、而不是「哪個工具最快」。

六個選型維度

選工具時要按六個維度評估、不能只看「能不能跑 HTTP GET」。

腳本表達能力：能不能寫複雜 user journey（登入 → 瀏覽 → 加購物車 → 結帳）、不只是單一 HTTP request。複雜系統的壓測通常是 user journey 級別、單一 endpoint 壓測只能找絕對極限、找不到 cross-endpoint contention。

協議支援：HTTP / WebSocket / gRPC / TCP / 自家二進位協議。WebSocket 跟 gRPC 是現代後端常見、傳統工具（JMeter、wrk）可能要 plugin 補。

規模能力：單機可以發多少 RPS、能不能分散式擴容。本機 wrk 可發 10K-50K RPS；分散式 Locust 可發 1M+ RPS。決定因素：CPU 效率、async I/O 模型、是否單機 bound。

CI 整合：能不能在 PR 上跑 lightweight perf check、結果能不能機器可讀（JSON / Prometheus exposition）、能不能跟 baseline diff。沒有 CI 整合的工具只能做「事件型壓測」、無法做 continuous perf governance。

結果分析：原生 dashboard（k6 Cloud、Gatling Enterprise）/ Prometheus + Grafana 整合 / 純文字輸出。要看結果分發、團隊成員能不能輕鬆查詢歷史。

學習曲線：腳本語言（JavaScript / Scala / Python / Go）、團隊熟悉度。工具好但團隊不會用、會變成 1-2 個工程師的孤島技能、流失時整套廢掉。

主流開源工具對照

k6 是過去 5 年崛起的綜合首選。JavaScript 腳本（前端工程師也能寫）、原生 dashboard、Prometheus exposition、CI 友善。Grafana 收購後生態加速。缺點：複雜 stateful 場景（DB connection pool 共享）需要繞 workaround。

JMeter 是企業常見的 incumbent。協議支援廣（含 LDAP、JDBC、JMS）、有 GUI 編輯器。缺點：腳本是 XML、版本控制困難；GUI 主要用來生成腳本、實際跑壓測還是要 headless。已經在用的團隊建議繼續、新團隊不必特意選它。

Gatling 高 throughput 純 async、性能優秀、報表精美。缺點：Scala / Kotlin DSL 學習曲線陡、新版本（11+）改了 DSL 不向後相容。

Locust 是 Python 生態的選擇、特別適合複雜業務邏輯（用 Python 寫 user journey 自然）。分散式部署原生支援。缺點：Python 單線程 throughput 受限、要靠分散式擴容。

Vegeta 跟 wrk 是「quick check」工具、用於單一 endpoint 的極限測試。不適合複雜場景、適合 saturation discovery 第一輪「找這個服務的天花板」。

Production traffic replay 工具

當需要複製 真實 production traffic 的壓測場景時、需要另一類工具。

GoReplay 是最常用的開源 traffic replay 工具。在 production server 上 tcpdump-based 捕獲 HTTP traffic、可以 store 到 file 或 stream 到 staging 環境。優點：開源、無 vendor lock-in；缺點：HTTP only、加密流量要拿到 key 才能用。

Service mesh shadow（Istio / Linkerd mirror）：mesh 層 mirror traffic 到 staging service。優點：mesh 已部署的話 zero infra cost、加密 traffic 也能 mirror。缺點：需要 service mesh 已落地。

AWS VPC Traffic Mirroring：底層網路層 mirror、application 完全無感。優點：最低 invasion；缺點：AWS only、加密 traffic 要另外處理。

Diffy（Twitter / X 開源、已 deprecated 但概念仍有效）：dual-write 同時打到舊 / 新版本、比對結果。適合驗證「新版本是否邏輯正確」、不是純壓測。

對應案例：Tixcraft 10K t2.micro 壓測 — 用分散式 EC2 跑 synthetic load 模擬 100K 同時搶票；SeatGeek Virtual Waiting Room — token 配發邏輯通常用 dual-write 驗證新舊版本一致。

雲端 managed 壓測服務

當不想養 load test infrastructure、想 ad-hoc 跑大規模壓測時、用 managed service。

AWS Distributed Load Testing：CloudFormation 起 Fargate cluster 跑 JMeter 或 Taurus、報表寫到 S3。優點：一鍵部署、Fargate 計費；缺點：JMeter-based、不是現代 k6 風格。

Grafana k6 Cloud：託管 k6、跨地理 distributed 壓測（從多個 region 同時發流量）。優點：地理分散原生、跟 Grafana 整合無縫；缺點：vendor cost。

Azure Load Testing：Azure 原生、整合 Application Insights。優點：Azure 用戶無縫；缺點：相對較新、生態還在補。

GCP 沒有 first-party managed load testing：要靠 Marketplace 方案或自管 Locust on GKE。

工具選型決策樹

落地時的快速決策：

• 想快速驗證單一 API 極限 → wrk / Vegeta
• 想寫複雜 user journey + CI 整合 + JavaScript 團隊 → k6（新項目首選）
• 企業已有 JMeter 流程、不想換 → JMeter（接受 XML / GUI 複雜度）
• 大規模分散式 + Python 生態 → Locust
• 報表給管理層看、Scala 團隊 → Gatling
• 想複製真實 production traffic → GoReplay 或 service mesh shadow
• 想 ad-hoc 雲端大規模壓測 → 對應雲商的 managed load test

常見反模式

• 只測單一 API、不測 user journey：找不到 cross-endpoint contention、找不到 session state 累積
• 壓測機跟被測機在同一網段：網路延遲被低估、p99 比 production 樂觀
• 壓測時 throttle 自己的工具：結果不是被測系統的極限、是工具自己的極限
• 結果報表只看平均：tail latency 看不到、p99 退化被掩蓋
• 壓測環境跟 production hardware 不一致：CPU 型號、network、disk IOPS 差很大、結果不可外推
• 沒驗證 model：跑了壓測但沒對比 production metrics、不知道 model 是否貼近 reality

案例對照

下一步路由

• 上游：9.2 Workload Modeling
• 下游：9.4 Saturation Discovery（用工具找 knee）
• 下游：9.9 Improvement Loop（CI 整合）
• 跨模組：06.1 CI Pipeline（壓測在 CI 的位置）

既建知識卡片

• Load Test
• Workload Model
• Shadow Traffic
• Saturation Point

設計一個冪等的改寫流水線有三個配合層：策略選擇（AST round-trip / byte surgical / 混合）、rule 鏈順序（每條 rule 的輸出要是下一條的合法輸入）、context 重算紀律（行數變動後索引要重建）。本章依序展開這三層，並以 mdtools fmt --fix 的 applyAll 為 concrete instance。

改檔的三種策略

把 AST 資訊轉成檔案修改有三條路：

mdtools 選第三條。純 AST round-trip 在長尾場景（nested fence、特殊 escape）會產出跟 source 不等價的 markdown；純 byte-offset 讓 MD047（trailing newline）這類微瑣事變得囉嗦。混合讓每條 rule 在它最自然的層級解決。

設計原則：能用 line-based 就用，AST 只在真的需要語意判讀時才上。

Rule 鏈的結構

mdtools fmt 的 applyAll 是條流水線：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2func applyAll(data []byte, cfg rules.Config) []byte {
 3	lines := splitLines(data)
 4
 5	// MD026 — 標題結尾標點，line-preserving
 6	if cfg.Headings.ForbidTrailingPunct {
 7		ctx := AnalyzeLines(lines)
 8		lines = FixHeadingTrailingPunct(lines, ctx, cfg.Headings.ForbiddenTrailingPunct)
 9	}
10
11	// MD022 — 標題前後空行，line-count changing
12	if cfg.Headings.RequireBlankLines {
13		ctx := AnalyzeLines(lines)
14		lines = FixHeadingBlankLines(lines, ctx)
15	}
16
17	// MD031 — fenced code block 前後空行
18	if cfg.CodeBlocks.RequireBlankLinesAround {
19		ctx := AnalyzeLines(lines)
20		lines = FixFencedCodeBlankLines(lines, ctx)
21	}
22
23	// MD032 — 列表前後空行
24	ctx := AnalyzeLines(lines)
25	lines = FixListBlankLines(lines, ctx)
26
27	// MD060 — 表格對齊
28	ctx = AnalyzeLines(lines)
29	lines = FixTables(lines, ctx, cfg.Tables)
30
31	// MD034 — 裸 URL 縮短
32	ctx = AnalyzeLines(lines)
33	lines = FixBareURLs(lines, ctx, cfg.URLs)
34
35	out := joinLines(lines)
36	out = EnsureTrailingNewline(out) // MD047
37	return out
38}

幾個設計決策值得拆開看。

順序決定結果

Rule 順序有明確的依賴判準：每條 rule 的輸出應該是下一條 rule 的合法輸入。

• MD026 先跑：它改標題內容、不改行數，後面 rule 的行號不會位移。
• MD022 / MD031 / MD032 緊接著：這些都 insert blank lines，會改行數；但它們彼此之間不衝突（heading ≠ fence ≠ list）。
• MD060 表格對齊在 URL 縮短之前：讓表格先成為可解析結構，URL rule 才能正確判斷「這個 URL 在表格 cell 內」。
• MD034 URL 縮短最後：URL 變短會讓表格欄寬變化；但因為 MD060 已經做過對齊，後續工具會再跑一次 fmt –fix 重新對齊。這個「跑兩次才穩定」的特性是可接受的，因為 fmt –fix 本來就冪等。
• MD047 trailing newline 在 byte 層做，最後一步。

每條 rule 重新 analyze context

AnalyzeLines(lines) 在每個會變行數的 rule 之前重跑。為什麼：

• 上一條 rule 可能把 fence 或 front matter 位置推後。
• Context 裡的 Skip[]、FenceOpen[]、FenceClose[] 都是按行索引儲存。
• 行數改變 → 索引失效 → 必須重算。

成本是 O(N)，對 500-行檔案微秒級。在整體 pipeline 中可忽略。

Line-based rule 本體範例

以 MD022（標題前後空行）為例：

 1// scripts/mdtools/internal/mdfmt/rules.go
 2func FixHeadingBlankLines(lines []string, ctx LineContext) []string {
 3	if len(lines) == 0 {
 4		return lines
 5	}
 6	out := make([]string, 0, len(lines)+8)
 7	for i, line := range lines {
 8		isHdr := !ctx.Skip[i] && isHeadingLine(line)
 9
10		if isHdr && len(out) > 0 && !isBlank(out[len(out)-1]) {
11			out = append(out, "")
12		}
13		out = append(out, line)
14		if isHdr && i+1 < len(lines) && !isBlank(lines[i+1]) {
15			out = append(out, "")
16		}
17	}
18	return out
19}

關鍵 idempotent 技巧：

• 判斷「上一行不是 blank 就插」而非「永遠插」。已經插過 blank 的情況下，第二次跑會看到 blank，跳過，結果相同。
• out 是新 slice，不改動原 lines。函式純粹。
• look-ahead 看原 lines，避免剛插的 blank 讓邏輯誤判下一輪。

AST-guided rule 範例：MD034 URL 縮短

這條 rule 用 AST 找「哪些 text 是 link 之外的」，行內用 regex + mask 處理：

 1// scripts/mdtools/internal/mdfmt/urls.go
 2func rewriteBareURLsInLine(line string, cfg rules.URLRules, idPatterns []*regexp.Regexp) string {
 3	masked := collectMaskedRanges(line) // [...](/go/09-tooling-and-analysis/ast-idempotent-rewriting/...) / <...> / `...` 的位置
 4	matches := bareURLRe.FindAllStringIndex(line, -1)
 5	if len(matches) == 0 {
 6		return line
 7	}
 8	var b strings.Builder
 9	cursor := 0
10	for _, m := range matches {
11		start, end := m[0], m[1]
12		end = trimURLTrailPunct(line, start, end)
13		b.WriteString(line[cursor:start])
14		if inMasked(masked, start) {
15			b.WriteString(line[start:end]) // 已在 link / code span / 角括號內
16		} else {
17			rawURL := line[start:end]
18			display := shortenURL(rawURL, cfg, idPatterns)
19			fmt.Fprintf(&b, "[%s](/go/09-tooling-and-analysis/ast-idempotent-rewriting/%s)", display, rawURL)
20		}
21		cursor = end
22	}
23	b.WriteString(line[cursor:])
24	return b.String()
25}

這裡的 混合精神：

• AST 不直接改檔，只提供「這行的哪些 byte 範圍是 existing link / code span」的判讀（實際上這段用了 regex 模擬；真正嚴謹時會改用 AST 定位）。
• 真的改寫走字串層級，保留原格式。
• 已在 link 內的 URL 不再包第二層 — inMasked 檢查防止 double-wrap，這也是 idempotent 關鍵：第二次跑，所有 URL 都已經在 masked range 裡，跳過。

--check 跟 --fix 共用邏輯

一個常見反 pattern 是：check 模式重寫一次邏輯「看會不會改」，fix 模式真的改。兩套邏輯一旦漂移，誤報或漏報就出現。

正確做法是共用同一個 FormatFile，然後比對結果：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2func FormatFile(path string, cfg rules.Config) (FixResult, error) {
 3	data, err := os.ReadFile(path)
 4	if err != nil {
 5		return FixResult{}, err
 6	}
 7	fixed := applyAll(data, cfg)
 8	return FixResult{Path: path, Original: data, Fixed: fixed}, nil
 9}
10
11// check / fix 都呼叫 FormatFile，只差在怎麼處理結果
12func (r FixResult) Changed() bool {
13	return !bytes.Equal(r.Original, r.Fixed)
14}

子命令層處理差異：

 1// cmd/fmt.go 簡化版
 2result, _ := mdfmt.FormatFile(path, cfg)
 3if !result.Changed() {
 4	return // 沒改動，跳過
 5}
 6if *fix {
 7	os.WriteFile(path, result.Fixed, 0o644)
 8} else {
 9	fmt.Printf("would fix: %s\n", path)
10}

check 跟 fix 跑一模一樣的 rule chain，只是其中一個寫檔、另一個回報。這個結構讓兩個模式的行為保證一致。

Idempotent 的驗證方式

工具宣稱冪等，測試要驗證：

 1func TestFormatIdempotent(t *testing.T) {
 2	inputs, _ := filepath.Glob("testdata/*.md")
 3	cfg := rules.Default()
 4	for _, in := range inputs {
 5		data, _ := os.ReadFile(in)
 6		once := applyAll(data, cfg)
 7		twice := applyAll(once, cfg)
 8		if !bytes.Equal(once, twice) {
 9			t.Errorf("%s: not idempotent (applied twice != once)", in)
10		}
11	}
12}

生產環境的 pre-commit hook 本質上每次 commit 都在驗證冪等：

1. 作者寫 commit → fmt --fix 跑過 → re-stage
2. 如果邏輯不冪等，下次作者改同檔案，可能又會被改回/改去
3. 使用者很快會發現「為什麼這個工具一直來回改我的檔案」

冪等是 pre-commit 的信譽基礎。

常見陷阱

Rule 之間互相抵消

1Rule A: 移除行尾空白
2Rule B: 把每個 heading 後面補空格到 60 欄

A 跟 B 串起來會永遠改來改去。寫 rule 時要想「其他 rule 會對我的輸出做什麼」。

讀 src 跟改 src 用不同的 byte slice

在迴圈中一邊掃 data、一邊 append 到 out，中間忘了切換視角。建議永遠遵循 (原 lines, 新 out) 兩個名字，迴圈體只 look-back 到 out[len(out)-1] 或 look-ahead 到 lines[i+1]，絕不在同一時段既讀又寫同一 slice。

Trailing newline 的邊界

1bytes.TrimRight(data, "\r\n")      // 去掉全部
2return append(data, '\n')           // 加一個

空檔案要特別處理 — 加了 \n 就變非空。mdtools 的作法是：

1if len(data) == 0 {
2	return data
3}

空檔保持空。

Regex-based URL 偵測的邊界

Go 的 RE2 沒有 lookbehind，無法用 regex 直接寫「URL 不在 ]( 後面」。解法是先掃 mask（link span、angle bracket、code span），再跑 URL regex，match 結果對照 mask 決定是否替換。collectMaskedRanges 就是這個模式。

擴充路徑

• Rule dry-run diff：把每條 rule 單獨跑一遍，輸出每條 rule 改了哪幾個檔案。debug 為什麼某檔案被改時用得到。
• Configurable rule disabling：把 rule 開關改成 front matter 級別（mdtools-disable: MD026），讓個別檔案能 opt-out。
• Rule 可程式化插入：把 applyAll 改成「讀 config → 產生 rule list → iterate」，讓新 rule 不用改 fixer.go 而是註冊進來。

下一步

9.4 跨檔案圖分析 離開 single-file 世界，看 mdtools cards 怎麼建整個 repo 的 link graph 跑反向查詢。

這類分析的典型觸發點是需求已經離開 single-file 層：orphan 偵測（某個檔案是否被引用）、backlink 完整性（連結目標是否存在）、dependency cycle 檢測（import graph 是否有環）、unused export 偵測（某個 symbol 是否被使用）。每個都是圖論問題，需要先把 repo 結構化，單檔 walker 看不見跨檔 edge。本章以 mdtools cards（L1 連結有效性、L2 orphan 卡片、L4 卡片 K4 合規）作為 concrete instance。

為什麼要預先建圖而非每次 lint 都現查

直覺會說：對每個 link，直接 os.Stat(target) 看存在不存在，就能驗證 L1。

這個做法在 100 個檔案、每檔 10 個 link 時 OK — 1000 次 stat、每次 < 1ms，總計 1 秒內。但一旦要做 L2 「每張卡片至少被一篇正文引用」，問題就變成：

1for each card file C:
2  for each other file F:
3    parse F
4    for each link L in F:
5      if L points to C: mark C as referenced

N² parse，每次 parse 又走 AST。1000 檔 × 1000 檔 = 100 萬次 parse，每次 50ms，總計 14 小時。

解法是 parse 一次、存下所有 edge、在圖上查。Parse 是 O(N) 一次；所有後續 query 都在 in-memory map 上做，microseconds。

Graph 的資料結構

 1// scripts/mdtools/internal/mdcards/graph.go
 2type Edge struct {
 3	SourcePath  string // 包含連結的檔案
 4	SourceLine  int    // 連結所在行
 5	Destination string // link 目的地（原文）
 6	Target      string // 解析後的檔案路徑（可能不存在）
 7	DisplayText string // 顯示文字（反釣魚用）
 8}
 9
10type FileNode struct {
11	Path string
12	AST  ast.Node
13	Src  []byte
14}
15
16type Graph struct {
17	Files []FileNode  // 所有 .md 檔
18	Edges []Edge      // 所有相對連結
19
20	byPath   map[string]*FileNode // path → FileNode
21	inbound  map[string][]int     // target path → edge indices
22	outbound map[string][]int     // source path → edge indices
23}

設計重點：

• FileNode 保留 AST + src：後面 L4 檢查（卡片首段是否有鄰卡連結）需要重讀 AST，不想再 parse 一次。
• Edge 用 slice 儲存，index 走 map：比起直接用 map[string][]Edge，這個 layout allocation 少、GC 友善，也容易 sort 輸出。
• inbound / outbound 都預先建：L1 靠 outbound，L2 靠 inbound。一次 parse 把兩邊都填好。

Parse pipeline：兩段式確保指標穩定

 1// scripts/mdtools/internal/mdcards/graph.go
 2func BuildGraph(roots []string) (*Graph, error) {
 3	mdFiles, err := files.WalkMarkdown(roots)
 4	if err != nil {
 5		return nil, err
 6	}
 7
 8	parser := astutil.NewParser()
 9	g := &Graph{
10		byPath:   map[string]*FileNode{},
11		inbound:  map[string][]int{},
12		outbound: map[string][]int{},
13	}
14
15	// 第一段：parse 全部檔案，填 g.Files
16	for _, path := range mdFiles {
17		data, err := os.ReadFile(path)
18		if err != nil {
19			return nil, err
20		}
21		doc := parser.Parse(data)
22		node := FileNode{Path: path, AST: doc, Src: data}
23		g.Files = append(g.Files, node)
24		g.byPath[path] = &g.Files[len(g.Files)-1]
25	}
26
27	// 第二段：抽出 edge（此時 g.Files 大小已固定，指標穩定）
28	for _, node := range g.Files {
29		g.extractEdges(node)
30	}
31
32	return g, nil
33}

兩段式的理由：第一段邊 parse 邊 append，slice 可能重新分配 underlying array，之前取的 *FileNode 指標會失效。第一段收斂後才取指標，保證穩定。這是 Go slice 常見的事故。

如果用 []*FileNode（指標 slice）就沒這問題，但對這個情境 []FileNode 空間效率較好。兩種都 OK，選一種就要注意對應的陷阱。

L1：連結有效性（outbound 走訪）

最簡單的 graph query：對每個 edge，檢查 target 是否存在。

 1// scripts/mdtools/internal/mdcards/l1.go
 2func checkL1LinkValidity(g *Graph) []report.Violation {
 3	var out []report.Violation
 4	for _, edge := range g.Edges {
 5		if TargetExists(edge.Target) {
 6			continue
 7		}
 8		out = append(out, report.Violation{
 9			Path:  edge.SourcePath,
10			Line:  edge.SourceLine,
11			Rule:  "L1-broken-link",
12			Level: report.LevelError,
13			Message: fmt.Sprintf(
14				"broken link %q: target not found", edge.Destination,
15			),
16		})
17	}
18	return out
19}

TargetExists 試兩個候選路徑 — {target}.md 跟 {target}/_index.md，因為 Hugo 的 URL routing 對 content page 跟 section page 一視同仁：

1func TargetExists(target string) bool {
2	for _, cand := range []string{target + ".md", filepath.Join(target, "_index.md")} {
3		if info, err := os.Stat(cand); err == nil && !info.IsDir() {
4			return true
5		}
6	}
7	return false
8}

L2：orphan 偵測（inbound 反查）

「每張卡片至少被一篇非卡片文章引用」— 這是反向查詢：對每張卡片，看它的 inbound 有沒有來自「非卡片檔」的 edge。

 1// scripts/mdtools/internal/mdcards/l2.go
 2func checkL2Orphans(g *Graph, cardsRoot string) []report.Violation {
 3	inboundNonCard := map[string]int{}
 4	for _, edge := range g.Edges {
 5		targetMd := edge.Target + ".md"
 6		if !isCardPath(targetMd, cardsRoot) || isSectionIndex(targetMd) {
 7			continue
 8		}
 9		if isCardPath(edge.SourcePath, cardsRoot) {
10			continue // card-to-card 不算
11		}
12		inboundNonCard[targetMd]++
13	}
14
15	var out []report.Violation
16	for _, fn := range g.Files {
17		if !isCardPath(fn.Path, cardsRoot) || isSectionIndex(fn.Path) {
18			continue
19		}
20		if inboundNonCard[fn.Path] > 0 {
21			continue
22		}
23		out = append(out, report.Violation{
24			Path:    fn.Path,
25			Rule:    "L2-orphan-card",
26			Level:   report.LevelWarn,
27			Message: "card has no inbound link from non-card content",
28		})
29	}
30	return out
31}

設計取捨：

• Card-to-card 不算 inbound：依 spec，卡片應被「教學文章」引用證明使用場景；卡片互連只證明概念網路，不證明實用。
• Warn 而非 error：orphan 是內容覆蓋率訊號，不是格式錯誤；新卡片剛建時不該被擋 commit。
• _index.md 排除：section page 不是 card。

L4：AST 跟 Graph 混用

這條規則複雜：「卡片的首段跟『概念位置』section 都要各有至少一個鄰卡連結」。要用 graph 抓候選，再用 AST 精確判讀在哪個 paragraph / section 內。

 1// scripts/mdtools/internal/mdcards/l4.go
 2func checkL4K4Structure(g *Graph, cardsRoot, conceptHeadingTitle string) []report.Violation {
 3	var out []report.Violation
 4	for _, fn := range g.Files {
 5		if !isCardPath(fn.Path, cardsRoot) || isSectionIndex(fn.Path) {
 6			continue
 7		}
 8
 9		firstPara := firstBodyParagraph(fn.AST)
10		if !subtreeHasCardLink(firstPara, fn.Path, cardsRoot) {
11			out = append(out, report.Violation{
12				Path:    fn.Path,
13				Rule:    "L4-first-paragraph-no-card-link",
14				Level:   report.LevelWarn,
15				Message: "opening paragraph should link to an adjacent card",
16			})
17		}
18
19		section := headingSection(fn.AST, conceptHeadingTitle, fn.Src)
20		if len(section) == 0 {
21			out = append(out, report.Violation{
22				Path:    fn.Path,
23				Rule:    "L4-missing-concept-position",
24				Level:   report.LevelWarn,
25				Message: "card missing 概念位置 section",
26			})
27			continue
28		}
29		if !sectionHasCardLink(section, fn.Path, cardsRoot) {
30			out = append(out, report.Violation{...})
31		}
32	}
33	return out
34}

兩個 helper 展示 graph 跟 AST 的交界：

• firstBodyParagraph(doc) 用 AST 走第一個 Paragraph 節點（document 的第一個 top-level child）。
• subtreeHasCardLink(node, sourcePath, cardsRoot) 用 ast.Walk 在該節點下找所有 Link，再用 resolveTarget 判斷是不是指向卡片。

為什麼用 AST 而不是行號範圍：Hugo content 的卡片結構多樣，首段可能跨多行；用 paragraph.Lines() 也能拿到 byte range，但還要處理 list item、table row 這類邊界。直接走 AST 子樹是最穩定的做法。

反向索引的設計擴充：slug-based 啟發式

mdtools migrate fix-links 要處理「broken link 但作者其實想連到某個存在的檔案，只是路徑寫錯」。這需要額外一個 slug 反向索引：

 1// scripts/mdtools/internal/mdmigrate/fixlinks.go
 2func buildSlugIndexes(g *mdcards.Graph) (primary, normalized map[string][]string) {
 3	primary = make(map[string][]string)
 4	normalized = make(map[string][]string)
 5	for _, fn := range g.Files {
 6		base := filepath.Base(fn.Path)
 7		var slug, target string
 8		if base == "_index.md" {
 9			parent := filepath.Dir(fn.Path)
10			slug = filepath.Base(parent)
11			target = parent
12		} else {
13			slug = strings.TrimSuffix(base, ".md")
14			target = strings.TrimSuffix(fn.Path, ".md")
15		}
16		primary[slug] = append(primary[slug], target)
17		if norm := sectionPrefixRe.ReplaceAllString(slug, ""); norm != slug && norm != "" {
18			normalized[norm] = append(normalized[norm], target)
19		}
20	}
21	return primary, normalized
22}

查詢時走多層啟發式：

1. 精確 slug 命中（broker → content/backend/knowledge-cards/broker）
2. 數字前綴 normalized 命中（03-cpython-internals 找不到 → 試 cpython-internals → 命中 04-cpython-internals）
3. 卡片優先（多個 candidate 時選 knowledge-cards/ 下的）
4. 同頂層子目錄優先（source 在 content/go/... 時選 content/go/ 下的 candidate）

這四層啟發式把 143 個 multi-candidate 收斂到 0 個 ambiguous。啟發式的層層疊加是 static analysis 工具常見 pattern — 寫過 linter、LSP、refactoring tool 的人都會在類似的決策樹花時間。

Parse 成本的實務控制

跨檔分析一次要 parse 幾百個檔案。幾個優化：

• 只 parse 一次：Graph 建好後 L1 / L2 / L4 共用。呼叫端不該重建 Graph。
• concurrent parse（選擇性）：mdtools 目前單執行緒 parse ~400 檔案 < 1 秒，沒必要並發。若檔案過萬，用 golang.org/x/sync/errgroup + worker pool fan out。
• 避免記憶體持有：Graph 的 FileNode.Src 跟 AST 都持有 reference。如果 GC 壓力敏感，做完 L1-L4 後顯式 g = nil 或分段釋放。blog 這個規模沒必要。

常見陷阱

Slice append 失效的指標

上面提過 — 邊 append 邊取指標會炸。BuildGraph 的兩段式是標準修法。

filepath.Rel 在 root 外的 panic

1rel, err := filepath.Rel("/foo", "/bar")  // 不會 panic，回傳 "../bar"
2rel, err := filepath.Rel("foo", "../bar") // err != nil

跨 repo root 的 rel 路徑會回 error。graph 的 target resolution 要接住這個 error。

Symlink 的走訪

filepath.WalkDir 預設不跟隨 symlink。這對 blog repo OK（沒 symlink）；但對其他 repo（例如 monorepo 有 symlink 指到 sibling package）要用 filepath.Walk 或自己實作。mdtools 不處理這個情境。

Hugo 的 URL 路由細節

../broker/ 從 content/backend/knowledge-cards/_index.md 出發，Hugo 解析成 content/backend/knowledge-cards/broker（也就是 sibling card 的 URL）。從 content/backend/knowledge-cards/acme-automation.md 出發，同樣的 ../broker/ 卻解析成 content/backend/broker（錯誤，broker 不在 backend 直屬）。這是因為 Hugo 把內容頁 URL dir 當成「slug 的 URL 資料夾」，不是「檔案所在的資料夾」。做 target resolution 時要注意這一點，參考 resolveTarget() 的實作。

擴充路徑

• Ingest commit history：把 git commit 的時序資訊加進 graph，抓「這張卡片連結了一個之前存在但被刪掉的檔案」。需要整合 go-git。
• Parallel parse：大型 monorepo 的 lint 可用 worker pool 並行 parse。用 channel 把 parse 結果丟回 main，注意 goldmark context 不跨 goroutine。
• Graph visualization：把 graph 輸出成 Graphviz DOT 或 Mermaid，給作者看「這張卡片的 backlinks 是什麼」。有助於規劃內容修訂。

下一步

9.5 工具決策的 tripwire 跳出實作，看「什麼時候該從 regex 升級到 AST、什麼時候該從 Python 換到 Go」的決策方法。

9.1–9.4 講了怎麼寫 Go 工具。這一章退一步，看什麼時候該寫這個工具、什麼時候該升級既有工具。決策錯了，寫得多好都沒用。本章介紹 tripwire 決策法、WRAP 框架在技術決策的套用、以及用 blog 工具鏈選型作為 concrete instance。

為什麼需要 tripwire

「什麼時候升級」本身是決策。如果不做預設，會發生兩件事：

太早升級：每次問「該不該升」的時候都說「升吧反正不會錯」。結果工具複雜度爆炸，維護成本拖慢產品開發。

太晚升級：每次都說「regex 再撐一下就好」。結果工具的誤判累積，作者開始手動 override、skip lint、加例外，工具信譽破產。

Tripwire 是事前約定：「當以下條件之一命中，就重新評估是否升級」。這把「該不該升」從臨時直覺變成有根據的再評估。

這個概念在 Chip 與 Dan Heath 的《Decisive》裡有詳細討論 — tripwire 的要點是用事前的明確條件，取代事後的模糊直覺。

WRAP 框架套用到工具決策

WRAP = Widen options / Reality-test / Attain distance / Prepare to be wrong。對應到技術決策：

Widen options：不要只在「Go 還是 Python」之間選。多選項至少要有：

• 現有工具撐著（regex + shell）
• 半自動化（Python + regex，50 行腳本）
• 自訂工具（Python / Go + 適當 parser）
• 買服務（買現成 linter SaaS）
• 不解決（接受這個問題）

Reality-test：用數字跟樣本驗證假設。「regex 夠用」是假設，數字可能說「每 100 個 match 裡 15 個誤判」。

Attain distance：退一步看，如果這個工具三年後可能被捨棄，現在投入多少才合理。

Prepare to be wrong：先設 tripwire，萬一決策錯了也能及時 pivot，不會沉沒到底。

blog 的工具鏈決策用這個框架跑過一次，結論是 Go + goldmark。過程紀錄在 mdtools 設計，這裡只提煉可複用的決策 pattern。

三個實戰 tripwire

以下三組 tripwire 對多數內部工具都適用。遇到其中一個命中時，該花一小時重新評估現有工具是否夠用。

Tripwire 1：從 shell one-liner 升級到腳本

訊號：

• 同樣的 shell 指令在三個以上地方重複貼過
• 指令超過 3 個 pipe 或巢狀 subshell
• 指令的行為要根據環境（CI vs local）分支

升級方向：寫成 20-50 行 Python 或 Bash script，放進 scripts/。

反例：每次寫新 shell 命令都起腳本檔。常用的一行 grep 不需要變 script。

Tripwire 2：從 regex 升級到 parser / AST

訊號：

• Regex 需要「上下文判斷」（這個 match 在 code block 內嗎？在 HTML tag 內嗎？）
• 規則要處理嵌套結構（表格內的 link、code block 內的 heading）
• 誤報率超過 1% 或每週出現
• 新規則要知道「父節點」「子節點」（MD024 siblings_only 就是這類）
• 跨檔案的 graph 需求出現（backlink 分析、broken link 偵測）

升級方向：引入該格式的官方 parser（markdown → goldmark；YAML → gopkg.in/yaml.v3；Go → go/parser）。

反例：簡單的「每行開頭是 # 就當 heading」這類規則，regex 永遠夠用。不要為了「學 AST」硬上。

Tripwire 3：從腳本語言升級到 Go

訊號：

• 需要 parse 有官方 Go 實作的格式（goldmark、go/ast、protobuf 等）
• 需要跨平台分發單一 binary
• Python / Node 的啟動時間在 pre-commit 的 accumulated cost 已感
• 要整合到 Go 生態系（產生 Go 程式碼、讀 Go 原始碼）
• 團隊主要語言是 Go，Python 腳本的維護者變成單一瓶頸

升級方向：Go。

反例：臨時的資料轉換、一次性的 data migration、快速 prototyping — Python 永遠比 Go 快動筆。

實戰紀錄：blog 的三層升級

blog 的 markdown 品質工具鏈在一個 session 內走完三層升級。把這個時間線攤開當案例。

Layer 0：沒工具，靠 markdownlint IDE extension

狀況：IDE 裝 markdownlint extension，作者寫稿時看到 yellow underline 手動改。

出現什麼 tripwire：內容規模長大後，reviewer 收到 PR 發現 20 個 MD026 違規，手動改成 cognitive burden。更糟的是紅隊教材有平行結構（13 個案例各有 ### 弱點環節），被 MD024 誤判為重複，作者開始 ignore 警告。

升級驅動：Tripwire 2 命中（規則需要父標題上下文，siblings_only 規則 IDE 沒有）。決策：升級到自訂工具。

Layer 1 候選：Python + regex

狀況：50 行 Python 腳本，逐行 match。

為什麼沒選：兩個跨檔需求已經浮現 — 卡片雙向完整性、L1 link 驗證。這是 graph 需求，regex 做不到 (Tripwire 2 的後半段命中)。加上 blog 本身用 Hugo（Go 寫的，markdown 由 goldmark parse），用 Python 的 markdown parser 會有 render 跟 lint 判讀不一致的長尾風險。

這個評估花了約 15 分鐘，記錄在決策文件裡 — 重點是評估本身有 artefact 可追溯。

Layer 2：Go + goldmark

狀況：選 Go，因為 (a) goldmark 是 Hugo 的 parser，lint 結果跟 render 必然一致；(b) 跨檔 graph 分析用 Go struct 乾淨；(c) 單一 binary 方便接 pre-commit hook 跟 CI，不用擔心 Python 環境。

如何驗證決策正確：看三個月後的狀態 — 工具有沒有被 bypass？新規則加起來順不順？CI 有沒有反覆失敗？作者有沒有開始覺得工具阻礙產出？這些訊號都沒出現，表示決策有效。若有出現，就是 Tripwire 3 的反向觸發（「該降級回 Python」或「該拆成多個專門工具」），又要重新評估。

延遲決策的具體成本

常見反論：「不急，等真的需要再升」。問題是延遲本身有成本：

• Technical debt 複利：regex 工具越長越大，每條新 rule 都變難，最後要重寫時要一次 migration 所有 rule。
• 誤報侵蝕信譽：使用者每週看到工具報錯、檢查後發現是誤判，開始忽略工具。信譽一旦壞，再好的工具也沒用。
• Option value 流失：跨檔分析、graph 視覺化、CI 整合這些 downstream feature 都要在 AST 基礎上才能做；延遲升級等於延遲 feature 路徑。
• 機會成本複利：每週花 30 分鐘手動改 lint 誤判，一年累積 26 小時 — 比升級工具的 8 小時多 3 倍。

時間視角變長，升級的 NPV 幾乎永遠正。延遲不是零成本的預設，是要主動合理化的選擇。

為什麼 blog 不走「先 Python 再 Go」的雙階段

有個常見建議：「先用 Python 快速做出雛形，驗證概念後再用 Go 重寫」。這個建議對不確定需求的情境有效（「我們不知道要什麼工具」），對已知需求的情境是浪費。

blog 的狀況是已知：

• 要 markdown lint + 跨檔 graph + pre-commit + CI — 四個需求都很明確
• 目標語言（Go）已經確定（Hugo 生態、單一 binary 需求）
• 第三方 parser 選擇（goldmark）已經是最優解

在這些條件下，寫 Python 原型的唯一價值是「學 AST 概念」。但同樣學習也能直接用 Go + goldmark 完成。花兩倍時間寫兩遍只為了「先驗證」，邏輯不成立。

判準：需求越明確、目標語言越確定，雙階段越浪費；需求越模糊、選型還在評估，雙階段越值得。

決策的副作用：artefact

不管最終選什麼，決策過程本身要留下 artefact。blog 案例裡的 artefact：

• mdtools 設計紀錄：為什麼是 Go、為什麼是 goldmark、tripwire 怎麼設的
• 什麼是 AST：AST vs regex 的概念說明
• markdown 寫作規範：工具要滿足的契約

三個文件加起來約 900 行，寫作時間不到半天。

為什麼留 artefact 比決策本身更重要：

• 半年後同樣問題再浮現時，不會重跑一遍評估
• 新加入的協作者能快速跟上決策脈絡
• Tripwire 條件寫下來才能被驗證（「三個月後有沒有命中？」）
• 反面證據出現時（例如發現 goldmark 有 bug），有清楚的位置記錄 revised decision

沒 artefact 的決策基本上等於沒做過。決策是動作，artefact 才是沉澱。

常見陷阱

把 tripwire 設太低

「每週誤判一次就升級」實務上等於「每週升級」。Tripwire 要設在真的造成信譽或產出瓶頸的位置。

把 tripwire 設太高

「等到 50% 誤判才升級」就太晚了 — 信譽早就垮了。合理範圍是 1-5% 誤判，或每週一次以上。

用 tripwire 取代日常 review

Tripwire 是「提醒重新評估」，不是「自動升級」。命中時要花時間評估，可能發現「還不該升，因為還有 X 原因」。Tripwire 是重新思考的觸發，不是自動化決策。

忽視已命中的 tripwire

「這個誤判已經出現第四週了，但我還是覺得先不要升」— 這是在告訴自己原本的 tripwire 設錯了，不是在等更好的時機。重新評估 tripwire 本身，不是 ignore。

擴充路徑

• Decision log 範本：把團隊的決策過程寫成 template，讓下次不用從零開始
• Post-mortem of decisions：決策後三個月回頭看，把「當時怎麼想」跟「現在怎麼看」對照
• Pre-mortem 技巧：決策前假設「三個月後這決定被推翻，最可能的原因是什麼」，當成補充 tripwire

下一步

9.6 pre-commit hook 與 CI 整合 回到工程落地，看工具怎麼從 binary 變成 commit 與 CI 流程裡的執行體。

工具一旦從 CLI 進入 hook / CI，就有幾個容易出狀況的邊界：哪些 check 該放 hook（快、本地可執行）、哪些該放 CI（慢、需要乾淨環境）、hook 改了檔怎麼 re-stage、–no-verify 的邊界怎麼約定、CI strict mode 跟 local dev 的差異怎麼處理。本章展開這些問題，並以 .githooks/pre-commit + .github/workflows/md-check.yml 作為 concrete instance。

Pre-commit hook 能做什麼、不該做什麼

能做：

• 讀 staged 檔案，跑 lint / fmt
• 自動修正格式違規、git add re-stage
• 擋下 lint error 的 commit
• 跑跨檔分析（cards）
• 執行 build（確保程式碼能編譯）

不該做：

• 執行完整 test suite（太慢，交給 CI）
• 執行 e2e 或需要網路的操作（脆弱，commit 不該依賴外部）
• 修改未 stage 的檔案（會造成 working tree 混亂）
• 執行超過幾秒的任務（心流殺手）

原則：pre-commit 是快速守門員，不是完整驗證器。該做的 checks 要在秒級完成；更慢的驗證交給 CI。

Makefile 作為 hook 與 CI 的共同介面

有個常被忽略的 pattern：hook 跟 CI 都透過 Makefile 呼叫工具，不直接呼叫 binary。這讓三方共用同一套指令。

 1# Makefile
 2MDTOOLS_SRC := $(shell find scripts/mdtools -type f -name '*.go' 2>/dev/null)
 3MDTOOLS_MOD := scripts/mdtools/go.mod scripts/mdtools/go.sum
 4MDTOOLS_BIN := bin/mdtools
 5
 6.PHONY: build check fix lint cards install-hooks
 7
 8build: $(MDTOOLS_BIN)
 9
10$(MDTOOLS_BIN): $(MDTOOLS_SRC) $(MDTOOLS_MOD)
11	@mkdir -p bin
12	@cd scripts/mdtools && go build -o ../../$(MDTOOLS_BIN) .
13
14check: build
15	@./$(MDTOOLS_BIN) fmt --check content/
16	@./$(MDTOOLS_BIN) lint content/
17	@./$(MDTOOLS_BIN) cards content/
18
19install-hooks:
20	@git config core.hooksPath .githooks

這樣：

• 開發者本機：make check 手動驗一次
• Pre-commit：hook 呼叫 ./bin/mdtools ...（或透過 Makefile target）
• CI：workflow 跑 make check
• 所有人看到的失敗訊息格式一致

Make 的依賴 timestamp 機制也剛好解決「binary 什麼時候重 build」— MDTOOLS_BIN 依賴 MDTOOLS_SRC，source 新於 binary 才重 build。

Pre-commit hook 實作

 1#!/usr/bin/env bash
 2# .githooks/pre-commit
 3set -euo pipefail
 4
 5MDTOOLS_BIN="bin/mdtools"
 6REPO_ROOT="$(git rev-parse --show-toplevel)"
 7cd "$REPO_ROOT"
 8
 9# 沒 staged .md 快速退出
10staged_md=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.md$' || true)
11if [[ -z "$staged_md" ]]; then
12    exit 0
13fi
14
15# Rebuild if source newer than binary
16if [[ ! -x "$MDTOOLS_BIN" ]] || [[ -n "$(find scripts/mdtools -type f -name '*.go' -newer "$MDTOOLS_BIN" 2>/dev/null || true)" ]]; then
17    echo "[pre-commit] rebuilding mdtools..."
18    (cd scripts/mdtools && go build -o "$REPO_ROOT/$MDTOOLS_BIN" .) || {
19        echo "[pre-commit] mdtools build failed" >&2
20        exit 1
21    }
22fi
23
24# fmt --fix on staged，re-stage 變動的檔案
25echo "[pre-commit] mdtools fmt --fix"
26while IFS= read -r f; do
27    [[ -z "$f" ]] && continue
28    before=$(git hash-object "$f")
29    "$MDTOOLS_BIN" fmt --fix "$f" >/dev/null
30    after=$(git hash-object "$f")
31    if [[ "$before" != "$after" ]]; then
32        git add "$f"
33    fi
34done <<< "$staged_md"
35
36# lint on staged (擋錯)
37echo "[pre-commit] mdtools lint"
38"$MDTOOLS_BIN" lint $staged_md || exit 1
39
40# cards on full content (擋錯)
41echo "[pre-commit] mdtools cards"
42"$MDTOOLS_BIN" cards content/ || exit 1
43
44exit 0

幾個關鍵 pattern：

Fast exit when no markdown staged

沒 md 改動時 hook 在 10ms 內退出。Go 工程師改 .go 檔時不會被 markdown hook 擋。這是使用者體驗的生死線。

git diff --cached --diff-filter=ACMR

• A (added), C (copied), M (modified), R (renamed) — 該檢查的變動類型
• 排除 D (deleted) — 刪除的檔案不用 lint

git hash-object 偵測實際變動

1before=$(git hash-object "$f")
2./bin/mdtools fmt --fix "$f"
3after=$(git hash-object "$f")
4[[ "$before" != "$after" ]] && git add "$f"

只在檔案內容實際改變時 re-stage。如果 fmt --fix 跑完沒改東西（檔案已經 compliant），不觸發多餘 git add。

避免用 stat 或 mtime — 那些會誤判（file touched 但內容相同）。

分層 exit code

• Fast exit (exit 0)：沒事要做
• Lint error (exit 1)：違規，擋 commit
• Build failure (exit 1)：工具壞了，擋 commit（比讓人用壞工具好）

Git 看 non-zero 就會阻止 commit，訊息會印到 terminal，作者能看到原因。

CI workflow

CI 跑得比 hook 更嚴格：

 1# .github/workflows/md-check.yml
 2name: md-check
 3
 4on:
 5  push:
 6    branches: [main]
 7  pull_request:
 8    branches: [main]
 9
10jobs:
11  md-check:
12    runs-on: ubuntu-latest
13    steps:
14      - uses: actions/checkout@v4
15      - uses: actions/setup-go@v5
16        with:
17          go-version-file: scripts/mdtools/go.mod
18          cache-dependency-path: scripts/mdtools/go.sum
19      - name: Build mdtools
20        run: |
21          mkdir -p bin
22          (cd scripts/mdtools && go build -o ../../bin/mdtools .)
23      - name: fmt --check
24        run: ./bin/mdtools fmt --check content/
25      - name: lint
26        run: ./bin/mdtools lint content/
27      - name: cards
28        run: ./bin/mdtools cards content/

設計決策：

go-version-file: scripts/mdtools/go.mod

讓 CI 從 go.mod 讀取 Go 版本。go.mod 裡寫 go 1.25.1，CI 自動用匹配的版本；本機升 Go 時 workflow 跟著同步。

CI 用 --check 而非 --fix

CI 的角色是偵測，修復留給本機。--check 發現問題就 fail，讓作者在本機修完再 push。若 CI 自動 --fix 然後 commit，會造成「CI 偷改作者 PR」的混亂。

不寫 try-catch 吞錯

CI 步驟失敗就 fail — 不要寫 continue-on-error: true 藏錯誤。早期接工具時覺得「讓 CI 通過先」很誘人，但藏錯誤等於工具沒生效。寧可 CI 紅，也要誠實。

安裝 hook 的 UX

.githooks/pre-commit 放進 repo，但 git 預設看 .git/hooks/，不會自動啟用。要跑：

1git config core.hooksPath .githooks

包成 Makefile target：

1install-hooks:
2	@git config core.hooksPath .githooks
3	@echo "hooks installed"

README 或 CONTRIBUTING.md 要寫「新 clone 時執行 make install-hooks」。這是一次性動作，但必要。

考慮過的替代方案：

• 放 .git/hooks/pre-commit — 不能 commit 進 repo，每個 clone 都要重設
• 用 husky / pre-commit 等工具 — 增加依賴，值得與否看團隊
• 用 direnv .envrc 自動設定 — 依賴 direnv，非標準

最乾淨是 Makefile target + 明確的 onboarding 步驟。

不能繞過的邊界

Pre-commit hook 可以用 --no-verify 跳過。規範要明寫：

寫作時遇到 pre-commit 報錯：讀錯誤訊息並修正，不可用 --no-verify 繞過 hook。

這是社會規範而非技術強制 — 技術上 git 一定允許 --no-verify。但只要規範明列、有人做 code review 抓到違規，就足夠維持紀律。

有個 nuance：緊急情況真的需要 --no-verify 怎麼辦？例如在服務中斷時要緊急 commit 修復。規範要留這個緊急閥門，但搭配：

• 事後必須補 commit 把違規修掉
• --no-verify 的使用要 log 或在 PR 描述標註

大多數 repo 一年可能用不到兩次。關鍵是預設是不繞過，而不是「看情況」。

常見陷阱

Hook 執行時間爆炸

常見在 cards 這類需要 parse 全 repo 的 check。對 400 檔 < 1 秒可接受；對 10000 檔就要評估。降級手段：

• cards 只跑受影響的子圖（根據 staged 檔案 inferrence）
• 複雜 check 搬到 CI
• 本機加 cache（invalidate on file mtime）

Binary 不 commit 進 repo，但 CI 失敗

.gitignore 排除 bin/，所以 CI checkout 時沒有 binary。要記得在 CI 加 build step（上面 workflow 的 Build mdtools step）。

fmt –fix 後 commit 有兩個版本

若 hook 的 fmt --fix 改了檔但 re-stage 失敗（例如 permission 問題），作者以為 commit 成功但實際 commit 的是舊版本。每次 staged 版本跟 working tree 都要同步 — git hash-object 比對能早期發現不一致。

Hook 不能跨平台

macOS / Linux 的 bash hook 在 Windows（未裝 WSL 或 Git Bash）可能不執行。如果 contributor 有 Windows，把 hook 寫成 Go 程式（例如 bin/mdtools hook pre-commit），讓 Go 本身處理跨平台。

擴充路徑

• Hook 只跑 staged 子圖：根據 staged files 推算需要 parse 的 repo subset，降低 hook 延遲。
• CI artifact 留 report：把 lint / cards 的報告 upload 成 GitHub Actions artifact，讓 PR 評論能連結到完整報告。
• Pre-push hook 做更重檢查：把 full test suite 放 pre-push（本機 push 前跑），更頻繁的 pre-commit 只做格式與 lint。

模組總結

走完九個章節，回到出發點：Go 除了寫後端服務，還能寫內部工具 / 靜態分析 / CLI / 程式碼生成。跟後端服務的差異在於生命週期、I/O 模式、錯誤處理慣例，但共用的 Go 技能（型別、interface、package、error）完全可遷移。

本模組介紹的技術 — stdlib flag、goldmark AST、idempotent rewriting、graph analysis、tripwire 決策、pre-commit 整合 — 適用範圍不只 markdown 工具。寫 linter、codegen、migration tool、build tool、dev helper 都是這些技術的組合。

下一步：動手把 scripts/mdtools clone 出來，加一條自己的 rule 進去。真正讀懂一個工具的方式是改它一次。

預計補充內容

這些工具使用邊界會在下列章節展開：

• Go 入門：從入口程式看應用啟動流程：先看 go run 與 go build 如何對應入口 package，才能理解 Go 專案真正的執行起點。
• Go 入門：testing 基礎：先建立最小回歸檢查的習慣，再談 go test ./... 在流程中的角色。
• Backend：可靠性驗證流程：CI 與自動化驗證的責任在這裡展開，不應塞進語言章節。
• Backend：部署平台與網路入口：容器建置、發布門檻與平台合約屬於部署層，不是 toolchain 本身。

與 Backend 教材的分工

本章只處理 Go toolchain。CI pipeline、container build、部署前 gate 與 release artifact 會放在 Backend：可靠性驗證流程 與 Backend：部署平台與網路入口。

和 Go 教材的關係

這一章承接的是入口流程、測試與設定讀取；如果你要先回看語言教材，可以讀：

• Go：從入口程式看應用啟動流程
• Go：testing 基礎
• Go：flag、os/env 與設定邊界
• Go：composition root 與依賴組裝

業界大量這類 Go 程式：hugo（靜態網站產生器）、kubectl / helm（k8s 客戶端）、terraform（基礎設施描述）、gh（GitHub CLI）、goldmark（markdown parser）、stringer / gopls（官方工具鏈）、golangci-lint（linter 集合）。後端工程師轉過去寫工具時會遇到不同的設計約束：沒有長時執行、資料來自檔案而非 request、錯誤處理偏向中斷而非降級、效能瓶頸是 I/O 而非併發。

本模組以 scripts/mdtools（blog 本身用來守住 markdown 品質的內部工具鏈）作為 worked example 串連概念。每一章提煉可複用的 Go 技術；mdtools 只是其中一種 concrete instance，讀者能把同樣 pattern 套到自己的工具上。

章節列表

本模組的教學主軸

• stdlib 優先：Go 的工具鏈文化偏好最小依賴。cobra / viper / 各種框架都有存在的理由，但 Go 的 flag + os + filepath 已經能撐起 80% 的 CLI 需求。
• AST 是原始 regex 的升級路徑，不是預設起點：line-based 處理便宜、直觀；AST 在需要「段落歸屬」「父子關係」「跨檔連結」時才付出整合成本才有回報。
• 工具要 idempotent：fmt --fix 跑兩次結果要相同；pre-commit 觸發的修改要保持 git state 完整；--check 跟 --fix 要共用同一套規則判讀。
• 跨檔案檢查需要圖：single-file linter 好寫；跨檔 orphan 偵測、連結完整性、reverse-dependency 這類問題需要先把整個 repo 建成結構化圖，再走訪。
• 工具的價值在落地：寫出能跑的 binary 只是起點；接到 pre-commit hook 跟 CI 才讓工具真正守住品質。

章節粒度說明

本模組每章都針對 一個可複用的工具開發技術，篇幅會比語法章長一些。每章的結構大致是：

1. 問題描述（為何需要這個技術）
2. 概念與 Go 層面的設計取捨
3. 實作與範例（引用 mdtools 對應程式碼）
4. 常見陷阱
5. 擴充路徑

先備知識

讀這個模組前建議已經熟悉：

• 模組一到模組三：Go 語法、型別、標準庫基礎
• 模組五：error 處理與 testing 的基本 pattern
• （加分）模組四：concurrency — 雖然 CLI 工具很少需要 goroutine，但 pipeline fan-out 偶爾用得到

本模組與後端服務模組（6、7、8）是並行關係，讀者可以直接跳入，無需先讀完後端系列。

本模組使用的範例

• scripts/mdtools/ — blog 自己的 markdown 品質工具鏈
  • main.go 的 subcommand dispatcher
  • internal/astutil/ 的 goldmark wrapper
  • internal/mdfmt/ 的格式正規化
  • internal/mdcards/ 的 link graph
  • internal/mdmigrate/ 的 L1 auto-fix
• .githooks/pre-commit — 把工具接進 git workflow
• .github/workflows/md-check.yml — CI 整合

完整工具的設計紀錄可參考 mdtools：Go + goldmark 的 markdown 工具鏈設計；AST 概念的入門說明見 什麼是 AST。

學習時間

預計 2.5-3.5 小時（含動手把 scripts/mdtools clone 下來編譯、修改、重跑）

預計補充內容

這些設定邊界會在下列章節展開：

• Go 進階：composition root 與依賴組裝：設定讀取的真正用途，是在啟動層把外部輸入轉成可驗證的依賴。
• Go 入門：從入口程式看應用啟動流程：先看主程式怎麼啟動，才知道設定應該在哪裡完成驗證。
• Backend：部署平台與網路入口：像 secret manager、ConfigMap 與 rollout 這類平台責任應該留給 Backend。

與 Backend 教材的分工

本章只處理 Go 程式內的設定邊界。secret manager、Kubernetes ConfigMap、container environment、遠端動態設定與部署平台 rollout 會放在 Backend：部署平台與網路入口。

和 Go 教材的關係

這一章承接的是入口流程與 composition root；如果你要先回看語言教材，可以讀：

• Go：從入口程式看應用啟動流程
• Go：composition root 與依賴組裝
• Go：testing 基礎
• Go：flag、os/env 與設定邊界

一個 App 的真實佔用不等於它的 .app 大小

判斷一個 App 吃多少空間，要算的是它的總足跡（footprint），而不是 /Applications 裡那顆 .app 的大小。.app 只是程式本體，App 跑起來產生的資料（下載內容、快取、登入狀態、設定、日誌）絕大多數寫在 ~/Library 底下的好幾個不同位置，跟 .app 完全分家。

這台機器上最極端的例子是 Steam：它的 .app 只有 10.8M，但遊戲資料佔了 8.1G，兩者差了近 800 倍。只看 /Applications 的大小排序，Steam 會排在很後面，完全看不出它是全機第一大戶。同樣地，Amazon Kindle 的 .app 才 138M，書庫卻在沙箱容器裡佔了 3.2G。這就是為什麼「按目錄統計」和「按 App 統計」會給出完全不同的排行；要回答「哪個 App 該清」，必須把佔用聚合回 App。

佔用散落在 ~/Library 的哪些地方

聚合的第一步是知道一個 App 會把資料寫到哪些固定位置。下表只列與空間相關的主要位置（非 ~/Library 全量），macOS 對它們有約定，每個位置承擔不同責任，也決定了它能不能安全清掉。

這張表的關鍵分界是「快取」與「資料」。Caches 和 HTTPStorages 是純衍生物，清掉只是讓 App 下次重新下載或重建，最多重新登入一次，所以是回收空間時的首選。Application Support、Containers、Group Containers 則是使用者資料，Steam 的遊戲、Kindle 的書庫、聊天記錄都在這裡，刪了就真的沒了。Group Containers 還要多一層留意：它是同一個開發商旗下多個 App 共享的目錄，動它可能同時影響好幾個 App。

腳本對每個 App 把上面這些位置全部找出來、用 du 量實際佔用、加總成一個數字，再附上逐項明細，讓人一眼看出「這 4G 裡有多少是可清的快取、多少是動不得的資料」。

命名不一致是聚合的主要難點

把資料夾正確歸給某個 App 的難點在於：macOS 對這些目錄沒有統一的命名規則。有些 App 用它的 bundle id（例如 com.valvesoftware.steam）當目錄名，有些直接用 App 的顯示名稱（例如 Steam），同一個 App 的不同位置甚至各用一種。

腳本的做法是對每個 App 先讀出它的 bundle id，然後 Caches、Application Support、Logs 這幾個位置兩種命名都比對一次，bundle id 專屬的位置（Containers、HTTPStorages、Saved Application State）則用 bundle id 找。Group Containers 又是另一種格式，名稱前面多一段開發商的 team id（10 碼英數，像 ABCDE12345.group.com.foo），因此改用 bundle id 做子字串比對。這套規則涵蓋了絕大多數 App，但用罕見自訂命名的資料仍可能漏抓，這是聚合式估算的固有邊界，腳本在輸出裡據實標明「可能漏抓」而不假裝是精確值。

Homebrew 要分開算

透過 Homebrew 裝的工具不在 /Applications，需要獨立統計。佔用分兩類（概念詳見 Homebrew 知識卡）：命令列工具與函式庫（formula）在 Cellar/，GUI App 的下載 artifact 與 metadata（cask）在 Caskroom/。cask 安裝的 .app 本體實際放在 /Applications，已被前面的 App 聚合排行計入；Caskroom/ 存的是安裝來源與版本資訊，體積通常遠小於 App 本體，兩邊不重複計。

這台機器的 formula 前幾名是開發語言執行環境：dotnet@9 634M、兩個版本的 openjdk 合計 600M、mysql 292M、go 258M。formula 會多版本並存（例如 python@3.13 和 python@3.14 各算各的），所以腳本把整個 formula 目錄一起計。除了已安裝的部分，腳本還列出 brew --cache 的下載快取，以及 brew cleanup -n 預估可回收的舊版本（-n 是 dry-run，只報告不刪），跟整支腳本的唯讀原則一致。

聚合一律用 du 取實際佔用

App 各位置的聚合一律用 du -skx 取實際佔用，而不是 ls / find -size 的邏輯大小。sparse 檔（稀疏檔）只有寫入過的區塊才真正佔磁碟，宣告的邏輯大小可能是實際佔用的數十倍；容器與資料目錄裡正好常有 VM 映像、容器磁碟這類 sparse 檔，拿邏輯大小加總會把整份聚合排行灌水。完整的 sparse 踩坑案例見 disk-report 那篇。

-x 讓 du 不跨越檔案系統邊界，避免把掛載進來的卷重複計入；-k 統一用 KB 當單位，方便把各位置的數字加總後再換算成人類可讀的 G / M。

實測結果

下面是這台機器的實測排行（名次因個人使用習慣而異）；要看的是聚合排行和「按目錄統計」給的印象差多少：

全機掃到 65 個 App、聚合總計 48.2G。這份排行的價值在於它直接指向「該從哪裡下手」，而判讀邏輯可以套到任何人的排行上：本體小、資料大的 App（這台是 Steam、Kindle）要回收就得處理書庫與遊戲本身；純快取大的（這台是 Dia 的 1.6G）清掉零風險；本體就大的開發工具（Xcode、Android Studio）除非不再開發否則動不得。同一個總數字底下，可清的比例天差地別，這正是逐項明細要回答的問題。

聚合的邊界：總計不等於整機

這個 48.2G 是「能歸屬到已安裝 App 的部分」之和，不是 ~/Library 的全量。disk-report 那篇量到的 ~/Library 約 70G，差額落在幾類刻意不歸進單一 App 的位置。

最大的一塊是 ~/Library/Developer（這台約 5.5G，幾乎全是 Xcode 的 DerivedData、CoreSimulator 與 iOS DeviceSupport）。它們是 Xcode 與模擬器產生的共用產物，硬塞給 Xcode 會誇大這顆 App、塞給別人又不對，app-report 比照 Homebrew 把它單獨列成一段（app-report --dev）。也因為這樣，上面排行裡的 Xcode 只算到 .app 本體，它的建置產物要看 Developer 那段——這也是為什麼 disk-report 會把「Xcode DeviceSupport」列為大戶，而逐 App 排行卻看不到：那筆資料正住在這個不歸單一 App 的位置。

其餘排除的還有 iCloud 與雲端硬碟的本地鏡像（Mobile Documents、CloudStorage）、已移除 App 留下的孤兒資料夾、以及 Preferences。排行掃的是 /Applications、~/Applications、/Applications/Utilities 與 Setapp、Mac App Store 裝的 App；直接從 DMG 跑、沒搬進 Applications 的 App 不會出現在排行，但它的 ~/Library 資料若命名對得上仍可能部分計入。

還有一個方向相反的誤差要記得：這是估算不是精算。同一份資料若以 APFS clone 出現在多個被聚合的位置，逐位置分開跑 du 會各自計入（du 只在單次執行內對硬連結以 inode 去重，對 APFS clone 不去重），聚合值可能偏高。要看整個 ~/Library 到底多大、由誰佔，回到 disk-report 的逐層 du。

固化成 app-report 腳本

把這套聚合邏輯寫成腳本，往後想知道「誰在吃空間」就一行重跑，不必每次重想要比對哪些目錄、要怎麼處理命名差異。腳本和 disk-report 收在同一個公開 repo tarrragon/scripts 裡，維持「跟專案無關的系統工具放個人 bin」的一致做法。

兩支腳本在同一個 repo；若已為 disk-report clone 過 ~/Projects/scripts，跳過 clone、只做 symlink。首次安裝則把 repo clone 下來，再把腳本本體 symlink 到個人的 ~/.local/bin，這樣本機呼叫的永遠是 repo 的最新版：

1git clone https://github.com/tarrragon/scripts.git ~/Projects/scripts
2ln -s ~/Projects/scripts/app-report/app-report ~/.local/bin/app-report

PATH 設定同 disk-report（見 macOS 新機基礎建設）。裝好後直接呼叫：

1app-report           # 完整報告：App 聚合排行 + Developer + Homebrew
2app-report --apps    # 只看 App 聚合排行（預設前 30）
3app-report --apps 50 # 排行顯示前 50
4app-report --dev     # 只看 ~/Library/Developer 開發工具共用資料
5app-report --brew    # 只看 Homebrew

要清哪個 App，看完明細再動手：移掉 .app 並清對應的 ~/Library 資料夾（報告每個 App 下方列的路徑就是清除對象；先從 Caches / HTTPStorages 開始，確認再考慮資料目錄），Homebrew 用 brew cleanup -s。

兩支腳本的分工

disk-report 與 app-report 是磁碟清理的兩個接力棒。前者在卷與目錄層找出最大的子樹，通常落在 ~/Library；後者接手把那棵子樹拆到 App，看出具體是誰佔的、各自有多少是可清的快取。先 disk 找方向、再 app 定位到人，兩支都唯讀，回收的最後一步都留在人這一端。

先裝 Homebrew，它是後面一切的基礎

macOS 本身沒有內建的第三方套件管理工具，而後面幾乎每一項補強（命令列工具、開發語言、甚至部分 GUI App）都靠它安裝。沒有 Homebrew，這份清單的其他項目全部無從裝起，所以它排第一。

安裝過程會要求輸入登入密碼（sudo），並自動下載 Xcode Command Line Tools，畫面可能停住數分鐘屬正常。

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

裝完還要把 Homebrew 的執行檔目錄加進 PATH，shell 才找得到 brew 與之後用它裝的工具。Homebrew 的安裝前綴依晶片而異：Apple Silicon 機器裝在 /opt/homebrew、Intel 機器裝在 /usr/local。安裝腳本結尾會印出對應這台機器的設定指令，照它印的路徑寫進 ~/.zprofile 讓每次開 shell 都生效。以下以 Apple Silicon 為例，Intel 機器把前綴換成 /usr/local 即可：

1echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
2eval "$(/opt/homebrew/bin/brew shellenv)"

這一步做完，驗證安裝成功：

1brew --version   # 應印出 Homebrew 4.x.x

版本號印出來，Homebrew 就能當後面所有項目的安裝來源。

把 bash 更新到 5.x

bash 是裝完 Homebrew 後最值得優先換掉的內建工具。macOS 的 /bin/bash 長年凍結在 3.2 系列（2006 年釋出，目前是 patchlevel 57），Apple 不再更新它，原因是 bash 4 改用 GPLv3 授權、Apple 不願隨系統散布。對寫腳本的人來說，這代表 associative array、${var,,} 大小寫轉換、mapfile 等近二十年的語法都用不了。

正確做法是用 Homebrew 另外裝一份新版並排存在，而不是覆寫系統版。/bin/bash 在唯讀的系統卷上、受 SIP（System Integrity Protection）保護，覆寫會被擋下：

1brew install bash

這會把 bash 5.x 裝到 /opt/homebrew/bin/bash，完全不碰 /bin/bash。因為前一步已經把 /opt/homebrew/bin 排在 PATH 前面，用 #!/usr/bin/env bash 起手的腳本就會自動改用新版。裝完驗證一下版本確實切過去：

1env bash --version   # 應顯示 5.x
2/bin/bash --version  # 系統版仍是 3.2.57，沒被動

要留意的是互動 shell 在現代 macOS 預設是 zsh，這一步不影響它。更新 bash 的目的是給 #!/usr/bin/env bash 腳本一個現代執行環境，不是換登入 shell。真要把新版 bash 當登入 shell，才需要額外把它加進 /etc/shells 再 chsh。

把 ~/.local/bin 加進 PATH，放個人腳本

跟專案無關的小工具（例如 disk-report 與 app-report 這類系統診斷腳本）需要一個能在任何地方直接呼叫、又不污染專案 repo 的家。慣例是個人的 ~/.local/bin，把它建好並掛上 PATH。

1mkdir -p ~/.local/bin
2echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
3export PATH="$HOME/.local/bin:$PATH"

目錄建好、PATH 掛上後，確認它確實生效：

1echo "$PATH" | tr ':' '\n' | grep "$HOME/.local/bin"

之後把腳本 symlink 進這個目錄就能直接當指令用。

後續項目

基礎建設到位後，第一個掛上去的實用腳本就是系統診斷：磁碟空間診斷的 disk-report 與 按 App 聚合佔用的 app-report，兩支都 symlink 進 ~/.local/bin 直接當指令用。

這份清單會隨著之後遇到的需求往下增補，新項目接在這裡。原則維持不變：基礎建設排前面，依賴它的補強排後面，每一項都寫清楚「為什麼要做」而不只是貼指令。

最後把整套診斷固化成一個唯讀的 disk-report 腳本，往後同類情況可以一行指令重跑。

先確認問題是「真的滿」還是「浮動的假象」

排查磁碟的第一步是分辨空間到底去哪：是被真實檔案佔走，還是被系統的快照與 purgeable（系統可隨時回收的緩衝空間）暫時佔住。這兩者的處理方式完全不同，先分清楚才不會白清。

在 APFS（Apple File System，macOS 的預設檔案系統）上，根目錄 / 是唯讀的系統封印卷，真正存放使用者資料的是 /System/Volumes/Data，而它們和其他卷（Preboot、Recovery、VM、模擬器 runtime）共用同一個 container（容器，APFS 管理空間的最上層單位）的空間池。判斷「還剩多少」要看整個 container 的可用空間，而不是單一卷的數字。

1df -h /System/Volumes/Data
2diskutil info /System/Volumes/Data | grep -iE "Container Free Space|Container Total Space"

這次的結果是資料卷 100% 滿、整個 container 只剩約 591MB。確認確實滿載、不是顯示誤差，後面才值得花力氣找佔用大戶。

「空間掉了又回來」的根因：本地快照與 purgeable

空間在幾小時內反覆消長、清 cache 卻無效，最常見的原因是 Time Machine 的本地快照（local snapshots）加上 macOS 的 purgeable 空間，而不是某個看得見的檔案。這是排查時要先排除的一條線。

本地快照的運作方式是：Time Machine 啟用時，系統約每小時自動建立一張快照「凍結」當下狀態，好讓本地也能做時光機回溯。這些被凍結的資料，正是先前以為已刪除、卻怎麼清都不會釋放的空間。快照保留約 24 小時（Apple 的 thinning 策略，觀察值），或在磁碟空間壓力過大時提前清除；後者正是「過一陣子空間又回來」的來源。若從未設定 Time Machine，這條線可跳過——沒啟用就不會有 local snapshot。

1tmutil listlocalsnapshots /System/Volumes/Data

這次查的時候快照數是 0，但這不代表它不是元兇——恰恰相反，是磁碟已經滿到讓系統把快照全數清光了。判讀訊號是：若這個指令平常列出多筆快照、且磁碟空間在數字上頻繁浮動，浮動量就來自這裡，跟手動清的 cache 無關。根治方向是把總用量降下來、讓磁碟保有餘裕，系統就不會一直貼著上限狂建狂清快照。

purgeable 是同一條線的另一半，但它沒有好用的精確讀數。diskutil apfs list 能看 container 層的概況，而 purgeable 主要由快照與系統快取構成、本來就會自己浮動。處理方式跟快照一樣：把總用量降下來、讓系統在空間有壓力時自行釋放，而不是找指令直接清它。「沒有直接讀數」本身就是判讀邊界——看到可用空間和「實際檔案總和」對不上時，差額多半就在這塊浮動緩衝，不必懷疑是哪個檔案在搞鬼。

用實際佔用值找大戶，避開 sparse 假大小

找佔用大戶要用 du（實際佔用的磁碟區塊）排序，不能依賴 ls -l 顯示、或 find -size 篩選所用的邏輯大小。對一般檔案兩者相同，但對 sparse 檔（稀疏檔）差距可以是好幾十倍，誤判會追錯目標。

這次就踩到這個陷阱。find 列出近期修改的大檔時，OrbStack（一套容器與 VM 執行環境）的虛擬磁碟映像顯示為 228G，看起來像頭號兇手；但用 du 一量，實際佔用只有 1.9G。同樣地，macOS Podcasts 在 tmp 塞的一堆 .tmp.resize.img 顯示有數十個檔，實際只佔 3.5M。這些都是 sparse 檔：宣告了很大的邏輯大小，但只有寫入過的區塊才真正佔磁碟。

1# 實際佔用（正確）
2du -sh ~/some/large.img
3
4# 顯示大小（對 sparse 檔會嚴重高估，誤判用）
5ls -lh ~/some/large.img

定位順序是由外往內逐層收斂：先看家目錄前 20 大，鎖定最大的子樹（這次是 ~/Library 70G 左右），再往下展開 ~/Library/Application Support、~/Library/Containers，直到找到具體的檔案或目錄。

1du -shx ~/* ~/.[!.]* 2>/dev/null | sort -rh | head -20
2du -shx ~/Library/* 2>/dev/null | sort -rh | head -12

-x 讓 du 不跨越檔案系統邊界，避免把掛載進來的唯讀卷（例如 iOS 模擬器 runtime）重複計入；~/.[!.]* 這個寫法只展開以單一點開頭的隱藏檔，排除掉 . 和 .. 兩個會被一般 .* 誤抓進來、算出整個家目錄大小的假項目。

這次找到的佔用大戶與處理

定位出來的大戶集中在開發工具鏈與閒置的本地資料，多數可逆、刪了之後需要時會自動重建或可重新下載。下面的項目與數字都是這台機器的實測，換一台機器組成會完全不同；值得帶走的是每一項背後的判讀問題，不是這份清單本身。具體刪除指令因工具而異（Android Studio GUI、rm -rf、ollama rm），本文只做診斷與定位，刪除操作留給各工具自身的文件。以下逐項說明判讀依據。

Android NDK 的判讀要回到「誰在用它」：這次專案是 Flutter，NDK 版本由 flutter.ndkVersion 決定，而不是專案自己 pin。查當前 Flutter 要求的版本後發現，本機裝的兩版都是舊 Flutter 留下的殘留，於是保留較新的一版、刪掉最舊的。判斷可不可刪的關鍵是先確認「現在到底用哪版」，而不是看修改日期就動手。

Claude 桌面的 vm_bundles 是最大單一項目（11G）。它是桌面 App 的 Cowork 功能在本地沙箱 VM 裡執行程式用的根檔案系統映像。關鍵判讀是：它不是每次開 App 就重建——映像的修改日期停在數月前，是一次性佈建、之後沿用。只有實際使用 Cowork 沙箱時才會佈建和更新。所以對只用終端機 CLI、桌面 App 僅拿來聊天的人，這 11G 是純佔用，可以安全刪除；唯一後果是哪天實際開了 Cowork session，它會重新佈建。

剩下三項的判讀各有自己的關鍵問題。閒置的 AVD 與 system-image 是「一個 API 版本一組」的綁定，停用某個 Android 版本時要連 AVD 帶它依賴的系統映像一起刪，只刪一邊會留下半套。ollama 本地模型的判斷是「改用雲端後還會不會在本地跑」，閒置的大模型可刪，但小的 embedding 模型常被其他工具當依賴、刪了會牽連（ollama 模型的累積速度與專屬清理 idiom，見 本地 LLM 的資源管理）。Xcode 的 iOS DeviceSupport 則是實體裝置接線除錯時產生的符號快取，可以放心刪——下次接上同一台裝置除錯時 Xcode 會自動重建。

這幾項合計回收約 17G，可用空間從約 591MB 拉回到 18G，磁碟脫離滿載。

把診斷固化成 disk-report 腳本

一次性查完之後，把這套順序寫成腳本的價值是：下次同類情況不必重新回想指令與判讀順序，一行就能重跑，而且固定先看快照、再用實際佔用值，不會又掉進 sparse 假大小的陷阱。

腳本收在公開 repo tarrragon/scripts，而不是放進某個專案的 bin/。它跟任何專案無關，連到個人 bin 才能在任何地方直接呼叫，也不會污染專案 repo。安裝方式是 clone 下來、把腳本本體 symlink 到 ~/.local/bin：

1git clone https://github.com/tarrragon/scripts.git ~/Projects/scripts
2ln -s ~/Projects/scripts/disk-report/disk-report ~/.local/bin/disk-report

這一步預設 ~/.local/bin 已在 PATH 上。若還沒設定，做法見 macOS 新機基礎建設 的對應項目。腳本刻意設計成唯讀：只報告、不刪除，刪什麼由人看完報告再決定。

1disk-report              # 完整診斷：總覽 + 快照狀態 + 各層大戶 + 開發環境可清項
2disk-report --growing    # 只看過去 180 分鐘內長大的大檔（抓動態暴增最快）
3disk-report --growing 60 # 改成過去 60 分鐘

--growing 模式對應的是本文開頭那個「幾小時內暴增」的情境：當空間正在快速消失、想抓現行犯時，直接列出近期被寫入的大檔，比逐層 du 更快定位。

1find "$HOME" -type f -size +50M -mmin -180 2>/dev/null \
2  -exec du -h {} \; 2>/dev/null | sort -rh | head -25

50M 的下限是為了過濾日常小檔雜訊、鎖定單一大檔暴增；若懷疑是大量小檔累積吃空間（如快取碎片），這個門檻抓不到，要回逐層 du 看目錄總量。排序依據同樣是 du 的實際佔用值，而不是 find -size 的邏輯大小門檻，理由和前面一致：避免 sparse 檔的邏輯大小把排序帶歪。

排查順序總結

這次的方法可以收斂成一條固定順序，往後遇到任何「磁碟莫名變滿」都先照這條走：

1. 先看 container 可用空間，確認是真滿還是顯示誤差。
2. 再查本地快照與 purgeable，排除「掉了又回來」的浮動來源。
3. 用 du -shx 由外往內逐層找大戶，全程以實際佔用值判斷，不信 ls / find 的顯示大小。
4. 對每個大戶問「現在誰在用它」再決定刪不刪，可逆的優先清。
5. 把整套順序固化成唯讀腳本，下次一行重跑。

第 3 步若收斂到 ~/Library 這種多個 App 共用的大目錄，按目錄統計只能看出 Caches、Containers 各多大，看不出是哪幾個 App 佔的。把這棵子樹再按 App 拆開的做法，見 macOS App 聚合佔用報告。

這類狀態可以稱為 Android emulator 半活（zombie）：emulator host process 還在、ADB 清單仍殘留 device，但 emulator 內的 adbd 或 Android system 已停止回應。Flutter 在掃描階段會對每個 Android device 查 properties，掃描到這個半活 device 就卡在 timeout。

事故場景

事故場景的核心是「Flutter 指令看似卡住，其實卡在下游 device property 查詢」。連續跑 flutter devices 時，輸出長這樣：

1$ flutter devices
2Found 4 connected devices:
3Error -2 retrieving device properties for sdk gphone64 arm64:
4[卡住]
5
6$ flutter devices
7Found 3 connected devices:
8[繼續卡]

這段輸出有兩個值得注意的點：

1. Error -2 retrieving device properties for sdk gphone64 arm64: 訊息出現後仍繼續等待，代表 Flutter 沒有在第一個 device 失敗時 fail-fast
2. 第一次 Found 4、第二次 Found 3，代表 device 數在兩次掃描之間自己少了 1

sdk gphone64 arm64 是 Android Studio AVD 預設模板（Google Phone 64-bit ARM）建出來的 emulator 顯示名稱、macOS 上跑 Android system image 都會看到這個。

為什麼計數變化是關鍵徵兆

device 數從 4 變 3，代表 ADB 對某個 emulator 的狀態判斷在兩次查詢之間變了。ADB server 內部追蹤每個 device 的狀態（device / offline / unauthorized / no permissions）；半活 emulator 在第一次掃描時仍被列在 Found 4，第二次掃描時可能已被標成 offline 或從候選清單移除，所以掉到 Found 3。

判讀訊號是「同一條 list 指令連跑兩次，device 數或 device 狀態自己變」。正常穩定狀態下，清單應該保持一致；清單漂移代表 ADB server 對某個 entry 的看法不穩定，下一步要先找出那個 entry，再決定是否重啟 ADB 或 emulator。

為什麼 flutter devices 會卡住

flutter devices 的責任是把每個候選 device 補成 Flutter 可用的 target，而不只是印出 adb devices 的結果。Flutter 對每個 ADB 看得到的 Android device 還要做幾件事：

1. 跑 adb shell getprop ro.product.cpu.abi 拉 ABI
2. 跑 adb shell getprop ro.build.version.sdk 拉 SDK level
3. 跑 adb shell getprop ro.product.model 拉裝置型號
4. 視情況跑 adb shell 其他指令確認 Flutter 支援度

這些是同步、序列化、有 timeout 的呼叫；timeout 通常設得相對寬鬆，讓慢一點的真機也能跑通。當其中一個 device 是 zombie 狀態：

• adb shell getprop ... 送出後，ADB 把指令轉發給 emulator 內的 adbd
• adbd 收到了但 Android system 沒回應，或 emulator process 整個卡住沒在處理 ADB request
• Flutter 端等 timeout、再 retry、再等更長 timeout，看起來就是「整個指令卡住」

Error -2 retrieving device properties 是其中一次嘗試 timeout 拿到的訊息（-2 是 Dart ProcessException 對應 adb exit code 的內部映射）。Flutter 仍會繼續掃描其他 device，所以使用者看到的是「印出錯誤訊息 + 繼續卡」。

為什麼是半活狀態

Android emulator 在 macOS 上的結構大致是：

1qemu-system-aarch64 (host process)
2  ├─ Android kernel
3  ├─ Android system services
4  └─ adbd (在 emulator 內部，跟 host ADB server 對接)

半活狀態指的是「host process 還在，但 device 內部服務已無法完成 ADB request」。完全正常時 emulator 跑得動、ADB 也通；完全退出時 emulator process 已結束、ADB 清單看不到它。半活介於兩者之間：

• qemu host process 還在（活著）
• emulator 內的某個環節卡住（Android system 沒在 schedule、或 adbd 卡在某個 mutex）
• ADB server 還記得有這個 device，尚未穩定 evict
• 任何 adb shell 指令都打不通

常見成因：

• Quick Boot snapshot 還原失敗或部分還原——AVD 預設關機是 quick boot（存 snapshot），下次開機從 snapshot 還原；snapshot 跟當前 host kernel / hypervisor 狀態不相容時會半開機
• macOS 從 sleep 喚醒後 hypervisor framework 重置——emulator 是用 Hypervisor.framework，喚醒後虛擬 CPU 可能停在奇怪 state
• host 端記憶體壓力導致 emulator 被 swap 嚴重——表面看起來像卡，其實是在等 page fault

這一層的操作目標是恢復工具鏈，而不是追到每個 emulator 內部 race condition。若症狀符合清單漂移與 property 查詢 timeout，先按恢復順序處理；只有反覆發生時，再追 AVD snapshot、system image 或 host 資源壓力。

恢復順序（從輕到重）

恢復順序的核心是先重置最小邊界，再逐層擴大。每一步都要重新跑一次 flutter devices 或 adb devices，確認是否已經恢復，避免直接砍掉 emulator 或清資料。

1# 1. 看 ADB 對每個 device 的狀態
2adb devices
3# 看到 offline / no device / unauthorized 等異常狀態 → 先鎖定該 device

如果有 device 顯示 offline，或正常列出但實際打不通，先重啟 ADB server：

1# 2. 重啟 ADB server（只重置 host 端 ADB session）
2adb kill-server && adb start-server
3adb devices
4# 多數狀況下，ADB 重啟後對該 device 的查詢會 fail-fast，flutter devices 會恢復

如果 ADB 重啟後仍打不通該 emulator，再處理 emulator process：

1# 3. 對特定 emulator 發 emu kill（讓它優雅關閉）
2adb -s emulator-5554 emu kill   # 把 5554 換成實際 port
3
4# 4. 還在的話，終止 qemu process
5pkill -f qemu-system-aarch64

長期修復路由是清掉不穩定的 snapshot。開 Android Studio → AVD Manager → 該 emulator 旁邊的小箭頭 → Cold Boot Now（避免 Quick Boot）。如果冷啟動後仍反覆壞，選 Wipe Data 把 snapshot 與 emulator 內資料整個清掉。

通用診斷思維

工具鏈卡住的診斷核心是先區分「上游 CLI 壞掉」還是「下游 target 沒回應」。flutter / adb 指令卡住時，先用清單穩定性與 device 識別碼定位下游狀態，再決定重啟邊界。

1. 觀察「同一指令連跑兩次結果是否一致」：不一致（device 數變、訊息變）等於某層狀態不穩定
2. 訊息裡有 device 識別碼就釘住它：sdk gphone64 arm64、emulator-5554、序號等都是 ADB 層的識別，可直接拿來 adb -s <id> ... 局部診斷
3. 從外往內排除：ADB server → 個別 device → emulator process → emulator 內 system，逐層重啟
4. 重啟邊界越大、副作用越大：adb kill-server 只影響 ADB session（其他 device 連線會斷一下），pkill qemu 直接砍 emulator，Wipe Data 連 emulator 內的資料都清。能用輕量手段解決就停在那層

操作判準

1. 「device 數兩次掃描之間自己變」是 zombie emulator 的關鍵徵兆：計數變化代表 ADB 內部狀態不穩定
2. Error -2 retrieving device properties 是 property 查詢失敗訊號：Flutter 仍可能繼續處理其他 device，結果是「印出錯誤訊息但繼續卡」
3. adb kill-server && adb start-server 是輕量首選：它只重置 ADB session，不動 emulator 本身，多數狀況下可讓壞 device fail-fast
4. 半活狀態跟 application code 層級不同：先把工具鏈狀態釐清，再回到剛改的程式碼

適用範圍

這個診斷思維不限於 Android emulator：

• iOS Simulator 卡住時 xcrun simctl list 印不出來——同樣的「指令卡 + 訊息看似 fatal 但 process 仍存在」結構
• flutter devices 對任何 device（含 iOS、Web、desktop）的查詢都會走類似的「列出 → 逐個 query property」流程、任一層卡都會表現為類似症狀
• 廣義地說，任何「server 維護一份 client 清單 + 對每個 client 做同步呼叫」的架構（k8s kubectl get pods 對 zombie node、docker docker ps 對掛掉的 container runtime 等）都有同款 failure mode

辨認規則一致：list 指令連跑兩次結果不一致 → 維護清單的 server 對某個 entry 的看法不穩定 → 找出那個 entry 局部處理。這條規則的邊界是：如果清單穩定但操作失敗，問題更可能在該 target 的權限、版本或 runtime 狀態，需要改走對應工具的細部診斷。

工具類跟服務類的差異常被隱晦地帶過，於是後端工程師轉寫工具時會帶進服務的慣性（長時 goroutine pool、defensive 錯誤降級、龐大依賴樹），讓工具變得重而難維護。把分野講清楚比給 cheatsheet 有用 — 後續每個模式落地時，讀者自己會判斷該採哪套預設。

業界哪些人在用 Go 寫工具

下列工具都用 Go 寫成，讀者多半每天都在使用或間接依賴它們：

• hugo — 靜態網站產生器，parse markdown + render template + serve dev。
• kubectl / helm — Kubernetes 的 CLI 客戶端，parse YAML + call API + render output。
• terraform — 基礎設施描述語言的 interpreter + state management。
• gh — GitHub CLI，把 REST/GraphQL API 包成命令列操作。
• goldmark — CommonMark parser，提供 AST 給其他 Go 程式使用。
• stringer / gopls — Go 官方工具鏈，分析 Go 原始碼並產生程式碼或語言服務。
• golangci-lint — 聚合多個 Go linter 的 runner。
• caddy / traefik — 雖然是服務，但以 CLI-first 配置見長。
• protobuf / grpc 的 code generator — 讀 IDL、吐 Go 程式碼。

這些程式都享受 Go 的幾個特定優勢：單一 binary 跨平台部署、快速啟動、stdlib 的 I/O 與檔案系統支援、goroutine 讓 pipeline fan-out 便宜、型別系統防止參數解析等瑣碎錯誤。

工具類 Go 跟服務類 Go 的結構差異

多數後端工程師轉去寫工具會遇到幾個慣性衝突。本節列五個最明顯的。

生命週期：短命而非長時

服務類 Go 跑起來就不預期結束 — goroutine pool、connection pool、graceful shutdown、health check 都繞著「長時健康運行」打轉。工具類 Go 預設是執行、完成工作、退出：

1func main() {
2    if err := run(); err != nil {
3        fmt.Fprintln(os.Stderr, err)
4        os.Exit(1)
5    }
6}

沒有 for { select {} } 的主迴圈，也不用註冊 signal handler 做 graceful 收尾（OS 會幫你回收檔案描述子）。延伸影響：

• 錯誤處理偏向中斷：服務類在錯誤時常選擇降級、記錄、繼續；工具類多半直接退出並印訊息，交給呼叫者決定下一步。
• goroutine 用法保守：工具很少要 100 個並發 worker。有也多半是 pipeline 的 fan-out，而非長時 pool。
• context 用法簡單：很少需要 context.WithCancel，context.Background() 經常夠用。

輸入輸出：檔案 / stdin / 命令列，而非 HTTP / queue

服務讀 request body、寫 response JSON、從 queue 拉訊息。工具讀檔案、parse 命令列 flag、接 stdin pipe、寫 stdout。這改變了幾個預設：

• 輸入格式多元：工具常處理 markdown、YAML、CSV、純文字；encoding/json 是基礎而非核心，其他 parser 反而更常用。
• os.ReadFile / os.WriteFile / filepath.WalkDir 是主力。Path 處理（filepath.Rel、filepath.ToSlash）會反覆出現。
• stdout 是結果通道。服務的 log 跟 response 是兩條 stream；工具的 log 跟 output 經常搶同一條 stream，需要嚴格 discipline：log 全部走 stderr，output 走 stdout，讓使用者能 pipe。

錯誤處理：accumulate or fail-fast

服務處理單一 request 時 fail-fast 容易（回 500、log 原因）。工具常一次處理多個輸入（批次 lint 300 個檔案），需要決定：

• Fail-fast：第一個錯誤就退出 — 適合 make check 這類 gate。
• Accumulate：蒐集全部錯誤一起報告 — 適合 lint 這類讓使用者看全貌的模式。

mdtools lint 就選 accumulate：一次 parse 全部 content，收齊所有 violations，sort 後輸出，退出碼反映是否有 error。作者可以一次看到所有問題，不用反覆跑。

依賴管理：盡可能 stdlib

服務的 go.mod 動輒幾十個 require — ORM、HTTP router、metrics、tracing、queue client 全要。工具圈文化明顯保守：

• 很多優秀 Go CLI 工具只有 1-3 個 direct dependency。
• 標準選型是先看 flag + os + filepath + encoding/* 能否滿足。
• 確實需要外部 parser、terminal UI、或結構化資料函式庫時才引入，而非預設。

這個 convention 出於實用考量：工具經常作為單一 binary 發佈，依賴越少、build 越快、跨平台問題越少。

部署：binary 而非 container

服務類部署到 k8s，工具類部署成 go install example.com/tool@latest 的 binary。連帶的預設：

• 配置用 CLI flag + 環境變數覆蓋：真正需要結構化配置時才引入 config schema。
• 版本管理用 build tag：go build -ldflags "-X main.Version=..." 把版本刻進 binary。
• 升級由 go install 承接：使用者重跑 go install 拉最新版，end-user 工具（hugo / kubectl）才額外設計自更新。

工具選型的判讀表

工具語言選型的核心判準是工作負載特徵：要不要跨平台分發、要不要處理大量 I/O、要不要整合既有生態。下表給八個判讀情境，各自有展開說明。

單一 binary 跨平台分發：工具的使用者可能分散在 macOS / Linux / Windows，每個人的 runtime 版本不同。Python 工具要求受眾先裝 Python、確定 3.x vs 2.7、管好 venv；shell 工具在不同 shell（bash / zsh / dash）行為分歧。Go 的靜態編譯讓一個 binary 直接丟出去能跑，這是推廣一個工具時最大的摩擦減法。適用信號：使用者超過 3 人、或使用者非工程師。反例：只在 CI 環境跑的 hook，runtime 已經固定，shell / Python 成本低。

大量檔案 I/O + 併發加速：linter 跑 1000 個檔案、migration 處理 10000 個 record，都是 I/O 密集任務。Go 的 goroutine + channel 讓 pipeline fan-out 極便宜，shell 靠 xargs -P 也能做但錯誤處理很脆弱；Python 的 GIL 限制真併發，得靠 multiprocessing 增加複雜度。信號：處理量超過「等半秒等得住」、或錯誤需要結構化蒐集。反例：處理一次、規模小於 100 檔，shell 反而快。

Parse 複雜格式：markdown、YAML、protobuf、Go 原始碼這類格式需要完整 parser，自己寫 AST walker 成本高。Go 有大量成熟 parser（goldmark、x/net/html、go/parser）可直接 import；shell 靠 grep / awk 拼不出正確解析；Python 的對應 parser（mistune、lxml）也成熟但跟 Go 生態隔離。信號：錯誤率 regex 已經解不乾淨。反例：純粹的文字搜尋 / 取代，regex 穩定勝出。

整合 Go 生態：要讀 Go 原始碼（gopls、stringer）、要跟 Hugo / Kubernetes 控制平面互動、要產生 Go 程式碼。這些場景跨語言整合成本高（要 FFI 或 serialization 橋接），Go 原生最直接。信號：上游依賴是 Go 專案、或產出物是 Go 程式碼。反例：跟 Python / JavaScript 生態為主時，用該語言更順。

一次性 one-liner：要做的事 grep / sed / awk 十行內能解決，沒有可觀的重複執行需求。用 Go 寫等於建立一個新 binary、build pipeline、版本管理 — 投資回不來。信號：命令能在 shell 下一口氣打完。反例：同樣 logic 要在三個地方重複貼，就該升級成腳本。

要用 ML / 資料科學套件：PyTorch、pandas、scikit-learn 沒有 Go 生態等價物。Go 有 gonum、但離 Python ML stack 的工具豐富度差一個數量級。信號：要調 model、做 EDA、畫圖表。反例：只是簡單統計彙總，Go 夠用。

快速 prototype、throw-away 腳本：動筆成本比 runtime 效能重要。Python 寫一個 50 行 script 的心智負擔比 Go 低（不用宣告型別、不用 import 大堆 package、REPL 可探索）。信號：要先弄清楚問題形狀。反例：prototype 很快會變成正式工具，Go 直接上反而省重寫。

需要 REPL 互動探索：Python / Node / Clojure 有成熟 REPL 文化，能邊試邊寫；Go 的 REPL 工具（yaegi 等）存在但非主流。信號：要實驗資料結構、API 行為、或設計決策。反例：解法已確定，不需要試 — Go 的 test-driven 小程式效果也不差。

mdtools 作為本模組的 worked example

本模組每一章講一個可複用的工具開發技術，同時用 scripts/mdtools（blog 自己用的 markdown 品質工具鏈，實體檔案在本 repo）作為 concrete instance。讀者不需要預先熟悉 mdtools — 每章會先講通用 pattern，再用 mdtools 的對應 code 示範一種可行實作。以下是 mdtools 的全貌，方便後面章節引用時有背景：

• 目的：保證 blog 的 content/**/*.md 在 commit 前符合規範文件（content/posts/markdown-writing-spec.md）的所有約束。
• 結構：單一 binary bin/mdtools，三個子命令 — fmt（格式修正）、lint（結構檢查）、cards（跨檔完整性）、加一個 migrate（一次性批量修正）。
• 實作層：
  • internal/mdfmt — 行為層 format rule，idempotent。
  • internal/mdlint — AST 層結構 rule，只報告。
  • internal/mdcards — 跨檔 link graph，報告 L1 / L2 / L4 違規。
  • internal/mdmigrate — 讀 graph、計算可自動化的修復、改檔。
• 依賴：stdlib + github.com/yuin/goldmark + github.com/mattn/go-runewidth（僅此三個 direct）。
• 整合：.githooks/pre-commit 跟 .github/workflows/md-check.yml 讓工具在每次 commit / push 都跑。

本模組的章節會逐層展開這些實作背後的 Go 技術。

下一步

進入 9.1 stdlib flag 做 subcommand CLI 開始看具體實作。