# @blackbelt-technology/dashboard-plugin-runtime 中文文档

规范地址：https://npmcn.com/package/%40blackbelt-technology/dashboard-plugin-runtime/

版本：0\.11\.0
npm 元数据更新时间：2026-10-26T11:13:30.849Z
中文译文更新时间：2026-11-08T05:48:46.995Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blackbelt-technology/dashboard-plugin-runtime
原文对照：https://npmcn.com/package/%40blackbelt-technology/dashboard-plugin-runtime/?lang=original
项目主页：https://github.com/BlackBeltTechnology/pi-agent-dashboard#readme
源码仓库：https://github.com/BlackBeltTechnology/pi-agent-dashboard

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

- 包体积（解压后）：660 kB，73 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：vite ^6\.0\.0，react \>=18\.0\.0，wouter ^3\.9\.0，fastify ^5\.0\.0，@tailwindcss/vite \>=4\.1\.0
- 首次发布：2026-04-30T08:58:17.935Z
- 最新版本发布：2026-10-26T11:13:30.466Z
- 近 30 天下载量：1941（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

插件加载器、槽登记器、槽消费者和上下文 Pi-dashboard 的 API

## 安装

```sh
npm install @blackbelt-technology/dashboard-plugin-runtime
```

也可以使用：`pnpm add @blackbelt-technology/dashboard-plugin-runtime`、`yarn add @blackbelt-technology/dashboard-plugin-runtime`、`bun add @blackbelt-technology/dashboard-plugin-runtime`

## README

# @blackbelt-technology/dashboard-plugin-runtime 页面存档备份,存于互联网档案馆 互联网档案馆

插件加载器,槽登记器,槽消费者,插件上下文 API,和pi-dashboard的Vite插件.

## 导入路径

| 路径 | 目录 |
| --- | --- |
| `@blackbelt-technology/dashboard-plugin-runtime` | 槽消费者、登记类型、桶 |
| `@blackbelt-technology/dashboard-plugin-runtime/context` | 已取消的别名(一个未成年人):进口钩子(`usePluginConfig`, (中文(简体) ), `useAllSessions`从根起,只使用 shell names from `./host` |
| `@blackbelt-technology/dashboard-plugin-runtime/server` | 装入器, `ServerPluginContext`配置验证符 |
| `@blackbelt-technology/dashboard-plugin-runtime/vite-plugin` | `viteDashboardPluginsPlugin` |

### 安全内容助手

`randomUuid()` 财务报告和审定财务报表 `copyText(text)` (桶出口)关于Plain-http 局域网起源的工作,地点 `crypto.randomUUID` 财务报告和审定财务报表 `navigator.clipboard` 未定义。 插件 MUST 使用它们而不是赤裸的API(由扫描测试强制). 使用运行时间版本0.9.1(0.9.0后发布);采用它们的插件必须将其运行时间底板提升至该发布. 见变动:审计-插件-捆绑-非安全-文本.

**插件只从这些公共路径导入 .** 从 `packages/client/`, (中文(简体) ), `packages/server/`,或者其他任何内部包被禁用,并且会使林特套件失效.

## 最低运单

添加一个 `pi-dashboard-plugin` 字段到您的软件包 `package.json`数字 :

```json
{
  "name": "@blackbelt-technology/my-feature-plugin",
  "pi-dashboard-plugin": {
    "id": "my-feature",
    "displayName": "My Feature",
    "priority": 100,
    "client": "./dist/client/index.js",
    "server": "./dist/server/index.js",
    "claims": [
      { "slot": "session-card-badge", "component": "MyFeatureBadge" }
    ]
  }
}
```

字段 :

-   `id` ——全球特有克巴布病例编号.
-   `priority` ——多捐款档的排序顺序. 低 = 首发。 默认为1000;先行方=100.
-   `client` ——已建客户端条目的路径(按名称导出反应组件).
-   `server` ——服务器条目的可选路径(导出) `default function registerPlugin(ctx: ServerPluginContext)`) (中文(简体) ).
-   `bridge` —— pi-extension/ bridge 条目的可选路径(自动注册输入) `~/.pi/agent/settings.json` 下级 `dashboard-<id>`) (中文(简体) ).
-   `configSchema` ——用于插件配置验证的 JSON Schema 7 文件的可选相对路径.
-   `claims` ——槽数申报.

## 槽量索赔

每项索赔都针对一个槽:

```json
{ "slot": "session-card-badge", "component": "MyBadge" }
{ "slot": "tool-renderer", "toolName": "MyTool", "component": "MyToolRenderer" }
{ "slot": "command-route", "command": "/myfeature", "component": "MyFeatureView" }
{ "slot": "anchored-popover", "trigger": "my-trigger-button", "component": "MyPopover" }
{ "slot": "settings-section", "component": "MySettings", "tab": "general" }
```

