# @averyyy/pi-server 中文文档

规范地址：https://npmcn.com/package/%40averyyy/pi-server/

版本：1\.5\.0-piclient\.4
npm 元数据更新时间：2026-11-05T01:10:39.447Z
中文译文更新时间：2026-11-07T08:01:10.152Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40averyyy/pi-server
原文对照：https://npmcn.com/package/%40averyyy/pi-server/?lang=original
项目主页：https://github.com/Averyyy/pi-client#readme
源码仓库：https://github.com/Averyyy/pi-client

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

- 包体积（解压后）：1 MB，82 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- 首次发布：2026-07-02T00:37:27.563Z
- 最新版本发布：2026-11-05T01:10:38.870Z
- 近 30 天下载量：6341（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：95（近 12 个月 95 个）

## 中文简介

存储会话状态并向上游 LLM 提供者转发递增请求的 pi- 客户端的代理服务器

## 安装

```sh
npm install @averyyy/pi-server
```

也可以使用：`pnpm add @averyyy/pi-server`、`yarn add @averyyy/pi-server`、`bun add @averyyy/pi-server`

## README

# @ averyyy/ pi 服务器

服务器 `@averyyy/pi-client`。它存储会话状态,并向上游模式提供者转发客户请求.

## 安装

```bash
npm i -g --ignore-scripts --legacy-peer-deps @averyyy/pi-server
```

## 开始

```bash
pi-server
```

默认它会听 `http://127.0.0.1:4217` 和存储会话 `.pi/pi-server/sessions` 在当前目录中.

## 配置

在服务器环境中设置提供者密钥, 然后启动服务器 :

```bash
OPENAI_API_KEY=your-key pi-server
```

有用的服务器设置 :

```bash
PI_SERVER_HOST=127.0.0.1
PI_SERVER_PORT=4217
PI_SERVER_AUTH_TOKEN=your-token
PI_SERVER_SESSION_STORE_DIR=/path/to/sessions
PI_SERVER_UPLOAD_DIR=/path/to/upload_files
PI_SERVER_ACCOUNT_STORE_DIR=/path/to/accounts
```

收到文件默认为 `~/.pi/upload_files`。 。 。 .

## 账户提供者

PiServer拥有Devin和Google Antigravity账户登录,认证持久性,符号刷新和模型发现. 连接 `pi-client`运行 `/login devin` 或者说 `/login google-antigravity`,然后完成浏览器的授权并快速重定向。 客户端接收账户状态和模型元数据;证书保留在服务器上.

账户文件默认为 `~/.pi/pi-server/accounts`设置 `PI_SERVER_ACCOUNT_STORE_DIR` 来选择另一个目录。 服务器在启动时恢复已保存的账户目录,并在背景中刷新,成功登录后,每4小时更新一次. 过期 OAuth 令牌在需要时刷新 。 失败发现保存了保存的目录并报告错误 . `/logout` 取消所选账户的待定工作并删除其证书和目录.

认证 `/api/accounts` 端点曝光这两个账户快照. 它们的推论和收缩请求 `options.authSource: "server-account"`,它选择了精确的保存账户模型和服务器证书。 其他供应商的配置和登录仍然为客户所有.

## 公共模型目录

认证 `/api/model-catalog/providers/:provider?pi-version=<version>` 端点服务于来自pi.dev的共享公共目录. 客户端只请求拥有已配置认证的提供者 。 服务器按要求获取一个提供者,并使用同Pi版本在客户端之间共享其缓存响应. Catalog请求包括聊天,图像,以及没有提供者证书的分类元数据;客户从自己的证书和配置中确定模型可用性.

目录存储在 `.model-catalog` 在会话存储目录中保存并保存4小时的新鲜度。 过期的条目使用ETag重新验证;同时提出的请求共享一个上游获取. `force=true` 请求立即重新确认。 服务器启动不会获取公共目录 。 失败刷新报告出错并保留保存的目录供下次尝试使用 。 OpenRouter的证书专用过滤器仍然保留在客户端上.

## 人类订阅

