Agent Loop：一个循环，就是模型与真实世界之间的全部距离

整个决策树只有两个分支：模型返回 tool_calls 了吗？是——执行工具喂回去再问一次；否——退出。循环是机械的，没有智能。

模型返回 tool_calls?
├── 是 → 执行工具，把结果喂回去，再问一次
└── 否 → 模型觉得做完了，退出

Agent = 模型决策 + Harness 执行 + 消息历史传递。换一种说法：Agent = LLM + 上下文 + 工具。系统提示、消息历史和工具 schema 组成了观察空间；ToolRegistry 里的工具组成了动作空间。

Agent = LLM + 上下文 + 工具
- LLM：决定要不要用工具、用哪个、传什么参数
- 上下文：模型每个决策点能看到的观察空间
- 工具：模型改变世界的动作空间

for 循环 + maxTurns 有界；每轮先请求模型，追加 assistant 消息；无工具调用且有文本就返回；否则逐个执行工具、回填 tool 消息，进入下一轮。

for (let turn = 1; turn <= maxTurns; turn += 1) {
  const reply = await model.complete(request);
  history.push(reply.message);
  if (reply.message.toolCalls.length === 0) return reply;
  for (const call of reply.message.toolCalls) {
    const result = await executeTool(call, context);
    history.push(toolMessage(result.content, call.id));
  }
}

两种格式形式不同，但本质信号一致：『模型有没有举手要工具』。OpenAI 用 message.tool_calls 数组与独立的 tool 角色；Anthropic 用 stop_reason==tool_use 与嵌在 user 消息里的 tool_result。

判断是否调工具:
  OpenAI:  response.choices[0].message.tool_calls 非空
  Anthropic: response.stop_reason == "tool_use"
结果消息 role:
  OpenAI:  tool（有 tool_call_id）
  Anthropic: user（内嵌 tool_result）

真实章节入口把 shell 标记为 execute，每次执行前询问『允许本次调用? [y/N]』，只有明确 y/yes 才执行。但 cwd 只是子进程起始目录，命令仍可访问绝对路径、切换目录或访问网络。

允许本次调用? [y/N]
→ 只有 y / yes 才执行
→ 回车、其他输入、无交互 stdin 都默认拒绝
→ 拒绝仍生成同一 tool_call_id 的工具错误结果

只有两个关心的部分：messages（模型能看到什么）和 tools（模型能做什么）。parameters 就是工具说明书，由 z.strictObject({ command: z.string().min(1) }) 自动生成——同一份定义既生成说明书又用于校验参数，不会错位。

{
  "model": "gpt-4.1",
  "messages": [
    { "role": "system", "content": "You are a coding agent..." },
    { "role": "user",   "content": "运行 Write-Output 42，并告诉我结果" }
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "shell",
      "description": "Run a PowerShell command in the current workspace.",
      "parameters": {
        "type": "object",
        "properties": { "command": { "type": "string", "minLength": 1 } },
        "required": ["command"],
        "additionalProperties": false
      }
    }
  }]
}

{
  "choices": [{
    "finish_reason": "tool_calls",
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": { "name": "shell", "arguments": "{\"command\":\"Write-Output 42\"}" }
      }]
    }
  }]
}

① 按名字查工具       shell → 找到定义（找不到就生成 unknown_tool 错误结果）
② 解析 arguments     JSON.parse('{"command":"Write-Output 42"}')
③ Zod 校验           必须有 command、必须非空字符串、不能有多余字段
④ 人工审批           终端打印命令，等你输入 y
   ↓ 你批准了
⑤ 真正执行           启动 PowerShell 子进程，拿到 stdout "42"

上一轮的 assistant 消息要原样留在历史里，然后紧跟一条 role: "tool" 的新消息。tool_call_id 和上一轮的 id 对上，这是模型唯一的线索。

"messages": [
  { "role": "system", "content": "..." },
  { "role": "user",   "content": "运行 Write-Output 42，并告诉我结果" },
  { "role": "assistant", "content": null,
    "tool_calls": [{ "id": "call_abc123", "type": "function",
      "function": { "name": "shell", "arguments": "{\"command\":\"Write-Output 42\"}" } }] },
  { "role": "tool", "tool_call_id": "call_abc123", "content": "42" }
]

→ 模型回复：finish_reason="stop"，content="命令执行成功，输出是 42。"，tool_calls=[]

它能验证代码本身没问题，把「环境问题」和「配置问题」分开。中间会看到一行 配置错误: Missing required settings: ...——这是正常的，它是 config.test.ts 故意触发的用例输出。

npm run test:ch01

 Test Files  6 passed (6)
      Tests  30 passed (30)

# 入口一：固定章节脚本
npm run ch01 -- --prompt "运行 Write-Output 42，并告诉我结果"

# 入口二：统一 CLI
npm run agent-tutorial -- run --chapter 1 --prompt "运行 Write-Output 42，并告诉我结果"

工具调用需要批准: shell
原因: PowerShell command execution requires explicit approval.
参数: {"command":"Write-Output 42"}
允许本次调用? [y/N]

• Agent Loop 就是「问模型 → 看 tool_calls 空不空 → 执行工具 → 把结果 push 回历史 → 再问模型」，代码不到 60 行。
• 循环只有一个分叉点（tool_calls 空不空）和三个出口（正常返回、轮次耗尽、不可恢复错误）。
• 生产级 Agent 的代码量差距不在循环，全在循环外围的保护：校验、审批、错误分类、恢复、上限。

• 模型返回 content: "好的" 且 tool_calls: []，循环该继续还是结束？
• 模型返回 content: null 且 tool_calls: []，代码该怎么做？为什么不能直接返回？
• 模型一轮请求了 3 个工具，其中 1 个执行失败。要往历史里 push 几条 tool 消息？
• snapshot() 到底防的是什么问题？
• 为什么 maxTurns=20 指的是 20 次模型请求，而不是 20 次工具调用？