🔥🔥 learn-claude-code（学习claude-code开源仓库 ⭐️20k）

核心模式
范围说明 (重要)
快速开始
- WEB平台
学习路径
项目结构
文档
学完之后 — 从理解到落地
- Kode Agent CLI — 开源 Coding Agent CLI
- Kode Agent SDK — 把 Agent 能力嵌入你的应用
姊妹教程: 从被动临时会话到主动常驻助手

https://github.com/shareAI-lab/learn-claude-code

                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         yes                           no
                          |                             |
                    execute tools                    return text
                    append results
                    loop back -----------------> messages[]


    这是最小循环。每个 AI 编程 Agent 都需要这个循环。
    生产级 Agent 还会叠加策略、权限与生命周期层。

THE AGENT PATTERN

=================

User --> messages[] --> LLM --> response

stop_reason == "tool_use"?

/ \

yes no

| |

execute tools return text

append results

loop back -----------------> messages[]

这是最小循环。每个 AI 编程 Agent 都需要这个循环。

生产级 Agent 还会叠加策略、权限与生命周期层。

12 个递进式课程, 从简单循环到隔离化的自治执行。 每个课程添加一个机制。每个机制有一句格言。

s01“One loop & Bash is all you need” — 一个工具 + 一个循环 = 一个智能体

s02“加一个工具, 只加一个 handler” — 循环不用动, 新工具注册进 dispatch map 就行

s03“没有计划的 agent 走哪算哪” — 先列步骤再动手, 完成率翻倍

s04“大任务拆小, 每个小任务干净的上下文” — 子智能体用独立 messages[], 不污染主对话

s05“用到什么知识, 临时加载什么知识” — 通过 tool_result 注入, 不塞 system prompt

s06“上下文总会满, 要有办法腾地方” — 三层压缩策略, 换来无限会话

s07“大目标要拆成小任务, 排好序, 记在磁盘上” — 文件持久化的任务图, 为多 agent 协作打基础

s08“慢操作丢后台, agent 继续想下一步” — 后台线程跑命令, 完成后注入通知

s09“任务太大一个人干不完, 要能分给队友” — 持久化队友 + 异步邮箱

s10“队友之间要有统一的沟通规矩” — 一个 request-response 模式驱动所有协商

s11“队友自己看看板, 有活就认领” — 不需要领导逐个分配, 自组织

s12“各干各的目录, 互不干扰” — 任务管目标, worktree 管目录, 按 ID 绑定

核心模式

每个课程在这个循环之上叠加一个机制 — 循环本身始终不变。

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})

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})

“TOOL_HANDLERS[block.name](**block.input)”这行代码的作用是——根据 Claude 选择的工具名，动态找到对应函数，并把 Claude 生成的参数传进去执行，实现了工具的自动分发调用。

范围说明 (重要)

本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent（轻量级的Claude Code）。为保证学习路径清晰，仓库有意简化或省略了部分生产机制：

完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。
s12 仅提供教学用途的最小 append-only 生命周期事件流。
基于规则的权限治理与信任流程
会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制
完整 MCP 运行时细节 (transport/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   # 编辑 .env 填入你的 ANTHROPIC_API_KEY

python agents/s01_agent_loop.py       # 从这里开始
python agents/s12_worktree_task_isolation.py  # 完整递进终点
python agents/s_full.py               # 总纲: 全部机制合一

git clone https://github.com/shareAI-lab/learn-claude-code

cd learn-claude-code

pip install -r requirements.txt

cp .env.example .env # 编辑 .env 填入你的 ANTHROPIC_API_KEY

python agents/s01_agent_loop.py # 从这里开始

python agents/s12_worktree_task_isolation.py # 完整递进终点

python agents/s_full.py # 总纲: 全部机制合一

WEB平台

交互式可视化、分步动画、源码查看器, 以及每个课程的文档。

cd web && npm install && npm run dev   # http://localhost:3000

1	cd web && npm install && npm run dev # http://localhost:3000

学习路径

第一阶段: 循环                       第二阶段: 规划与知识
==================                   ==============================
s01  Agent 循环              [1]     s03  TodoWrite               [5]
     while + stop_reason                  TodoManager + nag 提醒
     |                                    |
     +-> s02  Tool Use            [4]     s04  子智能体             [5]
              dispatch map: name->handler     每个子智能体独立 messages[]
                                              |
                                         s05  Skills               [5]
                                              SKILL.md 通过 tool_result 注入
                                              |
                                         s06  Context Compact      [5]
                                              三层上下文压缩

第三阶段: 持久化                     第四阶段: 团队
==================                   =====================
s07  任务系统                [8]     s09  智能体团队             [9]
     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱
     |                                    |
s08  后台任务                [6]     s10  团队协议               [12]
     守护线程 + 通知队列                  关机 + 计划审批 FSM
                                          |
                                     s11  自治智能体             [14]
                                          空闲轮询 + 自动认领
                                     |
                                     s12  Worktree 隔离          [16]
                                          任务协调 + 按需隔离执行通道

                                     [N] = 工具数量

第一阶段: 循环第二阶段: 规划与知识

================== ==============================

s01 Agent 循环 [1] s03 TodoWrite [5]

while + stop_reason TodoManager + nag 提醒

| |

+-> s02 Tool Use [4] s04 子智能体 [5]

dispatch map: name->handler 每个子智能体独立 messages[]

s05 Skills [5]

SKILL.md 通过 tool_result 注入

s06 Context Compact [5]

三层上下文压缩

第三阶段: 持久化第四阶段: 团队

================== =====================

s07 任务系统 [8] s09 智能体团队 [9]

文件持久化 CRUD + 依赖图队友 + JSONL 邮箱

| |

s08 后台任务 [6] s10 团队协议 [12]

守护线程 + 通知队列关机 + 计划审批 FSM

s11 自治智能体 [14]

空闲轮询 + 自动认领

s12 Worktree 隔离 [16]

任务协调 + 按需隔离执行通道

[N] = 工具数量

项目结构

learn-claude-code/
|
|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)
|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)
|-- web/                           # 交互式学习平台 (Next.js)
|-- skills/                        # s05 的 Skill 文件
+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建

