@nocobase/plugin-flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.10

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

@@ -0,0 +1,88 @@
+# ctx.location
+
+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** | 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 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 Definition
+
+```ts
+location: Location;
+```
+
+`Location` comes from `react-router-dom`, consistent with the return value of React Router's `useLocation()`.
+
+## Common Fields
+
+| Field | Type | Description |
+|------|------|------|
+| `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"`. |
+
+## Relationship with ctx.router and 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 parsed from `ctx.location.search`. If you only need query parameters, using `ctx.urlSearchParams` is more convenient.
+
+## Examples
+
+### Branching Based on Path
+
+```ts
+if (ctx.location.pathname.startsWith('/admin/users')) {
+  ctx.message.info('Currently on the user management page');
+}
+```
+
+### 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');
+```
+
+### 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 the dashboard');
+}
+```
+
+### Locating Anchors via Hash
+
+```ts
+const hash = ctx.location.hash; // e.g., "#edit"
+if (hash === '#edit') {
+  // Scroll to the edit area or execute corresponding logic
+}
+```
+
+## Related
+
+- [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

@@ -0,0 +1,85 @@
+# ctx.logger
+
+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.
+
+## Scenarios
+
+`ctx.logger` can be used in all RunJS scenarios for debugging, error tracking, performance analysis, etc.
+
+## Type Definition
+
+```ts
+logger: pino.Logger;
+```
+
+`ctx.logger` is an instance of `engine.logger.child({ module: 'flow-engine' })`, which is a pino child logger with a `module` context.
+
+## Log Levels
+
+pino supports the following levels (from highest to lowest):
+
+| Level | Method | Description |
+|------|------|------|
+| `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
+
+The recommended format is `level(msg, meta)`: the message comes first, followed by an optional metadata object.
+
+```ts
+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)` (object first) or `level({ msg, ...meta })` (single object), which can be used as needed.
+
+## Examples
+
+### Basic Usage
+
+```ts
+ctx.logger.info('Block loading complete');
+ctx.logger.warn('Request failed, using cache', { err });
+ctx.logger.debug('Saving...', { recordId: ctx.record?.id });
+```
+
+### 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('Executing step 1');
+log.debug('Executing step 2', { step: 2 });
+```
+
+### Relationship with console
+
+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`.
+
+## Log Format
+
+pino outputs structured JSON, where each log entry contains:
+
+- `level`: Log level (numeric)
+- `time`: Timestamp (milliseconds)
+- `msg`: Log message
+- `module`: Fixed as `flow-engine`
+- Other custom fields (passed via objects)
+
+## Notes
+
+- 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) — The underlying logging library

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

@@ -0,0 +1,90 @@
+# ctx.makeResource()
+
+**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 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 a single resource and want to bind it to `ctx.resource`, using [ctx.initResource()](./init-resource.md) is more appropriate.
+
+## Type Definition
+
+```ts
+makeResource<T = FlowResource>(
+  resourceType: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource'
+): T;
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `resourceType` | `string` | Resource type: `'APIResource'`, `'SingleRecordResource'`, `'MultiRecordResource'`, `'SQLResource'` |
+
+**Returns**: The newly created resource instance.
+
+## Difference from ctx.initResource()
+
+| Method | Behavior |
+|------|------|
+| `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
+
+### Single resource
+
+```ts
+const listRes = ctx.makeResource('MultiRecordResource');
+listRes.setResourceName('users');
+await listRes.refresh();
+const users = listRes.getData();
+// ctx.resource remains its original value (if any)
+```
+
+### Multiple resources
+
+```ts
+const usersRes = ctx.makeResource('MultiRecordResource');
+usersRes.setResourceName('users');
+await usersRes.refresh();
+
+const ordersRes = ctx.makeResource('MultiRecordResource');
+ordersRes.setResourceName('orders');
+await ordersRes.refresh();
+
+ctx.render(
+  <div>
+    <p>User count: {usersRes.getData().length}</p>
+    <p>Order count: {ordersRes.getData().length}</p>
+  </div>
+);
+```
+
+### Temporary query
+
+```ts
+// One-time query, does not pollute ctx.resource
+const tempRes = ctx.makeResource('SingleRecordResource');
+tempRes.setResourceName('users');
+tempRes.setFilterByTk(1);
+await tempRes.refresh();
+const record = tempRes.getData();
+```
+
+## Notes
+
+- 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): 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

@@ -0,0 +1,107 @@
+# ctx.message
+
+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** | 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 Definition
+
+```ts
+message: MessageInstance;
+```
+
+`MessageInstance` is the Ant Design message interface, providing the following methods.
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `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` | `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):
+
+```ts
+interface ConfigOptions {
+  content: React.ReactNode;  // Message content
+  duration?: number;        // Auto-close delay (seconds)
+  onClose?: () => void;    // Callback when closed
+  icon?: React.ReactNode;  // Custom icon
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```ts
+ctx.message.success('Operation successful');
+ctx.message.error('Operation failed');
+ctx.message.warning('Please select data first');
+ctx.message.info('Processing...');
+```
+
+### Internationalization with ctx.t
+
+```ts
+ctx.message.success(ctx.t('Copied'));
+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
+
+```ts
+const hide = ctx.message.loading(ctx.t('Saving...'));
+// Execute asynchronous operation
+await saveData();
+hide();  // Manually close loading
+ctx.message.success(ctx.t('Saved'));
+```
+
+### Custom Configuration with open
+
+```ts
+ctx.message.open({
+  type: 'success',
+  content: 'Custom success prompt',
+  duration: 5,
+  onClose: () => console.log('message closed'),
+});
+```
+
+### Close All Messages
+
+```ts
+ctx.message.destroy();
+```
+
+## Difference Between ctx.message and ctx.notification
+
+| 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, suitable for longer display durations
+- [ctx.modal](./modal.md) - Modal confirmation, blocking interaction
+- [ctx.t()](./t.md) - Internationalization, commonly used with message

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

