模組五：錯誤處理與測試 on Tarragon

5.1 異常處理策略

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

異常處理是撰寫穩健程式碼的關鍵。本章介紹 Python 的異常處理機制，以及 Hook 系統中採用的設計策略。

基本語法

try-except

1try:
2    result = risky_operation()
3except SomeException as e:
4    handle_error(e)

完整結構

 1try:
 2    result = risky_operation()
 3except SpecificError as e:
 4    # 處理特定錯誤
 5    handle_specific_error(e)
 6except (TypeError, ValueError) as e:
 7    # 處理多種錯誤
 8    handle_type_error(e)
 9except Exception as e:
10    # 處理其他所有錯誤
11    handle_unknown_error(e)
12else:
13    # 沒有錯誤時執行
14    process_result(result)
15finally:
16    # 無論如何都執行
17    cleanup()

常見異常類型

異常	發生時機
`FileNotFoundError`	檔案不存在
`PermissionError`	權限不足
`ValueError`	值不合法
`TypeError`	型別不正確
`KeyError`	字典鍵不存在
`IndexError`	索引超出範圍
`JSONDecodeError`	JSON 解析失敗
`TimeoutError`	操作超時

實際範例：Git 命令執行

來自 .claude/lib/git_utils.py：

 1import subprocess
 2from typing import Optional
 3
 4def run_git_command(
 5    args: list[str],
 6    cwd: Optional[str] = None,
 7    timeout: int = 10
 8) -> tuple[bool, str]:
 9    """
10    執行 git 命令並返回結果
11
12    Returns:
13        tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
14    """
15    try:
16        result = subprocess.run(
17            ["git"] + args,
18            cwd=cwd,
19            capture_output=True,
20            text=True,
21            timeout=timeout
22        )
23        if result.returncode == 0:
24            return True, result.stdout.strip()
25        else:
26            return False, result.stderr.strip()
27
28    except subprocess.TimeoutExpired:
29        # 命令超時
30        return False, f"Command timed out after {timeout}s"
31
32    except FileNotFoundError:
33        # git 命令不存在
34        return False, "git command not found"
35
36    except Exception as e:
37        # 其他未預期的錯誤
38        return False, str(e)

設計分析

這個函式展示了 Hook 系統的異常處理策略：

不拋出異常：返回 (bool, str) 元組
捕獲特定異常：分別處理 TimeoutExpired 和 FileNotFoundError
兜底處理：except Exception 捕獲其他錯誤
提供有意義的錯誤訊息：讓呼叫者知道發生了什麼

Hook 系統的異常哲學

為什麼不直接拋出異常？

Hook 腳本需要穩定運行，即使遇到錯誤也要：

給出有意義的反饋
不中斷整個 Claude 工作流程
讓主程式能夠決定如何處理

`(bool, str)` 返回值模式

 1# 函式簽名
 2def validate_something() -> tuple[bool, str]:
 3    """
 4    Returns:
 5        tuple[bool, str]: (成功與否, 訊息)
 6    """
 7    pass
 8
 9# 使用方式
10success, message = validate_something()
11if success:
12    print(f"成功: {message}")
13else:
14    print(f"失敗: {message}")

實際應用

 1def read_hook_input() -> dict:
 2    """
 3    從 stdin 讀取 Hook 輸入
 4
 5    Returns:
 6        dict: 解析後的 JSON 資料，解析失敗時返回空字典
 7    """
 8    try:
 9        return json.load(sys.stdin)
10    except json.JSONDecodeError:
11        return {}  # 不拋出異常，返回安全的預設值
12    except Exception:
13        return {}

異常處理策略

策略 1：捕獲並轉換

將異常轉換為返回值：

1def safe_divide(a: float, b: float) -> tuple[bool, float]:
2    try:
3        return True, a / b
4    except ZeroDivisionError:
5        return False, 0.0

策略 2：捕獲並記錄

記錄後繼續執行：

 1def process_files(files: list[str]) -> list[str]:
 2    results = []
 3    for file in files:
 4        try:
 5            result = process_file(file)
 6            results.append(result)
 7        except Exception as e:
 8            logger.error(f"Failed to process {file}: {e}")
 9            # 繼續處理其他檔案
10    return results

策略 3：捕獲並重新拋出

添加上下文後重新拋出：

1def load_config(path: str) -> dict:
2    try:
3        with open(path) as f:
4            return json.load(f)
5    except FileNotFoundError:
6        raise FileNotFoundError(f"Config file not found: {path}")
7    except json.JSONDecodeError as e:
8        raise ValueError(f"Invalid JSON in {path}: {e}")

策略 4：使用預設值

提供安全的預設值：

1def get_config_value(config: dict, key: str, default: str = "") -> str:
2    try:
3        return config[key]
4    except KeyError:
5        return default

最佳實踐

1. 具體優於籠統

 1# 好：捕獲具體異常
 2try:
 3    data = json.load(f)
 4except json.JSONDecodeError:
 5    data = {}
 6
 7# 不好：捕獲所有異常
 8try:
 9    data = json.load(f)
10except Exception:  # 可能隱藏其他問題
11    data = {}

2. 保留原始異常資訊

 1# 好：保留原始異常
 2try:
 3    process()
 4except ValueError as e:
 5    raise RuntimeError(f"Processing failed: {e}") from e
 6
 7# 不好：丟失原始資訊
 8try:
 9    process()
10except ValueError:
11    raise RuntimeError("Processing failed")

3. 使用 finally 清理資源

 1f = None
 2try:
 3    f = open("file.txt")
 4    process(f)
 5except IOError:
 6    handle_error()
 7finally:
 8    if f:
 9        f.close()  # 確保關閉檔案
10
11# 更好：使用 with 語句
12with open("file.txt") as f:
13    process(f)  # 自動關閉

4. 不要靜默忽略異常

 1# 不好：完全忽略錯誤
 2try:
 3    risky_operation()
 4except Exception:
 5    pass  # 什麼都不做
 6
 7# 好：至少記錄一下
 8try:
 9    risky_operation()
10except Exception as e:
11    logger.warning(f"Operation failed (ignored): {e}")

自訂異常

 1class HookError(Exception):
 2    """Hook 基礎異常"""
 3    pass
 4
 5class ValidationError(HookError):
 6    """驗證錯誤"""
 7    pass
 8
 9class ConfigurationError(HookError):
10    """配置錯誤"""
11    pass
12
13# 使用
14def validate_hook(path: str) -> None:
15    if not path.endswith(".py"):
16        raise ValidationError(f"Invalid hook file: {path}")

思考題

為什麼 run_git_command 不直接拋出異常？
什麼情況下應該使用 except Exception？
from e 在 raise ... from e 中的作用是什麼？

實作練習

重構一個使用異常的函式，改為返回 (bool, str) 模式
實作一個函式，嘗試多種方式載入配置（JSON、YAML、預設值）
寫一個裝飾器，自動捕獲異常並轉換為返回值

下一章：返回值設計

5.2 返回值設計

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

Hook 系統採用 (bool, str) 返回值模式，這是一種替代異常處理的設計策略。本章深入探討這個模式的設計理念和最佳實踐。

(bool, str) 模式

基本形式

 1def validate_something() -> tuple[bool, str]:
 2 """
 3 Returns:
 4 tuple[bool, str]:
 5 - (True, "成功訊息") - 操作成功
 6 - (False, "錯誤訊息") - 操作失敗
 7 """
 8 if some_condition:
 9 return True, "驗證通過"
10 return False, "驗證失敗：原因說明"

使用方式

1success, message = validate_something()
2if success:
3 print(f"成功: {message}")
4else:
5 print(f"失敗: {message}")
6 # 決定如何處理錯誤

實際範例：Git 命令

來自 .claude/lib/git_utils.py：

 1def run_git_command(
 2 args: list[str],
 3 cwd: Optional[str] = None,
 4 timeout: int = 10
 5) -> tuple[bool, str]:
 6 """
 7 執行 git 命令並返回結果
 8
 9 Args:
10 args: git 命令參數列表
11 cwd: 執行目錄
12 timeout: 超時時間（秒）
13
14 Returns:
15 tuple[bool, str]: (是否成功, 輸出或錯誤訊息)
16 """
17 try:
18 result = subprocess.run(
19 ["git"] + args,
20 cwd=cwd,
21 capture_output=True,
22 text=True,
23 timeout=timeout
24 )
25 if result.returncode == 0:
26 return True, result.stdout.strip()
27 else:
28 return False, result.stderr.strip()
29 except subprocess.TimeoutExpired:
30 return False, f"Command timed out after {timeout}s"
31 except FileNotFoundError:
32 return False, "git command not found"

