Back to Details

nocobase-plugin-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Goal

目标

Guide an AI agent through the complete process of developing a NocoBase plugin — from requirement analysis to working code — producing a plugin that follows NocoBase conventions and can be enabled immediately.
引导AI Agent完成NocoBase插件的完整开发流程——从需求分析到可运行代码——产出符合NocoBase约定、可立即启用的插件。

Scope

适用范围

  • Analyze user requirements and map them to NocoBase extension points.
  • Scaffold a new plugin with 
    yarn pm create
    .
  • Generate server-side code: collections, ACL, custom APIs, migrations, install hooks.
  • Generate client-side code: blocks, fields, actions, settings pages, routes.
  • Generate i18n locale files.
  • Enable and verify the plugin.
  • Troubleshoot common issues using FAQ checklist and source code (when available).
  • 分析用户需求并映射到NocoBase扩展点。
  • 使用
    yarn pm create
    搭建新插件脚手架。
  • 生成服务端代码：集合、ACL、自定义API、迁移脚本、安装钩子。
  • 生成客户端代码：区块、字段、操作、设置页面、路由。
  • 生成国际化（i18n）语言包文件。
  • 启用并验证插件。
  • 使用FAQ清单和源码（若可用）排查常见问题。

Non-Goals

不适用范围

  • Do not build NocoBase applications through the UI (that's 
    nocobase-ui-builder
    ).
  • Do not handle plugin publishing to external registries.
  • Do not modify NocoBase core code.
  • Do not migrate existing plugins from client v1 to v2 (that's 
    nocobase-client-v2-plugin-migration
    ).
  • 不通过UI构建NocoBase应用（该场景请使用
    nocobase-ui-builder
    ）。
  • 不处理插件发布到外部注册表的操作。
  • 不修改NocoBase核心代码。
  • 不处理现有插件从客户端v1到v2的迁移（该场景请使用
    nocobase-client-v2-plugin-migration
    ）。

Hard Constraints

硬性约束

These rules apply to ALL generated plugin code. Violating them is always wrong.
以下规则适用于所有生成的插件代码，违反规则即视为错误。

NEVER use 
this.app.use()
or React Providers

严禁使用
this.app.use()
或React Providers

this.app.use()
is an internal API. Plugins must NEVER use it to wrap the app with React providers. This is not a suggestion — it is a hard rule with no exceptions.
Providers add unnecessary React rendering layers, hurt performance, and make plugins harder to maintain. When implementing global effects (watermarks, overlays, theming, tracking, global listeners, etc.), use these approaches instead:
  1. FlowEngine mechanisms (preferred) — 
    registerModelLoaders
    , 
    registerFlow
    , 
    registerModels
    for UI capabilities.
  2. FlowEngine context — 
    this.context
    holds global data (e.g., 
    this.context.api
    , 
    this.context.dataSourceManager
    , 
    this.context.logger
    ). Read from it directly instead of creating Providers to pass data around. Note: some properties like 
    user
    , 
    viewer
    , 
    message
    , 
    themeToken
    are only available after React renders — use them in flow handlers or components, not in 
    load()
    .
  3. API requests — if the plugin needs data, use 
    this.app.apiClient.request()
    to fetch it directly. Axios interceptors are allowed but should not be the first choice — prefer direct requests or reading from context when possible.
  4. Pure DOM manipulation — operate on the DOM directly in 
    load()
    for visual effects. No React component needed.
  5. EventBus — 
    this.app.eventBus
    for reacting to app lifecycle events.
