@nocobase/plugin-ai 2.2.0-alpha.11 → 2.2.0-alpha.12

package/dist/ai/docs/nocobase/ai-employees/block/ai-chat-box.md

@@ -0,0 +1,133 @@
+---
+pkg: '@nocobase/plugin-ai'
+title: 'AI Chat box block'
+description: 'User guide for NocoBase administrators and page builders covering how to add an AI Chat box block, configure conversation capabilities, set Work context, manage conversations, and add Actions.'
+keywords: 'AI Chat box,AI Employee,page block,Work context,Scope,Actions,NocoBase'
+---
+
+# AI Chat box block
+
+In NocoBase, **AI Chat box** is an AI conversation block that can be added directly to a page. You can place it on a business page to provide a fixed AI assistant entry point for that page.
+
+Each AI Chat box block has its own current conversation and input state. Page builders can also restrict the available AI employees, models, file uploads, web search, and work context to suit the current business scenario.
+
+:::tip Before you start
+
+First [configure an LLM service](../features/llm-service.md) and [enable at least one AI employee](../features/enable-ai-employee.md).
+
+:::
+
+## Add an AI Chat box block
+
+1. Open the page you want to configure.
+2. Click `UI Editor` in the upper-right corner to enter page editing mode.
+3. Click `Add block`.
+4. Under `Other blocks`, select `AI chat box`.
+
+![Select AI chat box from the Add block menu](https://static-docs.nocobase.com/ai-employees/block/ai-chat-box/2026-07-22/add-ai-chat-box-block-3.png)
+
+## Understand the block structure
+
+![AI Chat box block](https://static-docs.nocobase.com/ai-employees/block/ai-chat-box/2026-07-22/ai-chat-box-overview-2.png)
+
+An AI Chat box contains three areas from top to bottom:
+
+- **Top action area** — conversation list, Actions, custom actions, and new conversation buttons; a messages button also appears when the messages area is hidden
+- **Messages area** — displays messages in the current draft or conversation
+- **Sender area** — input box, context selection, file upload, web search, AI employee selection, model selection, send button, and disclaimer
+
+### Add display content inside the block body
+
+In page editing mode, click `Add block` inside the AI Chat box to add any of the following blocks above the chat area:
+
+- JS block
+- Iframe
+- Markdown
+
+These blocks are useful for displaying instructions, external pages, or supporting information. The internal Add block menu only provides these three block types and does not allow another AI Chat box to be nested inside it.
+
+## Configure the AI Chat box
+
+Move the pointer over the block and open its settings menu. Click `Edit chat box` to configure the conversation scope, default message, Work context, AI employees, and models.
+
+![Edit chat box settings dialog](https://static-docs.nocobase.com/ai-employees/block/ai-chat-box/2026-07-22/edit-chat-box-settings-2.png)
+
+### Edit chat box settings
+
+| Setting | Description |
+| --- | --- |
+| `Scope` | Controls which AI Chat boxes share a conversation list. A new block uses its own block UID by default to keep conversations separate. |
+| `Background` | Adds a system prompt after the AI employee definition to provide the role, objective, or response requirements for the current page. |
+| `Default user message` | Prefills a default user message in the sender when a new conversation starts. |
+| `Work context` | Selects page blocks to place in a new draft by default. |
+| `AI employees` | Restricts the business AI employees that can be selected in this block. Leave it empty to allow all available business AI employees. |
+| `Models` | Restricts the models that can be selected in this block. Leave it empty to allow all available models. |
+
+### Other block settings
+
+| Setting | Description |
+| --- | --- |
+| `Show messages` | Controls whether the messages area is displayed directly in the block. When disabled, use the messages button at the top to open the right-side panel. |
+| `Sender placeholder` | Changes the placeholder shown in the sender. |
+| `Enable add context` | Shows or hides the context selection entry in the sender. |
+| `Enable upload files` | Shows or hides the file upload entry. When disabled, pasting a file does not start an upload. |
+| `Enable web search` | Shows or hides the web search switch. Disabling it also turns off web search for the current draft. |
+| `Enable employee select` | Shows or hides the AI employee selector. |
+| `Enable model select` | Shows or hides the model selector. |
+| `Show disclaimer` | Shows or hides the AI disclaimer below the sender. |
+
+## Configure Work context
+
+In `Work context` under `Edit chat box`, click the add context button, select `Pick block`, and then select the page block you want to provide to the AI. After saving, the selected block becomes the default work context for new conversations and can be removed from the sender before sending.
+
+## Hide the messages area and use the right-side panel
+
+After disabling `Show messages`, the block body only keeps the sender area. A messages button appears at the top; click it to open the messages panel from the right.
+
+![Right-side messages panel with the messages area hidden](https://static-docs.nocobase.com/ai-employees/block/ai-chat-box/2026-07-22/messages-side-panel-2.png)
+
+When the panel is open, the rest of the block is covered by an overlay. Click the overlay or click the messages button again to close the panel.
+
+This layout works well when the AI Chat box is used as a lightweight input entry on a page: keep only the sender visible and open the panel when you need to review messages.
+
+## Manage conversation history
+
+Click the conversation list button in the upper-left corner of the block to view conversation history under the current Scope.
+
+Keep these rules in mind:
+
+- Multiple AI Chat boxes with the same Scope can see the same conversation list
+- Each block still has its own current conversation, sender draft, AI employee, model, attachments, and context state
+- The global floating chatbox does not filter by block Scope, so it does not hide conversations with a Scope
+- After clearing Scope, the block no longer filters the conversation list by Scope and displays both conversations without a Scope and conversations using other Scopes
+
+Normally, keeping the Scope generated for a new block is enough to separate the history of each page assistant. Only configure the same Scope when multiple blocks need to share the same conversation list.
+
+## Add Actions
+
+In page editing mode, click `Actions` at the top of the block to add either of the following actions:
+
+- JS Action
+- AI employee
+
+After adding an AI employee, you can configure shortcut tasks for that employee.
+
+The `Chat box uid` setting in a shortcut task specifies which AI Chat box runs the task. An AI employee added directly inside an AI Chat box points to the current block UID by default.
+
+If the specified AI Chat box is not mounted, NocoBase reports that the target block cannot be found and does not fall back to the global floating chatbox. See [AI employee shortcut tasks](../features/task.md) for detailed configuration.
+
+## Configure a page-specific assistant
+
+The following steps create a lightweight AI assistant for a page:
+
+1. Add an AI Chat box block and move it to the appropriate position on the page.
+2. Enter a page-specific Background under `Edit chat box`.
+3. Select one or more Work contexts.
+4. Restrict the available employees and models under `AI employees` and `Models`.
+5. Exit editing mode, enter a question, and send it.
+
+## Notes
+
+- The AI Chat box block and the global floating chatbox in the lower-right corner are separate entry points; their current conversations and input states are not synchronized automatically
+- Only JS block, Iframe, and Markdown can be added from `Add block` inside an AI Chat box
+- Changing Scope affects the conversation list query and does not copy the conversation or draft currently open in another block

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/documents.md

@@ -17,7 +17,7 @@ After opening the knowledge base detail page, click Documents in the left sideba
 
 Click Upload in the upper-right corner to upload files. After upload, documents automatically enter segment generation and vectorization. Status first shows Pending, then changes to Success after processing. If processing fails, it shows Error, and an error icon appears next to the filename.
 
-Supported document types include: `txt`, `md`, `json`, `csv`, `xls`, `xlsx`, `pdf`, `doc`, `docx`, `ppt`, and `pptx`.
+Supported document types include: `txt`, `md`, `json`, `csv`, `xls`, `xlsx`, `pdf`, `doc`, `docx`, and `pptx`.
 
 :::tip PDF documents
 

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/index.md

@@ -13,7 +13,7 @@ A knowledge base is the foundation of RAG retrieval. You can add product manuals
 
 For most scenarios, a Local knowledge base is enough. Only consider Readonly or External knowledge bases when documents and vector data are already maintained by an external system.
 
-![](https://static-docs.nocobase.com/20260617003643.png)
+![](https://static-docs.nocobase.com/20260728222403.png)
 
 ## Open knowledge base management
 
@@ -23,15 +23,15 @@ Click a knowledge base card to open its detail page:
 
 - Documents is used to upload documents, run vectorization, and open segment management
 - Hit tests is used to test which segments can be matched by a query
-- Settings is used to adjust basic information, vector store, and default segmentation parameters
+- Settings is used to adjust basic information, vector configuration, and default segmentation parameters
 
-![](https://static-docs.nocobase.com/20260617004104.png)
+![](https://static-docs.nocobase.com/20260728222406.png)
 
 ## Create a knowledge base
 
 Click Add new in the upper-right corner to create a knowledge base. The menu shows three types: Local, Readonly, and External.
 
-![](https://static-docs.nocobase.com/20260617003505.png)
+![](https://static-docs.nocobase.com/20260728222404.png)
 
 The three knowledge base types have different capability boundaries:
 
@@ -45,19 +45,23 @@ Local knowledge bases are recommended by default. Only consider Readonly or Exte
 
 A Local knowledge base usually needs the following information:
 
-![](https://static-docs.nocobase.com/20260617003603.png)
+![](https://static-docs.nocobase.com/20260728222405.png)
 
 - Key: unique identifier of the knowledge base. It cannot be changed after creation
 - Name: knowledge base name
 - File storage: where original documents and segment files are stored
-- Vector store: vector store used to generate and retrieve vectors
+- Vector database: select a configured vector database. See [Vector database](../vector-database)
+- LLM service: select a configured LLM service that supports embedding models. See [LLM service management](../../features/llm-service)
+- Embedding model: select or enter the embedding model used to generate and retrieve vectors; available models update when the LLM service changes
 - Description: knowledge base description
 - Split document, Chunk size, and Chunk overlap: default segmentation parameters used after document upload
 - Enabled: whether the knowledge base is enabled
 
+A Readonly knowledge base does not require File storage or default segmentation parameters, but it still requires Vector database, LLM service, and Embedding model.
+
 :::tip Prerequisites
 
-Before creating a Local knowledge base, prepare two dependencies: file storage for original documents and segment files, see [File storage](../../../file-manager/storage/); and vector storage for generating and retrieving vectors, see [Vector database](../vector-database) and [Vector store](../vector-store).
+Before creating a Local knowledge base, prepare file storage, a vector database, and an LLM service that supports embedding models. File storage holds original documents and segment files; see [File storage](../../../file-manager/storage/index.md). Configure the vector database as described in [Vector database](../vector-database), and configure the LLM service as described in [LLM service management](../../features/llm-service).
 
 :::
 

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/settings.md

@@ -1,17 +1,17 @@
 ---
 pkg: "@nocobase/plugin-ai-knowledge-base"
 title: "Settings"
-description: "Modify basic information, vector store, and default segmentation settings on the Settings page of a knowledge base, and understand the relation between knowledge-base-level and document-level segmentation settings."
-keywords: "knowledge base settings,segmentation settings,Chunk size,Chunk overlap,vector store,NocoBase"
+description: "Modify basic information, vector database, LLM service, embedding model, and default segmentation settings on the Settings page of a knowledge base."
+keywords: "knowledge base settings,vector database,LLM service,embedding model,segmentation settings,NocoBase"
 ---
 
 # Settings
 
 ## Open the Settings page
 
-After opening the knowledge base detail page, click Settings in the left sidebar. This page modifies basic information, file storage, vector store, and default segmentation settings of the current knowledge base.
+After opening the knowledge base detail page, click Settings in the left sidebar. This page modifies basic information, file storage, vector database, LLM service, embedding model, and default segmentation settings of the current knowledge base.
 
-![](https://static-docs.nocobase.com/20260617005832.png)
+![](https://static-docs.nocobase.com/20260728222407.png)
 
 ## Basic information
 
@@ -22,17 +22,21 @@ Local knowledge base settings include:
 | Key | Unique identifier of the knowledge base. It cannot be changed after creation |
 | Name | Knowledge base name |
 | File storage | Where documents and segment files are stored. It cannot be changed after creation |
-| Vector store | Vector store used by the current knowledge base |
+| Vector database | Vector database used by the current knowledge base |
+| LLM service | LLM service used to generate embeddings |
+| Embedding model | Embedding model used to generate and retrieve vectors |
 | Description | Knowledge base description |
 | Enabled | Whether the current knowledge base is enabled |
 
-:::tip Vector store changes
+:::tip Vector configuration changes
 
-After you modify Vector store, NocoBase asks for confirmation when saving. After the vector store changes, existing documents must be vectorized again before vector data can be written to the new vector store. Choose Save and vectorize to save the settings and vectorize immediately, or choose Save only to save the settings and later run Vectorization manually on the Documents page.
+After you modify Vector database, LLM service, or Embedding model, NocoBase asks for confirmation when saving. After the vector configuration changes, existing documents must be vectorized again. Choose Save and vectorize to save the settings and vectorize immediately, or choose Save only to save the settings and later run Vectorization manually on the Documents page.
+
+If the vector database connection settings change, the Documents page also prompts you to run vectorization again.
 
 :::
 
-![](https://static-docs.nocobase.com/20260617005951.png)
+![](https://static-docs.nocobase.com/20260728222408.png)
 
 ## Default segmentation parameters
 

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/vector-database.md

@@ -10,10 +10,10 @@ Currently, the AI Knowledge Base plugin only has built-in support for PGVector,
 
 ## Vector Database Management
 
-Go to the AI Agent plugin configuration page, click the `Vector store` tab, and select `Vector database` to enter the vector database management page.
+Go to the AI employees plugin configuration page and click the top-level `Vector database` tab to open the vector database management page.
 
 
-![20251022233704](https://static-docs.nocobase.com/20251022233704.png)
+![20260728222401](https://static-docs.nocobase.com/20260728222401.png)
 
 
 Click the `Add new` button in the upper right corner to add a new `PGVector` vector database connection:
@@ -29,4 +29,4 @@ Click the `Add new` button in the upper right corner to add a new `PGVector` vec
 After entering all the necessary information, click the `Test` button to test if the vector database service is available, and click the `Submit` button to save the connection information.
 
 
-![20251022234644](https://static-docs.nocobase.com/20251022234644.png)
+![20260728222402](https://static-docs.nocobase.com/20260728222402.png)

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/knowledge/create-document.md

@@ -30,7 +30,7 @@ Where:
 
 The example uses the `Answers` / `Questions` collections and target knowledge base described in [Overview](./). Before configuring the workflow, confirm that:
 
-- A Local knowledge base has been created, with file storage and vector store configured. See [Knowledge base overview](../../../knowledge-base/knowledge-base) and [Vector store](../../../knowledge-base/vector-store)
+- A Local knowledge base has been created, with file storage, vector database, LLM service, and embedding model configured. See [Knowledge base overview](../../../knowledge-base/knowledge-base/index.md) and [Vector database](../../../knowledge-base/vector-database)
 - The `Answers.questions` relation field is ready. To review the collection structure, return to [Overview](./)
 - The workflow uses asynchronous execution. See [Workflow](../../../../workflow) for the basics
 

package/dist/ai/docs/nocobase/ops-management/migration-manager/built-in-tables.md

@@ -336,9 +336,8 @@ The “Data type” column comes from built-in classification. System base data
 | Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
 | --- | --- | --- | --- | --- | --- |
 | `aiKnowledgeBaseDocs` | Document chunks and index metadata stored in knowledge bases | Business runtime data | Schema-only | Not included | Backed up |
-| `aiKnowledgeBase` | Knowledge-base type, external ID, and base information | Business runtime data | Schema-only | Not included | Backed up |
+| `aiKnowledgeBase` | Knowledge-base type, external ID, vector database, LLM service, embedding model, and base information | Business runtime data | Schema-only | Not included | Backed up |
 | `aiVectorDatabases` | Vector database service and connection configuration | Business runtime data | Schema-only | Not included | Backed up |
-| `aiVectorStoreConfig` | Relationship between vector database connections and embedding models | Business runtime data | Schema-only | Not included | Backed up |
 
 ### Environment variables
 

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

@@ -1,23 +1,51 @@
 ---
 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"
+description: "Use ctx.ai in RunJS to trigger AI employee tasks in the global conversation or a specified AI Chat Box, either with inline task content or with tasks configured on an AI employee action."
+keywords: "ctx.ai,AI employee,uploadFile,attachments,triggerTask,triggerModelTask,onResponseLoadingChange,chatBoxUid,AI Chat Box,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.
+`ctx.ai` uploads AI task attachments and triggers tasks. File uploads can be awaited, but task triggering 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.
+`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?.uploadFile`, `ctx.ai?.triggerTask`, or `ctx.ai?.triggerModelTask` before calling it.
 
 :::
 
 ## Methods
 
+### ctx.ai.uploadFile()
+
+Upload one file and return an attachment object that can be passed directly to an AI employee task.
+
+```ts
+const attachment = await ctx.ai.uploadFile(file, options);
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `file` | `File` | Browser file object to upload. |
+| `options.onProgress` | `(percent: number) => void` | Upload progress callback. `percent` ranges from `0` to `100`. |
+| `options.signal` | `AbortSignal` | Signal used to cancel the upload. |
+
+The upload uses the file storage configured by the AI plugin and creates a record in `aiFiles`. The returned object includes fields such as `id`, `filename`, `url`, and `source`:
+
+```ts
+const attachment = await ctx.ai.uploadFile(file, {
+  onProgress(percent) {
+    console.log('upload progress', percent);
+  },
+});
+
+// attachment can be placed directly in message.attachments
+```
+
+The Promise is rejected when the upload fails. Removing an attachment from the local UI does not delete the record already created in `aiFiles`, matching the behavior of the default AI chat window.
+
 ### ctx.ai.triggerTask()
 
 Trigger an AI employee task directly.
@@ -30,8 +58,10 @@ ctx.ai.triggerTask(options: TriggerTaskOptions): void
 |------|------|------|
 | `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. |
+| `chatBoxUid` | `string` | FlowModel uid of the AI Chat Box block that should receive the task. |
 | `open` | `boolean` | Whether to open the AI employee conversation panel. |
 | `auto` | `boolean` | Whether to use the auto-trigger semantics of an AI employee action. |
+| `onResponseLoadingChange` | `(loading: boolean) => void` | Model response loading callback. It only runs when this task is sent automatically. |
 
 Common `Task` fields:
 
@@ -40,12 +70,160 @@ Common `Task` fields:
 | `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.attachments` | `Attachment[]` | Attachments used by the task, usually returned by `ctx.ai.uploadFile()`. |
 | `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. |
 
+### Track the Response Loading State
+
+Pass `onResponseLoadingChange` in the top-level options to track the model response loading state for this task. The callback receives `true` when NocoBase starts waiting for the model response, and `false` when the response completes, is canceled, or fails. If the React component has declared `setResponseLoading` with `useState`, you can write:
+
+```tsx
+ctx.ai.triggerTask({
+  aiEmployee: 'nathan',
+  open: true,
+  tasks: [
+    {
+      title: ctx.t('Review current page'),
+      message: {
+        user: 'Review the current page and summarize the main risks.',
+      },
+      autoSend: true,
+    },
+  ],
+  onResponseLoadingChange(loading) {
+    setResponseLoading(loading);
+  },
+});
+```
+
+`onResponseLoadingChange` only tracks the model response started directly by this `triggerTask()` call. With `autoSend: false`, the task is placed in the chat draft and the callback does not run. If the user sends the draft later, that manual send does not reuse this callback.
+
+In a React component inside a JS block, this state update rerenders the component while it remains mounted.
+
+### Target an AI Chat Box
+
+Set `chatBoxUid` on the top-level `triggerTask()` options to trigger the task in a mounted AI Chat Box block instead of the global AI employee dialog.
+
+```ts
+ctx.ai.triggerTask({
+  aiEmployee: 'nathan',
+  chatBoxUid: 'AI_CHAT_BOX_BLOCK_UID',
+  open: true,
+  tasks: [
+    {
+      title: ctx.t('Review current page'),
+      message: {
+        user: 'Review the current page and summarize the main risks.',
+      },
+    },
+  ],
+});
+```
+
+The uid must belong to the outer AI Chat Box block currently mounted on the page. Do not put this routing value inside `tasks`. If the target block cannot be found, NocoBase reports an error and does not fall back to the global dialog. When `chatBoxUid` is omitted, the task uses the global AI employee dialog.
+
+### Upload and Send Attachments in JSBlock
+
+The following example renders file upload, task instructions, and a send button in JSBlock. Uploaded files are passed to the AI employee through `message.attachments`:
+
+```tsx
+if (!ctx.ai?.uploadFile || !ctx.ai?.triggerTask) {
+  ctx.message.error(ctx.t('AI employee task API is not available.'));
+  return;
+}
+
+const { React } = ctx.libs;
+const { useState } = React;
+const { Button, Card, Input, Space, Upload } = ctx.libs.antd;
+const { InboxOutlined, SendOutlined } = ctx.libs.antdIcons;
+
+const AttachmentTask = () => {
+  const [prompt, setPrompt] = useState('');
+  const [fileList, setFileList] = useState([]);
+
+  const uploadAttachment = async ({ file, onError, onProgress, onSuccess }) => {
+    try {
+      const attachment = await ctx.ai.uploadFile(file, {
+        onProgress(percent) {
+          onProgress?.({ percent });
+        },
+      });
+      onSuccess?.(attachment);
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(ctx.t('File upload failed')));
+    }
+  };
+
+  const sendTask = () => {
+    const attachments = fileList
+      .filter((file) => file.status === 'done' && file.response)
+      .map((file) => file.response);
+
+    if (!prompt.trim()) {
+      ctx.message.warning(ctx.t('Enter task instructions'));
+      return;
+    }
+
+    ctx.ai.triggerTask({
+      aiEmployee: 'viz',
+      open: true,
+      tasks: [
+        {
+          title: ctx.t('Analyze uploaded files'),
+          message: {
+            user: prompt.trim(),
+            attachments,
+          },
+          autoSend: true,
+        },
+      ],
+    });
+    setPrompt('');
+    setFileList([]);
+  };
+
+  const uploading = fileList.some((file) => file.status === 'uploading');
+
+  return (
+    <Card title={ctx.t('AI file analysis')}>
+      <Space direction="vertical" size="middle" style={{ width: '100%' }}>
+        <Upload.Dragger
+          multiple
+          fileList={fileList}
+          customRequest={uploadAttachment}
+          onChange={({ fileList: nextFileList }) => setFileList(nextFileList)}
+        >
+          <p className="ant-upload-drag-icon"><InboxOutlined /></p>
+          <p>{ctx.t('Click or drag files here to upload')}</p>
+        </Upload.Dragger>
+        <Input.TextArea
+          value={prompt}
+          onChange={(event) => setPrompt(event.target.value)}
+          placeholder={ctx.t('Describe the task for the AI employee')}
+          autoSize={{ minRows: 3, maxRows: 8 }}
+        />
+        <Button
+          type="primary"
+          icon={<SendOutlined />}
+          disabled={uploading || !prompt.trim()}
+          onClick={sendTask}
+        >
+          {ctx.t('Send to AI')}
+        </Button>
+      </Space>
+    </Card>
+  );
+};
+
+ctx.render(<AttachmentTask />);
+```
+
+With `autoSend: false`, the attachments and task instructions are placed in the AI chat draft instead of being sent immediately.
+
 ### Add Page Block Context
 
 `message.workContext` currently passes page blocks. Put the FlowModel uid of the target page block into it:
@@ -163,9 +341,15 @@ ctx.ai.triggerModelTask(uid: string, taskIndex: number, options?: TriggerModelTa
 | `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. |
+| `options.attachments` | `Attachment[]` | Attachments dynamically appended to the configured task. |
+| `options.onResponseLoadingChange` | `(loading: boolean) => void` | Model response loading callback. It only runs when the configured task is sent automatically. |
 
 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.
 
+The public `triggerModelTask()` options do not accept `chatBoxUid`. To target an AI Chat Box, configure `chatBoxUid` on the preset task of the AI employee action. `triggerModelTask()` continues to reuse that preset value.
+
+`options.onResponseLoadingChange` behaves the same as the option on `triggerTask()`. Whether it runs depends on the configured task's `autoSend` value. It does not run when that task uses `autoSend: false`.
+
 ```ts
 if (!ctx.ai?.triggerModelTask) {
   ctx.message.error(ctx.t('AI employee task API is not available.'));
@@ -176,6 +360,7 @@ const weeklyReviewActionUid = 'AI_EMPLOYEE_ACTION_MODEL_UID';
 
 ctx.ai.triggerModelTask(weeklyReviewActionUid, 0, {
   open: true,
+  attachments,
 });
 
 ctx.message.success(ctx.t('Configured AI employee task triggered.'));
@@ -195,9 +380,14 @@ If the target model does not exist, has no AI employee configured, or the specif
 ## Notes
 
 - `triggerTask()` and `triggerModelTask()` are fire-and-forget. They do not return the execution result of the AI employee task.
+- `uploadFile()` returns a Promise. Wait for the upload to finish before triggering a task that uses the attachment.
 - `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.
+- Top-level `triggerTask().chatBoxUid` must reference an AI Chat Box block currently mounted on the page.
+- `triggerModelTask()` keeps using `chatBoxUid` configured on its preset task.
+- Dynamic `triggerModelTask()` attachments are appended to the preset task's existing `message.attachments` without changing the saved task configuration.
+- `onResponseLoadingChange` only tracks a model response automatically sent by the current call. It does not track a message the user sends manually later.
 
 ## Related
 

package/dist/ai/tools/getSkill.js

@@ -43,7 +43,7 @@ var import_ai = require("@nocobase/ai");
 var import_zod = require("zod");
 var import_package = __toESM(require("../../../package.json"));
 var getSkill_default = (0, import_ai.defineTools)({
-  scope: "GENERAL",
+  scope: "SPECIFIED",
   defaultPermission: "ALLOW",
   introduction: {
     title: `{{t("Load specific SKILLS", { ns: "${import_package.default.name}" })}}`,