1. 工具使用
1.1 工具原理
（1）每个工具有一个处理函数。路径沙箱防止逃逸工作区。
python
def safe_path(p: str) -> Path:
path = (WORKDIR / p).resolve()
if not path.is_relative_to(WORKDIR):
raise ValueError(f"Path escapes workspace: {p}")
return path
def run_read(path: str, limit: int = None) -> str:
text = safe_path(path).read_text()
lines = text.splitlines()
if limit and limit < len(lines):
lines = lines[:limit]
return "\n".join(lines)[:50000]safe_path 函数 ------ 路径安全检查
验证最终路径是否仍在 WORKDIR 目录树下，如果路径通过 ../../../etc/passwd 等手段试图跳出工作目录，立即抛出异常
run_read 函数 ------ 受控文件读取
如果指定 limit 参数，只返回前 N 行（适用于大文件预览），无论内容多长，最终返回字符串不超过 50,000 字符（防止内存溢出或输出过大）
（2）dispatch map 将工具名映射到处理函数。
将大模型输出的工具名映射为具体的函数，还要包括必需的参数
python
TOOL_HANDLERS = {
"bash": lambda **kw: run_bash(kw["command"]),
"read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
"write_file": lambda **kw: run_write(kw["path"], kw["content"]),
"edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"],
kw["new_text"]),
}
（3）循环中按名称查找处理函数。循环体本身与 s01 完全一致。
python
for block in response.content:
if block.type == "tool_use":
handler = TOOL_HANDLERS.get(block.name)
output = handler(**block.input) if handler \
else f"Unknown tool: {block.name}"
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})加工具 = 加 handler + 加 schema。循环永远不变。
（4）claude code中的Edit工具描述如下
在调用Edit之前必须调用Read，有三个必须参数（file_path、old_string、new_string）和一个可选参数（replace_all）
1.2 消息规范化
教学版的 messages 列表直接发给 API, 所见即所发。但当系统变复杂后 (工具超时、用户取消、压缩替换), 内部消息列表会出现 API 不接受的格式问题。需要在发送前做一次规范化。
API 协议有三条硬性约束:
-
每个
tool_use块必须有匹配的tool_result(通过tool_use_id关联) -
user/assistant消息必须严格交替 (不能连续两条同角色) -
只接受协议定义的字段 (内部元数据会导致 400 错误)
python
def normalize_messages(messages: list) -> list:
"""将内部消息列表规范化为 API 可接受的格式。"""
normalized = []
for msg in messages:
# Step 1: 剥离内部字段
clean = {"role": msg["role"]}
if isinstance(msg.get("content"), str):
clean["content"] = msg["content"]
elif isinstance(msg.get("content"), list):
clean["content"] = [
{k: v for k, v in block.items()
if k not in ("_internal", "_source", "_timestamp")}
for block in msg["content"]
]
normalized.append(clean)
# Step 2: tool_result 配对补齐
# 收集所有已有的 tool_result ID
existing_results = set()
for msg in normalized:
if isinstance(msg.get("content"), list):
for block in msg["content"]:
if block.get("type") == "tool_result":
existing_results.add(block.get("tool_use_id"))
# 找出缺失配对的 tool_use, 插入占位 result
for msg in normalized:
if msg["role"] == "assistant" and isinstance(msg.get("content"), list):
for block in msg["content"]:
if (block.get("type") == "tool_use"
and block.get("id") not in existing_results):
# 在下一条 user 消息中补齐
normalized.append({"role": "user", "content": [{
"type": "tool_result",
"tool_use_id": block["id"],
"content": "(cancelled)",
}]})
# Step 3: 合并连续同角色消息
merged = [normalized[0]] if normalized else []
for msg in normalized[1:]:
if msg["role"] == merged[-1]["role"]:
# 合并内容
prev = merged[-1]
prev_content = prev["content"] if isinstance(prev["content"], list) \
else [{"type": "text", "text": prev["content"]}]
curr_content = msg["content"] if isinstance(msg["content"], list) \
else [{"type": "text", "text": msg["content"]}]
prev["content"] = prev_content + curr_content
else:
merged.append(msg)
return merged在 agent loop 中, 每次 API 调用前运行:
python
response = client.messages.create(
model=MODEL, system=system,
messages=normalize_messages(messages), # 规范化后再发送
tools=TOOLS, max_tokens=8000,
)关键洞察 : messages 列表是系统的内部表示, API 看到的是规范化后的副本。两者不是同一个东西。