# @collective-intelligence/schema-codegen 中文文档

规范地址：https://npmcn.com/package/%40collective-intelligence/schema-codegen/

版本：0\.3\.2
npm 元数据更新时间：2026-11-15T10:13:05.584Z
中文译文更新时间：2026-11-16T01:59:34.176Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40collective-intelligence/schema-codegen
原文对照：https://npmcn.com/package/%40collective-intelligence/schema-codegen/?lang=original

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

- 包体积（解压后）：64.7 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-28T00:08:46.654Z
- 最新版本发布：2026-11-15T10:13:05.392Z
- 近 30 天下载量：1962（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

从2020-12 Draft JSON Schema文档到TypeScript, Zod和Effect Schema源的纯生成器.

## 安装

```sh
npm install @collective-intelligence/schema-codegen
```

也可以使用：`pnpm add @collective-intelligence/schema-codegen`、`yarn add @collective-intelligence/schema-codegen`、`bun add @collective-intelligence/schema-codegen`

## README

# `@collective-intelligence/schema-codegen`

从2020-12 Draft JSON Schema文档到TypeScript源的纯生成器. 它没有运行时间依赖。 它没有IO文件,也没有CLI. 呼叫通过 文档并写入返回的文本。 这个 `ci package codegen` 命令 `@collective-intelligence/cli` 是一揽子声明的呼叫者;参见 [CLI 读取](https://npmcn.com/package/%40collective-intelligence/cli/README.md#generate-typescript-schemas)。 。 。 .

目标:

-   `types`: 普通类型脚本类型.
-   `zod`: Zod schemas和推断出的类型.
-   `effect`数字 : `effect/Schema` 计划与类型.

## 生成模块

软件包导出 `generateSchemaModule` 及其类型。 功能是纯的 永远不要扔。 它返回一个目标文件的源文本 .

```ts
import { generateSchemaModule } from "@collective-intelligence/schema-codegen"

const result = generateSchemaModule({
  target: "zod",
  header: { packageFqn: "acme.billing", packageVersion: "1.0.0" },
  schemas: [
    {
      name: "acme.billing.invoice#input",
      document: { type: "object", properties: { id: { type: "string" } } },
      fidelity: "exact"
    }
  ]
})

if (result.errors === undefined) {
  // Write result.source to <out>/acme.billing/zod.ts. result.warnings is data.
}
```

-   `SchemaInput.name` 实值 `<component fqn>#<slot label>`创建生成器 从中导出名称: PascalCase 组件 `fqn` 没有软件包 `fqn`,然后是PascalCase插槽标签。 出口按构成部分分类 `fqn`, (中文(简体) ), 然后是插槽标签。 没有名字 `#<slot label>`名称 目标文件和两个具有一个导出名的策略是 错误 (`reserved_name`, (中文(简体) ), `invalid_name`, (中文(简体) ), `name_clash`) (中文(简体) ). 这个 `zod` 文件使用 `z`, (中文(简体) ), `RegExp` 财务报告和审定财务报表 `Infinity`; 数据 `effect` 文件使用 `Schema`, (中文(简体) ), `RegExp` 财务报告和审定财务报表 `Infinity`编辑 `types` 文件保留名称。 这是用来保存姓名的 `$defs` 条目.
-   `SchemaInput.fidelity` 实值 `exact` 或者说 `structural`A级 `structural` 计划可以 运行时比JSON Schema更严格 每个 `structural` 计划给出一个 `structural_fidelity` 警告 警告他们.
-   `GenerateResult` 实值 `{ source, warnings }` 或者说 `{ errors }`。一次运行收集 每一个错误,每个有代码, 计划名称, 一个JSON指针和 关键词( e)`null` 当没有任何一个关键词有错的时候.
-   `Warning.kind` 实值 `structural_fidelity`, (中文(简体) ), `dropped_keyword`, (中文(简体) ), `format_annotation_only` 或者说 `closed_object_unenforced`。 。 。 .
-   输出为字节稳定. 同样的输入给出了相同的文字: 无时间戳, 工具版本或散列。 图书馆不叫论坛.

## 文件头

每个文件都以 `//` 注释头. 标题为目标命名 软件包 `fqn` 和软件包版本, 并说计划不是 运行时间验证权限. 后面是一行空白线 这个 `effect` 标题 再来一行关于多余的键.

```ts
// @generated
// Target: zod
// Package: acme.billing
// Version: 1.0.0
// Generated schemas are a convenience and not runtime validation authority.
// The backend host validates.
```

这个 `@generated` 在主注释中标记是 CLI 如何识别文件 以便它覆盖.

## 权力和要求

所生之相为方便. 后端主机验证; 生成 文件从不替换。 计划描述了钢丝形状:编码为JSON, 未解码运行时间值 .

-   `zod` 产出需求 `zod` 4.4 或后来. 用这个 `z.xor` 页:1 `oneOf`。 。 。 .
-   `effect` 产出需求 `effect/Schema`。 。 。 .
-   `types` 输出没有导入 .

## 关键词

支持的关键字 :

-   类型和值: `type`, (中文(简体) ), `enum`, (中文(简体) ), `const`。 。 。 .
-   字符串 : `minLength`, (中文(简体) ), `maxLength`, (中文(简体) ), `pattern`, (中文(简体) ), `format`。 。 。 .
-   数量 : `minimum`, (中文(简体) ), `maximum`, (中文(简体) ), `exclusiveMinimum`, (中文(简体) ), `exclusiveMaximum`, (中文(简体) ), `multipleOf`。 。 。 .
-   对象 : `properties`, (中文(简体) ), `required`, (中文(简体) ), `additionalProperties`, (中文(简体) ), `minProperties`, (中文(简体) ), `maxProperties`。 。 。 .
-   矩阵 : `items`, (中文(简体) ), `prefixItems`, (中文(简体) ), `minItems`, (中文(简体) ), `maxItems`, (中文(简体) ), `uniqueItems`。 。 。 .
-   组成: `anyOf`, (中文(简体) ), `oneOf`, (中文(简体) ), `allOf`。 。 。 .
-   参考文献:当地 `$ref` 改为 `$defs` 输入同一文档和根 `$defs`A级 `$defs` 条目成为不导出的地方声明.
-   说明: `title`, (中文(简体) ), `description`, (中文(简体) ), `default`, (中文(简体) ), `examples`, (中文(简体) ), `deprecated`, (中文(简体) ), `readOnly`, (中文(简体) ), `writeOnly`。 。 。 .
-   已忽略 : `$schema`, (中文(简体) ), `$id`, (中文(简体) ), `$anchor`, (中文(简体) ), `$comment`, (中文(简体) ), `$vocabulary` 和每个 开始的关键字 `x-`。 。 。 .

制约关键字需要 `type`。 。 。 . `minLength`, (中文(简体) ), `pattern`, (中文(简体) ), `format`,数字 范围, `properties`, (中文(简体) ), `required`, (中文(简体) ), `additionalProperties`, (中文(简体) ), `minProperties`, (中文(简体) ), `maxProperties`, (中文(简体) ), `items`, (中文(简体) ), `prefixItems`, (中文(简体) ), `minItems`, (中文(简体) ), `maxItems` 财务报告和审定财务报表 `uniqueItems` 仅约束它们自己类型的值,所以没有 `type` 也接受所有其他价值,没有目标可以这么说. 这个 生成器不猜测类型: 每个关键字运行失败 `unsupported_keyword_combination`,以及 `keyword` 这是限制。 这个 内 `allOf`, (中文(简体) ), `anyOf` 财务报告和审定财务报表 `oneOf` 成员 `$defs` 条目.

一个名字在 `required` 那个 `properties` 不申报为财产 `additionalProperties` 描述:任何值,或 `additionalProperties` 计划 与 `additionalProperties: false` 没有物体可以满足它,所以它 失败 `unsupported_keyword_combination` (单位:千美元)`required+additionalProperties`(中文(简体) ) 地点 `required` 输入.

`prefixItems` 描述存在和不存在的立场. 仅需以下职位 `minItems`; 后期位置为可选 tuple 元素 (`[A, B?]`) (中文(简体) ). 位于或超出的职位 `maxItems` 不存在, 财务报告和审定财务报表 `items` 最后一个被丢弃之后.

这些关键字无法运行, 因为生成器无法表达它们 : `contains`, (中文(简体) ), `dependentRequired`, (中文(简体) ), `if`, (中文(简体) ), `then`, (中文(简体) ), `else`, (中文(简体) ), `not`, (中文(简体) ), `patternProperties`, (中文(简体) ), `unevaluatedItems`, (中文(简体) ), `unevaluatedProperties`, (中文(简体) ), `$dynamicRef`, (中文(简体) ), `$defs` 根下方,一个远程 `$ref`,递归 `$ref`,以及 (单位:千美元) `$ref` 这并不意味着 `$defs` 输入。 任何其它关键字 不从 `x-` 是一个 `unknown_keyword` 错误。 发电机从来没有 降解一个形状,改变计划接受的内容.

仅删除一个在目标中没有等效的验证关键字。 留下来 用作记念和警告`dropped_keyword` 或者说 `format_annotation_only`) (中文(简体) ).