If you find yourself thinking "I need a Provider for this", stop and reconsider. There is always a better alternative.
this.app.use()
是内部API，插件严禁使用它通过React Providers包裹应用。这不是建议——这是无例外的硬性规则。
Providers会增加不必要的React渲染层，影响性能，且会提高插件维护难度。实现全局效果（水印、浮层、主题、追踪、全局监听器等）时，请改用以下方式：
  1. FlowEngine机制（首选）——使用
    registerModelLoaders
    、
    registerFlow
    、
    registerModels
    实现UI能力。
  2. FlowEngine上下文——
    this.context
    包含全局数据（如
    this.context.api
    、
    this.context.dataSourceManager
    、
    this.context.logger
    ）。直接从中读取数据，而非创建Providers传递数据。注意：部分属性如
    user
    、
    viewer
    、
    message
    、
    themeToken
    仅在React渲染后可用——请在流处理器或组件中使用，不要在
    load()
    中使用。
  3. API请求——若插件需要数据，直接使用
    this.app.apiClient.request()
    获取。允许使用Axios拦截器，但不应作为首选——优先选择直接请求或从上下文读取数据。
  4. 纯DOM操作——在
    load()
    中直接操作DOM实现视觉效果，无需React组件。
  5. EventBus——使用
    this.app.eventBus
    响应应用生命周期事件。
如果你在想“我需要用Provider来实现这个”，请停下来重新考虑。总有更好的替代方案。

Client code goes in 
client-v2
ONLY

客户端代码仅允许放在
client-v2
目录

All client-side plugin code must be written in 
src/client-v2/
. The 
src/client/
directory is for the legacy v1 client — do NOT write or modify any files there. Import 
Plugin
from 
@nocobase/client-v2
, never from 
@nocobase/client
.
所有客户端插件代码必须写在
src/client-v2/
目录下。
src/client/
目录用于遗留v1客户端——请勿在该目录下编写或修改任何文件。从
@nocobase/client-v2
导入
Plugin
，绝对不要从
@nocobase/client
导入。

Input Contract

输入约定

InputRequiredDefaultValidationClarification Question
requirement
yesnonenon-empty natural language description"What should this plugin do?"
nocobase_root
yescurrent working directorymust contain 
package.json
with 
@nocobase/server
"Where is your NocoBase project root directory?"
plugin_name
noderived from requirement
@<scope>/plugin-<name>
format		"What should the plugin package name be?"
Rules:
  • If 
    nocobase_root
    is not provided, check if the current working directory is a NocoBase project.
  • If 
    plugin_name
    is not provided, derive a reasonable name from the requirement and confirm with the user.
  • If user says "you decide", use documented defaults.
输入项是否必填默认值验证规则澄清问题
requirement
是无非空自然语言描述“该插件需要实现什么功能？”
nocobase_root
是当前工作目录必须包含带有
@nocobase/server
的
package.json
“你的NocoBase项目根目录在哪里？”
plugin_name
否从需求推导格式为
@<scope>/plugin-<name>
“插件包名称应该是什么？”
规则：
  • 若未提供
    nocobase_root
    ，检查当前工作目录是否为NocoBase项目。
  • 若未提供
    plugin_name
    ，从需求中推导合理名称并与用户确认。
  • 若用户表示“由你决定”，使用文档中规定的默认值。

Mandatory Clarification Gate

强制澄清环节

  • Max clarification rounds: 
    2
  • Max questions per round: 
    3
  • Mutation preconditions: 
    • nocobase_root
      is a valid NocoBase project with 
      yarn
      available.
    • requirement
      is clear enough to determine which extension points are needed.
    • Functional plan has been confirmed by the user in plain language.
  • If preconditions are not met after two rounds, stop and report what's missing.
CRITICAL: You MUST always confirm the plan with the user before writing any code or running any scaffold command — even if the requirement seems perfectly clear. Users often have unstated assumptions, edge cases they haven't considered, or preferences about scope. The plan confirmation step (Step 2) is a hard gate, not a suggestion. Never skip it.
  • 最大澄清轮次：
    2
  • 每轮最多提问数：
    3
  • 前置条件： 
    • nocobase_root
      是有效的NocoBase项目且可用
      yarn
      。
    • requirement
      足够清晰，可确定所需的扩展点。
    • 功能方案已通过用户用自然语言确认。
  • 若两轮后仍未满足前置条件，停止操作并告知缺失的内容。
重要提示：在编写任何代码或运行任何脚手架命令之前，必须与用户确认方案——即使需求看起来非常清晰。 用户通常会有未说明的假设、未考虑到的边缘情况，或对范围的偏好。方案确认步骤（步骤2）是硬性关卡，而非建议。绝不能跳过。

