# Agent Execution - 执行追踪系统

## 职责

执行追踪系统负责记录和可视化 Agent 的执行过程：

1. **数据模型** (`models.py`)
   - `Trace` - 一次完整的执行轨迹
   - `Step` - 执行过程中的一个原子操作（形成树结构）
   - `StepType` - 步骤类型（思考、动作、结果等）
   - `Status` - 步骤状态（计划中、执行中、完成、失败）

2. **存储接口** (`protocols.py`, `store.py`)
   - `TraceStore` - Trace 存储接口协议
   - `MemoryTraceStore` - 内存实现（用于测试）

3. **可视化工具** (`tree_dump.py`)
   - `dump_tree()` - 输出文本格式的 step tree
   - `dump_markdown()` - 输出 markdown 格式（可折叠）
   - `dump_json()` - 输出 JSON 格式

4. **API 和实时推送** (`api.py`, `websocket.py`)
   - RESTful API - 查询 Trace 和 Step
   - WebSocket - 实时推送执行更新

## 模块边界

- **只依赖**：core（事件系统）
- **被依赖**：core.runner（记录 trace）
- **独立开发**：可视化、API、WebSocket 可独立迭代

## 使用示例

```python
from agent.execution import MemoryTraceStore, Trace, Step, dump_tree

# 创建存储
store = MemoryTraceStore()

# 创建 Trace
trace = Trace.create(mode="agent", task="Complete task")
trace_id = await store.create_trace(trace)

# 添加 Step
step = Step.create(
    trace_id=trace_id,
    step_type="thought",
    description="Analyzing task"
)
await store.add_step(step)

# 可视化
trace = await store.get_trace(trace_id)
steps = await store.get_trace_steps(trace_id)
dump_tree(trace, steps)
```

## 文件说明

- `models.py` - Trace 和 Step 数据模型
- `protocols.py` - TraceStore 接口定义
- `store.py` - MemoryTraceStore 实现
- `tree_dump.py` - Step tree 可视化工具
- `api.py` - RESTful API（可选，需要 FastAPI）
- `websocket.py` - WebSocket 推送（可选，需要 FastAPI）
- `__init__.py` - 模块导出

## 适合分工

- **算法同事**：负责 `tree_dump.py` 可视化优化
- **后端同事**：负责 `api.py` 和 `websocket.py` 开发