← Pi Agents

界面不是智能体

终端、print 模式、JSON 流、RPC 和 SDK 是驱动同一个智能体的五种方式;换界面后仍存留的东西,是智能体自成一层的证据,而存留不了的东西,是给扩展的设计规则。

你已经花了三十章,其中大部分时间都待在终端里,很容易在合上书时以为终端就是 Pi。它不是。终端是驱动一个智能体的五种方式之一,而你用哪一种,改变的是你如何观察它,不是它是什么。

这是一个关于架构的论断,而本书这一部分的结尾就是对它的检验。第 32 至 35 章一次讲一个界面。本章陈述它们共享什么,展示这种共享是真实的,并说出那唯一一处界面确实漏进"一个扩展可以假设什么"的地方。

结果

一次脚本化运行,在随附的二进制文件上分别通过 print、JSON 和 RPC 发送,给出了相同的答案、相同顺序的相同事件。它没有给出相同的失败行为、相同的完成信号或相同的控制面。这就是整章的内容,两行说完:

相同的底层智能体行为             !=   相同的外部控制契约
智能体语义                       !=   驱动语义
Print JSON RPC
一次失败的响应 非零退出状态,stderr 上有消息 退出状态 0,失败在事件流里 在事件流里,而 prompt 命令本身成功了
它什么时候算完成 进程退出 agent_settled,然后退出 agent_settled,进程保持运行
什么接受这项工作 命令行 命令行 一个响应,disposition: "started",在运行开始之前
你如何匹配一条回复 不需要 不需要 通过请求 id

智能体在三列里都是同一个。表里的一切都属于驱动。一个按某一个驱动的契约写好、却对着另一个运行的客户端,会把智能体弄对、把协议弄错,而这就是第 32 至 35 章不断警告的那个 bug。本章余下部分是证据,以及那个分离泄漏的唯一一处。

一个智能体,五个驱动

cli-integration.md 在开头几行陈述了这个不变式:“全部四种模式使用同一个智能体、会话、资源和工具。模式决定输入如何进入 Pi、输出如何暴露,以及进程是否保持可用于更多命令。“SDK——cli-integration.md 说它"不是一个 CLI 模式”——是第五个驱动,它把智能体嵌入到你自己的进程里。

    flowchart TD
  TUI["交互式终端"] --> AGENT["智能体:循环、会话、资源、工具"]
  PRINT["Print"] --> AGENT
  JSON["JSON 流"] --> AGENT
  RPC["RPC"] --> AGENT
  SDK["SDK 在你的进程里"] --> AGENT
  

它们之间不同的是观察者,而每一个观察者有它自己的失败契约:

界面 谁驱动 你观察到什么 失败如何显现
交互式 一个人 一份实时绘制的转录记录 在屏幕上
Print 一个脚本 一个字符串 一个非零退出状态
JSON 一个脚本 事件,然后退出 在流里,不在退出码里
RPC 一个进程 响应和事件 success: false,或事件
SDK 你的代码 带类型的对象 一个被拒绝的 promise 或一个事件

那个表的每一行都是关于界面的陈述。没有一行改变智能体对一条提示词做什么。

不带任何界面运行它

最强的证据不在表里。它在第 1 章和第 37 章:智能体内核在没有终端、没有 JSON 帧、没有 RPC、没有会话的情况下运行,而那个循环正是终端展示的那一个。agent.subscribe() 也是一个界面,尽可能小的那一个。界面层是可选的,因为它下面那一层不导入它。

为了把它讲具体,下面是建立在同一个智能体之上的两个界面,写成函数。一个做终端做的事:文本一到达就画出来。另一个做 print 模式做的事:等待,然后返回最终文本和一个状态。

import type { Agent } from "@earendil-works/pi-agent-core";

// Interface 1: streaming. What a terminal does: draw text as it arrives.
export async function drive_streaming(agent: Agent, prompt: string, draw: (chunk: string) => void): Promise<void> {
	const off = agent.subscribe((e) => {
		if (e.type === "message_update" && e.assistantMessageEvent.type === "text_delta") {
			draw(e.assistantMessageEvent.delta);
		}
	});
	try {
		await agent.prompt(prompt);
	} finally {
		off();
	}
}

// Interface 2: one-shot. What print mode does: no events, the final text and a status.
export async function drive_oneshot(agent: Agent, prompt: string): Promise<{ text: string; ok: boolean }> {
	await agent.prompt(prompt);
	const last = [...agent.state.messages].reverse().find((m) => m.role === "assistant") as any;
	const text = last.content.filter((b: any) => b.type === "text").map((b: any) => b.text).join("");
	return { text, ok: last.stopReason !== "error" && last.stopReason !== "aborted" };
}

那个测试构建两个完全相同的智能体,脚本设定为先查找某样东西、然后回答,并用每一个函数各驱动一个:

// The agent did the same thing under both drivers...
assert.deepEqual(shape(a.agent), shape(b.agent));
assert.equal(a.faux.state.callCount, b.faux.state.callCount);
// ...and the only difference is what each driver observed.
assert.equal(drawn.join(""), once.text);
assert.ok(drawn.length > 1, "the streaming driver saw the answer in pieces");

那些转录记录有相同的形状,而 provider 收到了相同数量的请求。界面唯一改变的东西是观察者看到的东西:一种情况下答案分成几块,另一种情况下是完整的。

