# @kanonak-protocol/codec 中文文档

规范地址：https://npmcn.com/package/%40kanonak-protocol/codec/

版本：3\.0\.1
npm 元数据更新时间：2026-11-01T12:29:58.525Z
中文译文更新时间：2026-11-01T15:15:29.810Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40kanonak-protocol/codec
原文对照：https://npmcn.com/package/%40kanonak-protocol/codec/?lang=original
项目主页：https://kanonak.org/
源码仓库：https://github.com/kanonak-protocol/runtime

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

- 包体积（解压后）：85.4 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-07T18:29:48.402Z
- 最新版本发布：2026-11-01T12:29:58.216Z
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

通用Kanonak编解码器运行时：从类型化节点+嵌入式模式构建规范化输入模型，通过@kanonak-protocol/canonical对其进行内容寻址，并序列化/反序列化规范化json连接表单。由生成的类型化sdk引用；

## 安装

```sh
npm install @kanonak-protocol/codec
```

也可以使用：`pnpm add @kanonak-protocol/codec`、`yarn add @kanonak-protocol/codec`、`bun add @kanonak-protocol/codec`

## README

# @kanonak-protocol /编解码器

通用的、与本体无关的 **编解码器运行时** 参考Kanonak’s 生成类型sdk。它将类型化对象转换为Kanonak内容地址和 给定每个包的规范化json连接形式 `CodecSchema` ,一个 生成SDK嵌入。

它是编解码器运行时的TypeScript端口。c# /Rust/Go/Java/Python端口 参考他们的 `kanonak-canonical` 库用于相同的标准哈希表项； 打印稿引用 **`@kanonak-protocol/canonical`** -它唯一的依赖。

## 它是做什么的

-   **`packageContentHash(nodes, schema, pkg)` → `sha256:…`** ——永久的 这些节点形成的包的内容地址。建立语言中立 规范输入模型(`kanonak.org/canonical-form`)，并将其散列 `@kanonak-protocol/canonical`． Byte-identical来 `kanonak hash` 的 等价的撰写 `.kan.yml`，包括合成的 `rdf:type` 三元组 和包装主体。
-   **`packageCanonicalForm(nodes, schema, pkg)`** -规范形式本身 ( `{subjects:[…]}` JSON)，用于检查/调试。
-   **`serialize(node, schema)` / `deserialize(json, schema)`** -规范化的json 线的形式。类型模型之外的开放世界断言可以无损地往返 通过 `$extra` (顶级线字段，收集下 `$extra` 在打字上 节点, `[JsonExtensionData]` 语义)。从3.0.0开始，每个整数和小数 value以JSON形式（kanonak-protocol 4.11.0’s）传播 `numbers-in-json`， 运行时#54)，通过列表和嵌入值。 `deserialize` 给出一个宽 整数(`integer`四种符号限制形式； `long`， `unsignedLong`), 一个 `bigint`,一个 `decimal` 作为其规范数字的字符串，和 `int` 和 窄得像 `number`； `serialize` 将宽整数和小数写入为 它们的规范数字的字符串，以及作为数字的窄整数。一个 模式不包含其类的内嵌值按给定方式携带。 `deserialize` 判断给定的值： `JSON.parse` 已经读过了 数字如 `1.0000000000000000001` 作为 `1`，所以来电者必须拒绝 判断数字的来源，作为一个复兴者 `context.source` 给出它（节点22）。超过±（2^53−1）的JSON数字用于宽整数，数字用于十进制，字符串用于窄整数，或超出其数据类型范围的值被拒绝，结束 `[json-number-form]`,因为 `codec-vectors-json-numbers.json` 每个端口的引脚。

散列也拒绝模式没有声明的语句 `$extra` 类没有建模的入口或键 `[hash-undeclared-statement]`：编解码器保存一个包的模式，不能键入另一个包的谓词，因此这样的节点与SDK在图上进行散列。序列化和反序列化仍然携带它（codec 2.0.0, runtime#37）。

## 设计独立

载体来自模式的数据类型uri和已解析的基础uri （`type`/`label` 谓词, `Package` 类)被生成器嵌入 所以哈希需要 **没有运行时本体解析** 而且不能访问注册表。一个 生成的SDK加上这个库（和它的一个库） `@kanonak-protocol/canonical` 依赖关系)足以在无服务器/边缘环境中实现内容地址类型的对象 运行时。

