AI Native搜索…
扩展阅读

GitHub - shareAI-lab/learn-claude-code: Bash 就是一切——一个类似 Claude Code 的纳米级「智能体框架」，从 0 到 1 构建。· GitHub

GitHub·2026/7/21·6 阅读

GitHub - shareAI-lab/learn-claude-code: Bash 就是一切——一个类似 Claude Code 的纳米级「智能体框架」，从 0 到 1 构建。· GitHub

来源: https://github.com/shareAI-lab/learn-claude-code 抓取时间: 2026-07-21 16:28:04

English | 中文 | 日本語 shareAI-lab%2Flearn-claude-code | Trendshift

学习 Claude Code——真实智能体的框架工程

智能体的能力来自模型。智能体产品 = 模型 + 框架。

在我们编写任何代码之前，有一点需要明确。 智能体能力——感知、推理和行动的能力——来自模型训练，而不是外部代码编排。 但一个可用的智能体产品需要模型和框架。模型是驾驶员。框架是车辆。本仓库教你如何构建车辆。

智能体能力来自哪里

每个智能体的核心都是一个神经网络——一个 Transformer、一个 RNN、一个经过训练的函数——通过对感知、推理和行动序列的数十亿次梯度更新而形成。智能体能力从来不是由周围的代码赋予的。它是在训练过程中学习到的。 人类是最初的证明。一个生物神经网络，经过数百万年的进化压力锤炼，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 说「智能体」时，它们都意味着同一件核心事情：一个通过训练学会行动的模型，加上让它在特定环境中运行的基础设施。 历史记录毫不含糊：

  • 2013年——DeepMind DQN 玩 Atari。 一个单一的神经网络，只接收原始像素和游戏分数，学会了 7 款 Atari 2600 游戏——超越了先前的算法，并在其中 3 款中击败了人类专家。到 2015 年，扩展到 49 款游戏，达到专业测试人员水平，发表在《自然》杂志上。没有特定于游戏的规则。一个模型，从经验中学习。
  • 2019年——OpenAI Five 征服 Dota 2。 五个神经网络在 10 个月内与自己玩了 45,000 年的 Dota 2，然后在一场现场比赛中以 2-0 击败了 OG——TI8 世界冠军。在公开场合，该 AI 在 42,729 场比赛中赢得了 99.4%。没有脚本化的策略。模型通过自我对弈学会了团队合作。
  • 2019年——DeepMind AlphaStar 精通《星际争霸 II》。 AlphaStar 在封闭比赛中 10-1 击败职业玩家，然后在欧洲服务器上达到 宗师级别——在 90,000 名玩家中排名前 0.15%。一个不完整信息的实时游戏，其组合动作空间远远超过国际象棋或围棋。
  • 2019年——腾讯绝悟主宰《王者荣耀》。 腾讯 AI Lab 的「绝悟」系统在世界冠军杯半决赛中 击败了 KPL 职业玩家，完成了 5v5 对战。在 1v1 模式下，职业玩家 15 场比赛只赢了 1 场，最好情况下持续不到 8 分钟。训练强度：一天等于 440 人类年。一个模型通过自我对弈从零开始学会了整个游戏。
  • 2024-2025年——LLM 智能体重塑软件工程。 Claude、GPT、Gemini——在人类代码和推理的全部广度上训练的大型语言模型——被部署为编码智能体。它们阅读代码库，编写实现，调试故障，并作为团队协调。该架构与之前的每个智能体相同：一个经过训练的模型，放置在环境中，赋予感知和行动工具。

每个里程碑都指向同一个事实：智能体能力——感知、推理和行动的能力——是训练出来的，而不是编码出来的。 但每个智能体也需要一个运行的环境：Atari 模拟器、Dota 2 客户端、《星际争霸 II》引擎、IDE 和终端。模型提供智能。环境提供动作空间。它们共同形成一个完整的智能体。

智能体不是什么

「智能体」这个词已经被整个提示管道行业劫持了。 拖放式工作流构建器。无代码「AI 智能体」平台。提示链编排库。它们都有一个共同的妄想：将 LLM API 调用与 if-else 分支、节点图和硬编码路由逻辑串在一起构成「构建智能体」。 不是的。它们产生的是鲁布·戈德堡机器——过度设计、脆弱、程序化的规则管道，其中 LLM 被楔入作为一个美化的文本补全节点。那不是一个智能体。那是一个有着宏伟野心的 Shell 脚本。 你不能通过堆叠程序化逻辑——庞大的规则树、节点图、链式提示瀑布——并祈祷足够的胶水代码会自发产生自主行为来蛮力实现智能。这不会发生。你不能把智能体能力工程化。智能体能力是学习的，不是编码的。

