chore: Spring AI 重构
This commit is contained in:
abel533
+263
-63
@@ -20,99 +20,299 @@
|
||||
^ |
|
||||
| tool_result |
|
||||
+----------------+
|
||||
(loop until stop_reason != "tool_use")
|
||||
(ChatClient.call() 自动循环直到无工具调用)
|
||||
```
|
||||
|
||||
一个退出条件控制整个流程。循环持续运行, 直到模型不再调用工具。
|
||||
一个 `call()` 调用控制整个流程。Spring AI 自动循环, 直到模型不再调用工具。
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. 用户 prompt 作为第一条消息。
|
||||
### 1. 构建 ChatClient：注入模型 + 注册工具
|
||||
|
||||
```python
|
||||
messages.append({"role": "user", "content": query})
|
||||
通过 Spring Boot 自动配置注入 `ChatModel`，用 `ChatClient.builder()` 构建客户端，设置系统提示和工具。
|
||||
|
||||
```java
|
||||
// TIP: Python 版在模块级创建 client = Anthropic() 和 MODEL。
|
||||
// Spring AI 通过自动配置注入 ChatModel，再用 builder 构建 ChatClient。
|
||||
public S01AgentLoop(ChatModel chatModel) {
|
||||
this.chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem("You are a coding agent at " + System.getProperty("user.dir")
|
||||
+ ". Use bash to solve tasks. Act, don't explain.")
|
||||
.defaultTools(new BashTool()) // @Tool 注解的工具对象
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
2. 将消息和工具定义一起发给 LLM。
|
||||
### 2. `@Tool` 注解：声明式工具注册
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model=MODEL, system=SYSTEM, messages=messages,
|
||||
tools=TOOLS, max_tokens=8000,
|
||||
)
|
||||
Spring AI 通过 `@Tool` 注解自动发现和注册工具。框架在启动时扫描 `defaultTools()` 传入的对象，提取所有 `@Tool` 方法的签名和描述，生成 LLM 需要的 tool schema（名称、参数、描述），然后在每次 `call()` 请求中自动携带。
|
||||
|
||||
```java
|
||||
// BashTool —— 对应 Python 版的 run_bash() 函数
|
||||
public class BashTool {
|
||||
@Tool(description = "Run a shell command and return stdout + stderr")
|
||||
public String bash(@ToolParam(description = "The shell command to execute")
|
||||
String command) {
|
||||
// 危险命令检查 + ProcessBuilder 执行 + 超时控制 + 输出截断
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. 追加助手响应。检查 `stop_reason` -- 如果模型没有调用工具, 结束。
|
||||
> 对比 Python 版的手动注册方式：
|
||||
> - Python: `TOOLS = [{"name": "bash", "input_schema": {...}}]` + `TOOL_HANDLERS = {"bash": run_bash}`
|
||||
> - Java: 只需 `@Tool` + `@ToolParam` 注解，框架自动完成 schema 生成和方法分派
|
||||
|
||||
### 3. Spring AI 内部自动循环：`call()` 的底层实现
|
||||
|
||||
**这是理解 Java 版与 Python 版最关键的区别。** Python 版本需要手写 while 循环来驱动工具调用：
|
||||
|
||||
```python
|
||||
messages.append({"role": "assistant", "content": response.content})
|
||||
if response.stop_reason != "tool_use":
|
||||
return
|
||||
```
|
||||
|
||||
4. 执行每个工具调用, 收集结果, 作为 user 消息追加。回到第 2 步。
|
||||
|
||||
```python
|
||||
results = []
|
||||
for block in response.content:
|
||||
if block.type == "tool_use":
|
||||
output = run_bash(block.input["command"])
|
||||
results.append({
|
||||
"type": "tool_result",
|
||||
"tool_use_id": block.id,
|
||||
"content": output,
|
||||
})
|
||||
messages.append({"role": "user", "content": results})
|
||||
```
|
||||
|
||||
组装为一个完整函数:
|
||||
|
||||
```python
|
||||
def agent_loop(query):
|
||||
messages = [{"role": "user", "content": query}]
|
||||
# Python 版 —— 手动循环
|
||||
def agent_loop(messages):
|
||||
while True:
|
||||
response = client.messages.create(
|
||||
model=MODEL, system=SYSTEM, messages=messages,
|
||||
tools=TOOLS, max_tokens=8000,
|
||||
)
|
||||
response = client.messages.create(model=MODEL, messages=messages, tools=TOOLS)
|
||||
# 收集 assistant 消息
|
||||
messages.append({"role": "assistant", "content": response.content})
|
||||
|
||||
if response.stop_reason != "tool_use":
|
||||
return
|
||||
|
||||
results = []
|
||||
return response # 模型不再调用工具，退出循环
|
||||
# 执行工具并回传结果
|
||||
for block in response.content:
|
||||
if block.type == "tool_use":
|
||||
output = run_bash(block.input["command"])
|
||||
results.append({
|
||||
"type": "tool_result",
|
||||
"tool_use_id": block.id,
|
||||
"content": output,
|
||||
})
|
||||
messages.append({"role": "user", "content": results})
|
||||
result = TOOL_HANDLERS[block.name](block.input)
|
||||
messages.append({"role": "user", "content": [{"type": "tool_result", ...}]})
|
||||
```
|
||||
|
||||
不到 30 行, 这就是整个智能体。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。
|
||||
Spring AI 的 `ChatClient.call()` **内部封装了完全等价的逻辑**：
|
||||
|
||||
```
|
||||
call() 内部流程:
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ 1. 组装请求: system prompt + user message + tools │
|
||||
│ 2. 发送给 LLM │
|
||||
│ 3. 解析响应 │
|
||||
│ ├── 有 tool_use? ──→ 是: │
|
||||
│ │ a. 提取工具名和参数 │
|
||||
│ │ b. 通过反射调用对应的 @Tool 方法 │
|
||||
│ │ c. 将 tool_result 追加到消息列表 │
|
||||
│ │ d. 回到步骤 2（自动循环） │
|
||||
│ └── 否 ──→ 返回最终文本 │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
关键点：
|
||||
- **工具检测**: Spring AI 检查响应中是否有 `tool_use` 类型的 content block（对应 Python 的 `stop_reason == "tool_use"`）
|
||||
- **反射分派**: 框架通过 Java 反射机制，根据 LLM 返回的工具名称找到对应的 `@Tool` 方法并调用（对应 Python 的 `TOOL_HANDLERS[block.name]`）
|
||||
- **结果回传**: 工具执行结果自动包装为 `tool_result` 消息追加到对话（对应 Python 手动构造 `tool_result` content block）
|
||||
- **循环终止**: 当模型返回纯文本（无工具调用）时，`call()` 返回最终结果
|
||||
|
||||
因此，Python 版约 15 行的 while 循环，在 Java 版中浓缩为一行 `.call()`。
|
||||
|
||||
### 4. `AgentRunner.interactive()`：REPL 交互循环
|
||||
|
||||
`AgentRunner` 是所有课程共用的交互式 REPL（Read-Eval-Print Loop）工具类，对应 Python 版 `if __name__ == "__main__"` 中的 `input()` 循环。
|
||||
|
||||
```java
|
||||
public class AgentRunner {
|
||||
/**
|
||||
* 启动交互式 REPL 循环。
|
||||
* @param prefix 提示符前缀（如 "s01"）
|
||||
* @param handler 处理用户输入并返回 Agent 响应的函数
|
||||
*/
|
||||
public static void interactive(String prefix, Function<String, String> handler) {
|
||||
Scanner scanner = new Scanner(System.in);
|
||||
System.out.println("输入 'q' 或 'exit' 退出");
|
||||
while (true) {
|
||||
System.out.print("\033[36m" + prefix + " >> \033[0m"); // 彩色提示符
|
||||
String input;
|
||||
try {
|
||||
if (!scanner.hasNextLine()) break;
|
||||
input = scanner.nextLine().trim();
|
||||
} catch (Exception e) {
|
||||
break;
|
||||
}
|
||||
if (input.isEmpty() || "exit".equalsIgnoreCase(input) || "q".equalsIgnoreCase(input)) {
|
||||
break;
|
||||
}
|
||||
try {
|
||||
String response = handler.apply(input); // 调用 Agent 处理
|
||||
if (response != null && !response.isBlank()) {
|
||||
System.out.println(response);
|
||||
}
|
||||
} catch (Exception e) {
|
||||
System.err.println("Error: " + e.getMessage());
|
||||
}
|
||||
System.out.println();
|
||||
}
|
||||
System.out.println("Bye!");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
工作流程：`Scanner` 读取输入 → `handler.apply()` 发给 Agent → 打印响应 → 循环。`handler` 是一个函数式接口，每个课程传入自己的 Agent 调用逻辑。
|
||||
|
||||
### 5. 组装为完整的 Agent 类
|
||||
|
||||
```java
|
||||
@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
|
||||
public class S01AgentLoop implements CommandLineRunner {
|
||||
|
||||
private final ChatClient chatClient;
|
||||
|
||||
public S01AgentLoop(ChatModel chatModel) {
|
||||
this.chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem("You are a coding agent at ...")
|
||||
.defaultTools(new BashTool())
|
||||
.build();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void run(String... args) {
|
||||
AgentRunner.interactive("s01", userMessage ->
|
||||
chatClient.prompt()
|
||||
.user(userMessage)
|
||||
.call() // ← 这一个调用 = Python 的整个 while 循环
|
||||
.content()
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **TIPS — Python → Java 关键适配点:**
|
||||
> - Python 的 `while True` + `stop_reason` 手动循环 → Spring AI `ChatClient.call()` 内置自动循环
|
||||
> - Python 的 `TOOLS` 数组 + `TOOL_HANDLERS` 字典 → `@Tool` 注解 + `defaultTools()` 自动注册与反射分派
|
||||
> - Python 的 `client = Anthropic()` → Spring Boot 自动配置注入 `ChatModel`
|
||||
> - Python 的 `input()` 交互 → `AgentRunner.interactive()` 封装 Scanner REPL + 函数式接口
|
||||
|
||||
不到 40 行核心代码, 这就是整个智能体。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。
|
||||
|
||||
## 变更内容
|
||||
|
||||
| 组件 | 之前 | 之后 |
|
||||
|---------------|------------|--------------------------------|
|
||||
| Agent loop | (无) | `while True` + stop_reason |
|
||||
| Tools | (无) | `bash` (单一工具) |
|
||||
| Messages | (无) | 累积式消息列表 |
|
||||
| Control flow | (无) | `stop_reason != "tool_use"` |
|
||||
| 组件 | 之前 | 之后 |
|
||||
|---------------|------------|--------------------------------------------------|
|
||||
| Agent loop | (无) | `ChatClient.call()` 内置工具循环 |
|
||||
| Tools | (无) | `BashTool` (单一 `@Tool` 工具) |
|
||||
| Messages | (无) | Spring AI 内部管理消息列表 |
|
||||
| Control flow | (无) | 框架自动判断: 无工具调用时返回最终文本 |
|
||||
|
||||
```java
|
||||
// 核心代码 —— 构建 + 调用
|
||||
ChatClient chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem("You are a coding agent ...")
|
||||
.defaultTools(new BashTool())
|
||||
.build();
|
||||
|
||||
AgentRunner.interactive("s01", userMessage ->
|
||||
chatClient.prompt().user(userMessage).call().content()
|
||||
);
|
||||
```
|
||||
|
||||
## 试一试
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s01_agent_loop.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s01.S01AgentLoop
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
> 运行前需设置环境变量: `AI_API_KEY`, `AI_BASE_URL`, `AI_MODEL`
|
||||
>
|
||||
> **当前默认使用 OpenAI 协议**（兼容所有 OpenAI API 格式的服务，包括 OpenAI 官方、Azure OpenAI、各类第三方大模型服务的 OpenAI 兼容接口等）。
|
||||
> 如需使用 Anthropic 协议（Claude 系列模型原生接口），请展开下方「切换 AI 协议」。
|
||||
|
||||
1. `Create a file called hello.py that prints "Hello, World!"`
|
||||
2. `List all Python files in this directory`
|
||||
<details>
|
||||
<summary><strong>切换 AI 协议（OpenAI ↔ Anthropic）</strong></summary>
|
||||
|
||||
本项目通过 Spring AI 的 **Starter 依赖 + 配置文件** 来切换底层协议，Java 业务代码（`ChatModel`、`ChatClient`）**无需任何修改**。
|
||||
|
||||
#### 方式一：OpenAI 协议（默认）
|
||||
|
||||
`pom.xml` 依赖：
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-starter-model-openai</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
`application.yml` 配置：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
ai:
|
||||
openai:
|
||||
api-key: ${AI_API_KEY:sk-xxx}
|
||||
base-url: ${AI_BASE_URL:https://api.openai.com}
|
||||
chat:
|
||||
options:
|
||||
model: ${AI_MODEL:gpt-4o}
|
||||
```
|
||||
|
||||
环境变量示例（以 OpenAI 官方为例）：
|
||||
|
||||
```sh
|
||||
export AI_API_KEY=sk-proj-xxxxxxxx
|
||||
export AI_BASE_URL=https://api.openai.com # 可替换为任何 OpenAI 兼容接口
|
||||
export AI_MODEL=gpt-4o
|
||||
```
|
||||
|
||||
> **TIP**: 许多第三方大模型服务（如 DeepSeek、Mistral、通义千问等）提供了 OpenAI 兼容接口，只需修改 `AI_BASE_URL` 和 `AI_MODEL` 即可接入，无需切换协议。
|
||||
|
||||
#### 方式二：Anthropic 协议（Claude 原生接口）
|
||||
|
||||
**第 1 步**：修改 `pom.xml`，将 OpenAI starter 替换为 Anthropic starter：
|
||||
|
||||
```xml
|
||||
<!-- 注释或删除 OpenAI starter -->
|
||||
<!-- <dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-starter-model-openai</artifactId>
|
||||
</dependency> -->
|
||||
|
||||
<!-- 添加 Anthropic starter -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-starter-model-anthropic</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
**第 2 步**：修改 `application.yml`，将 `spring.ai.openai` 替换为 `spring.ai.anthropic`：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
ai:
|
||||
anthropic:
|
||||
api-key: ${AI_API_KEY}
|
||||
base-url: ${AI_BASE_URL:https://api.anthropic.com}
|
||||
chat:
|
||||
options:
|
||||
model: ${AI_MODEL:claude-sonnet-4-20250514}
|
||||
```
|
||||
|
||||
**第 3 步**：设置环境变量：
|
||||
|
||||
```sh
|
||||
export AI_API_KEY=sk-ant-xxxxxxxx
|
||||
export AI_BASE_URL=https://api.anthropic.com
|
||||
export AI_MODEL=claude-sonnet-4-20250514
|
||||
```
|
||||
|
||||
#### 切换原理
|
||||
|
||||
Spring AI 的设计使得 `ChatModel` 是一个统一的抽象接口。不同的 Starter 提供不同的实现：
|
||||
|
||||
| Starter 依赖 | 自动注入的 ChatModel 实现 | 配置前缀 |
|
||||
|---|---|---|
|
||||
| `spring-ai-starter-model-openai` | `OpenAiChatModel` | `spring.ai.openai.*` |
|
||||
| `spring-ai-starter-model-anthropic` | `AnthropicChatModel` | `spring.ai.anthropic.*` |
|
||||
|
||||
业务代码始终面向 `ChatModel` 接口编程，切换协议只需替换依赖和配置，无需改动任何 Java 代码。
|
||||
|
||||
</details>
|
||||
|
||||
试试这些 prompt(英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
1. `Create a file called Hello.java that prints "Hello, World!"`
|
||||
2. `List all Java files in this directory`
|
||||
3. `What is the current git branch?`
|
||||
4. `Create a directory called test_output and write 3 files in it`
|
||||
|
||||
+96
-58
@@ -2,7 +2,7 @@
|
||||
|
||||
`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
||||
|
||||
> *"加一个工具, 只加一个 handler"* -- 循环不用动, 新工具注册进 dispatch map 就行。
|
||||
> *"加一个工具, 只加一个 @Tool 方法"* -- 循环不用动, 新工具传入 `defaultTools()` 就行。
|
||||
>
|
||||
> **Harness 层**: 工具分发 -- 扩展模型能触达的边界。
|
||||
|
||||
@@ -15,87 +15,125 @@
|
||||
## 解决方案
|
||||
|
||||
```
|
||||
+--------+ +-------+ +------------------+
|
||||
| User | ---> | LLM | ---> | Tool Dispatch |
|
||||
| prompt | | | | { |
|
||||
+--------+ +---+---+ | bash: run_bash |
|
||||
^ | read: run_read |
|
||||
| | write: run_wr |
|
||||
+-----------+ edit: run_edit |
|
||||
tool_result | } |
|
||||
+------------------+
|
||||
+--------+ +-------+ +--------------------+
|
||||
| User | ---> | LLM | ---> | defaultTools() |
|
||||
| prompt | | | | { |
|
||||
+--------+ +---+---+ | BashTool |
|
||||
^ | ReadFileTool |
|
||||
| | WriteFileTool |
|
||||
+-----------+ EditFileTool |
|
||||
tool_result | } |
|
||||
+--------------------+
|
||||
|
||||
The dispatch map is a dict: {tool_name: handler_function}.
|
||||
One lookup replaces any if/elif chain.
|
||||
Spring AI 通过 @Tool 注解自动注册和分派。
|
||||
无需手写 dispatch map，框架扫描工具对象的注解方法即可。
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. 每个工具有一个处理函数。路径沙箱防止逃逸工作区。
|
||||
1. 每个工具是一个独立的类，用 `@Tool` 注解声明。`PathValidator` 做路径沙箱防止逃逸工作区。
|
||||
|
||||
```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
|
||||
```java
|
||||
// PathValidator —— 对应 Python 版的 safe_path() 函数
|
||||
public class PathValidator {
|
||||
private final Path workDir;
|
||||
|
||||
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]
|
||||
```
|
||||
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;
|
||||
}
|
||||
}
|
||||
|
||||
2. dispatch map 将工具名映射到处理函数。
|
||||
// ReadFileTool —— 对应 Python 版的 run_read() 函数
|
||||
public class ReadFileTool {
|
||||
private final PathValidator pathValidator;
|
||||
|
||||
```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"]),
|
||||
@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);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. 循环中按名称查找处理函数。循环体本身与 s01 完全一致。
|
||||
2. 工具注册只需传入 `defaultTools()`。Spring AI 扫描 `@Tool` 注解方法，自动完成名称映射和参数绑定。
|
||||
|
||||
```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,
|
||||
})
|
||||
```java
|
||||
// 对应 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();
|
||||
```
|
||||
|
||||
加工具 = 加 handler + 加 schema。循环永远不变。
|
||||
3. 调用代码与 s01 完全一致。循环由框架管理，开发者只需关注工具实现。
|
||||
|
||||
```java
|
||||
// 对比 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 (仅 bash) | 4 (bash, read, write, edit) |
|
||||
| Dispatch | 硬编码 bash 调用 | `TOOL_HANDLERS` 字典 |
|
||||
| 路径安全 | 无 | `safe_path()` 沙箱 |
|
||||
| Agent loop | 不变 | 不变 |
|
||||
| 组件 | 之前 (s01) | 之后 (s02) |
|
||||
|----------------|-----------------------|----------------------------------------|
|
||||
| Tools | 1 (`BashTool`) | 4 (`Bash`, `ReadFile`, `WriteFile`, `EditFile`) |
|
||||
| Dispatch | `defaultTools(bash)` | `defaultTools(bash, read, write, edit)` |
|
||||
| 路径安全 | 无 | `PathValidator` 沙箱 |
|
||||
| Agent loop | 不变 | 不变 |
|
||||
|
||||
```java
|
||||
// s01 → s02 唯一变化: defaultTools() 多传了 3 个工具对象
|
||||
.defaultTools(
|
||||
new BashTool(),
|
||||
new ReadFileTool(), // +新增
|
||||
new WriteFileTool(), // +新增
|
||||
new EditFileTool() // +新增
|
||||
)
|
||||
```
|
||||
|
||||
## 试一试
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s02_tool_use.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s02.S02ToolUse
|
||||
```
|
||||
|
||||
> 运行前需设置环境变量: `AI_API_KEY`, `AI_BASE_URL`, `AI_MODEL`
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
1. `Read the file requirements.txt`
|
||||
2. `Create a file called greet.py with a greet(name) function`
|
||||
3. `Edit greet.py to add a docstring to the function`
|
||||
4. `Read greet.py to verify the edit worked`
|
||||
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`
|
||||
|
||||
+63
-42
@@ -28,71 +28,92 @@
|
||||
| [x] task C |
|
||||
+-----------------------+
|
||||
|
|
||||
if rounds_since_todo >= 3:
|
||||
inject <reminder> into tool_result
|
||||
每次请求时通过 defaultSystem()
|
||||
注入最新 todo 状态到系统提示
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. TodoManager 存储带状态的项目。同一时间只允许一个 `in_progress`。
|
||||
|
||||
```python
|
||||
class TodoManager:
|
||||
def update(self, items: list) -> str:
|
||||
validated, in_progress_count = [], 0
|
||||
for item in items:
|
||||
status = item.get("status", "pending")
|
||||
if status == "in_progress":
|
||||
in_progress_count += 1
|
||||
validated.append({"id": item["id"], "text": item["text"],
|
||||
"status": status})
|
||||
if in_progress_count > 1:
|
||||
raise ValueError("Only one task can be in_progress")
|
||||
self.items = validated
|
||||
return self.render()
|
||||
```
|
||||
```java
|
||||
public class TodoManager {
|
||||
|
||||
2. `todo` 工具和其他工具一样加入 dispatch map。
|
||||
public record TodoItem(String id, String text, String status) {}
|
||||
|
||||
```python
|
||||
TOOL_HANDLERS = {
|
||||
# ...base tools...
|
||||
"todo": lambda **kw: TODO.update(kw["items"]),
|
||||
private List<TodoItem> items = new ArrayList<>();
|
||||
|
||||
@Tool(description = "Update the full task list to track progress. "
|
||||
+ "Each item must have id, text, status (pending/in_progress/completed). "
|
||||
+ "Only one task can be in_progress at a time. Max 20 items.")
|
||||
public String updateTodos(
|
||||
@ToolParam(description = "The complete list of todo items")
|
||||
List<TodoItem> items) {
|
||||
if (items.size() > 20) return "Error: Max 20 todos allowed";
|
||||
List<TodoItem> validated = new ArrayList<>();
|
||||
int inProgressCount = 0;
|
||||
for (TodoItem item : items) {
|
||||
String status = (item.status() != null)
|
||||
? item.status().toLowerCase() : "pending";
|
||||
if ("in_progress".equals(status)) inProgressCount++;
|
||||
validated.add(new TodoItem(item.id(), item.text().trim(), status));
|
||||
}
|
||||
if (inProgressCount > 1)
|
||||
return "Error: Only one task can be in_progress at a time";
|
||||
this.items = validated;
|
||||
return render();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. nag reminder: 模型连续 3 轮以上不调用 `todo` 时注入提醒。
|
||||
2. `TodoManager` 通过 `defaultTools()` 注册, `@Tool` 注解方法自动暴露为工具。
|
||||
|
||||
```python
|
||||
if rounds_since_todo >= 3 and messages:
|
||||
last = messages[-1]
|
||||
if last["role"] == "user" and isinstance(last.get("content"), list):
|
||||
last["content"].insert(0, {
|
||||
"type": "text",
|
||||
"text": "<reminder>Update your todos.</reminder>",
|
||||
})
|
||||
```java
|
||||
ChatClient chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem(system)
|
||||
.defaultTools(
|
||||
new BashTool(),
|
||||
new ReadFileTool(),
|
||||
new WriteFileTool(),
|
||||
new EditFileTool(),
|
||||
todoManager // @Tool 注解方法自动注册
|
||||
)
|
||||
.build();
|
||||
```
|
||||
|
||||
"同时只能有一个 in_progress" 强制顺序聚焦。nag reminder 制造问责压力 -- 你不更新计划, 系统就追着你问。
|
||||
3. 系统提示注入: 每次用户输入时, 将最新 todo 状态注入系统提示, 并强调更新指令。
|
||||
|
||||
```java
|
||||
// 动态系统提示：包含当前 todo 状态
|
||||
String system = "You are a coding agent at " + workDir + ".\n"
|
||||
+ "Use the todo tool to plan multi-step tasks. "
|
||||
+ "Mark in_progress before starting, completed when done.\n"
|
||||
+ "IMPORTANT: You MUST call updateTodos regularly.\n\n"
|
||||
+ "<current-todos>\n" + todoManager.render() + "\n</current-todos>";
|
||||
```
|
||||
|
||||
"同时只能有一个 in_progress" 强制顺序聚焦。系统提示中持续注入 todo 状态制造问责压力 -- 模型每次都能看到自己的计划, 不会忘记更新。
|
||||
|
||||
> **TIP**: Python 版在工具循环内追踪 `rounds_since_todo`, 连续 3 轮未调用 todo 时注入 `<reminder>` 文本。Spring AI 的 ChatClient 自动管理工具循环, 无法在循环内注入, 因此改用系统提示注入的方式实现同等效果。
|
||||
|
||||
## 相对 s02 的变更
|
||||
|
||||
| 组件 | 之前 (s02) | 之后 (s03) |
|
||||
|----------------|------------------|--------------------------------|
|
||||
| Tools | 4 | 5 (+todo) |
|
||||
| 规划 | 无 | 带状态的 TodoManager |
|
||||
| Nag 注入 | 无 | 3 轮后注入 `<reminder>` |
|
||||
| Agent loop | 简单分发 | + rounds_since_todo 计数器 |
|
||||
| 组件 | 之前 (s02) | 之后 (s03) |
|
||||
|----------------|------------------|--------------------------------------|
|
||||
| Tools | 4 | 5 (+TodoManager `@Tool`) |
|
||||
| 规划 | 无 | 带状态的 TodoManager |
|
||||
| 状态注入 | 无 | 系统提示注入 `<current-todos>` |
|
||||
| ChatClient | 固定系统提示 | 每轮重建, 动态注入 todo 状态 |
|
||||
|
||||
## 试一试
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s03_todo_write.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s03.S03TodoWrite
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`
|
||||
2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`
|
||||
3. `Review all Python files and fix any style issues`
|
||||
1. `Refactor the file Hello.java: add JavaDoc, improve naming, and keep main method behavior unchanged`
|
||||
2. `Create a Java package with utils and tests`
|
||||
3. `Review all Java files and fix any style issues`
|
||||
|
||||
+53
-47
@@ -30,67 +30,73 @@ Parent context stays clean. Subagent context is discarded.
|
||||
|
||||
1. 父智能体有一个 `task` 工具。子智能体拥有除 `task` 外的所有基础工具 (禁止递归生成)。
|
||||
|
||||
```python
|
||||
PARENT_TOOLS = CHILD_TOOLS + [
|
||||
{"name": "task",
|
||||
"description": "Spawn a subagent with fresh context.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {"prompt": {"type": "string"}},
|
||||
"required": ["prompt"],
|
||||
}},
|
||||
]
|
||||
```
|
||||
|
||||
2. 子智能体以 `messages=[]` 启动, 运行自己的循环。只有最终文本返回给父智能体。
|
||||
|
||||
```python
|
||||
def run_subagent(prompt: str) -> str:
|
||||
sub_messages = [{"role": "user", "content": prompt}]
|
||||
for _ in range(30): # safety limit
|
||||
response = client.messages.create(
|
||||
model=MODEL, system=SUBAGENT_SYSTEM,
|
||||
messages=sub_messages,
|
||||
tools=CHILD_TOOLS, max_tokens=8000,
|
||||
```java
|
||||
// 父 Agent：拥有基础工具 + SubagentTool
|
||||
this.chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem("You are a coding agent. "
|
||||
+ "Use the task tool to delegate subtasks.")
|
||||
.defaultTools(
|
||||
new BashTool(),
|
||||
new ReadFileTool(),
|
||||
new WriteFileTool(),
|
||||
new EditFileTool(),
|
||||
new SubagentTool(chatModel) // 父 Agent 独有
|
||||
)
|
||||
sub_messages.append({"role": "assistant",
|
||||
"content": response.content})
|
||||
if response.stop_reason != "tool_use":
|
||||
break
|
||||
results = []
|
||||
for block in response.content:
|
||||
if block.type == "tool_use":
|
||||
handler = TOOL_HANDLERS.get(block.name)
|
||||
output = handler(**block.input)
|
||||
results.append({"type": "tool_result",
|
||||
"tool_use_id": block.id,
|
||||
"content": str(output)[:50000]})
|
||||
sub_messages.append({"role": "user", "content": results})
|
||||
return "".join(
|
||||
b.text for b in response.content if hasattr(b, "text")
|
||||
) or "(no summary)"
|
||||
.build();
|
||||
```
|
||||
|
||||
子智能体可能跑了 30+ 次工具调用, 但整个消息历史直接丢弃。父智能体收到的只是一段摘要文本, 作为普通 `tool_result` 返回。
|
||||
2. 子智能体以全新的 `ChatClient` 启动, 拥有独立上下文。只有最终文本返回给父智能体。
|
||||
|
||||
```java
|
||||
@Tool(description = "Spawn a subagent with fresh context. "
|
||||
+ "Use for exploration or subtasks that might pollute the main context.")
|
||||
public String task(
|
||||
@ToolParam(description = "The task prompt") String prompt,
|
||||
@ToolParam(description = "Short description", required = false)
|
||||
String description) {
|
||||
|
||||
// 创建全新的 ChatClient —— 这就是"上下文隔离"的全部
|
||||
ChatClient subClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem("You are a coding subagent. "
|
||||
+ "Complete the task, then summarize findings.")
|
||||
.defaultTools( // 基础工具, 没有 task (防止递归)
|
||||
new BashTool(),
|
||||
new ReadFileTool(),
|
||||
new WriteFileTool(),
|
||||
new EditFileTool()
|
||||
)
|
||||
.build();
|
||||
|
||||
String result = subClient.prompt()
|
||||
.user(prompt)
|
||||
.call()
|
||||
.content();
|
||||
|
||||
// 只返回最终文本, 子 Agent 上下文被丢弃
|
||||
return (result != null) ? result : "(no summary)";
|
||||
}
|
||||
```
|
||||
|
||||
子智能体可能跑了多次工具调用, 但整个消息历史直接丢弃。父智能体收到的只是一段摘要文本, 作为普通 `tool_result` 返回。Spring AI 的 `ChatClient.call()` 内部管理工具循环, 无需手动限制迭代次数。
|
||||
|
||||
## 相对 s03 的变更
|
||||
|
||||
| 组件 | 之前 (s03) | 之后 (s04) |
|
||||
|----------------|------------------|-------------------------------|
|
||||
| Tools | 5 | 5 (基础) + task (仅父端) |
|
||||
| 上下文 | 单一共享 | 父 + 子隔离 |
|
||||
| Subagent | 无 | `run_subagent()` 函数 |
|
||||
| 返回值 | 不适用 | 仅摘要文本 |
|
||||
| 组件 | 之前 (s03) | 之后 (s04) |
|
||||
|----------------|------------------|---------------------------------------|
|
||||
| Tools | 5 | 5 (基础) + SubagentTool (仅父端) |
|
||||
| 上下文 | 单一共享 | 父 + 子隔离 (独立 ChatClient) |
|
||||
| Subagent | 无 | `SubagentTool.task()` 方法 |
|
||||
| 返回值 | 不适用 | 仅摘要文本 |
|
||||
|
||||
## 试一试
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s04_subagent.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s04.S04Subagent
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
1. `Use a subtask to find what testing framework this project uses`
|
||||
2. `Delegate: read all .py files and summarize what each one does`
|
||||
2. `Delegate: read all .java files and summarize what each one does`
|
||||
3. `Use a task to create a new module, then verify it from here`
|
||||
|
||||
@@ -47,40 +47,85 @@ skills/
|
||||
|
||||
2. SkillLoader 递归扫描 `SKILL.md` 文件, 用目录名作为技能标识。
|
||||
|
||||
```python
|
||||
class SkillLoader:
|
||||
def __init__(self, skills_dir: Path):
|
||||
self.skills = {}
|
||||
for f in sorted(skills_dir.rglob("SKILL.md")):
|
||||
text = f.read_text()
|
||||
meta, body = self._parse_frontmatter(text)
|
||||
name = meta.get("name", f.parent.name)
|
||||
self.skills[name] = {"meta": meta, "body": body}
|
||||
```java
|
||||
public class SkillLoader {
|
||||
|
||||
def get_descriptions(self) -> str:
|
||||
lines = []
|
||||
for name, skill in self.skills.items():
|
||||
desc = skill["meta"].get("description", "")
|
||||
lines.append(f" - {name}: {desc}")
|
||||
return "\n".join(lines)
|
||||
private static final Pattern FRONTMATTER_PATTERN =
|
||||
Pattern.compile("^---\\n(.*?)\\n---\\n(.*)", Pattern.DOTALL);
|
||||
|
||||
def get_content(self, name: str) -> str:
|
||||
skill = self.skills.get(name)
|
||||
if not skill:
|
||||
return f"Error: Unknown skill '{name}'."
|
||||
return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
|
||||
private final Map<String, SkillInfo> skills = new LinkedHashMap<>();
|
||||
|
||||
record SkillInfo(Map<String, String> meta, String body, String path) {}
|
||||
|
||||
public SkillLoader(Path skillsDir) {
|
||||
loadAll(skillsDir);
|
||||
}
|
||||
|
||||
/** 递归扫描 skills 目录下所有 SKILL.md 文件 */
|
||||
private void loadAll(Path skillsDir) {
|
||||
if (!Files.exists(skillsDir)) return;
|
||||
try (Stream<Path> paths = Files.walk(skillsDir)) {
|
||||
paths.filter(p -> p.getFileName().toString().equals("SKILL.md"))
|
||||
.sorted()
|
||||
.forEach(p -> {
|
||||
String text = Files.readString(p);
|
||||
var parsed = parseFrontmatter(text);
|
||||
String name = parsed.meta().getOrDefault("name",
|
||||
p.getParent().getFileName().toString());
|
||||
skills.put(name, new SkillInfo(
|
||||
parsed.meta(), parsed.body(), p.toString()));
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/** Layer 1: 获取所有技能的简短描述（用于系统提示注入） */
|
||||
public String getDescriptions() {
|
||||
if (skills.isEmpty()) return "(no skills available)";
|
||||
StringBuilder sb = new StringBuilder();
|
||||
for (var entry : skills.entrySet()) {
|
||||
String desc = entry.getValue().meta()
|
||||
.getOrDefault("description", "No description");
|
||||
sb.append(" - ").append(entry.getKey())
|
||||
.append(": ").append(desc).append("\n");
|
||||
}
|
||||
return sb.toString().stripTrailing();
|
||||
}
|
||||
|
||||
/** Layer 2: 加载指定技能的完整内容（作为 @Tool 方法） */
|
||||
@Tool(description = "Load specialized knowledge by name.")
|
||||
public String loadSkill(
|
||||
@ToolParam(description = "Skill name to load") String name) {
|
||||
SkillInfo skill = skills.get(name);
|
||||
if (skill == null)
|
||||
return "Error: Unknown skill '" + name + "'. Available: "
|
||||
+ String.join(", ", skills.keySet());
|
||||
return "<skill name=\"" + name + "\">\n"
|
||||
+ skill.body() + "\n</skill>";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. 第一层写入系统提示。第二层不过是 dispatch map 中的又一个工具。
|
||||
3. 第一层写入系统提示。第二层通过 SkillLoader 上的 `@Tool` 注解方法按需加载。
|
||||
|
||||
```python
|
||||
SYSTEM = f"""You are a coding agent at {WORKDIR}.
|
||||
Skills available:
|
||||
{SKILL_LOADER.get_descriptions()}"""
|
||||
```java
|
||||
public S05SkillLoading(ChatModel chatModel) {
|
||||
Path skillsDir = Path.of(System.getProperty("user.dir"), "skills");
|
||||
SkillLoader skillLoader = new SkillLoader(skillsDir);
|
||||
|
||||
TOOL_HANDLERS = {
|
||||
# ...base tools...
|
||||
"load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
|
||||
// Layer 1: 技能元数据注入系统提示
|
||||
String system = "You are a coding agent at " + System.getProperty("user.dir") + ".\n"
|
||||
+ "Use loadSkill to access specialized knowledge.\n\n"
|
||||
+ "Skills available:\n"
|
||||
+ skillLoader.getDescriptions();
|
||||
|
||||
this.chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem(system)
|
||||
.defaultTools(
|
||||
new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(),
|
||||
skillLoader // Layer 2: loadSkill @Tool 方法
|
||||
)
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
@@ -99,7 +144,7 @@ TOOL_HANDLERS = {
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s05_skill_loading.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s05.S05SkillLoading
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
+107
-49
@@ -44,61 +44,119 @@ continue [Layer 2: auto_compact]
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. **第一层 -- micro_compact**: 每次 LLM 调用前, 将旧的 tool result 替换为占位符。
|
||||
1. **第一层 -- 上下文窗口管理**: Spring AI 的 ChatClient 自动管理工具循环, 无法在循环内插入压缩。Java 版通过限制注入系统提示的对话轮数（仅保留最近 N 轮）并截断内容来实现等价效果。
|
||||
|
||||
```python
|
||||
def micro_compact(messages: list) -> list:
|
||||
tool_results = []
|
||||
for i, msg in enumerate(messages):
|
||||
if msg["role"] == "user" and isinstance(msg.get("content"), list):
|
||||
for j, part in enumerate(msg["content"]):
|
||||
if isinstance(part, dict) and part.get("type") == "tool_result":
|
||||
tool_results.append((i, j, part))
|
||||
if len(tool_results) <= KEEP_RECENT:
|
||||
return messages
|
||||
for _, _, part in tool_results[:-KEEP_RECENT]:
|
||||
if len(part.get("content", "")) > 100:
|
||||
part["content"] = f"[Previous: used {tool_name}]"
|
||||
return messages
|
||||
```java
|
||||
/** 估算 token 数量: 粗略估计 4 字符 ≈ 1 token */
|
||||
public int estimateTokens() {
|
||||
int chars = history.stream().mapToInt(t -> t.content().length()).sum();
|
||||
return chars / 4;
|
||||
}
|
||||
|
||||
/** 获取对话历史的摘要（用于注入系统提示, 仅保留最近几轮） */
|
||||
public String getContextSummary() {
|
||||
if (history.isEmpty()) return "";
|
||||
StringBuilder sb = new StringBuilder("\n<conversation-context>\n");
|
||||
int start = Math.max(0, history.size() - KEEP_RECENT * 2);
|
||||
for (int i = start; i < history.size(); i++) {
|
||||
ConversationTurn turn = history.get(i);
|
||||
sb.append("[").append(turn.role()).append("]: ")
|
||||
.append(turn.content(), 0, Math.min(500, turn.content().length()))
|
||||
.append("\n");
|
||||
}
|
||||
sb.append("</conversation-context>");
|
||||
return sb.toString();
|
||||
}
|
||||
```
|
||||
|
||||
2. **第二层 -- auto_compact**: token 超过阈值时, 保存完整对话到磁盘, 让 LLM 做摘要。
|
||||
|
||||
```python
|
||||
def auto_compact(messages: list) -> list:
|
||||
# Save transcript for recovery
|
||||
transcript_path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
|
||||
with open(transcript_path, "w") as f:
|
||||
for msg in messages:
|
||||
f.write(json.dumps(msg, default=str) + "\n")
|
||||
# LLM summarizes
|
||||
response = client.messages.create(
|
||||
model=MODEL,
|
||||
messages=[{"role": "user", "content":
|
||||
"Summarize this conversation for continuity..."
|
||||
+ json.dumps(messages, default=str)[:80000]}],
|
||||
max_tokens=2000,
|
||||
)
|
||||
return [
|
||||
{"role": "user", "content": f"[Compressed]\n\n{response.content[0].text}"},
|
||||
{"role": "assistant", "content": "Understood. Continuing."},
|
||||
]
|
||||
```java
|
||||
public String compact() {
|
||||
// 保存 transcript 到磁盘（完整历史不丢失）
|
||||
Files.createDirectories(transcriptDir);
|
||||
Path transcriptPath = transcriptDir.resolve(
|
||||
"transcript_" + System.currentTimeMillis() + ".jsonl");
|
||||
try (BufferedWriter writer = Files.newBufferedWriter(transcriptPath)) {
|
||||
for (ConversationTurn turn : history) {
|
||||
writer.write(objectMapper.writeValueAsString(turn));
|
||||
writer.newLine();
|
||||
}
|
||||
}
|
||||
|
||||
// LLM 生成摘要
|
||||
String conversationText = history.stream()
|
||||
.map(t -> t.role() + ": " + t.content())
|
||||
.reduce("", (a, b) -> a + "\n" + b);
|
||||
if (conversationText.length() > 80000) {
|
||||
conversationText = conversationText.substring(0, 80000);
|
||||
}
|
||||
|
||||
ChatClient summaryClient = ChatClient.builder(chatModel).build();
|
||||
String summary = summaryClient.prompt()
|
||||
.user("Summarize this conversation for continuity. Include: "
|
||||
+ "1) What was accomplished, 2) Current state, "
|
||||
+ "3) Key decisions.\n\n" + conversationText)
|
||||
.call().content();
|
||||
|
||||
// 用摘要替换历史
|
||||
history.clear();
|
||||
history.add(new ConversationTurn("system",
|
||||
"[Conversation compressed. Transcript: " + transcriptPath
|
||||
+ "]\n\n" + summary));
|
||||
return summary;
|
||||
}
|
||||
```
|
||||
|
||||
3. **第三层 -- manual compact**: `compact` 工具按需触发同样的摘要机制。
|
||||
3. **第三层 -- manual compact**: `CompactTool` 工具按需触发同样的摘要机制。
|
||||
|
||||
4. 循环整合三层:
|
||||
```java
|
||||
public class CompactTool {
|
||||
private final ContextCompactor compactor;
|
||||
|
||||
```python
|
||||
def agent_loop(messages: list):
|
||||
while True:
|
||||
micro_compact(messages) # Layer 1
|
||||
if estimate_tokens(messages) > THRESHOLD:
|
||||
messages[:] = auto_compact(messages) # Layer 2
|
||||
response = client.messages.create(...)
|
||||
# ... tool execution ...
|
||||
if manual_compact:
|
||||
messages[:] = auto_compact(messages) # Layer 3
|
||||
public CompactTool(ContextCompactor compactor) {
|
||||
this.compactor = compactor;
|
||||
}
|
||||
|
||||
@Tool(description = "Trigger manual conversation compression to free up context space.")
|
||||
public String compact(
|
||||
@ToolParam(description = "What to preserve in summary",
|
||||
required = false) String focus) {
|
||||
compactor.requestCompact();
|
||||
return "Compression triggered. Context will be summarized.";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. REPL 层整合三层 (Spring AI 的 ChatClient 自动管理工具循环, 压缩在用户消息级别触发):
|
||||
|
||||
```java
|
||||
AgentRunner.interactive("s06", userMessage -> {
|
||||
// Layer 2: 自动压缩检查（每次用户输入前）
|
||||
if (compactor.needsAutoCompact()) {
|
||||
System.out.println("[auto_compact triggered]");
|
||||
compactor.compact();
|
||||
}
|
||||
compactor.addTurn("user", userMessage);
|
||||
|
||||
// 动态系统提示：包含对话上下文摘要
|
||||
String system = baseSystem + compactor.getContextSummary();
|
||||
ChatClient chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem(system)
|
||||
.defaultTools(new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(), compactTool)
|
||||
.build();
|
||||
|
||||
String response = chatClient.prompt()
|
||||
.user(userMessage).call().content();
|
||||
compactor.addTurn("assistant", response != null ? response : "");
|
||||
|
||||
// Layer 3: 手动压缩（如果 Agent 调用了 compact 工具）
|
||||
if (compactor.isCompactRequested()) {
|
||||
compactor.compact();
|
||||
}
|
||||
return response;
|
||||
});
|
||||
```
|
||||
|
||||
完整历史通过 transcript 保存在磁盘上。信息没有真正丢失, 只是移出了活跃上下文。
|
||||
@@ -109,7 +167,7 @@ def agent_loop(messages: list):
|
||||
|----------------|------------------|--------------------------------|
|
||||
| Tools | 5 | 5 (基础 + compact) |
|
||||
| 上下文管理 | 无 | 三层压缩 |
|
||||
| Micro-compact | 无 | 旧结果 -> 占位符 |
|
||||
| 上下文窗口管理 | 无 | 限制注入轮数 + 内容截断 |
|
||||
| Auto-compact | 无 | token 阈值触发 |
|
||||
| Transcripts | 无 | 保存到 .transcripts/ |
|
||||
|
||||
@@ -117,11 +175,11 @@ def agent_loop(messages: list):
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s06_context_compact.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s06.S06ContextCompact
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
1. `Read every Python file in the agents/ directory one by one` (观察 micro-compact 替换旧结果)
|
||||
1. `Read every Java file in the src/ directory one by one` (观察上下文窗口管理效果)
|
||||
2. `Keep reading files until compression triggers automatically`
|
||||
3. `Use the compact tool to manually compress the conversation`
|
||||
|
||||
+81
-40
@@ -48,57 +48,98 @@ s03 的 TodoManager 只是内存中的扁平清单: 没有顺序、没有依赖
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. **TaskManager**: 每个任务一个 JSON 文件, CRUD + 依赖图。
|
||||
1. **TaskManager**: 每个任务一个 JSON 文件, CRUD + 依赖图。使用 Jackson `ObjectMapper` 做 JSON 序列化。
|
||||
|
||||
```python
|
||||
class TaskManager:
|
||||
def __init__(self, tasks_dir: Path):
|
||||
self.dir = tasks_dir
|
||||
self.dir.mkdir(exist_ok=True)
|
||||
self._next_id = self._max_id() + 1
|
||||
```java
|
||||
public class TaskManager {
|
||||
private static final ObjectMapper MAPPER = new ObjectMapper();
|
||||
private final Path dir;
|
||||
private int nextId;
|
||||
|
||||
def create(self, subject, description=""):
|
||||
task = {"id": self._next_id, "subject": subject,
|
||||
"status": "pending", "blockedBy": [],
|
||||
"blocks": [], "owner": ""}
|
||||
self._save(task)
|
||||
self._next_id += 1
|
||||
return json.dumps(task, indent=2)
|
||||
public TaskManager(Path tasksDir) {
|
||||
this.dir = tasksDir;
|
||||
Files.createDirectories(dir);
|
||||
this.nextId = maxId() + 1;
|
||||
}
|
||||
|
||||
@Tool(description = "Create a new task with subject and optional description")
|
||||
public String taskCreate(
|
||||
@ToolParam(description = "Short subject of the task") String subject,
|
||||
@ToolParam(description = "Detailed description", required = false) String description) {
|
||||
Map<String, Object> task = new LinkedHashMap<>();
|
||||
task.put("id", nextId);
|
||||
task.put("subject", subject);
|
||||
task.put("status", "pending");
|
||||
task.put("blockedBy", new ArrayList<>());
|
||||
task.put("blocks", new ArrayList<>());
|
||||
save(task);
|
||||
nextId++;
|
||||
return MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(task);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **依赖解除**: 完成任务时, 自动将其 ID 从其他任务的 `blockedBy` 中移除, 解锁后续任务。
|
||||
|
||||
```python
|
||||
def _clear_dependency(self, completed_id):
|
||||
for f in self.dir.glob("task_*.json"):
|
||||
task = json.loads(f.read_text())
|
||||
if completed_id in task.get("blockedBy", []):
|
||||
task["blockedBy"].remove(completed_id)
|
||||
self._save(task)
|
||||
```java
|
||||
private void clearDependency(int completedId) {
|
||||
try (Stream<Path> files = Files.list(dir)) {
|
||||
files.filter(f -> f.getFileName().toString().matches("task_\\d+\\.json"))
|
||||
.forEach(f -> {
|
||||
Map<String, Object> task = MAPPER.readValue(
|
||||
Files.readString(f), new TypeReference<>() {});
|
||||
List<Integer> blockedBy = (List<Integer>) task.get("blockedBy");
|
||||
if (blockedBy != null && blockedBy.remove(Integer.valueOf(completedId))) {
|
||||
save(task);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **状态变更 + 依赖关联**: `update` 处理状态转换和依赖边。
|
||||
3. **状态变更 + 依赖关联**: `taskUpdate` 处理状态转换和依赖边。当 status 变为 `completed` 时自动调用 `clearDependency`；`blockedBy`/`blocks` 是双向关系。
|
||||
|
||||
```python
|
||||
def update(self, task_id, status=None,
|
||||
add_blocked_by=None, add_blocks=None):
|
||||
task = self._load(task_id)
|
||||
if status:
|
||||
task["status"] = status
|
||||
if status == "completed":
|
||||
self._clear_dependency(task_id)
|
||||
self._save(task)
|
||||
```java
|
||||
@Tool(description = "Update a task's status or dependencies.")
|
||||
public String taskUpdate(
|
||||
@ToolParam(description = "Task ID") int taskId,
|
||||
@ToolParam(description = "New status", required = false) String status,
|
||||
@ToolParam(description = "Task IDs that block this task", required = false) List<Integer> addBlockedBy,
|
||||
@ToolParam(description = "Task IDs that this task blocks", required = false) List<Integer> addBlocks) {
|
||||
Map<String, Object> task = load(taskId);
|
||||
if (status != null) {
|
||||
task.put("status", status);
|
||||
if ("completed".equals(status)) {
|
||||
clearDependency(taskId);
|
||||
}
|
||||
}
|
||||
// 处理 addBlockedBy / addBlocks 双向依赖 ...
|
||||
save(task);
|
||||
return MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(task);
|
||||
}
|
||||
```
|
||||
|
||||
4. 四个任务工具加入 dispatch map。
|
||||
4. **Spring AI 自动注册工具**: 将 `TaskManager` 作为 `defaultTools` 传入 `ChatClient`，Spring AI 自动识别 `@Tool` 注解方法，无需手动 dispatch map。
|
||||
|
||||
```python
|
||||
TOOL_HANDLERS = {
|
||||
# ...base tools...
|
||||
"task_create": lambda **kw: TASKS.create(kw["subject"]),
|
||||
"task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status")),
|
||||
"task_list": lambda **kw: TASKS.list_all(),
|
||||
"task_get": lambda **kw: TASKS.get(kw["task_id"]),
|
||||
```java
|
||||
@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
|
||||
public class S07TaskSystem implements CommandLineRunner {
|
||||
|
||||
private final ChatClient chatClient;
|
||||
|
||||
public S07TaskSystem(ChatModel chatModel) {
|
||||
Path tasksDir = Path.of(System.getProperty("user.dir"), ".tasks");
|
||||
TaskManager taskManager = new TaskManager(tasksDir);
|
||||
|
||||
this.chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem("You are a coding agent. Use task tools to plan and track work.")
|
||||
.defaultTools(
|
||||
new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(),
|
||||
taskManager // TaskManager 中的 @Tool 方法自动注册
|
||||
)
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -118,7 +159,7 @@ TOOL_HANDLERS = {
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s07_task_system.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s07.S07TaskSystem
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
@@ -32,58 +32,85 @@ Agent --[spawn A]--[spawn B]--[other work]----
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. BackgroundManager 用线程安全的通知队列追踪任务。
|
||||
1. BackgroundManager 用线程安全的并发容器追踪任务。Java 使用 `ConcurrentHashMap` 和 `CopyOnWriteArrayList` 代替 Python 的手动加锁。
|
||||
|
||||
```python
|
||||
class BackgroundManager:
|
||||
def __init__(self):
|
||||
self.tasks = {}
|
||||
self._notification_queue = []
|
||||
self._lock = threading.Lock()
|
||||
```java
|
||||
public class BackgroundManager {
|
||||
private static final int TIMEOUT_SECONDS = 300;
|
||||
|
||||
private final Map<String, TaskInfo> tasks = new ConcurrentHashMap<>();
|
||||
private final List<Notification> notificationQueue = new CopyOnWriteArrayList<>();
|
||||
private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
|
||||
|
||||
record TaskInfo(String status, String result, String command) {}
|
||||
public record Notification(String taskId, String status, String command, String result) {}
|
||||
}
|
||||
```
|
||||
|
||||
2. `run()` 启动守护线程, 立即返回。
|
||||
2. `backgroundRun()` 提交虚拟线程 (Java 21), 立即返回。相比 Python 的 `daemon=True` 线程，虚拟线程更轻量、由 JVM 调度。
|
||||
|
||||
```python
|
||||
def run(self, command: str) -> str:
|
||||
task_id = str(uuid.uuid4())[:8]
|
||||
self.tasks[task_id] = {"status": "running", "command": command}
|
||||
thread = threading.Thread(
|
||||
target=self._execute, args=(task_id, command), daemon=True)
|
||||
thread.start()
|
||||
return f"Background task {task_id} started"
|
||||
```java
|
||||
@Tool(description = "Run a command in a background thread. Returns task_id immediately without waiting.")
|
||||
public String backgroundRun(
|
||||
@ToolParam(description = "The shell command to run in background") String command) {
|
||||
String taskId = UUID.randomUUID().toString().substring(0, 8);
|
||||
tasks.put(taskId, new TaskInfo("running", null, command));
|
||||
|
||||
executor.submit(() -> execute(taskId, command));
|
||||
|
||||
return "Background task " + taskId + " started: "
|
||||
+ command.substring(0, Math.min(80, command.length()));
|
||||
}
|
||||
```
|
||||
|
||||
3. 子进程完成后, 结果进入通知队列。
|
||||
3. 子进程完成后, 结果进入通知队列。使用 `ProcessBuilder` 执行命令，支持超时控制。
|
||||
|
||||
```python
|
||||
def _execute(self, task_id, command):
|
||||
try:
|
||||
r = subprocess.run(command, shell=True, cwd=WORKDIR,
|
||||
capture_output=True, text=True, timeout=300)
|
||||
output = (r.stdout + r.stderr).strip()[:50000]
|
||||
except subprocess.TimeoutExpired:
|
||||
output = "Error: Timeout (300s)"
|
||||
with self._lock:
|
||||
self._notification_queue.append({
|
||||
"task_id": task_id, "result": output[:500]})
|
||||
```java
|
||||
private void execute(String taskId, String command) {
|
||||
String status, output;
|
||||
try {
|
||||
ProcessBuilder pb = new ProcessBuilder("sh", "-c", command);
|
||||
pb.redirectErrorStream(true);
|
||||
Process process = pb.start();
|
||||
try (BufferedReader reader = new BufferedReader(
|
||||
new InputStreamReader(process.getInputStream()))) {
|
||||
output = reader.lines().collect(Collectors.joining("\n"));
|
||||
}
|
||||
boolean finished = process.waitFor(TIMEOUT_SECONDS, TimeUnit.SECONDS);
|
||||
if (!finished) { process.destroyForcibly(); status = "timeout"; }
|
||||
else { status = "completed"; }
|
||||
} catch (Exception e) { output = "Error: " + e.getMessage(); status = "error"; }
|
||||
|
||||
tasks.put(taskId, new TaskInfo(status, output, command));
|
||||
notificationQueue.add(new Notification(taskId, status, command, output));
|
||||
}
|
||||
```
|
||||
|
||||
4. 每次 LLM 调用前排空通知队列。
|
||||
4. 每次用户输入时排空通知队列, 注入系统提示。Spring AI 的 `ChatClient` 管理内部工具循环, 因此改为在每次用户输入时 drain 通知并构建系统提示, 核心概念不变: fire and forget。
|
||||
|
||||
```python
|
||||
def agent_loop(messages: list):
|
||||
while True:
|
||||
notifs = BG.drain_notifications()
|
||||
if notifs:
|
||||
notif_text = "\n".join(
|
||||
f"[bg:{n['task_id']}] {n['result']}" for n in notifs)
|
||||
messages.append({"role": "user",
|
||||
"content": f"<background-results>\n{notif_text}\n"
|
||||
f"</background-results>"})
|
||||
messages.append({"role": "assistant",
|
||||
"content": "Noted background results."})
|
||||
response = client.messages.create(...)
|
||||
```java
|
||||
AgentRunner.interactive("s08", userMessage -> {
|
||||
// Drain 后台任务通知（对应 Python 中循环前的 drain_notifications）
|
||||
var notifs = bgManager.drainNotifications();
|
||||
String bgContext = "";
|
||||
if (!notifs.isEmpty()) {
|
||||
String notifText = notifs.stream()
|
||||
.map(n -> "[bg:" + n.taskId() + "] " + n.status() + ": " + n.result())
|
||||
.collect(Collectors.joining("\n"));
|
||||
bgContext = "\n\n<background-results>\n" + notifText + "\n</background-results>";
|
||||
}
|
||||
|
||||
String system = "You are a coding agent. Use backgroundRun for long-running commands."
|
||||
+ bgContext;
|
||||
|
||||
ChatClient chatClient = ChatClient.builder(chatModel)
|
||||
.defaultSystem(system)
|
||||
.defaultTools(new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(), bgManager)
|
||||
.build();
|
||||
|
||||
return chatClient.prompt().user(userMessage).call().content();
|
||||
});
|
||||
```
|
||||
|
||||
循环保持单线程。只有子进程 I/O 被并行化。
|
||||
@@ -92,16 +119,16 @@ def agent_loop(messages: list):
|
||||
|
||||
| 组件 | 之前 (s07) | 之后 (s08) |
|
||||
|----------------|------------------|------------------------------------|
|
||||
| Tools | 8 | 6 (基础 + background_run + check) |
|
||||
| 执行方式 | 仅阻塞 | 阻塞 + 后台线程 |
|
||||
| 通知机制 | 无 | 每轮排空的队列 |
|
||||
| 并发 | 无 | 守护线程 |
|
||||
| Tools | 8 | 6 (基础 + backgroundRun + check) |
|
||||
| 执行方式 | 仅阻塞 | 阻塞 + 虚拟线程 (Java 21) |
|
||||
| 通知机制 | 无 | 每轮排空的 ConcurrentLinkedQueue |
|
||||
| 并发 | 无 | 虚拟线程 (更轻量, JVM 调度) |
|
||||
|
||||
## 试一试
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s08_background_tasks.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s08.S08BackgroundTasks
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
+96
-50
@@ -39,67 +39,113 @@ Communication:
|
||||
|
||||
1. TeammateManager 通过 config.json 维护团队名册。
|
||||
|
||||
```python
|
||||
class TeammateManager:
|
||||
def __init__(self, team_dir: Path):
|
||||
self.dir = team_dir
|
||||
self.dir.mkdir(exist_ok=True)
|
||||
self.config_path = self.dir / "config.json"
|
||||
self.config = self._load_config()
|
||||
self.threads = {}
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s09/TeammateManager.java
|
||||
public class TeammateManager {
|
||||
private final ChatModel chatModel;
|
||||
private final MessageBus bus;
|
||||
private final Path configPath;
|
||||
private final ObjectMapper mapper = new ObjectMapper();
|
||||
private Map<String, Object> config;
|
||||
// Python用threading.Thread + dict; Java用ConcurrentHashMap天然线程安全
|
||||
private final Map<String, Thread> threads = new ConcurrentHashMap<>();
|
||||
|
||||
public TeammateManager(ChatModel chatModel, MessageBus bus, Path teamDir) {
|
||||
this.chatModel = chatModel;
|
||||
this.bus = bus;
|
||||
this.configPath = teamDir.resolve("config.json");
|
||||
Files.createDirectories(teamDir);
|
||||
this.config = loadConfig();
|
||||
}
|
||||
```
|
||||
|
||||
2. `spawn()` 创建队友并在线程中启动 agent loop。
|
||||
|
||||
```python
|
||||
def spawn(self, name: str, role: str, prompt: str) -> str:
|
||||
member = {"name": name, "role": role, "status": "working"}
|
||||
self.config["members"].append(member)
|
||||
self._save_config()
|
||||
thread = threading.Thread(
|
||||
target=self._teammate_loop,
|
||||
args=(name, role, prompt), daemon=True)
|
||||
thread.start()
|
||||
return f"Spawned teammate '{name}' (role: {role})"
|
||||
```java
|
||||
// Python用threading.Thread; Java用Thread.startVirtualThread()虚拟线程
|
||||
public synchronized String spawn(String name, String role, String prompt) {
|
||||
Map<String, Object> member = new LinkedHashMap<>();
|
||||
member.put("name", name);
|
||||
member.put("role", role);
|
||||
member.put("status", "working");
|
||||
((List<Map<String, Object>>) config.get("members")).add(member);
|
||||
saveConfig();
|
||||
|
||||
// 虚拟线程：轻量级，由JVM调度，不占用OS线程
|
||||
Thread thread = Thread.startVirtualThread(
|
||||
() -> teammateLoop(name, role, prompt));
|
||||
threads.put(name, thread);
|
||||
return "Spawned '" + name + "' (role: " + role + ")";
|
||||
}
|
||||
```
|
||||
|
||||
3. MessageBus: append-only 的 JSONL 收件箱。`send()` 追加一行; `read_inbox()` 读取全部并清空。
|
||||
|
||||
```python
|
||||
class MessageBus:
|
||||
def send(self, sender, to, content, msg_type="message", extra=None):
|
||||
msg = {"type": msg_type, "from": sender,
|
||||
"content": content, "timestamp": time.time()}
|
||||
if extra:
|
||||
msg.update(extra)
|
||||
with open(self.dir / f"{to}.jsonl", "a") as f:
|
||||
f.write(json.dumps(msg) + "\n")
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/core/team/MessageBus.java
|
||||
// Python靠GIL隐式保证线程安全; Java用synchronized显式保证
|
||||
public class MessageBus {
|
||||
private final Path inboxDir;
|
||||
private final ObjectMapper mapper = new ObjectMapper();
|
||||
|
||||
def read_inbox(self, name):
|
||||
path = self.dir / f"{name}.jsonl"
|
||||
if not path.exists(): return "[]"
|
||||
msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
|
||||
path.write_text("") # drain
|
||||
return json.dumps(msgs, indent=2)
|
||||
public synchronized String send(String sender, String to, String content,
|
||||
String msgType, Map<String, Object> extra) {
|
||||
Map<String, Object> msg = new LinkedHashMap<>();
|
||||
msg.put("type", msgType);
|
||||
msg.put("from", sender);
|
||||
msg.put("content", content);
|
||||
msg.put("timestamp", System.currentTimeMillis() / 1000.0);
|
||||
if (extra != null) msg.putAll(extra);
|
||||
|
||||
Path inbox = inboxDir.resolve(to + ".jsonl");
|
||||
Files.writeString(inbox, mapper.writeValueAsString(msg) + "\n",
|
||||
StandardOpenOption.CREATE, StandardOpenOption.APPEND);
|
||||
return "Sent " + msgType + " to " + to;
|
||||
}
|
||||
|
||||
public synchronized List<Map<String, Object>> readInbox(String name) {
|
||||
Path inbox = inboxDir.resolve(name + ".jsonl");
|
||||
if (!Files.exists(inbox)) return List.of();
|
||||
List<Map<String, Object>> messages = new ArrayList<>();
|
||||
for (String line : Files.readAllLines(inbox)) {
|
||||
if (!line.isBlank())
|
||||
messages.add(mapper.readValue(line, new TypeReference<>() {}));
|
||||
}
|
||||
Files.writeString(inbox, ""); // drain
|
||||
return messages;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. 每个队友在每次 LLM 调用前检查收件箱, 将消息注入上下文。
|
||||
4. 每个队友在每次 `call()` 调用间检查收件箱, 将消息注入上下文。ChatClient 的 `call()` 等价于 Python 的完整工具循环（循环到 `stop_reason != "tool_use"` 为止）。
|
||||
|
||||
```python
|
||||
def _teammate_loop(self, name, role, prompt):
|
||||
messages = [{"role": "user", "content": prompt}]
|
||||
for _ in range(50):
|
||||
inbox = BUS.read_inbox(name)
|
||||
if inbox != "[]":
|
||||
messages.append({"role": "user",
|
||||
"content": f"<inbox>{inbox}</inbox>"})
|
||||
messages.append({"role": "assistant",
|
||||
"content": "Noted inbox messages."})
|
||||
response = client.messages.create(...)
|
||||
if response.stop_reason != "tool_use":
|
||||
break
|
||||
# execute tools, append results...
|
||||
self._find_member(name)["status"] = "idle"
|
||||
```java
|
||||
// Python队友在每次LLM调用前检查收件箱; Java在每次call()调用间检查
|
||||
protected void teammateLoop(String name, String role, String initialPrompt) {
|
||||
String sysPrompt = String.format(
|
||||
"You are '%s', role: %s. Use send_message to communicate.",
|
||||
name, role);
|
||||
|
||||
var messageTool = new TeammateMessageTool(bus, name);
|
||||
ChatClient client = ChatClient.builder(chatModel)
|
||||
.defaultSystem(sysPrompt)
|
||||
.defaultTools(new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(), messageTool)
|
||||
.build();
|
||||
|
||||
// 初始工作（call() = 完整工具链，等价于Python循环到stop_reason != "tool_use"）
|
||||
String response = client.prompt(initialPrompt).call().content();
|
||||
|
||||
// 每次call()之间检查收件箱（而非Python的每次LLM调用之间）
|
||||
for (int round = 0; round < 50; round++) {
|
||||
Thread.sleep(2000);
|
||||
var inbox = bus.readInbox(name);
|
||||
if (inbox.isEmpty()) break;
|
||||
String inboxJson = mapper.writeValueAsString(inbox);
|
||||
response = client.prompt("<inbox>" + inboxJson + "</inbox>").call().content();
|
||||
}
|
||||
setStatus(name, "idle");
|
||||
}
|
||||
```
|
||||
|
||||
## 相对 s08 的变更
|
||||
@@ -117,7 +163,7 @@ def _teammate_loop(self, name, role, prompt):
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s09_agent_teams.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s09.S09AgentTeams
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
@@ -44,40 +44,66 @@ Trackers:
|
||||
|
||||
1. 领导生成 request_id, 通过收件箱发起关机请求。
|
||||
|
||||
```python
|
||||
shutdown_requests = {}
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s10/ProtocolTracker.java
|
||||
// Python用字典 + threading.Lock; Java用ConcurrentHashMap天然线程安全
|
||||
private final ConcurrentHashMap<String, Map<String, String>> shutdownRequests
|
||||
= new ConcurrentHashMap<>();
|
||||
|
||||
def handle_shutdown_request(teammate: str) -> str:
|
||||
req_id = str(uuid.uuid4())[:8]
|
||||
shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
|
||||
BUS.send("lead", teammate, "Please shut down gracefully.",
|
||||
"shutdown_request", {"request_id": req_id})
|
||||
return f"Shutdown request {req_id} sent (status: pending)"
|
||||
public String handleShutdownRequest(String teammate) {
|
||||
String reqId = UUID.randomUUID().toString().substring(0, 8);
|
||||
shutdownRequests.put(reqId, new ConcurrentHashMap<>(Map.of(
|
||||
"target", teammate, "status", "pending")));
|
||||
bus.send("lead", teammate, "Please shut down gracefully.",
|
||||
"shutdown_request", Map.of("request_id", reqId));
|
||||
return "Shutdown request " + reqId + " sent to '" + teammate
|
||||
+ "' (status: pending)";
|
||||
}
|
||||
```
|
||||
|
||||
2. 队友收到请求后, 用 approve/reject 响应。
|
||||
|
||||
```python
|
||||
if tool_name == "shutdown_response":
|
||||
req_id = args["request_id"]
|
||||
approve = args["approve"]
|
||||
shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
|
||||
BUS.send(sender, "lead", args.get("reason", ""),
|
||||
"shutdown_response",
|
||||
{"request_id": req_id, "approve": approve})
|
||||
```java
|
||||
// TeammateProtocolTool - 队友用@Tool注解响应关闭请求
|
||||
@Tool(description = "Respond to a shutdown request")
|
||||
public String shutdownResponse(
|
||||
@ToolParam(description = "The request_id") String requestId,
|
||||
@ToolParam(description = "true to approve") boolean approve,
|
||||
@ToolParam(description = "Reason for decision") String reason) {
|
||||
return tracker.respondToShutdown(name, requestId, approve, reason);
|
||||
}
|
||||
|
||||
// ProtocolTracker - 更新追踪器 + 发送响应消息
|
||||
public String respondToShutdown(String sender, String requestId,
|
||||
boolean approve, String reason) {
|
||||
var req = shutdownRequests.get(requestId);
|
||||
if (req != null) {
|
||||
req.put("status", approve ? "approved" : "rejected");
|
||||
}
|
||||
bus.send(sender, "lead", reason != null ? reason : "",
|
||||
"shutdown_response",
|
||||
Map.of("request_id", requestId, "approve", approve));
|
||||
return "Shutdown " + (approve ? "approved" : "rejected");
|
||||
}
|
||||
```
|
||||
|
||||
3. 计划审批遵循完全相同的模式。队友提交计划 (生成 request_id), 领导审查 (引用同一个 request_id)。
|
||||
|
||||
```python
|
||||
plan_requests = {}
|
||||
```java
|
||||
// ProtocolTracker - 同样的request_id关联模式，两种用途
|
||||
private final ConcurrentHashMap<String, Map<String, String>> planRequests
|
||||
= new ConcurrentHashMap<>();
|
||||
|
||||
def handle_plan_review(request_id, approve, feedback=""):
|
||||
req = plan_requests[request_id]
|
||||
req["status"] = "approved" if approve else "rejected"
|
||||
BUS.send("lead", req["from"], feedback,
|
||||
"plan_approval_response",
|
||||
{"request_id": request_id, "approve": approve})
|
||||
public String reviewPlan(String requestId, boolean approve, String feedback) {
|
||||
var req = planRequests.get(requestId);
|
||||
if (req == null) return "Error: Unknown plan request_id '" + requestId + "'";
|
||||
req.put("status", approve ? "approved" : "rejected");
|
||||
bus.send("lead", req.get("from"), feedback != null ? feedback : "",
|
||||
"plan_approval_response",
|
||||
Map.of("request_id", requestId, "approve", approve,
|
||||
"feedback", feedback != null ? feedback : ""));
|
||||
return "Plan " + req.get("status") + " for '" + req.get("from") + "'";
|
||||
}
|
||||
```
|
||||
|
||||
一个 FSM, 两种用途。同样的 `pending -> approved | rejected` 状态机可以套用到任何请求-响应协议上。
|
||||
@@ -96,7 +122,7 @@ def handle_plan_review(request_id, approve, feedback=""):
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s10_team_protocols.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s10.S10TeamProtocols
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
@@ -40,81 +40,130 @@ Teammate lifecycle with idle cycle:
|
||||
|
|
||||
+---> 60s timeout ----------------------> SHUTDOWN
|
||||
|
||||
Identity re-injection after compression:
|
||||
if len(messages) <= 3:
|
||||
messages.insert(0, identity_block)
|
||||
Identity via system prompt (always present):
|
||||
ChatClient.builder(chatModel)
|
||||
.defaultSystem(identityPrompt) // 每次调用自动携带
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. 队友循环分两个阶段: WORK 和 IDLE。LLM 停止调用工具 (或调用了 `idle`) 时, 进入 IDLE。
|
||||
|
||||
```python
|
||||
def _loop(self, name, role, prompt):
|
||||
while True:
|
||||
# -- WORK PHASE --
|
||||
messages = [{"role": "user", "content": prompt}]
|
||||
for _ in range(50):
|
||||
response = client.messages.create(...)
|
||||
if response.stop_reason != "tool_use":
|
||||
break
|
||||
# execute tools...
|
||||
if idle_requested:
|
||||
break
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s11/S11AutonomousAgents.java
|
||||
// AutonomousTeammateManager.autonomousLoop()
|
||||
|
||||
# -- IDLE PHASE --
|
||||
self._set_status(name, "idle")
|
||||
resume = self._idle_poll(name, messages)
|
||||
if not resume:
|
||||
self._set_status(name, "shutdown")
|
||||
return
|
||||
self._set_status(name, "working")
|
||||
private void autonomousLoop(String name, String role, String initialPrompt) {
|
||||
// idle标志：工具调用时设置，外部循环检测
|
||||
AtomicBoolean idleRequested = new AtomicBoolean(false);
|
||||
var idleTool = new IdleTool(idleRequested);
|
||||
|
||||
ChatClient client = ChatClient.builder(chatModel)
|
||||
.defaultSystem(sysPrompt)
|
||||
.defaultTools(new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(),
|
||||
messageTool, protocolTool, idleTool, claimTool)
|
||||
.build();
|
||||
|
||||
while (true) {
|
||||
// -- WORK PHASE --
|
||||
String nextMsg = initialPrompt;
|
||||
for (int round = 0; round < 50 && nextMsg != null; round++) {
|
||||
var inbox = bus.readInbox(name);
|
||||
// ... 合并收件箱消息到 nextMsg ...
|
||||
idleRequested.set(false);
|
||||
String response = client.prompt(sb.toString()).call().content();
|
||||
if (idleRequested.get()) break; // idle工具被调用
|
||||
nextMsg = null; // 后续轮次靠inbox驱动
|
||||
}
|
||||
|
||||
// -- IDLE PHASE --
|
||||
setStatus(name, "idle");
|
||||
// ... 轮询收件箱 + 任务板（见下文） ...
|
||||
if (!resume) { setStatus(name, "shutdown"); return; }
|
||||
setStatus(name, "working");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 空闲阶段循环轮询收件箱和任务看板。
|
||||
|
||||
```python
|
||||
def _idle_poll(self, name, messages):
|
||||
for _ in range(IDLE_TIMEOUT // POLL_INTERVAL): # 60s / 5s = 12
|
||||
time.sleep(POLL_INTERVAL)
|
||||
inbox = BUS.read_inbox(name)
|
||||
if inbox:
|
||||
messages.append({"role": "user",
|
||||
"content": f"<inbox>{inbox}</inbox>"})
|
||||
return True
|
||||
unclaimed = scan_unclaimed_tasks()
|
||||
if unclaimed:
|
||||
claim_task(unclaimed[0]["id"], name)
|
||||
messages.append({"role": "user",
|
||||
"content": f"<auto-claimed>Task #{unclaimed[0]['id']}: "
|
||||
f"{unclaimed[0]['subject']}</auto-claimed>"})
|
||||
return True
|
||||
return False # timeout -> shutdown
|
||||
```java
|
||||
// IDLE PHASE: 轮询收件箱 + 任务板
|
||||
setStatus(name, "idle");
|
||||
boolean resume = false;
|
||||
int polls = IDLE_TIMEOUT / Math.max(POLL_INTERVAL, 1); // 60/5 = 12
|
||||
|
||||
for (int p = 0; p < polls; p++) {
|
||||
Thread.sleep(POLL_INTERVAL * 1000L);
|
||||
|
||||
// 检查收件箱
|
||||
var inbox = bus.readInbox(name);
|
||||
if (!inbox.isEmpty()) {
|
||||
initialPrompt = "<inbox>" + mapper.writeValueAsString(inbox) + "</inbox>";
|
||||
resume = true;
|
||||
break;
|
||||
}
|
||||
|
||||
// 扫描任务板
|
||||
var unclaimed = scanUnclaimedTasks(tasksDir);
|
||||
if (!unclaimed.isEmpty()) {
|
||||
var task = unclaimed.get(0);
|
||||
int taskId = ((Number) task.get("id")).intValue();
|
||||
claimTask(tasksDir, taskId, name);
|
||||
initialPrompt = String.format(
|
||||
"<auto-claimed>Task #%d: %s\n%s</auto-claimed>",
|
||||
taskId, task.get("subject"),
|
||||
task.getOrDefault("description", ""));
|
||||
resume = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (!resume) { setStatus(name, "shutdown"); return; }
|
||||
setStatus(name, "working");
|
||||
```
|
||||
|
||||
3. 任务看板扫描: 找 pending 状态、无 owner、未被阻塞的任务。
|
||||
|
||||
```python
|
||||
def scan_unclaimed_tasks() -> list:
|
||||
unclaimed = []
|
||||
for f in sorted(TASKS_DIR.glob("task_*.json")):
|
||||
task = json.loads(f.read_text())
|
||||
if (task.get("status") == "pending"
|
||||
and not task.get("owner")
|
||||
and not task.get("blockedBy")):
|
||||
unclaimed.append(task)
|
||||
return unclaimed
|
||||
```java
|
||||
static List<Map<String, Object>> scanUnclaimedTasks(Path tasksDir) {
|
||||
if (!Files.exists(tasksDir)) return List.of();
|
||||
List<Map<String, Object>> unclaimed = new ArrayList<>();
|
||||
ObjectMapper mapper = new ObjectMapper();
|
||||
try (var files = Files.list(tasksDir)) {
|
||||
files.filter(f -> f.getFileName().toString().startsWith("task_")
|
||||
&& f.getFileName().toString().endsWith(".json"))
|
||||
.sorted()
|
||||
.forEach(f -> {
|
||||
Map<String, Object> task = mapper.readValue(f.toFile(), Map.class);
|
||||
if ("pending".equals(task.get("status"))
|
||||
&& (task.get("owner") == null || "".equals(task.get("owner")))
|
||||
&& (task.get("blockedBy") == null
|
||||
|| ((List<?>) task.get("blockedBy")).isEmpty())) {
|
||||
unclaimed.add(task);
|
||||
}
|
||||
});
|
||||
}
|
||||
return unclaimed;
|
||||
}
|
||||
```
|
||||
|
||||
4. 身份重注入: 上下文过短 (说明发生了压缩) 时, 在开头插入身份块。
|
||||
4. 身份保持: Java/Spring AI 的 `ChatClient.defaultSystem()` 在每次调用时自动携带系统提示, 身份信息始终存在, 无需像 Python 版本那样在压缩后手动重注入。
|
||||
|
||||
```python
|
||||
if len(messages) <= 3:
|
||||
messages.insert(0, {"role": "user",
|
||||
"content": f"<identity>You are '{name}', role: {role}, "
|
||||
f"team: {team_name}. Continue your work.</identity>"})
|
||||
messages.insert(1, {"role": "assistant",
|
||||
"content": f"I am {name}. Continuing."})
|
||||
```java
|
||||
// 身份信息通过 defaultSystem 在构建时注入, 每次 prompt 自动携带
|
||||
String sysPrompt = String.format(
|
||||
"You are '%s', role: %s, team: %s, at %s. "
|
||||
+ "Use idle tool when you have no more work. You will auto-claim new tasks.",
|
||||
name, role, teamName, workDir);
|
||||
|
||||
ChatClient client = ChatClient.builder(chatModel)
|
||||
.defaultSystem(sysPrompt) // 身份始终存在于系统提示中
|
||||
.defaultTools(new BashTool(), new ReadFileTool(),
|
||||
new WriteFileTool(), new EditFileTool(),
|
||||
messageTool, protocolTool, idleTool, claimTool)
|
||||
.build();
|
||||
```
|
||||
|
||||
## 相对 s10 的变更
|
||||
@@ -132,7 +181,7 @@ if len(messages) <= 3:
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s11_autonomous_agents.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s11.S11AutonomousAgents
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
## 问题
|
||||
|
||||
到 s11, 智能体已经能自主认领和完成任务。但所有任务共享一个目录。两个智能体同时重构不同模块 -- A 改 `config.py`, B 也改 `config.py`, 未提交的改动互相污染, 谁也没法干净回滚。
|
||||
到 s11, 智能体已经能自主认领和完成任务。但所有任务共享一个目录。两个智能体同时重构不同模块 -- A 改 `Config.java`, B 也改 `Config.java`, 未提交的改动互相污染, 谁也没法干净回滚。
|
||||
|
||||
任务板管 "做什么" 但不管 "在哪做"。解法: 给每个任务一个独立的 git worktree 目录, 用任务 ID 把两边关联起来。
|
||||
|
||||
@@ -38,48 +38,71 @@ State machines:
|
||||
|
||||
1. **创建任务。** 先把目标持久化。
|
||||
|
||||
```python
|
||||
TASKS.create("Implement auth refactor")
|
||||
# -> .tasks/task_1.json status=pending worktree=""
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeTaskManager.java
|
||||
tasks.create("Implement auth refactor", "");
|
||||
// -> .tasks/task_1.json status=pending worktree=""
|
||||
```
|
||||
|
||||
2. **创建 worktree 并绑定任务。** 传入 `task_id` 自动将任务推进到 `in_progress`。
|
||||
|
||||
```python
|
||||
WORKTREES.create("auth-refactor", task_id=1)
|
||||
# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
|
||||
# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeManager.java
|
||||
worktrees.create("auth-refactor", 1, "HEAD");
|
||||
// -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
|
||||
// -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
|
||||
```
|
||||
|
||||
绑定同时写入两侧状态:
|
||||
|
||||
```python
|
||||
def bind_worktree(self, task_id, worktree):
|
||||
task = self._load(task_id)
|
||||
task["worktree"] = worktree
|
||||
if task["status"] == "pending":
|
||||
task["status"] = "in_progress"
|
||||
self._save(task)
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeTaskManager.java
|
||||
public String bindWorktree(int taskId, String worktree, String owner) {
|
||||
var task = load(taskId);
|
||||
task.put("worktree", worktree);
|
||||
if (owner != null && !owner.isEmpty()) task.put("owner", owner);
|
||||
if ("pending".equals(task.get("status"))) task.put("status", "in_progress");
|
||||
task.put("updated_at", System.currentTimeMillis() / 1000.0);
|
||||
save(task);
|
||||
return mapper.writerWithDefaultPrettyPrinter().writeValueAsString(task);
|
||||
}
|
||||
```
|
||||
|
||||
3. **在 worktree 中执行命令。** `cwd` 指向隔离目录。
|
||||
|
||||
```python
|
||||
subprocess.run(command, shell=True, cwd=worktree_path,
|
||||
capture_output=True, text=True, timeout=300)
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeManager.java - run()
|
||||
boolean isWindows = System.getProperty("os.name").toLowerCase().contains("win");
|
||||
ProcessBuilder pb = isWindows
|
||||
? new ProcessBuilder("cmd", "/c", command)
|
||||
: new ProcessBuilder("sh", "-c", command);
|
||||
pb.directory(path.toFile());
|
||||
pb.redirectErrorStream(true);
|
||||
Process p = pb.start();
|
||||
String out = new String(p.getInputStream().readAllBytes()).trim();
|
||||
boolean finished = p.waitFor(300, java.util.concurrent.TimeUnit.SECONDS);
|
||||
```
|
||||
|
||||
4. **收尾。** 两种选择:
|
||||
- `worktree_keep(name)` -- 保留目录供后续使用。
|
||||
- `worktree_remove(name, complete_task=True)` -- 删除目录, 完成绑定任务, 发出事件。一个调用搞定拆除 + 完成。
|
||||
|
||||
```python
|
||||
def remove(self, name, force=False, complete_task=False):
|
||||
self._run_git(["worktree", "remove", wt["path"]])
|
||||
if complete_task and wt.get("task_id") is not None:
|
||||
self.tasks.update(wt["task_id"], status="completed")
|
||||
self.tasks.unbind_worktree(wt["task_id"])
|
||||
self.events.emit("task.completed", ...)
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeManager.java
|
||||
public String remove(String name, boolean force, boolean completeTask) {
|
||||
var wt = findWorktree(name);
|
||||
events.emit("worktree.remove.before", ...);
|
||||
runGit("worktree", "remove", wt.get("path").toString());
|
||||
if (completeTask && wt.get("task_id") != null) {
|
||||
int taskId = ((Number) wt.get("task_id")).intValue();
|
||||
tasks.update(taskId, "completed", null);
|
||||
tasks.unbindWorktree(taskId);
|
||||
events.emit("task.completed",
|
||||
Map.of("id", taskId, "status", "completed"),
|
||||
Map.of("name", name), null);
|
||||
}
|
||||
// 更新 index.json: status -> "removed"
|
||||
}
|
||||
```
|
||||
|
||||
5. **事件流。** 每个生命周期步骤写入 `.worktrees/events.jsonl`:
|
||||
@@ -111,7 +134,7 @@ def remove(self, name, force=False, complete_task=False):
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s12_worktree_task_isolation.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s12.S12WorktreeIsolation
|
||||
```
|
||||
|
||||
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
|
||||
|
||||
Reference in New Issue
Block a user