企业官网建设流程全解析

learn-claude-code 完整指南：从 Agent Loop 到多 Agent 协作的 17 个机制

【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code

learn-claude-code 是一个从 0 到 1 构建类 Claude Code「agent harness」的教学项目：它不教调用模型 API，而是拆解智能体框架的 17 个核心机制——工具调度、上下文压缩、任务系统、多 Agent 协作——每一章都配有可独立运行的代码和图解，帮你理解一个能干活的 Agent 到底是怎么搭起来的。

Agent 的智能来自模型，但让模型真正能读文件、跑命令、管任务的那套外围代码，业界称为harness（执行框架）。项目的口号很直接："Bash is all you need"——一个循环加一个 Bash 工具，就是一个最小可用的编码 Agent。本文先厘清这条主线，再挑几个关键机制拆开看。

Agent Loop 循环机制：一切机制都长在这一个循环上

框架的全部复杂度，都围绕一个看似朴素的主循环展开。

• 单一主循环：s01_agent_loop用while True不断把消息发给模型，直到模型不再要求调用工具为止
• stop_reason 分流：模型每次响应都会给出停止原因，若为tool_use就执行工具并把结果追加回消息列表，否则结束
• 模型决策，代码执行：什么时候用工具、用哪个、何时停，都由模型判断；循环本身不含任何业务逻辑

这个分工决定了整个项目的形态：模型是司机，harness 是车辆。下面的循环图是理解后续所有机制的钥匙：

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

工具系统的扩展也遵循同样原则：新增一个工具只是往TOOL_HANDLERS分发映射表里注册一个 handler，主循环一行不改。s02_tool_use演示了这种"注册即扩展"的调度设计，让工具池可以无限扩张而不触碰核心。

上下文压缩原理：上下文越用越长，Agent 如何不失忆？

长任务里，每次读文件、每条命令输出都会堆积在消息列表中，直到撞上模型的上下文窗口上限。项目的解法是一条按信息损失从低到高排序的压缩流水线（s08_context_compact）：

• 大结果外置：超过 3 万字符的工具结果写入磁盘文件，上下文里只保留路径和 2000 字符预览
• micro_compact：每轮静默执行，把陈旧的tool_result替换成占位符
• auto_compact：当估算 token 超阈值时，把旧历史总结成摘要替换掉，并保留目标、约束与当前工作
• 手动 compact 工具：模型自己也能主动发起压缩，还可指定聚焦主题

设计的巧味在于顺序：能"重读文件"解决的就不调用模型去摘要。文件内容和命令输出通常可再生，总结历史则不可逆且消耗额外一次模型调用。这条"先便宜后昂贵"的流水线，是长任务 Agent 能跑数小时而不"忘事"的关键。配套的权限系统（s03_permission）和钩子系统（s04_hooks）则在循环外围划定了信任边界——先决定什么能跑、什么必须审批，再放开模型的手脚。

任务状态管理与看板机制：目标如何拆成可跟踪的图

压缩解决"对话内"的记忆，任务系统解决"跨会话"的记忆。s10_task_system把任务持久化为磁盘上的 JSON 文件，每个任务就是一张带依赖关系的卡片：

• 文件持久化：任务落在.tasks/目录下，即使上下文被压缩或进程重启也不丢失
• 依赖图管理：blockedBy字段声明前置任务，完成某任务时自动从下游任务中移除该依赖
• 状态流转：pending → in_progress → completed，完成即解锁后继任务

任务在板上的流转大致如下：

create start complete -----> pending -----> in_progress -----> completed | | | (blocked by: [1]) owner: agent 从下游任务 | 的 blockedBy | 中移除自身 前置任务完成才 可 start

任务系统还刻意用文件锁保护写操作，为多 Agent 并发认领同一块板子打下基础——这正是下一章协作机制的前提。

多 Agent 团队协作架构：认领任务、信箱通信与隔离工作区

当任务大到单个 Agent 装不下，s13_agent_teams引入了 Lead + Teammates 的运行时。它的几个设计值得逐个看：

• 异步信箱通信：Teammates 之间通过文件支撑的MessageBus传递消息与结果，无需模型轮询收件箱，结果会注入 Lead 的下一轮
• 原子化任务认领：空闲 Teammate 自己发现就绪任务并在锁内认领，保证同一任务不会被两人同时拿走
• 任务绑定 worktree：需要并行修改同一仓库时，每个任务绑定独立工作目录（Git worktree），认领时才切换 cwd，避免编辑冲突
• WORK/IDLE 生命周期：Teammate 在"干活"与"空闲轮询"之间自动交替，发现新消息或可认领任务即唤醒

Lead ──创建团队/等待确认──▶ 用户 │ ├─ .mailboxes/ 消息、结果、协议响应 ├─ .worktrees/ 任务绑定的工作目录 └─ 共享任务板 空闲成员自行认领就绪任务

能力不够时还可以再往外扩：s07_skill_loading按需加载技能文档而不是启动时全量注入，s14_mcp_plugin则把外部 MCP 工具发现并命名空间化后并入同一个工具池。最后s15_integrated_harness把以上机制在同一个主循环里重新接通，验证"多个机制，一个循环"确实成立。

快速部署方法与运行环境配置

跑通这个项目不需要任何构建工具，三步即可开始：

git clone https://gitcode.com/GitHub_Trending/an/learn-claude-code cd learn-claude-code pip install -r requirements.txt cp .env.example .env # 填入 ANTHROPIC_API_KEY

依赖只有三个包：anthropic、python-dotenv、pyyaml。之后按章节顺序运行python s01_agent_loop/code.py起步，逐步推进到s15_integrated_harness/code.py的集成运行时；仓库还附带一个 Web 学习平台（cd web && npm install && npm run dev），提供阅读、源码、模拟器和架构图四种视图。建议的学习路径即仓库 README 中的主线：先会行动（s01-s04）→ 处理复杂工作（s05-s08）→ 跨会话记忆（s09）→ 长任务（s10-s12）→ 多 Agent 协作（s13）→ 扩展与集成（s14-s15）→ 编排与目标闭环（s16-s17）。

从单循环到自治团队：一条值得记住的演进线

这个项目最有价值的不是某段代码，而是它展示的能力演进轨迹——每一步都只解决一个具体问题：

• v0-v1：一个 Agent，一个/多个工具
• v2-v3：有计划的 Agent，能派子 Agent 干支线
• v4-v5：按需加载知识，有压缩机制可遗忘
• v6-v7：多 Agent 共享任务看板，能并行
• v8-v9：Agent 间能通信，最终走向自治协作

Agent 产品竞争的下半场，与其说是比拼谁的模型更强，不如说是比拼谁的 harness 更懂给智能留出恰当的空间：工具设计得够原子、权限划得够清楚、上下文留得够干净、协作协议定得够严格。学会建造车辆，剩下的交给司机。

【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code