@nocobase/plugin-ai 2.2.0-alpha.3 → 2.2.0-alpha.5

package/dist/ai/docs/nocobase/interface-builder/blocks/data-blocks/comment.md

@@ -0,0 +1,107 @@
+---
+pkg: "@nocobase/plugin-block-comment"
+title: "Comment Block"
+description: "Comment block: view and create comments in record details, pop-ups, and similar scenarios, with field mapping, pagination, data scope, default sorting, and auto jump to last page."
+keywords: "Comment Block,CommentBlock,comment collection,field mapping,data scope,default sorting,interface builder,NocoBase"
+---
+
+# Comment Block
+
+## Introduction
+
+The Comment block adds commenting capabilities to business records. You can add it to detail pages or pop-ups for tasks, articles, tickets, customers, and other records, so users can view, reply to, and create comments around the current record.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_02_PM.png)
+
+:::tip
+
+The Comment block does not create a collection by itself. Before using it, prepare a collection for storing comments and configure fields such as comment content, commenter, comment owner, and comment time.
+
+:::
+
+## Add a block
+
+The Comment block is usually added to the detail page or pop-up of a business record.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_03_PM.png)
+
+1. Open the target record detail page or pop-up
+2. Click "Add block"
+3. Select "Comment"
+4. Select the collection used to store comments
+5. Complete field mapping as prompted
+
+If the Comment block is created from an association, NocoBase will try to automatically identify the comment owner field and the current record value based on the current association. In this case, "Comment owner field" and "Comment owner field value" are filled automatically, and usually do not need manual configuration.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_04_PM.png)
+
+If the block is created directly from the comment collection, you need to manually configure the comment owner field and value.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_03_PM%20(1).png)
+
+## Field mapping
+
+The Comment block uses "Field mapping" to know how each comment should be displayed and saved.
+
+| Configuration | Description |
+| --- | --- |
+| Comment content field | Select the field used to store the comment body. |
+| Commenter field | Select a many-to-one field associated with the users collection. |
+| Comment owner field | Select the field used to store the current business record identifier. |
+| Comment owner field value | Specify the current business record value, such as `{{ ctx.popup.record.id }}`. |
+| Comment date field | Select the comment time field, used for display and default sorting. |
+
+### Comment owner field
+
+"Comment owner field" is used to filter comments for the current record, and is also written when a new comment is created.
+
+When selected manually, the dropdown only shows ordinary scalar fields and does not show association fields. Common configurations are:
+
+| Business collection | Owner field in comment collection | Comment owner field value |
+| --- | --- | --- |
+| Tasks | `taskId` | `{{ ctx.popup.record.id }}` |
+| Articles | `postId` | `{{ ctx.popup.record.id }}` |
+| Tickets | `ticketId` | `{{ ctx.popup.record.id }}` |
+
+If the current record uses a unique identifier other than `id`, change "Comment owner field value" to the corresponding field, such as `{{ ctx.popup.record.uuid }}`.
+
+### Automatic mapping from associations
+
+If the block is created from an association of the business record, the Comment block prioritizes the foreign key field of that association as the comment owner field, and uses the current record value as the comment owner field value.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_04_PM.png)
+
+For example, if there is a one-to-many association between the task collection and the task comment collection, and the foreign key field in the task comment collection is `taskId`, then when you add a Comment block from the association in the task detail page, the block automatically uses:
+
+- Comment owner field: `taskId`
+- Comment owner field value: the identifier of the current task record
+
+This approach is suitable for most scenarios and reduces manual configuration errors.
+
+## Block settings
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_07_PM.png)
+
+### Page size
+
+Set how many comments are displayed on each page. Available values include `5`, `10`, `20`, `50`, `100`, and `200`.
+
+### Data scope
+
+Set the data filtering scope for the comment list. You can add more conditions here, such as showing only comments that match certain status or permission conditions.
+
+For more details, see [Set data scope](../block-settings/data-scope.md).
+
+### Default sorting rule
+
+Set the default sorting rule for the comment list. Usually, you can sort by the comment date field in ascending or descending order.
+
+If no default sorting rule is configured separately, the Comment block prioritizes the "Comment date field" as the default sorting field.
+
+For more details, see [Set sorting rule](../block-settings/sorting-rule.md).
+
+### Auto jump to last page
+
+Disabled by default. When disabled, the Comment block stays on the first page after opening.
+
+When enabled, the Comment block jumps to the last page on first load. This is suitable when you want users to see the latest comments first.

