Pi 设计词汇表
统一消息、请求上下文、turn、run、队列和会话等概念的含义。
本章以 Pi 1.1.0 的 2026-10-11 源码快照 为基准;实验性接口不代表长期兼容承诺。
课程统一使用这些词。定义以 Pi 1.1.0 快照为准,区分相关但职责不同的概念。
| 术语 | 本课程中的精确定义 | 兼容意义 |
|---|---|---|
Message |
pi-ai定义的 provider-neutral 系统、用户、助手或工具结果消息。 |
跨 provider 的公共数据语言。 |
AgentMessage |
Message加上应用通过 declaration merging 扩展的自定义消息。 |
允许 UI/session 保存模型不理解的条目。 |
Context |
公开入口接受的一次请求输入,包含消息及 system prompt、工具的简写。 | 经 normalizeContext 生成 provider 接收的 TranscriptContext。 |
TranscriptContext |
经归一化并带有类型品牌的消息序列,提示词和工具声明放在 system message 中。 | 避免原始 Context 直接进入 provider 实现。 |
turn |
一个 assistant response 加其发起的整批 tool calls/results。 | 事件顺序与停止判断的基本单位。 |
run |
从一次 prompt/continue 开始,经过零到多轮 turn,直到 Agent 停止。 | agent_start到agent_end的生命周期。 |
StreamFunction |
把 Model + TranscriptContext + options 映射为 assistant event stream 的 provider 函数类型。 |
公开 Context 需要先经过归一化。 |
tool loop |
识别 tool call、校验参数、执行、生成 tool result,再请求模型的循环。 | mini_pi 最小内核的核心状态机。 |
steer |
当前 assistant turn 完成工具执行后、下一次模型请求前注入的消息。 | 不是中断当前工具调用。 |
followUp |
Agent 原本将停止时才被取出的排队消息。 | 与 steer 的 drain point 不同。 |
AgentSession |
coding-agent中组合 Agent、持久化、资源、压缩和扩展的产品级会话。 |
CLI/SDK 的主要行为门面。 |
SessionManager |
维护 JSONL 会话头、条目树、当前叶节点和恢复信息的组件。 | 文件格式与树语义均属兼容面。 |
wire DTO |
pi-protocolschema 允许在线路上传输的数据形状。 |
不能直接等同于pi-ai领域对象。 |
架构与课程地图 · Agent 事件顺序 · pi-ai 核心契约 · 第二课
这一页,先记到这里。