案例研究：非同步程式設計實戰 on Tarragon

案例：非同步 subprocess

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/git_utils.py 的實際程式碼，展示如何用 asyncio 實現非同步的外部命令執行。

先備知識

問題背景

現有設計

git_utils.py 使用同步的 subprocess.run：

 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 Args:
13 args: git 命令參數列表（不含 'git'）
14 cwd: 執行目錄
15 timeout: 命令超時時間（秒）
16
17 Returns:
18 tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
19 """
20 try:
21 result = subprocess.run(
22 ["git"] + args,
23 cwd=cwd,
24 capture_output=True,
25 text=True,
26 timeout=timeout
27 )
28 if result.returncode == 0:
29 return True, result.stdout.strip()
30 else:
31 return False, result.stderr.strip()
32 except subprocess.TimeoutExpired:
33 return False, f"Command timed out after {timeout}s"
34 except FileNotFoundError:
35 return False, "git command not found"
36 except Exception as e:
37 return False, str(e)
38
39def get_current_branch() -> Optional[str]:
40 """獲取當前分支名稱"""
41 success, output = run_git_command(["branch", "--show-current"])
42 return output if success and output else None
43
44def get_worktree_list() -> list[dict]:
45 """獲取所有 worktree 列表"""
46 success, output = run_git_command(["worktree", "list", "--porcelain"])
47 if not success:
48 return []
49 # ... 解析邏輯

這個設計的優點

簡單直覺：同步呼叫，容易理解
錯誤處理完善：處理超時、檔案不存在等情況
API 清晰：返回 (bool, str) 元組

這個設計的限制

問題：無法並行執行多個 Git 命令

 1def check_all_worktrees(worktrees: list[str]) -> dict[str, str]:
 2 """檢查所有 worktree 的狀態"""
 3 results = {}
 4 for worktree in worktrees:
 5 # 每次呼叫都會阻塞等待
 6 success, status = run_git_command(["status", "-s"], cwd=worktree)
 7 results[worktree] = status if success else "error"
 8 return results
 9
10# 如果有 10 個 worktree，每個花 0.5 秒
11# 總共需要 5 秒！

問題：阻塞事件迴圈

1async def handle_request():
2 # 這會阻塞事件迴圈！
3 branch = get_current_branch()
4 # 其他協程無法執行
5 return {"branch": branch}

進階解決方案：非同步 subprocess

設計目標

非阻塞執行：不阻塞事件迴圈
並行能力：可以同時執行多個命令
相容性：保持與同步版本相似的 API

實作步驟

步驟 1：建立非同步命令執行器

 1import asyncio
 2from typing import Optional
 3
 4async def async_run_git_command(
 5 args: list[str],
 6 cwd: Optional[str] = None,
 7 timeout: float = 10.0
 8) -> tuple[bool, str]:
 9 """
10 非同步執行 git 命令
11
12 Args:
13 args: git 命令參數列表（不含 'git'）
14 cwd: 執行目錄
15 timeout: 命令超時時間（秒）
16
17 Returns:
18 tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
19
20 Example:
21 success, output = await async_run_git_command(["status"])
22 """
23 try:
24 # 建立非同步子進程
25 process = await asyncio.create_subprocess_exec(
26 "git", *args,
27 cwd=cwd,
28 stdout=asyncio.subprocess.PIPE,
29 stderr=asyncio.subprocess.PIPE
30 )
31
32 # 等待完成（帶超時）
33 try:
34 stdout, stderr = await asyncio.wait_for(
35 process.communicate(),
36 timeout=timeout
37 )
38 except asyncio.TimeoutError:
39 process.kill()
40 await process.wait()
41 return False, f"Command timed out after {timeout}s"
42
43 # 處理結果
44 if process.returncode == 0:
45 return True, stdout.decode().strip()
46 else:
47 return False, stderr.decode().strip()
48
49 except FileNotFoundError:
50 return False, "git command not found"
51 except Exception as e:
52 return False, str(e)

步驟 2：建立便利函式

 1async def async_get_current_branch() -> Optional[str]:
 2 """非同步獲取當前分支名稱"""
 3 success, output = await async_run_git_command(["branch", "--show-current"])
 4 return output if success and output else None
 5
 6async def async_get_project_root() -> str:
 7 """非同步獲取專案根目錄"""
 8 import os
 9 success, output = await async_run_git_command(["rev-parse", "--show-toplevel"])
10 return output if success else os.getcwd()
11
12async def async_get_worktree_list() -> list[dict]:
13 """非同步獲取 worktree 列表"""
14 success, output = await async_run_git_command(
15 ["worktree", "list", "--porcelain"]
16 )
17 if not success:
18 return []
19
20 worktrees = []
21 current_worktree: dict = {}
22
23 for line in output.split("\n"):
24 if line.startswith("worktree "):
25 if current_worktree:
26 worktrees.append(current_worktree)
27 current_worktree = {"path": line[9:]} # len("worktree ") = 9
28 elif line.startswith("branch "):
29 branch_ref = line[7:] # len("branch ") = 7
30 if branch_ref.startswith("refs/heads/"):
31 branch_ref = branch_ref[11:] # len("refs/heads/") = 11
32 current_worktree["branch"] = branch_ref
33 elif line == "detached":
34 current_worktree["detached"] = True
35
36 if current_worktree:
37 worktrees.append(current_worktree)
38
39 return worktrees

步驟 3：實現並行執行

 1async def check_all_worktrees(worktrees: list[str]) -> dict[str, str]:
 2 """
 3 並行檢查所有 worktree 的狀態
 4
 5 Args:
 6 worktrees: worktree 路徑列表
 7
 8 Returns:
 9 dict[str, str]: {路徑: 狀態} 映射
