运行时清单 v2

Name: Darra AI Studio
Author: Darra

runtime-manifest.json 的 v2 格式：Provider 分包 + 场景整合包（profiles）+ 离线整合包。公开 SDK 用 darra_runtime_ensure 消费本清单。

v2 = v1 的 packages[] 之上加「Provider 身份 + 平台 + 硬件门 + ABI 门 + 逐文件校验」五道闸，再加 profiles[]。profile 只是清单，不产生新二进制。任何一道闸失败都如实返回 darra_error_code，绝不降级到别的 Provider 冒充成功。

公开 runtime 包物理上没有 darra_encrypt_ / darra_issue_ / darra_fingerprint_perturb。转换类符号（rknn-toolkit2、trtexec 编译链）不进 runtime 包。edge-rknn 的 osArch 只允许 linux-arm64。

相关：错误码 · 发布与下载 · 产品概述

与 v1 的关系

项	v1	v2
线上路径	`https://download.darra.xyz/ai-studio/runtime/v1/runtime-manifest.json`	`https://download.darra.xyz/ai-sdk/runtime/v2/runtime-manifest.json`
schemaVersion	`1`	`2`
消费方	AI Studio 环境管理器（Python embed + overlay）	Darra AI SDK（`darra_runtime_ensure`）；Studio 双发布期继续读 v1
选包维度	kind + pythonVer + minDriverCuda	providesProvider + osArch + hardwareGate + abiVersion + version
包内容	Python 嵌入式环境 / overlay	SDK Provider native 包（ORT / CUDA / TRT / OpenVINO / DirectML / rknn 重依赖全在包内）

v1 阅读器对 schemaVersion != 1 直接 fail-fast，因此 v1 / v2 必须分 URL 双发布，互不覆盖。
发布纪律：R2 zip 名带 sha 前缀按不可变对象发布，manifest 最后上传；读取线上清单异常时 fail-fast，拒绝覆盖。

顶层结构

{
  "schemaVersion": 2,
  "generatedAt": "2026-09-01T00:00:00Z",
  "packages": [ /* PackageEntry，至少 1 条 */ ],
  "profiles": [ /* ProfileEntry，可缺省 */ ]
}

字段	类型	必填	含义
schemaVersion	int	是	常量 `2`
generatedAt	string(date-time)	否	清单生成时间（UTC，ISO 8601），仅审计，不参与选包
packages	array	是	Provider 包条目，≥1；id 全清单唯一（不区分大小写）
profiles	array	否	场景整合包清单

未知字段一律拒绝（additionalProperties: false）——清单是安全边界，宁可 fail-closed 不静默忽略。

packages[] 字段

v2 核心字段

字段	类型	必填	含义 / 校验
providesProvider	string	是	Provider id。当前枚举：`onnx-cpu` / `onnx-cuda` / `onnx-openvino` / `onnx-trt-ep` / `onnx-directml` / `trt-native` / `edge-rknn` / `paddle-cpu`。未知值 fail-closed。
osArch	string	是	`windows-x64` / `linux-x64` / `linux-arm64`。选包第一道过滤。`edge-rknn` 只允许 `linux-arm64`；`paddle-cpu` 只允许 `windows-x64` / `linux-x64`。
abiVersion	int ≥1	是	本包对接的 DarraAI.Core ABI 主版本。必须等于本机 Core ABI 主版本，否则 `DARRA_PROVIDER_ABI_MISMATCH`。
version	string	否	`major.minor.patch`。选包排序主键；缺省按 `0.0.0`。
hardwareGate	object	否	硬件门。缺省 = 无硬件要求。
entryModule	string	是	包内 Provider 主模块相对路径（如 `bin/darra_provider_onnx_cuda.dll` / `lib/libdarra_provider_rknn.so`）。必须出现在 `dependencies[]` 里。
dependencies	array	否	包内受控文件：`[{path, sha256, size}]`。解压后逐文件校验；任一不符 = `DARRA_CHECKSUM_MISMATCH`。清单外文件不得被 dlopen。
description	string	否	中文说明。

与 v1 共用的下载字段

