# @hachej/boring-files 中文文档

规范地址：https://npmcn.com/package/%40hachej/boring-files/

版本：0\.5\.1
npm 元数据更新时间：2026-11-16T16:08:56.820Z
中文译文更新时间：2026-11-17T05:34:31.008Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hachej/boring-files
原文对照：https://npmcn.com/package/%40hachej/boring-files/?lang=original
项目主页：https://github.com/hachej/boring-ui#readme
源码仓库：https://github.com/hachej/boring-ui

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

- 包体积（解压后）：313 kB，59 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：1 个
- peer 依赖：isomorphic-git ^1\.42\.6，@earendil-works/chord ~1\.5\.2，@earendil-works/pi-durable ~1\.5\.2
- 首次发布：2026-10-11T19:07:27.799Z
- 最新版本发布：2026-11-16T16:08:56.451Z
- 近 30 天下载量：85879（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 98 个）

## 中文简介

版本资源合同和一个Pi FileSystem(磁盘,虚拟或SQLite)上的工作空间提供商.

## 安装

```sh
npm install @hachej/boring-files
```

也可以使用：`pnpm add @hachej/boring-files`、`yarn add @hachej/boring-files`、`bun add @hachej/boring-files`

## README

# @hachej/ 无聊的文件

一个工作空间文件的版本资源:合同,和Pi自己的FileSystem上的工作空间提供商(没有Boring文件系统). 读者、出版商和检索能力是可独立注入的;总资源提供者公布实际支助/赠款/可用性/合格保证。 ResourceClient 携带浏览器意图, 不可信主机资源访问 .

出版要求非空想变化和明确的原子化. 信任的边界计算出犬科摘要并检查批准情况;这些不是客户授权的授权字段。 接收确认有效的创建/替换/删除过渡;部分结果保留运行,输入指数和完整目标/视图. 和解是可选的,在要求和解时明确要求和解;未找到并不证明无效.

不透明资源视图ID是提供者范围,与提供者的实际支持/化身相接. 与 `import type`。 。 。 .

