# @atcute/lexicon-doc 中文文档

规范地址：https://npmcn.com/package/%40atcute/lexicon-doc/

版本：3\.1\.0
npm 元数据更新时间：2026-08-19T07:34:57.943Z
中文译文更新时间：2026-11-07T01:51:04.411Z
软件包许可：0BSD

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

原始 npm 页面：https://www.npmjs.com/package/%40atcute/lexicon-doc
原文对照：https://npmcn.com/package/%40atcute/lexicon-doc/?lang=original
源码仓库：https://tangled.org/did:plc:pljn5qch4tgadongtc7i6qij

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

- 包体积（解压后）：318 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：5 个
- peer 依赖：@atcute/lexicons ^2\.0\.0
- 首次发布：2025-05-14T13:24:38.172Z
- 最新版本发布：2026-08-19T07:34:57.779Z
- 近 30 天下载量：16843（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 18 个）

## 中文简介

atproto lexicon 文档的类型定义和计划

## 安装

```sh
npm install @atcute/lexicon-doc
```

也可以使用：`pnpm add @atcute/lexicon-doc`、`yarn add @atcute/lexicon-doc`、`bun add @atcute/lexicon-doc`

## README

# @ atcute/ lexicon- doc

解析和作者 atproto lexicon 文档.

```sh
npm install @atcute/lexicon-doc
```

## 使用量

### 解析词典文档

```ts
import { findExternalReferences, lexiconDoc } from '@atcute/lexicon-doc';
import * as v from 'valibot';

const rawDoc = {
    lexicon: 1,
    id: 'com.example.post',
    defs: {
        main: {
            type: 'record',
            key: 'tid',
            record: {
                type: 'object',
                required: ['text', 'createdAt', 'author'],
                properties: {
                    text: { type: 'string', maxLength: 300 },
                    createdAt: { type: 'string', format: 'datetime' },
                    replyTo: { type: 'ref', ref: 'com.atproto.repo.strongRef' },
                },
            },
        },
    },
};

const doc = v.parse(lexiconDoc, rawDoc);
//    ^? LexiconDoc

const refs = findExternalReferences(doc);
//    ^? Set<string> { 'com.atproto.repo.strongRef' }
```

## 构建器 API

此软件包提供构建器功能, 便于编写词汇文档

```ts
import { document, record, object, string, required, build } from '@atcute/lexicon-doc/builder';

const post = document({
    id: 'com.example.post',
    defs: {
        main: record({
            key: 'tid',
            record: object({
                properties: {
                    text: required(string({ maxLength: 300 })),
                    createdAt: required(string({ format: 'datetime' })),
                },
            }),
        }),
    },
});

const lexicons = build({ documents: [post] });
//    ^? { 'com.example.post': { lexicon: 1, ... } }
```

## aPI 验证

此软件包提供了远程计划验证功能

```ts
import { RecordValidator } from '@atcute/lexicon-doc/validations';

// lexicon documents retrieved from the network or loaded from disk
const docs = {
    'app.bsky.feed.post': {
        lexicon: 1,
        id: 'app.bsky.feed.post',
        defs: {
            main: {
                type: 'record',
                record: {
                    type: 'object',
                    required: ['text', 'createdAt'],
                    properties: {
                        text: { type: 'string', maxLength: 300 },
                        createdAt: { type: 'string', format: 'datetime' },
                    },
                },
            },
        },
    },
};

const validator = new RecordValidator(docs, 'app.bsky.feed.post');

validator.parse({
    key: '3m6bkzurm4c7w',
    object: {
        $type: 'app.bsky.feed.post',
        text: 'hello world',
        createdAt: '2024-01-01T00:00:00.000Z',
    },
});
```

## JSON 计划

此软件包还提供了用于编写词典文档的JSON schemas, 添加一个 `$schema` 属性改为 您的文档 :

```json
{
    "$schema": "https://unpkg.com/@atcute/lexicon-doc/schema/lexicon-doc.schema.json",
    "lexicon": 1,
    "id": "com.example.link",
    "defs": {
        "main": {
            "type": "record",
            "description": "a link submission",
            "key": "tid",
            "record": {
                "type": "object",
                "required": ["url", "createdAt"],
                "properties": {
                    "title": { "type": "string", "maxLength": 300 },
                    "url": { "type": "string", "format": "uri" },
                    "createdAt": { "type": "string", "format": "datetime" }
                }
            }
        }
    }
}
```

## 常见问题

### @atcute/lexicon-doc 是什么？

atproto lexicon 文档的类型定义和计划

### 如何安装 @atcute/lexicon-doc？

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

### @atcute/lexicon-doc 支持 TypeScript 吗？

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

### @atcute/lexicon-doc 支持 ESM 还是 CommonJS？

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

### @atcute/lexicon-doc 可以商用吗？

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

### @atcute/lexicon-doc 的下载量有多少？

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

### @atcute/lexicon-doc 还在维护吗？

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