# @aikdna/kdna-web-client 中文文档

规范地址：https://npmcn.com/package/%40aikdna/kdna-web-client/

版本：0\.3\.0
npm 元数据更新时间：2026-10-09T05:35:46.447Z
中文译文更新时间：2026-11-06T07:26:33.498Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aikdna/kdna-web-client
原文对照：https://npmcn.com/package/%40aikdna/kdna-web-client/?lang=original
项目主页：https://github.com/aikdna/kdna-web-client
源码仓库：https://github.com/aikdna/kdna-web-client

弃用说明：Deprecated: not part of the current supported KDNA release\. This version targets an earlier release line and is no longer maintained; keep it only for existing pinned installs and do not use it for new integrations\.

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

- 包体积（解压后）：318 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-07-03T08:41:21.001Z
- 最新版本发布：2026-08-08T04:10:14.857Z
- 近 30 天下载量：4185（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

浏览器-安全 KDNA 公用设备——文件选择,元数据检查,上传,并负载计划状态管理. 永远不要进行解密.

## 安装

```sh
npm install @aikdna/kdna-web-client
```

也可以使用：`pnpm add @aikdna/kdna-web-client`、`yarn add @aikdna/kdna-web-client`、`bun add @aikdna/kdna-web-client`

## README

# @aikdna/kdna-web-客户端

**浏览器- 安全 KDNA 工具 .**

> **状态 :** 实验性出版的浏览器集成 : 坐标。 这不是一个稳定的浏览器 runtime 或一个完整的主机政策 .

文件选择、元数据检查、上传到服务器以及 负载计划国家管理——从未在 浏览器.