使用這個函式

1def get_current_branch() -> Optional[str]:
2 """獲取當前分支名稱"""
3 success, output = run_git_command(["branch", "--show-current"])
4 return output if success and output else None
5
6def get_project_root() -> str:
7 """獲取專案根目錄"""
8 success, output = run_git_command(["rev-parse", "--show-toplevel"])
9 return output if success else os.getcwd()

為什麼選擇這個模式？

優點

明確的錯誤處理

1# 呼叫者必須處理兩種情況
2success, message = validate()
3if not success:
4 # 必須處理錯誤
5 pass

錯誤訊息保留

1# 錯誤訊息可以傳遞給使用者
2success, error = run_command()
3if not success:
4 logger.error(error)
5 return create_error_response(error)

不中斷執行流程

1# 可以收集所有錯誤
2errors = []
3for file in files:
4 success, message = process(file)
5 if not success:
6 errors.append(message)

與異常的比較

特性	(bool, str)	異常
強制處理	是（需要解包）	否（可能被忽略）
控制流程	不中斷	中斷
效能	較好	較差（stack trace）
適合場景	預期的錯誤	非預期的錯誤

設計變體

(bool, T) - 通用型別

1from typing import TypeVar, Tuple
2
3T = TypeVar("T")
4
5def parse_json(text: str) -> Tuple[bool, dict]:
6 try:
7 return True, json.loads(text)
8 except json.JSONDecodeError as e:
9 return False, {"error": str(e)}

(T | None) - 成功返回值，失敗返回 None

1def find_config(name: str) -> Optional[dict]:
2 """找不到時返回 None"""
3 path = get_config_path(name)
4 if not path.exists():
5 return None
6 return load_config(path)

Result 類別（進階）

 1from dataclasses import dataclass
 2from typing import Generic, TypeVar
 3
 4T = TypeVar("T")
 5
 6@dataclass
 7class Result(Generic[T]):
 8 success: bool
 9 value: Optional[T] = None
10 error: Optional[str] = None
11
12 @classmethod
13 def ok(cls, value: T) -> "Result[T]":
14 return cls(success=True, value=value)
15
16 @classmethod
17 def fail(cls, error: str) -> "Result[T]":
18 return cls(success=False, error=error)
19
20# 使用
21def divide(a: int, b: int) -> Result[float]:
22 if b == 0:
23 return Result.fail("Division by zero")
24 return Result.ok(a / b)
25
26result = divide(10, 2)
27if result.success:
28 print(result.value) # 5.0
29else:
30 print(result.error)

實際應用模式

鏈式操作

 1def process_pipeline(data: str) -> Tuple[bool, str]:
 2 # 第一步
 3 success, result = step_one(data)
 4 if not success:
 5 return False, f"Step 1 failed: {result}"
 6
 7 # 第二步
 8 success, result = step_two(result)
 9 if not success:
10 return False, f"Step 2 failed: {result}"
11
12 # 第三步
13 success, result = step_three(result)
14 if not success:
15 return False, f"Step 3 failed: {result}"
16
17 return True, result

收集多個錯誤

 1def validate_all(items: list[str]) -> Tuple[bool, list[str]]:
 2 errors = []
 3 for item in items:
 4 success, message = validate_item(item)
 5 if not success:
 6 errors.append(message)
 7
 8 if errors:
 9 return False, errors
10 return True, []

帶上下文的錯誤

 1def run_with_context(
 2 command: str
 3) -> Tuple[bool, str]:
 4 """執行命令並提供上下文"""
 5 try:
 6 result = execute(command)
 7 return True, result
 8 except Exception as e:
 9 context = f"Command: {command}\nError: {e}"
10 return False, context

Hook 系統的應用

Hook 輸入讀取

1def read_hook_input() -> dict:
2 """
3 從 stdin 讀取輸入
4 失敗時返回空字典（而非拋出異常）
5 """
6 try:
7 return json.load(sys.stdin)
8 except json.JSONDecodeError:
9 return {}

分支驗證

1def validate_branch(branch: str) -> Tuple[bool, str]:
2 """驗證分支是否可以編輯"""
3 if is_protected_branch(branch):
4 return False, f"Cannot edit protected branch: {branch}"
5 if not is_allowed_branch(branch):
6 return False, f"Branch not in allowed list: {branch}"
7 return True, f"Branch {branch} is valid"

最佳實踐

1. 訊息要有意義

1# 好：提供具體資訊
2return False, f"Config file not found: {path}"
3
4# 不好：模糊的訊息
5return False, "Error"

2. 保持一致性

1# 好：整個模組使用相同模式
2def func_a() -> Tuple[bool, str]: ...
3def func_b() -> Tuple[bool, str]: ...
4def func_c() -> Tuple[bool, str]: ...
5
6# 不好：混合使用
7def func_a() -> Tuple[bool, str]: ...
8def func_b() -> Optional[str]: ... # 不一致
9def func_c(): ... # 可能拋出異常

3. 文檔說明返回值

 1def validate(data: str) -> Tuple[bool, str]:
 2 """
 3 驗證資料格式
 4
 5 Returns:
 6 tuple[bool, str]:
 7 - (True, "Validation passed") - 驗證成功
 8 - (False, error_message) - 驗證失敗，包含原因
 9 """
10 ...

思考題

什麼情況下應該使用 (bool, str) 而不是異常？
如何處理需要返回多種錯誤類型的情況？
(bool, str) 模式如何與型別檢查工具配合？

實作練習

重構一個使用異常的函式，改為 (bool, str) 模式
實作一個 Result 類別，支援 map 和 flat_map 操作
寫一個函式，執行多個驗證並收集所有錯誤

上一章：異常處理策略 下一章：unittest 基礎

5.3 unittest 基礎

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

unittest 是 Python 內建的測試框架，提供了測試組織、斷言和測試執行等功能。Hook 系統的測試都使用 unittest 撰寫。

基本結構

最簡單的測試

 1import unittest
 2
 3class TestCalculator(unittest.TestCase):
 4
 5 def test_add(self):
 6 result = 1 + 1
 7 self.assertEqual(result, 2)
 8
 9 def test_subtract(self):
10 result = 5 - 3
11 self.assertEqual(result, 2)
12
13if __name__ == "__main__":
14 unittest.main()

執行測試：

1$ python -m unittest test_calculator.py
2..
3----------------------------------------------------------------------
4Ran 2 tests in 0.001s
5
6OK

測試類別結構

 1import unittest
 2
 3class TestMyModule(unittest.TestCase):
 4
 5 @classmethod
 6 def setUpClass(cls):
 7 """在所有測試前執行一次"""
 8 cls.shared_resource = create_expensive_resource()
 9
10 @classmethod
11 def tearDownClass(cls):
12 """在所有測試後執行一次"""
13 cls.shared_resource.cleanup()
14
15 def setUp(self):
16 """在每個測試前執行"""
17 self.test_data = {"key": "value"}
18
19 def tearDown(self):
20 """在每個測試後執行"""
21 self.test_data = None
22
23 def test_something(self):
24 """測試方法必須以 test_ 開頭"""
25 self.assertTrue(True)

常用斷言方法

方法	檢查
`assertEqual(a, b)`	a == b
`assertNotEqual(a, b)`	a != b
`assertTrue(x)`	x is True
`assertFalse(x)`	x is False
`assertIs(a, b)`	a is b
`assertIsNone(x)`	x is None
`assertIn(a, b)`	a in b
`assertIsInstance(a, b)`	isinstance(a, b)
`assertRaises(Error)`	拋出指定異常

實際範例：測試 Hook IO

