Pi 的工作方式

本页面是 Pi 官方文档的中文翻译。仅供学习参考。

Pi 协调模型请求、工具执行、上下文组装和会话存储。会话是 Pi 对一段对话的记录，包括消息、tool call 和结果、模型变更、压缩以及其他事件。

会话中的消息和事件构成一棵树。穿过这棵树的每条路径都是一个分支。结束于当前条目的分支是活动分支，它为下一次模型请求提供历史。

Agent 循环

提交的消息会加入活动分支。Pi 用系统提示、活动分支、可用工具和模型设置构建模型请求，然后通过选定的 Provider 发送。

Provider 以流式返回 assistant 响应，其中可以包含文本和 tool call。Pi 记录该响应，执行每个 tool call，并记录结果。这样完成一个 turn。如果工具结果或排队消息需要另一次模型请求，Pi 就开始下一个 turn；否则运行结束。

Steering 消息在当前 assistant turn 之后进入。Follow-up 消息在 Agent 完成待处理工作之后进入。中止会停止当前运行，并把排队消息退回编辑器。

活动分支提供对话历史。Pi 把会话条目转换为模型可用的 user、assistant 和 tool-result 消息。

Pi 用基础指令和发现的上下文文件构建系统提示。请求还携带工具定义和 Skill 描述。

完整的 Skill 指令按需加载。扩展可以添加指令或转换上下文。

Prompt 模板在编辑器输入成为用户消息之前展开。选中的文件、图片、粘贴的文本和 Shell 输出都可以成为消息内容。

持久会话是 JSONL 文件。每个树条目都有 ID，并指向它的父条目。当前条目标识活动分支。

从更早的条目继续会在同一个文件中产生另一个分支。Fork 和 clone 会把选中的历史复制到新的会话文件。

模型上下文从活动分支重建。压缩会插入一条摘要条目，在后续模型请求中替换较早的消息。原始条目仍留在会话树中。

交互模式在终端中渲染会话和 Agent 事件。Print 模式运行一次 Prompt 并写出最终响应。JSON 模式把 Agent 事件写成 JSONL。

RPC 模式在 stdin 上接受 JSONL 命令，并把响应和事件写到 stdout。TypeScript SDK 在进程内创建和控制 Agent 会话。

所有界面使用相同的 Agent 和会话机制。

扩展是加载到 Pi 进程中的 TypeScript 模块。它们的工厂函数注册工具、命令、快捷键、Provider、事件处理器、渲染器和终端 UI。

Skill 提供按需加载的指令和配套文件。Prompt 模板提供可复用的消息文本。主题提供终端配色。Pi 包通过 npm 或 git 分发这些资源。

Pi 在加载项目设置和资源之前先确定项目信任。在信任决策和项目资源加载之后，Pi 加载上下文文件。启用的工具使用 Pi 进程的操作系统权限。扩展在该进程内执行。

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。