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 核心契约 · 第二课

这一页,先记到这里。