字段	类型	必填	含义
id	string	是	包唯一 id。推荐 `<provider>-<osArch>[-<tag>]`（如 `onnx-cuda-windows-x64-cu130`）。
fileName	string	是	R2 对象名（sha 前缀不可变命名）。
url	string(HTTPS)	是	下载地址，必须 HTTPS。离线包内嵌清单中可缺省。
sha256	string(64 hex)	是	包 zip 整体 SHA-256。
size	int >0	是	包 zip 字节数。
cudaTag	string	否	CUDA 代际选择子（`cu118`…`cu130`）。
kind	string	否（legacy）	v1 兼容别名：`cpu` / `cuda` / `openvino` / `tensorrt` / `paddle`。
pythonVer / torchVer / torchvisionVer	string	否（legacy）	Studio Python embed 链专用；SDK native 包不携带。
minDriverCuda	string	否（legacy）	v1 顶层字段；v2 语义在 `hardwareGate.minDriverCuda`。两处同时出现必须同值。

hardwareGate

"hardwareGate": { "gpu": "nvidia", "minDriver": "535.0", "minDriverCuda": "12.8" }
"hardwareGate": { "npu": "rk3588" }

子字段	类型	判定
gpu	`nvidia` / `amd` / `intel`	本机 GPU 厂商必须相等；无此 GPU = `DARRA_HARDWARE_MISSING`。
minDriver	点分版本	本机驱动 ≥ 该值，否则 `DARRA_DRIVER_TOO_OLD`。
minDriverCuda	`major.minor`	`nvidia-smi` 报告的驱动 CUDA 上限 ≥ 该值，否则 `DARRA_DRIVER_TOO_OLD`。
npu	`rk3588`	SoC 匹配且 `librknnrt`（板厂镜像自带）可加载，否则 `DARRA_HARDWARE_MISSING`。SDK 不代装 NPU 驱动。

规则：gpu 与 npu 至少出现其一；多子字段是与关系。hardwareGate 只描述「本包要什么硬件」，不描述性能分档——分档靠多包并存（如 cu128 / cu130）+ 选包排序。

profiles[] 场景整合包

{
  "id": "nvidia-gpu",
  "description": "NVIDIA 独显场景：ORT CUDA EP + TensorRT EP，按驱动自动选 CUDA 代际",
  "members": ["onnx-cuda-windows-x64-cu128", "onnx-cuda-windows-x64-cu130", "onnx-trt-ep-windows-x64"]
}

字段	类型	必填	含义
id	string	是	五个标准 id：`cpu-only` / `nvidia-gpu` / `intel-iap` / `amd-dml` / `board-rk3588`。
description	string	是	中文说明。
members	array[string]	是	引用 `packages[]` 的 id，≥1；必须闭合。
default	bool	否	`true` 表示随主安装包默认装（仅 `cpu-only`）。

写死规则：

profile 只是清单，不产生新二进制。 禁止为 profile 单独打包。
members 允许同一 Provider 的多个变体（如 cu128 + cu130）；安装时按本机 osArch + hardwareGate 逐个解析，不是无脑全装。
darra_runtime_ensure("<profileId>", ...) = 解析 members → 逐成员选包 → 逐包装。任一成员失败如实报，已装成员保留，不整组回滚假装没发生。
cpu-only（onnx-cpu）零重依赖随主安装包，是默认形态。

v1 → v2 kind 映射

v1 kind	v2 providesProvider	说明
`cpu`	`onnx-cpu`	ORT CPU Provider。
`cuda`	`onnx-cuda`	`minDriverCuda` / `cudaTag` 原样搬进 hardwareGate / cudaTag。
`openvino`	`onnx-openvino`	—
`tensorrt`	`onnx-trt-ep`	ORT TensorRT EP。与原生 `trt-native`（编译 `.engine` 用，authoring 侧）不是同一个 Provider。
`paddle`	`paddle-cpu`	Paddle Inference CPU（Windows / Linux x64，PayloadKind=`paddle`）。

选包算法

输入：request.providerId（或先把 profile 展开成细包）、可选 preferredCudaTag；本机 osArch / ABI 主版本 / 硬件探测。

providesProvider 匹配。空集 → 清单无效（发布事故）。
osArch 过滤。空集 → DARRA_HARDWARE_MISSING（例：Windows 请求 edge-rknn = 「该载荷需 RK3588 板端运行时」）。
hardwareGate 判定。无 gate 通过；gpu / npu / 驱动任一门不过则剔除。全部剔除 → DARRA_HARDWARE_MISSING 优先于 DARRA_DRIVER_TOO_OLD。驱动类附官方链接，SDK 不代装系统驱动。
abiVersion == 本机 ABI 主版本。空集 → DARRA_PROVIDER_ABI_MISMATCH。
排序（能跑的最新）：preferredCudaTag 命中优先 → version 降序 → minDriverCuda 降序 → cudaTag 降序 → id 字典序降序。取首条。
下载与整体校验：HTTP / 网络异常 → DARRA_NETWORK_FAILED；字节数或 sha256 不符、zip 空/坏/含越界路径 → DARRA_CHECKSUM_MISMATCH。支持 Range 断点续传。
解压后逐文件校验 dependencies[]。任一缺失或 sha256 不符 → DARRA_CHECKSUM_MISMATCH。
加载门：entryModule 过 sha256 白名单后 dlopen / LoadLibrary；ABI 符号不符 → DARRA_PROVIDER_ABI_MISMATCH。
原子发布：候选目录 → 正式目录（备份 / 发布 / 探针 / 回滚）。取消或失败不留半成品。

