什么是 NocoBase

NocoBase 是一个开源的 AI + 无代码平台，用于快速构建业务系统。与从零开始生成所有内容不同，AI 在经过生产验证的基础设施和所见即所得（WYSIWYG）的无代码界面上工作，既能保证开发速度，又能确保系统的稳定性和可靠性。

资料来源：README.md:1-10

核心价值主张

NocoBase 的核心价值在于将人工智能与无代码技术相结合，让开发者和业务用户能够：

• 快速构建：通过可视化配置而非传统编码方式快速搭建业务系统
• AI 赋能：借助 AI Agent 实现自动化和智能化的业务流程
• 灵活扩展：支持插件化架构，可根据需求扩展功能
• 协作共建：AI 和人类协同工作，共同构建系统

资料来源：README.md:47-52

概述

NocoBase 采用分层模块化架构设计，核心遵循插件化架构（Plugin Architecture）和配置驱动架构（Configuration-driven Architecture）两大设计理念。系统分为服务端（Server）和客户端（Client）两大主体，通过插件机制实现功能扩展，通过 Schema 配置驱动实现前端界面与业务逻辑的解耦。

核心架构分层

架构层次总览

    A[客户端 Client] --> B[应用层 Application]
    A --> C[Schema 组件层]
    A --> D[Schema 配置层]
    B --> E[插件管理层 PM]
    C --> F[数据区块 Provider]
    D --> G[Schema 设计器]
    E --> H[插件 Plugin]
    H --> I[服务端插件]
    H --> J[客户端插件]

服务端架构

服务端基于 Plugin 插件基类构建，所有业务模块均以插件形式注册。插件系统提供了完整的生命周期管理，包括 load、enable、disable 等状态转换。

    A[Application] --> B[Plugin Manager]
    A --> C[数据层 Data]
    A --> D[认证层 Auth]
    B --> E[Plugin 实例]
    E --> F[install]
    E --> G[load]
    E --> H[enable]
    E --> I[disable]

服务端 Application 类负责统一管理插件的加载与初始化流程，通过 pm（Plugin Manager）实现插件的注册、启用、停用等操作。资料来源：packages/core/server/src/application.ts

客户端架构

客户端采用 React Context 进行状态管理和依赖注入，主要包括以下几个核心模块：

插件系统设计

插件架构模式

NocoBase 的插件系统采用观察者模式与依赖注入模式相结合的架构。每个插件包含服务端和客户端两部分，通过统一的插件管理器进行协调。

graph TD
    subgraph 服务端
        A1[Plugin 基类] --> A2[install 方法]
        A1 --> A3[load 方法]
        A1 --> A4[enable 方法]
    end
    
    subgraph 客户端
        B1[React Component] --> B2[Configuration]
        B1 --> B3[Settings]
        B1 --> B4[Initializer]
    end
    
    A1 --> B1

插件元数据管理

插件详情组件 PluginDetail 展示插件的完整信息，包括版本、依赖兼容性、许可证等。依赖兼容性检查机制确保插件间的版本匹配。

// 插件详情信息结构
interface PluginInfo {
  packageName: string;      // 包名
  version: string;          // 版本号
  description?: string;    // 描述
  author?: string;         // 作者
  homepage?: string;       // 主页
  license?: string;        // 许可证
  depsCompatible?: boolean; // 依赖兼容性
}

资料来源：packages/core/client/src/pm/PluginDetail.tsx

依赖兼容性检查

插件系统内置依赖兼容性检查机制，通过 externalVersion.js 文件记录插件的外部依赖版本信息。检查结果通过 isCompatible 字段标识，兼容性检查失败时会显示错误提示。

Schema 驱动架构

Schema 设计理念

NocoBase 的前端界面完全由 Schema 配置驱动。Schema 是 JSON 格式的配置对象，定义了界面的结构、行为和样式。这种设计实现了界面与逻辑的分离，使非开发人员也能通过配置自定义系统功能。

graph LR
    A[Schema JSON] --> B[Schema 解析器]
    B --> C[SchemaComponent]
    B --> D[SchemaSettings]
    B --> E[SchemaInitializer]
    C --> F[用户界面]

Schema 组件层级

SchemaToolbar 组件

GeneralSchemaDesigner 是 Schema 设计器的核心组件，负责渲染 Schema 的工具栏界面，包括标题、拖拽手柄、初始化器和配置下拉菜单。

interface SchemaToolbarProps {
  title?: string | string[];
  template?: boolean;
  draggable?: boolean;
  showDataSource?: boolean;
  templateName?: string;
}

资料来源：packages/core/client/src/schema-settings/GeneralSchemaDesigner.tsx

流程引擎架构

FlowSettings 配置系统

流程引擎（Flow Engine）采用配置化设计，通过 FlowSettings 类管理流程节点组件和作用域变量。

class FlowSettings {
  public components: Record<string, any> = {};  // 节点组件映射
  public scopes: Record<string, any> = {};      // 作用域变量
  private antdComponentsLoaded = false;
  public enabled: boolean;
  #forceEnabled = false;
}

资料来源：packages/core/flow-engine/src/flowSettings.ts

流程配置 Footer 自定义

流程设置支持四种 Footer 配置模式：

变量系统

内置变量机制

系统提供内置变量支持，通过 useBuiltInVariables Hook 获取。内置变量包括用户上下文、日期时间、URL 参数等。

// 内置变量列表
const builtinVariables = [
  { name: '$nUser', ctx: currentUserCtx },
  { name: '$nRole', ctx: currentRoleCtx },
  { name: '$nDate', ctx: datetimeCtx },
  { name: '$nExactDate', ctx: exactDateTimeCtx },
  { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx },
  { name: '$env', ctx: envVariableCtx },
];

已废弃的兼容变量包括 $date、$system、currentTime，建议使用新版变量名替代。

资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts

设计模式总结

核心设计模式

模块间通信

sequenceDiagram
    participant App as Application
    participant PM as Plugin Manager
    participant Plugin as Plugin
    participant Schema as SchemaComponent
    
    App->>PM: 注册插件
    PM->>Plugin: 实例化
    Plugin->>Plugin: load()
    Plugin->>Schema: 注册组件
    Schema->>Schema: 渲染界面

移动端适配

系统通过 DesktopMode 组件实现移动端与桌面端的视图切换，当检测到非移动端设备访问移动端页面时，渲染桌面端适配组件。

<DesktopMode>
  <Mobile />
</DesktopMode>

系统信息与帮助

Help 组件负责展示系统信息，包括版本号（data?.data?.version）、文档链接、许可证信息等。根据语言设置（isSimplifiedChinese）动态切换中英文文档地址。

资料来源：packages/core/client/src/user/Help.tsx

概述

NocoBase 的数据建模与集合管理模块是整个平台的核心基础设施，负责定义数据结构、管理数据关系、提供数据访问接口。该模块采用面向集合（Collection）的数据建模范式，支持多数据源管理，并提供了完整的 CRUD 操作能力。

数据建模系统的主要职责包括：

• 集合定义：定义数据集合的结构、字段和约束
• 字段管理：支持多种字段类型和数据验证规则
• 数据访问：通过 Repository 模式提供统一的数据操作接口
• 多数据源：支持连接不同类型的数据源（主数据库、远程服务等）
• Schema 管理：将数据模型与前端 Schema 绑定，实现 UI 联动

资料来源：packages/core/database/src/collection.ts

核心概念

集合（Collection）

集合是 NocoBase 中数据组织的基本单元，类似于传统数据库中的表概念。每个集合包含以下关键属性：

集合通过 Database 实例进行注册和管理，支持热插拔式的数据模型变更。

字段（Field）

字段是集合中的数据列定义，支持多种数据类型：