來自 .claude/lib/tests/test_hook_io.py：

 1import json
 2import sys
 3import unittest
 4from io import StringIO
 5from unittest.mock import patch
 6
 7# 導入被測試的模組
 8sys.path.insert(0, str(Path(__file__).parent.parent))
 9from hook_io import (
 10 read_hook_input,
 11 write_hook_output,
 12 create_pretooluse_output,
 13 create_posttooluse_output,
 14)
 15
 16
 17class TestReadHookInput(unittest.TestCase):
 18 """測試 read_hook_input 函式"""
 19
 20 def test_valid_json_input(self):
 21 """測試有效的 JSON 輸入"""
 22 test_data = {"tool_name": "Write", "file_path": "/test.txt"}
 23 json_input = json.dumps(test_data)
 24
 25 with patch("sys.stdin", StringIO(json_input)):
 26 result = read_hook_input()
 27
 28 self.assertEqual(result, test_data)
 29
 30 def test_invalid_json_returns_empty_dict(self):
 31 """測試無效的 JSON 應返回空字典"""
 32 with patch("sys.stdin", StringIO("not valid json")):
 33 result = read_hook_input()
 34
 35 self.assertEqual(result, {})
 36
 37 def test_empty_input_returns_empty_dict(self):
 38 """測試空輸入應返回空字典"""
 39 with patch("sys.stdin", StringIO("")):
 40 result = read_hook_input()
 41
 42 self.assertEqual(result, {})
 43
 44
 45class TestWriteHookOutput(unittest.TestCase):
 46 """測試 write_hook_output 函式"""
 47
 48 def test_output_json_format(self):
 49 """測試輸出為有效的 JSON 格式"""
 50 test_data = {"decision": "allow", "reason": "OK"}
 51
 52 with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
 53 write_hook_output(test_data)
 54 output = mock_stdout.getvalue()
 55
 56 parsed = json.loads(output)
 57 self.assertEqual(parsed["decision"], "allow")
 58
 59 def test_chinese_characters_preserved(self):
 60 """測試中文字元被保留"""
 61 test_data = {"message": "你好"}
 62
 63 with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
 64 write_hook_output(test_data, ensure_ascii=False)
 65 output = mock_stdout.getvalue()
 66
 67 self.assertIn("你好", output)
 68
 69
 70class TestCreatePretoolueOutput(unittest.TestCase):
 71 """測試 create_pretooluse_output 函式"""
 72
 73 def test_basic_output_structure(self):
 74 """測試基本輸出結構"""
 75 result = create_pretooluse_output(
 76 decision="allow",
 77 reason="Test reason"
 78 )
 79
 80 self.assertIn("hookSpecificOutput", result)
 81 self.assertEqual(
 82 result["hookSpecificOutput"]["permissionDecision"],
 83 "allow"
 84 )
 85
 86 def test_with_user_prompt(self):
 87 """測試包含 userPrompt 的輸出"""
 88 result = create_pretooluse_output(
 89 decision="ask",
 90 reason="Need confirmation",
 91 user_prompt="Continue?"
 92 )
 93
 94 self.assertEqual(
 95 result["hookSpecificOutput"]["userPrompt"],
 96 "Continue?"
 97 )
 98
 99
100if __name__ == "__main__":
101 unittest.main()

測試異常

assertRaises

 1def test_raises_value_error(self):
 2 """測試函式是否拋出 ValueError"""
 3 with self.assertRaises(ValueError):
 4 int("not a number")
 5
 6def test_raises_with_message(self):
 7 """測試異常訊息"""
 8 with self.assertRaises(ValueError) as context:
 9 raise ValueError("invalid input")
10
11 self.assertIn("invalid", str(context.exception))

測試檔案操作

使用臨時檔案

 1import tempfile
 2import unittest
 3
 4class TestFileOperations(unittest.TestCase):
 5
 6 def test_read_file(self):
 7 """測試檔案讀取"""
 8 with tempfile.NamedTemporaryFile(
 9 mode="w",
10 suffix=".txt",
11 delete=False
12 ) as f:
13 f.write("test content")
14 temp_path = f.name
15
16 try:
17 result = read_file(temp_path)
18 self.assertEqual(result, "test content")
19 finally:
20 os.unlink(temp_path)

使用臨時目錄

 1import tempfile
 2import unittest
 3
 4class TestDirectoryOperations(unittest.TestCase):
 5
 6 def setUp(self):
 7 self.temp_dir = tempfile.mkdtemp()
 8
 9 def tearDown(self):
10 import shutil
11 shutil.rmtree(self.temp_dir)
12
13 def test_create_file(self):
14 file_path = os.path.join(self.temp_dir, "test.txt")
15 create_file(file_path, "content")
16 self.assertTrue(os.path.exists(file_path))

執行測試

執行單一測試檔案

1python -m unittest tests/test_hook_io.py

執行單一測試類別

1python -m unittest tests.test_hook_io.TestReadHookInput

執行單一測試方法

1python -m unittest tests.test_hook_io.TestReadHookInput.test_valid_json_input

執行所有測試

1python -m unittest discover -s tests -p "test_*.py"

詳細輸出

1python -m unittest -v tests/test_hook_io.py

測試組織

目錄結構

 1.claude/lib/
 2├── __init__.py
 3├── git_utils.py
 4├── hook_io.py
 5├── hook_logging.py
 6└── tests/
 7 ├── __init__.py
 8 ├── test_git_utils.py
 9 ├── test_hook_io.py
10 └── test_hook_logging.py

命名慣例

測試檔案：test_<module>.py
測試類別：Test<ClassName>
測試方法：test_<behavior>

1# test_git_utils.py
2class TestRunGitCommand(unittest.TestCase):
3 def test_successful_command_returns_true(self):
4 ...
5 def test_failed_command_returns_false(self):
6 ...
7 def test_timeout_returns_error_message(self):
8 ...

最佳實踐

1. 一個測試驗證一件事

 1# 好：每個測試只驗證一個行為
 2def test_valid_input_returns_true(self):
 3 result = validate("valid")
 4 self.assertTrue(result)
 5
 6def test_invalid_input_returns_false(self):
 7 result = validate("invalid")
 8 self.assertFalse(result)
 9
10# 不好：一個測試驗證多件事
11def test_validate(self):
12 self.assertTrue(validate("valid"))
13 self.assertFalse(validate("invalid"))
14 self.assertEqual(validate(""), None)

2. 使用描述性的測試名稱

1# 好：清楚說明測試內容
2def test_empty_input_returns_empty_dict(self):
3 ...
4
5# 不好：模糊的名稱
6def test_input(self):
7 ...

3. 使用 setUp 避免重複

 1class TestMarkdownChecker(unittest.TestCase):
 2
 3 def setUp(self):
 4 self.checker = MarkdownLinkChecker()
 5 self.test_content = "# Test\n[link](/python/05-error-testing/unittest/file.md)"
 6
 7 def test_check_valid_link(self):
 8 # 使用 setUp 中建立的物件
 9 result = self.checker.check(self.test_content)
10 ...

思考題

setUp 和 setUpClass 有什麼區別？什麼時候用哪個？
為什麼測試方法必須以 test_ 開頭？
如何測試一個需要讀取 stdin 的函式？

實作練習

為 get_current_branch() 函式撰寫測試
測試一個會拋出異常的函式
使用 unittest.skip 暫時跳過某個測試

上一章：異常處理策略 下一章：Mock 與測試隔離

5.4 Mock 與測試隔離

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

當測試的程式碼依賴外部資源（檔案系統、網路、stdin/stdout）時，我們需要使用 Mock 來隔離這些依賴，確保測試的可靠性和速度。

為什麼需要 Mock？

問題場景

1def read_hook_input() -> dict:
2    """從 stdin 讀取 JSON 輸入"""
3    return json.load(sys.stdin)
4
5# 測試時如何提供 stdin？

使用 Mock 解決

 1from unittest.mock import patch
 2from io import StringIO
 3
 4def test_read_hook_input():
 5    json_input = '{"key": "value"}'
 6
 7    # 用 StringIO 替換 sys.stdin
 8    with patch("sys.stdin", StringIO(json_input)):
 9        result = read_hook_input()
10
11    assert result == {"key": "value"}

unittest.mock 基礎

patch 裝飾器

1from unittest.mock import patch
2
3class TestMyFunction(unittest.TestCase):
4
5    @patch("module.function_to_mock")
6    def test_something(self, mock_func):
7        mock_func.return_value = "mocked result"
8        result = my_function()
9        self.assertEqual(result, "expected")

patch 上下文管理器

1def test_something(self):
2    with patch("module.function") as mock_func:
3        mock_func.return_value = "mocked"
4        result = my_function()
5        self.assertEqual(result, "expected")

實際範例：測試 Hook IO

來自 .claude/lib/tests/test_hook_io.py：

 1import json
 2import unittest
 3from io import StringIO
 4from unittest.mock import patch
 5
 6from hook_io import read_hook_input, write_hook_output
 7
 8
 9class TestReadHookInput(unittest.TestCase):