package/dist/ai/docs/nocobase/ops-management/version-control/index.md

@@ -1,4 +1,5 @@
 ---
+pkg: '@nocobase/plugin-version-control'
 title: "Version control"
 description: "Version control plugin guide: automatically save versions during AI Builder sessions, create and restore versions manually, configure retention, set shortcuts, and include user collections in saved versions."
 keywords: "Version control,ops management,AI Builder,nocobase-revision,nb revision create,create version,restore version,NocoBase"

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-block-comment/index.md

@@ -0,0 +1,14 @@
+---
+title: "Block: Comment"
+keywords: "Block: Comment,comment block,comment collection,plugin,NocoBase"
+displayName: "Block: Comment"
+packageName: '@nocobase/plugin-block-comment'
+description: |
+  Provides a Comment block for viewing and creating comments in record details, pop-ups, and similar scenarios.
+isFree: true
+builtIn: true
+defaultEnabled: false
+editionLevel: 0
+---
+
+# Block: Comment

package/dist/ai/docs/nocobase/workflow/development/api.md

@@ -1,3 +1,9 @@
+---
+title: "API Reference"
+description: "Workflow extension API reference: Workflow Model, node execution context, trigger API, variable passing."
+keywords: "workflow,API reference,Workflow Model,node context,trigger API,NocoBase"
+---
+
 # API Reference
 
 ## Server-side
@@ -29,9 +35,9 @@ Extends and registers a new trigger type.
 
 **Parameters**
 
-| Parameter | Type | Description |
-| --------- | --------------------------- | ---------------- |
-| `type` | `string` | Trigger type identifier |
+| Parameter | Type                        | Description              |
+| --------- | --------------------------- | ------------------------ |
+| `type`    | `string`                    | Trigger type identifier  |
 | `trigger` | `typeof Trigger \| Trigger` | Trigger type or instance |
 
 **Example**
@@ -84,9 +90,9 @@ Extends and registers a new node type.
 
 **Parameters**
 
-| Parameter | Type | Description |
-| ------------- | ----------------------------------- | -------------- |
-| `type` | `string` | Instruction type identifier |
+| Parameter     | Type                                | Description                |
+| ------------- | ----------------------------------- | -------------------------- |
+| `type`        | `string`                            | Instruction type identifier |
 | `instruction` | `typeof Instruction \| Instruction` | Instruction type or instance |
 
 **Example**
@@ -128,7 +134,7 @@ Triggers a specific workflow. Mainly used in custom triggers to trigger the corr
 | `workflow` | `WorkflowModel` | The workflow object to be triggered |
 | `context` | `object` | Context data provided at trigger time |
 
-:::info{title=Tip}
+:::info{title=Note}
 `context` is currently a required item. If not provided, the workflow will not be triggered.
 :::
 
@@ -163,11 +169,11 @@ Resumes a waiting workflow with a specific node job.
 
 **Parameters**
 
-| Parameter | Type | Description |
-| ----- | ---------- | ---------------- |
-| `job` | `JobModel` | The updated job object |
+| Parameter | Type       | Description            |
+| --------- | ---------- | ---------------------- |
+| `job`     | `JobModel` | The updated job object |
 
-:::info{title=Tip}
+:::info{title=Note}
 The passed job object is generally an updated object, and its `status` is usually updated to a value other than `JOB_STATUS.PENDING`, otherwise it will continue to wait.
 :::
 
