Plugin Introduction

插件介绍

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

安全前提：内核内置插件可作为受信代码运行；第三方插件默认采用隔离执行边界。 permissions 是路由准入控制，不替代执行隔离。完整说明见信任模型、权限与 RBAC。

插件能做什么

一个 StackPanel 插件可以：

• 声明 HTTP 路由 — 提供自己的 REST API，由内核统一分发
• 注册扩展点实现 — 向内核或其他插件注入能力（认证提供者、支付提供者、导航项、Dashboard Widget 等）
• 发布/订阅事件 — 通过事件总线与其他插件松耦合通信
• 读写自有数据 — 用 defineModel 声明模型，经内核 Extension 引擎（ctx.extensions / ctx.tx）读写；插件零裸 DB（ADR-0008 / ADR-0009）
• 存储加密密钥 — 在插件命名空间下安全存储 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 声明派生（内核启动时扫描）。

文档归属

本指南只说明内核插件契约。非内核附带插件的领域模型、配置、部署、使用方式、领域 API 和发布说明必须维护在该插件仓库的 Wiki。内核 Wiki 可以链接其主页，但不维护副本。

技术约束

• 插件后端使用 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）

接下来

• 准备工作 — 搭建插件开发环境
• 插件项目结构 — 了解目录布局
• 插件清单 — 编写 manifest.json
• 插件 Capability — 公开 API、MCP 与 Agent 的统一能力入口
• 插件 Agent Surface — 自动化操作的契约与评审要求
• 完整示例 — 打包并上传你的第一个插件