# @bendyline/docblocks 中文文档

规范地址：https://npmcn.com/package/%40bendyline/docblocks/

版本：2\.7\.13
npm 元数据更新时间：2026-11-05T23:00:30.280Z
中文译文更新时间：2026-11-07T22:15:43.112Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bendyline/docblocks
原文对照：https://npmcn.com/package/%40bendyline/docblocks/?lang=original
项目主页：https://docblocks.com/
源码仓库：https://github.com/bendyline/docblocks

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

- 包体积（解压后）：1.2 MB，74 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.18\.0 \|\| \>=26\.0\.0
- 运行依赖：2 个
- 首次发布：2026-04-04T01:13:01.593Z
- 最新版本发布：2026-11-05T23:00:29.926Z
- 近 30 天下载量：2760（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

DocBlocks 的核心数据结构和文件系统抽象

## 安装

```sh
npm install @bendyline/docblocks
```

也可以使用：`pnpm add @bendyline/docblocks`、`yarn add @bendyline/docblocks`、`bun add @bendyline/docblocks`

## README

# @ bendyline/ docblocks (英语)

DocBlocks的核心类型和抽象——跨越一个过程或存储边界(文件系统提供者,工作空间管理,以及Electron主机合同)的一切事物的单一真理来源.

## 安装

```bash
npm install @bendyline/docblocks
```

## 出口

该软件包暴露出有重点的子路径模块. 文件系统、文档、工作空间, 和主机 API 也从包根再导出; 边界特异性 电线协议在自己的入口处保持隔离.

### 文件系统( E)`@bendyline/docblocks/filesystem`(中文(简体) )

正确性第一,字节授权文件系统抽象—— **用于用户文档存储的单个连接**. UI 代码从不触碰 `indexedDB`, (中文(简体) ), `node:fs`,或 `electron` 直接;它通过一个提供者.

-   **`FileSystemProviderV2`** ——划出有口碑的路径,打出错误,有明显的突变模式,不透明版本,能力,快照,手表,和处置
-   **`WorkspacePath` 编号 : `parseWorkspacePath()`** ——可移植逻辑路径表示(`''` 是工作空间根)
-   **`FsError`** ——能活过IPC/结构克隆边界的稳定出错代码
-   **`IndexedDBFileSystemProvider`** – 浏览器- 本地持久存储( site, VS Code webview refack)
-   **`NativeFileSystemProvider`** – 浏览器中通过文件系统访问 API 的真实文件夹
-   **`ElectronFileSystemProvider`** ——连接主机API上的桌面主进程
-   **`MemoryFileSystemProvider`** – 权威内膜v2存储,用于瞬态松散文件和 DBK 工作空间
-   **`IndexedDBContentContainer`** 编号 : **`FileSystemContentContainer`** – 媒体与文档同时使用的内容-容器层
-   **`createFileMediaProvider`** ——媒体供应商接通文件系统供应商

```ts
import { IndexedDBFileSystemProvider, parseWorkspacePath } from '@bendyline/docblocks/filesystem';

const fs = new IndexedDBFileSystemProvider('my-workspace', 'My workspace');
const path = parseWorkspacePath('/doc.md');
await fs.v2.writeFile(path, new TextEncoder().encode('# Hello'), {
  mode: 'create',
  createParents: true,
});
const content = await fs.v2.readFile(path);
```

`FileSystemProvider` 在 v2 迁移期间, 文本兼容性仍为被贬值的外观。 新的代码应该发现 `provider.v2` 与 `getFileSystemProviderV2()` 并仅使用 v1 作为明确的相容倒置。 每个新的后端都必须通过共享的 v2 兼容套件.

提供者家庭也有隔离的入口, 所以是一个浏览器或桌面 表面只能装入它选择的后端 :

-   `@bendyline/docblocks/filesystem/indexeddb`
-   `@bendyline/docblocks/filesystem/memory`
-   `@bendyline/docblocks/filesystem/native`
-   `@bendyline/docblocks/filesystem/electron`

在多地壳中使用这些亚道的活性进口。 这个 兼容性 `filesystem` 枪管仍然可以再出口每个供应商 但急切地 从那个管子上建起 将互相排斥的后端放入一个启动器 捆绑.

突变行为明显: `writeFile` 接受一个 `create`, (中文(简体) ), `replace`,或 `upsert` 模式和默认值 `upsert` 省略时; `remove` 区分空目录去除和 递归性除去树;以及 `move` 永远不能覆盖它的目的地。 失踪 条目以 `null` 只有通过 `stat` 财务报告和审定财务报表 `readFile`允许, 错误类型、冲突、配额和 I/O 失败仍然被输入 `FsError`编号.

能力宣言是保守的承诺,而不是营销标签:

