# @agentcontextdistributionprotocol/acdp 中文文档

规范地址：https://npmcn.com/package/%40agentcontextdistributionprotocol/acdp/

版本：0\.21\.4
npm 元数据更新时间：2026-11-07T04:53:09.893Z
中文译文更新时间：2026-11-06T15:16:10.658Z
软件包许可：MIT OR Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40agentcontextdistributionprotocol/acdp
原文对照：https://npmcn.com/package/%40agentcontextdistributionprotocol/acdp/?lang=original
项目主页：https://github.com/agentcontextdistributionprotocol/acdp-rs/tree/main/bindings/acdp-node
源码仓库：https://github.com/agentcontextdistributionprotocol/acdp-rs

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

- 包体积（解压后）：83.6 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-06-08T16:35:23.083Z
- 最新版本发布：2026-11-07T04:53:09.574Z
- 近 30 天下载量：2930（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

代理上下文分布协议-节点.js SDK

## 安装

```sh
npm install @agentcontextdistributionprotocol/acdp
```

也可以使用：`pnpm add @agentcontextdistributionprotocol/acdp`、`yarn add @agentcontextdistributionprotocol/acdp`、`bun add @agentcontextdistributionprotocol/acdp`

## README

# acdp——节点.js SDK

紧紧的NAPI - rs 绑起 [`acdp`](https://crates.io/crates/acdp) 鲁斯特图书馆. 执行生产者和消费者方面关于 代理上下文分发协议——0.1.0-0.0. 最后线加 RFC-ACDP-0016 外部锚;参见 spec's [版本矩阵](https://github.com/agentcontextdistributionprotocol/agentcontextdistributionprotocol/blob/main/docs/version-matrix.md) 确切地说 哪个协议行每个发布工具。 HTTP被故意留给 呼叫者,把这个配给 `fetch` 编号 : `undici` 用于运输.

软件包以同一版本发布 [`acdp`](https://crates.io/crates/acdp) 货箱.

## 安装

```bash
npm install @agentcontextdistributionprotocol/acdp
```

为macOS(x64/arm64)和Linux出版预建的本地二进制 (x64/arm64-gnu);加载器包在安装时选择正确的一个.

要求数 **22号节点或更新** (单位:千美元)`engines.node: ">=22"`; 节点 20 是 后被降入0.15.1级. CI测试节点22和24.

## 安装( 开发)

`package-lock.json` 已执行; 使用 `npm ci` (如CI所做的) 精确安装 包括准确的 `@napi-rs/cli` 版本——它失败 而不是默默地重新解决 `package.json` 锁文件不同意.

```bash
npm ci                       # installs @napi-rs/cli from the lockfile
npm run build:debug          # produces index.js + acdp.<platform>.node
node --test tests/*.mjs      # in-process unit tests, no HTTP
```

## 构建释放二进制

```bash
npm run build                # release mode (LTO + strip)
```

## 快速启动

```javascript
import { AcdpProducer, AcdpVerifier } from '@agentcontextdistributionprotocol/acdp';

const producer = AcdpProducer.generate(
  'did:web:agents.example.com:my-agent',
  'did:web:agents.example.com:my-agent#key-1',
);

const raw = producer.buildPublishRequest({
  title: 'Q1 snapshot',
  contextType: 'data_snapshot',
  summary: 'Quarter-end inventory',
});

// POST `raw` (the JSON string) to your registry's /contexts endpoint.
// On retrieve:
const body = (await response.json()).body;
AcdpVerifier.verifyContentHash(JSON.stringify(body), body.content_hash);
AcdpVerifier.verifySignature(
  pubKeyB64,                  // resolved from the producer's did:web doc
  body.signature.value,
  body.content_hash,
);
```

### 校验取回的正文

`ctx_id` 登记并列入RFC-ACDP-0001§5.7排除条款 设定,所以它被剥去之前 `content_hash` 两者都是计算出来的 重新计算上面, 或制作人的签名覆盖它。 没有 明确比较,登记处可为任何其他有效签字机构服务 由同一生产商根据 `ctx_id` 您想要的 URL, 以及每个 上面的检查还是会过去的 打电话 `verifyCtxIdBinding` 缩小这一差距 (RFC-ACDP-0006 第4.1节,步骤7,规范):

```javascript
// Argument order matters: `bodyJson` carries the *served* ctx_id,
// `expectedCtxId` is the one you requested.
AcdpVerifier.verifyCtxIdBinding(JSON.stringify(body), requestedCtxId);
```

像其他人一样 `AcdpVerifier` 布尔表面, 此返回 `true` 打开 成功和失败——永远不会 `false` 这样啊 `if (AcdpVerifier.verifyCtxIdBinding(...))` 守卫一个不可能的分行 已经到达.

### 核实登记收据

`verifyReceipt` (RFC-ACDP-0010 第8节) `bodyJson` 作为 **所需经费** 第二个论点——它约束收据 `lineage_id`, (中文(简体) ), `origin_registry`,以及 `created_at` (第8节) 步骤 3 :

```javascript
AcdpVerifier.verifyReceipt(
  receiptJson,            // the `registry_receipt` object, as received
  bodyJson,                // the accompanying `body`, same retrieval
  registryPublicKeyB64,    // resolved via AcdpDid.webToUrl + fetch
  expectedCtxId,           // the ctx_id you actually requested
  recomputedBodyHash,      // YOUR OWN verifyContentHash result — never
                            // the body's echoed content_hash field
  producerKeyFingerprint,  // fingerprint of the resolved producer key
);
```

扔出一个畸形 `bodyJson` (主机输入)或身体/接收不匹配 (核查失败)同样——从未 `false`还有两张支票 HOST的义务,因为两者都不需要身体:服务机构 装订( a)`receipt.registry_did` 必须等于您实际的权威 从那里取来,然后用你所递归的躯干来补偿.

## 核查表面

`AcdpVerifier` 涵盖除基本内容外的全部核查表面 以上: 身份约束(`verifyCtxIdBinding`,参见 [校验取回的正文](https://npmcn.com/package/%40agentcontextdistributionprotocol/acdp/#readme-verifying-a-retrieved-body) 页:1, 离线 `did:key` 核查`verifyBodyOffline`, (中文(简体) ), `verifyPublishRequestOffline`),登记收据 (单位:千美元)`verifyReceipt(receiptJson, bodyJson, registryPublicKeyB64, expectedCtxId, recomputedBodyHash, producerKeyFingerprint)`, (中文(简体) ), 见 [核实登记收据](https://npmcn.com/package/%40agentcontextdistributionprotocol/acdp/#readme-verifying-a-registry-receipt) 以上; `verifyLineageHeadReceipt`),透明度记录(`verifyLogCheckpoint`, (中文(简体) ), `verifyLogInclusion`, (中文(简体) ), `verifyLogConsistency`),生命周期事件 (单位:千美元)`verifyLifecycleEvent`),键撤销(`parseKeyRevocation`, (中文(简体) ), `classifyUnderRevocation`和见证的盟誓 (单位:千美元)`buildWitnessCosignature`, (中文(简体) ), `verifyWitnessCosignature`, (中文(简体) ), `evaluateWitnessQuorum`) (中文(简体) ). `AcdpP256Producer`, (中文(简体) ), `AcdpDid`, (中文(简体) ), `AcdpDidDocument`, (中文(简体) ), `AcdpCanonicalizer`, (中文(简体) ), `AcdpMerkle`,以及 `AcdpSsrfPolicy` 也被导出.

## 设计规则

-   **JSON穿越FFI边界.** 每一种方法都接受并返回 JSON弦——从来不是Rust型,你也不会是JS级的 发送前必须序列化.
-   **(原始内容存档于2017-09-21). Crypto in Rust, HTTP in JS.** 键生成器,JCS + SHA-256活塞, Ed25519 签字,签字核查在下面 `acdp` 货箱。 运输、退货和观察都是你的.
-   **`AcdpProducer` 存储了32字节种子.** 鲁斯特 `SigningKey` 实值 `ZeroizeOnDrop` 没有 `Clone`,所以绑定重建签名 键.
-   **黄金矢量等同.** `golden content_hash + signature match sig-001` 刺穿JS边 `content_hash` 财务报告和审定财务报表 `signature.value` 反光谱 `sig-001` 固定- 相同的常数 Rust 套房声称。 两边的漂移就是协议中断.

## 公众表面

出口类别和方法清单(及其数量) [`bindings/interop/expected_surface.json`](https://github.com/agentcontextdistributionprotocol/acdp-rs/blob/main/bindings/interop/expected_surface.json), (中文(简体) ), 通过对等测试执行此软件包 .

## 常见问题

### @agentcontextdistributionprotocol/acdp 是什么？

代理上下文分布协议-节点\.js SDK

### 如何安装 @agentcontextdistributionprotocol/acdp？

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

### @agentcontextdistributionprotocol/acdp 支持 TypeScript 吗？

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

### @agentcontextdistributionprotocol/acdp 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @agentcontextdistributionprotocol/acdp 需要什么版本的 Node\.js？

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

### @agentcontextdistributionprotocol/acdp 可以商用吗？

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

### @agentcontextdistributionprotocol/acdp 的下载量有多少？

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

### @agentcontextdistributionprotocol/acdp 还在维护吗？

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