第 3 课：SDK 心智模型

结论

Pi SDK 不是“调用模型并返回字符串”的薄封装。它更像一个可嵌入的 agent harness：session 是外部 API，model 负责生成下一步，tool 让模型影响外部世界，event 暴露运行过程，resource 决定系统提示和上下文，session manager 保存任务连续性。

入口问题

为什么 prompt() 的返回值不是学习重点，事件流和 session state 反而更重要？

心智模型

• AgentSession 是应用代码持有的对象。
• message 是模型、用户和工具结果共同组成的上下文。
• turn 是一次 assistant 响应加上它触发的工具结果。
• event 是宿主观察运行过程的稳定接口。

源码推演（省略版）

下面不是完整源码，而是把本课主线压缩成可以在文档里直接阅读的关键形状。读者即使不打开本地源码，也应该能看出运行时如何组织职责。

class AgentSession {
  subscribe(listener: EventListener) {
    this.listeners.add(listener);
  }

  async prompt(input: string) {
    const userMessage = createUserMessage(input);
    await this.store.append(userMessage);
    await this.agent.runUntilIdle({ messages: this.store.context() });
  }
}

• 省略版源码展示了两个重点：外部先订阅事件，再用 prompt() 推动执行。
• prompt() 不应该被理解成“返回字符串”，而是“追加用户消息并驱动 agent 跑到 idle”。
• 输出、工具调用、错误和结束状态都应该通过事件或 session state 观察。

课堂练习

用自己的话解释 session、message、turn、tool result、event 的区别。

掌握标准

• 能把一次 prompt 拆成输入、上下文、模型、工具、事件和持久化。
• 能说明为什么输出来自事件流。
• 能解释 session manager 对长任务的重要性。

课后习题

1. 实践题：基于本课的省略版源码，补出一个最小实现草图，要求写清输入、输出、副作用和错误处理。
2. 思考题：本课机制如果只靠 prompt 约束，而不放进 harness 或 runtime，会出现什么工程风险？