# @gadicc/watchbound-node 中文文档

规范地址：https://npmcn.com/package/%40gadicc/watchbound-node/

版本：2\.1\.2
npm 元数据更新时间：2026-08-17T08:53:02.354Z
中文译文更新时间：2026-11-15T21:57:52.627Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：75.2 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.15\.0
- 运行依赖：0 个
- 首次发布：2026-07-23T19:12:45.791Z
- 最新版本发布：2026-08-17T08:53:01.832Z
- 近 30 天下载量：2197（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

用于 Watchbound 的架构中立本地加载器

## 安装

```sh
npm install @gadicc/watchbound-node
```

也可以使用：`pnpm add @gadicc/watchbound-node`、`yarn add @gadicc/watchbound-node`、`bun add @gadicc/watchbound-node`

## README

# 监视

_一个保守的Linux递归目录监视器,具有明确的覆盖范围,限定资源,并加入了生命周期保障._

[![npm](https://img.shields.io/npm/v/watchbound)](https://www.npmjs.com/package/watchbound) [![JSR](https://jsr.io/badges/@gadicc/watchbound)](https://jsr.io/@gadicc/watchbound) [![JSR score](https://jsr.io/badges/@gadicc/watchbound/score)](https://jsr.io/@gadicc/watchbound) [![CI](https://github.com/gadicc/watchbound/actions/workflows/ci.yml/badge.svg)](https://github.com/gadicc/watchbound/actions/workflows/ci.yml) [![Release qualification](https://github.com/gadicc/watchbound/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/gadicc/watchbound/actions/workflows/release.yml?query=branch%3Amain) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40gadicc/watchbound-node/LICENSE.txt)

版权 (c)由加迪·科恩出品的2026. [麻省理工学院](https://npmcn.com/package/%40gadicc/watchbound-node/LICENSE.txt)。 。 。 .

## 介绍

Watchbound是一款实验性Linux-First的监视器,直接建立在不摄取上. 它报告保守路径的无效性,并使文件系统覆盖的完整,部分或不确定成为每个结果的一部分. 它从未默默地将资源压力或事件损失变成对完全保险的索赔.

软件包可从 [无](https://www.npmjs.com/package/watchbound) 财务报告和审定财务报表 [日 尔](https://jsr.io/@gadicc/watchbound). 版本历史和可用性来自登记册元数据, [Git 标签](https://github.com/gadicc/watchbound/tags),以及 [GitHub 发布](https://github.com/gadicc/watchbound/releases)。 。 。 .

检查的来源可能比这些不可改变的释放要早。 在使用本分行描述的API之前,验证已安装的包的申报和出口是否包含.

## 目录

-   [为什么守望](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-why-watchbound)
-   [安装和启动](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-install-and-start)
-   [支持矩阵](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-support-matrix)
-   [基准](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-benchmarks)
-   [与 Parcel 比较](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-compare-with-parcel)
-   [了解合同](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-understand-the-contract)
-   [项目状况和文件](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-project-status-and-documentation)
-   [捐款](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-contributing)
-   [AI 代理技能](https://npmcn.com/package/%40gadicc/watchbound-node/#readme-ai-agent-skill)

## 为什么守望

这些消费者在保守的无效状态后可以重新扫描

-   **真实报道**:每个机构、批量和回收结果报告 `complete`,说明理由 `partial`,或说明理由 `uncertain` 覆盖范围
-   **受压**: 监视预算, 批量大小, 本地输出队列, 以及 JavaScript 回调录被限制和可观察到
-   **递归性正确性**: 在可观察转换之前扫描已移动的目录
-   **明确追回**:溢出,地貌种族,回压,和根置换都有打入状态和有政策倾向的恢复路径
-   **加入生命周期**: 撤销企业将回滚自有资源 `dispose()` 在承诺达成后 防止召回

API 报告路径无效, 而非精确的文件系统日记 。 当覆盖范围不确定时,重新划定所报告的边界,而不是推断缺失 `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`,或重命名事件.

## 安装和启动

用您的软件包管理器安装节点包 :

```sh
pnpm add watchbound
```

在启用监视器之前, 给主机和根配置合格 。 将订阅保留到规定的寿命,然后在关闭时加入处理:

```ts
import { qualifyRoot, subscribe } from "watchbound";

const root = process.cwd();
const qualification = qualifyRoot(root);

if (qualification.state !== "qualified") {
  throw new Error(
    `Watchbound root is ${qualification.state}: ${qualification.reasons.join(", ")}`,
  );
}

const subscription = await subscribe(root, (batch) => {
  console.log(batch.coverage.state, batch.invalidatedPaths);
}, {
  excludedDirectoryNames: [".git", "node_modules"],
  observedExcludedPaths: [".git"],
});

await new Promise<void>((resolve) => process.once("SIGINT", () => resolve()));
await subscription.dispose();
```

每一个订阅者都会订购和序列化召回. 打开 `uncertain` 覆盖范围、重新划定安全报告边界或使用适用的回收作业。 打开 `partial` 覆盖,露出持续的盲点或保持倒数;一次性重新扫描不能使未来的覆盖完成. 见 [API和生命周期合同](https://npmcn.com/package/%40gadicc/watchbound-node/docs/api-lifecycle.md) 替换、取消、核对、恢复根部和停用.

## 支持矩阵

最高层的发行资格证上报了现场 `main` 工作流程。 对于发布候选人来说,该工作流程将所有本土目标的全面连续整合(CI)矩阵称为"CI". GitHub 暴露出每个矩阵单元格中一个工作流程徽章而不是一个徽章,因此每个检查都低于保留的确切承诺资格记录的链接.

| 目标 | 原生软件包 | 运行时间基线 | 状态 |
| --- | --- | --- | --: |
| GNU/ Linux x64 | `@gadicc/watchbound-node-linux-x64-gnu` | 节点 `>=18.15.0`,节点-API 6+,内核 5.15+,glibc 2.35+ | [获支持](https://npmcn.com/package/%40gadicc/watchbound-node/docs/support-matrix.md#source-candidate-target-contract) |
| GNU/Linux ARM64 | `@gadicc/watchbound-node-linux-arm64-gnu` | 节点 `>=18.15.0`,节点-API 6+,内核 5.15+,glibc 2.35+ | [获支持](https://npmcn.com/package/%40gadicc/watchbound-node/docs/support-matrix.md#source-candidate-target-contract) |
| GNU/ Linux ARMv7 硬浮点数 | `@gadicc/watchbound-node-linux-arm-gnueabihf` | 节点 `>=18.15.0`,节点-API 6+,ARMv7-A 硬浮小endian glibc,内核 5.15+ | [获支持](https://npmcn.com/package/%40gadicc/watchbound-node/docs/support-matrix.md#source-candidate-target-contract) |

得到支持的本土目标仍然刻意缩小。 检测到的WSL和具有公认集装箱证据的环境不能合格。 Musl,软浮或未知的32位ARM ABIs, Big-endian ARM,以及非Linux平台被关闭.

节点支持不是一个被测试的版本允许列表 。 JavaScript API要求Node 18.15.0或更新,原生的adon要求进程Node-API 6或更新,而精确的CI版本是证据点. 装载器没有节点上行绑定,但保留了精确的目标选择和所有平台,ARM ABI,libc,内核,ELF,文摘,元数据,以及能力检查. 见 [节点和电子相容性政策](https://npmcn.com/package/%40gadicc/watchbound-node/docs/runtime-compatibility.md)。 。 。 .

CI还锻炼了被钉住的Ubuntu,Debian,Fedora,Arch x64,openSUSE,Nix,内核5.15,代号Node和Electron的释放,一个ARMv7的QEMU用户电能循环道,以及系统QEMU下的一个真正的ARMHF 5.15内核. ARMv7的执行证据被效仿,没有提出本土硬件或履约索赔。 这个 [全面支助和资格表](https://npmcn.com/package/%40gadicc/watchbound-node/docs/support-matrix.md) 记录准确的车道、建筑、文物和促销证据; 不可改变的登记和发布记录指明某一已公布的版本包含哪些内容.

装入相容的本地软件包不合格主机或根 。 打电话 `qualifyRoot(root)` 和要求 `state === "qualified"`; 数据 [运行时间资格合同](https://npmcn.com/package/%40gadicc/watchbound-node/docs/runtime-qualification.md) 解释每一个被接受和拒绝的国家.

## 基准

保留的业绩系列是历史可行性证据,而不是关于目前来源业绩的索赔。 它比较了一个记录的Watchbound构建,精确配置的 Codex Linux JavaScript 帮助器,以及精确的 `@parcel/watcher` 2.5.6 强制使用其不充电后端.

每个单元格的中位数订阅时间以毫秒为单位 `[min–max]` 通过7起tmpfs审判:

| 树和相 | 监视 | 编码 Java 脚本 | 帕塞尔 2.5.6 |
| --- | --- | --- | --: |
| 1 001个目录,冷 | 7.20 (中文(简体) ) `[3.47–8.20]` | 38.44 (简体中文) `[28.77–47.00]` | 5.58 联合国 `[4.21–9.01]` |
| 1 001个目录,温暖 | 7.54 联合国 `[3.25–8.30]` | 37.25 联合国 `[31.37–42.07]` | 8.58 联合国 `[5.88–9.68]` |
| 10 001个目录,冷 | 32.31 国家 `[31.55–44.39]` | 273.05 (中文(简体) ) `[249.56–319.78]` | 49.11 联合国 `[45.61–52.74]` |
| 10 001个目录,温暖 | 36.59 (中文(简体) ) `[32.76–40.04]` | 239.37 联合国 `[184.88–380.16]` | 47.42 (中文(简体) ) `[43.51–50.65]` |

在主机和树形上,Watchbound的10 001个指令起动中位数低于Parcel的23%至34%,使用的是较少增量的居民设置大小(RSS)。 1,001-导冷范围相重叠,因此系列没有建立小树取胜. 来源早于后期运行时间,交付,排除,恢复工作,tmpfs不预测持久文件系统或应用性能.

单独的最终合规报告记录了30起适用的、经过观察的审判。 CI运行有限度的基准烟来捕捉功能回落,但其时间不作为性能证据来推广.

读取 [全部基准结果](https://npmcn.com/package/%40gadicc/watchbound-node/docs/benchmark-results.md) 包括记忆、爆破、处置、文物散装、东道国和警告。 这个 [方法](https://npmcn.com/package/%40gadicc/watchbound-node/docs/benchmark-methodology.md) 定义只通过聚合、旋转适配器顺序、静宿准备以及强制溢出的安全边界.

## 与 Parcel 比较

当Parcel的公共合同足够时,它仍然是更好的违约。 它是成熟的,跨平台的,预建的,并暴露出打出的事件和历史快照查询. 监视瞄准一个更窄的 Linux 使用案例 更强大的资源、损失和生命周期语义.

| 需求 | 监视 | `@parcel/watcher` 2.5.6 联合国 |
| --- | --- | --- |
| 平台 | 合格的 GNU/Linux x64, ARM64, 以及精确的 ARMv7 硬浮 | 广泛的跨平台预建覆盖 |
| 事件模式 | 保守的无效路径 | 混凝土 `create`, (中文(简体) ), `update`,以及 `delete` 事件 |
| 保险和损失 | 明确完整、部分和不确定状态 | 无公共报道状态 |
| 限制和压力 | 公共监视限制、 限定队列和会计 | 没有公共活动监视或后压状态 |
| 不适用情况 | 精确字节初始政策和原子活性替换 | 订阅时间路径和 glob 忽略 |
| 恢复 | 手动和有限度的选入自动调节 | 没有公共和解行动 |
| 处置 | 同上,有权力加入,以后不再召回 | 自动同步 `unsubscribe()` 没有同样的公共担保 |

比较范围为Parcel的公用API,再现了Linux在2.5.6. 这不是每个Parcel后端、版本或工作量的说法。 见 [正确性和能力调查结果](https://npmcn.com/package/%40gadicc/watchbound-node/docs/conformance-findings.md) 用于源的归属和复制情景.

## 了解合同

Watchbound的中央不变量是保守的报道:详细的路径可能会倒塌到根无效,但丢失的细节从未被报道为完整.

| 覆盖范围 | 含义 | 消费者行动 |
| --- | --- | --- |
| `complete` | 观察者可以说明所覆盖的地貌 并交付无效 | 正常处理无效文件 |
| `partial` | 已知资源或权限限制未查看的左侧目录 | 将未发现状态视为不可用或更改限制 |
| `uncertain` | 过度流量、地貌变化、根重置或消费者压力可能已失去细节 | 重新扫描或援引适用的回收行动 |

土生土长的加通运行在节点或电能过程内部. 文件系统 traversal和引擎交易从 JavaScript 线程中运行出,但模块加载,选项验证,状态访问,和回调没有. 慢回调创建有边框,订阅-局部后压;独立JavaScript进展需要单独的Worker环境.

订阅选项支持逻辑表限,一个全流程的本地表预算,精确的排除,只取消建制,限定批次,以及选择自动对账. 批次回调收到一个 `AbortSignal` 财务报告和审定财务报表 `stop()` 请求时 `dispose()` 加入本地清理和任何已允许的召回.

读取 [结构决定记录](https://npmcn.com/package/%40gadicc/watchbound-node/docs/architecture.md), (中文(简体) ), [节点绑定设计](https://npmcn.com/package/%40gadicc/watchbound-node/docs/node-binding.md), (中文(简体) ), [结构错误合同](https://npmcn.com/package/%40gadicc/watchbound-node/docs/error-contract.md),以及 [安全和路径威胁模式](https://npmcn.com/package/%40gadicc/watchbound-node/docs/security-threat-model.md) 完全的语义.

## 项目状况和文件

Watchbound仍然是Linux的第一实验项目. Rust引擎拥有文件系统语义;节点-API绑定会翻译表示和生命周期;JavaScript包提供公共包装. Git等消费者政策忽略了规则,UI行为,逻辑工作空间映射留在引擎外.

来源显示使用开发占位符,并保持隐私,以防止意外出版. 控制释放树实现了登记包和版本。 这个 [维修政策](https://npmcn.com/package/%40gadicc/watchbound-node/docs/maintenance-policy.md), (中文(简体) ), [本地分娩合同](https://npmcn.com/package/%40gadicc/watchbound-node/docs/native-delivery.md),以及 [发布运行本](https://npmcn.com/package/%40gadicc/watchbound-node/docs/releasing.md) 界定这些界限.

使用 [文档索引](https://npmcn.com/package/%40gadicc/watchbound-node/docs/README.md) 导航架构、API、资质、基准、包装、证据和决定记录.

## 捐款

见 [捐款额](https://npmcn.com/package/%40gadicc/watchbound-node/CONTRIBUTING.md) 先决条件、储存库布局、试验驱动的工作流程、要求检查、基准安全、数据包文件变化和约定.

## AI 代理技能

此寄存器包括 [与技能相匹配的代理技能](https://npmcn.com/package/%40gadicc/watchbound-node/skills/watchbound/SKILL.md) 包括包件整合、覆盖、生命周期、恢复和贡献者指导。 为兼容编码代理安装它 :

```sh
npx skills add gadicc/watchbound
```

## 常见问题

### @gadicc/watchbound-node 是什么？

用于 Watchbound 的架构中立本地加载器

### 如何安装 @gadicc/watchbound-node？

在项目目录运行 npm install @gadicc/watchbound-node，或使用 pnpm add / yarn add / bun add。

### @gadicc/watchbound-node 支持 TypeScript 吗？

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

### @gadicc/watchbound-node 支持 ESM 还是 CommonJS？

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

### @gadicc/watchbound-node 需要什么版本的 Node\.js？

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

### @gadicc/watchbound-node 可以商用吗？

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

### @gadicc/watchbound-node 的下载量有多少？

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

### @gadicc/watchbound-node 还在维护吗？

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