nocobase-app-plugin-development

NocoBase 插件开发

在 NocoBase 3 仓库中开发插件源码时，请使用此 Skill。编辑前，请阅读适用的 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 协议。

选择相关参考资料

这些英文参考资料根据具体任务，将插件开发指南改编为相应说明。请阅读与任务相关的条目；默认情况下不要加载整套参考资料。

任务	阅读
创建插件、选择功能、修改声明、导出、依赖或公共契约	脚手架与软件包契约
注册、配置、升级、停用、取消注册或诊断插件集成	注册与生命周期
选择客户端组件、ServiceProvider、React Provider、配置或 API 访问	客户端架构
定义服务端配置默认值、环境映射、验证或浏览器可见字段	插件配置
构建或修改任何插件 UI	shadcn 组件与样式
添加业务页面、菜单、Tab、路由对话框／抽屉、子路由或页面覆盖	客户端路由
设计配置实体、设置权限、路由编辑器和安全保存	系统设置
定义服务契约、Token、依赖注入或生命周期	服务与 Provider
添加 HTTP 端点、授权、Repository 操作、后台任务或队列	服务端开发
命名 /api 路径、选择方法、设计响应或错误格式，或验证输入	HTTP API 规则
添加迁移、种子数据或软件包资源／校验和处理	数据库资源
添加或修改文本、本地化资源、已翻译错误或收件人语言的消息	国际化
编写、发布、安装、升级或移除由 App 拥有的可编辑客户端源码	UI 库所有权
向 App Agent 暴露插件功能	插件技能
添加命令、CLI 导出或 CLI 注册	CLI 插件
使用 @nocobase/app-testing 进行数据库、服务端、客户端或 CLI 测试，并验证 App 集成	测试与交付
通过迁移、受保护 API、客户端、配置和 CLI 测试，了解一个可执行插件的完整流程	完整测试示例

对于 Realtime 变更，请检查目标工作区或应用是否提供了与版本匹配的 nocobase-realtime 技能（来自 @nocobase/realtime）；阅读时还应参照已安装的 API 声明。软件包集成指南必须与目标运行时版本相匹配。 有关可运行的实现和测试，请参阅相应的 Server Route 示例、ServiceToken 和 Provider 示例、Client 示例 或 Repository 示例。这些示例通过具体代码补充主题参考，并指向维护中的源代码夹具；请根据所请求的产品调整其中明确的示例访问策略。

实现前适用的规则

创建页面或编写页面组件时，请参阅 页面、路由和菜单，了解页面组件结构和路由声明。对于嵌套页面、页面级导航选项卡、路由对话框／抽屉或导航组，也请阅读 子路由、选项卡、覆盖层、导航组和 Outlet。使用页面和覆盖层示例前，请先将所需的组件源代码复制到插件中。示例通过相对 .js 路径导入这些由插件拥有的副本；宿主的私有面包屑组件不包含在内。有关路由覆盖层组件的可用性和 Hook 上下文边界，请参阅路由对话框和抽屉。

