前端挂载点

插件可以在 WebUI 的固定位置挂载自己的界面。界面是标准的 Web Component（custom element）：一个 ES module 定义元素，AB 创建它并传入 host 与 context。不依赖任何前端框架；想用 Vue、Lit 等，自己打包进模块即可。

清单

[[plugin.ui]]
slot = "bangumi.detail.tab"
element = "ab-plugin-manual-pick"
entry = "web/index.js"
title = { zh-CN = "手动选种", en-US = "Manual pick" }

• slot：挂载点，见下表。
• element：custom element 名。必须是 ab-plugin-<插件 id>，或以 ab-plugin-<插件 id>- 开头。命名空间归插件所有，插件不能定义别人的元素名。
• entry：定义该元素的 ES module，位于 web/ 下。
• title：按语言的标题，至少一种语言。用作标签页、页面标题或设置分区名。

清单不合法时整个插件被拒绝加载。ab-plugin validate 会检查入口文件是否存在。

挂载点

slot	位置	context
settings.section	设置页分区列表末尾，侧栏与搜索可见	{}
bangumi.detail.tab	番剧编辑弹窗里多一个标签（有插件标签时才显示分段控件）	{ bangumiId }
bangumi.card.action	番剧卡片标题下的操作条	{ bangumiId }
page	侧边栏多一个入口，路由 /plugins/<id>；页面标题取清单标题	{}
dashboard.widget	番剧列表页顶部的网格	{}

移动端底部导航没有插件页入口，手机上只能直接访问地址。

组件与 AbHost

AB 先设置 host 和 context 属性，再把元素插入文档，所以 connectedCallback 里可以直接使用它们。

class MyWidget extends HTMLElement {
  async connectedCallback() {
    const root = this.attachShadow({ mode: 'open' });
    root.innerHTML = `<button>${this.host.i18n.locale}</button>`;
    root.querySelector('button').onclick = async () => {
      const data = await this.host.api.get('stats');      // /api/v1/plugins/<id>/stats
      this.host.toast(JSON.stringify(data));
    };
    this.off = this.host.events.on('my-plugin.changed', () => this.refresh());
  }
  disconnectedCallback() { this.off?.(); }
}
customElements.define('ab-plugin-my-plugin', MyWidget);

成员	说明
host.pluginId	插件 id
host.api.get/post/put/delete	带登录态的请求，返回已解析的 JSON，非 2xx 时 reject。不以 / 开头的路径相对 /api/v1/plugins/<id>/；以 /api/v1/ 开头的宿主 API 只允许 GET（公开只读，含其它插件的 GET 路由）
host.i18n.locale	当前语言，如 zh-CN、en-US
host.i18n.t(key, params?)	翻译宿主文案；找不到时返回 key
host.theme.mode / host.theme.tokens	深浅色与 --ab-* 变量的当前值，随主题实时变化
host.toast(message, kind?)	弹出提示（info 或 error）
host.events.on(kind, callback)	订阅事件总线上的事件，回调收到事件字段；返回取消订阅函数。组件卸载时 AB 也会取消

路径越界（..、//host、完整 URL）会被拒绝。这是防误用的边界，不是安全边界：组件与主站同源，等同于插件拥有完整权限。请求默认不弹错误提示，由插件自己决定如何展示。

样式

AB 把组件放进 Shadow DOM 包裹层隔离全局样式，并注入主题变量（--ab-color-primary、--ab-color-surface、--ab-color-text、--ab-radius-sm、--ab-font-mono 等，完整列表见 @autobangumi/plugin-ui 的 tokens.css）。不做构建的组件直接用 var(--ab-…)。深浅色自动切换。

构建模板

不想手写原生模块时，用工作区包 @autobangumi/plugin-ui（webui/packages/plugin-ui/，不发布到 npm）：

• src/index.ts：AbHost、AbPluginElement、AbSlotContext 等类型。
• tokens.css：主题变量。
• template/：Vite 库模式模板，输出单文件自包含 ES module 到 ../web/index.js，把 tokens.css 内联进 Shadow DOM。把它复制到你的插件里，改元素名即可。

约束

• CSP：AB 的页面带 Content-Security-Policy: script-src 'self'。模块必须来自 AB 自己的地址（/api/v1/plugins/<id>/web/...）；不能用内联脚本、eval 或第三方 CDN 的脚本。图片、样式和网络请求不受限。
• 静态资源：web/ 目录由 GET /api/v1/plugins/<id>/web/<路径> 提供，要求登录，只服务已启用的插件，拒绝目录外的路径和符号链接。因此插件的 api_router 不能使用 web/ 前缀。
• 错误边界：模块导入失败、元素未定义、组件里抛出的未捕获错误，都只让该插件的挂载点显示「插件组件加载失败」，页面与其它插件不受影响。没有重试按钮，重新打开页面会重新导入。
• 缓存：模块带 Cache-Control: no-cache，升级插件后按 ETag 重新验证。

完整的可运行例子是 examples/plugins/manual-pick/：详情页标签，经宿主只读 API 列出种子，经插件自己的路由保存选择，并用 host.events.on 在别处选种后刷新。