Tool Use

s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12

"加一个工具, 只加一个 @Tool 方法" -- 循环不用动, 新工具传入 defaultTools() 就行。

Harness 层: 工具分发 -- 扩展模型能触达的边界。

问题

只有 bash 时, 所有操作都走 shell。cat 截断不可预测, sed 遇到特殊字符就崩, 每次 bash 调用都是不受约束的安全面。专用工具 (read_file, write_file) 可以在工具层面做路径沙箱。

关键洞察: 加工具不需要改循环。

解决方案

+--------+      +-------+      +--------------------+
|  User  | ---> |  LLM  | ---> | defaultTools()     |
| prompt |      |       |      | {                  |
+--------+      +---+---+      |   BashTool         |
                    ^           |   ReadFileTool     |
                    |           |   WriteFileTool    |
                    +-----------+   EditFileTool     |
                    tool_result | }                  |
                                +--------------------+

Spring AI 通过 @Tool 注解自动注册和分派。
无需手写 dispatch map，框架扫描工具对象的注解方法即可。

工作原理

1. 每个工具是一个独立的类，用 @Tool 注解声明。PathValidator 做路径沙箱防止逃逸工作区。

// PathValidator —— 对应 Python 版的 safe_path() 函数
public class PathValidator {
    private final Path workDir;

    public Path resolve(String relativePath) {
        Path resolved = workDir.resolve(relativePath).toAbsolutePath().normalize();
        if (!resolved.startsWith(workDir)) {
            throw new IllegalArgumentException("Path escapes workspace: " + relativePath);
        }
        return resolved;
    }
}

// ReadFileTool —— 对应 Python 版的 run_read() 函数
public class ReadFileTool {
    private final PathValidator pathValidator;

    @Tool(description = "Read file contents. Optionally limit the number of lines returned.")
    public String readFile(
            @ToolParam(description = "Relative path to the file") String path,
            @ToolParam(description = "Maximum number of lines to read", required = false) Integer limit) {
        Path filePath = pathValidator.resolve(path);
        List<String> lines = Files.readAllLines(filePath);
        if (limit != null && limit > 0 && limit < lines.size()) {
            lines = lines.subList(0, limit);
        }
        return String.join("\n", lines);
    }
}

1. 工具注册只需传入 defaultTools()。Spring AI 扫描 @Tool 注解方法，自动完成名称映射和参数绑定。

// 对应 Python 版的 TOOL_HANDLERS 字典
// Python: TOOL_HANDLERS = {"bash": fn, "read_file": fn, "write_file": fn, "edit_file": fn}
// Java:   只需传入工具对象，@Tool 注解自动注册
this.chatClient = ChatClient.builder(chatModel)
        .defaultSystem("You are a coding agent ...")
        .defaultTools(
                new BashTool(),       // bash 命令执行
                new ReadFileTool(),   // 文件读取
                new WriteFileTool(),  // 文件写入
                new EditFileTool()    // 文件编辑（查找替换）
        )
        .build();

1. 调用代码与 s01 完全一致。循环由框架管理，开发者只需关注工具实现。

// 对比 s01，唯一变化是 defaultTools() 多传了 3 个工具对象
// 循环代码完全相同 —— 这正是 s02 的核心洞察
AgentRunner.interactive("s02", userMessage ->
        chatClient.prompt()
                .user(userMessage)
                .call()
                .content()
);

加工具 = 加一个 @Tool 类 + 传入 defaultTools()。循环永远不变。

TIPS — Python → Java 关键适配点:

• Python 的 TOOL_HANDLERS 字典 → Spring AI @Tool 注解 + defaultTools() 自动注册分派
• Python 的 safe_path() 函数 → PathValidator 类（相同的路径逃逸检查逻辑）
• Python 的 lambda **kw 参数解包 → @ToolParam 注解自动绑定参数
• Python 的 block.type == "tool_use" 判断 → Spring AI 内部自动检测和分派

相对 s01 的变更

组件	之前 (s01)	之后 (s02)
Tools	1 (BashTool)	4 (Bash, ReadFile, WriteFile, EditFile)
Dispatch	defaultTools(bash)	defaultTools(bash, read, write, edit)
路径安全	无	PathValidator 沙箱
Agent loop	不变	不变

// s01 → s02 唯一变化: defaultTools() 多传了 3 个工具对象
.defaultTools(
        new BashTool(),
        new ReadFileTool(),    // +新增
        new WriteFileTool(),   // +新增
        new EditFileTool()     // +新增
)

值得关注的设计细节

工具粒度的三个层次

s02 的 4 个工具展示了 AI Agent 工具从粗到细的设计层次：

工具	粒度	特点
BashTool	万能	什么都能干，但输出不可控、不安全
WriteFileTool	文件级	整个文件覆盖写入，简单粗暴
EditFileTool	片段级	查找替换，精准修改，不破坏文件其他部分
ReadFileTool	只读	零风险，支持行数限制

关键架构决策：通过增加专用工具来扩展能力，而不是给万能工具加更多功能。每个工具职责单一，安全校验独立。

@Tool description 直接影响 AI 的工具选择准确率

@Tool(description = "Replace exact text in a file. Only the first occurrence is replaced.")
public String editFile(
        @ToolParam(description = "Relative path to the file") String path,
        @ToolParam(description = "The exact text to find") String oldText,
        @ToolParam(description = "The replacement text") String newText) {

Spring AI 会把 @Tool 和 @ToolParam 的 description 转成 JSON Schema 发给 AI。AI 根据这段描述决定什么时候调、传什么参数。所以 description 写得好不好直接决定 AI 的工具选择准确率。

EditFileTool 为什么用 indexOf 而不用 replaceFirst

// 实际代码 —— 字符串精确匹配
int index = content.indexOf(oldText);
String updated = content.substring(0, index) + newText + content.substring(index + oldText.length());

replaceFirst() 接受正则表达式。AI 传入的 oldText 可能包含 .、*、$ 等正则特殊字符，导致匹配结果不可预测。用 indexOf + substring 做纯字符串匹配，避免正则陷阱。这也是"不信任 AI 输入"的一个具体体现。

PathValidator — 路径安全防护

所有文件工具都通过 PathValidator 校验路径，防止 AI 传入 ../../etc/passwd 之类的逃逸路径：

public Path resolve(String relativePath) {
    Path resolved = workDir.resolve(relativePath).toAbsolutePath().normalize();
    if (!resolved.startsWith(workDir)) {
        throw new IllegalArgumentException("Path escapes workspace: " + relativePath);
    }
    return resolved;
}

核心原理：resolve 后再 normalize，用 startsWith(workDir) 校验。和 Python 版的 safe_path() 逻辑完全一致。

AI Agent 安全的两个基本功（s01 + s02）：

• s01 BashTool：危险命令黑名单 + 超时 + 输出截断
• s02 PathValidator：路径逃逸防护

试一试

cd learn-claude-code
mvn exec:java -Dexec.mainClass=com.demo.learn.s02.S02ToolUse

运行前需设置环境变量: AI_API_KEY, AI_BASE_URL, AI_MODEL

试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):

1. Read the file pom.xml
2. Create a file called Greet.java with a greet(name) method
3. Edit Greet.java to add a Javadoc comment to the method
4. Read Greet.java to verify the edit worked