那个演示位于智能体内核。同一个论断也在随附的二进制文件上被测试,那是更强的证据,因为它跨越了进程边界。examples/ch31-interface/binary.test.ts 通过 print、JSON 和 RPC 运行一次脚本化交换、一次工具调用,然后一个回答:

  • 三者都以相同的最终答案结束;
  • 智能体在每一种下都做了同样的事:JSON 模式和 RPC 产生了相同的生命周期事件——tool_execution_start 和 tool_execution_end、turn_end、agent_end 和 agent_settled——顺序相同,而工具在两者里都运行了;
  • 不同的是观察者:print 给出一个字符串、别的什么也没有,JSON 给出事件而没有命令响应,而 RPC 两者都给;
  • 失败上不同的是契约,别的什么也没有:一次失败的响应让 print 以非零退出,让 JSON 带着流里的失败以 0 退出,而在 RPC 里失败在流里,而 prompt 命令本身已经成功了。

*已观察:*两个测试都在 1.0.4 上、在一个脚本化模型之下运行。它们表明智能体在每个界面背后是同一个。它们并不表明每一个设置和标志在每一种模式下的行为都完全一样,而第 32 章的退出状态不对称是一个有文档记载的差异,这正是要点:界面在观察上有差异,别的什么也没有。

关于"随附的二进制文件"这个说法买到了什么,有两点限制,因为这个短语在上面那段里承担着实实在在的工作。测试骨架通过包自己的 bin 映射解析可执行文件,所以它运行的是 npm exec pi 会运行的那个打包构建——examples/ch31-interface/ 里的一个测试断言那个映射仍然指向 dist/bundle 之下,而这正是阻止证据悄悄降级成 dist/ 里某个其他模块的东西。而脚本化模型是由一个加载进子进程的扩展注入的,所以这是一个带真实配置目录和真实参数解析的真实子进程,但不是一次对着某个 provider 的运行。

被测试的论断据此是有界的:*同一个智能体在每个界面背后产生相同的答案和相同的生命周期事件。*它不是"任何界面都能替换任何其他界面”。第 20 章的自定义终端 UI 可以刻意改变一个结果——一块整个用途就是收集一个决定的屏幕——因此一个能确认的界面就不仅仅是一个不同的观察者。这里没有任何东西是对着真实模型运行的,所以这没有对模型的行为说任何东西。

换界面后什么能存留

对任何一项能力问:如果我切换界面,它还能用吗?

能存留 不能存留
工具调用及其结果 自定义终端组件(ctx.ui.custom())
会话文件与树 主题和按键绑定
事件及其顺序 覆盖层、挂件、页头页脚替换
压缩、重试、恢复 任何用 pi-tui 画出来的东西
技能、提示词模板、上下文文件 编辑器及其快捷键
对话框,通过 RPC 和在终端里 对话框,在 print 和 JSON 模式下(没有人可问)

左列是智能体。右列是呈现。第 20 章的模式矩阵是这张表从扩展作者那一侧看的样子:ctx.hasUI 在有人能回答一个对话框的地方为真,而 ctx.mode === "tui" 只在连接着终端的地方为真。

界面泄漏的唯一一处

那张表里藏着一条设计规则,而 extensions.md 直接陈述了它:“让工具和事件行为独立于渲染,好让非交互模式保持可用。”

这个泄漏很容易不小心写出来。一个用 ctx.ui.confirm() 确认、却对"没有 UI"没有答案的守卫,在 print 模式下不是一个守卫。一个其结果只有在一个自定义组件把它画出来之后才有意义的工具,在 JSON 模式下没有结果。第 16 章的强制推送守卫在 ctx.hasUI 为 false 时拒绝,正是因为在没有人可问的时候,安全的行为是不。

这条规则,表述成一个扩展作者可以应用的测试:

如果切换界面改变了一个扩展决定的东西,这个扩展就把呈现混进了策略。

渲染可以因模式而不同。一次调用是否被挡住不能。那是第 1 章在界面与智能体之间的分离,为那一个横跨两者的机制重新陈述一遍。

终端机制的细节去了哪里

终端是一个有真实失败模式的深主题:一个终端不会上报的、被修改过的 Enter、派生调色板的主题、针对 Ghostty、WezTerm 和 Windows Terminal 的逐终端修复,以及你用 pi-tui 画任何东西时要遵守的组件规则。那一切都准确且有文档记载,而其中没有一样是关于智能体的。它现在住在附录 B,如果你在构建一个终端组件、或者在调试一个不到达的按键,它就在那里等着你。

你能主张什么、不能主张什么

*有文档记载:*共享智能体不变式,以及 SDK"不是一个 CLI 模式"(cli-integration.md)、模式矩阵(extensions.md、rpc-extension-ui.md),以及让行为独立于渲染的规则(extensions.md)。

*已观察:*智能体内核上的双驱动测试,以及随附二进制文件上的三界面测试,两者都在 examples/ch31-interface/ 里,在 1.0.4 上、用脚本化响应。

*本书提出:*把"能存留/不能存留"表作为一种框架,以及"切换界面会改变一个决定吗"这个测试。它们从文档推出,但它们是本书的表述。

下一章

接下来四章按每一个界面给你多少控制、以及它为此收取什么代价的顺序来讲这些界面。

第 32 章是那些非终端界面里的第一章:无头 Pi,同一个智能体,没有人在场,调用一次然后退出。