@nocobase/plugin-flow-engine 2.1.0-beta.2 → 2.1.0-beta.20

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

@@ -1,109 +1,109 @@
 # ctx.form
 
-The Ant Design Form instance for the current block; used to read/write form fields, trigger validation, and submit. Same as `ctx.blockModel?.form`; in form blocks (Form, EditForm, sub-forms, etc.) you can use it directly.
+The Ant Design Form instance within the current block, used to read/write form fields, trigger validation, and submission. It is equivalent to `ctx.blockModel?.form` and can be used directly in form-related blocks (Form, Edit Form, Sub-form, etc.).
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField** | Read/write other fields for linkage, compute or validate from other field values |
-| **JSItem** | Read/write same row or other fields in sub-table items |
-| **JSColumn** | Read row or related field values for column rendering |
-| **Form actions / event flow** | Pre-submit validation, batch field updates, reset form, etc. |
+|------|------|
+| **JSField** | Read/write other form fields to implement linkage, or perform calculations and validation based on other field values. |
+| **JSItem** | Read/write same-row or other fields within sub-table items to achieve in-table linkage. |
+| **JSColumn** | Read the current row or association field values in a table column for rendering. |
+| **Form Actions / Workflow** | Pre-submission validation, batch updating fields, resetting forms, etc. |
 
-> Note: `ctx.form` is only available in RunJS contexts tied to a form block (Form, EditForm, sub-forms, etc.); in non-form contexts (e.g. standalone JSBlock, table block) it may be absent—check before use: `ctx.form?.getFieldsValue()`.
+> Note: `ctx.form` is only available in RunJS contexts related to form blocks (Form, Edit Form, Sub-form, etc.). It may not exist in non-form scenarios (such as independent JSBlocks or Table blocks). It is recommended to perform a null check before use: `ctx.form?.getFieldsValue()`.
 
-## Type
+## Type Definition
 
 ```ts
 form: FormInstance<any>;
 ```
 
-`FormInstance` is the Ant Design Form instance type.
+`FormInstance` is the instance type of Ant Design Form. Common methods are as follows.
 
 ## Common Methods
 
-### Read form values
+### Reading Form Values
 
 ```ts
-// Current registered field values (default: only rendered fields)
+// Read values of currently registered fields (defaults to rendered fields only)
 const values = ctx.form.getFieldsValue();
 
-// All field values (including unrendered, e.g. hidden, collapsed)
+// Read values of all fields (including registered but unrendered fields, e.g., hidden or inside collapsed sections)
 const allValues = ctx.form.getFieldsValue(true);
 
-// Single field
+// Read a single field
 const email = ctx.form.getFieldValue('email');
 
-// Nested (e.g. sub-table)
+// Read nested fields (e.g., in a sub-table)
 const amount = ctx.form.getFieldValue(['orders', 0, 'amount']);
 ```
 
-### Write form values
+### Writing Form Values
 
 ```ts
-// Batch update (e.g. linkage)
+// Batch update (commonly used for linkage)
 ctx.form.setFieldsValue({
   status: 'active',
   updatedAt: new Date(),
 });
 
-// Single field
-ctx.form.setFieldValue('remark', 'Noted');
+// Update a single field
+ctx.form.setFieldValue('remark', 'Updated remark');
 ```
 
-### Validation and submit
+### Validation and Submission
 
 ```ts
-// Trigger validation
+// Trigger form validation
 await ctx.form.validateFields();
 
-// Trigger submit
+// Trigger form submission
 ctx.form.submit();
 ```
 
-### Reset
+### Resetting
 
 ```ts
-// All fields
+// Reset all fields
 ctx.form.resetFields();
 
-// Specific fields
+// Reset only specific fields
 ctx.form.resetFields(['status', 'remark']);
 ```
 
-## Relation to Other Context
+## Relationship with Related Contexts
 
 ### ctx.getValue / ctx.setValue
 
