# @atcute/identity 中文文档

规范地址：https://npmcn.com/package/%40atcute/identity/

版本：2\.0\.2
npm 元数据更新时间：2026-07-16T00:10:06.803Z
中文译文更新时间：2026-11-07T01:49:28.133Z
软件包许可：0BSD

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

原始 npm 页面：https://www.npmjs.com/package/%40atcute/identity
原文对照：https://npmcn.com/package/%40atcute/identity/?lang=original
源码仓库：https://github.com/mary-ext/atcute

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

- 包体积（解压后）：28.9 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@atcute/lexicons ^2\.0\.0
- 首次发布：2025-03-13T09:36:17.902Z
- 最新版本发布：2026-07-16T00:10:06.611Z
- 近 30 天下载量：404427（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 7 个）

## 中文简介

atproto 处理、 DDs 和 DD 文档的语法、类型定义和计划

## 安装

```sh
npm install @atcute/identity
```

也可以使用：`pnpm add @atcute/identity`、`yarn add @atcute/identity`、`bun add @atcute/identity`

## README

# @ tcute/ 身份

类型、计划以及使用AT 协议身份的公用事业.

```sh
npm install @atcute/identity
```

在AT协议中,用户由 [已经](https://www.w3.org/TR/did-core/) (权力下放) (原始内容存档于2012-10-12) (中文(简体) ). 此软件包提供了与 DIDs 和 DID 文档合作的工具 - 文档 描述用户的身份,包括其手柄、PDS位置和密码密钥.

用于解析手柄和手柄的,参见 `@atcute/identity-resolver`。 。 。 .

## 使用量

### 检查已完成的类型

AT 协议支持两种DD方法: `did:plc` 财务报告和审定财务报表 `did:web`。使用类型守护检查哪个 dDE 方法的使用 :

```ts
import { isPlcDid, isWebDid, isAtprotoDid } from '@atcute/identity';

const did = 'did:plc:z72i7hdynmk6r22z27h6tvur';

if (isPlcDid(did)) {
    // did:plc identifier
    console.log('PLC DID');
}

if (isWebDid(did)) {
    // did:web identifier (general, includes custom paths)
    console.log('Web DID');
}

if (isAtprotoDid(did)) {
    // either did:plc or atproto-compatible did:web
    console.log('AT Protocol DID');
}
```

`isAtprotoDid` 检查AT 协议中有效的文件 - 不包括已做的: 网络标识符 带有自定义路径, atproto 不支持.

### 提取 DDE 方法

```ts
import { extractDidMethod } from '@atcute/identity';

const method = extractDidMethod('did:plc:z72i7hdynmk6r22z27h6tvur');
// -> "plc"
```

### 与 did: web 合作

将一个已完成的: web 标识符转换到其已执行的文档 URL :

```ts
import { webDidToDocumentUrl, normalizeWebDid } from '@atcute/identity';

// simple domain
const url = webDidToDocumentUrl('did:web:example.com');
// -> URL { href: "https://example.com/.well-known/did.json" }

// with path
const url2 = webDidToDocumentUrl('did:web:example.com:users:alice');
// -> URL { href: "https://example.com/users/alice/did.json" }

// normalize for comparison
const normalized = normalizeWebDid('did:web:EXAMPLE.COM');
// -> "did:web:example.com"
```

### 读取已读文档

一旦您有 DD 文档( 从解析器或 API) , 请使用工具提取信息 函数:

```ts
import {
    getPdsEndpoint,
    getAtprotoHandle,
    getAtprotoVerificationMaterial,
    getLabelerEndpoint,
} from '@atcute/identity';
import type { DidDocument } from '@atcute/identity';

const doc: DidDocument = {
    '@context': ['https://www.w3.org/ns/did/v1'],
    id: 'did:plc:z72i7hdynmk6r22z27h6tvur',
    alsoKnownAs: ['at://bsky.app'],
    verificationMethod: [
        {
            id: 'did:plc:z72i7hdynmk6r22z27h6tvur#atproto',
            type: 'Multikey',
            controller: 'did:plc:z72i7hdynmk6r22z27h6tvur',
            publicKeyMultibase: 'zDnaek...',
        },
    ],
    service: [
        {
            id: '#atproto_pds',
            type: 'AtprotoPersonalDataServer',
            serviceEndpoint: 'https://morel.us-east.host.bsky.network',
        },
    ],
};

// get the user's PDS URL
const pds = getPdsEndpoint(doc);
// -> "https://morel.us-east.host.bsky.network"

// get the user's handle
const handle = getAtprotoHandle(doc);
// -> "bsky.app"

// get the signing key material
const key = getAtprotoVerificationMaterial(doc);
// -> { type: "Multikey", publicKeyMultibase: "zDnaek..." }
```

### 服务端点助手

从 DCD 文档中提取特定服务端点 :

```ts
import {
    getPdsEndpoint,
    getLabelerEndpoint,
    getBlueskyChatEndpoint,
    getBlueskyFeedgenEndpoint,
    getBlueskyNotificationEndpoint,
    getAtprotoServiceEndpoint,
} from '@atcute/identity';

// standard helpers for common services
const pds = getPdsEndpoint(doc); // #atproto_pds
const labeler = getLabelerEndpoint(doc); // #atproto_labeler
const chat = getBlueskyChatEndpoint(doc); // #bsky_chat
const feedgen = getBlueskyFeedgenEndpoint(doc); // #bsky_fg
const notif = getBlueskyNotificationEndpoint(doc); // #bsky_notif

// or use the generic helper for custom services
const custom = getAtprotoServiceEndpoint(doc, {
    id: '#my_service',
    type: 'MyServiceType', // optional type filter
});
```

### 正在验证已执行的文档

使用验证计划检查一个 DD 文档是否配置良好 :

```ts
import { defs } from '@atcute/identity';
import * as v from 'valibot';

const result = v.safeParse(defs.didDocument, unknownData);
if (result.success) {
    // result.output is a validated DidDocument
    console.log(result.output.id);
} else {
    // validation failed
    console.error('invalid DID document', result.issues);
}
```

计划验证:

-   需要的字段(`@context`, (中文(简体) ), `id`(中文(简体) )
-   执行字符串格式
-   核查方法结构和关键格式
-   服务端点 URL
-   数组中没有重复的条目

### 类型定义

dOD 文档结构的软件包导出类型Script :

```ts
import type { DidDocument, VerificationMethod, Service } from '@atcute/identity';

// DidDocument - the full DID document
// VerificationMethod - a verification method entry
// Service - a service endpoint entry
```

## 常见问题

### @atcute/identity 是什么？

atproto 处理、 DDs 和 DD 文档的语法、类型定义和计划

### 如何安装 @atcute/identity？

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

### @atcute/identity 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/atcute\_\_identity 是否存在。

### @atcute/identity 支持 ESM 还是 CommonJS？

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

### @atcute/identity 可以商用吗？

@atcute/identity 使用 0BSD 许可。几乎没有限制：可自由使用、修改和分发，连保留版权声明也不要求。以上为概括，不构成法律意见，请以许可原文为准。

### @atcute/identity 的下载量有多少？

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

### @atcute/identity 还在维护吗？

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