Anthropic OAuth 请求使用 Claude 代码订阅请求在服务器上塑造,其基础是 [人类-原子](https://github.com/gotgenes/pi-anthropic-auth)。继续使用客户端的现有 `/login anthropic`;客户端存储并刷新其证书,并为每个请求提供访问符. 服务器将同样的形状应用于原始而简单的聊天流,收缩,和缓存变暖.

服务器使用本地请求 Claude 代码版本添加了计费系统块,并在客户端有效载荷回调后塑造了Pi 默认的提示部分. 项目指令,自定义提示,工具定义,以及签名的助手内容被保存. 这适用于: `anthropic` 提供者的 OAuth 请求; API 密钥和其他提供者保留它们现有的行为. 第一个用户信息必须包含文本 。 Pi客户端的额外使用警告反映了OAuth登录状态,而不是服务器的请求塑造;在克洛德的使用页面中验证实际消耗.

## 连接客户端

```bash
PI_SERVER_URL=http://127.0.0.1:4217 pi-client
```

带有认证 :

```bash
PI_SERVER_AUTH_TOKEN=your-token PI_SERVER_URL=http://127.0.0.1:4217 pi-client
```

对客户端和服务器使用相同的发布版本. 认证 `/api/models` 端点报告服务器配置的模型 。 客户模式选择使用公共目录缓存和客户端认证. `/api/stream`, (中文(简体) ), `/api/generate-images`,以及 `/api/classify` 解决服务器侧提供方证书或使用客户端明确提供的证书.

图像生成和分类流心跳响应和期刊在不重复提供者操作的情况下完成了回收结果. 供应商清理完成后确认取消 。 使用过大的有效载荷 `/api/request/chunk`,包括客户端设定64个KiB请求-体限时.

## 请求时间

设定 `PI_TIMING=1` 由客户端打印请求延迟诊断。 客户端请求选入 `event: timing` SSE 框架来自 `/api/stream`;普通请求不包括这个框架.

客户端 `clientPrepareMs` 起始于 `clientPrepareFrom`: 接受运行,代理工具补全事件,或用户消息启动. 工具边界包括后续扩展处理器和请求准备,同时排除工具执行本身. `sessionInitMs` 计量会话初始化和客户端 `firstContentMs` 测量从启动流 POST 到接收内容的间隔.

服务器字段是收到 HTTP 请求后累积的毫秒 : `bodyReadyMs` 标记解析请求数据, `providerDispatchMs` 标记提供者呼叫, `upstreamRequestMs` 标记准备的上游有效载荷, `upstreamHeadersMs` 标记第一个上游HTTP反应 `firstContentMs` 标记第一个非空文本、思维或工具调用输出。 最终唯一内容也算数. 没有生命周期回调的适配器省略了它的场. 对于被块状上传,服务器时间从完成的HTTP块开始. 客户的 `requestToHeadersMs` 包括序列化,所有上传块,服务器处理,以及响应头.

`providerDispatchMs` 改为 `upstreamRequestMs` 包括供应商认证、装载和服务器上的有效载荷准备. `upstreamRequestMs` 改为 `firstContentMs` 包括HTTP设置,网络中转,上游排队,再试,和模型处理. `upstreamHeadersMs` 将首个上游HTTP响应与剩余等内容相分离. 这些间隔并不单独测量模型预填. HTTP 头,心跳字节,和空流事件不计为模型内容.

## 线索查看器

打开服务器的根 URL并签名到 `PI_SERVER_AUTH_TOKEN`。主页按客户端工作目录组合线索,并首先列出运行的线索。 线程由其最新的活性来命令;项目使用其最新的活性线程. 服务器在开始和完成推断时记录活动,收缩,图像,分类器,以及被推迟的操作. 读取历史,重联,同步现有历史,更名,再播放完成的结果,不会推进这段时间. 已存档的会话使用他们保存的对话时间戳,直到服务器记录到新的操作. 缓存变暖使用相同的提供者请求协议并算作活性. 没有活动的会话最后出现.

项目文件夹一次扩展5个线程. 线索页显示最新的5个对话回合;滚动到顶部负载时会提前5个回合,同时保持当前段落的位置. 已完成的回合揭示出最后的答案;思维和工具活动可以单独扩展,包括在流出时扩展.

右键单击一个工程来崩溃或扩展,或者删除其服务器的全部对话. 右键单击线索删除服务器对话 。 相同的菜单通过上下文菜单键或Shift+F10提供. 删除需要确认,并包括已保存的历史和观察员记录。 项目删除包括当前已加载的页面以外的对白.

服务器索引每个进程一次并更新仅会随着变化而影响会话. Pgination 不扫描每个会话就读取工程的索引 。 浏览器加载可见的扩展文件夹并保留其页面为内存,而页面仍然开放;没有修改的文件夹会再使用这些页面. 当文件夹可见时会获取屏幕外的更改 。 JavaScript 和 CSS 使用构建版本的 URL 和 不可移动的浏览器缓存, 包括跨服务器重启; HTML 、 认证和对话响应仍然保留 `no-store`。 。 。 .

查看器会读取,写出,并且通知会同步运行,以排列每个线程. 活动更新不会等查看器存储或通知后再发送推论. 观察者更新在存储承诺后公布内容索引;删除等待之前的操作,服务器关闭排出待操作. 资产加载和认证状态I/O也是同步状态.

打开一条线程通过一个事件流请求读取其初始历史并直播更新. 直接线程 URL 启动该流与项目目录 。 未更改会话初始化和"一能"历史写作不会重发取景者的历史快照.

浏览器收到一个单独的12小时 `HttpOnly`, (中文(简体) ), `SameSite=Strict` 会话 cookie 范围到 `/viewer`。该 cookie 授权只读取并删除同源会话。 提供方请求和普通会话 APIs保留了无记名认证. 在公共访问的倒置代理上配置HTTPS;代理必须保留请求主机和HTTPS协议. 查看器需要配置的服务器令牌 .

10个失败的代币检查锁认证访问,包括正确的代币. 计数在重启的整个过程中持续,由查看器登录共享,并要求提供不正确的API授权头. 没有 API 证书的请求并不需要尝试 。 一个成功的查看器登录重置了计数;普通客户端流量没有. 解锁服务器, 使用与运行进程相同的配置和会话目录 :

```bash
PI_SERVER_SESSION_STORE_DIR=/path/to/sessions pi-server viewer unlock
```

在不重新启动服务器的情况下解锁生效 。 没有 HTTP 解锁端点 .

匹配 `pi-client` 发布事件触发更新,包含当前分支的承诺消息,项目目录,标题,以及明确的运行/工具状态. 客户端发布执行开始,内容更改,执行完成时更新,没有观察者连接,心跳,或定时重接. 运行报告和闲置报告共享TUI工作指标的会话周期,包括工具,收缩,同步完成处理器和取消确认. 已完成的闲置报告在服务器重启时持续存在;未完成的运行报告恢复为未知. 浏览器通过自己的事件流接收服务器更新. 观察者不修改服务器的推断树或提供者上下文. 它的历史和认证状态生活在 `.viewer` 在会话目录中.

现有的服务器会话是从已恢复的快照和WAL记录中读取. 项目使用在有效系统消息中声明的远程工作目录或Pi的标准系统即时目录字段;只有没有该元数据的会议才会显示为未指定的档案. 保存的分支历史在没有连接客户端的情况下是可用的,成功的会话会写更新开放的取景器页面.

取景器显示由服务器保存或由连接客户端发布的历史. 只包含初始化元数据的会话没有保存的对话正文 。 系统指令用于项目元数据,不包括在对话显示中. 图像以附件标签表示. 转写 Markdown 不执行 HTML 或装入外部图像 .

前端保留在 `viewer/` 作为固定资产的船舶 `dist/viewer/`与 `npm run build:viewer`· ; `npm run build` 包括这个步骤。 此查看器独立于由 `pi-client web`。 。 。 .

## 常见问题

### @averyyy/pi-server 是什么？

存储会话状态并向上游 LLM 提供者转发递增请求的 pi- 客户端的代理服务器

### 如何安装 @averyyy/pi-server？

在项目目录运行 npm install @averyyy/pi-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pi-server，可以用 npx pi-server 直接运行。

### @averyyy/pi-server 支持 TypeScript 吗？

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

### @averyyy/pi-server 支持 ESM 还是 CommonJS？

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

### @averyyy/pi-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @averyyy/pi-server 可以商用吗？

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

### @averyyy/pi-server 的下载量有多少？

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

### @averyyy/pi-server 还在维护吗？

最新版本 1\.5\.0-piclient\.4 发布于 2026/11/05（2 天前）；至今共发布 95 个版本，其中过去 12 个月发布了 95 个；首次发布于 2026/07/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。