10    """測試 read_hook_input 函式"""
11
12    def test_valid_json_input(self):
13        """測試有效的 JSON 輸入"""
14        test_data = {"tool_name": "Write", "file_path": "/test.txt"}
15        json_input = json.dumps(test_data)
16
17        # Mock sys.stdin
18        with patch("sys.stdin", StringIO(json_input)):
19            result = read_hook_input()
20
21        self.assertEqual(result, test_data)
22
23    def test_invalid_json_returns_empty_dict(self):
24        """測試無效的 JSON"""
25        with patch("sys.stdin", StringIO("not valid json")):
26            result = read_hook_input()
27
28        self.assertEqual(result, {})
29
30
31class TestWriteHookOutput(unittest.TestCase):
32    """測試 write_hook_output 函式"""
33
34    def test_output_json_format(self):
35        """測試輸出為有效的 JSON"""
36        test_data = {"decision": "allow"}
37
38        # Mock sys.stdout
39        with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
40            write_hook_output(test_data)
41            output = mock_stdout.getvalue()
42
43        # 驗證輸出是有效的 JSON
44        parsed = json.loads(output)
45        self.assertEqual(parsed["decision"], "allow")
46
47    def test_chinese_preserved(self):
48        """測試中文字元被保留"""
49        test_data = {"message": "你好"}
50
51        with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
52            write_hook_output(test_data, ensure_ascii=False)
53            output = mock_stdout.getvalue()
54
55        self.assertIn("你好", output)

Mock 物件的設定

return_value

1from unittest.mock import Mock
2
3mock_func = Mock()
4mock_func.return_value = 42
5
6result = mock_func()  # 42

side_effect - 動態返回值

 1from unittest.mock import Mock
 2
 3mock_func = Mock()
 4
 5# 依序返回不同值
 6mock_func.side_effect = [1, 2, 3]
 7mock_func()  # 1
 8mock_func()  # 2
 9mock_func()  # 3
10
11# 根據輸入返回不同值
12def side_effect_func(x):
13    return x * 2
14
15mock_func.side_effect = side_effect_func
16mock_func(5)  # 10

side_effect - 拋出異常

1from unittest.mock import Mock
2
3mock_func = Mock()
4mock_func.side_effect = ValueError("Error!")
5
6mock_func()  # 拋出 ValueError

驗證 Mock 被呼叫

 1from unittest.mock import Mock, call
 2
 3mock_func = Mock()
 4
 5# 呼叫 mock
 6mock_func(1, 2, key="value")
 7mock_func(3, 4)
 8
 9# 驗證呼叫
10mock_func.assert_called()              # 被呼叫過
11mock_func.assert_called_once()         # 只被呼叫一次（這會失敗）
12mock_func.assert_called_with(3, 4)     # 最後一次呼叫的參數
13
14# 檢查所有呼叫
15mock_func.assert_has_calls([
16    call(1, 2, key="value"),
17    call(3, 4)
18])
19
20# 呼叫次數
21self.assertEqual(mock_func.call_count, 2)

實際範例：測試 Git 工具

 1import unittest
 2from unittest.mock import patch, Mock
 3
 4from git_utils import run_git_command, get_current_branch
 5
 6
 7class TestRunGitCommand(unittest.TestCase):
 8
 9    @patch("subprocess.run")
10    def test_successful_command(self, mock_run):
11        """測試成功的 git 命令"""
12        # 設定 mock 返回值
13        mock_result = Mock()
14        mock_result.returncode = 0
15        mock_result.stdout = "main\n"
16        mock_result.stderr = ""
17        mock_run.return_value = mock_result
18
19        success, output = run_git_command(["branch", "--show-current"])
20
21        self.assertTrue(success)
22        self.assertEqual(output, "main")
23
24        # 驗證 subprocess.run 被正確呼叫
25        mock_run.assert_called_once()
26        call_args = mock_run.call_args
27        self.assertEqual(call_args[0][0], ["git", "branch", "--show-current"])
28
29    @patch("subprocess.run")
30    def test_failed_command(self, mock_run):
31        """測試失敗的 git 命令"""
32        mock_result = Mock()
33        mock_result.returncode = 1
34        mock_result.stdout = ""
35        mock_result.stderr = "fatal: not a git repository"
36        mock_run.return_value = mock_result
37
38        success, output = run_git_command(["status"])
39
40        self.assertFalse(success)
41        self.assertIn("not a git repository", output)
42
43    @patch("subprocess.run")
44    def test_timeout(self, mock_run):
45        """測試命令超時"""
46        import subprocess
47        mock_run.side_effect = subprocess.TimeoutExpired("git", 10)
48
49        success, output = run_git_command(["status"], timeout=10)
50
51        self.assertFalse(success)
52        self.assertIn("timed out", output)

MagicMock

MagicMock 自動支援魔術方法：

1from unittest.mock import MagicMock
2
3mock = MagicMock()
4
5# 自動支援各種操作
6mock[0]          # 不會報錯
7mock.anything()  # 返回另一個 MagicMock
8len(mock)        # 返回預設值
9str(mock)        # 返回字串

測試檔案操作

使用 mock_open

1from unittest.mock import patch, mock_open
2
3def test_read_config():
4    config_content = '{"key": "value"}'
5
6    with patch("builtins.open", mock_open(read_data=config_content)):
7        result = load_config("config.json")
8
9    self.assertEqual(result["key"], "value")

測試 Path 物件

1from unittest.mock import patch, Mock
2
3def test_check_file_exists():
4    with patch("pathlib.Path.exists") as mock_exists:
5        mock_exists.return_value = True
6
7        result = check_file_exists("/some/path")
8
9        self.assertTrue(result)

patch 的位置

重要：patch 的目標是模組匯入的位置，而非定義的位置。

 1# module_a.py
 2from os import getcwd
 3
 4def my_function():
 5    return getcwd()
 6
 7# test_module_a.py
 8# 正確：patch 匯入的位置
 9@patch("module_a.getcwd")
10def test_my_function(mock_getcwd):
11    ...
12
13# 錯誤：patch 定義的位置
14@patch("os.getcwd")  # 不會生效！
15def test_my_function(mock_getcwd):
16    ...

最佳實踐

1. 只 Mock 外部依賴

1# 好：Mock 外部系統
2@patch("subprocess.run")
3def test_git_command(self, mock_run):
4    ...
5
6# 不好：Mock 內部邏輯
7@patch("my_module.internal_helper")
8def test_my_function(self, mock_helper):
9    ...  # 過度 mock 會讓測試變脆弱

2. 使用 autospec

1from unittest.mock import patch
2
3# autospec 確保 mock 的簽名與原函式相同
4@patch("module.function", autospec=True)
5def test_something(self, mock_func):
6    # 如果呼叫簽名錯誤會報錯
7    mock_func("wrong", "args")  # 可能報錯

3. 清理 Mock

1def setUp(self):
2    self.patcher = patch("module.function")
3    self.mock_func = self.patcher.start()
4
5def tearDown(self):
6    self.patcher.stop()  # 確保清理

思考題

patch 的目標為什麼是匯入位置而非定義位置？
Mock 和 MagicMock 有什麼區別？
什麼時候應該使用 autospec=True？

實作練習

為 get_current_branch() 撰寫使用 Mock 的測試
測試一個讀取檔案的函式，使用 mock_open
測試一個會拋出異常的外部呼叫，使用 side_effect

上一章：unittest 基礎 下一模組：物件導向設計

5.5 頂層例外處理機制

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

前面的章節介紹了異常處理的基本語法和 (bool, str) 返回值模式。本章進入實務層面：當你有 44 個 Hook 腳本，每個都可能在不同地方失敗時，如何建立一套統一的錯誤基礎設施？

這是 W22-W25 開發週期中建立的機制，解決的核心問題是：

Hook 失敗時，錯誤不能靜默消失，也不能讓整個工作流程崩潰。

問題：44 個 Hook，44 種錯誤處理方式

在統一之前，每個 Hook 腳本各自處理例外：

 1# hook_a.py — 用 try-except 包整個 main
 2def main():
 3    try:
 4        do_work()
 5    except Exception as e:
 6        print(f"Error: {e}")
 7        sys.exit(1)
 8
 9# hook_b.py — 完全沒有錯誤處理
10def main():
11    do_work()  # 任何異常直接讓腳本 crash
12
13# hook_c.py — 錯誤寫到檔案但用戶看不到
14def main():
15    try:
16        do_work()
17    except Exception as e:
18        with open("error.log", "a") as f:
19            f.write(str(e))
20        # 用戶完全不知道出錯了

這造成三個問題：

行為不一致：有的 Hook 失敗會中斷流程，有的靜默吞掉
重複程式碼：每個 Hook 各寫一套 try-except
錯誤不可見：某些 Hook 靜默失敗了好幾個 session 才被發現

解決方案：`run_hook_safely`

