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

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

@@ -1,39 +1,39 @@
 # ctx.resource
 
-The **FlowResource** instance in the current context; used to access and operate on data. In most blocks (form, table, detail, etc.) and popups, the runtime binds `ctx.resource`; in JSBlock and similar contexts that have no resource by default, call [ctx.initResource()](./init-resource.md) first, then use `ctx.resource`.
+The **FlowResource** instance in the current context, used to access and operate on data. In most blocks (Forms, Tables, Details, etc.) and pop-up scenarios, the runtime environment pre-binds `ctx.resource`. In scenarios like JSBlock where there is no resource by default, you must first call [ctx.initResource()](./init-resource.md) to initialize it before using it via `ctx.resource`.
 
-## Use Cases
+## Applicable Scenarios
 
-Use whenever RunJS needs structured data (list, single record, custom API, SQL). Form, table, detail blocks and popups usually have it bound; in JSBlock, JSField, JSItem, JSColumn, etc., call `ctx.initResource(type)` first if you need to load data.
+`ctx.resource` can be used in any RunJS scenario that requires access to structured data (lists, single records, custom APIs, SQL). Forms, Tables, Detail blocks, and pop-ups are typically pre-bound. For JSBlock, JSField, JSItem, JSColumn, etc., if data loading is required, you can call `ctx.initResource(type)` first and then access `ctx.resource`.
 
-## Type
+## Type Definition
 
 ```ts
 resource: FlowResource | undefined;
 ```
 
-- When the context has a bound resource, `ctx.resource` is that instance.
-- In JSBlock etc. it is `undefined` by default; after `ctx.initResource(type)` it is set.
+- In contexts with pre-binding, `ctx.resource` is the corresponding resource instance.
+- In scenarios like JSBlock where there is no resource by default, it is `undefined` until `ctx.initResource(type)` is called.
 
-## Common methods
+## Common Methods
 
-Different resource types (MultiRecordResource, SingleRecordResource, APIResource, SQLResource) expose slightly different APIs; common ones:
+Methods exposed by different resource types (MultiRecordResource, SingleRecordResource, APIResource, SQLResource) vary slightly. Below are the universal or commonly used methods:
 
 | Method | Description |
-|--------|-------------|
-| `getData()` | Current data (list or single record) |
+|------|------|
+| `getData()` | Get current data (list or single record) |
 | `setData(value)` | Set local data |
-| `refresh()` | Refetch with current params |
-| `setResourceName(name)` | Set resource name (e.g. `'users'`, `'users.tags'`) |
-| `setFilterByTk(tk)` | Set primary key filter (single get, etc.) |
-| `runAction(actionName, options)` | Call any resource action (e.g. `create`, `update`) |
-| `on(event, callback)` / `off(event, callback)` | Subscribe/unsubscribe (e.g. `refresh`, `saved`) |
+| `refresh()` | Initiate a request with current parameters to refresh data |
+| `setResourceName(name)` | Set resource name (e.g., `'users'`, `'users.tags'`) |
+| `setFilterByTk(tk)` | Set primary key filter (for single record `get`, etc.) |
+| `runAction(actionName, options)` | Call any resource action (e.g., `create`, `update`) |
+| `on(event, callback)` / `off(event, callback)` | Subscribe/unsubscribe to events (e.g., `refresh`, `saved`) |
 
-**MultiRecordResource**: `getSelectedRows()`, `destroySelectedRows()`, `setPage()`, `next()`, `previous()`, etc.
+**MultiRecordResource Specific**: `getSelectedRows()`, `destroySelectedRows()`, `setPage()`, `next()`, `previous()`, etc.
 
 ## Examples
 
-### List (after initResource)
+### List Data (Requires initResource first)
 
 ```js
 ctx.initResource('MultiRecordResource');
@@ -42,7 +42,7 @@ await ctx.resource.refresh();
 const rows = ctx.resource.getData();
 ```
 
-### Table (pre-bound)
+### Table Scenario (Pre-bound)
 
 ```js
 const rows = ctx.resource?.getSelectedRows?.() || [];
@@ -54,7 +54,7 @@ await ctx.resource.destroySelectedRows();
 ctx.message.success(ctx.t('Deleted'));
 ```
 