## 目标限制

-   `types`: 类型不能检查值。 验证关键字( E)`minLength`, (中文(简体) ), `maxLength`, (中文(简体) ), `pattern`, (中文(简体) ), `format`,数字界限、财产和物品 计数, `uniqueItems`成为JSDoc标签并给予 `dropped_keyword` 警告! 警告你们.
-   `zod`: 对象 `additionalProperties: false` 为: `z.strictObject`。一个 无属性和无属性的对象 `additionalProperties` 这是公开的纪录, 和其他目标一样. `format` 被选中 `date-time`, (中文(简体) ), `email`, (中文(简体) ), `uuid` 财务报告和审定财务报表 `uri`; 任何其他 格式保持为 `.meta` 数据和给予 `format_annotation_only`。 。 。 . `uniqueItems`, (中文(简体) ), `minProperties` 财务报告和审定财务报表 `maxProperties` 保持不变 `.meta` 数据及数据 给 `dropped_keyword`。 。 。 .
-   `effect`数字 : `Schema.Struct` 没有关闭对象. `additionalProperties: false` 未执行并给出 `closed_object_unenforced` 每个对象发出警告; 仅以解码选项拒绝多余的密钥 `onExcessProperty: "error"`。仅限 `format: uuid` 是格式检查;任何其他 格式保留为注释并给出 `format_annotation_only`对象 已经宣布了密钥,没有额外的计划 无法计算它的密钥,所以 `minProperties` 财务报告和审定财务报表 `maxProperties` 留作说明并给予 `dropped_keyword`。 。 。 . `allOf` 只合并纯对象; 其他成员 (单位:千美元)`allof_not_plain_objects`,也用于 `$ref` 成员名单 以不同方式申报一项财产(`allof_property_conflict`),失败 运行。 一个未合并的计划对象的关键词, 例如 a `$ref` 限制或限制 `type` 与 `oneOf`失败 `unsupported_keyword_combination`; 其编号 `keyword` 列出与 `+`。 。 。 .

## 检查

```sh
bun test tests/package-contract.test.ts
bun run type-check
bun run build
bun run test:pack
```

## 常见问题

### @collective-intelligence/schema-codegen 是什么？

从2020-12 Draft JSON Schema文档到TypeScript, Zod和Effect Schema源的纯生成器\.

### 如何安装 @collective-intelligence/schema-codegen？

在项目目录运行 npm install @collective-intelligence/schema-codegen，或使用 pnpm add / yarn add / bun add。

### @collective-intelligence/schema-codegen 支持 TypeScript 吗？

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

### @collective-intelligence/schema-codegen 支持 ESM 还是 CommonJS？

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

### @collective-intelligence/schema-codegen 可以商用吗？

@collective-intelligence/schema-codegen 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @collective-intelligence/schema-codegen 的下载量有多少？

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

### @collective-intelligence/schema-codegen 还在维护吗？

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