`@hachej/boring-files/workspace` 出口 `createWorkspaceProvider({ identity, fs, journal })`: 工作空间文件的提供方( u)[文件的一个位置](https://npmcn.com/package/docs/architecture/FILES-GIT-EXEC.md#one-place-for-files)) (中文(简体) ). 来来来来来来来来 `FileSystem` (磁盘环境,虚拟工作空间或下面的 SQLite后端),主机的工作空间身份和一个日记(`createWorkspaceJournal(connection)` 从 `@hachej/boring-files/journal`,收据,意图和SQLite中每个文件的最后20个版本. 修订为字节的Git blob ids. 在工作区队列内进行有条件的写入检查, 记录其意图, 记录其最后收到; 未完成的意向为 `unknown` 而永不重复播放。 它的主人关闭连接;提供者借用. 节点当前标记 `node:sqlite` 实验.

提供者接受全部或全无创建、替换和有条件删除,并通过 `renaming.rename`它拒绝工作视图和文件夹的变异而未产生任何效果。 逻辑路径与工作空间根相对;其真实位置会离开根的路径被拒绝. 单个文件在原子上被每个后端所取代;多文件批次只被SQLite后端所取取取取取取取取取取取取取取取取取取取取取取取取取取分取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取的取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 访问控制是主机的,位于工作空间边界:在工作空间内没有每个文件的权限,外部撤销的栅栏没有执行.

### 代理写入和更改种子

代理写作被观察到,从未收到([所有权裁决 2](https://npmcn.com/package/docs/architecture/FILES-GIT-EXEC.md#one-place-for-files)) (中文(简体) ). `provider.record({ path, before?, after, source: 'agent', conversationId? }, access)` 是文件守护者`@hachej/boring-agent/file-guard`呼叫一个Pi `write` 或者说 `edit` 成功: 文件的历史通过 `source: 'agent'` (和已替换的修订本, `source: 'observed'`,当 `before` 中包含其字节,变化反馈到 `agent` 活动。 它从来不写出版日记 也不刻薄收据 它不进入提供者的队列(守卫已经在它内部运行),因此从队列中调用它不能陷入僵局. 历史条目( E)`saves`, (中文(简体) ), `catalog.history`携带 `source`数字 : `publish`, (中文(简体) ), `agent`, (中文(简体) ), `observed` (单位:千美元)`keep` 并取代订正案), `rename` 或者说 `delete` (受影响的保留版本)。 历史仍然是每个内容修订一行,而不是一个操作日志;收据保留每个有条件的突变. 重命名保留了两条路径上被移动的版本;删除保留了被删除的版本而不发明墓碑修订. `savedAt` 仍然是该版本在该路径上首次被记录的节省时间,而不是单独的删除时间戳.

`provider.changes({ since?, signal }, access)` 是每个文件视图的一个更改种子: a `AsyncIterable` 联 合 国 `{ kind: 'change', path, revision | null, source: 'publish' | 'agent' | 'poll' | 'watch', seq, at }`,命令 `seq` 并可以从 `since` (最后一个) `seq` 见; `changeHead()` 是"现在"。 提供者保留最后一个 `changeBuffer` 事件( 默认 1024 ); 光标比此大, 从另一个提供者的寿命或此时间之前, 以及一个落在后面的听众得到 `{ kind: 'resnapshot', seq, at }`: 重新装入显示的一切, 然后继续 。 事件为无效提示;字节和日记保持权威. 资料来源:有条件写作(`publish`, (中文(简体) ), `record` (单位:千美元)`agent`, (中文(简体) ), `poll` 而有人听从 `watchLingerMs` 之后,默认为 30 s),文件系统本身 `watch` (单位:千美元)`watch`; 已报告的目录为 `{ revision: null, directory: true }`) (中文(简体) ). SQLite文件系统报告通过自己的连接即刻写出,并每隔一秒钟为其他连接投票. 当文件系统无法监视时( 虚拟和远程环境报告) `not_supported`),主机呼叫 `provider.poll()` 在每个代理回合的结尾:没有路径,它会将每个文件都拖走(不是) `.git` 或者说 `node_modules`;第一次呼叫取了基线,后来的报告更改了,新建并删除了文件. A 类 `bash` 写作只得到改变事件,从没有历史。 在最后的收听者离开收看者停留后,然后关闭;在没有收看者打开时所做的更改未知,因此第一个收听者随后使收看者附件成为 `resnapshot` (保持连接的客户端从未受到影响). `changeIncarnation` 命名提供者寿命: 与另一个光标一起发送的光标 `incarnation` 是一个 `resnapshot` 不管号码多少. `provider.close()` 结束每条变化流,关闭监视器并放下收听器.

接收范围按工作空间身份、主、范围和发起人划分。 同样承诺的重试返回原始收据;更改参数冲突。 被拒绝的操作不保留身份证。 工作空间早期化身的收据为 `unknown`。未找到的搜索不能重放不确定的操作.

`@hachej/boring-files/publication` 是浏览器安全。 它能捕捉请求字节,用WebCrypto来计算出一个版本的Canonic SHA-256文摘,并剖析出结果形状. 文摘载有 `boring-publication-v1:sha256:` 并将格式标识符装入散列有效载荷。 消费者还必须根据自己的请求检查经营、目标、范围和指数关联。 该模块没有授权。 SQLite 连接( S)`openNodeConnection` 从 `@hachej/boring-files/sqlite`)是一个单独的服务器入口.

