@ assistant- ui/ react- pi

Pi 编码代理运行时间适配器 助理人员。 。 。 .

此软件包允许助理- ui 渲染和驱动 Pi- 后卫 线程: 流线助手/ 推理输出, 有活线流的工具调用 成果、中跑指导和后续、每行走模式/思维控制, 屏蔽扩展 UI(Pi的整个人行/批准表面),以及 多线程列表.

软件包边界

软件包有两个切入点:

• @assistant-ui/react-pi —— 说 浏览器安全。运行时钩,纯事件 减少、 消息投影和 HTTP PiClient。本条目 永远 进口 @earendil-works/pi-*它会说RPC-同位素 JSON-safe 合同(PiClient以任意运输为目的.
• @assistant-ui/react-pi/node —— 说 仅节点。 。 。 . createPiNodeClient,哪个 驱动 Pi AgentSession SDK 在进程- singleton 后面的进程中 PiThreadSupervisor。只有此条目吸引 Pi 的节点包.

HTTP是执行 PiClient,而不是合同——运行时间钩 从来没有烤在运输。 您可以在 HTTP/ SSE (以下) 上服务节点客户端, 直接交给 usePiRuntime 位于同一地点的电子/主要进程设置中,或 写入满足的其他运输工具 PiClient。 。 。 .

安装

npm install @assistant-ui/react-pi @assistant-ui/react
# the node entry drives the Pi SDK on the server:
npm install @earendil-works/pi-coding-agent

@earendil-works/pi-coding-agent 是一个可选的对等关系依赖 – 仅浏览器 消费者(进口遥控器的人) PiClient从不把它拉进来。 这个 ./node 输入需要它.

快速启动( HTTP/ SSE 运输)

二分之一的两分之一 PiClient 合同:

browser                         server (Node)
─────────                       ─────────────
usePiRuntime                    route layer (GET/POST /api/pi/**)
  └ createPiHttpClient  ──HTTP──▶ createPiNodeClient(...)
       (fetch + SSE)               └ PiThreadSupervisor → Pi SDK

1. 服务器:节点客户端

createPiNodeClient 返回 a PiClient它拥有一个 进程同步 主管 globalThis因此,它能活下来 模块级服务器文件,从不每个请求.

// lib/pi-server.ts  (server-only — imported only from route handlers)
import { createPiNodeClient } from "@assistant-ui/react-pi/node";

export const piClient = createPiNodeClient({
  workspacePath: process.env.PI_WORKSPACE_PATH ?? process.cwd(),
  // agentDir?: override Pi's config dir (default ~/.pi/agent)
  // model?:    a resolved Pi `Model` to seed new sessions (see Model controls)
});

2. 服务器:路由层

揭露 PiClient hTTP 方法,以及 subscribe 超过SSE。 电线 合同 createPiHttpClient 期望(与 baseUrl默认值 /api/pi:

GET    /threads                 → PiThreadMetadata[]
POST   /threads                 → PiThreadSnapshot      (body: create input)
GET    /threads/:id             → PiThreadSnapshot      (read-only snapshot)
PATCH  /threads/:id             → 204                   (body: { title })
POST   /threads/:id/messages    → 204                   (body: { input })
POST   /threads/:id/cancel      → 204
GET    /models                  → PiModelInfo[]
POST   /threads/:id/model       → 204                   (body: { provider, modelId })
POST   /threads/:id/thinking    → 204                   (body: { level })
POST   /threads/:id/archive     → 204
POST   /threads/:id/unarchive   → 204
DELETE /threads/:id             → 204                   (also when the thread is already gone)
POST   /threads/:id/host-ui     → 204                   (body: { response })
GET    /threads/:id/events      → SSE of PiClientEvent  (?snapshot=false skips initial snapshot)

事件路径必须流出 piClient.subscribe(threadId, …) 并取消订阅 请求中止。 浏览器必须断开 没有 中止运行——参见再连接 . 见 examples/with-pi/app/api/pi/** (单位:千美元) 完成 Next.js App Router 执行.

3. 浏览器:运行时间

"use client";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { createPiHttpClient, usePiRuntime } from "@assistant-ui/react-pi";
import { useMemo } from "react";

export function PiRuntimeProvider({ children }: { children: React.ReactNode }) {
  const client = useMemo(() => createPiHttpClient(), []); // baseUrl defaults to /api/pi
  const runtime = usePiRuntime({ client /*, workspacePath, includeArchived */ });
  return <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>;
}

usePiRuntime 需求 options.client ——没有隐含的运输. 丢弃 任何助理- ui 线程 UI 上方的提供者( )Thread, (中文(简体) ), ThreadList(中文(简体) ).

云帮