@@ -0,0 +1,115 @@
+# ctx.modal
+
+A shortcut API based on Ant Design Modal, used to actively open modal boxes (information prompts, confirmation pop-ups, etc.) in RunJS. It is implemented by `ctx.viewer` / the view system.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSField** | Display operation results, error prompts, or secondary confirmations after user interaction. |
+| **Workflow / Action Events** | Pop-up confirmation before submission; terminate subsequent steps via `ctx.exit()` if the user cancels. |
+| **Linkage Rules** | Pop-up prompts for the user when validation fails. |
+
+> Note: `ctx.modal` is available in RunJS environments with a view context (such as JSBlocks within a page, workflows, etc.); it may not exist in the backend or non-UI contexts. It is recommended to use optional chaining (`ctx.modal?.confirm?.()`) when calling it.
+
+## Type Definition
+
+```ts
+modal: {
+  info: (config: ModalConfig) => Promise<void>;
+  success: (config: ModalConfig) => Promise<void>;
+  error: (config: ModalConfig) => Promise<void>;
+  warning: (config: ModalConfig) => Promise<void>;
+  confirm: (config: ModalConfig) => Promise<boolean>;  // Returns true if the user clicks OK, false if they cancel
+};
+```
+
+`ModalConfig` is consistent with the configuration of Ant Design `Modal` static methods.
+
+## Common Methods
+
+| Method | Return Value | Description |
+|------|--------|------|
+| `info(config)` | `Promise<void>` | Information prompt modal |
+| `success(config)` | `Promise<void>` | Success prompt modal |
+| `error(config)` | `Promise<void>` | Error prompt modal |
+| `warning(config)` | `Promise<void>` | Warning prompt modal |
+| `confirm(config)` | `Promise<boolean>` | Confirmation modal; returns `true` if the user clicks OK, and `false` if they cancel |
+
+## Configuration Parameters
+
+Consistent with Ant Design `Modal`, common fields include:
+
+| Parameter | Type | Description |
+|------|------|------|
+| `title` | `ReactNode` | Title |
+| `content` | `ReactNode` | Content |
+| `okText` | `string` | OK button text |
+| `cancelText` | `string` | Cancel button text (only for `confirm`) |
+| `onOk` | `() => void \| Promise<void>` | Executed when clicking OK |
+| `onCancel` | `() => void` | Executed when clicking Cancel |
+
+## Relationship with ctx.message and ctx.openView
+
+| Purpose | Recommended Usage |
+|------|----------|
+| **Lightweight temporary prompt** | `ctx.message`, disappears automatically |
+| **Info/Success/Error/Warning modal** | `ctx.modal.info` / `success` / `error` / `warning` |
+| **Secondary confirmation (requires user choice)** | `ctx.modal.confirm`, used with `ctx.exit()` to control the flow |
+| **Complex interactions like forms or lists** | `ctx.openView` to open a custom view (page/drawer/modal) |
+
+## Examples
+
+### Simple Information Modal
+
+```ts
+ctx.modal.info({
+  title: 'Prompt',
+  content: 'Operation completed',
+});
+```
+
+### Confirmation Modal and Flow Control
+
+```ts
+const confirmed = await ctx.modal.confirm({
+  title: 'Confirm Delete',
+  content: 'Are you sure you want to delete this record?',
+  okText: 'Confirm',
+  cancelText: 'Cancel',
+});
+if (!confirmed) {
+  ctx.exit();  // Terminate subsequent steps if the user cancels
+  return;
+}
+await ctx.runAction('destroy', { filterByTk: ctx.record?.id });
+```
+
+### Confirmation Modal with onOk
+
+```ts
+await ctx.modal.confirm({
+  title: 'Confirm Submission',
+  content: 'Changes cannot be modified after submission. Do you want to continue?',
+  async onOk() {
+    await ctx.form.submit();
+  },
+});
+```
+
+### Error Prompt
+
+```ts
+try {
+  await someOperation();
+  ctx.modal.success({ title: 'Success', content: 'Operation completed' });
+} catch (e) {
+  ctx.modal.error({ title: 'Error', content: e.message });
+}
+```
+
+## Related
+
+- [ctx.message](./message.md): Lightweight temporary prompt, disappears automatically
+- [ctx.exit()](./exit.md): Commonly used as `if (!confirmed) ctx.exit()` to terminate the flow when a user cancels confirmation
+- [ctx.openView()](./open-view.md): Opens a custom view, suitable for complex interactions

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