Workflow

工作流程

Step 0: Environment Check

步骤0：环境检查

  1. Verify 
    nocobase_root
    contains a valid NocoBase project (
    package.json
    with 
    @nocobase/server
    ).
  2. Verify 
    yarn
    is available.
  3. Detect environment type:
    • Source install: 
      packages/core/
      exists → AI can read source code for troubleshooting.
    • create-nocobase-app: no 
      packages/core/
      → rely on documentation and online references only.
  1. 验证
    nocobase_root
    包含有效的NocoBase项目（带有
    @nocobase/server
    的
    package.json
    ）。
  2. 验证
    yarn
    可用。
  3. 检测环境类型：
    • 源码安装：存在
      packages/core/
      目录 → AI可读取源码进行故障排查。
    • create-nocobase-app安装：无
      packages/core/
      目录 → 仅依赖文档和在线参考资料。

Step 1: Requirement Analysis

步骤1：需求分析

Analyze the user's requirement and determine which extension points are needed:
  • Server-side: collections, custom REST APIs, ACL, cron jobs, migrations, event listeners
  • Client-side: blocks (BlockModel/TableBlockModel), fields (FieldModel), actions (ActionModel), settings pages, routes
  • Both: full-stack plugins with server data + client UI
Do NOT ask the user about technical details (e.g., "Do you need a BlockModel or TableBlockModel?"). Map requirements to extension points internally.
分析用户需求并确定所需的扩展点：
  • 服务端：集合、自定义REST API、ACL、定时任务、迁移脚本、事件监听器
  • 客户端：区块（BlockModel/TableBlockModel）、字段（FieldModel）、操作（ActionModel）、设置页面、路由
  • 全栈：包含服务端数据+客户端UI的全栈插件
请勿询问用户技术细节（如“你需要BlockModel还是TableBlockModel？”）。内部将需求映射到扩展点即可。

Step 2: Plan Confirmation (HARD GATE)

步骤2：方案确认（硬性关卡）

This step is mandatory and must not be skipped, regardless of how clear the requirement appears. Even seemingly straightforward requirements can have unstated edge cases, scope preferences, or assumptions the user hasn't mentioned. Always present the plan and wait for explicit confirmation before proceeding to Step 3.
Present a functional plan in plain language the user can understand. Proactively highlight decisions the user may not have considered (e.g., "Should the data persist after plugin disable?", "Do you need a settings page for configuration?"). Example:
"Here's my plan:
  1. Create a settings page where you can configure the API key
  2. Add a scheduled task that syncs data every 5 minutes
  3. Create a data table to store the synced records
  4. The table will be available as a block in the UI
A few things to confirm:
  • Should the synced data be cleared when the plugin is disabled?
  • Do you need permission control for who can access the settings?
Does this look right?"
Do NOT run 
yarn pm create
or write any code until the user explicitly confirms.
此步骤为强制要求，无论需求看起来多么清晰，都不能跳过。 即使看似简单的需求也可能存在未说明的边缘情况、范围偏好或用户未提及的假设。在进入步骤3之前，必须始终呈现方案并等待用户明确确认。
用用户能理解的自然语言呈现功能方案。主动指出用户可能未考虑到的决策（如“插件禁用后数据是否需要保留？”、“是否需要设置页面用于配置？”）。示例：
“我的方案如下：
  1. 创建一个可配置API密钥的设置页面
  2. 添加一个每5分钟同步数据的定时任务
  3. 创建一个数据表存储同步的记录
  4. 该数据表将作为区块在UI中可用
需要确认几点：
  • 插件禁用后，同步的数据是否需要清除？
  • 是否需要权限控制来限制谁可以访问设置页面？
这个方案是否符合你的需求？”
在用户明确确认之前，请勿运行
yarn pm create
或编写任何代码。

Step 3: Scaffold Plugin

步骤3：搭建插件脚手架

The exact command is:
bash
yarn pm create <plugin_name>
正确命令如下：
bash
yarn pm create <plugin_name>

Example: yarn pm create @nocobase-sample/plugin-hello

示例：yarn pm create @nocobase-sample/plugin-hello

