pi-ai 核心契约速查

查阅公共数据类型、归一化上下文和响应流的终止规则。

本章目录CONTENTS ↓

本章以 Pi 1.1.0 的 2026-10-11 源码快照 为基准;实验性接口不代表长期兼容承诺。

五种形状构成 Agent 与 provider 之间的语言;provider 的任务是翻译,不是重新定义它们。

抽象 回答的问题 关键字段 mini_pi 兼容点
Model 调用谁、能力和限制是什么? id, api, provider, input, contextWindow, maxTokens 路由与能力字段保持可观察一致。
Message 对话历史由哪些角色组成? system | user | assistant | toolResult 保留 role/content discriminants。
Tool 告诉模型有哪些调用能力? name, description, parameters 这里只是声明;执行属于AgentTool。
Context 这一次请求让模型看到什么? systemPrompt, messages, tools 它是请求快照,不是 Agent 全部状态。
AssistantMessageEventStream 响应如何渐进到达并最终结算? AsyncIterable<event> + result() 增量事件和最终值都必须存在。

公开入口的 Context 会经 normalizeContext() 转为 TranscriptContext:system prompt 与工具声明进入 system message,provider 只接收归一化后的消息序列。

终止规则

  • 成功路径先发出 start,再发更新和 done;请求准备阶段失败时,可以直接发出 error。
  • 中间事件按 content block 使用text_*、thinking_*或toolcall_*。
  • 成功以done终止;失败或取消以error终止。
  • done 或 error 被 push 时,result() 解析为最终 AssistantMessage;流内失败也不通过 Promise rejection 表达。生产者还可以通过底层 end(result) 显式提供终值。
  • 已经返回 stream 后,request/model/runtime 失败应编码进流。直接调用底层 streamSimple() 时,缺少认证可能同步抛错;Models.streamSimple() 的认证处理位于延迟流中。

completeSimple没有第二套实现 在Models中,它就是streamSimple(...).result()。流是原语,complete 是便利封装。

第一手来源:ai/src/types.ts · event-stream.ts · providers/faux.ts · Agent 事件顺序

这一页,先记到这里。