# @get-bb/plugin-sdk 中文文档

规范地址：https://npmcn.com/package/%40get-bb/plugin-sdk/

版本：0\.6\.144
npm 元数据更新时间：2026-11-14T16:56:43.502Z
中文译文更新时间：2026-11-16T05:39:15.142Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40get-bb/plugin-sdk
原文对照：https://npmcn.com/package/%40get-bb/plugin-sdk/?lang=original
项目主页：https://github.com/get-bb/bb#readme
源码仓库：https://github.com/get-bb/bb

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.5 MB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：hono ^4\.11\.9，react ^19\.0\.0，react-dom ^19\.0\.0，cron-parser ^5\.5\.0，@types/react ^19\.0\.0，better-sqlite3 \>=12，@types/better-sqlite3 ^7\.6\.12，@testing-library/react ^16\.3\.2
- 首次发布：2026-08-14T04:59:40.680Z
- 最新版本发布：2026-11-14T16:56:43.096Z
- 近 30 天下载量：406396（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：96（近 12 个月 96 个）

## 中文简介

已键入的外观 BB 插件作者正在编译 。 根会保存完整 `BbPluginApi` 财务报告和审定财务报表 `BbSdk` 合同; `./app` 是前端运行时间 `bb plugin build` 替换为 BB 共享执行.

## 安装

```sh
npm install @get-bb/plugin-sdk
```

也可以使用：`pnpm add @get-bb/plugin-sdk`、`yarn add @get-bb/plugin-sdk`、`bun add @get-bb/plugin-sdk`

## README

# @ get-bb/ plugin- sdk

已键入的外观 BB 插件作者正在编译 。 根会保存 完整 `BbPluginApi` 财务报告和审定财务报表 `BbSdk` 合同; `./app` 是前端运行时间 那个 `bb plugin build` 替换为 BB 共享执行.

权威合同是: [`src/backend-contract.ts`](https://npmcn.com/package/%40get-bb/plugin-sdk/src/backend-contract.ts) 财务报告和审定财务报表 [`src/app-contract.ts`](https://npmcn.com/package/%40get-bb/plugin-sdk/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` 引用插件](https://npmcn.com/package/examples/plugins/composer-customization/README.md) 在一个小应用中,每个区域都有。 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` 引用插件](https://npmcn.com/package/examples/plugins/content-script/README.md) 用于清洁安全编辑器的增强.

## 外部插件测试

包包包括可执行的 JavaScript 和可移植声明 页:1 `@get-bb/plugin-sdk/testing` 财务报告和审定财务报表 `@get-bb/plugin-sdk/testing/app`; 两个子路径 在运行时导入 BB 工作空间包或源类型Script。 安装 SDK 与您的插件使用的测试堆栈( 端点依赖性是可选的, 所以 无头插件不安装浏览器套接字 :

```sh
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
```

后端实例 :

```ts
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`:

```tsx
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` 保持这些新鲜 直到他们迁移.

## 常见问题

### @get-bb/plugin-sdk 是什么？

已键入的外观 BB 插件作者正在编译 。 根会保存完整 BbPluginApi 财务报告和审定财务报表 BbSdk 合同; \./app 是前端运行时间 bb plugin build 替换为 BB 共享执行\.

### 如何安装 @get-bb/plugin-sdk？

在项目目录运行 npm install @get-bb/plugin-sdk，或使用 pnpm add / yarn add / bun add。

### @get-bb/plugin-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @get-bb/plugin-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @get-bb/plugin-sdk 可以商用吗？

@get-bb/plugin-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @get-bb/plugin-sdk 的下载量有多少？

根据 npm 官方下载统计，@get-bb/plugin-sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 406,396 次，日均约 13,547 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @get-bb/plugin-sdk 还在维护吗？

最新版本 0\.6\.144 发布于 2026/11/15（1 天前）；至今共发布 96 个版本，其中过去 12 个月发布了 96 个；首次发布于 2026/08/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

