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

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

版本：1\.5\.2
npm 元数据更新时间：2026-11-10T12:22:10.261Z
中文译文更新时间：2026-11-13T03:37:01.869Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：18.5 MB，49 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- 首次发布：2026-10-05T19:03:56.922Z
- 最新版本发布：2026-11-10T12:22:09.559Z
- 近 30 天下载量：114583（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Pi 持久状态的远程执行环境: 在 SSH 及其 EmpireEnv 客户端上部署一个小守护进程

## 安装

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

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

## README

# @earendil-works/pi-env (英语)

远程执行环境 [持久性](https://npmcn.com/package/%40earendil-works/durable):一个代理工具运行在另一台机器上,通常运行在SSH之上, 而耐用工人,其储存和证书则留在当地.

-   `pi-env` (单位:千美元)`daemon/`:一个在远程机器上运行的小Rust程序. 它讲的是关于Stdin和 静态( t)[文档/protocol.md](https://npmcn.com/package/%40earendil-works/pi-env/docs/protocol.md)),并在那里执行文件操作和命令.
-   `RemoteExecutionEnv`: 持久 `ExecutionEnv` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}他通过一个 `Connection`。结果匹配 `NodeExecutionEnv` 在远程机器上运行; 只有错误消息可能不同 (单位:千美元)[文件/语义.md](https://npmcn.com/package/%40earendil-works/pi-env/docs/semantics.md)) (中文(简体) ).

```ts
import { acceptHostKey, connectSsh, RemoteExecutionEnv, scanHostKey, sshConnection } from "@earendil-works/pi-env";

const target = { host: "gpu-box", knownHostsFile: "/data/ssh/known_hosts", hostKeyAlias: "pi-env-gpu" };
// Once: show the host's key fingerprint to the owner, who compares it out of band and accepts it.
const { lines, fingerprints } = await scanHostKey(target);
await acceptHostKey(target, lines);

// Detects the remote system, deploys the daemon if missing (named by its SHA-256 and verified before every start),
// and returns a connection that starts it over ssh.
const { connection } = await connectSsh(target);
const env = new RemoteExecutionEnv({ connection, id: "pi-env:gpu", cwd: "/home/me/project" });

// Or lazily: nothing happens until the first operation, which detects, deploys and connects. A failure (no network,
// untrusted host key) is that operation's error, and the next operation tries again.
const lazy = sshConnection(target);
const lazyEnv = new RemoteExecutionEnv({ connection: lazy.connection, id: "pi-env:gpu", cwd: "/home/me/project" });
```

软件包为每个支持的远程系统发送守护进程 `bin/`。 。 。 . `ssh` 运行与 `BatchMode`,严格的主机键 以固定的化名检查应用程序自己的已知主机文件, 没有任何形式的转发, 没有共享 连接或配置命令,而不转发本地语言。 在Windows上,检测和部署开始 通过PowerShell,守护进程从服务器的默认 shell(cmd.exe 或 PowerShell)开始.

`env.listFiles(path, options, context)` 列出守护进程目录下方的树, 如 `fd --hidden --exclude .git` 在不遵循符号链接的情况下进行:文件、目录和链接作为相对 `/` 路径, 跳过 git 忽略的内容 以工作树为界 `maxEntries`, (中文(简体) ), `maxBytes` 财务报告和审定财务报表 `timeoutMs` 带有 `truncated` 旗下,然后终止 内容。 这是可选的 `ExecutionEnv.listFiles`一个守护进程在报告前发布 `not_supported` (单位:千美元)`hello.features` 缺少 `listFiles`),召唤者倒回自己的行走. 地方会议, `LocalExecutionEnv` 实值 `NodeExecutionEnv` 加号 `listFiles` 通过同一机器上的守护进程:

```ts
const local = new Connection({ command: [localDaemon()] }); // owned by the caller; close() it at shutdown
const env = new LocalExecutionEnv({ cwd: "/home/me/project", connection: local });
const listing = await env.listFiles(".", { exclude: ["node_modules"] }, context);
// { ok: true, value: { entries: [{ path: "src", kind: "directory" }, { path: "src/a.ts", kind: "file" }], truncated } }
```

`nodePlatform(await connection.info())` 给以节点名称中的远程系统( Q)`win32`, (中文(简体) ), `darwin`, (中文(简体) ), `x64`, (中文(简体) ), `arm64`, (中文(简体) ), 作为 `process.platform` 财务报告和审定财务报表 `process.arch` 拼出来.

`openTerminal(connection, options)` 运行一个程序,默认为用户的登录 shell, 默认为默认值, 默认为默认值 守护进程:用于交互式终端的原始输出,输入,再大小及其退出代码. `localDaemon()` 是此守护进程 机器,用于没有SSH的终端(`new Connection({ command: [localDaemon()] })`) (中文(简体) ). 不支持终端 视窗还没有.

`openProcess(connection, options)` 运行一个带有平通管线的程序,用于说 stdin 协议的程序和 stdout, 例如 MCP 服务器 : `write()` 财务报告和审定财务报表 `closeStdin()` 用于输入,原始 stdout 和 stderr 字节通过 `onStdout` 财务报告和审定财务报表 `onStderr`, (中文(简体) ), `close()` 杀死它的流程组,以及 `exited` 为它退出代码。 当程序退出时, 它开始于它的流程组 也被杀死,所以一个包装器,如 `npx` 留下什么也没有运行。 没什么 与终端不同,它能反射、翻译或合并;它在每一个支持的系统上工作。 一个守护进程在失败前释放 打开 `not_supported`。 。 。 . `argv` 运行为 `exec` argv 命令确实: 在 Windows 上, 批量文件, 如 `npx.cmd` 为: 被拒绝,因为节点拒绝 他们没有壳, 所以呼叫者开始他们通过 `cmd.exe`。 。 。 .

```ts
const server = await openProcess(connection, {
    cwd: "/home/me/project",
    argv: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
    onStdout: (bytes) => parser.push(bytes),
});
server.write(`${JSON.stringify(initialize)}\n`);
```

所支持的远程系统:Linux,macOS,Android (Termux)和Windows,在x86-64和arm64上. 在 Windows 上,字符串命令 运行在 Git Bash 作为 `NodeExecutionEnv` 运行它们在那里; argv 命令直接运行 .

## 发展

`npm run build:daemon` 以货物构建守护进程; 测试交谈到 `daemon/target/debug/pi-env` 过一管,或去 二进制名称 `PI_ENV_DAEMON` (CI测试释放 建立这种方式)。 他们经营耐用套房 反对 `RemoteExecutionEnv` 比较随机操作序列和持久工具 `NodeExecutionEnv` 打开 同样的机器. `test/ssh-external.test.ts` 在 SSH 服务器上运行套件 `PI_ENV_SSH_HOST` 已经设定.

## 常见问题

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

Pi 持久状态的远程执行环境: 在 SSH 及其 EmpireEnv 客户端上部署一个小守护进程

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

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

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

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

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

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

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

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

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

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

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

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

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

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