核心 API（wad.*）

先记住一件事：三个上下文里的 wad 不是同一个对象。同名方法的行为、同步/异步、可用范围都不一样。

能力	面板	逻辑层	渲染层
id / name / version	✅	✅	✅
appid	✅	✅	✅
plugin（完整 meta）	✅	—	—
ready / connected	✅	—	—
on / emit	✅	✅	✅
off	✅	✅	—
register	—	✅	—
logic.call	Promise	同步	Promise（参数是数组）
logic.eval	Promise	同步	—
logic.page	Promise	同步	—
render.eval	Promise	投递（返回 null）	同步
render.dom	—	—	✅
ui.* 组件库	✅	仅 toast	仅 toast
http.*	宿主代理	wx.request	—
storage.*	异步	同步	—
net.*	异步	同步 records	—
asset	—	✅	✅
loadWasm	原生 WebAssembly	✅	✅
loadScript	—	⚠ 沙箱可能禁用	✅
loadCss	—	—	✅

身份

面板

wad.id              // 插件 id
wad.plugin          // { id, name, version, author, description, ... }
wad.appid           // 当前小程序 appid
wad.version         // SDK 版本（'2.0'）
wad.plugin.version  // 插件版本

逻辑层 / 渲染层

wad.id        // 插件 id
wad.name      // 插件名
wad.version   // 插件版本（注意：不是 SDK 版本）
wad.appid     // 当前小程序 appid
wad.appidOf() // 逻辑层：同上，函数形式

两个 version

面板的 wad.version 是 SDK 版本；逻辑层 / 渲染层的 wad.version 是 插件版本。要拿插件版本，在面板里用 wad.plugin.version。

就绪与连接（面板）

wad.ready.then(function () {
  wad.log('bus online');
});

if (!wad.connected()) {
  // 断线重连中（1.5s 一次）
}

ready 在总线首次连上后 resolve，结果缓存；断线重连后会再次可用。

本地信息

// 面板
wad.info();      // { id, appid, plugin }
wad.instance();  // { id, pluginId, appid, version, role: 'panel' }

// 逻辑层 / 渲染层
wad.instance();  // { id, name, version, appid, role: 'logic' | 'render', page }

role 可以用来写同一份代码在不同上下文里的分支。

通用 RPC（面板）

wad.call('logic.call', 'add', 1, 2);
wad.call('net.records', 20);

约束	值
超时	6 s（TIMEOUT）
单帧上限	200 KB（SEND_FAILED）
返回值	必须 JSON 可序列化

日志

wad.log('hello', { a: 1 });

参数会逐个 String() 拼接，写入 App 的「插件」日志面板；逻辑层与渲染层还会同步到 Chrome Console（如果已连接）。

事件

wad.on('pageChange', fn);
wad.off('pageChange', fn);   // 需要同一个函数引用
wad.emit('my-event', { a: 1 });

完整的生命周期与回调见 生命周期与回调，事件列表见 事件系统。

资源

// 逻辑层 / 渲染层
const url = wad.asset('demo.wasm');

把 zip 里的相对路径转成 /v1/plugins/<id>/file/...。详见 资源与 WASM。

错误

所有 reject 的 Error 都带 code：

e.code	含义
TIMEOUT	6 秒内没有响应
BUS_DISCONNECTED	总线断开
SEND_FAILED	帧过大或序列化失败
HOST_ERROR	宿主返回的未归类错误
CDP_DISABLED	调试通道关闭
LOGIC_UNAVAILABLE	小程序未运行 / 业务上下文不存在
RENDER_UNAVAILABLE	没有可注入的页面 target
NOT_FOUND	请求 id / 资源不存在
PLUGINS_DISABLED	插件全局开关关闭

wad.logic.call('order.find', id).catch(function (e) {
  if (e.code === 'TIMEOUT') wad.ui.toast('逻辑层没有响应');
  else if (e.code === 'CDP_DISABLED') wad.ui.toast('请先开启调试通道');
  else wad.ui.toast(e.message);
});

命名建议

• 事件名加插件前缀：myplugin:refreshed；
• Skill 也用前缀：tokenwatch.scan；
• 一个插件暴露 3~8 个高内聚 Skill，粒度对齐「面板上的一个功能」。

下一步

• 生命周期与回调
• 事件系统
• 资源与 WASM