@nocobase/plugin-ai 2.1.0-alpha.40 → 2.1.0-alpha.45

package/dist/ai/docs/nocobase/api/cli/app/index.md

@@ -6,7 +6,7 @@ keywords: "nb app,NocoBase CLI,app runtime,start,stop,logs,upgrade"
 
 # nb app
 
-Manage the runtime of a selected NocoBase env. npm/Git envs run local app commands; Docker envs manage saved app containers.
+Manage the runtime of a selected NocoBase env. npm/Git envs run local app commands; Docker envs manage app containers from the saved env config.
 
 ## Usage
 
@@ -18,12 +18,12 @@ nb app <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb app start`](./start.md) | Start the app or Docker container |
-| [`nb app stop`](./stop.md) | Stop the app or Docker container |
+| [`nb app start`](./start.md) | Start the app or recreate the Docker container |
+| [`nb app stop`](./stop.md) | Stop the app or remove the Docker container |
 | [`nb app restart`](./restart.md) | Stop and then start the app |
 | [`nb app logs`](./logs.md) | View app logs |
 | [`nb app down`](./down.md) | Stop and clean up local runtime resources |
-| [`nb app upgrade`](./upgrade.md) | Update source or image and restart the app |
+| [`nb app upgrade`](./upgrade.md) | Stop the app, replace the source or image, then start it again |
 
 ## Examples
 

package/dist/ai/docs/nocobase/api/cli/app/restart.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app restart"
-description: "nb app restart command reference: restart the NocoBase app or Docker container for a selected env."
+description: "nb app restart command reference: restart the NocoBase app for a selected env and recreate the Docker app container from saved env config when needed."
 keywords: "nb app restart,NocoBase CLI,restart app,Docker"
 ---
 
 # nb app restart
 
-Stop and then start the NocoBase app for a selected env.
+Stop and then start the NocoBase app for a selected env. Local envs reuse the `nb app stop` and `nb app start` flow; Docker envs remove the current container first, then recreate the app container from saved env config.
 
 ## Usage
 
@@ -43,6 +43,8 @@ nb app restart --env local-docker
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
+Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out. If you pass `--no-daemon` for a local env, the app runs in the foreground, so the CLI does not keep waiting for the readiness check after startup.
+
 ## Related Commands
 
 - [`nb app start`](./start.md)

package/dist/ai/docs/nocobase/api/cli/app/start.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app start"
-description: "nb app start command reference: start the NocoBase app or Docker container for a selected env."
+description: "nb app start command reference: start the NocoBase app for a selected env and recreate the Docker app container from saved env config when needed."
 keywords: "nb app start,NocoBase CLI,start app,Docker,pm2"
 ---
 
 # nb app start
 
-Start the NocoBase app for a selected env. npm/Git installations run local app commands; Docker installations start the saved app container.
+Start the NocoBase app for a selected env. npm/Git installations run local app commands; Docker installations recreate the saved app container from the saved env config.
 
 ## Usage
 
@@ -44,6 +44,10 @@ nb app start --env local-docker
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
+By default, local envs start in daemon mode and Docker envs recreate the app container from saved env config. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
+
+If you pass `--no-daemon` for a local env, the app runs in the foreground. In that case, the CLI does not keep waiting for the readiness check after startup.
+
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

package/dist/ai/docs/nocobase/api/cli/app/stop.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app stop"
-description: "nb app stop command reference: stop the NocoBase app or Docker container for a selected env."
+description: "nb app stop command reference: stop the NocoBase app and remove the Docker app container for a selected env."
 keywords: "nb app stop,NocoBase CLI,stop app,Docker"
 ---
 
 # nb app stop
 
-Stop the NocoBase app for a selected env. npm/Git installations stop local app processes; Docker installations stop the saved app container.
+Stop the NocoBase app for a selected env. npm/Git installations stop local app processes; Docker installations remove the saved app container.
 
 ## Usage
 

package/dist/ai/docs/nocobase/api/cli/app/upgrade.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app upgrade"
-description: "nb app upgrade command reference: update source or image and restart a selected NocoBase app."
+description: "nb app upgrade command reference: stop the app, replace the saved source or image, then start the selected NocoBase app again."
 keywords: "nb app upgrade,NocoBase CLI,upgrade,update,Docker image"
 ---
 
 # nb app upgrade
 
-Upgrade a selected NocoBase app. npm/Git installations refresh the saved source and restart with quickstart; Docker installations refresh the saved image and recreate the app container.
+Upgrade a selected NocoBase app. The CLI stops the current app, replaces the saved source or image by default, synchronizes commercial plugins, quickstarts the app again, and refreshes the env runtime at the end. Docker envs recreate the app container from the saved env config during startup.
 
 ## Usage
 
@@ -20,23 +20,44 @@ nb app upgrade [flags]
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to upgrade; uses the current env if omitted |
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
-| `--skip-code-update`, `-s` | boolean | Restart from the saved local source or Docker image without downloading updates |
-| `--version` | string | Override the saved `downloadVersion`; when the upgrade succeeds, the new version is written back to the env config |
+| `--force`, `-f` | boolean | Skip the upgrade confirmation prompt. Required in non-interactive terminals and AI agent sessions |
+| `--skip-download`, `-s` | boolean | Restart from the currently saved local source or Docker image without downloading updates first; also skips `nb license plugins sync` |
+| `--version` | string | Override the target version for this upgrade; when the upgrade succeeds, the new version is written back to `downloadVersion` in the env config |
 | `--verbose` | boolean | Show underlying update and restart command output |
 
 ## Examples
 
 ```bash
 nb app upgrade
