详细解析Pi源代码学习：Session的两层含义与createAgentSession基本使用

在动手前，请务必完成环境搭建。正确的操作顺序至关重要。

第一步，检查 Node.js 版本满足 >= 22.19.0。然后通过 cd 进入目标项目目录，使用 git clone 命令拉取源代码。该命令会自动创建一个 pi-mono 文件夹，接着再 cd 进入该目录。

在 pi-mono 目录中安装项目依赖并执行构建步骤。

接下来配置模型的 API Key。本示例以 minimax 国内版为例，如需使用其他模型请参照官方文档。

完成上述配置后，通常即可使用 Pi。若想先尝试 TUI，可在仓库根目录（pi-mono）运行 npx pi，Linux/macOS 用户也可使用 ./pi-test.sh。如果已经全局安装了 @earendil-works/pi-coding-agent，直接输入 pi 命令即可启动。其使用方式类似于 Claude Code，在终端中与 Agent 进行交互。不过，本文将从 coding-agent 包的 SDK 示例开始讲解，执行以下命令运行第一个示例 01-minimal.ts。

为何使用 createAgentSession？

上一期我们从底层向上解析了 Pi 的三层架构：pi-ai 负责模型调用，pi-agent-core 管理 agent 循环，pi-coding-agent 则将它们组合成可直接使用的 Coding Agent。在这三层中，对外的统一接口便是 createAgentSession()，官方 SDK 文档称其为创建 AgentSession 的主工厂函数。

换句话说，只需使用 createAgentSession() 一行代码，无需传入参数，即可配置好模型、工具、会话持久化以及 skill 发现等完整的 Harness 能力。如果需要调整某个部分，只需在参数中指定；examples/sdk/ 目录下从 02 到 13 的示例，均是在此入口基础上更换不同配置。因此，从这个函数入手，能最快理解 Pi 对外提供的功能。

后续在深入阅读源码时，从 session.prompt() 向下追踪，会依次经过内部 Agent.prompt()、agent loop，最终在 pi-ai 中调用 streamSimple() 向模型发送请求。在这个意义上，createAgentSession() 确实是理解整个系统的最佳入口。

什么是 Session？

在进入示例代码之前，有必要先理解 Session 的概念。在 Pi 中，“Session”至少包含两个层面。

第一个层面是“一次对话的存档”——Pi 将你在项目中与 Agent 的完整交流记录视为一个 Session 进行管理。

通俗来说，这一层面的 Session 就是一份带有唯一编号的对话档案：每个 Session 拥有唯一的 sessionId，记录了当时的工作目录（cwd）、创建时间，以及从第一条用户输入到最新回复的完整交互记录——包括用户说的内容、模型生成的回复、调用的工具以及中途切换的模型等。当你在 TUI 中使用 /resume 选择历史对话继续，或使用 /fork 从某条消息分叉出新分支时，实际上都是在操作这类档案。这个层面的 Session 如何持久化到本地设备，由 SessionManager（位于 packages/coding-agent/src/core/session-manager.ts）负责。

第二个层面是运行时对象 AgentSession——即 createAgentSession() 返回的 session 对象。

session 对象 定义在 packages/coding-agent/src/core/agent-session.ts，它是 Pi 的 interactive、print、rpc 等多种运行模式所共享的核心抽象。我们调用的 session.prompt()、session.subscribe()、session.dispose() 等方法，都是作用于该对象。

该对象内部持有已配置好工具、模型和扩展的 Agent（如上一期所述：session.prompt() 最终会转发给 agent.prompt() 执行 loop）；同时它还包含 SessionManager、SettingsManager 等组件，在 loop 之外负责处理配置读取、事件推送、自动持久化、压缩等 Harness 事务。

简而言之，AgentSession 解决的是如何与 Agent 进行交互，而第一层面提到的 JSONL 档案解决的是如何事后找回并继续对话。当然，这两个层面关系紧密，createAgentSession() 默认将它们绑定在一起：运行中的 AgentSession 会通过调用 SessionManager，将对话内容实时同步到第一层面的 JSONL 档案中。