> **设计限制 :** 此软件包从不解密任何东西。 写着 a 的公开元数据 `.kdna` 文档和代表全部敏感 操作到服务器运行 [@aikdna/kdna-web-服务器](https://github.com/aikdna/kdna-web-server)。 。 。 .

> 新到KDNA吗 [KDNA 核心](https://github.com/aikdna/kdna)
> 
> 需要一个服务器侧适配器吗? → [@aikdna/kdna-web-服务器](https://github.com/aikdna/kdna-web-server)
> 
> 需要反应组件吗 ? → [@aikdna/kdna-反应](https://github.com/aikdna/kdna-react)

[![npm](https://img.shields.io/npm/v/@aikdna/kdna-web-client)](https://www.npmjs.com/package/@aikdna/kdna-web-client) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://npmcn.com/package/%40aikdna/kdna-web-client/LICENSE)

* * *

## 安装

```bash
npm install @aikdna/kdna-web-client
```

无对等依存. 浏览器捆绑中的Node.js内置.

* * *

## 快开始

```js
import { readKDNAMetadata, uploadKDNA, KDNALoadPlanManager } from '@aikdna/kdna-web-client'

// 1. Let the user pick a file
const input = document.createElement('input')
input.type = 'file'
input.accept = '.kdna'
input.onchange = async () => {
  const file = input.files[0]

  // 2. Read public metadata (no server round-trip, no decryption)
  const meta = await readKDNAMetadata(file)
  console.log(meta.domain, meta.version, meta.encrypted)

  // 3. Upload to your server and get a fileId
  const { fileId } = await uploadKDNA(file, '/api/kdna/inspect')

  // 4. Manage the load-plan flow
  const manager = new KDNALoadPlanManager('/api/kdna')
  const plan = await manager.planLoad(fileId)

  if (plan.canProceed) {
    const result = await manager.load(fileId, { profile: 'compact' })
    console.log(result.capsule.context)
  } else {
    console.log('Missing:', plan.missing)  // e.g. ['enter_password']
  }
}
input.click()
```

文件拾取器为此操作建立明确的用户选择. 若为 应用程序记得文件为附件, 它必须准确无误 身份、文摘、范围和理由可见,并提供禁用/开关/回滚 控制系统。 仅上传存储并不能授权未来的任务.

* * *

## API 参考

### `readKDNAMetadata(file)`

从 a 读取公共显示字段 `.kdna` `File` 没有对象 正在上传或执行任何解密.

```js
const meta = await readKDNAMetadata(file)
```

回返情况:

```ts
{
  domain:      string         // e.g. "kdna:aikdna:laozi-wuwei"
  version:     string         // e.g. "1.2.0"
  title:       string | null
  description: string | null
  encrypted:   boolean
  profiles:    string[]       // available load profiles
  fileSize:    number         // bytes
}
```

默认 `maxSizeBytes` 是 10 MiB,与官方 Web 服务器对齐. 当应用程序需要更紧的内存时, 传递一个较小的正整数 预算。 公示单独立限定为一米B.

掷出 `KDNAFileSizeError` 如果文件太大. 掷出 `KDNAFormatError` 如果文件无效 `.kdna` 集装箱.

* * *

### `uploadKDNA(file, endpoint)`

上传 a `.kdna` `File` 到终点( 通常为 `/api/kdna/inspect`并返回 `fileId` 由服务器指定.

```js
const { fileId, inspect } = await uploadKDNA(file, '/api/kdna/inspect')
```

回返情况:

```ts
{
  fileId:   string    // opaque ID — pass to plan-load and load
  inspect:  object    // bounded public inspect fields only
}
```

客户只保留 `fileId`,公共资产元数据,默认配置, 可选配置文件, 以及公共负载计划 。 内部服务器存储元数据 路径和未知字段被丢弃.

掷出 `KDNAUploadError` 如果请求失败或服务器返回非200 状态。 公用错误包含一个固定的本地信件, HTTP 状态和 a 当服务器提供一个时, 语言学 KDNA 错误代码 。 服务器错误消息 和反应机构从未附加; 兼容性 `response` 属性 总是 `null`。 。 。 .

* * *

### `KDNALoadPlanManager`

为单个文件驱动负载计划流的状态类.

```js
const manager = new KDNALoadPlanManager(baseUrl)
```

| 方法 | 说明 |
| --- | --- |
| `planLoad(fileId, context?)` | 评估负载计划。 回返要求. |
| `load(fileId, options)` | 装入资产。 全权证书直接通过. |

#### `planLoad(fileId, context?)`

```js
const plan = await manager.planLoad('abc123', {
  hasPassword: false,
  entitlementToken: null,
})
```

回返情况:

```ts
{
  canProceed:   boolean
  missing:      string[]    // e.g. ['enter_password']
  requirements: {
    password:   { required: boolean, hint: string | null }
    licenseKey: { required: boolean }
  }
}
```

#### `load(fileId, options)`

```js
const result = await manager.load('abc123', {
  profile:          'compact',
  password:         '...',   // only if required
  entitlementToken: { status: 'active' }, // signed entitlement from /activate, only if required
})
```

返回来自 `capsule` 仅在 `capsule` 完成完全运行时间 Capsule 计划关闭 锁定在经审计的 KDNA 核心承诺。 未知的顶级服务器字段被丢弃 . 代理造型出品是跑步相机; `content` 是一个网络用户界面 方便别名 `capsule.context`数字 :

```ts
{
  domain: "kdna:aikdna:laozi-wuwei"
  version: "0.1.1"
  judgmentVersion: "0.1.0"
  profile: "compact"
  content: object
  capsule: {
    type: "kdna.runtime-capsule"
    contract_version: "0.1.0"
    asset: object
    digests: object
    signature: object
    access: "public" | "licensed" | "remote"
    profile: "index" | "compact" | "scenario" | "full"
    context: object
    trace: object
  }
}
```

* * *

### `KDNAFileSizeError`

被丢弃 `readKDNAMetadata` 当文件超过配置时 最大尺寸.

### `KDNAFormatError`

被丢弃 `readKDNAMetadata` 当文件无效时 `.kdna` 头曰.

### `KDNAUploadError`

被丢弃 `uploadKDNA` 当 HTTP 请求失败时 .

### `KDNALoadError`

在请求失败或返回时按装入计划投放并装入呼叫 运行时间 Capsule 无效 。 一样 `KDNAUploadError`上游反应机构 而信息永远不会被曝光.

* * *

## 安保模式

见 [文件/安全模型.md](https://npmcn.com/package/%40aikdna/kdna-web-client/docs/security-model.md)。 。 。 .

短版本 :

-   此包只读取容器头和公开 `kdna.json` 显示 在记忆中。 它从不解析 解密 或暴露 `payload.kdnab`; 装入为 授权给官方服务器侧工具链.
-   密码和签名的权利记录或信使作为 参数到 `manager.load()` 并直接输入服务器 终点 它们不保存在任何对象属性或模块级别 变量。 原始许可密钥属于您的激活端点, 不是 `/load`。 。 。 .
-   这个软件包没有Node.js内建依赖性. 完全运行 在浏览器的安全模式内.
-   JSON响应被读取为受限UTF-8,必须是JSON对象. 错误 有效载荷被降低到状态,并具有犬类编码;成功有效载荷是: 投射到有记录的公众表面.

## 消费痕迹

`parseJudgmentTrace`, (中文(简体) ), `judgmentTraceView`和无依赖性 `JudgmentTraceViewer` 验证完整的判决 Trace 计划关闭 对同一经审计的KDNA核心承诺,因未知或不一致而未结案 巢所证. 他们保留了Capsule交付,主机执行, 语义消耗, 和符合作为单独的证据。 一个相互关联的主机 答复不能证明一个模型对判断有敏锐的消耗,或 答案是符合它的.

浏览器客户端应当收到一个可信赖的应用程序端点的跟踪. 浏览器检查仅证明方案符合性; 加密和语义 符合性仍然是服务器方面的KDNA核心责任。 追踪是永远不会 允许读取受保护的有效载荷.

* * *

## 相关软件包

| 软件包 | 作用 |
| --- | --- |
| [`@aikdna/kdna-core`](https://github.com/aikdna/kdna) | KDNA 格式和运行时间 (Node.js) |
| [`@aikdna/kdna-web-server`](https://github.com/aikdna/kdna-web-server) | 服务器侧适配器 |
| [`@aikdna/kdna-react`](https://github.com/aikdna/kdna-react) | 反应组件和钩 |
| [`create-kdna-web-app`](https://github.com/aikdna/create-kdna-web-app) | 项目脚手架CLI |

* * *

## 许可证

Apache 2.0 — 见 [自由主义](https://npmcn.com/package/%40aikdna/kdna-web-client/LICENSE)。 。 。 .

## 常见问题

### @aikdna/kdna-web-client 是什么？

浏览器-安全 KDNA 公用设备——文件选择,元数据检查,上传,并负载计划状态管理\. 永远不要进行解密\.注意：该包已被作者标记为弃用——Deprecated: not part of the current supported KDNA release\. This version targets an earlier release line and is no longer maintained; keep it only for existing pinned installs and do not use it for new integrations\.

### 如何安装 @aikdna/kdna-web-client？

在项目目录运行 npm install @aikdna/kdna-web-client，或使用 pnpm add / yarn add / bun add。

### @aikdna/kdna-web-client 支持 TypeScript 吗？

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

### @aikdna/kdna-web-client 支持 ESM 还是 CommonJS？

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

### @aikdna/kdna-web-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aikdna/kdna-web-client 可以商用吗？

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

### @aikdna/kdna-web-client 的下载量有多少？

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

### @aikdna/kdna-web-client 还在维护吗？

最新版本 0\.3\.0 发布于 2026/08/08（2 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/07/03。作者已将其标记为弃用，新项目建议寻找替代方案。