10 """
11 async def check_one(worktree: str) -> tuple[str, str]:
12 """檢查單個 worktree"""
13 success, status = await async_run_git_command(
14 ["status", "-s"],
15 cwd=worktree
16 )
17 return worktree, status if success else "error"
18
19 # 並行執行所有檢查
20 tasks = [check_one(wt) for wt in worktrees]
21 results = await asyncio.gather(*tasks)
22
23 return dict(results)
24
25async def get_all_branches(worktrees: list[str]) -> dict[str, str]:
26 """
27 並行獲取所有 worktree 的當前分支
28
29 Args:
30 worktrees: worktree 路徑列表
31
32 Returns:
33 dict[str, str]: {路徑: 分支名} 映射
34 """
35 async def get_branch(worktree: str) -> tuple[str, str]:
36 success, branch = await async_run_git_command(
37 ["branch", "--show-current"],
38 cwd=worktree
39 )
40 return worktree, branch if success else "unknown"
41
42 tasks = [get_branch(wt) for wt in worktrees]
43 results = await asyncio.gather(*tasks)
44
45 return dict(results)

完整程式碼

 1#!/usr/bin/env python3
 2"""
 3非同步 Git 操作工具 - 完整範例
 4
 5展示如何用 asyncio 實現非阻塞的 Git 命令執行。
 6"""
 7
 8import asyncio
 9import os
 10from typing import Optional
 11
 12# ===== 核心功能 =====
 13
 14async def async_run_git_command(
 15 args: list[str],
 16 cwd: Optional[str] = None,
 17 timeout: float = 10.0
 18) -> tuple[bool, str]:
 19 """
 20 非同步執行 git 命令
 21
 22 Args:
 23 args: git 命令參數列表
 24 cwd: 執行目錄
 25 timeout: 超時時間（秒）
 26
 27 Returns:
 28 (是否成功, 輸出或錯誤訊息)
 29 """
 30 try:
 31 process = await asyncio.create_subprocess_exec(
 32 "git", *args,
 33 cwd=cwd,
 34 stdout=asyncio.subprocess.PIPE,
 35 stderr=asyncio.subprocess.PIPE
 36 )
 37
 38 try:
 39 stdout, stderr = await asyncio.wait_for(
 40 process.communicate(),
 41 timeout=timeout
 42 )
 43 except asyncio.TimeoutError:
 44 process.kill()
 45 await process.wait()
 46 return False, f"Command timed out after {timeout}s"
 47
 48 if process.returncode == 0:
 49 return True, stdout.decode().strip()
 50 else:
 51 return False, stderr.decode().strip()
 52
 53 except FileNotFoundError:
 54 return False, "git command not found"
 55 except Exception as e:
 56 return False, str(e)
 57
 58# ===== 便利函式 =====
 59
 60async def async_get_current_branch() -> Optional[str]:
 61 """獲取當前分支"""
 62 success, output = await async_run_git_command(["branch", "--show-current"])
 63 return output if success and output else None
 64
 65async def async_get_project_root() -> str:
 66 """獲取專案根目錄"""
 67 success, output = await async_run_git_command(["rev-parse", "--show-toplevel"])
 68 return output if success else os.getcwd()
 69
 70async def async_get_worktree_list() -> list[dict]:
 71 """獲取 worktree 列表"""
 72 success, output = await async_run_git_command(
 73 ["worktree", "list", "--porcelain"]
 74 )
 75 if not success:
 76 return []
 77
 78 worktrees = []
 79 current_worktree: dict = {}
 80
 81 for line in output.split("\n"):
 82 if line.startswith("worktree "):
 83 if current_worktree:
 84 worktrees.append(current_worktree)
 85 current_worktree = {"path": line[9:]}
 86 elif line.startswith("branch "):
 87 branch_ref = line[7:]
 88 if branch_ref.startswith("refs/heads/"):
 89 branch_ref = branch_ref[11:]
 90 current_worktree["branch"] = branch_ref
 91 elif line == "detached":
 92 current_worktree["detached"] = True
 93
 94 if current_worktree:
 95 worktrees.append(current_worktree)
 96
 97 return worktrees
 98
 99# ===== 並行操作 =====
100
101async def check_all_worktrees(worktrees: list[str]) -> dict[str, str]:
102 """並行檢查所有 worktree 狀態"""
103 async def check_one(path: str) -> tuple[str, str]:
104 success, status = await async_run_git_command(["status", "-s"], cwd=path)
105 return path, status if success else "error"
106
107 tasks = [check_one(wt) for wt in worktrees]
108 results = await asyncio.gather(*tasks)
109 return dict(results)
110
111async def get_all_branches(worktrees: list[str]) -> dict[str, str]:
112 """並行獲取所有 worktree 的分支"""
113 async def get_branch(path: str) -> tuple[str, str]:
114 success, branch = await async_run_git_command(
115 ["branch", "--show-current"],
116 cwd=path
117 )
118 return path, branch if success else "unknown"
119
120 tasks = [get_branch(wt) for wt in worktrees]
121 results = await asyncio.gather(*tasks)
122 return dict(results)
123
124async def batch_git_commands(
125 commands: list[tuple[list[str], Optional[str]]]
126) -> list[tuple[bool, str]]:
127 """
128 批次執行多個 Git 命令
129
130 Args:
131 commands: [(args, cwd), ...] 命令列表
132
133 Returns:
134 [(success, output), ...] 結果列表
135 """
136 tasks = [
137 async_run_git_command(args, cwd=cwd)
138 for args, cwd in commands
139 ]
140 return await asyncio.gather(*tasks)
141
142# ===== 同步/非同步橋接 =====
143
144def run_git_command(
145 args: list[str],
146 cwd: Optional[str] = None,
147 timeout: float = 10.0
148) -> tuple[bool, str]:
149 """
150 同步版本（相容舊 API）
151
152 在已有事件迴圈的環境中，這會建立新的迴圈執行。
153 """
154 return asyncio.run(async_run_git_command(args, cwd, timeout))
155
156def get_current_branch() -> Optional[str]:
157 """同步版本：獲取當前分支"""
158 return asyncio.run(async_get_current_branch())
159
160# ===== 測試 =====
161
162async def demo():
163 """示範非同步 Git 操作"""
164 print("=== 非同步 Git 操作示範 ===\n")
165
166 # 單一命令
167 print("1. 獲取當前分支:")
168 branch = await async_get_current_branch()
169 print(f" 分支: {branch}\n")
170
171 # 獲取專案根目錄
172 print("2. 獲取專案根目錄:")
173 root = await async_get_project_root()
174 print(f" 根目錄: {root}\n")
175
176 # 獲取 worktree 列表
177 print("3. 獲取 worktree 列表:")
178 worktrees = await async_get_worktree_list()
179 for wt in worktrees:
180 branch = wt.get("branch", "detached")
181 print(f" - {branch}: {wt['path']}")
182 print()
183
184 # 如果有多個 worktree，示範並行操作
185 if len(worktrees) > 1:
186 print("4. 並行檢查所有 worktree 狀態:")
187 paths = [wt["path"] for wt in worktrees]
188 statuses = await check_all_worktrees(paths)
189 for path, status in statuses.items():
190 print(f" - {path}:")
191 if status:
192 for line in status.split("\n"):
193 print(f" {line}")
194 else:
195 print(" (clean)")
196 print()
197
198 # 批次命令示範
199 print("5. 批次執行多個命令:")
200 commands = [
201 (["config", "user.name"], None),
202 (["config", "user.email"], None),
203 (["rev-parse", "--short", "HEAD"], None),
204 ]
205 results = await batch_git_commands(commands)
206 labels = ["使用者名稱", "使用者信箱", "當前 commit"]
207 for label, (success, output) in zip(labels, results):
208 print(f" {label}: {output if success else '(未設定)'}")
209
210if __name__ == "__main__":
211 asyncio.run(demo())

使用範例

基本使用

 1import asyncio
 2
 3async def main():
 4 # 非同步獲取分支
 5 branch = await async_get_current_branch()
 6 print(f"當前分支: {branch}")
 7
 8 # 非同步獲取 worktree
 9 worktrees = await async_get_worktree_list()
10 print(f"Worktree 數量: {len(worktrees)}")
11
12asyncio.run(main())

並行操作

 1async def check_multiple_repos(repos: list[str]):
 2 """同時檢查多個 repo 的狀態"""
 3 tasks = [
 4 async_run_git_command(["status", "-s"], cwd=repo)
 5 for repo in repos
 6 ]
 7
 8 # 並行執行，等待全部完成
 9 results = await asyncio.gather(*tasks)
10
11 for repo, (success, output) in zip(repos, results):
12 status = "clean" if not output else "dirty"
13 print(f"{repo}: {status}")
14
15# 10 個 repo，如果每個花 0.5 秒
16# 並行執行只需要約 0.5 秒！

與 FastAPI 整合

 1from fastapi import FastAPI
 2
 3app = FastAPI()
 4
 5@app.get("/git/branch")
 6async def get_branch():
 7 """非同步端點：獲取當前分支"""
 8 branch = await async_get_current_branch()
 9 return {"branch": branch}
10
11@app.get("/git/worktrees")
12async def get_worktrees():
13 """非同步端點：獲取 worktree 列表"""
14 worktrees = await async_get_worktree_list()
15 return {"worktrees": worktrees}

效能比較

 1import time
 2import asyncio
 3
 4def sync_check_repos(repos: list[str]) -> float:
 5 """同步版本：依序檢查"""
 6 start = time.perf_counter()
 7 for repo in repos:
 8 run_git_command(["status", "-s"], cwd=repo)
 9 return time.perf_counter() - start
10
11async def async_check_repos(repos: list[str]) -> float:
12 """非同步版本：並行檢查"""
13 start = time.perf_counter()
14 tasks = [
15 async_run_git_command(["status", "-s"], cwd=repo)
16 for repo in repos
17 ]
18 await asyncio.gather(*tasks)
19 return time.perf_counter() - start
20
21# 假設每個 git status 花 0.2 秒
22repos = [f"/path/to/repo{i}" for i in range(10)]
23
24sync_time = sync_check_repos(repos) # ~2.0 秒
25async_time = asyncio.run(async_check_repos(repos)) # ~0.2 秒
26
27print(f"同步: {sync_time:.2f}s")
28print(f"非同步: {async_time:.2f}s")
29print(f"加速: {sync_time / async_time:.1f}x")

設計權衡

面向	同步 subprocess	非同步 subprocess
簡單性	簡單直覺	需要理解 async/await
效能	依序執行	可並行執行
相容性	到處可用	需要事件迴圈
錯誤處理	直覺	需要處理非同步異常
測試	簡單	需要 pytest-asyncio
記憶體	低	略高（維護多個進程）

什麼時候該用非同步 subprocess？

適合使用：

案例：並行 I/O 操作

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/git_utils.py 的實際程式碼，展示如何用 asyncio.gather 和 TaskGroup 實現高效的並行 I/O 操作。

先備知識

問題背景

現有設計

git_utils.py 的 get_worktree_list() 取得 worktree 列表後，如果要檢查每個 worktree 的狀態，需要逐一呼叫：

 1from git_utils import run_git_command, get_worktree_list
 2
 3def check_all_worktrees_sync() -> dict[str, str]:
 4    """
 5    同步版本：依序檢查每個 worktree 的狀態
 6
 7    Returns:
 8        dict[str, str]: {路徑: 狀態} 映射
 9    """
10    worktrees = get_worktree_list()
11    results = {}
12
13    for wt in worktrees:
14        path = wt["path"]
15        # Every call blocks until completion
16        success, output = run_git_command(["status", "-s"], cwd=path)
17        results[path] = output if success else "error"
18
19    return results
20
21def get_all_branches_sync() -> dict[str, str]:
22    """
23    同步版本：依序取得每個 worktree 的分支名稱
24
25    Returns:
26        dict[str, str]: {路徑: 分支名} 映射
27    """
28    worktrees = get_worktree_list()
29    results = {}
30
31    for wt in worktrees:
32        path = wt["path"]
33        # Each command waits for the previous one
34        success, output = run_git_command(["branch", "--show-current"], cwd=path)
35        results[path] = output if success else "unknown"
36
37    return results

這個設計的優點

簡單直覺：循序執行，容易理解和除錯
錯誤處理明確：每個操作的結果立即可用
資源友善：一次只執行一個進程

這個設計的限制

當 worktree 數量增加時：

執行時間線性增長：10 個 worktree，每個 0.2 秒 = 2 秒
無法利用 I/O 等待時間：等待一個命令完成時，CPU 閒置
使用者體驗差：大量 worktree 時響應緩慢

 1import time
 2
 3def benchmark_sync(worktrees: list[str]) -> float:
 4    """測量同步版本的執行時間"""
 5    start = time.perf_counter()
 6
 7    for path in worktrees:
 8        # Simulate I/O wait (actual git command)
 9        run_git_command(["status", "-s"], cwd=path)
10
11    return time.perf_counter() - start
12
13# 10 worktrees, each taking 0.2s
14# Total: 10 * 0.2 = 2.0 seconds

進階解決方案

設計目標

並行執行多個獨立的 I/O 操作
正確處理部分失敗的情況
支援取消和超時機制

實作步驟

步驟 1：使用 asyncio.gather

asyncio.gather 是並行執行多個協程最直接的方式：

 1import asyncio
 2from typing import Optional
 3
 4async def async_run_git_command(
 5    args: list[str],
 6    cwd: Optional[str] = None,
 7    timeout: float = 10.0
 8) -> tuple[bool, str]:
 9    """
