# @abele/sync-sdk 中文文档

规范地址：https://npmcn.com/package/%40abele/sync-sdk/

版本：0\.3\.17
npm 元数据更新时间：2026-11-05T00:18:40.571Z
中文译文更新时间：2026-11-06T09:11:02.880Z
软件包许可：GPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40abele/sync-sdk
原文对照：https://npmcn.com/package/%40abele/sync-sdk/?lang=original
项目主页：https://github.com/dudaanton/abele-sync-sdk/tree/main/packages/sdk#readme
源码仓库：https://github.com/dudaanton/abele-sync-sdk

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

- 包体积（解压后）：1.7 MB，286 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：7 个
- 首次发布：2026-10-19T21:12:44.177Z
- 最新版本发布：2026-11-05T00:18:40.372Z
- 近 30 天下载量：3649（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

节点客户端 SDK 用连接密钥同步一个文件夹或您自己的存储器, 包括任务和注释解析器 .

## 安装

```sh
npm install @abele/sync-sdk
```

也可以使用：`pnpm add @abele/sync-sdk`、`yarn add @abele/sync-sdk`、`bun add @abele/sync-sdk`

## README

# @abele/sync-sdk (英语)

安装目标 : `npm install @abele/sync-sdk`。 。 。 .

```js
import { open, parseKey } from "@abele/sync-sdk";
const key = process.env.SYNC_KEY;
parseKey(key); // local validation
const client = await open({ key, dir: "./mirror" });
try {
  await client.syncOnce();
  console.log(await client.replica.list());
} finally {
  await client.close();
}
```

## API 和业务

SDK 0.3.17 批次将保留物移入耐用组群。 本地 V2 主机可以 选择使用 `onRemovalCohort` 和借来的 `cohort.retain` 处理; 有 `onRemoval` 主持人继续工作. 公共群体援助人员可通过 核心导出。 所有权和召回合同见移民清单. 这件装饰品不是出版物或部署.

自定义主机必须跟随 [0.3.0 移徙清单](https://github.com/dudaanton/abele-sync-sdk/blob/main/docs/migration-0.3.md)。 。 。 . `pause()` 财务报告和审定财务报表 `stop()` 中断活动同步 。 中断 `syncOnce()` 拒绝 导出 `SyncCancelled`; 在检查前将其作为有意注销处理 继承 `offline` 代码。 取消显示没有出错事件或下线重试 .

要求节点.js 22+和无害环境管理。 SDK 0.3.17 有核心、节点和协议的对 **0.5.0 (单位:千美元)**,带有服务器目标 **0.3.3 (中文(简体) )** 财务报告和审定财务报表 **0.5.0 (单位:千美元)** (单位:千美元)`compat.json`议定书2 需要; 仅它的号码并不能保证与每个服务器的兼容性 建设。 匹配的核心,节点适配器和协议被捆绑在这个包内.

## 打开和适配器

`parseKey(key)` 在本地验证和解码时没有网络访问. 结果 包含符号地址和遗留范围或v2项目预览;将其作为证书处理. `open(options)` 检查能力和活动连接,然后打开本地 状态和完成恢复。 打电话 `syncOnce()` 明确用于当前服务器数据.

`client.scope` 报告服务器连接的文件夹、组或文件范围。 路径是 相对于预计的复制品。 没有SDK组管理 API. `client.readOnly` ; 没有本地只读选项. 来电同步仍然可以写入本地文件 。 使用服务器权限防止上传.

选择其中之一 `{ key, dir, stateDir? }` 用于SDK拥有的节点适配器,或 `{ key, files, state }` 为呼叫者拥有的适配器. `FileSystem` 财务报告和审定财务报表 `StateStore` 是导出的核心接口,而不是构建器。 供应自定义适配器和 不将它们与目录选项合并。 他们的耐久性,观看和最后 处理属于呼叫者; 关闭 SDK 不处理它们.

可选 `transport.fetch` 财务报告和审定财务报表 `transport.WebSocket` 替换全域节点. `clock: () => number` 以毫秒计的供给引擎时间,而不是文件系统 锁/恢复时钟. `logger: (line: string) => void` 接受一般活动 备注. `backoffMs: [min, max]` 财务报告和审定财务报表 `fallbackMs` 配置重试和周期 同步延迟以毫秒计 . `deleteGuard` 财务报告和审定财务报表 `defer` 控制决定如下.

## 项目集(服务器:0.5.0)

```ts
import { ItemClient, AccessClient, open } from "@abele/sync-sdk";

const owner = ItemClient.fromToken(ownerKey, { fetch });
if (await owner.supportsItems()) {
  const added = await owner.addItem(targetTokenId, {
    kind: "file",
    id: fileId,
  });
  const recipient = ItemClient.fromToken(recipientKey, { fetch });
  const inventory = await recipient.items();
  const client = await open({
    key: recipientKey,
    item: added.id,
    files,
    state,
  });
  try {
    await client.syncOnce();
  } finally {
    await client.close();
  }
  await owner.removeItem(targetTokenId, added.id); // detach access, keep content
}
```

`items()` 列出调用密钥的项目,包括已删除的条目. `ItemClient.tokenItems(tokenId)` 财务报告和审定财务报表 `AccessClient.tokenItems(tokenId)` 列表 a 拥有的密钥项目没有它的收件人秘密. `AccessClient.tokens()` 包含 选项 `item_count` 值; 旧服务器省略. `./protocol` 出口 `V2TokenItemsResponseSchema` 财务报告和审定财务报表 `V2TokenItemsResponse` 用于所有者库存回复.

项目清单、预览、总数和项目清点被过滤到呼叫者范围. 隐藏的子项目被省略; 直接预览一个返回 HTTP 403. 组 `overlap_count` 包括未披露的股票,因此可能超过 `overlaps.length` 甚至低于响应上限。 未披露的重叠没有 数组条目、路径或标识符;不要推断空数组不存在. 重叠-详细方案不变:披露的条目仍有所有字段. `ItemClient` 表面为 403 `AbeleError` 与 `code: "forbidden"` 财务报告和审定财务报表 `status: 403`,匹配服务器错误信封 `AccessClient`两者 `AbeleError` 财务报告和审定财务报表 `HttpError` 以 SDK 根导出( 非信封) 可拒绝访问 `HttpError` 与 `status: 403`) (中文(简体) ). 这将项目Client 403处理从 HttpError/ protocol 更改为 AbeleError/ forbidden . 消费者必须处理被省略的项目和部分总数,而不加以处理 作为完整的密钥库存或全库删除效果.

