# @cloudflare/shell 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/shell/

版本：0\.5\.0
npm 元数据更新时间：2026-10-20T15:21:40.429Z
中文译文更新时间：2026-11-10T02:59:50.123Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/shell
原文对照：https://npmcn.com/package/%40cloudflare/shell/?lang=original
源码仓库：https://github.com/cloudflare/agents

弃用说明：Deprecated: use @cloudflare/computer\. Migration guide: https://github\.com/cloudflare/agents/blob/main/docs/shell/migrating-to-computer\.md

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

- 包体积（解压后）：486 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-03-13T08:54:42.401Z
- 最新版本发布：2026-10-20T15:20:53.129Z
- 近 30 天下载量：885652（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

折旧:使用@cloudflare/计算机。 Cloudflare工人代理的实验沙盒JS处决和文件系统运行时间

## 安装

```sh
npm install @cloudflare/shell
```

也可以使用：`pnpm add @cloudflare/shell`、`yarn add @cloudflare/shell`、`bun add @cloudflare/shell`

## README

# `@cloudflare/shell`

> **堕地.** 使用 [`@cloudflare/computer`](https://github.com/cloudflare/computer) 用于新的代理工作空间。 要移动已有文件,请参见 [移动到 `@cloudflare/computer`](https://github.com/cloudflare/agents/blob/main/docs/shell/migrating-to-computer.md)。 。 。 .

Cloudflare工人代理的 sandboxed JavaScript 执行和文件系统运行时间.

出版的软件包包括工作空间指南 `docs/index.md`。 。 。 .

而不是分析外壳语法, `@cloudflare/shell` 在孤立的工人内部运行 JavaScript 并曝光一个已输入的 `state` 在文件系统后端操作的对象。 它为代理工作流程所设计,需要结构化的状态操作,可预测的语义,以及粗糙的主机-侧文件系统原始.

## 这是什么

-   运行时间中性 `StateBackend` 文件系统/状态操作接口
-   A 类 `FileSystem` 与两个执行的接口: `InMemoryFs` (efemeral)和(effemeral)两款 `WorkspaceFileSystem` (可延长)
-   `FileSystemStateBackend` —— 单个适配器将任意 `FileSystem` 改为 a `StateBackend`
-   `Workspace` ——由 SQLite + 可选 R2 支持的持久文件存储
-   `stateTools(workspace)` a 包括: `ToolProvider` 页:1 `@cloudflare/codemode` 这暴露了 `state.*` 沙箱处决
-   `createGit(filesystem)` – 纯- JS git 操作通过同位素- git, 由虚拟文件系统支持
-   `gitTools(workspace)` a 包括: `ToolProvider` 页:1 `@cloudflare/codemode` 这暴露了 `git.*` 在沙盒中使用自动注入的认证处决
-   预建 `state` 带有 LLM 声明类型的 stdlib 提示

## 事实并非如此

这是 **没有** 面额翻译。 它不解析外壳语法,出露管子,或模仿POSIX外壳行为. 它执行JavaScript.

## 示例——记忆状态

```ts
import { createMemoryStateBackend } from "@cloudflare/shell";
import { stateToolsFromBackend } from "@cloudflare/shell/workers";
import { DynamicWorkerExecutor, resolveProvider } from "@cloudflare/codemode";

const backend = createMemoryStateBackend({
  files: {
    "/src/app.ts": 'export const answer = "foo";\n'
  }
});

const executor = new DynamicWorkerExecutor({ loader: env.LOADER });

const result = await executor.execute(
  `async () => {
    const text = await state.readFile("/src/app.ts");
    await state.writeFile("/src/app.ts", text.replace("foo", "bar"));
    return await state.readFile("/src/app.ts");
  }`,
  [resolveProvider(stateToolsFromBackend(backend))]
);
```

## 实例——持久工作空间

```ts
import { Agent } from "agents";
import { Workspace } from "@cloudflare/shell";
import { stateTools } from "@cloudflare/shell/workers";
import { DynamicWorkerExecutor, resolveProvider } from "@cloudflare/codemode";

class MyAgent extends Agent<Env> {
  workspace = new Workspace({
    sql: this.ctx.storage.sql,
    r2: this.env.MY_BUCKET,
    name: () => this.name
  });

  async run(code: string) {
    const executor = new DynamicWorkerExecutor({ loader: this.env.LOADER });
    return executor.execute(code, [
      resolveProvider(stateTools(this.workspace))
    ]);
  }
}
```

## 示例- git 操作

```ts
import { Agent } from "agents";
import { Workspace } from "@cloudflare/shell";
import { WorkspaceFileSystem } from "@cloudflare/shell";
import { createGit } from "@cloudflare/shell/git";

class MyAgent extends Agent<Env> {
  workspace = new Workspace({
    sql: this.ctx.storage.sql,
    name: () => this.name
  });

  async run() {
    const git = createGit(new WorkspaceFileSystem(this.workspace));

    await git.clone({ url: "https://github.com/org/repo", depth: 1 });
    await this.workspace.writeFile("/README.md", "# Updated");
    await git.add({ filepath: "." });
    await git.commit({
      message: "update readme",
      author: { name: "Agent", email: "agent@example.com" }
    });
    await git.push({ token: this.env.GITHUB_TOKEN });
  }
}
```

### Git 命令

`init`, (中文(简体) ), `clone`, (中文(简体) ), `status`, (中文(简体) ), `add`, (中文(简体) ), `rm`, (中文(简体) ), `commit`, (中文(简体) ), `log`, (中文(简体) ), `branch`, (中文(简体) ), `checkout`, (中文(简体) ), `fetch`, (中文(简体) ), `pull`, (中文(简体) ), `push`, (中文(简体) ), `diff`, (中文(简体) ), `remote`

### 用于代码的 Git 工具

`gitTools(workspace)` 揭露所有在沙盒处决中的命令 默认 auth被自动注入到克隆/fetch/pull/push——LLM从不看到秘密.

```ts
import { stateTools } from "@cloudflare/shell/workers";
import { gitTools } from "@cloudflare/shell/git";

const providers = [
  resolveProvider(stateTools(this.workspace)),
  resolveProvider(gitTools(this.workspace, { token: this.env.GITHUB_TOKEN }))
];
```

对于需要 Basic 认证的 Git 服务器, 通过隐藏的默认证书 :

```ts
const providers = [
  resolveProvider(stateTools(this.workspace)),
  resolveProvider(
    gitTools(this.workspace, {
      auth: {
        username: "git",
        password: this.env.GIT_PASSWORD
      }
    })
  )
];
```

如果两者兼有 `auth` 财务报告和审定财务报表 `token` 已配置, `auth` 已使用。 如果提供了直接工具调用验证,则优先于任何一种默认.

## 设计目标

-   结构化状态操作而不是外壳解析
-   粗糙的东道方业务 `glob()` 财务报告和审定财务报表 `diff()` 避免闲聊 RPC
-   与瞬间记忆状态和持久性的相容性 `Workspace`
-   安全执行, 隔离级别超时, 并默认封锁外出网络

## `state` 对象 API

这个 `state` 每个隔离和曝光中都有对象:

### 原始文件系统

`readFile`, (中文(简体) ), `writeFile`, (中文(简体) ), `appendFile`, (中文(简体) ), `readFileBytes`, (中文(简体) ), `writeFileBytes`, (中文(简体) ), `mkdir`, (中文(简体) ), `rm`, (中文(简体) ), `cp`, (中文(简体) ), `mv`, (中文(简体) ), `symlink`, (中文(简体) ), `readlink`, (中文(简体) ), `realpath`, (中文(简体) ), `readdir`, (中文(简体) ), `glob`, (中文(简体) ), `stat`, (中文(简体) ), `lstat`, (中文(简体) ), `exists`, (中文(简体) ), `diff`, (中文(简体) ), `diffContent`

### JSON 帮手

`readJson(path)`, (中文(简体) ), `writeJson(path, value, { spaces? })`, (中文(简体) ), `queryJson(path, query)`, (中文(简体) ), `updateJson(path, operations)`

### 搜索和替换

`searchText(path, query, options?)`, (中文(简体) ), `searchFiles(glob, query, options?)`, (中文(简体) ), `replaceInFile(path, search, replacement, options?)`, (中文(简体) ), `replaceInFiles(glob, search, replacement, { dryRun?, rollbackOnError?, ...options })`

### 文件系统查询

`find(path, options?)`, (中文(简体) ), `walkTree(path, { maxDepth? })`, (中文(简体) ), `summarizeTree(path, { maxDepth? })`

### 归档和压缩

`createArchive(path, sources)`, (中文(简体) ), `listArchive(path)`, (中文(简体) ), `extractArchive(path, destination)`, (中文(简体) ), `compressFile(path, destination?)`, (中文(简体) ), `decompressFile(path, destination?)`, (中文(简体) ), `hashFile(path, { algorithm? })`, (中文(简体) ), `detectFile(path)`

### 结构化编辑规划

`planEdits(instructions)`, (中文(简体) ), `applyEditPlan(plan, { dryRun?, rollbackOnError? })`, (中文(简体) ), `applyEdits(edits, { dryRun?, rollbackOnError? })`

## 多文件工作流程

```ts
// Preview changes without applying
const preview = await state.replaceInFiles("src/**/*.ts", "foo", "bar", {
  dryRun: true
});

// Plan structured edits with intent
const plan = await state.planEdits([
  { kind: "replace", path: "/src/app.ts", search: "foo", replacement: "bar" },
  { kind: "writeJson", path: "/src/config.json", value: { enabled: true } }
]);
await state.applyEditPlan(plan);

// Apply raw edits transactionally
await state.applyEdits([
  { path: "/src/generated.ts", content: "export const generated = true;\n" }
]);
```

如果任何写入失败, 批次默认会回滚 。 设定 `rollbackOnError: false` 允许部分进展.

## 命令翻译不顺利

| 贝壳命令 | `state` 等值单位 |
| --- | --- |
| `cat` | `state.readFile()` |
| `echo x > file` | `state.writeFile()` |
| `mkdir` | `state.mkdir()` |
| `ls` 编号 : `find` | `state.readdir()` 编号 : `state.glob()` |
| `find` 有过滤器 | `state.find()` |
| `tree` 编号 : `du` | `state.walkTree()` 编号 : `state.summarizeTree()` |
| `cp` 编号 : `mv` 编号 : `rm` | `state.cp()` 编号 : `state.mv()` 编号 : `state.rm()` |
| `diff` | `state.diff()` 编号 : `state.diffContent()` |
| `grep` | `state.searchText()` 编号 : `state.searchFiles()` |
| `sed` | `state.replaceInFile()` 编号 : `state.replaceInFiles()` |
| `jq` | `state.readJson()` 编号 : `state.queryJson()` 编号 : `state.updateJson()` |
| `tar` | `state.createArchive()` 编号 : `state.listArchive()` 编号 : `state.extractArchive()` |
| `gzip` 编号 : `gunzip` | `state.compressFile()` 编号 : `state.decompressFile()` |
| `sha256sum` 编号 : `file` | `state.hashFile()` 编号 : `state.detectFile()` |
| `git` | `git.*` 通过 `@cloudflare/shell/git` |

## 以后再说吧

-   由 `sort`, (中文(简体) ), `uniq`, (中文(简体) ), `comm`, (中文(简体) ), `cut`, (中文(简体) ), `paste`, (中文(简体) ), `tr`
-   满 `rg` CLI 等同——文件类型,忽略控件,多根
-   更接近 Richer JSON 查询语义 `jq` 过滤器
-   覆盖更多 diff / codemod 工作流程的结构补丁帮助
-   一个较小的“ 命令” 库, 建在顶端 `state.*`

## 与其他软件包的关系

-   `@cloudflare/codemode`: 执行带管弦乐工具的沙盒 JavaScript
-   `@cloudflare/shell`: 提供文件系统后端和 `stateTools()` 提供代码工具

## 常见问题

### @cloudflare/shell 是什么？

折旧:使用@cloudflare/计算机。 Cloudflare工人代理的实验沙盒JS处决和文件系统运行时间注意：该包已被作者标记为弃用——Deprecated: use @cloudflare/computer\. Migration guide: https://github\.com/cloudflare/agents/blob/main/docs/shell/migrating-to-computer\.md

### 如何安装 @cloudflare/shell？

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

### @cloudflare/shell 支持 TypeScript 吗？

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

### @cloudflare/shell 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudflare/shell 可以商用吗？

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

### @cloudflare/shell 的下载量有多少？

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

### @cloudflare/shell 还在维护吗？

最新版本 0\.5\.0 发布于 2026/10/20（20 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/03/13。作者已将其标记为弃用，新项目建议寻找替代方案。