pages = splitter.split(doc);
+
+for (int i = 0; i < pages.size(); i++) {
+ pages.get(i).save("page_" + (i + 1) + ".pdf");
+ pages.get(i).close();
+}
+doc.close();
```
## Key Libraries
-| Task | Library | Install |
-|------|---------|---------|
-| Read/Write/Merge | PyMuPDF | `pip install pymupdf` |
-| Create from scratch | ReportLab | `pip install reportlab` |
-| HTML to PDF | pdfkit | `pip install pdfkit` + wkhtmltopdf |
+| Task | Library | Maven Dependency |
+|------|---------|-----------------|
+| Read/Write/Merge/Split | Apache PDFBox | `org.apache.pdfbox:pdfbox:3.0.x` |
+| Create from HTML | OpenHTMLToPDF | `com.openhtmltopdf:openhtmltopdf-pdfbox:1.0.x` |
+| Advanced layout | iText | `com.itextpdf:itext7-core:8.0.x` |
| Text extraction | pdftotext | `brew install poppler` / `apt install poppler-utils` |
## Best Practices
1. **Always check if tools are installed** before using them
2. **Handle encoding issues** - PDFs may contain various character encodings
-3. **Large PDFs**: Process page by page to avoid memory issues
-4. **OCR for scanned PDFs**: Use `pytesseract` if text extraction returns empty
+3. **Large PDFs**: Process page by page to avoid memory issues; use try-with-resources 确保资源释放
+4. **OCR for scanned PDFs**: Use Tesseract4J (`net.sourceforge.tess4j:tess4j`) if text extraction returns empty
diff --git a/src/main/java/io/mybatis/learn/core/AgentRunner.java b/src/main/java/io/mybatis/learn/core/AgentRunner.java
new file mode 100644
index 0000000..860ef8a
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/AgentRunner.java
@@ -0,0 +1,82 @@
+package io.mybatis.learn.core;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Scanner;
+import java.util.function.Function;
+
+/**
+ * Agent 交互式 REPL（Read-Eval-Print Loop）工具类。
+ *
+ * TIP: 对应 Python 中每个 session 的 {@code if __name__ == "__main__"} 交互循环。
+ * Python 使用 {@code input()} 读取输入，Java 使用 {@code Scanner}。
+ */
+public class AgentRunner {
+ private static final Logger log = LoggerFactory.getLogger(AgentRunner.class);
+ private static final String ANSI_CYAN = "\033[36m";
+ private static final String ANSI_GREEN = "\033[32m";
+ private static final String ANSI_RED = "\033[31m";
+ private static final String ANSI_RESET = "\033[0m";
+
+ /**
+ * 启动交互式 REPL 循环。
+ *
+ * @param prefix 提示符前缀（如 "s01"）
+ * @param handler 处理用户输入并返回 Agent 响应的函数
+ */
+ public static void interactive(String prefix, Function handler) {
+ log.info("启动交互循环，prefix={}", prefix);
+ Scanner scanner = new Scanner(System.in);
+ System.out.println("输入 'q' 或 'exit' 退出");
+ System.out.println();
+ while (true) {
+ System.out.print(ANSI_CYAN + prefix + " >> " + ANSI_RESET);
+ String input;
+ try {
+ if (!scanner.hasNextLine()) break;
+ input = scanner.nextLine().trim();
+ } catch (Exception e) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("💭 读取输入异常，结束交互循环: prefix=%s, error=%s%n", prefix, e.getMessage());
+ }
+ break;
+ }
+ if (input.isEmpty() || "exit".equalsIgnoreCase(input) || "q".equalsIgnoreCase(input)) {
+ log.info("收到退出指令，结束交互循环，prefix={}", prefix);
+ break;
+ }
+ try {
+ String response = handler.apply(input);
+ if (response != null && !response.isBlank()) {
+ printAssistantResponse(response);
+ }
+ } catch (Exception e) {
+ log.warn("处理输入失败，prefix={}, error={}", prefix, e.getMessage());
+ printAssistantError(e.getMessage());
+ }
+ System.out.println();
+ }
+ log.info("交互循环结束，prefix={}", prefix);
+ System.out.println("Bye!");
+ }
+
+ private static void printAssistantResponse(String response) {
+ System.out.println(ANSI_GREEN + "assistant >>" + ANSI_RESET);
+ System.out.println(ANSI_CYAN + response + ANSI_RESET);
+ }
+
+ private static void printAssistantError(String errorMessage) {
+ System.out.println(ANSI_RED + "assistant !!" + ANSI_RESET);
+ System.out.println(ANSI_RED + "Error: " + errorMessage + ANSI_RESET);
+ }
+
+ /**
+ * 截断过长输出。
+ * TIP: 对应 Python 中 {@code out[:50000]} 的截断逻辑。
+ */
+ public static String truncate(String text, int maxLen) {
+ if (text == null) return "";
+ return text.length() > maxLen ? text.substring(0, maxLen) + "...(truncated)" : text;
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/core/team/MessageBus.java b/src/main/java/io/mybatis/learn/core/team/MessageBus.java
new file mode 100644
index 0000000..33f85d0
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/team/MessageBus.java
@@ -0,0 +1,121 @@
+package io.mybatis.learn.core.team;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import java.util.*;
+
+/**
+ * JSONL消息队列 - 每个teammate一个收件箱文件
+ *
+ * TIPS: 对应Python的MessageBus类（s09第78-118行）。
+ * Python用 open("a") 追加JSONL行，Java用 Files.writeString(APPEND)。
+ * Python靠GIL隐式保证线程安全，Java用 synchronized 显式保证。
+ */
+public class MessageBus {
+ private static final Logger log = LoggerFactory.getLogger(MessageBus.class);
+
+ public static final Set VALID_MSG_TYPES = Set.of(
+ "message", "broadcast", "shutdown_request",
+ "shutdown_response", "plan_approval_response"
+ );
+
+ private final Path inboxDir;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public MessageBus(Path inboxDir) {
+ this.inboxDir = inboxDir;
+ try {
+ Files.createDirectories(inboxDir);
+ if (log.isDebugEnabled()) {
+ System.out.printf("🚀 消息收件箱就绪: %s%n", inboxDir);
+ }
+ } catch (IOException e) {
+ log.error("创建消息收件箱目录失败: {}, error={}", inboxDir, e.getMessage());
+ throw new UncheckedIOException(e);
+ }
+ }
+
+ /**
+ * 发送消息到指定teammate的收件箱（追加JSONL行）
+ */
+ public synchronized String send(String sender, String to, String content,
+ String msgType, Map extra) {
+ if (!VALID_MSG_TYPES.contains(msgType)) {
+ log.warn("发送消息失败，消息类型非法: type={}", msgType);
+ return "Error: Invalid type '" + msgType + "'. Valid: " + VALID_MSG_TYPES;
+ }
+ Map 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);
+
+ try {
+ Path inbox = inboxDir.resolve(to + ".jsonl");
+ Files.writeString(inbox, mapper.writeValueAsString(msg) + "\n",
+ StandardOpenOption.CREATE, StandardOpenOption.APPEND);
+ if (log.isDebugEnabled()) {
+ System.out.printf("📨 消息已发送: %s → %s (%s)%n", sender, to, msgType);
+ }
+ return "Sent " + msgType + " to " + to;
+ } catch (IOException e) {
+ log.warn("消息发送失败: from={}, to={}, type={}, error={}", sender, to, msgType, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+
+ public String send(String sender, String to, String content) {
+ return send(sender, to, content, "message", null);
+ }
+
+ /**
+ * 读取并清空指定teammate的收件箱（drain模式）
+ */
+ @SuppressWarnings("unchecked")
+ public synchronized List> readInbox(String name) {
+ Path inbox = inboxDir.resolve(name + ".jsonl");
+ if (!Files.exists(inbox)) return List.of();
+ try {
+ List> messages = new ArrayList<>();
+ for (String line : Files.readAllLines(inbox)) {
+ if (!line.isBlank()) {
+ messages.add(mapper.readValue(line,
+ new TypeReference>() {}));
+ }
+ }
+ Files.writeString(inbox, "");
+ if (!messages.isEmpty()) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("📬 收件箱已读取: %s (%d 条消息)%n", name, messages.size());
+ }
+ }
+ return messages;
+ } catch (IOException e) {
+ log.warn("读取收件箱失败: name={}, error={}", name, e.getMessage());
+ return List.of();
+ }
+ }
+
+ /**
+ * 广播消息给所有teammates（排除发送者自己）
+ */
+ public String broadcast(String sender, String content, List teammates) {
+ int count = 0;
+ for (String name : teammates) {
+ if (!name.equals(sender)) {
+ send(sender, name, content, "broadcast", null);
+ count++;
+ }
+ }
+ return "Broadcast to " + count + " teammates";
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/core/tools/BashTool.java b/src/main/java/io/mybatis/learn/core/tools/BashTool.java
new file mode 100644
index 0000000..afa53f0
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/tools/BashTool.java
@@ -0,0 +1,93 @@
+package io.mybatis.learn.core.tools;
+
+import io.mybatis.learn.core.AgentRunner;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+
+/**
+ * Shell 命令执行工具。
+ *
+ * TIP: 对应 Python {@code s01_agent_loop.py} 中的 {@code run_bash(command)} 函数。
+ * Python 使用 {@code subprocess.run()}，Java 使用 {@code ProcessBuilder}。
+ * 安全机制相同：危险命令过滤 + 超时控制 + 输出截断。
+ */
+public class BashTool {
+ private static final Logger log = LoggerFactory.getLogger(BashTool.class);
+
+ private static final int TIMEOUT_SECONDS = 120;
+ private static final int MAX_OUTPUT_LENGTH = 50000;
+
+ private static final List DANGEROUS_PATTERNS = List.of(
+ "rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"
+ );
+
+ private final String workDir;
+
+ public BashTool() {
+ this.workDir = System.getProperty("user.dir");
+ }
+
+ public BashTool(String workDir) {
+ this.workDir = workDir;
+ }
+
+ @Tool(description = "Run a shell command and return stdout + stderr")
+ public String bash(@ToolParam(description = "The shell command to execute") String command) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔧 调用工具 [Bash] workDir=%s, command=%s%n", workDir,
+ command.substring(0, Math.min(80, command.length())));
+ }
+ // 危险命令检查
+ for (String pattern : DANGEROUS_PATTERNS) {
+ if (command.contains(pattern)) {
+ log.warn("拦截危险命令，pattern={}", pattern);
+ return "Error: Dangerous command blocked";
+ }
+ }
+ try {
+ ProcessBuilder pb = new ProcessBuilder();
+ if (System.getProperty("os.name").toLowerCase().contains("win")) {
+ pb.command("cmd", "/c", command);
+ } else {
+ pb.command("sh", "-c", command);
+ }
+ pb.directory(new java.io.File(workDir));
+ pb.redirectErrorStream(true);
+
+ Process process = pb.start();
+
+ // 读取输出
+ String output;
+ try (BufferedReader reader = new BufferedReader(
+ new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) {
+ output = reader.lines().collect(Collectors.joining("\n"));
+ }
+
+ boolean finished = process.waitFor(TIMEOUT_SECONDS, TimeUnit.SECONDS);
+ if (!finished) {
+ process.destroyForcibly();
+ log.warn("命令执行超时，timeout={}s", TIMEOUT_SECONDS);
+ return "Error: Timeout (" + TIMEOUT_SECONDS + "s)";
+ }
+
+ output = output.trim();
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 工具完成 [Bash] 输出 %d 字符%n", output.length());
+ }
+ if (output.isEmpty()) return "(no output)";
+ return AgentRunner.truncate(output, MAX_OUTPUT_LENGTH);
+ } catch (Exception e) {
+ log.warn("命令执行异常，error={}", e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/core/tools/EditFileTool.java b/src/main/java/io/mybatis/learn/core/tools/EditFileTool.java
new file mode 100644
index 0000000..e33d009
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/tools/EditFileTool.java
@@ -0,0 +1,62 @@
+package io.mybatis.learn.core.tools;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * 文件编辑工具（查找替换）。
+ *
+ * TIP: 对应 Python {@code s02_tool_use.py} 中的 {@code run_edit(path, old_text, new_text)} 函数。
+ * Python 使用 {@code str.replace(old, new, 1)}，Java 使用 {@code String.replaceFirst()}。
+ * 只替换第一次出现的匹配文本。
+ */
+public class EditFileTool {
+ private static final Logger log = LoggerFactory.getLogger(EditFileTool.class);
+
+ private final PathValidator pathValidator;
+
+ public EditFileTool() {
+ this.pathValidator = new PathValidator();
+ }
+
+ public EditFileTool(PathValidator pathValidator) {
+ this.pathValidator = pathValidator;
+ }
+
+ @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) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("✏️ 调用工具 [EditFile] path=%s (替换 %d→%d 字符)%n",
+ path, oldText == null ? 0 : oldText.length(), newText == null ? 0 : newText.length());
+ }
+ try {
+ Path filePath = pathValidator.resolve(path);
+ String content = Files.readString(filePath);
+
+ if (!content.contains(oldText)) {
+ log.warn("编辑文件失败，未找到目标文本: path={}", path);
+ return "Error: Text not found in " + path;
+ }
+
+ // 只替换第一次出现（使用 indexOf + substring 避免正则转义问题）
+ int index = content.indexOf(oldText);
+ String updated = content.substring(0, index) + newText + content.substring(index + oldText.length());
+ Files.writeString(filePath, updated);
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 工具完成 [EditFile] %s%n", path);
+ }
+ return "Edited " + path;
+ } catch (Exception e) {
+ log.warn("编辑文件异常: path={}, error={}", path, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/core/tools/PathValidator.java b/src/main/java/io/mybatis/learn/core/tools/PathValidator.java
new file mode 100644
index 0000000..c02eafe
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/tools/PathValidator.java
@@ -0,0 +1,41 @@
+package io.mybatis.learn.core.tools;
+
+import java.nio.file.Path;
+
+/**
+ * 路径安全校验工具。
+ *
+ * TIP: 对应 Python {@code s02_tool_use.py} 中的 {@code safe_path()} 函数。
+ * 防止路径逃逸（path traversal），确保所有文件操作都在工作目录范围内。
+ */
+public class PathValidator {
+
+ private final Path workDir;
+
+ public PathValidator() {
+ this.workDir = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
+ }
+
+ public PathValidator(Path workDir) {
+ this.workDir = workDir.toAbsolutePath().normalize();
+ }
+
+ /**
+ * 校验并解析路径，确保不逃逸出工作目录。
+ *
+ * @param relativePath 相对路径字符串
+ * @return 解析后的绝对路径
+ * @throws IllegalArgumentException 路径逃逸时抛出
+ */
+ 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;
+ }
+
+ public Path getWorkDir() {
+ return workDir;
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/core/tools/ReadFileTool.java b/src/main/java/io/mybatis/learn/core/tools/ReadFileTool.java
new file mode 100644
index 0000000..da2a115
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/tools/ReadFileTool.java
@@ -0,0 +1,61 @@
+package io.mybatis.learn.core.tools;
+
+import io.mybatis.learn.core.AgentRunner;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * 文件读取工具。
+ *
+ * TIP: 对应 Python {@code s02_tool_use.py} 中的 {@code run_read(path, limit)} 函数。
+ * Python 使用 {@code Path.read_text()}，Java 使用 {@code Files.readString()}。
+ * 支持可选的行数限制参数。
+ */
+public class ReadFileTool {
+ private static final Logger log = LoggerFactory.getLogger(ReadFileTool.class);
+
+ private static final int MAX_OUTPUT_LENGTH = 50000;
+
+ private final PathValidator pathValidator;
+
+ public ReadFileTool() {
+ this.pathValidator = new PathValidator();
+ }
+
+ public ReadFileTool(PathValidator pathValidator) {
+ this.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 (0 or negative for all)", required = false) Integer limit) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("📖 调用工具 [ReadFile] path=%s, limit=%s%n", path, limit);
+ }
+ try {
+ Path filePath = pathValidator.resolve(path);
+ List lines = Files.readAllLines(filePath);
+
+ if (limit != null && limit > 0 && limit < lines.size()) {
+ lines = lines.subList(0, limit);
+ lines.add("... (" + (Files.readAllLines(filePath).size() - limit) + " more lines)");
+ }
+
+ String content = String.join("\n", lines);
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 工具完成 [ReadFile] %s 共 %d 行%n", path, lines.size());
+ }
+ return AgentRunner.truncate(content, MAX_OUTPUT_LENGTH);
+ } catch (Exception e) {
+ log.warn("读取文件失败: path={}, error={}", path, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/core/tools/WriteFileTool.java b/src/main/java/io/mybatis/learn/core/tools/WriteFileTool.java
new file mode 100644
index 0000000..76574a7
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/core/tools/WriteFileTool.java
@@ -0,0 +1,51 @@
+package io.mybatis.learn.core.tools;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * 文件写入工具。
+ *
+ * TIP: 对应 Python {@code s02_tool_use.py} 中的 {@code run_write(path, content)} 函数。
+ * Python 使用 {@code Path.write_text()}，Java 使用 {@code Files.writeString()}。
+ * 自动创建父目录。
+ */
+public class WriteFileTool {
+ private static final Logger log = LoggerFactory.getLogger(WriteFileTool.class);
+
+ private final PathValidator pathValidator;
+
+ public WriteFileTool() {
+ this.pathValidator = new PathValidator();
+ }
+
+ public WriteFileTool(PathValidator pathValidator) {
+ this.pathValidator = pathValidator;
+ }
+
+ @Tool(description = "Write content to a file. Creates parent directories if needed.")
+ public String writeFile(
+ @ToolParam(description = "Relative path to the file") String path,
+ @ToolParam(description = "Content to write") String content) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("✏️ 调用工具 [WriteFile] path=%s (%d 字符)%n", path, content == null ? 0 : content.length());
+ }
+ try {
+ Path filePath = pathValidator.resolve(path);
+ Files.createDirectories(filePath.getParent());
+ Files.writeString(filePath, content);
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 工具完成 [WriteFile] %s (%d 字节)%n", path, content.length());
+ }
+ return "Wrote " + content.length() + " bytes to " + path;
+ } catch (Exception e) {
+ log.warn("写文件失败: path={}, error={}", path, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/full/FullTeammateManager.java b/src/main/java/io/mybatis/learn/full/FullTeammateManager.java
new file mode 100644
index 0000000..5723bb1
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/full/FullTeammateManager.java
@@ -0,0 +1,373 @@
+package io.mybatis.learn.full;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.team.MessageBus;
+import io.mybatis.learn.core.tools.*;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * 综合版 TeammateManager - 融合S09(团队) + S10(协议) + S11(自治) 全部特性
+ *
+ * TIPS: 对应Python s_full.py的TeammateManager（第400-543行）。
+ * 特性汇总：
+ * S09: 虚拟线程 + JSONL收件箱通信
+ * S10: shutdown_request 检测 + 优雅退出
+ * S11: idle轮询 + 自动认领未分配任务
+ *
+ * Python队友执行50轮LLM调用的手动工具循环；
+ * Java队友用ChatClient.prompt().call()自动处理工具循环，每次call()相当于Python整个while循环。
+ */
+public class FullTeammateManager {
+
+ private static final int POLL_INTERVAL = 5;
+ private static final int IDLE_TIMEOUT = 60;
+ private static final int MAX_WORK_PHASES = 3;
+
+ private final ChatModel chatModel;
+ private final MessageBus bus;
+ private final Path teamDir;
+ private final Path configPath;
+ private final Path tasksDir;
+ private final ObjectMapper mapper = new ObjectMapper();
+ private Map config;
+ private final Map threads = new ConcurrentHashMap<>();
+
+ public FullTeammateManager(ChatModel chatModel, MessageBus bus,
+ Path teamDir, Path tasksDir) {
+ this.chatModel = chatModel;
+ this.bus = bus;
+ this.teamDir = teamDir;
+ this.configPath = teamDir.resolve("config.json");
+ this.tasksDir = tasksDir;
+ try { Files.createDirectories(teamDir); } catch (IOException e) { throw new RuntimeException(e); }
+ this.config = loadConfig();
+ }
+
+ @SuppressWarnings("unchecked")
+ private Map loadConfig() {
+ if (Files.exists(configPath)) {
+ try { return mapper.readValue(configPath.toFile(), new TypeReference<>() {}); }
+ catch (IOException e) { /* ignore */ }
+ }
+ Map def = new LinkedHashMap<>();
+ def.put("team_name", "default");
+ def.put("members", new ArrayList<>());
+ return def;
+ }
+
+ private synchronized void saveConfig() {
+ try { mapper.writerWithDefaultPrettyPrinter().writeValue(configPath.toFile(), config); }
+ catch (IOException e) { System.err.println("Config save error: " + e.getMessage()); }
+ }
+
+ @SuppressWarnings("unchecked")
+ private void setStatus(String name, String status) {
+ var members = (List>) config.get("members");
+ for (var m : members) {
+ if (name.equals(m.get("name"))) m.put("status", status);
+ }
+ saveConfig();
+ }
+
+ // ---- 公开方法 ----
+
+ @SuppressWarnings("unchecked")
+ public String spawn(String name, String role, String prompt) {
+ var members = (List>) config.get("members");
+ members.removeIf(m -> name.equals(m.get("name")));
+
+ Map member = new LinkedHashMap<>();
+ member.put("name", name);
+ member.put("role", role);
+ member.put("status", "working");
+ members.add(member);
+ saveConfig();
+
+ Thread t = Thread.startVirtualThread(() -> {
+ try { teammateLoop(name, role, prompt); }
+ catch (Exception e) {
+ System.err.println(" [" + name + "] Fatal: " + e.getMessage());
+ setStatus(name, "error");
+ }
+ });
+ threads.put(name, t);
+ return "Spawned '" + name + "' (role: " + role + ")";
+ }
+
+ @SuppressWarnings("unchecked")
+ public String listAll() {
+ var members = (List>) config.get("members");
+ if (members.isEmpty()) return "No teammates.";
+ StringBuilder sb = new StringBuilder();
+ for (var m : members) {
+ sb.append(String.format("[%s] %s (role: %s)%n",
+ m.getOrDefault("status", "unknown"), m.get("name"), m.get("role")));
+ }
+ return sb.toString().trim();
+ }
+
+ @SuppressWarnings("unchecked")
+ public List memberNames() {
+ var members = (List>) config.get("members");
+ return members.stream().map(m -> (String) m.get("name")).toList();
+ }
+
+ // ---- 队友主循环：工作 → 空闲 → 自动认领/恢复/关闭 ----
+
+ private void teammateLoop(String name, String role, String initialPrompt) {
+ String workDir = System.getProperty("user.dir");
+ String sysPrompt = String.format(
+ "You are '%s', role: %s, at %s. "
+ + "Send messages with send_message. Call idle when you have no more work. "
+ + "Call claim_task to pick up unassigned tasks from the shared board.",
+ name, role, workDir);
+
+ AtomicBoolean idleFlag = new AtomicBoolean(false);
+
+ var msgTool = new TeammateMessageTool(bus, name);
+ var idleTool = new IdleTool(idleFlag);
+ var claimTool = new ClaimTaskTool(tasksDir, name);
+
+ ChatClient client = ChatClient.builder(chatModel)
+ .defaultSystem(sysPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(),
+ msgTool, idleTool, claimTool)
+ .build();
+
+ String nextInput = initialPrompt;
+
+ for (int phase = 0; phase < MAX_WORK_PHASES; phase++) {
+ // ---- 工作阶段 ----
+ setStatus(name, "working");
+ idleFlag.set(false);
+
+ for (int round = 0; round < 50; round++) {
+ // 检查收件箱
+ var inbox = bus.readInbox(name);
+ StringBuilder input = new StringBuilder();
+ if (nextInput != null) { input.append(nextInput); nextInput = null; }
+
+ boolean shutdownRequested = false;
+ for (var msg : inbox) {
+ if ("shutdown_request".equals(msg.get("type"))) {
+ shutdownRequested = true;
+ bus.send(name, "lead", "Acknowledged shutdown.", "shutdown_response", null);
+ } else {
+ input.append("\n").append(toJson(msg)).append("");
+ }
+ }
+
+ if (shutdownRequested) {
+ System.out.println(" [" + name + "] Shutdown acknowledged.");
+ setStatus(name, "shutdown");
+ return;
+ }
+
+ String trimmedInput = input.toString().trim();
+ if (trimmedInput.isEmpty()) {
+ if (round > 0) break; // 没有更多输入，结束工作阶段
+ continue;
+ }
+
+ try {
+ String response = client.prompt(trimmedInput).call().content();
+ System.out.println(" [" + name + "] " + AgentRunner.truncate(response, 120));
+ } catch (Exception e) {
+ System.err.println(" [" + name + "] LLM error: " + e.getMessage());
+ break;
+ }
+
+ if (idleFlag.get()) break;
+ try { Thread.sleep(1000); } catch (InterruptedException e) { return; }
+ }
+
+ // ---- 空闲阶段 (S11) ----
+ setStatus(name, "idle");
+ System.out.println(" [" + name + "] Entering idle phase...");
+
+ boolean resume = false;
+ long deadline = System.currentTimeMillis() + IDLE_TIMEOUT * 1000L;
+
+ while (System.currentTimeMillis() < deadline) {
+ try { Thread.sleep(POLL_INTERVAL * 1000L); } catch (InterruptedException e) { return; }
+
+ // 轮询收件箱
+ var inbox = bus.readInbox(name);
+ if (!inbox.isEmpty()) {
+ StringBuilder sb = new StringBuilder();
+ boolean shutdown = false;
+ for (var msg : inbox) {
+ if ("shutdown_request".equals(msg.get("type"))) {
+ shutdown = true;
+ } else {
+ sb.append("").append(toJson(msg)).append("\n");
+ }
+ }
+ if (shutdown) {
+ bus.send(name, "lead", "Acknowledged shutdown.", "shutdown_response", null);
+ setStatus(name, "shutdown");
+ return;
+ }
+ String inboxInput = sb.toString().trim();
+ if (!inboxInput.isEmpty()) {
+ nextInput = inboxInput;
+ resume = true;
+ break;
+ }
+ }
+
+ // 自动认领未分配任务 (S11)
+ var unclaimed = scanUnclaimedTasks();
+ if (!unclaimed.isEmpty()) {
+ var task = unclaimed.get(0);
+ claimTaskFile(task, name);
+ nextInput = "Task #" + task.get("id") + ": "
+ + task.get("subject") + "\n"
+ + task.getOrDefault("description", "") + "";
+ resume = true;
+ break;
+ }
+ }
+
+ if (!resume) {
+ System.out.println(" [" + name + "] Idle timeout. Shutting down.");
+ setStatus(name, "shutdown");
+ return;
+ }
+ }
+
+ setStatus(name, "idle");
+ }
+
+ // ---- 辅助方法 ----
+
+ @SuppressWarnings("unchecked")
+ private List> scanUnclaimedTasks() {
+ if (tasksDir == null || !Files.exists(tasksDir)) return List.of();
+ try (var files = Files.list(tasksDir)) {
+ List> result = new ArrayList<>();
+ files.filter(f -> f.getFileName().toString().matches("task_\\d+\\.json"))
+ .forEach(f -> {
+ try {
+ Map task = mapper.readValue(f.toFile(), new TypeReference<>() {});
+ if ("pending".equals(task.get("status"))
+ && (task.get("owner") == null || task.get("owner").toString().isEmpty())) {
+ var blocked = (List) task.getOrDefault("blockedBy", List.of());
+ if (blocked == null || blocked.isEmpty()) result.add(task);
+ }
+ } catch (IOException e) { /* skip */ }
+ });
+ return result;
+ } catch (IOException e) { return List.of(); }
+ }
+
+ private void claimTaskFile(Map task, String owner) {
+ int taskId = ((Number) task.get("id")).intValue();
+ task.put("owner", owner);
+ task.put("status", "in_progress");
+ task.put("updated_at", System.currentTimeMillis() / 1000.0);
+ try {
+ mapper.writerWithDefaultPrettyPrinter().writeValue(
+ tasksDir.resolve("task_" + taskId + ".json").toFile(), task);
+ } catch (IOException e) { /* ignore */ }
+ }
+
+ private String toJson(Object obj) {
+ try { return mapper.writeValueAsString(obj); }
+ catch (Exception e) { return obj.toString(); }
+ }
+
+ // ---- 参数化工具对象（每个队友独立实例） ----
+
+ /**
+ * TIPS: 队友的消息工具。每个实例绑定特定的发送者名称（sender identity）。
+ * 对应Python中 TOOL_HANDLERS["send_message"] 和 TOOL_HANDLERS["read_inbox"]。
+ */
+ public static class TeammateMessageTool {
+ private final MessageBus bus;
+ private final String name;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public TeammateMessageTool(MessageBus bus, String name) {
+ this.bus = bus;
+ this.name = name;
+ }
+
+ @Tool(description = "Send message to another teammate or lead")
+ public String sendMessage(
+ @ToolParam(description = "Recipient name") String to,
+ @ToolParam(description = "Message content") String content) {
+ return bus.send(name, to, content);
+ }
+
+ @Tool(description = "Read and drain your inbox")
+ public String readInbox() {
+ try { return mapper.writeValueAsString(bus.readInbox(name)); }
+ catch (Exception e) { return "[]"; }
+ }
+ }
+
+ /**
+ * TIPS: 空闲信号工具。通过AtomicBoolean标志跨线程通信。
+ * Python中idle()直接break循环；Java中ChatClient自动处理工具循环，
+ * idle设置标志后，等call()返回再检查标志来退出外层循环。
+ */
+ public static class IdleTool {
+ private final AtomicBoolean flag;
+
+ public IdleTool(AtomicBoolean flag) { this.flag = flag; }
+
+ @Tool(description = "Signal that you have completed current work and entering idle state")
+ public String idle() {
+ flag.set(true);
+ return "Entering idle phase. Will poll for new tasks.";
+ }
+ }
+
+ /**
+ * TIPS: 任务认领工具。对应Python的claim_task（s_full第513-530行）。
+ * 直接读写 .tasks/task_N.json 文件，将owner设为当前队友名。
+ */
+ public static class ClaimTaskTool {
+ private final Path tasksDir;
+ private final String owner;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public ClaimTaskTool(Path tasksDir, String owner) {
+ this.tasksDir = tasksDir;
+ this.owner = owner;
+ }
+
+ @SuppressWarnings("unchecked")
+ @Tool(description = "Claim an unclaimed task from the shared task board")
+ public String claimTask(@ToolParam(description = "Task ID to claim") int taskId) {
+ try {
+ Path path = tasksDir.resolve("task_" + taskId + ".json");
+ if (!Files.exists(path)) return "Error: Task " + taskId + " not found";
+ Map task = mapper.readValue(path.toFile(), new TypeReference<>() {});
+ if (!"pending".equals(task.get("status")))
+ return "Error: Task " + taskId + " is not pending (status: " + task.get("status") + ")";
+ task.put("owner", owner);
+ task.put("status", "in_progress");
+ task.put("updated_at", System.currentTimeMillis() / 1000.0);
+ mapper.writerWithDefaultPrettyPrinter().writeValue(path.toFile(), task);
+ return "Claimed task " + taskId + ": " + task.get("subject");
+ } catch (IOException e) {
+ return "Error: " + e.getMessage();
+ }
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/full/SFullAgent.java b/src/main/java/io/mybatis/learn/full/SFullAgent.java
new file mode 100644
index 0000000..a3442f8
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/full/SFullAgent.java
@@ -0,0 +1,267 @@
+package io.mybatis.learn.full;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.team.MessageBus;
+import io.mybatis.learn.core.tools.*;
+import io.mybatis.learn.s03.TodoManager;
+import io.mybatis.learn.s04.SubagentTool;
+import io.mybatis.learn.s05.SkillLoader;
+import io.mybatis.learn.s07.TaskManager;
+import io.mybatis.learn.s08.BackgroundManager;
+import io.mybatis.learn.s10.ProtocolTracker;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.nio.file.Path;
+import java.util.*;
+
+/**
+ * Full Agent - 融合 S01-S11 全部机制的综合型Agent
+ *
+ * TIPS: 对应Python s_full.py（全部700+行）。
+ * 组合了12节课的所有核心概念：
+ *
+ * S01: ChatClient基础循环 → AgentRunner.interactive()
+ * S02: 4个基础工具 → BashTool, ReadFileTool, WriteFileTool, EditFileTool
+ * S03: TodoManager + 催促提醒 → todos.render() 注入系统提示 + nag counter
+ * S04: 子Agent委派 → SubagentTool
+ * S05: 技能加载 → SkillLoader
+ * S06: 上下文压缩（简化版） → /compact 命令
+ * S07: 持久化任务板 → TaskManager
+ * S08: 后台任务 + 通知排空 → BackgroundManager.drainNotifications()
+ * S09: 团队消息总线 → MessageBus + FullTeammateManager
+ * S10: 关闭/计划协议 → ProtocolTracker
+ * S11: 自治队友（空闲轮询+自动认领）→ FullTeammateManager idle+autoclaim
+ *
+ * 每次REPL调用前的流水线：
+ * 1. 排空后台通知 → 注入
+ * 2. 排空Lead收件箱 → 注入
+ * 3. Todo催促检查 → 注入
+ * 4. 重建ChatClient（注入当前todo状态到系统提示）
+ * 5. 调用LLM
+ *
+ * REPL命令：/compact, /tasks, /team, /inbox
+ * 工具总数：~20个（4基础 + TodoWrite + task + load_skill + 4任务 + 2后台 + 7团队协议）
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class SFullAgent implements CommandLineRunner {
+
+ @Autowired
+ private ChatModel chatModel;
+
+ @Override
+ public void run(String... args) throws Exception {
+ Path workDir = Path.of(System.getProperty("user.dir"));
+ Path teamDir = workDir.resolve(".team");
+
+ // ---- 初始化所有组件 ----
+
+ // S03: 内存中的todo列表
+ TodoManager todos = new TodoManager();
+
+ // S04: 子Agent委派
+ SubagentTool subagent = new SubagentTool(chatModel);
+
+ // S05: 技能加载
+ SkillLoader skills = new SkillLoader(workDir.resolve("skills"));
+
+ // S07: 持久化任务板
+ TaskManager taskMgr = new TaskManager(workDir.resolve(".tasks"));
+
+ // S08: 后台命令执行
+ BackgroundManager bgMgr = new BackgroundManager();
+
+ // S09: 团队消息总线
+ MessageBus bus = new MessageBus(teamDir.resolve("inbox"));
+
+ // S10: 协议追踪
+ ProtocolTracker protocols = new ProtocolTracker(bus);
+
+ // S09+S10+S11: 自治队友管理
+ FullTeammateManager team = new FullTeammateManager(
+ chatModel, bus, teamDir, workDir.resolve(".tasks"));
+
+ // Lead专用工具
+ LeadTools leadTools = new LeadTools(bus, team, protocols, taskMgr);
+
+ // ---- 系统提示 ----
+ String baseSystem = "You are a coding agent at " + workDir + ". Use tools to solve tasks.\n"
+ + "Prefer task_create/task_update/task_list for multi-step work. "
+ + "Use updateTodos for short checklists.\n"
+ + "Use task for subagent delegation. Use load_skill for specialized knowledge.\n"
+ + "Skills: " + skills.getDescriptions();
+
+ // S03: 催促计数器
+ final int[] roundsWithoutTodo = {0};
+ ObjectMapper mapper = new ObjectMapper();
+
+ System.out.println("Full Agent initialized. Components: todo, subagent, skills, "
+ + "tasks, background, team, protocols");
+ System.out.println("Commands: /compact, /tasks, /team, /inbox, q/exit");
+
+ // ---- REPL ----
+ AgentRunner.interactive("s_full", input -> {
+ // REPL命令
+ if ("/compact".equals(input)) {
+ return "[compact] 无状态模式，无会话历史可压缩。"
+ + "每次调用独立进行（TIPS: Python版维护messages列表并在超过100K token时自动压缩）。";
+ }
+ if ("/tasks".equals(input)) return taskMgr.taskList();
+ if ("/team".equals(input)) return team.listAll();
+ if ("/inbox".equals(input)) {
+ try { return mapper.writeValueAsString(bus.readInbox("lead")); }
+ catch (Exception e) { return "[]"; }
+ }
+
+ // ---- 调用前流水线 ----
+ StringBuilder prefix = new StringBuilder();
+
+ // S08: 排空后台通知
+ var notifications = bgMgr.drainNotifications();
+ if (!notifications.isEmpty()) {
+ prefix.append("\n");
+ for (var n : notifications) {
+ prefix.append(String.format("[bg:%s] %s: %s%n",
+ n.taskId(), n.status(),
+ AgentRunner.truncate(n.result() != null ? n.result() : "", 500)));
+ }
+ prefix.append("\n");
+ }
+
+ // S09: 排空Lead收件箱
+ var inbox = bus.readInbox("lead");
+ if (!inbox.isEmpty()) {
+ try {
+ prefix.append("")
+ .append(mapper.writeValueAsString(inbox))
+ .append("\n");
+ } catch (Exception e) { /* ignore */ }
+ }
+
+ // S03: Todo催促（连续3轮未更新todo时提醒）
+ String rendered = todos.render();
+ boolean hasOpenTodos = rendered.contains("[ ]") || rendered.contains("[>");
+ if (hasOpenTodos && roundsWithoutTodo[0] >= 3) {
+ prefix.append("You have open todos. Please update them.\n");
+ }
+ roundsWithoutTodo[0]++;
+
+ String fullInput = prefix.length() > 0 ? prefix + "\n" + input : input;
+
+ // 每次重建ChatClient，注入最新todo状态到系统提示
+ String currentSystem = baseSystem + "\n\nCurrent todos:\n" + rendered;
+
+ ChatClient client = ChatClient.builder(chatModel)
+ .defaultSystem(currentSystem)
+ .defaultTools(
+ new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(),
+ todos, subagent, skills,
+ taskMgr, bgMgr, leadTools)
+ .build();
+
+ String response = client.prompt(fullInput).call().content();
+
+ // 简易启发式：如果响应提及"todo"，重置催促计数器
+ if (response != null && response.toLowerCase().contains("todo")) {
+ roundsWithoutTodo[0] = 0;
+ }
+
+ return response;
+ });
+ }
+
+ // ---- Lead专用工具集：团队管理 + 协议 + 任务认领 ----
+
+ /**
+ * TIPS: 对应Python s_full.py中Lead可用的团队/协议工具。
+ * 7个工具：spawn_teammate, list_teammates, send_message, read_inbox, broadcast,
+ * shutdown_request, plan_approval
+ *
+ * Python中这些是TOOL_HANDLERS字典里的独立函数；
+ * Java中聚合为一个@Tool对象，通过ChatClient.defaultTools()注册。
+ */
+ public static class LeadTools {
+ private final MessageBus bus;
+ private final FullTeammateManager team;
+ private final ProtocolTracker protocols;
+ private final TaskManager taskMgr;
+
+ public LeadTools(MessageBus bus, FullTeammateManager team,
+ ProtocolTracker protocols, TaskManager taskMgr) {
+ this.bus = bus;
+ this.team = team;
+ this.protocols = protocols;
+ this.taskMgr = taskMgr;
+ }
+
+ @Tool(description = "Spawn an autonomous teammate that runs in its own thread with idle+auto-claim")
+ public String spawnTeammate(
+ @ToolParam(description = "Unique teammate name") String name,
+ @ToolParam(description = "Role description") String role,
+ @ToolParam(description = "Initial task prompt") String prompt) {
+ return team.spawn(name, role, prompt);
+ }
+
+ @Tool(description = "List all teammates with name, role, status")
+ public String listTeammates() {
+ return team.listAll();
+ }
+
+ @Tool(description = "Send message to a teammate's inbox")
+ public String sendMessage(
+ @ToolParam(description = "Recipient name") String to,
+ @ToolParam(description = "Message content") String content) {
+ return bus.send("lead", to, content);
+ }
+
+ @Tool(description = "Read and drain the lead's inbox")
+ public String readInbox() {
+ try { return new ObjectMapper().writeValueAsString(bus.readInbox("lead")); }
+ catch (Exception e) { return "[]"; }
+ }
+
+ @Tool(description = "Broadcast message to all teammates")
+ public String broadcast(
+ @ToolParam(description = "Message content") String content) {
+ return bus.broadcast("lead", content, team.memberNames());
+ }
+
+ @Tool(description = "Request a teammate to shutdown gracefully")
+ public String shutdownRequest(
+ @ToolParam(description = "Teammate name to shutdown") String teammate) {
+ return protocols.handleShutdownRequest(teammate);
+ }
+
+ @Tool(description = "Approve or reject a teammate's plan submission")
+ public String planApproval(
+ @ToolParam(description = "Plan request ID") String requestId,
+ @ToolParam(description = "Teammate who submitted the plan") String teammate,
+ @ToolParam(description = "Whether to approve the plan") boolean approve,
+ @ToolParam(description = "Feedback message") String feedback) {
+ String result = protocols.reviewPlan(requestId, approve, feedback);
+ String status = approve ? "approved" : "rejected";
+ bus.send("lead", teammate, feedback != null ? feedback : status,
+ "plan_approval_response",
+ Map.of("request_id", requestId, "status", status));
+ return result;
+ }
+
+ @Tool(description = "Claim an unclaimed task for the lead agent")
+ public String claimTask(
+ @ToolParam(description = "Task ID to claim") int taskId) {
+ return taskMgr.taskUpdate(taskId, "in_progress", null, null);
+ }
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(SFullAgent.class, args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s01/S01AgentLoop.java b/src/main/java/io/mybatis/learn/s01/S01AgentLoop.java
new file mode 100644
index 0000000..bf5f097
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s01/S01AgentLoop.java
@@ -0,0 +1,82 @@
+package io.mybatis.learn.s01;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * S01 - Agent 循环：AI 编码 Agent 的全部秘密。
+ *
+ * 格言: "One loop & Bash is all you need"
+ *
+ * 核心模式:
+ *
+ * +----------+ +-------+ +---------+
+ * | User | ---> | LLM | ---> | Tool |
+ * | prompt | | | | execute |
+ * +----------+ +---+---+ +----+----+
+ * ^ |
+ * | tool_result |
+ * +---------------+
+ * (loop continues)
+ *
+ *
+ * TIP: 对应 Python {@code agents/s01_agent_loop.py}。
+ * Python 版本手动实现 while 循环 + tool dispatch。
+ * Spring AI 的 {@link ChatClient} 内置了工具调用循环，
+ * 调用 {@code .tools(...).call()} 时自动完成：发送请求 → 检测 tool_use → 执行工具 → 回传结果 → 重复。
+ * 因此 Java 版本无需手写 while 循环，一行 {@code chatClient.prompt()...call()} 即可。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S01AgentLoop implements CommandLineRunner {
+
+ private final ChatClient chatClient;
+
+ /**
+ * TIP: Python 版在模块级创建 client = Anthropic() 和 MODEL。
+ * Spring AI 通过自动配置注入 ChatModel，再用 builder 构建 ChatClient。
+ */
+ public S01AgentLoop(ChatModel chatModel) {
+ // TIP: Python 的 SYSTEM prompt 对应 ChatClient 的 defaultSystem
+ // TIP: Python 的 TOOLS 数组 + TOOL_HANDLERS 对应 Spring AI 的 @Tool 注解 + defaultTools
+ 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())
+ .build();
+ }
+
+ @Override
+ public void run(String... args) {
+ /*
+ * TIP: 对应 Python 的 agent_loop(messages) 函数。
+ *
+ * Python 版需要手动实现:
+ * while True:
+ * response = client.messages.create(model, messages, tools)
+ * if response.stop_reason != "tool_use": return
+ * 执行工具, 收集结果
+ * messages.append(tool_results)
+ *
+ * Spring AI 的 ChatClient.call() 内部已封装此循环，
+ * 包括工具调用检测、自动执行、结果回传，直到模型返回最终文本。
+ */
+ AgentRunner.interactive("s01", userMessage ->
+ chatClient.prompt()
+ .user(userMessage)
+ .call()
+ .content()
+ );
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S01AgentLoop.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s02/S02ToolUse.java b/src/main/java/io/mybatis/learn/s02/S02ToolUse.java
new file mode 100644
index 0000000..5a69393
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s02/S02ToolUse.java
@@ -0,0 +1,81 @@
+package io.mybatis.learn.s02;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * S02 - 工具使用：扩展 Agent 能触达的范围。
+ *
+ * 格言: "加一个工具, 只加一个 handler"
+ *
+ * 核心变化:
+ *
+ * +----------+ +-------+ +------------------+
+ * | User | ---> | LLM | ---> | Tool Dispatch |
+ * | prompt | | | | { |
+ * +----------+ +---+---+ | bash |
+ * ^ | read_file |
+ * | | write_file |
+ * +----------+ edit_file |
+ * tool_result| } |
+ * +------------------+
+ *
+ *
+ * TIP: 对应 Python {@code agents/s02_tool_use.py}。
+ * Python 版通过 {@code TOOL_HANDLERS = {"bash": fn, "read_file": fn, ...}} 字典进行分派。
+ * Spring AI 通过 {@code @Tool} 注解声明工具，传入 {@code defaultTools()} 即可自动注册和分派。
+ * 关键洞察: "循环一点没变，只是多加了工具" —— 在 Spring AI 中更加明显，
+ * 因为循环由框架管理，开发者只需关注工具的实现。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S02ToolUse implements CommandLineRunner {
+
+ private final ChatClient chatClient;
+
+ /**
+ * TIP: Python 版在模块级定义 4 个工具函数 + TOOL_HANDLERS 字典。
+ * Spring AI 只需创建工具对象并传入 defaultTools()，框架自动完成注册和分派。
+ */
+ public S02ToolUse(ChatModel chatModel) {
+ this.chatClient = ChatClient.builder(chatModel)
+ .defaultSystem("You are a coding agent at " + System.getProperty("user.dir")
+ + ". Use tools to solve tasks. Act, don't explain.")
+ .defaultTools(
+ new BashTool(),
+ new ReadFileTool(),
+ new WriteFileTool(),
+ new EditFileTool()
+ )
+ .build();
+ }
+
+ @Override
+ public void run(String... args) {
+ /*
+ * TIP: 对比 Python 的 agent_loop()，循环代码完全相同——只是 TOOLS 数组多了 3 个工具。
+ * 在 Spring AI 中，循环代码也完全相同——只是 defaultTools() 多传了 3 个对象。
+ * 这正是 s02 的核心洞察: 扩展能力不需要修改循环。
+ */
+ AgentRunner.interactive("s02", userMessage ->
+ chatClient.prompt()
+ .user(userMessage)
+ .call()
+ .content()
+ );
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S02ToolUse.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s03/S03TodoWrite.java b/src/main/java/io/mybatis/learn/s03/S03TodoWrite.java
new file mode 100644
index 0000000..a25109d
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s03/S03TodoWrite.java
@@ -0,0 +1,102 @@
+package io.mybatis.learn.s03;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * S03 - TodoWrite：让 Agent 追踪自己的进度。
+ *
+ * 格言: "没有计划的 agent 走哪算哪"
+ *
+ * 核心模式:
+ *
+ * +----------+ +-------+ +---------+
+ * | User | ---> | LLM | ---> | Tools |
+ * | prompt | | | | + todo |
+ * +----------+ +---+---+ +----+----+
+ * ^ |
+ * | tool_result |
+ * +---------------+
+ * |
+ * +-----------+-----------+
+ * | TodoManager state |
+ * | [ ] task A |
+ * | [>] task B |
+ * | [x] task C |
+ * +-----------------------+
+ *
+ *
+ * TIP: 对应 Python {@code agents/s03_todo_write.py}。
+ * Python 版在工具循环内追踪 {@code rounds_since_todo}，
+ * 连续 3 轮未调用 todo 时注入 {@code Update your todos.} 文本。
+ * Spring AI 的 ChatClient 自动管理工具循环，无法在循环内注入文本，
+ * 因此改用系统提示注入当前 todo 状态 + 强调更新指令的方式实现同等效果。
+ * 如需精确的轮次追踪，可实现自定义 {@code Advisor}。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S03TodoWrite implements CommandLineRunner {
+
+ private final ChatModel chatModel;
+ private final TodoManager todoManager = new TodoManager();
+
+ public S03TodoWrite(ChatModel chatModel) {
+ this.chatModel = chatModel;
+ }
+
+ @Override
+ public void run(String... args) {
+ String workDir = System.getProperty("user.dir");
+
+ /*
+ * TIP: 每次用户输入时重建 ChatClient，将最新的 todo 状态注入系统提示。
+ * 这对应 Python 版在 agent_loop() 中每轮都能看到 TodoManager 状态的效果。
+ */
+ AgentRunner.interactive("s03", userMessage -> {
+ // 动态系统提示：包含当前 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"
+ + "Prefer tools over prose.\n"
+ + "IMPORTANT: You MUST call updateTodos regularly to track your progress.\n\n"
+ + "\n" + todoManager.render() + "\n";
+
+ ChatClient chatClient = ChatClient.builder(chatModel)
+ .defaultSystem(system)
+ .defaultTools(
+ new BashTool(),
+ new ReadFileTool(),
+ new WriteFileTool(),
+ new EditFileTool(),
+ todoManager
+ )
+ .build();
+
+ String response = chatClient.prompt()
+ .user(userMessage)
+ .call()
+ .content();
+
+ // 每次回复后打印当前 todo 状态
+ System.out.println("\n--- Todo Status ---");
+ System.out.println(todoManager.render());
+ System.out.println("-------------------");
+
+ return response;
+ });
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S03TodoWrite.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s03/TodoManager.java b/src/main/java/io/mybatis/learn/s03/TodoManager.java
new file mode 100644
index 0000000..5e82370
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s03/TodoManager.java
@@ -0,0 +1,102 @@
+package io.mybatis.learn.s03;
+
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Todo 任务管理器 —— Agent 追踪自身进度的结构化状态。
+ *
+ * TIP: 对应 Python {@code agents/s03_todo_write.py} 中的 {@code TodoManager} 类。
+ * Python 版通过 {@code TOOL_HANDLERS["todo"]} 注册，
+ * Spring AI 使用 {@code @Tool} 注解直接在方法上声明。
+ *
+ * 验证规则:
+ *
+ * - 最多 20 个 todo
+ * - 最多 1 个 in_progress 状态
+ * - text 不能为空
+ * - status 只能是 pending / in_progress / completed
+ *
+ */
+public class TodoManager {
+
+ /**
+ * Todo 项数据结构。
+ * TIP: 对应 Python 中 todo item 字典 {@code {"id": ..., "text": ..., "status": ...}}。
+ */
+ public record TodoItem(String id, String text, String status) {
+ }
+
+ private static final List VALID_STATUSES = List.of("pending", "in_progress", "completed");
+
+ private List items = new ArrayList<>();
+
+ /**
+ * 更新整个 todo 列表。
+ * TIP: 对应 Python {@code TodoManager.update(items)}，验证逻辑完全一致。
+ */
+ @Tool(description = "Update the full task list to track progress on multi-step tasks. "
+ + "Each item must have id, text, and 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 items) {
+ if (items.size() > 20) {
+ return "Error: Max 20 todos allowed";
+ }
+
+ List validated = new ArrayList<>();
+ int inProgressCount = 0;
+
+ for (int i = 0; i < items.size(); i++) {
+ TodoItem item = items.get(i);
+ String id = (item.id() != null && !item.id().isBlank()) ? item.id() : String.valueOf(i + 1);
+ String text = item.text();
+ String status = (item.status() != null) ? item.status().toLowerCase() : "pending";
+
+ if (text == null || text.isBlank()) {
+ return "Error: Item " + id + ": text required";
+ }
+ if (!VALID_STATUSES.contains(status)) {
+ return "Error: Item " + id + ": invalid status '" + status + "'";
+ }
+ if ("in_progress".equals(status)) {
+ inProgressCount++;
+ }
+ validated.add(new TodoItem(id, text.trim(), status));
+ }
+
+ if (inProgressCount > 1) {
+ return "Error: Only one task can be in_progress at a time";
+ }
+
+ this.items = validated;
+ return render();
+ }
+
+ /**
+ * 渲染当前 todo 列表为可读文本。
+ * TIP: 对应 Python {@code TodoManager.render()}，输出格式完全一致。
+ */
+ public String render() {
+ if (items.isEmpty()) {
+ return "No todos.";
+ }
+
+ StringBuilder sb = new StringBuilder();
+ long done = 0;
+ for (TodoItem item : items) {
+ String marker = switch (item.status()) {
+ case "in_progress" -> "[>]";
+ case "completed" -> "[x]";
+ default -> "[ ]";
+ };
+ sb.append(marker).append(" #").append(item.id()).append(": ").append(item.text()).append("\n");
+ if ("completed".equals(item.status())) done++;
+ }
+ sb.append("\n(").append(done).append("/").append(items.size()).append(" completed)");
+ return sb.toString();
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s04/S04Subagent.java b/src/main/java/io/mybatis/learn/s04/S04Subagent.java
new file mode 100644
index 0000000..87b995b
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s04/S04Subagent.java
@@ -0,0 +1,74 @@
+package io.mybatis.learn.s04;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * S04 - 子 Agent：上下文隔离，保护主 Agent 的思维清晰。
+ *
+ * 格言: "大任务拆小, 每个小任务干净的上下文"
+ *
+ * 核心模式:
+ *
+ * Parent agent Subagent
+ * +------------------+ +------------------+
+ * | messages=[...] | | messages=[] | ← fresh
+ * | | dispatch | |
+ * | tool: task | --------> | ChatClient.call |
+ * | prompt="..." | | execute tools |
+ * | | summary | |
+ * | result = "..." | <-------- | return last text |
+ * +------------------+ +------------------+
+ * |
+ * Parent context stays clean.
+ * Subagent context is discarded.
+ *
+ *
+ * TIP: 对应 Python {@code agents/s04_subagent.py}。
+ * Python 版手动创建空的 messages 列表实现隔离。
+ * Spring AI 通过创建独立的 {@link ChatClient} 实例实现相同效果 —— 更加自然。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S04Subagent implements CommandLineRunner {
+
+ private final ChatClient chatClient;
+
+ public S04Subagent(ChatModel chatModel) {
+ this.chatClient = ChatClient.builder(chatModel)
+ .defaultSystem("You are a coding agent at " + System.getProperty("user.dir")
+ + ". Use the task tool to delegate exploration or subtasks.")
+ .defaultTools(
+ new BashTool(),
+ new ReadFileTool(),
+ new WriteFileTool(),
+ new EditFileTool(),
+ new SubagentTool(chatModel) // 父 Agent 独有的 task 工具
+ )
+ .build();
+ }
+
+ @Override
+ public void run(String... args) {
+ AgentRunner.interactive("s04", userMessage ->
+ chatClient.prompt()
+ .user(userMessage)
+ .call()
+ .content()
+ );
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S04Subagent.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s04/SubagentTool.java b/src/main/java/io/mybatis/learn/s04/SubagentTool.java
new file mode 100644
index 0000000..4de201c
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s04/SubagentTool.java
@@ -0,0 +1,75 @@
+package io.mybatis.learn.s04;
+
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+/**
+ * 子 Agent 工具 —— 生成具有独立上下文的子 Agent 执行任务。
+ *
+ * TIP: 对应 Python {@code agents/s04_subagent.py} 中的 {@code run_subagent(prompt)} 函数。
+ * Python 版创建 {@code sub_messages = []} 实现上下文隔离，
+ * Spring AI 通过创建全新的 {@link ChatClient} 实例实现相同效果。
+ * 子 Agent 获得基础工具但没有 task 工具（防止递归生成）。
+ * 只有最终文本返回给父 Agent，子 Agent 的对话历史被完全丢弃。
+ */
+public class SubagentTool {
+ private static final Logger log = LoggerFactory.getLogger(SubagentTool.class);
+
+ private final ChatModel chatModel;
+ private final String workDir;
+
+ public SubagentTool(ChatModel chatModel) {
+ this.chatModel = chatModel;
+ this.workDir = System.getProperty("user.dir");
+ }
+
+ /**
+ * TIP: 对应 Python {@code run_subagent(prompt)}。
+ * Python 版在独立线程中运行子 Agent 的 while 循环（最多30次迭代）。
+ * Spring AI 的 ChatClient.call() 内部管理循环，无需手动限制迭代次数。
+ */
+ @Tool(description = "Spawn a subagent with fresh context. "
+ + "It shares the filesystem but not conversation history. "
+ + "Use for exploration or subtasks that might pollute the main context.")
+ public String task(
+ @ToolParam(description = "The task prompt for the subagent") String prompt,
+ @ToolParam(description = "Short description of the task", required = false) String description) {
+
+ String desc = (description != null && !description.isBlank()) ? description : "subtask";
+ if (log.isDebugEnabled()) {
+ System.out.printf("🤖 启动子代理「%s」: %s%n", desc, prompt.substring(0, Math.min(80, prompt.length())));
+ }
+
+ // 创建全新的 ChatClient —— 这就是"上下文隔离"的全部
+ // TIP: 对应 Python 的 sub_messages = [] —— 空的消息列表就是隔离
+ ChatClient subClient = ChatClient.builder(chatModel)
+ .defaultSystem("You are a coding subagent at " + workDir
+ + ". Complete the given task, then summarize your findings.")
+ .defaultTools(
+ new BashTool(),
+ new ReadFileTool(),
+ new WriteFileTool(),
+ new EditFileTool()
+ )
+ .build();
+
+ String result = subClient.prompt()
+ .user(prompt)
+ .call()
+ .content();
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 子代理「%s」完成，返回 %d 字符%n", desc, result == null ? 0 : result.length());
+ }
+
+ // 只返回最终文本，子 Agent 上下文被丢弃
+ return (result != null && !result.isBlank()) ? result : "(no summary)";
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s05/S05SkillLoading.java b/src/main/java/io/mybatis/learn/s05/S05SkillLoading.java
new file mode 100644
index 0000000..d055959
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s05/S05SkillLoading.java
@@ -0,0 +1,87 @@
+package io.mybatis.learn.s05;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.nio.file.Path;
+
+/**
+ * S05 - 技能加载：用到什么知识，临时加载什么知识。
+ *
+ * 格言: "用到什么知识, 临时加载什么知识"
+ *
+ * 两层注入:
+ *
+ * System prompt:
+ * +--------------------------------------+
+ * | You are a coding agent. |
+ * | Skills available: |
+ * | - pdf: Process PDF files... | ← Layer 1: 仅元数据 (~100 tokens)
+ * | - code-review: Review code... |
+ * +--------------------------------------+
+ *
+ * When model calls loadSkill("pdf"):
+ * +--------------------------------------+
+ * | tool_result: |
+ * | <skill> |
+ * | Full PDF processing instructions | ← Layer 2: 完整内容
+ * | Step 1: ... |
+ * | </skill> |
+ * +--------------------------------------+
+ *
+ *
+ * TIP: 对应 Python {@code agents/s05_skill_loading.py}。
+ * 核心洞察: "不要把所有东西塞进系统提示。按需加载。"
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S05SkillLoading implements CommandLineRunner {
+
+ private final ChatClient chatClient;
+
+ public S05SkillLoading(ChatModel chatModel) {
+ Path skillsDir = Path.of(System.getProperty("user.dir"), "skills");
+ SkillLoader skillLoader = new SkillLoader(skillsDir);
+
+ // Layer 1: 技能元数据注入系统提示
+ String system = "You are a coding agent at " + System.getProperty("user.dir") + ".\n"
+ + "Use loadSkill to access specialized knowledge before tackling unfamiliar topics.\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();
+ }
+
+ @Override
+ public void run(String... args) {
+ AgentRunner.interactive("s05", userMessage ->
+ chatClient.prompt()
+ .user(userMessage)
+ .call()
+ .content()
+ );
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S05SkillLoading.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s05/SkillLoader.java b/src/main/java/io/mybatis/learn/s05/SkillLoader.java
new file mode 100644
index 0000000..f51033b
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s05/SkillLoader.java
@@ -0,0 +1,118 @@
+package io.mybatis.learn.s05;
+
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+
+/**
+ * 技能加载器 —— 按需注入领域知识，避免系统提示膨胀。
+ *
+ * 两层技能注入系统:
+ *
+ * Layer 1 (cheap): 技能名称和描述注入系统提示 (~100 tokens/skill)
+ * Layer 2 (on demand): 完整技能内容通过 tool_result 返回
+ *
+ *
+ * TIP: 对应 Python {@code agents/s05_skill_loading.py} 中的 {@code SkillLoader} 类。
+ * 扫描 {@code skills//SKILL.md}，解析 YAML front matter 提取元数据。
+ */
+public class SkillLoader {
+
+ private static final Pattern FRONTMATTER_PATTERN =
+ Pattern.compile("^---\\n(.*?)\\n---\\n(.*)", Pattern.DOTALL);
+
+ private final Map skills = new LinkedHashMap<>();
+
+ record SkillInfo(Map meta, String body, String path) {
+ }
+
+ public SkillLoader(Path skillsDir) {
+ loadAll(skillsDir);
+ }
+
+ /**
+ * TIP: 对应 Python {@code SkillLoader._load_all()}。
+ * 递归扫描 skills 目录下所有 SKILL.md 文件。
+ */
+ private void loadAll(Path skillsDir) {
+ if (!Files.exists(skillsDir)) return;
+ try (Stream paths = Files.walk(skillsDir)) {
+ paths.filter(p -> p.getFileName().toString().equals("SKILL.md"))
+ .sorted()
+ .forEach(p -> {
+ try {
+ 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()));
+ } catch (IOException e) {
+ System.err.println("Warning: Failed to load skill from " + p + ": " + e.getMessage());
+ }
+ });
+ } catch (IOException e) {
+ System.err.println("Warning: Failed to scan skills directory: " + e.getMessage());
+ }
+ }
+
+ record ParsedSkill(Map meta, String body) {
+ }
+
+ /**
+ * 解析 YAML front matter。
+ * TIP: 对应 Python {@code SkillLoader._parse_frontmatter(text)}。
+ */
+ private ParsedSkill parseFrontmatter(String text) {
+ Matcher m = FRONTMATTER_PATTERN.matcher(text);
+ if (!m.matches()) {
+ return new ParsedSkill(Map.of(), text);
+ }
+ Map meta = new LinkedHashMap<>();
+ for (String line : m.group(1).strip().split("\n")) {
+ int colonIdx = line.indexOf(':');
+ if (colonIdx > 0) {
+ meta.put(line.substring(0, colonIdx).strip(), line.substring(colonIdx + 1).strip());
+ }
+ }
+ return new ParsedSkill(meta, m.group(2).strip());
+ }
+
+ /**
+ * Layer 1: 获取所有技能的简短描述（用于系统提示注入）。
+ * TIP: 对应 Python {@code SkillLoader.get_descriptions()}。
+ */
+ 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");
+ String tags = entry.getValue().meta().getOrDefault("tags", "");
+ sb.append(" - ").append(entry.getKey()).append(": ").append(desc);
+ if (!tags.isEmpty()) sb.append(" [").append(tags).append("]");
+ sb.append("\n");
+ }
+ return sb.toString().stripTrailing();
+ }
+
+ /**
+ * Layer 2: 加载指定技能的完整内容。
+ * TIP: 对应 Python {@code SkillLoader.get_content(name)}，
+ * 同时也是 {@code TOOL_HANDLERS["load_skill"]} 的处理函数。
+ */
+ @Tool(description = "Load specialized knowledge by name. "
+ + "Call this before tackling unfamiliar topics to get domain-specific instructions.")
+ 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 "\n" + skill.body() + "\n";
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s06/CompactTool.java b/src/main/java/io/mybatis/learn/s06/CompactTool.java
new file mode 100644
index 0000000..c108196
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s06/CompactTool.java
@@ -0,0 +1,27 @@
+package io.mybatis.learn.s06;
+
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+/**
+ * 手动压缩工具（Layer 3）。
+ *
+ * TIP: 对应 Python {@code TOOL_HANDLERS["compact"]}。
+ * 当 Agent 调用此工具时，触发上下文压缩。
+ */
+public class CompactTool {
+
+ private final ContextCompactor compactor;
+
+ public CompactTool(ContextCompactor compactor) {
+ this.compactor = compactor;
+ }
+
+ @Tool(description = "Trigger manual conversation compression to free up context space. "
+ + "Use when the conversation is getting long or you want to start fresh with a summary.")
+ public String compact(
+ @ToolParam(description = "What to focus on preserving in the summary", required = false) String focus) {
+ compactor.requestCompact();
+ return "Compression triggered. Context will be summarized.";
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s06/ContextCompactor.java b/src/main/java/io/mybatis/learn/s06/ContextCompactor.java
new file mode 100644
index 0000000..594d623
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s06/ContextCompactor.java
@@ -0,0 +1,154 @@
+package io.mybatis.learn.s06;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 上下文压缩器 —— 三层压缩管线，让 Agent 可以无限工作。
+ *
+ * TIP: 对应 Python {@code agents/s06_context_compact.py} 中的压缩函数。
+ *
+ * Layer 1 (Micro): 替换旧工具结果为占位符 "[Previous: used {tool}]"
+ * Layer 2 (Auto): tokens 超阈值时自动保存 transcript 并压缩
+ * Layer 3 (Manual): Agent 主动调用 compact 工具触发压缩
+ *
+ *
+ * 在 Spring AI 中，ChatClient 内部管理工具调用循环，无法直接在循环内插入压缩逻辑。
+ * 因此压缩在用户消息级别触发（每次用户输入前检查），效果等价。
+ * 如需更精细的循环内压缩，可实现自定义 {@code Advisor}。
+ */
+public class ContextCompactor {
+
+ private static final int TOKEN_THRESHOLD = 50000;
+ private static final int KEEP_RECENT = 3;
+
+ private final Path transcriptDir;
+ private final ChatModel chatModel;
+ private final ObjectMapper objectMapper = new ObjectMapper();
+
+ /**
+ * 对话历史（用户级别），在 ChatClient 调用之外维护。
+ */
+ private final List history = new ArrayList<>();
+ private boolean compactRequested = false;
+
+ public record ConversationTurn(String role, String content) {
+ }
+
+ public ContextCompactor(ChatModel chatModel, Path workDir) {
+ this.chatModel = chatModel;
+ this.transcriptDir = workDir.resolve(".transcripts");
+ }
+
+ /**
+ * 估算 token 数量。
+ * TIP: 对应 Python {@code estimate_tokens(messages)}，粗略估计 4 字符 ≈ 1 token。
+ */
+ public int estimateTokens() {
+ int chars = history.stream().mapToInt(t -> t.content().length()).sum();
+ return chars / 4;
+ }
+
+ /**
+ * 添加一轮对话记录。
+ */
+ public void addTurn(String role, String content) {
+ history.add(new ConversationTurn(role, content));
+ }
+
+ /**
+ * 获取对话历史的摘要（用于注入系统提示）。
+ */
+ public String getContextSummary() {
+ if (history.isEmpty()) return "";
+ StringBuilder sb = new StringBuilder("\n\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("");
+ return sb.toString();
+ }
+
+ /**
+ * 检查是否需要自动压缩（Layer 2）。
+ * TIP: 对应 Python 中 {@code if estimate_tokens(messages) > THRESHOLD} 的检查。
+ */
+ public boolean needsAutoCompact() {
+ return estimateTokens() > TOKEN_THRESHOLD;
+ }
+
+ /**
+ * 标记手动压缩请求（Layer 3）。
+ */
+ public void requestCompact() {
+ this.compactRequested = true;
+ }
+
+ public boolean isCompactRequested() {
+ boolean val = compactRequested;
+ compactRequested = false;
+ return val;
+ }
+
+ /**
+ * 执行压缩：保存 transcript 并用 LLM 生成摘要替换历史。
+ * TIP: 对应 Python {@code auto_compact(messages)}。
+ * 保存完整 transcript 到 .transcripts/ 目录，然后让 LLM 生成摘要。
+ */
+ public String compact() {
+ // 保存 transcript
+ try {
+ 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();
+ }
+ }
+ System.out.println("[transcript saved: " + transcriptPath + "]");
+
+ // 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 made. "
+ + "Be concise but preserve critical details.\n\n" + conversationText)
+ .call()
+ .content();
+
+ // 用摘要替换历史
+ history.clear();
+ history.add(new ConversationTurn("system",
+ "[Conversation compressed. Transcript: " + transcriptPath + "]\n\n" + summary));
+
+ return summary;
+ } catch (IOException e) {
+ return "Error during compaction: " + e.getMessage();
+ }
+ }
+
+ public List getHistory() {
+ return history;
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s06/S06ContextCompact.java b/src/main/java/io/mybatis/learn/s06/S06ContextCompact.java
new file mode 100644
index 0000000..ff1b277
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s06/S06ContextCompact.java
@@ -0,0 +1,108 @@
+package io.mybatis.learn.s06;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.nio.file.Path;
+
+/**
+ * S06 - 上下文压缩：三层压缩管线，让 Agent 永远不会"忘记"。
+ *
+ * 格言: "上下文总会满, 要有办法腾地方"
+ *
+ * 三层压缩:
+ *
+ * [Layer 1: micro_compact] 每轮调用前，替换旧工具结果为占位符
+ * |
+ * [Check: tokens > 50000?]
+ * | |
+ * no yes
+ * | |
+ * continue [Layer 2: auto_compact]
+ * 保存 transcript → LLM 生成摘要 → 替换 messages
+ * |
+ * [Layer 3: compact tool]
+ * Agent 主动调用 → 立即压缩
+ *
+ *
+ * TIP: 对应 Python {@code agents/s06_context_compact.py}。
+ * Python 版在工具循环内（每次 LLM 调用前）执行 micro_compact 和 auto_compact。
+ * Spring AI 的 ChatClient 自动管理工具循环，因此压缩在用户消息级别触发。
+ * 核心教学概念不变: Agent 可以策略性地"遗忘"，然后继续无限工作。
+ * 如需循环内精细压缩，可实现自定义 {@code CallAroundAdvisor}。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S06ContextCompact implements CommandLineRunner {
+
+ private final ChatModel chatModel;
+
+ public S06ContextCompact(ChatModel chatModel) {
+ this.chatModel = chatModel;
+ }
+
+ @Override
+ public void run(String... args) {
+ Path workDir = Path.of(System.getProperty("user.dir"));
+ ContextCompactor compactor = new ContextCompactor(chatModel, workDir);
+ CompactTool compactTool = new CompactTool(compactor);
+
+ String baseSystem = "You are a coding agent at " + workDir + ". Use tools to solve tasks.";
+
+ AgentRunner.interactive("s06", userMessage -> {
+ // Layer 2: 自动压缩检查（每次用户输入前）
+ if (compactor.needsAutoCompact()) {
+ System.out.println("[auto_compact triggered - " + compactor.estimateTokens() + " tokens]");
+ 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();
+
+ // 记录 Agent 回复
+ compactor.addTurn("assistant", response != null ? response : "");
+
+ // Layer 3: 手动压缩（如果 Agent 调用了 compact 工具）
+ if (compactor.isCompactRequested()) {
+ System.out.println("[manual compact triggered]");
+ String summary = compactor.compact();
+ System.out.println("[compressed to summary: " + summary.length() + " chars]");
+ }
+
+ return response;
+ });
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S06ContextCompact.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s07/S07TaskSystem.java b/src/main/java/io/mybatis/learn/s07/S07TaskSystem.java
new file mode 100644
index 0000000..ab2ff9c
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s07/S07TaskSystem.java
@@ -0,0 +1,63 @@
+package io.mybatis.learn.s07;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.nio.file.Path;
+
+/**
+ * S07 - 任务系统：大目标拆成小任务，排好序，记在磁盘上。
+ *
+ * 格言: "大目标要拆成小任务, 排好序, 记在磁盘上"
+ *
+ * TIP: 对应 Python {@code agents/s07_task_system.py}。
+ * 核心洞察: 任务状态持久化在磁盘（{@code .tasks/task_*.json}），
+ * 不受上下文压缩影响 —— 因为它在对话之外。
+ */
+@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 at " + System.getProperty("user.dir")
+ + ". Use task tools to plan and track work.")
+ .defaultTools(
+ new BashTool(),
+ new ReadFileTool(),
+ new WriteFileTool(),
+ new EditFileTool(),
+ taskManager
+ )
+ .build();
+ }
+
+ @Override
+ public void run(String... args) {
+ AgentRunner.interactive("s07", userMessage ->
+ chatClient.prompt()
+ .user(userMessage)
+ .call()
+ .content()
+ );
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S07TaskSystem.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s07/TaskManager.java b/src/main/java/io/mybatis/learn/s07/TaskManager.java
new file mode 100644
index 0000000..40c3bd5
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s07/TaskManager.java
@@ -0,0 +1,266 @@
+package io.mybatis.learn.s07;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.*;
+import java.util.stream.Stream;
+
+/**
+ * 持久化任务管理器 —— 任务状态存储在磁盘上，不受上下文压缩影响。
+ *
+ * TIP: 对应 Python {@code agents/s07_task_system.py} 中的 {@code TaskManager} 类。
+ * Python 使用 {@code json.loads/json.dumps}，Java 使用 Jackson {@code ObjectMapper}。
+ *
+ * .tasks/
+ * task_1.json {"id":1, "subject":"...", "status":"completed", ...}
+ * task_2.json {"id":2, "blockedBy":[1], "status":"pending", ...}
+ *
+ * 依赖解析:
+ * task 1 (complete) --> task 2 (blocked) --> task 3 (blocked)
+ * | ^
+ * +--- completing task 1 removes it from task 2's blockedBy
+ *
+ */
+public class TaskManager {
+ private static final Logger log = LoggerFactory.getLogger(TaskManager.class);
+
+ private static final ObjectMapper MAPPER = new ObjectMapper();
+ private static final List VALID_STATUSES = List.of("pending", "in_progress", "completed");
+
+ private final Path dir;
+ private int nextId;
+
+ public TaskManager(Path tasksDir) {
+ this.dir = tasksDir;
+ try {
+ Files.createDirectories(dir);
+ if (log.isDebugEnabled()) {
+ System.out.printf("🚀 任务目录就绪: %s%n", dir);
+ }
+ } catch (IOException e) {
+ log.error("创建任务目录失败: {}, error={}", dir, e.getMessage());
+ throw new RuntimeException("Cannot create tasks directory: " + e.getMessage(), e);
+ }
+ this.nextId = maxId() + 1;
+ log.info("TaskManager 初始化完成，nextId={}, dir={}", nextId, dir);
+ }
+
+ private int maxId() {
+ try (Stream files = Files.list(dir)) {
+ return files.filter(f -> f.getFileName().toString().matches("task_\\d+\\.json"))
+ .mapToInt(f -> {
+ String name = f.getFileName().toString();
+ return Integer.parseInt(name.substring(5, name.length() - 5));
+ })
+ .max().orElse(0);
+ } catch (IOException e) {
+ return 0;
+ }
+ }
+
+ private Map load(int taskId) throws IOException {
+ Path path = dir.resolve("task_" + taskId + ".json");
+ if (!Files.exists(path)) {
+ throw new IllegalArgumentException("Task " + taskId + " not found");
+ }
+ return MAPPER.readValue(Files.readString(path), new TypeReference<>() {
+ });
+ }
+
+ private void save(Map task) throws IOException {
+ Path path = dir.resolve("task_" + task.get("id") + ".json");
+ Files.writeString(path, MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(task));
+ }
+
+ @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) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("📋 创建任务: %s%n", subject);
+ }
+ try {
+ Map task = new LinkedHashMap<>();
+ task.put("id", nextId);
+ task.put("subject", subject);
+ task.put("description", description != null ? description : "");
+ task.put("status", "pending");
+ task.put("blockedBy", new ArrayList<>());
+ task.put("blocks", new ArrayList<>());
+ task.put("owner", "");
+ save(task);
+ nextId++;
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 任务 #%s 已创建 (nextId=%d)%n", task.get("id"), nextId);
+ }
+ return MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(task);
+ } catch (Exception e) {
+ log.warn("任务创建失败: subject={}, error={}", subject, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+
+ @Tool(description = "Get full details of a task by ID")
+ public String taskGet(@ToolParam(description = "Task ID") int taskId) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔍 查询任务 #%d%n", taskId);
+ }
+ try {
+ return MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(load(taskId));
+ } catch (Exception e) {
+ log.warn("查询任务详情失败: taskId={}, error={}", taskId, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+
+ /**
+ * TIP: 对应 Python {@code TaskManager.update()}。
+ * 当 status 变为 "completed" 时自动清除依赖（调用 clearDependency）。
+ * blockedBy/blocks 是双向关系：添加 blocks 时也更新被阻塞任务的 blockedBy。
+ */
+ @Tool(description = "Update a task's status or dependencies. "
+ + "Status: pending/in_progress/completed. "
+ + "Use addBlockedBy/addBlocks to manage dependency graph.")
+ @SuppressWarnings("unchecked")
+ 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 addBlockedBy,
+ @ToolParam(description = "Task IDs that this task blocks", required = false) List addBlocks) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔄 更新任务 #%d (status=%s, +blockedBy=%d, +blocks=%d)%n",
+ taskId, status, addBlockedBy == null ? 0 : addBlockedBy.size(), addBlocks == null ? 0 : addBlocks.size());
+ }
+ try {
+ Map task = load(taskId);
+
+ if (status != null) {
+ if (!VALID_STATUSES.contains(status)) {
+ log.warn("非法状态更新: taskId={}, status={}", taskId, status);
+ return "Error: Invalid status: " + status;
+ }
+ task.put("status", status);
+ if ("completed".equals(status)) {
+ clearDependency(taskId);
+ }
+ }
+
+ if (addBlockedBy != null && !addBlockedBy.isEmpty()) {
+ List current = (List) task.get("blockedBy");
+ Set merged = new LinkedHashSet<>(current);
+ merged.addAll(addBlockedBy);
+ task.put("blockedBy", new ArrayList<>(merged));
+ }
+
+ if (addBlocks != null && !addBlocks.isEmpty()) {
+ List current = (List) task.get("blocks");
+ Set merged = new LinkedHashSet<>(current);
+ merged.addAll(addBlocks);
+ task.put("blocks", new ArrayList<>(merged));
+ // 双向关系：更新被阻塞任务的 blockedBy
+ for (int blockedId : addBlocks) {
+ try {
+ Map blocked = load(blockedId);
+ List blockedBy = (List) blocked.get("blockedBy");
+ if (!blockedBy.contains(taskId)) {
+ blockedBy.add(taskId);
+ save(blocked);
+ }
+ } catch (Exception ignored) {
+ }
+ }
+ }
+
+ save(task);
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 任务 #%d 已更新%n", taskId);
+ }
+ return MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(task);
+ } catch (Exception e) {
+ log.warn("任务更新失败: taskId={}, error={}", taskId, e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+
+ /**
+ * TIP: 对应 Python {@code TaskManager._clear_dependency(completed_id)}。
+ * 完成任务后，从所有其他任务的 blockedBy 列表中移除该任务 ID。
+ */
+ @SuppressWarnings("unchecked")
+ private void clearDependency(int completedId) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("💭 清理依赖关系: 已完成任务 #%d%n", completedId);
+ }
+ try (Stream files = Files.list(dir)) {
+ files.filter(f -> f.getFileName().toString().matches("task_\\d+\\.json"))
+ .forEach(f -> {
+ try {
+ Map task = MAPPER.readValue(
+ Files.readString(f), new TypeReference<>() {
+ });
+ List blockedBy = (List) task.get("blockedBy");
+ if (blockedBy != null && blockedBy.remove(Integer.valueOf(completedId))) {
+ save(task);
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔗 已解除依赖: #%d ← %s%n", completedId, f.getFileName());
+ }
+ }
+ } catch (Exception ignored) {
+ }
+ });
+ } catch (IOException ignored) {
+ }
+ }
+
+ @Tool(description = "List all tasks with status summary")
+ public String taskList() {
+ if (log.isDebugEnabled()) {
+ System.out.printf("📋 列出所有任务%n");
+ }
+ try (Stream files = Files.list(dir)) {
+ List> tasks = files
+ .filter(f -> f.getFileName().toString().matches("task_\\d+\\.json"))
+ .sorted()
+ .map(f -> {
+ try {
+ return MAPPER.readValue(Files.readString(f),
+ new TypeReference>() {
+ });
+ } catch (IOException e) {
+ return null;
+ }
+ })
+ .filter(Objects::nonNull)
+ .toList();
+
+ if (tasks.isEmpty()) return "No tasks.";
+
+ StringBuilder sb = new StringBuilder();
+ for (Map t : tasks) {
+ String marker = switch (String.valueOf(t.get("status"))) {
+ case "in_progress" -> "[>]";
+ case "completed" -> "[x]";
+ default -> "[ ]";
+ };
+ sb.append(marker).append(" #").append(t.get("id")).append(": ").append(t.get("subject"));
+ List blockedBy = (List) t.get("blockedBy");
+ if (blockedBy != null && !blockedBy.isEmpty()) {
+ sb.append(" (blocked by: ").append(blockedBy).append(")");
+ }
+ sb.append("\n");
+ }
+ return sb.toString().stripTrailing();
+ } catch (IOException e) {
+ log.warn("列出任务失败: error={}", e.getMessage());
+ return "Error: " + e.getMessage();
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s08/BackgroundManager.java b/src/main/java/io/mybatis/learn/s08/BackgroundManager.java
new file mode 100644
index 0000000..26345af
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s08/BackgroundManager.java
@@ -0,0 +1,160 @@
+package io.mybatis.learn.s08;
+
+import io.mybatis.learn.core.AgentRunner;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.stream.Collectors;
+
+/**
+ * 后台任务管理器 —— 慢操作丢后台，Agent 继续想下一步。
+ *
+ * TIP: 对应 Python {@code agents/s08_background_tasks.py} 中的 {@code BackgroundManager} 类。
+ * Python 使用 {@code threading.Thread(daemon=True)}，
+ * Java 使用 {@link ExecutorService} + 虚拟线程（Java 21）。
+ *
+ * Main thread Background thread
+ * +-----------------+ +-----------------+
+ * | agent loop | | task executes |
+ * | ... | | ... |
+ * | [LLM call] <--+------- | notify(result) |
+ * | ^drain queue | +-----------------+
+ * +-----------------+
+ *
+ */
+public class BackgroundManager {
+ private static final Logger log = LoggerFactory.getLogger(BackgroundManager.class);
+
+ private static final int TIMEOUT_SECONDS = 300;
+
+ private final Map tasks = new ConcurrentHashMap<>();
+ private final List notificationQueue = new CopyOnWriteArrayList<>();
+ private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
+ private final String workDir;
+
+ record TaskInfo(String status, String result, String command) {
+ }
+
+ public record Notification(String taskId, String status, String command, String result) {
+ }
+
+ public BackgroundManager() {
+ this.workDir = System.getProperty("user.dir");
+ log.info("BackgroundManager 初始化，workDir={}", workDir);
+ }
+
+ @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));
+ log.info("后台任务已提交: taskId={}, command={}", taskId, command.substring(0, Math.min(80, command.length())));
+
+ executor.submit(() -> execute(taskId, command));
+
+ return "Background task " + taskId + " started: "
+ + command.substring(0, Math.min(80, command.length()));
+ }
+
+ private void execute(String taskId, String command) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("⏳ 后台任务 %s 开始执行%n", taskId);
+ }
+ String status;
+ String output;
+ try {
+ ProcessBuilder pb = new ProcessBuilder();
+ if (System.getProperty("os.name").toLowerCase().contains("win")) {
+ pb.command("cmd", "/c", command);
+ } else {
+ pb.command("sh", "-c", command);
+ }
+ pb.directory(new java.io.File(workDir));
+ pb.redirectErrorStream(true);
+
+ Process process = pb.start();
+ try (BufferedReader reader = new BufferedReader(
+ new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) {
+ output = reader.lines().collect(Collectors.joining("\n"));
+ }
+
+ boolean finished = process.waitFor(TIMEOUT_SECONDS, java.util.concurrent.TimeUnit.SECONDS);
+ if (!finished) {
+ process.destroyForcibly();
+ output = "Error: Timeout (" + TIMEOUT_SECONDS + "s)";
+ status = "timeout";
+ log.warn("后台任务超时: taskId={}, timeout={}s", taskId, TIMEOUT_SECONDS);
+ } else {
+ output = output.trim();
+ status = "completed";
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 后台任务 %s 执行完成%n", taskId);
+ }
+ }
+ } catch (Exception e) {
+ output = "Error: " + e.getMessage();
+ status = "error";
+ log.warn("后台任务执行异常: taskId={}, error={}", taskId, e.getMessage());
+ }
+
+ String finalOutput = AgentRunner.truncate(output.isEmpty() ? "(no output)" : output, 50000);
+ tasks.put(taskId, new TaskInfo(status, finalOutput, command));
+ log.info("后台任务状态更新: taskId={}, status={}", taskId, status);
+
+ notificationQueue.add(new Notification(
+ taskId, status,
+ command.substring(0, Math.min(80, command.length())),
+ finalOutput.substring(0, Math.min(500, finalOutput.length()))
+ ));
+ }
+
+ @Tool(description = "Check background task status. Omit taskId to list all tasks.")
+ public String checkBackground(
+ @ToolParam(description = "Task ID to check (omit for all)", required = false) String taskId) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔍 查询后台任务: %s%n", taskId);
+ }
+ if (taskId != null && !taskId.isBlank()) {
+ TaskInfo t = tasks.get(taskId);
+ if (t == null) return "Error: Unknown task " + taskId;
+ return "[" + t.status() + "] "
+ + t.command().substring(0, Math.min(60, t.command().length())) + "\n"
+ + (t.result() != null ? t.result() : "(running)");
+ }
+ if (tasks.isEmpty()) return "No background tasks.";
+ StringBuilder sb = new StringBuilder();
+ tasks.forEach((tid, t) ->
+ sb.append(tid).append(": [").append(t.status()).append("] ")
+ .append(t.command(), 0, Math.min(60, t.command().length()))
+ .append("\n"));
+ return sb.toString().stripTrailing();
+ }
+
+ /**
+ * 排空通知队列，返回所有已完成的后台任务结果。
+ * TIP: 对应 Python {@code BackgroundManager.drain_notifications()}。
+ */
+ public List drainNotifications() {
+ List drained = new ArrayList<>(notificationQueue);
+ notificationQueue.clear();
+ if (!drained.isEmpty()) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("📬 排空通知队列 (%d 条)%n", drained.size());
+ }
+ }
+ return drained;
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s08/S08BackgroundTasks.java b/src/main/java/io/mybatis/learn/s08/S08BackgroundTasks.java
new file mode 100644
index 0000000..ac9e4dd
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s08/S08BackgroundTasks.java
@@ -0,0 +1,79 @@
+package io.mybatis.learn.s08;
+
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.util.stream.Collectors;
+
+/**
+ * S08 - 后台任务：慢操作丢后台，Agent 继续想下一步。
+ *
+ * 格言: "慢操作丢后台, agent 继续想下一步"
+ *
+ * TIP: 对应 Python {@code agents/s08_background_tasks.py}。
+ * Python 在每次 LLM 调用前 drain 通知队列并注入 {@code }。
+ * Spring AI 的 ChatClient 管理内部循环，因此改为在每次用户输入时
+ * drain 通知并注入系统提示。核心概念不变: fire and forget。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S08BackgroundTasks implements CommandLineRunner {
+
+ private final ChatModel chatModel;
+
+ public S08BackgroundTasks(ChatModel chatModel) {
+ this.chatModel = chatModel;
+ }
+
+ @Override
+ public void run(String... args) {
+ BackgroundManager bgManager = new BackgroundManager();
+ String workDir = System.getProperty("user.dir");
+
+ 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\n" + notifText + "\n";
+ System.out.println("[Background tasks completed: " + notifs.size() + "]");
+ }
+
+ String system = "You are a coding agent at " + workDir
+ + ". 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();
+ });
+ }
+
+ public static void main(String[] args) {
+ SpringApplication app = new SpringApplication(S08BackgroundTasks.class);
+ app.setWebApplicationType(WebApplicationType.NONE);
+ app.run(args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s09/S09AgentTeams.java b/src/main/java/io/mybatis/learn/s09/S09AgentTeams.java
new file mode 100644
index 0000000..6f624c0
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s09/S09AgentTeams.java
@@ -0,0 +1,137 @@
+package io.mybatis.learn.s09;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.team.MessageBus;
+import io.mybatis.learn.core.tools.*;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * S09 - Agent Teams：持久化命名agent + JSONL收件箱通信
+ *
+ * TIPS: 对应Python s09_agent_teams.py。
+ * Python用 TOOL_HANDLERS 字典 + 手动while循环分发9个工具；
+ * Java用 ChatClient + @Tool 自动处理，Lead工具封装在 LeadTools 内部类。
+ *
+ * 核心概念：
+ * Subagent (s04): spawn → execute → return summary → destroyed
+ * Teammate (s09): spawn → work → idle → work → ... → shutdown
+ *
+ * 关键差异：Python队友在每次LLM调用前检查收件箱（s09第174行），
+ * Java队友在每次完整工具链（call()）之间检查。这是Spring AI的自然适配。
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S09AgentTeams implements CommandLineRunner {
+
+ @Autowired
+ private ChatModel chatModel;
+
+ @Override
+ public void run(String... args) throws Exception {
+ Path workDir = Path.of(System.getProperty("user.dir"));
+ Path teamDir = workDir.resolve(".team");
+
+ MessageBus bus = new MessageBus(teamDir.resolve("inbox"));
+ TeammateManager team = new TeammateManager(chatModel, bus, teamDir);
+ LeadTools leadTools = new LeadTools(bus, team);
+ ObjectMapper mapper = new ObjectMapper();
+
+ String systemPrompt = "You are a team lead at " + workDir
+ + ". Spawn teammates and communicate via inboxes.";
+
+ ChatClient chatClient = ChatClient.builder(chatModel)
+ .defaultSystem(systemPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(), leadTools)
+ .build();
+
+ AgentRunner.interactive("s09", input -> {
+ if ("/team".equals(input)) return team.listAll();
+ if ("/inbox".equals(input)) {
+ try {
+ return mapper.writeValueAsString(bus.readInbox("lead"));
+ } catch (Exception e) {
+ return "Error: " + e.getMessage();
+ }
+ }
+
+ // 每次LLM调用前检查lead收件箱
+ var inbox = bus.readInbox("lead");
+ String fullInput = input;
+ if (!inbox.isEmpty()) {
+ try {
+ fullInput = "" + mapper.writeValueAsString(inbox)
+ + "\n\n" + input;
+ } catch (Exception e) { /* ignore */ }
+ }
+
+ return chatClient.prompt(fullInput).call().content();
+ });
+ }
+
+ /**
+ * Lead专用工具集（5个团队管理工具）
+ *
+ * TIPS: 对应Python TOOL_HANDLERS中的5个lead工具（s09第310-319行）。
+ * Python用lambda + 字典映射；Java用@Tool注解的方法。
+ */
+ public static class LeadTools {
+ private final MessageBus bus;
+ private final TeammateManager team;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public LeadTools(MessageBus bus, TeammateManager team) {
+ this.bus = bus;
+ this.team = team;
+ }
+
+ @Tool(description = "Spawn a persistent teammate that runs in its own thread")
+ public String spawnTeammate(
+ @ToolParam(description = "Teammate name") String name,
+ @ToolParam(description = "Role description") String role,
+ @ToolParam(description = "Initial task prompt") String prompt) {
+ return team.spawn(name, role, prompt);
+ }
+
+ @Tool(description = "List all teammates with name, role, status")
+ public String listTeammates() {
+ return team.listAll();
+ }
+
+ @Tool(description = "Send a message to a teammate's inbox")
+ public String sendMessage(
+ @ToolParam(description = "Recipient teammate name") String to,
+ @ToolParam(description = "Message content") String content) {
+ return bus.send("lead", to, content);
+ }
+
+ @Tool(description = "Read and drain the lead's inbox")
+ public String readInbox() {
+ try {
+ return mapper.writeValueAsString(bus.readInbox("lead"));
+ } catch (Exception e) {
+ return "[]";
+ }
+ }
+
+ @Tool(description = "Send a message to all teammates")
+ public String broadcast(
+ @ToolParam(description = "Message content") String content) {
+ return bus.broadcast("lead", content, team.memberNames());
+ }
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(S09AgentTeams.class, args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s09/TeammateManager.java b/src/main/java/io/mybatis/learn/s09/TeammateManager.java
new file mode 100644
index 0000000..ad5f115
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s09/TeammateManager.java
@@ -0,0 +1,240 @@
+package io.mybatis.learn.s09;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.team.MessageBus;
+import io.mybatis.learn.core.tools.BashTool;
+import io.mybatis.learn.core.tools.EditFileTool;
+import io.mybatis.learn.core.tools.ReadFileTool;
+import io.mybatis.learn.core.tools.WriteFileTool;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * 团队管理器 - 持久化命名agent，通过JSONL收件箱通信
+ *
+ * TIPS: 对应Python TeammateManager类（s09第124-248行）。
+ * Python用 threading.Thread 创建队友线程，Java用虚拟线程（Thread.startVirtualThread）。
+ * Python队友手动执行 while/tool_use 循环 + _exec分发；
+ * Java队友用 ChatClient + @Tool 自动处理工具循环（一次 call() = 完整工具链）。
+ * 每次 call() 等价于Python的「循环直到 stop_reason != tool_use」。
+ */
+public class TeammateManager {
+ private static final Logger log = LoggerFactory.getLogger(TeammateManager.class);
+
+ private final ChatModel chatModel;
+ private final MessageBus bus;
+ private final Path configPath;
+ private final ObjectMapper mapper = new ObjectMapper();
+ private Map config;
+ private final Map threads = new ConcurrentHashMap<>();
+
+ public TeammateManager(ChatModel chatModel, MessageBus bus, Path teamDir) {
+ this.chatModel = chatModel;
+ this.bus = bus;
+ this.configPath = teamDir.resolve("config.json");
+ try {
+ Files.createDirectories(teamDir);
+ } catch (IOException e) {
+ log.error("创建团队目录失败: {}, error={}", teamDir, e.getMessage());
+ throw new RuntimeException(e);
+ }
+ this.config = loadConfig();
+ log.info("TeammateManager 初始化完成，configPath={}", configPath);
+ }
+
+ // ---- 配置持久化 ----
+
+ @SuppressWarnings("unchecked")
+ private Map loadConfig() {
+ if (Files.exists(configPath)) {
+ try {
+ if (log.isDebugEnabled()) {
+ System.out.printf("💭 加载团队配置: %s%n", configPath);
+ }
+ return mapper.readValue(configPath.toFile(), Map.class);
+ } catch (IOException e) { /* ignore */ }
+ }
+ Map cfg = new LinkedHashMap<>();
+ cfg.put("team_name", "default");
+ cfg.put("members", new ArrayList<>());
+ return cfg;
+ }
+
+ private synchronized void saveConfig() {
+ try {
+ mapper.writerWithDefaultPrettyPrinter().writeValue(configPath.toFile(), config);
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 团队配置已保存: %s%n", configPath);
+ }
+ } catch (IOException e) {
+ log.warn("保存团队配置失败: error={}", e.getMessage());
+ System.err.println("Error saving config: " + e.getMessage());
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private Map findMember(String name) {
+ List> members = (List>) config.get("members");
+ for (Map m : members) {
+ if (name.equals(m.get("name"))) return m;
+ }
+ return null;
+ }
+
+ protected synchronized void setStatus(String name, String status) {
+ Map member = findMember(name);
+ if (member != null) {
+ member.put("status", status);
+ saveConfig();
+ }
+ }
+
+ // ---- Spawn ----
+
+ @SuppressWarnings("unchecked")
+ public synchronized String spawn(String name, String role, String prompt) {
+ log.info("请求启动队友: name={}, role={}", name, role);
+ Map member = findMember(name);
+ if (member != null) {
+ String status = (String) member.get("status");
+ if (!"idle".equals(status) && !"shutdown".equals(status)) {
+ return "Error: '" + name + "' is currently " + status;
+ }
+ member.put("status", "working");
+ member.put("role", role);
+ } else {
+ member = new LinkedHashMap<>();
+ member.put("name", name);
+ member.put("role", role);
+ member.put("status", "working");
+ ((List>) config.get("members")).add(member);
+ }
+ saveConfig();
+
+ Thread thread = Thread.startVirtualThread(() -> teammateLoop(name, role, prompt));
+ threads.put(name, thread);
+ log.info("队友已启动: name={}, role={}", name, role);
+ return "Spawned '" + name + "' (role: " + role + ")";
+ }
+
+ // ---- 队友循环 ----
+
+ /**
+ * TIPS: Python队友循环（s09第166-204行）在range(50)内逐次调用LLM。
+ * Java用ChatClient.prompt().call()一次完成整个工具链，
+ * 等价于Python循环到 stop_reason != "tool_use" 为止。
+ * 收件箱检查在每次call()之间进行（而非Python的每次LLM调用之间）。
+ */
+ protected void teammateLoop(String name, String role, String initialPrompt) {
+ log.info("队友工作循环开始: name={}, role={}", name, role);
+ String workDir = System.getProperty("user.dir");
+ String sysPrompt = String.format(
+ "You are '%s', role: %s, at %s. "
+ + "Use send_message to communicate. Complete your task.",
+ name, role, workDir);
+
+ var messageTool = new TeammateMessageTool(bus, name);
+ ChatClient client = ChatClient.builder(chatModel)
+ .defaultSystem(sysPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(), messageTool)
+ .build();
+
+ try {
+ // 初始工作
+ String response = client.prompt(initialPrompt).call().content();
+ System.out.println(" [" + name + "] " + AgentRunner.truncate(response, 120));
+ if (log.isDebugEnabled()) {
+ System.out.printf("✅ 队友「%s」初始响应完成%n", name);
+ }
+
+ // 等待收件箱消息（每2秒检查一次，最多50轮）
+ for (int round = 0; round < 50; round++) {
+ Thread.sleep(2000);
+ var inbox = bus.readInbox(name);
+ if (inbox.isEmpty()) break;
+ if (log.isDebugEnabled()) {
+ System.out.printf("📨 队友「%s」收到 %d 条收件箱消息%n", name, inbox.size());
+ }
+
+ String inboxJson = mapper.writeValueAsString(inbox);
+ response = client.prompt("" + inboxJson + "").call().content();
+ System.out.println(" [" + name + "] " + AgentRunner.truncate(response, 120));
+ }
+ } catch (Exception e) {
+ log.warn("队友执行异常: name={}, error={}", name, e.getMessage());
+ System.err.println(" [" + name + "] Error: " + e.getMessage());
+ }
+
+ setStatus(name, "idle");
+ log.info("队友工作循环结束: name={}", name);
+ }
+
+ // ---- 查询 ----
+
+ @SuppressWarnings("unchecked")
+ public String listAll() {
+ List> members = (List>) config.get("members");
+ if (members.isEmpty()) return "No teammates.";
+ StringBuilder sb = new StringBuilder("Team: " + config.get("team_name"));
+ for (Map m : members) {
+ sb.append("\n ").append(m.get("name"))
+ .append(" (").append(m.get("role")).append("): ").append(m.get("status"));
+ }
+ return sb.toString();
+ }
+
+ @SuppressWarnings("unchecked")
+ public List memberNames() {
+ List> members = (List>) config.get("members");
+ return members.stream().map(m -> (String) m.get("name")).toList();
+ }
+
+ // ---- 队友专用消息工具（参数化sender名称） ----
+
+ /**
+ * TIPS: Python队友通过 _exec() 分发工具调用（s09第206-220行），
+ * send_message和read_inbox使用队友自己的名字作为sender。
+ * Java用参数化工具类：构造时绑定sender，@Tool方法自动注入。
+ */
+ public static class TeammateMessageTool {
+ private final MessageBus bus;
+ private final String name;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public TeammateMessageTool(MessageBus bus, String name) {
+ this.bus = bus;
+ this.name = name;
+ }
+
+ @Tool(description = "Send message to a teammate")
+ public String sendMessage(
+ @ToolParam(description = "Recipient name") String to,
+ @ToolParam(description = "Message content") String content) {
+ return bus.send(name, to, content);
+ }
+
+ @Tool(description = "Read and drain your inbox")
+ public String readInbox() {
+ try {
+ return mapper.writeValueAsString(bus.readInbox(name));
+ } catch (Exception e) {
+ return "[]";
+ }
+ }
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s10/ProtocolTracker.java b/src/main/java/io/mybatis/learn/s10/ProtocolTracker.java
new file mode 100644
index 0000000..6a9b369
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s10/ProtocolTracker.java
@@ -0,0 +1,107 @@
+package io.mybatis.learn.s10;
+
+import io.mybatis.learn.core.team.MessageBus;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * 协议追踪器 - 关闭协议 + 计划审批协议（请求-响应FSM）
+ *
+ * TIPS: 对应Python全局变量 shutdown_requests、plan_requests 和 _tracker_lock（s10第82-84行）。
+ * Python用字典 + threading.Lock；Java用 ConcurrentHashMap 天然线程安全。
+ * 两种协议使用相同的 request_id 关联模式：pending → approved | rejected。
+ */
+public class ProtocolTracker {
+ private static final Logger log = LoggerFactory.getLogger(ProtocolTracker.class);
+
+ // {request_id: {"target": name, "status": "pending|approved|rejected"}}
+ private final ConcurrentHashMap> shutdownRequests = new ConcurrentHashMap<>();
+ // {request_id: {"from": name, "plan": text, "status": "pending|approved|rejected"}}
+ private final ConcurrentHashMap> planRequests = new ConcurrentHashMap<>();
+ private final MessageBus bus;
+
+ public ProtocolTracker(MessageBus bus) {
+ this.bus = bus;
+ }
+
+ // ---- 关闭协议（Lead端） ----
+
+ /**
+ * Lead发起关闭请求 → 生成request_id → 发送shutdown_request消息
+ */
+ public String handleShutdownRequest(String teammate) {
+ String reqId = UUID.randomUUID().toString().substring(0, 8);
+ shutdownRequests.put(reqId, new ConcurrentHashMap<>(Map.of(
+ "target", teammate, "status", "pending")));
+ log.info("发起关闭请求: requestId={}, target={}", reqId, teammate);
+ bus.send("lead", teammate, "Please shut down gracefully.",
+ "shutdown_request", Map.of("request_id", reqId));
+ return "Shutdown request " + reqId + " sent to '" + teammate + "' (status: pending)";
+ }
+
+ /**
+ * Lead查询关闭状态
+ */
+ public String checkShutdownStatus(String requestId) {
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔍 查询关闭请求状态: %s%n", requestId);
+ }
+ var req = shutdownRequests.get(requestId);
+ return req != null ? req.toString() : "{\"error\": \"not found\"}";
+ }
+
+ // ---- 关闭协议（Teammate端） ----
+
+ /**
+ * Teammate响应关闭请求 → 更新追踪器 → 发送shutdown_response消息
+ */
+ 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");
+ }
+ log.info("响应关闭请求: sender={}, requestId={}, approve={}", sender, requestId, approve);
+ bus.send(sender, "lead", reason != null ? reason : "",
+ "shutdown_response", Map.of("request_id", requestId, "approve", approve));
+ return "Shutdown " + (approve ? "approved" : "rejected");
+ }
+
+ // ---- 计划审批协议（Teammate端） ----
+
+ /**
+ * Teammate提交计划 → 生成request_id → 发送plan_approval_response消息
+ */
+ public String submitPlan(String sender, String planText) {
+ String reqId = UUID.randomUUID().toString().substring(0, 8);
+ planRequests.put(reqId, new ConcurrentHashMap<>(Map.of(
+ "from", sender, "plan", planText, "status", "pending")));
+ log.info("提交计划审批: requestId={}, sender={}", reqId, sender);
+ bus.send(sender, "lead", planText, "plan_approval_response",
+ Map.of("request_id", reqId, "plan", planText));
+ return "Plan submitted (request_id=" + reqId + "). Waiting for lead approval.";
+ }
+
+ // ---- 计划审批协议（Lead端） ----
+
+ /**
+ * Lead审批计划 → 更新追踪器 → 发送plan_approval_response消息
+ */
+ public String reviewPlan(String requestId, boolean approve, String feedback) {
+ var req = planRequests.get(requestId);
+ if (req == null) {
+ log.warn("审批计划失败，请求不存在: requestId={}", requestId);
+ return "Error: Unknown plan request_id '" + requestId + "'";
+ }
+ req.put("status", approve ? "approved" : "rejected");
+ log.info("审批计划: requestId={}, from={}, approve={}", requestId, req.get("from"), approve);
+ 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") + "'";
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s10/S10TeamProtocols.java b/src/main/java/io/mybatis/learn/s10/S10TeamProtocols.java
new file mode 100644
index 0000000..4d82805
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s10/S10TeamProtocols.java
@@ -0,0 +1,315 @@
+package io.mybatis.learn.s10;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.team.MessageBus;
+import io.mybatis.learn.core.tools.*;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * S10 - Team Protocols：关闭协议 + 计划审批协议
+ *
+ * TIPS: 对应Python s10_team_protocols.py。
+ * 在S09基础上新增3个Lead工具和2个Teammate工具。
+ *
+ * 关闭协议FSM: pending → approved | rejected
+ * Lead调用 shutdown_request → Teammate收到 shutdown_request 消息
+ * → Teammate调用 shutdown_response → Lead收件箱收到响应
+ *
+ * 计划审批FSM: pending → approved | rejected
+ * Teammate调用 plan_approval → Lead收件箱收到计划
+ * → Lead调用 plan_approval(review) → Teammate收到审批结果
+ *
+ * 关键洞察："Same request_id correlation pattern, two domains."
+ */
+@SpringBootApplication(scanBasePackages = "io.mybatis.learn.core")
+public class S10TeamProtocols implements CommandLineRunner {
+
+ @Autowired
+ private ChatModel chatModel;
+
+ @Override
+ public void run(String... args) throws Exception {
+ Path workDir = Path.of(System.getProperty("user.dir"));
+ Path teamDir = workDir.resolve(".team");
+
+ MessageBus bus = new MessageBus(teamDir.resolve("inbox"));
+ ProtocolTracker tracker = new ProtocolTracker(bus);
+ S10TeammateManager team = new S10TeammateManager(chatModel, bus, tracker, teamDir);
+ S10LeadTools leadTools = new S10LeadTools(bus, team, tracker);
+ ObjectMapper mapper = new ObjectMapper();
+
+ String systemPrompt = "You are a team lead at " + workDir
+ + ". Manage teammates with shutdown and plan approval protocols.";
+
+ ChatClient chatClient = ChatClient.builder(chatModel)
+ .defaultSystem(systemPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(), leadTools)
+ .build();
+
+ AgentRunner.interactive("s10", input -> {
+ if ("/team".equals(input)) return team.listAll();
+ if ("/inbox".equals(input)) {
+ try { return mapper.writeValueAsString(bus.readInbox("lead")); }
+ catch (Exception e) { return "Error: " + e.getMessage(); }
+ }
+
+ var inbox = bus.readInbox("lead");
+ String fullInput = input;
+ if (!inbox.isEmpty()) {
+ try {
+ fullInput = "" + mapper.writeValueAsString(inbox)
+ + "\n\n" + input;
+ } catch (Exception e) { /* ignore */ }
+ }
+
+ return chatClient.prompt(fullInput).call().content();
+ });
+ }
+
+ // ---- 队友管理器（增加协议处理） ----
+
+ /**
+ * TIPS: 对应Python s10第134-290行的TeammateManager。
+ * 相比S09增加了：
+ * 1. should_exit标志 - 队友批准关闭后退出循环
+ * 2. shutdown_response工具 - 更新tracker + 发送响应消息
+ * 3. plan_approval工具 - 提交计划到lead收件箱
+ */
+ static class S10TeammateManager {
+ private final ChatModel chatModel;
+ private final MessageBus bus;
+ private final ProtocolTracker tracker;
+ private final Path configPath;
+ private final ObjectMapper mapper = new ObjectMapper();
+ private Map config;
+
+ S10TeammateManager(ChatModel chatModel, MessageBus bus,
+ ProtocolTracker tracker, Path teamDir) {
+ this.chatModel = chatModel;
+ this.bus = bus;
+ this.tracker = tracker;
+ this.configPath = teamDir.resolve("config.json");
+ try { Files.createDirectories(teamDir); } catch (IOException e) { throw new RuntimeException(e); }
+ this.config = loadConfig();
+ }
+
+ @SuppressWarnings("unchecked")
+ private Map loadConfig() {
+ if (Files.exists(configPath)) {
+ try { return mapper.readValue(configPath.toFile(), Map.class); } catch (IOException e) { /* ignore */ }
+ }
+ Map cfg = new LinkedHashMap<>();
+ cfg.put("team_name", "default");
+ cfg.put("members", new ArrayList<>());
+ return cfg;
+ }
+
+ private synchronized void saveConfig() {
+ try { mapper.writerWithDefaultPrettyPrinter().writeValue(configPath.toFile(), config); }
+ catch (IOException e) { /* ignore */ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private Map findMember(String name) {
+ for (Map m : (List>) config.get("members")) {
+ if (name.equals(m.get("name"))) return m;
+ }
+ return null;
+ }
+
+ private synchronized void setStatus(String name, String status) {
+ Map member = findMember(name);
+ if (member != null) { member.put("status", status); saveConfig(); }
+ }
+
+ @SuppressWarnings("unchecked")
+ public synchronized String spawn(String name, String role, String prompt) {
+ Map member = findMember(name);
+ if (member != null) {
+ String status = (String) member.get("status");
+ if (!"idle".equals(status) && !"shutdown".equals(status))
+ return "Error: '" + name + "' is currently " + status;
+ member.put("status", "working");
+ member.put("role", role);
+ } else {
+ member = new LinkedHashMap<>();
+ member.put("name", name);
+ member.put("role", role);
+ member.put("status", "working");
+ ((List>) config.get("members")).add(member);
+ }
+ saveConfig();
+ Thread.startVirtualThread(() -> teammateLoop(name, role, prompt));
+ return "Spawned '" + name + "' (role: " + role + ")";
+ }
+
+ private void teammateLoop(String name, String role, String initialPrompt) {
+ String workDir = System.getProperty("user.dir");
+ String sysPrompt = String.format(
+ "You are '%s', role: %s, at %s. "
+ + "Submit plans via plan_approval before major work. "
+ + "Respond to shutdown_request with shutdown_response.",
+ name, role, workDir);
+
+ // 队友协议工具
+ var protocolTool = new TeammateProtocolTool(bus, tracker, name);
+ var messageTool = new io.mybatis.learn.s09.TeammateManager.TeammateMessageTool(bus, name);
+
+ ChatClient client = ChatClient.builder(chatModel)
+ .defaultSystem(sysPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(),
+ messageTool, protocolTool)
+ .build();
+
+ try {
+ client.prompt(initialPrompt).call().content();
+
+ for (int round = 0; round < 50; round++) {
+ Thread.sleep(2000);
+ var inbox = bus.readInbox(name);
+ if (inbox.isEmpty()) break;
+
+ // 检查是否有关闭请求
+ boolean hasShutdown = inbox.stream()
+ .anyMatch(m -> "shutdown_request".equals(m.get("type")));
+
+ String inboxJson = mapper.writeValueAsString(inbox);
+ client.prompt("" + inboxJson + "").call().content();
+
+ if (hasShutdown) {
+ setStatus(name, "shutdown");
+ return;
+ }
+ }
+ } catch (Exception e) {
+ System.err.println(" [" + name + "] Error: " + e.getMessage());
+ }
+
+ setStatus(name, "idle");
+ }
+
+ @SuppressWarnings("unchecked")
+ public String listAll() {
+ List> members = (List>) config.get("members");
+ if (members.isEmpty()) return "No teammates.";
+ StringBuilder sb = new StringBuilder("Team: " + config.get("team_name"));
+ for (Map m : members)
+ sb.append("\n ").append(m.get("name"))
+ .append(" (").append(m.get("role")).append("): ").append(m.get("status"));
+ return sb.toString();
+ }
+
+ @SuppressWarnings("unchecked")
+ public List memberNames() {
+ return ((List>) config.get("members")).stream()
+ .map(m -> (String) m.get("name")).toList();
+ }
+ }
+
+ // ---- 队友协议工具 ----
+
+ public static class TeammateProtocolTool {
+ private final MessageBus bus;
+ private final ProtocolTracker tracker;
+ private final String name;
+
+ public TeammateProtocolTool(MessageBus bus, ProtocolTracker tracker, String name) {
+ this.bus = bus;
+ this.tracker = tracker;
+ this.name = name;
+ }
+
+ @Tool(description = "Respond to a shutdown request. Approve to shut down, reject to keep working.")
+ public String shutdownResponse(
+ @ToolParam(description = "The request_id from shutdown request") String requestId,
+ @ToolParam(description = "true to approve shutdown") boolean approve,
+ @ToolParam(description = "Reason for decision") String reason) {
+ return tracker.respondToShutdown(name, requestId, approve, reason);
+ }
+
+ @Tool(description = "Submit a plan for lead approval before major work")
+ public String planApproval(
+ @ToolParam(description = "Plan text to submit") String plan) {
+ return tracker.submitPlan(name, plan);
+ }
+ }
+
+ // ---- Lead工具集（12个工具 = S09的9个 + 3个协议工具） ----
+
+ public static class S10LeadTools {
+ private final MessageBus bus;
+ private final S10TeammateManager team;
+ private final ProtocolTracker tracker;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public S10LeadTools(MessageBus bus, S10TeammateManager team, ProtocolTracker tracker) {
+ this.bus = bus;
+ this.team = team;
+ this.tracker = tracker;
+ }
+
+ @Tool(description = "Spawn a persistent teammate")
+ public String spawnTeammate(String name, String role, String prompt) {
+ return team.spawn(name, role, prompt);
+ }
+
+ @Tool(description = "List all teammates")
+ public String listTeammates() { return team.listAll(); }
+
+ @Tool(description = "Send a message to a teammate's inbox")
+ public String sendMessage(String to, String content) {
+ return bus.send("lead", to, content);
+ }
+
+ @Tool(description = "Read and drain the lead's inbox")
+ public String readInbox() {
+ try { return mapper.writeValueAsString(bus.readInbox("lead")); }
+ catch (Exception e) { return "[]"; }
+ }
+
+ @Tool(description = "Broadcast message to all teammates")
+ public String broadcast(String content) {
+ return bus.broadcast("lead", content, team.memberNames());
+ }
+
+ @Tool(description = "Request a teammate to shut down gracefully. Returns request_id for tracking.")
+ public String shutdownRequest(
+ @ToolParam(description = "Teammate name to shut down") String teammate) {
+ return tracker.handleShutdownRequest(teammate);
+ }
+
+ @Tool(description = "Check shutdown request status by request_id")
+ public String shutdownResponse(
+ @ToolParam(description = "The request_id to check") String requestId) {
+ return tracker.checkShutdownStatus(requestId);
+ }
+
+ @Tool(description = "Approve or reject a teammate's plan")
+ public String planApproval(
+ @ToolParam(description = "Plan request_id") String requestId,
+ @ToolParam(description = "true to approve") boolean approve,
+ @ToolParam(description = "Feedback text") String feedback) {
+ return tracker.reviewPlan(requestId, approve, feedback);
+ }
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(S10TeamProtocols.class, args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s11/S11AutonomousAgents.java b/src/main/java/io/mybatis/learn/s11/S11AutonomousAgents.java
new file mode 100644
index 0000000..763eaf7
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s11/S11AutonomousAgents.java
@@ -0,0 +1,413 @@
+package io.mybatis.learn.s11;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.mybatis.learn.core.AgentRunner;
+import io.mybatis.learn.core.team.MessageBus;
+import io.mybatis.learn.core.tools.*;
+import io.mybatis.learn.s10.ProtocolTracker;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.tool.annotation.Tool;
+import org.springframework.ai.tool.annotation.ToolParam;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.*;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * S11 - Autonomous Agents：自主agent + 空闲轮询 + 任务认领
+ *
+ * TIPS: 对应Python s11_autonomous_agents.py。
+ * 在S10基础上新增：
+ * 1. idle工具 - 队友主动进入空闲阶段
+ * 2. 空闲轮询 - 每5秒检查收件箱和任务板
+ * 3. 自动认领 - 发现未分配任务时自动claim
+ * 4. 身份重注入 - 上下文压缩后恢复身份信息
+ *
+ * 队友生命周期：
+ * spawn → WORK → idle → IDLE POLL → (message|task) → WORK → ...
+ * IDLE超时(60s) → shutdown
+ *
+ * 关键洞察："The agent finds work itself."
+ */
+@SpringBootApplication(scanBasePackages = {"io.mybatis.learn.core", "io.mybatis.learn.s10"})
+public class S11AutonomousAgents implements CommandLineRunner {
+
+ private static final int POLL_INTERVAL = 5;
+ private static final int IDLE_TIMEOUT = 60;
+
+ @Autowired
+ private ChatModel chatModel;
+
+ @Override
+ public void run(String... args) throws Exception {
+ Path workDir = Path.of(System.getProperty("user.dir"));
+ Path teamDir = workDir.resolve(".team");
+ Path tasksDir = workDir.resolve(".tasks");
+
+ MessageBus bus = new MessageBus(teamDir.resolve("inbox"));
+ ProtocolTracker tracker = new ProtocolTracker(bus);
+ AutonomousTeammateManager team = new AutonomousTeammateManager(
+ chatModel, bus, tracker, teamDir, tasksDir);
+ AutonomousLeadTools leadTools = new AutonomousLeadTools(bus, team, tracker, tasksDir);
+ ObjectMapper mapper = new ObjectMapper();
+
+ String systemPrompt = "You are a team lead at " + workDir
+ + ". Teammates are autonomous -- they find work themselves.";
+
+ ChatClient chatClient = ChatClient.builder(chatModel)
+ .defaultSystem(systemPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(), leadTools)
+ .build();
+
+ AgentRunner.interactive("s11", input -> {
+ if ("/team".equals(input)) return team.listAll();
+ if ("/inbox".equals(input)) {
+ try { return mapper.writeValueAsString(bus.readInbox("lead")); }
+ catch (Exception e) { return "Error: " + e.getMessage(); }
+ }
+
+ var inbox = bus.readInbox("lead");
+ String fullInput = input;
+ if (!inbox.isEmpty()) {
+ try { fullInput = "" + mapper.writeValueAsString(inbox) + "\n\n" + input; }
+ catch (Exception e) { /* ignore */ }
+ }
+ return chatClient.prompt(fullInput).call().content();
+ });
+ }
+
+ // ---- 任务板扫描（全局函数） ----
+
+ /**
+ * TIPS: 对应Python scan_unclaimed_tasks()（s11第127-136行）。
+ * 扫描 .tasks/task_*.json，找到 status=pending 且无 owner 的任务。
+ */
+ @SuppressWarnings("unchecked")
+ static List> scanUnclaimedTasks(Path tasksDir) {
+ if (!Files.exists(tasksDir)) return List.of();
+ List> 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 -> {
+ try {
+ Map 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);
+ }
+ } catch (IOException e) { /* skip */ }
+ });
+ } catch (IOException e) { /* ignore */ }
+ return unclaimed;
+ }
+
+ /**
+ * TIPS: 对应Python claim_task()（s11第139-148行）。
+ * 原子操作：标记任务被认领，使用 synchronized 保证互斥。
+ */
+ @SuppressWarnings("unchecked")
+ static synchronized String claimTask(Path tasksDir, int taskId, String owner) {
+ Path path = tasksDir.resolve("task_" + taskId + ".json");
+ if (!Files.exists(path)) return "Error: Task " + taskId + " not found";
+ ObjectMapper mapper = new ObjectMapper();
+ try {
+ Map task = mapper.readValue(path.toFile(), Map.class);
+ task.put("owner", owner);
+ task.put("status", "in_progress");
+ mapper.writerWithDefaultPrettyPrinter().writeValue(path.toFile(), task);
+ return "Claimed task #" + taskId + " for " + owner;
+ } catch (IOException e) {
+ return "Error: " + e.getMessage();
+ }
+ }
+
+ // ---- 自治队友管理器 ----
+
+ /**
+ * TIPS: 对应Python TeammateManager（s11第160-367行）。
+ * 核心差异：双阶段循环（WORK → IDLE）。
+ *
+ * Python: WORK阶段逐次LLM调用（range(50)），idle工具触发进入IDLE阶段；
+ * IDLE阶段每5秒轮询收件箱+任务板，超时60秒→shutdown。
+ * Java: ChatClient.prompt().call()自动完成WORK阶段的整个工具链，
+ * idle工具通过AtomicBoolean标志通知外部循环进入IDLE阶段。
+ */
+ static class AutonomousTeammateManager {
+ private final ChatModel chatModel;
+ private final MessageBus bus;
+ private final ProtocolTracker tracker;
+ private final Path configPath;
+ private final Path tasksDir;
+ private final ObjectMapper mapper = new ObjectMapper();
+ private Map config;
+
+ AutonomousTeammateManager(ChatModel chatModel, MessageBus bus,
+ ProtocolTracker tracker, Path teamDir, Path tasksDir) {
+ this.chatModel = chatModel;
+ this.bus = bus;
+ this.tracker = tracker;
+ this.tasksDir = tasksDir;
+ this.configPath = teamDir.resolve("config.json");
+ try { Files.createDirectories(teamDir); } catch (IOException e) { throw new RuntimeException(e); }
+ this.config = loadConfig();
+ }
+
+ @SuppressWarnings("unchecked")
+ private Map loadConfig() {
+ if (Files.exists(configPath)) {
+ try { return mapper.readValue(configPath.toFile(), Map.class); }
+ catch (IOException e) { /* ignore */ }
+ }
+ Map cfg = new LinkedHashMap<>();
+ cfg.put("team_name", "default");
+ cfg.put("members", new ArrayList<>());
+ return cfg;
+ }
+
+ private synchronized void saveConfig() {
+ try { mapper.writerWithDefaultPrettyPrinter().writeValue(configPath.toFile(), config); }
+ catch (IOException e) { /* ignore */ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private Map findMember(String name) {
+ for (Map m : (List>) config.get("members")) {
+ if (name.equals(m.get("name"))) return m;
+ }
+ return null;
+ }
+
+ private synchronized void setStatus(String name, String status) {
+ Map member = findMember(name);
+ if (member != null) { member.put("status", status); saveConfig(); }
+ }
+
+ @SuppressWarnings("unchecked")
+ public synchronized String spawn(String name, String role, String prompt) {
+ Map member = findMember(name);
+ if (member != null) {
+ String status = (String) member.get("status");
+ if (!"idle".equals(status) && !"shutdown".equals(status))
+ return "Error: '" + name + "' is currently " + status;
+ member.put("status", "working");
+ member.put("role", role);
+ } else {
+ member = new LinkedHashMap<>();
+ member.put("name", name);
+ member.put("role", role);
+ member.put("status", "working");
+ ((List>) config.get("members")).add(member);
+ }
+ saveConfig();
+ Thread.startVirtualThread(() -> autonomousLoop(name, role, prompt));
+ return "Spawned '" + name + "' (role: " + role + ")";
+ }
+
+ /**
+ * 自治循环：WORK → IDLE → WORK → ... → shutdown
+ */
+ private void autonomousLoop(String name, String role, String initialPrompt) {
+ String teamName = (String) config.get("team_name");
+ String workDir = System.getProperty("user.dir");
+ 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);
+
+ // idle标志：工具调用时设置，外部循环检测
+ AtomicBoolean idleRequested = new AtomicBoolean(false);
+
+ var messageTool = new io.mybatis.learn.s09.TeammateManager.TeammateMessageTool(bus, name);
+ var protocolTool = new io.mybatis.learn.s10.S10TeamProtocols.TeammateProtocolTool(bus, tracker, name);
+ var idleTool = new IdleTool(idleRequested);
+ var claimTool = new ClaimTaskTool(tasksDir, name);
+
+ ChatClient client = ChatClient.builder(chatModel)
+ .defaultSystem(sysPrompt)
+ .defaultTools(new BashTool(), new ReadFileTool(),
+ new WriteFileTool(), new EditFileTool(),
+ messageTool, protocolTool, idleTool, claimTool)
+ .build();
+
+ try {
+ while (true) {
+ // -- WORK PHASE --
+ String nextMsg = initialPrompt;
+ for (int round = 0; round < 50 && nextMsg != null; round++) {
+ // 检查收件箱
+ var inbox = bus.readInbox(name);
+ StringBuilder sb = new StringBuilder(nextMsg);
+ for (var msg : inbox) {
+ if ("shutdown_request".equals(msg.get("type"))) {
+ setStatus(name, "shutdown");
+ return;
+ }
+ sb.append("\n").append(mapper.writeValueAsString(msg));
+ }
+
+ idleRequested.set(false);
+ String response = client.prompt(sb.toString()).call().content();
+ System.out.println(" [" + name + "] "
+ + AgentRunner.truncate(response, 120));
+
+ if (idleRequested.get()) break;
+ nextMsg = null; // 后续轮次靠inbox驱动
+
+ Thread.sleep(1000);
+ var newInbox = bus.readInbox(name);
+ if (newInbox.isEmpty()) break;
+ nextMsg = "" + mapper.writeValueAsString(newInbox) + "";
+ }
+
+ // -- IDLE PHASE: 轮询收件箱 + 任务板 --
+ setStatus(name, "idle");
+ boolean resume = false;
+ int polls = IDLE_TIMEOUT / Math.max(POLL_INTERVAL, 1);
+
+ for (int p = 0; p < polls; p++) {
+ Thread.sleep(POLL_INTERVAL * 1000L);
+
+ // 检查收件箱
+ var inbox = bus.readInbox(name);
+ if (!inbox.isEmpty()) {
+ for (var msg : inbox) {
+ if ("shutdown_request".equals(msg.get("type"))) {
+ setStatus(name, "shutdown");
+ return;
+ }
+ }
+ initialPrompt = "" + mapper.writeValueAsString(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(
+ "Task #%d: %s\n%s",
+ taskId, task.get("subject"),
+ task.getOrDefault("description", ""));
+ resume = true;
+ break;
+ }
+ }
+
+ if (!resume) {
+ setStatus(name, "shutdown");
+ return;
+ }
+ setStatus(name, "working");
+ }
+ } catch (Exception e) {
+ System.err.println(" [" + name + "] Error: " + e.getMessage());
+ setStatus(name, "shutdown");
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ public String listAll() {
+ List> members = (List>) config.get("members");
+ if (members.isEmpty()) return "No teammates.";
+ StringBuilder sb = new StringBuilder("Team: " + config.get("team_name"));
+ for (Map m : members)
+ sb.append("\n ").append(m.get("name"))
+ .append(" (").append(m.get("role")).append("): ").append(m.get("status"));
+ return sb.toString();
+ }
+
+ @SuppressWarnings("unchecked")
+ public List memberNames() {
+ return ((List>) config.get("members")).stream()
+ .map(m -> (String) m.get("name")).toList();
+ }
+ }
+
+ // ---- idle工具 ----
+
+ /**
+ * TIPS: 对应Python idle工具（s11第352-353行）。
+ * Python在_exec中直接返回字符串并设置idle_requested标志；
+ * Java通过AtomicBoolean实现跨线程通信：
+ * 工具执行时设置标志 → ChatClient完成工具链后 → 外部循环检测标志。
+ */
+ public static class IdleTool {
+ private final AtomicBoolean idleFlag;
+
+ public IdleTool(AtomicBoolean idleFlag) {
+ this.idleFlag = idleFlag;
+ }
+
+ @Tool(description = "Signal that you have no more work. Enters idle polling phase.")
+ public String idle() {
+ idleFlag.set(true);
+ return "Entering idle phase. Will poll for new tasks.";
+ }
+ }
+
+ // ---- claim_task工具 ----
+
+ public static class ClaimTaskTool {
+ private final Path tasksDir;
+ private final String owner;
+
+ public ClaimTaskTool(Path tasksDir, String owner) {
+ this.tasksDir = tasksDir;
+ this.owner = owner;
+ }
+
+ @Tool(description = "Claim a task from the task board by ID")
+ public String claimTask(
+ @ToolParam(description = "Task ID to claim") int taskId) {
+ return S11AutonomousAgents.claimTask(tasksDir, taskId, owner);
+ }
+ }
+
+ // ---- Lead工具集（14个工具 = S10的12个 + idle + claim_task） ----
+
+ public static class AutonomousLeadTools {
+ private final MessageBus bus;
+ private final AutonomousTeammateManager team;
+ private final ProtocolTracker tracker;
+ private final Path tasksDir;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public AutonomousLeadTools(MessageBus bus, AutonomousTeammateManager team,
+ ProtocolTracker tracker, Path tasksDir) {
+ this.bus = bus;
+ this.team = team;
+ this.tracker = tracker;
+ this.tasksDir = tasksDir;
+ }
+
+ @Tool(description = "Spawn an autonomous teammate") public String spawnTeammate(String name, String role, String prompt) { return team.spawn(name, role, prompt); }
+ @Tool(description = "List all teammates") public String listTeammates() { return team.listAll(); }
+ @Tool(description = "Send message to teammate") public String sendMessage(String to, String content) { return bus.send("lead", to, content); }
+ @Tool(description = "Read lead's inbox") public String readInbox() { try { return mapper.writeValueAsString(bus.readInbox("lead")); } catch (Exception e) { return "[]"; } }
+ @Tool(description = "Broadcast to all teammates") public String broadcast(String content) { return bus.broadcast("lead", content, team.memberNames()); }
+ @Tool(description = "Request teammate shutdown") public String shutdownRequest(String teammate) { return tracker.handleShutdownRequest(teammate); }
+ @Tool(description = "Check shutdown status") public String shutdownResponse(String requestId) { return tracker.checkShutdownStatus(requestId); }
+ @Tool(description = "Approve/reject plan") public String planApproval(String requestId, boolean approve, String feedback) { return tracker.reviewPlan(requestId, approve, feedback); }
+ @Tool(description = "Claim a task from the board") public String claimTask(int taskId) { return S11AutonomousAgents.claimTask(tasksDir, taskId, "lead"); }
+ }
+
+ public static void main(String[] args) {
+ SpringApplication.run(S11AutonomousAgents.class, args);
+ }
+}
diff --git a/src/main/java/io/mybatis/learn/s12/EventBus.java b/src/main/java/io/mybatis/learn/s12/EventBus.java
new file mode 100644
index 0000000..90a02a2
--- /dev/null
+++ b/src/main/java/io/mybatis/learn/s12/EventBus.java
@@ -0,0 +1,93 @@
+package io.mybatis.learn.s12;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 事件总线 - 追加式JSONL生命周期事件日志
+ *
+ * TIPS: 对应Python EventBus类（s12第83-118行）。
+ * 记录 worktree 和 task 的生命周期事件，用于可观测性。
+ * 事件类型：worktree.create.before/after/failed, worktree.remove.*, worktree.keep, task.completed
+ */
+public class EventBus {
+ private static final Logger log = LoggerFactory.getLogger(EventBus.class);
+
+ private final Path logPath;
+ private final ObjectMapper mapper = new ObjectMapper();
+
+ public EventBus(Path logPath) {
+ this.logPath = logPath;
+ try {
+ Files.createDirectories(logPath.getParent());
+ if (!Files.exists(logPath)) Files.writeString(logPath, "");
+ if (log.isDebugEnabled()) {
+ System.out.printf("🚀 事件日志就绪: %s%n", logPath);
+ }
+ } catch (IOException e) {
+ log.error("初始化事件日志失败: {}, error={}", logPath, e.getMessage());
+ throw new RuntimeException(e);
+ }
+ }
+
+ public synchronized void emit(String event, Map task,
+ Map worktree, String error) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("event", event);
+ payload.put("ts", System.currentTimeMillis() / 1000.0);
+ payload.put("task", task != null ? task : Map.of());
+ payload.put("worktree", worktree != null ? worktree : Map.of());
+ if (error != null) payload.put("error", error);
+
+ try {
+ Files.writeString(logPath, mapper.writeValueAsString(payload) + "\n",
+ StandardOpenOption.APPEND);
+ if (log.isDebugEnabled()) {
+ System.out.printf("📡 事件已记录: %s%n", event);
+ }
+ } catch (IOException e) {
+ log.warn("事件写入失败: event={}, error={}", event, e.getMessage());
+ System.err.println("EventBus emit error: " + e.getMessage());
+ }
+ }
+
+ public void emit(String event) {
+ emit(event, null, null, null);
+ }
+
+ @SuppressWarnings("unchecked")
+ public String listRecent(int limit) {
+ int n = Math.max(1, Math.min(limit, 200));
+ if (log.isDebugEnabled()) {
+ System.out.printf("🔍 读取最近 %d 条事件 (请求 %d)%n", n, limit);
+ }
+ try {
+ List lines = Files.readAllLines(logPath);
+ List recent = lines.subList(Math.max(0, lines.size() - n), lines.size());
+ List