-| Scenario | Recommended |
-|----------|-------------|
-| **Current field** | `ctx.getValue()` / `ctx.setValue(v)` |
-| **Other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
+| Scenario | Recommended Usage |
+|------|----------|
+| **Read/Write current field** | `ctx.getValue()` / `ctx.setValue(v)` |
+| **Read/Write other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
 
-In the current JS field, use `getValue`/`setValue` for that field; use `ctx.form` for other fields.
+Within the current JS field, prioritize using `getValue`/`setValue` to read/write the field itself; use `ctx.form` when you need to access other fields.
 
 ### ctx.blockModel
 
-| Need | Recommended |
-|------|-------------|
-| **Read/write form fields** | `ctx.form` (same as `ctx.blockModel?.form`) |
-| **Parent block** | `ctx.blockModel` (includes `collection`, `resource`, etc.) |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Read/Write form fields** | `ctx.form` (Equivalent to `ctx.blockModel?.form`, more convenient) |
+| **Access parent block** | `ctx.blockModel` (Contains `collection`, `resource`, etc.) |
 
 ### ctx.getVar('ctx.formValues')
 
-Form values are obtained via `await ctx.getVar('ctx.formValues')`, not as `ctx.formValues`. In form contexts, prefer `ctx.form.getFieldsValue()` for up-to-date values.
+Form values must be obtained via `await ctx.getVar('ctx.formValues')` and are not directly exposed as `ctx.formValues`. In a form context, it is preferred to use `ctx.form.getFieldsValue()` to read the latest values in real-time.
 
 ## Notes
 
-- `getFieldsValue()` by default returns only rendered fields; for unrendered (e.g. collapsed) use `getFieldsValue(true)`.
-- Nested paths use arrays, e.g. `['orders', 0, 'amount']`; you can use `ctx.namePath` to build paths for other columns in the same row.
-- `validateFields()` throws with `errorFields` etc. on failure; use `ctx.exit()` to stop further steps when validation fails.
-- In event flow or linkage, `ctx.form` may not be ready yet; use optional chaining or null checks.
+- `getFieldsValue()` returns only rendered fields by default. To include unrendered fields (e.g., in collapsed sections or hidden by conditional rules), pass `true`: `getFieldsValue(true)`.
+- Paths for nested fields like sub-tables are arrays, e.g., `['orders', 0, 'amount']`. You can use `ctx.namePath` to get the current field's path and construct paths for other columns in the same row.
+- `validateFields()` throws an error object containing `errorFields` and other information. If validation fails before submission, you can use `ctx.exit()` to terminate subsequent steps.
+- In asynchronous scenarios like workflows or linkage rules, `ctx.form` might not be ready yet. It is recommended to use optional chaining or null checks.
 
 ## Examples
 
-### Field linkage by type
+### Field Linkage: Display different content based on type
 
 ```ts
 const type = ctx.form.getFieldValue('type');
@@ -114,7 +114,7 @@ if (type === 'vip') {
 }
 ```
 
-### Compute current field from others
+### Calculate current field based on other fields
 
 ```ts
 const quantity = ctx.form.getFieldValue('quantity') ?? 0;
@@ -122,48 +122,48 @@ const price = ctx.form.getFieldValue('price') ?? 0;
 ctx.setValue(quantity * price);
 ```
 
-### Same row in sub-table
+### Read/Write other columns in the same row within a sub-table
 
 ```ts
-// ctx.namePath is current field path, e.g. ['orders', 0, 'amount']
-// Same row status: ['orders', 0, 'status']
+// ctx.namePath is the path of the current field in the form, e.g., ['orders', 0, 'amount']
+// Read 'status' in the same row: ['orders', 0, 'status']
 const rowIndex = ctx.namePath?.[1];
 const status = ctx.form.getFieldValue(['orders', rowIndex, 'status']);
 ```
 
-### Pre-submit validation
+### Pre-submission Validation
 
 ```ts
 try {
   await ctx.form.validateFields();
-  // Continue submit logic
+  // Validation passed, continue with submission logic
 } catch (e) {
-  ctx.message.error('Please fix form errors');
+  ctx.message.error('Please check the form fields');
   ctx.exit();
 }
 ```
 
