@nocobase/plugin-ai 2.2.0-alpha.7 → 2.2.0-alpha.9

package/dist/ai/docs/nocobase/multi-app/multi-app-vs-multi-portal-vs-multi-space.md

@@ -0,0 +1,159 @@
+# Multi-portal, Multi-app, and Multi-space
+
+NocoBase provides three capabilities: Multi-portal, Multi-app, and Multi-space.
+
+They solve problems at different levels. They can be used independently or together.
+
+## Key differences
+
+| Capability | Multi-portal | Multi-app | Multi-space |
+|------|------|------|------|
+| What problem it solves | Provides multiple access entries | Splits business into multiple systems | Isolates business data |
+| Core focus | Where users enter | How the system is divided | Who the data belongs to |
+| Data | Shared | Independent by default | Isolated |
+| Pages and menus | Independent | Independent | Shared |
+| Plugin configuration | Shared | Independent | Shared |
+| User system | Shared | Can be shared through SSO | Shared |
+| Typical scenarios | Different roles need different entries | Different businesses need independent management | Multiple organizations, stores, or tenants |
+| Can be combined | Yes | Yes | Yes |
+
+## Multi-portal
+
+Multi-portal provides multiple access entries within the same application.
+
+For example:
+
+```text
+ERP App
+
+├─ Admin Portal (/v/admin)
+├─ Store Portal (/v/store)
+├─ Distributor Portal (/v/dealer)
+└─ Mobile Portal (/v/mobile)
+```
+
+Features:
+
+- Uses the same application
+- Shares the same data
+- Shares plugin configuration
+- Pages and menus can be configured independently
+
+Suitable for scenarios where different roles need different access entries, such as:
+
+- Administrators
+- Employees
+- Customers
+- Distributors
+
+## Multi-app
+
+Multi-app splits business into multiple independent applications.
+
+For example:
+
+```text
+Group System
+
+├─ CRM
+├─ ERP
+├─ OA
+└─ Analytics
+```
+
+Features:
+
+- Each app is managed independently
+- Independent plugin configuration
+- Independent database connection
+- Independent upgrade and maintenance
+
+Suitable for:
+
+- Splitting large business systems
+- Multi-team collaborative development
+- Batch creation of apps for SaaS platforms
+- Independent apps for different customers
+
+## Multi-space
+
+Multi-space isolates business data within the same application.
+
+For example:
+
+```text
+Store Management App
+
+Spaces
+├─ Beijing Store
+├─ Shanghai Store
+└─ Shenzhen Store
+```
+
+Features:
+
+- Shared pages
+- Shared menus
+- Shared workflows
+- Shared configuration
+- Isolated data
+
+For tables that have a space field enabled, the system automatically filters data according to the current space.
+
+From the user's perspective:
+
+- The Beijing store can only see Beijing store data
+- The Shanghai store can only see Shanghai store data
+- The Shenzhen store can only see Shenzhen store data
+
+But all stores still use the same system.
+
+## Relationship among the three
+
+These three capabilities do not conflict. They work on different dimensions.
+
+They can be used together:
+
+```text
+Group System
+
+CRM App
+├─ Admin Portal
+├─ Sales Portal
+└─ Customer Portal
+
+Spaces
+├─ Beijing Branch
+├─ Shanghai Branch
+└─ Shenzhen Branch
+```
+
+Conceptually:
+
+```text
+Portal
+    ↓
+Where users enter the system
+
+App
+    ↓
+How the system is divided
+
+Space
+    ↓
+Who the data belongs to
+```
+
+## How to choose
+
+If you only want to provide different entries for different roles, choose **Multi-portal**.
+
+If you want to split business into multiple independent systems, choose **Multi-app**.
+
+If you want to isolate data for different organizations or tenants within the same system, choose **Multi-space**.
+
+In real projects, these three capabilities are usually combined rather than used as substitutes for one another.
+
+In one sentence:
+
+> Multi-portal solves entry points, Multi-app solves system splitting, and Multi-space solves data isolation.

package/dist/ai/docs/nocobase/multi-app/multi-portal/index.md