+nb app upgrade --force
 nb app upgrade --env local
-nb app upgrade --env local -s
+nb app upgrade --env local --force
+nb app upgrade --env local --skip-download
+nb app upgrade --env local --skip-download --version beta
 nb app upgrade --env local --version beta
 nb app upgrade --env local --verbose
-nb app upgrade --env local-docker -s
+nb app upgrade --env local-docker --skip-download
 ```
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
+Before the upgrade starts, interactive terminals also ask for upgrade confirmation unless you pass `--force`. In non-interactive terminals and AI agent sessions, `nb app upgrade` refuses to proceed without `--force` and prints a copyable re-run command. If the command is also cross-env, you need both `--yes` and `--force`.
+
+By default, `nb app upgrade` runs these steps:
+
+1. `nb app stop`
+2. `nb source download --replace`
+3. `nb license plugins sync --skip-if-no-license`
+4. `nb app start --quickstart`
+5. Save the new `downloadVersion` when needed
+6. `nb env update`
+
+When `--skip-download` is passed, the CLI skips steps 2 and 3 and restarts the currently saved source or image directly. If `--version` is also passed, the CLI does not download that version during this run; instead it only saves it as the new `downloadVersion` after a successful restart so later upgrades can use it.
+
+Step 4 waits for the app to pass `__health_check`. During this wait, the CLI prints one waiting line first, then one progress line every 10 seconds until the app is ready or the health check times out.
+
+If the final `nb env update` step fails, the upgrade still counts as successful. The CLI prints a warning and tells you to run `nb env update <envName>` manually afterward.
+
 ## Related Commands
 
 - [`nb source download`](../source/download.md)

package/dist/ai/docs/nocobase/api/cli/init.md

@@ -63,7 +63,7 @@ nb init --env app1 --resume
 | `--db-database` | string | Database name |
 | `--db-user` | string | Database user |
 | `--db-password` | string | Database password |
-| `--fetch-source` | boolean | Download app files or pull the Docker image before installation |
+| `--skip-download` | boolean | Skip downloading app files or pulling the Docker image before installation, and reuse existing local resources |
 | `--source`, `-s` | string | How to obtain NocoBase: `docker`, `npm`, or `git` |
 | `--version`, `-v` | string | Version parameter: npm version, Docker image tag, or Git ref |
 | `--replace`, `-r` | boolean | Replace the target directory if it already exists |

package/dist/ai/docs/nocobase/api/cli/license/plugins/sync.md

@@ -22,6 +22,7 @@ nb license plugins sync [flags]
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--dry-run` | boolean | Preview changes without installing, upgrading, or removing plugins |
 | `--version` | string | Registry version or dist-tag to synchronize; defaults to the current workspace version |
+| `--skip-if-no-license` | boolean | Skip without error when the current env does not have a saved license key |
 | `--verbose` | boolean | Show detailed per-plugin sync logs |
 | `--json` | boolean | Output JSON |
 
@@ -32,6 +33,7 @@ nb license plugins sync
 nb license plugins sync --env app1
 nb license plugins sync --env app1 --yes
 nb license plugins sync --env app1 --dry-run