-### Single record
+### Single Record
 
 ```js
 ctx.initResource('SingleRecordResource');
@@ -64,29 +64,29 @@ await ctx.resource.refresh();
 const record = ctx.resource.getData();
 ```
 
-### Custom action
+### Calling a Custom Action
 
 ```js
-await ctx.resource.runAction('create', { data: { name: 'John' } });
+await ctx.resource.runAction('create', { data: { name: 'John Doe' } });
 ```
 
-## Relation to ctx.initResource / ctx.makeResource
+## Relationship with ctx.initResource / ctx.makeResource
 
-- **ctx.initResource(type)**: Creates and binds if missing; otherwise returns existing. Ensures `ctx.resource` is set.
-- **ctx.makeResource(type)**: Creates a new instance and returns it; **does not** set `ctx.resource`. Use when you need multiple resources or a temporary one.
-- **ctx.resource**: The bound resource in the current context. Most blocks/popups have it; when not bound it is `undefined` and you must call `ctx.initResource` first.
+- **ctx.initResource(type)**: If `ctx.resource` does not exist, it creates and binds one; if it already exists, it returns the existing instance. This ensures `ctx.resource` is available.
+- **ctx.makeResource(type)**: Creates a new resource instance and returns it, but does **not** write it to `ctx.resource`. This is suitable for scenarios requiring multiple independent resources or temporary usage.
+- **ctx.resource**: Accesses the resource already bound to the current context. Most blocks/pop-ups are pre-bound; otherwise, it is `undefined` and requires `ctx.initResource`.
 
 ## Notes
 
-- Prefer null checks: `ctx.resource?.refresh()`, especially in JSBlock and similar contexts.
-- After init, call `setResourceName(name)` then `refresh()` to load data.
-- See the resource type docs for full API.
+- It is recommended to perform a null check before use: `ctx.resource?.refresh()`, especially in scenarios like JSBlock where pre-binding might not exist.
+- After initialization, you must call `setResourceName(name)` to specify the collection before loading data via `refresh()`.
+- For the full API of each Resource type, see the links below.
 
 ## Related
 
