# @xyo-network/event-kit-node 中文文档 规范地址：https://npmcn.com/package/%40xyo-network/event-kit-node/ 版本：2\.3\.4 npm 元数据更新时间：2026-11-02T22:27:24.107Z 中文译文更新时间：2026-11-02T23:40:59.086Z 软件包许可：LGPL-3\.0-only 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40xyo-network/event-kit-node 原文对照：https://npmcn.com/package/%40xyo-network/event-kit-node/?lang=original 源码仓库：https://github.com/XYOracleNetwork/event-kit ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.4 MB，87 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=26 - 运行依赖：5 个 - peer 依赖：ajv ^8\.20，zod ^4\.6，ethers ^6\.17，async-mutex ^0\.5，@ariestools/sdk ^9\.0，@xyo-network/sdk ^8\.1，@ariestools/actor ^2\.0，@opentelemetry/api ^1\.10，@xyo-network/xl1-sdk ^5\.8，@xyo-network/sdk-protocol ^8\.0，@xyo-network/xl1-protocol ^5\.8，@xyo-network/xl1-statement-graph-sdk ^0\.7，@xyo-network/xl1-statement-graph-engine ^0\.7，@xyo-network/xl1-statement-graph-schemas ^0\.7 - 首次发布：2026-08-20T22:45:33.774Z - 最新版本发布：2026-11-02T22:27:23.939Z - 已发布版本数：22（近 12 个月 22 个） ## 中文简介 Node 26+ Event Kit持久性，握手客户端，和SQLite源代码发布者运行时 ## 安装 ```sh npm install @xyo-network/event-kit-node ``` 也可以使用：`pnpm add @xyo-network/event-kit-node`、`yarn add @xyo-network/event-kit-node`、`bun add @xyo-network/event-kit-node` ## README # `@xyo-network/event-kit-node` Event Kit的Node.js 26+耐久性适配器。存储库是Node 26.9.0： - `createFilesystemCursorStore` -唤醒发布者参与者的发布者光标 - `createFilesystemPublisherOutbox` -持久的pending-wake槽，用于重试稳定性 - `createSqliteWakeReceiver` -原子持久的收件箱/队列在一个私有的FULL/WAL SQLite数据库 - `createSqliteWakeQueue` -独立围栏 `WakeQueue` 在 `node:sqlite` - `createFilesystemWakeQueue` / `createFilesystemWakeInbox` -协调SQLite权限与可检查的JSON投影 - `createSqliteBestEffortInbox` / `createBestEffortSnapshotWorker` -持久有界提示安全/合并和独立快照工作 - `migrateReceiverStore` / `migrateIdOnlyReducerCheckpoint` -显式停止所有者离线迁移和报告 ## 握手的客户 进口 `@xyo-network/event-kit-node/handshake` 第三阶段控制平面 表面。该子路径导出： - 同步的终局重播阅读器和XL1发布组合； - 用于声明、发现、加密的发布者和订阅者客户端 订阅/拨款的发表、质疑、接受和撤销；和 - 文件系统存储重播检查点、突变意图、发布 日志、发布者加密密钥保管和端点质疑决策。 生成的链上握手突变使用调用者提供的16字节 小写十六进制操作ID。 `createFilesystemHandshakeMutationIntentStore` 原子地绑定第一个 请求其精确随机服务/密钥、授予、密文或接受 工件。在咨询可变链之前，精确的重试加载该赢家 状态;在相同作用域的操作ID下更改输入失败关闭。 记录和目录是私有的(`0600`/`0700`）. 发布者服务意图 保留加密私钥，直到可以将其幂等复制到密钥中 拘留。订阅者意图保留密文和请求指纹，而不是 端点或挑战秘密明文。 `createFilesystemFinalizedStatementPublicationJournal` 然后绑定逻辑 声明源、有序对象/附件哈希和精确值 签署的交易。重新启动从最高持久阶段恢复，并且可能 只重播那个证据；它从不重建或重新签署一个模棱两可的 出版。 握手子路径故意不加载唤醒队列、收件箱、 发件箱,或者 `node:sqlite`。干净包装的消费者类型检查并执行它 没有SQLite耦合。有一种不受版本控制的源感知契约。 服务发布要求 `sources` 和 `maxPositionsPerWake`； 订阅 出版要求 `source` 和 `fromPosition`。授权仍然固定 到XL1会话独立于源位置。删除模式后缀， 块范围字段和配置文件选择器没有兼容性别名。 ## 居民出版商 `@xyo-network/event-kit-node/publisher-runtime` 导出SQLite发布器 权限/存储，持久运行时，真正的D-005发现，有界传输， 原生REST网关/数据组合，以及XL1/以太坊/UTC源阅读器。 它使用共享的周期性角色生命周期；CLI拥有进程中断； 提供程序清理和探测。导入模块不会打开数据库； 打开发布者状态加载 `node:sqlite` 明确。 逻辑唤醒创建和挂起的发件箱持久性共同提交。持久的承认 收据、连续发布者游标和发件箱分别清除共同提交 对于每个订阅者。过程死亡和模棱两可的反应重新发送相同的身体 一个新鲜的真正的钱包智威汤逊。发布者进度是准入进度，而不是 完成接收器计算。看到 [runbook](https://npmcn.com/package/docs/RESIDENT_PUBLISHER.md) 对于所有权，加密保管，重试/取消规则，传输限制和 其余的宿主/序列门。 `status().deliveryDiagnostics` 报告固定的故障阶段/原因计数器和 最近收到的HTTP状态和有界的Retry-After延迟。这些计数器 仅覆盖当前进程并在重试成功后存活；两者都不是 遗失通知不计算持久收据。现有的 `failures` 场 保持当前连胜并在匹配确认时清除。畸形的 200/202的内容不算作交付。错误文本和响应体是 排除在诊断之外。 ## 耐久性模型 这个 [2026-10-05补救](https://npmcn.com/package/docs/CODE_REVIEW_REMEDIATION_PLAN_2026-10-05.md) 在作用域唤醒上用一个事务替换拆分身份/队列提交 和令牌绑定，稳定的收据，准确的授权工作，租赁状态和 完成。重复令牌绑定/过期扩展是原子性的。全/细胞膜SQLite 在一个本地主机上协调对象和进程；有限的100毫秒繁忙等待 在未解决的争论中明显失败。重试保留逻辑身份。 文件系统适配器在中使用相同的权限 `receiver.sqlite`。私人 `pending/` 和 `inflight/` JSON文件是投影，仅由 `link` 还有同步目录。他们不决定入场或租赁所有权。 缺失的凸出物可以修复；损坏或不匹配的字节停止处理 并随时准备接受检查。声明验证形状和规范散列 反对承诺的权威。补全将在保持时移除保留的函数体 稳定的身份/收据墓碑；过时的文件无法恢复已完成的工作。 `repairProjections()` 显式扫描活动工作和文件系统引用。 所属目录/文件为 `0700`/`0600`，包含owner、regular-file和symbol - link 检查。不安全的现有保管被拒绝，而不是修改不相关的路径。 发布者游标/发件箱替换仍然是单写入器 `rename`，带文件 以及出版目录同步。读取，解析，状态和同步失败传播； 保留的重试字节/ id不会因为读取失败而被替换。 在日志模式更改之前，将拒绝遗留存储。使用 [脱机迁移手册](https://npmcn.com/package/docs/CODE_REVIEW_RECEIVER_MIGRATION_2026-10-05.md) 在已停止所有者副本上；保留备份、库存和隔离证据。这个 新的源格式故意与旧的编写器和运行时不兼容 没有双读卡器。 ## 队列服务提供商 所有三个提供商都为每个索赔分配了一个新的租赁围栏。 `ack()`/`release()` 自动比较当前条目/状态/令牌。陈腐的或相反的完成 抛出 `StaleWakeLeaseError`； 重复同样的成功操作是惰性的。 经济复苏需要 `recoverInflight({ consumersStopped: true })` 在每一个 消费者共享商店已经停止。断言是一个操作符契约， 不是活体探测器。单独启动不能建立静默。 扩展的共享一致性涵盖了陈旧/重复的完成和后续 保存。独立对象/进程允许竞争，真正的SIGKILL边界， 私有托管和签名HTTP测试对其进行了补充。供应商条款要求 `reopen`/跨编写器支持仍然显式跳过内存。 应用程序效果至少保留一次。栅栏的排队状态和分开制作 外部效果幂等或自动提交效果/检查点在其所有者。 `node:sqlite` 是内建的，所以这不会增加依赖项。它不发射射线 在固定的Node 26.9.0运行时加载时的ExperimentalWarning。 ## 边界 当前的恢复证据包括本地对象/进程和复制的fixture； 不能主机丢失、存储硬件故障、恢复或跨机鉴定。 历史核心5号门的证据仍然局限于它的原始文物。看到 当前检查和测量的性能/保留成本的补救计划。 链上发行商路线图 通过阶段4-7的单个VM；多虚拟机协同部署需要一个 事务性共享存储、租赁和围栏，以及路线图第8阶段。 ## 常见问题 ### @xyo-network/event-kit-node 是什么？ Node 26\+ Event Kit持久性，握手客户端，和SQLite源代码发布者运行时 ### 如何安装 @xyo-network/event-kit-node？ 在项目目录运行 npm install @xyo-network/event-kit-node，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ajv（^8\.20）、zod（^4\.6）、ethers（^6\.17）、async-mutex（^0\.5）、@ariestools/sdk（^9\.0）、@xyo-network/sdk（^8\.1）、@ariestools/actor（^2\.0）、@opentelemetry/api（^1\.10）、@xyo-network/xl1-sdk（^5\.8）、@xyo-network/sdk-protocol（^8\.0）、@xyo-network/xl1-protocol（^5\.8）、@xyo-network/xl1-statement-graph-sdk（^0\.7）、@xyo-network/xl1-statement-graph-engine（^0\.7）、@xyo-network/xl1-statement-graph-schemas（^0\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @xyo-network/event-kit-node 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @xyo-network/event-kit-node 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @xyo-network/event-kit-node 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=26。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @xyo-network/event-kit-node 可以商用吗？ @xyo-network/event-kit-node 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。 ### @xyo-network/event-kit-node 还在维护吗？ 最新版本 2\.3\.4 发布于 2026/11/03（今天）；至今共发布 22 个版本，其中过去 12 个月发布了 22 个；首次发布于 2026/08/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。