// 插件 · 自定义开发

你的功能模块，走官方插件同一条路

uuos 没有给自己开后门：saas 与 im-channel 用的注册接口、路由挂载、导航投影，就是你要用的那一套。实现一个 Go 接口、声明一份 manifest，你的模块获得一级导航、租户鉴权、能力控制与初始化对账。

五步接入

01
声明 Descriptor
一份 manifest 说清一切：ai.uuos.* 命名空间下的插件 ID、版本、认证/公开路由基址、能力（capabilities）、一级导航与菜单/页面/API 资源。校验器强制命名规范与路由合法性。
02
实现 Plugin 接口
六个方法：Descriptor / AuthenticatedRoutes / PublicRoutes / Ready / Close / Upgrade。认证路由自动挂在租户鉴权之后，公开路由留给 webhook 回调，Upgrade 在版本变更时执行迁移。
03
保持依赖单向
插件不 import 宿主内部包。定义自己的中立 Scope 契约，由宿主适配器把租户与身份注入进来——官方插件 saas 与 im-channel 都是独立仓库，一行 uuos 代码不引。
04
前端接 HostBridge
页面包只依赖宿主注入的 apiBaseUrl、短期 token、capabilities、主题与语言，不读宿主内部状态。registerProductPlugin 注册后，入口出现在左侧一级导航。
05
注册并交给对账
Registry.Add() 在路由冻结前强校验唯一性（ID / 路由 / 资源）；每次启动幂等对账，checksum 漂移自动修复，初始化失败指数退避——插件的运维复杂度由平台兜底。

// 插件契约（internal/productplugin）
type Plugin interface {
    Descriptor() Descriptor
    AuthenticatedRoutes() []Route
    PublicRoutes() []Route
    Ready(context.Context) error
    Close(context.Context) error
    // 版本变更时执行迁移钩子
    Upgrade(ctx context.Context, prev string) error
}

// manifest：一份声明说清一切
Descriptor{
    ID:                "ai.uuos.my-plugin",
    Name:              "我的插件",
    Version:           "0.1.0",
    Mode:              "embedded",
    AuthenticatedBase: "/v1/my-plugin",
    Capabilities:      []string{
        "my-plugin.read",
    },
    // Navigation / Frontend / Resources …
}

// 启动时注册：ID / 路由 / 资源强校验
registry.Add(&MyPlugin{})

插件生命周期

从被发现到就绪的每一步都有状态落库，初始化报告经GET /v1/product-plugins/initialization 随时可查。

discoververifyinstallconfigureenableregisterready

失败不清除、只隔离：退避重试从 5 秒起步、5 分钟封顶，修复后自动回到 ready。

前端：页面包与宿主的约定

宿主给你什么

apiBaseUrl 与短期 token——请求自己的插件 API
tenant / workspace 上下文与 capabilities
主题（亮/暗）与语言，跟随宿主切换
导航注册：入口出现在一级菜单，按权限投影

页面包不读宿主内部 store——换个宿主也能跑。

// 前端注册（TypeScript）
registerProductPlugin({
  id: "ai.uuos.my-plugin",
  route: "/my-plugin",
  requiredCapability: "my-plugin.read",
  load: () => import("@my-org/my-plugin-web"),
})