+nb license plugins sync --env app1 --skip-if-no-license
 nb license plugins sync --env app1 --json
 ```
 
@@ -39,6 +41,8 @@ nb license plugins sync --env app1 --json
 
 When `--version` is omitted, the CLI detects the current app version automatically and uses that to decide which registry version of commercial plugins should be downloaded.
 
+`--skip-if-no-license` only ignores one case: the current env does not have a saved license key yet. Other errors, such as missing registry credentials in the key, registry login failures, or plugin download failures, still surface normally.
+
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
 ## Related Commands

package/dist/ai/docs/nocobase/auth-verification/api-keys/index.md

@@ -8,7 +8,7 @@ pkg: '@nocobase/plugin-api-keys'
 
 ## Usage Instructions
 
-http://localhost:13000/admin/settings/api-keys/configuration
+https://example.com/admin/settings/api-keys
 
 
 ![](https://static-docs.nocobase.com/d64ccbdc8a512a0224e9f81dfe14a0a8.png)

package/dist/ai/docs/nocobase/file-manager/file-preview/index.md

@@ -9,3 +9,20 @@ For file types that do not support native preview, you can enable preview functi
 Currently, NocoBase provides the following file preview plugins:
 
 * [Office File Preview Plugin](../file-preview/ms-office.md)
+
+## PDF preview with external storage
+
+PDF preview uses PDF.js to render files in the browser. The browser must first read the PDF file content and then pass it to PDF.js for rendering. Therefore, when files are stored in external storage such as OSS, S3, COS, or a CDN, and the file access domain is different from the NocoBase site domain, the external storage must allow the NocoBase site to read files across origins.
+
+If CORS is not configured, PDF downloads can still work normally, but preview may fail with a file loading error.
+
+The CORS configuration for external storage or CDN should include:
+
+```http
+Access-Control-Allow-Origin: https://your-nocobase-domain
+Access-Control-Allow-Methods: GET, HEAD
+Access-Control-Allow-Headers: *
+Access-Control-Expose-Headers: Content-Length, Content-Range, Accept-Ranges, Content-Disposition, Content-Type
+```
+
+`Access-Control-Allow-Origin` should be set to the actual domain used to access NocoBase. Avoid using `*` for non-public files over the long term, because it expands the range of sites that can read the files.

package/dist/ai/docs/nocobase/integration/api-keys/index.md

@@ -6,7 +6,7 @@
 
 ## Usage Instructions
 
-http://localhost:13000/admin/settings/api-keys/configuration
+https://example.com/admin/settings/api-keys
 
 
 ![](https://static-docs.nocobase.com/d64ccbdc8a512a0224e9f81dfe14a0a8.png)

package/dist/ai/docs/nocobase/multi-app/multi-app/app-block-and-switcher.md

@@ -0,0 +1,68 @@
+---
+pkg: '@nocobase/plugin-app-supervisor'
+title: 'Applications block and app switcher'
+description: 'Applications block and app switcher in multi-app: show sub-app entries on the frontend, configure app icons, visibility, and the app switcher in the upper-left corner.'
+keywords: 'multi-app,Applications block,app switcher,sub-app entry,NocoBase'
+---
+
+# Applications block and app switcher
+
+Besides managing sub-apps in the admin panel, multi-app can also provide app entries on the frontend. Common ways include:
+
+- Adding an "Applications" block to a page to display accessible sub-apps
+- Enabling the app switcher in the upper-left corner so users can switch between the main app and sub-apps
+
+## Applications block
+
+![](https://static-docs.nocobase.com/202605271350840.png)
+
+The "Applications" block displays a list of sub-apps on a frontend page. It is suitable for building a simple app portal, where end users can enter different business apps from one page.
+
+Each app in the block displays:
+
+- App icon
+- App name
+- Access entry
+
+Clicking an app opens the corresponding sub-app.
+
+### Configure app icons
+
+When creating or editing an app in App Supervisor, you can upload an app icon in "Display configuration".
+
+If no icon is uploaded, the system generates a default icon from the first letter of the app name, making apps easier to distinguish in the list.
+
+![](https://static-docs.nocobase.com/202605271402603.png)
+
+### Hide apps
+
+If an app should not appear in the frontend "Applications" block, select "Hide in Applications block" in the app configuration.
+
+After it is hidden:
+
+- The app can still be managed in the admin panel
+- The app can still be opened through its direct URL
+- It simply no longer appears in the frontend "Applications" block
+
+![](https://static-docs.nocobase.com/202605271403980.png)
+
+## App switcher
+
+![](https://static-docs.nocobase.com/202605271403304.png)
+
+The app switcher appears in the upper-left corner and is used to quickly switch to other apps.
+
+To show an app in the app switcher, enable "Show in app switcher" in the app configuration.
+
+After it is enabled, users can see the app switcher in the upper-left corner of the main app or sub-apps and enter other apps from the list.
+
+![](https://static-docs.nocobase.com/202605271404322.png)
+
+### Opening behavior
+
+The app switcher opens apps as follows:
+
+- From the main app to a sub-app: opens in a new tab
+- From one sub-app to another: opens in the current tab
+
+This avoids interrupting work in the main app while keeping switching between sub-apps natural.

package/dist/ai/docs/nocobase/multi-app/multi-app/app-sso.md

@@ -0,0 +1,71 @@
+---
+pkg: '@nocobase/plugin-app-supervisor'
+title: 'App SSO'
+description: 'App SSO in multi-app: automatically sign in to sub-apps from the main app or app switcher, with username mapping and automatic user signup.'
+keywords: 'multi-app,App SSO,automatic sign-in,app switcher,sub-app,NocoBase'
+---
+
+# App SSO
+
+App SSO simplifies the sign-in flow when users enter sub-apps in a multi-app setup.
+
+After it is enabled, when a user enters a sub-app from the main app entry or switches between sub-apps, the system attempts to automatically sign in to the target sub-app as the current user. Users do not need to enter their username and password repeatedly in each sub-app.
+
+## Use cases
+
+App SSO is suitable for the following scenarios:
+
+- The main app acts as a unified entry, and users enter different business sub-apps from it
+- A system is split into multiple business sub-apps, but the user sign-in experience should remain continuous
+- Users need to switch frequently between multiple sub-apps
+- User accounts are mapped between sub-apps by the same username
+
+## Enable App SSO
+
+Go to "App Supervisor", create or edit a sub-app, and enable "App SSO" in "Authentication configuration".
+
+After it is enabled, the sub-app can trigger automatic sign-in through the main app entry or the app switcher.
+
+> After changing authentication configuration, the sub-app usually needs to be restarted for the change to take effect.
+
+![](https://static-docs.nocobase.com/202605271406542.png)
+
+## Automatic user signup
+
+If the corresponding user does not exist in the target sub-app, you can enable "Automatically sign up when user does not exist".
+
+After it is enabled, when a user enters a sub-app through App SSO for the first time, the system creates a basic user in the sub-app from the user information in the main app.
+
+User mapping is mainly based on username. This means:
+
+- If the username is the same in the main app and sub-app, the user signs in as the corresponding sub-app user
+- If the username does not exist in the sub-app, the user is created only when automatic signup is enabled
+- If automatic signup is not enabled, the administrator needs to create the user in the sub-app in advance
+
+Roles and permissions after user creation are determined by the sub-app's own user and permission configuration.
+
+## Entries that trigger automatic sign-in
+
+App SSO is mainly triggered from:
+
+- Entering a sub-app from the main app's app entry
+- Entering a sub-app from the upper-left app switcher
+- Switching from one sub-app to another
+
+Directly visiting the sub-app sign-in page or the sub-app's own URL does not force the main app sign-in state. This preserves the sub-app's own sign-in methods and makes it possible to manage sub-app accounts separately when needed.
+
+## FAQ
+
+### Still not signed in automatically after enabling it?
+
+Check the following:
+
+- Whether App SSO is enabled for the sub-app
+- Whether the sub-app has been restarted so the authentication configuration takes effect
+- Whether the user entered from the main app entry or app switcher
+- Whether a user with the same username exists in the sub-app
+- If the user does not exist, whether automatic signup is enabled
+
+### Why does direct access to a sub-app not automatically sign in?
+
+This is expected. When directly visiting a sub-app, the sub-app may need to use its own sign-in method, so the main app sign-in state is not forced.

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

@@ -8,6 +8,14 @@ pkg: '@nocobase/plugin-app-supervisor'
 
 Multi-app management is a unified application management solution provided by NocoBase for creating and managing multiple physically isolated NocoBase application instances in one or more runtime environments. Through the AppSupervisor, users can create and maintain multiple applications from a unified entry point to meet the needs of different businesses and scale stages.
 
+Multi-app is suitable for the following scenarios:
+
+- Splitting a large system into multiple applications by business module, such as CRM, after-sales service, operations, and analytics
+- Letting teams develop by business line or module in parallel, reducing configuration and release impact between modules
+- Creating isolated applications for different customers, tenants, or organizations
+- Creating independent demo, test, or sandbox applications in batches
+- Assigning applications to different runtime environments as application count or load increases
+
 ## Single App
 
 In the early stages of a project, most users start with a single app.
@@ -63,4 +71,4 @@ For users, multiple applications can still be created and managed through a sing
 
 ![](https://static-docs.nocobase.com/202512231215186.png)
 
-This approach is suitable for SaaS platforms, large numbers of demo environments, or multi-tenant scenarios, improving system stability and maintainability while ensuring flexibility.
+This approach is suitable for SaaS platforms, large numbers of demo environments, or multi-tenant scenarios, improving system stability and maintainability while ensuring flexibility.

package/dist/ai/docs/nocobase/multi-app/multi-app/sub-app-api.md

@@ -0,0 +1,112 @@
+---
+pkg: '@nocobase/plugin-app-supervisor'
+title: 'Calling sub-app APIs'
+description: 'How to call sub-app APIs in multi-app: access sub-app APIs through the entry app and specify the target sub-app with a path prefix, request header, or query parameter.'
+keywords: 'multi-app,sub-app API,AppSupervisor,entry app,API call,NocoBase'
+---
+
+# Calling sub-app APIs
+
+In a multi-app setup, each sub-app has its own independent APIs. When calling a sub-app API, the entry app needs to know which sub-app the request should be routed to.
+
+For example, a main app API is usually:
+
+```bash
+GET /api/users:list
+```
+
+`/api` is the default API prefix and can be customized with the `API_BASE_PATH` environment variable.
+
+To call the same API in a sub-app, specify the sub-app name in the request.
+
+## Use a path prefix
+
+Use the `/api/__app/<appName>/` prefix to call sub-app APIs:
+
+```bash
+GET /api/__app/a_xxx/users:list
+```
+
+Where:
+
+- `a_xxx` is the sub-app name
+- `users:list` is the resource and action to call
+- `/api` is the current system's API base path
+
+Query parameters can be appended as usual:
+
+```bash
+GET /api/__app/a_xxx/users:list?page=1&pageSize=20
+```
+
+This approach is explicit and works well when sub-app APIs are accessed through the entry app in multi-environment deployments.
+
+## Specify the sub-app with a request header
+
+If the caller already uses a fixed `/api/...` address, specify the sub-app with the `X-App` request header:
+
+```bash
+curl \
+  -H "X-App: a_xxx" \
+  http://localhost:13003/api/users:list
+```
+
+This is suitable for backend service calls, or when a frontend request utility already centralizes API URLs and only needs an additional header.
+
+## Specify the sub-app with a query parameter
+
+You can also specify the sub-app with the `__appName` query parameter:
+
+```bash
+GET /api/users:list?__appName=a_xxx
+```
+
+If there are other query parameters, pass them together:
+
+```bash
+GET /api/users:list?__appName=a_xxx&page=1&pageSize=20
+```
+
+In general, the path prefix or request header is clearer because the target sub-app is more explicit.
+
+## API address in multi-environment deployments
+
+In multi-environment deployments, there is usually an entry app and multiple runtime environments.
+
+For example:
+
+- Entry app address: `http://localhost:13003`
+- Runtime environment address: `http://localhost:14000`
+
+When calling sub-app APIs, it is recommended to access them through the entry app:
+
+```bash
+GET http://localhost:13003/api/__app/a_xxx/users:list
+```
+
+The entry app routes the request to the corresponding sub-app according to the app configuration. If you clearly know which runtime environment to access, you can also call through that environment address.
+
+```bash
+GET http://localhost:14000/api/__app/a_xxx/users:list
+```
+
+## Sub-app custom domains
+
+If a sub-app has its own access domain, you can also call that sub-app's APIs directly through that domain:
+
+```bash
+GET https://app-example.example.com/api/users:list
+```
+
+If you want to go through the entry app uniformly, continue using the entry app's `/api/__app/<appName>/...` address.
+
+## Authentication
+
+When calling sub-app APIs, permission checks are still based on the target sub-app.
+
+This means:
+
+- A sign-in state or access token valid for the sub-app is required
+- The main app sign-in state does not automatically equal API permissions in the sub-app
+
+If the request does not carry valid authentication information, the sub-app returns an unauthenticated or unauthorized error according to its own authentication configuration.