快速开始

30 秒上手

插件就是一个 HTML 文件。三段脚本各跑各的上下文：

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="wad:package" content="my-first">
  <meta name="wad:name" content="我的第一个插件">
  <meta name="wad:version" content="1.0.0">
  <meta name="wad:author" content="you">
  <meta name="wad:description" content="三上下文演示">
</head>
<body>
  <!-- ① 面板：浮窗 WebView 里跑（有 wad SDK，无 wx） -->
  <button id="go">调逻辑层</button>
  <script src="/ui/plugin-sdk.js"></script>
  <script>
    wad.ready.then(function () {
      document.getElementById('go').onclick = function () {
        wad.logic.call('add', 1, 2).then(function (r) {
          wad.ui.toast('1+2=' + r);
        });
      };
    });
  </script>

  <!-- ② 逻辑层：appservice V8 里跑（有 wx，无 DOM） -->
  <script type="text/wad-logic">
    wad.register('add', function (a, b) { return a + b; });
  </script>

  <!-- ③ 渲染层：当前页面 XWeb 里跑（有 DOM，无 wx） -->
  <script type="text/wad-render">
    wad.render.dom(function (doc) {
      var t = doc.createElement('div');
      t.textContent = '插件已注入';
      doc.body.appendChild(t);
    });
  </script>
</body>
</html>

安装

• App 内：开发者工具 → 插件 → 右上角「+」→ 粘贴 HTML / 远程 URL / 本地文件；
• 插件市场：管理员在后台上传，客户端一键安装 / 更新；
• 小程序浮窗：打开任意小程序 → 右上角「…」→「插件」。

安装时会先做语法预检：所有内联脚本用 new Function(src) 编译一遍，SyntaxError 直接拒绝（E_SYNTAX），不会落盘。

meta 字段

字段	必填	说明
wad:package	是	唯一包名，[A-Za-z0-9][A-Za-z0-9._-]{0,63}；同包名升级覆盖
wad:id	否	旧字段，package 缺省时参与推导
wad:name	否	显示名，默认「未命名插件」
wad:version	否	版本名，默认 1.0.0
wad:versionCode	否	整数版本号，市场判断更新用，默认 1
wad:author	否	作者
wad:description	否	一句话介绍
wad:logo	否	data: URL（≤128KB）/ http(s) 图片 / zip 内文件名

README 可以放在 zip 根目录的 README.md，或者在单 HTML 里写 <script type="text/markdown">…</script>。

硬限制

项	限制
单文件 HTML	≤ 2 MB
text/wad-logic / text/wad-render	各 ≤ 256 KB
同时启用插件	≤ 120 个
单条总线消息	≤ 256 KB
外部 <script src>	不执行；需要外部脚本请用 wad.loadScript（渲染层）
zip 资源	总量 8 MB，单资产 4 MB，支持 wasm / css / js / 图片

调试

• wad.log(...) 写到 App「插件」页的日志面板，同时进 console；
• 运行时异常只影响当前插件：同一代连续失败 2 次自动停止注入，下一代重试；
• 面板固定亮色主题，宿主会注入 /ui/plugin-base.css，你可以只写业务样式。

目录建议

my-plugin/
├── plugin.html     # 入口（必需）
├── logo.png        # 图标（可选）
└── README.md       # 详情页说明（可选）

打包成 zip 后直接安装（wad:logo 可以写 zip 内的文件名）。zip 里的其它文件会作为资产提供，路径与加载方式见 资源与 WASM。

下一步

• 核心 API
• 事件系统
• 逻辑层 · 渲染层