第 2 课：Pi 项目结构总览

结论

读 Pi 不要从目录树开始，而要从三个用户可见行为反推模块边界：一次 prompt 如何启动、工具如何被调用、模型和资源如何进入 session。

入口问题

为什么一个 SDK 调用能同时牵动模型、工具、事件、上下文和会话？

心智模型

• SDK 入口负责创建可交互的 session。
• Agent core 负责 message state、turn、tool call 和 tool result。
• Coding-agent 层负责工具实现、资源加载、认证、模型 registry 和宿主模式。
• TUI、print、RPC 等模式只是不同外壳，它们最终都要拿到同一种 session runtime。

源码推演（省略版）

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

async function createSession(options: SessionOptions) {
  const services = createServices(options);
  const tools = createTools(services.toolPolicy);
  const resources = await services.resourceLoader.load();

  return new AgentSession({
    modelRegistry: services.models,
    tools,
    resources,
    sessionStore: services.sessions,
  });
}

• 这段源码形状说明 Pi 的包边界不是按“文件夹名”理解，而是按职责理解。
• createServices() 聚合认证、配置、资源和会话；createTools() 把工具权限落成真实工具集合。
• AgentSession 是学习者最应该先抓住的边界：外部使用它，内部再连接 core loop。

课堂练习

画出从创建 session 到一次 prompt 完成的高层模块图，只写职责，不写源码位置。

掌握标准

• 能从行为反推模块，而不是从目录逐个扫。
• 能说明 SDK、agent core、coding-agent 外壳和宿主模式之间的关系。
• 能为后续源码课提出具体问题。

课后习题

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