• 使用 shadcn 组件作为按钮、输入框、对话框、选择器和 Tabs 等交互式 UI 基元。开始 UI 工作前，先阅读组件参考文档。插件自有组件应保留在插件中，并使 components.json 与其包本地 # 导入和发布的 dist 映射保持一致。使用共享主题令牌设置颜色、字体、间距、尺寸、圆角和阴影。
• 默认使用子路由实现页面级导航 Tabs，即使用户未提及路由也如此。将每个 Tab 的内容声明为子路由，在父页面组件中渲染 Outlet，并从 URL 确定当前激活的 Tab。若打开父 URL 时没有子路由，则替换当前历史记录条目并保留查询参数，重定向到默认的无障碍 Tab。打开明确指定的 Tab URL 时，必须保留该 Tab 的选中状态。若用户明确要求采用其他交互方式，则遵照其要求。
• 使用 pnpm plugin:create 创建插件，并明确声明 capabilities；必要时包括 cli。使用 --dry-run --json 预览。保留生成的、感知运行时的共享开发配置。
• 声明应保持静态，且不产生启动副作用。在叶子边界处延迟加载页面组件、本地化消息、大型 SDK 和确实可选的功能。页面属于 Routes，组件属于公开／源码导出；二者都不是独立的运行时加载器。
• 将所有插件文案翻译成每个客户端和服务端本地化清单中列出的全部十种支持的语言（en-US、zh-CN、zh-TW、ja-JP、es-ES、pt-BR、fr-FR、de-DE、vi-VN、id-ID），并使用完整的 en-US 资源进行类型定义。插件依赖且自带翻译的库也要补全至全部十种语言，例如 @nocobase/app-plugin-i18n 所依赖的 @nocobase/i18n。新增或更改的键必须在同一变更中翻译成全部十种语言；应用模板除外。
• 通过 useApiClient() 或 apiClientToken 复用宿主的 API 客户端；不要另行构造应用 API 客户端。在实现前定义共享服务契约和由所有者创建的 Token；使用方应导入原始 Token。
• 插件不提供设置页面或开发页面；defineAppRoutes() 是唯一的客户端路由 API。将管理功能作为设置项和 API 暴露，并按管理领域分组（例如，Automation 包含 Workflow 和 Schedules），相关页面由应用提供。关于声明和服务端操作边界，请参阅系统设置。
• 每个 /api 路由都必须遵循 HTTP API 规则：在插件命名空间下使用 camelCase 路径和标准方法，响应格式为 { data }，每种失败都使用 ApiError（客户端根据 reason 分支处理），通过 apiValidator() 验证 zod 输入，并在每个路由上使用 describeRoute() 声明，以纳入应用位于 /api/swagger/docs 的 OpenAPI 文档。数据端点使用 POST /api/{name}/{action}，采用 camelCase 暴露名称，并以无声明的方式记录文档。
• 每个服务端路由都必须负责自身的身份验证与授权，或负责定义明确的公开协议边界，并对其进行测试。其他贡献中的中间件或注册顺序不构成保护。通过 createRouter() 测试生产环境中的贡献。
• 每个服务端插件都必须声明绝对路径的 baseDir。迁移、种子数据和 Jobs 都应以此为基准解析，以确保编译后的插件使用编译后的资源。迁移必须显式定义、自包含、合并后不可更改，并针对真实数据库进行测试。
• 插件测试夹具来自 devDependencies 中声明的 @nocobase/app-testing/server、/client 或 /cli。使用测试目录和夹具指南选择环境、注册生产插件，并确保数据库和存储彼此隔离。
• 在对应的目标应用组合根中显式注册客户端、服务端和 CLI 导出。安装、注册、Skills 同步和运行时行为是彼此独立的事实；旧版清单元数据不代表运行时发现机制。
• 插件集成知识编写在 <plugin>/skills/ 中；目标应用的 .agents/skills/ 是生成的输出。可编辑 UI 在 UI Library 中维护；安装到应用中的源码属于该应用。本仓库的开发 Skill 是维护中的源码，与这两类输出均不同。
• 遵循仓库的依赖规则：共享运行时和客户端值导入应设为对等依赖，常规服务端运行时导入应设为依赖项，仅用于开发的导入应设为 devDependencies。发布的声明中保留的类型引用，必须具有使用方可解析的契约。

实现工作流

1. 检查工作树更改、插件清单、声明、导出、测试和目标 App。确定所请求的行为，以及谁负责其数据、UI、服务和集成代码。
2. 选择功能并定义最小化的公共契约：客户端选项/导出、服务端 Tokens/API、CLI 命令、权限/错误边界和可观察结果。仅使用上方相关参考资料。
3. 在所属插件中实现。将领域行为放在 Services 中，将 HTTP 边界放在 Routes 中，将异步编排放在 Jobs 中，将 React 上下文放在 React Providers 中，并将应用集成说明放在 Plugin Skills 中。
4. 确保声明、源码/发布导出、依赖项、发布文件、测试、README 和 Plugin Skills 保持一致。移除未使用的脚手架示例和草稿。每个 Markdown 正文段落写在同一物理行上，不要手动换行。
5. 如果请求包含集成，则预览并将注册应用到选定的 App，同步适用的 Skills，并验证最终行为。不要仅仅因为适用此 Skill，就运行创建、注册、迁移或其他有状态命令。
6. 遵循测试与交付：运行已修改插件的检查和相关使用方检查，然后验证所请求的运行时工作流。plugin inspect 是可选的只读注册诊断，不是测试或完成门槛。准确报告结果、跳过的检查和剩余限制。