两个客户都曝光了 `previewTokenItem(tokenId, itemId, { limit? })` 财务报告和审定财务报表 `previewToken(tokenId, { limit? })` 用于所有者授权的删除效果预览. 它们返回完整的文件/字节总和,封顶的文件路径和组交叉键重叠; 文件/文件夹预览有空重叠列表。 密钥总计 。 可选文件限制默认为 100,上限为500;重叠名单上限为20. 这些只读 预览,而不是删除授权或快照保证. `./protocol` 出口 `V2ContentPreviewQuerySchema`, (中文(简体) ), `V2ItemContentPreviewSchema`, (中文(简体) ), `V2TokenContentPreviewSchema`,其反应类型 `V2ItemContentPreview` 财务报告和审定财务报表 `V2TokenContentPreview`,则 `V2_PREVIEW_FILE_LIMIT` 财务报告和审定财务报表 `V2_PREVIEW_OVERLAP_LIMIT` 常数。 发行人或 整个所有者使用 `addItem(tokenId, selector)` 财务报告和审定财务报表 `removeItem(tokenId, itemId)` 用于管理目标密钥。 选择器支持 `folder`, (中文(简体) ), `group` 财务报告和审定财务报表 `file`;他们的ID识别服务器对象,而不是路径. 使用 `AccessClient.fromToken(key, { fetch })` 发出/列出/撤消密钥 `V2EngineClient` 从根或 `./core` 用于低级引擎操作.

`deleteItem(itemId, idempotencyKey)` 删除选中项目的服务器内容 在服务器所有权检查下。 它可以瞄准自有收件人的密钥项目. 在重新试验这种破坏行动时,坚持并再利用同样的同能键. 删除访问和删除内容是单独的操作.

`supportsItems()` 探测已认证的库存路径, 因为服务器 不在物品能力旗上作广告。 它在404上变回了假,扔了 关于认证、连接、错误反应和其他服务器错误. 服务器0.3.3只支持遗留密钥. `open({ item })` 检查项目支持 打开内容连接前; 省略 `item` 保留主镜行为. 每个项目都需要单独的文件和状态. 节点复制品在其中坚持选择 连接身份并拒绝在已有状态目录中切换项目.

`parseKey` 接受遗留的有效载荷v1(`scope`)和有效载荷v2(`items` 预览). 用工会的 `v` 字段来缩小它。 预览是提示; 服务器连接 和库存提供当前权威. `./protocol` 导出 v2 令牌, a. 项目、选择器、连接和删除计划以及现有有效载荷类型; 根也输出 `ScopeItem`, (中文(简体) ), `ScopeItemsResponse`, (中文(简体) ), `V2AccessToken`, (中文(简体) ), `V2Scope`, (中文(简体) ), `V2Selector`, (中文(简体) ), `V2Connection` 和核心数据 `ClientOptions` 类型.