-- [ctx.initResource()](./init-resource.md): init and bind resource
-- [ctx.makeResource()](./make-resource.md): create resource without binding
-- [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 a resource to the current context
+- [ctx.makeResource()](./make-resource.md) - Create a new resource instance without binding it to `ctx.resource`
+- [MultiRecordResource](../resource/multi-record-resource.md) - Multiple records/Lists
+- [SingleRecordResource](../resource/single-record-resource.md) - Single record
+- [APIResource](../resource/api-resource.md) - General API resource
+- [SQLResource](../resource/sql-resource.md) - SQL query resource

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

@@ -1,74 +1,76 @@
 # ctx.route
 
-Current route match info, corresponding to React Router’s route; used to get the matched route config, params, etc. Use with `ctx.router` and `ctx.location`.
+The current route matching information, corresponding to the `route` concept in React Router. It is used to retrieve the current matching route configuration, parameters, and more. It is typically used in conjunction with `ctx.router` and `ctx.location`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField** | Conditional render or display based on `route.pathname` or `route.params` |
-| **Linkage / event flow** | Read route params (e.g. `params.name`) for logic or pass to children |
-| **View navigation** | Compare `ctx.route.pathname` with target path to decide `ctx.router.navigate` |
+|------|------|
+| **JSBlock / JSField** | Perform conditional rendering or display the current page identifier based on `route.pathname` or `route.params`. |
+| **Linkage Rules / FlowEngine** | Read route parameters (e.g., `params.name`) for logic branching or to pass them to child components. |
+| **View Navigation** | Internally compare `ctx.route.pathname` with a target path to determine whether to trigger `ctx.router.navigate`. |
 
-> Note: `ctx.route` is only available in RunJS when a router context exists (e.g. JSBlock on a page, Flow page); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
+> Note: `ctx.route` is only available in RunJS environments that contain a routing context (such as JSBlocks within a page, Flow pages, etc.). It may be null in pure backend or non-routing contexts (such as background workflows).
 
-## Type
+## Type Definition
 
 ```ts
 type RouteOptions = {
-  name?: string;
-  path?: string;
-  params?: Record<string, any>;
-  pathname?: string;
+  name?: string;   // Unique route identifier
+  path?: string;   // Route template (e.g., /admin/:name)
+  params?: Record<string, any>;  // Route parameters (e.g., { name: 'users' })
+  pathname?: string;  // Full path of the current route (e.g., /admin/users)
 };
 ```
 
-## Common fields
+## Common Fields
 
 | Field | Type | Description |
-|-------|------|-------------|
-| `pathname` | `string` | Full path of current route; same as `ctx.location.pathname` |
-| `params` | `Record<string, any>` | Dynamic params from route template, e.g. `{ name: 'users' }` |
-| `path` | `string` | Route template, e.g. `/admin/:name` |
-| `name` | `string` | Route unique id; often used for tabs/views |
+|------|------|------|
+| `pathname` | `string` | The full path of the current route, consistent with `ctx.location.pathname`. |
+| `params` | `Record<string, any>` | Dynamic parameters parsed from the route template, such as `{ name: 'users' }`. |
+| `path` | `string` | The route template, such as `/admin/:name`. |
+| `name` | `string` | Unique route identifier, commonly used in multi-tab or multi-view scenarios. |
 
-## Relation to ctx.router, ctx.location
+## Relationship with ctx.router and ctx.location
 
-| Use | Recommended |
-|-----|-------------|
-| **Current path** | `ctx.route.pathname` or `ctx.location.pathname`; they match when route is matched |
-| **Route params** | `ctx.route.params`, e.g. `params.name` for current page UID |
-| **Navigate** | `ctx.router.navigate(path)` |
-| **Query params, state** | `ctx.location.search`, `ctx.location.state` |
+| Purpose | Recommended Usage |
+|------|----------|
+| **Read current path** | `ctx.route.pathname` or `ctx.location.pathname`; both are consistent during matching. |
+| **Read route parameters** | `ctx.route.params`, e.g., `params.name` representing the current page UID. |
+| **Navigation** | `ctx.router.navigate(path)` |
+| **Read query parameters, state** | `ctx.location.search`, `ctx.location.state` |
 
-`ctx.route` is “matched route config”; `ctx.location` is “current URL”; together they describe the current route state.
+`ctx.route` focuses on the "matched route configuration," while `ctx.location` focuses on the "current URL location." Together, they provide a complete description of the current routing state.
 
 ## Examples
 
-### Read pathname
+### Reading pathname
 
 ```ts
-ctx.message.info('Current page: ' + ctx.route.pathname);
+// Display the current path
+ctx.message.info('Current Page: ' + ctx.route.pathname);
 ```
 
-### Branch by params
+### Branching based on params
 
 ```ts
+// params.name is typically the current page UID (e.g., a Flow page identifier)
 if (ctx.route.params?.name === 'users') {
-  // On user management page
+  // Execute specific logic on the user management page
 }
 ```
 
-### In Flow page
+### Displaying in a Flow page
 
 ```tsx
 <div>
-  <h1>Current page - {ctx.route.pathname}</h1>
-  <p>Route id: {ctx.route.params?.name}</p>
+  <h1>Current Page - {ctx.route.pathname}</h1>
+  <p>Route Identifier: {ctx.route.params?.name}</p>
 </div>
 ```
 
 ## Related
 
-- [ctx.router](./router.md): navigation; after `ctx.router.navigate()`, `ctx.route` updates
-- [ctx.location](./location.md): current URL (pathname, search, hash, state); use with `ctx.route`
+- [ctx.router](./router.md): Route navigation. When `ctx.router.navigate()` changes the path, `ctx.route` will update accordingly.
+- [ctx.location](./location.md): Current URL location (pathname, search, hash, state), used in conjunction with `ctx.route`.

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

@@ -1,31 +1,31 @@
 # ctx.router
 
-Router instance based on React Router; used for programmatic navigation in RunJS. Use with `ctx.route` and `ctx.location`.
+A router instance based on React Router, used for programmatic navigation within RunJS. It is typically used in conjunction with `ctx.route` and `ctx.location`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField** | Button navigates to detail, list, or external link |
-| **Linkage / event flow** | After submit success, `navigate` to list or detail, or pass state to target |
-| **JSAction / event handler** | Navigate on form submit, link click, etc. |
-| **View navigation** | Update URL when switching views |
+|------|------|
+| **JSBlock / JSField** | Navigate to detail pages, list pages, or external links after a button click. |
+| **Linkage Rules / Event Flow** | Execute `navigate` to a list or detail page after successful submission, or pass `state` to the target page. |
+| **JSAction / Event Handling** | Execute route navigation within logic such as form submissions or link clicks. |
+| **View Navigation** | Update the URL via `navigate` during internal view stack switching. |
 
-> Note: `ctx.router` is only available in RunJS when a router context exists (e.g. JSBlock on a page, Flow page, event flow); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
+> Note: `ctx.router` is only available in RunJS environments with a routing context (e.g., JSBlock within a page, Flow pages, event flows, etc.); it may be null in pure backend or non-routing contexts (e.g., Workflows).
 
-## Type
+## Type Definition
 
 ```typescript
 router: Router
 ```
 
-`Router` is from `@remix-run/router`; use `ctx.router.navigate()` for navigation, back, refresh.
+`Router` is derived from `@remix-run/router`. In RunJS, navigation operations such as jumping, going back, and refreshing are implemented via `ctx.router.navigate()`.
 
 ## Methods
 
 ### ctx.router.navigate()
 
-Navigate to a path, or go back/refresh.
+Navigates to a target path, or executes a back/refresh action.
 
 **Signature:**
 
@@ -35,65 +35,77 @@ navigate(to: string | number | null, options?: RouterNavigateOptions): Promise<v
 
 **Parameters:**
 
-- `to`: Target path (string), relative history position (number, e.g. `-1` for back), or `null` (refresh current page)
-- `options`:
-  - `replace?: boolean`: Replace current history entry (default `false`, i.e. push)
-  - `state?: any`: State passed to the target route. Not in URL; target page reads it via `ctx.location.state`. Use for sensitive or temporary data.
+- `to`: Target path (string), relative history position (number, e.g., `-1` to go back), or `null` (to refresh the current page).
+- `options`: Optional configuration.
+  - `replace?: boolean`: Whether to replace the current history entry (default is `false`, which pushes a new entry).
+  - `state?: any`: State to pass to the target route. This data does not appear in the URL and can be accessed via `ctx.location.state` on the target page. It is suitable for sensitive information, temporary data, or information that should not be placed in the URL.
 
 ## Examples
 
-### Basic navigation
+### Basic Navigation
 
 ```ts
+// Navigate to the user list (pushes a new history entry, allows going back)
 ctx.router.navigate('/admin/users');
 
+// Navigate to a detail page
 ctx.router.navigate(`/admin/users/${recordId}`);
 ```
 
-### Replace (no new history entry)
+### Replacing History (No new entry)
 
 ```ts
+// Redirect to the home page after login; the user won't return to the login page when going back
 ctx.router.navigate('/admin', { replace: true });
 
+// Replace the current page with the detail page after successful form submission
 ctx.router.navigate(`/admin/users/${newId}`, { replace: true });
 ```
 
-### Pass state
+### Passing State
 
 ```ts
+// Carry data during navigation; the target page retrieves it via ctx.location.state
 ctx.router.navigate('/admin/users/123', { 
   state: { from: 'dashboard', tab: 'profile' } 
 });
 ```
 
-### Back and refresh
+### Back and Refresh
 
 ```ts
+// Go back one page
 ctx.router.navigate(-1);
 
+// Go back two pages
 ctx.router.navigate(-2);
 
+// Refresh the current page
 ctx.router.navigate(null);
 ```
 
-## Relation to ctx.route, ctx.location
+## Relationship with ctx.route and ctx.location
 
-| Use | Recommended |
-|-----|-------------|
-| **Navigate** | `ctx.router.navigate(path)` |
-| **Current path** | `ctx.route.pathname` or `ctx.location.pathname` |
-| **State from navigation** | `ctx.location.state` |
-| **Route params** | `ctx.route.params` |
+| Purpose | Recommended Usage |
+|------|----------|
+| **Navigation/Jumping** | `ctx.router.navigate(path)` |
+| **Read current path** | `ctx.route.pathname` or `ctx.location.pathname` |
+| **Read state passed during navigation** | `ctx.location.state` |
+| **Read route parameters** | `ctx.route.params` |
 
-`ctx.router` does “navigation”; `ctx.route` and `ctx.location` describe “current route state”.
+`ctx.router` is responsible for "navigation actions," while `ctx.route` and `ctx.location` are responsible for the "current route state."
 
 ## Notes
 
-- `navigate(path)` by default pushes a new history entry; user can use browser back.
-- `replace: true` replaces the current entry; use after login redirect, submit-success redirect, etc.
-- **`state`**: Data in `state` is not in the URL; target page reads it via `ctx.location.state`. State is stored in history (back/forward keep it); it is lost on page refresh.
+- `navigate(path)` pushes a new history entry by default, allowing users to return via the browser's back button.
+- `replace: true` replaces the current history entry without adding a new one, which is suitable for scenarios like post-login redirection or navigation after successful submission.
+- **Regarding the `state` parameter**:
+  - Data passed via `state` does not appear in the URL, making it suitable for sensitive or temporary data.
+  - It can be accessed via `ctx.location.state` on the target page.
+  - `state` is saved in the browser history and remains accessible during forward/backward navigation.
+  - `state` will be lost after a hard page refresh.
 
 ## Related
 
-- [ctx.route](./route.md): current route match (pathname, params)
-- [ctx.location](./location.md): current URL; read `state` here after navigation
+- [ctx.route](./route.md): Current route match information (pathname, params, etc.).
+- [ctx.location](./location.md): Current URL location (pathname, search, hash, state); `state` is read here after navigation.

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

@@ -1,29 +1,29 @@
 # ctx.setValue()
 
-In JSField, JSItem, and other editable field contexts, sets the current field’s value. Use with `ctx.getValue()` for two-way binding with the form.
+Sets the value of the current field in editable field scenarios such as JSField and JSItem. Combined with `ctx.getValue()`, it enables two-way binding with the form.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField** | Write user selection or computed value in editable custom fields |
-| **JSItem** | Update current cell value in table/sub-table editable items |
-| **JSColumn** | Update row field value when rendering a column |
+|------|------|
+| **JSField** | Write user-selected or calculated values into editable custom fields. |
+| **JSItem** | Update the current cell value in editable items of tables/sub-tables. |
+| **JSColumn** | Update the field value of the corresponding row based on logic during table column rendering. |
 
-> Note: `ctx.setValue(v)` is only available in RunJS contexts with form binding; in event flow, linkage, JSBlock, etc. (no field binding) the method may not exist—use optional chaining: `ctx.setValue?.(value)`.
+> **Note**: `ctx.setValue(v)` is only available in RunJS contexts with form binding. It is not available in scenarios without field binding, such as FlowEngine, linkage rules, or JSBlock. It is recommended to use optional chaining before use: `ctx.setValue?.(value)`.
 
-## Type
+## Type Definition
 
 ```ts
 setValue<T = any>(value: T): void;
 ```
 
-- **Parameter**: `value` is the value to write; type depends on the field’s form item type.
+- **Parameters**: `value` is the field value to be written. The type is determined by the form item type of the field.
 
 ## Behavior
 
-- `ctx.setValue(v)` updates the current field’s value in the Ant Design Form and triggers linkage and validation.
-- If the form is not yet rendered or the field is not registered, the call may have no effect; use `ctx.getValue()` to confirm.
+- `ctx.setValue(v)` updates the value of the current field in the Ant Design Form and triggers related form linkage and validation logic.
+- If the form has not finished rendering or the field is not registered, the call may be ineffective. It is recommended to use `ctx.getValue()` to confirm the write result.
 
 ## Examples
 
@@ -42,7 +42,7 @@ ctx.render(
 );
 ```
 
-### Set default by condition
+### Setting default values based on conditions
 
 ```ts
 const status = ctx.getValue();
@@ -51,9 +51,10 @@ if (status == null || status === '') {
 }
 ```
 
-### Write current field when linking others
+### Writing back to the current field when linked to other fields
 
 ```ts
+// Synchronously update the current field when another field changes
 const otherValue = ctx.form?.getFieldValue('type');
 if (otherValue === 'custom') {
   ctx.setValue?.({ label: 'Custom', value: 'custom' });
@@ -62,11 +63,11 @@ if (otherValue === 'custom') {
 
 ## Notes
 
-- In non-editable contexts (e.g. JSField detail mode, JSBlock), `ctx.setValue` may be `undefined`; use `ctx.setValue?.(value)`.
-- For association fields (m2o, o2m, etc.), pass a value that matches the field type (e.g. `{ id, [titleField]: label }`); see field config.
+- In non-editable fields (e.g., JSField in Read-only Mode, JSBlock), `ctx.setValue` may be `undefined`. It is recommended to use `ctx.setValue?.(value)` to avoid errors.
+- When setting values for association fields (M2O, O2M, etc.), you need to pass a structure that matches the field type (e.g., `{ id, [titleField]: label }`), depending on the specific field configuration.
 
 ## Related
 
-- [ctx.getValue()](./get-value.md): get current field value; use with setValue for two-way binding
-- [ctx.form](./form.md): Ant Design Form; read/write other fields
-- `js-field:value-change`: container event when value changes from outside; use to update display
+- [ctx.getValue()](./get-value.md) - Get the current field value, used with setValue for two-way binding.
+- [ctx.form](./form.md) - Ant Design Form instance, used to read or write other fields.
+- `js-field:value-change` - A container event triggered when an external value changes, used to update the display.

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

@@ -74,7 +74,7 @@ interface FlowSQLRepository {
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `bind` | `Record<string, any>` \| `any[]` | Bound variables. Object with `:name`, array with `?` |
+| `bind` | `Record<string, any>` | Bound variables. Use `$name` in SQL and pass object `{ name: value }` |
 | `type` | `'selectRows'` \| `'selectRow'` \| `'selectVar'` | Result type: multiple rows, single row, single value; default `selectRows` |
 | `dataSourceKey` | `string` | Data source key; default is main data source |
 | `filter` | `Record<string, any>` | Extra filter (if supported) |
@@ -84,7 +84,7 @@ interface FlowSQLRepository {
 | Option | Type | Description |
 |--------|------|-------------|
 | `uid` | `string` | Template unique id; use with `runById(uid, ...)` |
-| `sql` | `string` | SQL text; supports `{{ctx.xxx}}` and `:name` / `?` placeholders |
+| `sql` | `string` | SQL text; supports `{{ctx.xxx}}` and `$name` placeholders |
 | `dataSourceKey` | `string` | Optional data source key |
 
 ## Template Variables and Parameter Binding
@@ -105,21 +105,13 @@ Variable sources are the same as for `ctx.getVar()` (e.g. `ctx.user.*`, `ctx.rec
 
 ### Parameter binding
 
-- **Named**: use `:name` in SQL and pass `bind: { name: value }`
-- **Positional**: use `?` in SQL and pass `bind: [value1, value2]`
+- Use `$name` in SQL and pass `bind: { name: value }`
 
 ```js
-// Named
 const users = await ctx.sql.run(
-  'SELECT * FROM users WHERE status = :status AND age > :minAge',
+  'SELECT * FROM users WHERE status = $status AND age > $minAge',
   { bind: { status: 'active', minAge: 18 }, type: 'selectRows' }
 );
-
-// Positional
-const count = await ctx.sql.run(
-  'SELECT COUNT(*) AS total FROM users WHERE city = ? AND status = ?',
-  { bind: ['Beijing', 'active'], type: 'selectVar' }
-);
 ```
 
 ## Examples
@@ -132,7 +124,7 @@ const rows = await ctx.sql.run('SELECT * FROM users LIMIT 10');
 
 // Single row
 const user = await ctx.sql.run(
-  'SELECT * FROM users WHERE id = :id',
+  'SELECT * FROM users WHERE id = $id',
   { bind: { id: 1 }, type: 'selectRow' }
 );
 
@@ -160,7 +152,7 @@ const rows = await ctx.sql.run(
 // Save (requires SQL config permission)
 await ctx.sql.save({
   uid: 'active-users-report',
-  sql: 'SELECT * FROM users WHERE status = :status ORDER BY created_at DESC',
+  sql: 'SELECT * FROM users WHERE status = $status ORDER BY created_at DESC',
 });
 
 // Any logged-in user can run
@@ -197,7 +189,7 @@ const meta = ctx.resource.getMeta();  // page, pageSize, etc.
 
 ## Notes
 
-- Use parameter binding (`:name` / `?`) instead of string concatenation to avoid SQL injection.
+- Use parameter binding (`$name`) instead of string concatenation to avoid SQL injection.
 - With `type: 'selectVar'` the result is a scalar (e.g. for `COUNT`, `SUM`).
 - Template variables `{{ctx.xxx}}` are resolved before execution; ensure the context defines them.
 

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

@@ -1,12 +1,12 @@
 # ctx.t()
 
-i18n helper in RunJS for translating copy; uses the current context’s language. Use for buttons, titles, hints, etc.
+An i18n shortcut function used in RunJS to translate text based on the current context's language settings. It is suitable for internationalizing inline copy such as buttons, titles, and prompts.
 
 ## Use Cases
 
-Available in all RunJS environments.
+`ctx.t()` can be used in all RunJS execution environments.
 
-## Type
+## Type Definition
 
 ```ts
 t(key: string, options?: Record<string, any>): string
@@ -16,35 +16,38 @@ t(key: string, options?: Record<string, any>): string
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `key` | `string` | Translation key or template with placeholders (e.g. `Hello {{name}}`, `{{count}} rows`) |
-| `options` | `object` | Optional. Interpolation (e.g. `{ name: 'John', count: 5 }`) or i18n options (`defaultValue`, `ns`) |
+| `key` | `string` | Translation key or template with placeholders (e.g., `Hello {{name}}`, `{{count}} rows`). |
+| `options` | `object` | Optional. Interpolation variables (e.g., `{ name: 'John', count: 5 }`), or i18n options (e.g., `defaultValue`, `ns`). |
 
-## Returns
+## Return Value
 
-- Translated string; if key has no translation and no `defaultValue`, may return the key or the interpolated string.
+- Returns the translated string. If no translation exists for the key and no `defaultValue` is provided, it may return the key itself or the interpolated string.
 
 ## Namespace (ns)
 
-RunJS **default namespace is `runjs`**. Without `ns`, `ctx.t(key)` looks up the key in the `runjs` namespace.
+The **default namespace for the RunJS environment is `runjs`**. When `ns` is not specified, `ctx.t(key)` will look up the key in the `runjs` namespace.
 
 ```ts
-ctx.t('Submit');  // same as ctx.t('Submit', { ns: 'runjs' })
+// Looks up key from the 'runjs' namespace by default
+ctx.t('Submit'); // Equivalent to ctx.t('Submit', { ns: 'runjs' })
 
+// Looks up key from a specific namespace
 ctx.t('Submit', { ns: 'myModule' });
 
+// Searches multiple namespaces sequentially (first 'runjs', then 'common')
 ctx.t('Save', { ns: ['runjs', 'common'] });
 ```
 
 ## Examples
 
-### Simple key
+### Simple Key
 
 ```ts
 ctx.t('Submit');
 ctx.t('No data');
 ```
 
-### With interpolation
+### With Interpolation Variables
 
 ```ts
 const text = ctx.t('Hello {{name}}', { name: ctx.user?.nickname || 'Guest' });
@@ -55,14 +58,14 @@ ctx.render(`<div>${text}</div>`);
 ctx.message.success(ctx.t('Processed {{count}} rows', { count: rows.length }));
 ```
 
-### Relative time etc.
+### Dynamic Copy (e.g., Relative Time)
 
 ```ts
 if (minutes < 60) return ctx.t('{{count}} minutes ago', { count: minutes });
 if (hours < 24) return ctx.t('{{count}} hours ago', { count: hours });
 ```
 
-### Specify namespace
+### Specifying a Namespace
 
 ```ts
 ctx.t('Hello {{name}}', { name: 'Guest', ns: 'myModule' });
@@ -70,10 +73,10 @@ ctx.t('Hello {{name}}', { name: 'Guest', ns: 'myModule' });
 
 ## Notes
 
-- **Localization plugin**: Activate the localization plugin to manage translations. Missing keys can be collected for translation.
-- i18next-style interpolation: use `{{varName}}` in the key and pass the same name in `options`.
-- Language comes from the current context (e.g. `ctx.i18n.language`, user locale).
+- **Localization Plugin**: To translate text, the Localization plugin must be activated. Missing translation keys will be automatically extracted to the localization management list for unified maintenance and translation.
+- Supports i18next-style interpolation: Use `{{variableName}}` in the key and pass the corresponding variable in `options` to replace it.
+- The language is determined by the current context (e.g., `ctx.i18n.language`, user locale).
 
 ## Related
 
-- [ctx.i18n](./i18n.md): read or change language
+- [ctx.i18n](./i18n.md): Read or switch languages