观念转变：从「构建智能体」到构建框架

当有人说「我正在构建一个智能体」时，他们只能意味着两件事之一： 1. 训练模型。 通过强化学习、监督微调、RLHF 或其他基于梯度的方法调整权重。收集轨迹数据——目标领域中感知、推理和行动的真实世界序列——并使用它来塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab 和 Anthropic 所做的。 2. 构建框架。 编写代码，为模型提供操作环境。这是我们大多数人所做的，也是本仓库的核心。 框架是智能体在特定领域工作所需的一切：

框架 = 工具 + 知识 + 观察 + 行动接口 + 权限

    工具：文件 I/O、Shell、网络、数据库、浏览器
    知识：产品文档、领域参考、API 规范、风格指南
    观察：Git 差异、错误日志、浏览器状态、传感器数据
    行动：CLI 命令、API 调用、UI 交互
    权限：沙盒隔离、批准工作流、信任边界

模型做决定。框架执行。模型推理。框架提供上下文。模型是驾驶员。框架是车辆。 本仓库教你构建车辆。一个用于编码的车辆。但设计模式可以推广到任何领域。

框架工程师实际上做什么

如果你正在阅读本仓库，你很可能是一名框架工程师。以下是该工作实际涉及的内容：

  • 实现工具。 给智能体双手。文件读取/写入、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是智能体在其环境中可以采取的一个动作。将它们设计为原子性、可组合且描述清晰。
  • 策划知识。 给智能体领域专业知识。产品文档、架构决策记录、风格指南、合规要求。按需加载，而不是预先加载。
  • 管理上下文。 给智能体干净的内存。子智能体隔离防止噪声泄漏。上下文压缩防止历史淹没当前。任务系统让目标在单次对话之外持续存在。
  • 控制权限。 给智能体边界。沙盒文件访问。要求批准破坏性操作。强制执行智能体与外部系统之间的信任边界。
  • 收集轨迹数据。 智能体在您的框架中执行的每个动作序列都是训练信号。真实部署的轨迹是微调下一代智能体模型的原材料。

你不是在编写智能。你是在构建智能所栖息的世界。那个世界的质量直接决定了智能能够多有效地表达自己。 构建好框架。模型会完成剩下的。

为什么选择 Claude Code

因为 Claude Code 是我们见过的最优雅、最完整的智能体框架实现。不是因为任何聪明的技巧，而是因为它不做的事情：它不试图成为智能体。它不施加僵化的工作流。它不用手工制作的决策树来代替模型自己的判断。它给模型工具、知识、上下文管理和权限边界——然后让开道路。 将 Claude Code 精简到其本质：

Claude Code = 一个智能体循环
              + 工具（Bash、读取、写入、编辑、Glob、Grep、浏览器……）
              + 按需技能加载
              + 上下文压缩
              + 子智能体生成
              + 带依赖图的任务系统
              + 异步邮箱团队协调
              + 工作树隔离的并行执行
              + 权限治理
              + 钩子扩展系统
              + 内存持久化
              + MCP 外部能力路由

就是这样。智能体本身？Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练。框架没有让 Claude 变聪明。Claude 已经很聪明了。框架给了 Claude 手、眼睛和一个工作空间。 要点不是「复制 Claude Code」。要点是：最好的智能体产品来自那些理解他们的工作是框架，而不是智能的工程师。

                    智能体模式
                    =========

    用户 --> messages[] --> LLM --> 响应
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         是                           否
                          |                             |
                    执行工具                    返回文本
                    追加结果
                    循环回来 ----------------> messages[]


    模型决定何时调用工具以及何时停止。
    代码只是执行模型要求的内容。
    本仓库教你围绕这个循环构建一切——
    使智能体在特定领域有效的框架。

核心模式

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

每节课都在这个循环之上添加一个框架机制——循环本身永远不会改变。循环属于智能体。机制属于框架。 循环是恒定的。工具、知识和权限会改变。智能体 = 模型（LLM）+ 通用操作环境（框架）。

版本状态

本仓库目前包含两个教程轨道：

  • 当前轨道：根级s01-s20 根级 s01_* ... s20_* 文件夹是新的规范版本。每章包含完整的叙述性 README、翻译、可运行的 code.py 以及必要时的图表。
  • 旧版过渡轨道：docs/、agents/ 和当前的 web/ 应用 这些仍然保留较旧的 12 课版本。它们暂时保留给现有读者、旧链接和 Web 平台，同时新的 20 课轨道稳定下来。

