# @automerge/subduction 中文文档

规范地址：https://npmcn.com/package/%40automerge/subduction/

版本：0\.27\.0
npm 元数据更新时间：2026-11-04T02:07:29.314Z
中文译文更新时间：2026-11-07T07:01:52.231Z
软件包许可：MIT OR Apache-2\.0

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

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

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

- 包体积（解压后）：317 MB，77 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-27T00:33:34.173Z
- 最新版本发布：2026-11-04T02:07:28.600Z
- 近 30 天下载量：3515（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

Wasm/JavaScript subsuccess (浏览器和节点.js)的装订

## 安装

```sh
npm install @automerge/subduction
```

也可以使用：`pnpm add @automerge/subduction`、`yarn add @automerge/subduction`、`bun add @automerge/subduction`

## README

# 债务约束

> \[尖叫声\] 这是提前发布预览 。 它的API非常不稳定. 没有保证。 目前不要用于生产。 使用你自己的风险.

## 平面对象 API

`Subduction` 这是唯一的公共图书馆课。 身份证、摘要和专题 64字符十六键;检查点前缀为24字符十六键. 输入接受任意一个大小写, 不 `0x`;输出总是小写。 集团和 保留签名信封 `Uint8Array`元数据、同步结果和流出事件 属于递归平原对象,不需要 `.free()` 打电话.

```javascript
import {
  Subduction, createMemorySigner, createMemoryStorage,
} from "@automerge/subduction";

const node = new Subduction({
  signer: createMemorySigner(),
  storage: createMemoryStorage(),
});
try {
  await node.storeBatch(treeId, {
    commits: [{ head: commitHash, parents: parentHashes, blob: changeBytes }],
  });
  const results = await node.syncWithAllPeers(treeId, { subscribe: true });
  for (const [peerId, result] of Object.entries(results)) {
    console.log(peerId, result.success, result.stats);
  }
} finally {
  try { await node.close(); } finally { node.free(); }
}
```

数据参数在之前同步解码/复制为自有 Rust 值 计划同步工作。 呼叫者可能重新使用或改变其物体,以及 普通缓冲器一旦返回。 投入既不消耗也不分离; 冻结是可选的。 共有的有效载荷被拒绝。 独立产出 JS记忆,关闭后仍然可用. 服务(储存、签署、政策、, 运输,回调,和取消信号)仍然是活界面.

### 从包装班迁移

这是一个打破的 API 变化; 没有隐含的 遗留- 包装转换 .

| 此前 | 现在 |
| --- | --- |
| `PeerId`, (中文(简体) ), `CommitId`, (中文(简体) ), `SedimentreeId`, (中文(简体) ), `Digest`, (中文(简体) ), `Topic` 构造器 | 十六进制字符串 |
| `Checkpoint.fromBytes(bytes)` | 24个字符十六进制前缀(`commitId.slice(0, 24)` 用于有效十六进制标识) |
| `new MemoryStorage()` | `createMemoryStorage()` |
| `IndexedDbStorage.setup(indexedDB, name)` | `createIndexedDbStorage(indexedDB, name)` |
| `MemorySigner.generate()` 编号 : `.fromBytes(seed)` | `createMemorySigner()` 编号 : `createMemorySigner(seed)` |
| `WebCryptoSigner.setup()` | `createWebCryptoSigner()` |
| `new CommitInput(new LooseCommit(...), blob)` | `{ head, parents, blob }` |
| `new FragmentInput(new Fragment(...), blob)` | `{ head, boundary, checkpoints, blob }` |
| `storeCommit(id, head, parents, blob)` | `storeCommit(id, { head, parents, blob })` |
| `storeBuiltBatch(id, commits, fragments)` 供普通出版物使用 | `storeBatch(id, { commits, fragments })` |
| 预先计算的元数据出版物 | `storeBuiltBatch(id, { commits: [{ metadata, blob }], fragments: [...] })` |
| 位置同步布尔/ 超时 | `{ subscribe, timeoutMilliseconds }` 选项 |
| `PeerResultMap.getResult(peer)` 编号 : `.entries()` | `results[peer]` 编号 : `Object.entries(results)` |
| `Depth.value` | 数字深度 |
| 元数据包 | 记录来源 `getCommits`, (中文(简体) ), `getFragments`,或存储更新流 |
| `AuthenticatedTransport.setup(...)` 接下来 `addConnection(...)` | `node.connectTransport(transport, { expectedPeerId })` |
| 发现运输设置 | `connectTransport` 编号 : `acceptTransport` 与 `{ serviceName }` |

