@nocobase/plugin-ai 2.3.0-beta.3 → 3.0.0-alpha.11

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

@@ -1,7 +1,7 @@
 ---
 title: 'NocoBase CLI'
-description: 'NocoBase CLI (`nb` command) reference: initialization, backup and restore, configuration, environment management, app runtime, source code, database, plugins, commercial license, API, CLI self-update, and Skills management.'
-keywords: 'NocoBase CLI,nb,command line,command reference,backup,restore,environment management,plugin management,commercial license,API'
+description: 'NocoBase CLI (`nb` command) reference: initialization, backup and restore, configuration, environment management, app runtime, portal, source code, database, plugins, commercial license, API, CLI self-update, and Skills management.'
+keywords: 'NocoBase CLI,nb,command line,command reference,backup,restore,environment management,Portal,plugin management,commercial license,API'
 ---
 
 # NocoBase CLI
@@ -39,6 +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 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.           |
@@ -70,6 +71,8 @@ nb backup --help
 nb config --help
 nb api resource --help
 nb license --help
+nb portal --help
+nb portal config --help
 ```
 
 ## Examples
@@ -127,6 +130,15 @@ nb license status -e app1
 nb license plugins list -e app1
 ```
 
+Create and develop a portal:
+
+```bash
+nb portal create customer -e app1 --yes
+nb portal config customer -e app1 --yes --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
+nb portal dev customer -e app1 --yes
+nb portal deploy customer -e app1 --yes
+```
+
 Create and download a backup:
 
 ```bash

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

@@ -0,0 +1,46 @@
+---
+title: "nb portal config"
+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 portal development path, source storage, and Git source configuration
+
+## Usage
+
+```bash
+nb portal config <portal> [flags]
+```
+
+## Flag
+
+| 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. |
+| `--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`. |
+| `--git-path` | string | Directory inside the Git repository; defaults to the repository root (`.`). |
+
+## 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
+```
+
+## Notes
+
+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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,45 @@
+---
+title: "nb portal create"
+description: "nb portal create command reference: create a local portal from a template and create or update the portal record."
+keywords: "nb portal create,NocoBase CLI,Portal"
+---
+
+# nb portal create
+
+Create a local portal from a template and create or update the portal record
+
+## Usage
+
+```bash
+nb portal create <portal> [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `<portal>` | string | Portal name or slug. |
+| `--template` | string | Template package, local path, or `file://` URL. Default: `@nocobase/portal-template-default`. |
+| `--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. |
+
+## 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
+```
+
+## Notes
+
+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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,39 @@
+---
+title: "nb portal deploy"
+description: "nb portal deploy command reference: build and deploy a portal."
+keywords: "nb portal deploy,NocoBase CLI,Portal"
+---
+
+# nb portal deploy
+
+Build and deploy the specified portal
+
+## Usage
+
+```bash
+nb portal deploy <portal> [flags]
+```
+
+## Flag
+
+| 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. |
+
+## Examples
+
+```bash
+nb portal deploy customer
+nb portal deploy customer --env dev --yes
+```
+
+## Notes
+
+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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,43 @@
+---
+title: "nb portal destroy"
+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 deployed files.
+
+## Usage
+
+```bash
+nb portal destroy <portal> [flags]
+```
+
+## Flag
+
+| 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 confirmation prompts. |
+| `--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 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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,51 @@
+---
+title: "nb portal dev"
+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'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
+
+```bash
+nb portal dev <portal> [flags]
+```
+
+## Flag
+
+| 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 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
+
+`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 create`](./create.md)
+- [`nb portal pull`](./pull.md)
+- [`nb portal deploy`](./deploy.md)

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

@@ -0,0 +1,142 @@
+---
+title: "nb portal"
+description: "nb portal command reference: manage portals, including configuration, creation, development, source sync, deployment, and deletion."
+keywords: "nb portal,NocoBase CLI,Portal,workspace,source storage,deploy"
+---
+
+# nb portal
+
+`nb portal` manages portals. A portal can have its own frontend source, entry path, and deployment output; this command group connects the portal record in NocoBase with the local workspace and source storage.
+
+A typical flow is to create a local workspace, start development mode, push source changes to source storage, and then build and deploy. If you are taking over an existing portal, pull it locally first.
+
+## Usage
+
+```bash
+nb portal <command>
+```
+
+## Subcommands
+
+| Command | Description |
+| --- | --- |
+| [`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 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
+
+Create a portal named `customer`:
+
+```bash
+nb portal create customer -e dev --yes
+```
+
+Start local development mode:
+
+```bash
+nb portal dev customer -e dev --yes
+```
+
+Inspect the local workspace and remote record:
+
+```bash
+nb portal info customer -e dev --yes
+nb portal list -e dev --yes
+```
+
+Push source and deploy:
+
+```bash
+nb portal push customer -e dev --yes --message "Update customer portal"
+nb portal deploy customer -e dev --yes
+```
+
+Take over an existing portal:
+
+```bash
+nb portal list -e dev --yes
+nb portal pull customer -e dev --yes
+nb portal dev customer -e dev --yes
+```
+
+Switch source storage:
+
+```bash
+nb portal config customer -e dev --yes --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
+nb portal push customer -e dev --yes --message "Move customer portal source to Git"
+```
+
+## source storage
+
+Portal source storage is stored in the remote portal record options:
+
+| Mode | Description |
+| --- | --- |
+| `nocobase` | Default mode. Source code is managed by NocoBase source storage. |
+| `git` | Source code is stored in a Git repository, configured with `--git-repo`, `--git-branch`, and `--git-path`. |
+
+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.
+
+`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
+
+`nb portal` currently supports `local`, `docker`, and `http` envs:
+
+| Mode | Description |
+| --- | --- |
+| `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.
+
+## Development And Deployment Paths
+
+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>
+```
+
+The main app access path is usually:
+
+```text
+<appPublicPath>/x/<portal>/
+```
+
+A sub-app access path is usually:
+
+```text
+<appPublicPath>/x/apps/<app>/<portal>/
+```
+
+## Env Confirmation
+
+Most `nb portal` subcommands support `--env` and `--yes`:
+
+| Flag | Description |
+| --- | --- |
+| `--env`, `-e` | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | Skip cross-env confirmation when an explicit `--env` targets a different env from the current env. |
+
+In scripts or AI agent workflows, pass `--env` and `--yes` explicitly to avoid stopping at an interactive confirmation.
+
+## Related Commands
+
+- [`nb env`](../env/index.md)
+- [`nb app`](../app/index.md)
+- [`nb source`](../source/index.md)

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

@@ -0,0 +1,41 @@
+---
+title: "nb portal info"
+description: "nb portal info command reference: show portal record and local workspace details."
+keywords: "nb portal info,NocoBase CLI,Portal"
+---
+
+# nb portal info
+
+Show details for the specified portal record and local workspace
+
+## Usage
+
+```bash
+nb portal info <portal> [flags]
+```
+
+## Flag
+
+| 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. |
+| `--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
+```
+
+## Notes
+
+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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,40 @@
+---
+title: "nb portal list"
+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 development paths
+
+## Usage
+
+```bash
+nb portal list [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--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
+```
+
+## Notes
+
+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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,53 @@
+---
+title: "nb portal pull"
+description: "nb portal pull command reference: pull portal source into the local workspace."
+keywords: "nb portal pull,NocoBase CLI,Portal"
+---
+
+# nb portal pull
+
+Pull portal source from source storage into the local workspace
+
+## Usage
+
+```bash
+nb portal pull <portal> [flags]
+```
+
+## Flag
+
+| 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. |
+| `--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
+
+```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`. 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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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

@@ -0,0 +1,41 @@
+---
+title: "nb portal push"
+description: "nb portal push command reference: push local portal source changes to source storage."
+keywords: "nb portal push,NocoBase CLI,Portal"
+---
+
+# nb portal push
+
+Push local portal source changes to source storage
+
+## Usage
+
+```bash
+nb portal push <portal> [flags]
+```
+
+## Flag
+
+| 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. |
+| `--message`, `-m` | string | Source update message; for Git-managed source, it is used as the Git commit message. |
+
+## Examples
+
+```bash
+nb portal push customer
+nb portal push customer --env prod --yes
+nb portal push customer --message "Update customer portal"
+```
+
+## Notes
+
+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
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)

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/get-started/installation/env.md