10    非同步執行 git 命令（詳見上一章）
11    """
12    try:
13        process = await asyncio.create_subprocess_exec(
14            "git", *args,
15            cwd=cwd,
16            stdout=asyncio.subprocess.PIPE,
17            stderr=asyncio.subprocess.PIPE
18        )
19
20        try:
21            stdout, stderr = await asyncio.wait_for(
22                process.communicate(),
23                timeout=timeout
24            )
25        except asyncio.TimeoutError:
26            process.kill()
27            await process.wait()
28            return False, f"Command timed out after {timeout}s"
29
30        if process.returncode == 0:
31            return True, stdout.decode().strip()
32        else:
33            return False, stderr.decode().strip()
34
35    except FileNotFoundError:
36        return False, "git command not found"
37    except Exception as e:
38        return False, str(e)
39
40async def check_all_worktrees_basic(worktrees: list[str]) -> dict[str, str]:
41    """
42    使用 asyncio.gather 並行檢查所有 worktree
43
44    Args:
45        worktrees: worktree 路徑列表
46
47    Returns:
48        dict[str, str]: {路徑: 狀態} 映射
49    """
50    async def check_one(path: str) -> tuple[str, str]:
51        """Check a single worktree and return (path, status)"""
52        success, output = await async_run_git_command(
53            ["status", "-s"],
54            cwd=path
55        )
56        return path, output if success else "error"
57
58    # Create tasks for all worktrees
59    tasks = [check_one(path) for path in worktrees]
60
61    # Execute all tasks in parallel
62    results = await asyncio.gather(*tasks)
63
64    # Convert list of tuples to dict
65    return dict(results)
66
67# Usage example
68async def demo_basic():
69    worktrees = ["/path/to/repo1", "/path/to/repo2", "/path/to/repo3"]
70
71    # All three checks run in parallel
72    # If each takes 0.2s, total time is ~0.2s, not 0.6s
73    statuses = await check_all_worktrees_basic(worktrees)
74
75    for path, status in statuses.items():
76        print(f"{path}: {'clean' if not status else status}")

重點說明：

asyncio.gather(*tasks) 同時啟動所有協程
等待所有協程完成後，返回結果列表
結果順序與輸入任務順序一致

步驟 2：處理錯誤（return_exceptions）

預設情況下，gather 在遇到第一個異常時會傳播該異常。使用 return_exceptions=True 可以收集所有結果，包括異常：

 1async def check_all_worktrees_safe(
 2    worktrees: list[str]
 3) -> dict[str, str | Exception]:
 4    """
 5    安全版本：使用 return_exceptions 處理部分失敗
 6
 7    即使某些 worktree 檢查失敗，仍然返回其他的結果。
 8
 9    Args:
10        worktrees: worktree 路徑列表
11
12    Returns:
13        dict: {路徑: 狀態或例外} 映射
14    """
15    async def check_one(path: str) -> tuple[str, str]:
16        """Check with potential exception"""
17        success, output = await async_run_git_command(
18            ["status", "-s"],
19            cwd=path,
20            timeout=5.0  # Shorter timeout
21        )
22
23        if not success:
24            # Raise exception for failed commands
25            raise RuntimeError(f"Git command failed: {output}")
26
27        return path, output
28
29    tasks = [check_one(path) for path in worktrees]
30
31    # return_exceptions=True: exceptions become results, not propagated
32    results = await asyncio.gather(*tasks, return_exceptions=True)
33
34    # Process results, handling both successes and exceptions
35    output = {}
36    for path, result in zip(worktrees, results):
37        if isinstance(result, Exception):
38            output[path] = f"error: {result}"
39        else:
40            # result is (path, status) tuple
41            _, status = result
42            output[path] = status if status else "clean"
43
44    return output
45
46async def demo_error_handling():
47    """示範錯誤處理"""
48    worktrees = [
49        "/valid/repo1",      # Works
50        "/invalid/path",     # Fails
51        "/valid/repo2",      # Works
52    ]
53
54    results = await check_all_worktrees_safe(worktrees)
55
56    for path, status in results.items():
57        if status.startswith("error:"):
58            print(f"[FAILED] {path}: {status}")
59        else:
60            print(f"[OK] {path}: {status}")
61
62# Output:
63# [OK] /valid/repo1: clean
64# [FAILED] /invalid/path: error: Git command failed: ...
65# [OK] /valid/repo2: M file.txt

return_exceptions 行為對比：

 1async def compare_exception_handling():
 2    async def might_fail(n: int) -> int:
 3        if n == 2:
 4            raise ValueError(f"Task {n} failed")
 5        return n * 10
 6
 7    tasks = [might_fail(i) for i in range(5)]
 8
 9    # Without return_exceptions (default)
10    try:
11        results = await asyncio.gather(*tasks)  # Raises ValueError
12    except ValueError as e:
13        print(f"Caught: {e}")  # Only see first error, others lost
14
15    # With return_exceptions=True
16    results = await asyncio.gather(*tasks, return_exceptions=True)
17    # results: [0, 10, ValueError('Task 2 failed'), 30, 40]
18
19    for i, result in enumerate(results):
20        if isinstance(result, Exception):
21            print(f"Task {i}: Failed - {result}")
22        else:
23            print(f"Task {i}: Success - {result}")

步驟 3：使用 TaskGroup（Python 3.11+）

Python 3.11 引入的 TaskGroup 提供更好的結構化並行控制：

 1import asyncio
 2from typing import Optional
 3
 4async def check_all_worktrees_taskgroup(
 5    worktrees: list[str]
 6) -> dict[str, str]:
 7    """
 8    使用 TaskGroup 並行檢查所有 worktree
 9