• 普通字段：字符串、数字、布尔值、日期等
• 关系字段：belongsTo、hasOne、hasMany、belongsToMany
• 特殊字段：json、radio、checkbox、sequence 等

资料来源：packages/core/database/src/field.ts

架构设计

graph TD
    A[数据建模层] --> B[CollectionManager]
    A --> C[数据源管理器]
    B --> D[Collection 集合]
    D --> E[Field 字段]
    D --> F[Repository 数据访问]
    C --> G[主数据源]
    C --> H[远程数据源]
    G --> I[MySQL/PostgreSQL/SQLite]
    H --> J[外部 API]

层次结构

NocoBase 数据建模系统分为三个主要层次：

1. Schema 层：定义数据结构的元信息
2. Collection 层：将 Schema 实例化为可操作的集合
3. Repository 层：提供数据访问的抽象接口

classDiagram
    class Collection {
        +name: string
        +fields: Field[]
        +repository: Repository
        +create(data)
        +update(id, data)
        +delete(id)
        +find(params)
    }
    
    class Field {
        +name: string
        +type: string
        +options: object
        +validate(data)
    }
    
    class Repository {
        +create(data)
        +find(params)
        +update(id, data)
        +destroy(id)
        +count(params)
    }
    
    class Database {
        +registerCollections()
        +getCollection(name)
    }
    
    Collection "1" --> "*" Field : contains
    Collection --> Repository
    Database --> Collection : manages

资料来源：packages/core/database/src/collection.ts:1-100

集合管理

CollectionManager

CollectionManager 是集合管理的核心类，负责维护所有已注册的集合实例：

// 伪代码示例
class CollectionManager {
  collections: Map<string, Collection>;
  
  getCollection(name: string): Collection;
  registerCollection(collection: Collection): void;
  removeCollection(name: string): void;
  getCollections(options?: FilterOptions): Collection[];
}

集合注册流程

sequenceDiagram
    participant User as 用户/开发者
    participant DB as Database
    participant CM as CollectionManager
    participant Col as Collection
    
    User->>DB: registerCollection(config)
    DB->>CM: addCollection(name, config)
    CM->>Col: new Collection(config)
    Col->>Col: parse fields
    Col->>Col: create repository
    CM->>DB: collection registered
    DB-->>User: success

资料来源：packages/core/database/src/collection.ts

集合配置组件

在前端，集合配置通过 Summary 组件展示：

const Summary: React.FC<SummaryProps> = ({ label, schema }) => {
  // 展示集合配置的摘要信息
  return (
    <div style={styles.container}>
      <div style={styles.title}>
        {label}: <Tag>{compile(schema.title)}</Tag>
      </div>
      {schema.description && <div>{compile(schema.description)}</div>}
    </div>
  );
};

该组件负责渲染集合的名称和描述信息，支持国际化配置。

资料来源：packages/core/client/src/collection-manager/Configuration/components/Summary.tsx

字段系统

字段类型

NocoBase 支持丰富的字段类型，定义在 field.ts 中：

字段定义

interface FieldOptions {
  type: string;
  name: string;
  title?: string;
  description?: string;
  defaultValue?: any;
  uiSchema?: object;
  validation?: ValidationRule[];
  unique?: boolean;
  allowNull?: boolean;
  primaryKey?: boolean;
}

字段支持级联配置，包括验证规则、默认值、UI 组件绑定等。

资料来源：packages/core/database/src/field.ts

Repository 数据访问层

Repository 模式

Repository 提供统一的数据访问接口，封装了底层数据库操作：

interface IRepository {
  // 创建
  create(data: object, options?: CreateOptions): Promise<object>;
  createMany(data: object[], options?: CreateOptions): Promise<object[]>;
  
  // 查询
  find(params: FindParams): Promise<object[]>;
  findOne(params: FindParams): Promise<object | null>;
  findById(id: any): Promise<object>;
  count(params?: FilterParams): Promise<number>;
  
  // 更新
  update(params: UpdateParams): Promise<object[]>;
  updateById(id: any, data: object): Promise<object>;
  
  // 删除
  destroy(params: FilterParams): Promise<number>;
  destroyById(id: any): Promise<void>;
  
  // 关联操作
  add(field: string, id: any, relatedIds: any[]): Promise<void>;
  set(field: string, id: any, relatedIds: any[]): Promise<void>;
  remove(field: string, id: any, relatedIds: any[]): Promise<void>;
}

查询构建器

Repository 内置强大的查询构建能力：

// 基础查询
repository.find({
  filter: { status: 'active' },
  fields: ['id', 'name'],
  sort: ['createdAt'],
  page: 1,
  pageSize: 20
});

// 关联查询
repository.find({
  filter: { 'profile.nickname.$contains': 'admin' },
  appends: ['profile']
});

资料来源：packages/core/database/src/repository.ts

数据源管理

数据源管理器插件

plugin-data-source-manager 负责管理多数据源连接：

graph LR
    A[应用层] --> B[数据源管理器]
    B --> C[主数据源<br/>Main Database]
    B --> D[远程数据源<br/>Remote Data Source]
    B --> E[第三方服务]
    
    C --> F[MySQL/PostgreSQL]
    D --> G[REST API]
    D --> H[GraphQL]

数据源配置

数据源隔离

NocoBase 支持逻辑隔离的数据源架构，每个数据源可以：

• 拥有独立的连接池
• 使用不同的数据库引擎
• 配置独立的迁移策略
• 实现独立的缓存策略

Schema 集成

Schema 与集合绑定

数据模型通过 Schema 与前端组件绑定：

const schema = {
  type: 'object',
  'x-collection': 'users',
  properties: {
    name: {
      type: 'string',
      'x-field': 'name'
    },
    email: {
      type: 'string',
      'x-field': 'email'
    }
  }
};

Schema 初始化器

Schema 初始化器提供了动态插入 Schema 的能力：

// 插入 Schema 配置
const initializerConfig = {
  title: 'Form Item',
  type: 'object',
  'x-component': 'FormItem',
  properties: {
    field1: {
      type: 'string',
      'x-component': 'Input'
    }
  }
};

支持动态显示/隐藏、动态加载子节点等高级功能。

资料来源：packages/core/client/src/schema-initializer/index.md

内置变量与上下文

变量系统

数据模型支持在运行时使用内置变量：

const builtinVariables = [
  { name: '$nDate', ctx: datetimeCtx },
  { name: '$nExactDate', ctx: exactDateTimeCtx },
  { name: '$nRole', ctx: currentRoleCtx },
  { name: '$nUser', ctx: currentUserCtx },
  { name: '$nUrlSearchParams', ctx: urlSearchParamsCtx }
];

上下文变量

资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts

工作流程

数据操作完整流程

graph TD
    A[前端请求] --> B[Schema 验证]
    B --> C{请求类型}
    C -->|Create| D[数据验证]
    C -->|Read| E[查询构建]
    C -->|Update| F[变更检测]
    C -->|Delete| G[软删除检查]
    
    D --> H[事务开始]
    E --> I[Repository.find]
    F --> H
    G --> H
    
    H --> J[数据库操作]
    J --> K[事务提交]
    K --> L[返回结果]
    
    I --> L

集合管理器初始化流程

sequenceDiagram
    participant App as 应用启动
    participant DB as Database
    participant CM as CollectionManager
    participant Plugin as 插件加载
    
    App->>DB: initialize()
    DB->>CM: 创建实例
    CM->>Plugin: 加载数据源插件
    Plugin->>CM: registerCollection()
    CM->>CM: 创建 Collection 实例
    CM->>CM: 解析字段定义
    CM->>CM: 创建 Repository
    Plugin-->>DB: 注册完成
    DB-->>App: 数据库就绪

最佳实践