## 国家、锁和复原

默认 `dir/.abele-sync` 存储配置(包括证书), SQLite状态和恢复证据. 保持它私密 并远离其他同步工具. `stateDir` 可以命名一个外部目录,或者确切的默认状态路径; 复制品内的其他路径,包括同名异名,都被拒绝.

外部状态将证书和分类账移到复制品之外,但本地 安装中转和瞬时目录锁仍在使用 `dir/.abele-sync` 用于原子文件系统操作。 活动时不要删除它 .

重新打开同一目录、 密钥和状态目录以恢复 。 分类账是 与它的联系; 外部状态也与cononical复制品相连 目录。 拒绝为另一个目录或密钥重用 。 用一对新鲜的 对于不同的复制; 不编辑配置以绕过绑定检查.

节点适配器使用本地 `better-sqlite3`: 安装需要二进制 节点 ABI/ 平面,或者如果不存在预建的二进制,则使用本地构建的工具链. 安装/进口失败并不意味着服务器不兼容.

只有一个过程可能拥有一个复制品. 锁定获取可等待检查 a 上一个所有者; 不删除一个锁以强制另一个写入 。 等着 `close()` 改为 释放SQLite和锁. 中断后重开同一状态以恢复 日记和待写在正常同步前. `RecoveryRequiredError` (代码) `RECOVERY_REQUIRED`)意味着恢复需要注意;其信息没有本地信息 路径或基础错误细节。 以原始状态目录重新打开 。 若为 拒绝寻回,保存文档,并声明调查. 两个都退后 客户端关闭时.

## 同步和交付

`syncOnce()` 返回核心 `SyncReport`数字 : `pull`, (中文(简体) ), `push`, (中文(简体) ), `secondPull`, (中文(简体) ), `collisions`, (中文(简体) ), `deferred`, (中文(简体) ), `joined`。成功并不一定意味着每个传输的文件: 结算文件、所持有的删除和所推迟的更改可能需要再次通过/操作. 同步是双向的.

`start()` 允许监视、事件锁定和回落触发. `pause()` 中断 活动运行并暂停自动触发; 手动同步仍然有效, 除非 授权已经停止。 中断 `syncOnce()` 拒绝方式 `SyncCancelled`, (中文(简体) ), 没有错误事件或离线重试. `resume()` 清除暂停/ 授权停止并提示同步 . `stop()` 等着 进行中的工作并释放出自动资源;在重新启动之前等待. 暂停和授权停止 生存停止/启动. `close()` 也拥有的释放 适配器,为同位素,并永久关闭客户端. 使用 `finally` 财务报告和审定财务报表 处理 SIGINT/ SIGTERM , 如文件夹- 镜像样.

`on(event, listener)` 返回未订阅的函数。 听者同步运行; 抛出例外是孤立的。 处理你自己的反弹.

| 活动 | 数值 |
| --- | --- |
| `status` | 核心状态; 状态闲置、 同步、 下线、 暂停或出错; 已善后错误文本 |
| `synced` | 成功的核心报告 |
| `change` | 核心应用变化 |
| `conflict` | 最后推后合并/复制结果、路径和ID;副本包括冲突路径和ID |
| `error` | 安全同步错误 |
| `revoked` | 一次批准停止,或成功自行撤销 |
| `heldDeletes` | 更改的非空控删除列表 |

应用更改通知可以在崩溃回放时重复. 事件是现场的, 不是一个持久的队列或完全的一次性订阅。 冲突事件涉及 最后的推动响应,不是所有的历史批次。 建设一能消费者 通过重读复制品和通过路径更新衍生记录,而不是 按通知附上一项行动。 与 `list()` 启动到 覆盖丢失的通知。 外部副作用需要自身的持久性, 原子分解;内相集无法活出碰撞.

## 阅读、历史和决定

`replica.list(prefix?)`, (中文(简体) ), `read(path)` 财务报告和审定财务报表 `readText(path)` 读取本地数据, 包括未符号编辑。 列表按排序、递归和字面前缀排列: `Notes/` 选择后代; `Notes` 也匹配 `Notes-old.md`条目 `path`字节 `size`, (中文(简体) ), `mtime`和可选分类账 `fileId`。文本为 UTF-8. 国家道路被排除在外;绝对的、逆向的和反向的路径被拒绝.