10    TaskGroup 特性：
11    - 任一任務失敗時，自動取消其他任務
12    - 明確的作用域（context manager）
13    - 異常聚合（ExceptionGroup）
14
15    Args:
16        worktrees: worktree 路徑列表
17
18    Returns:
19        dict[str, str]: {路徑: 狀態} 映射
20    """
21    results: dict[str, str] = {}
22
23    async def check_and_store(path: str) -> None:
24        """Check worktree and store result in shared dict"""
25        success, output = await async_run_git_command(
26            ["status", "-s"],
27            cwd=path
28        )
29        results[path] = output if success else "error"
30
31    async with asyncio.TaskGroup() as tg:
32        for path in worktrees:
33            tg.create_task(check_and_store(path))
34
35    # All tasks complete when exiting the context
36    return results
37
38async def demo_taskgroup():
39    """示範 TaskGroup 的基本用法"""
40    worktrees = ["/repo1", "/repo2", "/repo3"]
41
42    try:
43        results = await check_all_worktrees_taskgroup(worktrees)
44        for path, status in results.items():
45            print(f"{path}: {status}")
46    except* Exception as eg:
47        # Python 3.11+ except* syntax for ExceptionGroup
48        for exc in eg.exceptions:
49            print(f"Task failed: {exc}")

TaskGroup 的錯誤處理模式：

 1async def taskgroup_error_demo():
 2    """示範 TaskGroup 的異常處理"""
 3
 4    async def task_might_fail(name: str, should_fail: bool) -> str:
 5        await asyncio.sleep(0.1)
 6        if should_fail:
 7            raise ValueError(f"{name} failed!")
 8        return f"{name} succeeded"
 9
10    try:
11        async with asyncio.TaskGroup() as tg:
12            tg.create_task(task_might_fail("A", False))
13            tg.create_task(task_might_fail("B", True))   # Will fail
14            tg.create_task(task_might_fail("C", False))  # Gets cancelled
15    except* ValueError as eg:
16        print(f"Caught {len(eg.exceptions)} errors:")
17        for exc in eg.exceptions:
18            print(f"  - {exc}")
19
20# When B fails:
21# 1. TaskGroup cancels C (even though it would succeed)
22# 2. Waits for all tasks to finish
23# 3. Raises ExceptionGroup with the ValueError

步驟 4：並行與循序的混合模式

實際應用中，常需要混合並行和循序操作：

  1async def check_worktrees_batched(
  2    worktrees: list[str],
  3    batch_size: int = 5
  4) -> dict[str, str]:
  5    """
  6    分批並行處理：控制同時執行的任務數量
  7
  8    適用場景：
  9    - 避免同時開啟過多進程
 10    - 防止 API rate limiting
 11    - 控制資源使用
 12
 13    Args:
 14        worktrees: worktree 路徑列表
 15        batch_size: 每批並行數量
 16
 17    Returns:
 18        dict[str, str]: {路徑: 狀態} 映射
 19    """
 20    results: dict[str, str] = {}
 21
 22    # Process in batches
 23    for i in range(0, len(worktrees), batch_size):
 24        batch = worktrees[i:i + batch_size]
 25
 26        async def check_one(path: str) -> tuple[str, str]:
 27            success, output = await async_run_git_command(
 28                ["status", "-s"],
 29                cwd=path
 30            )
 31            return path, output if success else "error"
 32
 33        # Process batch in parallel
 34        batch_results = await asyncio.gather(
 35            *[check_one(path) for path in batch]
 36        )
 37
 38        # Collect results
 39        results.update(dict(batch_results))
 40
 41    return results
 42
 43async def check_worktrees_semaphore(
 44    worktrees: list[str],
 45    max_concurrent: int = 5
 46) -> dict[str, str]:
 47    """
 48    使用 Semaphore 限制並行數量
 49
 50    比分批更靈活：任務完成後立即啟動新任務，
 51    而不是等整批完成。
 52
 53    Args:
 54        worktrees: worktree 路徑列表
 55        max_concurrent: 最大同時執行數
 56
 57    Returns:
 58        dict[str, str]: {路徑: 狀態} 映射
 59    """
 60    semaphore = asyncio.Semaphore(max_concurrent)
 61
 62    async def check_with_limit(path: str) -> tuple[str, str]:
 63        """Check worktree with concurrency limit"""
 64        async with semaphore:
 65            # At most max_concurrent tasks run this block
 66            success, output = await async_run_git_command(
 67                ["status", "-s"],
 68                cwd=path
 69            )
 70            return path, output if success else "error"
 71
 72    # Launch all tasks (they'll wait at semaphore if needed)
 73    tasks = [check_with_limit(path) for path in worktrees]
 74    results = await asyncio.gather(*tasks)
 75
 76    return dict(results)
 77
 78async def pipeline_example():
 79    """
 80    示範流水線模式：前一步的輸出是後一步的輸入
 81    """
 82    # Step 1: Get worktree list (single operation)
 83    worktrees = await async_get_worktree_list()
 84    paths = [wt["path"] for wt in worktrees]
 85
 86    # Step 2: Check status in parallel
 87    statuses = await check_all_worktrees_basic(paths)
 88
 89    # Step 3: For dirty repos, get detailed diff (parallel)
 90    dirty_paths = [p for p, s in statuses.items() if s]
 91
 92    async def get_diff(path: str) -> tuple[str, str]:
 93        success, diff = await async_run_git_command(["diff"], cwd=path)
 94        return path, diff if success else ""
 95
 96    diffs = dict(await asyncio.gather(
 97        *[get_diff(p) for p in dirty_paths]
 98    ))
 99
100    return {"statuses": statuses, "diffs": diffs}

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3並行 I/O 操作工具 - 完整範例
  4
  5展示如何用 asyncio.gather 和 TaskGroup 實現高效的並行 Git 操作。
  6"""
  7
  8import asyncio
  9import time
 10from typing import Optional
 11
 12# ===== Core async function =====
 13
 14async def async_run_git_command(
 15    args: list[str],
 16    cwd: Optional[str] = None,
 17    timeout: float = 10.0
 18) -> tuple[bool, str]:
 19    """
 20    非同步執行 git 命令
 21
 22    Args:
 23        args: git 命令參數列表
 24        cwd: 執行目錄
 25        timeout: 超時時間（秒）
 26
 27    Returns:
 28        (是否成功, 輸出或錯誤訊息)
 29    """
 30    try:
 31        process = await asyncio.create_subprocess_exec(
 32            "git", *args,
 33            cwd=cwd,
 34            stdout=asyncio.subprocess.PIPE,
 35            stderr=asyncio.subprocess.PIPE
 36        )
 37
 38        try:
 39            stdout, stderr = await asyncio.wait_for(
 40                process.communicate(),
 41                timeout=timeout
 42            )
 43        except asyncio.TimeoutError:
 44            process.kill()
 45            await process.wait()
 46            return False, f"Command timed out after {timeout}s"
 47
 48        if process.returncode == 0:
 49            return True, stdout.decode().strip()
 50        else:
 51            return False, stderr.decode().strip()
 52
 53    except FileNotFoundError:
 54        return False, "git command not found"
 55    except Exception as e:
 56        return False, str(e)
 57
 58async def async_get_worktree_list() -> list[dict]:
 59    """獲取 worktree 列表"""
 60    success, output = await async_run_git_command(
 61        ["worktree", "list", "--porcelain"]
 62    )
 63    if not success:
 64        return []
 65
 66    worktrees = []
 67    current_worktree: dict = {}
 68
 69    for line in output.split("\n"):
 70        if line.startswith("worktree "):
 71            if current_worktree:
 72                worktrees.append(current_worktree)
 73            current_worktree = {"path": line[9:]}
 74        elif line.startswith("branch "):
 75            branch_ref = line[7:]
 76            if branch_ref.startswith("refs/heads/"):
 77                branch_ref = branch_ref[11:]
 78            current_worktree["branch"] = branch_ref
 79        elif line == "detached":
 80            current_worktree["detached"] = True
 81
 82    if current_worktree:
 83        worktrees.append(current_worktree)
 84
 85    return worktrees
 86
 87# ===== Parallel strategies =====
 88
 89async def parallel_with_gather(
 90    worktrees: list[str],
 91    return_exceptions: bool = False
 92) -> dict[str, str]:
 93    """
 94    Strategy 1: asyncio.gather
 95
 96    Args:
 97        worktrees: worktree 路徑列表
 98        return_exceptions: 是否將異常作為結果返回
 99
100    Returns:
101        dict[str, str]: 檢查結果
102    """
103    async def check_one(path: str) -> tuple[str, str]:
104        success, output = await async_run_git_command(
105            ["status", "-s"],
106            cwd=path
107        )
108        return path, output if success else "error"
109
110    tasks = [check_one(path) for path in worktrees]
111    results = await asyncio.gather(*tasks, return_exceptions=return_exceptions)
112
113    output = {}
114    for path, result in zip(worktrees, results):
115        if isinstance(result, Exception):
116            output[path] = f"exception: {result}"
117        else:
118            _, status = result
119            output[path] = status if status else "clean"
120
121    return output
122
123async def parallel_with_taskgroup(worktrees: list[str]) -> dict[str, str]:
124    """
125    Strategy 2: TaskGroup (Python 3.11+)
126
127    One task fails -> all cancelled
128    """
129    results: dict[str, str] = {}
130
131    async def check_and_store(path: str) -> None:
132        success, output = await async_run_git_command(
133            ["status", "-s"],
134            cwd=path
135        )
136        results[path] = output if success else "error"
137
138    async with asyncio.TaskGroup() as tg:
139        for path in worktrees:
140            tg.create_task(check_and_store(path))
141
142    return results
143
144async def parallel_with_semaphore(
145    worktrees: list[str],
146    max_concurrent: int = 5
147) -> dict[str, str]:
148    """
149    Strategy 3: Semaphore for rate limiting
150    """
151    semaphore = asyncio.Semaphore(max_concurrent)
152
153    async def check_with_limit(path: str) -> tuple[str, str]:
154        async with semaphore:
155            success, output = await async_run_git_command(
156                ["status", "-s"],
157                cwd=path
158            )
159            return path, output if success else "error"
160
161    tasks = [check_with_limit(path) for path in worktrees]
162    results = await asyncio.gather(*tasks)
163
164    return dict(results)
165
166# ===== Practical helpers =====
167
168async def get_worktree_status_report() -> dict:
169    """
170    生成完整的 worktree 狀態報告
171
172    Returns:
173        dict: 包含狀態、分支、變更的完整報告
174    """
175    # Step 1: Get worktree list
176    worktrees = await async_get_worktree_list()
177    paths = [wt["path"] for wt in worktrees]
178
179    if not paths:
180        return {"error": "No worktrees found"}
181
182    # Step 2: Parallel operations
183    async def get_status(path: str) -> tuple[str, str]:
184        success, output = await async_run_git_command(
185            ["status", "-s"],
186            cwd=path
187        )
188        return path, output if success else "error"
189
190    async def get_branch(path: str) -> tuple[str, str]:
191        success, output = await async_run_git_command(
192            ["branch", "--show-current"],
193            cwd=path
194        )
195        return path, output if success else "unknown"
196
197    async def get_last_commit(path: str) -> tuple[str, str]:
198        success, output = await async_run_git_command(
199            ["log", "-1", "--format=%s"],
200            cwd=path
201        )
202        return path, output if success else "unknown"
203
204    # Execute all queries in parallel
205    status_task = asyncio.gather(*[get_status(p) for p in paths])
206    branch_task = asyncio.gather(*[get_branch(p) for p in paths])
207    commit_task = asyncio.gather(*[get_last_commit(p) for p in paths])
208
209    statuses, branches, commits = await asyncio.gather(
210        status_task, branch_task, commit_task
211    )
212
213    # Combine results
214    report = {}
215    for wt in worktrees:
216        path = wt["path"]
217        status_dict = dict(statuses)
218        branch_dict = dict(branches)
219        commit_dict = dict(commits)
220
221        report[path] = {
222            "branch": branch_dict.get(path, "unknown"),
223            "status": status_dict.get(path, "error"),
224            "is_clean": not status_dict.get(path, "error"),
225            "last_commit": commit_dict.get(path, "unknown"),
226        }
227
228    return report
229
230# ===== Benchmark =====
231
232async def benchmark_strategies(worktrees: list[str]) -> dict[str, float]:
233    """
234    比較不同策略的執行時間
235    """
236    results = {}
237
238    # Strategy 1: Sequential (baseline)
239    start = time.perf_counter()
240    for path in worktrees:
241        await async_run_git_command(["status", "-s"], cwd=path)
242    results["sequential"] = time.perf_counter() - start
243
244    # Strategy 2: gather
245    start = time.perf_counter()
246    await parallel_with_gather(worktrees)
247    results["gather"] = time.perf_counter() - start
248
249    # Strategy 3: TaskGroup
250    start = time.perf_counter()
251    await parallel_with_taskgroup(worktrees)
252    results["taskgroup"] = time.perf_counter() - start
253
254    # Strategy 4: Semaphore
255    start = time.perf_counter()
256    await parallel_with_semaphore(worktrees, max_concurrent=3)
257    results["semaphore(3)"] = time.perf_counter() - start
258
259    return results
260
261# ===== Demo =====
262
263async def demo():
264    """示範並行 I/O 操作"""
265    print("=== 並行 I/O 操作示範 ===\n")
266
267    # Get worktrees
268    print("1. 獲取 worktree 列表:")
269    worktrees = await async_get_worktree_list()
270    paths = [wt["path"] for wt in worktrees]
271
272    for wt in worktrees:
273        branch = wt.get("branch", "detached")
274        print(f"   - {branch}: {wt['path']}")
275    print()
276
277    if len(paths) >= 1:
278        # Benchmark
279        print("2. 效能比較:")
280        times = await benchmark_strategies(paths)
281        for strategy, elapsed in times.items():
282            print(f"   {strategy}: {elapsed:.3f}s")
283
284        speedup = times["sequential"] / times["gather"]
285        print(f"   加速比: {speedup:.1f}x")
286        print()
287
288        # Full report
289        print("3. 完整狀態報告:")
290        report = await get_worktree_status_report()
291        for path, info in report.items():
292            status = "clean" if info["is_clean"] else "dirty"
293            print(f"   [{info['branch']}] {path}")
294            print(f"       狀態: {status}")
295            print(f"       最新提交: {info['last_commit'][:50]}...")
296
297if __name__ == "__main__":
298    asyncio.run(demo())

使用範例

基本使用

 1import asyncio
 2
 3async def main():
 4    # Get all worktree paths
 5    worktrees = await async_get_worktree_list()
 6    paths = [wt["path"] for wt in worktrees]
 7
 8    # Check all in parallel
 9    statuses = await parallel_with_gather(paths)
10
11    for path, status in statuses.items():
12        print(f"{path}: {status or 'clean'}")
13
14asyncio.run(main())

處理大量 worktree

 1async def check_many_worktrees(paths: list[str]):
 2    """處理大量 worktree 時使用 semaphore 限制並行數"""
 3    # Limit to 10 concurrent git processes
 4    results = await parallel_with_semaphore(paths, max_concurrent=10)
 5
 6    clean_count = sum(1 for s in results.values() if not s or s == "clean")
 7    dirty_count = len(results) - clean_count
 8
 9    print(f"Clean: {clean_count}, Dirty: {dirty_count}")
10    return results

與錯誤重試結合

 1async def check_with_retry(
 2    path: str,
 3    max_retries: int = 3
 4) -> tuple[str, str]:
 5    """帶重試的檢查"""
 6    for attempt in range(max_retries):
 7        success, output = await async_run_git_command(
 8            ["status", "-s"],
 9            cwd=path,
10            timeout=5.0
11        )
12
13        if success:
14            return path, output
15
16        if attempt < max_retries - 1:
17            await asyncio.sleep(0.5 * (attempt + 1))  # Backoff
18
19    return path, "error: max retries exceeded"
20
21async def check_all_with_retry(paths: list[str]) -> dict[str, str]:
22    """所有檢查都帶重試機制"""
23    tasks = [check_with_retry(p) for p in paths]
24    results = await asyncio.gather(*tasks)
25    return dict(results)