hook_utils.py 提供了一個頂層例外處理器，所有 Hook 統一使用：

 1def run_hook_safely(main_func: Callable[[], int], hook_name: str) -> int:
 2    """安全執行 Hook 函式，頂層例外處理
 3
 4    Args:
 5        main_func: Hook 主入口函式，必須返回 int
 6        hook_name: Hook 識別名稱
 7
 8    Returns:
 9        int: main_func 的返回值（正常），或 1（異常）
10    """
11    logger = setup_hook_logging(hook_name)
12
13    try:
14        exit_code = main_func()
15        # 驗證返回值是整數
16        if not isinstance(exit_code, int):
17            try:
18                exit_code = int(exit_code)
19            except (ValueError, TypeError):
20                exit_code = 0
21        return exit_code
22    except (KeyboardInterrupt, SystemExit):
23        raise  # 這兩個不攔截
24    except Exception:
25        tb_str = traceback.format_exc()
26        _log_exception(logger, hook_name, tb_str)
27        return EXIT_ERROR

每個 Hook 的使用方式

 1#!/usr/bin/env python3
 2import sys
 3sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 4from hook_utils import run_hook_safely
 5
 6def main() -> int:
 7    # 專注於業務邏輯，不需要處理頂層例外
 8    data = json.load(sys.stdin)
 9    result = validate(data)
10    print(json.dumps(result))
11    return 0
12
13if __name__ == "__main__":
14    sys.exit(run_hook_safely(main, "my-hook-name"))

設計解析

為什麼用 Callable 包裝？

run_hook_safely 接收一個函式，而不是直接包裝程式碼區塊。這個設計有三個好處：

 1# 方式 A：直接包裝（不採用）
 2try:
 3    # 所有程式碼放在這裡
 4    data = read_input()
 5    result = process(data)
 6    output(result)
 7except Exception:
 8    handle_error()
 9
10# 方式 B：函式包裝（採用）
11def main() -> int:
12    data = read_input()
13    result = process(data)
14    output(result)
15    return 0
16
17run_hook_safely(main, "hook-name")

比較	方式 A	方式 B
可重用性	每個 Hook 各寫一次	`run_hook_safely` 寫一次，所有 Hook 共用
測試性	無法單獨測試錯誤處理	可以測試 `run_hook_safely` 的行為
關注點分離	業務邏輯和錯誤處理混在一起	Hook 只寫業務邏輯，錯誤處理交給框架

這就是高階函式在實務中的應用。

為什麼 `KeyboardInterrupt` 和 `SystemExit` 要特別處理？

1except (KeyboardInterrupt, SystemExit):
2    raise  # 不攔截，直接往上傳
3except Exception:
4    # 只攔截「普通」的程式錯誤

Python 的例外繼承結構：

1BaseException
2├── KeyboardInterrupt    ← Ctrl+C
3├── SystemExit           ← sys.exit()
4└── Exception            ← 所有「普通」例外的父類別
5    ├── ValueError
6    ├── TypeError
7    ├── FileNotFoundError
8    └── ...

KeyboardInterrupt 和 SystemExit 不是程式錯誤，它們是控制信號：

KeyboardInterrupt：用戶按了 Ctrl+C，意圖是終止程式
SystemExit：程式碼呼叫了 sys.exit()，意圖是正常退出

如果攔截了這兩個，用戶按 Ctrl+C 程式不會停，sys.exit(0) 也不會退出。這違反了「最小驚訝原則」。

返回值型別驗證

1if not isinstance(exit_code, int):
2    try:
3        exit_code = int(exit_code)
4    except (ValueError, TypeError):
5        exit_code = 0

這段防護處理的是：萬一某個 Hook 的 main() 返回了非整數（例如 None 或字串）。

main() 返回值	處理結果	說明
`0`	`0`	正常
`1`	`1`	正常
`None`	`0`	忘記寫 return
`"0"`	`0`	字串轉整數
`"abc"`	`0`	無法轉換，視為成功

stderr vs stdout：Hook 系統的特殊規則

Claude Code 的 Hook 系統對輸出有特殊解讀：

輸出管道	Claude Code 的解讀
`stdout`	正常訊息，顯示為 `hook success`
`stderr`	錯誤訊息，顯示為 `hook error`

這個行為影響了 _log_exception 的設計：

 1def _log_exception(logger, hook_name, tb_str):
 2    # 1. 寫入日誌檔案（給開發者事後分析）
 3    try:
 4        logger.critical(f"Unhandled exception in {hook_name}")
 5        logger.critical(tb_str)
 6    except Exception as logging_error:
 7        print(f"Failed to log exception: {logging_error}", file=sys.stdout)
 8        print(tb_str, file=sys.stdout)
 9
10    # 2. 輸出到 stderr（讓用戶知道出錯了）
11    print(
12        f"[Hook Error] {hook_name} failed unexpectedly. "
13        f"Check hook logs for details.",
14        file=sys.stderr
15    )

第二行的 stderr 輸出是刻意的。在 W25-005 之前，所有錯誤只寫入日誌檔案，導致 7 個 Hook 靜默失敗了至少 2 個 session 才被發現。加入 stderr 輸出後，用戶會立刻看到 hook error 提示。

實際案例

1# 用戶看到的訊息（W25-005 之前）
2SessionStart:startup hook success: Success     ← 看起來正常
3SessionStart:startup hook success: Success
4# 實際上有 7 個 Hook 在靜默失敗
5
6# W25-005 之後
7SessionStart:startup hook success: Success
8SessionStart:startup hook error: [Hook Error] acceptance-gate-hook failed unexpectedly.
9# 用戶立刻知道有問題

這個教訓的完整記錄在 IMP-003 錯誤模式中，模組七的作用域迴歸案例研究有詳細分析。

日誌系統配置

run_hook_safely 背後依賴 setup_hook_logging 建立日誌系統：

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    """建立並設定 Hook 日誌系統
 3
 4    功能：
 5    - 建立日誌目錄 .claude/hook-logs/{hook_name}/
 6    - 建立日誌檔案 {hook_name}-{YYYYMMDD-HHMMSS}.log
 7    - 配置 FileHandler + StreamHandler
 8    """
 9    sanitized_name = _sanitize_hook_name(hook_name)
10    root_dir = _find_project_root()
11    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
12
13    try:
14        log_base_dir.mkdir(parents=True, exist_ok=True)
15    except OSError:
16        return _create_fallback_logger(hook_name)
17
18    logger = logging.getLogger(hook_name)
19    _clear_logger_handlers(logger)
20    logger.setLevel(logging.DEBUG)
21
22    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
23    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
24    return logger

Fallback 策略

注意 except OSError 的處理：目錄建立失敗時不拋出異常，而是返回一個只有 StreamHandler 的 fallback logger。這確保即使檔案系統出問題，日誌功能仍然可用（只是沒有檔案記錄）。

這體現了 5.1 異常處理策略中「策略 4：使用預設值」的原則。

統一前後的對比

指標	統一前（v0.28.0）	統一後（v0.31.0）
錯誤處理方式	44 種不同實作	1 個 `run_hook_safely`
靜默失敗風險	高（多個 Hook 實際靜默失敗中）	低（stderr 強制可見）
日誌格式	不一致	統一時間戳、格式、目錄結構
新增 Hook 所需程式碼	~15 行錯誤處理	1 行 `run_hook_safely` 呼叫

思考題

run_hook_safely 為什麼選擇返回 EXIT_ERROR（整數 1）而不是拋出異常？
如果 _log_exception 本身也拋出異常（例如磁碟已滿），會發生什麼？
為什麼 _create_fallback_logger 只配 StreamHandler 而不是直接返回 None？

實作練習

寫一個類似 run_hook_safely 的裝飾器版本，讓 @safe_hook 就能保護函式
擴展 _log_exception，讓它在記錄日誌的同時發送通知（例如寫入一個 .alert 檔案）
修改 setup_hook_logging，加入日誌檔案大小限制（使用 RotatingFileHandler）

上一章：Mock 與測試隔離 相關：作用域迴歸案例研究 — 這套機制如何在一次重構中暴露出潛在問題

5.6 Hook 系統可觀測性設計

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

上一章介紹了 run_hook_safely 這個頂層例外處理器，解決了「44 個 Hook 各自處理錯誤」的問題。但「捕獲錯誤」只是可觀測性的第一步。真正的問題是：

當 44 個 Hook 每天執行數百次，你怎麼知道它們運行正常？出了問題你怎麼找到原因？

本章從三個維度建立 Hook 系統的可觀測性：

維度	解決的問題	核心機制
日誌架構	每次執行的痕跡在哪裡？	Structured Logging + Log Rotation
錯誤可見性	出錯了誰來告訴用戶？	stderr 輸出 + Fallback 策略
健康監控	系統整體是否正常？	執行時間追蹤 + 日誌清理

一、日誌架構設計

1.1 需求分析

Hook 日誌系統和一般應用程式的日誌有兩個根本差異：