集合命名规范

• 使用小写字母和下划线：user_profiles
• 避免使用保留字：order, user, group
• 使用单数名词：user 而非 users
• 有意义的名称：order_items 而非 oi

字段设计建议

1. 主键设计：每个集合应定义主键字段
2. 时间戳：建议包含 createdAt 和 updatedAt 字段
3. 软删除：使用 deletedAt 而非物理删除
4. 索引：频繁查询字段添加索引配置

关系设计原则

// 一对多关系示例
const postCollection = {
  name: 'posts',
  fields: [
    { type: 'string', name: 'title' },
    { 
      type: 'hasMany', 
      name: 'comments',
      foreignKey: 'postId'
    }
  ]
};

// 评论表定义
const commentCollection = {
  name: 'comments',
  fields: [
    { type: 'string', name: 'content' },
    { type: 'integer', name: 'postId' },
    { 
      type: 'belongsTo', 
      name: 'post',
      foreignKey: 'postId'
    }
  ]
};

总结

NocoBase 的数据建模与集合管理系统提供了完整的数据建模解决方案：

1. 灵活的集合定义：支持多种字段类型和复杂的数据结构
2. 强大的数据访问：通过 Repository 模式提供统一的 CRUD 接口
3. 多数据源支持：可连接多种类型的数据库和外部服务
4. Schema 驱动：与前端组件无缝集成，实现数据与 UI 联动
5. 变量系统：运行时支持丰富的上下文变量

该系统设计遵循低耦合、高内聚的原则，便于扩展和维护，是 NocoBase 作为无代码平台的核心支撑模块。

概述

NocoBase 的权限系统基于 ACL（Access Control List，访问控制列表） 机制实现。该系统采用角色（Role）和资源（Resource）两层的权限管理模式，支持细粒度的操作级别控制。权限系统贯穿整个应用，从服务端到客户端均有完整的权限校验链路，确保数据安全和操作合规。

核心概念

资料来源：packages/core/server/src/acl/role.ts:1-20

架构设计

整体架构

graph TD
    A[用户请求] --> B[ACL 中间件]
    B --> C{权限校验}
    C -->|通过| D[业务逻辑处理]
    C -->|拒绝| E[返回 403 错误]
    D --> F[数据响应]
    
    G[角色管理] --> H[角色权限配置]
    H --> I[Snippet 定义]
    I --> C

服务端架构

服务端 ACL 模块位于 packages/core/server/src/acl/ 目录，包含以下核心组件：

• ACL 类：权限系统的核心管理器，负责加载权限规则、执行权限校验
• Role 类：角色实体，封装角色的权限配置信息
• 中间件：拦截请求并进行权限验证

graph LR
    A[Request] --> B[ACL Middleware]
    B --> C[ACL Manager]
    C --> D[Role Manager]
    D --> E[Snippet Matcher]
    E --> F{Permission Check}
    F -->|Match| G[Allow]
    F -->|No Match| H[Deny]

资料来源：packages/core/server/src/acl/acl.ts:1-30

客户端架构

客户端通过 React Context 提供 ACL 上下文，使用 Hook 方式暴露权限判断能力：

// ACL Provider 提供全局上下文
<ACLProvider>
  <App />
</ACLProvider>

// 子组件中使用权限 Hook
const { allow, snippets } = useACLRoleContext();

资料来源：packages/core/client/src/application/hooks/useAclSnippets.ts:10-20

角色与权限

角色定义

角色是权限管理的基本单位，每个角色包含以下属性：

资料来源：packages/core/server/src/acl/role.ts:20-40

预定义内置变量

NocoBase 在权限上下文中注入了多个内置变量，用于权限判断和动态规则：

资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts:20-50

Snippet 匹配机制

系统使用 ignore 库实现 Snippet 的模式匹配，支持通配符和否定前缀：

const ig = ignore().add(snippets);
const appAllowed = allowAll || ig.ignores(aclSnippet);

匹配规则：

• allowAll 为 true 时，跳过 Snippet 校验，直接放行
• 使用 ignore 库的标准 glob 匹配规则
• 支持 ! 前缀表示显式拒绝

资料来源：packages/core/client/src/application/hooks/useAclSnippets.ts:12-18

权限配置

Schema 中的权限声明

在数据 Schema 中通过 x-acl-action 字段声明权限要求：

const schema: ISchema = {
  type: 'void',
  'x-acl-action': 'collections:view',  // 声明需要的权限
  'x-decorator': 'DetailsBlockProvider',
  'x-component': 'CardItem',
};

资料来源：packages/core/client/src/schema-initializer/utils.ts:15-25

权限操作类型

资料来源：packages/core/client/src/schema-initializer/utils.ts:22-30

插件系统集成

插件兼容性检查

NocoBase 的插件管理界面集成了 ACL 权限校验，插件详情页提供依赖兼容性检查功能：

{
  key: 'dependencies',
  label: t('Dependencies compatibility check'),
  children: (
    <>
      <Table
        columns={dependenciesCompatibleTableColumns}
        dataSource={data?.data?.depsCompatible}
      />
    </>
  ),
}

资料来源：packages/core/client/src/pm/PluginDetail.tsx:80-100

插件权限声明

插件可通过配置文件声明所需的权限：

{
  "name": "@nocobase/plugin-sample",
  "permissions": [
    "collections:view",
    "collections:create",
    "!system:admin"
  ]
}

工作流程

权限校验流程

sequenceDiagram
    participant Client as 客户端
    participant Middleware as ACL 中间件
    participant ACL as ACL 管理器
    participant Role as 角色管理器
    participant Resource as 资源

    Client->>Middleware: 请求资源
    Middleware->>ACL: 发起权限校验
    ACL->>Role: 获取用户角色
    Role-->>ACL: 返回角色配置
    ACL->>ACL: 匹配 Snippet
    ACL-->>Middleware: 校验结果
    Middleware->>Resource: 允许/拒绝访问

客户端权限 Hook 使用

import { useAclSnippets } from '@nocobase/client';

function MyComponent() {
  const { allow } = useAclSnippets();
  
  // 检查特定权限
  if (!allow('collections:view')) {
    return <NoPermission />;
  }
  
  return <Content />;
}

资料来源：packages/core/client/src/application/hooks/useAclSnippets.ts:1-25

最佳实践

1. 合理设计角色

建议采用最小权限原则，按业务职能划分角色：

2. 使用 Snippet 组合

将常用权限组合定义为 Snippet，便于复用：

// 定义 Snippet
snippets: [
  'collections:view',
  'collections:create',
  'collections:update',
]

// 使用通配符
snippets: [
  'collections:*',      // 所有集合操作
  '!collections:delete' // 排除删除
]

3. Schema 权限声明

在开发插件或自定义页面时，应明确声明所需的权限：

const schema = {
  type: 'void',
  'x-acl-action': `${collectionName}:view`,
  'x-settings': 'settings:acl',
};

相关配置

环境变量

插件依赖

权限系统作为核心插件 @nocobase/plugin-acl 提供，独立于业务插件存在：

@nocobase/plugin-acl
├── server/src/acl/       # 服务端实现
├── client/src/acl/      # 客户端实现
└── index.ts             # 插件入口

资料来源：packages/plugins/@nocobase/plugin-acl

总结

NocoBase 的权限系统采用成熟的 ACL 模型，通过角色、权限片段和资源操作的三层结构实现了灵活且强大的访问控制。系统支持服务端的中间件校验和客户端的上下文感知，两端协同确保权限策略的一致性和安全性。开发者应遵循最小权限原则，合理设计角色和 Snippet，在 Schema 中明确声明权限需求，以构建安全可靠的应用系统。

概述