-### Confirm then submit
+### Submit after Confirmation
 
 ```ts
 const confirmed = await ctx.modal.confirm({
-  title: 'Confirm submit',
-  content: 'Cannot be changed after submit. Continue?',
-  okText: 'OK',
+  title: 'Confirm Submission',
+  content: 'You will not be able to modify this after submission. Continue?',
+  okText: 'Confirm',
   cancelText: 'Cancel',
 });
 if (confirmed) {
   await ctx.form.validateFields();
   ctx.form.submit();
 } else {
-  ctx.exit();
+  ctx.exit(); // Terminate if user cancels
 }
 ```
 
 ## Related
 
-- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): read/write current field
-- [ctx.blockModel](./block-model.md): parent block; `ctx.form` is `ctx.blockModel?.form`
-- [ctx.modal](./modal.md): confirm dialog, often with `ctx.form.validateFields()` / `ctx.form.submit()`
-- [ctx.exit()](./exit.md): stop flow on validation failure or cancel
-- `ctx.namePath`: current field path in the form (array); use for nested `getFieldValue` / `setFieldValue` names
+- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): Read and write the current field value.
+- [ctx.blockModel](./block-model.md): Parent block model; `ctx.form` is equivalent to `ctx.blockModel?.form`.
+- [ctx.modal](./modal.md): Confirmation dialogs, often used with `ctx.form.validateFields()` and `ctx.form.submit()`.
+- [ctx.exit()](./exit.md): Terminate the process upon validation failure or user cancellation.
+- `ctx.namePath`: The path (array) of the current field in the form, used to construct names for `getFieldValue` / `setFieldValue` in nested fields.

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

@@ -1,18 +1,18 @@
 # ctx.getModel()
 
-Returns a model instance (e.g. BlockModel, PageModel, ActionModel) from the current engine or view stack by its `uid`. Use in RunJS to access other models across blocks, pages, or popups.
+Retrieves a model instance (such as `BlockModel`, `PageModel`, `ActionModel`, etc.) from the current engine or view stack based on the model `uid`. This is used in RunJS to access other models across blocks, pages, or popups.
 
-If you only need the model or block for the current execution context, use `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
+If you only need the model or block where the current execution context is located, prioritize using `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSAction** | Get another block’s model by known `uid`; read/write its `resource`, `form`, `setProps`, etc. |
-| **RunJS inside popup** | Access a model on the page that opened the popup; pass `searchInPreviousEngines: true` |
-| **Custom actions** | Find a form or sub-model in the settings panel across the view stack by `uid` |
+|------|------|
+| **JSBlock / JSAction** | Get models of other blocks based on a known `uid` to read or write their `resource`, `form`, `setProps`, etc. |
+| **RunJS in Popups** | When needing to access a model on the page that opened the popup, pass `searchInPreviousEngines: true`. |
+| **Custom Actions** | Locate forms or sub-models in the configuration panel by `uid` across view stacks to read their configuration or state. |
 
