# @agenticprimitives/agent-naming 中文文档 规范地址：https://npmcn.com/package/%40agenticprimitives/agent-naming/ 版本：1\.0\.0-alpha\.46 npm 元数据更新时间：2026-10-26T11:48:23.365Z 中文译文更新时间：2026-11-06T06:17:13.241Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40agenticprimitives/agent-naming 原文对照：https://npmcn.com/package/%40agenticprimitives/agent-naming/?lang=original 项目主页：https://agenticprimitives.dev/ 源码仓库：https://github.com/agentictrustlabs/agenticprimitives ## 关键信息（来自 npm 元数据） - 包体积（解压后）：458 kB，90 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：viem ^2\.52\.2，@agenticprimitives/types ^1\.0\.0-alpha\.46，@agenticprimitives/connect-auth ^1\.0\.0-alpha\.46，@agenticprimitives/agent-account ^1\.0\.0-alpha\.46 - 首次发布：2026-05-31T17:13:04.188Z - 最新版本发布：2026-10-26T11:48:20.491Z - 近 30 天下载量：4507（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：45（近 12 个月 45 个） ## 中文简介 代理命名服务SDK:为智能代理打入了分级命名(.me.org.team.svc.workspace.treasury-一个后缀名称是衍生代理类型; spec 346). 拥有语法名称 + 正常化, namehash/ labehash, 记录计划, DNS/A2A 端点 ## 安装 ```sh npm install @agenticprimitives/agent-naming ``` 也可以使用：`pnpm add @agenticprimitives/agent-naming`、`yarn add @agenticprimitives/agent-naming`、`bun add @agenticprimitives/agent-naming` ## README # @ agenticprimitives/ agent-name > 部分 **[代理先导](https://agenticprimitives.dev/)** ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. [开发者工具包](https://github.com/agentictrustlabs/agentic-primitives) • 妇女 [所有软件包](https://agenticprimitives.dev/developers) **名为相. 地址是身份证.** 代理命名正在解决中——GoDaddy启动了代理命名服务,ERC-8004将代理注册放入主网,每个发现堆都需要回答"哪个代理回答这个名字?". 大部分命名系统都取回了依赖性:名称成为了身份,而失去名称(或登记员)意味着失去与它相关的一切. 在这里,每个人,Org,服务代理,和国库是一个犬类 ERC-4337 智能代理地址——和一个 `.agent` 名称是一个可替换的记录指向 _时间_ 该地址([ADR-0010 (英语)](https://npmcn.com/package/docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)) (中文(简体) ). 旋转名称,保留身份. 旋转你的证书,保持名称。 下游没有间断. 部分 [代理原始产品](https://npmcn.com/package/README.md) ——代理经济的信托基底:一个有监护,授权,命名,证书,审计证据的犬类智能代理身份,设计成一个系统. 使用此软件包来解析名称, 如 `alice.agent` 财务报告和审定财务报表 `treasury.acme.agent` 转到智能代理地址,读取打入的服务发现记录(A2A端点,MCP端点,CAIP-10) `nativeId`),并构建对名称管理交易的编码调用。 名称是分级的——狼在自己的子注册下发出子名——正常化是决定性的,可以连锁核查. > **图层 :** 发现——一个命名 **侧** (不是犬科特征——即: `agent-account`) (中文(简体) ). **条形键 :** 智能代理地址 名称决定. ## 使用这个当 - 您需要向前解析 : `alice.agent → 0x…`。 。 。 . - 您需要从智能代理地址到其主名的反向解析度——并进行回转检查,所以一个名字只有在解回同地址时才会被信任. - 您需要输入的记录, 如 `displayName`, (中文(简体) ), `a2aEndpoint`, (中文(简体) ), `mcpEndpoint`, (中文(简体) ), `nativeId`,或 `metadataUri` ——服务发现没有硬码的URL. - 您需要纯粹的呼叫构建者 注册名称, 解析器更新, 主名更新, 或所有者旋转 组成 监管政策仪式. ## 不使用此选项 - 密码仪式或认证流—— `@agenticprimitives/connect-auth`。 。 。 . - 智能账户部署或用户操作- `@agenticprimitives/agent-account`。 。 。 . - 账户安全政策和核准时间安排 - `@agenticprimitives/account-custody`。 。 。 . - 许可薄荷或减量- `@agenticprimitives/delegation`。 。 。 . - MCP/A2A运输接线——演示应用或运行时包. ## 安装 工作空间- 内部;尚未出版. ```bash pnpm add @agenticprimitives/agent-naming ``` ## 60秒快速启动 ```ts import { AgentNamingClient, labelhash, namehash, normalizeAgentName, } from '@agenticprimitives/agent-naming'; normalizeAgentName(' ALICE.AGENT '); // "alice.agent" labelhash('alice'); // 0x... namehash('treasury.acme.agent'); // 0x... const naming = new AgentNamingClient({ rpcUrl: 'https://base-sepolia.example/rpc', chainId: 84532, registry: '0x0000000000000000000000000000000000000001', universalResolver: '0x0000000000000000000000000000000000000002', }); const address = await naming.resolveName('alice.agent'); const primaryName = await naming.reverseResolve('0x0000000000000000000000000000000000000003'); const records = await naming.getRecords('treasury.acme.agent'); ``` ## 怎么不一样 参考点是: **ENS 和不可阻挡域** 两者都非常出色 都围绕着不同的重力中心: - **名相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.** ENS和Untopable将名称视为被奖励的对象;身份在它周围的接合. 在这里,Smart Agent的地址是Canonical的,强制的独特名称被分配到身份靴子上(S[220 第5节](https://npmcn.com/package/specs/220-agent-identity-bootstrap.md))——名称为指针,可替换而不会丧失身份,并 `addr` + 键 `nativeId` 必须参考同一个聪明特工. - **代理本土记录.** 类型上游 `a2aEndpoint`, (中文(简体) ), `mcpEndpoint`, CAIP- 10 (中文(简体) ) `nativeId`,以及一个公共安全的通行证证书摘要——记录一个代理经济实际上解决了,而不是一个TXT免费的. 未知的上游被解码器忽略并被打入编码器拒绝. - **监管的轮换.** 名称所有人轮船作为纯编码的呼叫建造者(`/custody` —— 法定人数和受托人,而不是一个可以被一刀两断的私人钥匙. - **有纪律的读取.** 产品读取使用 `readContract` 仅 -- -- 没有 `eth_getLogs` 步行,没有无声回放([ADR-0012 (英语)](https://npmcn.com/package/docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md), (中文(简体) ), [ADR-0013 (英语)](https://npmcn.com/package/docs/architecture/decisions/0013-no-silent-fallbacks.md)) (中文(简体) ). 反向解析是单一的链上 `reverseResolveString` 读取,然后在信任它之前,先向前转转. 这个 `.agent` TLD是命名协议;一个给定的部署登记册的名称是applayer配置——这个软件包仍然是通用的. ## 主要概念 - **Canonical SA (英语)**: ERC-4337地址必须注明每个名称(`addr`, (中文(简体) ), `nativeId`) (中文(简体) ). 拥有者 `agent-account`而不是这个包裹. - **代理Name**: 一个普通点名 `.agent` (一个面额标签). - **标签/节点**: 一个部分(`treasury`); 递归 `namehash(name)`。 。 。 . - **书记官处/裁定人**: 名称记录(所有者,解析者,父,子注册);为节点打出记录. - **主要名称**:智能代理地址的倒数记录. 见 [`docs/concepts.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/concepts.md)。 。 。 . ## 共同食谱 ```ts import { decodeRecords, encodeRecords, PREDICATE_ID, } from '@agenticprimitives/agent-naming/records'; const encoded = encodeRecords({ addr: '0x0000000000000000000000000000000000000003', agentKind: 'service', // a treasury is a service agent; 'treasury' is a profile subtype displayName: 'Acme Treasury', nativeId: 'eip155:84532:0x0000000000000000000000000000000000000003', }); const decoded = decodeRecords({ strings: { [PREDICATE_ID.displayName]: 'Acme Treasury' }, addresses: { [PREDICATE_ID.addr]: '0x0000000000000000000000000000000000000003' }, bytes32s: {}, }); ``` 更多实例: [`examples/basic.ts`](https://npmcn.com/package/%40agenticprimitives/agent-naming/examples/basic.ts) • 妇女 [`examples/records.ts`](https://npmcn.com/package/%40agenticprimitives/agent-naming/examples/records.ts) • 妇女 [`examples/custody-rotation.ts`](https://npmcn.com/package/%40agenticprimitives/agent-naming/examples/custody-rotation.ts) ## 已发行A2A卡片记录(第347页第8.3节) `atl:cardDigest` (字节32 = 已发行的A2A代理卡的RFC 8785字节中的sha256)和 `atl:cardUri` (仅在 纸牌不在 a2a 主机 `/.well-known/agent-card.json`)是普通的名称-节点记录: `encodeRecords({ cardDigest, cardUri })`时,读回 `resolve()`。核查人获取卡片并比较摘要;记录没有证明 自己来 现有部署人员向 `contracts/script/AddCardPredicates.s.sol`。 。 。 . ## 运行时间支持 纯粹的帮助和记录编码器在浏览器,节点和Workers工作. 客户端使用 `viem` 公开客户端和钱包客户端,并需要RPC URL来进行链读或交易提交. ## 子路径导出 - `@agenticprimitives/agent-naming` ——公共帮手,客户端,ABI,和类型. - `@agenticprimitives/agent-naming/records` ——上游ids和打出的记录编码/解码帮助器. - `@agenticprimitives/agent-naming/custody` ——纯编码调用器,用于名称管理交易. ## 安全变化因素 - 名称正常化是决定性的——平等正常化产生同名的hashes. - 反向解析必须绕行才能被信任 . - 未知的上游被解码器忽略并被打入编码器拒绝. - 原始的通行证证书ID从未被存储——只有一份摘要. - 端点记录是发现提示,不是端点控制的证据. - 产品读取使用 `readContract`; 无 `eth_getLogs` 在热道上([ADR-0012 (英语)](https://npmcn.com/package/docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)) (中文(简体) ). 见 [`docs/security.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/security.md) 财务报告和审定财务报表 [`AUDIT.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/AUDIT.md)。 。 。 . ## 文件地图 - [`docs/concepts.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/concepts.md) ——命名模式和词汇. - [`docs/api.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/api.md) ——人可读公众API指南. - [`docs/security.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/security.md) ——安全态势和变化无常. - [`docs/troubleshooting.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/troubleshooting.md) ——常见错误. - [`docs/migration.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/docs/migration.md) ——版本和移民笔记. - [`CLAUDE.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/CLAUDE.md) ——剂道和防漂. - [`spec.md`](https://npmcn.com/package/%40agenticprimitives/agent-naming/spec.md) ——克能谱指. ## 验证 ```bash pnpm check:agent-naming pnpm check:public-exports pnpm check:forbidden-terms ``` ## 状态 测试网/飞行员准备 生产启动在根部的公开核对表上进行 [`README.md`](https://npmcn.com/package/README.md#status--honest-version) ——包括第三方合同审计和治理关键轮换. 追踪所有安全发现 [`docs/audits/findings.yaml`](https://npmcn.com/package/docs/audits/findings.yaml)。 。 。 . ## 许可证 失败. ## 常见问题 ### @agenticprimitives/agent-naming 是什么？ 代理命名服务SDK:为智能代理打入了分级命名\(\.me\.org\.team\.svc\.workspace\.treasury-一个后缀名称是衍生代理类型; spec 346\)\. 拥有语法名称 \+ 正常化, namehash/ labehash, 记录计划, DNS/A2A 端点 ### 如何安装 @agenticprimitives/agent-naming？ 在项目目录运行 npm install @agenticprimitives/agent-naming，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.52\.2）、@agenticprimitives/types（^1\.0\.0-alpha\.46）、@agenticprimitives/connect-auth（^1\.0\.0-alpha\.46）、@agenticprimitives/agent-account（^1\.0\.0-alpha\.46）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @agenticprimitives/agent-naming 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @agenticprimitives/agent-naming 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @agenticprimitives/agent-naming 可以商用吗？ @agenticprimitives/agent-naming 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @agenticprimitives/agent-naming 的下载量有多少？ 根据 npm 官方下载统计，@agenticprimitives/agent-naming 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,507 次，日均约 150 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @agenticprimitives/agent-naming 还在维护吗？ 最新版本 1\.0\.0-alpha\.46 发布于 2026/10/26（11 天前）；至今共发布 45 个版本，其中过去 12 个月发布了 45 个；首次发布于 2026/06/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。