@nocobase/plugin-ai 2.2.0-beta.14 → 2.2.0-beta.15

package/client-v2.d.ts

@@ -1 +1,2 @@
 export * from './dist/client-v2';
+export { default } from './dist/client-v2';

package/dist/ai/docs/nocobase/interface-builder/blocks/data-blocks/comment.md

@@ -0,0 +1,107 @@
+---
+pkg: "@nocobase/plugin-block-comment"
+title: "Comment Block"
+description: "Comment block: view and create comments in record details, pop-ups, and similar scenarios, with field mapping, pagination, data scope, default sorting, and auto jump to last page."
+keywords: "Comment Block,CommentBlock,comment collection,field mapping,data scope,default sorting,interface builder,NocoBase"
+---
+
+# Comment Block
+
+## Introduction
+
+The Comment block adds commenting capabilities to business records. You can add it to detail pages or pop-ups for tasks, articles, tickets, customers, and other records, so users can view, reply to, and create comments around the current record.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_02_PM.png)
+
+:::tip
+
+The Comment block does not create a collection by itself. Before using it, prepare a collection for storing comments and configure fields such as comment content, commenter, comment owner, and comment time.
+
+:::
+
+## Add a block
+
+The Comment block is usually added to the detail page or pop-up of a business record.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_03_PM.png)
+
+1. Open the target record detail page or pop-up
+2. Click "Add block"
+3. Select "Comment"
+4. Select the collection used to store comments
+5. Complete field mapping as prompted
+
+If the Comment block is created from an association, NocoBase will try to automatically identify the comment owner field and the current record value based on the current association. In this case, "Comment owner field" and "Comment owner field value" are filled automatically, and usually do not need manual configuration.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_04_PM.png)
+
+If the block is created directly from the comment collection, you need to manually configure the comment owner field and value.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_03_PM%20(1).png)
+
+## Field mapping
+
+The Comment block uses "Field mapping" to know how each comment should be displayed and saved.
+
+| Configuration | Description |
+| --- | --- |
+| Comment content field | Select the field used to store the comment body. |
+| Commenter field | Select a many-to-one field associated with the users collection. |
+| Comment owner field | Select the field used to store the current business record identifier. |
+| Comment owner field value | Specify the current business record value, such as `{{ ctx.popup.record.id }}`. |
+| Comment date field | Select the comment time field, used for display and default sorting. |
+
+### Comment owner field
+
+"Comment owner field" is used to filter comments for the current record, and is also written when a new comment is created.
+
+When selected manually, the dropdown only shows ordinary scalar fields and does not show association fields. Common configurations are:
+
+| Business collection | Owner field in comment collection | Comment owner field value |
+| --- | --- | --- |
+| Tasks | `taskId` | `{{ ctx.popup.record.id }}` |
+| Articles | `postId` | `{{ ctx.popup.record.id }}` |
+| Tickets | `ticketId` | `{{ ctx.popup.record.id }}` |
+
+If the current record uses a unique identifier other than `id`, change "Comment owner field value" to the corresponding field, such as `{{ ctx.popup.record.uuid }}`.
+
+### Automatic mapping from associations
+
+If the block is created from an association of the business record, the Comment block prioritizes the foreign key field of that association as the comment owner field, and uses the current record value as the comment owner field value.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_04_PM.png)
+
+For example, if there is a one-to-many association between the task collection and the task comment collection, and the foreign key field in the task comment collection is `taskId`, then when you add a Comment block from the association in the task detail page, the block automatically uses:
+
+- Comment owner field: `taskId`
+- Comment owner field value: the identifier of the current task record
+
+This approach is suitable for most scenarios and reduces manual configuration errors.
+
+## Block settings
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_07_PM.png)
+
+### Page size
+
+Set how many comments are displayed on each page. Available values include `5`, `10`, `20`, `50`, `100`, and `200`.
+
+### Data scope
+
+Set the data filtering scope for the comment list. You can add more conditions here, such as showing only comments that match certain status or permission conditions.
+
+For more details, see [Set data scope](../block-settings/data-scope.md).
+
+### Default sorting rule
+
+Set the default sorting rule for the comment list. Usually, you can sort by the comment date field in ascending or descending order.
+
+If no default sorting rule is configured separately, the Comment block prioritizes the "Comment date field" as the default sorting field.
+
+For more details, see [Set sorting rule](../block-settings/sorting-rule.md).
+
+### Auto jump to last page
+
+Disabled by default. When disabled, the Comment block stays on the first page after opening.
+
+When enabled, the Comment block jumps to the last page on first load. This is suitable when you want users to see the latest comments first.

