夜雨聆风写在前面
最近把系统学习下Agent的日程的优先级往前排了下，做了个小实验项目，边学 Claude Code 源码，边把一些感兴趣的功能点先拆成不同的小模块动手复现一下
复盘的大致流程是：我分功能模块把源码解读完后，会简单回顾下各模块的设计思路，然后会挑其中1~2个点，简单写下Prompt，给到Opencode+GLM5.1，生成对应的实验Python代码，最后用Trae跑下实验，如果过程有一些我觉得新手可能需要注意的问题（我踩的坑），也会记录下来。
所以，后续这个系列会陆续分享一些我觉得好玩的功能点学习笔记，如果你自己也想进行深入学下ClaudeCode的源码，不是浅尝即止，或者想大概了解下Antropic的设计机制，那希望这个系列对你有所帮助~
之前读过 Anthropic 的 Agent 设计模式，里面有提到了 Orchestrator-Workers、上下文管理这些概念，不过看的时候好像懂和实际能落地是有巨大gap的~
这篇拆解的就是源码里runAgent.ts 里的设计runAgent.ts是CC里面派生子Agent的核心函数，代码也不多，900多行，覆盖了从参数解析到资源清理的完整生命周期，一个函数就能建立完整的 Agent 概念框架，这次，我实验复现的是循环执行这个点：
几分钟即可完成，展示一个最小 Agent loop长什么样~
阅读指引
简单欣赏下runAgent.ts有哪些设计？ 👉 一
三个实验分别跑了什么？ 👉 二、三、四
复现完有哪意外的收获？ 👉 五
下一个功能可能拆什么？ 👉 六
一、runAgent.ts设计包含什么
这个函数是 Claude Code 里启动子 Agent 的核心处理逻辑
它处理的内容不光是派出子Agent “调一次模型” ，还包括子Agent的模型选择、权限处理、上下文组装、工具裁剪、执行循环、以及最后清理资源。
启动并运行一个子 Agent，本质上都绕不开这五个环节，先看下Antropic咋做的
使用中根据任务需要，同一个父Agent可能会派出多个子Agent执行不同任务
那需要一个机制定义"这个子Agent 是什么、做什么、不做什么"
runAgent.ts 里面的做法是： 每个子 Agent 都需要有自己的类型定义（agentDefinition），预先注册好能力边界。
LLM 不能发明新的 Agent 类型，只能从已有类型里选、决定什么时候用
agentDefinition：静态模板，预注册在 activeAgents目录里，定义能力边界
model：按优先级确定 → 临时指定 > agentDefinition.model > 继承父 Agent
agentId：实例标识符，用于 transcript 路由和追踪，不控制权限
override：在不改静态模板的前提下临时覆盖系统提示、上下文、 agentId
子 Agent 的权限肯定不能照搬父 Agent——专用 Agent 应该收窄权限
父级的高权限授权也不该被子 Agent 随意覆盖，子 Agent 只能在父级允许的范围内收窄。
用户在会话中临时点击”允许”的权限，也不会自动扩散给子 Agent。
bypassPermissions：父级开启 → 子 Agent 不能降级
acceptEdits：父级开启 → 子 Agent 不能降级
agentDefinition.permissionMode：子 Agent 自定义，仅在父级非高权限时生效
遇到异步 Agent 强制shouldAvoidPermissionPrompts: true，遇到未预授权操作直接拒绝，不弹窗等待用户确认
此外，CC在这里面还加了工具权限隔离，区分全局授权和父Agent临时批准给某个子Agent的权限。
Agent 启动时会读取外部存储（CLAUDE.md、git 状态），组装成初始上下文。
不同类型的 Agent 会做裁剪——只读型的 Agent 不需要提交规范，就不给它这些信息，省 token 也减少噪音。
这个设计就比较比较简单了，加载上下文后按 Agent 类型裁剪：
Explore / Plan → 去掉 CLAUDE.md + git 状态（只读型不需要）
其他 → 保留完整
Agent 不是一次调用就结束，它要反复"想→做→看结果→再想"，直到任务完成或达到限制（如时间、token 数量）。
核心是一个异步循环：
forawait (message of query(...)) {记录消息yield 给上层调用者}
query() 内部处理 "LLM 调用 → 工具执行 → 结果返回 → 再次 LLM 调用"的循环逻辑，runAgent 负责把每一轮的消息记录下来并向上传递。
Agent 运行期间会申请很多资源：MCP 服务器连接、注册的 hooks、内存缓存、后台 shell 任务……Agent 结束后如果不主动释放，这些会一直占用资源
runAgent.ts将所有清理逻辑放在 finally {} 里：MCP 连接关闭、缓存释放、后台任务终止。
不管是正常结束、报错还是被中断，清理都必须执行~
任何用的Agent 框架（Claude Code、LangChain、CrewAI）都绕不过这五件事，只是实现方式有区别
我自己做实验不需要完整复现 runAgent.ts 的所有，因为那相当于再手搓一个残缺框架，重复造轮子，
只把自己感兴趣的地方最小成本复现出来，先挑的就是执行循环验证，完成单个Agent loop，简单来说就是完成
发消息 — LLM判断是否要调用工具 — 调用工具，工具结果放回message — 继续问LLM — 直到模型不要工具
这显然对新手更友好，接下来简单说下各部分的设计
二、第一个部分：先确认模型能正常回话
第一个实验先写的是 experiments/01_hello.py，负责调通和大模型的对话.env是包含 API key 的环境变量文件，提前配置好自己用的模型。
读 .env创建 OpenAI client 发一条消息 打印回复 打印 token 用量
这个很简单，token 用量也不多，跑完这个，说明LLM 调用链路通了。
Agent 虽然还没开始干活，但Agent后面都要接模型的，所以先确认Agent和模型能通话。
三、第二个部分：让模型自己决定调不调工具
第二个文件是 experiments/02_tools.py
这一轮开始有点 Agent 的内容了，里面写了个特别简单的本地函数：
然后把它包装成 function calling 的工具定义，交给模型。
用户给的问题是：问几月几号，模型不会硬答，返回的就是工具调用
程序执行完本地函数以后，把结果作为tool 消息塞回messages，再发第二次 API 请求。
最后模型回答：
调用日期本身没什么技术含量，不过这个模型能通过工具调用获取到当前时间的链路是可以跑通的
这一步跑通以后，模型已经不只是在聊天，它开始能通过工具去碰外部世界。
这里还有复现的时候，发现有个小点很重要，python里面写的：tool_calls 不能悬空。
模型说“我要调用这个工具”，程序就必须给它一个对应的工具结果。这个对应关系靠 tool_call_id 串起来。
如果中间断了，消息历史就不完整，下一轮就容易出错。之前看runAgent.ts里的 filterIncompleteToolCalls 时，对这个点还停留在源码注释层面，不理解为什么需要专门处理这种残缺消息，自己复现跑完就知道了
四、第三个部分：加入 while 循环，实现工具调用的loop
之前的两个都是单次的，后面要价格循环才能实现loop，python里面就是加个while true
设计逻辑也不复杂：
这里面我加了2个工具，一个获取当前时间，一个计算表达式。
工具有两个：
get_current_time、calculate比较有意思的是，模型第一轮一次性要了两个工具：
第二轮，它停止请求工具，直接给最终回答：
这次一共跑了 2 轮：
这轮能看到就是，代码里没有写死“先查时间，再计算”的流程，模型自己判断这个问题是否需要两个工具。
本地函数读模型的请求，执行工具，把工具结果递回去，这就是最小的 Agent loop
五、复现完有哪些意外的收获
项目做其实很简单，按实验一步步走，基本没碰到啥太大的问题：
验证的就是一个最小 Agent loop 里面有几个东西不能少
messages：是状态
tool_calls：是模型发出的行动请求
工具结果是外部世界给回来的反馈
while: 循环负责让它持续跑
模型不再请求工具时，任务才自然结束
这轮实验跑完以后，我对 runAgent.ts 里几个点的理解更具体了。
第一个是message
以前我知道 LLM API 是无状态的，每一轮都要把历史重新发过去。但在 02_tools.py 和 03_loop.py 里，messages 的增长过程是能直接看见的：
这让我重新理解了一次：Agent 的“记忆”来自程序维护的历史消息，再一轮一轮发回去；模型本身并不会在 API 调用之间保留这些内容。
这个点和之前读的那篇：
https://www.anthropic.com/engineering/building-effective-agents；
文章是一致的
context window 更像工作记忆，外部存储靠工具按需拉进来。
第二个是工具调用的边界
get_current_time 和 calculate 都很简单，但它们刚好说明了工具的角色：模型只提出调用意图，真实动作由外部程序执行。
这和runAgent.ts 里的工具裁剪、权限处理是类似的
模型不能随便做任何事，它只能在你给的工具箱里发请求。工具箱里有什么、参数怎么定义、结果怎么返回，决定了 Agent 能接触到多大的外部世界。
第三个是循环推出方式
03_loop.py 的退出条件很单一：没有 tool_calls，就认为模型给出了最终回答。
但ClaudeCode组作为生产系统，还要加 maxTurns、abort signal 和清理逻辑，这些防止无限循环的机制，因为真实系统里不是所有都会自然退出，还会有卡死、循环死、用户等不及kill等一系列问题
maxTurns是为了防止模型无限循环，abort signal 是为了防止用户中断，clean up 是为了防止后台任务清理。
第四个是日志和运行入口
这个是我加给实验的记录，Trae本身自己做终端脚本运行的时候，log路径写的稀奇古怪，还有些编码问题，其他Agent审阅的时候，并不能找准，所以就补了这个基础要求。
此外，还有些其他的小的容易踩坑的点
Windows终端里看中文，很容易乱码，所以后面的实验的脚本都加了这一段：
还有最小跑通的这个指令，带来的安全性问题
比如第三部分，03_loop.py 里的calculate工具现在是用 eval() 算表达式
自己做测试这么写很方便，能快速验证“模型调用计算工具”这个机制
但这东西肯定进不了正式环境，这就是代码注入风险
六、下一步功能拆什么
跑完这个之后，我想过一个问题：要不要继续补完整
不过后来感觉这个意义不大，因为真正做的时候，估计直接用 LangChain 或者 OpenAI Agent SDK这种框架就行
后面应该会写复盘写CC的父子 Agent 怎么拆任务。
因为一个 Agent 处理单任务，大致流程是这样子，但现实里的问题基本都更复杂
一个任务太大怎么办？要不要拆给多个 Agent 并行干？拆了之后结果怎么汇聚回来？父 Agent 和子 Agent 的上下文怎么传、怎么隔离？
ClaudeCode 设计里面，父 Agent 可以把完整的对话上下文 fork 给多个子 Agent，每个子 Agent 拿到一份相同的历史加上各自的任务指令，并行执行，最后汇报结果，这是对Context Window 中每一个token的极致利用
所以，下一篇应该会复盘下父子 Agent 拆任务的机制~
做这个事情有啥意义
其实CC源码泄露后，与其自己看，丢给Agent自己学，肯定是效率更高的一种方式，不过Agent会，和我会，中间其实还是会有个更巨大的gap
所以，系列开这个项目的复盘，就是帮助自己，从“让Agent能跑，但我知道Agent为什么能跑，怎么跑会更好”
这次用 opencode 生成最小 loop，再对照源码和日志复盘，反而把很多忽视的问题带出来了
有些问题想明白以后，再去看 LangGraph、CrewAI、Dify，或者继续读 Claude Code / Codex 的 harness，感觉会不一样。
你会不自觉开始看它怎么设计runtime：
怎么组上下文？给工具设边界？怎么退出？恢复？记录？怎么避免Agent自己绕死自己
这个系列应该会持续更新，但是时间频率会慢一些，因为还有其他想看的主方向，但如果这个对你有帮助
欢迎一键三连，下篇文章见~