設計權衡

面向	asyncio.gather	TaskGroup	Semaphore
Python 版本	3.4+	3.11+	3.4+
錯誤處理	`return_exceptions`	自動取消其他任務	同 gather
取消行為	需手動處理	結構化取消	需手動處理
程式碼可讀性	中等	較高	中等
並行控制	無內建限制	無內建限制	可限制數量
適用場景	一般並行	全有或全無	需要限流

選擇指南

1需要並行執行多個獨立 I/O 操作？
2├── 是 → 是否需要「一個失敗全部取消」？
3│        ├── 是 → 使用 TaskGroup
4│        └── 否 → 是否需要限制並行數量？
5│                 ├── 是 → 使用 Semaphore + gather
6│                 └── 否 → 使用 gather（可選 return_exceptions）
7└── 否 → 直接使用 await

什麼時候該用這個技術？

適合使用：

多個獨立的 I/O 操作（HTTP 請求、檔案讀取、資料庫查詢）
需要等待所有操作完成
操作之間沒有依賴關係
單一操作耗時較長（> 10ms）

不建議使用：

CPU 密集計算（應用 multiprocessing）
操作之間有依賴關係（應用循序執行或流水線）
單一操作極快（overhead 可能大於收益）
外部服務有嚴格的 rate limit（需要更精細的控制）

練習

基礎練習

練習 1：用 gather 同時讀取多個設定檔

1async def read_configs(paths: list[str]) -> dict[str, str]:
2    """
3    並行讀取多個設定檔
4
5    提示：使用 aiofiles 或 asyncio.to_thread
6    """
7    # Your implementation here
8    pass

練習 2：實作 worktree 狀態快取

 1class WorktreeCache:
 2    """
 3    快取 worktree 狀態，避免頻繁查詢
 4
 5    提示：
 6    - 使用 dict 儲存狀態
 7    - 設定過期時間
 8    - 過期時重新並行查詢
 9    """
10    def __init__(self, ttl_seconds: float = 30.0):
11        self._cache: dict[str, tuple[str, float]] = {}
12        self._ttl = ttl_seconds
13
14    async def get_status(self, path: str) -> str:
15        # Your implementation here
16        pass
17
18    async def get_all_statuses(self, paths: list[str]) -> dict[str, str]:
19        # Your implementation here
20        pass

進階練習

練習 3：實作帶有重試邏輯的並行下載器

 1async def parallel_download(
 2    urls: list[str],
 3    max_concurrent: int = 5,
 4    max_retries: int = 3
 5) -> dict[str, bytes | Exception]:
 6    """
 7    並行下載多個 URL，支援重試
 8
 9    提示：
10    - 使用 Semaphore 限制並行數
11    - 實作指數退避（exponential backoff）
12    - 使用 aiohttp 進行非同步 HTTP 請求
13    """
14    # Your implementation here
15    pass

挑戰題

練習 4：實作 semaphore 限制並行數量的 TaskGroup

 1class BoundedTaskGroup:
 2    """
 3    限制最大並行數的 TaskGroup
 4
 5    使用方式：
 6        async with BoundedTaskGroup(max_concurrent=5) as tg:
 7            for item in items:
 8                tg.create_task(process(item))
 9
10    提示：
11    - 結合 Semaphore 和 TaskGroup
12    - 保持 TaskGroup 的錯誤處理語義
13    """
14    def __init__(self, max_concurrent: int):
15        self._semaphore = asyncio.Semaphore(max_concurrent)
16        self._tg: asyncio.TaskGroup | None = None
17
18    async def __aenter__(self):
19        # Your implementation here
20        pass
21
22    async def __aexit__(self, *args):
23        # Your implementation here
24        pass
25
26    def create_task(self, coro):
27        # Your implementation here
28        pass

練習 5：實作監控儀表板

建立一個即時監控多個 Git repo 狀態的工具：

 1async def monitor_repos(
 2    repos: list[str],
 3    interval: float = 5.0,
 4    on_change: callable = None
 5):
 6    """
 7    每隔 interval 秒並行檢查所有 repo
 8    狀態變化時呼叫 on_change callback
 9
10    提示：
11    - 使用 asyncio.sleep 控制間隔
12    - 比較前後狀態找出變化
13    - 支援 Ctrl+C 優雅退出
14    """
15    # Your implementation here
16    pass

案例：同步/非同步橋接

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib 整體架構，展示如何用 run_in_executor 和 asyncio.run 在同步與非同步程式碼之間建立橋樑。

先備知識

問題背景

現有設計

.claude/lib 是一個同步設計的 Python 工具庫，包含多個模組：

 1# .claude/lib/__init__.py
 2"""
 3Claude Hooks 共用程式庫
 4
 5模組結構:
 6- git_utils: Git 操作工具（分支、worktree、專案根目錄）
 7- config_loader: 配置檔案載入
 8- hook_io: Hook 輸入輸出處理
 9- hook_validator: Hook 合規性驗證
10- markdown_link_checker: Markdown 連結檢查
11"""
12
13from .git_utils import (
14    run_git_command,
15    get_current_branch,
16    get_project_root,
17    get_worktree_list,
18)
19
20from .config_loader import (
21    load_config,
22    load_agents_config,
23)
24
25from .hook_io import (
26    read_hook_input,
27    write_hook_output,
28)

這些函式都是同步的：

 1# git_utils.py - 同步的 subprocess 呼叫
 2def run_git_command(
 3    args: list[str],
 4    cwd: Optional[str] = None,
 5    timeout: int = 10
 6) -> tuple[bool, str]:
 7    """Execute git command and return result"""
 8    result = subprocess.run(
 9        ["git"] + args,
10        cwd=cwd,
11        capture_output=True,
12        text=True,
13        timeout=timeout
14    )
15    if result.returncode == 0:
16        return True, result.stdout.strip()
17    return False, result.stderr.strip()
18
19# config_loader.py - 同步的檔案 I/O
20def load_config(config_name: str) -> dict:
21    """Load configuration file"""
22    config_dir = get_config_dir()
23    yaml_path = config_dir / f"{config_name}.yaml"
24
25    with open(yaml_path, "r", encoding="utf-8") as f:
26        return yaml.safe_load(f)
27
28# hook_validator.py - 同步的檔案驗證
29def validate_hook(hook_path: str) -> ValidationResult:
30    """Validate a single hook file"""
31    with open(hook_path, "r", encoding="utf-8") as f:
32        content = f.read()
33    # ... validation logic

這個設計的優點

簡單直覺：不需要了解 asyncio，任何 Python 開發者都能使用
向後相容：可以在任何 Python 環境中執行
測試容易：同步程式碼的測試更直觀
依賴少：不需要額外的非同步依賴庫

這個設計的限制

在非同步環境（如 FastAPI、aiohttp）中使用時：

問題 1：阻塞事件迴圈

 1from fastapi import FastAPI
 2from lib.git_utils import get_current_branch, get_worktree_list
 3
 4app = FastAPI()
 5
 6@app.get("/git/status")
 7async def get_git_status():
 8    # BAD: These synchronous calls block the event loop!
 9    branch = get_current_branch()      # Blocks ~50ms
10    worktrees = get_worktree_list()    # Blocks ~50ms
11
12    # During these 100ms, NO other requests can be processed!
13    return {"branch": branch, "worktrees": worktrees}

問題 2：無法並行執行

 1def validate_all_hooks(hooks_dir: str) -> list[ValidationResult]:
 2    """Validate all hooks - sequential execution"""
 3    results = []
 4    for hook_file in Path(hooks_dir).glob("*.py"):
 5        # Each validation runs one after another
 6        result = validate_hook(str(hook_file))  # ~10ms each
 7        results.append(result)
 8    return results
 9
10# 10 hooks = 100ms total
11# With parallelization, could be ~10ms!

問題 3：無法有效利用等待時間

 1def check_project_health() -> dict:
 2    """Check multiple aspects of project health"""
 3    # All I/O operations execute sequentially
 4    git_status = run_git_command(["status", "-s"])      # Wait...
 5    config = load_config("agents")                       # Wait...
 6    links = check_markdown_links("docs/README.md")       # Wait...
 7
 8    # Total time = sum of all operations
 9    return {
10        "git": git_status,
11        "config": config,
12        "links": links
13    }

進階解決方案

設計目標

在非同步程式碼中安全地呼叫同步函式（不阻塞事件迴圈）
在同步程式碼中使用非同步函式（保持向後相容）
避免巢狀事件迴圈問題
保持原有 API 不變

實作步驟

步驟 1：run_in_executor - 同步到非同步

run_in_executor 將同步函式放到執行緒池中執行，讓事件迴圈可以繼續處理其他任務。

 1import asyncio
 2from concurrent.futures import ThreadPoolExecutor
 3from typing import TypeVar, Callable, Any
 4
 5T = TypeVar('T')
 6
 7# Create a shared thread pool for I/O operations
 8_io_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="async_io")
 9
10async def run_sync_in_executor(
11    func: Callable[..., T],
12    *args: Any,
13    **kwargs: Any
14) -> T:
15    """
16    Run a synchronous function in a thread pool executor.
17
18    This prevents blocking the event loop when calling
19    synchronous I/O operations from async code.
20
21    Args:
22        func: The synchronous function to execute
23        *args: Positional arguments for the function
24        **kwargs: Keyword arguments for the function
25
26    Returns:
27        The result of the function call
28
29    Example:
30        # Instead of blocking:
31        result = sync_function(arg1, arg2)
32
33        # Use executor:
34        result = await run_sync_in_executor(sync_function, arg1, arg2)
35    """
36    loop = asyncio.get_running_loop()
37
38    # functools.partial handles kwargs
39    if kwargs:
40        import functools
41        func = functools.partial(func, **kwargs)
42
43    return await loop.run_in_executor(_io_executor, func, *args)

