@nocobase/plugin-ai 2.1.0-alpha.25 → 2.1.0-alpha.27

package/dist/ai/docs/nocobase/flow-engine/flow-model-lifecycle.md

@@ -0,0 +1,48 @@
+# FlowModel Lifecycle
+
+## model Methods
+
+Internal calls
+
+```ts
+class MyModel extends FlowModel {
+  onInit() {}
+  onMount() {}
+  useHooksBeforeRender() {}
+  render() {}
+  onUnMount() {}
+  onDispatchEventStart() {}
+  onDispatchEventEnd() {}
+  onDispatchEventError() {}
+}
+```
+
+## model.emitter
+
+For external triggers
+
+- onSubModelAdded
+- onSubModelRemoved
+- onSubModelMoved
+
+## Process
+
+1. Construct model
+    - onInit
+2. Render model
+    - onDispatchEventStart
+    - dispatchEvent('beforeRender')
+    - onDispatchEventEnd
+    - render
+    - onMount
+3. Unmount component
+    - onUnMount
+4. Trigger flow
+    - onDispatchEventStart
+    - onDispatchEventEnd
+5. Re-render
+  - onUnMount
+  - onDispatchEventStart
+  - dispatchEvent('beforeRender')
+  - onDispatchEventEnd
+  - onUnMount

package/dist/ai/docs/nocobase/flow-engine/flow-model-options.md

@@ -0,0 +1 @@
+# FlowModel Configuration

package/dist/ai/docs/nocobase/flow-engine/flow-model-renderer.md

