# @desplega\.ai/agent-fs-just-bash 中文文档

规范地址：https://npmcn.com/package/%40desplega.ai/agent-fs-just-bash/

版本：0\.18\.25
npm 元数据更新时间：2026-11-12T00:31:00.557Z
中文译文更新时间：2026-11-12T01:27:56.618Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40desplega.ai/agent-fs-just-bash
原文对照：https://npmcn.com/package/%40desplega.ai/agent-fs-just-bash/?lang=original
项目主页：https://github.com/desplega-ai/agent-fs#readme
源码仓库：https://github.com/desplega-ai/agent-fs

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

- 包体积（解压后）：84.9 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：just-bash \>=3\.0\.1
- 首次发布：2026-06-04T16:16:10.237Z
- 最新版本发布：2026-11-12T00:31:00.165Z
- 近 30 天下载量：35925（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

代理文件系统适配器

## 安装

```sh
npm install @desplega.ai/agent-fs-just-bash
```

也可以使用：`pnpm add @desplega.ai/agent-fs-just-bash`、`yarn add @desplega.ai/agent-fs-just-bash`、`bun add @desplega.ai/agent-fs-just-bash`

## README

# @desplega.ai/探员-fs-just-bash

`just-bash` 用于代理用户的兼容文件系统适配器.

```ts
import { Bash } from "just-bash";
import { AgentFsFileSystem } from "@desplega.ai/agent-fs-just-bash";

const fs = new AgentFsFileSystem({
  baseUrl: "http://127.0.0.1:7433",
  apiKey: process.env.AGENT_FS_API_KEY,
  orgId: "org_...",
  driveId: "drive_...",
});

const bash = new Bash({ fs, cwd: "/" });
await bash.exec("cat README.md");
```

适配器与代理-fs守护进程HTTP API交谈. 用这个 `/raw` 用于字节安全 读书写作 `/ops` 页:1 `ls`, (中文(简体) ), `stat`, (中文(简体) ), `rm`, (中文(简体) ), `cp`,以及 `mv`。 。 。 .

## 支持的语义

-   文件作为原始字节读取并被写入.
-   Directories是代理-fs的前缀. 空目录以一个 隐藏 `.agent-fs-dir` 标记此适配器过滤器从 `readdir`。 。 。 .
-   `appendFile` 缺少时创建文件 .
-   `chmod` 财务报告和审定财务报表 `utimes` 校验路径存在, 然后取消操作, 因为代理 - fs 这样做 不坚持POSIX模式或调用人提供时间戳.
-   同步创建不支持并丢弃 `EPERM`· ; `lstat` 等同为 `stat`· ; `realpath` 返回已规范的虚拟路径.
-   硬链接大致为文件副本.

`getAllPaths()` 为同步 `just-bash` 接口,因此此适配器 返回通过读取、写取和列表找到的路径的本地缓存. 打电话 `await fs.refreshAllPaths()` 在 shell 命令之前,它依赖于光荣 已经流行的远程驱动器.

## 缓存

Shell 命令调用 `stat` 财务报告和审定财务报表 `readdir` 很多次都一样 这个 适配器保留 `stat` 财务报告和审定财务报表 `ls` 答案为 `cacheTtlMs` (违约5000毫秒)和 回答一个孩子的 `stat` 从其父母的列表中,如果可以的话。 文件内容 永远不会被缓存.

-   适配器自己的写作(`writeFile`, (中文(简体) ), `appendFile`, (中文(简体) ), `mkdir`, (中文(简体) ), `rm`, (中文(简体) ), `cp`, (中文(简体) ), `mv`) 放下它们改变的条目,所以它们一并可见.
-   另一客户端的更改可以隐蔽到 `cacheTtlMs`。 。 。 . `refreshAllPaths(path)` 将条目在 `path` 并再次列出清单.
-   `cacheTtlMs: 0` 关闭缓存. `cacheTtlMs: Infinity` 保存条目 案件的生命.
-   随着新条目的到来,过期的条目被删除,每个缓存最多持有 一万道道来. 过了那,最老的先走.

## 常见问题

### @desplega\.ai/agent-fs-just-bash 是什么？

代理文件系统适配器

### 如何安装 @desplega\.ai/agent-fs-just-bash？

在项目目录运行 npm install @desplega\.ai/agent-fs-just-bash，或使用 pnpm add / yarn add / bun add。

### @desplega\.ai/agent-fs-just-bash 支持 TypeScript 吗？

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

### @desplega\.ai/agent-fs-just-bash 支持 ESM 还是 CommonJS？

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

### @desplega\.ai/agent-fs-just-bash 可以商用吗？

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

### @desplega\.ai/agent-fs-just-bash 的下载量有多少？

根据 npm 官方下载统计，@desplega\.ai/agent-fs-just-bash 在 2026/10/12 – 2026/11/10 这 30 天内被下载 35,925 次，日均约 1,198 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @desplega\.ai/agent-fs-just-bash 还在维护吗？

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