@nocobase/plugin-flow-engine 2.1.0-beta.15 → 2.1.0-beta.17

package/dist/ai/ai-employees/nathan/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+declare const _default: import("@nocobase/ai").AIEmployeeOptions;
+export default _default;

package/dist/ai/ai-employees/nathan/index.js

@@ -0,0 +1,41 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var nathan_exports = {};
+__export(nathan_exports, {
+  default: () => nathan_default
+});
+module.exports = __toCommonJS(nathan_exports);
+var import_ai = require("@nocobase/ai");
+var nathan_default = (0, import_ai.defineAIEmployee)({
+  username: "nathan",
+  description: "AI employee for coding",
+  avatar: "nocobase-002-male",
+  nickname: "Nathan",
+  position: "Frontend code engineer",
+  bio: "An frontend engineer specializing in JavaScript, HTML, and CSS.",
+  greeting: "Hello, I\u2019m Nathan, your frontend code engineer. I\u2019ll generate high-quality JavaScript / HTML / CSS code for you. What would you like me to build today?"
+});

package/dist/ai/ai-employees/nathan/prompt.md

@@ -0,0 +1,132 @@
+You are an AI coding assistant for NocoBase RunJS.
+
+RunJS is used in:
+
+- JS Block
+- JS Field
+- JS Item
+- JS Action
+- Event Flow
+- Linkage Rules
+
+Runtime:
+
+- Sandboxed environment
+- Access via \`ctx\`
+- Supports top-level await (PREFER whenever possible)
+- JSX → ctx.libs.React.createElement
+- Dynamic ESM via ctx.importAsync()
+
+
+# Core Rule (Strict)
+
+Never guess.
+
+You must NOT assume:
+
+- ctx APIs
+- context variables
+- collections / fields / schema
+- runtime behavior
+- React / Antd exposure
+- browser globals (window, document, location, history, navigator)
+
+All of the above MUST be verified via tools or NocoBase docs.
+
+If not confirmed → ask user.
+
+# Mandatory Workflow (Every Task)
+
+Follow this exact order. Do NOT skip ahead to coding.
+
+1. Runtime inspection first
+   - Use `frontend-developer` skill guidance.
+   - Call:
+     - `getContextEnvs`
+     - `getContextVars`
+     - `getContextApis`
+   - Goal: confirm what the current runtime exposes.
+   - This step does NOT replace documentation lookup.
+
+2. Documentation lookup before writing any code
+   - Use `document-search` skill guidance.
+   - You MUST call:
+     - `searchDocs`
+     - `readDocEntry`
+   - Always search docs before coding when the task involves any of the following:
+     - RunJS / workflow / JS Block / JS Field / JS Item / JS Action / Event Flow / Linkage Rules
+     - `ctx` APIs, runtime constraints, rendering, routing, requests, imports, React, Antd
+     - any NocoBase-specific feature, component, schema, collection behavior, or API usage
+   - Do not rely on memory, prior experience, or "common NocoBase patterns" as a substitute for this step.
+   - Minimum requirement:
+     - search for the relevant module / keywords
+     - read the most relevant matching entry or entries
+     - extract the concrete constraints or APIs you will rely on
+   - Only after this step may you decide how to implement the solution.
+
+3. Data inspection when data model is involved
+   - Use `data-metadata` skill guidance.
+   - If the task touches collections, fields, relations, filtering, querying, or record structure, call:
+     - `getDatasources`
+     - `getCollectionNames`
+     - `getCollectionMetadata`
+     - `searchFieldMetadata`
+   - Do not invent collection names, field names, relation paths, or schema details.
+
+4. Resolve uncertainty before coding
+   - If runtime inspection, docs, or metadata still leave a gap, stop and use `suggestions` or ask the user.
+   - If a required fact is unverified, you must not start writing code yet.
+
+5. Write code only after steps 1-4 are complete
+   - `frontend-developer` is the implementation skill, not the starting shortcut.
+   - Never use `frontend-developer` alone as justification to begin coding.
+   - The code must be based on verified runtime context, verified documentation, and verified metadata when applicable.
+
+6. Validate before output (REQUIRED)
+   - `lintAndTestJS` must pass before output.
+   - If validation fails, fix the code and validate again.
+
+# Coding Rules
+
+- Single file
+- Prefer top-level await
+- No import / require
+- Libraries ONLY via ctx.importAsync()
+- HTTP ONLY via ctx.request()
+- Only call ctx.render when UI is required
+- JSX uses ctx.libs.React by default
+- When rendering UI, PREFER Ant Design components via ctx.libs.antd to match NocoBase style
+- Inline styles only
+
+Forbidden:
+
+- fetch
+- XMLHttpRequest
+- localStorage
+- eval
+- new Function
+- Direct document / window access unless explicitly documented
+
+# i18n
+
+All user-facing strings MUST use: \`ctx.t(...)\`
+
+# Security
+
+Never inject unsanitized user input into DOM.
+
+# Output Rules
+
+- Markdown
+- Exactly ONE complete code block at end
+- No partial snippets
+- Brief explanation after code
+
+# Standard
+
+Senior NocoBase engineer mindset:
+Tool-driven, deterministic, production-minded.
+
+If unsure: search.
+If still unsure: ask.
+Never guess.

package/dist/ai/ai-employees/nathan/skills/frontend-developer/SKILLS.md

@@ -0,0 +1,69 @@
+---
+name: frontend-developer
+description: Assists with writing, validating, and testing JavaScript code snippets for NocoBase workflows and frontend blocks.
+introduction:
+  title: '{{t("ai.skills.frontendDeveloper.title")}}'
+  about: '{{t("ai.skills.frontendDeveloper.about")}}'
+---
+
+You are a professional frontend developer assistant for NocoBase.
+
+You help users write, validate, and test JavaScript code for workflows, including:
+- Workflow nodes (e.g., Custom JS, Calculation, Conditional branches)
+- Frontend blocks and pages
+
+# Primary Workflow
+
+When helping users with JavaScript code, follow this process:
+
+1. **Understand the Context**
+   - Use `getContextVars` to understand what variables are available in the current context
+   - Use `getContextApis` to see what API methods can be used
+   - Use `getContextEnvs` to understand the current page/block/flow model metadata
+
+2. **Write the Code**
+   - Write clean, correct JavaScript/JSX code based on the user's requirements
+   - Ensure the code follows best practices for NocoBase workflows
+
+3. **Validate the Code**
+   - Use `lintAndTestJS` to lint and test the code before final output
+   - Fix any errors reported by the linting tool
+   - Do not output final code unless it passes validation
+
+4. **Submit the Code**
+   - Once validated, provide the final code to the user
+   - Explain how the code works and what it does
+
+# Available Tools
+
+- `getContextVars`: Retrieves available variables from the current context. Variables are references only — you must explicitly resolve values via `await ctx.getVar(path)`. Supports dot-notation for progressive drilling (e.g., `ctx.popup.record.id`).
+- `getContextApis`: Returns available API methods from the context that can be used in the code.
+- `getContextEnvs`: Returns metadata about the current page, block, or flow model.
+- `lintAndTestJS`: Lints, performs sandbox checks, and trial-runs JavaScript/JSX code. Returns success/failure with diagnostics. **Always call this tool before outputting final code to verify it works.**
+
+# Code Writing Guidelines
+
+## Variable Access
+
+- Always use `await ctx.getVar(path)` to get actual values
+- Use dot-notation for nested paths: `await ctx.getVar('ctx.popup.record.id')`
+- Prefer specific paths instead of fetching entire objects when possible
+
+## Return Values
+
+- For Custom JS nodes, use `return` to output data to the next node
+- Return values are passed as input to subsequent nodes in the workflow
+- Example: `return { result: calculatedValue };`
+
+## Error Handling
+
+- Wrap code in try-catch blocks when appropriate
+- Return error information in a consistent format
+- Example: `return { error: 'Error message', details: ... };`
+
+## Best Practices
+
+- Keep code concise and readable
+- Use meaningful variable names
+- Add comments for complex logic
+- Test code with the lint tool before final submission

package/dist/ai/{tools → ai-employees/nathan/skills/frontend-developer/tools}/getContextApis.js

@@ -44,9 +44,9 @@ var getContextApis_default = (0, import_ai.defineTools)({
     description: "Get available API methods from context",
     schema: import_zod.z.object({})
   },
-  invoke: async (ctx, _args, id) => {
+  invoke: async (ctx, _args, runtime) => {
     const { toolCallResults } = ctx.action.params.values || {};
-    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === id)) ?? {};
+    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === runtime.toolCallId)) ?? {};
     if (toolCallResults && result) {
       return {
         status: "success",

package/dist/ai/{tools → ai-employees/nathan/skills/frontend-developer/tools}/getContextEnvs.js

@@ -44,9 +44,9 @@ var getContextEnvs_default = (0, import_ai.defineTools)({
     description: "Get current page/block/flow model metadata from context",
     schema: import_zod.z.object({})
   },
-  invoke: async (ctx, _args, id) => {
+  invoke: async (ctx, _args, runtime) => {
     const { toolCallResults } = ctx.action.params.values || {};
-    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === id)) ?? {};
+    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === runtime.toolCallId)) ?? {};
     if (toolCallResults && result) {
       return {
         status: "success",

package/dist/ai/{tools → ai-employees/nathan/skills/frontend-developer/tools}/getContextVars.js

@@ -60,9 +60,9 @@ instead of fetching the entire object, e.g.
       )
     })
   },
-  invoke: async (ctx, _args, id) => {
+  invoke: async (ctx, _args, runtime) => {
     const { toolCallResults } = ctx.action.params.values || {};
-    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === id)) ?? {};
+    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === runtime.toolCallId)) ?? {};
     if (toolCallResults && result) {
       return {
         status: "success",

package/dist/ai/{tools → ai-employees/nathan/skills/frontend-developer/tools}/lintAndTestJS.js

@@ -46,9 +46,9 @@ var lintAndTestJS_default = (0, import_ai.defineTools)({
       code: import_zod.z.string().describe("The JavaScript/JSX code to preview and validate")
     })
   },
-  invoke: async (ctx, _args, id) => {
+  invoke: async (ctx, _args, runtime) => {
     const { toolCallResults } = ctx.action.params.values || {};
-    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === id)) ?? {};
+    const { result } = (toolCallResults == null ? void 0 : toolCallResults.find((item) => item.id === runtime.toolCallId)) ?? {};
     if (toolCallResults && result) {
       return {
         status: result.status ?? "error",

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

@@ -1,49 +1,49 @@
 # ctx.blockModel
 
-The parent block model (BlockModel instance) that hosts the current JS field / JS block. In JSField, JSItem, JSColumn, etc., `ctx.blockModel` refers to the form block or table block that hosts the current JS logic; in a standalone JSBlock it may be `null` or the same as `ctx.model`.
+The parent block model (BlockModel instance) where the current JS Field / JS Block is located. In scenarios such as JSField, JSItem, and JSColumn, `ctx.blockModel` points to the form block or table block carrying the current JS logic. In a standalone JSBlock, it may be `null` or the same as `ctx.model`.
 
-## Use Cases
+## Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField** | Access parent form block's `form`, `collection`, `resource` for linkage or validation |
-| **JSItem** | Access parent table/form block's resource and collection in sub-table items |
-| **JSColumn** | Access parent table block's `resource` (e.g. `getSelectedRows`), `collection` |
-| **Form actions / event flow** | Use `form` for pre-submit validation, `resource` for refresh, etc. |
+|------|------|
+| **JSField** | Access the `form`, `collection`, and `resource` of the parent form block within a form field to implement linkage or validation. |
+| **JSItem** | Access the resource and collection information of the parent table/form block within a sub-table item. |
+| **JSColumn** | Access the `resource` (e.g., `getSelectedRows`) and `collection` of the parent table block within a table column. |
+| **Form Actions / FlowEngine** | Access `form` for pre-submission validation, `resource` for refreshing, etc. |
 
-> Note: `ctx.blockModel` is only available in RunJS contexts that have a parent block; in a standalone JSBlock (no parent form/table) it may be `null`—check before use.
+> Note: `ctx.blockModel` is only available in RunJS contexts where a parent block exists. In standalone JSBlocks (without a parent form/table), it may be `null`. It is recommended to perform a null check before use.
 
-## Type
+## Type Definition
 
 ```ts
 blockModel: BlockModel | FormBlockModel | TableBlockModel | CollectionBlockModel | DataBlockModel | null;
 ```
 
-The exact type depends on the parent block: form blocks are usually `FormBlockModel` / `EditFormModel`, table blocks are usually `TableBlockModel`.
+The specific type depends on the parent block type: form blocks are mostly `FormBlockModel` or `EditFormModel`, while table blocks are mostly `TableBlockModel`.
 
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `uid` | `string` | Block model unique id |
-| `collection` | `Collection` | Collection bound to the block |
-| `resource` | `Resource` | Resource instance (`SingleRecordResource` / `MultiRecordResource`, etc.) |
-| `form` | `FormInstance` | Form block: Ant Design Form instance (`getFieldsValue`, `validateFields`, `setFieldsValue`, etc.) |
-| `emitter` | `EventEmitter` | Event emitter; can listen to `formValuesChange`, `onFieldReset`, etc. |
+|------|------|------|
+| `uid` | `string` | Unique identifier of the block model. |
+| `collection` | `Collection` | The collection bound to the current block. |
+| `resource` | `Resource` | The resource instance used by the block (`SingleRecordResource` / `MultiRecordResource`, etc.). |
+| `form` | `FormInstance` | Form Block: Ant Design Form instance, supporting `getFieldsValue`, `validateFields`, `setFieldsValue`, etc. |
+| `emitter` | `EventEmitter` | Event emitter, used to listen for `formValuesChange`, `onFieldReset`, etc. |
 
-## Relation to ctx.model, ctx.form
+## Relationship with ctx.model and ctx.form
 
-| Need | Recommended |
-|------|-------------|
-| **Parent block of current JS** | `ctx.blockModel` |
-| **Read/write form fields** | `ctx.form` (same as `ctx.blockModel?.form`; more convenient in form blocks) |
-| **Model for current execution context** | `ctx.model` (field model in JSField, block model in JSBlock) |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Parent block of the current JS** | `ctx.blockModel` |
+| **Read/Write form fields** | `ctx.form` (equivalent to `ctx.blockModel?.form`, more convenient in form blocks) |
+| **Model of the current execution context** | `ctx.model` (Field model in JSField, Block model in JSBlock) |
 
-In JSField, `ctx.model` is the field model and `ctx.blockModel` is the form/table block that hosts it; `ctx.form` is usually `ctx.blockModel.form`.
+In a JSField, `ctx.model` is the field model, and `ctx.blockModel` is the form or table block carrying that field; `ctx.form` is typically `ctx.blockModel.form`.
 
 ## Examples
 
-### Table: get selected rows and process
+### Table: Get selected rows and process
 
 ```ts
 const rows = ctx.blockModel?.resource?.getSelectedRows?.() || [];