@@ -0,0 +1,200 @@
+# Render FlowModel
+
+`FlowModelRenderer` is the core React component for rendering a `FlowModel`. It is responsible for converting a `FlowModel` instance into a visual React component.
+
+## Basic Usage
+
+### FlowModelRenderer
+
+```tsx pure
+import { FlowModelRenderer } from '@nocobase/flow-engine';
+
+// Basic usage
+<FlowModelRenderer model={myModel} />
+```
+
+```tsx file="./_demos/flow-model-renderer.tsx" preview
+```
+
+### FieldModelRenderer
+
+For controlled field Models, use `FieldModelRenderer` to render:
+
+```tsx pure
+import { FieldModelRenderer } from '@nocobase/flow-engine';
+
+// Controlled field rendering
+<FieldModelRenderer model={fieldModel} />
+```
+
+## Props
+
+### FlowModelRendererProps
+
+| Parameter | Type | Default | Description |
+|------|------|--------|------|
+| `model` | `FlowModel` | - | The FlowModel instance to render |
+| `uid` | `string` | - | The unique identifier for the flow model |
+| `fallback` | `React.ReactNode` | `<Skeleton.Button size="small" />` | Fallback content to display on rendering failure |
+| `showFlowSettings` | `boolean \| object` | `false` | Whether to show the entry for flow settings |
+| `flowSettingsVariant` | `'dropdown' \| 'contextMenu' \| 'modal' \| 'drawer'` | `'dropdown'` | The interaction style for flow settings |
+| `hideRemoveInSettings` | `boolean` | `false` | Whether to hide the remove button in the settings |
+| `showTitle` | `boolean` | `false` | Whether to display the model title in the top-left corner of the border |
+| `skipApplyAutoFlows` | `boolean` | `false` | Whether to skip applying auto flows |
+| `inputArgs` | `Record<string, any>` | - | Extra context passed to `useApplyAutoFlows` |
+| `showErrorFallback` | `boolean` | `true` | Whether to wrap the outermost layer with the `FlowErrorFallback` component |
+| `settingsMenuLevel` | `number` | - | Settings menu level: 1=current model only, 2=include child models |
+| `extraToolbarItems` | `ToolbarItemConfig[]` | - | Additional toolbar items |
+
+### `showFlowSettings` Detailed Configuration
+
+When `showFlowSettings` is an object, the following configurations are supported:
+
+```tsx pure
+showFlowSettings={{
+  showBackground: true,    // Show background
+  showBorder: true,        // Show border
+  showDragHandle: true,    // Show drag handle
+  style: {},              // Custom toolbar style
+  toolbarPosition: 'inside' // Toolbar position: 'inside' | 'above' | 'below'
+}}
+```
+
+## Rendering Lifecycle
+
+The entire rendering cycle calls the following methods in order:
+
+1.  **model.dispatchEvent('beforeRender')** - `beforeRender` event
+2.  **model.render()** - Executes the model's render method
+3.  **model.onMount()** - Component mount hook
+4.  **model.onUnmount()** - Component unmount hook
+
+## Usage Examples
+
+### Basic Rendering
+
+```tsx pure
+import { FlowModelRenderer } from '@nocobase/flow-engine';
+
+function MyComponent() {
+  const model = useFlowModel();
+  
+  return (
+    <FlowModelRenderer 
+      model={model}
+      fallback={<div>Loading...</div>}
+    />
+  );
+}
+```
+
+### Rendering with Flow Settings
+
+```tsx pure
+// Show settings but hide the remove button
+<FlowModelRenderer
+  model={myModel}
+  showFlowSettings={true}
+  hideRemoveInSettings={true}
+/>
+
+// Show settings and title
+<FlowModelRenderer
+  model={myModel}
+  showFlowSettings={true}
+  showTitle={true}
+/>
+
+// Use context menu mode
+<FlowModelRenderer
+  model={myModel}
+  showFlowSettings={true}
+  flowSettingsVariant="contextMenu"
+  hideRemoveInSettings={true}
+/>
+```
+
+### Custom Toolbar
+
+```tsx pure
+<FlowModelRenderer
+  model={myModel}
+  showFlowSettings={true}
+  extraToolbarItems={[
+    {
+      key: 'custom-action',
+      title: 'Custom Action',
+      icon: 'SettingOutlined',
+      onClick: () => {
+        console.log('Custom action');
+      }
+    }
+  ]}
+/>
+```
+
+### Skipping Auto Flows
+
+```tsx pure
+<FlowModelRenderer
+  model={myModel}
+  skipApplyAutoFlows={true}
+  showErrorFallback={false}
+/>
+```
+
+### Field Model Rendering
+
+```tsx pure
+import { FieldModelRenderer } from '@nocobase/flow-engine';
+
+function FormField({ model, onChange, ...props }) {
+  return (
+    <FieldModelRenderer
+      model={model}
+      onChange={onChange}
+      {...props}
+    />
+  );
+}
+```
+
+## Error Handling
+
+`FlowModelRenderer` has a comprehensive built-in error handling mechanism:
+
+-   **Automatic Error Boundary**: `showErrorFallback={true}` is enabled by default
+-   **Auto Flow Errors**: Catches and handles errors during the execution of auto flows
+-   **Rendering Errors**: Displays fallback content when model rendering fails
+
+```tsx pure
+<FlowModelRenderer
+  model={myModel}
+  showErrorFallback={true}
+  fallback={<div>Rendering failed, please try again</div>}
+/>
+```
+
+## Performance Optimization
+
+### Skipping Auto Flows
+
+For scenarios where auto flows are not needed, you can skip them to improve performance:
+
+```tsx pure
+<FlowModelRenderer
+  model={myModel}
+  skipApplyAutoFlows={true}
+/>
+```
+
+### Reactive Updates
+
+`FlowModelRenderer` uses the `observer` from `@formily/reactive-react` for reactive updates, ensuring that the component automatically re-renders when the model's state changes.
+
+## Notes
+
+1.  **Model Validation**: Ensure the passed `model` has a valid `render` method.
+2.  **Lifecycle Management**: The model's lifecycle hooks will be called at the appropriate times.
+3.  **Error Boundary**: It is recommended to enable the error boundary in a production environment to provide a better user experience.
+4.  **Performance Consideration**: For scenarios involving rendering a large number of models, consider using the `skipApplyAutoFlows` option.

package/dist/ai/docs/nocobase/flow-engine/flow-model-repository.md