如果你现在开始，阅读根级 s01_agent_loop/ 到 s20_comprehensive/ 章节。如果你正在关注旧链接或使用当前的 Web 应用，你可能正在阅读旧版 12 课轨道。旧版和当前章节号并不总是匹配，所以避免跨轨道混合章节号。

旧版到当前映射

旧版 12 课轨道当前 20 课轨道主题
旧 s01新 s01智能体循环
旧 s02新 s02工具使用
旧 s03新 s05待办事项写入
旧 s04新 s06子智能体
旧 s05新 s07技能加载
旧 s06新 s08上下文压缩
旧 s07新 s12任务系统
旧 s08新 s13后台任务
旧 s09新 s15智能体团队
旧 s10新 s16团队协议
旧 s11新 s17自主智能体
旧 s12新 s18工作树隔离
仅限新版s03, s04, s09, s10, s11, s14, s19, s20权限、钩子、内存、系统提示、错误恢复、Cron、MCP、综合智能体

范围

本仓库是一个 0 到 1 的框架工程项目：它教你如何构建智能体模型周围的工作环境。为了保持学习路径清晰，一些生产机制被有意简化或省略：

  • 完整事件/钩子总线行为，例如 PreToolUse、SessionStart/End 和 ConfigChange。教学代码在需要时使用最小的生命周期事件。
  • 基于规则的权限治理和完整信任工作流。
  • 会话生命周期控制，例如恢复/分叉，以及更完整的工作树生命周期处理。
  • 完整的 MCP 运行时细节，例如传输、OAuth、资源订阅和轮询。

本仓库中的 JSONL 邮箱协议是一个教学实现，而不是对任何特定生产内部实现的主张。

20 个渐进课程

每节课添加一个框架机制。每个机制都有一个座右铭。

s01 「一个循环 + Bash 就是一切」 ——一个工具 + 一个循环 = 一个智能体 s02 「添加工具意味着添加一个处理程序」 ——循环保持不变；新工具注册到调度映射中 s03 「先设置边界，然后授予自由」 ——检查什么可以运行，什么必须停止，什么需要批准 s04 「在循环周围挂钩，永远不要重写循环」 ——添加扩展点而不改变主循环 s05 「没有计划的智能体会漂移」 ——在开始之前列出步骤；完成率翻倍 s06 「大任务分成小任务，每个子任务获得干净的上下文」 ——子智能体做辅助工作并只带回结果 s07 「按需加载知识，而不是预先加载」 ——首先列出技能，只在需要时扩展它们 s08 「上下文总是会填满——有办法腾出空间」 ——多层压缩策略为你提供无限会话 s09 「记住重要的，忘记不重要的」 ——三个子系统：选择、提取、整合 s10 「提示在运行时组装，不是硬编码的」 ——基于部分的连接，按需加载 s11 「错误不是结束，它们是重试的开始」 ——当事情失败时重试、腾出空间或走另一条路 s12 「大目标分解成小任务，有序，持久化到磁盘」 ——一个文件支持的任务图，为多智能体协调奠定基础 s13 「慢操作后台执行，智能体继续思考」 ——后台线程运行命令；通知在完成时注入 s14 「按计划触发，不需要人类启动」 ——按时间自动触发任务 s15 「一个智能体太大——委托给队友」 ——持久化队友 + 异步邮箱 s16 「队友需要共享通信规则」 ——使用固定的请求-应答格式进行协调 s17 「队友查看董事会，自己认领工作」 ——没有领导者逐个分配；自组织 s18 「每个都在自己的目录中工作，没有干扰」 ——任务拥有目标，工作树拥有目录，由 ID 绑定 s19 「能力不够？通过 MCP 插入更多」 ——将外部工具连接到同一个工具池 s20 「许多机制，一个循环」 ——所有先前的机制都回到一个完整的框架

学习路径

主线：行动 → 处理复杂工作 → 记住和恢复 → 运行长任务 → 协作 → 扩展和组装。