接下来，我们先通过第一个示例代码来理解 Pi SDK，尤其是 createAgentSession() 的基本功能。

最简示例：01-minimal.ts

官方提供的最简示例位于 packages/coding-agent/examples/sdk/01-minimal.ts，完整代码如下。

这段代码展示了 Pi SDK 的典型使用模式。官方 examples/sdk/ 目录中的示例大多遵循相同流程：首先使用 createAgentSession() 创建 session，然后通过 session 与 Agent 交互，最后调用 session.dispose() 释放资源。

这些示例均为一次性运行模式——发送一条 prompt、获取结果、释放资源，进程随即终止。如果你想实现持续对话，可以在自己的脚本中保持同一个 session 不销毁，循环调用 session.prompt()，这样每一轮输入都会追加到同一段对话历史中。

下面我们来详细解析这个示例代码。

1. 创建 AgentSession

在该示例中，我们并未向 createAgentSession() 传递任何参数。这意味着 Pi 构造出的 AgentSession 在模型、工具、工作目录、存档方式等方面均采用默认配置。具体如下：

也就是说，只需编写一行 createAgentSession()，Pi 就会按照上表配置好一套完整的 Coding Agent。当然，你也可以通过传递参数来修改模型、工具等配置，这正是后续示例代码所要展示的内容。

2. 监听：session.subscribe()

示例代码在 session.prompt() 之前注册了一个 session.subscribe()。这个 subscribe 方法是 Pi 对外提供的底层事件通道。其原理是将一个回调函数注册到 AgentSession 的监听器列表中，在运行过程中每当 Pi 产生一个 AgentSessionEvent，就会调用该回调并传入事件对象。

当 Agent 开始运行，它会持续抛出过程事件，例如模型流式输出、工具开始执行、工具返回结果、本轮结束等。对于 TUI 而言，这些事件成为界面更新的数据源：UI 并非在任务完成后才去查询 messages，而是订阅同一事件流，每个事件描述“当前发生的事”，界面据此进行增量刷新。你在终端中看到的对话内容和工具进度，本质上是 Agent 运行过程通过此通道实时投射到屏幕上的。

让我们具体查看相关代码。

以上代码的实际效果是，在 Agent 运行期间将模型回复的流式文本实时输出到终端。

Pi 在运行过程中会反复调用此回调；每次调用时，都会对接收的事件进行两个条件判断：

• event.type === "message_update"：该事件表示“消息内容正在更新”，即模型尚未完成完整回复，Pi 正在推送中间状态。
• event.assistantMessageEvent.type === "text_delta"：本次更新涉及正文文字的流式片段；event.assistantMessageEvent.delta 即为本次新增的一段文本。

当上述两个条件同时满足时，Pi 会将事件携带的增量文本（即 delta）通过 process.stdout.write 连续输出。由于 process.stdout.write 不自动换行，因此文本会不断追加在同一行，形成逐字出现的效果。

值得一提的是，subscribe 可以监听的并不限于流式文字。根据官方 examples/sdk/README.md 的说明，你还可以监听 tool_execution_start（工具开始执行）、tool_execution_end（工具执行完成）、agent_end（本轮结束）等事件——TUI 的 handleEvent() 也遵循相同的事件分类策略。不过，在 01-minimal.ts 中，这一步并非强制：不写 subscribe 同样可以正常向 Agent 发送指令并完成运行；只是脚本无法实时显示过程输出，需要等待 Agent 结束后，再通过 session.state.messages 一次性查看完整记录。

3. 使用：session.prompt()

前面两步准备好之后，与 Agent 对话的核心操作就是这一行。

session.prompt() 是 SDK 中最核心的 API——你只需传入用户输入，Pi 便会处理其余所有工作。

上一期提到，第二层 agent 包中的 agent.prompt() 会先将用户输入包装成一条 user 消息，添加到 state.messages，然后进入 agent loop 调用模型；如果模型返回 tool call，则执行相应工具、将结果写回，并自动触发下一轮调用，直到本轮不再产生 tool call 为止。这就是 Agent 的核心工作：维护内存中的对话状态，并完成 ReAct 式的内层循环。