@@ -0,0 +1,81 @@
+# FlowModel Persistence
+
+FlowEngine provides a complete persistence system.
+
+
+![20251008231338](https://static-docs.nocobase.com/20251008231338.png)
+
+
+## IFlowModelRepository
+
+`IFlowModelRepository` is the model persistence interface for FlowEngine, defining operations such as remote loading, saving, and deleting of models. By implementing this interface, model data can be persisted to a backend database, API, or other storage media, enabling data synchronization between the frontend and backend.
+
+### Main Methods
+
+- **findOne(query: Query): Promise<FlowModel \| null>**  
+  Loads model data from a remote source based on the unique identifier `uid`.
+
+- **save(model: FlowModel): Promise<any\>**  
+  Saves the model data to remote storage.
+
+- **destroy(uid: string): Promise<boolean\>**  
+  Deletes the model from remote storage based on `uid`.
+
+### FlowModelRepository Example
+
+```ts
+class FlowModelRepository implements IFlowModelRepository<FlowModel> {
+  constructor(private app: Application) {}
+
+  async findOne(query) {
+    const { uid, parentId } = query;
+    // Implementation: Get model by uid
+    return null;
+  }
+
+  async save(model: FlowModel) {
+    console.log('Saving model:', model);
+    // Implementation: Save model
+    return model;
+  }
+
+  async destroy(uid: string) {
+    // Implementation: Delete model by uid
+    return true;
+  }
+}
+```
+
+### Set FlowModelRepository
+
+```ts
+flowEngine.setModelRepository(new FlowModelRepository(this.app));
+```
+
+## Model Management Methods Provided by FlowEngine
+
+### Local Methods
+
+```ts
+await flowEngine.createModelAsync(options); // Create a local model instance
+flowEngine.getModel(uid);        // Get a local model instance
+flowEngine.removeModel(uid);     // Remove a local model instance
+```
+
+### Remote Methods (Implemented by ModelRepository)
+
+```ts
+await flowEngine.loadModel(uid);     // Load model from remote
+await flowEngine.saveModel(model);   // Save model to remote
+await flowEngine.destroyModel(uid);  // Delete model from remote
+```
+
+## model Instance Methods
+
+```ts
+const model = await this.flowEngine.createModelAsync({
+  use: 'FlowModel',
+});
+await model.save();     // Save to remote
+await model.destroy();  // Delete from remote
+```

package/dist/ai/docs/nocobase/flow-engine/flow-model-settings.md

@@ -0,0 +1,101 @@
+# FlowModel Flow and Configuration
+
+FlowModel provides a "Flow"-based approach to implement component configuration logic, making component behavior and configuration more extensible and visual.
+
+## Custom Model
+
+You can create a custom component model by extending `FlowModel`. The model needs to implement the `render()` method to define the component's rendering logic.
+
+```ts
+class MyModel extends FlowModel {
+  render() {
+    return <Button {...this.props} />;
+  }
+}
+```
+
+## Registering a Flow
+
+Each model can register one or more **Flows** to describe the component's configuration logic and interaction steps.
+
+```ts
+MyModel.registerFlow({
+  key: 'buttonSettings',
+  title: 'Button Settings',
+  steps: {
+    general: {
+      title: 'General Configuration',
+      uiSchema: {
+        title: {
+          type: 'string',
+          title: 'Button Title',
+          'x-decorator': 'FormItem',
+          'x-component': 'Input',
+        },
+      },
+      defaultParams: {
+        type: 'primary',
+      },
+      handler(ctx, params) {
+        ctx.model.setProps('children', params.title);
+        ctx.model.setProps('type', params.type);
+      },
+    },
+  },
+});
+```
+
+Description
+
+-   `key`: The unique identifier for the Flow.
+-   `title`: The name of the Flow, used for UI display.
+-   `steps`: Defines the configuration steps (Step). Each step includes:
+    -   `title`: The step title.
+    -   `uiSchema`: The configuration form structure (compatible with Formily Schema).
+    -   `defaultParams`: Default parameters.
+    -   `handler(ctx, params)`: Triggered on save to update the model's state.
+
+## Rendering the Model
+
+When rendering a component model, you can use the `showFlowSettings` parameter to control whether to enable the configuration feature. If `showFlowSettings` is enabled, a configuration entry (such as a settings icon or button) will automatically appear in the upper-right corner of the component.
+
+```ts
+<FlowModelRenderer model={model} showFlowSettings />
+```
+
+## Manually Opening the Configuration Form with openFlowSettings
+
+In addition to opening the configuration form through the built-in interaction entry, you can also manually call
+`openFlowSettings()`.
+
+``` ts
+flowSettings.open(options: FlowSettingsOpenOptions): Promise<boolean>;
+model.openFlowSettings(options?: Omit<FlowSettingsOpenOptions, 'model'>): Promise<boolean>;
+```
+
+### Parameter Definitions
+
+``` ts
+interface FlowSettingsOpenOptions {
+  model: FlowModel;               // Required, the model instance it belongs to
+  preset?: boolean;               // Renders only steps marked as preset=true (default false)
+  flowKey?: string;               // Specify a single Flow
+  flowKeys?: string[];            // Specify multiple Flows (ignored if flowKey is also provided)
+  stepKey?: string;               // Specify a single step (usually used with flowKey)
+  uiMode?: 'dialog' | 'drawer';   // The container for displaying the form, default 'dialog'
+  onCancel?: () => void;          // Callback when cancel is clicked
+  onSaved?: () => void;           // Callback after the configuration is saved successfully
+}
+```
+
+### Example: Opening a Specific Flow's Configuration Form in Drawer Mode
+
+``` ts
+await model.openFlowSettings({
+  flowKey: 'buttonSettings',
+  uiMode: 'drawer',
+  onSaved: () => {
+    console.log('Button settings saved');
+  },
+});
+```

package/dist/ai/docs/nocobase/flow-engine/flow-model-usage.md

@@ -0,0 +1 @@
+# Using and Rendering FlowModel

package/dist/ai/docs/nocobase/flow-engine/flow-model-vs-react-component.md

@@ -0,0 +1,74 @@
+# FlowModel vs React.Component
+
+## Comparison of Basic Responsibilities
+
+| Feature/Capability | `React.Component` | `FlowModel` |
+| --- | --- | --- |
+| Rendering Capability | Yes, the `render()` method generates UI | Yes, the `render()` method generates UI |
+| State Management | Built-in `state` and `setState` | Uses `props`, but state management relies more on the model tree structure |
+| Lifecycle | Yes, e.g., `componentDidMount` | Yes, e.g., `onInit`, `onMount`, `onUnmount` |
+| Purpose | Building UI components | Building data-driven, flow-based, structured "model trees" |
+| Data Structure | Component tree | Model tree (supports parent-child models, multi-instance Fork) |
+| Child Components | Using JSX to nest components | Using `setSubModel`/`addSubModel` to explicitly set sub-models |
+| Dynamic Behavior | Event binding, state updates drive UI | Registering/dispatching Flows, handling automatic flows |
+| Persistence | No built-in mechanism | Supports persistence (e.g., `model.save()`) |
+| Supports Fork (multiple renderings) | No (requires manual reuse) | Yes (`createFork` for multiple instantiations) |
+| Engine Control | None | Yes, managed, registered, and loaded by `FlowEngine` |
+
+## Lifecycle Comparison
+
+| Lifecycle Hook | `React.Component` | `FlowModel` |
+| --- | --- | --- |
+| Initialization | `constructor`, `componentDidMount` | `onInit`, `onMount` |
+| Unmounting | `componentWillUnmount` | `onUnmount` |
+| Responding to Input | `componentDidUpdate` | `onBeforeAutoFlows`, `onAfterAutoFlows` |
+| Error Handling | `componentDidCatch` | `onAutoFlowsError` |
+
+## Construction Structure Comparison
+
+**React:**
+
+```tsx pure
+class MyComponent extends React.Component {
+  render() {
+    return <div>Hello</div>;
+  }
+}
+```
+
+**FlowModel:**
+
+```tsx pure
+class HelloModel extends FlowModel {
+  render() {
+    return <div>Hello</div>;
+  }
+}
+```
+
+## Component Tree vs Model Tree
+
+*   **React Component Tree**: A UI rendering tree formed by nested JSX at runtime.
+*   **FlowModel Model Tree**: A logical structure tree managed by FlowEngine, which can be persisted, and allows dynamic registration and control of sub-models. Suitable for building page blocks, action flows, data models, etc.
+
+## Special Features (FlowModel Specific)
+
+| Function | Description |
+| --- | --- |
+| `registerFlow` | Register flow |
+| `applyFlow` / `dispatchEvent` | Execute/trigger flow |
+| `setSubModel` / `addSubModel` | Explicitly control the creation and binding of sub-models |
+| `createFork` | Supports reusing a model's logic for multiple renderings (e.g., each row in a table) |
+| `openFlowSettings` | Flow step settings |
+| `save` / `saveStepParams()` | The model can be persisted and integrated with the backend |
+
+## Summary
+
+| Item | React.Component | FlowModel |
+| --- | --- | --- |
+| Suitable Scenarios | UI layer component organization | Data-driven flow and block management |
+| Core Idea | Declarative UI | Model-driven structured flow |
+| Management Method | React controls the lifecycle | FlowModel controls the model's lifecycle and structure |
+| Advantages | Rich ecosystem and toolchain | Strongly structured, flows can be persisted, sub-models are controllable |
+
+> FlowModel can be used complementarily with React: Use React for rendering within a FlowModel, while its lifecycle and structure are managed by FlowEngine.

package/dist/ai/docs/nocobase/flow-engine/flow-model.md

@@ -0,0 +1,45 @@
+# Starting with FlowModel
+
+## Custom FlowModel
+
+```tsx pure
+class HelloModel extends FlowModel {
+  render() {
+    return (
+      <div>
+        <h1>Hello, NocoBase!</h1>
+        <p>This is a simple block rendered by HelloModel.</p>
+      </div>
+    );
+  }
+}
+```
+
+## Available FlowModel Base Classes
+
+| Base Class Name         | Description                               |
+| ----------------------- | ----------------------------------------- |
+| `BlockModel`            | Base class for all blocks                 |
+| `CollectionBlockModel`  | Collection block, inherits from BlockModel |
+| `ActionModel`           | Base class for all actions                |
+
+## Registering FlowModel
+
+```ts
+export class PluginHelloClient extends Plugin {
+  async load() {
+    this.engine.registerModelLoaders({
+      HelloModel: {
+        // Dynamic import: the model module loads only when this model is first needed
+        loader: () => import('./HelloModel'),
+      },
+    });
+  }
+}
+```
+
+## Rendering FlowModel
+
+```tsx pure
+<FlowModelRenderer model={model} />
+```

package/dist/ai/docs/nocobase/flow-engine/index.md

@@ -0,0 +1,59 @@
+# What is FlowEngine?
+
+FlowEngine is a new front-end no-code, low-code development engine introduced in NocoBase 2.0. It combines models (Model) with flows (Flow) to simplify front-end logic and enhance reusability and maintainability. At the same time, by leveraging the configurable nature of Flow, it provides no-code configuration and orchestration capabilities for front-end components and business logic.
+
+## Why is it called FlowEngine?
+
+Because in FlowEngine, the properties and logic of components are no longer statically defined, but are driven and managed by a **Flow**.
+
+*   **Flow**, like a data stream, breaks down logic into ordered steps (Step) and applies them to the component sequentially;
+*   **Engine** signifies that it is an engine that drives front-end logic and interactions.
+
+Therefore, **FlowEngine = A front-end logic engine driven by flows**.
+
+## What is a Model?
+
+In FlowEngine, a Model is an abstract model of a component, responsible for:
+
+*   Managing the component's **properties (Props) and state**;
+*   Defining the component's **rendering method**;
+*   Hosting and executing the **Flow**;
+*   Uniformly handling **event dispatching** and **lifecycles**.
+
+In other words, **the Model is the logical brain of the component**, turning it from a static element into a configurable and orchestratable dynamic unit.
+
+## What is a Flow?
+
+In FlowEngine, a **Flow is a logical flow that serves the Model**.
+Its purpose is to:
+
+*   Break down property or event logic into steps (Step) and execute them sequentially in a flow-like manner;
+*   Manage property changes as well as event responses;
+*   Make logic **dynamic, configurable, and reusable**.
+
+## How to understand these concepts?
+
+You can think of a **Flow** as a **stream of water**:
+
+*   **A Step is like a node along the stream's path**
+    Each Step performs a small task (e.g., setting a property, triggering an event, calling an API), just as water has an effect when it passes through a gate or a waterwheel.
+
+*   **The flow is ordered**
+    Water flows along a predetermined path from upstream to downstream, passing through all Steps in sequence; similarly, the logic in a Flow is executed in the defined order.
+
+*   **The flow can be branched and combined**
+    A stream of water can be split into multiple smaller streams or merged together; a Flow can also be broken down into multiple sub-flows or combined into more complex logical chains.
+
+*   **The flow is configurable and controllable**
+    The direction and volume of a water stream can be adjusted with a sluice gate; the execution method and parameters of a Flow can also be controlled through configuration (stepParams).
+
+Analogy Summary
+
+*   A **component** is like a waterwheel that needs a stream of water to turn;
+*   The **Model** is the base and controller of this waterwheel, responsible for receiving the water and driving its operation;
+*   The **Flow** is that stream of water that passes through each Step in order, causing the component to continuously change and respond.
+
+So in FlowEngine:
+
+*   **Flow allows logic to move naturally like a stream of water**;
+*   **Model makes the component the carrier and executor of this stream**.

package/dist/ai/docs/nocobase/flow-engine/js-model/js-action.md

@@ -0,0 +1 @@
+# JS Action

package/dist/ai/docs/nocobase/flow-engine/js-model/js-block.md

@@ -0,0 +1,2 @@
+# JS Block
+---

package/dist/ai/docs/nocobase/flow-engine/js-model/js-column.md

@@ -0,0 +1 @@
+# JS Table Column

package/dist/ai/docs/nocobase/flow-engine/js-model/js-field.md

@@ -0,0 +1 @@
+# JS 字段

package/dist/ai/docs/nocobase/flow-engine/js-model/js-item.md

@@ -0,0 +1 @@
+# JS Item

package/dist/ai/docs/nocobase/flow-engine/learning-roadmap.md

@@ -0,0 +1,3 @@
+# Learning Roadmap
+
+![20251102202401](https://static-docs.nocobase.com/20251102202401.png)