# @atcute/lex-cli 中文文档

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

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

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

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

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

- 包体积（解压后）：116 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：10 个
- peer 依赖：prettier ^3\.8\.4
- 首次发布：2024-08-18T04:16:49.268Z
- 最新版本发布：2026-08-19T07:35:00.017Z
- 近 30 天下载量：15450（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 19 个）

## 中文简介

cli 生成类型定义的工具

## 安装

```sh
npm install @atcute/lex-cli
```

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

## README

# @ atcute/ lex- cli

从词典文档中生成 TypeScript 计划.

```sh
npm install @atcute/lex-cli
```

## 快速开始

创建配置文件,用于指导工具查找词汇文档的位置 将生成的 TypeScript 计划放入其中:

```ts
// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
    },
});
```

然后运行工具( 它自动查找) `lex.config.js` 或者说 `lex.config.ts`:

```
npm exec lex-cli generate
```

## 使用类型脚本编写词典

而不是将词汇表写为 JSON 文件, 你可以在程序上使用 构建器函数来自 `@atcute/lexicon-doc/builder`。 。 。 .

```ts
// file: lexicons-src/com/example/bookmark.ts
import { array, document, object, record, required, string } from '@atcute/lexicon-doc/builder';

export default document({
    id: 'com.example.bookmark',
    defs: {
        main: record({
            key: 'tid',
            description: 'a saved link to come back to later',
            record: object({
                properties: {
                    subject: required(string({ format: 'uri' })),
                    createdAt: required(string({ format: 'datetime' })),
                    tags: array({ items: string(), description: 'tags for organizing bookmarks' }),
                },
            }),
        }),
    },
});
```

更新您的配置以指向 TypeScript 文件 :

```ts
// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons-src/**/*.ts'],
        outdir: 'src/lexicons/',
    },
});
```

### 向 JSON 导出词典

如果您需要实际的 JSON 词汇文档(例如用于发布或共享),请配置 导出命令 :

```ts
export default defineLexiconConfig({
    generate: {
        files: ['lexicons-src/**/*.ts'],
        outdir: 'src/lexicons/',
    },
    export: {
        outdir: 'lexicons/',
        clean: true,
    },
});
```

然后运行 :

```
npm exec lex-cli export
```

## 绘制词典

您可以从其他来源调取词汇文件.

### git 来源

从 git 寄存器中取出词典 :

```ts
// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
    },
    pull: {
        outdir: 'lexicons/',
        clean: true,
        sources: [
            {
                type: 'git',
                remote: 'https://github.com/bluesky-social/atproto.git',
                ref: 'main',
                pattern: ['lexicons/**/*.json'],
            },
        ],
    },
});
```

### 原生地来源

从AT协议网络直接拉出词典.

```ts
export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
    },
    pull: {
        outdir: 'lexicons/',
        sources: [
            {
                type: 'atproto',
                mode: 'nsids',
                nsids: ['app.bsky.feed.post', 'app.bsky.actor.profile'],
            },
            {
                type: 'atproto',
                mode: 'authority',
                authority: 'atproto-lexicons.bsky.social',
                pattern: ['com.atproto.*'], // optional
            },
        ],
    },
});
```

### 运行拉动命令

将词典拉入磁盘,然后从中生成类型 :

```
npm exec lex-cli pull
npm exec lex-cli generate
```

## 发布您的计划

如果你正在将生成的策略包装成可出版的库,请添加 `atcute:lexicons` 字段 给你的包裹 json 它允许其他工程自动发现和导入您的计划 没有手动配置.

```json
{
    "name": "@example/my-schemas",
    "atcute:lexicons": {
        "mappings": {
            "com.example.*": {
                "type": "namespace",
                "path": "./types/{{nsid_remainder}}"
            }
        }
    }
}
```

页:1 `path` 字段支持多个模板扩展:

-   `.` 或者说 `./` 开始时用软件包名称替换(例如, `./types/foo` 变成 `@example/my-schemas/types/foo`,或 `.` 变成 `@example/my-schemas`(中文(简体) )
-   `{{nsid}}` - 完整的NSID 有点被鞭打所取代(例如, `com/example/foo/bar`(中文(简体) )
-   `{{nsid_prefix}}` - 通配符前的部分(例如, `com/example`(中文(简体) )
-   `{{nsid_remainder}}` - 前缀后的部分(例如, `foo/bar`(中文(简体) )

## 外部参考资料

当您的词典从您配置的文件以外的命名空间引用类型时, 您需要 配置这些引用是如何解决的 .

例如,如果您的词典引用了另一个命名空间的某个类型:

```jsonc
// file: lexdocs/tools/ozone/team/defs.json
{
    "lexicon": 1,
    "id": "tools.ozone.team.defs",
    "defs": {
        "member": {
            "type": "object",
            "required": ["did", "role"],
            "properties": {
                "profile": {
                    "type": "ref",
                    "ref": "app.bsky.actor.defs#profileViewDetailed",
                    //     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                    //     not covered by any of our included files
                },
            },
        },
    },
}
```

解决外部引用的最简单方法是 `imports` 带有软件包的阵列 提供 `atcute:lexicons` 元数据 :

```ts
// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
        imports: ['@atcute/atproto', '@atcute/bluesky'],
    },
});
```

cLI 将自动从每个软件包中发现命名空间映射 `atcute:lexicons` (原始内容存档于2018-03-21). field in their package.json.

对于没有元数据的软件包,或者当您需要更精细的导入分辨率控制时, 使用该 `mappings` 替换配置 :

```ts
// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
        mappings: [
            {
                nsid: ['com.atproto.*'],
                imports: (nsid) => {
                    const specifier = nsid.slice('com.atproto.'.length).replaceAll('.', '/');
                    return { type: 'namespace', from: `@atcute/atproto/types/${specifier}` };
                },
            },
            {
                nsid: ['app.bsky.*'],
                imports: (nsid) => {
                    const specifier = nsid.slice('app.bsky.'.length).replaceAll('.', '/');
                    return { type: 'namespace', from: `@atcute/bluesky/types/app/${specifier}` };
                },
            },
        ],
    },
});
```

## 常见问题

### @atcute/lex-cli 是什么？

cli 生成类型定义的工具

### 如何安装 @atcute/lex-cli？

在项目目录运行 npm install @atcute/lex-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 lex-cli，可以用 npx lex-cli 直接运行。

### @atcute/lex-cli 支持 TypeScript 吗？

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

### @atcute/lex-cli 支持 ESM 还是 CommonJS？

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

### @atcute/lex-cli 可以商用吗？

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

### @atcute/lex-cli 的下载量有多少？

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

### @atcute/lex-cli 还在维护吗？

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