session.prompt() 并不是另起炉灶。AgentSession 内部持有一个已配置好的 Agent，也就是说，当你调用 session.prompt() 并完成准备工作后，最终仍会转到 agent.prompt() 来执行 loop。

区别在于，Session 在 loop 外层又封装了一层 Harness。对 Pi 而言，session.prompt() 在将消息传递给 Agent 之前，已经为用户完成了一轮“发送前处理”——扩展可以拦截或修改输入，skill / 模板命令会先展开，系统提示词会根据扩展要求刷新，模型和鉴权也会先进行校验。

消息进入 loop 后，内部行为与 agent.prompt() 完全一致；loop 抛出的事件，AgentSession 会捕获并向外转发：此前注册的 subscribe 可以实时接收，SessionManager 也会将消息写入本地档案。loop 执行完毕后并非就此结束——如果需要自动重试、上下文压缩等操作，Harness 还会进行后续处理，必要时会驱动 agent.continue() 补充运行。

换句话说，agent.prompt() 专注于“单个轮次如何运行”；session.prompt() 则负责“发送前的准备、运行中的记录与广播，以及运行后的收尾工作”。示例中虽然仅有一行字符串看似简单，但实际上外层 Harness 已经在幕后完成了所有繁琐的工作。

示例询问“当前目录有哪些文件”。这类问题 Agent 无法直接回答，通常会调用默认工具中的 bash（例如执行 ls）来查询，然后将结果组织成自然语言回复给你。如果之前注册了 subscribe，流式文字和工具进度会边运行边打印；这里的 await 则是等待整轮 loop 彻底完成 再继续执行——期间可能经历多轮模型调用和工具交互，但对你而言，只需“发一条指令，等它完成”即可。

4. 收尾 session.dispose()

prompt() 返回后，示例并未立即退出，而是先查看对话记录，再释放 session。

session.state.messages 是当前内存中的完整对话列表，本质上它与内部 Agent 的 state.messages 一致。完成一轮 prompt() 后，该列表通常包含多条消息：用户输入、模型的助手回复、中间的 tool call 和 tool result 等。示例使用 forEach 逐条输出到 console.log，便于你对照查看 Agent 实际经过的步骤——如果之前未启用 subscribe，这里就是一次性查看完整运行记录的主要方式。

session.dispose() 用于告知 Pi“此 session 已使用完毕”。它会断开与内部 Agent 的事件连接、清理监听器，并释放本轮占用的资源。示例将其置于 finally 块中，确保无论 prompt() 成功还是抛出异常，都能执行收尾操作。值得留意的是，对话记录已在运行过程中由 SessionManager 处理完毕，dispose() 并不负责“保存聊天记录”，而是负责干净地关闭运行时对象。

总结

本期内容从上一期的三层架构理论落到 SDK 实践，通过官方最简示例 01-minimal.ts 演示了 createAgentSession() 的基本用法。

1. createAgentSession()：只需一行代码且无需传递参数，Pi 便会按默认配置自动设置模型、工具、工作目录和会话持久化——这是第三层 Harness 对外的统一入口。
2. session.subscribe()（可选）：注册回调函数以接收 Agent 运行期间的事件流；示例仅处理 text_delta 事件，使你能够实时查看模型回复，TUI 的实时展示也依赖同一机制。
3. session.prompt()：表面写法与第二层的 agent.prompt() 类似，但额外封装了一层 Harness——发送前处理、运行中广播与存档、运行后收尾，内部 loop 仍由 Agent 执行。
4. session.dispose()：负责安全地释放运行时占用的资源。

成功运行此示例后，我们就掌握了 Pi SDK 的标准流程：创建 session → 按需订阅 → 发送指令 → 释放资源。examples/sdk/ 中从 02 到 13 的后续示例，均是在此基础上替换模型、工具、存档方式等配置——这些定制化内容我们将在后续逐步探讨。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：详细解析Pi源代码学习：Session的两层含义与createAgentSession基本使用要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题