@nocobase/plugin-flow-engine 2.1.0-alpha.7 → 2.1.0-alpha.9

package/dist/ai/docs/runjs/context/data-source.md

@@ -1,18 +1,18 @@
 # ctx.dataSource
 
-The data source instance (`DataSource`) bound to the current RunJS context; used to access collections, field metadata, and collection config **within that data source**. Usually the current page/block’s data source (e.g. main `main`).
+The `DataSource` instance bound to the current RunJS execution context, used to access collections, field metadata, and manage collection configurations **within the current data source**. It usually corresponds to the data source selected for the current page or block (e.g., the main database `main`).
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Single data source** | Get collections, field metadata when the current data source is known |
-| **Collection management** | Get/add/update/remove collections in the current data source |
-| **Field by path** | Get field definition by `collectionName.fieldPath` (supports association path) |
+|------|------|
+| **Single Data Source Operations** | Get collection and field metadata when the current data source is known. |
+| **Collection Management** | Get, add, update, or delete collections under the current data source. |
+| **Get Fields by Path** | Use the `collectionName.fieldPath` format to get field definitions (supports association paths). |
 
-> Note: `ctx.dataSource` is the single data source for the current context; to enumerate or access other data sources use [ctx.dataSourceManager](./data-source-manager.md).
+> Note: `ctx.dataSource` represents a single data source for the current context. To enumerate or access other data sources, please use [ctx.dataSourceManager](./data-source-manager.md).
 
-## Type
+## Type Definition
 
 ```ts
 dataSource: DataSource;
@@ -20,15 +20,18 @@ dataSource: DataSource;
 class DataSource {
   constructor(options?: Record<string, any>);
 
-  get flowEngine(): FlowEngine;
-  get displayName(): string;
-  get key(): string;
-  get name(): string;
+  // Read-only properties
+  get flowEngine(): FlowEngine;   // Current FlowEngine instance
+  get displayName(): string;      // Display name (supports i18n)
+  get key(): string;              // Data source key, e.g., 'main'
+  get name(): string;             // Same as key
 
-  getCollections(): Collection[];
-  getCollection(name: string): Collection | undefined;
-  getAssociation(associationName: string): CollectionField | undefined;
+  // Collection reading
+  getCollections(): Collection[];                      // Get all collections
+  getCollection(name: string): Collection | undefined; // Get collection by name
+  getAssociation(associationName: string): CollectionField | undefined; // Get association field (e.g., users.roles)
 
+  // Collection management
   addCollection(collection: Collection | CollectionOptions): void;
   updateCollection(newOptions: CollectionOptions): void;
   upsertCollection(options: CollectionOptions): Collection | undefined;
@@ -36,6 +39,7 @@ class DataSource {
   removeCollection(name: string): void;
   clearCollections(): void;
 
+  // Field metadata
   getCollectionField(fieldPath: string): CollectionField | undefined;
 }
 ```