差異	一般應用程式	Hook 系統
生命週期	長時間運行	每次觸發執行一次（秒級）
實例數量	1-3 個服務	44 個獨立腳本
日誌量	大量、持續	少量、離散
讀者	運維團隊	開發者自己

這些差異決定了日誌架構的選擇：不需要集中式日誌服務，但需要按 Hook 名稱隔離和按時間自動清理。

1.2 目錄結構設計

 1.claude/hook-logs/
 2├── acceptance-gate-hook/
 3│   ├── acceptance-gate-hook-20260304-091523.log
 4│   ├── acceptance-gate-hook-20260304-091845.log
 5│   └── .cleanup_trigger           # 清理觸發計數器
 6├── command-entrance-gate-hook/
 7│   ├── command-entrance-gate-hook-20260304-091523.log
 8│   └── ...
 9└── phase-completion-gate-hook/
10    └── ...

每個 Hook 有獨立的日誌目錄。每次執行產生一個獨立的日誌檔案，檔名包含時間戳。這個設計的好處：

隔離性：排查問題時只需看特定 Hook 的目錄
時間線：按檔名排序就能看到執行歷史
清理：按目錄或按時間清理都很容易

1.3 日誌系統初始化

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    """建立並設定 Hook 日誌系統"""
 3    if not hook_name:
 4        hook_name = DEFAULT_HOOK_NAME
 5
 6    sanitized_name = _sanitize_hook_name(hook_name)
 7    root_dir = _find_project_root()
 8    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
 9
10    # 建立日誌目錄（失敗時降級，不拋出異常）
11    try:
12        log_base_dir.mkdir(parents=True, exist_ok=True)
13    except OSError:
14        return _create_fallback_logger(hook_name)
15
16    logger = logging.getLogger(hook_name)
17    _clear_logger_handlers(logger)
18    logger.setLevel(logging.DEBUG)
19
20    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
21    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
22    return logger

這段程式碼有幾個值得注意的設計決策。

Named Logger：使用 logging.getLogger(hook_name) 取得 named logger，而非 root logger。這確保每個 Hook 的日誌設定互不干擾：

1# 每個 Hook 有自己的 logger 實例
2logger_a = logging.getLogger("acceptance-gate-hook")
3logger_b = logging.getLogger("command-entrance-gate-hook")
4# 兩者的 handlers、level、format 完全獨立

Handler 清理：每次初始化前先清除舊的 handlers。這防止同一個 logger 被重複配置（例如在測試中多次呼叫 setup_hook_logging）：

1def _clear_logger_handlers(logger: logging.Logger) -> None:
2    """清除 logger 的所有 handlers"""
3    for handler in logger.handlers[:]:
4        logger.removeHandler(handler)
5        handler.close()

注意 logger.handlers[:] 的切片複製。直接遍歷 logger.handlers 並在迴圈中 removeHandler 會修改列表長度，導致跳過元素。這是 Python 中遍歷時修改集合的經典陷阱。

環境變數控制：透過 HOOK_DEBUG 環境變數切換日誌詳細程度，不需要修改程式碼：

1# 正常模式：stdout 只顯示 WARNING 以上
2python3 my-hook.py
3
4# 除錯模式：stdout 顯示所有等級
5HOOK_DEBUG=true python3 my-hook.py

1.4 雙通道輸出

每個 logger 配置兩個 handler，分別負責不同用途：

 1def _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug):
 2    """為 logger 配置 handlers"""
 3    # 檔案 handler：記錄所有等級，供事後分析
 4    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
 5    log_file_path = log_base_dir / f"{sanitized_name}-{timestamp}.log"
 6    file_handler = _create_file_handler(log_file_path)
 7    if file_handler:
 8        logger.addHandler(file_handler)
 9
10    # 控制台 handler：正常模式只顯示 WARNING+，除錯模式顯示全部
11    logger.addHandler(_create_stream_handler(is_debug))

Handler	輸出目標	等級	格式	用途
FileHandler	日誌檔案	DEBUG	`[2026-03-04 09:15:23] DEBUG - message`	事後分析
StreamHandler	stdout	WARNING（正常）/ DEBUG（除錯）	`[WARNING] message`	即時回饋

為什麼 StreamHandler 輸出到 stdout 而非 stderr？這和 Claude Code 的 Hook 系統規則有關：

輸出管道	Claude Code 的解讀
stdout	正常訊息，顯示為 `hook success`
stderr	錯誤訊息，顯示為 `hook error`

日誌中的 WARNING 訊息是給開發者的提醒，不是 Hook 執行失敗。如果把 WARNING 輸出到 stderr，Claude Code 會把它當成錯誤。所以 StreamHandler 必須走 stdout。

1.5 Hook 名稱淨化

Hook 名稱會用於檔案系統路徑（目錄名和檔名），所以需要淨化：

 1def _sanitize_hook_name(name: str) -> str:
 2    """淨化 hook 名稱，移除無法用於檔案系統的字元"""
 3    if not name:
 4        return DEFAULT_HOOK_NAME
 5
 6    for char in ["<", ">", "|"]:
 7        name = name.replace(char, "-")
 8    name = name.replace("/", "-").replace("\\", "-")
 9
10    # 合併連續 "-" 並移除前後
11    while "--" in name:
12        name = name.replace("--", "-")
13    name = name.strip("-")
14
15    return name if name else DEFAULT_HOOK_NAME

這是防禦性程式設計的典型例子。雖然目前所有 Hook 的名稱都是合法的檔案名（像 acceptance-gate-hook），但不能假設呼叫端一定傳入合法名稱。淨化函式確保即使傳入也能產生合法的目錄名 invalid-name。

1.6 專案根目錄定位

日誌目錄在專案根目錄下的 .claude/hook-logs/。但 Hook 可能從不同的工作目錄被執行，所以需要動態定位：

 1def _find_project_root() -> Path:
 2    """查詢專案根目錄
 3
 4    優先順序：
 5    1. 環境變數 CLAUDE_PROJECT_DIR
 6    2. 從 cwd 向上搜尋 CLAUDE.md（最多 5 層）
 7    3. os.getcwd() fallback（永不失敗）
 8    """
 9    env_dir = os.getenv("CLAUDE_PROJECT_DIR")
10    if env_dir:
11        return Path(env_dir)
12
13    current_dir = Path.cwd()
14    for _ in range(CLAUDE_MD_SEARCH_DEPTH):
15        if (current_dir / "CLAUDE.md").exists():
16            return current_dir
17        parent = current_dir.parent
18        if parent == current_dir:
19            break
20        current_dir = parent
21
22    return Path.cwd()

三層 fallback 的設計邏輯：

優先級	方式	適用場景	失敗條件
1	環境變數	Claude Code 啟動時自動設定	手動執行時未設定
2	向上搜尋 CLAUDE.md	手動執行、測試	在非專案目錄執行
3	cwd	最後手段	永不失敗

注意搜尋深度限制 CLAUDE_MD_SEARCH_DEPTH = 5。不做深度限制的話，在 / 目錄執行時會遍歷整個檔案系統。5 層足以覆蓋大多數專案結構（/Users/user/projects/my-app/.claude/hooks/ 需要 4 層）。

二、錯誤可見性設計

2.1 核心問題：靜默失敗

IMP-003 事件是錯誤可見性設計的直接動機。7 個 Hook 因為變數作用域問題（NameError）靜默失敗了至少 2 個 session。失敗的流程是：

1Hook 執行 → NameError → run_hook_safely 捕獲 → 寫入日誌檔案 → 返回 EXIT_ERROR
2                                                    ↑
3                                              用戶看不到這裡

問題出在 _log_exception 的初版只寫入日誌檔案：

1# W25-005 之前的版本（有缺陷）
2def _log_exception(logger, hook_name, tb_str):
3    logger.critical(f"Unhandled exception in {hook_name}")
4    logger.critical(tb_str)
5    # 到這裡就結束了 -- 用戶完全不知道出錯

2.2 修正：stderr 強制可見

W25-005 在日誌寫入之後加了一行 stderr 輸出：

 1def _log_exception(logger, hook_name, tb_str):
 2    """記錄異常 traceback 到日誌"""
 3    # 1. 寫入日誌檔案（完整 traceback，供事後分析）
 4    try:
 5        logger.critical(f"Unhandled exception in {hook_name}")
 6        logger.critical(tb_str)
 7    except Exception as logging_error:
 8        # 日誌系統本身也可能失敗（磁碟滿了、權限問題）
 9        print(f"Failed to log exception: {logging_error}", file=sys.stdout)