@@ -179,11 +185,15 @@ See [source code](https://github.com/nocobase/nocobase/blob/main/packages/plugin
 
 The base class for triggers, used to extend custom trigger types.
 
-| Parameter | Type | Description |
-| ------------- | ----------------------------------------------------------- | ---------------------- |
-| `constructor` | `(public readonly workflow: PluginWorkflowServer): Trigger` | Constructor |
-| `on?` | `(workflow: WorkflowModel): void` | Event handler after enabling a workflow |
-| `off?` | `(workflow: WorkflowModel): void` | Event handler after disabling a workflow |
+```ts
+import { Trigger } from '@nocobase/plugin-workflow';
+```
+
+| Parameter     | Type                                                        | Description                              |
+| ------------- | ----------------------------------------------------------- | ---------------------------------------- |
+| `constructor` | `(public readonly workflow: PluginWorkflowServer): Trigger` | Constructor                              |
+| `on?`         | `(workflow: WorkflowModel): void`                           | Event handler after enabling a workflow  |
+| `off?`        | `(workflow: WorkflowModel): void`                           | Event handler after disabling a workflow |
 
 `on`/`off` are used to register/unregister event listeners when a workflow is enabled/disabled. The passed parameter is the workflow instance corresponding to the trigger, which can be processed according to the configuration. Some trigger types that already have globally listened events may not need to implement these two methods. For example, in a scheduled trigger, you can register a timer in `on` and unregister it in `off`.
 
@@ -191,12 +201,16 @@ The base class for triggers, used to extend custom trigger types.
 
 The base class for instruction types, used to extend custom instruction types.
 
-| Parameter | Type | Description |
-| ------------- | --------------------------------------------------------------- | ---------------------------------- |
-| `constructor` | `(public readonly workflow: PluginWorkflowServer): Instruction` | Constructor |
-| `run` | `Runner` | Execution logic for the first entry into the node |
-| `resume?` | `Runner` | Execution logic for entering the node after resuming from an interruption |
-| `getScope?` | `(node: FlowNodeModel, data: any, processor: Processor): any` | Provides the local variable content for the branch generated by the corresponding node |
+```ts
+import { Instruction } from '@nocobase/plugin-workflow';
+```
+
+| Parameter     | Type                                                            | Description                                                                    |
+| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `constructor` | `(public readonly workflow: PluginWorkflowServer): Instruction` | Constructor                                                                    |
+| `run`         | `Runner`                                                        | Execution logic for the first entry into the node                              |
+| `resume?`     | `Runner`                                                        | Execution logic for entering the node after resuming from an interruption      |
+| `getScope?`   | `(node: FlowNodeModel, data: any, processor: Processor): any`  | Provides the local variable content for the branch generated by the corresponding node |
 
 **Related Types**
 
@@ -230,16 +244,20 @@ For `getScope`, you can refer to the [implementation of the loop node](https://g
 
 A constant table for workflow execution plan statuses, used to identify the current status of the corresponding execution plan.
 
-| Constant Name | Meaning |
-| ------------------------------- | -------------------- |
-| `EXECUTION_STATUS.QUEUEING` | Queueing |
-| `EXECUTION_STATUS.STARTED` | Started |
-| `EXECUTION_STATUS.RESOLVED` | Resolved |
-| `EXECUTION_STATUS.FAILED` | Failed |
-| `EXECUTION_STATUS.ERROR` | Error |
-| `EXECUTION_STATUS.ABORTED` | Aborted |
-| `EXECUTION_STATUS.CANCELED` | Canceled |
-| `EXECUTION_STATUS.REJECTED` | Rejected |
+```ts
+import { EXECUTION_STATUS } from '@nocobase/plugin-workflow';
+```
+
+| Constant Name                   | Meaning                                 |
+| ------------------------------- | --------------------------------------- |
+| `EXECUTION_STATUS.QUEUEING`     | Queueing                                |
+| `EXECUTION_STATUS.STARTED`      | Started                                 |
+| `EXECUTION_STATUS.RESOLVED`     | Resolved                                |
+| `EXECUTION_STATUS.FAILED`       | Failed                                  |
+| `EXECUTION_STATUS.ERROR`        | Error                                   |
+| `EXECUTION_STATUS.ABORTED`      | Aborted                                 |
+| `EXECUTION_STATUS.CANCELED`     | Canceled                                |
+| `EXECUTION_STATUS.REJECTED`     | Rejected                                |
 | `EXECUTION_STATUS.RETRY_NEEDED` | Not successfully executed, retry needed |
 
 Except for the first three, all others represent a failed state, but can be used to describe different reasons for failure.
@@ -248,33 +266,39 @@ Except for the first three, all others represent a failed state, but can be used
 
 A constant table for workflow node job statuses, used to identify the current status of the corresponding node job. The status generated by the node also affects the status of the entire execution plan.
 
-| Constant Name | Meaning |
-| ------------------------- | ---------------------------------------- |
-| `JOB_STATUS.PENDING` | Pending: Execution has reached this node, but the instruction requires it to suspend and wait |
-| `JOB_STATUS.RESOLVED` | Resolved |
-| `JOB_STATUS.FAILED` | Failed: The execution of this node failed to meet the configured conditions |
-| `JOB_STATUS.ERROR` | Error: An unhandled error occurred during the execution of this node |
-| `JOB_STATUS.ABORTED` | Aborted: The execution of this node was terminated by other logic after being in a pending state |
-| `JOB_STATUS.CANCELED` | Canceled: The execution of this node was manually canceled after being in a pending state |
-| `JOB_STATUS.REJECTED` | Rejected: The continuation of this node was manually rejected after being in a pending state |
-| `JOB_STATUS.RETRY_NEEDED` | Not successfully executed, retry needed |
+```ts
+import { JOB_STATUS } from '@nocobase/plugin-workflow';
+```
+
+| Constant Name              | Meaning                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `JOB_STATUS.PENDING`      | Pending: Execution has reached this node, but the instruction requires it to suspend and wait    |
+| `JOB_STATUS.RESOLVED`     | Resolved                                                                                         |
+| `JOB_STATUS.FAILED`       | Failed: The execution of this node failed to meet the configured conditions                      |
+| `JOB_STATUS.ERROR`        | Error: An unhandled error occurred during the execution of this node                             |
+| `JOB_STATUS.ABORTED`      | Aborted: The execution of this node was terminated by other logic after being in a pending state  |
+| `JOB_STATUS.CANCELED`     | Canceled: The execution of this node was manually canceled after being in a pending state         |
+| `JOB_STATUS.REJECTED`     | Rejected: The continuation of this node was manually rejected after being in a pending state      |
+| `JOB_STATUS.RETRY_NEEDED` | Not successfully executed, retry needed                                                          |
 
 ## Client-side
 
 The APIs available in the client-side package structure are shown in the following code:
 
 ```ts
-import PluginWorkflowClient, {
+import PluginWorkflowClientV2, {
   Trigger,
   Instruction,
-} from '@nocobase/plugin-workflow/client';
+} from '@nocobase/plugin-workflow/client-v2';
 ```
 
-### `PluginWorkflowClient`
+### `PluginWorkflowClientV2`
+
+Workflow client plugin class. Usually obtained via `this.app.pm.get('workflow')`.
 
 #### `registerTrigger()`
 
-Registers the configuration panel for the trigger type.
+Registers the configuration panel for a trigger type.
 
 **Signature**
 
@@ -283,13 +307,13 @@ Registers the configuration panel for the trigger type.
 **Parameters**
 
 | Parameter | Type | Description |
-| --------- | --------------------------- | ------------------------------------ |
-| `type` | `string` | Trigger type identifier, consistent with the identifier used for registration |
+| --- | --- | --- |
+| `type` | `string` | Trigger type identifier, consistent with the server-side registered identifier |
 | `trigger` | `typeof Trigger \| Trigger` | Trigger type or instance |
 
 #### `registerInstruction()`
 
-Registers the configuration panel for the node type.
+Registers the configuration panel for a node type.
 
 **Signature**
 
@@ -298,8 +322,8 @@ Registers the configuration panel for the node type.
 **Parameters**
 
 | Parameter | Type | Description |
-| ------------- | ----------------------------------- | ---------------------------------- |
-| `type` | `string` | Node type identifier, consistent with the identifier used for registration |
+| --- | --- | --- |
+| `type` | `string` | Node type identifier, consistent with the server-side registered identifier |
 | `instruction` | `typeof Instruction \| Instruction` | Node type or instance |
 
 #### `registerInstructionGroup()`
@@ -320,63 +344,221 @@ If you need to extend other groups, you can use this method to register them.
 **Parameters**
 
 | Parameter | Type | Description |
-| --------- | ----------------- | ----------------------------- |
-| `type` | `string` | Node group identifier, consistent with the identifier used for registration |
+| --- | --- | --- |
+| `type` | `string` | Node group identifier |
 | `group` | `{ label: string }` | Group information, currently only includes the title |
 
 **Example**
 
-```js
-export default class YourPluginClient extends Plugin {
-  load() {
-    const pluginWorkflow = this.app.pm.get(PluginWorkflowClient);
+```ts
+import { Plugin } from '@nocobase/client-v2';
 
+export default class YourPluginClient extends Plugin {
+  async load() {
+    const pluginWorkflow = this.app.pm.get('workflow');
     pluginWorkflow.registerInstructionGroup('ai', { label: `{{t("AI", { ns: "${NAMESPACE}" })}}` });
   }
 }
 ```
 
+#### `isWorkflowSync()`
+
+Determines whether a workflow is in synchronous mode.
+
+**Signature**
+
+`isWorkflowSync(workflow: object): boolean`
+
 ### `Trigger`
 
 The base class for triggers, used to extend custom trigger types.
 
 | Parameter | Type | Description |
-| --------------- | ---------------------------------------------------------------- | ---------------------------------- |
+| --- | --- | --- |
 | `title` | `string` | Trigger type name |
-| `fieldset` | `{ [key: string]: ISchema }` | Collection of trigger configuration items |
-| `scope?` | `{ [key: string]: any }` | Collection of objects that may be used in the configuration item Schema |
-| `components?` | `{ [key: string]: React.FC }` | Collection of components that may be used in the configuration item Schema |
-| `useVariables?` | `(config: any, options: UseVariableOptions ) => VariableOptions` | Value accessor for trigger context data |
+| `description?` | `string` | Trigger type description |
+| `PresetFieldsetLoader?` | `LoaderOf` | Preset configuration form on creation (lazy-loaded) |
+| `FieldsetLoader?` | `LoaderOf` | Full trigger configuration form (lazy-loaded) |
+| `TriggerFieldsetLoader?` | `LoaderOf` | Input form for manual execution (lazy-loaded) |
+| `validate` | `(config: Record<string, unknown>) => boolean` | Configuration validation; returns `true` if the configuration is valid |
+| `createDefaultConfig?` | `() => Record<string, unknown>` | Provides default configuration values |
+| `useVariables?` | `(config, options?: UseVariableOptions) => VariableOption[] \| null` | Variable options for trigger context data |
+| `getCreateModelMenuItem?` | `(args) => SubModelItem \| SubModelItem[] \| null` | Menu items for creating sub-models on the canvas |
+| `useTempAssociationSource?` | `(config, workflow?) => TriggerTempAssociationSource \| null` | Provides a temporary association data source |
 
-- If `useVariables` is not set, it means that this type of trigger does not provide a value retrieval function, and the trigger's context data cannot be selected in the workflow nodes.
+**Related Types**
+
+```ts
+export type LoaderOf<P = {}> = () => Promise<{ default: ComponentType<P> }>;
+```
+
+- If `useVariables` is not set, it means that this trigger type does not provide a value retrieval function, and the trigger's context data cannot be selected in the workflow nodes.
 
 ### `Instruction`
 
 The base class for instructions, used to extend custom node types.
 
 | Parameter | Type | Description |
-| -------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `group` | `string` | Node type group identifier, currently available options: `'control'`/`'collection'`/`'manual'`/`'extended'` |
-| `fieldset` | `Record<string, ISchema>` | Collection of node configuration items |
-| `scope?` | `Record<string, Function>` | Collection of objects that may be used in the configuration item Schema |
-| `components?` | `Record<string, React.FC>` | Collection of components that may be used in the configuration item Schema |
-| `Component?` | `React.FC` | Custom rendering component for the node |
-| `useVariables?` | `(node, options: UseVariableOptions) => VariableOption` | Method for the node to provide node variable options |
-| `useScopeVariables?` | `(node, options?) => VariableOptions` | Method for the node to provide branch local variable options |
-| `useInitializers?` | `(node) => SchemaInitializerItemType` | Method for the node to provide initializer options |
-| `isAvailable?` | `(ctx: NodeAvailableContext) => boolean` | Method to determine if the node is available |
+| --- | --- | --- |
+| `title` | `string` | Node type name |
+| `type` | `string` | Node type identifier |
+| `group` | `string` | Node type group identifier, options: `'control'`/`'collection'`/`'manual'`/`'extended'` |
+| `description?` | `string` | Node type description |
+| `icon?` | `JSX.Element` | Node icon |
+| `FieldsetLoader?` | `LoaderOf` | Node configuration drawer form (lazy-loaded) |
+| `PresetFieldsetLoader?` | `LoaderOf` | Preset configuration form on creation (lazy-loaded) |
+| `ComponentLoader?` | `LoaderOf<{ data: any }>` | Custom node rendering on the canvas (lazy-loaded), used for branch nodes and other cases requiring special rendering |
+| `branching?` | `boolean \| object \| ((config) => boolean \| object)` | Declares whether the node is a branch node |
+| `end?` | `boolean \| ((node) => boolean)` | Declares whether the node is a terminal node |
+| `testable?` | `boolean` | Declares whether the node supports test runs |
+| `createDefaultConfig?` | `() => object` | Provides default configuration values |
+| `useVariables?` | `(node, options?: UseVariableOptions) => VariableOption` | Method for the node to provide variable options |
+| `useScopeVariables?` | `(node, options?) => VariableOption[] \| MetaTreeNode[]` | Method for the node to provide branch-scoped variable options |
+| `isAvailable?` | `(ctx: NodeAvailableContext) => boolean` | Method to determine whether the node is available |
+| `getCreateModelMenuItem?` | `({ node, workflow }) => SubModelItem \| null` | Menu items for creating sub-models on the canvas |
+| `useTempAssociationSource?` | `(node) => TempAssociationSource \| null` | Provides a temporary association data source |
 
 **Related Types**
 
 ```ts
 export type NodeAvailableContext = {
+  engine: WorkflowPlugin;
   workflow: object;
   upstream: object;
   branchIndex: number;
 };
 ```
 
-- If `useVariables` is not set, it means that this node type does not provide a value retrieval function, and the result data of this type of node cannot be selected in the workflow nodes. If the result value is singular (not selectable), you can return static content that expresses the corresponding information (see: [calculation node source code](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/nodes/calculation.tsx#L68)). If it needs to be selectable (e.g., a property of an Object), you can customize the corresponding selection component output (see: [create data node source code](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/nodes/create.tsx#L41)).
-- `Component` is a custom rendering component for the node. When the default node rendering is not sufficient, it can be completely overridden for custom node view rendering. For example, if you need to provide more action buttons or other interactions for the start node of a branch type, you would use this method (see: [parallel branch source code](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow-parallel/src/client/ParallelInstruction.tsx)).
-- `useInitializers` is used to provide a method for initializing blocks. For example, in a manual node, you can initialize related user blocks based on upstream nodes. If this method is provided, it will be available when initializing blocks in the manual node's interface configuration (see: [create data node source code](https://github.com/nocobase/nocobase/blob/main/packages/plugins/@nocobase/plugin-workflow/src/client/nodes/create.tsx#L71)).
-- `isAvailable` is mainly used to determine whether a node can be used (added) in the current environment. The current environment includes the current workflow, upstream nodes, and the current branch index.
+- If `useVariables` is not set, it means that this node type does not provide a value retrieval function, and the result data of this type of node cannot be selected in the workflow nodes. If the result value is singular (not selectable), you can return static content that expresses the corresponding information (see: [calculation node source code](https://github.com/nocobase/nocobase/blob/develop/packages/plugins/%40nocobase/plugin-workflow/src/client-v2/nodes/calculation.tsx)). If it needs to be selectable (e.g., a property of an Object), you can customize the corresponding selection component output (see: [query data node source code](https://github.com/nocobase/nocobase/blob/develop/packages/plugins/%40nocobase/plugin-workflow/src/client-v2/nodes/query.tsx)).
+- `ComponentLoader` is a custom rendering component for the node. When the default node rendering is not sufficient, it can be completely overridden for custom node view rendering. For example, to provide additional branch rendering for branch-type nodes (see: [condition node source code](https://github.com/nocobase/nocobase/blob/develop/packages/plugins/%40nocobase/plugin-workflow/src/client-v2/nodes/condition.tsx)).
+- `isAvailable` is mainly used to determine whether a node can be used (added) in the current environment. The current environment includes the workflow plugin instance, the current workflow, upstream nodes, and the current branch index.
+
+### Variable Input Components
+
+The workflow provides a set of variable input components for letting users select workflow variables in node/trigger configuration forms.
+
+```ts
+import {
+  WorkflowVariableInput,
+  WorkflowVariableTextArea,
+  WorkflowTypedVariableInput,
+  WorkflowVariableWrapper,
+} from '@nocobase/plugin-workflow/client-v2';
+```
+
+#### `WorkflowVariableInput`
+
+Variable input that supports selecting a variable and continuing to type content. Suitable for single-line input scenarios that require a mix of variable references and free text.
+
+```tsx
+import { WorkflowVariableInput } from '@nocobase/plugin-workflow/client-v2';
+
+<Form.Item name={['config', 'target']} label="Target">
+  <WorkflowVariableInput />
+</Form.Item>
+```
+
+![WorkflowVariableInput](https://static-docs.nocobase.com/20260701160110.png)
+
+**Props**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value?` | `string` | Variable path value, e.g. `{{$jobsMapByNodeKey.xxx.field}}` |
+| `onChange?` | `(value: string) => void` | Value change callback |
+| `variableOptions?` | `UseWorkflowVariableOptions` | Variable filter options (type filtering, depth, etc.) |
+| `disabled?` | `boolean` | Whether disabled |
+| `placeholder?` | `string` | Placeholder text |
+
+#### `WorkflowVariableTextArea`
+
+Multi-line text area that supports inserting variable references at any cursor position. Suitable for free text scenarios such as HTTP Body, template text, etc.
+
+```tsx
+import { WorkflowVariableTextArea } from '@nocobase/plugin-workflow/client-v2';
+
+<Form.Item name={['config', 'body']} label="Body">
+  <WorkflowVariableTextArea autoSize={{ minRows: 5 }} />
+</Form.Item>
+```
+
+![WorkflowVariableTextArea](https://static-docs.nocobase.com/20260701160242.png)
+
+**Props**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value?` | `string` | Text value (may contain variable references) |
+| `onChange?` | `(value: string) => void` | Value change callback |
+| `variableOptions?` | `UseWorkflowVariableOptions` | Variable filter options |
+| `delimiters?` | `readonly [string, string]` | Variable delimiters, defaults to `['{{', '}}']` |
+
+Inherits other Props from antd `TextArea` (such as `autoSize`, `placeholder`, etc.).
+
+#### `WorkflowTypedVariableInput`
+
+Typed input that switches between "constant" and "variable reference" modes. In variable mode, you can only select a variable; you cannot continue typing after selection. In constant mode, five types are supported: `string`, `number`, `boolean`, `date`, and `object`.
+
+```tsx
+import { WorkflowTypedVariableInput } from '@nocobase/plugin-workflow/client-v2';
+
+<Form.Item name={['config', 'value']} label="Value">
+  <WorkflowTypedVariableInput />
+</Form.Item>
+```
+
+![WorkflowTypedVariableInput](https://static-docs.nocobase.com/20260701160608.png)
+
+**Props**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `variableOptions?` | `UseWorkflowVariableOptions` | Variable filter options |
+
+Inherits other Props from `TypedVariableInput` (excluding internally used `extraNodes`, `metaTree`, `namespaces`).
+
+#### `WorkflowVariableWrapper`
+
+Generic wrapper for substituting different input components in different contexts. For example, when the same field requires different input methods in the trigger node configuration and the node configuration drawer, you can use this component to wrap a native input into a variable-mode-switchable input.
+
+```tsx
+import { WorkflowVariableWrapper } from '@nocobase/plugin-workflow/client-v2';
+
+<Form.Item name={['config', 'timeout']} label="Timeout">
+  <WorkflowVariableWrapper
+    render={({ value, onChange }) => (
+      <InputNumber value={value} onChange={onChange} min={0} />
+    )}
+  />
+</Form.Item>
+```
+
+**Props**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value?` | `TValue \| string \| null` | Current value (constant value or variable path string) |
+| `onChange?` | `(value: TValue \| string \| null) => void` | Value change callback |
+| `variableOptions?` | `UseWorkflowVariableOptions` | Variable filter options |
+| `render` | `(props: { value?, onChange? }) => ReactNode` | Renders the native input component |
+| `clearValue?` | `TValue \| null` | Initial value when switching from variable mode back to constant mode, defaults to `null` |
+
+### Collection-related Components
+
+The workflow also provides a set of collection-related helper components:
+
+```ts
+import {
+  CollectionCascader,
+  AppendsSelect,
+  FieldsSelect,
+  SortFieldsInput,
+  PaginationFields,
+} from '@nocobase/plugin-workflow/client-v2';
+```
+
+- `CollectionCascader` — Data-source-aware collection selector (cascader)
+- `AppendsSelect` — Association field preloading selector (tree select)
+- `FieldsSelect` — Collection field multi-selector
+- `SortFieldsInput` — Sort field input
+- `PaginationFields` — Pagination parameter form items

package/dist/ai/docs/nocobase/workflow/development/index.md

@@ -9,4 +9,5 @@ Extensions are mainly divided into two parts:
 
 ## Other Content
 
-- [API Reference](./api.md)
+- [API Reference](./api.md)
+- [v1 to v2 Client-side Migration Guide](./migration.md)