# @alwith/module-fs 中文文档

规范地址：https://npmcn.com/package/%40alwith/module-fs/

版本：0\.6\.2
npm 元数据更新时间：2026-11-03T14:55:30.372Z
中文译文更新时间：2026-11-07T07:41:08.148Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：13.8 MB，747 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@tauri-apps/api ^3\.0\.0-alpha\.3
- 首次发布：2026-10-22T10:34:46.731Z
- 最新版本发布：2026-11-03T14:55:29.903Z
- 近 30 天下载量：2009（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

一个运输独立文件系统合同和操作协调员。 核心没有反应,DOM或Tauri依赖. 适配器执行权限;JavaScript能力只描述UI可用的动作.

## 安装

```sh
npm install @alwith/module-fs
```

也可以使用：`pnpm add @alwith/module-fs`、`yarn add @alwith/module-fs`、`bun add @alwith/module-fs`

## README

# @alwith/module-fs (英语)

一个运输独立文件系统合同和操作协调员。 核心没有反应,DOM或Tauri依赖. 适配器执行权限;JavaScript能力只描述UI可用的动作.

## 使用

```ts
import { createFileSystem } from "@alwith/module-fs"
import { createMemoryAdapter } from "@alwith/module-fs/testing"
const fs = createFileSystem({
  adapter: createMemoryAdapter({ "/project/readme.md": "# Hello" }),
  reportError: error => console.error(error)
})
const stop = fs.subscribe(event => console.log(event))
await fs.writeFile("/project/readme.md", new TextEncoder().encode("# Changed"), { mode: "replace" })
stop()
```

## 合同

-   `FsAdapter` 执行stat、字节读取/写入、目录列表、mkdir、移动、复制和删除. `stat` 返回为无效,仅用于缺失的路径;所有其他错误都传播.
-   `WriteOptions.mode` 区分只创建、替换和上升. `expectedVersion` 拒绝 Stale 储蓄。 适应者必须执行两者,而不是将其作为咨询.
-   `createFileSystem` 序列化变异和 `transaction` 一次打电话 交易接收到一个非排队写作机;从不从交易或守护内部调用外服的变异方法.
-   `beforeMutation` 可取消移动/删除/复制/mkdir。 编辑器控制器使用它来保护未保存被删除的文档. 取消拒绝使用 `MutationCancelledError`。警卫可以返回 `{ allow, release }` 以持有操作租赁,直到承诺/失败; 释放总是运行,不能改变磁盘结果.
-   `subscribe` 报告已采取行动。 土著/观察观测有单独的 `source: "watch"`; 它们是无效的,而不是证明一个特定的UI操作. `reportError` 绝不能扔出.
-   `watch` 是可选的。 主机拥有并发布了返回的订阅. 无法通过导入软件包开始投票或网络访问.
-   路径帮助者理解POSIX,Windows驱动器和UNC根. `joinPath` 接受一个文件名并拒绝翻转。 帮助者是名词化的;适配者仍然必须执行犬科/同名链接边界. 路径身份对案例有敏感认识;本土适配器必须提供一致的犬科特征.

## 土著分布

本地访问是 Tauri 插件 `alwith-fs` (crates.io);执行是本套件中运出的一个私人图书馆 `native/`,由应用程序出演.

```rust
.plugin(alwith_fs::init(alwith_fs::Config { development_directory, ..Default::default() }))
```

赠款 `alwith-fs:default` (开放、清单、统计、阅读、观察),并视需要, `alwith-fs:workspace-write`, (中文(简体) ), `alwith-fs:patches`, (中文(简体) ), `alwith-fs:git` (分支、文件状态、上游同步摘要、最近输入和更改的已打开的工作空间文件、在库中用 gix 读取、没有系统 git), `alwith-fs:exec` (单位:千美元)`workspace_exec_bash`: 用用户的登录 shell 在打开的工作空间中运行一个打入的 shell 命令, 5分钟后被杀死; 不是沙盒)和 `alwith-fs:capability` 内 `src-tauri/capabilities/*.json`。 。 。 . `@alwith/module-fs/commands` 保存生成的已键入命令和 `workspace:change` 事件; `@alwith/module-fs/tauri` 构建一个 `FsAdapter` 以他们的根部发誓 `commands.workspaceOpen`。 。 。 .

同步文件的应用程序通过 a `Coordinator` 内 `Config`:每个突变,都有其犬形文字和去除的路径,一次跑入其中;读取从不等. rust 代码使用 `FileSystem`, (中文(简体) ), `watch`, (中文(简体) ), `validate_patch_path`, (中文(简体) ), `apply_patches`,吉特读者 `current_branch`, (中文(简体) ), `file_statuses`, (中文(简体) ), `sync_status`, (中文(简体) ), `recent_commits` 财务报告和审定财务报表 `changed_files` (堵塞)和 `exec_bash` (async),它也在之后没有网页视图的情况下工作 `alwith_native_client::configure_host` 或者说 `ALWITH_NATIVE_DIRECTORY`,并通过 `app.state::<Workspace>()` (单位:千美元)`open`, (中文(简体) ), `root`, (中文(简体) ), `lock`) (中文(简体) ).

库限读出/写出16个米B,保存二进制字节,检查版本,使用同名标题的临时写作,拒绝终端符号链接的根突变和突变,并拒绝现有的副本/移动目的地. 在暴露目的地之前会制作递归拷贝。 补丁被完全验证(路径,同义链接, `.git`,hunks,大小)在第一次更改之前,与Git一起应用而未触及索引. 版本检查并不能提供针对任意外部作者的全OS交易. 观察错误被明确报告.

## 开发

从寄存器根 : `bun run --cwd packages/fs build` 财务报告和审定财务报表 `bun test packages/fs/src`; 内 `rust/`, (中文(简体) ), `cargo test` (约束当前; `UPDATE_BINDINGS=1` 并随着图书馆的建成, `ALWITH_NATIVE_DIRECTORY=<target/debug> cargo test -- --ignored`。出版授权是分开的.

## 常见问题

### @alwith/module-fs 是什么？

一个运输独立文件系统合同和操作协调员。 核心没有反应,DOM或Tauri依赖\. 适配器执行权限;JavaScript能力只描述UI可用的动作\.

### 如何安装 @alwith/module-fs？

在项目目录运行 npm install @alwith/module-fs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@tauri-apps/api（^3\.0\.0-alpha\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alwith/module-fs 支持 TypeScript 吗？

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

### @alwith/module-fs 支持 ESM 还是 CommonJS？

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

### @alwith/module-fs 可以商用吗？

@alwith/module-fs 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @alwith/module-fs 的下载量有多少？

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

### @alwith/module-fs 还在维护吗？

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