过 cloud 以 云帮 而不是 Pi 服务器的线程列表 . cloud 是唯一的开关: 与运行时间不同的是,列表生活在浏览器中, NEXT_PUBLIC_ASSISTANT_BASE_URL 单是保留了 Pi 服务器的列表,所以设置它从不移动已存在的应用程序的线程.

const runtime = usePiRuntime({ client, cloud });

每个云纹图通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通 workspacePath,并删除线程先删除它的 Pi 线程,其中已经消失的 Pi 线程不会被屏蔽. 列表保留了云项目的所有线条,存档在自己的部分,所以 workspacePath 只放置新线程 includeArchived 未使用。 无 Pi 运行时创建的云线没有 Pi 线程: 它打开了空, 并发送到其中拒绝. 与 cloud, (中文(简体) ), threadId 财务报告和审定财务报表 initialThreadId 取出云纹标识,所以一个命名为 Pi 线纹标识的链接不再打开. 重命名和归档只更改了云线; Pi 线程保留了自己的标题和归档状态, 如果列表再次显示此状态 cloud 删除.

环境/模型分辨率

A Pi会话需要模型和证书. 分辨率镜像 Pi 自己的 createAgentSession: 明示 PI_PROVIDER + 键 PI_MODEL_ID 赢了,不然就派 返回到它所配置的默认值( n)settings.json是因为 defaultProvider 编号 : defaultModel) (中文(简体) ). 经认证的用户 pi 并具有默认模式 选择需求 没有潜入。 。 。 .

这个 ./node 条目需要解析的 Pi Model 通过 createPiNodeClient({ model }) 以种子新会话。 使用 Pi 的自带 ModelRegistry 编号 : SettingsManager 编号 : AuthStorage 在服务器上解决它。 见 examples/with-pi/lib/pi-server.ts。 。 。 .

模型思维控制( I)

每条线,浮出水面 usePiRuntimeExtras()数字 :

import { usePiRuntimeExtras } from "@assistant-ui/react-pi";

const { readiness, contextUsage, setModel, setThinkingLevel } = usePiRuntimeExtras();
// readiness: "ready" | "missing-model" | "missing-credentials" | "unavailable-model"
// await setModel({ provider, modelId });
// await setThinkingLevel("off" | "minimal" | "low" | "medium" | "high" | "xhigh");

getAvailableModels() 在客户端返回目录( 自动配置的模型) 首先,倒回完整的内置列表). setThinkingLevel 被夹住 Pi 到模型支持的级别; UI 反映了从 下一个快照/活动. contextUsage (单位:千美元){ tokens, contextWindow, percent }(中文(简体) ) 回答"我即将自动完成吗?",甚至可以使用冷线.

readiness 门发送——屏蔽作曲家并显示 readiness.message (下一个具体步骤,例如: pi,然后重新启动服务器。” 当它不是 "ready"。 。 。 .

作曲家运行语义

Pi的定型互动是中跑方向 和平地 prompt() 时 流线 掷出。运行时间将 Pi 的本地队列曝光给助手 (单位:千美元)capabilities.queue),因此标准作曲家在一时继续接受输入 运行并获得正确的行为:

强迫方向从自己的作曲家,发送 steer: true 或设置 message.runConfig.custom.streamingBehavior = "steer"。运行时,一个 省略行为默认 "followUp"。 。 。 .

排队消息在皮的队列中直播, 没有 - 记录 - Pi 附加 仅当队列冲出时用户消息 。 运行时间以队列形式映射 项目(项目)s.composer.queue,可用 ComposerPrimitive.Queue和继续 线程元数据 queuedMessages。皮支持清除整队 (单位:千美元)clearQueue() 客户端/ usePiRuntimeExtras().clearQueue(),哪个 以已清除的文本解决,以便将其恢复为作曲者),但 (见已知限制).

主机-UI请求(核准表面)

Pi没有内置许可系统—— 仅限 人类的潜入机制 扩展/工具呼叫 ctx.ui.confirm / select / input / editor此软件包 执行并约束 ExtensionUIContext 在服务器和路径 4 屏蔽对话框到 UI, 按因果关系拆分 :

• 工具关联 作为工具调用 ToolCallMessagePart.approval 通过运行时间回答 onRespondToToolApproval。 。 。 . confirm 要求一个决定, select 每个选择提供一种选择(选择编号是选择索引),以及 input 编号 : editor 请求文本答案,所以默认工具倒置会使匹配控件产生. 自定义工具 UI 的答案 respondToApproval({ approved }), (中文(简体) ), respondToApproval({ optionId, approved: true }) 或者说 respondToApproval({ text }),以及 approved: false 开除a select, (中文(简体) ), input 或者说 editor 请求;预计这些请求 dismissible,因此默认工具倒置会为他们提供解职控制. 后退不显示 input 占位符或一个 editor 预填; 自定义工具 UI 从 usePiRuntimeExtras().allHostUiRequests。 。 。 .
• 独立 (扩展命令、在多个工具正在飞行时提出的任何请求,以及任何请求都无法回答,例如 select 缺少选择或该客户端不知道的类型) — 一个侧道:

import { usePiHostUiRequests } from "@assistant-ui/react-pi";

const { requests, respond } = usePiHostUiRequests();
// confirm:                 respond({ requestId, confirmed: boolean })
// select/input/editor:     respond({ requestId, value: string })
//                      or  respond({ requestId, dismissed: true })

Pi的UI请求没有 toolCallId,因此,只有在 单一工具正在执行;否则请求会留在侧道上。 待决 请求在服务器记录中被跟踪(不是SSE连接),所以 重新连接的客户端仍然看到它们. 不支持 ExtensionUIContext 方法 降解而不是崩溃.

主办方提供Pi的 Theme 带有终端默认颜色, 因此扩展 格式化帮助, 如 ctx.ui.theme.fg() 财务报告和审定财务报表 bold() 无工作 初始化或取代 Pi 的全过程主题. 对话框标题, 信件、选项和占位符以终端逃逸方式到达浏览器 代码被删除 。 在节点主机中仍然无法选择主题 .

重新连接语义

• 主管在浏览器断开时保持运行时间——只有 明确 cancelRun 或处理退出停止运行. 一个被放弃的SSE从不中止.
• HTTP 重联接收权威 snapshot 活动,然后是现场活动. includeSnapshot: false 只跳过初始快照。 重新连接快照 恢复丢失的消息和线索状态而不重放事件 .
• 浏览器订阅者共享长寿的SSE连接. 用户加入 延迟先收到当前快照;当缓存快照被后面时, 所有等待的订阅者共享一个短暂的快照请求.
• 冷/历史线通过a负载 只读会话文件快照 - 开幕 要读的线程有 没有 开场吧 AgentSession。实时运行时间是 仅在您发送、取消、更改模式/思考、回答主机 UI 时创建,或 明确订阅现场活动.

选择钩

运行时间保持高频记录和低频状态 元数据,所以元数据控制不会对每个符号重新回复:

• usePiRuntimeExtras() —— 说 status, (中文(简体) ), readiness, (中文(简体) ), contextUsage, (中文(简体) ), queue, (中文(简体) ), compaction, (中文(简体) ), retry, (中文(简体) ), lastError,主机用户界面请求,以及 cancel 编号 : refresh 编号 : clearQueue 编号 : setModel 编号 : setThinkingLevel 编号 : respondTo* 编号 : resumeToolCall 行动.
• usePiSession() ——当前 PiThreadMetadata (或 null) (中文(简体) ).
• usePiThreadState(selector?) ——生还还还原状态,可选择选择.
• usePiHostUiRequests() ——独立主机-UI请求+回应.

已知的限制(MVP)

• 没有 RPC-子进程传输 . SDK在进程节点客户端假设一个 长寿命节点进程; 它无法从无服务器/对接中幸存 。 合同是 RPC-同位素,因此子进程/远相传输可以在后期下降.
• 没有持久事件重放 / 后压 / 版本谈判 . 恢复为 仅限第一.
• 线程不自动跟随视图 . 打开线程是便宜的 仅读快取; 运行时自动订阅到活动 装入的快照报告线索为运行( 或发送时) 。 运行 从其它地方开始 之后 您打开了下一个空闲视图 新鲜,不是活的controller.connect() 已存在,用于明确永远存在 订阅。 )
• 节点主机的目录是进程本地和内元. 它会缓存 SessionManager.list() 并跟踪运行过程的归档状态; 无 在整个重新启动中持续(没有最后选定的工作空间、草稿、标签或 搜索索引)。 工作空间只是一个 workspacePath 客户端上的字符串 — UI 用于选择一个(文本字段,目录拾取器,.)是耗用应用程序的 担心,不是这个包.
• 没有叉/克罗内/navigate或每个项目队列编辑. 减少/预测 保存基本数据——树相连接parentSessionPath),已排队 电文 (queuedMessages因此消费者可以建造这些设备 表面,但客户端没有显示叉出会话的方法,导航 树,或重排队列。 队列项目镜像 Pi 的服务器侧队列 : 排队工作(即中跑后续/派遣人员)和清除 所有作品( 仅次于clearQueue,镜像 Pi 唯一的队列突变),但每个项目 方向/移动出价是没有的——皮没有这种API.
• 附件只是图像通过. 非图像输入部分不是 转换为 Pi 用户内容.
• 模型/思考是唯一的运行时间配置动作. 没有 供应商/供应商/证书或默认模式/客户端设置方法——管理 那些Pi自己的SDK在服务器上。 技能/扩展/斜线命令不是 已经浮出水面.