MIP DESKTOP · 扩展开发
Host、WebView 与 SDK
在正确的运行环境中调用公开能力，并管理扩展生命周期。
@mip/desktop-extension-sdk 封装扩展公开契约。Host 端使用 /host，页面使用 /webview；两者访问的上下文与返回值约定不同。
获取 SDK
扩展 SDK 和配套协议包目前按平台实际交付方式获取，不假定公共 npm 已发布。应向发布方获取匹配版本的已构建包、版本说明和目标宿主要求。
获得 .tgz 后，可按实际文件名安装。下面的文件名是交付方式示意：
npm install ./vendor/mip-desktop-protocol-<version>.tgz ./vendor/mip-desktop-extension-sdk-<version>.tgz
SDK 应由扩展自己的构建工具打包到 Host 和页面资源中；安装后的扩展不依赖开发机目录或在线 npm。若暂未拿到正式 SDK，可先完成 基础 Bridge 示例。
在 Host 中注册命令
import { createHostSdk } from '@mip/desktop-extension-sdk/host';
export async function activate(context) {
const sdk = createHostSdk(context);
sdk.commands.register('mip.example.notes.open', () =>
sdk.window.showView('mip.example.notes.home')
);
}
这个源文件使用 ESM，交付前须由构建工具生成 CommonJS Host 入口，并把 SDK 内联到产物。Manifest 的 main 应指向该产物。
激活阶段只注册必要能力，较重的数据加载放到实际使用时执行。命令 ID 还应在 Manifest 中声明。
在 WebView 中使用 SDK
import { createExtensionSdk } from '@mip/desktop-extension-sdk/webview';
const sdk = createExtensionSdk();
if (!sdk.isEmbedded) {
// 显示浏览器预览状态，不发起依赖宿主的请求。
} else if (sdk.capabilities.has('storage')) {
const response = await sdk.storage.get<string>('note');
if (response.code === 1) {
console.log(response.data);
} else {
console.error(response.message);
}
}
isEmbedded 表示存在扩展 Bridge，不证明当前已经登录。capabilities.has() 只探测接口是否存在，不能替代 Manifest 权限或实际调用结果。
正确理解命令返回值
| 位置 | 调用形式 | 返回约定 |
|---|---|---|
| WebView | sdk.commands.execute(command, argsArray) |
检查外层 code，业务值在 data |
| Host | sdk.commands.execute(command, ...args) |
返回业务值，失败通过 Promise 拒绝 |
const response = await sdk.commands.execute('mip.example.notes.open', []);
if (response.code !== 1) {
throw new Error(response.message || '命令调用失败');
}
业务值本身可以含有 code/data。不要按字段名称反复解包；后台代理 API 也应按各自公开返回类型处理。
管理生命周期
主题、身份等监听应在页面卸载时取消。SDK 提供生命周期集合，Host 自定义资源则加入宿主 context.subscriptions。
const stop = sdk.theme.onDidChange(theme => {
document.documentElement.dataset.theme = theme.resolved;
});
sdk.lifecycle.add(stop);
window.addEventListener('pagehide', () => {
void sdk.lifecycle.dispose();
}, { once: true });
停用扩展后，不应继续保留定时器、长连接或后台任务。使用截图、导航、AI 等可选能力前，确认目标版本并做好能力不可用的处理。
基础契约：Extension API 1.x；具体能力以目标 Desktop 发行版为准。