Creates: packages/plugins/@nocobase-sample/plugin-hello/

创建目录： packages/plugins/@nocobase-sample/plugin-hello/


This is the only correct command. Do NOT use `create-plugin`, `generate`, or any other variant. Do NOT look up alternatives — just run it.

Read `references/getting-started.md` for the expected project structure.

这是唯一正确的命令。请勿使用`create-plugin`、`generate`或任何其他变体。请勿查找替代方案——直接运行该命令即可。

阅读`references/getting-started.md`了解预期的项目结构。

Step 4: Generate Code (MUST Read References First)

步骤4：生成代码（必须先阅读参考文档）

You MUST read the relevant reference files BEFORE writing any code. Do NOT skip this by searching source code, reading examples, or relying on prior knowledge. The references contain project-specific conventions that override general knowledge.
Read 
references/index.md
to locate the relevant reference files, then read the ones needed for this plugin.
在编写任何代码之前，必须先阅读相关参考文件。 请勿通过搜索源码、查看示例或依赖已有知识跳过此步骤。参考文档包含项目专属约定，优先级高于通用知识。
阅读
references/index.md
定位相关参考文件，然后阅读当前插件所需的文件。

Mandatory Reference Rules

强制参考规则

These are hard gates, not suggestions. Read the file BEFORE editing the corresponding code:
When you edit...You MUST first read
src/client-v2/plugin.tsx
references/client/plugin.md
src/server/plugin.ts
references/server/plugin.md
Any file in 
src/client-v2/models/
references/client/block.md
, 
references/client/field.md
, or 
references/client/action.md
(whichever applies)
Any file in 
src/server/collections/
references/server/collection.md
这些是硬性关卡，而非建议。编辑对应代码之前必须先阅读指定文件：
当你编辑...必须先阅读
src/client-v2/plugin.tsx
references/client/plugin.md
src/server/plugin.ts
references/server/plugin.md
src/client-v2/models/
下的任何文件
references/client/block.md
、
references/client/field.md
或
references/client/action.md
（根据适用情况选择）
src/server/collections/
下的任何文件
references/server/collection.md

Keyword-Triggered References

关键字触发的参考文档

If your implementation involves any of these concepts, you MUST also read the corresponding reference:
Keywords in your codeMUST read
route
, 
router
, 
navigate
, 
location
, 
pathname
references/client/router.md
and 
references/client/ctx.md
ctx.api
, 
ctx.viewer
, 
ctx.message
, 
ctx.model
references/client/ctx.md
registerFlow
, 
uiSchema
, 
on:
event handlers
references/client/flow.md
resource
, 
MultiRecordResource
, 
SingleRecordResource
references/client/resource.md
tExpr
, 
useT
, 
this.t
references/client/i18n.md
acl.allow
, permissions
references/server/acl.md
defineCollection
, fields, relations
references/server/collection.md
如果你的实现涉及以下概念，还必须阅读对应的参考文档：
代码中的关键字必须阅读
route
、
router
、
navigate
、
location
、
pathname
references/client/router.md
和
references/client/ctx.md
ctx.api
、
ctx.viewer
、
ctx.message
、
ctx.model
references/client/ctx.md
registerFlow
、
uiSchema
、
on:
事件处理器
references/client/flow.md
resource
、
MultiRecordResource
、
SingleRecordResource
references/client/resource.md
tExpr
、
useT
、
this.t
references/client/i18n.md
acl.allow
、权限
references/server/acl.md
defineCollection
、字段、关联
references/server/collection.md

Generation Order

生成顺序

Flexible — adapt to the plugin's needs:
  • Server-first when the plugin has data tables and APIs.
  • Client-first when the plugin is purely frontend.
  • Interleaved when both sides are tightly coupled.
Checkpoint before writing client code: Review the "Hard Constraints" section. Never use 
this.app.use()
or Providers. Use FlowEngine, context, pure DOM, or EventBus instead.
灵活调整——适配插件需求：
  • 若插件包含数据表和API，优先开发服务端。
  • 若插件纯前端，优先开发客户端。
  • 若前后端紧密耦合，可交替开发。
