Plugin Introduction

插件介绍

StackPanel 采用微内核 + 插件架构。内核只提供基础设施（认证、RBAC、插件运行时、主题引擎、事件总线、设置/密钥、审计），所有业务功能（商品、订单、支付、工单、认证对接等）都以插件形式存在。

插件执行模式

插件有两个执行边界，由清单的 execution 字段选择。

生产环境下第三方插件默认 execution: "isolated"：插件入口在独立的 Node 子进程中运行，API 进程只保留清单、路由代理与 RPC 桥。插件通过 IPC RPC 暴露 ctx.*，协议包含协议版本、插件身份校验、消息大小上限（1 MiB）、并发上限（64）、双向超时（10 秒）与取消。

• worker 崩溃会把插件置为 failed，清理其路由、模型与任务，并拒绝在途请求。
• worker 退出累计达到 3 次后熔断，必须重新注册修复后的包才能恢复。
• isolated 模式下无法安全表达要求同步 next() / 同步返回值的 ctx.events.intercept() 与 ctx.events.waterfall()，调用会得到明确错误；原始流式路由（kind: 'raw'）与无法转为 JSON Schema 的自定义模型会在 worker 启动时被拒绝。

内置插件在所有环境都以 trusted（与内核同进程）加载；非生产开发环境也可使用 trusted。非内置插件在 NODE_ENV=production 下请求 trusted 会被拒绝。

permissions 与路由的 permission 是路由准入与前端可见性控制，不是 OS 沙盒；isolated 也不是完整容器。安装并激活一个插件，等价于在服务器上运行其携带的服务器端代码。完整说明见信任模型、权限与 RBAC。

能力范围

一个 StackPanel 插件可以：

• 声明 HTTP 路由：提供自己的 REST API，由内核统一分发。
• 注册扩展点实现：向内核或其他插件注入能力（认证提供者、支付提供者、导航项、Dashboard Widget 等）。
• 发布/订阅事件：通过事件总线与其他插件松耦合通信。
• 读写自有数据：用 defineModel 声明模型，经内核 Extension 引擎（ctx.extensions / ctx.tx）读写。插件不直接持有数据库句柄。
• 存储加密密钥：在插件命名空间下存储 API Key 等敏感信息。
• 携带前端包：提供用户页面、管理后台页面、Dashboard Widget 等前端能力。
• 声明权限与角色模板：定义细粒度权限并自动授予内置角色。
• 实现履约/交付物提供方：把已付款商品变成交付物（云服务器开通、发卡等），并读取/展示服务数据。见 履约/交付物。

内核职责边界

内核不预设任何业务 Slot 或页面 ID。页面引擎、Finder、管理操作、后台/账户路由均由插件或主题自行声明。内核只提供渲染基础设施和三级覆盖机制（主题 > 插件 > 内置）。

插件 vs 主题

维度	插件	主题
后端代码	有（definePlugin）	无
HTTP 路由	可声明	不可
前端包	可选	可选
CSS Token	无	theme.css
数据库表	可拥有	不可
扩展点	可注册/消费	不可

内置插件一览

插件	说明
login	邮箱密码登录（内置）
hello	最小示例，演示基本结构
store	商品/购物车/订单 + 订单结算处理器（支付/钱包为内核服务）
store-wallet	钱包：余额/充值/管理（依赖内核 ctx.payments/ctx.wallet）
store-product-server	服务器类商品类型（类型定义 + 本地履约）
store-product-card	卡密类商品类型
catalog	商品分类：依赖 store，经 store.product.read/store.product.update 读写商品
llm-gateway	OpenAI 兼容 LLM 网关：签发 key、上游转发、按 token 扣钱包余额
zjmf-compat	智简魔方协议兼容层：把魔方客户端请求翻译为平台商业域操作
ticket	工单系统
wowid	WowID OAuth 第三方认证
zjmf-upstream	智简魔方上游商品同步与履约
epay	易支付支付提供者

内置插件不可通过上传覆盖或删除。它们的 dist 产物在 API 启动时自动 seed 到 data/plugins/。 权威清单由各插件包 package.json 的 stackpanel.builtin: true 声明派生（内核启动时扫描）。

第三方插件参考

插件	说明
notice	最小演示插件：路由 + 公开页/管理页，pnpm plugin:create --frontend 产物
cms	内容管理插件（文章/页面，自带管理页，经 seo.provider 输送站点 SEO）

catalog 是扩展 store 业务的现成模板（现已列为内置）：requires 依赖 store、 用 defineModel 声明自有模型（catalog/category、catalog/product）、公开/受权限路由、 Finder + 页面级数据、admin 路由与 action。它通过 store 提供的 store.product.read / store.product.update 扩展点读取商品明细与更新库存 （consumes 声明，而非直接读 store 的数据表）。

技术约束

• 插件后端使用 TypeScript，编译为 CommonJS/ESM 后以 dist/index.js 为入口
• 插件不直接依赖 Fastify，通过 SDK 提供的框架无关接口（HttpRequest/HttpReply）处理请求
• 插件 ZIP 不允许包含 .ts/.tsx/.jsx/.mts/.cts 源码文件（含 .d.ts.map），只允许编译后的 .js
• 插件 ID 格式：/^[a-z0-9_-]{1,64}$/，不能使用保留 ID（内置插件 + kernel + default）