@@ -0,0 +1,85 @@
+# ctx.model
+
+The `FlowModel` instance where the current RunJS execution context is located. It serves as the default entry point for scenarios like JSBlock, JSField, and JSAction. The specific type varies depending on the context: it could be a subclass such as `BlockModel`, `ActionModel`, or `JSEditableFieldModel`.
+
+## Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSBlock** | `ctx.model` is the current block model. You can access `resource`, `collection`, `setProps`, etc. |
+| **JSField / JSItem / JSColumn** | `ctx.model` is the field model. You can access `setProps`, `dispatchEvent`, etc. |
+| **Action Events / ActionModel** | `ctx.model` is the action model. You can read/write step parameters, dispatch events, etc. |
+
+> Tip: If you need to access the **parent block carrying the current JS** (e.g., a Form or Table block), use `ctx.blockModel`. To access **other models**, use `ctx.getModel(uid)`.
+
+## Type Definition
+
+```ts
+model: FlowModel;
+```
+
+`FlowModel` is the base class. At runtime, it is an instance of various subclasses (such as `BlockModel`, `FormBlockModel`, `TableBlockModel`, `JSEditableFieldModel`, `ActionModel`, etc.). Available properties and methods depend on the specific type.
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `uid` | `string` | Unique identifier of the model. Can be used for `ctx.getModel(uid)` or popup UID binding. |
+| `collection` | `Collection` | The collection bound to the current model (exists when the block/field is bound to data). |
+| `resource` | `Resource` | Associated resource instance, used for refreshing, getting selected rows, etc. |
+| `props` | `object` | UI/behavior configuration of the model. Can be updated using `setProps`. |
+| `subModels` | `Record<string, FlowModel>` | Collection of child models (e.g., fields within a form, columns within a table). |
+| `parent` | `FlowModel` | Parent model (if any). |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `setProps(partialProps: any): void` | Updates model configuration and triggers re-rendering (e.g., `ctx.model.setProps({ loading: true })`). |
+| `dispatchEvent(eventName: string, payload?: any, options?: any): Promise<any[]>` | Dispatches an event to the model, triggering workflows configured on that model that listen for the event name. Optional `payload` is passed to the workflow handler; `options.debounce` enables debouncing. |
+| `getStepParams?.(flowKey, stepKey)` | Reads configuration flow step parameters (used in settings panels, custom actions, etc.). |
+| `setStepParams?.(flowKey, stepKey, params)` | Writes configuration flow step parameters. |
+
+## Relationship with ctx.blockModel and ctx.getModel
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Model of the current execution context** | `ctx.model` |
+| **Parent block of the current JS** | `ctx.blockModel`. Often used to access `resource`, `form`, or `collection`. |
+| **Get any model by UID** | `ctx.getModel(uid)` or `ctx.getModel(uid, true)` (search across view stacks). |
+
+In a JSField, `ctx.model` is the field model, while `ctx.blockModel` is the Form or Table block containing that field.
+
+## Examples
+
+### Updating Block/Action Status
+
+```ts
+ctx.model.setProps({ loading: true });
+await doSomething();
+ctx.model.setProps({ loading: false });
+```
+
+### Dispatching Model Events
+
+```ts
+// Dispatch an event to trigger a workflow configured on this model that listens for this event name
+await ctx.model.dispatchEvent('remove');
+
+// When a payload is provided, it is passed to the workflow handler's ctx.inputArgs
+await ctx.model.dispatchEvent('customEvent', { id: 123 });
+```
+
+### Using UID for Popup Binding or Cross-Model Access
+
+```ts
+const myUid = ctx.model.uid;
+// In popup configuration, you can pass openerUid: myUid for association
+const other = ctx.getModel('other-block-uid');
+if (other) other.rerender?.();
+```
+
+## Related
+
+- [ctx.blockModel](./block-model.md): The parent block model where the current JS is located.
+- [ctx.getModel()](./get-model.md): Get other models by UID.

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

