Rust 后端

插件需要文件系统、绕开浏览器 CORS 的外部 HTTP、密钥处理、本地进程、长任务或高权限宿主操作时，应使用 Rust 后端。

纯前端插件适合简单 UI 或只消费公开 SDK hooks 的面板。

Cargo 配置

[package]
name = "hf-my-plugin"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
haloforge-plugin-api = "0.2.13"
serde_json = "1"

最小后端

use haloforge_plugin_api::*;

pub struct MyPlugin;

impl MyPlugin {
    pub fn new() -> Self {
        Self
    }
}

impl HaloForgePlugin for MyPlugin {
    fn metadata(&self) -> PluginMetadata {
        PluginMetadata {
            id: "dev.example.my-plugin".into(),
            name: "My Plugin".into(),
            version: "0.1.0".into(),
            description: "A sample HaloForge plugin".into(),
            author: "Example".into(),
            abi_version: PLUGIN_ABI_VERSION,
        }
    }

    fn on_load(
        &mut self,
        _ctx: &dyn PluginContext,
        ipc: &mut dyn IpcRegistrar,
    ) -> Result<(), PluginError> {
        ipc.register("ping", Box::new(|args, _ctx| {
            Ok(serde_json::json!({
                "ok": true,
                "echo": args
            }))
        }))?;
        Ok(())
    }
}

declare_plugin!(MyPlugin, MyPlugin::new);

命令命名

Rust 注册短命令名：

ipc.register("ping", Box::new(|args, _ctx| {
    Ok(serde_json::json!({ "ok": true, "echo": args }))
}))?;

前端调用：

await invokePlugin("ping", { value: 1 });

不要手写最终 wire name，SDK 会按当前 plugin ID 自动加前缀。

外部 HTTP

插件调用用户配置的 API 端点时，如果涉及浏览器 CORS、API key、请求签名、重试、超时或响应归一化，优先通过 Rust 后端请求。

需要外部网络访问时，在 manifest 中声明 network_http 或更窄的 network_http_domain 权限。

日志

Rust 后端应使用 PluginContext 提供的日志入口记录运行诊断：

ctx.log(LogLevel::Info, "image request started request_id=hfis-123 model=gpt-image-2.0 size=1024x1024");
ctx.log(LogLevel::Error, "image request failed request_id=hfis-123 status=502 elapsed_ms=1842");

这些记录会写入 HaloForge 应用日志：~/.haloforge/logs/haloforge.log.YYYY-MM-DD。生命周期、开始和成功事件使用 Info；可恢复降级使用 Warn；用户操作失败使用 Error。Debug 和 Trace 需要应用以对应 RUST_LOG 启动。

不要记录 API key、bearer token、完整 prompt、文件内容、原始图片字节或 base64 payload。优先记录 request ID、端点类型、模型、尺寸、状态、耗时和输出数量。