`@hachej/boring-files/sqlite` 出口 `openNodeConnection(filename, settings?)` 联合国 `node:sqlite` 作为文件 `SqliteConnection`和 `openNodeDatabase(filename, settings?)` (已配置) `DatabaseSync`,对于皮的公共适配器: `SqliteStorage.open(new NodeSqliteDatabase(openNodeDatabase(file, settings)))`) (中文(简体) ). `settings` 实值 `SqliteSettings` `{ journalMode?: 'wal' | 'delete' | 'truncate' | 'persist', lockingMode?: 'normal' | 'exclusive', busyTimeoutMs?, synchronous?: 'off' | 'normal' | 'full' | 'extra', tempStore?: 'default' | 'file' | 'memory' }`; 缺失的字段来自 `sqliteSettings.localDisk` (WAL,正常锁定,5s繁忙超时,完全同步:设置存在前的行为). `sqliteSettings.networkFilesystem` 用于一个进程,在 NFS 上拥有文件,例如 EFS: 回滚日记, `exclusive` 锁定打开时的锁, 10 s 繁忙的超时, 完全同步, 临时的内存表格; 与文件的另一个连接失败 `SqliteLockedError` (单位:千美元)`code: 'sqlite-locked'`)在繁忙的超时后. 名称和价值允许列入清单(`TypeError` 否则,在文件打开之前; 没有自由形式 pragma 。 设置在 `@hachej/boring-files/sqlite-settings` (纯度,浏览器安全; `sqlitePragmas(settings)` 浏览器的 SQLite Wasm 使用,并且 `npm run check` 拒绝 `PRAGMA journal_mode`编号 :`locking_mode` 其他任何地方的任务。 日记,计量分类账和SQLite文件系统借出一个连接,从不设置平板电脑.

`@hachej/boring-files/sqlite-filesystem` 出口 `openSqliteFileSystem({ connection, workspace, cwd })`: 一个 Pi `FileSystem` 其正则文件和目录为工作空间的行 `SqliteConnection` (单位:千美元)`openNodeConnection`, (中文(简体) ), `durableObjectSqliteConnection`,或 `openBrowserSqliteConnection` 从私人,未公布 `@hachej/boring-browser/sqlite`,仅可在此单列坡内使用) `incarnation` 这些行。 像皮的一样 `NodeExecutionEnv` (这是皮的) `write` 工具依赖, `writeFile` 创建缺少的父目录; 属于文件的父目录仍然失败 。 给 `createWorkspaceProvider` 是 SQLite 工作空间后端([文件的一个位置](https://npmcn.com/package/docs/architecture/FILES-GIT-EXEC.md#one-place-for-files):多文件有条件批次在一个交易中执行,当日记使用同一连接时连同收件一起执行. 它执行Pi 1.2的满分 `FileSystem` (读者: `scanLines` 是阿皮自己来的 `LineScanner`,网页目录阅读器,以及民调 `watch`和回答与皮自己的 `FileError`s, 因此此条目载重 `@earendil-works/pi-durable/env` (Pi的便携式合同,没有发动机):安装 `@earendil-works/pi-durable` 带着它 此套件的其他条目不需要 Pi.

见 [脚手架指南](https://npmcn.com/package/docs/contracts/SCAFFOLD.md) 财务报告和审定财务报表 [资源设计](https://npmcn.com/package/docs/architecture/FILES-GIT-EXEC.md)。 。 。 .

### 大文件( blob指针) 和媒体嗅觉

大型或二进制文件(可达100 MB)可以活在主机的blob商店中,作为不可变的blob,而工作空间则在其位置上持有一个小指针文件, `<name>.blob.json` 有介质类型 `application/vnd.boring.blob+json`数字 : `{ "boring:blob": 1, "id", "sha256", "size", "type", "name" }`。在位字节是提供商的业务;指针是提供商代表一个巨大的不可移动的blob,像任何文件一样通过工作空间的一个提供商写作并阅读(没有第二名,没有同步). 主机服务字节 `GET <blobBase><encodeURIComponent(id)>` (默认) `/_files/`(b) 同一来源,检查每项请求的进入和设定处置, `nosniff` 和一个CSP. `@hachej/boring-files/blob` (纯,浏览器安全)导出:

-   `parseBlobPointer(bytes | text)`: 严格(输入 `BLOB_POINTER_MAX_BYTES` =4 KB,UTF-8 JSON,每个字段都有其类型,64个小写十六进制数字,一个非负式安全整数大小,一个介质类型,一个没有路径分隔符的名称. 它返回指针, `{ kind: 'unsupported-version', version }` 高级 `boring:blob` (将文件显示为JSON并说出"更新格式"),或 `undefined`。主机以相同的功能验证.
-   `checkBlobBase(base)`: 从一个开始的同源路径 `/`一个计谋,一个宿主, `//`,反斜或白色空间是一个 `TypeError`。 。 。 . `blobItemOf(pointer, base)` 财务报告和审定财务报表 `resolveBlobPointer(bytes, base)` 给 `{ name, size, type, url }`观众唯一看到的.
-   `withBlobPointers(provider, base)`: 作为列表的修订提供者读取: a 的每个指针文件 `list` 或者说 `search` 页面载 `blob` (单位:千美元)`FileEntry.blob`),通过同一个提供者读取一次. 读取仍然返回指针的字节.
-   `BLOB_POINTER_MEDIA_TYPE`, (中文(简体) ), `BLOB_POINTER_SUFFIX`, (中文(简体) ), `BLOB_POINTER_VERSION`, (中文(简体) ), `DEFAULT_BLOB_BASE`, (中文(简体) ), `isBlobPointerPath` 编辑 `BlobPointer` 编号 : `BlobItem` 类型.

`@hachej/boring-files/file-types` 是一个文件的表格. `sniffMediaType(head)` (通过最多 `SNIFF_BYTES` = 8 KB)名称 PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF (ISO-BMFF) `ftyp` 品牌: `heic`, (中文(简体) ), `heix`, (中文(简体) ), `hevc`...是HEIC吗; `mif1`编号 :`msf1` hEIC是一个HEVC相容的品牌,HEIF其他的,没有使用AVIF品牌的称号),并且单从头拉链文件: OpenDocument and EPUB 由所存储 `mimetype` 条目, docx/xlsx/pptx 乘以 a `[Content_Types].xml` 条目,然后是存储时的主要部分类型,否则是后期条目的文件夹(`word/`, (中文(简体) ), `xl/`, (中文(简体) ), `ppt/`) (中文(简体) ). 头从未被夸大(`[Content_Types].xml` 几乎总是被去充气,而充气在浏览器中是同步的,所以其大小在数据描述符中的zip不主张. 否则,无效的 UTF-8 字节为 NUL `text/plain`,一个从不凌驾于名字之上的弱答. `delimitedTextType(path, head)` 在字节为文本时, 表示扩展名的 CSV 或 TSV . `@hachej/boring-agent/file-types` 读取此表并读取头部大小;它只保留自己的路由类型.

## 节点主机

`@hachej/boring-files/node-http` 桥 `node:http` 转到这些软件包的获取处理器 : `webRequest(incoming, url, { signal, maxBytes })` 在字节盖下首先读取身体(从未读取) `Readable.toWeb` (b) 提出现场请求,而取消请求会影响这一进程) `sendWebResponse(response, outgoing, { signal })` 一次冲出信头, 保留每个信头 `set-cookie`,等待着 `drain` 当套接字满后,当客户端断开时取消网络正文。 服务器使用的范例; `npm run check` 拒绝手写回复副本 `examples/`。 。 。 .

## 可选认证的资源传输

`@hachej/boring-files/remote` 出口 `createResourceClient` 财务报告和审定财务报表 `createResourceHandler`。两者都是对现有资源合同的适配器。 他们不导入 Pi 运行时间、 文件系统或数据库 。 客户端执行 `ResourceClient`· ; `publication: true` 选择 `publish`, (中文(简体) ), `rename` 财务报告和审定财务报表 `delete`,以及 `reconciliation: true` 选择 `lookup`。处理器借用读者、可选的出版者、重命名者、删除者和查找者。 它从来没有关闭他们.

```ts
const handler = createResourceHandler({
  authenticate: request => host.authenticateResourceRequest(request),
  reader: provider,
  publisher: provider.publication,
  lookup: provider.reconciliation,
  renamer: provider.renaming,
  deleter: provider.deletion,
});
const client = createResourceClient({
  identity: { principalId, scopeId, initiatorId },
  endpoint: 'https://example.invalid/resources',
  fetch: authenticatedFetch,
  publication: true,
  reconciliation: true,
});
```

`publication: true` 需求 `reconciliation: true` (类型和构造器):其识别被丢失的变体 `unknown`,只有检查才能解决. 一个只读的客户端也没有设置 。 处理器为未安装的能力回答 405;客户端选择内置不授予服务器权限.

信任的认证返回 `ResourceAccess` 或无效。 其可选信号代表主机撤销;处理器将其与请求取消合并. 客户身份是预期的反应元数据,绝不是权威. 主办方拥有证书,来源/CSRF/CORS政策,端口路由和提供者封口. 注入的抓取必须尊重 `redirect: 'error'`,保留取消并永远不要重试效果。 绑定一个处理器到主机所选择的提供者能力. 浏览器 JSON 无法授权访问或提供可信赖的文摘或批准 .

私人版本的JSON信封在任何同步工作之前会捕捉出出版字节. 协议版本2载有字节作为cononical base64文本(版本1整数组被拒绝). 默认限制为每个序列化请求4个米B和每个序列化响应8个米B,可配置最多64个米B. 进入的身体使用有限度的生长缓冲. 这些是被接受的信息限制,而不是对获取分配,提供者输出,本地请求捕获,JSON扩展或文摘内存的限制. 主机必须将其信任的投入和提供者的生产分开.

全收或全收必须匹配被捕获的操作,犬科文摘,演员和完整的目标过渡. 收货单是保留下来的,但并不确定联系。 更改请求在发出前被拒绝;部分确认不合格,成为未知数。 在添加运输担保之前,真正的部分提供者必须订立其接收合同.

运输出错、不匹配或超规模的确认和中止观察产生未知的出版/查询结果。 他们从来没有制造一个已知的不承诺否认 或提供者没有找到, 并且从来没有触发回放。 读取失败无法使用 。 查询检查操作和演员协会;呼叫者仍然对照其捕获的原始尝试检查摘要和过渡. 单凭行动ID无法证实这些论点。 未找到不能授权重播 .

撤销会抑制披露直到处理器构建其响应;已经交付的字节无法被撤回. 中止观测不能证明提供者终止、回滚或原子撤销围栏。 提供者的例外和响应序列化失败可能跟随承诺,因此客户端保留了不确定性. 工作空间提供者申报的担保保持不变.

运行 `node fixtures/resource-transport.mjs` 用于通过真实的要求/响应对象进行虚构的精确保存和检索。 公共产出测试还组成了本土工具任务和丢失的识别标记调节. 被孤立的文档消费者用严格的类型和没有安装Pi,代理或React的浏览器捆绑来练习这个适配器. 这些检查不合格已部署的HTTP,浏览器身份政策或远程提供者生命周期.

`@hachej/boring-files/text` 供给共享纯度 `applyTextEdits` 转换和输入解析器。 编辑按顺序运行,需要独特的非空的精确匹配并保存未触动的白空间. 编辑失败拒绝整个转换 。 它没有执行I/O,也没有批准.

## 可选工作基特

`@hachej/boring-files/git` 需要钉入 `isomorphic-git@1.42.6`。 。 。 . `createGitRepository` 借给公众 `PromiseFsClient`,绝对规范目录、主机作者和当前 `authorize(operation)` 调用。 回调让绑定的呼叫者访问整个所选寄存器,包括工作树和元数据. 唯一准确 `true` 获得赠款。 它在队列获取后运行,并在返回结果前再次运行. 在呼叫者之间共享一个存储器实例 。 它的队列只将这些调用序列化;其他实例,原始文件系统作者和化名需要基础主机政策. 相对的参数验证并不限制不受限制的文件系统或同义链接目标.

`createEnvGitFs(fileSystem, context)` 这是 `PromiseFsClient` 超过一分 `FileSystem` (单位:千美元) `ExecutionEnv`'文件':每个Git读取和写出都经过这个环境,所以它的封口也适用于Git. 文件作为模式读取 `0o100644` (Pi的文件合同没有模式) 符号链接被拒绝(`ENOSYS`从来没有跟随.

方法是: `init`矩阵 `status`, (中文(简体) ), `add`,仅限索引 `remove`, (中文(简体) ), `commit`,二十进 `log`, (中文(简体) ), `branches`, (中文(简体) ), `branch`, (中文(简体) ), `checkout` 财务报告和审定财务报表 `diff`. Diff比较精确的树指针/对象ID,索引和工作树. 它返回已更改的blob路径、模式、对象ID和字节数组,包括未跟踪的工作树文件。 它排除 `.git`,拒绝不支持的条目类型,并报告限制错误而不短短成功。 默认返回内容限制为100个文件和1个MIB. Traversal是串行,但上游可以在检查字节限制前分配一个完整的blob. 这些限制不约束峰值内存或寄存器的倒转成本. 状态和工作树 diff 禁用本地索引刷新 .

主机拥有文件系统的封存,证书和处理. 没有安装网络传输. 取消在本地操作周围和diff traversal进行检查;它不能回滚Git突变. `GitOperationError.effects` 区分执行前拒绝与可能的先前突变. Git业务没有耐用业务收据,没有有条件的公布或失事修复保证.

### 当地出版筹备失败

`PublicationNotDispatchedError` 从 `@hachej/boring-files/publication` 识别远程客户端无法发送的有效出版请求。 内容 `operationId` 识别引用。 本地字节限制,不支持的原子,文摘,请求-构建和发送前取消失败都使用这个错误. 错误不能确定先前尝试使用同一操作ID的结果. 保留和调和任何先前的不确定企图.

一旦调取回调, 运输例外、 HTTP 错误和无效的确认仍然保留 `unknown`,包括一个在实施后投出相同错误等级的回调. 检查 `not-found` 仍然不能证明中断的请求没有效果。 文本控制器只使用被打出的错误来进行新生成的操作,释放出此尝试,这样用户就可以保存被更正的草稿.

SQLite 读取并接收对 SQLite 工作空间后端使用延迟读取交易的浏览; 有条件的写入保留它 `BEGIN IMMEDIATE` 其文件和收据的交易。 测试持有独立的WAL写作交易,并通过提供者读取之前承诺的文件和收件. 这符合 WAL 争论大小写; 打开数据库和任意 SQLite 锁定模式仍然需要写入访问或等待 .

## 从已删除的资源存储中移入

SQLite 资源存储 `@hachej/boring-files/sqlite` (单位:千美元)`openSqliteResources`, (中文(简体) ), `SqliteResourceProvider` 及其选项类型)是 已删除。 其文件成为工作空间的文件; `SqliteConnection` 财务报告和审定财务报表 `openNodeConnection` 留下来 `@hachej/boring-files/sqlite`。 。 。 . 一个主机,每个瞄准镜保留一个有行的存储器(这里的当前接合固定器)打开一个 SQLite 后置的工作空间 同一数据库中的范围:

| 旧电话 | 新电话 |
| --- | --- |
| `openSqliteResources({ filename, providerId, authorize })` | `connection = openNodeConnection(filename)`, (中文(简体) ), `journal = createWorkspaceJournal(connection)`,然后每个范围 `fs = openSqliteFileSystem({ connection, workspace: scopeId, cwd: '/workspace' })` 财务报告和审定财务报表 `createWorkspaceProvider({ identity: { providerId, instanceId: scopeId, incarnation: fs.incarnation, viewId: 'published' }, fs, journal })` |
| `openSqliteResources({ connection, ... })` (永久目标) | 同样的电话与 `durableObjectSqliteConnection(ctx.storage)` 从 `@hachej/boring-files/sqlite-durable-object` |
| `authorize(action, target, access)` 在商店里 | 主机在调用工作空间提供者之前检查其政策; [`shared/sqlite-workspaces.mjs`](https://npmcn.com/package/shared/sqlite-workspaces.mjs) 显示一种方式( 已执行操作的被拒绝的写入和拒绝的查找读取) `unknown`(中文(简体) ) |
| `provider.close()` | `connection.close()` 由连接的拥有者 |
| (单位:千美元) `delete` 变动 | 附有所观察到的修订的有条件出版物,或 `provider.deletion.delete({ path: locator, expectedRevision, operationId }, access)` |
| 修改为随机编号; 保存相同的字节做了新的修改 | 修改为 Git blob ids: 相同的字节保留其修改,以及 `before` 等于 `after` 是有效的承诺更改 |
| 每次订正保留 | 每个文件的最后20个版本(`createWorkspaceJournal(connection, { historyLimit })`; 较老的读取 `unavailable` |

现有存储数据库没有迁移: `boring_documents` 行不由工作空间后端读取 。 复制每个当前 将创建或从文件开始输入工作空间.

## 前端修订版提供者

`@hachej/boring-files/revision-handler` 为现有的工作空间提供商提供服务。 这个 主机解决其 OAuth 会话,并根据每项请求选择工作空间:

```ts
const handleFiles = createRevisionHandler({
  resolve: async request => {
    const session = await authenticate(request);
    if (!session) return null;
    return {
      provider: workspaces.workspace(session.workspaceId),
      access: {
        principalId: session.userId,
        scopeId: session.workspaceId,
        initiatorId: session.userId,
      },
    };
  },
});
```

`authenticate` 财务报告和审定财务报表 `workspaces` 是主机对象。 导入 `createRevisionHandler` 从 `@hachej/boring-files/revision-handler`。如果收购返回租赁, 包含 `release`管理者保留它,直到基本作业结束, 包括在请求取消之后.

在浏览器中导入 `connectRevisionProvider` 从 `@hachej/boring-files/revision` 并按选定工作区连接一次:

```ts
const revisionProvider = await connectRevisionProvider({
  endpoint: new URL('/api/workspace', location.origin),
  fetch: request => fetch(request),
});
```

同一路线也回答 `createResourceClient` 联 合 国 `@hachej/boring-files/remote`数字 : 资源呼吁(`read`, (中文(简体) ), `publish`, (中文(简体) ), `lookup`, (中文(简体) ), `rename`, (中文(简体) ), `delete`(没有 装订信头由 `createResourceHandler` 与解析访问,所以 信封的身份必须与之相匹配,有条件的写法拒绝 stale 修订版 与 `conflict`检查发送的装订信头(`409` 用于另一个 工作空间);列表和更改种子总是需要它. 一个只服务于 `createResourceHandler` (例如,2004年,纽约) `/api/resource`继续用同样的 客户端; `connectRevisionProvider` 发现失败(`405`),这意味着没有列名.

绑定从认证中发现身份和工作空间化身 服务器。 当选定工作空间发生变化时重新连接 。 它会暴露 `list`, (中文(简体) ), 文件名 `search`,保留 `history`, (中文(简体) ), `locate`, (中文(简体) ), `read`, (中文(简体) ), `publish`, (中文(简体) ), `lookup`, (中文(简体) ), `rename`, (中文(简体) ), `delete` 财务报告和审定财务报表 `changes({ since?, signal })`,工作空间的改变反馈.

```ts
const moved = await revisionProvider.rename?.({
  from: revisionProvider.locate('draft.md'),
  to: revisionProvider.locate('final.md'),
  expectedRevision: loaded.snapshot.ref.revision,
  operationId: 'move-draft-1',
});
const removed = await revisionProvider.delete?.({
  path: revisionProvider.locate('final.md'),
  expectedRevision: loaded.snapshot.ref.revision,
  operationId: 'remove-final-1',
});
```

这些方法发送 `rename` 财务报告和审定财务报表 `delete` 在同一认证文件上的类型 终点. `from`, (中文(简体) ), `to` 财务报告和审定财务报表 `path` 为: `ResourceLocator`而不是绳子 两者都要求 当前源修改; 重命名时也需要在同一处缺少目标 提供者/视图和现有的父目录。 使用直接工作空间呼叫器 `provider.renaming.rename(request, access)` 财务报告和审定财务报表 `provider.deletion.delete(request, access)`。 。 。 . 重命名收件是内容相同的删除/ 创建对; 其种子 释放出旧路径 `revision: null` 然后是新途径的修订,两者 `source: 'publish'`。 。 。 . 删除发射 `revision: null`. Stale 修订和现有文件目标冲突. 相同的操作ID重试和 `lookup` 返回原始收据;已更改 参数冲突。 丢失的回复保留 `unknown`从不自动重试. `createRevisionHandler` 从选定的提供者安装这些能力 并持有同样的工作空间租约,直到他们解决。 一般资源处理器 安装 `renamer`编号 :`deleter` 当然 文件夹、 递归删除和文件树 重命名/删除控件不属于此端点递增的一部分.

两个操作都使用工作空间队列和 Pi 的本地 `renameFile`编号 :`remove`。 。 。 . SQLite(包括持久对象适配器)再利用这些文件系统变异 当日记分享其连接时,在字节/历史/收件交易中. 磁盘/远程后端保留其现有的崩溃窗口:没有效果 已完成的日记收据为 `unknown`. 贝壳作家仍然在排队之外.

饲料是 `GET <endpoint>?op=changes[&since=<seq>&incarnation=<id>]` 与绑定头相接: 服务器发送事件( e)`event: ready` 然后是现世的后世和供养者 `event: change` 或者说 `event: resnapshot` 与 `id:` 下至JSON事件 `data:`页:1 注释行数 `heartbeatMs` (单位:千美元)`createRevisionHandler({ resolve, heartbeatMs })`, (中文(简体) ), 默认 15 s). 这是一个没有队列的平流响应( 以推为主), 所以是一个缓慢的客户端 花费提供者的限定回放缓冲器和 a `resnapshot`内存 处理器; 撤销会丢弃任何未读的 。 它运行在节点和工人上 一样。 操作者持有工作空间租赁 溪流的生命和 当客户端断开或访问信号中断时释放它; 请求 主机拒绝,或者其约束性名称是另一个工作空间或身份,但没有得到 事件(403或409)。 客户端在交付的后几后重新连接,与 备份,直到其 `signal` 中止;拒绝结束为 `RevisionError`。 。 。 . 所有写作都使用有条件的发布; 上传新文件需要缺发, 并且替换一个需要精确的资源修订。 未知结果必须 在上传到该路径之前通过操作ID调节.

目录默认隐藏 Git- ignored 文件、 依赖/ 构建文件夹和内部 元数据。 配置 `createWorkspaceProvider({ ..., catalog: { defaults: false, filter: entry => ... } })` 来推翻他们 过滤器规范演示文稿, 不 进入控制。 主机授权整个所选的工作空间. 列出 不跟随符号链接。 平地取景是一种活生生的地貌,不是被冻结的快照; 在同一修改后刷新。 在配置中拖曳 `maxEntries` (违约10万)明显失败. A. 历史 工作空间日记,不是 Git 承诺,也不是导入文件系统的以往历史 .

文件搜索( `@` picker, 树的过滤器) 并上传此路径 还有: `search` 是目录请求, 而上传是有条件的创建 (单位:千美元)`expected: absent`与任何其他出版物一样,有收据。 没有 要服务的单独搜索或上传路径.

`createRevisionHandler({ resolve, maxFileBytes })` 最大文件名称 写入可能带入字节( 默认为 3 MiB; 最多) 大约48米B). 字节作为 Base64 旅行,所以处理器大小为其资源 请求和对该限制的答复(至少4个小米B和8个小米B)。 一个更大的文件 获得键 `file_too_large` 结果(`{ path, size, limit, reason }`和 无所写; 重放日志保存过的操作 记录结果。 大于运输载体的请求得到答复 413, 客户报告为 `unavailable` (明确拒绝)。 约束 (单位:千美元)`GET` 无 `op`将限制命名为 `limits.maxFileBytes`· ; `connectRevisionProvider` 将其请求大小显示为 `maxFileBytes`,且文件树在发送前拒绝更大的上传. 提供者自己的文件系统可能拒绝一个较小的文件(SQLite:1 900 000) 默认字节). 此 API 不提供流上传 .

### 持久对象应用程序

一个 Cloudflare 持久对象将它的工作空间保存在自己的SQLite存储器中,而库与节点主机一样与之相接. 每个 块是节点示例使用的一个,与 `durableObjectSqliteConnection(ctx.storage)` 从 `@hachej/boring-files/sqlite-durable-object` 替换 `openNodeConnection`。工作空间及其日记共享一个连接, 所以一个多文件保存, 并且它的收件被输入到其中 `transactionSync`数字 :

```ts
import { durableObjectSqliteConnection } from '@hachej/boring-files/sqlite-durable-object';
import { openSqliteFileSystem } from '@hachej/boring-files/sqlite-filesystem';
import { createWorkspaceJournal } from '@hachej/boring-files/journal';
import { createWorkspaceProvider } from '@hachej/boring-files/workspace';
import { createRevisionHandler } from '@hachej/boring-files/revision-handler';

// In the object's constructor: one connection and journal, one provider per workspace the object serves.
const connection = durableObjectSqliteConnection(this.ctx.storage);
const journal = createWorkspaceJournal(connection);
const fs = openSqliteFileSystem({ connection, workspace: workspaceId, cwd: '/workspace' });
const provider = createWorkspaceProvider({
  identity: { providerId: 'files', instanceId: workspaceId, incarnation: fs.incarnation, viewId: 'published' },
  fs,
  journal,
});

// The object's HTTP route: the host authenticates the request and picks the workspace it selected.
const handleFiles = createRevisionHandler({
  resolve: async request => {
    const session = await authenticate(request);
    if (!session) return null;
    return { provider: this.providerFor(session.workspaceId), access: { principalId: session.userId, scopeId: session.workspaceId, initiatorId: session.userId } };
  },
});
```

`history` 是日志对每个文件的保留修改, 首先是最新的, 与 `savedAt` 以毫秒计; 此选项之前已保存 日记记录时间报告 `savedAt: 0`。浏览器的连接方式如下: `connectRevisionProvider({ endpoint, fetch })` 从 `@hachej/boring-files/revision`。每个范围都是自己的工作空间(按键为: `workspace`),因此,只从 提供者 `resolve` 返回.

## 常见问题

### @hachej/boring-files 是什么？

版本资源合同和一个Pi FileSystem\(磁盘,虚拟或SQLite\)上的工作空间提供商\.

### 如何安装 @hachej/boring-files？

在项目目录运行 npm install @hachej/boring-files，或使用 pnpm add / yarn add / bun add。

### @hachej/boring-files 支持 TypeScript 吗？

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

### @hachej/boring-files 支持 ESM 还是 CommonJS？

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

### @hachej/boring-files 需要什么版本的 Node\.js？

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

### @hachej/boring-files 可以商用吗？

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

### @hachej/boring-files 的下载量有多少？

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

### @hachej/boring-files 还在维护吗？

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

