# @agenticprimitives/agent-resolution 中文文档

规范地址：https://npmcn.com/package/%40agenticprimitives/agent-resolution/

版本：0\.0\.0-alpha\.21
npm 元数据更新时间：2026-10-26T11:06:30.923Z
中文译文更新时间：2026-11-06T11:44:31.593Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agenticprimitives/agent-resolution
原文对照：https://npmcn.com/package/%40agenticprimitives/agent-resolution/?lang=original
项目主页：https://agenticprimitives.dev/
源码仓库：https://github.com/agentictrustlabs/agenticprimitives

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

- 包体积（解压后）：302 kB，96 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@agenticprimitives/types ^1\.0\.0-alpha\.45
- 首次发布：2026-08-03T02:53:29.018Z
- 最新版本发布：2026-10-26T11:06:30.601Z
- 近 30 天下载量：3366（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

提供者中立的代理解析原始:代理解析政策,署名"代理解析"(Agent Service Publication)并有反回滚核查,私人解析赠款,连接邀请,受众投影,和分辨率提供者端口. 苏鲁地

## 安装

```sh
npm install @agenticprimitives/agent-resolution
```

也可以使用：`pnpm add @agenticprimitives/agent-resolution`、`yarn add @agenticprimitives/agent-resolution`、`bun add @agenticprimitives/agent-resolution`

## README

# @ agenticprimitives/ agent- 解析

> 部分 **[代理先导](https://agenticprimitives.dev/)** ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. [开发者工具包](https://github.com/agentictrustlabs/agentic-primitives) • 妇女 [所有软件包](https://agenticprimitives.dev/developers)

**每个特工都有犬科特征. 取名可选. 公开上市是可选的。 入境 可处理性是可选的。 授权的私人分辨率是一等能力.**

用于回答的提供者中立原始 _"愿这个政党发现如何找到这个代理人 现在在哪里?"_ 问题和问题之间有一道硬墙 _"这个派对能用吗?"_

谱: `[specs/338](https://github.com/agentictrustlabs/agenticprimitives/blob/master/specs/338-private-agent-resolution-and-service-publication.md)` • 妇女 理论: [ADR-0056 (英语)](https://github.com/agentictrustlabs/agenticprimitives/blob/master/docs/architecture/decisions/0056-resolution-is-not-authority-private-agent-resolution.md)

* * *

## 规则

```
A resolution grant answers:      "May this party DISCOVER how to reach this agent?"
It NEVER answers:                "May this party USE this agent?"
```

成功的解析给你一个结束点和一个经过验证的同级身份. 仍须 整个链条,在源头重运行:

```
delegation ∩ entitlement ∩ tool/action policy ∩ exact invocation proof ∩ revocation ∩ audit
```

决议是 **四个正统关切** 与 **监护** ("谁签名"),, **录取** (“允许这些字节输入”),和 **权力** ("该校长做什么"). A 类 _对_ 一个是永远 (单位:千美元) _对_ 到另一个.

## 四个独立层面

"无名"=没有只有公用标签. 清单、分辨率和入境是分别模拟的.

| 姿态 | 名称 | 列名 | 决议 | 入境 |
| --- | --- | --- | --- | --- |
| 公共商业代理人 | `public` | `public` | `public` | `delegation-required` |
| 公共名称、保护细节 | `public` | `public` | `authenticated` | `delegation-required` |
| 私人伙伴代理人 | `private-label` | `none` | `invitation` | `known-peer` |
| 对等金库代理 | `private-label` | `none` | `pairwise` | `delegation-required` |
| 未命名的内部工人 | `none` | `none` | `invitation` | `known-peer` |
| 临时直接代理 | `none` | `none` | `direct` | `delegation-required` |
| 外部工人的背景 | `none` | `none` | `none` | `outbound-only` |

```ts
import { discoveryPolicyFromPreset, validateDiscoveryPolicy } from '@agenticprimitives/agent-resolution';

const policy = discoveryPolicyFromPreset('private-partner');
validateDiscoveryPolicy(policy); // [] — combinations that cannot be enforced are rejected
```

每一条路都决定了同样的犬科特征: `eip155:<chainId>:<SmartAgentAddress>`。 。 。 .

## 工作流程——A代理达到无名金库(代理B)

设想: **A探员** (电话:SA for a person/org) **B探员** (财务服务SA)结束 A2A. B已经 **无公开的 ANS 名称** (单位:千美元)`naming: none`, (中文(简体) ), `listing: none`) (中文(简体) ). 可达到性是邀请/ 私人赠与的解决方案——不是公共标签.

**A2A URL来源于:** 这是 **没有** 由私人解决者发明 **没有** 看着 由名字开始。 这是一块有签名的地 `AgentServicePublicationV1`数字 :

`publication.surfaces[]` + 与 `protocol: 'a2a'` → **`uri`** (例如:. `https://xyz.example/a2a/v1`) (中文(简体) ).

解决者 **承认** 爱丽丝的赠款和 **选择** b所有者预先署名的出版物 保险库( r)`selectPresignedPublication` ——选择,永远不编辑). 爱丽丝提取URI **之后** `verifyPublication` 在她身边.

