# @earendil-works/pi-server 中文文档

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

版本：1\.1\.0
npm 元数据更新时间：2026-10-07T22:11:16.928Z
中文译文更新时间：2026-11-13T03:36:02.216Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：236 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- 首次发布：2026-08-06T10:51:25.262Z
- 最新版本发布：2026-10-07T22:11:16.569Z
- 近 30 天下载量：246206（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

pi 的实验服务器包

## 安装

```sh
npm install @earendil-works/pi-server
```

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

## README

# @ earendil- works/ pi- 服务器

实验本地服务器,将客户端引导到应用程序托管的持久会话.

当前的切片支持服务器和会话镜面服务路由和多呈现附件. `RoutedServerServiceHost.attachClient()` 创建一个连接-扫描服务器服务端点,具有狭窄的附件管理能力. `RoutedSessionHandle.attachClient()` 返回显示范围会话的能力。 内容 `invokeService()` 向选定的会话端点转发不透明的服务/成员信封; 服务器验证附件路由, 但不会加载面板合同.

-   通过连接不透明地调用和订阅服务器服务路由 `RoutedServerServiceAttachment`· ;
-   应用程序拥有者 `SessionDirectory` 将私人目录纳入可复制的列报安全状态;
-   应用程序拥有者 `SessionManagement` 创建、去除、附加和解析会话,而不在业务结果中披露路由ID;
-   在路由器安装或清除了活路由后,附件更改会发布出带外;
-   会话服务呼叫路由 `invokeService` 没有服务器侧业务负载解码;
-   服务订阅的更新仍限于请求的附件;
-   应用程序观测,如记录仪路由作为普通服务状态,而不包含服务器拥有的商业计划.

一个会话可能有多个演示文稿附件. 重复 `attach` 从一个连接中生成一等元; 每个成功的附件都有服务器生成 `attachmentId` 仅作为路由控制数据提供。 会话请求包含 `{ serverId, sessionId, attachmentId }`,而服务器拒绝过时或不匹配的路径。 失去连接会拒绝当地的反应,但只有在接受服务电话结算后才会解除连接。 主办方决定零展示需求和工人-地方的和谐活动何时允许工人退休。 服务器关闭关闭每个路由会话控件, 释放它的工人和会话作者所有权 .

```ts
import { randomUUID } from "node:crypto";
import {
  type RoutedServerServiceHost,
  type RoutedSessionHandle,
  type ServerHost,
  type SessionMetadata,
  SessionNotFoundError,
} from "@earendil-works/pi-server";
import { createUnixServer, getUnixSocketPath } from "@earendil-works/pi-server/unix";

interface StoredSession extends SessionMetadata {
  path: string;
}

async function startServer(
  serverServices: RoutedServerServiceHost,
  sessions: Map<string, StoredSession>,
  openRoutedSession: (session: StoredSession) => Promise<RoutedSessionHandle>,
) {
  const host: ServerHost<StoredSession> = {
    serverServices,
    async resolveSession(sessionId) {
      const metadata = sessions.get(sessionId);
      if (!metadata) throw new SessionNotFoundError(`Unknown session: ${sessionId}`);
      return metadata;
    },
    openSession: (metadata) => openRoutedSession(metadata),
  };

  const serverId = randomUUID();
  const server = createUnixServer(host, {
    serverId,
    path: getUnixSocketPath(serverId, "/run/user/1000/pi"),
  });
  await server.start();
  return server;
}
```

应用程序提供需要的服务器服务主机,有限定的会话解析器,以及路由会话厂. `SessionMetadata` 只需要一个 `id`;应用程序可能用自己的存储字段来扩展. 会话发现和管理是应用程序拥有的服务;协议服务器仅在路径一个附件时向解析器询问元数据. 主办方拥有工人-地方会议与机会。 失败者被清理 在工人。 开放的JavaScript会话和Harness都没有跨越进程边界.

`serverId` 是发射装置提供的逻辑身份,而不是套接字地址。 Unix 预设需要明确物理 `path`· ; `getUnixSocketPath()` 取自一个调用者选中的目录。 选择一个短而私有的运行时间目录,而不是从一个无限制的主目录路径来得出路径. 长寿命的发射装置在替换服务器进程时可以再用相同的ID和路径.

`Server` 作曲通过 `ServerListener`;对等认证仍然是应用政策,没有被实验性的Unix迁移所执行. Unix 子模块提供 `createUnixListener()` 财务报告和审定财务报表 `createUnixServer()`。低级路由-信封验证、CBOR和框架来自 `@earendil-works/pi-protocol`; Cord 拥有服务控制解析,出错代码,快照和更新,每个订阅的复制状态编码器.

服务器和工人的生命周期在公共Pi协议之外进行管理. 可替换的应用程序服务器将连接附件转换为私人需求更新;工人将生成标记的需求与权威的Harness活动相结合. 实验协调员只提供稳定的路由,并报告通用服务器生成连接的变化.

## 常见问题

### @earendil-works/pi-server 是什么？

pi 的实验服务器包

### 如何安装 @earendil-works/pi-server？

在项目目录运行 npm install @earendil-works/pi-server，或使用 pnpm add / yarn add / bun add。

### @earendil-works/pi-server 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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