-## Type
+## Type Definition
 
 ```ts
 getModel<T extends FlowModel = FlowModel>(
@@ -24,19 +24,19 @@ getModel<T extends FlowModel = FlowModel>(
 ## Parameters
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `uid` | `string` | Unique id of the target model (e.g. from config or creation) |
-| `searchInPreviousEngines` | `boolean` | Optional, default `false`. When `true`, search up the view stack from the current engine to find models in parent views (e.g. the page that opened the popup) |
+|------|------|------|
+| `uid` | `string` | The unique identifier of the target model instance, specified during configuration or creation (e.g., `ctx.model.uid`). |
+| `searchInPreviousEngines` | `boolean` | Optional, defaults to `false`. When `true`, searches from the current engine up to the root in the "view stack," allowing access to models in upper-level engines (e.g., the page that opened a popup). |
 
-## Return value
+## Return Value
 
-- Returns the corresponding `FlowModel` subclass (e.g. `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
+- Returns the corresponding `FlowModel` subclass instance (e.g., `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
 - Returns `undefined` if not found.
 
-## Search scope
+## Search Scope
 
-- **Default (`searchInPreviousEngines: false`)**: Search only in the **current engine** by `uid`. In popups or nested views, each view has its own engine; by default only the current view is searched.
-- **`searchInPreviousEngines: true`**: Search from the current engine along the `previousEngine` chain; returns the first match. Use when RunJS in a popup needs to access a model on the page that opened it.
+- **Default (`searchInPreviousEngines: false`)**: Searches only within the **current engine** by `uid`. In popups or multi-level views, each view has an independent engine; by default, it only searches for models within the current view.
+- **`searchInPreviousEngines: true`**: Searches upwards along the `previousEngine` chain starting from the current engine, returning the first match. This is useful for accessing a model on the page that opened the current popup.
 
 ## Examples
 
@@ -49,16 +49,17 @@ if (block?.resource) {
 }
 ```
 
-### Access page model from inside popup
+### Access a model on the page from a popup
 
 ```ts
+// Access a block on the page that opened the current popup
 const pageBlock = ctx.getModel('page-block-uid', true);
 if (pageBlock) {
   pageBlock.rerender?.();
 }
 ```
 
-### Cross-model update and rerender
+### Cross-model read/write and trigger rerender
 
 ```ts
 const target = ctx.getModel('other-block-uid');
@@ -68,17 +69,17 @@ if (target) {
 }
 ```
 
-### Null check
+### Safety check
 
 ```ts
 const model = ctx.getModel(someUid);
 if (!model) {
-  ctx.message.warning('Target model not found');
+  ctx.message.warning('Target model does not exist');
   return;
 }
 ```
 
 ## Related
 
-- [ctx.model](./model.md): model for current execution context
-- [ctx.blockModel](./block-model.md): parent block of current JS; often no need for `getModel`
+- [ctx.model](./model.md): The model where the current execution context is located.
+- [ctx.blockModel](./block-model.md): The parent block model where the current JS is located; usually accessible without needing `getModel`.

package/dist/ai/docs/runjs/context/get-value.md

@@ -1,33 +1,33 @@
 # ctx.getValue()
 
-In JSField, JSItem, and other editable field contexts, returns the current value of the field. Use with `ctx.setValue(v)` for two-way binding with the form.
+In editable field scenarios such as JSField and JSItem, use this to get the latest value of the current field. Combined with `ctx.setValue(v)`, it enables two-way binding with the form.
 
-## Use Cases
+## Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField** | Read user input or current form value in editable custom fields |
-| **JSItem** | Read current cell value in table/sub-table editable items |
-| **JSColumn** | Read row field value when rendering a column |
+|------|------|
+| **JSField** | Read user input or the current form value in editable custom fields. |
+| **JSItem** | Read the current cell value in editable items of tables/sub-tables. |
+| **JSColumn** | Read the field value of the corresponding row during table column rendering. |
 
-> Note: `ctx.getValue()` is only available in RunJS contexts with form binding; it does not exist in event flow, linkage, etc., where there is no field binding.
+> **Note**: `ctx.getValue()` is only available in RunJS contexts with form binding; it does not exist in scenarios without field binding, such as workflows or linkage rules.
 
-## Type
+## Type Definition
 
 ```ts
 getValue<T = any>(): T | undefined;
 ```
 
-- **Returns**: Current field value; type depends on the field’s form item type. May be `undefined` if the field is not registered or not filled.
+- **Return Value**: The current field value, whose type is determined by the field's form item type; it may be `undefined` if the field is not registered or not filled.
 
-## Value resolution
+## Retrieval Order
 
-`ctx.getValue()` resolves in this order:
+`ctx.getValue()` retrieves values in the following order:
 
-1. **Form state**: Prefer current Ant Design Form state.
-2. **Fallback**: If the field is not in the form, use the field’s initial value or props.
+1. **Form State**: Prioritizes reading from the current state of the Ant Design Form.
+2. **Fallback Value**: If the field is not in the form, it falls back to the field's initial value or props.
 
-If the form is not yet rendered or the field is not registered, the result may be `undefined`.
+> If the form has not finished rendering or the field is not registered, it may return `undefined`.
 
 ## Examples
 
@@ -36,9 +36,9 @@ If the form is not yet rendered or the field is not registered, the result may b
 ```ts
 const current = ctx.getValue();
 if (current == null || current === '') {
-  ctx.render(<span>Please enter something</span>);
+  ctx.render(<span>Please enter content first</span>);
 } else {
-  ctx.render(<span>Current: {current}</span>);
+  ctx.render(<span>Current value: {current}</span>);
 }
 ```
 
@@ -47,6 +47,7 @@ if (current == null || current === '') {
 ```tsx
 const { Input } = ctx.libs.antd;
 
+// Read current value as default value
 const defaultValue = ctx.getValue() ?? '';
 
 ctx.render(
@@ -59,6 +60,6 @@ ctx.render(
 
 ## Related
 
-- [ctx.setValue()](./set-value.md): set current field value; use with getValue for two-way binding
-- [ctx.form](./form.md): Ant Design Form instance for other fields
-- `js-field:value-change`: container event when value changes from outside; use to update display
+- [ctx.setValue()](./set-value.md) - Set the current field value, used with `getValue` for two-way binding.
+- [ctx.form](./form.md) - Ant Design Form instance, for reading/writing other fields.
+- `js-field:value-change` - Container event triggered when external values change, used to update the display.

package/dist/ai/docs/runjs/context/get-var.md

@@ -1,94 +1,97 @@
 # ctx.getVar()
 
-**Asynchronously** reads a variable from the current runtime context. Variable sources are the same as for SQL and template `{{ctx.xxx}}`: current user, current record, view params, popup context, etc.
+Asynchronously reads variable values from the current runtime context. Variable resolution is consistent with `{{ctx.xxx}}` in SQL and templates, typically originating from the current user, current record, view parameters, popup context, etc.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField** | Get current record, user, resource, etc. for rendering or logic |
-| **Linkage / event flow** | Read `ctx.record`, `ctx.formValues`, etc. for conditions |
-| **Formulas / templates** | Same variable resolution as `{{ctx.xxx}}` |
+|------|------|
+| **JSBlock / JSField** | Get information about the current record, user, resource, etc., for rendering or logic. |
+| **Linkage Rules / FlowEngine** | Read `ctx.record`, `ctx.formValues`, etc., for conditional logic. |
+| **Formulas / Templates** | Uses the same variable resolution rules as `{{ctx.xxx}}`. |
 
-## Type
+## Type Definition
 
 ```ts
 getVar(path: string): Promise<any>;
 ```
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | `string` | Variable path; **must start with `ctx.`**; supports dot and array index |
+|------|------|------|
+| `path` | `string` | Variable path; **must start with `ctx.`**. Supports dot notation and array indices. |
 
-**Returns**: `Promise<any>`; use `await` to get the resolved value. Returns `undefined` if the variable does not exist.
+**Return Value**: `Promise<any>`. Use `await` to get the resolved value; returns `undefined` if the variable does not exist.
 
-> If the path does not start with `ctx.`, an error is thrown: `ctx.getVar(path) expects an expression starting with "ctx.", got: "..."`.
+> If a path that does not start with `ctx.` is passed, an error will be thrown: `ctx.getVar(path) expects an expression starting with "ctx.", got: "..."`.
 
-## Common paths
+## Common Variable Paths
 
 | Path | Description |
-|------|-------------|
-| `ctx.record` | Current record (when form/detail is bound to a record) |
+|------|------|
+| `ctx.record` | Current record (available when a form/details block is bound to a record) |
 | `ctx.record.id` | Current record primary key |
-| `ctx.formValues` | Current form values (common in linkage/event flow; in form context prefer `ctx.form.getFieldsValue()` for live values) |
-| `ctx.user` | Current user |
-| `ctx.user.id` | Current user id |
+| `ctx.formValues` | Current form values (commonly used in linkage rules and FlowEngine; in form scenarios, prefer `ctx.form.getFieldsValue()` for real-time reading) |
+| `ctx.user` | Current logged-in user |
+| `ctx.user.id` | Current user ID |
 | `ctx.user.nickname` | Current user nickname |
 | `ctx.user.roles.name` | Current user role names (array) |
-| `ctx.popup.record` | Record in popup |
-| `ctx.popup.record.id` | Popup record primary key |
-| `ctx.urlSearchParams` | URL query params (from `?key=value`) |
-| `ctx.token` | Current API token |
+| `ctx.popup.record` | Record within a popup |
+| `ctx.popup.record.id` | Primary key of the record within a popup |
+| `ctx.urlSearchParams` | URL query parameters (parsed from `?key=value`) |
+| `ctx.token` | Current API Token |
 | `ctx.role` | Current role |
 
 ## ctx.getVarInfos()
 
-Returns **structure info** (type, title, child properties, etc.) for variables that can be resolved in the current context. Useful to discover available paths. Values are static meta, not runtime values.
+Gets the **structural information** (type, title, sub-properties, etc.) of resolvable variables in the current context, making it easier to explore available paths. The return value is a static description based on `meta` and does not include actual runtime values.
 
-### Type
+### Type Definition
 
 ```ts
 getVarInfos(options?: { path?: string | string[]; maxDepth?: number }): Promise<Record<string, any>>;
 ```
 
-Each key in the result is a variable path; each value is that path’s structure (e.g. `type`, `title`, `properties`).
+In the return value, each key is a variable path, and the value is the structural information for that path (including `type`, `title`, `properties`, etc.).
 
-### Options
+### Parameters
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `string \| string[]` | Limit to paths under this; e.g. `'record'`, `'record.id'`, `'ctx.record'`, `'{{ ctx.record }}'`; array = multiple paths merged |
-| `maxDepth` | `number` | Max depth to expand; default `3`. Without path, top-level depth=1; with path, that node depth=1 |
+| Parameter | Type | Description |
+|------|------|------|
+| `path` | `string \| string[]` | Truncation path; only collects the variable structure under this path. Supports `'record'`, `'record.id'`, `'ctx.record'`, `'{{ ctx.record }}'`; an array represents the merging of multiple paths. |
+| `maxDepth` | `number` | Maximum expansion depth, default is `3`. When `path` is not provided, top-level properties have `depth=1`. When `path` is provided, the node corresponding to the path has `depth=1`. |
 
 ### Example
 
 ```ts
+// Get the variable structure under record (expanded up to 3 levels)
 const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
 
+// Get the structure of popup.record
 const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });
 