NocoBase 工作流引擎是一个强大的业务流程自动化模块，允许用户通过可视化画布设计、配置和管理自动化工作流程。工作流引擎支持在数据保存前后触发、执行队列任务、审批流程以及自定义操作事件，为业务系统提供灵活的自动化能力。

工作流引擎的核心职责包括：

• 提供可视化的流程设计画布
• 管理流程节点的执行逻辑
• 处理流程执行状态和历史记录
• 支持条件分支和循环控制
• 与系统各模块集成实现自动化触发

资料来源：packages/core/flow-engine/src/flowSettings.ts:1-50

架构设计

核心组件

工作流引擎由多个核心组件构成，各组件协同完成流程设计、执行和监控功能。

graph TD
    A[FlowSettings 配置面板] --> B[FlowModel 模型层]
    B --> C[FlowModelRenderer 渲染器]
    C --> D[CanvasContent 画布内容]
    D --> E[ExecutionCanvas 执行画布]
    
    F[FlowContext 上下文] --> B
    G[节点组件] --> D
    H[任务队列] --> E

目录结构

工作流引擎主要代码分布在以下位置：

资料来源：packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-30

FlowSettings 配置系统

FlowSettings 是工作流引擎的配置管理核心类，负责注册和管理流程相关的 UI 组件和作用域。

export class FlowSettings {
  public components: Record<string, any> = {};
  public scopes: Record<string, any> = {};
  private antdComponentsLoaded = false;
  public enabled: boolean;
  #forceEnabled = false; // 强制启用状态
}

配置属性

底部栏配置

FlowSettings 支持通过 footer 属性自定义底部操作栏的展示形式：

// 1. 静态自定义 - 直接替换
footer: <div>自定义底部内容</div>

// 2. 包裹式自定义 - 在原节点基础上添加内容
footer: (originNode, { OkBtn, CancelBtn }) => (
  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
    <span>Additional info</span>
    {originNode}
  </div>
)

// 3. 函数式自定义 - 完全重新组合按钮
footer: (originNode, { OkBtn, CancelBtn }) => (
  <Space>
    <CancelBtn title="Close" />
    <Button type="link">Help</Button>
    <OkBtn title="Apply" />
  </Space>
)

// 4. 隐藏底部
footer: null

资料来源：packages/core/flow-engine/src/flowSettings.ts:1-80

流程渲染器

FlowModelRenderer

FlowModelRenderer 是核心的流程模型渲染组件，负责将流程模型渲染为可视化的流程配置界面。

export const FlowModelRenderer: React.FC<FlowModelRendererProps> = React.memo((props) => {
  // 构建渲染内容：统一在渲染前触发 beforeRender 事件（带缓存）
  const content = (
    <FlowModelRendererWithAutoFlows
      model={model}
      showFlowSettings={showFlowSettings}
      flowSettingsVariant={flowSettingsVariant}
      hideRemoveInSettings={hideRemoveInSettings}
      showTitle={showTitle}
      inputArgs={inputArgs}
      showErrorFallback={showErrorFallback}
      settingsMenuLevel={settingsMenuLevel}
      extraToolbarItems={extraToolbarItems}
      fallback={fallback}
      useCache={resolvedUseCache}
    />
  );

  // 当需要错误回退时，将整体包裹在 ErrorBoundary 和 FlowModelProvider 中
  if (showErrorFallback) {
    return (
      <FlowModelProvider model={model}>
        <ErrorBoundary FallbackComponent={FlowErrorFallback}>{content}</ErrorBoundary>
      </FlowModelProvider>
    );
  }

  return content;
});

MemoFlowModelRenderer

对于需要优化渲染性能的场景，引擎提供了 MemoFlowModelRenderer 包装版本，仅在父级重渲且 props 浅比较未变时跳过渲染，不影响内部响应式更新。

export const MemoFlowModelRenderer = React.memo(FlowModelRenderer);
MemoFlowModelRenderer.displayName = 'MemoFlowModelRenderer';

Props 配置

资料来源：packages/core/flow-engine/src/components/FlowModelRenderer.tsx:1-100

执行上下文

FlowContext

FlowContext 提供流程执行时的运行时上下文，贯穿整个流程执行生命周期。

<FlowContext.Provider
  value={{
    workflow: workflow.type ? workflow : null,
    nodes,
    execution,
    viewJob,
    setViewJob,
  }}
>
  {children}
</FlowContext.Provider>

上下文属性

资料来源：packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-60

可视化画布

CanvasContent

画布内容组件负责渲染流程节点的可视化展示和交互。

<div className="workflow-canvas-wrapper">
  <ErrorBoundary>
    <div className="workflow-canvas">
      <div className="workflow-canvas-content">
        <div className={styles.terminalClass}>{lang('Start')}</div>
        {renderNodes(entry, nodes)}
        <div className={styles.terminalClass}>{lang('End')}</div>
      </div>
    </div>
  </ErrorBoundary>
  {copiedNode ? (
    <div className={styles.clipboardPreviewClass}>
      <div className="workflow-clipboard-header">
        <span>{lang('Copied node')}</span>
      </div>
      <div className="workflow-clipboard-card">
        <div className="workflow-clipboard-type">{copiedTypeTitle}</div>
        <div className="workflow-clipboard-title">{copiedNode.title ?? copiedNode.type}</div>
      </div>
    </div>
  ) : null}
  <div className="workflow-canvas-zoomer">
    <Slider vertical reverse defaultValue={100} step={10} min={10} value={zoom} onChange={setZoom} />
  </div>
</div>

画布功能

ExecutionCanvas 执行画布

执行画布展示流程的实际执行状态和结果。

<Breadcrumb
  items={[
    { title: <Link to={app.pluginSettingsManager.getRoutePath('workflow')}>{lang('Workflow')}</Link> },
    { title: <Link to={getWorkflowDetailPath(workflow.id)}>{workflow.title}</Link> },
    { title: <ExecutionsDropdown /> },
  ]}
/>
<Tag color={statusOption.color}>{compile(statusOption.label)}</Tag>
<time>{str2moment(execution.updatedAt).format('YYYY-MM-DD HH:mm:ss')}</time>

执行状态展示

资料来源：packages/plugins/@nocobase/plugin-workflow/src/client/CanvasContent.tsx:1-80 资料来源：packages/plugins/@nocobase/plugin-workflow/src/client/ExecutionCanvas.tsx:1-70

触发机制

工作流支持多种触发方式，满足不同业务场景的自动化需求。

graph LR
    A[数据保存] --> B[触发前 Pre-Action]
    A --> C[触发后 Post-Action]
    D[按钮点击] --> E[自定义事件]
    F[定时任务] --> G[队列执行]

触发类型

资料来源：packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:1-50

国际化支持

工作流引擎内置多语言支持，核心翻译键值如下：

资料来源：packages/plugins/@nocobase/plugin-workflow/src/locale/ko-KR.json:50-100

相关插件

plugin-workflow

基础工作流插件，提供核心的流程设计、执行和管理功能。

• 可视化流程画布设计
• 节点配置和管理
• 执行历史记录
• 流程复制和粘贴

plugin-workflow-approval

审批流程插件，扩展工作流引擎支持审批业务场景。

• 审批节点类型
• 审批人指定
• 审批意见记录

plugin-workflow-request

HTTP 请求插件，支持在工作流中发起外部 API 调用。

• HTTP 请求节点
• 响应数据处理
• 错误处理机制

最佳实践

性能优化

1. 使用 MemoFlowModelRenderer：在父组件频繁重渲但实际数据未变的场景，使用 Memo 版本避免不必要的重渲
2. 合理设置 useCache：启用缓存可减少重复计算，但需注意数据一致性问题
3. showErrorFallback 策略：在复杂节点场景启用错误边界，避免单个节点错误导致整个流程崩溃

