Thought:  我需要先查一下 Apple 的创始人是谁          ← Reason：想
Action:    Search[Apple 创始人]                      ← Act：动（一个文本指令）
Observation: Apple 由 Steve Jobs、Steve Wozniak 创立…  ← 程序执行后，把结果拼回 prompt
Thought:  我还需要查 Wozniak 的出生年……              ← 带着观察，继续想

/** Context snapshot passed into the low-level agent loop. */
export interface AgentContext {
  systemPrompt: string;          // ① 说明书：你是谁、有哪些工具、守什么规矩
  messages: AgentMessage[];      // ② 记事本：完整对话历史（R/A/O 全在里面）
  tools?: AgentTool[];           // ③ 工具箱：模型可以申请使用的动作
}
// ④ 发动机：agent-loop.ts 的 while 循环，推着 ①②③ 转起来

{
  role: "assistant",
  content: [
    { type: "thinking",  thinking: "用户要总结 README，我得先读到它……" },  ← 草稿纸（可选）
    { type: "text",      text: "我先看一下项目根目录。" },              ← 说给你听的话
    { type: "toolCall",  id: "call_01", name: "read",
      arguments: { path: "README.md" } }                             ← 动作申请（给循环看）
  ],
  stopReason: "toolUse",   ← 为什么停笔：因为有工具要执行
  usage: { input: 3122, output: 89, … },
  timestamp: 1756600000000
}

export interface AgentTool {
  name: "read";                // ① 模型看到的函数名
  label: "Read";               // ② UI 显示名
  description: "Read file contents";  // ③ 卖给模型的广告词（直接影响调用质量）
  parameters: Type.Object({     // ④ 参数 schema：JSON Schema + 逐字段 description
    path:   Type.String({ description: "Path to the file to read" }),
    offset: Type.Optional(Type.Number({ description: "1-indexed start line" })),
    limit:  Type.Optional(Type.Number({ description: "Max lines" })),
  }),
  execute: async (toolCallId, params, signal, onUpdate) => { … },  // ⑤ 真正干活的 handler
  executionMode?: "sequential",  // 可选：强制本工具串行执行
}

execute: async (toolCallId, params, signal, onUpdate) => {
  await access(absolutePath);                 // ① 权限检查：读不到就 throw（循环会接住）
  const buffer = await readFile(absolutePath); // ② 真正的「动作」：一行 fs 调用
  //    图片文件走另一条路：探测 MIME → 压到 2000×2000 → 返回 image 块
  const truncated = truncateHead(text, {      // ③ 节流：观察也有成本
    maxLines: 2000, maxBytes: 50 * 1024,      //    超出就截头留尾 + 说明被截断
  });
  return {
    content: [{ type: "text", text: truncated.text }],  // 给【模型】看的
    details: { truncation: truncated },                 // 给【UI】看的
  };
}

{
  role: "toolResult",
  toolCallId: "call_01",      ← 与 assistant 消息里的 toolCall.id 严格配对
  toolName: "read",
  content: [{ type: "text", text: "# My Project\n…" }],
  isError: false,             ← 错误标记直接长在消息上
  timestamp: 1756600000123
}

type Msg = any;  // 简化：实际项目应使用 provider SDK 的消息类型

async function runAgent(
  systemPrompt: string,                      // 原料① 说明书
  tools: { name: string; description: string;
           parameters: object; execute: (args: any) => Promise<string> }[],  // 原料③ 工具箱
  messages: Msg[],                           // 原料② 记事本（外部持有 → 状态即数据库）
  callLLM: (msgs: Msg[]) => Promise<Msg>,   // pi 的 StreamFn 对应物
): Promise<Msg[]> {
  while (true) {                             // 原料④ 发动机
    const reply = await callLLM([
      { role: "system", content: systemPrompt },
      ...messages,                           // ← 无状态模型：每次全量带上历史
    ]);
    messages.push(reply);                    // R：想法先入账

    const calls = reply.content.filter((c: any) => c.type === "tool_use");
    if (calls.length === 0) return messages; // 没有动作申请 → 模型交卷，循环出口

    for (const call of calls) {
      const tool = tools.find(t => t.name === call.name);
      let result: string, isError = false;
      try {
        result = tool
          ? await tool.execute(call.input)   // A：替模型动手
          : throwErr(`Tool ${call.name} not found`);
      } catch (e) {
        result = String(e); isError = true; // 错误即观察：绝不向上抛
      }
      messages.push({                        // O：结果写回（含错误）
        role: "tool_result", tool_use_id: call.id,
        content: String(result).slice(0, 50_000),  // 节流：观察也要限量
        is_error: isError,
      });
    }                                        // ↻ 带着观察，回到下一轮 R
  }
}
function throwErr(m: string): never { throw new Error(m); }