# @b4run/workspace 中文文档

规范地址：https://npmcn.com/package/%40b4run/workspace/

版本：0\.15\.8
npm 元数据更新时间：2026-10-30T22:22:43.078Z
中文译文更新时间：2026-11-07T16:18:01.223Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40b4run/workspace
原文对照：https://npmcn.com/package/%40b4run/workspace/?lang=original
项目主页：https://github.com/cacheplane/b4run/tree/main/packages/workspace#readme
源码仓库：https://github.com/cacheplane/b4run

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

- 包体积（解压后）：259 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：1 个
- 首次发布：2026-09-09T07:13:52.591Z
- 最新版本发布：2026-10-30T22:22:42.766Z
- 近 30 天下载量：5067（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

B4.run代理应用程序的文件系统和 shell 工作空间合同及工具.

## 安装

```sh
npm install @b4run/workspace
```

也可以使用：`pnpm add @b4run/workspace`、`yarn add @b4run/workspace`、`bun add @b4run/workspace`

## README

# @ b4run/ 工作空间

B4. 运行代理工作空间的文件系统和 shell后端合同.

**当 :** 您正在向 B4 运行应用程序提供文件系统或 shell 后端、 中间软件或工作空间工具 .

## 安装

```bash
pnpm add @b4run/workspace
```

## 示例

```ts
import { compose, type FilesystemBackend, withFilesystemLogging } from "@b4run/workspace"
import { localFilesystem } from "@b4run/workspace/node"

const base: FilesystemBackend = localFilesystem({ maxFileBytes: 512 * 1024 })
const filesystem = compose(withFilesystemLogging())(base)
```

## 运行时间和稳定性

### 获取初始源

节点入口提供 `captureWorkspaceSource`, (中文(简体) ), `createSourceBundle`, (中文(简体) ), `verifySourceBundle`,以及 `readSourceFile` 对于不可改变的源捆.

```ts
import { captureWorkspaceSource, readSourceFile } from "@b4run/workspace/node"

const source = await captureWorkspaceSource(appRoot, {
  directory: "fixtures/demo",
  include: ["index.ts", "package.json"],
  files: [{ path: "TASK.md", text: "Repair the failing example.\n" }],
})
const original = readSourceFile(source, "index.ts")
```

路径解析相对 `appRoot`。 。 。 . `include` 确切的文件目录; 意外文件导致抓取失败 . `excludeDirectories` 可明确省略 已有目录子树, 如已安装的依赖 。 其他条目 能够声明 `file` 路径相对 `appRoot` 而不是内含 `text`。 。 。 .

抓取会保存二进制字节和可执行标记,拒绝符号链接和 模糊路径,并返回一个内容不可变的经过验证的文摘。 限制是 10 000个不同的文件系统路径(包括应用程序根和祖先) 目录),每个文件有16个米B,以及64个米B的总文件内容. 源路径 使用具有一致目录外壳的便携式ASCII子集.

抓取读取信任的应用程序树并拒绝在 读取; 这不是原子文件系统快照 。 它不会创造出一个沙盒, 注册运行时间配置,或提供工作空间生命周期恢复.

### 检查文本工作空间

`inspectWorkspace` 接受权限约束 `ctx.fs` 作者手柄, a `SandboxHandle`,或任何 `WorkspaceReadSource` - 包括 `SandboxWorkspaceReader` 提供商的手从 `openWorkspaceReader`。它们都使用相同的有界限的横道 并需要叶元数据(`stat` 编号 : `lstat`)和原始二进制读取;缺少支持 未关闭 .

```ts
import { inspectWorkspace } from "@b4run/workspace"

const inventory = await inspectWorkspace(ctx.fs, {
  signal: ctx.signal,
  excludeRootDirectories: [".git"],
  expectedRootSymlinks: { node_modules: "/opt/project/node_modules" },
})
// inventory.files: relative path → exact UTF-8 text (including a leading BOM)
// inventory.symlinks: validated root name → exact readlink target
```