## 形状

```ts
import { packageContentHash, serialize, deserialize } from '@kanonak-protocol/codec';
import type { CodecSchema, CodecNode, PackageContext } from '@kanonak-protocol/codec';

// `Schema` is the constant a generated SDK embeds for its own classes.
const hash = packageContentHash(nodes, Schema, {
  publisher: 'example.com', packageName: 'my-data', version: '1.0.0',
});
```

`canonicalFormVersion: "1"` -内容地址规则是冻结和发展的 只能创建一个新版本（通过底层的规范形式规范）。

## 嵌入值（0.2.0）

对象属性的值是a **参考** （`{ $ref: uri }`)或 **嵌入式节点**没有数字的地图 `$id`，可选 `$name` (撰写 Dict-key - hash-relevant)，可选的 `$type`，以及模式映射字段。 一个显式的 `$type` 在嵌入的（哈希相关的） 即使它等于范围派生类型)；如果没有，字段将通过映射 包含属性的 `range` 并且不会发出类型语句。嵌入式 集合是有序列表——列表的顺序是语义的和散列的。一个空 List不提供任何语句（在规范中，缺席和空是相同的） 层)。封闭的 `vectors/codec-vectors-embedded.json`.

一个参考值指向A **命名资源**： `publisher/package[@version]/name`. 一、 `$ref` 包含URI片段(`#…`)被规范化所拒绝， `serialize` 和 `deserialize` 在任何深度都是一样的，以错误结尾 `[fragment-reference]`． 片段处理用于导航的嵌入式资源； 它们不是参考图的一部分。封闭的 `vectors/codec-vectors-references.json`.

## 读取早期兼容版本（0.6.1）

节点的类型是与其生成器导入解析的类的版本一致的 出现。生成的编解码器 **兼容的** 同一软件包的版本 仍然是这样读的： `deserialize` 首先获取精确版本化的类，然后是 的最高级架构版本中的同一个类 `isReadableBy` (从 `@kanonak-protocol/canonical`)说可以读书面的。节点保持 这个 `$type` 上面写着。

-   **`typeMatches(node, classUri, schema)`** -生成的类型保护要求的内容。 每个节点的类型(`$types`,否则 `$type`)经历了同样的事情 兼容查找和匹配时，类 `classUri` 或者它在 它的 `ancestors`，可选的传递超类列表a `CodecClass` 可以 携带。类通过无版本标识进行比较。
-   **`enumMember(schema, ref)`** -枚举成员a `{"$ref"}` 的名字, 首先是完全相同的，然后是兼容的后续版本中的相同成员。
-   **哈希保持精确版本。** 内容散列覆盖了生产者的 谓词和类型uri，包括版本，所以模式在较新的版本 无法复制。散列缺少确切类的节点会失败 `[hash-needs-exact-version]` 当只有一个兼容类存在时。

错误以括号中的类型结束： `[unknown-type]`， `[newer-version]` (数据 可能会使用这个模式缺少的术语)， `[other-major]`， `[other-minor-line]` (下图 1.0.0（次要行是不兼容的行）和 `[hash-needs-exact-version]`. 封闭的 `vectors/codec-vectors-compat.json`.

来源和问题： [https://github.com/kanonak-protocol/runtime](https://github.com/kanonak-protocol/runtime)

## 常见问题

### @kanonak-protocol/codec 是什么？

通用Kanonak编解码器运行时：从类型化节点\+嵌入式模式构建规范化输入模型，通过@kanonak-protocol/canonical对其进行内容寻址，并序列化/反序列化规范化json连接表单。由生成的类型化sdk引用；

### 如何安装 @kanonak-protocol/codec？

在项目目录运行 npm install @kanonak-protocol/codec，或使用 pnpm add / yarn add / bun add。

### @kanonak-protocol/codec 支持 TypeScript 吗？

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

### @kanonak-protocol/codec 支持 ESM 还是 CommonJS？

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

### @kanonak-protocol/codec 可以商用吗？

@kanonak-protocol/codec 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @kanonak-protocol/codec 还在维护吗？

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