flowchart TD
    %% 卡片样式
    classDef stage1 fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#0D47A1,rx:12,ry:12,text-align:left
    classDef stage2 fill:#E8F5E9,stroke:#388E3C,stroke-width:2px,color:#1B5E20,rx:12,ry:12,text-align:left
    classDef stage3 fill:#FFF3E0,stroke:#F57C00,stroke-width:2px,color:#E65100,rx:12,ry:12,text-align:left
    classDef stage4 fill:#FCE4EC,stroke:#C2185b,stroke-width:2px,color:#880E4F,rx:12,ry:12,text-align:left
    classDef stage5 fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C,rx:12,ry:12,text-align:left
    classDef stage6 fill:#E0F7FA,stroke:#0097A7,stroke-width:2px,color:#006064,rx:12,ry:12,text-align:left

    %% 组样式
    classDef groupBox fill:#F8F9FA,stroke:#CED4DA,stroke-width:2px,stroke-dasharray: 5 5,rx:15,ry:15,color:#495057

    %% 第 1 层：阶段 1-3
    subgraph Phase1 ["🌱 阶段 1-3：核心能力（从简单到复杂）"]
        direction LR
        S1["<b>1. 让智能体行动</b><br/>━━━━━━━━━━━━━<br/><b>s01 智能体循环</b><br/>└─一个循环 + Bash<br/><br/><b>s02 工具使用</b><br/>└─一个工具到多个工具<br/><br/><b>s03 权限</b><br/>└─决定什么可以运行<br/><br/><b>s04 钩子</b><br/>└─工具周围的扩展点"]:::stage1

        S2["<b>2. 处理复杂工作</b><br/>━━━━━━━━━━━━━<br/><b>s05 待办事项写入</b><br/>└─先计划，然后执行<br/><br/><b>s06 子智能体</b><br/>└─辅助工作，结果返回<br/><br/><b>s08 上下文压缩</b><br/>└─在长上下文中腾出空间"]:::stage2

        S3["<b>3. 记住和恢复</b><br/>━━━━━━━━━━━━━<br/><b>s09 内存</b><br/>└─记住重要的<br/><br/><b>s10 系统提示</b><br/>└─在运行时组装<br/><br/><b>s11 错误恢复</b><br/>└─重试或改变路径"]:::stage3

        S1 ==> S2 ==> S3
    end

    %% 第 2 层：阶段 4-6
    subgraph Phase2 ["🚀 阶段 4-6：高级能力（长时间运行、协作、集成）"]
        direction LR
        S4["<b>4. 运行长任务</b><br/>━━━━━━━━━━━━━<br/><b>s12 任务系统</b><br/>└─持久化任务和依赖<br/><br/><b>s13 后台任务</b><br/>└─发送慢工作到后台<br/><br/><b>s14 Cron 调度器</b><br/>└─按时间触发"]:::stage4

        S5["<b>5. 协调多个智能体</b><br/>━━━━━━━━━━━━━<br/><b>s15 智能体团队</b><br/>└─队友 + 邮箱<br/><br/><b>s16 团队协议</b><br/>└─固定的请求-应答格式<br/><br/><b>s17 自主智能体</b><br/>└─从董事会认领工作<br/><br/><b>s18 工作树隔离</b><br/>└─单独的目录"]:::stage5

        S6["<b>6. 扩展和组装</b><br/>━━━━━━━━━━━━━<br/><b>s07 技能加载</b><br/>└─按需扩展技能<br/><br/><b>s19 MCP 插件</b><br/>└─外部工具，一个池<br/><br/><b>s20 综合智能体</b><br/>└─所有机制，一个循环"]:::stage6

        S4 ==> S5 ==> S6
    end

    %% 连接两层
    Phase1 ===> Phase2

    class Phase1,Phase2 groupBox

正在加载

所有章节

章节主题核心概念
s01智能体循环messages / while True / stop_reason
s02工具使用TOOL_HANDLERS / 调度映射 / 并发
s03权限系统PermissionRule / 批准管道
s04钩子系统PreToolUse / PostToolUse / 扩展点
s05待办事项写入TodoItem / 先计划后执行
s06子智能体新鲜的 messages[] / 上下文隔离
s07技能加载SkillManifest / 按需注入
s08上下文压缩剪切压缩 / 微压缩 / 工具结果预算 / 自动压缩
s09内存系统选择 / 提取 / 整合
s10系统提示运行时组装 / 部分连接
s11错误恢复Token 升级 / 备用模型 / 重试策略
s12任务系统TaskRecord / blockedBy / 磁盘持久化
s13后台任务线程执行 / 通知队列
s14Cron 调度器持久化调度 / 会话范围的触发器
s15智能体团队MessageBus / 收件箱 / 权限冒泡
s16团队协议关闭握手 / 计划批准
s17自主智能体空闲循环 / 自动认领 / 自组织
s18工作树隔离WorktreeRecord / 任务-目录绑定
s19MCP 插件多传输 / 通道路由 / 工具池组装
s20综合智能体一个循环周围的所有机制

