从零理解 Agent Harness：Learn Claude Code 深度解析

一套「造载具」的工程课：为什么这个项目值得学习

想象一下，你拿到了一辆顶级跑车的钥匙——那是 Claude/GPT/Gemini 等大语言模型，拥有强大的推理和行动能力。但问题是：没有一辆合适的「载具」，再强的模型也只能在原地打转。这个仓库教你的，就是如何从零打造那辆载具——也就是 Agent Harness（智能体框架）。

这不是一门教你「如何使用 AI」的课程，而是一门教你「如何构建让 AI 真正发挥作用的基础设施」的工程课。作者在 README 开篇就抛出了一个反直觉但极其重要的观点：Agency 来自模型训练，而非外部代码编排。这句话点出了整个项目的核心立场——Agent 的核心能力（感知、推理、行动）是模型在训练中学到的，代码的作用是给它一个舞台。

shareAI-lab 项目图标

图1：shareAI-lab 项目头像

从 DQN 到 Claude Code：Agency 进化的完整脉络

要理解这个项目的价值，必须先理解 Agent 的历史。README 中详细梳理了一条从 2013 年到 2024 年的技术进化线：

2013 年 DeepMind DQN 突破 Atari — 一个只接收原始像素和游戏分数的神经网络，在没有人工设计游戏规则的前提下，在 7 款 Atari 游戏中超越了所有此前算法。这是有记录以来最早引起广泛关注的通用 AI Agent 案例。

2019 年 OpenAI Five 征服 Dota 2 — 五个神经网络通过 10 个月内与自己对战了相当于 45,000 年的 Dota 2，最终在直播赛中 2-0 击败了世界冠军战队 OG，在后续公开竞技中胜率达到 99.4%。

2019 年 DeepMind AlphaStar 制霸星际争霸 II — 在信息不完全、实时决策的复杂环境中，AlphaStar 达到了玩家中的前 0.15%（宗师段位）。

2024-2025 年 LLM Agent 重塑软件工程 — Claude、GPT、Gemini 等大语言模型作为编程 Agent，阅读代码库、编写实现、调试故障、团队协作。其架构与前述所有 Agent 完全一致：一个经过训练的模型，放入一个环境，赋予感知和行动的工具。

作者用这条时间线要说明的核心结论是：Agency 是训练出来的，不是编出来的。这是理解整个项目定位的关键前提。

核心理念：Agent = 模型 + Harness

项目标题「Bash is all you need」本身就是一种宣言——它告诉你，这个仓库不需要复杂的容器编排，不需要 Kubernetes，甚至不需要 Docker。它用最少的工程基础设施，演示了 Agent 的核心工作原理。

用生活化的比喻：如果把 Agent 想象成一个有超能力的助手，模型是这个助手的大脑（经过训练），而 Harness 是这个助手的手和眼——它让大脑能够与环境交互：读取文件、执行命令、浏览网页、处理结果。

README 中用 Agent Loop 图示清晰展示了这一架构：

Agent Loop 架构图

图2：Agent Loop 架构 — LLM 调用 → 工具执行 → 结果回传 → 循环

核心循环只有一行伪代码：

while stop_reason == "tool_use":
    response = LLM(messages, tools)
    execute tools
    append results

这行代码道出了整个 Agent 工作流程的本质：将工具执行结果反馈给模型，直到模型决定停下来。

十大主题模块：从基础到进阶的完整学习路径

项目采用分主题（session）目录结构，共有 10 个递进的学习模块，每个模块对应一个核心 Agent 开发主题：

模块	主题	核心内容
s01	Agent Loop	最基础的「提问→LLM→执行→结果→再提问」循环
s02	Tool Use	让 Agent 调用外部工具（bash 命令、文件读取等）
s03	Permission	Agent 执行敏感操作前的权限控制机制
s04	Hooks	在关键节点注入自定义逻辑（生命周期钩子）
s05	Todo Write	Agent 自主维护任务列表并持续推进
s06	Subagent	主 Agent 调度子 Agent 实现并行/分层任务
s07	Skill Loading	动态加载外部技能模块扩展 Agent 能力
s08	Context Compact	长对话上下文压缩与摘要技术
s09	Memory	Agent 跨会话记忆持久化机制
s10	System Prompt	系统提示词工程与角色设定

