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 事件顺序
这一页,先记到这里。