learn-claude-code/

|-- agents/ # Python 参考实现 (s01-s12 + s_full 总纲)

|-- docs/{en,zh,ja}/ # 心智模型优先的文档 (3 种语言)

|-- web/ # 交互式学习平台 (Next.js)

|-- skills/ # s05 的 Skill 文件

+-- .github/workflows/ci.yml # CI: 类型检查 + 构建

文档

心智模型优先: 问题、方案、ASCII 图、最小化代码。

课程	主题	格言
s01	Agent 循环	One loop & Bash is all you need
s02	Tool Use	加一个工具, 只加一个 handler
s03	TodoWrite	没有计划的 agent 走哪算哪
s04	子智能体	大任务拆小, 每个小任务干净的上下文
s05	Skills	用到什么知识, 临时加载什么知识
s06	Context Compact	上下文总会满, 要有办法腾地方
s07	任务系统	大目标要拆成小任务, 排好序, 记在磁盘上
s08	后台任务	慢操作丢后台, agent 继续想下一步
s09	智能体团队	任务太大一个人干不完, 要能分给队友
s10	团队协议	队友之间要有统一的沟通规矩
s11	自治智能体	队友自己看看板, 有活就认领
s12	Worktree + 任务隔离	各干各的目录, 互不干扰

学完之后 — 从理解到落地

12 个课程走完, 你已经从内到外理解了 agent 的工作原理。两种方式把知识变成产品:

Kode Agent CLI — 开源 Coding Agent CLI

npm i -g @shareai-lab/kode

支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。

GitHub: shareAI-lab/Kode-cli

Kode Agent SDK — 把 Agent 能力嵌入你的应用

官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 — 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。

GitHub: shareAI-lab/Kode-agent-sdk

姊妹教程: 从被动临时会话到主动常驻助手

本仓库教的 agent 属于 用完即走 型 — 开终端、给任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。

但 OpenClaw (小龙虾) 证明了另一种可能: 在同样的 agent core 之上, 加两个机制就能让 agent 从”踹一下动一下”变成”自己隔 30 秒醒一次找活干”:

心跳 (Heartbeat) — 每 30 秒系统给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。
定时任务 (Cron) — agent 可以给自己安排未来要做的事, 到点自动执行。

再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。

claw0 是我们的姊妹教学仓库, 从零拆解这些机制:

claw agent = agent core + heartbeat + cron + IM chat + memory + soul

1	claw agent = agent core + heartbeat + cron + IM chat + memory + soul

learn-claude-code                   claw0
(agent 运行时内核:                   (主动式常驻 AI 助手:
 循环、工具、规划、                    心跳、定时任务、IM 通道、
 团队、worktree 隔离)                  记忆、Soul 人格)

learn-claude-code claw0

(agent 运行时内核: (主动式常驻 AI 助手:

循环、工具、规划、心跳、定时任务、IM 通道、

团队、worktree 隔离) 记忆、Soul 人格)

Heart.Think.Do