错误处理

1. ErrorBoundary 包装：确保节点渲染错误被正确捕获
2. FlowErrorFallback 自定义：根据业务需求提供友好的错误展示
3. FlowModelProvider 上下文：在错误回退中仍可获取模型上下文进行恢复操作

总结

NocoBase 工作流引擎采用模块化设计，通过 FlowSettings 配置系统、FlowModelRenderer 渲染器、CanvasContent 画布和 ExecutionCanvas 执行画布等核心组件，为业务系统提供了完整的流程自动化能力。引擎支持多种触发机制、可视化设计和执行监控，结合审批和请求等扩展插件，能够满足复杂业务场景的流程自动化需求。

概述

根据当前检索到的上下文信息，未能获取到 AI 插件和智能员工相关的具体源码文件。以下信息基于 NocoBase 仓库中可访问的通用架构和功能模块进行说明。

当前可访问的上下文信息

从仓库中检索到的相关文件主要包括：

AI 集成架构

根据项目 README 中的描述，NocoBase 是一个开源的 AI + No-Code 平台，用于快速构建业务系统。AI 功能建立在经过生产验证的基础设施和所见即所得的 No-Code 界面上。

Coding agents get a... (文档内容在此处截断)

变量系统与 AI 上下文

NocoBase 的内置变量系统为 AI 集成提供了上下文数据支持：

// 资料来源：packages/core/client/src/variables/hooks/useBuiltinVariables.ts:1-100

const builtinVariables = [
  {
    name: '$date',
    ctx: datetimeCtx,  // 日期时间上下文
  },
  {
    name: '$nExactDate',
    ctx: exactDateTimeCtx,  // 精确日期时间
  },
  {
    name: '$system',
    ctx: {
      now: () => dayjs().toISOString(),
    },
  },
  {
    name: 'currentTime',
    ctx: () => dayjs().toISOString(),
  },
  {
    name: urlSearchParamsName,
    ctx: urlSearchParamsCtx,
    defaultValue,
  },
];

文档资源链接

根据 Help 组件配置，NocoBase 提供了以下官方文档资源：

资料来源：packages/core/client/src/user/Help.tsx:1-60

流程引擎配置

AI 智能员工的执行逻辑可能通过流程引擎实现。当前可访问的流程配置支持自定义底部按钮：

// 资料来源：packages/core/flow-engine/src/flowSettings.ts:1-50

interface FlowSettingsConfig {
  footer?:
    | React.ReactNode
    | ((originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC }) => React.ReactNode)
    | null;
  [key: string]: any;
}

插件系统

NocoBase 的插件管理器支持查看插件详情，包括依赖兼容性检查：

资料来源：packages/core/client/src/pm/PluginDetail.tsx:1-100

注意事项

当前页面内容不完整

由于以下关键源码文件未在当前检索上下文中提供，无法生成详细的 AI 集成与智能员工技术文档：

1. packages/plugins/@nocobase/plugin-ai - AI 核心插件
2. packages/plugins/@nocobase/plugin-ai-knowledge-base - AI 知识库插件
3. docs/docs/cn/ai-employees/index.md - AI 员工文档首页
4. docs/docs/cn/ai-employees/knowledge-base/rag.md - RAG 检索增强生成文档

后续步骤

如需完整的技术文档，请提供以下任一方式：

1. 重新检索 - 请求检索上述缺失的 AI 相关源码文件
2. 访问源码 - 直接访问 GitHub 仓库中的 AI 插件目录
3. 访问文档 - 查看官方文档站点 https://docs.nocobase.com/

概述

界面构建器（Interface Builder）是 NocoBase 平台的核心模块之一，用于通过可视化的方式构建业务系统的用户界面。它基于 Schema 驱动的架构设计，允许用户通过声明式配置定义界面结构、数据源、交互行为等，而无需编写大量代码。

界面构建器的核心理念是通过数据驱动的方式实现 UI 的声明式构建，所有界面配置都以 JSON Schema 格式存储在数据库中，支持运行时动态修改和渲染。

核心架构

整体架构图

graph TD
    A[用户界面] --> B[Schema 配置]
    B --> C[Schema 解析器]
    C --> D[组件映射表]
    D --> E[React 组件]
    E --> A
    
    F[Schema 设置面板] --> B
    G[Schema 初始化器] --> B
    H[Schema 工具栏] --> B
    
    I[数据源配置] --> J[变量系统]
    J --> C

主要模块

Schema 配置结构

Schema 基本结构

Schema 是界面构建器的核心配置单元，采用 JSON Schema 格式定义界面的层级结构和属性。

{
  type: 'string',
  'x-decorator': 'FormItem',
  'x-component': 'Input',
  'x-component-props': {
    placeholder: '{{t("Please enter")}}',
  },
  'x-designable-bahavior': 'editable'
}

x-designable-bahavior 行为类型

资料来源：schema-component/index.md:8-11

Schema 初始化器

Schema 初始化器负责在设计时动态向 Schema 中插入新的节点或配置，是实现可视化配置的关键组件。

功能特性

• 动态可见性：根据条件动态显示或隐藏配置项
• 子节点动态加载：支持按需加载子配置节点
• Schema 插入：支持多种类型的 Schema 插入模式

插入模式

资料来源：schema-initializer/index.md:12-20

Schema 设置面板

Schema 设置面板提供配置界面的入口，允许用户修改 Schema 节点的各种属性。

GeneralSchemaDesigner 组件

GeneralSchemaDesigner 是核心的 Schema 设计器组件，提供了完整的可视化编辑能力。

interface SchemaToolbarProps {
  title?: string | string[];
  showDataSource?: boolean;
  dataSource?: any;
  template?: boolean;
  draggable?: boolean;
  disableInitializer?: boolean;
}

资料来源：GeneralSchemaDesigner.tsx:145-153

工具栏功能

资料来源：GeneralSchemaDesigner.tsx:40-75

标题渲染逻辑

// 数据源和标题组合显示
{dataSource ? `${compile(dataSource?.displayName)} > ${compile(title)}` : compile(title)}

组件类型系统

内置组件类型

NocoBase 提供了多种内置组件类型，可直接在 Schema 中引用：

LinkageFilter 组件

LinkageFilter 用于前端联动规则的条件配置，支持变量、操作符的联动变化。

type FilterActionProps<T = {}> = ActionProps & {
  options?: any[];
  form?: Form;
  onSubmit?: (values: T) => void;
  onReset?: (values: T) => void;
}

资料来源：linkageFilter/index.md:7-13

变量系统

内置变量

界面构建器支持丰富的内置变量，用于在配置中引用运行时数据：

资料来源：useBuiltinVariables.ts:30-70

变量上下文结构

{
  name: '$nDate',
  ctx: () => dayjs().toISOString(),
  defaultValue?: any
}

流程设置集成

界面构建器与流程引擎深度集成，支持在配置面板中嵌入流程节点设置。

FlowSettings 配置结构

interface FlowSettingsProps {
  footer?: React.ReactNode | 
    ((originNode: React.ReactNode, extra: { 
      OkBtn: React.FC; 
      CancelBtn: React.FC 
    }) => React.ReactNode) | null;
  onCancel?: () => void | Promise<void>;
  onSaved?: () => void | Promise<void>;
}

资料来源：flowSettings.ts:40-52

自定义 Footer 示例

// 在底部工具栏添加内容
footer: (originNode, { OkBtn, CancelBtn }) => (
  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
    <span>Additional info</span>
    {originNode}
  </div>
)

// 隐藏底部
footer: null

移动端适配

桌面模式组件

当在桌面端访问移动端页面时，系统会渲染 DesktopMode 组件进行适配。