如何阅读

每章是一个文件夹。打开一个，你会发现：

s08_context_compact/
  README.md              # 带内联代码的完整叙述
  README.en.md           # 英文翻译
  README.ja.md           # 日文翻译
  code.py                # 独立可运行实现
  images/                # SVG 图表（必要时）

阅读 README.md 了解核心思想并完成代码。复杂章节有 <details> 折叠用于深入探讨——当你想更深入时打开它们。简单章节有 0-1 个图表，复杂章节有更多。 按顺序从 s01 读到 s20。每章假设你已经读过前面的章节，并以与下一章的钩子结尾。

快速开始

当前 20 课轨道

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env   # 配置 ANTHROPIC_API_KEY

python s01_agent_loop/code.py        # 从这里开始——一个循环 + Bash
python s08_context_compact/code.py   # 上下文压缩（复杂）
python s20_comprehensive/code.py     # 终点：一个循环中的所有机制

旧版 12 课轨道

python agents/s01_agent_loop.py
python agents/s12_worktree_task_isolation.py
python agents/s_full.py

Web 平台

当前的 Web 应用仍然渲染旧版 docs/ s01-s12 轨道。使用根级文件夹获取新的 s01-s20 轨道。

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

项目结构

learn-claude-code/
  s01_agent_loop/          # 每章一个文件夹
    README.md              #   中文源（完整叙述）
    README.en.md           #   英文翻译
    README.ja.md           #   日文翻译
    code.py                #   独立可运行代码
    images/                #   SVG 图表
  s02_tool_use/
  ...
  s19_mcp_plugin/
  s20_comprehensive/       # 终点章节
  agents/                  # 旧版 12 个可运行副本 + s_full.py
  skills/                  # s07 使用的示例技能
  docs/                    # 旧版 12 课文档，在过渡期间保留
  web/                     # 当前渲染旧版 docs/ 轨道
  tests/

下一步

在 20 节课之后，你从内到外理解框架工程。有两条路径可以将这些知识转化为产品：

Kode 智能体 CLI——开源编码智能体 CLI

npm i -g @shareai-lab/kode 支持技能和 LSP，兼容 Windows，适用于 GLM / MiniMax / DeepSeek 和其他开源模型。安装即可使用。 GitHub：shareAI-lab/Kode-CLI

Kode 智能体 SDK——在你的应用程序中嵌入智能体能力

一个独立的库，没有每个用户的进程开销。将其嵌入到后端、浏览器扩展、嵌入式设备或任何运行时中。 GitHub：shareAI-lab/kode-agent-sdk

姐妹教程：从被动会话到永远在线的助手

本仓库中教授的框架是**「使用后丢弃」**类型——打开终端，给智能体一个任务，完成后关闭，下一次会话重新开始。Claude Code 就是这样工作的。 但 OpenClaw 证明了另一种可能性：在同一个智能体核心上，两个额外的框架机制将智能体从「戳它它就动」变成「每 30 秒自己醒来寻找工作」：

  • 心跳 ——每 30 秒框架给智能体发一条消息，让它检查待处理的工作。什么都不做？继续睡觉。有东西出现了？立即行动。
  • Cron ——智能体可以安排自己的未来任务，这些任务在时间到达时自动触发。

添加 IM 多通道路由（WhatsApp / Telegram / Slack / Discord 和 13+ 其他平台）、持久化上下文内存和 Soul 人格系统，智能体从一次性工具转变为永远在线的个人 AI 助手。 claw0 是我们的姐妹教学仓库，从零开始分解这些框架机制：

claw 智能体 = 智能体核心 + 心跳 + Cron + IM 聊天 + 内存 + Soul


learn-claude-code                   claw0
(智能体框架内部：                    (永远在线框架：
 循环、工具、规划、               心跳、Cron、IM 通道、
 团队、工作树隔离)                内存、Soul 人格)

许可证

MIT

智能体能力来自模型。框架给智能体能力一个降落的地方。构建好框架，模型会完成剩下的。 Bash 就是一切。真实的智能体就是宇宙所需的一切。 这不是「复制源代码」。这是「掌握关键设计并自己构建」。

#P0 必读#GitHub

评论 (0)

暂无评论，快来抢沙发吧！

学91学AI

© 2026 91学AI · 按岗位学 AI 与大数据. All rights reserved.