# @erichll/pi-sandbox 中文文档

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

版本：0\.29\.2
npm 元数据更新时间：2026-11-03T02:40:45.115Z
中文译文更新时间：2026-11-14T06:38:30.920Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：169 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：3 个
- peer 依赖：typebox \>=1\.4\.3，pi-subagents \>=0\.83\.0，@earendil-works/pi-tui \>=1\.4\.0，@earendil-works/pi-coding-agent \>=1\.4\.0
- 首次发布：2026-07-28T05:32:01.093Z
- 最新版本发布：2026-11-03T02:40:44.964Z
- 近 30 天下载量：2247（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 58 个）

## 中文简介

Linux (bulble wrap) 和 macOS (Seatbelt) 为 Pi 处理沙盒, 由 Anthropic 的 @ harmanic-ai/ sandbox-runtime 支持 。 未关闭的静态文件系统政策 加上 Pi- auto- review 的每次连接网络审批; 沙盒主代理 Bash 和内置子ag

## 安装

```sh
npm install @erichll/pi-sandbox
```

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

## README

# @erichll/pi-sandbox (英语)

`pi-sandbox` 是一个Linux和macOS 进程沙盒,用于 Pi 由 Anthropic 支持 `@anthropic-ai/sandbox-runtime`它保护主要代理Bash命令,并能 还在独立的沙盒内运行完整的进程后置子剂树.

## 目录

-   [安保模式](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-security-model)
-   [Linux 要求](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-linux-requirements)
-   [子代理供应商](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-subagent-provider)
    -   [`pi-subagents` 本地背景工具边界](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-pi-subagents-native-background-tool-boundary)