编写客户端代码前的检查点：回顾“硬性约束”部分。绝不使用
this.app.use()
或Providers。改用FlowEngine、上下文、纯DOM或EventBus。

Step 5: Internationalization

步骤5：国际化

Default behavior (do NOT ask):
  • Always generate 
    src/locale/zh-CN.json
    and 
    src/locale/en-US.json
    .
  • Use the plugin's auto-generated 
    locale.ts
    for 
    tExpr
    and 
    useT
    imports.
Only ask about additional languages if:
  • The user explicitly mentions other languages, OR
  • The user is communicating in a language other than Chinese or English.
默认行为（无需询问）：
  • 始终生成
    src/locale/zh-CN.json
    和
    src/locale/en-US.json
    文件。
  • 使用插件自动生成的
    locale.ts
    导入
    tExpr
    和
    useT
    。
仅在以下情况询问是否需要额外语言：
  • 用户明确提及其他语言，或
  • 用户使用中文或英文以外的语言沟通。

Step 6: Enable and Verify

步骤6：启用并验证

bash
yarn pm enable <plugin_name>
After enabling, describe what the user should see in the UI and how to test the plugin.
bash
yarn pm enable <plugin_name>
启用后，告知用户在UI中应看到的内容以及如何测试插件。

Default Behaviors

默认行为

These defaults apply unless the user explicitly requests otherwise. Do NOT ask about them.
DecisionDefaultWhen to ask
Client version
client-v2
ONLY. All client code in 
src/client-v2/
. Never use 
src/client/
or import from 
@nocobase/client
Never
Model registration
registerModelLoaders
(lazy loading)		Never
Route registration
componentLoader
(lazy loading)		Never
Settings page registration
pluginSettingsManager.addMenuItem()
+ 
addPageTabItem()
with 
componentLoader
Never
ACL
acl.allow('*', '*', 'loggedIn')
User mentions fine-grained permissions
Locale files
zh-CN.json
+ 
en-US.json
User mentions other languages
addCollection
(client-side)		Do NOT add — recommend UI "Data Source Management" insteadOnly as a demo; if needed, use 
eventBus
pattern (NOT direct call in 
load()
)
install()
seed data		Do NOT addUser mentions preset/demo data
tExpr
import		From plugin's 
locale.ts
, NOT from 
@nocobase/flow-engine
directly		Never
this.app.use()
(Provider)		Do NOT use — use FlowEngine mechanisms or pure DOM instead. See 
client/plugin.md
Never
以下默认行为适用于用户未明确要求的情况。无需询问。
决策默认值询问时机
客户端版本仅使用
client-v2
。所有客户端代码放在
src/client-v2/
目录。绝不使用
src/client/
或从
@nocobase/client
导入		绝不
模型注册使用
registerModelLoaders
（懒加载）		绝不
路由注册使用
componentLoader
（懒加载）		绝不
设置页面注册使用
pluginSettingsManager.addMenuItem()
+ 
addPageTabItem()
并搭配
componentLoader
绝不
ACL使用
acl.allow('*', '*', 'loggedIn')
用户提及细粒度权限时
语言包文件
zh-CN.json
+ 
en-US.json
用户提及其他语言时
addCollection
（客户端）		不添加——推荐使用UI“数据源管理”功能仅用于演示；若确实需要，使用
eventBus
模式（不要在
load()
中直接调用）
install()
种子数据		不添加用户提及预设/演示数据时
tExpr
导入		从插件的
locale.ts
导入，而非直接从
@nocobase/flow-engine
导入		绝不
this.app.use()
（Provider）		不使用——改用FlowEngine机制或纯DOM操作。详见
client/plugin.md
绝不

Troubleshooting

故障排查

When the plugin doesn't work as expected:
当插件未按预期工作时：

FAQ Checklist