### `settings-section` 安置情况

每个 `settings-section` 在自有插件的自有页面上, `/settings/plugins/<id>`在宿主拥有的铬下 这页列在下面 页:1 **插件** 启用插件时的导航条目 .

`tab` 实值 **惰性**: 为后向相容性接受(任何字符串,无) 警告),无字可读. 它不选择设置页面 .

### `settings-section` 导航提示

权利要求可能要求主机将插件的页面 ProMOTE 插入到设置导航组中 :

```json
{
  "slot": "settings-section",
  "component": "BuiltInRolesSettings",
  "nav": { "group": "models", "label": "Model roles", "description": "Pick which model answers each @role.", "order": 1000 }
}
```

| 外地 | 规则 |
| --- | --- |
| `group` | 需要,修整后不为空。 仅 `models` ; 未知值被接受并被忽略(向前-相容). |
| `label` | 需要,非空,在 NFKC + 修剪后为 40 个字符。 铁路标签+页名. |
| `description` | \-200个字符。 页面线索。 空虚 独自掉下. |
| `order` | 可选限定数,默认为1000。 在组内排序密钥( 独立于显示 `priority`) (中文(简体) ). |

-   只放置: URL 保留 `/settings/plugins/<id>`;没有授予任何能力.
-   无效的提示( 非对象, 缺失/ 空白字段, 超长, 任意 Unicode Cc/ Cf 字符, 非无限) `order`页:1 **降下一个警告** 命名插件 id, 索赔索引, 字段。 不致命: 插件正常加载 . `nav` 任何其它插槽都默不作声.
-   仅因 **第一当事方** 插件 — npm 软件包 `@blackbelt-technology/` 范围(`firstParty` 打开 `GET /api/plugins` 行; 没有 `priority`) (中文(简体) ).
-   与任何内置设置页面或组标签相撞的标签(英语 + 每个已运出的地方, NFKC + case- trold) 被忽略; 在所推广的插件之间, 下 ()`order`,id)获胜.
-   一个被提升的页面得到一个紧凑的主机chrome(label title,描述引导,"由插件提供"+toggle,只当不健康时用药,在披露后使用元数据). 一个被禁用的被推广的插件保留在其组中,标记为"off".
-   字符串可以做成纯文本 永远不要标记.

参见:促销-模型-角色设定.

## 客户端插件 Context API

插件客户端组件接收槽消费者的道具. 钩子通过最近的 `PluginContextProvider`数字 :

```ts
import {
  usePluginConfig,
  useAllSessions,
  useSessionState,
  usePluginLogger,
  usePluginSend,
  usePluginRouter,
} from "@blackbelt-technology/dashboard-plugin-runtime";

function MyBadge({ session }) {
  const config = usePluginConfig<{ enabled: boolean }>();
  const logger = usePluginLogger(); // logs as [plugin:my-feature]
  const send = usePluginSend();
  // ...
}
```

`usePluginConfig<T>()` 反应——当 `POST /api/config/plugins/<id>` 成功和服务器广播 `plugin_config_update`。 。 。 .

**您必须从槽贡献组件中调用这些钩子** (即:a内部) `CurrentPluginLayer`) (中文(简体) ). 从外部调用它们会引发描述性错误.

### 槽请求无效存储

一个插件 `shouldRender` 闸门依赖于解决 ATER 第一次渲染后的信号( 例如, 启动时已安装的检查) 调用 `bumpSlotClaimsVersion()` 一旦信号到达 每个挂起的门包装器——包括从未播出的闲/无间会卡 `session_updated` 重播时 `shouldRender` 同步进行. 只有全球信号;没有每个部分的有效载荷搭载起一个起落. 见变化:添加-黑洞-会话-管线.

```ts
import { bumpSlotClaimsVersion } from "@blackbelt-technology/dashboard-plugin-runtime";
```

## 服务器侧服务器PluginContext API

您的服务器条目必须导出默认值 `registerPlugin` 函数 :

```ts
// packages/my-feature-plugin/server/index.ts
import type { ServerPluginContext } from "@blackbelt-technology/dashboard-plugin-runtime/server";

export default async function registerPlugin(ctx: ServerPluginContext): Promise<void> {
  ctx.fastify.get("/api/my-feature/status", async () => {
    return { ok: true };
  });

  ctx.logger.info("my-feature plugin loaded");
}
```

备查 `ctx`数字 :