10        print(tb_str, file=sys.stdout)
11
12    # 2. 輸出到 stderr，讓 Claude Code 顯示 "hook error"（W25-005 新增）
13    print(
14        f"[Hook Error] {hook_name} failed unexpectedly. "
15        f"Check hook logs for details.",
16        file=sys.stderr
17    )

這個設計的關鍵在於兩層輸出各司其職：

輸出	目標	內容	讀者
日誌檔案	`.claude/hook-logs/{name}/`	完整 traceback	開發者（事後分析）
stderr	Claude Code UI	簡短錯誤提示	用戶（即時感知）

為什麼不把完整 traceback 輸出到 stderr？ 因為 stderr 的內容會直接顯示在 Claude Code 的對話介面中。一段 20 行的 Python traceback 對用戶來說是噪音。只需要告訴用戶「哪個 Hook 出錯了」和「去哪裡看詳情」就夠了。

2.3 日誌系統自身的 Fallback

如果日誌系統本身出了問題（例如磁碟已滿，無法寫入日誌檔案），怎麼辦？

 1# 目錄建立失敗時的 Fallback
 2try:
 3    log_base_dir.mkdir(parents=True, exist_ok=True)
 4except OSError:
 5    return _create_fallback_logger(hook_name)  # 降級為純 stdout 輸出
 6
 7def _create_fallback_logger(hook_name: str) -> logging.Logger:
 8    """建立 Fallback Logger（僅 StreamHandler）"""
 9    logger = logging.getLogger(hook_name)
10    _clear_logger_handlers(logger)
11    logger.setLevel(logging.DEBUG)
12    logger.addHandler(_create_stream_handler())
13    return logger

Fallback Logger 只有 StreamHandler（stdout），沒有 FileHandler。這表示日誌不會被儲存到檔案，但至少 Hook 能正常運行，而且重要訊息仍然會出現在控制台。

這體現了一個重要的設計原則：可觀測性基礎設施的故障不應該導致業務功能中斷。日誌系統壞了，Hook 仍然要能工作。

2.4 IMP-005 的教訓：Import 階段的可見性

IMP-005 暴露了另一個可見性盲區：import 階段的錯誤。當模組遷移後 import 路徑沒更新，ModuleNotFoundError 在 run_hook_safely 之前就發生了：

 1#!/usr/bin/env python3
 2import sys
 3from pathlib import Path
 4
 5# 這一行在 run_hook_safely 之前執行
 6# 如果失敗，run_hook_safely 根本不會被呼叫
 7from lib.common_functions import hook_output  # ModuleNotFoundError!
 8
 9from hook_utils import run_hook_safely
10
11def main() -> int:
12    # ...
13    return 0
14
15if __name__ == "__main__":
16    sys.exit(run_hook_safely(main, "my-hook"))

run_hook_safely 的保護範圍是 main() 函式內部，但 import 發生在模組載入階段。解決方案是在 import 處加入 try-except 防護：

 1#!/usr/bin/env python3
 2import sys
 3from pathlib import Path
 4
 5# Import 防護：確保失敗時有明確的 stderr 輸出
 6try:
 7    sys.path.insert(0, str(Path(__file__).parent))
 8    from hook_utils import run_hook_safely
 9    from lib.common_functions import hook_output
10except ImportError as e:
11    print(f"[Hook Import Error] {Path(__file__).name}: {e}", file=sys.stderr)
12    sys.exit(1)

沒有 Import 防護	有 Import 防護
Claude Code 顯示 `hook error`	Claude Code 顯示 `hook error`
無法得知是哪個 Hook	`[Hook Import Error] my-hook.py: No module named 'common_functions'`
無法得知什麼原因	精確到模組名稱和檔案名稱

2.5 IMP-006 的教訓：兩條錯誤路徑

IMP-006 案例 D 揭示了一個更隱蔽的問題：Hook 有兩條不同的「失敗路徑」，但只有一條有 stderr 輸出。

 1def main() -> int:
 2    # ...驗證邏輯...
 3
 4    if should_block:
 5        # 路徑 1：業務邏輯拒絕（有意阻止）
 6        result = {"error": error_message}
 7        print(json.dumps(result), file=sys.stdout)
 8        return 2  # 只有 stdout，沒有 stderr！
 9
10    return 0
11
12# run_hook_safely 包裝
13# 路徑 2：未預期異常 -- _log_exception 已有 stderr 輸出

開發者只考慮了「未預期異常」這條路徑（由 _log_exception 處理），忘了「有意阻止」也需要 stderr 輸出。修復：

1if should_block:
2    result = {"error": error_message}
3    print(json.dumps(result), file=sys.stdout)
4    # 新增：確保用戶在 Claude Code UI 能看到拒絕原因
5    print(f"[Agent Ticket Validation] blocked: {error_message}", file=sys.stderr)
6    return 2

教訓歸納為一條規則：Hook 的所有非成功路徑都必須有 stderr 輸出。不只是 exception，業務邏輯的拒絕也算。

1Hook 執行結果
2├── 成功（return 0）→ stdout 正常訊息
3├── 未預期異常（Exception）→ stderr 由 _log_exception 處理
4└── 有意阻止（return 非 0）→ stderr 必須有原因說明  ← 容易遺漏

三、健康監控設計

3.1 執行時間追蹤

run_hook_safely 記錄每次執行的耗時：

 1def run_hook_safely(main_func, hook_name):
 2    logger = setup_hook_logging(hook_name)
 3    start_time = time.time()
 4
 5    try:
 6        exit_code = main_func()
 7        elapsed_time = time.time() - start_time
 8        logger.debug(f"Hook execution time: {elapsed_time:.2f}s")
 9        return exit_code
10    except (KeyboardInterrupt, SystemExit):
11        raise
12    except Exception:
13        elapsed_time = time.time() - start_time
14        logger.debug(f"Hook execution time before failure: {elapsed_time:.2f}s")
15        tb_str = traceback.format_exc()
16        _log_exception(logger, hook_name, tb_str)
17        return EXIT_ERROR

注意兩處 elapsed_time 的記錄位置——成功和失敗路徑各記一次。失敗時記錄「失敗前的執行時間」，可以判斷是立即失敗（import 錯誤，< 0.01s）還是在執行過程中失敗（邏輯錯誤，可能數秒）。

日誌檔案中的記錄：

1[2026-03-04 09:15:23] DEBUG - Hook execution time: 0.05s       # 正常
2[2026-03-04 09:15:24] DEBUG - Hook execution time: 2.34s       # 偏慢，值得關注
3[2026-03-04 09:15:25] DEBUG - Hook execution time before failure: 0.00s  # import 階段就失敗了

這些數據在 IMP-006 案例 C 的排查中發揮了作用。hookify plugin 的 timeout 設定為 10ms，而 Python 啟動需要約 24ms。比對 Hook 執行時間和 timeout 設定，就能定位超時問題。

3.2 日誌自動清理（Log Rotation）

44 個 Hook 每天執行數百次，日誌檔案會快速累積。自動清理機制避免磁碟空間被耗盡：

 1LOG_RETENTION_DAYS = 7
 2LOG_CLEANUP_TRIGGER_FREQUENCY = 10
 3
 4def _cleanup_old_logs(log_base_dir: Path, retention_days: int = LOG_RETENTION_DAYS):
 5    """清理超期日誌檔案"""
 6    try:
 7        cutoff_time = datetime.now() - timedelta(days=retention_days)
 8        for log_file in log_base_dir.glob("*.log"):
 9            try:
10                mtime = datetime.fromtimestamp(log_file.stat().st_mtime)
11                if mtime < cutoff_time:
12                    log_file.unlink()
13            except (OSError, ValueError):
14                pass
15    except OSError:
16        pass

為什麼不用 Python 標準庫的 RotatingFileHandler

RotatingFileHandler 按照單一檔案大小輪轉，適合長時間運行的服務。但 Hook 系統的日誌模式是每次執行一個新檔案，需要的是按時間清理舊檔案。兩者的需求場景不同：

機制	適用場景	Hook 系統需求
RotatingFileHandler	單一長期運行程序，同一個日誌檔	不適用
TimedRotatingFileHandler	單一程序按時間分割日誌	部分適用
自訂清理	多程序、每次新檔案、按時間保留	適用

3.3 清理頻率控制

每次 Hook 執行都檢查是否需要清理，這本身也有成本。所以用一個 .cleanup_trigger 檔案作為計數器，每 N 次呼叫才真正執行清理：

 1def _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug):
 2    """為 logger 配置 handlers"""
 3    # 觸發日誌清理（降低頻率）
 4    cleanup_marker = log_base_dir / ".cleanup_trigger"
 5    try:
 6        if cleanup_marker.exists():
 7            count = int(cleanup_marker.read_text().strip() or "0")
 8            if count >= LOG_CLEANUP_TRIGGER_FREQUENCY:
 9                _cleanup_old_logs(log_base_dir)
