WebAssembly AI 插件通信：消息协议比函数名更重要

一、插件边界需要协议

WebAssembly 插件常通过宿主导入导出函数进行通信。初学时很容易只关注函数能不能调用，却忽略消息协议。AI 插件往往需要传 prompt、配置、权限、上下文和结果，如果协议不清，宿主和插件很快会互相猜格式。

函数名只是入口，真正稳定的是消息协议。

之前参与一个插件项目，不同团队的插件都叫execute，但各自定义了不同的参数含义。一个插件把input当成 prompt，另一个当成文件路径，还有一个当配置 key。宿主调用时连参数映射都做不对，排查成本很大。

二、定义请求和响应

flowchart TD A[宿主] --> B[请求消息] B --> C[WASM 插件] C --> D[响应消息] D --> A

可以先用 JSON 做协议，等性能成为问题再考虑 MessagePack、CBOR 或自定义二进制格式。

#[derive(serde::Serialize, serde::Deserialize)] struct PluginRequest { task: String, input: String, permissions: Vec<String>, }

协议字段要比函数参数更稳定，因为它能版本化和扩展。

三、错误也要结构化

插件失败时，不要只返回字符串。宿主要知道是参数错误、权限不足、模型超时、内部异常还是版本不兼容。

#[derive(serde::Serialize)] struct PluginError { code: String, message: String, retryable: bool, }

retryable很有用。AI 请求超时可能可重试，权限不足则不应该重试。

实战踩坑：插件有一个版本只返回err: "failed"字符串，连错误码都没有。宿主遇到这个错误只能笼统提示用户"操作失败"。后来上游服务挂了，用户反复重试导致请求堆积，但插件没有返回retryable: false，宿主也无法做限流。加上了结构化错误后，这类问题就不会被误重试了。

四、协议版本要前置

WASM 插件一旦分发出去，就可能出现宿主和插件版本不一致。请求里应该带协议版本，插件也应该声明自己支持的版本。

plugin_protocol: version: 1 min_host_version: 1 capabilities: - summarize - classify

如果版本不兼容，宿主要优雅拒绝，而不是运行到一半崩掉。

边界场景：有一次宿主升级了协议版本 v2，但部分老插件仍用 v1。请求发过去后，v2 新增的context字段被 v1 插件丢弃。插件没报错，结果也没异常，但回答质量明显下降。事后加了版本协商：请求头带版本号，不兼容时宿主要给明确错误提示。

还要限制消息大小。AI 上下文很容易越塞越多，跨 WASM 边界复制成本不低。协议里定义最大输入长度，比出了 OOM 再排查强很多。

最后，协议要写测试。固定请求经过插件后，响应字段和错误码应该稳定。插件系统靠约定运行，测试就是约定的护栏。

协议还要考虑流式输出。AI 插件可能不是一次性返回完整结果，而是持续返回 token、进度或中间状态。此时响应协议要能表达delta、done、error，宿主也要能处理中途取消。

stream_message: type: delta sequence: 12 content: "partial text"

如果插件运行在沙箱中，权限也应该写进协议。插件声明自己需要网络、文件读取或模型调用能力，宿主根据策略授权。不要让插件通过隐式导入获得过宽能力。

跨语言互操作时，还要规定字符串编码和数字精度。JavaScript、Rust、Go 对大整数和二进制数据的处理方式不同，协议不写清楚，边界 bug 会很难查。

最后，协议文档要和代码一起发布。插件作者不能靠读宿主源码猜字段含义，稳定生态从一份清楚的协议开始。

调试工具也要跟上。宿主可以提供一个协议检查命令，读取插件声明并发送样例请求，确认版本、能力、错误格式和消息大小限制都符合预期。这样插件问题能在接入前暴露，而不是运行时才发现。

五、总结

WebAssembly AI 插件通信要定义请求、响应、错误、版本、能力和消息大小限制。

消息协议比函数名更重要。边界清楚，插件才敢扩展。