铁律：指定了 Provider 时，以上任何一步失败 = 如实返回对应错误码，绝不静默改用别的 Provider 冒充成功。 仅当调用方显式请求 auto 策略时，SDK 才按策略表选取替代 Provider，且诊断 JSON 必须记录实际加载的 Provider 与包 id。

失败码对照

`darra_error_code`	步骤	含义	处置
`DARRA_HARDWARE_MISSING`	2 / 3	平台无此包，或 gpu/npu 硬件门不满足	如实告知缺什么；Windows 上 `edge-rknn` 走此路径拒载
`DARRA_DRIVER_TOO_OLD`	3	minDriver / minDriverCuda 不满足	升官方驱动；SDK 不代装
`DARRA_NETWORK_FAILED`	6	清单/包下载失败	可重试；断网走离线包
`DARRA_CHECKSUM_MISMATCH`	6 / 7	size、整体 sha256、逐文件任一不符	删缓存重下；不得跳过校验
`DARRA_PROVIDER_ABI_MISMATCH`	4 / 8	包 abiVersion ≠ Core ABI，或加载失败	升级 SDK 或装匹配代际的包
`DARRA_UNSUPPORTED_PLATFORM`	指名非法平台	如 Windows 上指名 `edge-rknn`	换到 linux-arm64 板端
`DARRA_CANCELLED`	任意	`darra_runtime_ensure_cancel`	半成品已清理，需要时重调

清单 schema 不过、无 packages、id 重复、profile 引用悬空 = 发布侧事故，fail-fast 拒绝整份清单。所有失败路径记日志；诊断 JSON 不含密钥 / 密码 / token。

离线整合包

文件名 darra-runtime-offline-<profileId>-<yyyymmdd>-<sha8>.zip：

├── manifest.json              # v2 子集: schemaVersion=2 + 一条 profile + 其 members 的 packages 条目
└── packages/<packageId>/<fileName>   # 成员包原始 zip，与 R2 对象逐字节一致

外层 zip 可读、非空、无越界路径。
内嵌 manifest 过 v2 schema 全量校验；url 允许缺省。安装时不联网。
每个成员包 size 精确相等 + sha256 逐字节复核（不因为在离线包里就信任）。
之后走逐文件校验 → 加载门 → 原子发布。离线不等于绕过任何一道闸。
离线包本身只是「细包 + 清单子集」的容器，不产生新二进制。
darra_runtime_ensure(..., offline_zip) 与 Studio「导入离线包」共用同一条校验链。

禁止项

rknn 载荷不进 Windows / linux-x64 包。 edge-rknn 的 osArch 只允许 linux-arm64。Windows 环境管理器下载列表经 osArch 过滤天然不含它。Windows / linux-x64 收到 rknn 载荷如实拒载（DARRA_UNSUPPORTED_PAYLOAD：该载荷需 linux-arm64 + edge-rknn + librknnrt）。
转换类符号不进 runtime 包。 rknn-toolkit2、trtexec 编译链、darra_encrypt_ / darra_issue_ / darra_fingerprint_perturb 一律只在 authoring 侧（AI Studio）。runtime 包发布门 strings 检查，命中即拒绝发布。trt-native 包仅供 authoring 编译 .engine，不进 runtime 机器的自动选包集。
诊断不得含密钥。 授权状态只写「有效 / 无效 / 试用剩余」。
profile / 离线包不产生新二进制。
SDK 不自动安装 / 升级系统驱动（NVIDIA / NPU）。
未知字段 / 未知 Provider / 未知 osArch 一律 fail-closed。

与 v1 的关系​

顶层结构​

packages[] 字段​

v2 核心字段​

与 v1 共用的下载字段​

hardwareGate​

profiles[] 场景整合包​

v1 → v2 kind 映射​

选包算法​

失败码对照​

离线整合包​

禁止项​