🤖 AI 智能体版本演进详解 (Python 小白版)
从 s01 到 s12，一步步看懂 Claude Code 是如何构建的
📊 版本总览
s01 ──→ s02 ──→ s03 ──→ s04 ──→ s05 ──→ s06 ──→ s07 ──→ s08 ──→ s09 ──→ s10 ──→ s11 ──→ s12
│ │ │ │ │ │ │ │ │ │ │ │
基础 工具 任务 子智能 技能 上下文 任务 后台 团队 团队 自主 工作区
循环 系统 规划 体 加载 压缩 系统 任务 协作 协议 智能体 隔离
🎯 s01: 基础循环 - "一切的开始"
代码量: 106 行 | 工具数: 1 个
💡 核心思想
就像打乒乓球一样，AI 和用户来回对话，直到 AI 觉得"我说完了"。
🔑 关键代码（只有 20 行核心逻辑）
def agent_loop(messages):
while True: # 无限循环
# 1. 问 AI：你想干嘛？
response = client.messages.create(
model=MODEL, messages=messages, tools=TOOLS
)
messages.append({"role": "assistant", "content": response.content})
# 2. AI 说"我说完了"，就退出
if response.stop_reason != "tool_use":
return
# 3. AI 想用工具，执行它
results = []
for block in response.content:
if block.type == "tool_use":
output = run_bash(block.input["command"]) # 执行命令
results.append({"type": "tool_result", "content": output})
# 4. 把结果告诉 AI，继续循环
messages.append({"role": "user", "content": results})
🎓 小白理解
想象你在和一个助手对话：
- 你: "帮我查一下文件"
- 助手: "我需要用 bash 工具执行
ls命令"（停止原因 = tool_use） - 系统: 执行
ls，得到结果 - 系统: "这是结果：[文件列表]"
- 助手: "找到了，有这些文件..."（停止原因 = stop）→ 结束
📈 相比上一个版本
这是第一个版本，没有上一个版本 😄
🛠️ s02: 工具系统 - "给 AI 更多'手脚'"
代码量: 148 行 | 工具数: 4 个 | 新增: +42 行
💡 核心思想
s01 只有 bash 一个工具，太局限了。现在给 AI 添加读写文件的能力。
🔑 新增内容
# 工具调度表：菜名 → 厨师
TOOL_HANDLERS = {
"bash": lambda **kw: run_bash(kw["command"]),
"read_file": lambda **kw: run_read(kw["path"]),
"write_file": lambda **kw: run_write(kw["path"], kw["content"]),
"edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
}
🎓 小白理解
就像给助手配备了更多工具：
- s01: 只有一把螺丝刀（bash）
- s02: 多了扳手、锤子、钳子（读、写、改文件）
关键 insight: 循环本身一点没变！只是菜单上多了几道菜。
📈 相比 s01 的改动
| 方面 | s01 | s02 | 变化 |
|---|---|---|---|
| 工具数 | 1 | 4 | +3 |
| 核心循环 | ✅ | ✅ 完全一样 | 无变化 |
| 新增能力 | 只能执行命令 | 能读写文件了 | 质的飞跃 |
📝 s03: 任务规划 - "让 AI 学会做计划"
代码量: 209 行 | 工具数: 5 个 | 新增: +61 行
💡 核心思想
没有计划的 AI 容易"跑偏"。让 AI 先列 TODO 清单，再执行。
🔑 新增内容
class TodoManager:
"""就像做项目前先写 TODO 清单"""
def update(self, items: list) -> str:
# 验证：最多 20 个任务
# 验证：只能有 1 个 "进行中" 的任务
# 返回：格式化的任务列表
def render(self) -> str:
# 显示：[ ] 待完成 [>] 进行中 [x] 已完成
唠叨提醒: 如果 AI 3 轮都不更新 TODO，系统会提醒它："Update your todos."
🎓 小白理解
就像你要打扫房间，先列个清单：
- ☐ 整理书桌
- ☐ 扫地
- ☐ 倒垃圾
做完一项勾一项，不会遗漏！
📈 相比 s02 的改动
| 方面 | s02 | s03 | 变化 |
|---|---|---|---|
| 工具数 | 4 | 5 | +1 (todo) |
| 新增能力 | 无规划 | 有 TODO 管理 | 能跟踪进度 |
| 智能程度 | 走一步看一步 | 有计划有目标 | 更聪明 |
👶 s04: 子智能体 - "一个人忙不过来？找帮手"
代码量: 183 行 | 工具数: 5 个 | 新增: -26 行（但功能更强）
💡 核心思想
大任务拆成小任务，每个小任务给一个"干净的"新智能体处理，只返回摘要。
🔑 新增内容
def run_subagent(prompt: str) -> str:
"""创建一个子智能体，给它新的大脑（messages=[]）"""
sub_messages = [{"role": "user", "content": prompt}]
# 子智能体自己循环最多 30 轮
for _ in range(30):
response = client.messages.create(...)
...
# 只返回最终结果，子智能体的"记忆"被丢弃
return summary
🎓 小白理解
想象你是项目经理：
- s03: 你自己做所有事，脑子越来越乱
- s04: 你把任务分给临时工，他们做完给你汇报，你脑子保持清醒
关键 insight: 子智能体有独立的"大脑"（messages），不会污染主智能体的上下文。
📈 相比 s03 的改动
| 方面 | s03 | s04 | 变化 |
|---|---|---|---|
| 智能体数 | 1 | 1+N | 支持子智能体 |
| 上下文 | 越来越长 | 主智能体保持清爽 | 更优雅 |
| 任务处理 | 自己扛 | 能外包 | 更灵活 |
📚 s05: 技能加载 - "按需学习，不要一次性塞太多"
代码量: 225 行 | 工具数: 5 个 | 新增: +42 行
💡 核心思想
不要把所有知识都塞进系统提示词（会太长），而是让 AI 按需加载。
🔑 新增内容
class SkillLoader:
"""两层加载系统"""
# 第一层：系统提示词里只放技能名称（便宜）
# "Skills available: pdf, code-review"
def get_content(self, name: str) -> str:
# 第二层：AI 调用 load_skill("pdf") 时才加载完整内容
return f"<skill name='{name}'>{full_content}</skill>"
🎓 小白理解
就像你去图书馆：
- s04: 把所有书都背在身上（太重了！）
- s05: 身上只带目录，需要哪本再去拿
关键 insight: 只在需要时加载知识，避免上下文爆炸。
📈 相比 s04 的改动
| 方面 | s04 | s05 | 变化 |
|---|---|---|---|
| 知识管理 | 无 | 技能系统 | 更专业 |
| 上下文长度 | 可能很长 | 按需加载 | 更高效 |
| 学习方式 | 一次性灌输 | 按需学习 | 更智能 |
🗜️ s06: 上下文压缩 - "让 AI 能永远工作下去"
代码量: 247 行 | 工具数: 6 个 | 新增: +22 行
💡 核心思想
对话太长会爆，需要三层压缩策略让 AI 能无限工作。
🔑 新增内容
# 三层压缩系统
def micro_compact(messages):
"""第一层：微观压缩
把旧的工具结果替换成占位符 '[Previous: used bash]'
"""
def auto_compact(messages):
"""第二层：自动压缩
如果超过 50000 token，保存完整记录到文件，
然后让 AI 总结，只保留摘要
"""
# 第三层：手动压缩
# AI 可以调用 compact 工具主动触发压缩
🎓 小白理解
就像你写日记：
- 第一层: 把旧日记收进抽屉，只留最近 3 天的在桌上
- 第二层: 桌子满了，写个摘要，把详细内容存档案室
- 第三层: 你觉得该整理了，主动收拾一下
📈 相比 s05 的改动
| 方面 | s05 | s06 | 变化 |
|---|---|---|---|
| 上下文管理 | 无限增长 | 三层压缩 | 能无限工作 |
| 新工具 | 无 | compact | 主动压缩 |
| 持久性 | 会话结束就丢 | 保存到文件 | 可恢复 |
📋 s07: 任务系统 - "把任务存到硬盘上"
代码量: 247 行 | 工具数: 8 个 | 新增: 0 行（重构）
💡 核心思想
任务要持久化到磁盘，即使上下文压缩了，任务还在。
🔑 新增内容
class TaskManager:
"""任务存到 .tasks/task_1.json 文件里"""
def create(self, subject: str) -> str:
# 创建 task_1.json
def update(self, task_id: int, status: str):
# 更新状态，支持依赖关系
def _clear_dependency(self, completed_id: int):
# 任务 A 完成了，解除任务 B 的阻塞
依赖关系: 任务 B 被任务 A 阻塞，A 完成后 B 才能开始。
🎓 小白理解
就像项目管理系统：
- s06: 任务只在脑子里，忘了就没了
- s07: 任务写在白板上，谁都能看到，不会丢
📈 相比 s06 的改动
| 方面 | s06 | s07 | 变化 |
|---|---|---|---|
| 任务存储 | 内存（易失） | 磁盘文件（持久） | 更可靠 |
| 依赖管理 | 无 | 支持 blockedBy/blocks | 更强大 |
| 任务工具 | 1 个 (todo) | 4 个 (CRUD) | 更完善 |
⏳ s08: 后台任务 - "让 AI 能'多线程'工作"
代码量: 233 行 | 工具数: 6 个 | 新增: -14 行（但功能更强）
💡 核心思想
慢操作（比如编译）不应该阻塞 AI，让它们在后台跑。
🔑 新增内容
class BackgroundManager:
"""后台任务管理器"""
def run(self, command: str) -> str:
# 启动新线程执行命令
# 立即返回 task_id，不等待
def drain_notifications(self) -> list:
# 在每次 LLM 调用前，检查完成的任务
# 把结果注入到对话中
🎓 小白理解
就像你做饭：
- s07: 你站在锅前等水烧开（浪费时间）
- s08: 你让水在后台烧，同时切菜，水开了通知你
📈 相比 s07 的改动
| 方面 | s07 | s08 | 变化 |
|---|---|---|---|
| 执行方式 | 同步阻塞 | 异步非阻塞 | 更高效 |
| 并发能力 | 单线程 | 多线程 | 并行处理 |
| 新工具 | 任务管理 | background_run/check | 后台执行 |
👥 s09: 团队协作 - "一个人干不完，组个队"
代码量: 405 行 | 工具数: 9 个 | 新增: +172 行
💡 核心思想
多个智能体同时工作，通过"邮箱"（JSONL 文件）通信。
🔑 新增内容
class MessageBus:
"""消息总线：每个智能体有自己的 .team/inbox/alice.jsonl"""
def send(self, sender: str, to: str, content: str):
# 往 alice.jsonl 追加一条消息
def read_inbox(self, name: str) -> list:
# 读取并清空邮箱
class TeammateManager:
"""队友管理器"""
def spawn(self, name: str, role: str, prompt: str):
# 创建新线程运行子智能体
# 子智能体持久存在，不是用完即弃
🎓 小白理解
就像办公室协作：
- s08: 你一个人干所有活
- s09: 你招了几个员工（alice、bob），每人一个邮箱，你给他们在邮箱里派活
关键区别: s04 的子智能体是"临时工"，用完就走；s09 的队友是"正式员工"，一直在。
📈 相比 s08 的改动
| 方面 | s08 | s09 | 变化 |
|---|---|---|---|
| 智能体数 | 1 | N | 团队协作 |
| 通信方式 | 无 | JSONL 邮箱 | 异步通信 |
| 生命周期 | 单次 | 持久 | 长期协作 |
📜 s10: 团队协议 - "团队需要规矩"
代码量: 486 行 | 工具数: 12 个 | 新增: +81 行
💡 核心思想
队友之间需要标准协议：优雅关闭、计划审批。
🔑 新增内容
# 两种协议，都用 request_id 关联
# 1. 优雅关闭协议
shutdown_request -> shutdown_response
# 队长请求关闭 -> 队友同意/拒绝
# 2. 计划审批协议
plan_approval -> plan_approval_response
# 队友提交计划 -> 队长批准/拒绝
🎓 小白理解
就像公司流程：
-
s09: 大家各自干活，有点乱
-
s10:
- 你想下班？先打申请，老板批准才能走
- 要做大项目？先写计划，老板批准才能做
📈 相比 s09 的改动
| 方面 | s09 | s10 | 变化 |
|---|---|---|---|
| 协议 | 无 | shutdown + plan approval | 有规矩 |
| 消息类型 | 3 种 | 5 种 | 更丰富 |
| 控制能力 | 弱 | 强 | 可管理 |
🤖 s11: 自主智能体 - "让 AI 自己找活干"
代码量: 578 行 | 工具数: 14 个 | 新增: +92 行
💡 核心思想
队友不用等派活，空闲时自己扫描任务板，认领任务。
🔑 新增内容
def _loop(self, name: str, role: str, prompt: str):
while True:
# 1. 工作阶段：正常干活
for _ in range(50):
...
if idle_requested:
break # 进入空闲阶段
# 2. 空闲阶段：每 5 秒检查一次
for _ in range(polls):
time.sleep(5)
# 检查邮箱有新消息？
if inbox:
resume = True
break
# 扫描任务板，有未认领任务？
unclaimed = scan_unclaimed_tasks()
if unclaimed:
claim_task(task["id"], name)
resume = True
break
if not resume:
shutdown # 60 秒没活干，下班
🎓 小白理解
就像员工从"被动"变"主动"：
- s10: "老板，我干完了，还有啥活？"
- s11: "老板，我看任务板上有个活没人干，我认领了开始做"
关键 insight: AI 从"被驱动"变成"自驱动"。
📈 相比 s10 的改动
| 方面 | s10 | s11 | 变化 |
|---|---|---|---|
| 工作模式 | 被动派活 | 主动认领 | 更自主 |
| 空闲处理 | 无 | 扫描+认领 | 更智能 |
| 生命周期 | 手动管理 | 自动关机 | 更省心 |
🏗️ s12: 工作区隔离 - "各干各的，互不干扰"
代码量: 780 行 | 工具数: 16 个 | 新增: +202 行
💡 核心思想
用 Git Worktree 创建独立工作目录，任务和目录绑定，并行开发不冲突。
🔑 新增内容
class WorktreeManager:
"""Git 工作区管理"""
def create(self, name: str, task_id: int):
# git worktree add -b wt/name .worktrees/name
# 绑定到任务
def run(self, name: str, command: str):
# 在指定工作区执行命令
def remove(self, name: str, complete_task: bool):
# 删除工作区，可选标记任务完成
class EventBus:
"""事件总线：记录所有操作到 .worktrees/events.jsonl"""
🎓 小白理解
就像软件公司：
- s11: 大家都在同一个代码库改，容易冲突
- s12: 每个人在自己的分支（工作区）开发，完成后合并
关键 insight: 任务管目标，工作区管目录，通过 ID 绑定。
📈 相比 s11 的改动
| 方面 | s11 | s12 | 变化 |
|---|---|---|---|
| 工作目录 | 共享 | 隔离 | 不冲突 |
| 版本控制 | 无 | Git Worktree | 更专业 |
| 可追溯性 | 弱 | EventBus | 可审计 |
📊 完整对比表
| 版本 | 核心功能 | 代码行 | 工具数 | 关键改进 |
|---|---|---|---|---|
| s01 | 基础循环 | 106 | 1 | 万事开头难 |
| s02 | 工具系统 | 148 | 4 | 能读写文件 |
| s03 | 任务规划 | 209 | 5 | 有 TODO 管理 |
| s04 | 子智能体 | 183 | 5 | 任务外包 |
| s05 | 技能加载 | 225 | 5 | 按需学习 |
| s06 | 上下文压缩 | 247 | 6 | 无限工作 |
| s07 | 任务系统 | 247 | 8 | 持久化存储 |
| s08 | 后台任务 | 233 | 6 | 异步执行 |
| s09 | 团队协作 | 405 | 9 | 多智能体 |
| s10 | 团队协议 | 486 | 12 | 标准流程 |
| s11 | 自主智能体 | 578 | 14 | 自驱动 |
| s12 | 工作区隔离 | 780 | 16 | 完整系统 |
🎯 学习建议
第一阶段：理解核心（1-2天）
- s01 → 搞懂循环是怎么回事
- s02 → 理解工具是如何被调度的
- s03 → 学会让 AI 做计划
第二阶段：进阶功能（2-3天）
- s04-s06 → 子智能体、技能加载、上下文管理
- s07-s08 → 任务系统、后台任务
第三阶段：团队协作（3-5天）
- s09-s12 → 多智能体协作、工作区隔离
第四阶段：实战
- s_full.py → 看所有功能如何整合
- 尝试修改代码，添加自己的工具
🌟 一句话总结每个版本
- s01: "一个循环走天下"
- s02: "工具多了路好走"
- s03: "有计划不跑偏"
- s04: "大事化小，小事外包"
- s05: "按需学习，不背书包"
- s06: "忘记该忘的，记住该记的"
- s07: "好记性不如烂笔头（存硬盘）"
- s08: "别傻等，干别的去"
- s09: "人多力量大"
- s10: "无规矩不成方圆"
- s11: "主动找活干"
- s12: "各干各的，最后合并"
现在就开始吧！ 从 python agents/s01_agent_loop.py 开始你的 AI 智能体之旅 🚀
