# @assistant-ui/react-pi 中文文档

规范地址：https://npmcn.com/package/%40assistant-ui/react-pi/

版本：0\.0\.32
npm 元数据更新时间：2026-10-19T21:47:24.845Z
中文译文更新时间：2026-11-07T00:30:41.372Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40assistant-ui/react-pi
原文对照：https://npmcn.com/package/%40assistant-ui/react-pi/?lang=original
项目主页：https://www.assistant-ui.com/
源码仓库：https://github.com/assistant-ui/assistant-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，149 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18 \|\| ^19，@types/react \*，@assistant-ui/react ^0\.15\.22，@earendil-works/pi-coding-agent \>=0\.80\.8
- 首次发布：2026-06-13T22:09:28.972Z
- 最新版本发布：2026-10-19T21:47:24.417Z
- 近 30 天下载量：10386（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

助手- i 的 Pi 编码代理运行时间适配器

## 安装

```sh
npm install @assistant-ui/react-pi
```

也可以使用：`pnpm add @assistant-ui/react-pi`、`yarn add @assistant-ui/react-pi`、`bun add @assistant-ui/react-pi`

## README

# @ assistant- ui/ react- pi

Pi 编码代理运行时间适配器 [助理人员](https://www.assistant-ui.com/)。 。 。 .

此软件包允许助理- ui 渲染和驱动 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)\- 后卫 线程: 流线助手/ 推理输出, 有活线流的工具调用 成果、中跑指导和后续、每行走模式/思维控制, 屏蔽扩展 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`。 。 。 .

## 安装

```bash
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`因此,它能活下来 模块级服务器文件,从不每个请求.

```ts
// 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/**`](https://npmcn.com/package/examples/with-pi/app/api/pi) (单位:千美元) 完成 Next.js App Router 执行.

### 3\. 浏览器:运行时间

```tsx
"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` 以 [云帮](https://www.assistant-ui.com/docs/cloud) 而不是 Pi 服务器的线程列表 . `cloud` 是唯一的开关: 与运行时间不同的是,列表生活在浏览器中, `NEXT_PUBLIC_ASSISTANT_BASE_URL` 单是保留了 Pi 服务器的列表,所以设置它从不移动已存在的应用程序的线程.

```tsx
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` 并具有默认模式 选择需求 **没有潜入**。 。 。 .

| 变量 | 目的 |
| --- | --- |
| `PI_PROVIDER` | 覆盖新会话的提供者(例如:. `anthropic`) (中文(简体) ). |
| `PI_MODEL_ID` | 覆盖新会话的模型 ID . |
| `PI_WORKSPACE_PATH` | 代理读取/ 写入/ 运行 shell 命令的工作目录 。 把它指到划痕上. |
| `PI_CODING_AGENT_DIR` | Pi 的代理配置 dir (`~/.pi/agent` (默认情况下). |

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

## 模型思维控制( I)

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

```tsx
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`),因此标准作曲家在一时继续接受输入 运行并获得正确的行为:

| 国家/行动 | 行为 |
| --- | --- |
| 闲置+提交 | `prompt()` |
| 运行 + 输入 | 后续行动`streamingBehavior: "followUp"`)——已排队 |
| 运行 + Cmd/Ctrl+Shift+ 输入 | 引导( t)`streamingBehavior: "steer"`(中文(简体) ) |

强迫方向从自己的作曲家,发送 `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` 缺少选择或该客户端不知道的类型) — 一个侧道:

```tsx
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在服务器上。 技能/扩展/斜线命令不是 已经浮出水面.

## 常见问题

### @assistant-ui/react-pi 是什么？

助手- i 的 Pi 编码代理运行时间适配器

### 如何安装 @assistant-ui/react-pi？

在项目目录运行 npm install @assistant-ui/react-pi，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 \|\| ^19）、@assistant-ui/react（^0\.15\.22）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @assistant-ui/react-pi 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @assistant-ui/react-pi 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @assistant-ui/react-pi 可以商用吗？

@assistant-ui/react-pi 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @assistant-ui/react-pi 的下载量有多少？

根据 npm 官方下载统计，@assistant-ui/react-pi 在 2026/10/07 – 2026/11/05 这 30 天内被下载 10,386 次，日均约 346 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @assistant-ui/react-pi 还在维护吗？

最新版本 0\.0\.32 发布于 2026/10/20（18 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/06/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。