shareAI-lab/learn-claude-code
GitHub: shareAI-lab/learn-claude-code
一个从 0 到 1 教学 Claude Code 类 Agent 核心架构的递进式学习仓库，覆盖从基础循环到多 Agent 协作的完整心智模型。
Stars: 20096 | Forks: 4024
# 学习 Claude Code —— 从 0 到 1 构建一个纳米级 Claude Code 类 Agent
[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
```
THE AGENT PATTERN
=================
User --> messages[] --> LLM --> response
|
stop_reason == "tool_use"?
/ \
yes no
| |
execute tools return text
append results
loop back -----------------> messages[]
That's the minimal loop. Every AI coding agent needs this loop.
Production agents add policy, permissions, and lifecycle layers.
```
**12 个递进式 Session，从简单循环到隔离的自主执行。**
**每个 Session 增加一个机制。每个机制有一个座右铭。**
## 核心模式
```
def agent_loop(messages):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM,
messages=messages, tools=TOOLS,
)
messages.append({"role": "assistant",
"content": response.content})
if response.stop_reason != "tool_use":
return
results = []
for block in response.content:
if block.type == "tool_use":
output = TOOL_HANDLERS[block.name](**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})
```
每个 Session 在此循环之上叠加一个机制 —— 且不改变循环本身。
## 范围（重要）
本仓库是一个从 0 到 1 的学习项目，旨在构建一个纳米级 Claude Code 类 Agent。
它有意简化或省略了一些生产环境机制：
- 完整的事件/钩子总线（例如 PreToolUse、SessionStart/End、ConfigChange）。
s12 仅包含一个用于教学的最小化仅追加生命周期事件流。
- 基于规则的权限治理和信任工作流
- Session 生命周期控制（恢复/分叉）和高级 worktree 生命周期控制
- 完整的 MCP 运行时细节（传输/OAuth/资源订阅/轮询）
请将本仓库中的团队 JSONL 邮箱协议视为一种教学实现，而非对任何特定生产环境内部机制的断言。
## 快速开始
```
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env # Edit .env with your ANTHROPIC_API_KEY
python agents/s01_agent_loop.py # Start here
python agents/s12_worktree_task_isolation.py # Full progression endpoint
python agents/s_full.py # Capstone: all mechanisms combined
```
### Web 平台
交互式可视化、单步图表、源码查看器和文档。
```
cd web && npm install && npm run dev # http://localhost:3000
```
## 学习路径
```
Phase 1: THE LOOP Phase 2: PLANNING & KNOWLEDGE
================== ==============================
s01 The Agent Loop [1] s03 TodoWrite [5]
while + stop_reason TodoManager + nag reminder
| |
+-> s02 Tool Use [4] s04 Subagents [5]
dispatch map: name->handler fresh messages[] per child
|
s05 Skills [5]
SKILL.md via tool_result
|
s06 Context Compact [5]
3-layer compression
Phase 3: PERSISTENCE Phase 4: TEAMS
================== =====================
s07 Tasks [8] s09 Agent Teams [9]
file-based CRUD + deps graph teammates + JSONL mailboxes
| |
s08 Background Tasks [6] s10 Team Protocols [12]
daemon threads + notify queue shutdown + plan approval FSM
|
s11 Autonomous Agents [14]
idle cycle + auto-claim
|
s12 Worktree Isolation [16]
task coordination + optional isolated execution lanes
[N] = number of tools
```
## 架构
```
learn-claude-code/
|
|-- agents/ # Python reference implementations (s01-s12 + s_full capstone)
|-- docs/{en,zh,ja}/ # Mental-model-first documentation (3 languages)
|-- web/ # Interactive learning platform (Next.js)
|-- skills/ # Skill files for s05
+-- .github/workflows/ci.yml # CI: typecheck + build
```
## 文档
心智模型优先：问题、解决方案、ASCII 图、最小化代码。
提供 [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/) 版本。
| Session | 主题 | 座右铭 |
|---------|-------|-------|
| [s01](./docs/en/s01-the-agent-loop.md) | Agent 循环 | *只需一个循环 & Bash* |
| [s02](./docs/en/s02-tool-use.md) | 工具使用 | *添加一个工具意味着添加一个处理程序* |
| [s03](./docs/en/s03-todo-write.md) | TodoWrite | *没有计划的 Agent 会迷失方向* |
| [s04](./docs/en/s04-subagent.md) | 子 Agent | *分解大任务；每个子任务获得一个干净的上下文* |
| [s05](./docs/en/s05-skill-loading.md) | 技能 | *按需加载知识，而非预先加载* |
| [s06](./docs/en/s06-context-compact.md) | 上下文压缩 | *上下文终将填满；你需要腾出空间的方法* |
| [s07](./docs/en/s07-task-system.md) | 任务 | *将大目标分解为小任务，排序，持久化到磁盘* |
| [s08](./docs/en/s08-background-tasks.md) | 后台任务 | *在后台运行慢速操作；Agent 继续思考* |
| [s09](./docs/en/s09-agent-teams.md) | Agent 团队 | *当任务对单个 Agent 太大时，委托给队友* |
| [s10](./docs/en/s10-team-protocols.md) | 团队协议 | *队友需要共享的通信规则* |
| [s11](./docs/en/s11-autonomous-agents.md) | 自主 Agent | *队友扫描看板并自行认领任务* |
| [s12](./docs/en/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各自在自己的目录工作，互不干扰* |
## 下一步 —— 从理解到交付
完成 12 个 Session 后，你将从里到外彻底理解 Agent 如何工作。有两种方式将知识投入实践：
### Kode Agent CLI —— 开源编码 Agent CLI
支持 Skill & LSP，兼容 Windows，可插拔 GLM / MiniMax / DeepSeek 及其他开源模型。安装即用。
GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
### Kode Agent SDK —— 在你的应用中嵌入 Agent 能力
官方 Claude Code Agent SDK 在底层与完整的 CLI 进程通信 —— 每个并发用户意味着一个独立的终端进程。Kode SDK 是一个独立库，没有单用户进程开销，可嵌入后端、浏览器扩展、嵌入式设备或任何运行时。
GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
## 姊妹仓库：从 *按需会话* 到 *全天候助手*
本仓库教授的 Agent 是 **即用即弃** 的 —— 打开终端，给它一个任务，完成后关闭，下一个 Session 从空白开始。这就是 Claude Code 的模式。
[OpenClaw](https://github.com/openclaw/openclaw) 证明了另一种可能性：在同样的 Agent 核心之上，两个机制将 Agent 从“推一下动一下”转变为“每 30 秒醒来寻找工作”：
- **心跳** —— 系统每 30 秒向 Agent 发送一条消息，检查是否有事可做。没事？回去睡觉。有事？立即行动。
- **Cron** —— Agent 可以调度自己的未来任务，时间一到自动执行。
加上多渠道 IM 路由（WhatsApp / Telegram / Slack / Discord，13+ 平台）、持久化上下文记忆和 Soul 人格系统，Agent 从一次性工具变身为全天候个人 AI 助手。
**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的配套教学仓库，从头解构这些机制：
```
claw agent = agent core + heartbeat + cron + IM chat + memory + soul
```
```
learn-claude-code claw0
(agent runtime core: (proactive always-on assistant:
loop, tools, planning, heartbeat, cron, IM channels,
teams, worktree isolation) memory, soul personality)
```
## 许可证
MIT
**模型即 Agent。我们的工作是给它工具，然后别挡路。**
标签：Anthropic, Bash 脚本, CIS基准, Claude, CLI, CVE检测, DLL 劫持, DNS解析, LLM 应用开发, Python, WiFi技术, 人工智能, 代码助手, 大语言模型, 学习资源, 工具调用, 应用安全, 开源项目, 教程, 无后门, 时序数据库, 智能体模式, 机器学习工程, 用户模式Hook绕过, 网络调试, 自动化, 自动化攻击, 自动化攻击, 自动化编程, 软件开发, 逆向工具