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-codelearn-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-v9Agent 间能通信最终走向自治协作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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 learn-claude-code 完整指南：从 Agent Loop 到多 Agent 协作的 17 个机制
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-codelearn-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-v9Agent 间能通信最终走向自治协作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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考