@@ -0,0 +1,195 @@
+---
+title: "Multi-portal"
+description: "Learn the concept, use cases, configuration, and relationship between Multi-portal, Multi-app, and Multi-space in NocoBase."
+keywords: "workspace, portal, multi-portal, NocoBase"
+pkg: "@nocobase/plugin-multi-portal"
+---
+
+# Multi-portal
+
+## What is a portal
+
+A portal is used to provide multiple access entries within the same application.
+
+Each portal can have its own:
+
+- Pages
+- Menus
+- Navigation structure
+- Layout
+- Permission settings
+
+The Multi-portal plugin provides the following capabilities:
+
+- Portal management
+- Portal switching
+- Portal permission control
+
+With these capabilities, you can provide different experiences for different roles while sharing the same data and business capabilities.
+
+## Why use portals
+
+In real business scenarios, different roles often need different interfaces.
+
+For example, in a retail management system:
+
+```text
+Retail Management System
+
+├─ Headquarters Portal
+├─ Store Portal
+├─ Distributor Portal
+└─ Mobile Portal
+```
+
+Headquarters staff focus on:
+
+- Product management
+- Inventory management
+- Data analysis
+
+Store staff focus on:
+
+- Cashiering
+- Stocktaking
+- Order processing
+
+Distributors focus on:
+
+- Purchasing
+- Reconciliation
+- Shipment status
+
+Although everyone uses the same system, different roles do not need to see the same menus and pages.
+
+That is exactly the problem portals solve.
+
+## Relationship between portals and menus
+
+Each portal has its own menu tree.
+
+Menus in different portals do not affect each other.
+
+For example:
+
+```text
+Headquarters Portal
+├─ Product Management
+├─ Supply Chain Management
+└─ Data Analysis
+
+Store Portal
+├─ Cashiering
+├─ Order Management
+└─ Stocktaking
+```
+
+## Relationship between portals and pages
+
+Pages belong to their respective portals.
+
+The same page can also be shown only in specific portals.
+
+This makes it possible to design completely different workflows for different roles.
+
+## Relationship between portals and permissions
+
+Portals themselves can be configured with access permissions.
+
+Only authorized users can access the corresponding portal.
+
+Unauthorized portals:
+
+- Do not appear in the switcher list
+- Cannot be accessed directly
+
+## Portal management
+
+After enabling the Multi-portal plugin, the system provides two built-in portals by default:
+
+| Portal | Path | Purpose |
+|----------|----------|----------|
+| Desktop | `/v/admin` | Desktop entry |
+| Mobile | `/v/mobile` | Mobile entry |
+
+### Built-in portals
+
+![2026-07-10-08-01-50](https://static-docs.nocobase.com/2026-07-10-08-01-50.png)
+
+### Desktop portal
+
+Access path:
+
+```text
+/v/admin
+```
+
+![2026-07-10-08-03-12](https://static-docs.nocobase.com/2026-07-10-08-03-12.png)
+
+### Mobile portal
+
+Access path:
+
+```text
+/v/mobile
+```
+
+![2026-07-10-08-04-59](https://static-docs.nocobase.com/2026-07-10-08-04-59.png)
+
+## Create a portal
+
+In addition to the built-in portals, you can create more portals based on business needs.
+
+For example:
+
+- Store portal
+- Distributor portal
+- Customer service portal
+- Data analysis portal
+
+After creation, you can configure:
+
+- Pages
+- Menus
+- Permissions
+- Navigation
+
+![2026-07-10-08-06-15](https://static-docs.nocobase.com/2026-07-10-08-06-15.png)
+
+## Switch portals
+
+Users can quickly switch between portals through the portal switcher.
+
+### Switch portals within a single app
+
+Add it to the portal switcher panel in the upper-left corner
+
+![2026-07-10-08-20-41](https://static-docs.nocobase.com/2026-07-10-08-20-41.png)
+
+Add it to the action panel block
+
+![2026-07-10-08-21-15](https://static-docs.nocobase.com/2026-07-10-08-21-15.png)
+
+### Switch portals across apps
+
+After enabling Multi-app and configuring SSO, users can also switch between portals across different apps through the portal switcher.
+
+Add it to the portal switcher panel in the upper-left corner
+
+![2026-07-10-08-25-19](https://static-docs.nocobase.com/2026-07-10-08-25-19.png)
+
+Add it to the action panel block
+
+![2026-07-10-08-25-50](https://static-docs.nocobase.com/2026-07-10-08-25-50.png)
+
+## Portal permissions
+
+You can control which portals a user can access through role permissions.
+
+Unauthorized portals do not appear in the portal switcher list, and users cannot access those entries directly.
+
+![2026-07-10-08-29-22](https://static-docs.nocobase.com/2026-07-10-08-29-22.png)
+
+## Related links
+
+For the differences and combination patterns among Multi-portal, Multi-app, and Multi-space, see: [Multi-portal, Multi-app, and Multi-space](../multi-app-vs-multi-portal-vs-multi-space.md).

package/dist/ai/docs/nocobase/nocobase-cli/production/index.md

@@ -69,6 +69,16 @@ If you happen to be stuck here "Why do you need `nb app autostart`", just contin
 - If you are going to connect to the reverse proxy, `appPort` has been saved in env
 - If you are ready to officially open it to the outside world, you have already planned the domain name, entrance port and HTTPS solution.
 
+:::warning Note
+
+Use a different `hostname`, such as a separate subdomain, for each independent NocoBase service. Do not distinguish services only by port. Browser cookies are not isolated by port, so services under the same `hostname` may overwrite login state and affect [stable URL](../../file-manager/stable-url.md) authorization.
+
+Sub-apps within the same NocoBase deployment are distinguished by app name and do not need separate hostnames. However, if another independent NocoBase service runs on a different port under the same `hostname` and contains a main app or sub-app with the same name, its cookies may still conflict.
+
+For example, use `app1.example.com` and `app2.example.com` instead of `example.com:13000` and `example.com:14000`.
+
+:::
+
 If you have not completed the CLI installation or env initialization, go back to [Install using CLI](../installation/cli.md).
 
 If the command prompts that env is missing `appPort`, first execute [`nb env update`](../../api/cli/env/update.md) to fill it in.

package/dist/ai/docs/nocobase/nocobase-cli/production/reverse-proxy/caddy.md

@@ -124,7 +124,7 @@ If you want to make up for Caddy site-level configuration, such as additional he
 
 If your application is not CLI hosted, or you explicitly want to maintain the complete Caddy configuration yourself, you can also write it by hand.
 
-However, for NocoBase, the production environment entry is usually not just a simple `reverse_proxy`. In addition to forwarding API requests to the backend application, a complete and working Caddy configuration usually also needs to handle the upload directory, front-end static resources, `.well-known` routing, WebSocket, and SPA fallback page.
+However, for NocoBase, the production environment entry is usually not just a simple `reverse_proxy`. In addition to forwarding API requests to the backend application, a complete and working Caddy configuration usually also needs to handle the upload directory, front-end static resources, the `/files/` file access route, `.well-known` routing, WebSocket, and SPA fallback pages.
 
 Taking `test2` as an example, key directories related to Caddy usually include:
 
@@ -139,6 +139,7 @@ In other words, handwritten configuration usually needs to cover at least the fo
 - `dist`: Expose the front-end build product directory
 - `oauth well-known`: Handle OAuth discovery paths
 - `openid well-known`: Handle OpenID discovery paths
+- `files`: Forward file access requests under `/files/` to the backend application
 - `api`: forward `/api/` request to the backend application
 - `ws`: forward WebSocket requests to the backend application
 - `spa v2`: Provides front-end entry and return page for `/v/`
@@ -187,6 +188,10 @@ c.local.nocobase.com {
         reverse_proxy host.docker.internal:56575
     }
 
+    handle /files/* {
+        reverse_proxy host.docker.internal:56575
+    }
+
     handle /api/* {
         reverse_proxy host.docker.internal:56575
     }
@@ -249,7 +254,15 @@ A more prudent approach is usually:
 2. Confirm the routing structure and actual path based on the generated results.
 3. Then make manual adjustments according to your domain name, running mode and mounting path.
 
-This is usually less likely to miss details related to WebSockets, static resources, upload directories, `.well-known` routes, or SPA fallback pages than handwriting a configuration from scratch.
+This is usually less likely to miss details related to `/files/`, WebSockets, static resources, upload directories, `.well-known` routes, or SPA fallback pages than handwriting a configuration from scratch.
+
+:::warning Note
+
+`/files/` is an application route that must pass through NocoBase authorization. Do not handle it as a static directory or let it fall through to the SPA fallback. Forward it to the NocoBase backend and place the rule before `handle_path /*` and other front-end fallback rules.
+
+If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/*`. Keep the root-level `/files/*` rule for compatibility with existing file URLs.
+
+:::
 
 ## Check and reload configuration
 

package/dist/ai/docs/nocobase/nocobase-cli/production/reverse-proxy/index.md

@@ -9,7 +9,7 @@ keywords: "NocoBase,nb proxy nginx,nb proxy caddy, reverse proxy, Nginx, Caddy,
 
 This article only applies to applications installed using `nb init`.
 
-In NocoBase, the production environment reverse proxy does more than simply forward requests to the application process. Often the details of WebSockets, subpaths, front-end static resources, upload directories, and SPA fallback pages are also handled at the same time.
+In NocoBase, the production environment reverse proxy does more than simply forward requests to the application process. It also needs to handle WebSockets, subpaths, front-end static resources, upload directories, the `/files/` file access route, and SPA fallback pages.
 
 The function of `nb proxy` is to collect these easily missed details into a stable set of command entries.
 

package/dist/ai/docs/nocobase/nocobase-cli/production/reverse-proxy/nginx.md

@@ -122,7 +122,7 @@ If you want to add site-level Nginx configuration, such as current limiting, add
 
 If your application is not CLI hosted, or you explicitly want to maintain the complete Nginx configuration yourself, you can also write it by hand.
 
-However, for NocoBase, the production reverse proxy is usually more than a simple `proxy_pass`. In addition to forwarding API requests to the backend application, a complete and usable configuration usually needs to handle the upload directory, front-end static resources, WebSocket, `.well-known` route, and SPA fallback page.
+However, for NocoBase, the production reverse proxy is usually more than a simple `proxy_pass`. In addition to forwarding API requests to the backend application, a complete and usable configuration usually needs to handle the upload directory, front-end static resources, the `/files/` file access route, WebSocket, the `.well-known` route, and SPA fallback pages.
 
 Taking `test2` as an example, key files and directories related to Nginx usually include:
 
@@ -138,6 +138,7 @@ In other words, handwritten configuration usually needs to cover at least the fo
 - `uploads`: Expose the upload directory through `alias`
 - `dist`: Expose the front-end build product directory through `alias`
 - `well-known`: Handle OAuth / OpenID related discovery paths
+- `files`: Forward file access requests under `/files/` to the backend application
 - `api`: forward `/api/` request to the backend application
 - `ws`: forward WebSocket requests to the backend application
 - `spa`: Provides front-end entry and `try_files` fallback for `/` and `/v/`
@@ -180,6 +181,11 @@ server {
         include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
     }
 
+    location ^~ /files/ {
+        proxy_pass http://127.0.0.1:56575;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
+    }
+
     location ^~ /api/ {
         proxy_pass http://127.0.0.1:56575;
         include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
@@ -229,7 +235,15 @@ A more prudent approach is usually:
 2. Confirm the routing structure and actual path based on the generated results.
 3. Then make manual adjustments according to your domain name, running mode and mounting path.
 
-This is usually less likely to miss details related to WebSockets, static resources, upload directories, or SPA fallback pages than handwriting a configuration from scratch.
+This is usually less likely to miss details related to `/files/`, WebSockets, static resources, upload directories, or SPA fallback pages than handwriting a configuration from scratch.
+
+:::warning Note
+
+`/files/` is an application route that must pass through NocoBase authorization. Do not handle it as a static directory or let it fall through to the SPA fallback. Forward it to the NocoBase backend and place the rule before `location /` and other front-end fallback rules.
+
+If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/`. Keep the root-level `/files/` rule for compatibility with existing file URLs.
+
+:::
 
 ## How to handle HTTPS
 

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.