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

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

@@ -1,39 +1,39 @@
 # ctx.libs
 
-`ctx.libs` is the unified namespace for RunJS built-in libraries (React, Ant Design, dayjs, lodash, etc.). **No `import` or async loading**; use `ctx.libs.xxx` directly.
+`ctx.libs` is the unified namespace for built-in libraries in RunJS, containing commonly used libraries such as React, Ant Design, dayjs, and lodash. **No `import` or asynchronous loading is required**; they can be used directly via `ctx.libs.xxx`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField / JSItem / JSColumn** | React + Ant Design for UI, dayjs for dates, lodash for data |
-| **Formulas / calculations** | formula or math for Excel-like formulas and math expressions |
-| **Event flow / linkage** | lodash, dayjs, formula, etc. in logic-only code |
+|------|------|
+| **JSBlock / JSField / JSItem / JSColumn** | Use React + Ant Design to render UI, dayjs for date handling, and lodash for data processing. |
+| **Formula / Calculation** | Use formula or math for Excel-like formulas and mathematical expression operations. |
+| **Workflow / Linkage Rules** | Call utility libraries like lodash, dayjs, and formula in pure logic scenarios. |
 
-## Built-in libraries
+## Built-in Libraries Overview
 
-| Property | Description | Docs |
-|----------|-------------|------|
-| `ctx.libs.React` | React core for JSX and Hooks | [React](https://react.dev/) |
-| `ctx.libs.ReactDOM` | ReactDOM (e.g. `createRoot`) | [React DOM](https://react.dev/reference/react-dom) |
-| `ctx.libs.antd` | Ant Design (Button, Card, Table, Form, Input, Modal, etc.) | [Ant Design](https://ant.design/components/overview/) |
-| `ctx.libs.antdIcons` | Ant Design icons (PlusOutlined, UserOutlined, etc.) | [@ant-design/icons](https://ant.design/components/icon/) |
-| `ctx.libs.dayjs` | Date/time utilities | [dayjs](https://day.js.org/) |
-| `ctx.libs.lodash` | Utilities (get, set, debounce, etc.) | [Lodash](https://lodash.com/docs/) |
-| `ctx.libs.formula` | Excel-like formulas (SUM, AVERAGE, IF, etc.) | [Formula.js](https://formulajs.info/functions/) |
-| `ctx.libs.math` | Math expressions and evaluation | [Math.js](https://mathjs.org/docs/) |
+| Property | Description | Documentation |
+|------|------|------|
+| `ctx.libs.React` | React core, used for JSX and Hooks | [React](https://react.dev/) |
+| `ctx.libs.ReactDOM` | ReactDOM client API (including `createRoot`), used with React for rendering | [React DOM](https://react.dev/reference/react-dom) |
+| `ctx.libs.antd` | Ant Design component library (Button, Card, Table, Form, Input, Modal, etc.) | [Ant Design](https://ant.design/components/overview/) |
+| `ctx.libs.antdIcons` | Ant Design icon library (e.g., PlusOutlined, UserOutlined) | [@ant-design/icons](https://ant.design/components/icon/) |
+| `ctx.libs.dayjs` | Date and time utility library | [dayjs](https://day.js.org/) |
+| `ctx.libs.lodash` | Utility library (get, set, debounce, etc.) | [Lodash](https://lodash.com/docs/) |
+| `ctx.libs.formula` | Excel-like formula function library (SUM, AVERAGE, IF, etc.) | [Formula.js](https://formulajs.info/functions/) |
+| `ctx.libs.math` | Mathematical expression and calculation library | [Math.js](https://mathjs.org/docs/) |
 
-## Top-level aliases
+## Top-level Aliases
 
-For backward compatibility, some libs are also on `ctx`: `ctx.React`, `ctx.ReactDOM`, `ctx.antd`, `ctx.dayjs`. **Prefer `ctx.libs.xxx`** for consistency and docs.
+For compatibility with legacy code, some libraries are also exposed at the top level: `ctx.React`, `ctx.ReactDOM`, `ctx.antd`, and `ctx.dayjs`. **It is recommended to consistently use `ctx.libs.xxx`** for easier maintenance and documentation searching.
 
-## Lazy loading
+## Lazy Loading
 
-`lodash`, `formula`, `math` are **lazy-loaded**: the first access to `ctx.libs.lodash` triggers a dynamic import, then the result is cached. `React`, `antd`, `dayjs`, `antdIcons` are preloaded in context.
+`lodash`, `formula`, and `math` use **lazy loading**: a dynamic import is triggered only when `ctx.libs.lodash` is accessed for the first time, and the cache is reused thereafter. `React`, `antd`, `dayjs`, and `antdIcons` are pre-configured by the context and are available immediately.
 
 ## Examples
 
-### React and Ant Design
+### Rendering with React and Ant Design
 
 ```tsx
 const { Button, Card } = ctx.libs.antd;
@@ -45,7 +45,7 @@ ctx.render(
 );
 ```
 
-### Hooks
+### Using Hooks
 
 ```tsx
 const { React } = ctx.libs;
@@ -59,7 +59,7 @@ const App = () => {
 ctx.render(<App />);
 ```
 
-### Icons
+### Using Icons
 
 ```tsx
 const { Button } = ctx.libs.antd;
@@ -68,7 +68,7 @@ const { UserOutlined, HeartOutlined } = ctx.libs.antdIcons;
 ctx.render(<Button icon={<UserOutlined />}>User</Button>);
 ```
 
-### dayjs
+### Date Processing with dayjs
 
 ```ts
 const now = ctx.libs.dayjs();
@@ -76,14 +76,14 @@ const formatted = now.format('YYYY-MM-DD HH:mm:ss');
 ctx.message.info(formatted);
 ```
 
-### lodash
+### Utility Functions with lodash
 
 ```ts
 const user = { profile: { name: 'Alice' } };
 const name = ctx.libs.lodash.get(user, 'profile.name', 'Unknown');
 ```
 
-### formula
+### Formula Calculations
 
 ```ts
 const values = [1, 2, 3, 4];
@@ -91,7 +91,7 @@ const sum = ctx.libs.formula.SUM(values);
 const avg = ctx.libs.formula.AVERAGE(values);
 ```
 
-### math
+### Mathematical Expressions with math.js
 
 ```ts
 const result = ctx.libs.math.evaluate('2 + 3 * 4');
@@ -100,10 +100,10 @@ const result = ctx.libs.math.evaluate('2 + 3 * 4');
 
 ## Notes
 
-- **Mixing with ctx.importAsync**: If you load external React via `ctx.importAsync('react@19')`, JSX uses that instance; **do not** mix with `ctx.libs.antd`. Load antd for that React version (e.g. `ctx.importAsync('antd@5.x')`, `ctx.importAsync('@ant-design/icons@5.x')`).
-- **Multiple React instances**: "Invalid hook call" or null hook dispatcher usually means multiple React instances. Before using `ctx.libs.React` or Hooks, run `await ctx.importAsync('react@version')` so the same React as the page is used.
+- **Mixing with ctx.importAsync**: If an external React is loaded via `ctx.importAsync('react@19')`, JSX will use that instance. In this case, **do not** mix it with `ctx.libs.antd`. Ant Design must be loaded to match that React version (e.g., `ctx.importAsync('antd@5.x')`, `ctx.importAsync('@ant-design/icons@5.x')`).
+- **Multiple React Instances**: If "Invalid hook call" occurs or the hook dispatcher is null, it is usually caused by multiple React instances. Before reading `ctx.libs.React` or calling Hooks, execute `await ctx.importAsync('react@version')` first to ensure the same React instance is shared with the page.
 
 ## Related
 
-- [ctx.importAsync()](./import-async.md): load external ESM (e.g. specific React, Vue)
-- [ctx.render()](./render.md): render into container
+- [ctx.importAsync()](./import-async.md) - Load external ESM modules on demand (e.g., specific versions of React, Vue)
+- [ctx.render()](./render.md) - Render content to a container

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

@@ -1,85 +1,88 @@
 # ctx.location
 
-Current route location, equivalent to React Router’s `location`. Use with `ctx.router` and `ctx.route` to read pathname, search, hash, and state passed via navigation.
+Current route location information, equivalent to the React Router `location` object. It is typically used in conjunction with `ctx.router` and `ctx.route` to read the current path, query string, hash, and state passed through the route.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField** | Conditional render or logic based on path, query, or hash |
-| **Linkage / event flow** | Read URL params for filtering or use `location.state` for source |
-| **After navigation** | On target page, read `ctx.location.state` from `ctx.router.navigate` |
+|------|------|
+| **JSBlock / JSField** | Perform conditional rendering or logic branching based on the current path, query parameters, or hash. |
+| **Linkage Rules / FlowEngine** | Read URL query parameters for linkage filtering, or determine the source based on `location.state`. |
+| **Post-navigation processing** | Receive data passed from the previous page via `ctx.router.navigate` using `ctx.location.state` on the target page. |
 
-> Note: `ctx.location` is only available in RunJS when a router context exists (e.g. JSBlock on a page, event flow); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
+> Note: `ctx.location` is only available in RunJS environments with a routing context (e.g., JSBlock within a page, FlowEngine, etc.); it may be null in pure backend or non-routing contexts (e.g., Workflows).
 
-## Type
+## Type Definition
 
 ```ts
 location: Location;
 ```
 
-`Location` is from `react-router-dom`, same as `useLocation()`.
+`Location` comes from `react-router-dom`, consistent with the return value of React Router's `useLocation()`.
 
 ## Common Fields
 
 | Field | Type | Description |
-|-------|------|-------------|
-| `pathname` | `string` | Current path, leading `/` (e.g. `/admin/users`) |
-| `search` | `string` | Query string, leading `?` (e.g. `?page=1&status=active`) |
-| `hash` | `string` | Hash fragment, leading `#` (e.g. `#section-1`) |
-| `state` | `any` | Data passed via `ctx.router.navigate(path, { state })`; not in URL |
-| `key` | `string` | Unique key for this location; initial page is `"default"` |
+|------|------|------|
+| `pathname` | `string` | The current path, starting with `/` (e.g., `/admin/users`). |
+| `search` | `string` | The query string, starting with `?` (e.g., `?page=1&status=active`). |
+| `hash` | `string` | The hash fragment, starting with `#` (e.g., `#section-1`). |
+| `state` | `any` | Arbitrary data passed via `ctx.router.navigate(path, { state })`, not reflected in the URL. |
+| `key` | `string` | A unique identifier for this location; the initial page is `"default"`. |
 
-## Relation to ctx.router, ctx.urlSearchParams
+## Relationship with ctx.router and ctx.urlSearchParams
 
-| Use | Recommended |
-|-----|-------------|
-| **Path, hash, state** | `ctx.location.pathname` / `ctx.location.hash` / `ctx.location.state` |
-| **Query params as object** | `ctx.urlSearchParams` |
-| **Parse search** | `new URLSearchParams(ctx.location.search)` or `ctx.urlSearchParams` |
+| Purpose | Recommended Usage |
+|------|----------|
+| **Read path, hash, state** | `ctx.location.pathname` / `ctx.location.hash` / `ctx.location.state` |
+| **Read query parameters (as object)** | `ctx.urlSearchParams`, which provides the parsed object directly. |
+| **Parse search string** | `new URLSearchParams(ctx.location.search)` or use `ctx.urlSearchParams` directly. |
 
-`ctx.urlSearchParams` is derived from `ctx.location.search`; use it when you only need query params.
+`ctx.urlSearchParams` is parsed from `ctx.location.search`. If you only need query parameters, using `ctx.urlSearchParams` is more convenient.
 
 ## Examples
 
-### Branch by path
+### Branching Based on Path
 
 ```ts
 if (ctx.location.pathname.startsWith('/admin/users')) {
-  ctx.message.info('On user management page');
+  ctx.message.info('Currently on the user management page');
 }
 ```
 
-### Parse query params
+### Parsing Query Parameters
 
 ```ts
+// Method 1: Using ctx.urlSearchParams (Recommended)
 const page = ctx.urlSearchParams.page || 1;
 const status = ctx.urlSearchParams.status;
 
+// Method 2: Using URLSearchParams to parse search
 const params = new URLSearchParams(ctx.location.search);
 const page = params.get('page') || '1';
 const status = params.get('status');
 ```
 
-### Read state from navigation
+### Receiving State Passed via Route Navigation
 
 ```ts
+// When navigating from the previous page: ctx.router.navigate('/users/123', { state: { from: 'dashboard' } })
 const prevState = ctx.location.state;
 if (prevState?.from === 'dashboard') {
-  ctx.message.info('Navigated from dashboard');
+  ctx.message.info('Navigated from the dashboard');
 }
 ```
 
-### Anchor by hash
+### Locating Anchors via Hash
 
 ```ts
-const hash = ctx.location.hash;
+const hash = ctx.location.hash; // e.g., "#edit"
 if (hash === '#edit') {
-  // Scroll to edit or run logic
+  // Scroll to the edit area or execute corresponding logic
 }
 ```
 
 ## Related
 
-- [ctx.router](./router.md): navigation; `state` from `ctx.router.navigate` is available as `ctx.location.state`
-- [ctx.route](./route.md): current route match (params, config); use with `ctx.location`
+- [ctx.router](./router.md): Route navigation; the `state` from `ctx.router.navigate` can be retrieved via `ctx.location.state` on the target page.
+- [ctx.route](./route.md): Current route match information (parameters, configuration, etc.), often used in conjunction with `ctx.location`.

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

@@ -1,84 +1,85 @@
 # ctx.logger
 
-Logging built on [pino](https://github.com/pinojs/pino); outputs structured JSON. Prefer `ctx.logger` over `console` for collection and analysis.
+A logging wrapper based on [pino](https://github.com/pinojs/pino), providing high-performance structured JSON logs. It is recommended to use `ctx.logger` instead of `console` for easier log collection and analysis.
 
-## Use Cases
+## Scenarios
 
-Available in all RunJS contexts for debugging, error tracking, and performance.
+`ctx.logger` can be used in all RunJS scenarios for debugging, error tracking, performance analysis, etc.
 
-## Type
+## Type Definition
 
 ```ts
 logger: pino.Logger;
 ```
 
-`ctx.logger` is `engine.logger.child({ module: 'flow-engine' })`, i.e. a pino child logger with a `module` context.
+`ctx.logger` is an instance of `engine.logger.child({ module: 'flow-engine' })`, which is a pino child logger with a `module` context.
 
-## Log levels
+## Log Levels
 
-From highest to lowest:
+pino supports the following levels (from highest to lowest):
 
 | Level | Method | Description |
-|-------|--------|-------------|
-| `fatal` | `ctx.logger.fatal()` | Fatal; usually process exit |
-| `error` | `ctx.logger.error()` | Error; request or operation failed |
-| `warn` | `ctx.logger.warn()` | Warning; potential issue |
-| `info` | `ctx.logger.info()` | General runtime info |
-| `debug` | `ctx.logger.debug()` | Debug; development |
-| `trace` | `ctx.logger.trace()` | Verbose; deep diagnosis |
+|------|------|------|
+| `fatal` | `ctx.logger.fatal()` | Fatal error, usually leading to process exit |
+| `error` | `ctx.logger.error()` | Error, indicating a failed request or operation |
+| `warn` | `ctx.logger.warn()` | Warning, indicating potential risks or abnormal situations |
+| `info` | `ctx.logger.info()` | General runtime information |
+| `debug` | `ctx.logger.debug()` | Debugging information, used during development |
+| `trace` | `ctx.logger.trace()` | Detailed trace, used for deep diagnostics |
 
-## Recommended usage
+## Recommended Usage
 
-Use `level(msg, meta)`: message first, optional metadata object second.
+The recommended format is `level(msg, meta)`: the message comes first, followed by an optional metadata object.
 
 ```ts
-ctx.logger.info('Block loaded');
-ctx.logger.info('Success', { recordId: 456 });
-ctx.logger.warn('Slow', { duration: 5000 });
-ctx.logger.error('Failed', { userId: 123, action: 'create' });
+ctx.logger.info('Block loading complete');
+ctx.logger.info('Operation successful', { recordId: 456 });
+ctx.logger.warn('Performance warning', { duration: 5000 });
+ctx.logger.error('Operation failed', { userId: 123, action: 'create' });
 ctx.logger.error('Request failed', { err });
 ```
 
-pino also supports `level(meta, msg)` or `level({ msg, ...meta })` if needed.
+pino also supports `level(meta, msg)` (object first) or `level({ msg, ...meta })` (single object), which can be used as needed.
 
 ## Examples
 
-### Basic
+### Basic Usage
 
 ```ts
-ctx.logger.info('Block loaded');
+ctx.logger.info('Block loading complete');
 ctx.logger.warn('Request failed, using cache', { err });
-ctx.logger.debug('Saving', { recordId: ctx.record?.id });
+ctx.logger.debug('Saving...', { recordId: ctx.record?.id });
 ```
 
-### Child logger
+### Creating a Child Logger with child()
 
 ```ts
+// Create a child logger with context for the current logic
 const log = ctx.logger.child({ scope: 'myBlock' });
-log.info('Step 1');
-log.debug('Step 2', { step: 2 });
+log.info('Executing step 1');
+log.debug('Executing step 2', { step: 2 });
 ```
 
-### vs console
+### Relationship with console
 
-Prefer `ctx.logger` for structured JSON. Rough mapping: `console.log` → `ctx.logger.info`, `console.error` → `ctx.logger.error`, `console.warn` → `ctx.logger.warn`.
+It is recommended to use `ctx.logger` directly to obtain structured JSON logs. If you are accustomed to using `console`, the mappings are: `console.log` → `ctx.logger.info`, `console.error` → `ctx.logger.error`, `console.warn` → `ctx.logger.warn`.
 
-## Output format
+## Log Format
 
-pino outputs JSON with:
+pino outputs structured JSON, where each log entry contains:
 
-- `level`: numeric level
-- `time`: timestamp (ms)
-- `msg`: message
-- `module`: `flow-engine`
-- Any custom fields passed in the object
+- `level`: Log level (numeric)
+- `time`: Timestamp (milliseconds)
+- `msg`: Log message
+- `module`: Fixed as `flow-engine`
+- Other custom fields (passed via objects)
 
 ## Notes
 
-- Logs are JSON for easy collection and querying
-- Child loggers from `child()` also work well with `level(msg, meta)`
-- Some environments (e.g. workflow) may use different log handling
+- Logs are structured JSON, making them easy to collect, search, and analyze.
+- Child loggers created via `child()` also follow the `level(msg, meta)` recommendation.
+- Some runtime environments (such as Workflows) may use different log output methods.
 
 ## Related
 
-- [pino](https://github.com/pinojs/pino)
+- [pino](https://github.com/pinojs/pino) — The underlying logging library

package/dist/ai/docs/runjs/context/make-resource.md

@@ -1,18 +1,18 @@
 # ctx.makeResource()
 
-**Creates** a new resource instance and returns it; **does not** set or change `ctx.resource`. Use when you need multiple resources or a temporary one.
+**Creates** and returns a new resource instance **without** writing to or modifying `ctx.resource`. It is suitable for scenarios requiring multiple independent resources or temporary usage.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Multiple resources** | Load several data sources (e.g. users + orders), each with its own resource |
-| **One-off query** | Single query, no need to bind to `ctx.resource` |
-| **Auxiliary data** | Main data in `ctx.resource`, extra data from a `makeResource` instance |
+|------|------|
+| **Multiple resources** | Load multiple data sources simultaneously (e.g., user list + order list), each using an independent resource. |
+| **Temporary queries** | One-time queries that are discarded after use, without needing to bind to `ctx.resource`. |
+| **Auxiliary data** | Use `ctx.resource` for primary data and `makeResource` to create instances for additional data. |
 
-If you only need one resource and want it on `ctx.resource`, use [ctx.initResource()](./init-resource.md).
+If you only need a single resource and want to bind it to `ctx.resource`, using [ctx.initResource()](./init-resource.md) is more appropriate.
 
-## Type
+## Type Definition
 
 ```ts
 makeResource<T = FlowResource>(
@@ -21,17 +21,17 @@ makeResource<T = FlowResource>(
 ```
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `resourceType` | `string` | `'APIResource'`, `'SingleRecordResource'`, `'MultiRecordResource'`, `'SQLResource'` |
+|------|------|------|
+| `resourceType` | `string` | Resource type: `'APIResource'`, `'SingleRecordResource'`, `'MultiRecordResource'`, `'SQLResource'` |
 
-**Returns**: The new resource instance.
+**Returns**: The newly created resource instance.
 
-## Relation to ctx.initResource()
+## Difference from ctx.initResource()
 
 | Method | Behavior |
-|--------|----------|
-| `ctx.makeResource(type)` | Creates and returns; **does not** set `ctx.resource`; can call multiple times for multiple resources |
-| `ctx.initResource(type)` | Creates and binds if missing; otherwise returns existing. Ensures `ctx.resource` is set |
+|------|------|
+| `ctx.makeResource(type)` | Only creates and returns a new instance, **not** writing to `ctx.resource`. Can be called multiple times to obtain multiple independent resources. |
+| `ctx.initResource(type)` | Creates and binds if `ctx.resource` does not exist; returns it directly if it already exists. Ensures `ctx.resource` is available. |
 
 ## Examples
 
@@ -42,7 +42,7 @@ const listRes = ctx.makeResource('MultiRecordResource');
 listRes.setResourceName('users');
 await listRes.refresh();
 const users = listRes.getData();
-// ctx.resource unchanged (if it existed)
+// ctx.resource remains its original value (if any)
 ```
 
 ### Multiple resources
@@ -58,15 +58,16 @@ await ordersRes.refresh();
 
 ctx.render(
   <div>
-    <p>Users: {usersRes.getData().length}</p>
-    <p>Orders: {ordersRes.getData().length}</p>
+    <p>User count: {usersRes.getData().length}</p>
+    <p>Order count: {ordersRes.getData().length}</p>
   </div>
 );
 ```
 
-### One-off query
+### Temporary query
 
 ```ts
+// One-time query, does not pollute ctx.resource
 const tempRes = ctx.makeResource('SingleRecordResource');
 tempRes.setResourceName('users');
 tempRes.setFilterByTk(1);
@@ -76,14 +77,14 @@ const record = tempRes.getData();
 
 ## Notes
 
-- Call `setResourceName(name)` then `refresh()` to load data.
-- Each instance is independent; good for loading several sources in parallel.
+- The newly created resource needs to call `setResourceName(name)` to specify the collection, and then load data via `refresh()`.
+- Each resource instance is independent and does not affect others; suitable for loading multiple data sources in parallel.
 
 ## Related
 
-- [ctx.initResource()](./init-resource.md): init and bind to `ctx.resource`
-- [ctx.resource](./resource.md): current context resource
-- [MultiRecordResource](../resource/multi-record-resource.md)
-- [SingleRecordResource](../resource/single-record-resource.md)
-- [APIResource](../resource/api-resource.md)
-- [SQLResource](../resource/sql-resource.md)
+- [ctx.initResource()](./init-resource.md): Initialize and bind to `ctx.resource`
+- [ctx.resource](./resource.md): The resource instance in the current context
+- [MultiRecordResource](../resource/multi-record-resource) — Multiple records/List
+- [SingleRecordResource](../resource/single-record-resource) — Single record
+- [APIResource](../resource/api-resource) — General API resource
+- [SQLResource](../resource/sql-resource) — SQL query resource

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

@@ -1,63 +1,63 @@
 # ctx.message
 
-Ant Design global message API; shows short messages at the top center. Messages auto-close after a while or can be closed by the user.
+Ant Design global message API, used to display temporary light prompts at the top center of the page. Messages close automatically after a certain period or can be closed manually by the user.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField / JSItem / JSColumn** | Quick feedback: validation, copy success, etc. |
-| **Form actions / event flow** | Submit success, save failed, validation failed |
-| **JSAction** | Click or batch action feedback |
+|------|------|
+| **JSBlock / JSField / JSItem / JSColumn** | Operation feedback, validation prompts, copy success, and other light prompts |
+| **Form Operations / Workflow** | Feedback for submission success, save failure, validation failure, etc. |
+| **Action Events (JSAction)** | Immediate feedback for clicks, batch operation completion, etc. |
 
-## Type
+## Type Definition
 
 ```ts
 message: MessageInstance;
 ```
 
-`MessageInstance` is the Ant Design message API.
+`MessageInstance` is the Ant Design message interface, providing the following methods.
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `success(content, duration?)` | Success message |
-| `error(content, duration?)` | Error message |
-| `warning(content, duration?)` | Warning message |
-| `info(content, duration?)` | Info message |
-| `loading(content, duration?)` | Loading (usually closed manually) |
-| `open(config)` | Open with custom config |
-| `destroy()` | Close all messages |
+|------|------|
+| `success(content, duration?)` | Display a success prompt |
+| `error(content, duration?)` | Display an error prompt |
+| `warning(content, duration?)` | Display a warning prompt |
+| `info(content, duration?)` | Display an information prompt |
+| `loading(content, duration?)` | Display a loading prompt (must be closed manually) |
+| `open(config)` | Open a message using custom configuration |
+| `destroy()` | Close all currently displayed messages |
 
 **Parameters:**
 
-- `content`: `string` or `ConfigOptions`
-- `duration`: optional seconds; default 3; 0 = no auto-close
+- `content` (`string` | `ConfigOptions`): Message content or configuration object
+- `duration` (`number`, optional): Auto-close delay (seconds), default is 3 seconds; set to 0 to disable auto-close
 
-**ConfigOptions** (when content is an object):
+**ConfigOptions** (when `content` is an object):
 
 ```ts
 interface ConfigOptions {
-  content: React.ReactNode;
-  duration?: number;
-  onClose?: () => void;
-  icon?: React.ReactNode;
+  content: React.ReactNode;  // Message content
+  duration?: number;        // Auto-close delay (seconds)
+  onClose?: () => void;    // Callback when closed
+  icon?: React.ReactNode;  // Custom icon
 }
 ```
 
 ## Examples
 
-### Basic
+### Basic Usage
 
 ```ts
-ctx.message.success('Done');
-ctx.message.error('Failed');
+ctx.message.success('Operation successful');
+ctx.message.error('Operation failed');
 ctx.message.warning('Please select data first');
 ctx.message.info('Processing...');
 ```
 
-### With ctx.t (i18n)
+### Internationalization with ctx.t
 
 ```ts
 ctx.message.success(ctx.t('Copied'));
@@ -65,42 +65,43 @@ ctx.message.warning(ctx.t('Please select at least one row'));
 ctx.message.success(ctx.t('Exported {{count}} records', { count: rows.length }));
 ```
 
-### Loading and manual close
+### Loading and Manual Close
 
 ```ts
 const hide = ctx.message.loading(ctx.t('Saving...'));
+// Execute asynchronous operation
 await saveData();
-hide();
+hide();  // Manually close loading
 ctx.message.success(ctx.t('Saved'));
 ```
 
-### open with config
+### Custom Configuration with open
 
 ```ts
 ctx.message.open({
   type: 'success',
-  content: 'Custom success',
+  content: 'Custom success prompt',
   duration: 5,
-  onClose: () => console.log('closed'),
+  onClose: () => console.log('message closed'),
 });
 ```
 
-### Close all
+### Close All Messages
 
 ```ts
 ctx.message.destroy();
 ```
 
-## ctx.message vs ctx.notification
+## Difference Between ctx.message and ctx.notification
 
-| | ctx.message | ctx.notification |
-|---|-------------|-------------------|
-| **Position** | Top center | Top right |
-| **Use** | Short, auto-dismiss | Panel with title/description; can stay longer |
-| **Typical** | Action feedback, validation, copy | Task done, system notice, longer content |
+| Feature | ctx.message | ctx.notification |
+|------|--------------|------------------|
+| **Position** | Top center of the page | Top right corner |
+| **Purpose** | Temporary light prompt, disappears automatically | Notification panel, can include title and description, suitable for longer display |
+| **Typical Scenarios** | Operation feedback, validation prompts, copy success | Task completion notifications, system messages, longer content requiring user attention |
 
 ## Related
 
-- [ctx.notification](./notification.md): top-right notifications
-- [ctx.modal](./modal.md): modal confirm
-- [ctx.t()](./t.md): i18n; often used with message
+- [ctx.notification](./notification.md) - Top-right notifications, suitable for longer display durations
+- [ctx.modal](./modal.md) - Modal confirmation, blocking interaction
+- [ctx.t()](./t.md) - Internationalization, commonly used with message