FAQ清单

  1. Plugin not appearing in plugin manager → Check 
    package.json
    has correct NocoBase metadata. Run 
    yarn pm enable <name>
    .
  2. Collection not showing in block picker → Recommend user to add the table via NocoBase UI "Data Source Management". If code-level registration is needed (demo only), use 
    addCollection
    with 
    filterTargetKey: 'id'
    and 
    eventBus
    pattern. See 
    client/plugin.md
    .
  3. Settings page shows blank → Verify using 
    componentLoader
    (not 
    Component
    ) for client-v2.
  4. Model not appearing in menus → Check 
    define({ label: tExpr('...') })
    and 
    registerModelLoaders
    in plugin 
    load()
    .
  5. load()
    database query fails     → 
    load()
    runs before DB sync. Move DB operations to 
    install()
    or request handlers.
  6. i18n not working → First-time locale files require app restart. Check 
    tExpr
    is imported from 
    locale.ts
    not 
    @nocobase/flow-engine
    .
  7. registerFlow handler not firing → Check 
    on
    event name. Use 
    'click'
    for buttons, 
    'beforeRender'
    for initialization.
  1. 插件未出现在插件管理器中 → 检查
    package.json
    是否包含正确的NocoBase元数据。运行
    yarn pm enable <name>
    。
  2. 集合未出现在区块选择器中 → 建议用户通过NocoBase UI“数据源管理”添加数据表。若需要代码级注册（仅用于演示），使用
    addCollection
    并搭配
    filterTargetKey: 'id'
    和
    eventBus
    模式。详见
    client/plugin.md
    。
  3. 设置页面显示空白 → 验证客户端v2是否使用
    componentLoader
    （而非
    Component
    ）。
  4. 模型未出现在菜单中 → 检查
    define({ label: tExpr('...') })
    以及插件
    load()
    中的
    registerModelLoaders
    。
  5. load()
    数据库查询失败     → 
    load()
    在数据库同步前运行。将数据库操作移至
    install()
    或请求处理器中。
  6. 国际化不生效 → 首次添加语言包文件需要重启应用。检查
    tExpr
    是否从
    locale.ts
    导入，而非
    @nocobase/flow-engine
    。
  7. registerFlow处理器未触发 → 检查
    on
    事件名称。按钮使用
    'click'
    ，初始化使用
    'beforeRender'
    。

Source Code Debugging (Source Install Only)

源码调试（仅源码安装环境）

If the environment is a source install, the AI agent may read NocoBase core source code to debug issues:
packages/core/server/src/          — Server core
packages/core/client/src/          — Client core (v1, reference only)
packages/core/client-v2/src/       — Client core (v2, recommended)
packages/core/database/src/        — Database layer
packages/core/flow-engine/src/     — FlowEngine
若环境为源码安装，AI Agent可读取NocoBase核心源码排查问题：
packages/core/server/src/          — 服务端核心
packages/core/client/src/          — 客户端核心（v1，仅作参考）
packages/core/client-v2/src/       — 客户端核心（v2，推荐）
packages/core/database/src/        — 数据库层
packages/core/flow-engine/src/     — FlowEngine

Complete Example Plugins

完整示例插件

When a full working example is needed:
当需要完整的可运行示例时：

Reference Loading Map

参考文档加载映射