每个模块都包含 code.py（可运行的实现代码）和多语言 README 文档（含中文、英文、日文三个版本）。这种「代码 + 文档」的双轨结构，使它既是一个可运行的示例库，也是一本可以系统学习的教材。

从 agents/ 目录的结构来看，实际代码库分为 9 个 Python 模块：s01_agent_loop.py（Agent 循环）、s02_tool_use.py（工具调用）、s03_todo_write.py（任务列表管理）、s04_subagent.py（子代理）、s05_skill_loading.py（技能加载）、s06_context_compact.py（上下文压缩）、s07_task_system.py（任务系统）、s08_background_tasks.py（后台任务）和 s09_agent_teams.py（多 Agent 协作）。

技术栈：极简背后的工程深度

项目选用 Python + Bash 作为主要技术栈，极简但不简陋。这两个工具的组合恰好覆盖了 AI 开发的两个核心场景：Python 处理模型调用、API 通信和复杂逻辑，Bash 处理系统级操作（文件 I/O、进程管理、命令行工具调用）。

核心依赖只有三个：anthropic（Anthropic 官方 SDK）、python-dotenv（环境变量管理）和 pyyaml（配置文件解析）。这种极简依赖策略使项目易于理解、安装和调试。

代码中大量使用注释和 ASCII 架构图来解释原理，降低了理解门槛。例如 s01_agent_loop.py 开头的图示清晰展示了 LLM → 工具执行 → 结果回传的循环关系。这种「代码即文档」的理念贯穿整个项目。

上手门槛：极低，但需要基础

这个项目的目标用户是想要深入理解 Agent 内部工作原理的开发者，而非只想快速调用 API 的使用者。

入门要求：

Python 3.10+
基础编程能力（能读懂函数调用和循环逻辑）
一个 Anthropic API Key（或其他兼容的 LLM API）
至少理解「AI 能理解自然语言」这一基本概念

不适合：

完全零基础的编程新手（缺乏 Python 经验会吃力）
只想使用现成 AI 产品而不关心原理的用户
需要生产级部署能力的团队（项目不提供容器化支持）

争议与局限：它不做什么

作为一个教学项目，它有明确的边界，不回避这些边界本身就是一个优点。

它不做容器化 — 没有 Dockerfile，没有 docker-compose，纯 Python 环境运行。对教学来说这是优点（减少复杂度），但对团队协作和生产部署来说是明显的短板。不同的开发环境可能遇到依赖冲突。

它不涉及模型训练 — 正如作者在 README 中强调的，Agent 的核心能力来自模型训练。这个项目只关注 Harness 层的工程实现，不涉及模型训练、微调或评测。

它不提供生产级错误处理 — 示例代码追求简洁明了，生产环境需要的重试机制、熔断器、监控告警等都不在讨论范围内。

学习曲线陡峭 — 虽然代码本身简洁，但背后的 Agent 设计理念、工具调用协议、上下文管理策略都需要一定的 AI 开发经验才能真正吸收。零基础用户可能会在初期感到「看懂了但不知道怎么用」。

行业意义：开源社区对 AI Agent 工程化的集体探索

这个项目目前 GitHub Star 数超过 62,000（截至 2026 年 5 月），Forks 超过 10,000，在 GitHub trending 上持续活跃。这种规模的关注度本身就说明了一件事：市场对「如何从零构建 Agent」的需求极其旺盛。

从更宏观的视角看，这个项目代表了一种趋势：AI 开发正在从「调 API 拼应用」向「搭框架做系统」演进。随着 Claude Code、GitHub Copilot 等 AI 编程工具的成熟，开发者越来越意识到：真正的壁垒不在于模型本身，而在于如何围绕模型构建可靠、可维护的工作流系统。

