宿主运行库（`requires_runtime`）

插件需要一份原生运行库（llama.cpp、某个推理后端、一组 DLL）才能工作，但这东西几十 MB 以上——打进 .tbmod 既过不了上传通道（20 MB 上限），也会让每个订阅者、每次更新都重复下载。
从 0.2.0 起，常用运行库（llama / whisper / audio.cpp / tts-server）已随安装包内置（bundled），插件只需声明要哪个，用户不用点任何下载按钮。早期版本还有「宿主按需下载运行库组件」（下载 + sha256 校验 + 解压，带断点续传/暂停/盘满预检）这条通道，非内置运行库仍走它。

声明

json

{
  "requires_runtime": [
    { "id": "llama_runtime", "reason": "提供 llama.cpp 运行时（llama-server + Vulkan/CPU 后端）" }
  ]
}

项	说明
条数	≤ 4（超出丢弃）；简写 `["llama_runtime"]` 与对象写法等价
`id`	宿主已知的运行库 id（见下表）；未知 id 视为未满足，提示用户「更新 TransBox 后才支持」
`reason`	可选，给人看的一句话（卡片/提示里可能展示）

宿主已知运行库

id	内容	适用场景	落盘位置
`llama_runtime`	llama.cpp 运行库（`llama-server.exe` + Vulkan/CPU 后端）	文本翻译 (MT) / 多模态 ASR	`data/local-runtime/runtimes/llama-vulkan/`
`whisper_runtime`	whisper.cpp 运行库（`whisper-server.exe` + Vulkan/CPU 后端）	本地语音识别 (ASR)	`data/local-runtime/runtimes/whisper-vulkan/`
`audiocpp_runtime`	audio.cpp 运行库（`audiocpp_server.exe` + Vulkan/CPU 后端 + eSpeak-NG）	本地语音合成 (TTS)	`data/local-runtime/runtimes/audiocpp/`
`tts_server_runtime`	qwentts.cpp 的 `tts-server.exe`（Qwen3-TTS 专用，OpenAI 兼容 `/v1/audio/speech` + 克隆音色注册表）	本地语音合成 (TTS，Qwen3-TTS 系列)	`data/local-runtime/runtimes/tts-server/`
`nv_pack_cu13`	NVIDIA 专属加速包（CUDA 13.3 深度优化，包含 llama + whisper + audiocpp 三引擎及共享 CUDA 动态库）	仅 N 卡用户加速全线本地模型	`data/local-runtime/runtimes/nv-pack-cu13/`

bundled 语义：llama_runtime / whisper_runtime / audiocpp_runtime / tts_server_runtime 都是 随安装包内置（bundled=True）——用户不需要、也不会看到「下载运行库」按钮。声明它们只是让宿主做就绪校验（缺文件时给出明确提示），不走下载流程。 tts-server 的完整 HTTP 契约见本地 TTS 服务（tts_server_runtime）。

宿主行为

与 requires_plugins 共用同一道门禁：

运行库未就绪时：启用插件被拒绝、选为 ASR/MT/TTS 引擎被拒绝、启动同传时以 missing_dependency 阻断；
非内置运行库未就绪时，提示为「需要运行库：llama.cpp 运行库（未下载）」，插件卡片按钮变成「下载运行库」；内置（bundled）运行库没有下载通路，就绪失败只会被归因为「安装不完整」，提示用户重装；
非内置运行库由宿主自行完成 下载 → sha256 校验 → 解压（可暂停 / 断点续传 / 重试 / 盘满预检），完成后即就绪，再点启用即可；
依赖链同样生效（见前置插件依赖）。

插件不要自己下载/解包/随包携带这份二进制，也不要把它写进 model_artifacts。

取用

python

from pathlib import Path

runtime = self.host.runtime_dir("llama_runtime")     # 未下载返回 ""
if not runtime or not self.host.has_runtime("llama_runtime"):
    return False, "model_not_ready", "需要先下载「llama.cpp 运行库」（「运行组件」窗口或插件卡片按钮）"

exe = Path(runtime) / "llama-server.exe"

不需要知道运行库由哪个插件承载。

内置运行库（bundled=True）已经在安装包里，runtime_dir() 直接返回目录。定位失败只可能是安装不完整 —— 提示用户重装，不要引导他去「下载运行库」。

兼容说明（仅 0.1.x）：0.1 时代运行库由承载插件（如 workshop.common_llama）携带在 extensions/ 里，老写法 host.plugin_dir("workshop.common_llama") / "llama" / "llama-server.exe" 当时可用。 0.2.0 已没有这些承载插件：运行库统一落在 data/local-runtime/runtimes/，老写法在新版上一律返回空路径，请改用 runtime_dir()。

`requires_runtime` vs `model_artifacts`

	`requires_runtime`	`model_artifacts`
装的是什么	原生二进制/运行库（exe/dll）	模型权重（safetensors/gguf…）
来源	官方 CDN	Hugging Face / ModelScope / hf-mirror
落盘	插件目录内（由运行库组件决定）	`<数据目录>/models/<...>`
用户可见	「运行组件」窗口 / 卡片「下载运行库」	设置页模型卡（镜像/代理/进度/清缓存）
插件取用	`host.runtime_dir(id)`	`inspect_model_artifact()["target_dir"]`

宿主运行库（requires_runtime） ​

声明 ​

宿主已知运行库 ​

宿主行为 ​

取用 ​

requires_runtime vs model_artifacts ​

相关 ​

宿主运行库（`requires_runtime`）

声明

宿主已知运行库

宿主行为

取用

`requires_runtime` vs `model_artifacts`

相关