@tt-plug/plugin-sdk

插件物料管理系统的运行时 API 与 TypeScript 协议包。

每个插件都通过这套协议与基座对话 —— 不论是 pnpm link 的本地包，还是通过 Module Federation 加载的远程 bundle。本包提供类型系统、校验器、运行时门面，以及你写贡献时用的声明组件。

依赖 React 19，消费者用 tsup 构建，要求 Node ≥ 24、pnpm ≥ 10。

用本 SDK 写什么

插件的贡献是一棵声明组件的 JSX 树：

// src/contributions.tsx
import { Fill, hostContract } from '@tt-plug/plugin-sdk';

export const contributions = (
  <Fill
    id="module"
    into={hostContract.slots.dashboard}
    permission="dashboard:view"
    order={10}
    load={() => import('./MyModule')}
  />
);

// src/index.ts
import { definePlugin } from '@tt-plug/plugin-sdk';

export const plugin = definePlugin({
  manifest: { id: 'example', name: '示例', version: '1.0.0' }, // apiVersion 自动补
  contract: myContract,
  contributions,
});

完整教程见 docs/plugin-development.md —— 包含页面、插槽、嵌套插槽、契约、通道、运行时的完整走读。

安装

pnpm add @tt-plug/plugin-sdk

主要导出

声明组件

| 组件 | 意思 | 产出 | 关键 props | | --- | --- | --- | --- | | <Page> | 一个页面 | routes | id、path、permission、label?、icon?、order?、load | children | element | | <Slot> | 我开的洞 | extensionSlots | id、on?、inside?、description? | | <Fill> | 我往别人洞里填的内容 | modules | id、into、permission?、order?、内容三选一 | | <Entry> | 别人页面上跳回我的入口 | routeLinks | into、to、label、icon?、order? |

宿主用同样的 <Page> / <Slot>，内容给 element。

三条自动规则省掉样板：

1. id 自动加前缀——<Fill id="two-demo"> 在插件 five 里产出 five.two-demo。<Page id> 例外（它本身就是路由 ID）。
2. order 一律升序，内部转成宿主排序用的 priority。
3. <Entry> 权限默认继承目标页面。

<Slot inside="<某个 Fill 的 id>"> 用于跨插件嵌套：routeId 与 ownerModuleId 都由那个 Fill 推出，不用手写。

定义入口

• definePlugin({ manifest, contract?, contributions }) → WorkspacePlugin（四类贡献收窄成必选，manifest 保留字面量类型）
• defineHost(tree, { reservedPaths? }) → { routes, extensionSlots, reservedPaths, knownSlots }

两者都会拒绝未知元素、重复路径和指向不存在声明的引用。

运行时（按组件下发）

PluginRuntime 提供：

• pluginId、user、can(permission)
• api —— 自动附 Bearer token 的 HTTP 客户端（get / post / patch）
• query —— 按用户和插件隔离的缓存（搭配 usePluginQuery(query, options) 使用）
• channel —— 类型化定向消息与公共广播
• contracts —— 所有已启用插件公开的契约表
• extensions —— renderSlot(slot, fallback)、routesFor(route)、navigateTo(route, options)

宿主契约（开箱即用）

• hostContract —— 宿主开放的路径与插槽 ID
• workspaceContract —— 公共通道 topic
• dataContract —— 显式共享 query key、Schema 与路径
• workspaceContract.host —— 与 hostContract 等价

校验

• validatePlugins(plugins, { reservedPaths, knownSlots }) → PluginRegistration[]
• loadPluginRegistrations(descriptors, options) —— 加载并校验
• parseRemotePluginManifest(unknown) —— 严格 manifest 解析器

诊断码见 PLUGIN_DIAGNOSTIC_CODES / PluginDiagnosticCode；严重级别决定插件是否参与路由解析。

普通 query key 只在当前插件内共享。确需跨宿主和插件复用的缓存键必须由 createSharedPluginQueryKey(...parts) 创建；dataContract.status.queryKey 就是一个共享键。键片段只允许 string | finite number | boolean | null。

贡献目录（纯数据）

catalogPluginContributions(plugins, hostCatalog) —— 产出插件中心渲染的拓扑结构，也适合作为外部工具的内省入口。

版本

• 1.x —— 协议稳定
• 1.3.0 —— 新增声明组件
• 1.4.0 —— EXTENSION_SLOT_ROUTE_UNKNOWN 接受带 ownerModuleId 的跨插件嵌套插槽
• 1.5.0 —— 宿主侧声明组件
• 2.0.0 —— 声明 API 重命名为 Page / Slot / Fill / Entry，入口改 definePlugin / defineHost；id 自动加前缀、order 统一升序、ownerModuleId 由 inside 推导。
• 2.x 保留 PageRouter / ModuleRouter / ExtensionSlot / createPluginContributions 作为弃用兼容层。新代码应只使用 2.x 声明 API；当前运行时协议版本仍为 1，远程 manifest Schema 版本也为 1。

许可证

内部项目 —— 详见仓库根目录。