使用範例：包裝現有同步函式

 1from lib.git_utils import get_current_branch, get_worktree_list, run_git_command
 2from lib.config_loader import load_config
 3from lib.hook_validator import validate_hook
 4
 5# Async wrappers for existing sync functions
 6async def async_get_current_branch() -> Optional[str]:
 7    """Async wrapper for get_current_branch"""
 8    return await run_sync_in_executor(get_current_branch)
 9
10async def async_get_worktree_list() -> list[dict]:
11    """Async wrapper for get_worktree_list"""
12    return await run_sync_in_executor(get_worktree_list)
13
14async def async_load_config(config_name: str) -> dict:
15    """Async wrapper for load_config"""
16    return await run_sync_in_executor(load_config, config_name)
17
18async def async_validate_hook(hook_path: str) -> ValidationResult:
19    """Async wrapper for validate_hook"""
20    return await run_sync_in_executor(validate_hook, hook_path)

步驟 2：asyncio.run - 非同步到同步

當你有非同步程式碼，但需要從同步環境呼叫時，使用 asyncio.run。

 1import asyncio
 2from typing import TypeVar, Coroutine
 3
 4T = TypeVar('T')
 5
 6def run_async(coro: Coroutine[Any, Any, T]) -> T:
 7    """
 8    Run an async function from synchronous code.
 9
10    Creates a new event loop if none exists.
11    Safe to call from synchronous entry points.
12
13    Args:
14        coro: The coroutine to execute
15
16    Returns:
17        The result of the coroutine
18
19    Example:
20        # From a synchronous script:
21        result = run_async(async_function(arg1, arg2))
22
23    Warning:
24        Cannot be called when an event loop is already running!
25        Use nest_asyncio or redesign your code structure.
26    """
27    return asyncio.run(coro)
28
29# Synchronous API that uses async implementation internally
30def get_all_worktree_branches() -> dict[str, str]:
31    """
32    Get branches for all worktrees.
33
34    Uses async implementation internally for parallelization,
35    but provides a synchronous API for compatibility.
36    """
37    async def _async_impl():
38        worktrees = await async_get_worktree_list()
39        tasks = []
40        for wt in worktrees:
41            path = wt["path"]
42            tasks.append(_get_branch_for_path(path))
43        results = await asyncio.gather(*tasks)
44        return dict(zip([wt["path"] for wt in worktrees], results))
45
46    return run_async(_async_impl())
47
48async def _get_branch_for_path(path: str) -> str:
49    """Get current branch for a specific path"""
50    success, output = await run_sync_in_executor(
51        run_git_command,
52        ["branch", "--show-current"],
53        cwd=path
54    )
55    return output if success else "unknown"

步驟 3：處理已存在的事件迴圈

當你在已有事件迴圈的環境中（如 Jupyter Notebook、某些 Web 框架），直接呼叫 asyncio.run 會失敗：

1# This will raise RuntimeError in Jupyter or when loop is running
2asyncio.run(some_coroutine())
3# RuntimeError: asyncio.run() cannot be called from a running event loop

解決方案 A：使用 nest_asyncio（快速修復）

 1# pip install nest-asyncio
 2import nest_asyncio
 3
 4def run_async_safe(coro: Coroutine[Any, Any, T]) -> T:
 5    """
 6    Run async code safely, even from a running event loop.
 7
 8    Uses nest_asyncio to allow nested event loops.
 9    This is a pragmatic solution for environments like Jupyter.
10
11    Note:
12        nest_asyncio patches the event loop globally.
13        Use with caution in production code.
14    """
15    try:
16        loop = asyncio.get_running_loop()
17    except RuntimeError:
18        # No running loop - safe to use asyncio.run
19        return asyncio.run(coro)
20
21    # Running loop exists - need to nest
22    nest_asyncio.apply()
23    return loop.run_until_complete(coro)

解決方案 B：偵測執行環境（推薦）

 1import asyncio
 2from typing import TypeVar, Coroutine, Any
 3
 4T = TypeVar('T')
 5
 6def is_event_loop_running() -> bool:
 7    """Check if there's a running event loop"""
 8    try:
 9        asyncio.get_running_loop()
10        return True
11    except RuntimeError:
12        return False
13
14def run_async_adaptive(coro: Coroutine[Any, Any, T]) -> T:
15    """
16    Run async code with automatic environment detection.
17
18    - If no event loop: uses asyncio.run()
19    - If loop running: uses run_in_executor to run in a new thread
20
21    This is safer than nest_asyncio for production use.
22    """
23    if is_event_loop_running():
24        # We're in an async context - run in a new thread
25        import concurrent.futures
26        with concurrent.futures.ThreadPoolExecutor() as executor:
27            future = executor.submit(asyncio.run, coro)
28            return future.result()
29    else:
30        # Safe to run directly
31        return asyncio.run(coro)

解決方案 C：提供雙重 API（最佳實踐）

 1class GitUtils:
 2    """
 3    Git utilities with both sync and async APIs.
 4
 5    Usage:
 6        # Synchronous (traditional)
 7        utils = GitUtils()
 8        branch = utils.get_current_branch()
 9
10        # Asynchronous
11        branch = await utils.async_get_current_branch()
12    """
13
14    def __init__(self, cwd: Optional[str] = None):
15        self.cwd = cwd
16
17    # ===== Synchronous API (original) =====
18
19    def get_current_branch(self) -> Optional[str]:
20        """Get current branch (sync)"""
21        success, output = run_git_command(
22            ["branch", "--show-current"],
23            cwd=self.cwd
24        )
25        return output if success else None
26
27    def get_worktree_list(self) -> list[dict]:
28        """Get worktree list (sync)"""
29        # ... original implementation
30        pass
31
32    # ===== Asynchronous API =====
33
34    async def async_get_current_branch(self) -> Optional[str]:
35        """Get current branch (async)"""
36        return await run_sync_in_executor(self.get_current_branch)
37
38    async def async_get_worktree_list(self) -> list[dict]:
39        """Get worktree list (async)"""
40        return await run_sync_in_executor(self.get_worktree_list)

步驟 4：建立統一的 API

整合以上模式，建立一個統一的適配器：

  1"""
  2Sync/Async Bridge Adapter
  3
  4Provides unified access to .claude/lib modules from both
  5synchronous and asynchronous contexts.
  6"""
  7
  8import asyncio
  9import functools
 10from concurrent.futures import ThreadPoolExecutor
 11from typing import TypeVar, Callable, Any, Optional, Coroutine
 12
 13T = TypeVar('T')
 14
 15# Shared executor for I/O operations
 16_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="lib_async")
 17
 18class AsyncAdapter:
 19    """
 20    Adapter for converting sync functions to async.
 21
 22    Provides both decorator and wrapper patterns for flexibility.
 23
 24    Example:
 25        adapter = AsyncAdapter()
 26
 27        # As decorator
 28        @adapter.make_async
 29        def sync_function(x):
 30            return x * 2
 31
 32        result = await sync_function(5)
 33
 34        # As wrapper
 35        result = await adapter.run(other_sync_function, arg1, arg2)
 36    """
 37
 38    def __init__(self, executor: Optional[ThreadPoolExecutor] = None):
 39        self.executor = executor or _executor
 40
 41    async def run(
 42        self,
 43        func: Callable[..., T],
 44        *args: Any,
 45        **kwargs: Any
 46    ) -> T:
 47        """Run a sync function asynchronously"""
 48        loop = asyncio.get_running_loop()
 49
 50        if kwargs:
 51            func = functools.partial(func, **kwargs)
 52
 53        return await loop.run_in_executor(self.executor, func, *args)
 54
 55    def make_async(self, func: Callable[..., T]) -> Callable[..., Coroutine[Any, Any, T]]:
 56        """
 57        Decorator to create async version of sync function.
 58
 59        Example:
 60            @adapter.make_async
 61            def slow_io_operation(path: str) -> str:
 62                with open(path) as f:
 63                    return f.read()
 64
 65            # Now can be awaited
 66            content = await slow_io_operation("file.txt")
 67        """
 68        @functools.wraps(func)
 69        async def wrapper(*args: Any, **kwargs: Any) -> T:
 70            return await self.run(func, *args, **kwargs)
 71        return wrapper
 72
 73class SyncAdapter:
 74    """
 75    Adapter for calling async functions from sync code.
 76
 77    Example:
 78        adapter = SyncAdapter()
 79
 80        # Run async function synchronously
 81        result = adapter.run(async_function(arg1, arg2))
 82    """
 83
 84    @staticmethod
 85    def run(coro: Coroutine[Any, Any, T]) -> T:
 86        """
 87        Run a coroutine from synchronous code.
 88
 89        Automatically handles the case when an event loop
 90        is already running.
 91        """
 92        try:
 93            asyncio.get_running_loop()
 94            # Loop is running - use thread
 95            import concurrent.futures
 96            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
 97                future = ex.submit(asyncio.run, coro)
 98                return future.result()
 99        except RuntimeError:
100            # No running loop - safe to use asyncio.run
101            return asyncio.run(coro)
102
103    @staticmethod
104    def make_sync(
105        async_func: Callable[..., Coroutine[Any, Any, T]]
106    ) -> Callable[..., T]:
107        """
108        Decorator to create sync version of async function.
109
110        Example:
111            @SyncAdapter.make_sync
112            async def async_fetch(url: str) -> str:
113                async with aiohttp.get(url) as resp:
114                    return await resp.text()
115
116            # Now can be called synchronously
117            content = async_fetch("https://example.com")
118        """
119        @functools.wraps(async_func)
120        def wrapper(*args: Any, **kwargs: Any) -> T:
121            coro = async_func(*args, **kwargs)
122            return SyncAdapter.run(coro)
123        return wrapper

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Sync/Async Bridge for .claude/lib
  4
  5This module provides async wrappers for the synchronous
  6.claude/lib modules, enabling their use in async contexts
  7like FastAPI without blocking the event loop.
  8
  9Usage:
 10    # In async code (FastAPI, aiohttp, etc.)
 11    from lib_async import (
 12        async_get_current_branch,
 13        async_load_config,
 14        async_validate_hooks,
 15    )
 16
 17    branch = await async_get_current_branch()
 18
 19    # In sync code that needs parallelization
 20    from lib_async import parallel_validate_hooks
 21
 22    results = parallel_validate_hooks(hooks_dir)
 23"""
 24
 25import asyncio
 26import functools
 27from concurrent.futures import ThreadPoolExecutor
 28from pathlib import Path
 29from typing import TypeVar, Callable, Any, Optional, Coroutine
 30
 31# Import original sync modules
 32from lib.git_utils import (
 33    run_git_command,
 34    get_current_branch,
 35    get_project_root,
 36    get_worktree_list,
 37    is_protected_branch,
 38    is_allowed_branch,
 39)
 40from lib.config_loader import (
 41    load_config,
 42    load_agents_config,
 43    load_quality_rules,
 44)
 45from lib.hook_io import (
 46    read_hook_input,
 47    write_hook_output,
 48)
 49from lib.hook_validator import (
 50    validate_hook,
 51    validate_all_hooks,
 52    ValidationResult,
 53)
 54from lib.markdown_link_checker import (
 55    check_markdown_links,
 56    check_directory as check_markdown_directory,
 57    LinkCheckResult,
 58)
 59
 60T = TypeVar('T')
 61
 62# ===== Shared Resources =====
 63
 64# Thread pool for I/O-bound sync operations
 65_io_executor = ThreadPoolExecutor(
 66    max_workers=10,
 67    thread_name_prefix="lib_async_io"
 68)
 69
 70# ===== Core Utilities =====
 71
 72async def run_in_executor(
 73    func: Callable[..., T],
 74    *args: Any,
 75    **kwargs: Any
 76) -> T:
 77    """
 78    Run a synchronous function in the thread pool executor.
 79
 80    Args:
 81        func: Synchronous function to execute
 82        *args: Positional arguments
 83        **kwargs: Keyword arguments
 84
 85    Returns:
 86        Function result
 87    """
 88    loop = asyncio.get_running_loop()
 89
 90    if kwargs:
 91        func = functools.partial(func, **kwargs)
 92
 93    return await loop.run_in_executor(_io_executor, func, *args)
 94
 95def make_async(func: Callable[..., T]) -> Callable[..., Coroutine[Any, Any, T]]:
 96    """
 97    Decorator to create async version of a sync function.
 98
 99    Example:
100        @make_async
101        def slow_operation(x):
102            time.sleep(1)
103            return x * 2
104
105        result = await slow_operation(5)
106    """
107    @functools.wraps(func)
108    async def wrapper(*args: Any, **kwargs: Any) -> T:
109        return await run_in_executor(func, *args, **kwargs)
110    return wrapper
111
112# ===== Async Git Utils =====
113
114async def async_run_git_command(
115    args: list[str],
116    cwd: Optional[str] = None,
117    timeout: int = 10
118) -> tuple[bool, str]:
119    """Async version of run_git_command"""
120    return await run_in_executor(run_git_command, args, cwd=cwd, timeout=timeout)
121
122async def async_get_current_branch() -> Optional[str]:
123    """Async version of get_current_branch"""
124    return await run_in_executor(get_current_branch)
125
126async def async_get_project_root() -> str:
127    """Async version of get_project_root"""
128    return await run_in_executor(get_project_root)
129
130async def async_get_worktree_list() -> list[dict]:
131    """Async version of get_worktree_list"""
132    return await run_in_executor(get_worktree_list)
133
134# ===== Async Config Loader =====
135
136async def async_load_config(config_name: str) -> dict:
137    """Async version of load_config"""
138    return await run_in_executor(load_config, config_name)
139
140async def async_load_agents_config() -> dict:
141    """Async version of load_agents_config"""
142    return await run_in_executor(load_agents_config)
143
144async def async_load_quality_rules() -> dict:
145    """Async version of load_quality_rules"""
146    return await run_in_executor(load_quality_rules)
147
148# ===== Async Hook Validator =====
149
150async def async_validate_hook(hook_path: str) -> ValidationResult:
151    """Async version of validate_hook"""
152    return await run_in_executor(validate_hook, hook_path)
153
154async def async_validate_all_hooks(
155    hooks_dir: Optional[str] = None
156) -> list[ValidationResult]:
157    """
158    Validate all hooks in parallel.
159
160    Unlike the sync version that validates sequentially,
161    this version validates all hooks concurrently.
162    """
163    if hooks_dir is None:
164        hooks_dir = str(Path(await async_get_project_root()) / ".claude" / "hooks")
165
166    hooks_path = Path(hooks_dir)
167    if not hooks_path.is_dir():
168        return []
169
170    # Collect all hook files
171    hook_files = [
172        str(f) for f in sorted(hooks_path.glob("*.py"))
173        if not f.name.startswith("_")
174    ]
175
176    # Validate all in parallel
177    tasks = [async_validate_hook(hook) for hook in hook_files]
178    return await asyncio.gather(*tasks)
179
180# ===== Async Markdown Link Checker =====
181
182async def async_check_markdown_links(file_path: str) -> LinkCheckResult:
183    """Async version of check_markdown_links"""
184    return await run_in_executor(check_markdown_links, file_path)
185
186async def async_check_markdown_directory(
187    dir_path: str,
188    recursive: bool = True
189) -> list[LinkCheckResult]:
190    """
191    Check all markdown files in directory in parallel.
192    """
193    # Get file list synchronously (fast operation)
194    dir_path_obj = Path(dir_path)
195    if not dir_path_obj.is_dir():
196        return []
197
198    if recursive:
199        md_files = list(dir_path_obj.rglob("*.md"))
200    else:
201        md_files = list(dir_path_obj.glob("*.md"))
202
203    # Check all files in parallel
204    tasks = [async_check_markdown_links(str(f)) for f in md_files]
205    return await asyncio.gather(*tasks)
206
207# ===== Parallel Operations =====
208
209async def async_check_all_worktrees() -> dict[str, dict]:
210    """
211    Check status of all worktrees in parallel.
212
213    Returns:
214        dict: {path: {"branch": str, "status": str, "is_clean": bool}}
215    """
216    worktrees = await async_get_worktree_list()
217
218    async def check_one(wt: dict) -> tuple[str, dict]:
219        path = wt["path"]
220
221        # Run git status and branch in parallel for each worktree
222        status_task = async_run_git_command(["status", "-s"], cwd=path)
223        branch_task = async_run_git_command(["branch", "--show-current"], cwd=path)
224
225        (status_ok, status), (branch_ok, branch) = await asyncio.gather(
226            status_task, branch_task
227        )
228
229        return path, {
230            "branch": branch if branch_ok else wt.get("branch", "unknown"),
231            "status": status if status_ok else "error",
232            "is_clean": status_ok and not status,
233        }
234
235    tasks = [check_one(wt) for wt in worktrees]
236    results = await asyncio.gather(*tasks)
237
238    return dict(results)
239
240async def async_project_health_check() -> dict:
241    """
242    Comprehensive project health check with parallel execution.
243
244    Checks:
245    - Git status
246    - Configuration validity
247    - Hook compliance
248    - Documentation links
249
250    Returns:
251        dict: Health check results
252    """
253    # Run all checks in parallel
254    git_task = async_get_current_branch()
255    worktrees_task = async_check_all_worktrees()
256    config_task = async_load_agents_config()
257    hooks_task = async_validate_all_hooks()
258
259    branch, worktrees, config, hook_results = await asyncio.gather(
260        git_task, worktrees_task, config_task, hooks_task,
261        return_exceptions=True  # Don't fail if one check fails
262    )
263
264    return {
265        "git": {
266            "branch": branch if not isinstance(branch, Exception) else str(branch),
267            "worktrees": worktrees if not isinstance(worktrees, Exception) else {},
268        },
269        "config": {
270            "loaded": not isinstance(config, Exception),
271            "agents_count": len(config.get("known_agents", [])) if not isinstance(config, Exception) else 0,
272        },
273        "hooks": {
274            "total": len(hook_results) if not isinstance(hook_results, Exception) else 0,
275            "compliant": sum(1 for r in hook_results if r.is_compliant) if not isinstance(hook_results, Exception) else 0,
276        }
277    }
278
279# ===== Sync Wrappers for Async Functions =====
280
281def parallel_validate_hooks(hooks_dir: Optional[str] = None) -> list[ValidationResult]:
282    """
283    Synchronous API that uses async parallelization internally.
284
285    Use this when you want parallelization but are in sync context.
286    """
287    return asyncio.run(async_validate_all_hooks(hooks_dir))
288
289def parallel_check_worktrees() -> dict[str, dict]:
290    """
291    Synchronous API for parallel worktree checking.
292    """
293    return asyncio.run(async_check_all_worktrees())
294
295def project_health_check() -> dict:
296    """
297    Synchronous API for comprehensive health check.
298    """
299    return asyncio.run(async_project_health_check())
300
301# ===== Demo =====
302
303async def demo():
304    """Demonstrate the sync/async bridge capabilities"""
305    import time
306
307    print("=" * 60)
308    print("Sync/Async Bridge Demo")
309    print("=" * 60)
310
311    # 1. Basic async wrapper usage
312    print("\n1. Basic async wrapper:")
313    branch = await async_get_current_branch()
314    print(f"   Current branch: {branch}")
315
316    # 2. Parallel execution comparison
317    print("\n2. Parallel vs Sequential comparison:")
318
319    # Sequential (simulated)
320    start = time.perf_counter()
321    worktrees = await async_get_worktree_list()
322    seq_time = 0
323    for wt in worktrees:
324        _ = await async_run_git_command(["status", "-s"], cwd=wt["path"])
325        seq_time += time.perf_counter() - start
326        start = time.perf_counter()
327    print(f"   Sequential check: {seq_time:.3f}s")
328
329    # Parallel
330    start = time.perf_counter()
331    results = await async_check_all_worktrees()
332    par_time = time.perf_counter() - start
333    print(f"   Parallel check: {par_time:.3f}s")
334    print(f"   Speedup: {seq_time/par_time:.1f}x")
335
336    # 3. Project health check
337    print("\n3. Project health check (parallel):")
338    start = time.perf_counter()
339    health = await async_project_health_check()
340    elapsed = time.perf_counter() - start
341
342    print(f"   Branch: {health['git']['branch']}")
343    print(f"   Worktrees: {len(health['git']['worktrees'])}")
344    print(f"   Hooks compliant: {health['hooks']['compliant']}/{health['hooks']['total']}")
345    print(f"   Time: {elapsed:.3f}s")
346
347    print("\n" + "=" * 60)
348
349if __name__ == "__main__":
350    asyncio.run(demo())

使用範例

在 FastAPI 中使用同步函式

 1from fastapi import FastAPI, HTTPException
 2from lib_async import (
 3    async_get_current_branch,
 4    async_get_worktree_list,
 5    async_check_all_worktrees,
 6    async_validate_all_hooks,
 7    async_project_health_check,
 8)
 9
10app = FastAPI()
11
12@app.get("/git/branch")
13async def get_branch():
14    """
15    Get current git branch.
16
17    Uses async wrapper to prevent blocking the event loop.
18    """
19    branch = await async_get_current_branch()
20    if branch is None:
21        raise HTTPException(status_code=500, detail="Not a git repository")
22    return {"branch": branch}
23
24@app.get("/git/worktrees")
25async def get_worktrees():
26    """
27    Get all worktrees with their status.
28
29    Checks all worktrees in parallel for fast response.
30    """
31    worktrees = await async_check_all_worktrees()
32    return {"worktrees": worktrees}
33
34@app.get("/health")
35async def health_check():
36    """
37    Comprehensive project health check.
38
39    Runs multiple checks in parallel:
40    - Git status
41    - Configuration
42    - Hook compliance
43    """
44    health = await async_project_health_check()
45    return health
46
47@app.get("/hooks/validate")
48async def validate_hooks():
49    """
50    Validate all hooks in parallel.
51
52    Much faster than sequential validation for many hooks.
53    """
54    results = await async_validate_all_hooks()
55
56    return {
57        "total": len(results),
58        "compliant": sum(1 for r in results if r.is_compliant),
59        "issues": [
60            {
61                "hook": r.hook_path,
62                "issues": [
63                    {"level": i.level, "message": i.message}
64                    for i in r.issues
65                ]
66            }
67            for r in results
68            if not r.is_compliant
69        ]
70    }

在同步腳本中使用非同步函式

 1#!/usr/bin/env python3
 2"""
 3Synchronous script that leverages async parallelization internally.
 4"""
 5
 6from lib_async import (
 7    parallel_validate_hooks,
 8    parallel_check_worktrees,
 9    project_health_check,
10)
11
12def main():
13    print("Project Health Report")
14    print("=" * 50)
15
16    # These functions use asyncio internally for parallelization
17    # but provide a synchronous API
18
19    # 1. Check all worktrees in parallel
20    print("\n1. Worktree Status:")
21    worktrees = parallel_check_worktrees()
22    for path, info in worktrees.items():
23        status = "clean" if info["is_clean"] else "dirty"
24        print(f"   [{info['branch']}] {path}: {status}")
25
26    # 2. Validate all hooks in parallel
27    print("\n2. Hook Validation:")
28    results = parallel_validate_hooks()
29    compliant = sum(1 for r in results if r.is_compliant)
30    print(f"   Compliant: {compliant}/{len(results)}")
31
32    for result in results:
33        if not result.is_compliant:
34            print(f"   - {result.hook_path}:")
35            for issue in result.issues:
36                print(f"     [{issue.level}] {issue.message}")
37
38    # 3. Comprehensive health check
39    print("\n3. Overall Health:")
40    health = project_health_check()
41    print(f"   Git branch: {health['git']['branch']}")
42    print(f"   Config loaded: {health['config']['loaded']}")
43    print(f"   Hooks OK: {health['hooks']['compliant']}/{health['hooks']['total']}")
44
45if __name__ == "__main__":
46    main()

Python 3.9+ 使用 asyncio.to_thread

Python 3.9 引入了 asyncio.to_thread，提供更簡潔的語法：

 1import asyncio
 2from lib.git_utils import get_current_branch, run_git_command
 3from lib.config_loader import load_config
 4
 5# Python 3.9+ simplified syntax
 6async def async_get_current_branch_39() -> Optional[str]:
 7    """Using asyncio.to_thread (Python 3.9+)"""
 8    return await asyncio.to_thread(get_current_branch)
 9
10async def async_load_config_39(config_name: str) -> dict:
11    """Using asyncio.to_thread (Python 3.9+)"""
12    return await asyncio.to_thread(load_config, config_name)
13
14async def async_run_git_command_39(
15    args: list[str],
16    cwd: Optional[str] = None
17) -> tuple[bool, str]:
18    """Using asyncio.to_thread with keyword arguments"""
19    # to_thread supports kwargs directly in Python 3.9+
20    return await asyncio.to_thread(run_git_command, args, cwd)
21
22# Comparison: run_in_executor vs to_thread
23async def comparison_demo():
24    """
25    asyncio.to_thread vs run_in_executor
26
27    to_thread advantages:
28    - Simpler syntax
29    - Better default executor management
30    - Direct kwargs support
31
32    run_in_executor advantages:
33    - Works on Python 3.7+
34    - Can use custom executors
35    - More control over thread pool
36    """
37    # run_in_executor (Python 3.7+)
38    loop = asyncio.get_running_loop()
39    result1 = await loop.run_in_executor(None, get_current_branch)
40
41    # to_thread (Python 3.9+)
42    result2 = await asyncio.to_thread(get_current_branch)
43
44    assert result1 == result2

設計權衡

面向	run_in_executor	asyncio.run	asyncio.to_thread
方向	同步 -> 非同步	非同步 -> 同步	同步 -> 非同步
執行緒	使用執行緒池	建立新事件迴圈	使用預設執行緒池
適用場景	非同步環境呼叫同步 I/O	同步入口點執行非同步	非同步環境呼叫同步 I/O
限制	需要事件迴圈存在	不能巢狀呼叫	需要 Python 3.9+
效能	高（可重用執行緒）	中（建立新迴圈開銷）	高（優化的執行緒池）
複雜度	中	低	低

ThreadPoolExecutor vs ProcessPoolExecutor

面向	ThreadPoolExecutor	ProcessPoolExecutor
適用場景	I/O 密集操作	CPU 密集操作
記憶體	共享記憶體	獨立記憶體空間
GIL	受 GIL 限制	繞過 GIL
啟動成本	低	高（進程建立）
資料傳遞	直接傳遞	需要序列化

 1from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
 2
 3# I/O-bound: use ThreadPoolExecutor
 4io_executor = ThreadPoolExecutor(max_workers=10)
 5
 6# CPU-bound: use ProcessPoolExecutor
 7cpu_executor = ProcessPoolExecutor(max_workers=4)
 8
 9async def io_bound_task():
10    """File I/O, network calls, subprocess"""
11    loop = asyncio.get_running_loop()
12    return await loop.run_in_executor(io_executor, sync_io_function)
13
14async def cpu_bound_task():
15    """Heavy computation"""
16    loop = asyncio.get_running_loop()
17    return await loop.run_in_executor(cpu_executor, sync_cpu_function)

什麼時候該用這個技術？

適合使用

漸進式遷移到 asyncio：有大量同步程式碼，需要逐步遷移
在 FastAPI 中使用同步第三方庫：如 requests、boto3、資料庫驅動
提供同步/非同步雙 API：讓使用者選擇適合的模式
並行化現有同步操作：如批次檔案處理、多 API 呼叫
整合傳統程式碼：舊系統的同步函式需要在新非同步系統中使用

不建議使用

全新專案：直接用原生 asyncio 設計
CPU 密集操作：應用 multiprocessing 或 ProcessPoolExecutor
簡單的單一操作：不需要並行的情況
效能極度敏感：執行緒池有微小開銷
已有原生非同步替代方案：如用 aiohttp 替代 requests

練習

基礎練習

用 run_in_executor 包裝 requests.get

 1import requests
 2import asyncio
 3
 4# TODO: Implement this function
 5async def async_fetch(url: str) -> str:
 6    """
 7    Fetch URL content asynchronously using requests library.
 8
 9    Hint: Use run_in_executor to wrap requests.get