<DesktopMode>
  <Mobile />
</DesktopMode>

资料来源：packages/plugins/@nocobase/plugin-mobile/src/client/desktop-mode/index.md

移动端 TabBar

移动端使用自定义的 MobileTabBar 组件，支持链接跳转功能：

资料来源：mobile-layout/index.md

设计态与运行态

状态切换机制

stateDiagram-v2
    [*] --> Designable: 设计态开启
    Designable --> [*]: 保存配置
    Designable --> Readonly: 切换为只读
    Readonly --> Designable: 重新编辑
    Readonly --> [*]: 退出编辑

Designable 上下文

通过 useDesignable() Hook 可以获取当前设计态状态：

const { designable } = useDesignable();

配置示例

基本 Schema 配置

{
  type: 'object',
  properties: {
    name: {
      type: 'string',
      'x-decorator': 'FormItem',
      'x-component': 'Input',
      'x-component-props': {
        placeholder: '{{t("Name")}}',
      },
    },
  },
}

Markdown 编辑器配置

{
  content: {
    type: 'string',
    'x-decorator': 'FormItem',
    'x-component': (props) => {
      return ctx.markdown.edit({
        ...props,
        value: props.value || ctx.model.props.value,
        mode: 'sv',
        height: '82vh',
      });
    },
  },
}

资料来源：packages/core/client/src/flow/flows/editMarkdownFlow.tsx

最佳实践

性能优化

1. 减少不必要的渲染：使用 React.memo 包装自定义组件
2. 延迟加载：对于复杂配置，使用动态导入
3. 状态管理：合理使用 Context 避免过度 prop drilling

可维护性

1. Schema 分离：将复杂的 Schema 拆分为多个子 Schema
2. 组件复用：提取公共配置为可复用组件
3. 类型定义：为自定义配置提供完整的 TypeScript 类型支持

相关资源

• Schema Settings 文档
• Schema Initializer 文档
• Schema Component 文档
• 流程引擎文档

概述

NocoBase 的文件管理与存储系统是一个模块化的基础设施，用于处理用户上传的文件、文档解析、以及与各种云存储服务的集成。该系统通过插件化的架构设计，支持灵活扩展存储后端，同时提供统一的客户端上传组件和服务器端处理逻辑。

文件管理在 NocoBase 中扮演着关键角色，因为作为一个无代码平台，用户经常需要上传附件、文档、图片等资源，并对其进行管理和应用。

核心组件架构

上传组件（Upload）

NocoBase 的前端上传组件基于 ant-design 的 Upload 组件进行封装，提供增强的功能和更好的用户体验。

组件类型定义：

type UploadProps = Omit<AntdUploadProps, 'onChange'> & {
  onChange?: (fileList: UploadFile[]) => void;
  serviceErrorMessage?: string;
  value?: any;
  size?: string;
};

type UploadReadPrettyProps = AntdUploadProps;

资料来源：packages/core/client/src/schema-component/antd/upload/index.md:1-9

主要功能特性：

文档加载器

在 AI 插件中，文件管理系统还负责文档的解析和加载。

private get aiFilesRepo() {
  return this.plugin.db.getRepository('aiFiles');
}

private get fileManager(): PluginFileManagerServer {
  return this.plugin.app.pm.get('file-manager');
}

资料来源：packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:76-81

存储插件体系

文件管理器插件

文件管理器插件（plugin-file-manager）是 NocoBase 核心的文件管理模块，负责：

• 文件元数据管理
• 文件上传处理
• 存储后端抽象
• 访问权限控制

存储后端插件

NocoBase 采用插件化的存储后端设计，支持多种存储服务：

数据流架构

graph TD
    A[客户端上传组件] --> B[Upload API 端点]
    B --> C[文件管理器插件]
    C --> D[存储后端选择]
    D --> E[本地磁盘]
    D --> F[S3 兼容存储]
    D --> G[其他云存储]
    E --> H[文件元数据存储]
    F --> H
    G --> H
    H --> I[数据库记录]

客户端上传组件使用

基础用法

import { Upload } from '@nocobase/client';

// 基础上传示例
<Upload />

多文件上传

// 多文件上传模式
<Upload multiple />

带规则验证

// 配置上传规则
<Upload 
  rules={[
    { type: 'fileType', value: ['image/jpeg', 'image/png'] },
    { type: 'fileSize', value: 10 * 1024 * 1024 } // 10MB
  ]}
/>

只读展示

// 用于展示已上传文件
<UploadReadPretty value={fileList} />

服务器端处理

文件管理器服务端

文件管理器服务端负责处理上传请求、管理存储后端、以及维护文件元数据：

private get aiFilesRepo() {
  return this.plugin.db.getRepository('aiFiles');
}

private get fileManager(): PluginFileManagerServer {
  return this.plugin.app.pm.get('file-manager');
}

服务器端提供以下核心能力：

1. 文件存储抽象 - 通过统一的接口支持多种存储后端
2. 元数据管理 - 使用 aiFiles 仓库管理文件元数据
3. 访问控制 - 集成 NocoBase 的权限系统
4. 文档解析 - 支持 AI 插件的文档加载需求

文档解析元数据

private getParseMeta(meta?: Record<string, any>): DocumentParseMeta | null {
  if (!meta || typeof meta !== 'object') {
    return null;
  }
  return meta[DOCUMENT_PARSE_META_KEY] ?? null;
}

资料来源：packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:47-52

配置与扩展

创建自定义存储后端

开发者可以通过实现以下接口来创建自定义存储后端：

interface StorageBackend {
  upload(file: Buffer, metadata: FileMetadata): Promise<string>;
  download(path: string): Promise<Buffer>;
  delete(path: string): Promise<void>;
  getUrl(path: string): string;
}

注册文件处理插件

// 在插件的 install 方法中注册
this.app.pm.get('file-manager').registerBackend('custom', CustomStorageBackend);

与 AI 系统的集成

NocoBase 的文件管理系统与 AI 插件深度集成，支持：

• 文档加载 - 从存储中加载文档进行 AI 处理
• 文件解析 - 解析各种文档格式提取内容
• 向量化存储 - 支持将文件内容向量化后存储

return [
  new Document({
    pageContent: text,
    metadata: {
      source: sourceFile.filename,
      extname,
    },
  }),
];

资料来源：packages/plugins/@nocobase/plugin-ai/src/server/document-loader/cached.ts:32-40

最佳实践

前端配置建议

1. 合理设置文件大小限制 - 根据业务需求和存储成本设置
2. 使用适当的文件类型白名单 - 提高系统安全性
3. 配置错误提示信息 - 提供清晰的用户反馈

存储策略建议

1. 生产环境使用云存储 - 如 S3、阿里云 OSS 等
2. 配置合理的缓存策略 - 减少存储成本
3. 定期清理过期文件 - 释放存储空间

相关资源

• NocoBase 官方文档
• 文件管理器插件源码
• S3 存储插件源码

概述

NocoBase 采用插件化架构，所有功能均以插件形式实现。插件系统是 NocoBase 的核心组成部分，允许开发者通过编写插件来扩展系统功能，实现模块化的功能管理与部署。

NocoBase 的插件分为两类：

• 客户端插件：负责用户界面、页面路由、Schema 组件、Schema 初始化器等前端功能
• 服务器端插件：负责数据模型、API 接口、业务逻辑、数据库操作等后端功能

一个完整的插件可以同时包含客户端和服务器端代码，通过统一的插件机制进行注册和管理。

插件架构

核心架构图

