# S12 Task System 代码讲解

这一节只讲相对 S11 新增的内容：

**把任务变成可持久化、可依赖、可认领、可完成的任务图。**

---

## 1. 本节新增内容

- `Task` dataclass：任务数据模型。
- `.tasks/`：任务持久化目录。
- `create_task()`：创建任务。
- `save_task()` / `load_task()`：保存和读取任务。
- `list_tasks()` / `get_task()`：查看任务。
- `can_start()`：检查依赖是否完成。
- `claim_task()`：认领任务。
- `complete_task()`：完成任务并提示下游解锁。
- 5 个任务工具：`create_task`、`list_tasks`、`get_task`、`claim_task`、`complete_task`。

---

## 2. Task 数据结构

`Task` 是一个 dataclass：

```python
@dataclass
class Task:
    id: str
    subject: str
    description: str
    status: str
    owner: str | None
    blockedBy: list[str]
```

一条任务保存成 JSON 后大概是：

```python
{
    "id": "task_1234567890_0001",
    "subject": "实现登录页面",
    "description": "完成表单和校验",
    "status": "pending",
    "owner": None,
    "blockedBy": ["task_1234567890_0000"]
}
```

---

## 3. 状态流转

任务状态有三种：

```text
pending -> in_progress -> completed
```

`claim_task()` 做：

```python
pending -> in_progress
owner = "agent"
```

`complete_task()` 做：

```python
in_progress -> completed
```

---

## 4. `blockedBy`

`blockedBy` 是依赖任务 ID 列表：

```python
blockedBy: list[str] = ["task_a", "task_b"]
```

意思是：

```text
当前任务必须等 task_a 和 task_b 都 completed 后才能开始
```

`can_start(task_id)` 会检查所有依赖：

```python
如果依赖任务不存在 -> 不能开始
如果依赖任务不是 completed -> 不能开始
全部完成 -> 可以开始
```

---

## 5. `.tasks/` 持久化

每个任务是一个文件：

```text
.tasks/
  task_1234567890_0001.json
```

这样任务不会只存在内存里，程序重启后仍然能读回来。

---

## 6. 工具层封装

底层函数：

```python
create_task()
claim_task()
complete_task()
```

工具处理器：

```python
run_create_task()
run_claim_task()
run_complete_task()
```

模型真正看到的是工具 schema：

```python
{
    "name": "create_task",
    "input_schema": {...}
}
```

---

## 7. 本节课堂重点

任务系统让 Agent 从“临时执行”进入“可管理工作流”。

有了任务系统，Agent 可以表达：

```python
有哪些任务
谁正在做
哪些被依赖阻塞
哪些已经完成
完成后解锁了什么
```