1
# ============================================================
2
# 处理 AI 响应中的工具调用（Tool Use）
3
# ============================================================
4

5
# 存储所有工具执行结果的列表
6
# 每个元素是一个字典，包含工具调用的返回信息
7
results = []
8

9
# 遍历 AI 响应中的每个内容块（content block）
10
# response.content 可能包含文本、工具调用等多种类型
11
for block in response.content:
12
    # --------------------------------------------------------
13
    # 第一步：过滤非工具调用块
14
    # --------------------------------------------------------
15
    # 只处理 tool_use 类型的块，文本或其他类型直接跳过
16
    # tool_use 表示 AI 决定调用某个工具（如 bash、read_file 等）
17
    if block.type != "tool_use":
18
        continue
19

20
    # --------------------------------------------------------
21
    # 第二步：判断是否需要在后台执行（异步）
22
    # --------------------------------------------------------
23
    # should_run_background 判断逻辑：
24
    #   1. 优先：用户是否显式指定 run_in_background=True
25
    #   2. 兜底：命令是否包含慢操作关键词（install/build/test 等）
26
    if should_run_background(block.name, block.input):
27
        # ---------- 分支 A：后台执行（异步） ----------
28
        # 启动后台任务，立即返回任务 ID
29
        # start_background_task 会：
30
        #   1. 生成唯一 ID（如 bg_0001）
31
        #   2. 在全局字典 background_tasks 中注册任务状态
32
        #   3. 启动守护线程执行实际工具调用
33
        #   4. 立即返回任务 ID（不等待执行完成）
34
        bg_id = start_background_task(block)
35

36
        # 立即返回一个"占位"结果，告知用户任务已在后台启动
37
        results.append({
38
            "type": "tool_result",
39
            "tool_use_id": block.id,          # 关联到具体的工具调用
40
            "content": f"[Background task {bg_id} started] "
41
                       f"Result will be available when complete."
42
        })
43
    else:
44
        # ---------- 分支 B：前台执行（同步） ----------
45
        # 直接执行工具调用，会阻塞直到完成
46
        # 适用于快速操作（如 ls、git status、read_file 等）
47
        output = execute_tool(block)
48

49
        # 返回实际的执行结果
50
        results.append({
51
            "type": "tool_result",
52
            "tool_use_id": block.id,
53
            "content": output                 # 命令的实际输出
54
        })
55

56
# ============================================================
57
# 构造发送给 AI 的 user 消息（包含工具执行结果）
58
# ============================================================
59

60
# 初始化用户消息内容列表
61
# 这个消息将包含两部分：
62
#   1. 后台任务完成的通知（如果有）
63
#   2. 所有工具的执行结果
64
user_content = []
65

66
# ------------------------------------------------------------
67
# 第一部分：收集后台任务完成的通知
68
# ------------------------------------------------------------
69
# collect_background_results() 会：
70
#   1. 检查 background_tasks 中已完成的任务
71
#   2. 从 background_results 中取出输出
72
#   3. 清理已完成的任务（防止内存泄漏）
73
#   4. 返回格式化的通知列表
74
bg_notifications = collect_background_results()
75

76
if bg_notifications:
77
    # 将每条通知作为独立的文本块添加到消息中
78
    # 例如："✅ Background task bg_0001 completed: npm install finished"
79
    for notif in bg_notifications:
80
        user_content.append({"type": "text", "text": notif})
81

82
# ------------------------------------------------------------
83
# 第二部分：添加所有工具的执行结果
84
# ------------------------------------------------------------
85
# 将之前收集的所有 tool_result 追加到消息中
86
# 包括：
87
#   - 同步执行的实际结果
88
#   - 异步执行的占位通知
89
user_content.extend(results)
90

91
# ------------------------------------------------------------
92
# 第三部分：将消息添加到对话历史
93
# ------------------------------------------------------------
94
# 将工具结果作为 user 消息发送给 AI
95
# 这样 AI 就能看到工具执行的结果，并据此生成后续响应
96
#
97
# 关键设计：使用 "user" 角色而不是 "tool" 角色
98
# 原因：某些 AI 模型（如 Claude）不支持 tool 角色
99
#       用 user 消息传递工具结果是兼容性更好的做法
100
messages.append({
101
    "role": "user",
102
    "content": user_content
103
})