@ get-bb/ plugin- sdk
已键入的外观 BB 插件作者正在编译 。 根会保存
完整 BbPluginApi 财务报告和审定财务报表 BbSdk 合同; ./app 是前端运行时间
那个 bb plugin build 替换为 BB 共享执行.
权威合同是:
src/backend-contract.ts 财务报告和审定财务报表
src/app-contract.ts。保持给作者的指导
内置 bb-plugin-authoring 技能与这些声明同步.
作曲家定制
编译器 UI 扩展寄存器 app.composer.customize(...)A级
ComposerCustomization 可以贡献反应动作和横幅组件,
主机已交付 ComposerPlusMenuItem 财务报告和审定财务报表 ComposerSendMenuItem 横行,和
ComposerRichTextSpec 规则。 已挂载组件使用 useComposer()页:1
写作者文本的稳定手柄 引用 选择 范围,
排版、运行和提交状态、写作、效果和输入锁定。 选择是
反应并正在 null 作曲家没有拾取者。 面板和页
写入用户选择使用的作曲家 useComposers(),每个手柄
作曲在屏幕上.
任何挂载的插件组件都可以调用 experimental_useAppPanel() 联 合 国
它在表面( 线程视图、 插件页面或
新线条屏幕). openTab({ tab, target?, params?, title? }) 选择其中之一
已注册的插件 experimental_tab 选项卡; 在新线程屏幕上 a
线程- 折叠动作标签解析 experimental_newThreadPanelAction
同样的身份证明. toggleTab(options) 标签时关闭面板
显示或以其他方式打开它 close() 关闭面板。 命令 :,
线程动作、消息动作和面板动作收到相同的控制器
作为 experimental_panel。 。 。 .
使用 UrlLink 用于应用 BB 电流的正锚
普通 HTTP( S) 激活时的 in- app/ 外部浏览器偏好, 或
useBbNavigate().openUrl(url) 用于按钮或菜单。 内部应用程序
路径、 修改器点击、 明确的锚定目标、 和不支持的计划都保留
浏览器拥有 。 A 类 _blank 或指定目标保存 rel 不过
添加 noopener noreferrer 除非 rel 明确包含 opener,所以一个
新打开的页面无法意外控制 BB 。 前端的吊带记录
两种表格在 navigateCalls 并接受 openUrl 行为选择.
使用 experimental_FileLink 明确工作空间、宿主或
线程存储文件 。 普通激活打开共享的 BB 预览及其
上下文菜单显示内置/插件查看器,首选的外部打开,以及
复制动作。 有效的目标显示一个编码的 安全计划的主锚
修改器点击、下载和复制链接,无法将文件名称重新解释为
外部 URL 方案。 错误的运行时间目标——包括出轨路径
且 Unicode 格式不齐全的 Unicode - 没有活动色调, 无法在
前端系带。 按钮和菜单可以调用
experimental_openFilePreview({ target, location }) 或者说
experimental_openFileExternally({ target, location }); 两者是否都返回
目前的主机接受了这个意图。 过 opener: "<id>" 改为
experimental_openFilePreview 用自己的文件显示文件
fileOpener 该打开的注册, 如“ 打开” 菜单所做的。 这个
experimental_useCanOpenFileExternally(target) 钩子报告是否
外部打开后现在可以成功(装入时假冒)并重新发送
组件; 用于禁用 Open 外部控制.
目标永远不会推断一个环境工作空间.
前端绑带记录两种方法并接受 openFilePreview, (中文(简体) ),
openFileExternally,以及 canOpenFileExternally 行为选择.
要显示您的用户界面旁边的终端, 请创建它 useSdk().terminals.create
在您想要的线程、 环境或主机目录中, 然后调用
useBbNavigate().experimental_openTerminal({ terminalId })它决定
当前表面是否选择了终端标签; 线程表面是否接受
只有他们自己的线程终端。 绳子记录了电话 并接受了
openTerminal 行为选择.
给定标签( 线程或导航板) a experimental_target.validate 类型
警卫,呼叫 experimental_useAppPanel().openTab({ tab, target }),并读取
选项卡内的状态 experimental_useFixedTabTarget(tab)。目标在标签、面板和
当前应用程序会话的路由重新挂载; call clear() 当标签返回时
进入其非目标状态。 主办方在业主类型守护前验证了JSON,
选项卡或无效的选项卡
目标。 前端拉带记录每个控制器的呼叫
experimental_panelCalls,接受 experimental_panel 行为,并且可以
种子 experimental_fixedTabTarget 状态.
每个控制器调用报告的方式相同: true 当主人接受了它的时候,
false 当它下降时(非JSON) target 或者说 params,插件的标签
或没有侧面板的表面)。 下降是回报值,永远不会
一个出错, 因此注册几种动作的插件可以共享一个
在结果上打开常规和分支.
使用 app.slots.experimental_appOverlay({ id, component }) 用于添加剂,
应用宽浮回放 UI. BB 在每个应用程序窗口中挂载组件一次
普通插件槽边框,所以 SDK 钩子和插件 CSS 工作和反应
上下文存在于门户中。 此应用程序级边界包括侧边栏线
数据与动作钩。 钩子,其合同要求特定的表面,
包括 useComposer,仍限于地表.
该插件拥有覆盖的铬,定位,能见度,焦点,以及
反应性行为; 崩溃的覆被隐藏而不影响兄弟姐妹.
使用内容脚本用于应用全局的DOM行为不需要回放上下文.
见
composer-customization 引用插件
在一个小应用中,每个区域都有。 1.0之前的贬值
app.slots.composerAccessory(...) 页脚 API 已被删除; 迁移页脚
对动作或附加菜单的控制,对横幅的控制.
信任的前端内容脚本
使用 app.contentScripts.register({ id, mount }) 普通项目
捆绑的 TypeScript/ JavaScript 不渲染而增强 bb 应用程序外壳
a 反应槽。 东道方用品 { pluginId, generation, signal },等待着
挂载设置, 并拥有终止操作和整个散列的精确逆序处理
重新装入,禁用,去除,替换失败,以及应用窗口被撕毁. 旧的
世代相传 世代相传.
内容脚本是信任的同源页面代码,而不是沙盒.
静态样式应保留在正常导入的 app.css。主机保留
当插件提供了槽、面板标题或
a. 门户UI,以及任何活动内容标注生成的全部寿命;
这不是一个全应用的样式表钩。 使用表单 bb.themes 条目
应用全局可选调色板 CSS. 设计或装饰已存在的 app- shell DOM
属于内容脚本,脚本可能只拥有动态 DOM/样式节点
当他们的处置者清除他们的时候。 见
content-script 引用插件
用于清洁安全编辑器的增强.
外部插件测试
包包包括可执行的 JavaScript 和可移植声明
页:1 @get-bb/plugin-sdk/testing 财务报告和审定财务报表 @get-bb/plugin-sdk/testing/app; 两个子路径
在运行时导入 BB 工作空间包或源类型Script。 安装 SDK
与您的插件使用的测试堆栈( 端点依赖性是可选的, 所以
无头插件不安装浏览器套接字 :
npm install --save-dev @get-bb/plugin-sdk vitest better-sqlite3 cron-parser hono
npm install --save-dev react react-dom @testing-library/react jsdom # frontend tests
后端实例 :
import {
createFakePluginHost,
makePluginAgentConfigurationContext,
} from "@get-bb/plugin-sdk/testing";
import plugin from "./server.js";
const host = createFakePluginHost({ pluginId: "notes" });
await plugin(host.bb);
await host.harness.behavior.resolveAgentConfiguration(
makePluginAgentConfigurationContext({
provider: { id: "codex" },
}),
);
await host.harness.behavior.callRpc("list", { query: "today" });
expect(host.harness.inspection.registrations.rpcMethods).toContain("list");
await host.harness.lifecycle.dispose();
makePluginAgentConfigurationContext, (中文(简体) ), makeMessageDispatchHookContext, (中文(简体) ),
makeHostResponse, (中文(简体) ), makeThreadResponse, (中文(简体) ), makeQueueEntry,以及
makeTurnFailedEvent 返回时
完全确定 SDK 对象。 传出部分的覆盖, 这样的行为
测试仅显示与其情景相关的值。 内嵌上下文
成员在完全违约的情况下合并部分超标,因此要求的合同
共享固定装置中添加的部分仍然是局部的.
harness.behavior 包含确定主机输入(RPC/HTTP/CLI调用,
事件、设置、工具、互动和时间表, harness.inspection
包含登记和记录状态,以及 harness.lifecycle 拥有原子
重装和处置。 先前存在的每个直接成员仍作为下列机构的别名:
源兼容性。 一个成功的 reload(factory) 保存设置, KV,
和数据库状态,并仅在替换后无效旧 API
工厂成功;一个倒闭的工厂让旧负载活下来.
前端示例( E)// @vitest-environment jsdom:
import {
loadPluginApp,
mountPluginContentScripts,
renderSlot,
} from "@get-bb/plugin-sdk/testing/app";
const app = await loadPluginApp(() => import("./app.js"));
const scripts = await mountPluginContentScripts(app, { pluginId: "notes" });
const slot = renderSlot(
app.homepageSections[0]!,
{ projectId: "proj_1" },
{
rpc: { list: () => [] },
context: { projectId: "proj_1", threadId: null },
},
);
await slot.behavior.emitRealtime("notes-changed", null);
expect(slot.inspection.rpcCalls).toHaveLength(1);
slot.lifecycle.unmount();
await scripts.lifecycle.dispose();
loadPluginApp 安装运行时间并验证所有注册; 通过
导入模块或 tunk . @get-bb/plugin-sdk/app 导出看起来运行时间
当它们被调用或调出时会上升,所以静态导入 app.tsx 或
组件也起作用. mountPluginContentScripts 镜像主机的订单上,
后回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回. renderSlot 用品
RPC,实时,设置,导航,上下文,和范围作曲行为,
然后返回测试库查询加相同的行为/检查/生命周期
拆分;它也会安装运行时间。 打电话 installTestPluginRuntime() 你自己来
仅当测试生成插件组件时 renderSlot。 。 。 .
菲德尔界限
后端假的匹配可观察到的 schema-RPC 验证/错误和严格
JSON结果,添加剂事件,按键注册故障,原子重载,
设置、 KV/ 数据库存储、 有条件的代理配置、 请求输入、,
和处置令。 HTTP运行于Hono,但不执行 BB 本地或
符号认证 。 背景服务和时间表仅在驱动时运行;
没有重新开始的计时器或克龙扫描。 存储为进程本地化
临时目录,秘密保存在记忆中, bb.sdk 永远被束缚
直通电话 交叉插座/全球碰撞政策不在其中
假主机 .
前端吊带匹配注册验证、内容标记挂载和 清理命令, RPC/实时 JSON 边框、面板和槽道具、导航记录和作曲文本, 范围,引用,提及,焦点,以及清晰的行为. 它不复制BB 布局、 CSS、 持久性、 路由、 主机认证、 崩溃边界或 多插素仲裁;对这些边界使用活的BB测试.
声明表面
完全的根状使未公布的BB工作空间合同变得平淡.
公开的试验申报 @get-bb/plugin-sdk 将根改为:
嵌入第二个副本, 不声明取决于未公布 @bb/*
软件包。 真正的 npm 类型(hono, (中文(简体) ), better-sqlite3测试
图书馆)仍然是同行进口。 Zod是SDK的运行时间依赖,所以
插件仅在自有源导入时声明. 脚手架插件依赖于此软件包——
bb plugin new 把它完全钉入 devDependencies 读取根/应用程序
直接从 node_modules/@get-bb/plugin-sdk/bundled-types/, (中文(简体) ),
相同的文件 测试子路径重复使用。 之前的插件脚手架
切换仍在销售 root/app 声明的副本 types/ 和地图
@get-bb/plugin-sdk 通过他们 tsconfig.json· ; bb plugin types 保持这些新鲜 直到他们迁移.