【从0到1构建一个ClaudeAgent】规划与和谐-TodoWrite

发表于 6 天前

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要登录才可以下载或查看，没有账号？立即注册

×

这段代码引入了一个非常关键的概念：“自我反思与状态管理”。
之前的 Agent 只是单纯的“听指令 -> 干活”，轻易干着干着就忘了初志，大概在复杂的使掷中迷失方向。TodoManager 就像是给 Agent 装了一个“记事本”和“监工”。
Java 实当代码

public class AgentWithTodo {
private static final Path WORKDIR = Paths.get(System.getProperty("user.dir"));
// --- 1. 状态管理：TodoManager ---
// 任务状态枚举
public enum TaskStatus {
PENDING("pending"), IN_PROGRESS("in_progress"), COMPLETED("completed");
public final String label;
TaskStatus(String label) { this.label = label; }
public static TaskStatus fromLabel(String s) {
for (TaskStatus ts : values()) if (ts.label.equals(s)) return ts;
return PENDING;
}
}
// 任务实体
public static class TodoItem {
public String id;
public String text;
public TaskStatus status;
public TodoItem(String id, String text, String status) {
this.id = id; this.text = text; this.status = TaskStatus.fromLabel(status);
}
}
// 管理器类
public static class TodoManager {
private List<TodoItem> items = new ArrayList<>();
public String update(List<Map<String, Object>> newItems) throws Exception {
if (newItems.size() > 20) throw new Exception("Max 20 todos allowed");
List<TodoItem> validated = new ArrayList<>();
int inProgressCount = 0;
for (int i = 0; i < newItems.size(); i++) {
Map<String, Object> item = newItems.get(i);
String text = (String) item.getOrDefault("text", "");
String statusStr = (String) item.getOrDefault("status", "pending");
String id = String.valueOf(item.getOrDefault("id", String.valueOf(i + 1)));
if (text.trim().isEmpty()) throw new Exception("Item " + id + ": text required");
TaskStatus status = TaskStatus.fromLabel(statusStr.toLowerCase());
if (status == TaskStatus.IN_PROGRESS) inProgressCount++;
validated.add(new TodoItem(id, text.trim(), status.label));
}
if (inProgressCount > 1) throw new Exception("Only one task can be in_progress at a time");
this.items = validated;
return render();
}
public String render() {
if (items.isEmpty()) return "No todos.";
StringBuilder sb = new StringBuilder();
for (TodoItem item : items) {
String marker = item.status == TaskStatus.PENDING ? "[ ]" :
item.status == TaskStatus.IN_PROGRESS ? "[>]" : "[x]";
sb.append(String.format("%s #%s: %s%n", marker, item.id, item.text));
}
long done = items.stream().filter(i -> i.status == TaskStatus.COMPLETED).count();
sb.append(String.format("%n(%d/%d completed)", done, items.size()));
return sb.toString();
}
}
private static final TodoManager TODO_MANAGER = new TodoManager();
// --- 2. 工具定义与分发 ---
public enum ToolType {
BASH("bash"), READ_FILE("read_file"), WRITE_FILE("write_file"),
EDIT_FILE("edit_file"), TODO("todo"); // 新增 todo 工具
public final String name;
ToolType(String name) { this.name = name; }
}
private static final Map<String, ToolExecutor> TOOL_HANDLERS = new HashMap<>();
static {
// ... 省略已有的工具注册
// 注册 Todo 工具
TOOL_HANDLERS.put(ToolType.TODO.name, args -> {
@SuppressWarnings("unchecked")
List<Map<String, Object>> items = (List<Map<String, Object>>) args.get("items");
return TODO_MANAGER.update(items);
});
}
// --- 3. 核心循环 ---
public static void agentLoop(List<Map<String, Object>> messages) {
int roundsSinceTodo = 0; // 新增：跟踪轮数
while (true) {
// ... 省略相同的 LLM 调用、消息追加、停止检查逻辑
// 3. 执行工具
List<Map<String, Object>> toolResults = new ArrayList<>();
List<Map<String, Object>> content = (List<Map<String, Object>>) response.get("content");
boolean usedTodo = false; // 新增：标记是否使用了 todo 工具
for (Map<String, Object> block : content) {
if ("tool_use".equals(block.get("type"))) {
// ... 省略相同的工具调用逻辑
String toolName = (String) block.get("name");
// ... 执行工具
if (toolName.equals("todo")) usedTodo = true; // 标记 todo 使用
}
}
// 4. 监工逻辑 (Nag Reminder)
roundsSinceTodo = usedTodo ? 0 : roundsSinceTodo + 1;
if (roundsSinceTodo >= 3) { // 关键：超过3轮没更新就提醒
Map<String, Object> nag = new HashMap<>();
nag.put("type", "text");
nag.put("text", "<reminder>Update your todos.</reminder>");
toolResults.add(0, nag); // 插入到结果列表最前面
System.out.println(">>> 监工提醒：更新待办列表！");
}
// 5. 回传结果
// ... 省略相同的回传逻辑
}
}
// --- 4. 工具实现 (简化版) ---
// ... 省略已有的工具实现
}

复制代码

状态管理：TodoManager 类

