ChroviaChrovia

内置插件安装与开发

将构建后的扩展安装到 Provision，检查 Service Worker，添加工具栏弹出窗口，并更新或移除插件。

SDK 内置插件是从 <Provision 根目录>/Extensions/<插件名> 加载的 Chrome 扩展。内置插件会自动安装；使用 --show-component-extension-options 可在 chrome://extensions 中显示它们。安装插件不会授予它需要的 License 能力。

安装已有插件

  1. 完全退出该浏览器安装目录对应的运行实例。
  2. 获取插件的构建后扩展文件，包括 Chrome manifest.json、JavaScript 和引用资源。先解压，不要直接把 .zip 或 .crx 当作插件目录复制。
  3. 将目录复制到实际 Provision 根目录的 Extensions 下。
  4. 确认 Extensions/my-plugin/manifest.json 直接存在，避免误套一层变成 my-plugin/dist/manifest.json。
  5. 保持提供的目录名，安装所需的 License 能力和 EP 配置，再重新启动。
Extensions/
  chrovia-infra/
    manifest.json
    background.js
  my-plugin/
    manifest.json
    background.js
    popup.html
    popup.js

保留 chrovia-infra 以完成 License 在线续租。其他附带插件以发行包为准，使用前检查 Extensions 目录及对应插件文档。

不要用加载已解压的扩展程序安装 License。以普通方式加载的开发扩展也不会自动获得 Provision Service Worker 身份。本教程使用 Provision 目录安装。

带弹出窗口的最小插件

此例需要 extendedPrefs。弹出窗口只向自己的 Service Worker 请求一个明确操作，不直接读取特权 API。

manifest.json：

{
  "manifest_version": 3,
  "name": "My SDK Plugin",
  "version": "1.0.0",
  "background": { "service_worker": "background.js" },
  "action": { "default_popup": "popup.html" },
  "toolbar_pin": "default_pinned"
}

toolbar_pin: "default_pinned" 会在每次加载 Provision 插件时固定工具栏图标；手动取消固定后，重启时也会再次固定。仅为实际使用的 Chrome API 和外部域名添加标准权限或 host_permissions。

background.js：

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (sender.id !== chrome.runtime.id || message?.type !== 'read-label') {
    return;
  }
  const prefs = globalThis.chrovia?.prefs;
  if (!prefs) {
    sendResponse({ error: 'extendedPrefs unavailable' });
    return;
  }
  prefs.get('internal.instance_appearance.label').then(
    label => sendResponse({ label: typeof label === 'string' ? label : '' }),
    () => sendResponse({ error: 'Unable to read label' }),
  );
  return true;
});

popup.html：

<!doctype html>
<html>
  <body>
    <p id="label">Loading...</p>
    <script src="popup.js"></script>
  </body>
</html>

popup.js：

chrome.runtime.sendMessage({ type: 'read-label' }).then(
  result => {
    document.getElementById('label').textContent = result.error || result.label || 'No label';
  },
  () => {
    document.getElementById('label').textContent = 'Service Worker unavailable';
  },
);

按实例外观配置标签。读取字段需要 extendedPrefs，显示浏览器徽标还需要 instanceAppearance。渲染文本使用 textContent，不要向任意消息开放通用特权方法分发器。

验证安装

使用 --show-component-extension-options 启动，打开 chrome://extensions，启用开发者模式，检查插件的 Service Worker。在其中运行 globalThis.chrovia。根对象缺失通常是上下文或安装位置错误；某个 API 域缺失则应检查其能力。

弹出窗口和扩展标签页默认没有 chrovia。不要只是为了修复 popup 就开启 unrestrictedApi，应使用上面的消息模式。调试实例不要启用 disable_devtools。

更新与移除

更新时保持目录名稳定，在浏览器关闭后替换构建文件，为发布追踪递增扩展清单版本，然后重新启动。只改源码或 Provision 根清单不会更新已安装脚本。核对实际启动的可执行文件，特别是桌面客户端可能解压了自己的浏览器副本。

移除时先退出浏览器，删除 Extensions 下对应的直接子目录，再重新启动。重启后确认插件不再出现在列表中。移除不保证清除全部扩展设置或产品数据。需要租约的发行包不要在缺少有效授权续租集成的情况下移除 Infra。

Service Worker 可能重启，每次脚本执行都应注册处理器，不要只在 onInstalled 中注册。避免多个插件争抢唯一的网络拦截器或同一个启动回复通道。