---
title: Todo 会话任务系统
created: 2026-04-14
updated: 2026-04-14
type: entity
tags: [agent, runtime, tool]
sources: [packages/backend/src/modules/netaclaw/runtime/todo_store.ts, packages/backend/src/modules/netaclaw/tools/builtin/todo.ts]
---

# Todo 会话任务系统

Agent 会话级的任务规划和跟踪机制，Agent 通过 `todo` 工具管理任务列表，前端实时展示进度。

## 数据结构

```typescript
interface TodoItem {
  id: string;
  content: string;
  status: 'pending' | 'in_progress' | 'completed' | 'cancelled';
}
```

## TodoStore（runtime/todo_store.ts）

每个 Agent 会话创建一个 TodoStore 实例。

| 方法 | 功能 |
|------|------|
| `write(todos, merge)` | 写入 todo 列表（merge=false 全量替换，merge=true 增量更新） |
| `read()` | 读取完整列表 |
| `hasItems()` | 检查是否有任务 |
| `getSummary()` | 统计摘要（total/pending/in_progress/completed/cancelled） |
| `formatForInjection()` | 格式化为上下文注入（仅保留 pending + in_progress） |
| `hydrateFromHistory()` | 从历史消息恢复 todo 状态 |

## 集成点

- **Agent 运行时**：自动创建 TodoStore 实例
- **todo 工具**：Agent 通过 tool_use 调用管理任务
- **上下文压缩**：压缩后保留活跃任务（formatForInjection）
- **WebSocket**：推送 `todo_update` 事件到前端
- **前端**：`todo-card.vue` 组件展示任务列表和进度

## 相关页面

- [[tool-system]] — todo 工具定义
- [[agent-runtime]] — 运行时集成
- [[websocket-gateway]] — todo_update 事件推送