自定义存储执行 接收十六进制ID并签名字节; 加载返回 `{ signed: Uint8Array, blob: Uint8Array }` 记录,不是阶级。 内置 索引 DB 后端保留现有的版本 1 存储、索引、密钥和记录 设置。 它返回的结构对象 `close()`; 存储是呼叫者拥有的 未被节点关闭。 存储被信任以保存本地签名或 先前核实的信封。 重新装入潜入检查编码和blob 协议,但不重新验证签名。 存储回调不是 未核实网络记录的录取路径.

自定义政策、远程头部观察员、电子回调和帧处理器 还收到六分位识别符. `hashMetricOverride` 现在取一个承诺的ID字符串 并返回数字深度。 现有不易倒塌的粗口签注/计量特性合同 仍然需要有效的签名/公用密钥和不投掷的有效深度测量; 这种代表性的改变不会使这些特征变得不合理.

详细的边界设计在 [POJO API.md (英语)](https://npmcn.com/package/%40automerge/POJO_API.md)同步, 授权、注销和部分书面担保保持不变.

## 构建软件包

从寄存器根 :

```sh
nix build .#subduction-js
```

构建和测试 npm 包,包括 `/debug` 变体,并写入 `result/subduction.tgz`。见 [释放](https://npmcn.com/package/%40automerge/RELEASING.md#npm-packages) 用于标记驱动的出版工作流程.

用于在原地开发 `subduction_wasm/dist/`,使用时 `nix develop` 接下来是 `bodge subduction_wasm` 换句话说.

## 运行测试

安装依赖性 :

```
pnpm install
```

安装 Playwright 的浏览器二进制 :

```
pnpm run test:install
```

运行测试 :

```
pnpm test
```

重建并测试公共软件包及其类型脚本声明:

```sh
pnpm run test:pojo
```

这需要一个瓦斯姆启用的 Rust 工具链, 被打包, 建造, TypeScript, 和 a `wasm-bindgen` CLI 匹配 `Cargo.lock`覆盖 Rust 工具链和绑定 使用 `CARGO_TOOLCHAIN` 财务报告和审定财务报表 `WASM_BINDGEN` 如果需要的话。 脚本重建 `dist/`,将消费者与已排放的软件包申报进行打字,并运行 对放出和调试包进行节点测试. 浏览器测试使用相同的 新建公共包装并需要电流 `subduction_cli` (或 `SUBDUCTION_CLI`) (中文(简体) ).

查看 Playwright 报告 :

```
pnpm run test:report
```

## 命名公约

`wasm-bindgen`\- 生成类型所有权规则可能混乱而繁琐, 不同的行为取决于您类型创建的 Wasm 边界的哪一侧。 为了直截了当,我们通过了命名公约:

> \[注\] 内部 Rust 包装器类型前缀为 `Wasm`。 。 。 . 从联署材料中导入的类型前缀为: `Js`。 。 。 .

这些是执行公约,不是公共JavaScript建筑 所需经费。 私人驾驶员内部仍可能使用瓦斯姆包装.

## 与 Chrome DevTools 调试

潜入的瓦斯包可以运载一个平行 `./debug` 保存 DWARF 调试信息 的子路径导出, 允许 Chrome DevTools 中的源级步骤 。 本节适用于: `@automerge/subduction` 但对 `@automerge/sedimentree` 财务报告和审定财务报表 `@automerge/automerge-subduction`。 。 。 .

### 一次性Chrome设置

1.  安装 _C/C++ 开发工具支助(DWARF)_ chrome Web Store 的扩展名。 它处理从Wasm模块读取DWARF部分;wem-bindgen输出使用扩展所构建的同DWARF格式.
2.  在克罗姆,访问 `chrome://flags/#enable-webassembly-debugging` 并启用 _网络大会调试: 启用 DWARF 支持_ 旗帜。 重新启动浏览器 .
3.  在装入您 Wasm 捆绑的页面上打开 DevTools, 去齿轮图标 ~ _实验_,确认 _网络大会调试: 启用 DWARF 支持_ 被选中.

### 构建调试变量

从工作空间根 :

```
bodge subduction_wasm          # one crate
bodge:all                      # all four _wasm crates
```

两者 `bodge` 财务报告和审定财务报表 `bodge:all` 通过 `--debug-profile wasm-debug` 改为 `wasm-bodge`,运行一个秒 `cargo build` 下划线 `[profile.wasm-debug]` 在工作空间中声明的配置文件 `Cargo.toml`生成 `dist/` 树上包含两种释放文物(在通常路径下) _财务报告和审定财务报表_ 调试文物( 前缀为 `debug-` 下级 `esm/` 编号 : `cjs/`附加时 `*-debug.wasm` 独立,加 `iife/debug.js`) (中文(简体) ).

### 正在完成调试捆绑

您的下游应用程序进口 `./debug` 子路径 :

```javascript
import { init, /* ... */ } from "@automerge/subduction/debug";
```

对于 Chrome DevTools 定位 DWARF 符号, 它必须在它能够读取的 URL 中获取 Wasm 二进制 。 这排除了内线-基础64路径. 使用 :

-   **Bundler 路径( 建议)**: 导入 `@automerge/subduction/debug` 在捆绑机(Vite/Webpack/Rollup)下. 这个 `browser` 条件确定为 `./dist/esm/debug-bundler.js`,代表瓦斯姆装入 捆绑者的本地 `.wasm` 导入 —— 将二进制作为DevTools可以从中读取的可取资产.
-   **手动获取**: 服务 `./dist/subduction-debug.wasm` 直接通话 `initSync(bytes)` 从 `@automerge/subduction/slim` (通过自动闪电).

### 源路径解析度

DWARF从编译主机嵌入了绝对路径(例如. `/home/expede/Documents/Code/subduction/subduction_core/src/…`) (中文(简体) ). 要步入工作,DevTools需要将路径映射到磁盘上的文件. 两种方式:

-   _首选_:在Subsuccess的检出中打开一页的 DevTools, 这样绝对的 DWARF 路径就解决了 .
-   _或者说_: 在 C/C++ 中 DevTools 支持扩展的选项页面, 在本地的检出中添加一个路径替代映射 DWARF 路径 .

如果 DevTools 显示的话 "`<file>: file not found`" 在源面板中,你需要设置映射.

### 交易被烤进档案

`[profile.wasm-debug]` (见工作空间) `Cargo.toml` 完整附加说明的定义) `release` 并调制这些旋钮:

-   `opt-level = 1` ——大多数本地人保持可见,行步感觉自然;优化后足以进行互动调试.
-   `lto = "thin"` ——避免重起重的相克率内延 `lto = "fat"` 那会崩溃的堆栈框架.
-   `debug = "limited"` ——将行表,类型信息,以及大多数本地数据保持为~1⁄2,DWARF大小为~ `debug = "full"`. 实证潜入- 土地为~29 MiB生/~6 MiB gziped (相对于~3 MiB/723 KiB放出).
-   `debug-assertions = true` 财务报告和审定财务报表 `overflow-checks = true` 捕捉虫 释放的建筑 不会绊倒。 如果复制一个只释放的代码路径,则在分支上禁用这些.
-   `strip = "none"` 四点 `_wasm` 特别是箱子, 压倒发布配置文件 `strip = "debuginfo"` (否则会抹去妇女资源中心).
-   自动合并和 `sedimentree_core` 被钉入 `opt-level = 2` 防止他们的散动/穿透-重力内衣在浏览器中爬行。 如果你需要通过 _这些_ 箱子的内脏,评论一下相应的 `[profile.wasm-debug.package.*]` 工作空间中的覆盖 `Cargo.toml`。 。 。 .

### 检查 DWARF 存在

```
wasm-tools objdump ./subduction_wasm/dist/subduction-debug.wasm | grep debug_
```

应列出 `.debug_info`, (中文(简体) ), `.debug_line`, (中文(简体) ), `.debug_str`, (中文(简体) ), `.debug_abbrev`还有朋友 如果这些失踪,则DWARF被剥去,很可能是偶然的 `wasm-opt` 运行,或 `strip = "debuginfo"` 从发布配置文件中漏出.

## 常见问题

### @automerge/subduction 是什么？

Wasm/JavaScript subsuccess \(浏览器和节点\.js\)的装订

### 如何安装 @automerge/subduction？

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

### @automerge/subduction 支持 TypeScript 吗？

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

### @automerge/subduction 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @automerge/subduction 可以商用吗？

@automerge/subduction 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @automerge/subduction 的下载量有多少？

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

### @automerge/subduction 还在维护吗？

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