graph TB
    subgraph 客户端 Client
        UI[用户界面]
        SC[Schema 组件]
        SI[Schema 初始化器]
        SS[Schema 设置]
        PM_UI[插件管理器 UI]
    end

    subgraph 服务器端 Server
        API[API 接口]
        DB[数据库操作]
        MODEL[数据模型]
        HOOKS[Hooks 钩子]
    end

    subgraph 核心 Core
        PM[插件管理器 PluginManager]
        PM_API[插件 API]
    end

    UI --> PM_UI
    SC --> SS
    SI --> SS
    PM_UI --> PM
    PM --> PM_API
    API --> PM_API
    DB --> PM_API
    MODEL --> PM_API
    HOOKS --> PM_API

    style PM fill:#e1f5fe
    style PM_API fill:#e1f5fe

插件生命周期

stateDiagram-v2
    [*] --> 安装: npm install
    安装 --> 启用: enable()
    启用 --> 加载: load()
    加载 --> 运行: activate()
    运行 --> 禁用: deactivate()
    禁用 --> 启用: activate()
    启用 --> 卸载: disable()\nuninstall()
    运行 --> 卸载: disable()\nuninstall()
    卸载 --> [*]

目录结构

一个典型的插件项目目录结构如下：

packages/plugins/@nocobase/plugin-sample/
├── src/
│   ├── client/                    # 客户端代码
│   │   ├── index.ts               # 客户端插件入口
│   │   ├── pages/                 # 页面组件
│   │   ├── components/            # 自定义组件
│   │   ├── schema-components/    # Schema 组件
│   │   ├── schema-initializers/   # Schema 初始化器
│   │   ├── schema-settings/       # Schema 设置
│   │   ├── demos/                 # 文档示例
│   │   └── index.md               # 文档
│   └── server/                    # 服务器端代码
│       ├── index.ts               # 服务器端插件入口
│       ├── actions/               # 自定义 actions
│       ├── collections/           # 数据模型定义
│       └── migrations/            # 数据库迁移
├── package.json
└── README.md

服务器端插件开发

插件类基础

服务器端插件继承自 Plugin 基类，通过覆写生命周期方法来实现功能：

import { Plugin } from '@nocobase/server';

export class SamplePlugin extends Plugin {
  async load() {
    // 加载阶段：注册数据模型、API 路由等
    this.app.collection({
      name: 'samples',
      fields: [
        { type: 'string', name: 'title' },
        { type: 'text', name: 'description' },
      ],
    });

    this.app.acl.allow('samples', 'list');
  }

  async activate() {
    // 激活阶段：执行初始化逻辑
  }

  async deactivate() {
    // 停用阶段：清理资源
  }
}

export default SamplePlugin;

数据模型定义

this.app.collection({
  name: 'articles',
  fields: [
    { type: 'belongsTo', name: 'author' },
    { type: 'hasMany', name: 'comments' },
    { type: 'string', name: 'title' },
    { type: 'richtext', name: 'content' },
    { type: 'date', name: 'publishedAt' },
    { type: 'boolean', name: 'isPublished' },
  ],
});

API 路由注册

this.app.resourcer.define({
  name: 'articles',
  actions: {
    async list(ctx, next) {
      // 自定义列表逻辑
      await next();
    },
    async create(ctx, next) {
      ctx.request.body.author = ctx.state.currentUser.id;
      await next();
    },
  },
});

Hooks 机制

NocoBase 提供了丰富的 Hooks 用于扩展功能：

this.app.on('afterSave', async (event, model) => {
  if (model.get('type') === 'published') {
    // 发送通知等操作
  }
});

资源上下文 API

插件可以通过 ctx.resource 访问当前资源上下文：

// 设置资源当前数据（仅前端）
ctx.resource.setData(value);

// 从后端刷新数据
await ctx.resource.refresh();

// 订阅资源事件
ctx.resource.on('refresh', () => {});

// 设置资源名称
ctx.resource.setResourceName('users');

// 设置主键/过滤键
ctx.resource.setFilterByTk(id);

// 执行资源动作
await ctx.resource.runAction('create', data);

客户端插件开发

插件入口

import { Plugin } from '@nocobase/client';

export class SamplePlugin extends Plugin {
  async load() {
    // 注册页面路由
    this.app.router.add('sample', {
      path: '/sample',
      Component: SamplePage,
    });

    // 注册 Schema 组件
    this.app.schemaInitializerManager.add('SampleInitializer', {
      // ...
    });

    // 注册 Schema 设置
    this.app.schemaSettingsManager.add('SampleSetting', {
      // ...
    });
  }
}

export default SamplePlugin;

Schema 组件

Schema 是 NocoBase 前端配置的核心机制，用于描述界面结构和行为：

graph LR
    A[Schema 配置] --> B[组件渲染]
    A --> C[数据绑定]
    A --> D[事件处理]
    A --> E[样式配置]

#### Schema 基础结构

const schema = {
  type: 'void',
  'x-component': 'SampleCard',
  'x-component-props': {
    title: '{{ title }}',
  },
  properties: {
    content: {
      type: 'void',
      'x-component': 'Markdown',
      'x-content': '{{ content }}',
    },
  },
};

#### Schema 组件类型

Schema 初始化器

Schema 初始化器用于在设计器中插入 Schema 节点：

this.app.schemaInitializerManager.add('SampleBlockInitializer', {
  title: '示例区块',
  icon: 'PlusOutlined',
  sections: {
    basic: {
      title: '基础',
      items: [
        {
          title: '表格',
          schema: {
            type: 'void',
            'x-component': 'Table',
          },
        },
      ],
    },
  },
});

#### 动态显示和隐藏

{
  'x-initializer': 'SampleInitializer',
  'x-initializer-props': {
    filter: (node) => node.schema?.['x-designer'] === 'SampleDesigner',
  },
}

Schema 设置

Schema 设置用于配置 Schema 节点的属性：

this.app.schemaSettingsManager.add('SampleSetting', {
  title: '示例设置',
  items: [
    {
      name: 'title',
      title: '标题',
      component: {
        name: 'Input',
        props: {
          placeholder: '{{ t("Title") }}',
        },
      },
    },
    {
      name: 'description',
      title: '描述',
      component: {
        name: 'TextArea',
        props: {
          rows: 4,
        },
      },
    },
    {
      name: 'divider',
      type: 'divider',
    },
    {
      name: 'delete',
      title: '删除',
      component: {
        name: 'Delete',
        props: {
          danger: true,
        },
      },
    },
  ],
});

Schema 设计器

Schema 设计器提供可视化编辑 Schema 的能力：

import { GeneralSchemaDesigner } from '@nocobase/client';

const SampleDesigner = () => {
  return (
    <GeneralSchemaDesigner
      title="示例设计器"
      schemaSettings={['SampleSetting', 'divider', 'delete']}
    />
  );
};

插件管理器

NocoBase 提供了内置的插件管理器，支持插件的安装、启用、禁用和卸载。

插件信息展示

插件详情页面展示以下信息：

依赖兼容性检查

插件管理器会检查插件依赖的兼容性：

// 检查是否包含 externalVersion.js
if (data?.data?.depsCompatible === false) {
  return <Alert type="error" message="dist/externalVersion.js 未找到或加载失败，请重新构建插件。" />;
}

// 检查依赖版本是否兼容
if (!data?.data?.['isCompatible']) {
  return <Alert type="error" message="插件依赖检查失败，请调整依赖版本。" />;
}

变量系统

NocoBase 提供了内置变量系统，支持在配置中使用动态值：

内置变量

变量上下文

{
  name: '$nUser',
  ctx: {
    id: () => currentUser.id,
    name: () => currentUser.name,
    email: () => currentUser.email,
  },
}

流程引擎集成

插件可以与流程引擎集成，实现复杂的业务流程：

自定义动作

import { FlowSettings } from '@nocobase/plugin-workflow';