为Agent引入长期影象和工作进度追踪本领，让Agent能"记取"本身的使命列表和工作状态。

// 任务状态枚举
public enum TaskStatus {
PENDING("pending"),
IN_PROGRESS("in_progress"),
COMPLETED("completed");
// 状态枚举：明确定义三种状态
// 状态驱动：Agent根据状态决定下一步操作
}

复制代码

// 任务实体 - 数据结构
public static class TodoItem {
public String id; // 唯一标识
public String text; // 任务描述
public TaskStatus status; // 状态
// 结构化的任务表示
// 为LLM提供清晰的上下文
}

复制代码

// TodoManager - 核心状态管理
public class TodoManager {
private List<TodoItem> items = new ArrayList<>(); // 状态存储
public String update(List<Map<String, Object>> newItems) throws Exception {
if (newItems.size() > 20) throw new Exception("Max 20 todos allowed");
// 业务规则1：限制任务数量，防止滥用
int inProgressCount = 0;
List<TodoItem> validated = new ArrayList<>();
for (int i = 0; i < newItems.size(); i++) {
Map<String, Object> item = newItems.get(i);
String text = (String) item.getOrDefault("text", "");
String statusStr = (String) item.getOrDefault("status", "pending");
String id = String.valueOf(item.getOrDefault("id", String.valueOf(i + 1)));
if (text.trim().isEmpty()) throw new Exception("Item " + id + ": text required");
// 业务规则2：任务文本必填
TaskStatus status = TaskStatus.fromLabel(statusStr.toLowerCase());
if (status == TaskStatus.IN_PROGRESS) inProgressCount++;
// 业务规则3：跟踪进行中任务数量
}
if (inProgressCount > 1) throw new Exception("Only one task can be in_progress at a time");
// 业务规则4：一次只能进行一个任务，聚焦执行
this.items = validated; // 原子性更新
return render(); // 返回可视化表示
}
public String render() {
if (items.isEmpty()) return "No todos.";
StringBuilder sb = new StringBuilder();
for (TodoItem item : items) {
String marker = item.status == TaskStatus.PENDING ? "[ ]" :
item.status == TaskStatus.IN_PROGRESS ? "[>]" : "[x]";
sb.append(String.format("%s #%s: %s%n", marker, item.id, item.text));
// 可视化格式：[ ] 待办, [>] 进行中, [x] 已完成
}
long done = items.stream().filter(i -> i.status == TaskStatus.COMPLETED).count();
sb.append(String.format("%n(%d/%d completed)", done, items.size()));
// 进度统计：为LLM提供进度反馈
return sb.toString();
}
}

复制代码

状态长期化：Agent有了"影象"，不再是完全无状态的
布局化表现：用面向对象的方式管理使命状态
业务束缚：通过校验规则确保状态同等性
可视化输出：为LLM提供人类可读的进度展示

Todo工具集成

// 在工具枚举中新增
TODO("todo"); // 扩展工具集，添加状态管理工具
// 注册Todo工具实现
TOOL_HANDLERS.put(ToolType.TODO.name, args -> {
@SuppressWarnings("unchecked")
List<Map<String, Object>> items = (List<Map<String, Object>>) args.get("items");
return TODO_MANAGER.update(items);
// 状态更新工具：让LLM能操作任务状态
// 接受LLM传入的任务列表，更新内部状态
});

复制代码

状态使用作为工具：将状态管理抽象为工具调用
双向通讯：LLM可以通过工具更新状态，也能获取状态
同一接口：与其他工具使用雷同的调用模式

监工逻辑（Nag Reminder）

// 在agentLoop中新增
int roundsSinceTodo = 0; // 计数器：记录多少轮没使用todo工具
boolean usedTodo = false; // 标记当前轮是否使用了todo
// 执行工具时记录
if (toolName.equals("todo")) usedTodo = true;
// 每轮结束后的监工检查
roundsSinceTodo = usedTodo ? 0 : roundsSinceTodo + 1; // 重置或递增
if (roundsSinceTodo >= 3) { // 如果超过3轮没更新待办
Map<String, Object> nag = new HashMap<>();
nag.put("type", "text");
nag.put("text", "<reminder>Update your todos.</reminder>");
toolResults.add(0, nag); // 插入到结果列表最前面
System.out.println(">>> 监工提醒：更新待办列表！");
// 强制提醒：防止LLM忘记更新状态
}

复制代码

防忘记机制：LLM大概会忘记更新状态，须要外部提示
渐进式提示：容忍短期忘记，高出阈值再干预
布局化提示：使用特别标签，让LLM辨认这是体系提示
优先级：插入到结果列表最前面，确保LLM先看到

架构演进与代价

从 AgentWithTools 到 AgentWithTodo 的升级：
维度AgentWithToolsAgentWithTodo状态管理无状态有状态（TodoManager）进度追踪不支持支持使命进度管理长期影象不支持支持使命列表影象监视机制无有监工提示使命管理工具级项目级
免责声明：如果侵犯了您的权益，请联系站长及时删除侵权内容，谢谢合作！qidao123.com:ToB企服之家，中国第一个企服评测及软件市场,开放入驻,技术点评得现金.

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

浏览过的版块