插件
插件内核的工作方式:什么是插件,它向哪些客户端插槽和服务端插槽贡献内容,插件如何在构建期安装、在运行时启用和停用。
管理后台和用户工作区的代码不写死任何功能。它们读取插槽(侧边栏、仪表盘、账单页头部、agent 工作台),每个已安装的插件向这些插槽贡献条目。基础版本身是一个插件,每个模块是一个插件,你为自己产品写的功能也可以是一个插件。编写方法见编写后台插件。
什么是插件
一个插件由一份清单和若干插槽贡献组成,放在 src/plugins/<id>/ 目录里。
| 文件 | 内容 | 由谁加载 |
|---|---|---|
manifest.ts | 纯数据:id、version、kind、requires、routes | 任何地方 |
plugin.ts | 浏览器安全的贡献:带图标的导航、页面区块、工作台扩展 | Web 应用 |
plugin.server.ts | 只在服务端的贡献:API 路由、支付履约、agent 宿主扩展。可选 | Web 应用的服务端和 agent 服务 |
清单的 routes 列出插件拥有的路径前缀(不含语言前缀),例如 /admin/cms、/app/image。requires 列出必须已安装并启用的其他插件 id。
| 类型 | 含义 | 能否停用 |
|---|---|---|
builtin | 基础版:每个安装都有的后台 | 不能 |
module | 随仓库提供的模块,带标记区段和 module.json | 能 |
agent | 一项 agent 能力,依赖 agent-starter | 能 |
local | 属于你自己的项目。没有标记区段,也没有 module.json | 能 |
构建期安装,运行时启用
插件不会在应用运行时下载或加载。模板要部署到 Cloudflare Workers,那里不能加载远程代码。文件路由在构建期就确定。插件还必须和宿主一起通过类型检查和校验器。因此一个插件有两个彼此独立的状态。
已安装是构建期的事实。src/plugins/installed.ts 是一份显式的列表,一个部署运行哪些插件以它为准。模块的条目写在这份列表里它自己的 // @module:<key> 区段内。local 插件由你手工加入,写在任何区段之外。src/plugins/installed.server.ts 是对应的服务端列表。agent 服务会 import 它,所以从它能到达的代码都不能 import React、图标或 @/ 别名。
已启用是运行时的事实,保存在后台配置表的 plugins.state.v1 里。这里只记录被运营人员停用的 id,所以之后新装的插件默认启用。启用集合这样计算:
builtin插件始终启用。- 停用列表里的插件停用。
- 依赖了已停用插件的插件也停用,按依赖关系传递。
持有 config.write 的管理员在 设置 → 插件(/admin/plugins)里修改。停用一个仍被已启用插件依赖的插件会被拒绝,并列出依赖它的插件。启用一个依赖尚未启用的插件也会被拒绝,并指出缺少的依赖。
客户端插槽与服务端插槽
插槽是一个带类型、有名字的列表,由宿主读取,由插件贡献内容。客户端插槽增加界面:admin.nav 和 app.nav 接收侧边栏条目,app.dashboard.cards 接收 /app 仪表盘上的卡片。插件通过 plugin.ts 里的 contributes 向它们贡献内容,后台外壳通过 usePluginValues(slot) 读取。服务端插槽增加行为:api.routes 在 /api/plugins/<pluginId>/… 下提供接口,billing.fulfilment 交付已支付订单购买的内容。插件通过 plugin.server.ts 里的 contributes 向它们贡献内容。
每个插槽都声明了单条贡献的结构,以及用哪个字段作为 key。完整列表和每条贡献的类型见 src/plugins/slots.ts(客户端)和 src/plugins/server-slots.ts(服务端)。agent 插槽只在安装了 agent-starter 模板后才存在,见 Agent 插件。
注册表把已安装的插件合并一次,并在构建注册表时拒绝所有冲突,报以下错误之一:
| 错误 | 原因 |
|---|---|
duplicate_plugin | 两个插件的 id 相同 |
duplicate_slot_key | 同一个插槽里两条贡献的 key 相同 |
duplicate_plugin_route | 两个插件声明了同一个路由前缀 |
missing_plugin_dependency | 插件依赖的插件没有安装 |
plugin_dependency_cycle | 插件之间循环依赖 |
unknown_plugin_slot | 贡献指向一个没有声明的插槽 |
停用插件之后
| 位置 | 效果 |
|---|---|
| 导航和页面区块 | 外壳只读取已启用插件的贡献,它的入口和卡片随之消失。 |
/admin 和 /app 下的页面 | 两个后台布局在 beforeLoad 里调用路由守卫;属于已停用插件的路径返回未找到。路径归属按最长匹配的路由前缀判断。 |
/api/plugins/<id>/… | 通配路由返回 404。 |
| Server function | 模块自己的函数在鉴权之后调用 requirePluginEnabled(<id>),拒绝调用。 |
| 支付 | 只调用已启用插件的履约器。 |
| Agent | 已停用插件的场景、路由和技能被跳过,在它的场景上创建运行会被拒绝,错误码 plugin_disabled。 |
路由守卫只在两个后台布局里执行。清单里的公开路由前缀(例如 /blog)只登记归属,不在那里拦截。
停用插件不会卸载它。文件、数据表、数据和迁移都保留。
部署能力
有些入口取决于部署具备的能力。app.nav 的条目可以带 requires: "agent"。agent 服务不可用时,即使插件已启用,这个入口也会隐藏。后台布局在服务端同时解析已启用的 id 和部署能力,一起传给外壳。见 Agent 运行机制。
模块与插件的关系
模块是一项边界记录在 modules/<key>/module.json 里的功能:文件、共享文件区段、迁移和依赖包。插件则是这个模块接入后台的方式。两者必须在三个地方保持一致,由 pnpm validate:plugins 检查:
- 插件 id 等于模块 key,版本号一致。
- 模块的
files包含src/plugins/<key>/**。 - 模块的
fragments包含src/plugins/installed.ts,它的标记区段就在那里。
Schema、权限种子和文案词典不是插件贡献。它们仍在共享文件的 // @module:<key> 区段里。见开发一个模块。