ReferenceUse WhenNotes
references/index.mdAlways, after Step 1Global index — read this to find relevant module references
references/getting-started.mdStep 3 (scaffolding)Plugin scaffold + project structure
references/server/*.mdPlugin needs server-side codeOne file per server module
references/client/*.mdPlugin needs client-side codeOne file per client module
references/build.mdUser asks about building/packagingBuild and distribution
参考文档使用时机说明
references/index.md步骤1之后，始终使用全局索引——阅读此文档查找相关模块参考
references/getting-started.md步骤3（搭建脚手架）插件脚手架+项目结构
references/server/*.md插件需要服务端代码时每个服务端模块对应一个文件
references/client/*.md插件需要客户端代码时每个客户端模块对应一个文件
references/build.md用户询问构建/打包相关问题时构建与分发

Safety Gate

安全关卡

High-impact actions:
  • Running 
    yarn pm create
    (creates files in user's project)
  • Running 
    yarn pm enable
    (modifies database state)
  • Modifying existing plugin files (if plugin already exists)
Secondary confirmation template:
  • "I'm about to run 
    {{command}}
    in 
    {{directory}}
    . This will {{impact}}. Should I proceed?"
Rollback guidance:
  • If 
    yarn pm create
    produced wrong scaffold → delete the generated directory and re-run.
  • If plugin code has bugs after enable → fix the code, the plugin can be disabled with 
    yarn pm disable <name>
    .
  • Never run 
    yarn nocobase install -f
    without explicit user confirmation — it resets the database.
高影响操作：
  • 运行
    yarn pm create
    （在用户项目中创建文件）
  • 运行
    yarn pm enable
    （修改数据库状态）
  • 修改现有插件文件（若插件已存在）
二次确认模板：
  • “我将在
    {{directory}}
    目录下运行
    {{command}}
    ，这会{{impact}}。是否继续？”
回滚指南：
  • 若
    yarn pm create
    生成了错误的脚手架 → 删除生成的目录并重新运行。
  • 若启用后插件代码存在bug → 修复代码，可使用
    yarn pm disable <name>
    禁用插件。
  • 未经用户明确确认，绝不运行
    yarn nocobase install -f
    ——该命令会重置数据库。

Verification Checklist

验证清单

  • NocoBase project root is valid and 
    yarn
    is available.
  • Environment type (source vs create-nocobase-app) is detected.
  • User requirement is analyzed and extension points are identified.
  • Functional plan is confirmed by user before code generation.
  • Plugin scaffold is created successfully.
  • All generated files follow NocoBase conventions (client-v2, lazy loading, locale.ts).
  • No 
    this.app.use()
    or React Provider patterns in generated code (Hard Constraint).
  • zh-CN.json
    and 
    en-US.json
    are generated with all translatable strings.
  • Plugin can be enabled with 
    yarn pm enable
    without errors.
  • Generated code matches the patterns in reference templates.
  • FAQ checklist is consulted when issues arise.
  • NocoBase项目根目录有效且
    yarn
    可用。
  • 已检测环境类型（源码安装vs create-nocobase-app安装）。
  • 已分析用户需求并确定扩展点。
  • 功能方案已通过用户确认后才开始生成代码。
  • 插件脚手架已成功创建。
  • 所有生成文件符合NocoBase约定（client-v2、懒加载、locale.ts）。
  • 生成代码中无
    this.app.use()
    或React Provider模式（硬性约束）。
  • 已生成
    zh-CN.json
    和
    en-US.json
    ，包含所有可翻译字符串。
  • 插件可通过
    yarn pm enable
    成功启用且无错误。
  • 生成代码与参考模板中的模式一致。
  • 出现问题时已查阅FAQ清单。

Minimal Test Scenarios

最小测试场景

  1. User requests a simple settings page plugin → scaffold + server API + client settings page.
  2. User requests a custom block plugin → scaffold + BlockModel + registerFlow + i18n.
  3. User requests a full-stack CRUD plugin → scaffold + defineCollection + ACL + TableBlockModel + custom field + custom action.
  4. User provides vague requirement → clarification gate triggers, plan is confirmed before coding.
  5. Plugin enable fails → FAQ checklist is consulted, source code is read if available.
  1. 用户请求简单的设置页面插件 → 脚手架+服务端API+客户端设置页面。
  2. 用户请求自定义区块插件 → 脚手架+BlockModel+registerFlow+国际化。
  3. 用户请求全栈CRUD插件 → 脚手架+defineCollection+ACL+TableBlockModel+自定义字段+自定义操作。
  4. 用户提供模糊需求 → 触发澄清环节，编码前确认方案。
  5. 插件启用失败 → 查阅FAQ清单，若可用则读取源码。

Output Contract

输出约定

Final response must include:
  • What was requested (user's original requirement).
  • What was created (list of generated files).
  • How to enable and test (commands + expected UI behavior).
  • What assumptions/defaults were applied.
  • Known limitations or next steps (if any).
最终响应必须包含：
  • 用户的原始需求。
  • 创建的内容（生成文件列表）。
  • 启用和测试方法（命令+预期UI行为）。
  • 应用的假设/默认值。
  • 已知限制或后续步骤（若有）。

References

参考资料