API

版本查询与本机环境自检。Provider 安装见 ensure。

功能概览

类别	属性	类型	访问	说明
版本	version	u32	函数	打包版本 major*65536 + minor*256 + patch。线程安全，不会失败
	version_string	&'static str	函数	形如 "1.0.0+runtime" 的静态字符串。禁止释放
	version_major	u32	函数	拆打包版本的 major
diagnostics	diagnostics::collect	Result<String, Error>	函数	本机环境诊断 JSON（去敏）。禁止放进 PLC 扫描周期
	diagnostics::collect_json	Result<Value, Error>	函数	同 collect，feature json 下解析为 serde_json::Value

版本

version()

pub fn version() -> u32

打包版本 major*65536 + minor*256 + patch。线程安全，不会失败，无错误槽改动。

返回值:

• u32 — 打包版本

version_string()

pub fn version_string() -> &'static str

形如 "1.0.0+runtime" / "1.0.0+authoring" 的静态字符串。进程生命周期有效，禁止释放。客户机必须看到 +runtime。

返回值:

• &'static str — 版本字符串

version_major()

pub fn version_major(packed: u32) -> u32

拆打包版本的 major。绑定侧核对：运行时 major 必须 == 1，否则 ABI 已破坏，禁止继续调用任何其它函数。

参数:

• packed (u32) — version() 的返回值

返回值:

• u32 — major

示例:

let packed = darra_ai::version();
if darra_ai::version_major(packed) != 1 {
    return Err(darra_ai::Error::Internal {
        message: format!("ABI 不匹配，库版本 = {}", darra_ai::version_string()),
        hint: "Darra.AI SDK 与 DarraAI.Core 升到同一发布批次后重试。".to_string(),
    });
}

诊断

diagnostics::collect()

pub fn collect() -> Result<String, Error>

采集本机环境诊断，输出统一 JSON。覆盖：os/arch、CPU、GPU 型号 + 驱动版本 + CUDA 上限、已装 Provider 及版本、授权状态（去敏：绝不含密钥 / 密码 / token / 机器指纹字节）、最近错误环形缓冲（去敏）。

• 尽力而为：单个字段采不到时 JSON 中该字段为 null 或缺席，整体不失败；只有彻底无法采集才返回 Error::Internal。
• 注意：可能触发 WMI / NVML / sysfs 查询，耗时可到数百毫秒——禁止在 PLC 扫描周期等实时路径调用。

返回值:

• Result<String, Error> — UTF-8 JSON

示例:

use darra_ai::diagnostics;

match diagnostics::collect() {
    Ok(j) => eprintln!("[diag] {j}"),
    Err(e) => eprintln!("[diag] 采集失败: {e}"),
}

diagnostics::collect_json()

#[cfg(feature = "json")]
pub fn collect_json() -> Result<serde_json::Value, Error>

同 collect，feature json 下解析为 serde_json::Value。默认 feature 已打开 json。

返回值:

• Result<serde_json::Value, Error> — 解析后的诊断 JSON