class SamplePlugin extends Plugin {
  async load() {
    // 注册流程设置组件
    this.app.setFlowSettings({
      components: {
        SampleNode: SampleNodeComponent,
      },
      scopes: {
        sampleScope: SampleScopeComponent,
      },
    });
  }
}

自定义 Footer

流程设置支持自定义底部按钮区域：

// 方式一：追加内容
footer: (originNode, { OkBtn, CancelBtn }) => (
  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
    <span>Additional info</span>
    {originNode}
  </div>
)

// 方式二：完全自定义
footer: (originNode, { OkBtn, CancelBtn }) => (
  <Space>
    <CancelBtn title="Close" />
    <OkBtn title="Apply" />
  </Space>
)

// 方式三：隐藏底部
footer: null

移动端插件开发

NocoBase 支持移动端页面的开发，通过 MobileTabBar 提供底部导航：

MobileTabBar 组件

import { MobileTabBar } from '@nocobase/plugin-mobile';

// 使用 Link 跳转
<MobileTabBar.Link
  to="/pages/home/index"
  icon={<HomeOutlined />}
  title="首页"
/>

// 外部链接
<MobileTabBar.Link
  to="https://example.com"
  external
  icon={<GlobalOutlined />}
  title="外部链接"
/>

Schema 定义

{
  type: 'void',
  'x-component': 'MobileTabBar',
  'x-component-props': {
    activeKey: '{{ activeKey }}',
  },
  properties: {
    home: {
      type: 'void',
      'x-component': 'MobileTabBar.Item',
      'x-component-props': {
        key: 'home',
        icon: 'HomeOutlined',
        link: '/pages/home/index',
      },
    },
  },
}

Desktop Mode

当在桌面端访问移动端页面时，可以使用 DesktopMode 组件：

import { DesktopMode } from '@nocobase/plugin-mobile';

<DesktopMode>
  <MobilePage />
</DesktopMode>

联动规则

NocoBase 支持在表单中使用联动规则，实现字段间的动态关联：

LinkageFilter 组件

type FilterActionProps<T = {}> = ActionProps & {
  options?: any[];           // 可选的操作符
  form?: Form;              // 表单实例
  onSubmit?: (values: T) => void;   // 提交回调
  onReset?: (values: T) => void;    // 重置回调
};

基本用法

左侧支持变量、操作符，右侧变量组件跟随左侧变量联动：

{
  type: 'void',
  'x-component': 'LinkageFilter',
  'x-component-props': {
    options: [
      { label: '等于', value: '=' },
      { label: '包含', value: 'contains' },
    ],
    onSubmit: (values) => {
      // 处理筛选
    },
  },
}

最佳实践

1. 插件命名规范

{
  "name": "@nocobase/plugin-{feature-name}",
  "version": "1.0.0",
  "displayName": "{{t('Feature Name')}}",
  "description": "{{t('Plugin description')}}"
}

2. 国际化支持

// 使用 t() 函数进行翻译
title: t('Sample Plugin'),
description: t('This is a sample plugin for demonstration'),

// 支持中文
data?.data?.lang === 'zh-CN' ? '中文链接' : 'English Link'

3. Schema 组件开发

import { SchemaComponent } from '@nocobase/client';

const SampleComponent = (props) => {
  return (
    <SchemaComponent
      schema={{
        type: 'void',
        'x-component': 'Card',
        properties: {
          content: {
            type: 'void',
            'x-component': 'Markdown',
            'x-content': props.content,
          },
        },
      }}
    />
  );
};

4. 错误处理

// 插件加载失败处理
async load() {
  try {
    await this.registerCollections();
    await this.registerActions();
  } catch (error) {
    console.error('Plugin load error:', error);
    throw error;
  }
}

// 依赖检查
if (data?.data?.depsCompatible === false) {
  throw new Error('插件依赖不兼容，请重新构建');
}

5. 性能优化

// 使用 React.memo 优化组件
const SchemaToolbar = React.memo((props) => {
  // ...
});

// 使用 useCallback 缓存回调
const onVisibleChange = useCallback((nextVisible: boolean) => {
  startTransition(() => {
    setVisible(nextVisible);
  });
}, []);

注册插件到系统

服务器端注册

// packages/plugins/@nocobase/plugin-sample/src/server/index.ts
import { SamplePlugin } from './SamplePlugin';

export default SamplePlugin;

客户端注册

// packages/plugins/@nocobase/plugin-sample/src/client/index.ts
import { SampleClientPlugin } from './SampleClientPlugin';

export default SampleClientPlugin;

插件启用

在 packages/core/server/src/plugins/index.ts 中添加插件：

import sample from '@nocobase/plugin-sample';

export const plugins = [
  // ...其他插件
  sample,
];

总结

NocoBase 的插件系统提供了完整的扩展能力：

• 模块化架构：前后端分离的插件开发模式
• Schema 机制：灵活的界面配置系统
• 生命周期管理：完整的插件安装、启用、停用流程
• 依赖管理：自动化的依赖检查和兼容性验证
• 多端支持：同时支持桌面端和移动端插件开发

开发者可以通过继承基类、重写生命周期方法、注册组件和配置来实现各种业务需求。

Pitfall Log / 踩坑日志

项目：nocobase/nocobase

摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：REST API: Multiple select field not working in edit form。

1. 安全/权限坑 · 来源证据：REST API: Multiple select field not working in edit form

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REST API: Multiple select field not working in edit form
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_36b6b605781f4652849d06443cd76da9 | https://github.com/nocobase/nocobase/issues/8836 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：v2.1.0-alpha.33

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-alpha.33
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_71fc97aec74e43618fab9e19d0aa9a9f | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.33 | 来源类型 github_release 暴露的待验证使用条件。

3. 安装坑 · 来源证据：v2.1.0-beta.30

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0-beta.30
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3eea74dae9c548fc8058563df21058d3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.30 | 来源类型 github_release 暴露的待验证使用条件。

4. 配置坑 · 来源证据：v2.0.51

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.0.51
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_06f3ce01049e42f586931cf6e9a46335 | https://github.com/nocobase/nocobase/releases/tag/v2.0.51 | 来源类型 github_release 暴露的待验证使用条件。

5. 配置坑 · 来源证据：v2.1.0-alpha.32

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-alpha.32
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7055255c88f94ecc84dfc5c09fc6c3a3 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.32 | 来源类型 github_release 暴露的待验证使用条件。

6. 配置坑 · 来源证据：v2.1.0-beta.29

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v2.1.0-beta.29
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c4b7dfdc1a164f5cb82fec5622b80342 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.29 | 来源类型 github_release 暴露的待验证使用条件。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:306829688 | https://github.com/nocobase/nocobase | README/documentation is current enough for a first validation pass.

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | last_activity_observed missing

9. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium

10. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:306829688 | https://github.com/nocobase/nocobase | No sandbox install has been executed yet; downstream must verify before user use.

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:306829688 | https://github.com/nocobase/nocobase | no_demo; severity=medium

12. 安全/权限坑 · 来源证据：v2.0.52

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.52
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1ca2b2aac82447ea8ca5b5536fff978e | https://github.com/nocobase/nocobase/releases/tag/v2.0.52 | 来源类型 github_release 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：v2.1.0-alpha.31

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-alpha.31
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7a2bc590f0974b79880f86db553b3a2e | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-alpha.31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：v2.1.0-beta.27

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.27
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_43d1bbbbee81474cb8e2e4f722fdb398 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.27 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：v2.1.0-beta.32

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0-beta.32
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_31e3065c9e884205a29f181cbbc50458 | https://github.com/nocobase/nocobase/releases/tag/v2.1.0-beta.32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

16. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | issue_or_pr_quality=unknown

17. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:306829688 | https://github.com/nocobase/nocobase | release_recency=unknown