AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载导读本文聚焦 Kimi Code 项目agent-core-v2包中内置的TodoList 工具工具名TodoList它以结构化 TODO 列表帮助 Agent 在跨越多次工具调用的长任务中持续追踪进度。文章以官方工具说明文档 todo-list.md 为骨架完整继承其使用规范并结合同目录源码与测试展开底层原理。读完本文你将掌握 TodoList 的三种调用模式读取 / 整体替换 / 清空、三种状态pending/in_progress/done的正确用法、防抖更新与过期提醒机制以及它在 xstate Actor 与持久化事件体系中的真实实现路径。一、工具定位面向多步任务的进度记忆TodoList 不是普通的笔记工具而是 Agent 在长任务执行过程中的结构化进度跟踪器。官方说明文档明确其核心用途在完成一个多步骤任务时用它维护一份结构化的 TODO 列表并在进度跟踪对当前工作有帮助时主动、频繁地使用——尤其是在包含大量工具调用的长时间调查investigation与多步骤实现任务中。文档还特别提醒处于 plan 模式时应将计划写入 plan 文件而不是在这里追踪。在架构层面TodoList 是agent-core-v2中todoFeature 贡献出的一个内置工具工具名常量定义在 todoItem.tsexport const TODO_LIST_TOOL_NAME TodoList as const;其整体组织如下目录 packages/agent-core-v2/src/features/todotools/todo-list/todo-list.md工具描述文档即本文依据的官方说明tools/todo-list/todo-list.ts输入 Schema 与工具接口定义tools/todo-list/todoListTool.ts工具执行实现tools/todo-list/todo-list-write-reminder.md每次写入成功后追加的继续使用提醒文案todoItem.ts状态类型、校验与渲染todoService.tsAgentTodoService服务xstate Actor 与持久化todoListReminder.ts列表过期时的兜底提醒todoFeature.tsFeature 注册。二、何时使用When to use原文档列出的适用场景共五条是模型判断该不该动 TodoList的决策依据跨多次工具调用的多步任务Multi-step tasks that span several tool calls跨大型代码库搜索的调查进度追踪Tracking investigation progress across a large codebase search在执行编辑前规划一组改动Planning a sequence of edits before making them收到新的多步指令后先把需求拆解成 todos 记录After receiving new multi-step instructions, capture the requirements as todos纪律性状态流转开始一项被追踪的任务前恰好把一项标记为in_progress一项任务刚完成就立刻标记done不要到最后批量补标。上述第 5 条对应测试中验证过的输出约束——更新成功后工具会在输出中追加写提醒文案见 todo-list-write-reminder.md提醒 Agent keep exactly one task in_progress。测试 todo-list.test.ts 明确断言更新输出中包含Ensure that you continue to use the todo list to track progress.与exactly one task in_progress两句提示。三、何时不要使用When NOT to use原文档给出三个反例避免工具被滥用造成上下文噪声一两次工具调用就能完成的单发回答Single-shot answers——无需进度追踪琐碎请求——追踪不会带来任何清晰度收益纯对话或纯信息回复Purely conversational or informational replies。理解这一节的关键是TodoList 的每次写入都会产生一条可持久化事件见下文底层实现并占用上下文对短任务调用它反而增加 token 开销与状态维护成本得不偿失。四、避免无效更新Avoid churn这是原文档中最具工程实践价值的一节强调不要为了调用而调用无实质进展就不重复调用自上次调用以来没有有意义的变化时不要再次调用只在真正取得进展后更新列表。不确定当前状态时先查询调用查询模式省略todos参数先看当前列表再决定怎么更新避免基于过期认知盲目覆写。卡住时如实汇报如果没有可用工具能推进任何任务直接告诉用户卡在哪里而不是反复重排同一批 todos 假装在推进。从实现上看查询不产生变更这一点有测试兜底测试 todo-list.test.ts 先播种一条in_progress的既有任务再用空参数{}执行工具断言输出包含Current todo list与[in_progress] existing且工具执行后列表内容保持不变。五、如何使用How to use三种调用模式原文档定义了 TodoList 的完整调用协议对应实现中的三种模式todoListTool.ts 会按模式生成对应的执行描述调用方式行为执行描述resolveExecutiontodos: [...]非空数组整体替换整个列表一次性写入全部条目Updating todo list省略todos参数查询当前列表不产生任何修改Reading todo listtodos: []空数组清空列表Clearing todo list状态取值只有三种定义于 todoItem.tsexport type TodoStatus pending | in_progress | done;其余操作纪律全部继承自原文档调用时传入todos: [...]表示整体替换状态可为pending/in_progress/done省略todos表示只读当前列表不改动任何内容传入todos: []表示清空列表标题保持简短可执行例如Read session-control.ts、Add planMode flag to TurnManager进行中时恰好保持一项in_progress只有任务完全完成才标记done禁止在测试失败、实现不完整、错误未解决、依赖文件缺失时标记done遇到阻塞时保持该任务in_progress或新增一条pending任务描述待解决事项。5.1 输入 Schema 与校验输入 Schema 使用 zod 定义todo-list.tsconst TodoItemSchema z.object({ title: z.string().min(1).describe(Short, actionable title for the todo.), status: z.enum([pending, in_progress, done]).describe(Current status of the todo.), }); export const TodoListInputSchema: z.ZodTypeTodoListInput z.object({ todos: z .array(TodoItemSchema) .optional() .describe( The updated todo list. Omit to read the current todo list without making changes. Pass an empty array to clear the list., ), });要点title必须是非空字符串min(1)status严格限定枚举非法值会被 Schema 拒绝。测试明确验证了这一点{ todos: [{ title: x, status: wip }] }无法通过safeParsetodo-list.test.ts。该 Schema 会通过toInputJsonSchema转换为 JSON Schema 暴露给模型additionalProperties: false、todos: { type: array }见测试第 45-51 行断言。5.2 执行流程与输出工具执行逻辑todoListTool.ts查询模式直接返回renderTodoList(this.todo.get())写入模式先对传入条目做防御性拷贝只保留title/status两个字段再调用this.todo.replace(next)整体替换替换后重新读取存储若为空输出Todo list cleared.否则输出Todo list updated. 渲染后的列表 写提醒文案。测试 todo-list.test.ts 验证了防御性拷贝传入的input[0]在调用后被外部修改为leaked/done但存储中的列表仍是原始的两条证明工具不会持有调用方可变引用。5.3 列表渲染格式渲染函数renderTodoListtodoItem.ts输出格式为Current todo list: [pending] first [in_progress] second [done] shipped每条以两个空格缩进状态标记与枚举值完全一致[pending]/[in_progress]/[done]。测试断言[done] shipped存在且不出现[completed]之类的变体todo-list.test.ts。列表为空时输出Todo list is empty.。六、底层实现AgentTodoService 与持久化事件TodoList 工具本身只是薄壳真正的状态管理在AgentTodoServicetodoService.ts。其服务接口为export interface IAgentTodoService { readonly _serviceBrand: undefined; readonly onDidChange: EventTodoState; get(): readonly TodoItem[]; replace(todos: readonly TodoItem[]): Promisevoid; clear(): Promisevoid; }三个核心事实值得展开xstate Actor 驱动AgentTodoService继承AgentActorServiceTodoState通过attachActor(todoActorLogic, ...)挂载一个 xstate 状态机todoService.ts。状态机含beforeRestore、active、reminding三个状态以及todo.used标记工具被使用过与todo.commit提交新列表两个事件。get()/replace()/clear()都会发送todo.used驱动状态迁移。持久化与可撤销写入通过ToolsUpdateStore事件完成todoOps.ts该事件继承自AgentEvent2声明type tools.update_store、durable true载荷为{ agentId, key, value }。在 actor 上配置durable: { events: [ToolsUpdateStore], undoable: true, ... }意味着 TodoList 的每次变更可持久化、可撤销undo——这与 undo.test.ts 等撤销测试体系一致。状态收敛持久化恢复时通过transition把ToolsUpdateStore事件中的value用readTodoItems清洗成合法的TodoItem[]非法项被过滤todoItem.ts保证任何来源的数据都满足title: string status ∈ {pending, in_progress, done}。此外工具执行对象还声明了approvalRule: this.nametodoListTool.ts表示该工具调用受同名审批策略约束且display.kind todo_list用于前端以列表形态展示执行过程。七、防止僵死列表过期提醒Stale Reminder机制为了让频繁使用、及时更新的纪律在长会话中持续生效agent-core-v2内置了兜底提醒当 TodoList 长时间未被更新时以注入消息injection形式温和地提醒模型继续维护列表。实现位于 todoListReminder.ts变体名TODO_LIST_REMINDER_VARIANT todo_list_reminder第 5 行阈值常量距上次写入超过10 轮TODO_LIST_REMINDER_TURNS_SINCE_WRITE 10且距上次提醒超过10 轮TODO_LIST_REMINDER_TURNS_BETWEEN_REMINDERS 10才触发第 7-8 行判定逻辑回溯上下文历史统计自上次 TodoList 写入assistant 消息中出现过带todos数组的 TodoList 工具调用与上次提醒以来的轮数第 35-67 行提醒文案是温和提示明确要求模型绝不向用户提及该提醒仅在相关时使用第 90-100 行并附上当前列表摘要按序号. [状态] 标题渲染第 102-104 行。提醒通过todoReminderactor 注册todoService.ts且仅对主 AgentMAIN_AGENT_ID生效注册时还会检查工具策略toolPolicy.isToolActive(TODO_LIST_TOOL_NAME, builtin)——工具未激活时提醒静默不触发。相关行为有独立测试覆盖test/features/todo/todoListReminder.test.ts。八、Feature 注册与集成方式TodoList 并非散落的工具而是todoFeature 的一部分todoFeature.tsexport class TodoFeature extends Feature { static override readonly name todo; constructor() { super(); this.contributeAgentService(IAgentTodoService, AgentTodoService); this.contributeTool(ITodoListTool, TodoListTool, { name: TodoList, domain: todo }); } } registerFeature(TodoFeature);它同时贡献了两样东西服务IAgentTodoService→AgentTodoService状态管理与持久化工具ITodoListTool→TodoListTool注册名为TodoList归属域todo。工具描述文本通过import DESCRIPTION from ./todo-list.md?raw直接内联为descriptiontodoListTool.ts即模型每次看到的工具说明正是本文依据的这份官方文档。此外agent-core-v2的src/human/todo/tool.ts与src/index.ts也存在对 todo 相关符号的引用说明该能力同时向 human人工交互等外围模块暴露。九、测试验证全景TodoList 的行为由测试 todo-list.test.ts 系统兜底覆盖的契约包括测试用例验证点工具元数据名称恰为TodoList、description 非空、Schema 拒绝非法状态、parameters 为{ type: object, additionalProperties: false }查询模式不修改列表、输出包含Current todo list与状态标记写入模式整体替换、防御性拷贝、输出包含更新确认与写提醒文案状态标记done渲染为[done]不出现[completed]清空模式输出Todo list cleared.且不附带进度追踪提醒执行描述读取 / 清空 / 更新分别对应Reading todo list/Clearing todo list/Updating todo list结合 sessionTodo.test.ts 与 todoListReminder.test.ts可确认整个 todo 能力在会话、持久化与提醒三个层面都有端到端验证。十、实践总结Agent 侧的最佳使用范式综合原文档与源码一个健康的 TodoList 使用循环是收到多步指令后立即把需求拆解为简短、可执行的 todos 并整体写入开始执行时保证恰好一项为in_progress每取得实质进展就调用一次查询当前状态 → 整体替换更新绝不批量补标任务完成即标记done只有全部完成、无遗留错误时才收尾若列表已与当前工作脱节用空数组清空或重写短任务、单发回答、纯对话场景不调用避免状态维护噪声。这套范式背后有完整的工程支撑zod Schema 保证输入合法、xstate Actor 保证状态一致、ToolsUpdateStore持久化事件保证可恢复与可撤销、过期提醒保证长任务不遗忘列表。对希望在 Kimi Code / agent-core-v2 之上构建 Agent 的开发者而言理解 TodoList 的实现即理解了一条可复用的轻量状态管理 上下文约束设计路径。赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐Crush 的 todos 工具Agent 多步任务的结构化进度追踪机制Crush 的 todos 工具Agent 多步任务的结构化进度追踪机制 导读 本文围绕 CrushGlamourous agentic coding foAI 应用代码智能体交互助手CLIMCP Clients人工智能WinUI 版本管理一次讲清microsoft-ui-xaml 的构建版本体系完整指南WinUI 版本管理一次讲清microsoft ui xaml 的构建版本体系完整指南 如果你克隆过 WinUI 官方仓库microsoft ui xaml前端UI组件桌面应用Gemini CLI write_todos 工具详解Agent 多步任务规划与进度可视化的实现机制Gemini CLI write_todos 工具详解Agent 多步任务规划与进度可视化的实现机制 本文聚焦 Gemini CLI 内置的 write_to人工智能AI Agent交互助手CLIMCP Clients上一篇ESP32-A2DP构建现代化蓝牙音频系统的架构深度解析下一篇大麦自动抢票教程3 步从环境搭建到参数配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
