开发文档插件开发

界面 SDK

插件界面运行在沙箱 iframe 里,通过桌面端内置的 SDK 调用宿主能力。SDK 随桌面端更新,不用安装。

引入

HTML
<link rel="stylesheet" href="pdt-plugin://__kit__/ui-kit.css">
<script type="module">
  import { createBridge } from 'pdt-plugin://__kit__/plugin-sdk.js'

  const bridge = createBridge()
  const { theme, grantedPermissions } = await bridge.ready()
  // ……初始化界面
  bridge.reportAppReady()
</script>

ui-kit.css 提供和桌面端一致的按钮、输入框和明暗主题,可选。需要桌面端 2.2.0 以上,manifest 请写 "minHost": "2.2.0"。

常用能力

JavaScript
// 剪贴板(clipboard.read / clipboard.write)
const text = await bridge.clipboard.readText()
await bridge.clipboard.writeText('hello')

// Toast(notify)
await bridge.toast({ level: 'success', title: '完成' })

// AI(ai.chat):不指定模型时按用户当前工作模式路由
const { content } = await bridge.ai.chat({ prompt: '用一句话总结' })

// 本地 KV(storage.local);云端 KV 用 bridge.cloud.*,用法相同
await bridge.storage.set('prefs', { dark: true })
const prefs = await bridge.storage.get('prefs')

// 调用自己 manifest 里声明的命令,返回 handler 的返回值,失败时抛错
const out = await bridge.commands.run('transform', { text: '{"a":1}', action: 'format' })
命名空间 方法
clipboard readText / writeText
ai chat(一次返回)/ stream + onEvent(流式)/ stop / capabilities
image / video create / get / history
storage / cloud get / set / remove / keys(本地另有 clear)
user profile
commands run(id, input, { timeoutMs }),只能调用自己的命令
其他 toast / hostInfo / invoke(底层调用)

要点

  • ready() 返回当前主题和已授予的权限,SDK 会自动给 <html> 设置 data-theme。
  • 首屏渲染完调用 reportAppReady(),宿主据此判断插件已正常启动。
  • iframe 只有 allow-scripts,没有同源权限,不能用 cookie 或访问宿主页面。
  • 界面能力不够时,把逻辑写成命令脚本,再用 commands.run 调用。旧版桌面端没有它,可以用 bridge.invoke('command.invoke', { command, input }, { timeoutMs }),示例插件里有兼容写法。
  • SDK 只新增方法、不改已有方法的行为,旧插件可以一直用。