AI Agent 本质秘密

项目地址 : https://github.com/shareAI-lab/learn-claude-code
Stars : 25.3k ｜ Forks : 4.6k ｜ License: MIT

---

目录

1. 项目概览
2. 核心哲学
3. 整体架构
4. [12 阶段学习路径](#12 阶段学习路径)
5. 关键机制深度解析
6. 设计思路与思考
7. 使用场景
8. 技术栈
9. 与生产级系统的对比
10. 总结与评价

---

1. 项目概览

learn-claude-code 是一个以渐进式教学为核心设计理念的开源项目，旨在通过 12 个递进章节，带领开发者从零构建一个类 Claude Code 的 AI 编程助手 Agent。

项目的核心主张极为简洁，却震撼人心：

"One loop & Bash is all you need."

一个循环 + Bash 工具，就是 AI Agent 的全部秘密。

项目定位

学习曲线定位:
初学者 ──────── 进阶 ──────── 专家
    s01-s02      s03-s08     s09-s12
  (基础循环)    (规划/持久化)  (多智能体)

仓库语言构成

语言	占比	用途
TypeScript	59.7%	Web 交互式学习平台
Python	38.5%	Agent 实现核心逻辑
Other	1.8%	配置、文档等

---

2. 核心哲学

2.1 最小化原则

项目的第一课（s01）用不到 80 行 Python 就实现了一个完整的 AI 编程 Agent，核心是这个 while 循环：

while True:
    response = client.messages.create(model, messages, tools)
    messages.append(assistant_turn)
    if response.stop_reason != "tool_use":
        return          # 模型决定停止
    results = execute_tools(response)
    messages.append(tool_results)  # 结果反馈回模型

这个循环揭示了 LLM Agent 的本质：模型驱动的工具调用循环。

2.2 每课一概念

项目严格遵守"每课只引入一个新概念"的教学原则，每个 session 都有一句醒目的格言：

Session	格言
s01	One loop & Bash is all you need
s03	An agent without a plan drifts
s04	Process isolation gives context isolation for free
s06	The agent can forget strategically and keep working forever
s09	Teammates that can talk to each other
s12	Isolate by directory, coordinate by task ID

2.3 渐进复杂性

循环
工具
任务规划
子 Agent
技能注入
上下文压缩
任务系统
后台任务
Agent 团队
通信协议
自主 Agent
目录隔离

---

3. 整体架构

3.1 仓库结构

learn-claude-code/
├── agents/                  # 核心：12 个渐进式 Python 实现
│   ├── s01_agent_loop.py    # 基础循环
│   ├── s02_tool_use.py      # 工具使用
│   ├── s03_todo_write.py    # 任务规划
│   ├── s04_subagent.py      # 子 Agent
│   ├── s05_skill_loading.py # 技能注入
│   ├── s06_context_compact.py # 上下文压缩
│   ├── s07_task_system.py   # 任务系统
│   ├── s08_background_tasks.py # 后台任务
│   ├── s09_agent_teams.py   # Agent 团队
│   ├── s10_team_protocols.py # 团队协议
│   ├── s11_autonomous_agents.py # 自主 Agent
│   ├── s12_worktree_task_isolation.py # 目录隔离
│   └── s_full.py            # 综合示例（Capstone）
├── docs/
│   ├── en/                  # 英文文档
│   ├── zh/                  # 中文文档
│   └── ja/                  # 日文文档
├── web/                     # Next.js 交互式学习平台
├── skills/                  # 技能知识文件
└── requirements.txt

3.2 分层架构总览

知识层
记忆层
执行层
Agent层
UI层
CLI 交互界面
Next.js Web 平台
Lead Agent\n主控 Agent
Sub Agent\n子 Agent
Teammate Agent\n协作 Agent
工具集\nbash / read / write / edit
Worktree\n隔离执行环境
Background Task\n后台任务
对话历史\nmessages
上下文压缩\n3层压缩策略
任务持久化\n.tasks/*.json
技能文件\nskills/*/SKILL.md
消息总线\n.team/inbox/*.jsonl
历史转录\n.transcripts/*.jsonl

---

4. 12 阶段学习路径

4.1 四大阶段划分

阶段 4：团队 (Teams)
s09\nAgent 团队
s10\n通信协议
s11\n自主 Agent
s12\n目录隔离
阶段 3：持久化 (Persistence)
s07\n任务系统
s08\n后台任务
阶段 2：规划与知识 (Planning & Knowledge)
s03\n任务规划
s04\n子 Agent
s05\n技能加载
s06\n上下文压缩
阶段 1：循环 (The Loop)
s01\n基础循环
s02\n工具使用

4.2 各 Session 详细说明

Session	文件名	核心机制	新增概念	关键格言
s01	agent_loop.py	while 循环 + stop_reason 判断	Agent Loop	One loop & Bash is all you need
s02	tool_use.py	bash/read/write/edit 工具集	Tool Use	工具是 Agent 的手
s03	todo_write.py	TodoWrite 工具 + 任务规划	Planning	An agent without a plan drifts
s04	subagent.py	独立上下文子进程委派	Subagent	Process isolation gives context isolation for free
s05	skill_loading.py	YAML frontmatter 技能文件	Skill Loading	按需注入知识
s06	context_compact.py	3 层压缩（微压缩/自动/手动）	Context Compact	The agent can forget strategically
s07	task_system.py	JSONL 文件持久化任务	Task System	任务即文件
s08	background_tasks.py	后台线程异步执行	Background Tasks	不阻塞 = 更高效
s09	agent_teams.py	MessageBus + 持久 Teammate	Agent Teams	Teammates that can talk
s10	team_protocols.py	shutdown/plan_approval 协议	Team Protocols	协议保障安全关闭
s11	autonomous_agents.py	自主决策循环	Autonomous Agents	自主 = 无需提示
s12	worktree_task_isolation.py	Git worktree 目录隔离	Task Isolation	Isolate by directory

---

5. 关键机制深度解析

5.1 基础 Agent 循环（s01）

这是整个项目的基石。
工具执行器 LLM (Claude) Agent Loop 用户 工具执行器 LLM (Claude) Agent Loop 用户 loop [遍历工具调用] loop [while stop_reason == "tool_use"] 输入 prompt messages.append(user_msg) messages.create(messages, tools) response (tool_use blocks) messages.append(assistant_turn) execute(tool_name, input) tool_result messages.append(tool_results) 输出最终文本

核心安全机制：

• 危险命令黑名单过滤（rm -rf /、sudo、shutdown）
• 120 秒超时保护
• 输出截断（50000 字符）

---

5.2 子 Agent 模式（s04）

核心洞察：进程隔离自带上下文隔离。
共享文件系统
父 Agent (完整历史)
dispatch prompt
summary only
子 Agent (干净上下文)
messages = 全新开始
bash / read / write / edit\n 无 task 工具，防递归
返回: 最后一条文本摘要
messages = 长历史
task 工具
工作目录文件\n两者均可读写

关键设计决策：

1. 子 Agent 不能再派生子 Agent（移除 task 工具）→ 防无限递归
2. 只返回摘要 → 父 Agent 上下文不膨胀
3. 共享文件系统 → 子 Agent 成果可持久化

---

5.3 三层上下文压缩（s06）

这是让 Agent 能"永久工作"的关键机制。
否
否
是
是
第 3 层：手动压缩 (compact tool) --- Agent 主动触发
与 auto_compact 相同流程\n但由 Agent 自主决定时机
第 2 层：自动压缩 (auto_compact) --- 阈值触发
保存完整对话到\n.transcripts/ts_time.jsonl
请求 LLM 生成摘要\n含: 已完成/当前状态/关键决策
用 2 条消息替换全部历史\nuser： 摘要 + assistant: 了解
第 1 层：微压缩 (micro_compact) --- 每轮执行
扫描所有 tool_result\n保留最近 3 条\n其余替换为占位符\n如: Previous: used bash
每次 LLM 调用前
tokens > 50000?
调用 LLM
是否调用了\ncompact 工具?
下一轮

三层设计的意义：

• 第 1 层 是静默的、无损的 → 减少噪声，不丢核心信息
• 第 2 层 是被动的、有损的 → 超阈值自动触发，全局压缩
• 第 3 层 是主动的、智能的 → Agent 自己判断何时需要"清理思绪"

---

5.4 技能注入系统（s05）

两层设计：避免系统提示词膨胀的同时保留完整知识。
按需注入 (重量)
启动时解析
Agent 调用 load_skill
系统提示词 (轻量)
skill-a: 简短描述 (~100 tokens)\nskill-b: 简短描述\n...
磁盘: skills/
skill-a/SKILL.md\n---\nname: skill-a\ndesc: 简短描述\n---\n\n完整知识体\n(可能很长)
skill-b/SKILL.md\n...
load_skill('skill-a') 调用后\n完整知识体作为 tool_result\n注入当前上下文

SKILL.md 文件格式：

---
name: python-debugging
description: Python 调试技巧和工具
triggers: [debug, traceback, error, exception]
---

# Python 调试完整指南
... (完整知识，不限长度)

---

5.5 多 Agent 团队通信（s09/s10）

消息总线 (文件系统)
Lead Agent (主线程)
send_message('bob', content)
broadcast(content)
broadcast(content)
drain & read
spawn_teammate('alice', 'coder', prompt)
send_message('lead', summary)
send_message('alice', task)
update status
Bob Agent (独立线程)
teammate_loop
status: idle/working
Alice Agent (独立线程)
teammate_loop\nfor _ in range 50
status: idle/working/shutdown
agent_loop
读取 lead.jsonl inbox
9 个工具:\nbash / read / write / edit\nspawn_teammate / list_teammates\nsend_message / read_inbox / broadcast
.team/inbox/alice.jsonl
.team/inbox/bob.jsonl
.team/inbox/lead.jsonl
.team/config.json\nmembers: name, role, status

5 种消息类型：

消息类型	说明	使用阶段
message	普通点对点消息	s09+
broadcast	广播给所有成员	s09+
shutdown_request	请求优雅关闭	s10
shutdown_response	批准/拒绝关闭	s10
plan_approval_response	批准/拒绝计划	s10

Subagent vs Teammate 对比：

维度	Subagent (s04)	Teammate (s09)
生命周期	生 → 执行 → 销毁	生 → 工作 → 空闲 → 工作 → 关闭
上下文	每次全新	持久保留
通信	单向（父发子）	双向（任意方向）
并发	串行	真正并行（Thread）
协调	无	通过 MessageBus

---

5.6 Worktree 任务隔离（s12）

可观测面 (EventBus)
执行面 (WorktreeManager)
控制面 (TaskManager)
bind_worktree
bind_worktree
emit events
emit events
register
.tasks/task_abc.json\n{id, subject, status, owner, worktree}
.tasks/task_def.json
.worktrees/feature-auth/\n独立 git 分支: wt/feature-auth
.worktrees/fix-bug/\n独立 git 分支: wt/fix-bug
.worktrees/index.json\n所有 worktree 注册表
.worktrees/events.jsonl\n追加式事件日志\ncreated/removed/task_done

隔离保证：

• 路径限制：命令只在分配的 worktree 目录内执行
• 任务-worktree 绑定：防止跨目录污染
• 追加式事件日志：可重放历史，便于调试

---

6. 设计思路与思考

6.1 为什么是"One Loop"？

作者对 Agent 本质做了极其精炼的抽象：LLM Agent 不过是一个反馈控制系统。

传统程序:          AI Agent:
Input → Logic → Output    Input → LLM → Tool → LLM → ... → Output

将工具调用结果"喂回"模型，让模型自己决定下一步------这个"反馈"思想是整个项目的哲学根基。

6.2 为什么选择文件系统作为通信基础？

s07-s12 大量使用文件（JSONL、JSON、worktree）作为持久化和通信媒介，而非数据库或消息队列，这是一个深思熟虑的设计选择：

文件系统的优势：

• 零依赖：无需 Redis、PostgreSQL、RabbitMQ
• 可调试 ：直接 cat 查看任何状态
• 天然持久：进程崩溃不丢数据
• Git 友好：worktree 天然支持版本控制

6.3 上下文压缩的本质

s06 的三层压缩揭示了一个深刻的类比：

Agent 的上下文压缩 ≈ 人类的记忆机制

• 微压缩 ≈ 工作记忆的衰减（不重要的细节淡出）
• 自动压缩 ≈ 睡眠期间的记忆巩固（全局摘要替代细节）
• 手动压缩 ≈ 有意识的思维整理（主动清空冗余）

6.4 子 Agent 的哲学

s04 的设计暗含一个重要洞见：上下文即认知资源。

子 Agent 拥有干净的上下文，就像派遣一个"不带任何先入为主偏见"的人去调查------它能更专注、更客观地处理特定子任务，而不被父 Agent 的历史包袱干扰。

6.5 Agent 团队的涌现行为

s09-s10 的多 Agent 系统表明：当 Agent 拥有稳定的通信机制（文件 inbox）+ 持久身份（name/role/status），就可能出现涌现式协作行为------类似人类团队的分工、汇报、协商。

这正是从"工具调用"到"社会性 AI"的临界点。

6.6 设计的局限性与取舍

诚实地说，该项目也存在一些教学优先于生产就绪的取舍：

领域	教学版简化	生产级应对方案
并发	threading.Thread	asyncio / 进程池
消息总线	JSONL 文件	Redis Pub/Sub / Kafka
错误恢复	简单 try/except	指数退避重试 + 死信队列
安全	简单黑名单	Sandbox / seccomp / 容器
监控	print 日志	OpenTelemetry / Prometheus

---

7. 使用场景

7.1 教学与学习

Python 基础
有 LLM 经验
团队负责人
想学 AI Agent 开发
技术背景?
从 s01 开始\n按序学习
从 s04 开始\n聚焦高级机制
从 s09 开始\n理解多 Agent 协调

适合人群：

• 想理解 Claude Code / Cursor / Devin 工作原理的开发者
• 想从头实现 AI Agent 的学生和研究者
• 想为团队建立 AI Agent 开发规范的工程师

7.2 作为 Agent 框架原型

每个 session 都是独立的、可扩展的模板，可以直接基于任意 session 构建定制 Agent：

# 基于 s09（团队）+ 自定义工具，构建代码审查机器人
class CodeReviewTeam(TeammateManager):
    def add_reviewer(self, language: str):
        return self.spawn(
            name=f"{language}-reviewer",
            role=f"专注 {language} 的代码审查专家",
            prompt="审查所有 PR，输出结构化评论到 reviews/..."
        )

7.3 理解生产级系统

项目关联两个生产实现（Kode Agent CLI 和 Kode Agent SDK），learn-claude-code 是它们的"教学型精简版"，学完 12 个 session 后，可以更快读懂真实系统的代码。

7.4 多语言文档的覆盖场景

项目提供英/中/日三语文档，面向：

• 中文开发者社区（zh 文档）
• 国际开源贡献者（en 文档）
• 日本 AI 研究和工程社区（ja 文档）

---

8. 技术栈

8.1 核心依赖

基础设施
Web平台
Python核心
anthropic SDK\nLLM API 调用
python-dotenv\n环境变量管理
subprocess / threading\nPython 标准库
Next.js\n交互式学习平台
TypeScript\n前端类型安全
Git Worktree\n任务隔离
文件系统\nJSONL 持久化
learn-claude-code 核心
交互平台

8.2 环境配置

# .env 配置
ANTHROPIC_BASE_URL=https://api.anthropic.com  # 或自定义 base URL
MODEL_ID=claude-opus-4-6                       # 或其他兼容模型

# 启动任意 session
python agents/s01_agent_loop.py   # 最简 Agent
python agents/s09_agent_teams.py  # 多 Agent 团队
python agents/s_full.py           # 完整综合版

---

9. 与生产级系统的对比

9.1 与 Claude Code 的概念对应

learn-claude-code	Claude Code 对应功能
s01: agent_loop	核心 REPL 循环
s02: tool_use	bash / read / write / edit 工具
s03: todo_write	TodoWrite 工具
s04: subagent	Task 工具（子 Agent）
s05: skill_loading	SKILL.md 技能系统
s06: context_compact	上下文压缩与 /compact 命令
s08: background_tasks	后台 Agent 任务
s09-s10: agent_teams	多 Agent 协调框架
s12: worktree_isolation	Git Worktree 隔离执行

9.2 演化路线图

learn-claude-code\n教学精简版
Kode Agent CLI\n生产开源版
Kode Agent SDK\n可嵌入库
claw0\n常驻助手 + heartbeat/cron

---

10. 总结与评价

10.1 项目亮点

极致的教学设计 --- 每课一个概念，不多不少。从 s01 的 80 行到 s12 的复杂团队协作，复杂度曲线非常平滑。

理念领先于工具 --- 项目不依赖 LangChain、AutoGen 等框架，直接使用 Anthropic SDK 裸写，让学习者真正理解底层机制，而不是框架 API。

实用性强 --- 每个 session 都是可直接运行的完整程序，不是代码片段，适合动手实验。

多语言覆盖 --- 中/英/日文档展示了良好的国际化意识，这也是 25k star 的原因之一。

10.2 核心洞见总结

Agent 的三大基石:
┌─────────────────────────────────────────────────────┐
│  1. 循环 (Loop)         --- 模型决定工具 → 执行 → 反馈   │
│  2. 记忆 (Memory)       --- 历史 + 压缩 + 技能注入        │
│  3. 协作 (Collaboration) --- 子 Agent + 团队 + 隔离       │
└─────────────────────────────────────────────────────┘

10.3 学习建议

对于不同背景的读者，推荐的阅读路径：

快速了解 Agent 原理（1-2小时）→ 精读 s01、s04、s06

系统学习 Agent 开发（1-2天）→ 按序完成 s01-s08

掌握多 Agent 系统（完整学习）→ s01-s12 + 阅读 s_full.py

想基于此构建产品（进阶）→ 学完后阅读 Kode Agent CLI 源码

---

结语 ：learn-claude-code 不仅是一个教程，更是一份关于"AI Agent 本质"的思考结晶。它告诉我们，复杂的 AI 系统最终都可以还原为几个简单的模式：循环、工具、记忆、隔离、通信。掌握这些模式，你就掌握了构建任何 AI Agent 的基础。

---