Basics on Tarragon

1.1 Go 專案結構與 module

Wed, 22 Apr 2026 00:00:00 +0000

Go 專案的邊界通常從 go.mod 開始。它定義目前程式碼屬於哪個 module、使用哪個 Go 版本，以及依賴哪些外部套件。

本章目標

學完本章後，你將能夠：

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

【觀察】`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 分成三類：

類型	例子	意義
標準庫	`net/http`, `context`, `encoding/json`	Go 內建能力
第三方套件	`github.com/gorilla/websocket`	由 `go.mod` 管理
module 內部套件	`example.com/notify-service/messages`	同一個 module 的其他 package

這個分類會告訴你：問題應該去查標準庫文件、第三方套件文件，還是目前 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 基礎概念

Wed, 22 Apr 2026 00:00:00 +0000

本模組帶你建立閱讀 Go 程式需要的基本模型。重點是理解 module、變數、控制流程、package、檔案拆分、函式、入口程式與 Go tooling 如何組成日常開發流程。

章節列表

章節	主題	關鍵收穫
1.1	Go 專案結構與 module	理解 module 與 import path
1.2	變數、零值與短變數宣告	理解 Go 如何宣告與初始化資料
1.3	控制流程：if、for、switch	掌握 Go 的基本流程控制
1.4	package、檔案與可見性	看懂 `package main` 與大小寫可見性
1.5	從單檔到多檔案	理解 Go 程式如何從 `main.go` 長成多檔案與多 package
1.6	函式、方法與 receiver	區分函式、建構函式與物件方法
1.7	從入口程式看應用啟動流程	建立 Go 應用啟動地圖
1.8	Go tooling 與日常開發流程	用 `go run`、`go test`、`go fmt`、`go mod tidy` 建立基本工作節奏

本模組使用的範例主題

module 宣告與依賴
變數、零值與流程控制
單檔、多檔案與跨 package 呼叫
入口點與應用啟動
建構函式與方法
receiver 與狀態方法
Go command、format、test、module tidy

預備知識

基本變數、函式、條件判斷
知道命令列程式或 HTTP server 的基本概念

學習時間

預計 140-170 分鐘

1.1 Python 哲學與設計理念

Tue, 20 Jan 2026 00:00:00 +0000

在學習任何程式語言之前，了解其設計理念能幫助你寫出更符合語言風格的程式碼。Python 有一套廣為人知的設計原則，被稱為「Python 之禪」。

Python 之禪

在 Python 直譯器中輸入 import this，你會看到 Python 的設計原則：

 1>>> import this
 2The Zen of Python, by Tim Peters
 3
 4Beautiful is better than ugly.
 5Explicit is better than implicit.
 6Simple is better than complex.
 7Complex is better than complicated.
 8Flat is better than nested.
 9Sparse is better than dense.
10Readability counts.
11...

實踐中的 Python 哲學

顯式優於隱式（Explicit is better than implicit）

在 Hook 系統中，我們明確導入需要的函式，而不是使用 import *：

1# 好的做法：明確導入
2from lib.hook_io import read_hook_input, write_hook_output
3from lib.git_utils import get_current_branch
4
5# 不好的做法：隱式導入所有
6from lib.hook_io import * # 不知道導入了什麼

可讀性很重要（Readability counts）

函式和變數命名要清楚表達用途：

 1# 好的命名：一看就懂
 2def get_current_branch() -> Optional[str]:
 3 """獲取當前分支名稱"""
 4 success, output = run_git_command(["branch", "--show-current"])
 5 return output if success and output else None
 6
 7# 不好的命名：需要猜測
 8def gcb():
 9 s, o = rgc(["branch", "--show-current"])
10 return o if s and o else None

簡單優於複雜（Simple is better than complex）

Hook 系統使用簡單的 (bool, str) 返回值模式：

 1def run_git_command(args: list[str]) -> tuple[bool, str]:
 2 """
 3 執行 git 命令並返回結果
 4
 5 Returns:
 6 tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
 7 """
 8 try:
 9 result = subprocess.run(
10 ["git"] + args,
11 capture_output=True,
12 text=True,
13 )
14 if result.returncode == 0:
15 return True, result.stdout.strip()
16 else:
17 return False, result.stderr.strip()
18 except Exception as e:
19 return False, str(e)

這個設計比拋出異常更直觀，呼叫者可以用簡單的 if 來處理：

1success, output = run_git_command(["status"])
2if success:
3 print(output)
4else:
5 print(f"Error: {output}")

扁平優於巢狀（Flat is better than nested）

避免過深的巢狀結構：

 1# 不好：過深的巢狀
 2def check_file(path):
 3 if path:
 4 if path.exists():
 5 if path.suffix == '.py':
 6 if path.stat().st_size > 0:
 7 return True
 8 return False
 9
10# 好：使用 early return
11def check_file(path):
12 if not path:
13 return False
14 if not path.exists():
15 return False
16 if path.suffix != '.py':
17 return False
18 if path.stat().st_size <= 0:
19 return False
20 return True

「Pythonic」的含義

當我們說程式碼是「Pythonic」時，意思是它遵循 Python 的慣例和風格。以下是一些例子：

使用 List Comprehension

1# Pythonic
2squares = [x**2 for x in range(10)]
3
4# 非 Pythonic
5squares = []
6for x in range(10):
7 squares.append(x**2)

使用上下文管理器

1# Pythonic
2with open(file_path, "r", encoding="utf-8") as f:
3 content = f.read()
4
5# 非 Pythonic
6f = open(file_path, "r", encoding="utf-8")
7content = f.read()
8f.close() # 容易忘記關閉

使用 enumerate 而非 range(len())

1# Pythonic
2for i, item in enumerate(items):
3 print(f"{i}: {item}")
4
5# 非 Pythonic
6for i in range(len(items)):
7 print(f"{i}: {items[i]}")

實際範例：Hook 系統的設計體現

來自 .claude/lib/hook_io.py 的設計展示了這些原則：

6.1 如何新增一個 Hook

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹如何從零開始建立一個 Claude Code Hook 腳本。這是一個實戰指南，整合了前面學到的所有概念。

前置知識

建議先閱讀：

Hook 系統概述

Claude Code Hook 是在特定事件發生時執行的腳本，例如：

SessionStart - 會話開始
Stop - Claude 主動結束
PreToolUse - 工具使用前
PostToolUse - 工具使用後

步驟 1：建立基本結構

使用 UV 單檔模式

推薦使用 uv 的單檔腳本模式：

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7My Custom Hook - 簡短描述
 8
 9Hook Event: SessionStart
10
11這裡寫詳細說明。
12"""
13
14import sys
15from pathlib import Path
16
17# 添加 lib 目錄到路徑
18sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
19
20from hook_logging import setup_hook_logging
21
22def main():
23    """Hook 主函式"""
24    logger = setup_hook_logging("my_custom_hook")
25    logger.info("Hook 開始執行")
26
27    # 你的邏輯在這裡
28
29    logger.info("Hook 執行完成")
30    return 0
31
32if __name__ == "__main__":
33    sys.exit(main())

路徑設定

Hook 腳本需要能找到共用模組：

 1import sys
 2from pathlib import Path
 3
 4# 添加 lib 目錄到路徑
 5sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 6
 7# 現在可以導入共用模組
 8from git_utils import get_current_branch
 9from hook_logging import setup_hook_logging
10from hook_io import read_hook_input, write_hook_output

步驟 2：處理輸入輸出

SessionStart Hook 範例

SessionStart Hook 不需要讀取輸入，直接輸出即可：

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7Branch Status Reminder - 分支狀態提醒
 8
 9Hook Event: SessionStart
10"""
11
12import sys
13from pathlib import Path
14
15sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
16
17from git_utils import (
18    get_current_branch,
19    get_project_root,
20    is_protected_branch,
21)
22
23
24def main():
25    print("=" * 60)
26    print("Branch Status Reminder")
27    print("=" * 60)
28
29    current_branch = get_current_branch()
30    if not current_branch:
31        print("警告: 無法獲取分支資訊")
32        return 0
33
34    is_protected = is_protected_branch(current_branch)
35    branch_status = "保護分支" if is_protected else "開發分支"
36
37    print(f"當前分支: {current_branch} ({branch_status})")
38    print(f"工作目錄: {get_project_root()}")
39
40    if is_protected:
41        print()
42        print("警告: 當前在保護分支上")
43        print("建議: 建立 feature 分支後再進行開發")
44
45    print("=" * 60)
46    return 0
47
48
49if __name__ == "__main__":
50    sys.exit(main())

PreToolUse/PostToolUse Hook 範例

這類 Hook 需要讀取 stdin 並輸出 JSON：

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7Tool Usage Logger - 記錄工具使用情況
 8
 9Hook Event: PostToolUse
10"""
11
12import sys
13from pathlib import Path
14
15sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
16
17from hook_io import read_hook_input, write_hook_output
18from hook_logging import setup_hook_logging
19
20
21def main():
22    logger = setup_hook_logging("tool_usage_logger")
23
24    try:
25        # 讀取 Hook 輸入
26        hook_input = read_hook_input()
27
28        if hook_input is None:
29            write_hook_output(continue_execution=True)
30            return 0
31
32        # 取得工具資訊
33        tool_name = hook_input.get("tool_name", "unknown")
34        tool_input = hook_input.get("tool_input", {})
35
36        # 記錄使用情況
37        logger.info(f"工具使用: {tool_name}")
38        logger.debug(f"輸入參數: {tool_input}")
39
40        # 輸出結果（不阻擋執行）
41        write_hook_output(continue_execution=True)
42
43    except Exception as e:
44        logger.error(f"Hook 執行錯誤: {e}")
45        write_hook_output(continue_execution=True)
46
47    return 0
48
49
50if __name__ == "__main__":
51    sys.exit(main())

步驟 3：使用共用模組

Git 工具

 1from git_utils import (
 2    run_git_command,
 3    get_current_branch,
 4    get_project_root,
 5    is_protected_branch,
 6    is_allowed_branch,
 7)
 8
 9# 取得當前分支
10branch = get_current_branch()
11
12# 檢查是否為保護分支
13if is_protected_branch(branch):
14    print("警告：你在保護分支上")
15
16# 執行 git 命令
17success, output = run_git_command(["status", "--short"])
18if success:
19    print(output)

日誌系統

 1from hook_logging import setup_hook_logging
 2
 3# 設定日誌
 4logger = setup_hook_logging("my_hook")
 5
 6# 使用日誌
 7logger.debug("詳細資訊")
 8logger.info("一般資訊")
 9logger.warning("警告訊息")
10logger.error("錯誤訊息")

輸入輸出

 1from hook_io import (
 2    read_hook_input,
 3    write_hook_output,
 4    create_pretooluse_output,
 5    create_posttooluse_output,
 6)
 7
 8# 讀取輸入
 9hook_input = read_hook_input()
10
11# 允許繼續執行
12write_hook_output(continue_execution=True)
13
14# 阻擋執行並附帶訊息
15write_hook_output(
16    continue_execution=False,
17    decision="block",
18    reason="不允許此操作"
19)
20
21# PreToolUse 專用輸出
22output = create_pretooluse_output(
23    decision="allow",  # 或 "block", "modify"
24    reason="操作允許"
25)
26print(json.dumps(output))

步驟 4：註冊 Hook

在 .claude/settings.json 中註冊：

 1{
 2  "hooks": {
 3    "SessionStart": [
 4      {
 5        "type": "command",
 6        "command": "python .claude/hooks/branch-status-reminder.py",
 7        "event": "SessionStart"
 8      }
 9    ],
10    "PreToolUse": [
11      {
12        "type": "command",
13        "command": "python .claude/hooks/tool-guard.py",
14        "event": "PreToolUse"
15      }
16    ]
17  }
18}

步驟 5：撰寫測試

 1# tests/test_my_hook.py
 2"""
 3My Hook 測試
 4"""
 5
 6import unittest
 7from unittest.mock import patch, MagicMock
 8import sys
 9from pathlib import Path
10
11# 添加 hooks 目錄到路徑
12sys.path.insert(0, str(Path(__file__).parent.parent / ".claude" / "hooks"))
13
14
15class TestMyHook(unittest.TestCase):
16    """測試 My Hook"""
17
18    @patch("my_hook.get_current_branch")
19    def test_protected_branch_warning(self, mock_branch):
20        """測試保護分支警告"""
21        mock_branch.return_value = "main"
22
23        # 導入並測試
24        from my_hook import check_branch_status
25
26        result = check_branch_status()
27        self.assertTrue(result["is_protected"])
28
29    @patch("my_hook.read_hook_input")
30    def test_empty_input_handling(self, mock_input):
31        """測試空輸入處理"""
32        mock_input.return_value = None
33
34        from my_hook import main
35
36        # 應該正常退出，不拋出異常
37        result = main()
38        self.assertEqual(result, 0)
39
40
41if __name__ == "__main__":
42    unittest.main()

完整範例：檔案類型檢查 Hook

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7File Type Permission Hook - 檔案類型權限檢查
 8
 9阻止對特定類型檔案的危險操作。
10
11Hook Event: PreToolUse
12"""
13
14import sys
15from pathlib import Path
16
17sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
18
19from hook_io import read_hook_input, create_pretooluse_output
20from hook_logging import setup_hook_logging
21import json
22
23
24# 配置：受保護的檔案模式
25PROTECTED_PATTERNS = [
26    "*.env",
27    "*.pem",
28    "*.key",
29    "*credentials*",
30]
31
32# 需要檢查的工具
33MONITORED_TOOLS = ["Write", "Edit", "Bash"]
34
35
36def main():
37    logger = setup_hook_logging("file_type_permission")
38
39    try:
40        hook_input = read_hook_input()
41
42        if hook_input is None:
43            print(json.dumps(create_pretooluse_output("allow")))
44            return 0
45
46        tool_name = hook_input.get("tool_name", "")
47        tool_input = hook_input.get("tool_input", {})
48
49        # 只檢查特定工具
50        if tool_name not in MONITORED_TOOLS:
51            print(json.dumps(create_pretooluse_output("allow")))
52            return 0
53
54        # 取得檔案路徑
55        file_path = tool_input.get("file_path") or tool_input.get("command", "")
56
57        # 檢查是否為受保護的檔案
58        if is_protected_file(file_path):
59            logger.warning(f"阻擋對受保護檔案的操作: {file_path}")
60            output = create_pretooluse_output(
61                decision="block",
62                reason=f"此檔案受保護，不允許直接操作: {file_path}"
63            )
64        else:
65            output = create_pretooluse_output("allow")
66
67        print(json.dumps(output))
68
69    except Exception as e:
70        logger.error(f"Hook 錯誤: {e}")
71        print(json.dumps(create_pretooluse_output("allow")))
72
73    return 0
74
75
76def is_protected_file(file_path: str) -> bool:
77    """檢查檔案是否受保護"""
78    if not file_path:
79        return False
80
81    path = Path(file_path)
82
83    for pattern in PROTECTED_PATTERNS:
84        if path.match(pattern):
85            return True
86
87    return False
88
89
90if __name__ == "__main__":
91    sys.exit(main())

開發檢查清單

新增 Hook 時的檢查項目：

使用 UV 單檔模式（#!/usr/bin/env -S uv run --quiet --script）
正確設定 sys.path 以導入共用模組
使用 setup_hook_logging() 設定日誌
使用 read_hook_input() / write_hook_output() 處理 I/O
妥善處理異常（不讓 Hook 崩潰影響系統）
在 settings.json 中註冊
撰寫單元測試
更新文件

常見問題

Q: Hook 執行失敗會影響 Claude 嗎？

Hook 應該優雅地處理錯誤，不要讓異常傳播出去：

 1def main():
 2    try:
 3        # 你的邏輯
 4        pass
 5    except Exception as e:
 6        logger.error(f"Error: {e}")
 7        # 允許繼續執行，不阻擋系統
 8        write_hook_output(continue_execution=True)
 9
10    return 0  # 總是返回 0

Q: 如何調試 Hook？

使用日誌：

1logger = setup_hook_logging("my_hook", level=logging.DEBUG)
2logger.debug(f"輸入資料: {hook_input}")

查看日誌檔案：

1tail -f .claude/hook-logs/my_hook.log

Q: Hook 執行順序是什麼？

同一事件的多個 Hook 按照 settings.json 中定義的順序執行。

思考題

為什麼要將 Hook 邏輯封裝在 main() 函式中？
什麼時候應該使用 block，什麼時候使用 allow？
如何設計 Hook 以便於測試？

下一章：如何擴展共用模組 回到首頁：Python 維護工程師實戰指南

模組一：Python 基礎概念

Tue, 20 Jan 2026 00:00:00 +0000

本模組帶你快速回顧 Python 的核心概念。如果你已經有其他程式語言經驗，這些內容能幫助你理解 Python 的「思考方式」，以及程式如何從單一 script 長成多檔案與 package。

章節列表

章節	主題	關鍵收穫
1.1	Python 哲學與設計理念	理解「Pythonic」的真正含義
1.2	從單一 script 到多檔案專案	理解 `.py` module、package、執行方式與測試結構如何逐步出現
1.3	模組與套件組織	掌握 `__init__.py` 的作用
1.4	導入機制與路徑管理	解決「找不到模組」的困擾

實際範例來源

本模組的範例主要來自：

.claude/lib/__init__.py - 模組初始化範例
Hook 腳本的導入結構

後續補寫提示：1.2 從單一 script 到多檔案專案 應改用中立範例，避免依賴特定 Hook 系統背景。這一章負責補上初學者從單檔到 package 的過渡；1.3 和 1.4 再處理既有專案中的 module、package 與 import 問題。

預備知識

基本程式設計概念（變數、函式、迴圈）
對任一程式語言有基礎了解

學習時間

預計 45-60 分鐘

1.2 從單一 script 到多檔案專案

Wed, 22 Apr 2026 00:00:00 +0000

Python 程式變大的第一個斷點通常是執行方式與 import 邊界，而非物件導向或架構分層。初學者常從一個 script.py 開始，接著拆出 helper module，最後才整理成 package；每一步都會改變程式如何被執行、如何 import，以及測試如何找到程式碼。

撰寫提示：本章先保留大綱，詳細內容之後補。補寫時請使用中立範例，例如 notify.py、config.py、parser.py、service.py，避免綁定特定專案或 Hook 系統細節。

本章目標

學完本章後，你將能夠：

判斷何時保留單一 script
理解一個 .py 檔案就是一個 module
分辨「同層多檔案」與「package」的差異
看懂 python file.py 與 python -m package.module 的差異
判斷何時需要 __init__.py、pyproject.toml 或 src/ layout

章節大綱

1. 單一 script 是合理起點

核心原則：小工具與實驗程式可以先從單一 .py 檔案開始。這個階段的重點是讓流程清楚，不是急著拆資料夾。

後續補寫範例：

1notify.py

應補充重點：

if __name__ == "__main__" 的基本用途。
函式先集中在同一檔案，避免過早拆分。
當檔案開始同時包含 CLI、設定、解析、業務規則時，再考慮拆檔。

2. 拆成同層 module

核心原則：Python 的每個 .py 檔案都是 module。同層拆檔可以降低單檔負擔，但 import 會受到目前執行位置與 sys.path 影響。

後續補寫範例：

1notify/
2├── notify.py
3├── config.py
4├── parser.py
5└── service.py

應補充重點：

import config 與 from config import load_config。
從專案根目錄執行與從其他目錄執行的差異。
同層 module 適合小型工具，但不一定適合長期擴張。

3. 整理成 package

核心原則：package 是一組 module 的命名空間。當多個 module 共同形成一個概念，就可以用資料夾與 __init__.py 整理成 package。

後續補寫範例：

1notify/
2├── notify_app/
3│   ├── __init__.py
4│   ├── config.py
5│   ├── parser.py
6│   └── service.py
7└── main.py

應補充重點：

__init__.py 的角色：初始化、公開 API、package 標記。
package 內部使用 absolute import 或 relative import 的取捨。
不要把所有名稱都重新 export 到 __init__.py。

4. 執行方式會影響 import

核心原則：Python 的 import 行為和執行方式密切相關。python main.py、python -m package.module、測試工具與安裝後執行，可能會看到不同的 module search path。

後續補寫範例：

1python main.py
2python -m notify_app.cli
3python -m pytest

應補充重點：

__name__ 與 __package__ 的差異。
為什麼 package 內相對 import 在直接執行檔案時容易失敗。
CLI 入口和 library module 最好分開。

5. 測試會推動專案結構

核心原則：當程式需要測試時，專案結構必須讓測試穩定 import 目標程式碼。測試是拆分 module 與 package 的重要壓力來源。

後續補寫範例：

1notify/
2├── notify_app/
3│   ├── __init__.py
4│   └── service.py
5└── tests/
6    └── test_service.py

應補充重點：

tests/ 和 package 的相對位置。
為什麼測試常揭露 import 路徑設計不穩。
小型專案可以先維持簡單，大型或可發布專案再導入 pyproject.toml。

6. 何時進入可安裝專案與 `src/` layout

核心原則：pyproject.toml 與 src/ layout 是正式專案管理工具，不是所有初學程式的起點。當專案需要被安裝、發布、由多個工具穩定執行時，再導入這些結構。

後續補寫範例：

1notify/
2├── pyproject.toml
3├── src/
4│   └── notify_app/
5│       ├── __init__.py
6│       └── service.py
7└── tests/
8    └── test_service.py

應補充重點：

src/ layout 防止「剛好從目前目錄 import 成功」的假象。
editable install 的用途。
進階打包內容應連到 python-advanced/07-packaging/。

後續補寫時的比較提示

Python 和 Go 在這個主題上的差異應明確說清楚：

主題	Python	Go
最小單位	`.py` module	package
單檔起點	任意 script	`package main` + `func main()`
可見性	`_name` 慣例，runtime 不強制	大小寫由編譯器強制
import 問題	受 `sys.path`、執行方式、安裝方式影響	受 `go.mod`、module path、package 邊界影響
循環依賴	runtime 才可能爆 partially initialized module	編譯期拒絕 import cycle
正式專案	`pyproject.toml`、package、`src/` layout	`go.mod`、package、`cmd/`、`internal/`

本章不處理

不展開 packaging 與發布流程。
不深入 dependency management。
不討論大型框架專案結構。
不把 src/ layout 當成所有專案的預設起點。

和 Python 教材的關係

這一章承接的是 module、package 與測試路徑；如果你要先回看 Python 教材，可以讀：

小結

Python 程式的成長路線通常是 script、同層 module、package、可安裝專案。這條路線的核心是執行方式、import 邊界與測試方式逐步穩定。

1.2 變數、零值與短變數宣告

Wed, 22 Apr 2026 00:00:00 +0000

Go 變數宣告的核心規則是：每個變數都有明確型別，未指定初始值時會得到該型別的零值。本章將說明 var、:=、型別推斷與零值如何讓 Go 程式保持可預測。

變數一定有型別

Go 的變數一定屬於某個明確型別。這個型別可以由程式直接寫出，也可以由編譯器根據右側的初始值推斷出來；但推斷完成後，變數的型別就固定了。

1var name string = "api"
2var port int = 8080
3
4enabled := true
5timeout := 30

name 的型別是 string，port 的型別是 int，enabled 與 timeout 則由右側初始值推斷型別。Go 允許省略重複資訊，但不允許變數在執行期間任意改變型別。

1count := 10
2count = 20 // 可以，仍然是 int
3// count = "20" // 編譯錯誤：string 不能指派給 int

這個規則讓 Go 程式在閱讀時更穩定：看到一個變數後，讀者可以相信它的型別不會在後面突然變成另一種資料。

零值讓變數可立即使用

零值是 Go 對「尚未明確指定初始值」的標準答案。每個型別都有自己的零值：數字是 0，字串是空字串，布林是 false，指標、slice、map、function、interface 與 channel 是 nil。

1var retryCount int
2var title string
3var debug bool
4var tags []string
5
6fmt.Println(retryCount) // 0
7fmt.Println(title) // ""
8fmt.Println(debug) // false
9fmt.Println(tags == nil) // true

零值是型別的預設狀態。這是 Go 設計中很重要的精神：讓資料結構在最少初始化下仍然有合理行為。

 1type Counter struct {
 2 value int
 3}
 4
 5func (c *Counter) Add(n int) {
 6 c.value += n
 7}
 8
 9func (c Counter) Value() int {
10 return c.value
11}
12
13var counter Counter
14counter.Add(3)
15fmt.Println(counter.Value()) // 3

Counter 沒有建構函式也能使用，因為 value 的零值是 0。當型別可以靠零值進入可用狀態時，使用者需要記住的初始化規則就會少很多。

`var` 適合宣告意圖

var 的主要用途是清楚宣告變數的存在、型別或零值意義。當你需要讓讀者知道「這個變數稍後才會被賦值」或「零值本身有意義」時，var 比 := 更清楚。

1var userID string
2
3if fromHeader != "" {
4 userID = fromHeader
5} else {
6 userID = fromCookie
7}

這裡的 userID 需要經過條件判斷才會得到值，因此先用 var 宣告變數，再在不同分支指派。讀者看到 var userID string，可以理解這是一個稍後會被填入的字串。

var 也適合用在 package 層級，因為 package 層級不能使用 :=。

1var defaultPort = 8080
2var serviceName = "worker"

package 層級變數會增加全域狀態，使用前要先確認它是否真的代表整個 package 的共同狀態；如果只是函式內部暫存資料，應該放回函式裡。

`:=` 適合區域初始化

短變數宣告 := 的主要用途是在函式內同時宣告與初始化變數。當右側初始值已經清楚表達型別時，:= 可以讓程式更精簡。

1func greeting(name string) string {
2 message := "hello, " + name
3 return message
4}

message 的型別可以從字串串接結果推斷，所以不需要寫成 var message string = ...。這種省略是移除讀者已經能從右側看懂的重複資訊。

短變數宣告只能用在函式內。以下寫法不能放在 package 層級：

1// package 層級不允許：
2// port := 8080

:= 也要求左側至少有一個新變數。這個規則會影響常見的錯誤處理寫法。

1data, err := loadFile("config.json")
2if err != nil {
3 return err
4}
5
6config, err := parseConfig(data) // config 是新變數，err 是重新指派
7if err != nil {
8 return err
9}

第二次使用 := 是合法的，因為 config 是新變數；同時 err 會被重新指派。這種寫法在 Go 很常見，但要留意不要在內層區塊意外宣告出新的同名變數。

型別推斷不等於放棄型別

型別推斷的核心作用是減少重複，不是讓變數變成動態型別。Go 只在編譯期根據右側表達式推斷型別，推斷後仍然遵守靜態型別規則。

1limit := 100 // int
2ratio := 0.75 // float64
3label := "active" // string

當右側型別不夠明確，或你需要指定更精確的型別時，就應該直接寫出型別。

1var timeoutSeconds int64 = 30
2var threshold float32 = 0.8

這裡如果只寫 timeoutSeconds := 30，通常會得到 int；如果 API、資料庫欄位或二進位格式需要 int64，明確宣告型別會比事後轉型更好讀。

指標、slice 與 map 的零值差異

零值的共同規則是「未初始化時有定義好的狀態」，但不同型別的零值可用程度不同。指標的零值是 nil，使用前需要確認是否指向有效資料；slice 的零值可以安全讀長度與 append；map 的零值可以讀取但不能寫入。

1var names []string
2names = append(names, "alice")
3fmt.Println(len(names)) // 1
4
5var scores map[string]int
6fmt.Println(scores["alice"]) // 0
7// scores["alice"] = 10 // panic: assignment to entry in nil map

slice 的零值能直接 append，所以很多函式可以回傳 nil slice 表示沒有資料；呼叫端仍然可以用 len 與 range 處理。map 要寫入前必須先用 make 初始化。

1.3 控制流程：if、for、switch

Wed, 22 Apr 2026 00:00:00 +0000

Go 控制流程的核心規則是：語法少但語意明確；if 處理條件分支，for 是唯一迴圈語法，switch 用於多分支判斷。本章將建立閱讀 Go 流程控制的基本模型。

`if` 表達條件與提前返回

if 的核心責任是根據條件決定程式是否進入某段邏輯。Go 的 if 條件不需要小括號，但區塊大括號是必要語法。

1if age >= 18 {
2 fmt.Println("adult")
3}

Go 不會把數字、字串或指標自動當成布林值。條件必須是明確的 bool 表達式。

1count := 3
2
3if count > 0 {
4 fmt.Println("has items")
5}
6
7// if count {
8// fmt.Println("invalid")
9// }

這個規則讓條件判斷更直接：讀者不需要猜某個非布林值在條件中會被如何轉換。

`if` 可以包含短宣告

if 的短宣告用來把只屬於這個判斷的暫存變數限制在區塊內。這讓錯誤處理與查找結果的作用範圍更清楚。

1if value, ok := cache["user:1"]; ok {
2 fmt.Println("cache hit:", value)
3}

value 與 ok 只存在於 if 與對應的 else 區塊內。這種寫法適合處理 map 查找、型別轉換、函式呼叫錯誤等短生命週期資料。

1if err := saveProfile(profile); err != nil {
2 return err
3}

這裡的 err 只用來判斷 saveProfile 是否失敗，離開 if 後就不再需要。短宣告可以降低變數留在外層範圍造成的干擾。

提前返回讓主流程靠左

Go 常用提前返回處理失敗或特殊情況。核心原則是先處理不能繼續的狀態，讓正常流程留在較少縮排的位置。

 1func normalizeEmail(input string) (string, error) {
 2 input = strings.TrimSpace(input)
 3 if input == "" {
 4 return "", fmt.Errorf("email is required")
 5 }
 6
 7 if !strings.Contains(input, "@") {
 8 return "", fmt.Errorf("invalid email")
 9 }
10
11 return strings.ToLower(input), nil
12}

這段程式先排除空字串與格式錯誤，最後才回傳正常結果。讀者可以依序看到「不能接受什麼」以及「通過檢查後會得到什麼」。

提前返回不是要求每個條件都拆開。當兩個條件代表同一個規則時，可以合併成一個判斷；當條件代表不同失敗原因時，拆開通常比較清楚。

`for` 是唯一迴圈語法

Go 的迴圈只有 for。它可以表達傳統計數迴圈、條件迴圈、無限迴圈與 range 迴圈。

1for i := 0; i < 3; i++ {
2 fmt.Println(i)
3}

這是傳統的三段式迴圈：初始化、條件、迭代後處理。它適合需要 index、固定次數或精準控制遞增方式的場景。

1remaining := 3
2for remaining > 0 {
3 fmt.Println(remaining)
4 remaining--
5}

省略初始化與後處理後，for 就是其他語言常見的 while 迴圈。Go 不另外提供 while，因為 for 條件 已經能表達同一件事。

1for {
2 fmt.Println("polling")
3 break
4}

沒有條件的 for 是無限迴圈，通常會搭配 break、return、context 或 channel 退出。無限迴圈要讓退出條件清楚可見，否則很容易讓讀者無法判斷生命週期。

`range` 用來走訪集合

range 的核心用途是逐一走訪陣列、slice、map、字串與 channel。它會依資料型別產生不同的索引或值。

1names := []string{"alice", "bob"}
2
3for i, name := range names {
4 fmt.Println(i, name)
5}

走訪 slice 時，第一個值是 index，第二個值是元素副本。若不需要 index，可以用 _ 忽略。

1for _, name := range names {
2 fmt.Println(name)
3}

走訪 map 時，順序沒有保證。這是語言刻意設計的結果，避免程式誤以為 map 有穩定順序。

1scores := map[string]int{
2 "alice": 90,
3 "bob": 80,
4}
5
6for name, score := range scores {
7 fmt.Println(name, score)
8}

如果輸出順序重要，應該先取出 key、排序，再依序讀取 map。

`break` 與 `continue` 控制迴圈節奏

break 的核心作用是結束目前迴圈，continue 的核心作用是跳過本次迭代並進入下一輪。它們應該用來表達清楚的流程轉折，而不是補救過度複雜的迴圈。

 1for _, line := range lines {
 2 if line == "" {
 3 continue
 4 }
 5
 6 if line == "STOP" {
 7 break
 8 }
 9
10 fmt.Println(line)
11}

這段程式忽略空行，遇到 STOP 停止，其他行則輸出。條件都放在處理邏輯前方，讀者可以先理解哪些資料不進入主流程。

當迴圈內的 break、continue、巢狀條件太多時，通常代表應該把部分邏輯抽成函式，讓每個函式只負責一層判斷。

`switch` 表達多分支判斷

switch 的核心責任是把同一個概念的多種可能集中呈現。Go 的 switch 預設不會自動落入下一個 case，所以大多數情況不需要寫 break。

 1switch method {
 2case "GET":
 3 fmt.Println("read")
 4case "POST":
 5 fmt.Println("create")
 6case "DELETE":
 7 fmt.Println("delete")
 8default:
 9 fmt.Println("unsupported")
10}

每個 case 預設只執行自己的區塊。若真的需要落入下一個 case，Go 提供 fallthrough，但日常程式很少需要它。

1.3 模組與套件組織

Tue, 20 Jan 2026 00:00:00 +0000

Python 的模組系統是組織程式碼的基礎。理解模組如何運作，是維護和擴展 Hook 系統的關鍵。

承接提示：如果你還不熟悉程式如何從單一 .py 檔案拆成多個 module，請先閱讀從單一 script 到多檔案專案。本章聚焦在已經出現 package 後，如何理解 module、__init__.py 與公開 API。

基本概念

模組（Module）

一個 .py 檔案就是一個模組。例如 git_utils.py 就是 git_utils 模組。

1# git_utils.py 是一個模組
2# 可以被其他檔案導入
3
4from git_utils import get_current_branch

套件（Package）

包含 __init__.py 的目錄就是一個套件。套件可以包含多個模組。

1.claude/lib/
2├── __init__.py      # 使 lib 成為套件
3├── git_utils.py     # 模組
4├── hook_io.py       # 模組
5├── hook_logging.py  # 模組
6└── config_loader.py # 模組

`init.py` 的作用

__init__.py 是套件的初始化檔案，它在套件被導入時執行。

實際範例：Hook 系統的 `init.py`

來自 .claude/lib/__init__.py：

 1"""
 2Claude Hooks 共用程式庫
 3
 4提供 Hook 腳本共用的工具函式，消除程式碼重複。
 5
 6模組結構:
 7- git_utils: Git 操作工具（分支、worktree、專案根目錄）
 8- hook_logging: Hook 日誌系統
 9- hook_io: Hook 輸入輸出處理
10"""
11
12# 從子模組導入並重新匯出
13from .git_utils import (
14    run_git_command,
15    get_current_branch,
16    get_project_root,
17    get_worktree_list,
18    is_protected_branch,
19    is_allowed_branch,
20)
21
22from .hook_logging import setup_hook_logging
23
24from .hook_io import (
25    read_hook_input,
26    write_hook_output,
27    create_pretooluse_output,
28    create_posttooluse_output,
29)
30
31from .config_loader import (
32    load_config,
33    load_agents_config,
34    load_quality_rules,
35    clear_config_cache,
36)
37
38# 定義公開 API
39__all__ = [
40    # git_utils
41    "run_git_command",
42    "get_current_branch",
43    # ... 省略其他
44]
45
46__version__ = "0.28.0"

`init.py` 的三個主要功能

1. 宣告套件身份

空的 __init__.py 也能讓目錄成為套件：

1# lib/__init__.py（最簡形式）
2# 即使是空檔案，也使 lib 成為套件

2. 定義公開 API

透過 __all__ 列表控制 from package import * 的行為：

1__all__ = [
2    "run_git_command",
3    "get_current_branch",
4    "setup_hook_logging",
5]
6
7# 當使用者執行 from lib import * 時
8# 只會導入 __all__ 中列出的名稱

3. 簡化導入路徑

使用者可以直接從套件導入，而不需要知道子模組：

1# 有 __init__.py 的重新匯出：簡潔
2from lib import get_current_branch, setup_hook_logging
3
4# 沒有 __init__.py 的重新匯出：冗長
5from lib.git_utils import get_current_branch
6from lib.hook_logging import setup_hook_logging

相對導入與絕對導入

相對導入（使用 `.`）

在套件內部使用相對導入：

1# 在 lib/config_loader.py 中
2from .git_utils import get_project_root  # 同級模組
3from . import hook_io                     # 導入整個模組

絕對導入

從套件外部或在腳本中使用絕對導入：

1# 在 .claude/hooks/some_hook.py 中
2import sys
3sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
4
5from git_utils import get_current_branch  # 絕對導入
6from hook_io import read_hook_input

套件版本管理

在 __init__.py 中定義版本號是常見做法：

1__version__ = "0.28.0"

這樣使用者可以查詢版本：

1import lib
2print(lib.__version__)  # "0.28.0"

模組載入順序

Python 搜尋模組的順序：

內建模組
sys.path[0]（腳本所在目錄）
PYTHONPATH 環境變數
標準庫
site-packages（第三方套件）

實際範例：Hook 腳本的路徑設定

 1#!/usr/bin/env python3
 2"""Branch Verify Hook"""
 3
 4import sys
 5from pathlib import Path
 6
 7# 將 lib 目錄加入搜尋路徑
 8sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 9
10# 現在可以導入 lib 中的模組
11from git_utils import get_current_branch
12from hook_io import read_hook_input, write_hook_output

最佳實踐

1. 避免循環導入

 1# 不好：a.py 和 b.py 互相導入
 2# a.py
 3from b import func_b
 4# b.py
 5from a import func_a  # 循環導入！
 6
 7# 好：重構為第三個模組
 8# common.py
 9def shared_function(): ...
10# a.py
11from common import shared_function
12# b.py
13from common import shared_function

2. 延遲導入

對於可選依賴或避免循環導入：

1def load_yaml_config():
2    # 只在需要時才導入
3    try:
4        import yaml
5        return yaml.safe_load(...)
6    except ImportError:
7        # 備案方案
8        import json
9        return json.load(...)

3. 清晰的模組邊界

每個模組應該有單一、明確的職責：

1lib/
2├── git_utils.py      # Git 操作（單一職責）
3├── hook_io.py        # 輸入輸出處理（單一職責）
4├── hook_logging.py   # 日誌系統（單一職責）
5└── config_loader.py  # 配置載入（單一職責）

思考題

為什麼 __init__.py 使用 from .git_utils import ... 而不是 from git_utils import ...？
Hook 腳本中的 sys.path.insert(0, ...) 為什麼使用 0 作為索引？
__all__ 列表的作用是什麼？如果不定義會怎樣？

實作練習

閱讀 .claude/lib/__init__.py，回答以下問題：

這個套件匯出了多少個公開函式？
套件的版本號是多少？
如果要新增一個 utils.py 模組並匯出 format_message 函式，需要修改哪些地方？

上一章：Python 哲學與設計理念 下一章：導入機制與路徑管理

1.4 package、檔案與可見性

Wed, 22 Apr 2026 00:00:00 +0000

Go 用 package 組織程式碼。package 不只是資料夾名稱，而是 API 邊界：哪些名稱能被其他 package 使用，哪些名稱只在內部可見，都由 package 與命名共同決定。

本章目標

學完本章後，你將能夠：

理解 package main 和一般 package 的差異
看懂同一個 package 如何拆成多個檔案
用大小寫判斷 exported 與 unexported 名稱
設計不暴露過多細節的 package API

【觀察】每個 Go 檔案都從 package 開始

package 宣告的核心規則是：每個 Go 檔案都必須先宣告自己屬於哪個 package。可執行程式使用 package main，例如：

1package main
2
3import "fmt"
4
5func main() {
6 fmt.Println("hello")
7}

第一行 package main 表示這個檔案屬於 main package。Go 編譯器會尋找 main package 裡的 main() 函式，將它編譯成可執行程式。

一般 package 的核心規則是：它不負責啟動程式，而是提供型別、函式或方法給其他 package 使用。可被其他程式引用的工具 package 通常會使用自己的 package 名稱：

1package config
2
3type Config struct {
4 Port int
5}

這個 package 不會自己啟動程式，而是提供型別、函式或方法給其他 package 使用。

【判讀】package 是一組共同編譯的檔案

package 的編譯單位是一組同 package 檔案。同一個資料夾中的 Go 檔案通常必須宣告同一個 package；這些檔案會被一起編譯，也可以直接互相使用彼此的 unexported 名稱。

例如：

1config/
2├── config.go
3├── defaults.go
4└── validate.go

三個檔案都可以是：

1package config

這表示 config.go 裡的函式可以直接呼叫 validate.go 裡的小工具函式，即使那個工具函式沒有 exported。

【策略】用大小寫控制 API 邊界

Go 可見性的核心規則是：大寫開頭 exported，小寫開頭 unexported。Go 沒有 public、private 關鍵字，而是用命名大小寫決定可見性：

名稱	可見性	意義
`Config`	exported	其他 package 可使用
`Load`	exported	其他 package 可呼叫
`defaultPort`	unexported	只在目前 package 內可用
`validatePath`	unexported	內部實作細節

範例：

 1package config
 2
 3type Config struct {
 4 Port int
 5}
 6
 7const defaultPort = 8080
 8
 9func Load(path string) (Config, error) {
10 if path == "" {
11 return Config{Port: defaultPort}, nil
12 }
13 return readConfig(path)
14}
15
16func readConfig(path string) (Config, error) {
17 // 內部解析邏輯
18 return Config{Port: defaultPort}, nil
19}

其他 package 可以使用 config.Config 和 config.Load，但不能直接使用 config.defaultPort 或 config.readConfig。

【執行】把檔案切分成認知單位

檔案切分的核心規則是：依照讀者理解程式的方式分組，而不是機械地一個型別一個檔案。Go 不要求「一個型別一個檔案」。

例如設定讀取 package 可以這樣切：

1config/
2├── config.go # Config 型別與 Load 入口
3├── defaults.go # 預設值
4├── validate.go # 驗證規則
5└── config_test.go # 測試

這樣切分的好處是：

config.go 作為 package 入口，讀者先看這裡
defaults.go 集中預設值，不和解析流程混在一起
validate.go 集中驗證規則，方便測試
unexported helper 留在 package 內，不污染外部 API

設計檢查

檢查一：控制 exported API

如果你把所有型別、函式、常數都用大寫開頭，其他 package 就會開始依賴你的內部細節。未來你想重構時，會發現很多名稱都不能改。

1.4 導入機制與路徑管理

Tue, 20 Jan 2026 00:00:00 +0000

「ModuleNotFoundError」是 Python 開發者最常遇到的錯誤之一。理解導入機制可以幫助你快速解決這類問題。

承接提示：import 問題通常是 script、module、package 與執行位置共同造成的結果，而非單一語法問題。如果還不確定這幾個概念的差異，請先閱讀從單一 script 到多檔案專案。

模組搜尋路徑

Python 使用 sys.path 列表來搜尋模組。你可以查看當前的搜尋路徑：

1import sys
2for path in sys.path:
3    print(path)

典型輸出：

1/current/script/directory     # 腳本所在目錄
2/usr/local/lib/python3.11     # 標準庫
3/usr/local/lib/python3.11/site-packages  # 第三方套件

Hook 腳本的導入問題

問題情境

Hook 腳本位於 .claude/hooks/，共用模組位於 .claude/lib/：

1.claude/
2├── hooks/
3│   └── branch-verify-hook.py    # 需要導入 lib 的模組
4└── lib/
5    ├── __init__.py
6    └── git_utils.py

如果直接在 Hook 腳本中寫 from git_utils import ...，會得到 ModuleNotFoundError。

解決方案

在導入前將 lib 目錄加入搜尋路徑：

 1#!/usr/bin/env python3
 2"""Branch Verify Hook"""
 3
 4import sys
 5from pathlib import Path
 6
 7# 計算 lib 目錄的路徑
 8# __file__ = .claude/hooks/branch-verify-hook.py
 9# parent = .claude/hooks/
10# parent.parent = .claude/
11# parent.parent / "lib" = .claude/lib/
12lib_path = Path(__file__).parent.parent / "lib"
13
14# 插入到搜尋路徑的最前面
15sys.path.insert(0, str(lib_path))
16
17# 現在可以導入了
18from git_utils import get_current_branch
19from hook_io import read_hook_input

為什麼用 `insert(0, ...)` 而不是 `append(...)`？

1# 優先搜尋我們的模組（推薦）
2sys.path.insert(0, str(lib_path))
3
4# 最後才搜尋我們的模組（可能被標準庫覆蓋）
5sys.path.append(str(lib_path))

如果你的模組名稱與標準庫衝突（例如 email.py），使用 append 會導致導入標準庫而非你的模組。

使用 Path 物件

Path 的基本操作

 1from pathlib import Path
 2
 3# 取得目前檔案的路徑
 4current_file = Path(__file__)
 5
 6# 取得父目錄
 7parent_dir = current_file.parent
 8
 9# 組合路徑
10lib_path = parent_dir / "lib"  # 使用 / 運算子
11
12# 轉換為字串
13lib_path_str = str(lib_path)

路徑解析的陷阱

1# __file__ 可能是相對路徑
2print(__file__)  # 可能是 "./hooks/my_hook.py"
3
4# 轉換為絕對路徑
5absolute_path = Path(__file__).resolve()
6print(absolute_path)  # "/home/user/project/.claude/hooks/my_hook.py"

環境變數方式

另一種方法是使用 PYTHONPATH 環境變數：

1# 在 shell 中設定
2export PYTHONPATH="${PYTHONPATH}:/path/to/.claude/lib"
3
4# 然後執行腳本
5python .claude/hooks/my_hook.py

專案根目錄的取得

Hook 系統中經常需要取得專案根目錄：

1def get_project_root() -> str:
2    """
3    獲取專案根目錄（git 倉庫根目錄）
4
5    Returns:
6        str: 專案根目錄路徑
7    """
8    success, output = run_git_command(["rev-parse", "--show-toplevel"])
9    return output if success else os.getcwd()

使用範例：

1root = get_project_root()
2config_path = os.path.join(root, ".claude", "config.json")

常見錯誤與解決

錯誤 1: ModuleNotFoundError

1ModuleNotFoundError: No module named 'git_utils'

解決方案：確認 sys.path.insert() 在導入語句之前。

錯誤 2: 相對導入錯誤

1ImportError: attempted relative import with no known parent package

原因：在腳本中使用相對導入。

解決方案：在腳本中使用絕對導入，相對導入只用於套件內部。

1# 錯誤：在腳本中使用相對導入
2from .lib import git_utils
3
4# 正確：使用絕對導入
5from lib import git_utils

錯誤 3: 循環導入

1ImportError: cannot import name 'xxx' from partially initialized module

解決方案：重構程式碼，避免模組間互相依賴。

導入風格指南

導入順序（PEP 8）

 1# 1. 標準庫
 2import os
 3import sys
 4from pathlib import Path
 5
 6# 2. 第三方套件
 7import yaml
 8import requests
 9
10# 3. 本地模組
11from lib.git_utils import get_current_branch
12from lib.hook_io import read_hook_input

避免 `import *`

1# 不推薦
2from lib.git_utils import *
3
4# 推薦
5from lib.git_utils import (
6    get_current_branch,
7    get_project_root,
8    is_protected_branch,
9)

長導入的換行

1from lib.git_utils import (
2    run_git_command,
3    get_current_branch,
4    get_project_root,
5    get_worktree_list,
6    is_protected_branch,
7    is_allowed_branch,
8)

實際範例：完整的 Hook 腳本開頭

 1#!/usr/bin/env python3
 2"""
 3Branch Verify Hook
 4
 5驗證當前分支是否適合進行編輯操作。
 6"""
 7
 8# ===== 標準庫導入 =====
 9import os
10import sys
11from pathlib import Path
12
13# ===== 路徑設定 =====
14# 將 lib 目錄加入搜尋路徑
15sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
16
17# ===== 本地模組導入 =====
18from git_utils import get_current_branch, is_protected_branch
19from hook_io import read_hook_input, write_hook_output, create_pretooluse_output
20from hook_logging import setup_hook_logging
21
22# ===== 初始化 =====
23logger = setup_hook_logging("branch-verify")

思考題

為什麼不把 lib 目錄加入 PYTHONPATH 環境變數，而要在每個腳本中設定 sys.path？
Path(__file__).resolve() 和 Path(__file__) 有什麼區別？
如何驗證一個路徑是否已經在 sys.path 中？

實作練習

寫一個函式，列出 sys.path 中所有存在的目錄
建立一個簡單的模組，然後在另一個檔案中使用兩種不同的方式導入它

上一章：模組與套件組織 下一模組：型別系統

1.5 從單檔到多檔案

Wed, 22 Apr 2026 00:00:00 +0000

Go 程式變大的第一個拆分單位通常是檔案，不是架構。學習與開發常從一個 main.go 開始，等到入口程式太長，再把相關函式拆到同一個 package 的其他檔案；只有當某組概念需要形成獨立 API 邊界時，才搬到新的資料夾成為新的 package。

本章目標

學完本章後，你將能夠：

判斷何時保留單一 main.go
理解同 package 多檔案如何互相呼叫
分辨「拆檔案」和「拆 package」的差異
看懂跨 package 呼叫、exported 名稱與 import path 的關係
避免過早把小程式拆成複雜架構

【觀察】單檔是合理起點

單一 main.go 的核心價值是降低初期理解成本。程式還小的時候，把入口、設定、簡單函式放在同一個檔案，通常比一開始拆成多個資料夾更容易閱讀。

1notify/
2├── go.mod
3└── main.go

一個最小 HTTP 服務可以先長這樣：

 1package main
 2
 3import (
 4    "fmt"
 5    "net/http"
 6)
 7
 8func main() {
 9    http.HandleFunc("/health", healthHandler)
10
11    if err := http.ListenAndServe(":8080", nil); err != nil {
12        panic(err)
13    }
14}
15
16func healthHandler(w http.ResponseWriter, r *http.Request) {
17    fmt.Fprintln(w, "ok")
18}

這個階段不需要急著建立 handler、service 或 domain 資料夾。讀者一眼能看懂程式如何啟動，比形式上的分層更重要。

【判讀】main.go 膨脹時，先拆同 package 多檔案

同 package 多檔案的核心規則是：同一個資料夾、同一個 package 名稱的 Go 檔案會被一起編譯，彼此可以直接呼叫，不需要 import。

當 main.go 開始同時包含設定、handler、資料型別與啟動流程，可以先拆成這樣：

1notify/
2├── go.mod
3├── main.go
4├── config.go
5├── server.go
6└── message.go

每個檔案仍然使用：

1package main

因此 main.go 可以直接呼叫 loadConfig()：

1func main() {
2    cfg := loadConfig()
3    server := newServer(cfg)
4
5    if err := server.ListenAndServe(); err != nil {
6        panic(err)
7    }
8}

config.go 可以提供這個函式：

1package main
2
3type config struct {
4    Port string
5}
6
7func loadConfig() config {
8    return config{Port: ":8080"}
9}

這是同 package 內的檔案切分。loadConfig 即使用小寫開頭，main.go 也可以呼叫，因為它們都屬於 package main。

【策略】先拆檔案，再拆 package

拆分的核心判斷是：檔案用來降低閱讀負擔，package 用來建立 API 邊界。這兩者成本不同，不應混在一起。

拆分方式	使用時機	呼叫方式	成本
同 package 多檔案	檔案太長、概念需要分段	直接呼叫	成本低，沒有新 API 邊界
新 package	概念可獨立、需要被其他 package 使用	import 後呼叫 exported 名稱	成本較高，需要設計 API

例如 message.go 只是放一些內部型別時，可以留在 package main：

1package main
2
3type message struct {
4    Title string
5    Body  string
6}

如果 notification 概念開始有自己的建構規則、驗證規則與測試需求，就可以搬成獨立 package：

1notify/
2├── go.mod
3├── main.go
4└── notification/
5    ├── notification.go
6    └── validate.go

此時 notification package 要明確決定哪些名稱是對外 API。

【執行】跨 package 呼叫需要 import 與 exported 名稱

跨 package 呼叫的核心規則是：其他 package 只能使用大寫開頭的 exported 名稱，並且必須透過 import path 引入。

假設 module path 是：

1module example.com/notify

notification/notification.go 可以這樣寫：

 1package notification
 2
 3import "strings"
 4
 5type Notification struct {
 6    Title string
 7    Body  string
 8}
 9
10func New(title, body string) Notification {
11    return Notification{
12        Title: strings.TrimSpace(title),
13        Body:  strings.TrimSpace(body),
14    }
15}
16
17func isEmpty(n Notification) bool {
18    return n.Title == "" && n.Body == ""
19}

main.go 要使用這個 package，必須 import：

 1package main
 2
 3import (
 4    "fmt"
 5
 6    "example.com/notify/notification"
 7)
 8
 9func main() {
10    n := notification.New("Deploy finished", "Version 1.2.0 is live")
11    fmt.Println(n.Title)
12}

notification.New 和 notification.Notification 可以被外部使用，因為它們是大寫開頭。isEmpty 不能被 main.go 呼叫，因為它是 package 內部實作細節。

【判讀】import cycle 是依賴方向錯了

import cycle 的核心意義是兩個 package 互相依賴，Go 會直接拒絕編譯。Go 工具鏈透過這個限制強迫你把依賴方向想清楚。

例如這種結構容易出問題：

1notify/
2├── main.go
3├── handler/
4│   └── handler.go
5└── notification/
6    └── notification.go

如果 handler import notification，同時 notification 又 import handler，就會形成循環依賴。

1handler -> notification -> handler

修正的核心做法是讓低層概念不要依賴高層協定。notification 應該描述通知資料與規則，不應知道 HTTP handler；handler 可以把 HTTP request 轉成 notification command 或 value。

1handler -> notification

這個方向比「互相知道」更容易測試，也更容易重構。

常見拆分路線

Go 服務常見的成長路線是漸進式的。每一步都應該解決當下的閱讀、測試或依賴問題，而不是為了看起來正式。

階段一：單一檔案

1notify/
2├── go.mod
3└── main.go

適合小工具、實驗程式、剛開始的服務雛形。

階段二：同 package 多檔案

1notify/
2├── go.mod
3├── main.go
4├── config.go
5├── server.go
6└── notification.go

適合 main.go 開始太長，但概念還沒有明確 API 邊界的階段。

階段三：多 package

 1notify/
 2├── go.mod
 3├── main.go
 4├── config/
 5│   └── config.go
 6├── notification/
 7│   ├── notification.go
 8│   └── validate.go
 9└── transport/
10    └── http.go

適合設定、通知規則、HTTP transport 已經能清楚分成不同責任的階段。

階段四：服務邊界更清楚

1notify/
2├── go.mod
3├── cmd/
4│   └── notify-server/
5│       └── main.go
6└── internal/
7    ├── notification/
8    ├── transport/
9    └── storage/

適合服務已經有明確部署入口、內部 package 不想被外部 module 引用的階段。這是程式長大後的選擇。

設計檢查

檢查一：檔案切分跟著 Go package 模型

Go 的檔案不是 class。把每個 struct 都拆成一個檔案，通常只會增加跳轉成本，不會讓設計更清楚。

檢查二：資料夾跟著邊界成長

程式還小時就建立 domain、application、infrastructure，會讓讀者先學資料夾，再學行為本身。Go 更適合先讓程式跑起來，再根據壓力拆邊界。

檢查三：exported 名稱代表公開承諾

exported 名稱就是 package 對外承諾。還不確定會被外部使用的型別與函式，先保持 unexported，等 API 真的穩定再開放。

1.6 函式、方法與 receiver

Wed, 22 Apr 2026 00:00:00 +0000

Go 沒有 class，但有函式、struct 與方法。方法只是帶有 receiver 的函式；receiver 讓函式和某個型別形成關聯，進而表達「這個行為屬於這個資料」。

本章目標

學完本章後，你將能夠：

區分普通函式與方法
理解 receiver 的語法與語義
判斷何時使用 pointer receiver
用建構函式集中初始化規則

【觀察】普通函式不屬於特定值

普通函式的核心規則是：它不綁定特定型別，只接收參數並回傳結果。以下函式只負責把名稱正規化：

1func NormalizeName(name string) string {
2 return strings.TrimSpace(strings.ToLower(name))
3}

呼叫方式：

1name := NormalizeName(" Alice ")

這種函式適合描述純粹轉換：輸入什麼，輸出什麼，不需要修改某個物件的內部狀態。

【判讀】方法是帶 receiver 的函式

方法的核心規則是：函式若需要以某個型別作為操作對象，就用 receiver 綁到該型別。行為和某個型別密切相關時，可以寫成方法：

 1type Counter struct {
 2 value int
 3}
 4
 5func (c *Counter) Inc() {
 6 c.value++
 7}
 8
 9func (c Counter) Value() int {
10 return c.value
11}

(c *Counter) 和 (c Counter) 就是 receiver。它放在 func 和方法名稱之間，表示這個函式是 Counter 的方法。receiver 只表示「這個函式以這個型別作為操作對象」，不代表繼承關係 — Go 沒有類別繼承，方法只是綁定到型別的函式。

呼叫方式：

1var c Counter
2c.Inc()
3fmt.Println(c.Value())

Go 會讓方法呼叫看起來像物件操作，但本質仍然是函式呼叫。

【策略】用是否修改狀態選擇 receiver

receiver 選擇的核心規則是：要修改原值用 pointer receiver，不修改且型別小可以用 value receiver。receiver 有兩種常見形式：

receiver	適用情境
value receiver	不修改原值，型別小，複製成本低
pointer receiver	需要修改原值，或型別較大，避免複製

例如 Value() 不修改 Counter，可以用 value receiver：

1func (c Counter) Value() int {
2 return c.value
3}

Inc() 需要修改原本的 counter，所以使用 pointer receiver：

1func (c *Counter) Inc() {
2 c.value++
3}

如果你不確定，先問一個問題：這個方法是否要改變 receiver 的狀態？答案是 yes，通常就用 pointer receiver。

【執行】用建構函式集中初始化

建構函式的核心用途是集中初始化規則。Go 沒有 constructor 關鍵字，但慣例會用 NewTypeName 建立需要初始化的型別：

 1type Cache struct {
 2 items map[string]string
 3}
 4
 5func NewCache() *Cache {
 6 return &Cache{
 7 items: make(map[string]string),
 8 }
 9}
10
11func (c *Cache) Set(key, value string) {
12 c.items[key] = value
13}
14
15func (c *Cache) Get(key string) (string, bool) {
16 value, ok := c.items[key]
17 return value, ok
18}

使用方式：

1cache := NewCache()
2cache.Set("theme", "dark")
3value, ok := cache.Get("theme")

這裡 NewCache() 的價值是保證 items 一定被初始化。呼叫者不需要知道 Cache 內部有 map，也不需要記得手動 make。

函式還是方法？

函式與方法的選擇規則是：純轉換用函式，依賴型別狀態用方法，需要初始化保證用 NewTypeName。可以用這張表判斷：

問題	選擇
只是轉換資料？	普通函式
行為依賴某個型別的狀態？	方法
需要保證初始化規則？	`NewTypeName` 建構函式
需要符合 interface？	方法

範例：

1func ParsePort(raw string) (int, error) {
2 // 純資料轉換，適合普通函式
3}
4
5func (s *Server) Start() error {
6 // 啟動 Server，適合方法
7}

模組六：實戰指南

Tue, 20 Jan 2026 00:00:00 +0000

本模組將前五個模組的知識整合起來，透過三個實戰案例，教你如何在 Hook 系統中進行實際開發。

章節列表

章節	主題	關鍵收穫
6.1	如何新增一個 Hook	完整開發流程
6.2	如何擴展共用模組	模組設計與整合
6.3	如何新增語言解析器	繼承 ABC 實作

前置要求

建議先完成以下模組：

模組一：理解 Python 模組系統
模組二：掌握型別提示
模組四：了解抽象基類（對於 6.3）
模組五：掌握測試技巧

實戰流程預覽

新增 Hook 的完整流程

11. 確定 Hook 類型和觸發時機
22. 建立腳本檔案
33. 實作核心邏輯
44. 設定 Claude Code 配置
55. 撰寫測試
66. 更新文件

擴展共用模組的流程

11. 分析需求和現有架構
22. 設計新功能介面
33. 實作並保持向後相容
44. 更新所有使用者
55. 撰寫測試

新增解析器的流程

11. 繼承 BaseParser
22. 實作 parse 方法
33. 註冊到 ParserFactory
44. 撰寫測試

學習時間

每章節約 30-45 分鐘，全模組約 90-135 分鐘

1.7 從入口程式看應用啟動流程

Wed, 22 Apr 2026 00:00:00 +0000

入口程式是 Go 應用的系統地圖。它不一定包含最多細節，但應該讓你知道 process 如何初始化、哪些 goroutine 會啟動、HTTP endpoint 如何註冊，以及程式如何關閉。

本章目標

學完本章後，你將能夠：

用啟動流程理解 Go 應用結構
看懂 channel 與元件之間的資料流
理解 context.WithCancel 在關閉流程中的角色
判斷新增功能應該接在哪個生命週期位置

【觀察】入口流程分成五段

入口程式的核心責任是揭露應用如何啟動，而不是承載所有實作細節。一個稍具規模的 main() 可以切成五個區塊：

區塊	責任
Runtime 與日誌設定	設定記憶體限制、初始化 `slog`
環境設定	讀取設定檔、環境變數與 port
元件組裝	建立 repository、worker、service 或 server
背景工作	啟動 worker、queue consumer 或定時任務
對外介面	註冊 CLI command、HTTP endpoint 或 WebSocket route

這種切法讓入口同時保留完整脈絡，又不把所有實作細節塞進 main()。

【判讀】`main()` 的價值是揭露依賴關係

main() 的核心價值是讓依賴關係可見。Go 專案常把依賴直接組裝在 main()，好處是維護者能直接看到應用骨架：

1events := make(chan Event, 128)
2notifications := make(chan Notification, 128)
3
4repo := NewNotificationRepository()
5worker := NewWorker(repo, events, notifications)
6server := NewHTTPServer(repo, notifications)

這段程式揭露一個重要事實：repo 負責保存共享狀態，worker 負責處理背景事件，server 負責提供 HTTP 入口。資料如何流動，不需要先查框架設定就能看懂。

【策略】用生命週期判斷功能應該放哪裡

新增功能的核心判斷是：先確認它屬於哪一種生命週期，再決定接入位置。新增功能時，先判斷它屬於哪一種生命週期：

新功能類型	接入位置
新 HTTP endpoint	入口程式註冊 route，實作獨立 handler
新背景事件來源	新增 channel、worker 或 queue consumer
新即時訊息 action	message router 或連線管理元件
新狀態欄位	repository 更新與 model 擴展
新診斷能力	條件註冊 endpoint 或 `slog` 欄位

這個判斷可以避免把功能塞進錯誤元件，造成後續難測與難改。

【執行】完整啟動路徑

啟動路徑的核心用途是提供除錯地圖。一個有背景工作與 HTTP 介面的 Go 應用，啟動後的主要路徑可能如下：

 1main()
 2 ├─ setup logger / runtime
 3 ├─ create channels
 4 ├─ create repository / worker / server
 5 ├─ context.WithCancel()
 6 ├─ go worker.Run(ctx)
 7 ├─ go startPeriodicSync(ctx)
 8 ├─ go server.Run(ctx)
 9 ├─ register /health
10 ├─ register /ws
11 ├─ register /events
12 ├─ go waitForShutdown(cancel, ...)
13 └─ http.Server.ListenAndServe()

這份路徑也是除錯清單。當應用沒有產生預期輸出時，可以依序確認：輸入來源是否產生資料、worker 是否處理資料、對外介面是否有 client 或呼叫者、狀態資料是否被正確更新。

Basics on Tarragon

1.1 Go 專案結構與 module

本章目標

【觀察】go.mod 定義 module

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

【策略】先分辨三種 import

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

模組一：Go 基礎概念

章節列表

本模組使用的範例主題

預備知識

學習時間

1.1 Python 哲學與設計理念

Python 之禪

實踐中的 Python 哲學

顯式優於隱式（Explicit is better than implicit）

可讀性很重要（Readability counts）

簡單優於複雜（Simple is better than complex）

扁平優於巢狀（Flat is better than nested）

「Pythonic」的含義

使用 List Comprehension

使用上下文管理器

使用 enumerate 而非 range(len())

實際範例：Hook 系統的設計體現

6.1 如何新增一個 Hook

前置知識

Hook 系統概述

步驟 1：建立基本結構

使用 UV 單檔模式

路徑設定

步驟 2：處理輸入輸出

SessionStart Hook 範例

PreToolUse/PostToolUse Hook 範例

步驟 3：使用共用模組

Git 工具

日誌系統

輸入輸出

步驟 4：註冊 Hook

步驟 5：撰寫測試

完整範例：檔案類型檢查 Hook

開發檢查清單

常見問題

Q: Hook 執行失敗會影響 Claude 嗎？

Q: 如何調試 Hook？

Q: Hook 執行順序是什麼？

思考題

模組一：Python 基礎概念

章節列表

實際範例來源

預備知識

學習時間

1.2 從單一 script 到多檔案專案

本章目標

章節大綱

1. 單一 script 是合理起點

2. 拆成同層 module

3. 整理成 package

4. 執行方式會影響 import

5. 測試會推動專案結構

6. 何時進入可安裝專案與 src/ layout

後續補寫時的比較提示

本章不處理

和 Python 教材的關係

小結

1.2 變數、零值與短變數宣告

變數一定有型別

零值讓變數可立即使用

var 適合宣告意圖

:= 適合區域初始化

型別推斷不等於放棄型別

指標、slice 與 map 的零值差異

1.3 控制流程：if、for、switch

if 表達條件與提前返回

if 可以包含短宣告

提前返回讓主流程靠左

for 是唯一迴圈語法

range 用來走訪集合

break 與 continue 控制迴圈節奏

switch 表達多分支判斷

1.3 模組與套件組織

【觀察】`go.mod` 定義 module

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

6. 何時進入可安裝專案與 `src/` layout

`var` 適合宣告意圖

`:=` 適合區域初始化

`if` 表達條件與提前返回

`if` 可以包含短宣告

`for` 是唯一迴圈語法

`range` 用來走訪集合

`break` 與 `continue` 控制迴圈節奏

`switch` 表達多分支判斷

`init.py` 的作用

實際範例：Hook 系統的 `init.py`

`init.py` 的三個主要功能

相對導入（使用 `.`）

為什麼用 `insert(0, ...)` 而不是 `append(...)`？

避免 `import *`