# S17 Autonomous Agents 代码讲解

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

**队友 Agent 不再只等 Lead 指令，而是进入 IDLE 状态后可以自己轮询任务板并自动认领任务。**

---

## 1. 本节新增内容

- `scan_unclaimed_tasks()`：扫描可认领任务。
- `idle_poll()`：队友空闲时轮询收件箱和任务板。
- 队友生命周期：`WORK -> IDLE -> WORK / SHUTDOWN`。
- 队友新增任务工具：`list_tasks`、`claim_task`、`complete_task`。
- 身份重新注入：压缩或历史变短后，让队友记住自己是谁。
- `consume_lead_inbox()`：Lead 统一处理协议响应和普通消息。

---

## 2. 生命周期

队友 Agent 不再是“跑 10 轮就结束”。

它变成：

```text
WORK
  ↓ 没有 tool_use / 当前任务结束
IDLE
  ↓ 有收件箱消息
WORK
  ↓ 有可认领任务
WORK
  ↓ 收到 shutdown 或超时
SHUTDOWN
```

---

## 3. `scan_unclaimed_tasks()`

作用：从 `.tasks/` 里找可以自动认领的任务。

筛选条件：

```python
status == "pending"
owner 为空
can_start(task["id"]) 为 True
```

返回结构：

```python
list[dict]
```

例如：

```python
[
    {
        "id": "task_001",
        "subject": "补充测试",
        "status": "pending",
        "owner": None,
        "blockedBy": []
    }
]
```

---

## 4. `idle_poll(name, messages, role)`

作用：队友空闲时做轮询。

每隔几秒检查：

```python
1. 收件箱有没有消息
2. 有没有 shutdown_request
3. 任务板上有没有可认领任务
```

返回值是：

```python
"work"      # 有新消息或认领到任务，回到工作状态
"shutdown"  # 收到关闭请求
"timeout"   # 空闲太久，结束
```

---

## 5. 队友新增任务工具

S17 中，队友也能操作任务板：

```text
list_tasks
claim_task
complete_task
```

这意味着 Lead 不一定要明确分配任务。

队友可以：

```python
查看任务板
认领未分配任务
完成后标记 completed
```

---

## 6. 身份重新注入

代码里有一段：

```python
if len(messages) <= 3:
    messages.insert(0, {
        "role": "user",
        "content": "<identity>你是 ...</identity>"
    })
```

它的作用是：当上下文很短或被压缩后，重新提醒队友自己的身份和角色。

对于长期运行 Agent，这很重要。

---

## 7. Lead 的收件箱消费

`consume_lead_inbox()` 会：

```python
读取 lead 的收件箱
如果是协议响应，就调用 match_response()
返回所有消息，供 Agent 注入上下文
```

这样 Lead 不会漏掉队友的计划审批、关闭确认、普通结果消息。

---

## 8. 本节课堂重点

Autonomous Agent 的关键不是“模型自己活了”，而是 Harness 加了生命周期：

```python
WORK：执行当前任务
IDLE：轮询消息和任务板
AUTO-CLAIM：发现任务后自动认领
SHUTDOWN：收到协议或超时后退出
```

所谓自主性，本质上是：

```python
循环 + 状态机 + 任务板 + 收件箱 + 工具权限
```