@cloudflare/shell

中文文档

0.5.0发布于 2026/10/20MITTypeScriptESM + CJS构建来源已验证近 30 天下载 88.6万

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

此软件包已被标记为弃用

Deprecated: use @cloudflare/computer. Migration guide: https://github.com/cloudflare/agents/blob/main/docs/shell/migrating-to-computer.md

文档目录19 节

这是什么
事实并非如此
示例——记忆状态
实例——持久工作空间
示例- git 操作
Git 命令
用于代码的 Git 工具
设计目标
state 对象 API
原始文件系统
JSON 帮手
搜索和替换
文件系统查询
归档和压缩
结构化编辑规划
多文件工作流程
命令翻译不顺利
以后再说吧
与其他软件包的关系

`@cloudflare/shell`

堕地. 使用 @cloudflare/computer 用于新的代理工作空间。要移动已有文件,请参见移动到 @cloudflare/computer。。。 .

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.

示例——记忆状态

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))]
);

实例——持久工作空间

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 操作

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: "[email protected]" }
    });
    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从不看到秘密.

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 服务器, 通过隐藏的默认证书 :

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? })

多文件工作流程

// 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 共发布 20 个版本，首次发布于 2026/03/13；过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`0.5.0`latest	2026/10/20	20 天前
`0.4.3`	2026/07/23	3 个月前
`0.4.2`	2026/07/23	3 个月前
`0.4.1`	2026/06/26	4 个月前
`0.4.0`	2026/06/13	4 个月前
`0.3.9`	2026/06/07	5 个月前

关于 @cloudflare/shell 的常见问题

@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。作者已将其标记为弃用，新项目建议寻找替代方案。

npm install @cloudflare/shell

pnpmpnpm add @cloudflare/shell
yarnyarn add @cloudflare/shell
bunbun add @cloudflare/shell

在你的项目目录中运行此命令。

近 30 天下载

885,652

约 88.6万次日均 29,522 次

统计周期 2026/10/10 – 2026/11/08
数据来自 npm 官方下载统计，今天更新

最新版本0.5.0发布于 20 天前

开源许可MIT宽松许可

包体积486 kB21 个文件 · 解压后

运行依赖2 个

模块格式ESM + CJS

TypeScript自带类型

发布版本20 个近 12 个月 20 个

首次发布2026/03/137 个月前

元数据更新2026/10/20

每一个软件包背后，
都有分享与创造的人。

@cloudflare/shell

@cloudflare/shell

这是什么

事实并非如此

示例——记忆状态

实例——持久工作空间

示例- git 操作

Git 命令

用于代码的 Git 工具

设计目标

state 对象 API

原始文件系统

JSON 帮手

搜索和替换

文件系统查询

归档和压缩

结构化编辑规划

多文件工作流程

命令翻译不顺利

以后再说吧

与其他软件包的关系

版本与发布记录

关于 @cloudflare/shell 的常见问题

@cloudflare/shell 是什么？

如何安装 @cloudflare/shell？

@cloudflare/shell 支持 TypeScript 吗？

@cloudflare/shell 支持 ESM 还是 CommonJS？

@cloudflare/shell 可以商用吗？

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

@cloudflare/shell 还在维护吗？

`@cloudflare/shell`

`state` 对象 API