Claude Code Agent Loop 研究系列（00）—— 从聊天窗口到 loop
内容提要
Claude Code Agent Loop的核心机制是：用户输入后，harness记录历史并循环调用LLM，执行工具调用并追加结果，直到无工具请求才结束。用户仅参与首尾，中间自动运行。真实产品需处理上下文满、API失败、中断、工具崩溃等复杂情况，并集成hooks、权限批准、maxTurns等机制。
延伸解读
为什么需要 harness 层
LLM 本身是无状态的，每次调用都不会记住之前的对话。为了让 Claude Code 看起来像连续对话，必须有一个中间层（harness）来记录所有历史消息，并在每次调用时把完整历史打包发送。这就是为什么 messages 数组只增不减，而 harness 承担了所有记忆职责。
一次输入背后的多次调用
用户的一次输入可能触发多次 LLM 调用。每次工具执行后，结果都会被追加到消息历史中，然后再次调用 LLM 来决定下一步。直到 LLM 返回一条不带工具请求的消息，这一轮才算结束。因此，一次简单的 bug 修复可能背后有 5-10 次 LLM 调用。
agent 与 chatbot 的本质区别
Chatbot 每轮都等待用户输入，而 agent（如 Claude Code）只在开头和结尾等待用户，中间的过程完全由程序自动循环执行。这种自动循环是 agent 的核心特征，也是后续各种机制（如中断、权限批准、maxTurns 断路器、hooks）存在的前提。
真实产品远超 happy path
文章中的 5 行代码只是理想情况。真实产品需要处理上下文窗口满、API 失败、模型拒绝、用户中断、工具崩溃、max_tokens 触顶、并行执行、hooks 集成等多种复杂情况。这些都被编织进主循环，使得实际代码远比基础循环复杂。
Q&A
Claude Code Agent Loop 的核心机制是什么？
Claude Code Agent Loop 的核心机制是：用户输入后，harness 记录历史并循环调用 LLM，执行工具调用并追加结果，直到 LLM 返回不带工具请求的消息才结束。用户只参与开头和结尾，中间过程自动运行。
为什么 Claude Code 需要 harness 层？
因为 LLM 本身是无状态的，每次调用都不知道之前的对话。harness 负责记录历史，并在每次调用 LLM 时将完整的历史消息打包发送，从而实现连续对话。
一次用户输入在 Claude Code 中会触发多少次 LLM 调用？
一次用户输入通常对应 5-10 次 LLM 调用，具体取决于工具调用的次数。每次工具执行后，harness 都会将结果追加到消息中，并再次调用 LLM 来决定下一步，直到 LLM 返回不带工具请求的消息。
