NocoBase Plugin Development 是一项用于 NocoBase 3 仓库中进行插件源码开发的技能。使用前应阅读适用的 AGENTS.md,并在编辑前检查目标插件与 App。需要确认工作区包含 packages/tools/create-plugin/、packages/app/app-client/、packages/app/app-server/ 以及 pnpm-workspace.yaml。仅存在 packages/plugins/ 目录并不能判定为 v3;不应在此处应用旧版 Plugin 类、src/client-v2/ 或 nb scaffold plugin 协议。
参考资料选择
这些英文参考资料将插件开发指南改编为面向具体任务的指令。只阅读与任务相关的行,不要默认加载完整参考集。
- 创建插件、选择能力、更改声明、导出、依赖或公共契约:阅读 Scaffolding and package contracts。
- 注册、配置、升级、禁用、注销或诊断插件集成:阅读 Registration and lifecycle。
- 选择 Client 组件、ServiceProviders、React Providers、配置或 API 访问:阅读 Client architecture。
- 构建或更改任何插件 UI:阅读 shadcn components and styling。
- 添加页面、Settings、Dev routes、菜单、Tabs、路由对话框/抽屉、子路由或页面覆盖:阅读 Client routing。
- 设计配置实体、设置权限、路由编辑器和安全保存:阅读 System settings。
- 定义服务契约、Tokens、依赖注入或生命周期:阅读 Services and Providers。
- 添加 HTTP 端点、授权、Repository 操作、后台任务或队列:阅读 Server development。
- 命名 /api 路径、选择方法、构造响应或错误、验证输入:阅读 HTTP API rules。
- 添加迁移、种子或包资源/校验和处理:阅读 Database resources。
- 添加或更改文本、区域设置资源、翻译错误或接收方语言消息:阅读 Internationalization。
- 编写、发布、安装、升级或移除 App 拥有的可编辑 Client 源码:阅读 Registry。
- 向 App Agent 暴露插件能力:阅读 Plugin Skills。
- 添加命令、CLI 导出或 CLI 注册:阅读 CLI plugins。
- 选择行为测试并验证包/App 集成:阅读 Testing and delivery。
对于已实现的示例与测试,可阅读匹配的 Server Route 示例、ServiceToken 与 Provider 示例、Client 示例或 Repository 示例。这些内容以具体代码补充主题参考,并指向维护中的源码 fixture;应将其显式示例访问策略调整为所需产品。
实现前规则
创建页面或编写页面组件时,应参考 Pages, routes, and menus 了解页面组件结构与路由声明。对于嵌套页面、页面级导航 Tabs、路由对话框/抽屉或导航组,还应阅读 Child routes, Tabs, overlays, navigation groups, and Outlet。在使用页面与覆盖层示例前,需将所需组件源码复制到插件中。示例通过相对 .js 路径导入这些插件自有副本;宿主私有的面包屑组件被排除。关于路由覆盖层组件可用性与 hook 上下文边界,应阅读 route dialogs and drawers。
交互式 UI 基础组件(如按钮、输入框、对话框、选择框和 Tabs)应使用 shadcn 组件。进行 UI 工作前应阅读组件参考。插件自有组件应保留在插件内,并使 components.json 与其包本地 # 导入及发布的 dist 映射保持一致。颜色、排版、间距、尺寸、圆角和阴影应使用共享主题令牌。
页面级导航 Tabs 默认应使用子路由,即使用户未提及路由。将每个 Tab 的内容声明为子路由,在父页面组件中渲染 Outlet,并从 URL 派生活动 Tab。当打开父 URL 但没有子路由时,应通过替换当前历史记录条目并保留查询参数,重定向到默认可访问 Tab。打开显式 Tab URL 时必须保留该 Tab 的选中状态。若用户明确要求不同交互,则遵循用户请求。
使用 pnpm plugin:create 和显式能力创建插件,必要时包含 cli。使用 --dry-run --json 预览。保留生成的运行时感知共享开发配置。
声明应保持静态,且不包含启动副作用。页面组件、区域设置消息、重型 SDK 和真正可选的特性应在叶子边界懒加载。页面是 Routes,组件是 public/source 导出,两者都不是单独的运行时加载器。
通过 useApiClient() 或 apiClientToken 复用宿主的 API 客户端;不要构造另一个应用 API 客户端。在实现之前定义共享服务契约和所有者创建的 Tokens;消费者导入原始 Token。
插件不贡献设置或开发页面;defineAppRoutes() 是唯一的 Client 路由 API。将管理功能暴露为设置项和 API,并按管理区域分组(例如 Automation 包含 Workflow 和 Schedules),其上的任何页面留给应用。声明与服务器操作边界参见 System settings。
每个 /api 路由都遵循 HTTP API rules:插件命名空间下的 camelCase 路径、标准方法、{ data } 响应、所有失败使用 ApiError(客户端根据 reason 分支)、通过 apiValidator() 验证的 zod 输入,以及每个路由上的 describeRoute() 声明,用于 /api/swagger/docs 上的应用 OpenAPI 文档。数据端点是 POST /api/{name}/{action},使用 camelCase 暴露名称,并且在没有声明的情况下记录文档。
每个 Server Route 拥有并测试其身份验证和授权,或其显式公共协议边界。另一个贡献的中间件或注册顺序不是保护。通过 createRouter() 测试生产贡献。
每个 Server 插件都声明绝对 baseDir。迁移、种子和 Jobs 相对于它解析,以便编译后的插件使用编译资源。迁移是显式的、自包含的、合并后不可变的,并针对真实数据库进行测试。
在相应目标 App 组合根中显式注册 Client、Server 和 CLI 导出。安装、注册、Skills 同步和运行时行为是不同的事实;旧版 manifest 元数据不是运行时发现。
插件集成知识编写在 <plugin>/skills/ 中;目标 App 的 .agents/skills/ 是生成输出。复制到 App 中的 Registry 源码归该 App 所有。本仓库的开发 Skill 是维护中的源码,区别于上述任一输出。
遵循仓库的依赖规则:共享运行时和客户端值导入为 peers,普通服务器运行时导入为 dependencies,仅开发用导入为 devDependencies。发布声明中保留的类型引用需要可被消费者解析的契约。
实现工作流
检查工作树变更、插件清单、声明、导出、测试和目标 App。识别请求的行为,以及谁拥有其数据、UI、服务和集成代码。
选择能力并定义最小的公共契约:Client 选项/导出、Server Tokens/APIs、CLI 命令、权限/错误边界和可观察结果。仅使用上述相关参考。
在所属插件中实现。将领域行为放在 Services 中,HTTP 边界放在 Routes 中,异步编排放在 Jobs 中,React 上下文放在 React Providers 中,应用集成说明放在 Plugin Skills 中。
保持声明、源码/发布导出、依赖、发布文件、测试、README 和 Plugin Skills 一致。移除未使用的脚手架示例和草稿。每个 Markdown 正文段落写在一个物理行上,不手动换行。
当集成是请求的一部分时,预览并将注册应用到所选 App,同步适用的 Skills,并验证结果行为。不要仅因本 Skill 适用就运行创建、注册、迁移或其他有状态命令。
遵循测试与交付:运行修改插件的检查和相关消费者检查,然后验证请求的运行时工作流。plugin inspect 是可选的只读注册诊断,不是测试或完成门槛。准确报告结果、跳过的检查和剩余限制。