10                cleanup_marker.write_text("0")
11            else:
12                cleanup_marker.write_text(str(count + 1))
13        else:
14            cleanup_marker.write_text("1")
15    except (OSError, ValueError):
16        pass  # 清理失敗不影響日誌功能

LOG_CLEANUP_TRIGGER_FREQUENCY = 10 表示每 10 次執行才清理一次。這是一個權衡：

頻率	好處	代價
每次（1）	日誌目錄永遠乾淨	每次 Hook 都多一次目錄掃描
每 10 次	幾乎感覺不到開銷	最多累積 10 個多餘檔案
每 100 次	開銷最小	可能累積數百個多餘檔案

為什麼用檔案而不用記憶體計數器？ 因為 Hook 是獨立程序，每次執行都是新進程。記憶體中的計數器在進程結束後就消失了。檔案是跨進程持久化的最簡單方式。

注意最外層的 except (OSError, ValueError): pass。清理機制本身的故障（例如檔案被鎖定、計數器檔案損壞）不應該影響日誌功能。這和 Fallback Logger 的設計原則一致：輔助功能的故障不阻擋核心功能。

四、三個錯誤模式的可觀測性教訓

前面三個維度的設計，很大程度源自三個真實錯誤模式（IMP-003、IMP-005、IMP-006）的教訓。把它們放在一起看，可以提煉出可觀測性設計的通用原則。

4.1 IMP-003：作用域迴歸 – 靜默失敗的代價

項目	說明
事件	7 個 Hook 因 `NameError` 靜默失敗 2+ session
根因	logger 從全域移入 main()，引用者未更新
可觀測性缺陷	`_log_exception` 只寫檔案日誌，不輸出 stderr
修正	新增 stderr 輸出（W25-005）
通用原則	錯誤必須有用戶可感知的通知管道

詳細的作用域分析見作用域迴歸案例研究。

4.2 IMP-005：Import 未同步 – 保護範圍的盲區

項目	說明
事件	5 個 Hook 因 `ModuleNotFoundError` 啟動失敗
根因	模組遷移後 import 路徑未更新
可觀測性缺陷	`run_hook_safely` 無法保護 import 階段
修正	在 import 處加入 try-except + stderr
通用原則	頂層保護的範圍必須覆蓋所有執行階段

4.3 IMP-006：隱性故障 – 錯誤路徑的完整性

項目	說明
事件	多種不同根因的 hook error 無法區分
案例 A	函式參數遺漏（部分 call site 缺少 logger）
案例 C	Plugin timeout 10ms，Python 啟動需 24ms
案例 D	有意阻止路徑缺少 stderr
通用原則	所有非成功路徑都需要可區分的錯誤輸出

4.4 共通教訓

三個錯誤模式的共通點，提煉為三條可觀測性設計規則：

規則 1：錯誤不可靜默

1# 錯誤做法：只寫日誌，用戶不知道
2logger.critical(tb_str)
3
4# 正確做法：日誌 + 用戶通知
5logger.critical(tb_str)
6print(f"[Hook Error] {hook_name} failed", file=sys.stderr)

規則 2：保護必須完整

 1# 錯誤做法：只保護 main()
 2sys.exit(run_hook_safely(main, "hook"))
 3
 4# 正確做法：import 也要保護
 5try:
 6    from lib.module import function
 7except ImportError as e:
 8    print(f"[Hook Import Error] {__file__}: {e}", file=sys.stderr)
 9    sys.exit(1)
10
11sys.exit(run_hook_safely(main, "hook"))

規則 3：錯誤要可區分

1# 錯誤做法：所有錯誤用同一種訊息
2print("hook error", file=sys.stderr)
3
4# 正確做法：包含 Hook 名稱和錯誤類型
5print(f"[Hook Error] {hook_name} failed unexpectedly", file=sys.stderr)
6print(f"[Hook Import Error] {filename}: {error}", file=sys.stderr)
7print(f"[Agent Validation] blocked: {reason}", file=sys.stderr)

五、完整的可觀測性架構

把前面的設計串在一起，一個 Hook 的完整執行路徑和可觀測性覆蓋如下：

 1Hook 被觸發
 2│
 3├─ [階段 1] Import 載入
 4│  ├─ 成功 → 繼續
 5│  └─ 失敗 → try-except 捕獲
 6│            ├─ stderr: [Hook Import Error] hook.py: error
 7│            └─ sys.exit(1)
 8│
 9├─ [階段 2] setup_hook_logging
10│  ├─ 成功 → Logger 就緒（FileHandler + StreamHandler）
11│  └─ 失敗 → Fallback Logger（僅 StreamHandler）
12│
13├─ [階段 3] main() 執行
14│  ├─ 成功 → logger.debug("execution time: Xs")
15│  │         return exit_code
16│  ├─ 業務拒絕 → stderr: [Hook Name] blocked: reason
17│  │             return 2
18│  └─ 未預期異常 → logger.critical(traceback)
19│                   stderr: [Hook Error] hook failed
20│                   return 1
21│
22└─ [階段 4] 日誌清理（每 10 次觸發）
23   └─ 清理 7 天前的日誌檔案

每個階段都有對應的可觀測性機制。沒有任何執行路徑是「靜默」的。

思考題

為什麼 _cleanup_old_logs 使用 mtime（修改時間）而非 ctime（建立時間）來判斷過期？在什麼情況下兩者會不同？
如果兩個 Hook 同時執行（例如同時觸發的 PreToolUse Hook），它們的日誌會互相干擾嗎？提示：思考 logging.getLogger(hook_name) 的行為。
目前的清理計數器用檔案系統實作。如果改用原子操作（例如 os.rename），能否解決並行存取的 race condition？值得嗎？

實作練習

寫一個日誌分析腳本：掃描 .claude/hook-logs/ 目錄，統計每個 Hook 的平均執行時間、失敗次數、最後一次執行時間。
實作 RotatingFileHandler 版本：修改 setup_hook_logging，改用單一日誌檔 + RotatingFileHandler（按大小輪轉），並比較和目前方案的優缺點。
加入健康檢查端點：寫一個 hook-health-check.py 腳本，檢查每個 Hook 目錄的最新日誌是否包含 CRITICAL 等級的記錄，輸出健康報告。

上一章：頂層例外處理機制 相關：重構陷阱與防護 – IMP-003/005/006 的重構角度分析 相關：作用域迴歸案例研究 – IMP-003 的完整技術分析

模組五：錯誤處理與測試 on Tarragon

5.1 異常處理策略

基本語法

try-except

完整結構

常見異常類型

實際範例：Git 命令執行

設計分析

Hook 系統的異常哲學

為什麼不直接拋出異常？

(bool, str) 返回值模式

實際應用

異常處理策略

策略 1：捕獲並轉換

策略 2：捕獲並記錄

策略 3：捕獲並重新拋出

策略 4：使用預設值

最佳實踐

1. 具體優於籠統

2. 保留原始異常資訊

3. 使用 finally 清理資源

4. 不要靜默忽略異常

自訂異常

思考題

實作練習

5.2 返回值設計

(bool, str) 模式

基本形式

使用方式

實際範例：Git 命令

使用這個函式

為什麼選擇這個模式？

優點

明確的錯誤處理

錯誤訊息保留

不中斷執行流程

與異常的比較

設計變體

(bool, T) - 通用型別

(T | None) - 成功返回值，失敗返回 None

Result 類別（進階）

實際應用模式

鏈式操作

收集多個錯誤

帶上下文的錯誤

Hook 系統的應用

Hook 輸入讀取

分支驗證

最佳實踐

1. 訊息要有意義

2. 保持一致性

3. 文檔說明返回值

思考題

實作練習

5.3 unittest 基礎

基本結構

最簡單的測試

測試類別結構

常用斷言方法

實際範例：測試 Hook IO

測試異常

assertRaises

測試檔案操作

使用臨時檔案

使用臨時目錄

執行測試

執行單一測試檔案

執行單一測試類別

執行單一測試方法

執行所有測試

詳細輸出

測試組織

目錄結構

命名慣例

最佳實踐

1. 一個測試驗證一件事

2. 使用描述性的測試名稱

3. 使用 setUp 避免重複

思考題

實作練習

`(bool, str)` 返回值模式

解決方案：`run_hook_safely`

為什麼 `KeyboardInterrupt` 和 `SystemExit` 要特別處理？