`history(path, { limit?, before? }?)` 读取服务器版本. `restore(path, versionId)` 使用引擎的序列还原操作. `trash()` 列出已删除的文件; `restoreDeleted(pathOrId)` 恢复列出的路径 或文件编号。 恢复返回核心承诺结果; 拒绝丢出历史错误 . 之后同步以获取恢复的内容 。 服务器保留和权限适用.

默认删除的守护符有50个删除, 或至少10个构成一个季度 同步条目。 最近的删除数为默认的 15分钟窗口 . `deleteGuard: { count, floor, share, windowMs? }` 超过阈值; `deleteGuard: false` 禁用保护. `heldDeletes()` 列表路径/文件ID对. 将经审查的身份证传递给 `decideDeletes({ kind: "confirm" | "restore", fileIds })`。 。 。 . 确认发送删除; 恢复从活服务器获取缺失的本地文件 复制,不是垃圾。 结果是 `{ decided, report }`。决定开始同步 除非暂停/吸入, 等待同步恢复.

`defer: (wirePath) => boolean` 匹配远程更改而不是写入 他们在当地. `deferred()` 列出分阶段的更改; `applyDeferred(versionIds?)` 通过引擎应用所选版本。 启用所有当前 ID 分阶段更改; 通过经过审查的ID以避免隐形替换。 这是数据 推迟,不是代码批准/执行设施.

`disconnect()` 停止,忘记本地连接状态/证书和关闭, 保存用户文件。 自定义元数据存储需要 `metadataKeys` 财务报告和审定财务报表 `setMeta` 用于完全忘记,否则将丢出 HistoryError(“ 不支持”) . `revoke()` 撤销此连接的服务器令牌并停止同步、 保留 当地州。 自发客户端无法启动/ 恢复; 关闭或断开 分别.

## 错误

关于导出类和代码的分支, 不是消息文本 .

| 类 | 代码 |
| --- | --- |
| 无效的密钥 | 风险 儿童 |
| 不兼容的服务器 | 信息输入服务 |
| 复制配置错误 | 答复 冲突 |
| 同步无效 | 下行( 故意中断; 检查类第一) |
| 同步错误 | 离线、未经许可、其他 |
| 历史错误 | 关闭, 未经授权, 离线, 禁止, 未找到, 未支持, 其他 |

无效的适配器/ 路径可以丢入 TypeError; 生命周期误用可以丢出普通 错误。 有点 `open()` 保留运输和本地文件系统/SQLite/锁故障 此版本的上游错误形状 。 不记录任意错误/ 原因或 连接证书。 SDK事件/历史出错和同步故障被消毒.

## 许可证

仅限GPL-3.0;见LICENSE. 连接此软件包或组合衍生工具 应用程序要求GPLv3遵守,包括适用的源、通知和 许可证义务。 私人修改和使用不需要公布; 仅网络访问无法创建 AGPL 风格的源报价 。 分发他人 即使在私人或商业场合,也仍然承担着GPL的义务.

## 包含注释解析器和类型

任务和说明分析包括:

```js
import { taskFromFrontmatter, noteFromMarkdown } from "@abele/sync-sdk/notes";
const task = taskFromFrontmatter({ groups: ["work"] });
```

使用 `@abele/sync-sdk/core` 财务报告和审定财务报表 `@abele/sync-sdk/protocol` 核心项目 公共SDK API参考的协议类型,包括适配器合同 并解码连接符. 不需要单独的Abele软件包.

核心、协议和节点适配器代码来自 [abele- sync 源码](https://github.com/dudaanton/abele-sync/tree/7f5825017b7079d59b36a69cafe329488b05f9f7)。 。 。 . 见NOTICE和包括上游许可证。 注释解析器从 此仓库 。 需要公开的 YAML 助手声明 `@types/js-yaml`, (中文(简体) ), 被作为附属物列入.

## 常见问题

### @abele/sync-sdk 是什么？

节点客户端 SDK 用连接密钥同步一个文件夹或您自己的存储器, 包括任务和注释解析器 \.

### 如何安装 @abele/sync-sdk？

在项目目录运行 npm install @abele/sync-sdk，或使用 pnpm add / yarn add / bun add。

### @abele/sync-sdk 支持 TypeScript 吗？

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

### @abele/sync-sdk 支持 ESM 还是 CommonJS？

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

### @abele/sync-sdk 需要什么版本的 Node\.js？

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

### @abele/sync-sdk 可以商用吗？

@abele/sync-sdk 使用 GPL-3\.0-only 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @abele/sync-sdk 的下载量有多少？

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

### @abele/sync-sdk 还在维护吗？

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