+// Get the complete top-level variable structure (default maxDepth=3)
 const vars = await ctx.getVarInfos();
 ```
 
-## Relation to ctx.getValue
+## Difference from ctx.getValue
 
-| Method | Context | Description |
-|--------|---------|-------------|
-| `ctx.getValue()` | JSField, JSItem, etc. | Sync; **current field** value; requires form binding |
-| `ctx.getVar(path)` | Any RunJS | Async; **any ctx variable**; path must start with `ctx.` |
+| Method | Scenario | Description |
+|------|----------|------|
+| `ctx.getValue()` | Editable fields like JSField or JSItem | Synchronously gets the value of the **current field**; requires form binding. |
+| `ctx.getVar(path)` | Any RunJS context | Asynchronously gets **any ctx variable**; path must start with `ctx.`. |
 
-In JSField, use getValue/setValue for the field; use getVar for other context (record, user, formValues).
+In a JSField, use `getValue`/`setValue` to read/write the current field; use `getVar` to access other context variables (such as `record`, `user`, `formValues`).
 
 ## Notes
 
-- **Path must start with `ctx.`**: e.g. `ctx.record.id`; otherwise an error is thrown.
-- **Async**: Use `await`, e.g. `const id = await ctx.getVar('ctx.record.id')`.
-- **Missing variable**: Returns `undefined`; use `??` for default: `(await ctx.getVar('ctx.user.nickname')) ?? 'Guest'`.
-- **Form values**: Get via `await ctx.getVar('ctx.formValues')`; not exposed as `ctx.formValues`. In form context prefer `ctx.form.getFieldsValue()` for latest values.
+- **Path must start with `ctx.`**: e.g., `ctx.record.id`, otherwise an error will be thrown.
+- **Asynchronous method**: You must use `await` to get the result, e.g., `const id = await ctx.getVar('ctx.record.id')`.
+- **Variable does not exist**: Returns `undefined`. You can use `??` after the result to set a default value: `(await ctx.getVar('ctx.user.nickname')) ?? 'Guest'`.
+- **Form values**: `ctx.formValues` must be retrieved via `await ctx.getVar('ctx.formValues')`; it is not directly exposed as `ctx.formValues`. In a form context, prefer using `ctx.form.getFieldsValue()` to read the latest values in real-time.
 
 ## Examples
 
-### Current record id
+### Get Current Record ID
 
 ```ts
 const recordId = await ctx.getVar('ctx.record.id');