@@ -146,7 +146,7 @@ For example, to add the `hello` plugin to the `my-nocobase-app` project, the plu
 PLUGIN_PACKAGE_PREFIX can be configured as:
 
 ```bash
-PLUGIN_PACKAGE_PREFIX=@nocobase/plugin-,@nocobase-preset-,@my-nocobase-app/plugin-
+PLUGIN_PACKAGE_PREFIX=@nocobase/plugin-,@nocobase/preset-,@my-nocobase-app/plugin-
 ```
 
 The correspondence between plugin name and package name is as follows:

package/dist/ai/docs/nocobase/nocobase-cli/installation/cli.md

@@ -9,7 +9,7 @@ Only executed when installing the CLI for the first time.
 First install the CLI globally:
 
 ```bash
-npm install -g @nocobase/cli
+npm install -g @nocobase/cli@alpha
 nb --version
 ```
 

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-action-bulk-edit/index.md

@@ -10,7 +10,7 @@ description: |
   Batch edit all records or selected records.
 isFree: true
 builtIn: true
-defaultEnabled: false
+defaultEnabled: true
 editionLevel: 0
 ---
 

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-action-bulk-update/index.md

@@ -10,7 +10,7 @@ description: |
   Batch update all records or selected records.
 isFree: true
 builtIn: true
-defaultEnabled: false
+defaultEnabled: true
 editionLevel: 0
 ---
 

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-action-custom-request/index.md

@@ -10,7 +10,7 @@ description: |
   Sending a request to any HTTP service supports sending context data to the target service.
 isFree: true
 builtIn: true
-defaultEnabled: false
+defaultEnabled: true
 editionLevel: 0
 ---
 

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-action-duplicate/index.md

@@ -10,7 +10,7 @@ description: |
   Duplicate a record, you can either duplicate it into a form and edit it before saving it, or you can duplicate it directly to generate a new record.
 isFree: true
 builtIn: true
-defaultEnabled: false
+defaultEnabled: true
 editionLevel: 0
 ---
 

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-action-export/index.md

@@ -10,7 +10,7 @@ description: |
   Export filtered records to excel, you can configure which fields to export.
 isFree: true
 builtIn: true
-defaultEnabled: false
+defaultEnabled: true
 editionLevel: 0
 ---
 

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-action-import/index.md

@@ -10,7 +10,7 @@ description: |
   Import records using excel templates. You can configure which fields to import and templates will be generated automatically.
 isFree: true
 builtIn: true
-defaultEnabled: false
+defaultEnabled: true
 editionLevel: 0
 ---