@nocobase/plugin-ai 3.0.0-alpha.1 → 3.0.0-alpha.11

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

@@ -1,29 +1,59 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "RAG Retrieval-Augmented Generation"
+description: "Enable RAG for AI employees, configure the Knowledge Base, Retrieval strategy, Top K, and Score, and control knowledge-base access through user roles."
+keywords: "RAG,retrieval-augmented generation,knowledge-base retrieval,Retrieval strategy,knowledge-base permissions,Top K,NocoBase"
+---
+
 # RAG Retrieval
 
 ## Introduction
 
-After configuring the knowledge base, you can enable the RAG feature in the AI employee settings.
+In NocoBase, **RAG (Retrieval-Augmented Generation)** enables an AI employee to retrieve relevant content from knowledge bases before answering a question.
+
+The knowledge bases an AI employee can actually use are determined by both the employee's `Knowledge Base` configuration and the knowledge-base permissions of the current user's roles. Only knowledge bases included in both scopes are searched.
+
+## Configure an AI employee's knowledge bases
+
+Go to the `AI employees` configuration page, select the AI employee for which you want to enable RAG, and click `Edit`. In the edit drawer, open the `Knowledge Base` tab and turn on `Enable`.
+
+![](https://static-docs.nocobase.com/ai-employee-knowledge-base-settings-202608171620.png)
+
+The available settings are:
+
+- `Knowledge Base` — Optional. If left empty, the AI employee searches all enabled knowledge bases accessible to the current user's roles. If you select knowledge bases, it searches only the selected knowledge bases that the user is allowed to access
+- `Retrieval strategy` — Controls when knowledge-base retrieval runs:
+  - `Retrieve on demand` — The AI employee retrieves knowledge-base content only when it determines that the current question requires it. New AI employees use this strategy by default, and it is the recommended option for most cases
+  - `Automatically retrieve for every question` — Retrieval runs before every user question is sent to the AI employee. Use this when every turn depends on knowledge-base content
+- `Knowledge Base Prompt` — Defines how retrieved content is provided to the AI employee. `{knowledgeBaseData}` is a fixed placeholder; do not remove or modify it
+- `Top K` — The maximum number of knowledge-base results returned by each retrieval. The range is 1–100, and the default is 3
+- `Score` — The minimum similarity score required for a result. The range is 0–1, and the default is 0.6. A higher value returns more relevant content, but may produce fewer results
+
+Click `Submit` to save the configuration.
+
+## Configure knowledge-base permissions
 
-With RAG enabled, when a user chats with an AI employee, the AI employee will use RAG retrieval to fetch documents from the knowledge base based on the user's message and reply based on the retrieved documents.
+Selecting knowledge bases for an AI employee does not give every user access to them. Go to `Users & Permissions / Roles & Permissions`, select the role assigned to the user, and then open `Permissions / Knowledge bases`.
 
-## Enable RAG
+Select `Available` for each knowledge base that the role should be allowed to access. To automatically grant this role access to knowledge bases created later, select `New knowledge bases are allowed by default`.
 
-Go to the AI employee plugin configuration page, click the `AI employees` tab to enter the AI employee management page.
+![](https://static-docs.nocobase.com/knowledge-base-role-permissions-202608171620.png)
 
+:::warning Note
 
-![20251023010811](https://static-docs.nocobase.com/20251023010811.png)
+The knowledge-base scope available to an AI employee is the intersection of its `Knowledge Base` configuration and the current user's role permissions. Unauthorized knowledge bases are automatically excluded.
 
+:::
 
-Select the AI employee for which you want to enable RAG, click the `Edit` button to enter the AI employee editing page.
+## When the user has no knowledge-base access
 
-In the `Knowledge base` tab, turn on the `Enable` switch.
+If knowledge bases are enabled for an AI employee but its configured scope has no overlap with the current user's role permissions, the AI employee first answers with information that does not depend on a knowledge base. It then appends a prominent notice explaining that no knowledge-base content was used because the user does not have access and advising the user to contact an administrator.
 
-- In `Knowledge Base Prompt`, enter the prompt for referencing the knowledge base. `{knowledgeBaseData}` is a fixed placeholder and should not be modified.
-- In `Knowledge Base`, select the configured knowledge base. See: [Knowledge Base](./knowledge-base/).
-- In the `Top K` input box, enter the number of documents to retrieve, the default is 3.
-- In the `Score` input box, enter the document relevance threshold for retrieval.
+![](https://static-docs.nocobase.com/ai-employee-no-knowledge-base-access-side-panel-202608171653.png)
 
-Click the `Submit` button to save the AI employee settings.
+If the user can access at least one knowledge base but the current question returns no relevant content, the no-permission notice is not displayed.
 
+## Related links
 
-![20251023010844](https://static-docs.nocobase.com/20251023010844.png)
+- [Knowledge Base](./knowledge-base/index.md) — Create and maintain knowledge bases used for RAG retrieval
+- [Roles and permissions](../../users-permissions/acl/permissions.md) — Configure system, menu, and data access for roles

package/dist/ai/docs/nocobase/api/cli/api/resource/create.md

@@ -1,12 +1,12 @@
 ---
 title: "nb api resource create"
-description: "nb api resource create command reference: create a record in a selected NocoBase resource."
+description: "nb api resource create command reference: create one or more records in a selected NocoBase resource."
 keywords: "nb api resource create,NocoBase CLI,create record,CRUD"
 ---
 
 # nb api resource create
 
-Create a record in a selected resource. Pass record data as a JSON object through `--values`.
+Create records in a selected resource. Pass record data as a JSON object through `--values`, or as a JSON array of objects to create multiple records in a single request.
 
 ## Usage
 
@@ -21,7 +21,7 @@ nb api resource create --resource <resource> --values <json> [flags]
 | `--resource` | string | Resource name, required |
 | `--data-source` | string | Data source key, default `main` |
 | `--source-id` | string | Source record ID for association resources |
-| `--values` | string | Data for the new record as a JSON object, required |
+| `--values` | string | Data for the new records: a JSON object, or a JSON array of objects to create multiple records; required |
 | `--whitelist` | string[] | Fields allowed to write; repeatable or pass a JSON array |
 | `--blacklist` | string[] | Fields forbidden to write; repeatable or pass a JSON array |
 
@@ -31,6 +31,7 @@ Also supports common connection parameters from [`nb api resource`](./index.md).
 
 ```bash
 nb api resource create --resource users --values '{"nickname":"Ada"}'
+nb api resource create --resource users --values '[{"nickname":"Ada"},{"nickname":"Grace"}]'
 nb api resource create --resource posts.comments --source-id 1 --values '{"content":"Hello"}'
 ```
 

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

@@ -39,7 +39,7 @@ The following command groups are shown in `nb --help`:
 | [`nb env`](./env/index.md)           | Manage NocoBase project environments, the current env, status, details, and runtime commands. |
 | [`nb license`](./license/index.md)   | Manage commercial licenses and licensed plugins.                                              |
 | [`nb plugin`](./plugin/index.md)     | Manage plugins in the selected NocoBase env.                                                  |
-| [`nb portal`](./portal/index.md)     | Manage portals: configure, create, develop, sync source, deploy, and destroy.                       |
+| [`nb portal`](./portal/index.md)     | Manage a Portal's local source directory: configure, create, develop, sync source, deploy, and destroy. |
 | [`nb scaffold`](./scaffold/index.md) | Generate scaffolding for NocoBase plugin development.                                         |
 | [`nb self`](./self/index.md)         | Check or update NocoBase CLI itself.                                                          |
 | [`nb session`](./session/index.md)   | Configure `NB_SESSION_ID` so the current env is isolated by shell or agent runtime.           |

package/dist/ai/docs/nocobase/api/cli/portal/config.md

@@ -1,12 +1,12 @@
 ---
 title: "nb portal config"
-description: "nb portal config command reference: update source storage and Git source configuration for a portal."
+description: "nb portal config command reference: update the development path, source storage, and Git source configuration for a portal."
 keywords: "nb portal config,NocoBase CLI,Portal"
 ---
 
 # nb portal config
 
-Update the local portal source configuration and sync it to the remote portal record when possible
+Update the portal development path, source storage, and Git source configuration
 
 ## Usage
 
@@ -21,6 +21,7 @@ nb portal config <portal> [flags]
 | `<portal>` | string | Portal name or slug |
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--path` | string | Portal development workspace directory. |
 | `--source-storage` | `nocobase` \| `git` | Where portal source code is managed. |
 | `--git-repo` | string | Git repository URL used with `--source-storage=git`. |
 | `--git-branch` | string | Git branch used with `--source-storage=git`. |
@@ -29,6 +30,7 @@ nb portal config <portal> [flags]
 ## Examples
 
 ```bash
+nb portal config customer --path ./portals/customer
 nb portal config customer --source-storage nocobase
 nb portal config customer --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
 nb portal config customer --git-branch main --git-path portals/customer
@@ -36,7 +38,7 @@ nb portal config customer --git-branch main --git-path portals/customer
 
 ## Notes
 
-Pass at least one configuration flag. The local workspace must already exist; use `nb portal create` or `nb portal pull` first. If the remote portal record exists, the configuration is synced to it; otherwise only `portal.config.json` is updated locally.
+Pass at least one configuration flag. `--path` updates the selected CLI env config. `--source-storage` and `--git-*` update the remote portal record options.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/create.md

@@ -23,24 +23,21 @@ nb portal create <portal> [flags]
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
 | `--title` | string | Portal display title. |
+| `--path` | string | Portal workspace directory. Default: `./<portal>`. |
 | `--force` | boolean | Delete the existing workspace and recreate it. |
-| `--source-storage` | `nocobase` \| `git` | Where portal source code is managed. Default: `nocobase`. |
-| `--git-repo` | string | Git repository URL used with `--source-storage=git`. |
-| `--git-branch` | string | Git branch used with `--source-storage=git`. |
-| `--git-path` | string | Directory inside the Git repository; defaults to the repository root (`.`). |
 
 ## Examples
 
 ```bash
 nb portal create customer
+nb portal create customer --path ./portals/customer
 nb portal create customer --template @nocobase/portal-template-default
 nb portal create customer --env dev --yes
-nb portal create customer --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
 ```
 
 ## Notes
 
-The command writes `.env`, `.env.local`, and `portal.config.json`. If the template contains `package.json`, it runs `pnpm install`. Portal names must use lowercase letters, numbers, underscores, or hyphens, and start with a lowercase letter or number.
+The command writes `.env` and `.env.local`, stores the workspace path in the selected CLI env config, and runs `pnpm install` when the template contains `package.json`. Portal names must use lowercase letters, numbers, underscores, or hyphens, and start with a lowercase letter or number.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/deploy.md

@@ -31,7 +31,7 @@ nb portal deploy customer --env dev --yes
 
 ## Notes
 
-The command refreshes `.env` and `.env.local`, runs `pnpm build`, and expects `dist/index.html`. For `local` and `docker` envs, it syncs the portal record and uses the local or volume-mounted `dist`; for `http` envs, it uploads the packed `dist` through the API.
+The command refreshes `.env` and `.env.local`, builds from the development path stored in the selected CLI env config, and syncs deployment output to the target app storage. Source storage and Git settings are managed by `nb portal config` in the remote portal record.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/destroy.md

@@ -1,12 +1,12 @@
 ---
 title: "nb portal destroy"
-description: "nb portal destroy command reference: delete a portal record and its local workspace."
+description: "nb portal destroy command reference: delete a portal record and its deployed files."
 keywords: "nb portal destroy,NocoBase CLI,Portal"
 ---
 
 # nb portal destroy
 
-Delete the portal record and local workspace
+Delete the portal record and deployed files.
 
 ## Usage
 
@@ -21,19 +21,21 @@ nb portal destroy <portal> [flags]
 | `<portal>` | string | Portal name or slug. |
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip confirmation prompts. |
-| `--force` | boolean | Ignore missing portal records or workspace directories. |
+| `--force` | boolean | Ignore missing portal records or deployment directories. |
+| `--delete-dev-path`, `-D` | boolean | Delete the portal development directory in addition to the deployed portal. |
 
 ## Examples
 
 ```bash
 nb portal destroy customer --yes
+nb portal destroy customer --delete-dev-path --yes
 nb portal destroy customer --env dev --yes
 nb portal destroy customer --force --yes
 ```
 
 ## Notes
 
-This command affects both the remote portal record and the local workspace. In non-interactive mode, pass `--yes`. Use `--force` to ignore missing records or local files.
+This command deletes the remote portal record and deployed files. The development directory is retained by default; pass `--delete-dev-path` to delete it as well. In non-interactive mode, pass `--yes`. Use `--force` to ignore missing records or deployment files.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/dev.md

@@ -1,12 +1,14 @@
 ---
 title: "nb portal dev"
-description: "nb portal dev command reference: start a portal in development mode."
-keywords: "nb portal dev,NocoBase CLI,Portal"
+description: "nb portal dev command reference: start development mode for a Portal's local source directory."
+keywords: "nb portal dev,NocoBase CLI,Portal,development mode,local development"
 ---
 
 # nb portal dev
 
-Start development mode for the specified portal
+Start development mode for the specified Portal's local source directory. It is normally used after [`nb portal create`](./create.md) or [`nb portal pull`](./pull.md).
+
+It refreshes `.env` and `.env.local` in the local source directory, then runs `pnpm dev` there.
 
 ## Usage
 
@@ -18,22 +20,32 @@ nb portal dev <portal> [flags]
 
 | Flag | Type | Description |
 | --- | --- | --- |
-| `<portal>` | string | Portal name or slug. |
-| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
-| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `<portal>` | string | Portal name or slug |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used |
+| `--yes`, `-y` | boolean | Skip the interactive confirmation when an explicit `--env` differs from the current env |
 
 ## Examples
 
+Start development mode for a Portal in the current env:
+
 ```bash
 nb portal dev customer
+```
+
+Start development mode for a Portal in a specified env:
+
+```bash
 nb portal dev customer --env dev --yes
 ```
 
 ## Notes
 
-The workspace must contain `package.json`. The command refreshes `.env` and `.env.local`, then runs `pnpm dev`. `ssh` envs are not supported in the current version.
+`dev` starts the dev server from the Portal's local source directory. It doesn't create a Portal record, and it doesn't pull remote source; if the local source directory doesn't exist, use [`nb portal create`](./create.md) or [`nb portal pull`](./pull.md) first.
+
+The local source directory must contain `package.json`. `ssh` envs don't support starting Portal development mode yet.
 
 ## Related Commands
 
-- [`nb portal`](./index.md)
-- [`nb env`](../env/index.md)
+- [`nb portal create`](./create.md)
+- [`nb portal pull`](./pull.md)
+- [`nb portal deploy`](./deploy.md)

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

@@ -20,14 +20,14 @@ nb portal <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb portal config`](./config.md) | Update the local portal source configuration and sync it to the remote portal record when possible |
-| [`nb portal create`](./create.md) | Create a local portal from a template and create or update the portal record |
-| [`nb portal deploy`](./deploy.md) | Build and deploy the specified portal |
-| [`nb portal destroy`](./destroy.md) | Delete the portal record and local workspace |
+| [`nb portal config`](./config.md) | Update portal source configuration |
+| [`nb portal create`](./create.md) | Create a local AI portal from a template |
+| [`nb portal deploy`](./deploy.md) | Build and deploy a portal |
+| [`nb portal destroy`](./destroy.md) | Destroy a portal record and deployed files |
 | [`nb portal dev`](./dev.md) | Start development mode for the specified portal |
-| [`nb portal info`](./info.md) | Show details for the specified portal record and local workspace |
-| [`nb portal list`](./list.md) | List portal records and local workspace sync status |
-| [`nb portal pull`](./pull.md) | Pull portal source from source storage into the local workspace |
+| [`nb portal info`](./info.md) | Show portal record and local file details |
+| [`nb portal list`](./list.md) | List portal records and development paths |
+| [`nb portal pull`](./pull.md) | Pull portal source into local files |
 | [`nb portal push`](./push.md) | Push local portal source changes to source storage |
 
 ## Typical Flow
@@ -75,7 +75,7 @@ nb portal push customer -e dev --yes --message "Move customer portal source to G
 
 ## source storage
 
-When creating a portal, choose where the source code is managed:
+Portal source storage is stored in the remote portal record options:
 
 | Mode | Description |
 | --- | --- |
@@ -84,7 +84,7 @@ When creating a portal, choose where the source code is managed:
 
 For quick creation and development, the default `nocobase` storage is usually enough. Use `git` when the portal source should be reviewed, versioned, or built through an existing team workflow.
 
-Source configuration is written to `portal.config.json` in the local workspace. `create`, `pull`, and `config` maintain this file; `push` and `deploy` read it to sync source or deployment output.
+`nb portal config` updates source storage and Git settings in the remote portal record. The development workspace path is stored separately in the CLI env config as `portals.<portal>.path`, maintained by `create`, `pull --path`, or `config --path`.
 
 ## Env Types
 
@@ -92,15 +92,21 @@ Source configuration is written to `portal.config.json` in the local workspace.
 
 | Mode | Description |
 | --- | --- |
-| `local` | The workspace and app storage are on the current machine. With default `nocobase` storage, `pull`/`push` usually do not need extra sync. |
-| `docker` | The workspace is shared with the app through a Docker volume. With default `nocobase` storage, `pull`/`push` usually do not need extra sync. |
+| `local` | The workspace and app storage are on the current machine. `pull` writes source to the development path, and `deploy` builds from that path before syncing deployment output. |
+| `docker` | The workspace is shared with the app through a Docker volume. `pull` writes source to the development path, and `deploy` builds from that path before syncing deployment output. |
 | `http` | Source and deployment output are synced through APIs. `pull` downloads a source archive, and `push` uploads one. |
 
 `ssh` envs do not support portal management in the current version.
 
-## Local Workspace Path
+## Development And Deployment Paths
 
-Portals are stored under the selected env storage:
+Portal development workspaces are created under the current working directory by default:
+
+```text
+./<portal>
+```
+
+Use `--path` with `create`, `pull`, or `config` to choose a different development path. Deployment output is still stored under the target app storage:
 
 ```text
 <storagePath>/portals/<app>/<portal>

package/dist/ai/docs/nocobase/api/cli/portal/info.md

@@ -21,19 +21,19 @@ nb portal info <portal> [flags]
 | `<portal>` | string | Portal name or slug. |
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
-| `--json-output`, `-j` | boolean | Print portal details as JSON. |
+| `--json-output`, `--json`, `-j` | boolean | Print portal details as JSON. |
 
 ## Examples
 
 ```bash
 nb portal info customer
 nb portal info customer --env dev --yes
-nb portal info customer --json-output
+nb portal info customer --json
 ```
 
 ## Notes
 
-Text output includes name, URL, portal type, local path, enabled status, and local sync status. `--json-output` prints `name`, `url`, `portalType`, `localPath`, `enabled`, `sourceStorage`, and `localSynced`. You can query by `routeName` or `uid`.
+Text output includes name, URL, portal type, development path, deployment path, and enabled status. `--json-output` and its alias `--json` print `name`, `url`, `portalType`, `developmentPath`, `deploymentPath`, `enabled`, `isDefault`, and `sourceStorage`. You can query by `routeName` or `uid`.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/list.md

@@ -1,12 +1,12 @@
 ---
 title: "nb portal list"
-description: "nb portal list command reference: list portal records and local workspace sync status."
+description: "nb portal list command reference: list portal records and development paths."
 keywords: "nb portal list,NocoBase CLI,Portal"
 ---
 
 # nb portal list
 
-List portal records and local workspace sync status
+List portal records and development paths
 
 ## Usage
 
@@ -20,19 +20,19 @@ nb portal list [flags]
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
-| `--json-output`, `-j` | boolean | Print portal records as JSON. |
+| `--json-output`, `--json`, `-j` | boolean | Print portal records as JSON. |
 
 ## Examples
 
 ```bash
 nb portal list
 nb portal list --env dev --yes
-nb portal list --json-output
+nb portal list --json
 ```
 
 ## Notes
 
-The list shows name, URL, portal type, source storage, local path, enabled status, and local sync status. Only `ai` portals have local workspace sync checks; other portal types show an empty sync status.
+The list shows name, URL, portal type, source storage, development path, enabled status, and default status. `--json-output` and its alias `--json` print `name`, `url`, `portalType`, `developmentPath`, `deploymentPath`, `enabled`, `isDefault`, and `sourceStorage`.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/pull.md

@@ -22,6 +22,10 @@ nb portal pull <portal> [flags]
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
 | `--force` | boolean | Delete the existing local workspace and pull it again. |
+| `--path` | string | Portal workspace directory. Defaults to the saved path, then `./<portal>`. |
+| `--git-repo` | string | Temporarily pull source from this Git repository without updating the portal source configuration. |
+| `--git-branch` | string | Git branch for the temporary `--git-repo` pull. Defaults to `main`. |
+| `--git-path` | string | Directory inside the temporary Git repository. Defaults to the repository root (`.`). |
 | `--install` / `--no-install` | boolean | Run `pnpm install` after pulling source. Enabled by default. |
 
 ## Examples
@@ -29,13 +33,19 @@ nb portal pull <portal> [flags]
 ```bash
 nb portal pull customer
 nb portal pull customer --env prod --yes
+nb portal pull customer --path ./portals/customer
+nb portal pull customer --git-repo git@github.com:nocobase/customer-portal.git --git-branch main --git-path portals/customer
 nb portal pull customer --force
 nb portal pull customer --no-install
 ```
 
 ## Notes
 
-When the pulled workspace contains `package.json`, `pnpm install` runs by default. Use `--no-install` to skip it. Git source storage clones the configured repo and branch, then copies `--git-path`. With default `nocobase` storage, `local` and `docker` envs are usually no-op; `http` envs download a source archive through the API.
+When the pulled workspace contains `package.json`, `pnpm install` runs by default. Use `--no-install` to skip it.
+
+Git source storage clones the configured repo and branch, then copies `--git-path`. To pull from a Git repo one time without changing the remote portal record, pass `--git-repo`; `--git-branch` and `--git-path` can only be used together with `--git-repo`. Use `nb portal config` when you want to persist Git source settings.
+
+With default `nocobase` storage, `pull` downloads a source archive through the API and writes it to the development workspace. After a successful pull, the development workspace path is saved to the CLI env config as `portals.<portal>.path`.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/push.md

@@ -33,7 +33,7 @@ nb portal push customer --message "Update customer portal"
 
 ## Notes
 
-The command reads `portal.config.json` and syncs that configuration to the remote portal record first. Git source storage clones the configured repo, copies the local workspace into `--git-path`, commits, and pushes. With default `nocobase` storage, `local` and `docker` envs are usually no-op; `http` envs upload a source archive through the API.
+The command reads source storage and Git settings from the remote portal record, then reads local source from the development path stored in the selected CLI env config. Git source storage clones the configured repo, copies the local workspace into `--git-path`, commits, and pushes. With default `nocobase` storage, `local` and `docker` envs are usually no-op; `http` envs upload a source archive through the API.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/development/index.md

@@ -52,5 +52,5 @@ features:
         link: /file-manager/development
       - title: Knowledge Base Extension
         details: Connect external knowledge bases or custom retrieval services to extend RAG retrieval sources for AI employees.
-        link: /ai-employees/knowledge-base/dev/external-knowledge-base
+        link: /ai-employees/dev/knowledge-base/external-knowledge-base
 ---

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

@@ -8,12 +8,53 @@ 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)
+- [Office File Preview Plugin](./ms-office.md)
 
-## PDF preview with external storage
+## PDF preview mechanism
 
-NocoBase previews PDFs through a browser iframe. Some browsers or PDF readers may support scripts, forms, or other interactive content inside PDF files. If the previewed file comes from an untrusted source, pay attention to the security boundary for script execution.
+NocoBase selects the PDF preview method according to whether the file URL has the same origin as the current page:
+
+| File URL | Common storage type | Preview method | CORS requirement |
+| --- | --- | --- | --- |
+| Same origin as NocoBase | Local storage | NocoBase reads the file and renders it with the built-in PDF.js viewer | No cross-origin CORS involved |
+| Cross-origin | Third-party storage such as OSS, S3, COS, or a CDN | The browser opens the file URL in an iframe | The iframe preview itself does not require CORS |
+
+:::tip What determines the preview method
+
+The preview method depends on whether the file URL is same-origin, not directly on the storage engine name. Local storage served from a separate file domain is treated as cross-origin. Third-party storage accessed through a same-origin NocoBase proxy is treated as same-origin.
+
+:::
+
+### Local storage or a same-origin URL
+
+Local storage URLs usually start with `/storage/uploads/` and have the same origin as the NocoBase page. During preview, NocoBase reads the PDF data and passes it to the built-in PDF.js viewer to render pages and text.
+
+This method does not depend on the browser's built-in PDF reader. Even if the file response uses `Content-Disposition: attachment` for security, NocoBase can still read and render the file in the preview component. The file URL must remain accessible with the current login state.
+
+### Third-party storage or a cross-origin URL
+
+Third-party storage such as OSS, S3, COS, and CDNs usually uses a separate domain. NocoBase places this PDF URL in an iframe, so the browser and the storage service's response headers determine the result.
+
+To open a PDF in the iframe, the storage service should normally return `Content-Type: application/pdf` and must not force a download with `Content-Disposition: attachment`. If the response requests a download, the browser downloads the file directly and NocoBase cannot override that behavior in the frontend.
+
+Loading a cross-origin PDF in an iframe does not itself require CORS. However, the download button in the preview component reads the file with `fetch` and creates a Blob, so cross-origin downloads still require the storage service to allow CORS requests from the NocoBase site.
+
+### Notes for Aliyun OSS
+
+In some cases, the default Aliyun OSS domain forces a download by returning `Content-Disposition: attachment` and `x-oss-force-download: true`. Images may still preview normally, while a PDF placed in an iframe is downloaded.
+
+You can usually resolve this by binding a custom domain to the bucket and configuring NocoBase to access files through that domain. See [Aliyun OSS troubleshooting](../storage/aliyun-oss.md#common-issues) for configuration and diagnostic steps.
+
+### Security boundary for cross-origin previews
+
+Some browsers or PDF readers may support scripts, forms, or other interactive content inside PDF files. If the previewed file comes from an untrusted source, pay attention to the security boundary for script execution.
 
 We recommend isolating the file access domain from the NocoBase site and API domains. For example, serve files from OSS, S3, COS, or a CDN through a dedicated domain, instead of sharing the same origin with the NocoBase frontend or API.
 
 If the file domain is different from the API domain, and the API does not enable CORS access for the file domain, scripts running in the PDF preview environment are usually restricted by the browser's same-origin policy. They cannot directly read the NocoBase page, browser storage, or API responses.
+
+## Related links
+
+- [Office File Preview Plugin](./ms-office.md)
+- [Aliyun OSS](../storage/aliyun-oss.md)
+- [S3 Pro](../storage/s3-pro.md)