默认为一万个条目,每个文件有2个米B,以及16个米B文件总字节; `maxEntries`, (中文(简体) ), `maxFileBytes`,以及 `maxTotalBytes` 接受非负式安全整数. 目录和省略的根项数到条目限制; 工作空间 根本身没有。 限制检查报告大小和实际返回的字节. 结果还包括: `entries` 财务报告和审定财务报表 `totalBytes`。文件和链接记录 无效原型,所以文件名如下: `__proto__` 仍然是普通键.

排除的根名可能缺失,但当存在时必须是目录. 预期 根链接是需要的,必须与其准确、非正常的目标相匹配。 他们 目标从不穿越。 嵌入式条目没有根排除. 所有其他 符号链接,非文件/非目录条目,可执行文件,无效的UTF-8和 含有NUL的二进制数据被拒绝. 叶名不能穿行目录 . 接受没有NUL的UTF-8文本;这不是一个文件格式的分类器.

### 读取另一个线程的工作空间

`withWorkspaceReader(provider, { threadId, signal }, operation)` 打开提供者的 对一个线程的工作空间存储的可选只读视图, 将其交给 `operation`, (中文(简体) ), 并在成功和失败的道路上关闭它。 读者不带文字 方法和没有命令后端,读取不会扰乱线程的活性 沙盒 `openWorkspaceReader` 可选于 `SandboxProvider`; 提供者 省略它制造出来的 `withWorkspaceReader` 而不是默默无声地还原.

这是已经信任的呼叫者的主机侧 API 。 这不是授权 边框,不是代理人可以调用的工具,也不是HTTP表面.

通过一个信号检查每个文件系统调用周围的取消; 沙盒后端 他们也会收到 `BackendContext`。作者手柄保留现有的 许可政策和取消行为。 帮助者无法中断 正在飞行中。 它使用无外壳和主机文件系统API.

视察不是原子快照,也不是新的隔离边界。 元数据, 列出,并读取单独的后端调用,并可以与并行的作者进行比赛; 写作时要经过考核 或重新鉴定 精确链接验证链接身份, 而不是其外部目标的内容。 后端读取必须尊重所提供的 返回数据前绑定分配的字节上限 .

### 支持的表面

-   `@b4run/workspace` 是一个边缘安全、支持的应用程序表面.
-   `@b4run/workspace/node` 是一个唯一的节点,支持应用程序表面.

工作空间后端定义了运行地点;它们本身不是孤立的边界. 在未信任的执行必须离开主机进程时使用沙盒提供者.

## 相关

-   [工作空间 API 参考](https://b4.run/docs/api/workspace) ——精确的后端,中件,以及工具合同.
-   [工作空间文件系统](https://b4.run/docs/workspace) ——应用程序配置和后端行为.
-   [`@b4run/sandbox`](https://www.npmjs.com/package/@b4run/sandbox) ——工作空间操作隔离执行供应商.

## 成熟和支持

B4.run为1.0前置,其公用地表可以改变. 所有可公布的 B4. 运行包作为一个固定组一起发布; 审查 [`@b4run/workspace` 更改日志](https://github.com/cacheplane/b4run/blob/main/packages/workspace/CHANGELOG.md) 财务报告和审定财务报表 [升级指南](https://b4.run/docs/upgrading) 升级前。 用于支持, 使用 [GitHub 讨论](https://github.com/cacheplane/b4run/discussions); 报告缺陷 [GitHub 问题](https://github.com/cacheplane/b4run/issues)。 。 。 .

## 许可证

麻省理工学院. 见 [仓库许可证](https://github.com/cacheplane/b4run/blob/main/LICENSE)。 。 。 .

## 常见问题

### @b4run/workspace 是什么？

B4\.run代理应用程序的文件系统和 shell 工作空间合同及工具\.

### 如何安装 @b4run/workspace？

在项目目录运行 npm install @b4run/workspace，或使用 pnpm add / yarn add / bun add。

### @b4run/workspace 支持 TypeScript 吗？

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

### @b4run/workspace 支持 ESM 还是 CommonJS？

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

### @b4run/workspace 需要什么版本的 Node\.js？

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

### @b4run/workspace 可以商用吗？

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

### @b4run/workspace 的下载量有多少？

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

### @b4run/workspace 还在维护吗？

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