这类项目（如 LangChain、AutoGPT、 crews、Flowise 等）的共同特点是：它们都在尝试回答同一个问题——如何让 AI 模型从「能聊天」变成「能干活」。Learn Claude Code 的独特价值在于：它用最少的工程复杂度，展示了这一转变的核心机制，给学习者提供了最直接的路线图。

快速开始

git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
pip install -r requirements.txt

# 配置 API Key
cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY=sk-ant-...

# 运行第一个 Agent 示例
python agents/s01_agent_loop.py

整个流程从安装到跑通第一个示例，熟练开发者通常不超过 10 分钟。

从零理解 Agent Harness：Learn Claude Code 深度解析

一套「造载具」的工程课：为什么这个项目值得学习

shareAI-lab 项目图标

图1：shareAI-lab 项目头像

从 DQN 到 Claude Code：Agency 进化的完整脉络

要理解这个项目的价值，必须先理解 Agent 的历史。README 中详细梳理了一条从 2013 年到 2024 年的技术进化线：

2019 年 DeepMind AlphaStar 制霸星际争霸 II — 在信息不完全、实时决策的复杂环境中，AlphaStar 达到了玩家中的前 0.15%（宗师段位）。

作者用这条时间线要说明的核心结论是：Agency 是训练出来的，不是编出来的。这是理解整个项目定位的关键前提。

核心理念：Agent = 模型 + Harness

README 中用 Agent Loop 图示清晰展示了这一架构：

Agent Loop 架构图

图2：Agent Loop 架构 — LLM 调用 → 工具执行 → 结果回传 → 循环

核心循环只有一行伪代码：

while stop_reason == "tool_use":
    response = LLM(messages, tools)
    execute tools
    append results

这行代码道出了整个 Agent 工作流程的本质：将工具执行结果反馈给模型，直到模型决定停下来。

十大主题模块：从基础到进阶的完整学习路径

项目采用分主题（session）目录结构，共有 10 个递进的学习模块，每个模块对应一个核心 Agent 开发主题：

模块	主题	核心内容
s01	Agent Loop	最基础的「提问→LLM→执行→结果→再提问」循环
s02	Tool Use	让 Agent 调用外部工具（bash 命令、文件读取等）
s03	Permission	Agent 执行敏感操作前的权限控制机制
s04	Hooks	在关键节点注入自定义逻辑（生命周期钩子）
s05	Todo Write	Agent 自主维护任务列表并持续推进
s06	Subagent	主 Agent 调度子 Agent 实现并行/分层任务
s07	Skill Loading	动态加载外部技能模块扩展 Agent 能力
s08	Context Compact	长对话上下文压缩与摘要技术
s09	Memory	Agent 跨会话记忆持久化机制
s10	System Prompt	系统提示词工程与角色设定

技术栈：极简背后的工程深度

上手门槛：极低，但需要基础

这个项目的目标用户是想要深入理解 Agent 内部工作原理的开发者，而非只想快速调用 API 的使用者。

入门要求：

Python 3.10+
基础编程能力（能读懂函数调用和循环逻辑）
一个 Anthropic API Key（或其他兼容的 LLM API）
至少理解「AI 能理解自然语言」这一基本概念

不适合：

完全零基础的编程新手（缺乏 Python 经验会吃力）
只想使用现成 AI 产品而不关心原理的用户
需要生产级部署能力的团队（项目不提供容器化支持）

争议与局限：它不做什么

作为一个教学项目，它有明确的边界，不回避这些边界本身就是一个优点。

它不提供生产级错误处理 — 示例代码追求简洁明了，生产环境需要的重试机制、熔断器、监控告警等都不在讨论范围内。

行业意义：开源社区对 AI Agent 工程化的集体探索

快速开始

git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
pip install -r requirements.txt

# 配置 API Key
cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY=sk-ant-...

# 运行第一个 Agent 示例
python agents/s01_agent_loop.py

整个流程从安装到跑通第一个示例，熟练开发者通常不超过 10 分钟。