@@ -53,7 +53,7 @@ if (rows.length === 0) {
 }
 ```
 
-### Form: validate and refresh
+### Form Scenario: Validate and Refresh
 
 ```ts
 if (ctx.blockModel?.form) {
@@ -62,15 +62,15 @@ if (ctx.blockModel?.form) {
 }
 ```
 
-### Listen to form changes
+### Listen for Form Changes
 
 ```ts
 ctx.blockModel?.emitter?.on?.('formValuesChange', (payload) => {
-  // React to latest form values or re-render
+  // Implement linkage or re-rendering based on the latest form values
 });
 ```
 
-### Trigger block re-render
+### Trigger Block Re-render
 
 ```ts
 ctx.blockModel?.rerender?.();
@@ -78,13 +78,13 @@ ctx.blockModel?.rerender?.();
 
 ## Notes
 
-- In a **standalone JSBlock** (no parent form/table), `ctx.blockModel` may be `null`; use optional chaining: `ctx.blockModel?.resource?.refresh?.()`.
-- In **JSField / JSItem / JSColumn**, `ctx.blockModel` is the form or table block that hosts the field; in **JSBlock**, it may be the block itself or an ancestor, depending on hierarchy.
-- `resource` exists only on data blocks; `form` exists only on form blocks; table blocks usually have no `form`.
+- In a **standalone JSBlock** (without a parent form or table block), `ctx.blockModel` may be `null`. It is recommended to use optional chaining when accessing its properties: `ctx.blockModel?.resource?.refresh?.()`.
+- In **JSField / JSItem / JSColumn**, `ctx.blockModel` refers to the form or table block carrying the current field. In a **JSBlock**, it may be itself or an upper-level block, depending on the actual hierarchy.
+- `resource` only exists in data blocks; `form` only exists in form blocks. Table blocks typically do not have a `form`.
 
 ## Related
 
-- [ctx.model](./model.md): model for current execution context
-- [ctx.form](./form.md): form instance, common in form blocks
-- [ctx.resource](./resource.md): resource instance (same as `ctx.blockModel?.resource` when present)
-- [ctx.getModel()](./get-model.md): get another block model by uid
+- [ctx.model](./model.md): The model of the current execution context.
+- [ctx.form](./form.md): Form instance, commonly used in form blocks.
+- [ctx.resource](./resource.md): Resource instance (equivalent to `ctx.blockModel?.resource`, use directly if available).
+- [ctx.getModel()](./get-model.md): Get other block models by UID.

package/dist/ai/docs/runjs/context/collection-field.md

@@ -1,18 +1,18 @@
 # ctx.collectionField
 
-The collection field (CollectionField) instance for the current RunJS context; used to access field metadata, type, validation rules, and association info. Only present when the field is bound to a collection definition; custom/virtual fields may have `null`.
+The `CollectionField` instance associated with the current RunJS execution context, used to access field metadata, types, validation rules, and association information. It only exists when the field is bound to a collection definition; custom/virtual fields may be `null`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField** | Use `interface`, `enum`, `targetCollection`, etc. for linkage or validation |
-| **JSItem** | Access metadata of the column’s field in sub-table items |
-| **JSColumn** | Choose render by `collectionField.interface`, or use `targetCollection` |
+|------|------|
+| **JSField** | Perform linkage or validation in form fields based on `interface`, `enum`, `targetCollection`, etc. |
+| **JSItem** | Access metadata of the field corresponding to the current column in sub-table items. |
+| **JSColumn** | Select rendering methods based on `collectionField.interface` or access `targetCollection` in table columns. |
 
-> Note: `ctx.collectionField` is only available when the field is bound to a collection; in standalone JSBlock or actions with no field binding it is usually `undefined`—check before use.
+> Note: `ctx.collectionField` is only available when the field is bound to a Collection definition; it is usually `undefined` in scenarios like JSBlock independent blocks or action events without field binding. It is recommended to check for null values before use.
 
-## Type
+## Type Definition
 
 ```ts
 collectionField: CollectionField | null | undefined;
@@ -21,46 +21,47 @@ collectionField: CollectionField | null | undefined;
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Field name (e.g. `status`, `userId`) |
-| `title` | `string` | Field title (i18n) |
-| `type` | `string` | Data type (`string`, `integer`, `belongsTo`, etc.) |
-| `interface` | `string` | UI type (`input`, `select`, `m2o`, `o2m`, `m2m`, etc.) |
-| `collection` | `Collection` | Field’s collection |
-| `targetCollection` | `Collection` | Target collection for association fields only |
-| `target` | `string` | Target collection name (association) |
-| `enum` | `array` | Enum options (select, radio, etc.) |
+|------|------|------|
+| `name` | `string` | Field name (e.g., `status`, `userId`) |
+| `title` | `string` | Field title (including internationalization) |
+| `type` | `string` | Field data type (`string`, `integer`, `belongsTo`, etc.) |
+| `interface` | `string` | Field interface type (`input`, `select`, `m2o`, `o2m`, `m2m`, etc.) |
+| `collection` | `Collection` | The collection the field belongs to |
+| `targetCollection` | `Collection` | The target collection of the association field (only for association types) |
+| `target` | `string` | Target collection name (for association fields) |
+| `enum` | `array` | Enumeration options (select, radio, etc.) |
 | `defaultValue` | `any` | Default value |
-| `collectionName` | `string` | Collection name |
-| `foreignKey` | `string` | Foreign key (e.g. belongsTo) |
-| `sourceKey` | `string` | Source key (e.g. hasMany) |
-| `targetKey` | `string` | Target key |
-| `fullpath` | `string` | Full path (e.g. `main.users.status`) for API/variables |
-| `resourceName` | `string` | Resource name (e.g. `users.status`) |
-| `readonly` | `boolean` | Read-only |
-| `titleable` | `boolean` | Can be used as title |
-| `validation` | `object` | Validation config |
-| `uiSchema` | `object` | UI config |
-| `targetCollectionTitleField` | `CollectionField` | Title field of target collection (association) |
+| `collectionName` | `string` | Name of the collection it belongs to |
+| `foreignKey` | `string` | Foreign key field name (belongsTo, etc.) |
+| `sourceKey` | `string` | Association source key (hasMany, etc.) |
+| `targetKey` | `string` | Association target key |
+| `fullpath` | `string` | Full path (e.g., `main.users.status`), used for API or variable references |
+| `resourceName` | `string` | Resource name (e.g., `users.status`) |
+| `readonly` | `boolean` | Whether it is read-only |
+| `titleable` | `boolean` | Whether it can be displayed as a title |
+| `validation` | `object` | Validation rule configuration |
+| `uiSchema` | `object` | UI configuration |
+| `targetCollectionTitleField` | `CollectionField` | The title field of the target collection (for association fields) |
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `isAssociationField(): boolean` | Whether it is an association (belongsTo, hasMany, hasOne, belongsToMany, etc.) |
-| `isRelationshipField(): boolean` | Whether it is a relationship (o2o, m2o, o2m, m2m, etc.) |
-| `getComponentProps(): object` | Default props for the field component |
-| `getFields(): CollectionField[]` | Fields of target collection (association only) |
-| `getFilterOperators(): object[]` | Filter operators (e.g. `$eq`, `$ne`) |
+|------|------|
+| `isAssociationField(): boolean` | Whether it is an association field (belongsTo, hasMany, hasOne, belongsToMany, etc.) |
+| `isRelationshipField(): boolean` | Whether it is a relationship field (including o2o, m2o, o2m, m2m, etc.) |
+| `getComponentProps(): object` | Get the default props of the field component |
+| `getFields(): CollectionField[]` | Get the field list of the target collection (association fields only) |
+| `getFilterOperators(): object[]` | Get the filter operators supported by this field (e.g., `$eq`, `$ne`, etc.) |
 
 ## Examples
 
-### Branch by field type
+### Branch rendering based on field type
 
 ```ts
 if (!ctx.collectionField) return null;
 const { interface: iface } = ctx.collectionField;
 if (['m2o', 'o2m', 'm2m'].includes(iface)) {
+  // Association field: display associated records
   const target = ctx.collectionField.targetCollection;
   // ...
 } else if (iface === 'select' || iface === 'radioGroup') {
@@ -69,24 +70,24 @@ if (['m2o', 'o2m', 'm2m'].includes(iface)) {
 }
 ```
 
-### Check association and use target collection
+### Determine if it is an association field and access the target collection
 
 ```ts
 if (ctx.collectionField?.isAssociationField()) {
   const targetCol = ctx.collectionField.targetCollection;
   const titleField = targetCol?.titleCollectionField?.name;
-  // ...
+  // Process according to the target collection structure
 }
 ```
 
-### Get enum options
+### Get enumeration options
 
 ```ts
 const options = ctx.collectionField?.enum ?? [];
 const labels = options.map((o) => (typeof o === 'object' ? o.label : o));
 ```
 
-### Conditional render by readonly
+### Conditional rendering based on read-only/view mode
 
 ```ts
 const { Input } = ctx.libs.antd;
@@ -97,34 +98,35 @@ if (ctx.collectionField?.readonly) {
 }
 ```
 
-### Title field of target collection
+### Get the title field of the target collection
 
 ```ts
+// When displaying an association field, use targetCollectionTitleField to get the title field name
 const titleField = ctx.collectionField?.targetCollectionTitleField;
 const titleKey = titleField?.name ?? 'title';
 const assocValue = ctx.getValue?.() ?? ctx.record?.[ctx.collectionField?.name];
 const label = assocValue?.[titleKey];
 ```
 
-## Relation to ctx.collection
+## Relationship with ctx.collection
 
-| Need | Recommended |
-|------|-------------|
-| **Collection of current field** | `ctx.collectionField?.collection` or `ctx.collection` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Current field's collection** | `ctx.collectionField?.collection` or `ctx.collection` |
 | **Field metadata (name, type, interface, enum, etc.)** | `ctx.collectionField` |
 | **Target collection** | `ctx.collectionField?.targetCollection` |
 
-`ctx.collection` is usually the block’s collection; `ctx.collectionField` is the field definition; they can differ in sub-tables and associations.
+`ctx.collection` usually represents the collection bound to the current block; `ctx.collectionField` represents the definition of the current field in the collection. In scenarios like sub-tables or association fields, the two may differ.
 
 ## Notes
 
-- In **JSBlock**, **JSAction (no field binding)**, `ctx.collectionField` is usually `undefined`; use optional chaining.
-- Custom JS fields not bound to a collection field may have `ctx.collectionField` as `null`.
-- `targetCollection` exists only for association fields (m2o, o2m, m2m); `enum` only for select, radioGroup, etc.
+- In scenarios such as **JSBlock** or **JSAction (without field binding)**, `ctx.collectionField` is usually `undefined`. It is recommended to use optional chaining before access.
+- If a custom JS field is not bound to a collection field, `ctx.collectionField` may be `null`.
+- `targetCollection` only exists for association type fields (e.g., m2o, o2m, m2m); `enum` only exists for fields with options like select or radioGroup.
 
 ## Related
 
-- [ctx.collection](./collection.md): collection for current context
-- [ctx.model](./model.md): model for current execution context
-- [ctx.blockModel](./block-model.md): parent block
-- [ctx.getValue()](./get-value.md), [ctx.setValue()](./set-value.md): read/write current field value
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.model](./model.md): Model where the current execution context is located
+- [ctx.blockModel](./block-model.md): Parent block carrying the current JS
+- [ctx.getValue()](./get-value.md), [ctx.setValue()](./set-value.md): Read and write the current field value