package/dist/ai/docs/nocobase/interface-builder/index.md

@@ -16,12 +16,9 @@ Edit mode:
 ![20251023215951](https://static-docs.nocobase.com/20251023215951.png)
 
 
-## Layout Template
+## UI Layout
 
-NocoBase ships with a default layout template: navigation on the top and left, and a content area on the right.
-
-
-![未命名.002](https://static-docs.nocobase.com/未命名.002.jpeg)
+NocoBase provides desktop and mobile layouts. The desktop layout works well for standard administration and adapts its navigation and page content on phones. The mobile layout provides separate mobile navigation and page configuration. See [UI Layout](./ui-layout/index.md) for details.
 
 
 ## Configuration Options
@@ -55,4 +52,8 @@ Action configuration options:
 Table column configuration options:
 
 
-![20251023221814](https://static-docs.nocobase.com/20251023221814.png)
+![20251023221814](https://static-docs.nocobase.com/20251023221814.png)
+
+## Related links
+
+- [UI Layout](./ui-layout/index.md) — Learn about desktop and mobile layouts

package/dist/ai/docs/nocobase/interface-builder/ui-layout/desktop.md

@@ -0,0 +1,97 @@
+---
+title: "Desktop Layout"
+description: "Learn about the navigation structure, page building, route management, and narrow-screen responsive behavior of the NocoBase desktop layout."
+keywords: "desktop layout,UI layout,narrow-screen responsive,page building,route management,UI Editor,NocoBase"
+---
+
+# Desktop Layout
+
+In NocoBase, the **desktop layout** is the default application interface. It is designed for data management, form entry, business configuration, and everyday work on a computer, and can also be used on mobile devices.
+
+The desktop layout is available at `/admin` by default. If the application has its own access prefix, the actual URL automatically includes that prefix.
+
+![20260715224020](https://static-docs.nocobase.com/20260715224020.png)
+
+![20260715224603](https://static-docs.nocobase.com/20260715224603.png)
+
+## Build a page
+
+### Step 1: Open the desktop layout
+
+Visit `/admin` to open the desktop layout. After signing in, the application usually opens this layout directly.
+
+![20260715225049](https://static-docs.nocobase.com/20260715225049.png)
+
+### Step 2: Open UI Editor
+
+Click 「UI Editor」 in the upper-right corner of the page to enter UI building mode. Configuration entries then appear around menus, pages, blocks, fields, and actions.
+
+![20260715225155_rec_](https://static-docs.nocobase.com/20260715225155_rec_.gif)
+
+### Step 3: Create menus and pages
+
+You can add groups, pages, or links in the navigation area, and enable tabs for a page. After creating a page, open it and add the blocks you need.
+
+Page content is built in the same way as other interfaces: add [blocks](../blocks/index.md) first, then configure [fields](../fields/index.md) and [actions](../actions/index.md) for your business needs.
+
+![20260715225316_rec_](https://static-docs.nocobase.com/20260715225316_rec_.gif)
+
+### Step 4: Configure page content
+
+Add table, form, details, filter, or other blocks to the page, then adjust the fields, actions, and arrangement of the blocks. Each change is reflected directly on the current page.
+
+![20260715225424_rec_](https://static-docs.nocobase.com/20260715225424_rec_.gif)
+
+## Manage routes and menus
+
+When you add a page or link in the navigation area, it also appears in the [Route Manager](../../routes/index.md). Changes made in the Route Manager also update the menu.
+
+The desktop layout supports these common route types:
+
+- **Group** — Organizes multiple pages and links under the same navigation group.
+- **Page** — Opens a page where you can continue adding blocks.
+- **Link** — Opens an internal or external URL.
+- **Tab** — Organizes multiple content tabs within a page.
+
+In the Route Manager, you can add, edit, delete, show, or hide routes. It is often the more convenient place to reorganize the entire menu structure.
+
+![20260715225711_rec_](https://static-docs.nocobase.com/20260715225711_rec_.gif)
+
+## Responsive behavior on narrow screens
+
+The desktop layout can be used directly on a phone or in a narrow browser window. In narrow-screen mode, it still uses the same desktop routes and pages. It does not automatically switch to the mobile layout.
+
+### Layout changes
+
+The navigation menu collapses, and top actions move into a more compact entry. Page margins and spacing between blocks also shrink, while the content area adapts to the visible height of the mobile browser.
+
+UI Editor is not available on narrow screens. To change menus or pages, you need to return to a desktop browser and make the changes there.
+
+![20260715224603](https://static-docs.nocobase.com/20260715224603.png)
+
+### How page content adapts
+
+Common components also adjust their interactions for narrow screens, making them easier to use on a phone. For instance, multi-column blocks switch to a single column, tables allow horizontal scrolling for columns that extend beyond the screen, and pagination and action entries become more compact. Selection, date and time, filter, and subpage interactions also use forms that are easier to operate on a phone.
+
+:::tip Desktop responsiveness and the mobile layout
+
+If you only access the application from a phone occasionally, the responsive desktop layout is usually enough. If you need separate bottom navigation, mobile pages, and mobile workflows, build a [mobile layout](./mobile.md) as well.
+
+:::
+
+## Recommendations
+
+- Use the desktop layout by default for work performed mainly on a computer.
+- Finish building the page on a wide screen, then narrow the window to check its responsive behavior.
+- If a page contains many table columns or horizontal actions, keep only the necessary content to reduce the workload on smaller screens.
+- If the desktop and mobile workflows differ significantly, separate pages are usually clearer.
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Mobile layout](./mobile.md) — Build separate mobile navigation and pages
+- [Blocks](../blocks/index.md) — Add and configure blocks on a page
+- [Fields](../fields/index.md) — Configure fields in tables, forms, and details blocks
+- [Actions](../actions/index.md) — Configure actions on pages and blocks
+- [Route Manager](../../routes/index.md) — Manage desktop menus and routes in one place
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which desktop routes each role can access

package/dist/ai/docs/nocobase/interface-builder/ui-layout/index.md

@@ -0,0 +1,50 @@
+---
+title: "UI Layout"
+description: "An overview of NocoBase UI layouts, including desktop and mobile layout features, use cases, and how their configurations relate."
+keywords: "UI layout,desktop layout,mobile layout,responsive layout,mobile pages,NocoBase"
+---
+
+# UI Layout
+
+NocoBase provides desktop and mobile layouts. Both layouts support UI building, so you can create pages and configure blocks, fields, and actions within them.
+
+The desktop layout is the default choice and works well for everyday administration and data processing on a computer. If you need dedicated navigation and pages for mobile devices, you can build a mobile layout as well.
+
+## Desktop layout
+
+The [desktop layout](./desktop.md) is available at `/admin` by default. It consists of top navigation, side navigation, and a page content area, making it suitable for common business scenarios such as managing tables, entering form data, and viewing records.
+
+The desktop layout also supports responsive behavior on narrow screens. When a page is displayed on a smaller screen, the navigation, spacing, and common components adjust to fit while continuing to use the existing desktop menus and pages.
+
+![20260715224020](https://static-docs.nocobase.com/20260715224020.png)
+
+## Mobile layout
+
+The [mobile layout](./mobile.md) is available at `/mobile` by default. It uses a bottom tab bar for primary navigation and provides separate mobile pages, links, and page tabs.
+
+The mobile layout works well for frequent phone-based tasks such as on-site data entry, mobile approvals, task processing, and data lookup. You can build and preview pages in a desktop browser, then use a QR code to check the result on a physical device.
+
+![20260715230725](https://static-docs.nocobase.com/20260715230725.png)
+
+## Which layout should I use?
+
+Use the desktop layout by default.
+
+| I want to... | Recommended layout |
+| --- | --- |
+| Work mainly on a computer and occasionally access pages from a phone | [Desktop layout](./desktop.md) |
+| Design separate navigation, pages, and workflows for phones | [Mobile layout](./mobile.md) |
+| Provide a complete experience for both computers and mobile devices | Build the desktop and mobile layouts separately |
+
+## How the configurations relate
+
+The desktop and mobile layouts use the same data sources and business data. You can use the same data table to build separate pages for different devices.
+
+Menus, routes, and page configurations are maintained separately. Changes to a desktop page do not automatically update its mobile counterpart, and changes to mobile navigation do not affect desktop navigation. [Route access permissions](../../users-permissions/acl/permissions.md) also need to be configured separately for each layout.
+
+## Related links
+
+- [Desktop layout](./desktop.md) — Build desktop pages and learn how they behave on narrow screens
+- [Mobile layout](./mobile.md) — Build separate mobile navigation and pages
+- [Route Manager](../../routes/index.md) — Manage desktop and mobile pages, links, and menus
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which menus and pages each role can access

package/dist/ai/docs/nocobase/interface-builder/ui-layout/mobile.md

@@ -0,0 +1,133 @@
+---
+title: "Mobile Layout"
+description: "Learn about NocoBase mobile navigation, page building, desktop preview, subpage interactions, routes, and permissions."
+keywords: "mobile layout,mobile pages,bottom navigation,mobile preview,mobile routes,UI Editor,NocoBase"
+---
+
+# Mobile Layout
+
+In NocoBase, the **mobile layout** is used to build dedicated navigation and pages for mobile devices. It is available at `/mobile` by default and uses a bottom tab bar as its primary navigation, making it more suitable for data entry, lookup, approval, and task processing on a phone.
+
+The mobile and desktop layouts use the same data sources and business data, but their menus, routes, and page content are configured separately. This lets you reorganize pages around mobile workflows without being constrained by the desktop page structure.
+
+<!-- Add a full-page screenshot of the mobile layout on a physical device -->
+
+## Open and preview the mobile layout
+
+By default, you can click 「Mobile」 in Settings to open the layout, or visit `/mobile` directly.
+
+It is best to build pages in a desktop browser. The desktop view provides a mobile preview area and a toolbar at the top:
+
+- 「UI Editor」 turns UI building mode on or off.
+- 「Tablet preview」 checks the display on wider mobile devices.
+- 「Mobile preview」 restores the phone-sized preview area.
+- 「QR code」 opens the current mobile URL on a phone.
+
+![20260715221712](https://static-docs.nocobase.com/20260715221712.png)
+
+After building the pages on a computer, scan the QR code and check them on a physical device. Pay particular attention to navigation, scrolling, form input, pop-up pages, and safe areas.
+
+## Build mobile navigation
+
+The mobile layout uses a bottom tab bar as its primary navigation. Primary navigation currently supports mainly pages and links.
+
+### Add a page
+
+1. Open 「UI Editor」.
+2. Click the add button on the right side of the bottom tab bar.
+3. Select 「Page」.
+4. Enter a page title and select an icon.
+5. Submit the form to open the new page, then continue adding page content.
+
+![20260715221823_rec_](https://static-docs.nocobase.com/20260715221823_rec_.gif)
+
+### Add a link
+
+To open an internal or external URL, select 「Link」 and configure its title, icon, and URL.
+
+A link can open in the current window or a new window, depending on its configuration.
+
+![20260715221950](https://static-docs.nocobase.com/20260715221950.png)
+
+### Arrange navigation
+
+In UI building mode, drag bottom tabs to reorder them. You can also edit a tab's title and icon, configure linkage rules, copy its UID, or delete it.
+
+To view, show, hide, or delete mobile routes in one place, open 「Settings / Routes / Mobile routes」.
+
+![20260715222113_rec_](https://static-docs.nocobase.com/20260715222113_rec_.gif)
+
+## Build a mobile page
+
+Create and open a mobile page before adding blocks to it. The approach to building page content is essentially the same as on desktop: use [blocks](../blocks/index.md), [fields](../fields/index.md), and [actions](../actions/index.md) to organize business content. However, mobile navigation and some component interactions are adjusted for smaller screens.
+
+### Add page content
+
+1. Open the mobile page you want to build.
+2. Make sure 「UI Editor」 is enabled.
+3. Click 「Add block」 on the page.
+4. Select a table, form, details, filter, or another block.
+5. Continue configuring fields, actions, and block settings.
+
+![20260715222230_rec_](https://static-docs.nocobase.com/20260715222230_rec_.gif)
+
+### Use page tabs
+
+A mobile page can also use tabs. If multiple pieces of content belong under the same navigation entry but remain relatively independent, place them in separate tabs.
+
+1. Open the page settings and enable 「Enable page tabs」. You can also edit the page under 「Settings / Routes / Mobile routes」 and select 「Enable page tabs」.
+2. Turn on 「UI Editor」.
+3. Click 「Add tab」 on the right side of the page tab bar.
+4. Add the tab, then configure its name and page content.
+
+If a mobile page contains only a small amount of content, use a single page. You do not need to enable tabs.
+
+![20260715222354_rec_](https://static-docs.nocobase.com/20260715222354_rec_.gif)
+
+### Mobile interactions for common components
+
+Common components adjust their arrangement and interactions for the mobile layout. For instance, multi-column content automatically switches to a single column that is easier to browse vertically; selection and date-time fields use mobile-friendly pickers; and filters, associated record selection, and subpages use interfaces designed for touch interaction.
+
+Tables remain tables on mobile, with horizontal scrolling for columns that extend beyond the screen. Any additional mobile behavior depends on the support provided by each block.
+
+## Pages and subpages
+
+Content opened from view, edit, associated record selection, and similar actions appears as a mobile subpage. The subpage provides a back button that returns you to the previous page.
+
+When you open a deeper subpage, the bottom tab bar is hidden to leave more room for the current content. It reappears when you close the subpage or return to the previous level.
+
+When switching between bottom tabs, the state of open pages is preserved, making it easier to move between mobile tasks.
+
+![20260715222828_rec_](https://static-docs.nocobase.com/20260715222828_rec_.gif)
+
+## Manage routes and permissions
+
+Mobile routes can be maintained in the [Route Manager](../../routes/index.md). Open 「Settings / Routes / Mobile routes」 to add, edit, delete, show, or hide pages and links, or to configure tabs for a page.
+
+Mobile route access permissions are configured separately from desktop permissions. Under role permissions, open 「Mobile routes」 and select the pages the current role can access. See [Permission configuration](../../users-permissions/acl/permissions.md) for details.
+
+![20260715223016_rec_](https://static-docs.nocobase.com/20260715223016_rec_.gif)
+
+![20260715223106_rec_](https://static-docs.nocobase.com/20260715223106_rec_.gif)
+
+## Relationship with the desktop layout
+
+You can build separate desktop and mobile pages from the same data table. For instance, a desktop page may use a table with many fields for data processing, while a mobile page may use a simpler list or form for on-site data entry.
+
+The two layouts do not synchronize pages automatically. Changes to desktop pages, menus, or routes do not update the mobile configuration, and mobile changes do not affect desktop pages.
+
+:::tip Recommendation
+
+If mobile users only need occasional access to desktop pages, try the responsive [desktop layout](./desktop.md) first. Build a separate mobile layout only when you need dedicated navigation and page workflows for mobile devices.
+
+:::
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Desktop layout](./desktop.md) — Use the default desktop layout and its narrow-screen responsiveness
+- [Blocks](../blocks/index.md) — Add business content to mobile pages
+- [Fields](../fields/index.md) — Configure mobile forms and data display fields
+- [Actions](../actions/index.md) — Configure actions on mobile pages
+- [Route Manager](../../routes/index.md) — Manage mobile pages, links, and tabs
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which mobile routes each role can access

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-block-comment/index.md

@@ -0,0 +1,14 @@
+---
+title: "Block: Comment"
+keywords: "Block: Comment,comment block,comment collection,plugin,NocoBase"
+displayName: "Block: Comment"
+packageName: '@nocobase/plugin-block-comment'
+description: |
+  Provides a Comment block for viewing and creating comments in record details, pop-ups, and similar scenarios.
+isFree: true
+builtIn: true
+defaultEnabled: false
+editionLevel: 0
+---
+
+# Block: Comment

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

@@ -0,0 +1,206 @@
+---
+title: "ctx.ai"
+description: "Use ctx.ai in RunJS to trigger AI employee tasks, either with inline task content or with tasks configured on an AI employee action."
+keywords: "ctx.ai,AI employee,triggerTask,triggerModelTask,RunJS,NocoBase"
+---
+
+# ctx.ai
+
+Use `ctx.ai` in RunJS to trigger **AI employee tasks**. It works well in JSBlock, JSAction, and other interactions where a button, form, or business flow needs to hand work to a specific AI employee.
+
+`ctx.ai` only triggers tasks. It does not return the execution result of the AI employee task. After the call, the task enters the AI employee conversation flow, and the result is handled by the AI employee session.
+
+:::warning Note
+
+`ctx.ai` is provided by the AI plugin. If the AI plugin is not enabled, or the current RunJS environment has not loaded the corresponding client capability, `ctx.ai` may not exist. You can check `ctx.ai?.triggerTask` or `ctx.ai?.triggerModelTask` before calling it.
+
+:::
+
+## Methods
+
+### ctx.ai.triggerTask()
+
+Trigger an AI employee task directly.
+
+```ts
+ctx.ai.triggerTask(options: TriggerTaskOptions): void
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `aiEmployee` | `string \| AIEmployee` | AI employee. When a string is passed, NocoBase matches `AIEmployee.username` exactly, and the AI employee must be accessible to the current user. |
+| `tasks` | `Task[]` | Tasks to trigger. |
+| `open` | `boolean` | Whether to open the AI employee conversation panel. |
+| `auto` | `boolean` | Whether to use the auto-trigger semantics of an AI employee action. |
+
+Common `Task` fields:
+
+| Field | Type | Description |
+|------|------|------|
+| `title` | `string` | Task title. |
+| `message.system` | `string` | System message, used to constrain the AI employee's role and output requirements. |
+| `message.user` | `string` | User message, which is the main instruction for this task. |
+| `message.workContext` | `ContextItem[]` | Page block context used by the task. |
+| `autoSend` | `boolean` | Whether to send the task message automatically. |
+| `webSearch` | `boolean` | Whether Web search is allowed for this task. |
+| `model` | `{ llmService: string; model: string } \| null` | Model used by this task. |
+| `skillSettings` | `SkillSettings` | Skills and tools available to this task. |
+
+### Add Page Block Context
+
+`message.workContext` currently passes page blocks. Put the FlowModel uid of the target page block into it:
+
+```ts
+message: {
+  user: 'Review the current users table and summarize operational risks.',
+  workContext: [
+    {
+      type: 'flow-model',
+      uid: 'USERS_TABLE_BLOCK_UID',
+    },
+  ],
+}
+```
+
+| Field | Description |
+|------|------|
+| `type` | Fixed to `flow-model`, meaning this item is a page block context. |
+| `uid` | FlowModel uid of the page block, such as a table block, detail block, or chart block. |
+
+If you want to use the current JSBlock itself as context, use the current model uid:
+
+```ts
+workContext: [
+  {
+    type: 'flow-model',
+    uid: ctx.model.uid,
+  },
+],
+```
+
+Usually, `message.workContext` should be placed inside the `message` of a concrete task. `triggerModelTask()` reuses the task configured on the target AI employee action, so it also reads `message.workContext` from that task.
+
+### Specify Model
+
+`model` specifies the model for a single task. If omitted, the AI employee's default model configuration is used. Passing `null` means no task-level model is specified.
+
+```ts
+model: {
+  llmService: 'openai-main',
+  model: 'gpt-4.1',
+}
+```
+
+### Configure Skills / Tools
+
+`skillSettings` specifies the skills and tools available to a single task. If omitted, the AI employee's own capability configuration is used.
+
+```ts
+skillSettings: {
+  skillsVersion: 2,
+  toolsVersion: 2,
+  skills: ['business-analysis-report'],
+  tools: ['businessReportGenerator'],
+}
+```
+
+To explicitly disable all skills or tools for this task, pass empty arrays and keep the version fields:
+
+```ts
+skillSettings: {
+  skillsVersion: 2,
+  toolsVersion: 2,
+  skills: [],
+  tools: [],
+}
+```
+
+The following example asks `viz` to generate a handoff brief and opens the AI employee conversation panel:
+
+```ts
+if (!ctx.ai?.triggerTask) {
+  ctx.message.error(ctx.t('AI employee task API is not available.'));
+  return;
+}
+
+ctx.ai.triggerTask({
+  aiEmployee: 'viz',
+  open: true,
+  tasks: [
+    {
+      title: ctx.t('Daily operations handoff brief'),
+      message: {
+        system:
+          'You prepare reusable daily operations handoff briefs. Focus on risks, blockers, decisions, owners, and next actions.',
+        user: [
+          "Prepare today's operations handoff brief.",
+          'Cover customer escalations, SLA risks, approvals, and follow-up owners.',
+          'Return a concise brief that can be posted to the team channel.',
+        ].join('\n'),
+      },
+      autoSend: true,
+      webSearch: false,
+    },
+  ],
+});
+
+ctx.message.success(ctx.t('AI employee task triggered.'));
+```
+
+If `aiEmployee` is a string, NocoBase matches accessible AI employees by `username` exactly. If no match is found, the task is not triggered and a warning is printed to the console.
+
+### ctx.ai.triggerModelTask()
+
+Read a task from an AI employee action model on the page and trigger it.
+
+```ts
+ctx.ai.triggerModelTask(uid: string, taskIndex: number, options?: TriggerModelTaskOptions): void
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `uid` | `string` | FlowModel uid of the AI employee action. |
+| `taskIndex` | `number` | Task index, starting from `0`. |
+| `options.open` | `boolean` | Whether to open the AI employee conversation panel. |
+| `options.auto` | `boolean` | Whether to use the auto-trigger semantics of an AI employee action. |
+
+This method reads the AI employee and task configuration from the target model. It is useful when the task has already been configured on an AI employee action on the page, and RunJS only needs to trigger it.
+
+```ts
+if (!ctx.ai?.triggerModelTask) {
+  ctx.message.error(ctx.t('AI employee task API is not available.'));
+  return;
+}
+
+const weeklyReviewActionUid = 'AI_EMPLOYEE_ACTION_MODEL_UID';
+
+ctx.ai.triggerModelTask(weeklyReviewActionUid, 0, {
+  open: true,
+});
+
+ctx.message.success(ctx.t('Configured AI employee task triggered.'));
+```
+
+If the target model does not exist, has no AI employee configured, or the specified index has no task, no task is triggered and a warning is printed to the console.
+
+## Which Method to Use
+
+| Scenario | Recommended method |
+|------|------|
+| Task content is assembled dynamically in RunJS, such as from form values. | `ctx.ai.triggerTask()` |
+| The task has already been configured on an AI employee action on the page, and RunJS only triggers it. | `ctx.ai.triggerModelTask()` |
+| Business users need to adjust task content without changing code. | `ctx.ai.triggerModelTask()` |
+| The AI employee, prompt, or sending behavior needs to be decided at runtime. | `ctx.ai.triggerTask()` |
+
+## Notes
+
+- `triggerTask()` and `triggerModelTask()` are fire-and-forget. They do not return the execution result of the AI employee task.
+- `aiEmployee` strings only match `AIEmployee.username` exactly. They do not match nicknames, job titles, or translated names.
+- `triggerModelTask()` uses a `0`-based `taskIndex`.
+- `triggerModelTask()` reads task configuration from the target AI employee action model. If the task needs work context, configure `message.workContext` on that task.
+
+## Related
+
+- [ctx.message](./message.md): Show lightweight prompts before and after triggering tasks.
+- [ctx.render](./render.md): Render buttons or forms in JSBlock.
+- [ctx.model](./model.md): Get current FlowModel information.