拆解 Claude Code Agent：工具调用与上下文管理背后的 4 个关键设计

拆解 Claude Code Agent工具调用与上下文管理背后的 4 个关键设计【免费下载链接】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你敲下帮我查这个仓库的报错这句话时Claude Code Agent 要在毫秒内决定调哪个工具、读哪个文件、之前的输出还值不值得保留。这就是 AI 工具调用机制的起点。开源项目 learn-claude-code 对 Claude Code v1.0.33 做了逆向拆解用 17 章 Python 代码把机制逐层复现本文只挑最值得抄的 4 个关键设计决策。 架构全景模型 HarnessClaude Code 一个 agent loop 工具 技能 压缩 子代理 权限。模型是司机harnessharness 指让模型在具体环境里运转的全部外围设施是车模型决策harness 执行。这个仓库的做法是把零件拆成 17 个文件从 s01 的单 bash 工具 单 while 循环开始每章加一个机制。⚙️ 循环是怎么转起来的一个循环两个信号核心就在agents/s01_agent_loop.py的agent_loop()里输入用户消息进messages列表处理调用 LLM把返回内容追加进 messages输出stop_reason tool_use就执行工具、把结果写回 messages 继续循环否则返回、结束结果是下一轮的输入工具结果被包装成tool_result块按tool_use_id对上号作为新的 user 消息还给模型。模型看到的工具其实只是对话里多出来的一段。这个设计解决的具体问题没有这个循环模型只能写出命令得靠人手动执行、再手动贴回结果人是中间层。 工具是怎么被选中并派发的工具数组 派发表循环本身不变只是往 TOOLS 数组里加了 read_file / write_file / edit_file 三个工具再写一张派发表见agents/s02_tool_use.py。输入模型返回带name字段的tool_use块处理按名字查TOOL_HANDLERS调用对应 handler输出handler 的返回字符串就是工具结果安全写在 handler 里不写在提示词里safe_path()解析路径不在工作区内直接抛错挡住../逃逸run_bash()字符串匹配sudo、rm -rf /等危险词即拒绝输出统一截断到 5 万字符这个设计解决的具体问题给模型真实的 shell 权限时爆炸半径必须在代码里圈住不能指望模型听话。 状态管理上下文压缩的三层管道长会话的死结是messages 只增不减迟早撞上 token 上限。agents/s06_context_compact.py的解法是一条三层管道。第一层micro_compact静默每轮跑只保留最近 3 条工具结果更早的 content 替换成占位符[Previous: used bash]。例外是read_file——文件内容是参考资料清了模型就得重读反而更贵。第二层auto_compact估算 token 超 5 万触发先把完整 transcript 存进.transcripts/落盘再让 LLM 生成摘要做了什么 / 当前状态 / 关键决策然后把全部 messages 替换成这唯一一条摘要。第三层compact 工具模型自己触发模型觉得上下文臃肿时主动调用 compact 工具逻辑同第二层只是触发方换成模型。多 Agent 协同场景下子代理保持独立的消息列表干完活只把摘要返回主代理——全局状态在主代理侧统一子代理的上下文不污染主对话。这个设计解决的具体问题让 agent 可以战略性遗忘会话长度不再被上下文窗口卡死。▶️ 动手跑起来git clone https://gitcode.com/GitHub_Trending/an/learn-claude-code cd learn-claude-code pip install -r requirements.txt # .env 里配好 ANTHROPIC_API_KEY 和 MODEL_ID 后 python agents/s01_agent_loop.py三个值得读的入口文件agents/s02_tool_use.py看TOOL_HANDLERS派发表与safe_path工具调用机制的最小完整形态agents/s06_context_compact.py看micro_compact和auto_compact如何串成管道agents/s_full.pys01–s11 全部机制合体的完整参考实现❓ 边界与开放问题危险命令黑名单是纯子串匹配注释里出现sudo会误杀模型仍可能执行rm -rf ./build代码里没有真正的沙箱隔离token 估算用len(str)//4的粗略启发式auto_compact 触发点和真实用量有明显偏差第二层压缩后细节只能靠翻磁盘 transcript 找回上下文缓存式的按相关性分级淘汰在代码里并不存在只有清空或保留两档多 Agent 邮箱是进程内状态重启即丢失跨节点协同无从谈起下次再敲下那句帮我查这个仓库的报错你知道毫秒内发生了什么一个 while 循环在转一张派发表在定位 bash一条压缩管道在悄悄决定哪些旧输出该被忘掉。【免费下载链接】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），仅供参考