@@ -97,55 +100,58 @@ if (recordId) {
 }
 ```
 
-### Popup record
+### Get Record Within a Popup
 
 ```ts
 const recordId = await ctx.getVar('ctx.popup.record.id');
 if (recordId) {
-  ctx.message.info(`Popup record: ${recordId}`);
+  ctx.message.info(`Current popup record: ${recordId}`);
 }
 ```
 
-### Array field items
+### Read Sub-items of an Array Field
 
 ```ts
 const roleNames = await ctx.getVar('ctx.user.roles.name');
-// e.g. ['admin', 'member']
+// Returns an array of role names, e.g., ['admin', 'member']
 ```
 
-### Default value
+### Set Default Value
 
 ```ts
+// getVar does not have a defaultValue parameter; use ?? after the result
 const userName = (await ctx.getVar('ctx.user.nickname')) ?? 'Guest';
 ```
 
-### Form field value
+### Read Form Field Values
 
 ```ts
+// Both ctx.formValues and ctx.form are for form scenarios; use getVar to read nested fields
 const status = await ctx.getVar('ctx.formValues.status');
 if (status === 'draft') {
   // ...
 }
 ```
 
-### URL query params
+### Read URL Query Parameters
 
 ```ts
-const id = await ctx.getVar('ctx.urlSearchParams.id'); // ?id=xxx
+const id = await ctx.getVar('ctx.urlSearchParams.id'); // Corresponds to ?id=xxx
 ```
 
-### Explore variables
+### Explore Available Variables
 
 ```ts