@@ -0,0 +1,106 @@
+# ctx.notification
+
+Based on Ant Design Notification, this global notification API is used to display notification panels in the **top-right corner** of the page. Compared to `ctx.message`, notifications can include a title and description, making them suitable for content that needs to be displayed for a longer period or requires user attention.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / Action Events** | Task completion notifications, batch operation results, export completion, etc. |
+| **FlowEngine** | System-level alerts after asynchronous processes end. |
+| **Content requiring longer display** | Full notifications with titles, descriptions, and action buttons. |
+
+## Type Definition
+
+```ts
+notification: NotificationInstance;
+```
+
+`NotificationInstance` is the Ant Design notification interface, providing the following methods.
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `open(config)` | Opens a notification with custom configuration |
+| `success(config)` | Displays a success notification |
+| `info(config)` | Displays an information notification |
+| `warning(config)` | Displays a warning notification |
+| `error(config)` | Displays an error notification |
+| `destroy(key?)` | Closes the notification with the specified key; if no key is provided, closes all notifications |
+
+**Configuration Parameters** (Consistent with [Ant Design notification](https://ant.design/components/notification)):
+
+| Parameter | Type | Description |
+|------|------|------|
+| `message` | `ReactNode` | Notification title |
+| `description` | `ReactNode` | Notification description |
+| `duration` | `number` | Auto-close delay (seconds). Default is 4.5 seconds; set to 0 to disable auto-close |
+| `key` | `string` | Unique identifier for the notification, used for `destroy(key)` to close a specific notification |
+| `onClose` | `() => void` | Callback function triggered when the notification is closed |
+| `placement` | `string` | Position: `topLeft` \| `topRight` \| `bottomLeft` \| `bottomRight` |
+
+## Examples
+
+### Basic Usage
+
+```ts
+ctx.notification.open({
+  message: 'Operation successful',
+  description: 'Data has been saved to the server.',
+});
+```
+
+### Shortcut Calls by Type
+
+```ts
+ctx.notification.success({
+  message: ctx.t('Export completed'),
+  description: ctx.t('Exported {{count}} records', { count: 10 }),
+});
+
+ctx.notification.error({
+  message: ctx.t('Export failed'),
+  description: ctx.t('Please check the console for details'),
+});
+
+ctx.notification.warning({
+  message: ctx.t('Warning'),
+  description: ctx.t('Some data may be incomplete'),
+});
+```
+
+### Custom Duration and Key
+
+```ts
+ctx.notification.open({
+  key: 'task-123',
+  message: ctx.t('Task in progress'),
+  description: ctx.t('Please wait...'),
+  duration: 0,  // Do not auto-close
+});
+
+// Manually close after task completion
+ctx.notification.destroy('task-123');
+```
+
+### Close All Notifications
+
+```ts
+ctx.notification.destroy();
+```
+
+## Difference from ctx.message
+
+| Feature | ctx.message | ctx.notification |
+|------|--------------|------------------|
+| **Position** | Top center of the page | Top right corner (configurable) |
+| **Structure** | Single-line light hint | Includes title + description |
+| **Purpose** | Temporary feedback, disappears automatically | Complete notification, can be displayed for a long time |
+| **Typical Scenarios** | Operation success, validation failure, copy success | Task completion, system messages, longer content requiring user attention |
+
+## Related
+
+- [ctx.message](./message.md) - Top light hint, suitable for quick feedback
+- [ctx.modal](./modal.md) - Modal confirmation, blocking interaction
+- [ctx.t()](./t.md) - Internationalization, often used in conjunction with notifications