### 图表

**1\. 概念流动** - 无名A-财务代理B(下文各处使用的术语):

![Nameless private resolution flow — Agent A to treasury Agent B](https://npmcn.com/package/%40agenticprimitives/agent-resolution/docs/nameless-private-resolution-flow.png)

_代理A-无名国库 B. Vault持有签名出版物(A2A) `uri` 内 `surfaces[]`, (中文(简体) ), 受主题限制的赠款,出版当局。 步骤:发放赠款-邀请 (单位:千美元)`initialPublication` +会合) → 第拨号或解析器刷新 (单位:千美元)`selectPresignedPublication`\+ A2A+ 代表团。 解脱者从不伪造终点._

**2\. 地方建筑** 同样的术语 单列工人:

![Local architecture — apps mapped to nameless resolution terms](https://npmcn.com/package/%40agenticprimitives/agent-resolution/docs/local-architecture-app-interaction.png)

_`demo-web-pro` 编号 : `demo-sso-next` = A探员; `demo-resolver` `:8795` = 私人溶剂; `demo-publications` `:8796` = 酒吧商店; `demo-a2a` `:8787` =B's A2A主机(URI in publishing). 可选 `demo-edge`。步骤匹配图1。 现场金库仍可使用已知的 URL + 授权; 私人决心是平行的Ring-1路径._

| 步骤 | 什么动作 | A2A端点? |
| --- | --- | --- |
| 1个 | B个问题 `PrivateResolutionGrantV1` (受A项约束) | 否——赠款=可 _发现_ |
| 2个 | A级邀请 = **初始出版物** +赠款+会议 | **对** - URI已经在里面了 `initialPublication.surfaces[]` |
| (单位:千美元) | 第一次连接: 在当地核实该出版物 | 来自已核实出版物的URI( 无解析器 hop) |
| 页:1 | 刷新:A 解析器 `selectPresignedPublication` - 核实 | **对** - 从URI出自 **选定出版物** `surfaces[]`逻辑 |
| 页:1 | A2A 任务 + 授权 + 应享权利 + 政策 | 使用,而不是解析 |

**无名** =没有公开标签. **出版当局** = 结束点/会话键旋转为操作 发布,而不是监护仪式. **代表团** = URL 后让 A 引用金库技能 已经知道.

```mermaid
sequenceDiagram
  autonumber
  participant B as Agent B treasury SA
  participant Vault as B owner vault
  participant R as Private resolver
  participant A as Agent A
  participant A2A as B A2A host<br/>xyz…/a2a/v1

  B->>Vault: Store signed AgentServicePublicationV1<br/>surfaces: [{protocol:a2a, uri}]
  B->>Vault: Issue PrivateResolutionGrantV1 subject=A
  B-->>A: Invitation = initialPublication + grant + rendezvous

  Note over A: Resolve — endpoint is in the publication
  A->>A: verifyPublication(initialPublication)
  A->>A: a2aUrl = surfaces.find(p=>p.protocol==='a2a').uri

  opt Endpoint moved — same grant
    A->>R: Present grant + PoP
    R->>Vault: Admit + selectPresignedPublication
    R-->>A: Pre-signed publication (includes new uri)
    A->>A: verifyPublication → read surfaces[].uri again
  end

  A->>A2A: Open channel to a2aUrl
  A->>A2A: Task + delegation (other packages)
  alt Authority OK
    A2A-->>A: Result
  else Resolution grant only
    A2A-->>A: Denied — resolution ≠ use
  end
```

### 本地应用程序-术语-工人地图

| 概念术语 | 本地应用程序 |
| --- | --- |
| 代理应用程序 | `demo-web-pro`; 邀请检查 `demo-sso-next` `/visibility` |
| 代理 B A2A 主机 | `demo-a2a` `:8787` —— 说 `/api/a2a`, (中文(简体) ), `A2aTaskDO` |
| 私人解析器 | `demo-resolver` `:8795` —— 说 `/v1/private/{challenge,resolve}` |
| B金库(演示站) | `demo-publications` `:8796` —— 说 `/v1/publications` |
| A2A 对 `uri` | 内部出版物 `surfaces[]` ——例如. `http://127.0.0.1:8787/api/a2a` |
| 可选边缘 | `demo-edge` —— 说 `/api/a2a/<handle>` |
| 使用( 未解析) | 代表团大门进入 `demo-a2a` |

## 工作序列——作为 Ring-1 分辨率提供者的 DNTLS

DNTLS为 **没有** a 依赖性。 环一号 `AgentResolutionProvider` (单位:千美元)`method: 'dntls'`(a) 地图a 记录 `AgentServicePublicationV1`· ; `createComposedResolver` 验证SA装订(Spec 338 §18). 命名空间成员资格可以是 **政策上游**从不给钱. **双向绑定 所需经费.** 仅凭DNTLS就永远不会给予身份、授权、MCP/A2A许可、应享权利或监护权.

```mermaid
sequenceDiagram
  autonumber
  participant D as DNTLS resolver<br/>(external)
  participant Adapt as dntls provider<br/>(Ring-1)
  participant AP as createComposedResolver
  actor A as Agent A
  participant A2A as B A2A host

  A->>AP: resolve({ kind:'external', method:'dntls', identifier })
  AP->>Adapt: resolve(reference, context)
  Adapt->>D: Resolve name / commitment
  D-->>Adapt: Service Record + proof
  Adapt->>Adapt: Map → AgentServicePublicationV1
  Adapt-->>AP: UnverifiedResolutionBundleV1
  AP->>AP: verifyPublication + SA↔DNTLS binding<br/>+ authorityCheck + continuity
  alt Fail
    AP-->>A: resolution failure
  else OK
    AP-->>A: VerifiedAgentResolutionV1<br/>(reachability only)
  end
  A->>A2A: Open surface URI + AP delegation
  A2A->>A2A: delegation ∩ entitlement ∩ policy
  alt Authority OK
    A2A-->>A: Result + receipt
  else Resolution-only
    A2A-->>A: Denied — resolution ≠ use
  end
```

插图适配器( 端口为真实; DNTLS 客户端/ 线程为外部而未发运) :

```ts
import {
  createComposedResolver,
  type AgentResolutionProvider,
  type AgentServicePublicationV1,
} from '@agenticprimitives/agent-resolution';

// Ring-1: map DNTLS Service Record → AgentServicePublicationV1
// (agentId, channelId, sequence, surfaces[].uri/protocol, transportKeyBinding,
//  publishedBy, publicationAuthorityRef, digest, proofs[] — then ERC-1271 sign)
declare function mapDntlsRecord(record: unknown): AgentServicePublicationV1;
declare const externalDntlsClient: { resolve(id: string): Promise<{ record: unknown; proof: unknown }> };

const dntlsProvider: AgentResolutionProvider = {
  method: 'dntls',
  supports: (ref) => ref.kind === 'external' && ref.method === 'dntls',
  async resolve(ref, _ctx) {
    if (ref.kind !== 'external') throw new Error('unsupported');
    const { record, proof } = await externalDntlsClient.resolve(ref.identifier);
    return {
      method: 'dntls',
      referenceKind: 'external',
      publication: mapDntlsRecord(record),
      providerEvidence: [proof],
      servedAt: new Date().toISOString(),
    };
  },
};

const resolve = createComposedResolver({
  providers: [dntlsProvider],
  verifier: publicClient,
  // authorityCheck should also require AP facet → DNTLS commitment (bidirectional)
  authorityCheck,
  minAssurance: 'signed-publication',
});

const result = await resolve(
  { kind: 'external', method: 'dntls', identifier: 'treasury.ops.acme.dntls' },
  { requester: 'eip155:84532:0xaaa…', now: new Date().toISOString() },
  'eip155:84532:0xbbb…',
);
// result.ok ⇒ VerifiedAgentResolutionV1 — still no spend / tool permission
```

全面审计: [`dntls-comparison.md`](https://npmcn.com/package/docs/architecture/dntls-comparison.md)。 。 。 .

## 一个散列证明 _未修改_它不能证明 _当前_。 。 。 .

一张签名的卡证明没有人篡改快照——而不是证明它仍然有效。 所以每个 出版物带有单调 `sequence`, (中文(简体) ), `previousDigest`, (中文(简体) ), `status`,以及 `expiresAt`。 。 。 . 核查失败(回滚、模棱两可、过期、未经授权的出版商、失踪) 端点控制证明,出窗运输键:

```ts
import { verifyPublication } from '@agenticprimitives/agent-resolution';

const result = await verifyPublication(publication, {
  expectedAgentId: 'eip155:84532:0xacme…',
  now: new Date().toISOString(),
  verifier: publicClient,          // any { verifyHash } — a viem PublicClient fits
  authorityCheck,                  // "was this publisher allowed to publish for this agent?"
  known: continuity,               // what we already accepted on this channel
  requireEndpointProof: true,
  maxExposure: 'private',
});

if (!result.ok) {
  // Precise codes for YOUR logs; result.failures[].wireCode for anything you return to a caller.
  if (result.freshness.conflict) escalate('publisher equivocation — possible key compromise');
}
```

平等——按同样顺序有效签署的两份出版物——是: _报告_不仅仅是 拒绝。 这是出版社关键折中的证据,而不是瞬间的错误.

### 旋转是便宜的; 身份永远不会移动

端点变化、运输键旋转、区域故障、协议起落架和提供者迁移 所有重排时间 `sequence + 1`。 。 。 . **不再发放补助,卡通代理代号不变.**

## 私人解决赠款,而非私人姓名

私人盐 _名称_ 拒绝(低调的秘密,名字变为负载)。 赠款为 不透明地高通力(`apd1_…`),受援方:

| 模式 | 使用 |
| --- | --- |
| `subject-bound` _(默认)_ | 介绍人证明SA拥有主题——副本对他人无用 |
| `pairwise` | 每项关系的不同赠款/预测/历史 |
| `bearer-bootstrap` | 短时间直到接收者有SA |

```ts
const admission = await admitGrantPresentation(presentation, deps, {
  resolverAudience: 'https://resolve.acme.example/v1/private',
});
admission.projectionProfile; // 'partner' — what may be DISCLOSED, never invoked
```

电线拒绝全部使用 `resolution_denied` (不计数词);精确代码保留在本地.

## 启动、解析器、存储

邀请 = 初始公布 + 赠款 + 会合 + 预期装订(在终点没有重新邀请) 旋转)。 奥尔格会合只显示存在私人解析服务——可替换,不 不得伪造目标单位或批准使用. `findOverDisclosure` 捕获过度披露.

**所有者金库** (授权):酒吧,赠款,撤销,别名. **解析器金库** (仅限: 关键赠款指数、非收入、预算——从来不是任何重要内容的唯一副本.

```ts
const digest = await deriveGrantDigest(grantId, resolverIndexSecret); // HMAC; 32-byte secret
```

## 范围

**拥有 :** · 出版物核查 · 新鲜度 · 赠款 · 邀请 · 预测 o 提供者端口. **没有 :** 运输、存储、时钟、自动识别、命名、目录、搜索、, 剖面图,表面目录。 环-0 (`types` ; ANS /会合 / DNTLS / Did 是 Ring-1 .

## 安装

```bash
pnpm add @agenticprimitives/agent-resolution
```

## 许可证

麻省理工学院

## 常见问题

### @agenticprimitives/agent-resolution 是什么？

提供者中立的代理解析原始:代理解析政策,署名"代理解析"\(Agent Service Publication\)并有反回滚核查,私人解析赠款,连接邀请,受众投影,和分辨率提供者端口\. 苏鲁地

### 如何安装 @agenticprimitives/agent-resolution？

在项目目录运行 npm install @agenticprimitives/agent-resolution，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@agenticprimitives/types（^1\.0\.0-alpha\.45）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agenticprimitives/agent-resolution 支持 TypeScript 吗？

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

### @agenticprimitives/agent-resolution 支持 ESM 还是 CommonJS？

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

### @agenticprimitives/agent-resolution 可以商用吗？

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

### @agenticprimitives/agent-resolution 的下载量有多少？

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

### @agenticprimitives/agent-resolution 还在维护吗？

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