@@ -43,57 +47,61 @@ class DataSource {
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `key` | `string` | Data source key (e.g. `main`) |
+|------|------|------|
+| `key` | `string` | Data source key, e.g., `'main'` |
 | `name` | `string` | Same as key |
-| `displayName` | `string` | Display name (i18n) |
+| `displayName` | `string` | Display name (supports i18n) |
 | `flowEngine` | `FlowEngine` | Current FlowEngine instance |
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `getCollections()` | All collections in this data source (sorted, hidden filtered) |
-| `getCollection(name)` | Collection by name; `name` can be `collectionName.fieldName` for association target |
-| `getAssociation(associationName)` | Association field by `collectionName.fieldName` |
-| `getCollectionField(fieldPath)` | Field by `collectionName.fieldPath`; supports paths like `users.profile.avatar` |
+|------|------|
+| `getCollections()` | Gets all collections under the current data source (sorted, with hidden ones filtered). |
+| `getCollection(name)` | Gets a collection by name; `name` can be `collectionName.fieldName` to get the target collection of an association. |
+| `getAssociation(associationName)` | Gets an association field definition by `collectionName.fieldName`. |
+| `getCollectionField(fieldPath)` | Gets a field definition by `collectionName.fieldPath`, supporting association paths like `users.profile.avatar`. |
 
-## Relation to ctx.dataSourceManager
+## Relationship with ctx.dataSourceManager
 
-| Need | Recommended |
-|------|-------------|
-| **Single data source for context** | `ctx.dataSource` |
-| **Entry to all data sources** | `ctx.dataSourceManager` |
-| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
-| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
-| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
-| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to current context** | `ctx.dataSource` |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **Get collection within current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
 
-## Examples
+## Example
 
-### Get collections and fields
+### Get Collections and Fields
 
 ```ts
+// Get all collections
 const collections = ctx.dataSource.getCollections();
 
+// Get collection by name
 const users = ctx.dataSource.getCollection('users');
 const primaryKey = users?.filterTargetKey ?? 'id';
 
+// Get field definition by "collectionName.fieldPath" (supports associations)
 const field = ctx.dataSource.getCollectionField('users.profile.avatar');
 const userNameField = ctx.dataSource.getCollectionField('orders.createdBy.name');
 ```
 
-### Get association field
+### Get Association Fields
 
 ```ts
+// Get association field definition by collectionName.fieldName
 const rolesField = ctx.dataSource.getAssociation('users.roles');
 if (rolesField?.isAssociationField()) {
   const targetCol = rolesField.targetCollection;
-  // ...
+  // Process based on target collection structure
 }
 ```
 
-### Iterate collections
+### Iterate Through Collections for Dynamic Processing
 
 ```ts
 const collections = ctx.dataSource.getCollections();
@@ -104,25 +112,25 @@ for (const col of collections) {
 }
 ```
 
-### Validation or dynamic UI from field metadata
+### Perform Validation or Dynamic UI Based on Field Metadata
 
 ```ts
 const field = ctx.dataSource.getCollectionField('users.status');
 if (field) {
   const options = field.enum ?? [];
   const operators = field.getFilterOperators();
-  // ...
+  // Perform UI logic or validation based on interface, enum, validation, etc.
 }
 ```
 
 ## Notes
 
-- `getCollectionField(fieldPath)` uses path format `collectionName.fieldPath`; first segment is collection name, rest is field path (supports association, e.g. `user.name`).
-- `getCollection(name)` supports `collectionName.fieldName` and returns the association target collection.
-- In RunJS, `ctx.dataSource` is usually determined by the current block/page; if there is no bound data source it may be `undefined`—check before use.
+- The path format for `getCollectionField(fieldPath)` is `collectionName.fieldPath`, where the first segment is the collection name and the subsequent segments are the field path (supports associations, e.g., `user.name`).
+- `getCollection(name)` supports the `collectionName.fieldName` format, returning the target collection of the association field.
+- In the RunJS context, `ctx.dataSource` is usually determined by the data source of the current block or page. If no data source is bound to the context, it may be `undefined`; it is recommended to perform a null check before use.
 
 ## Related
 
-- [ctx.dataSourceManager](./data-source-manager.md): manager for all data sources
-- [ctx.collection](./collection.md): collection for current context
-- [ctx.collectionField](./collection-field.md): current field’s collection field definition
+- [ctx.dataSourceManager](./data-source-manager.md): Data source manager, manages all data sources.
+- [ctx.collection](./collection.md): The collection associated with the current context.
+- [ctx.collectionField](./collection-field.md): The collection field definition for the current field.

package/dist/ai/docs/runjs/context/element.md

@@ -1,57 +1,60 @@
 # ctx.element
 
-The ElementProxy instance for the sandbox DOM container; it is the default render target of `ctx.render()`. Available in JSBlock, JSField, JSItem, JSColumn, and other contexts that have a render container.
+An `ElementProxy` instance pointing to the sandbox DOM container, serving as the default rendering target for `ctx.render()`. It is available in scenarios where a rendering container exists, such as `JSBlock`, `JSField`, `JSItem`, and `JSColumn`.
 
-## Use Cases
+## Applicable Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Block’s DOM container for custom content |
-| **JSField / JSItem / FormJSFieldItem** | Field/item render container (often a `<span>`) |
-| **JSColumn** | Table cell DOM container for custom column content |
+|------|------|
+| **JSBlock** | The DOM container for the block, used to render custom block content. |
+| **JSField / JSItem / FormJSFieldItem** | The rendering container for a field or form item (usually a `<span>`). |
+| **JSColumn** | The DOM container for a table cell, used to render custom column content. |
 
-> Note: `ctx.element` is only available in RunJS contexts that have a render container; in contexts without UI (e.g. pure backend) it may be `undefined`—check before use.
+> Note: `ctx.element` is only available in RunJS contexts that have a rendering container. In contexts without a UI (such as pure backend logic), it may be `undefined`. It is recommended to perform a null check before use.
 
-## Type
+## Type Definition
 
 ```typescript
 element: ElementProxy | undefined;
 
+// ElementProxy is a proxy for the raw HTMLElement, exposing a secure API
 class ElementProxy {
-  __el: HTMLElement;  // Internal native DOM (only for specific cases)
-  innerHTML: string;  // Read/write sanitized with DOMPurify
-  outerHTML: string;
+  __el: HTMLElement;  // The internal raw DOM element (accessible only in specific scenarios)
+  innerHTML: string;  // Sanitized via DOMPurify during read/write
+  outerHTML: string; // Same as above
   appendChild(child: HTMLElement | string): void;
-  // Other HTMLElement methods passed through (not recommended)
+  // Other HTMLElement methods are passed through (direct use is not recommended)
 }
 ```
 
-## Security
+## Security Requirements
 
-**Recommended: do all rendering via `ctx.render()`.** Do not use `ctx.element`’s DOM APIs directly (e.g. `innerHTML`, `appendChild`, `querySelector`).
+**Recommended: All rendering should be performed via `ctx.render()`.** Avoid using the DOM APIs of `ctx.element` directly (e.g., `innerHTML`, `appendChild`, `querySelector`, etc.).
 
-### Why use ctx.render()
+### Why ctx.render() is Recommended
 
-| Benefit | Description |
-|---------|-------------|
-| **Security** | Centralized control, avoids XSS and unsafe DOM use |
-| **React** | Full JSX, components, and lifecycle |
-| **Context** | Inherits app ConfigProvider, theme, etc. |
-| **Conflicts** | Manages React root create/unmount, avoids multiple instances |
+| Advantage | Description |
+|------|------|
+| **Security** | Centralized security control to prevent XSS and improper DOM operations. |
+| **React Support** | Full support for JSX, React components, and lifecycles. |
+| **Context Inheritance** | Automatically inherits the application's `ConfigProvider`, themes, etc. |
+| **Conflict Handling** | Automatically manages React root creation/unmounting to avoid multi-instance conflicts. |
 
-### ❌ Not recommended: direct ctx.element use
+### ❌ Not Recommended: Direct Manipulation of ctx.element
 
 ```ts
+// ❌ Not recommended: Using ctx.element APIs directly
 ctx.element.innerHTML = '<div>Content</div>';
 ctx.element.appendChild(node);
 ctx.element.querySelector('.class');
 ```
 
-> `ctx.element.innerHTML` is deprecated; use `ctx.render()` instead.
+> `ctx.element.innerHTML` is deprecated. Please use `ctx.render()` instead.
 
-### ✅ Recommended: ctx.render()
+### ✅ Recommended: Using ctx.render()
 
 ```ts
+// ✅ Rendering a React component
 const { Button, Card } = ctx.libs.antd;
 ctx.render(
   <Card title={ctx.t('Welcome')}>
@@ -59,40 +62,43 @@ ctx.render(
   </Card>
 );
 
+// ✅ Rendering an HTML string
 ctx.render('<div style="padding:16px;">' + ctx.t('Content') + '</div>');
 
+// ✅ Rendering a DOM node
 const div = document.createElement('div');
 div.textContent = ctx.t('Hello');
 ctx.render(div);
 ```
 
-## Exception: popover anchor
+## Special Case: As a Popover Anchor
 
-When you need the current element as a popover anchor, use `ctx.element?.__el` as the native DOM `target`:
+When you need to open a Popover using the current element as an anchor, you can access `ctx.element?.__el` to get the raw DOM as the `target`:
 
 ```ts
+// ctx.viewer.popover requires a raw DOM as the target
 await ctx.viewer.popover({
   target: ctx.element?.__el,
-  content: <div>Popover content</div>,
+  content: <div>Popup Content</div>,
 });
 ```
 
-> Use `__el` only for this “current container as anchor” case; do not touch DOM otherwise.
+> Use `__el` only in scenarios like "using the current container as an anchor"; do not manipulate the DOM directly in other cases.
 
-## Relation to ctx.render
+## Relationship with ctx.render
 
-- `ctx.render(vnode)` without a `container` argument renders into `ctx.element`.
-- If there is no `ctx.element` and no `container`, an error is thrown.
-- You can pass a container: `ctx.render(vnode, customContainer)`.
+- If `ctx.render(vnode)` is called without a `container` argument, it renders into the `ctx.element` container by default.
+- If both `ctx.element` is missing and no `container` is provided, an error will be thrown.
+- You can explicitly specify a container: `ctx.render(vnode, customContainer)`.
 
 ## Notes
 
-- Treat `ctx.element` as the internal container for `ctx.render()`; avoid reading or mutating it directly.
-- In contexts without a render container, `ctx.element` is `undefined`; ensure a container exists or pass `container` to `ctx.render()`.
-- ElementProxy’s `innerHTML`/`outerHTML` are sanitized with DOMPurify, but prefer `ctx.render()` for all rendering.
+- `ctx.element` is intended for internal use by `ctx.render()`. Directly accessing or modifying its properties/methods is not recommended.
+- In contexts without a rendering container, `ctx.element` will be `undefined`. Ensure the container is available or pass a `container` manually before calling `ctx.render()`.
+- Although `innerHTML`/`outerHTML` in `ElementProxy` are sanitized via DOMPurify, it is still recommended to use `ctx.render()` for unified rendering management.
 
 ## Related
 
-- [ctx.render](./render.md): render into container
-- [ctx.view](./view.md): current view controller
-- [ctx.modal](./modal.md): modal APIs
+- [ctx.render](./render.md): Rendering content into a container
+- [ctx.view](./view.md): Current view controller
+- [ctx.modal](./modal.md): Shortcut API for modals

package/dist/ai/docs/runjs/context/exit-all.md

@@ -1,94 +1,96 @@
 # ctx.exitAll()
 
-Stops the current event flow and all **subsequent** event flows that were triggered in the same event dispatch. Use when a global error or permission check requires stopping every flow for that event.
+Terminates the current event flow and all subsequent event flows triggered in the same event dispatch. It is commonly used when all event flows under the current event need to be aborted immediately due to a global error or permission validation failure.
 
 ## Use Cases
 
-Use `ctx.exitAll()` in JS-capable contexts when you need to **stop both the current flow and any later flows for the same event**:
+`ctx.exitAll()` is generally used in JS-executable contexts where it is necessary to **simultaneously abort the current event flow and subsequent event flows triggered by that event**:
 
 | Scenario | Description |
-|----------|-------------|
-| **Event flow** | Main flow fails (e.g. no permission); stop it and any subsequent flows for that event |
-| **Linkage rules** | When linkage validation fails and you want to stop current and subsequent linkage |
-| **Action events** | Pre-action check fails (e.g. delete permission); block the action and later steps |
+|------|------|
+| **Event Flow** | Main event flow validation fails (e.g., insufficient permissions), requiring the termination of the main flow and any subsequent flows under the same event that have not yet executed. |
+| **Linkage Rules** | When linkage validation fails, the current linkage and subsequent linkages triggered by the same event must be terminated. |
+| **Action Events** | Pre-action validation fails (e.g., permission check before deletion), requiring the prevention of the main action and subsequent steps. |
 
-> Difference from `ctx.exit()`: `ctx.exit()` only stops the current flow; `ctx.exitAll()` also stops **subsequent** flows for that event.
+> Difference from `ctx.exit()`: `ctx.exit()` only terminates the current event flow; `ctx.exitAll()` terminates the current event flow and any **unexecuted** subsequent event flows in the same event dispatch.
 
-## Type
+## Type Definition
 
 ```ts
 exitAll(): never;
 ```
 
-Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which the engine uses to stop the current flow instance and subsequent flows for the same event. The rest of the current JS does not run.
+Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which is caught by the FlowEngine to stop the current event flow instance and subsequent event flows under the same event. Once called, the remaining statements in the current JS code will not be executed.
 
 ## Comparison with ctx.exit()
 
 | Method | Scope |
-|--------|--------|
-| `ctx.exit()` | Stops only the current flow; later flows still run |
-| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+|------|----------|
+| `ctx.exit()` | Only terminates the current event flow; subsequent event flows are unaffected. |
+| `ctx.exitAll()` | Terminates the current event flow and aborts subsequent event flows executed **sequentially** under the same event. |
 
-## Execution mode
+## Execution Mode
 
-- **Sequential**: flows for the same event run one after another; after any flow calls `ctx.exitAll()`, later flows do not run.
-- **Parallel**: flows run in parallel; one flow calling `ctx.exitAll()` does not stop other already-running flows.
+- **Sequential Execution**: Event flows under the same event are executed in order. After any event flow calls `ctx.exitAll()`, subsequent event flows will not execute.
+- **Parallel Execution**: Event flows under the same event are executed in parallel. Calling `ctx.exitAll()` in one event flow will not interrupt other concurrent event flows (as they are independent).
 
 ## Examples
 
-### Stop all flows on permission failure
+### Terminate all event flows when permission validation fails
 
 ```ts
+// Abort the main event flow and subsequent event flows when permissions are insufficient
 if (!hasPermission(ctx)) {
-  ctx.notification.error({ message: 'No permission' });
+  ctx.notification.error({ message: 'No operation permission' });
   ctx.exitAll();
 }
 ```
 
-### Stop on global pre-check failure
+### Terminate when global pre-validation fails
 
 ```ts
+// Example: If associated data is found to be non-deletable before deletion, prevent the main event flow and subsequent actions
 const canDelete = await checkDeletable(ctx.model?.getValue?.());
 if (!canDelete) {
-  ctx.message.error('Cannot delete: related data exists');
+  ctx.message.error('Cannot delete: associated data exists');
   ctx.exitAll();
 }
 ```
 
-### When to use ctx.exit() vs ctx.exitAll()
+### Choosing between ctx.exit() and ctx.exitAll()
 
 ```ts
-// Only this flow → ctx.exit()
+// Only the current event flow needs to exit -> Use ctx.exit()
 if (!params.valid) {
-  ctx.message.error('Invalid params');
-  ctx.exit();
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Subsequent event flows are unaffected
 }
 
-// This and all subsequent flows → ctx.exitAll()
+// Need to terminate all subsequent event flows under the current event -> Use ctx.exitAll()
 if (!ctx.model?.context?.getPermission?.()) {
-  ctx.notification.warning({ message: 'No permission' });
-  ctx.exitAll();
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the main event flow and subsequent event flows under the same event are terminated
 }
 ```
 
-### Message then exit
+### Prompt before terminating
 
 ```ts
 if (!isValidInput(ctx.form?.getValues?.())) {
-  ctx.message.warning('Please fix form errors first');
+  ctx.message.warning('Please correct the errors in the form first');
   ctx.exitAll();
 }
 ```
 
 ## Notes
 
-- After `ctx.exitAll()`, the rest of the current JS does not run; explain to the user with `ctx.message`, `ctx.notification`, or a dialog before calling.
-- You usually do not need to catch `FlowExitAllException`; the engine handles it.
-- To stop only the current flow, use `ctx.exit()`.
-- In parallel mode, `ctx.exitAll()` only stops the current flow; it does not cancel other concurrent flows.
+- After calling `ctx.exitAll()`, subsequent code in the current JS will not execute. It is recommended to explain the reason to the user via `ctx.message`, `ctx.notification`, or a modal before calling it.
+- Business code usually does not need to catch `FlowExitAllException`; let the FlowEngine handle it.
+- If you only need to stop the current event flow without affecting subsequent ones, use `ctx.exit()`.
+- In parallel mode, `ctx.exitAll()` only terminates the current event flow and does not interrupt other concurrent event flows.
 
 ## Related
 
-- [ctx.exit()](./exit.md): stop only the current flow
-- [ctx.message](./message.md): message API
-- [ctx.modal](./modal.md): confirm dialog
+- [ctx.exit()](./exit.md): Terminates only the current event flow
+- [ctx.message](./message.md): Message prompts
+- [ctx.modal](./modal.md): Confirmation modal

package/dist/ai/docs/runjs/context/exit.md

@@ -1,86 +1,89 @@
 # ctx.exit()
 
-Stops the current event flow; later steps in that flow do not run. Often used when business conditions fail, the user cancels, or an unrecoverable error occurs.
+Terminates the execution of the current event flow; subsequent steps will not run. It is commonly used when business conditions are not met, the user cancels, or an irrecoverable error occurs.
 
 ## Use Cases
 
-`ctx.exit()` is used in contexts that execute JS, such as:
+`ctx.exit()` is generally used in the following contexts where JS can be executed:
 
 | Scenario | Description |
-|----------|-------------|
-| **Event flow** | In flows triggered by form submit, button click, etc., stop when conditions are not met |
-| **Linkage rules** | Field or filter linkage; stop when validation fails or execution should be skipped |
-| **Action events** | In custom actions (e.g. delete confirm, pre-save validation), exit when user cancels or validation fails |
+|------|------|
+| **Event Flow** | In event flows triggered by form submissions, button clicks, etc., terminates subsequent steps when conditions are not met. |
+| **Linkage Rules** | In field linkages, filter linkages, etc., terminates the current event flow when validation fails or execution needs to be skipped. |
+| **Action Events** | In custom actions (e.g., delete confirmation, pre-save validation), exits when the user cancels or validation fails. |
 
-> Difference from `ctx.exitAll()`: `ctx.exit()` only stops the **current** event flow; other flows for the same event still run. `ctx.exitAll()` also stops **subsequent** flows for that event.
+> Difference from `ctx.exitAll()`: `ctx.exit()` only terminates the current event flow; other event flows under the same event are not affected. `ctx.exitAll()` terminates the current event flow as well as any subsequent event flows under the same event that have not yet been executed.
 
-## Type
+## Type Definition
 
 ```ts
 exit(): never;
 ```
 
-Calling `ctx.exit()` throws an internal `FlowExitException`, which the event flow engine catches and uses to stop the current flow. Once called, the rest of the current JS does not run.
+Calling `ctx.exit()` throws an internal `FlowExitException`, which is caught by the FlowEngine to stop the current event flow execution. Once called, the remaining statements in the current JS code will not execute.
 
 ## Comparison with ctx.exitAll()
 
-| Method | Scope |
-|--------|--------|
-| `ctx.exit()` | Stops only the current event flow; others unaffected |
-| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+| Method | Scope of Effect |
+|------|----------|
+| `ctx.exit()` | Terminates only the current event flow; subsequent event flows are unaffected. |
+| `ctx.exitAll()` | Terminates the current event flow and aborts subsequent event flows under the same event that are set to **execute sequentially**. |
 
 ## Examples
 
-### Exit on user cancel
+### Exit on User Cancellation
 
 ```ts
+// In a confirmation modal, terminate the event flow if the user clicks cancel
 if (!confirmed) {
-  ctx.message.info('Cancelled');
+  ctx.message.info('Operation cancelled');
   ctx.exit();
 }
 ```
 
-### Exit on validation failure
+### Exit on Parameter Validation Failure
 
 ```ts
+// Prompt and terminate when validation fails
 if (!params.value || params.value.length < 3) {
-  ctx.message.error('Invalid: length must be at least 3');
+  ctx.message.error('Invalid parameters, length must be at least 3');
   ctx.exit();
 }
 ```
 
-### Exit when business condition fails
+### Exit When Business Conditions Are Not Met
 
 ```ts
+// Terminate if conditions are not met; subsequent steps will not execute
 const record = ctx.model?.getValue?.();
 if (!record || record.status !== 'draft') {
-  ctx.notification.warning({ message: 'Only draft can be submitted' });
+  ctx.notification.warning({ message: 'Only drafts can be submitted' });
   ctx.exit();
 }
 ```
 
-### When to use ctx.exit() vs ctx.exitAll()
+### Choosing Between ctx.exit() and ctx.exitAll()
 
 ```ts
-// Only this flow should stop → ctx.exit()
+// Only the current event flow needs to exit → Use ctx.exit()
 if (!params.valid) {
-  ctx.message.error('Invalid params');
-  ctx.exit();
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Other event flows are unaffected
 }
 
-// Stop this and all subsequent flows for this event → ctx.exitAll()
+// Need to terminate all subsequent event flows under the current event → Use ctx.exitAll()
 if (!ctx.model?.context?.getPermission?.()) {
-  ctx.notification.warning({ message: 'No permission' });
-  ctx.exitAll();
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the current event flow and subsequent event flows under the same event are terminated
 }
 ```
 
-### Exit after modal confirm
+### Exit Based on User Choice After Modal Confirmation
 
 ```ts
 const ok = await ctx.modal?.confirm?.({
-  title: 'Confirm delete',
-  content: 'Cannot be recovered. Continue?',
+  title: 'Confirm Delete',
+  content: 'This action cannot be undone. Do you want to continue?',
 });
 if (!ok) {
   ctx.message.info('Cancelled');
@@ -90,12 +93,12 @@ if (!ok) {
 
 ## Notes
 
-- After `ctx.exit()`, the rest of the current JS does not run; use `ctx.message`, `ctx.notification`, or a dialog before calling to explain why.
-- You usually do not need to catch `FlowExitException`; the event flow engine handles it.
-- To stop all subsequent flows for the same event, use `ctx.exitAll()`.
+- After calling `ctx.exit()`, subsequent code in the current JS will not execute; it is recommended to explain the reason to the user via `ctx.message`, `ctx.notification`, or a modal before calling it.
+- There is usually no need to catch `FlowExitException` in business code; let the FlowEngine handle it.
+- If you need to terminate all subsequent event flows under the current event, use `ctx.exitAll()`.
 
 ## Related
 
-- [ctx.exitAll()](./exit-all.md): stop current and subsequent flows for the event
-- [ctx.message](./message.md): message API
-- [ctx.modal](./modal.md): confirm dialog
+- [ctx.exitAll()](./exit-all.md): Terminates the current event flow and subsequent event flows under the same event.
+- [ctx.message](./message.md): Message prompts.
+- [ctx.modal](./modal.md): Confirmation modals.