+// Get the variable structure under record (expanded up to 3 levels)
 const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
-// e.g. { 'record.id': { type: 'string', title: 'id' }, ... }
+// vars looks like { 'record.id': { type: 'string', title: 'id' }, ... }
 ```
 
 ## Related
 
-- [ctx.getValue()](./get-value.md): sync current field value (JSField/JSItem only)
-- [ctx.form](./form.md): form instance; `ctx.form.getFieldsValue()` for live form values
-- [ctx.model](./model.md): current model
-- [ctx.blockModel](./block-model.md): parent block
-- [ctx.resource](./resource.md): resource in current context
-- SQL / template `{{ctx.xxx}}`: same resolution as `ctx.getVar('ctx.xxx')`
+- [ctx.getValue()](./get-value.md) - Synchronously gets the current field value (JSField/JSItem only)
+- [ctx.form](./form.md) - Form instance; `ctx.form.getFieldsValue()` can read form values in real-time
+- [ctx.model](./model.md) - The model where the current execution context resides
+- [ctx.blockModel](./block-model.md) - The parent block where the current JS is located
+- [ctx.resource](./resource.md) - The resource instance in the current context
+- `{{ctx.xxx}}` in SQL / Templates - Uses the same resolution rules as `ctx.getVar('ctx.xxx')`