核心概念

最后更新：2026-10-10

四个贯穿 Pi 运行时的基本概念。理解了它们，就能读懂任意一层的代码。这些概念不是孤立的：它们共同支撑起 Pi 的「可自我扩展」能力——工具、扩展与资源在运行时按需加载，而内核无需重启。

1. 消息、流式事件与状态

Pi 内部以「消息」为单位传递信息，模型返回分为两类信号：

• message_update：文本增量、推理过程等流式更新，用于实时渲染。
• toolCall：模型请求执行某个工具，附带参数。

这些信号被封装为 AgentEvent 沿着「核心循环 → Agent → Session → UI」向上回传，UI 据此增量更新界面，而不必等整轮结束。这种流式回传让长任务也能实时可见，也是总体架构里交互层能「只管发声」的前提。

2. 工具调用机制

工具是 Pi 与外部世界交互的出口。机制要点：

• 注册：工具在注册表中声明名称、描述与参数 schema。
• 执行：模型给出 toolCall 后，运行时校验参数并执行，得到 AgentToolResult。
• 回写：工具结果作为一条新消息写回会话，供下一轮模型推理使用。

3. 会话、树与分支

会话以 JSONL 形式持久化，天然支持「树」与「分支」：

• 每个消息一行，便于追加与回放。
• 同一会话可以从任意节点分叉，探索不同解决路径。
• 支持断点续跑：中断后可从已有会话恢复。

这种结构让编码过程可审查、可分享——配合 pi-share-hf 还能把会话发布到 Hugging Face。在运行与调试中，你可借助会话树回放并定位某一轮工具调用的来龙去脉。

4. 上下文、技能与压缩

随着会话变长，塞进模型的上下文会超出窗口。Pi 的处理方式：

• 技能/模板展开：Session 在请求模型前，按需把相关技能与模板注入上下文。
• 上下文压缩：当接近上限，自动压缩历史（摘要、裁剪低价值消息），保留关键信息。
• 进阶边界：压缩有取舍——过度压缩会丢失细节，Pi 在「保留有用信息」与「控制 token 成本」之间做平衡。

上下文构建与压缩同样是 pi-agent-core 的职责之一。若想从零观察这套机制，快速上手里的 MockModel 例子最直观。

相关阅读

• 总体架构：这些概念发生在哪一层。
• 运行与调试：如何在本地观察事件与压缩。
• 核心包：概念对应的代码归属。