S03TodoWrite - 任务规划：没有计划的 Agent 会迷失方向

核心理念“没有计划的 Agent 走哪算哪” – 先列步骤再动手完成率翻倍。源码https://github.com/xiayongchao/learn-claude-code-4j/blob/main/src/main/java/org/jc/agents/S03TodoWrite.java原版https://github.com/shareAI-lab/learn-claude-code上篇S02ToolUse - 工具使用上篇回顾上篇文章我们实现了 4 个工具bash、readFile、writeFile、editFile并通过 Dispatch Map 实现工具分发。问题多步任务中模型会丢失进度重复做过的事跳步跑偏对话越长越严重工具结果不断填满上下文系统提示的影响力逐渐被稀释。一个 10 步重构可能做完 1-3 步就开始即兴发挥因为 4-10 步已经被挤出注意力了。解决方案-------- ------- --------- | User | --- | LLM | --- | Tools | | prompt | | | | todo | -------- ------ -------- ^ | | tool_result | ---------------- | ---------------------- | TodoManager state | | [ ] task A | | [] task B - doing | | [x] task C | ----------------------- | if roundsSinceTodo 3: inject reminder两个关键机制TodoManager- 模型自己维护任务状态Nag Reminder- 3 轮不更新待办就提醒Java 实现详解1. TodoManager带状态的任务管理器publicclassTodoManager{publicstaticfinalStringPENDINGpending;publicstaticfinalStringIN_PROGRESSin_progress;publicstaticfinalStringCOMPLETEDcompleted;privateListTodoItemitemsnewArrayList();publicStringupdate(Stringjson){returnthis.update(JSON.parseArray(JSON.parseObject(json).getString(items),TodoItem.class));}publicStringupdate(ListTodoItemitems){// 最多20条if(items.size()20){thrownewIllegalArgumentException(最多允许20条待办事项);}ListTodoItemvalidatednewArrayList();intinProgressCount0;for(inti0;iitems.size();i){TodoItemitemitems.get(i);Stringtextitem.getText()null?:item.getText().trim();Stringstatusitem.getStatus()null?PENDING:item.getStatus().toLowerCase();StringitemId(item.getId()null||item.getId().isBlank())?String.valueOf(i1):item.getId();if(text.isBlank()){thrownewIllegalArgumentException(待办事项 itemId: 文本不能为空);}if(!List.of(PENDING,IN_PROGRESS,COMPLETED).contains(status)){thrownewIllegalArgumentException(状态无效: status);}if(status.equals(IN_PROGRESS)){inProgressCount;}validated.add(newTodoItem(itemId,text,status));}// 关键约束只能有一个进行中if(inProgressCount1){thrownewIllegalArgumentException(同一时间仅允许一个任务处于进行中状态);}this.itemsvalidated;returnrender();}publicStringrender(){if(items.isEmpty()){return暂无待办事项;}ListStringlinesnewArrayList();for(TodoItemitem:items){Stringmarkerswitch(item.getStatus()){casepending-[ ];casein_progress-[];casecompleted-[x];default-[ ];};lines.add(marker #item.getId(): item.getText());}longdoneCountitems.stream().filter(item-COMPLETED.equals(item.getStatus())).count();lines.add(\n(doneCount/items.size() 已完成));returnString.join(\n,lines);}}2. TodoItem待办事项实体publicclassTodoItem{privateStringid;privateStringtext;privateStringstatus;// pending | in_progress | completed}3. 工具注册privatestaticfinalTodoManagerTODOnewTodoManager();privatestaticfinalMapString,FunctionString,StringTOOL_HANDLERSnewHashMap();static{TOOL_HANDLERS.put(bash,Tools::runBash);TOOL_HANDLERS.put(readFile,Tools::runReadFile);TOOL_HANDLERS.put(writeFile,Tools::runWriteFile);TOOL_HANDLERS.put(editFile,Tools::runEditFile);TOOL_HANDLERS.put(todo,TODO::update);// 新增}privatestaticfinalListChatCompletionTooltoolsList.of(Tools.bashTool(),Tools.readFileTool(),Tools.writeFileTool(),Tools.editFileTool(),Tools.todoTool()// 新增);4. SYSTEM 提示词privatestaticfinalStringSYSTEM你是工作目录 Commons.CWD 下的编程智能体使用待办工具规划多步骤任务。开始前标记为进行中完成后标记为已完成优先使用工具操作而非文字说明;5. agentLoop 方法Nag Reminder 机制publicstaticvoidagentLoop(ListChatCompletionMessageParammessages){introundsSinceTodo0;// 追踪轮次while(true){ListChatCompletionMessageParamfullMessagesnewArrayList();fullMessages.add(ChatCompletionMessageParam.ofSystem(ChatCompletionSystemMessageParam.builder().content(SYSTEM).build()));fullMessages.addAll(messages);ChatCompletionCreateParamsparamsChatCompletionCreateParams.builder().model(qwen3.5-plus).messages(fullMessages).tools(tools).build();ChatCompletionchatCompletionCommons.getClient().chat().completions().create(params);ChatCompletionMessagemessagechatCompletion.choices().get(0).message();messages.add(ChatCompletionMessageParam.ofAssistant(message.toParam()));OptionalListChatCompletionMessageToolCalltoolCallsOptionalmessage.toolCalls();if(toolCallsOptional.isEmpty()){return;}booleanusedTodofalse;for(ChatCompletionMessageToolCalltoolCall:toolCallsOptional.get()){ChatCompletionMessageParamtoolMessageTools.exe(TOOL_HANDLERS,toolCall);if(toolMessage!null){messages.add(toolMessage);}if(Tools.isTodoTool(toolCall)){usedTodotrue;}}// Nag Reminder连续3轮不调用todo则提醒if(usedTodo){roundsSinceTodo0;}else{roundsSinceTodo;}if(roundsSinceTodo3){messages.add(ChatCompletionMessageParam.ofUser(ChatCompletionUserMessageParam.builder().content(reminder更新你的待办事项/reminder).build()));}}}关键约束约束说明最多 20 条防止上下文溢出只能有一个 in_progress强制顺序聚焦3 轮 nag reminder制造问责压力相对 s02 的变更组件s02s03Tools45 (todo)规划无带状态的 TodoManagerNag 注入无3 轮后注入 reminderAgent loop简单分发 roundsSinceTodo 计数器试试看重构 hello.java 文件添加类型注解、文档字符串并补充程序入口守卫判断创建一个 java 包包含 utils.java 以及测试文件 tests/test_utils.java检查所有 java 代码文件并修复所有代码风格问题核心要义“An agent without a plan drifts”模型自己追踪进度Harness 负责在它忘记时提醒设计原则约束即智慧in_progress只能一个提醒即压力不更新就追问工具即行动优先操作而非文字