10    """
11    pass
12
13# Test your implementation
14async def test():
15    content = await async_fetch("https://httpbin.org/get")
16    print(content[:200])
17
18asyncio.run(test())

參考解答

案例研究：非同步程式設計實戰 on Tarragon

案例：非同步 subprocess

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

問題：無法並行執行多個 Git 命令

問題：阻塞事件迴圈

進階解決方案：非同步 subprocess

設計目標

實作步驟

步驟 1：建立非同步命令執行器

步驟 2：建立便利函式

步驟 3：實現並行執行

完整程式碼

使用範例

基本使用

並行操作

與 FastAPI 整合

效能比較

設計權衡

什麼時候該用非同步 subprocess？

案例：並行 I/O 操作

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

進階解決方案

設計目標

實作步驟

步驟 1：使用 asyncio.gather

步驟 2：處理錯誤（return_exceptions）

步驟 3：使用 TaskGroup（Python 3.11+）

步驟 4：並行與循序的混合模式

完整程式碼

使用範例

基本使用

處理大量 worktree

與錯誤重試結合

設計權衡

選擇指南

什麼時候該用這個技術？

練習

基礎練習

練習 1：用 gather 同時讀取多個設定檔

練習 2：實作 worktree 狀態快取

進階練習

練習 3：實作帶有重試邏輯的並行下載器

挑戰題

練習 4：實作 semaphore 限制並行數量的 TaskGroup

練習 5：實作監控儀表板

延伸閱讀

案例：同步/非同步橋接

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

問題 1：阻塞事件迴圈

問題 2：無法並行執行

問題 3：無法有效利用等待時間

進階解決方案

設計目標

實作步驟

步驟 1：run_in_executor - 同步到非同步

使用範例：包裝現有同步函式

步驟 2：asyncio.run - 非同步到同步

步驟 3：處理已存在的事件迴圈

解決方案 A：使用 nest_asyncio（快速修復）

解決方案 B：偵測執行環境（推薦）

解決方案 C：提供雙重 API（最佳實踐）

步驟 4：建立統一的 API

完整程式碼

使用範例

在 FastAPI 中使用同步函式

在同步腳本中使用非同步函式

Python 3.9+ 使用 asyncio.to_thread

設計權衡