-   `fastify` - 简化REST线路.
-   `sessionManager` 编号 : `eventStore` ——只读仪表板状态.
-   `broadcastToSubscribers(msg)` ——向所有订阅浏览器发送WebSocket消息.
-   `registerPiHandler(type, handler)` 编号 : `registerBrowserHandler(type, handler)` ——钩入WebSocket消息流.
-   `getPluginConfig<T>()` ——读取此插件的配置 `~/.pi/dashboard/config.json#plugins.<id>.*`。 。 。 .
-   `updatePluginConfig<T>(partial)` - 验证、合并、坚持和广播 `plugin_config_update`。 。 。 .
-   `isPiExtensionInstalled?(name)` – 布尔- 仅安装到 pi 的软件包注册(Global+local spects,~30s缓存) 。 可选:在旧主机/注入测试上下文上缺席——插件拥有倒置. 扫描失败 REJECS( 从未解决 ) `false`因此,一个 `false` 是权威的。 见变化:添加-黑洞-会话-管线.
-   `logger` - 名称空格记录器(`[plugin:<id>]`) (中文(简体) ).

## 桥梁自动登记

如果你的申报单 `bridge`仪表板自动登记 `~/.pi/agent/settings.json` 下级 `dashboardPluginBridges["dashboard-<id>"]` 在服务器启动时。 当插件被禁用时,仪表板会删除条目.

这个 `dashboard-` 键前缀保留。 用户拥有的扩展条目 `packages[]` 永远不会被触动.

## 插件配置持久性

插件设置位于 `~/.pi/dashboard/config.json#plugins.<id>.*`。 。 。 .

```json
{
  "plugins": {
    "my-feature": { "enabled": true, "pollInterval": 30 }
  }
}
```

如果你的申报单 `configSchema`,装载器:

-   应用计划 `default` 读取值.
-   验证器在持续前写( 拒绝使用 `ValidationError` (关于违反计划).

## 失败的隔离规则

-   显示验证过程中的插件抛出,服务器侧负载,或客户端侧渲染不会崩溃仪表板.
-   失败反映在 `/api/health.plugins[]` 作为 `{ loaded: false, error: "..." }`。 。 。 .
-   Slot 消费者错误边界抓取 React 渲染错误 / 要求( 不是每秒), 因此一个插件崩溃不会压制兄弟姐妹.

## 演示插件

`packages/demo-plugin/` 是一个私有的固定套件,可以练习运行时间端到端。 没错 **不包括生产建筑** (明显声明) `fixture: true`) (中文(简体) ). 不要将其作为真实插件的模板 .

## Spawn-env 贡献者(实验性)

信任的插件( I)`priority <= 100`,与 `spawnSession`可以打电话 `ctx.registerSpawnEnvContributor(fn, opts?)` 在服务器上下文. `fn({ mechanism })` 同步返回 env vars 添加到每一次仪表板喷出 pi 会话中 (单位:千美元)`headless`, (中文(简体) ), `tmux`, (中文(简体) ), `wt`, (中文(简体) ), `wsl-tmux`) (中文(简体) ). 主机从不覆盖一个继承的变量, 拒绝保留名称( e)`PATH`, (中文(简体) ), `HOME`, (中文(简体) ), `NODE_*`, (中文(简体) ), `LD_*`, (中文(简体) ), `DYLD_*`, (中文(简体) ), `PI_DASHBOARD_*`, (中文(简体) ), `ELECTRON_*`, (中文(简体) ), `CONTEXT_MODE_BRIDGE_*`,跳过投稿人,跳过插件时 是残废的. `opts.supersede = { marker, names }` 让主机删除列表名称( 只有) 在申请捐款之前, 政策,不是沙盒。 见 `packages/context-mode-settings-plugin` 用于参考用户.

## 常见问题

### @blackbelt-technology/dashboard-plugin-runtime 是什么？

插件加载器、槽登记器、槽消费者和上下文 Pi-dashboard 的 API

### 如何安装 @blackbelt-technology/dashboard-plugin-runtime？

在项目目录运行 npm install @blackbelt-technology/dashboard-plugin-runtime，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（^6\.0\.0）、react（\>=18\.0\.0）、wouter（^3\.9\.0）、fastify（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blackbelt-technology/dashboard-plugin-runtime 支持 TypeScript 吗？

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

### @blackbelt-technology/dashboard-plugin-runtime 支持 ESM 还是 CommonJS？

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

### @blackbelt-technology/dashboard-plugin-runtime 可以商用吗？

@blackbelt-technology/dashboard-plugin-runtime 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blackbelt-technology/dashboard-plugin-runtime 的下载量有多少？

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

### @blackbelt-technology/dashboard-plugin-runtime 还在维护吗？

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