| 提供者 | 写入 | 移动 | 抓图 | 有条件写入 | 看着 | 重复性 |
| --- | --- | --- | --- | --- | --- | --- |
| 内存 | 进程 | 进程 | 进程 | 进程 | 对 | 不稳定 |
| 索引数据库 | 横线 | 横线 | 横线 | 存储-原子 | 没有 | 最佳成绩 |
| 本地文件系统访问 | 无 | 无 | 无 | 进程 | 没有 | 最佳成绩 |
| 电子工作空间 | 进程 | 进程 | 进程 | 进程 | 对 | 最佳成绩 |

版本是不透明的平等象征物,其发行商可以使用。 A 类 消费者决不能分析它们或比较不同供应商的征兆. 当一个表报 `overflow`,放弃增量假设并重新装入或 拍下相关状态.

索引 DB 工作空间迁移遗产 `fs:*` 文本/二进制命名空间 交易,然后使用 v2 记录作为其唯一的权限。 不同的遗产 或发布前 v2 数据作为明确的回收对象予以保留 被猜想离开。 如果过时的标签重现了遗留的密钥, 则以 a. 在要求的作业复试之前进行分行的前缀探测器隔离; 普通操作不会扫描或去除整个工作空间.

### 文 件 (续)`@bendyline/docblocks/document`(中文(简体) )

框架中性文件交易/会话原始:序列化的最新写作,单调修改,明确转换/再目标/删除/关闭,冲突状态,以及崩溃恢复等期刊.

### 工作空间( E)`@bendyline/docblocks/workspace`(中文(简体) )

工作空间注册——DocBlocks如何跟踪一个用户打开的文档收藏.

-   **`WorkspaceDescriptor`** 工作空间记录类型
-   **`listWorkspaces`** 编号 : **`getWorkspace`** 编号 : **`saveWorkspace`** 编号 : **`removeWorkspace`** - 登记册CRUD
-   **`touchWorkspace`** ——更新最后打开的时间戳
-   **`ensureDefaultWorkspace`** —— 如果不存在, 则创建默认的工作空间

```ts
import { listWorkspaces, ensureDefaultWorkspace } from '@bendyline/docblocks/workspace';

const workspaces = await listWorkspaces();
```

### 东道主( E)`@bendyline/docblocks/host`(中文(简体) )

Electron桌面外壳暴露于其渲染器的犬类合同(`fsV2`遗产 `fs`, (中文(简体) ), `workspaces`, (中文(简体) ), `shell`, (中文(简体) ), `ffmpeg`, (中文(简体) ), `updater`, (中文(简体) ), `menu`,打开文件请求).

-   **`DocBlocksHostAPI`** 合同类型(由 `desktop/main/ipc-*.ts`,由 `desktop/preload/preload.ts`(中文(简体) )
-   **`isElectronHost()`** ——特征- 检测桌面外壳
-   **`getDocBlocksHost()`** ——获得主机API(向电外推出)
-   **`maybeGetDocBlocksHost()`** ——获得主机API或 `null`,用于在浏览器中优雅地降解代码

```ts
import { isElectronHost, maybeGetDocBlocksHost } from '@bendyline/docblocks/host';

const host = maybeGetDocBlocksHost();
if (host) {
  await host.shell.revealInFolder(workspaceId, path);
}
```

### VS 代码协议 (`@bendyline/docblocks/vscode`(中文(简体) )

条子双向 `postMessage` vS码扩展合同 主机和编辑器网页视图。 双方都拥有同样的受歧视的结合 必须解析来源 `unknown` 数值为 `parseWebviewToExtensionMessage()` 或者说 `parseExtensionToWebviewMessage()` 在发送前.

## 公约

任何跨越 IPC,后Message,HTTP,或MCP边界的都属于这个包中——表面包决不能定义自己所复制的线型.

线型文档形状; 它们不授予权限 。 特权宿主必须 将运行时间值分析为 `unknown`,应用 `HOST_WIRE_LIMITS`,使用时 `parseExternalHttpUrl` ,并接受工作空间ID或 所有者范围不透明的赠款,而不是由渲染器提供的绝对路径.

## 许可证

麻省理工学院

## 常见问题

### @bendyline/docblocks 是什么？

DocBlocks 的核心数据结构和文件系统抽象

### 如何安装 @bendyline/docblocks？

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

### @bendyline/docblocks 支持 TypeScript 吗？

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

### @bendyline/docblocks 支持 ESM 还是 CommonJS？

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

### @bendyline/docblocks 需要什么版本的 Node\.js？

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

### @bendyline/docblocks 可以商用吗？

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

### @bendyline/docblocks 的下载量有多少？

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

### @bendyline/docblocks 还在维护吗？

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