-   [网络域政策](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-network-domain-policy)
-   [可选主机 IPC 倒置](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-optional-host-ipc-fallback)
-   [其他可信任的读取路径](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-additional-trusted-read-paths)
-   [安装](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-installation)
-   [发展](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-development)
-   [上游](https://npmcn.com/package/%40erichll/pi-sandbox/#readme-upstream)

## 安保模式

-   Linux 使用气泡包挂载/ 网络命名空间和 seccomp .
-   macOS使用生成的Seatbelt配置文件.
-   文件系统访问是一个静态政策:在允许的区域之外读取 在工作空间外写入失败 。 运行时文件系统否认 转换为动态赠款, 因为 Sandbox Runtime 不曝光一个 值得信赖的文件系统要求回调 .
-   网络策略被评价为静态否定、静态允许、动态 检讨. 每一个无与伦比的公共目的地都被送到 `pi-auto-review` 作为 罐头主机名和混凝土端口. 批准仅适用于 连接.
-   每个巴什指令和持久子代理会话都拥有一个单独的经纪人 进程和 Sandbox 运行时管理器。 因此,同时期工人保留 独立的政策、代理、批准和清理生命周期.
-   每个沙盒命令都有一个 **可写入的私人临时目录**(单位:千美元) 新鲜 `pi-sandbox-tmp-*` 添加到主机临时树的子目录 沙盒的读取/写出允许列表,带有命令的 `TMPDIR`, (中文(简体) ), `TMP`,以及 `TEMP` 指着它。 只有这个孤立的目录是可写入的——共享的 主机临时根( 例如 ). `/tmp` (本身)只读到沙盒——它 命令退出时删除。 如果没有主机临时目录 (例如只读) `/tmp`命令会降解为上一个已拒绝的调值 行为而不是失败.
-   项目和全球 Pi 安全配置, 信任的扩展树, 已安装的软件包、 Git 钩子和其他 Sandbox 运行时强制路径 继续保存.
-   默认情况下常见的工作空间秘密会被写入- 拒绝: root- level `.env` 变体, `secrets/` 编号 : `.secrets/`外加浅扫描 `.env*`, (中文(简体) ), `*.pem`, (中文(简体) ), `*.key`, (中文(简体) ), `*.p12`,以及 `*.pfx`模板文件,例如: `.env.example` 保持可写。 在 macOS 上, 额外的软块也会被堵住 创建; Linux Sandbox 运行时只执行字节路径, 所以嵌入创建 新的秘密文件仍然是扫描组外的剩余风险.
-   可选主机IPC执行默认被禁用. 启用时, 每个 完整主机命令仍需要一发 `pi-auto-review` 或人类 批准并运行 在OS沙盒之外.

此 Pi 适配器不支持 Windows .

## Linux 要求

在装入扩展名前安装本地助手 :

```bash
sudo apt-get install bubblewrap socat ripgrep
```

非特权用户命名空间必须可用 。 在Ubuntu24.04+上, 无论是 配置用于气泡包或禁用 AppArmor 配置文件 `kernel.apparmor_restrict_unprivileged_userns`。 。 。 .

macOS 使用内置的Seatbelt支持,但仍需要 `ripgrep`。 。 。 .

用于 Bun 编译的独立 Pi , 安装 **节点.js** 并包含其 `bin` 作为绝对条目的目录 `PATH`沙盒经纪人在其中运行 独立的节点进程; 内置子剂直接发射 Pi 可执行文件. 如果无法使用 `node` 找到,在执行前命令失败。 基于节点的 Pi 常规 `bun cli.js` 发射使用其现有的JavaScript运行时间.

## 子代理供应商

供应商是从配置中选择的(`~/.pi/agent/extensions/pi-sandbox/config.json` 全球或 `.pi/extensions/pi-sandbox/config.json` 项目-当地:

```json
{
  "subagents": {
    "provider": "builtin"
  }
}
```

支持的模式 :

-   `builtin` (默认) : 记录进程支持 `subagent` 工具与沙盒 每一个完整的工序树.
-   `pi-subagents`: 让 `pi-subagents >=0.83.0` 按要求自行指挥 下文描述的本土-背景工具边界.
-   `off`:只保护巴什.

### `pi-subagents` 本地背景工具边界

这个供应商需要Pi 1.4.0, `typebox >=1.4.3` 财务报告和审定财务报表 `pi-subagents >=0.83.0` (确定于0.83.0和0.83.1)和 未关闭 如果其公共天花板 API、模块布局、发现、拥有或运行时间路径 缝合漂流. 对等依赖是无上指针的地板 加载器明确出口和布局检查为正门. 在节点上 加载器别名 `@earendil-works/pi-tui` 运行中的 Pi 软件包的主机端点 . 在Bun上,包括编译的Pi,它通过了Pi's `pi-tui` 财务报告和审定财务报表 `typebox` 模块 将对象嵌入其内部加载器中,这样这些同位素就可以被嵌入到 Pi 中 安装在旁边 `pi-subagents`。 。 。 . 配置保护模式和不空的峡谷白名单 :

```json
{
  "subagents": {
    "provider": "pi-subagents",
    "protection": "native-background-tools",
    "allowedNativeAgents": ["worker", "reviewer", "scout"]
  }
}
```

这个 `pi-subagents` 配置时间 `~/.pi/agent/extensions/subagent/config.json` 还必须包含 `"scheduledRuns": { "enabled": false }`每次发射都必须明确规定 `async: true`。只支持直接的单剂发射。 公开 `workflowScript` 编号 : `workflowScriptPath` 儿童妨碍环境 上游扩展,所以两者 与命名的工作流程,时间表, 配置突变、恢复、链接附件、嵌入子剂和外部 赛跑者。 未知的管理动作被拒绝而不是默认信任.

指导仅限于直接出生的儿童,必须明确规定 `options: { "steeringRecovery": false }` (遗留的顶级拼写也 工作) (中文(简体) ). 使用完整的运行ID, 而不是前缀或 `dir`在引导前 适配器重新验证代理白名单并读取主机拥有的运行状态 : 所有权本身并不是保护。 目标需要沙盒的天花板 和它自己的儿童运行时间确认,包括同期会后 继承。 缺少/无效证明、链接路径或不再允许代理 块方向盘; 检查或停止运行。 这不是改装a 沙盒放在一个已经运行的无保护的孩子身上。 现状/停机坪仍然可用. 此状态文件检查是最佳的, 不是证明: 主机侧写器 访问 Async 运行时目录可以伪造 JSON 证明,包括 a 允许在此写入父工具 。 没有程序-当地发射-接收登记 ,因此保留恢复兼容性;单独保护运行时间 如果敌对作者在范围中.

每个儿童都受到上游能力上限的制约 `bash`, (中文(简体) ), `read`, (中文(简体) ), `grep`, (中文(简体) ), `find`,以及 `ls`。孩子装入环境扩展,必须 确认 `@erichll:pi-sandbox`;因此,只能通过 沙盒巴什工具 . `write`, (中文(简体) ), `edit`,MCP和其他扩展工具不是 可用.

| 能力 | `builtin` | `pi-subagents` 保护模式 |
| --- | --- | --- |
| 外出工人沙盒 | 对 | 没有 |
| 巴什沙盒 | 对 | 对 |
| 持续的后续行动 | 对 | 对 |
| 公开同步 `workflowScript` | 没有 | 否( 上游已禁用环境扩展) |
| 附表/已命名的工作流程资源 | 没有 | 没有 |
| 儿童工具 | 配置父工具 | 固定的5个工具上限 |

在发布之前,运行 决定性和模型支持的部分 `npm run gate:pi-subagents`。见 `docs/compat-notes.md` 用于记录的相容性接合以及每个接合方式 升级时核实.

配置解析器拒绝不正确的 JSON, 未知的字段和未知的 而不是默默地削弱孤立.

## 网络域政策

域授权可以全局配置于 `~/.pi/agent/extensions/pi-sandbox/config.json` 或项目所在地 `.pi/extensions/pi-sandbox/config.json` (与工会语义相融合):

```json
{
  "network": {
    "strictAllowlist": false,
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "registry.npmjs.org:443"
    ],
    "deniedDomains": [
      "uploads.github.com",
      "*:22"
    ]
  }
}
```

条目支持精确域, 严格子域通配符, 如 `*.example.com`,可选 `:port` 限制。 一个赤裸的 `*` (可选择) 仅允许在 `deniedDomains`价值被调整 已破损, 且配置不整齐或未知无法关闭 .

优先是决定:

1.  一个匹配 `deniedDomains` 条目拒绝连接.
2.  否则,一个匹配 `allowedDomains` 入境可以不经审查.
3.  否则,如果 `strictAllowlist` 实值 `true`,则该连接不包含 引用运行时请求回调,模式审查,或人类批准.
4.  否则, Cononical 公共主机名和端口会输入现有的 一发自动审查或人类批准流程.

两个阵列默认为空并 `strictAllowlist` 默认为 `false`,保留 现有的每个连接批准行为。 设置只接受布尔值 . 使用严格的模式和一个空的许可列表,所有代理目的地都会被拒绝. `deniedDomains: ["*"]` 块也允许条目,因为拒绝规则具有优先权. 同样的网络政策适用于主要代理Bash、用户Bash、内置子代理和 由被保护的本地装入的沙盒 Bash 工具 `pi-subagents` 孩子们.

对于仅限于明确批准的推断终点的工人:

```json
{
  "subagents": { "provider": "builtin" },
  "network": {
    "strictAllowlist": true,
    "allowedDomains": ["inference.example.com:443"],
    "deniedDomains": []
  },
  "hostIPC": { "mode": "off" }
}
```

将示例主机名替换为您批准的端点 。 全球和项目 `strictAllowlist` 值与逻辑 OR 合并: 项目不能严格禁用 需要全球模式。 域列表仍然组成工会,所以一个项目 **可添加 允许目的地**。两个文件都是可信任的政策输入;全局允许列表 不属于项目许可的行政上限.

严格模式不能与 `hostIPC.mode: "ask"`,因为主机执行 就能逃脱网络沙盒 有效配置在之前被拒绝 创建工具或工人;设置 Host-IPC 模式 `off`之后检查此选项 global/ project合并,并在嵌入式Host-IPC 覆盖后再次合并.

注册扩展名时装入配置 。 现有持久性 工人通过后续行动来维持其政策,发放工人得到的津贴相同 配置策略 。 重新装入扩展名并创建应用文件的新工作者 更改; 没有配置热重装 。 经纪人启动失败从不重试 沙盒外的工人 和无法提供的审批服务不能放松 严格网络否定.

域允许列表不是一个完整的数据-损失-防止边界. A 类 多租户或用户可加载的目的地,例如 `github.com` 能够自己是 过滤通道; 只授予您想要的狭窄域和端口 . 真正的软件包管理流量可能需要额外的主机- 例如 PyPI 常用下载 `files.pythonhosted.org`。 。 。 . `pi-sandbox` 永远不会推断或 默地添加了这些域.

原生背景跑跑者初始化本身位于OS沙盒外. 只有孩子的巴什修改通道被沙箱所覆盖. 选择 `builtin` 何时 整个工作流程树必须被 Sandbox Runtime 控制.

## 可选主机 IPC 倒置

一些主机服务只曝光OS沙盒无法使用的Unix套接字. 信任的全球配置可以启用一个由批准驱动的本地 Bash 这些命令的后端 :

```json
{
  "hostIPC": {
    "mode": "ask",
    "preflightCommandPrefixes": ["tmux", "/usr/bin/tmux"],
    "retryOnUnixSocketError": true
  }
}
```

`mode` 实值 `off` 默认且仅接受 `off` 或者说 `ask`前缀为 修饰相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相相去相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 前缀仅在 开始修剪命令,并必须在白空或结束时结束 命令。 前缀选择要审查的命令;它们从来不授权执行. 审阅员和一发奖金必须服从全权指挥和工作 目录.

与 `retryOnUnixSocketError` 启用, 未选择飞行前的命令 仍然在 Sandbox 运行时间第一。 只考虑一个主机重试 在非零退出之后,其stderr 识别了两者 `Operation not permitted` 以及一个插座/连接/IPC操作。 原产出保留 警告说,第一次尝试可能已经是局部的 效应。 成功, 超时, 或中止的命令永远不会被重试 .

主机转发器在内部内置的子代理中被故意拒绝 这个版本。 这也不符合 `network.strictAllowlist: true`。 。 。 .

## 其他可信任的读取路径

信任的全球配置可能会将绝对路径附加到沙盒中 默认读取许可列表 。 这对安装在下面的可执行文件有用 以其他方式拒绝的主目录 :

```json
{
  "subagents": {
    "provider": "builtin"
  },
  "filesystem": {
    "additionalAllowRead": [
      "/home/user/.local/bin/rtk"
    ]
  }
}
```

`filesystem.additionalAllowRead` 必须是一系列绝对路径。 这些 路径扩展默认;它们不替换工作空间、节点.js,或 Sandbox 运行时读取权限 。 尽量缩小条目 选择精确的可执行路径,而不是允许整个 bin 目录.

持续内在会议支助 `start`, (中文(简体) ), `follow_up`, (中文(简体) ), `wait`, (中文(简体) ), `status`, (中文(简体) ), `stop`并筑巢 `handoff` 操作。 最多四届是现场直播 一次,而筑巢深度被封为三.

## 项目级别配置和只读保护

除了用户级配置 `~/.pi/agent/extensions/pi-sandbox/config.json`, (中文(简体) ), `pi-sandbox` 支持放置在以下位置的项目级别配置:

```
.pi/extensions/pi-sandbox/config.json
```

目前,项目配置与全球配置合并:

-   阵列政策`additionalAllowRead`, (中文(简体) ), `allowedDomains`, (中文(简体) ), `deniedDomains`, (中文(简体) ), `preflightCommandPrefixes`(a) 组成一个分裂的联盟.
-   斯卡拉尔设置( S)`provider`, (中文(简体) ), `mode`, (中文(简体) ), `retryOnUnixSocketError`)允许项目级别覆盖.
-   `network.strictAllowlist` 使用逻辑 OR : `true` 在两个文件中都允许它. 这两个配置文件都可信;项目允许列表添加仍然有效.
-   合并配置不能同时启用严格的允许列表和Host-IPC `ask`。 。 。 .

**仅读的安全保证**数字 : 项目层面的配置在沙箱政策中得到明确保护(`denyWrite`, (中文(简体) ), 表示可读取的沙盒任务 `.pi/extensions/pi-sandbox/config.json` 但永远不能 从沙盒里篡改或覆盖它.

```bash
pi install npm:@erichll/pi-auto-review
pi install npm:@erichll/pi-sandbox
```

不在本地安装安全软件包 。 开发装载从 此寄存器需要 `PI_AUTO_REVIEW_ALLOW_UNTRUSTED_DEV=1`。 。 。 .

## 发展

从单列波根:

```bash
npm install
npm run check
npm test
npm run gate:pi-subagents
```

`gate:pi-subagents` 验证被钉住的发展依赖的一揽子布局, 发现行为, 能力上限和在孤立的临时代理中受保护的发射政策 目录。 它从未读取或更新出品的 Pi 配置. 模型支持 接受要求 `PI_SUBAGENTS_GATE_MODEL` 和已导出匹配 证书; 缺少的先决条件报告为 `SKIP`。当前对等点 地平面为Pi 1.4.0,有Pi-subagents 0.83.0,开发基线为: pi-subagents 0.83.1,两者均使用 `typebox >=1.4.3`。 。 。 . `pi-tui >=1.4.0` 是明确的主机对等点,而不是捆绑 运行时间依赖。 见 `docs/compat-notes.md` 记录的确定性 和模型支持的验证结果.

测试套房包含真正的 Linux Sandbox Runtime 执行 当它的本土 依赖性被安装,加上决定性的经纪人,网络批准, 工艺清理、货币和跨平台管弦测试.

## 上游

Sandbox Runtime是一个Apache-2.0许可的研究预览: [https://github.com/ 人类-实验/sandbox-runtime (中文(简体) )](https://github.com/anthropic-experimental/sandbox-runtime)。 。 。 .

## 常见问题

### @erichll/pi-sandbox 是什么？

Linux \(bulble wrap\) 和 macOS \(Seatbelt\) 为 Pi 处理沙盒, 由 Anthropic 的 @ harmanic-ai/ sandbox-runtime 支持 。 未关闭的静态文件系统政策 加上 Pi- auto- review 的每次连接网络审批; 沙盒主代理 Bash 和内置子ag

### 如何安装 @erichll/pi-sandbox？

在项目目录运行 npm install @erichll/pi-sandbox，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\>=1\.4\.3）、@earendil-works/pi-tui（\>=1\.4\.0）、@earendil-works/pi-coding-agent（\>=1\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @erichll/pi-sandbox 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/erichll\_\_pi-sandbox 是否存在。

### @erichll/pi-sandbox 支持 ESM 还是 CommonJS？

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

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

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

### @erichll/pi-sandbox 可以商用吗？

@erichll/pi-sandbox 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @erichll/pi-sandbox 的下载量有多少？

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

### @erichll/pi-sandbox 还在维护吗？

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