@nocobase/plugin-ai 2.2.0-beta.1 → 2.2.0-beta.10

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

@@ -1,7 +1,7 @@
 ---
-title: "nb config"
-description: "nb config command reference: manage default configuration items for the NocoBase CLI."
-keywords: "nb config,NocoBase CLI,configuration,default configuration"
+title: 'nb config'
+description: 'nb config command reference: manage default configuration items for the NocoBase CLI.'
+keywords: 'nb config,NocoBase CLI,configuration,default configuration'
 ---
 
 # nb config
@@ -10,7 +10,8 @@ Manage default CLI configuration values. The currently supported keys are mainly
 
 - CLI itself: `locale`, `update.policy`, `license.pkg-url`
 - Docker runtime: `docker.network`, `docker.container-prefix`
-- External executables: `bin.docker`, `bin.caddy`, `bin.git`, `bin.nginx`, `bin.yarn`
+- Official NocoBase images: `nb-image-registry`, `nb-image-variant`
+- External executables: `bin.docker`, `bin.caddy`, `bin.git`, `bin.nginx`, `bin.pnpm`, `bin.yarn`
 - Proxy generation: `proxy.nb-cli-root`, `proxy.upstream-host`, `proxy.nginx-driver`, `proxy.caddy-driver`
 
 Most projects only need a few of these keys. In practice, the most common ones are:
@@ -18,27 +19,32 @@ Most projects only need a few of these keys. In practice, the most common ones a
 - `update.policy`
 - `docker.network`
 - `docker.container-prefix`
+- `nb-image-registry`
+- `nb-image-variant`
 - `bin.nginx` or `bin.caddy`
 - `proxy.nginx-driver` or `proxy.caddy-driver`
 
 ## Common configuration keys
 
-| Key | Default | Description |
-| --- | --- | --- |
-| `locale` | resolved by the current CLI rules | Override the language used by the CLI |
-| `update.policy` | `prompt` | Startup update policy: `prompt`, `auto`, or `off` |
-| `license.pkg-url` | `https://pkg.nocobase.com/` | Override the download URL for commercial extension packages |
-| `docker.network` | `nocobase` | Default network for CLI-managed Docker apps |
-| `docker.container-prefix` | `nb` | Default prefix for CLI-managed Docker containers |
-| `bin.docker` | `docker` | Override the Docker executable path |
-| `bin.caddy` | `caddy` | Override the Caddy executable path |
-| `bin.git` | `git` | Override the Git executable path |
-| `bin.nginx` | `nginx` | Override the Nginx executable path |
-| `bin.yarn` | `yarn` | Override the Yarn executable path |
-| `proxy.nb-cli-root` | CLI root, usually the current user's home directory | Override the root path visible to the generated proxy config when the proxy process and CLI do not see the same filesystem root |
-| `proxy.upstream-host` | `127.0.0.1` | Override the host used when the proxy forwards traffic back to the NocoBase app |
-| `proxy.nginx-driver` | `local` | Default runtime driver used by `nb proxy nginx` |
-| `proxy.caddy-driver` | `local` | Default runtime driver used by `nb proxy caddy` |
+| Key                       | Default                                             | Description                                                                                                                     |
+| ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `locale`                  | resolved by the current CLI rules                   | Override the language used by the CLI                                                                                           |
+| `update.policy`           | `prompt`                                            | Startup update policy: `prompt`, `auto`, or `off`                                                                               |
+| `license.pkg-url`         | `https://pkg.nocobase.com/`                         | Override the download URL for commercial extension packages                                                                     |
+| `docker.network`          | `nocobase`                                          | Default network for CLI-managed Docker apps                                                                                     |
+| `docker.container-prefix` | `nb`                                                | Default prefix for CLI-managed Docker containers                                                                                |
+| `nb-image-registry`       | `dockerhub`                                         | Default registry family for official NocoBase images: `dockerhub` or `aliyun`                                                   |
+| `nb-image-variant`        | `full`                                              | Default tag variant for official NocoBase app images: `standard`, `no-nginx`, `full`, or `full-no-nginx`                        |
+| `bin.docker`              | `docker`                                            | Override the Docker executable path                                                                                             |
+| `bin.caddy`               | `caddy`                                             | Override the Caddy executable path                                                                                              |
+| `bin.git`                 | `git`                                               | Override the Git executable path                                                                                                |
+| `bin.nginx`               | `nginx`                                             | Override the Nginx executable path                                                                                              |
+| `bin.pnpm`                | `pnpm`                                              | Override the pnpm executable path                                                                                               |
+| `bin.yarn`                | `yarn`                                              | Override the Yarn executable path                                                                                               |
+| `proxy.nb-cli-root`       | CLI root, usually the current user's home directory | Override the root path visible to the generated proxy config when the proxy process and CLI do not see the same filesystem root |
+| `proxy.upstream-host`     | `127.0.0.1`                                         | Override the host used when the proxy forwards traffic back to the NocoBase app                                                 |
+| `proxy.nginx-driver`      | `local`                                             | Default runtime driver used by `nb proxy nginx`                                                                                 |
+| `proxy.caddy-driver`      | `local`                                             | Default runtime driver used by `nb proxy caddy`                                                                                 |
 
 ## Usage
 
@@ -48,12 +54,12 @@ nb config <command>
 
 ## Subcommands
 
-| Command | Description |
-| --- | --- |
-| [`nb config get`](./get.md) | Read the effective value of a configuration key |
-| [`nb config set`](./set.md) | Set a configuration key |
-| [`nb config delete`](./delete.md) | Delete an explicitly set configuration key |
-| [`nb config list`](./list.md) | List the configuration keys that are currently set explicitly |
+| Command                           | Description                                                   |
+| --------------------------------- | ------------------------------------------------------------- |
+| [`nb config get`](./get.md)       | Read the effective value of a configuration key               |
+| [`nb config set`](./set.md)       | Set a configuration key                                       |
+| [`nb config delete`](./delete.md) | Delete an explicitly set configuration key                    |
+| [`nb config list`](./list.md)     | List the configuration keys that are currently set explicitly |
 
 ## Examples
 
@@ -68,14 +74,22 @@ nb config set proxy.nginx-driver docker
 nb config set proxy.caddy-driver local
 nb config get docker.network
 nb config set docker.network nocobase
+nb config get nb-image-registry
+nb config set nb-image-registry aliyun
+nb config set nb-image-variant full-no-nginx
 nb config set bin.nginx /usr/sbin/nginx
 nb config set bin.git /usr/bin/git
+nb config set bin.pnpm /usr/local/bin/pnpm
 nb config delete docker.container-prefix
 ```
 
 ## Notes
 
 - `bin.nginx` and `bin.caddy` only affect the `local` driver for `nb proxy nginx` and `nb proxy caddy`
+- `bin.pnpm` is used when commands need to run pnpm directly, such as updating a pnpm-managed global CLI install with `nb self update`
+- `nb-image-registry` only affects official NocoBase image defaults used by the CLI. `dockerhub` maps app images to `nocobase/nocobase`, while `aliyun` maps them to `registry.cn-shanghai.aliyuncs.com/nocobase/nocobase`
+- `nb-image-variant` only affects official NocoBase app image tags. With version tag `1.7.14`, the CLI resolves `standard` to `1.7.14`, `no-nginx` to `1.7.14-no-nginx`, `full` to `1.7.14-full`, and `full-no-nginx` to `1.7.14-full-no-nginx`
+- When `nb-image-registry=aliyun`, the CLI also switches the default built-in database images to the official Aliyun mirrors for PostgreSQL, MySQL, MariaDB, and Kingbase
 - `proxy.nginx-driver` and `proxy.caddy-driver` store the default driver used by each provider
 - `proxy.nb-cli-root` and `proxy.upstream-host` are advanced proxy overrides. Most CLI-managed `local` or `docker` envs can use the defaults directly
 - If you only want to switch the active proxy driver, using `nb proxy nginx use` or `nb proxy caddy use` is usually clearer than setting the config key manually

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

@@ -1,7 +1,7 @@
 ---
-title: "nb config set"
-description: "nb config set command reference: set a CLI configuration item."
-keywords: "nb config set,NocoBase CLI,set configuration"
+title: 'nb config set'
+description: 'nb config set command reference: set a CLI configuration item.'
+keywords: 'nb config set,NocoBase CLI,set configuration'
 ---
 
 # nb config set
@@ -16,10 +16,10 @@ nb config set <key> <value>
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
-| `<value>` | string | Configuration value, cannot be empty |
+| Parameter | Type   | Description                                                                 |
+| --------- | ------ | --------------------------------------------------------------------------- |
+| `<key>`   | string | Configuration item name. See [`nb config`](./index.md) for supported values |
+| `<value>` | string | Configuration value, cannot be empty                                        |
 
 ## Examples
 
@@ -29,10 +29,15 @@ nb config set update.policy auto
 nb config set license.pkg-url https://pkg.nocobase.com/
 nb config set docker.network nocobase
 nb config set docker.container-prefix nb
+nb config set nb-image-registry dockerhub
+nb config set nb-image-registry aliyun
+nb config set nb-image-variant full
+nb config set nb-image-variant full-no-nginx
 nb config set bin.docker /usr/local/bin/docker
 nb config set bin.caddy /opt/homebrew/bin/caddy
 nb config set bin.git /usr/bin/git
 nb config set bin.nginx /usr/sbin/nginx
+nb config set bin.pnpm /usr/local/bin/pnpm
 nb config set proxy.nb-cli-root /workspace
 nb config set proxy.upstream-host host.docker.internal
 nb config set proxy.nginx-driver docker
@@ -42,7 +47,9 @@ nb config set bin.yarn yarn
 
 ## Notes
 
-`update.policy` supports `prompt`, `auto`, and `off`, and the default value is `prompt`.
+- `update.policy` supports `prompt`, `auto`, and `off`, and the default value is `prompt`
+- `nb-image-registry` supports `dockerhub` and `aliyun`, and the default value is `dockerhub`
+- `nb-image-variant` supports `standard`, `no-nginx`, `full`, and `full-no-nginx`, and the default value is `full`
 
 ## Related commands
 

package/dist/ai/docs/nocobase/api/cli/env/auth.md

@@ -1,17 +1,19 @@
 ---
 title: "nb env auth"
-description: "nb env auth command reference: run OAuth login for a saved NocoBase env."
-keywords: "nb env auth,NocoBase CLI,OAuth,login,authentication"
+description: "nb env auth command reference: authenticate a saved NocoBase env with basic, token, or OAuth authentication."
+keywords: "nb env auth,NocoBase CLI,basic,token,OAuth,login,authentication"
 ---
 
 # nb env auth
 
-Run OAuth login for a selected env. When the env name is omitted, the current env is used.
+Authenticate a saved NocoBase env again, or update the authentication information saved for it. When the env name is omitted, the current env is used.
+
+`nb env auth` supports three authentication methods: `basic`, `token`, and `oauth`. If `--auth-type` is omitted, the CLI first infers the method from the authentication options you pass. If it still cannot infer the method, it uses the authentication method already saved in the env.
 
 ## Usage
 
 ```bash
-nb env auth [name]
+nb env auth [name] [flags]
 ```
 
 ## Parameters
@@ -19,19 +21,65 @@ nb env auth [name]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `[name]` | string | Configured environment name to sign in to; uses the current env if omitted |
+| `--auth-type`, `-a` | string | Authentication method: `basic`, `token`, or `oauth` |
+| `--access-token`, `-t` | string | API key or access token used with `token` authentication |
+| `--username` | string | Username used with `basic` authentication; prompted in TTY when omitted |
+| `--password` | string | Password used with `basic` authentication; prompted in TTY when omitted |
+
+## Compatibility options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `--env`, `-e` | string | Environment name, equivalent to `[name]`. This hidden option is kept for compatibility with other commands; normally the positional argument is enough |
 
 ## Notes
 
-Internally, this command uses the PKCE flow: start a local callback server, open the browser for authorization, exchange the token, and save it to the config file.
+The authentication methods work as follows:
+
+- `basic`: sign in to NocoBase with a username and password, then save the returned access token and username
+- `token`: save the API key or access token passed through `--access-token`
+- `oauth`: start the browser authentication flow, then save the access token after authentication finishes
+
+In an interactive terminal, the CLI prompts for `--auth-type`, `--username`, `--password`, or `--access-token` when needed. In non-interactive mode, `basic` authentication requires both `--username` and `--password`.
+
+`oauth` authentication first tries Device Authorization Grant. When the OAuth server supports this flow, the command prints a verification URL and user code, then polls until the browser approval is complete. This works on remote or headless servers because it does not require a local callback listener.
+
+If the OAuth server does not expose a device authorization endpoint, the command falls back to the PKCE loopback flow: start a local callback server, open the browser for authorization, exchange the token, and save it to the config file.
+
+After authentication succeeds, the CLI automatically runs `nb env update <name>` to re-sync the env state.
+
+## Limits
+
+- `[name]` and `--env` cannot provide different environment names at the same time
+- `--access-token` cannot be used with `--username` or `--password`
+- `--auth-type oauth` cannot be used with `--access-token`, `--username`, or `--password`
+- `--auth-type token` cannot be used with `--username` or `--password`
+- `--auth-type basic` cannot be used with `--access-token`
+- `--access-token`, `--username`, and `--password` cannot be empty after they are provided
 
 ## Examples
 
 ```bash
+# Authenticate the current env with the saved authentication method
 nb env auth
+
+# Authenticate a specific env
 nb env auth prod
+
+# Use OAuth browser login
+nb env auth prod --auth-type oauth
+
+# Sign in with username and password
+nb env auth prod --auth-type basic --username admin --password secret
+
+# Save an API key or access token
+nb env auth prod --auth-type token --access-token <api-key>
 ```
 
+For device authorization, follow the URL printed by the command and enter the displayed code in the browser.
+
 ## Related Commands
 
 - [`nb env add`](./add.md)
+- [`nb env info`](./info.md)
 - [`nb env update`](./update.md)

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

@@ -42,7 +42,7 @@ nb init --env app1 --resume
 
 `--prepare-only` is intended for flows where the env should be prepared first, then the license is activated, and only after that the app is installed and started.
 
-If you want to save the env config, prepare the source files or image, and get the database ready first, but delay the actual app installation and first startup, you can use:
+If you want to save the env config and prepare the database first, while delaying dependency download, app installation, and first startup, you can use:
 
 ```bash
 nb init --env app1 --prepare-only
@@ -67,6 +67,7 @@ By default, the CLI organizes local files under `app-path` using the following c
 
 ```text
 <app-path>/
+├── .nb/      # CLI metadata for this env, such as hooks.mjs
 ├── source/   # Default directory for app source code or downloaded content
 ├── storage/  # Runtime data directory
 └── .env      # Optional app environment variable file
@@ -74,7 +75,8 @@ By default, the CLI organizes local files under `app-path` using the following c
 
 Typically:
 
-- `source/` mainly corresponds to the local app directory for npm / Git envs. For Docker envs, the CLI also keeps this default path derivation, but most of the time you do not need to care about it manually
+- `.nb/` stores CLI-managed metadata. A script passed with `--hook-script` is copied to `<app-path>/.nb/hooks.mjs`, so later `nb app upgrade` and local source restore can reuse it
+- `source/` mainly corresponds to the local app directory for npm / Git envs. For Docker envs, the CLI also keeps this default path derivation, but most of the time you do not need to care about it manually. Pay special attention during upgrades: the `source/` directory will be deleted and downloaded again, so do not put files you need to keep here
 - `storage/` is used for runtime data, such as built-in database data, plugins, logs, and more
 - `.env` is an optional app environment variable file. You only need to add it in `<app-path>/.env` when you want to customize environment variables; if this file exists, Docker, npm, and Git install sources will all read it by default
 
@@ -101,7 +103,7 @@ If you are following the local UI wizard step by step, you can first use the tab
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Getting started`         | `--env`、`--yes`、`--ui`、`--locale`、`--verbose`、`--skip-skills`、`--resume`                                                                                                                                    |
 | `App environment`         | `--lang`、`--app-path`、`--app-port`、`--force`                                                                                                                                                                   |
-| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts` |
+| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts`、`--hook-script` |
 | `Configure the database`  | `--builtin-db`、`--db-dialect`、`--builtin-db-image`、`--db-host`、`--db-port`、`--db-database`、`--db-user`、`--db-password`、`--db-schema`、`--db-table-prefix`、`--db-underscored`                             |
 | `Create an admin account` | `--root-username`、`--root-email`、`--root-password`、`--root-nickname`                                                                                                                                           |
 | `Remote connection`       | `--api-base-url`、`--auth-type`、`--access-token`、`--username`、`--password`、`--skip-auth`                                                                                                                      |
@@ -121,7 +123,7 @@ The “Default” below means the value or behavior that `nb init` usually uses
 | `--ui`          | boolean | `false`                                                                      | Open the local browser wizard; cannot be used with `--yes` or `--resume`               |
 | `--verbose`     | boolean | `false`                                                                      | Show detailed command output                                                           |
 | `--skip-skills` | boolean | `false`                                                                      | Skip syncing NocoBase AI coding skills                                                 |
-| `--ui-host`     | string  | `127.0.0.1`                                                                  | Bind address for the `--ui` local service                                              |
+| `--ui-host`     | string  | `127.0.0.1`                                                                  | Browser-accessible host shown in the `--ui` wizard URL; the local service always listens on `0.0.0.0` |
 | `--ui-port`     | integer | `0`                                                                          | Port for the `--ui` local service; `0` means automatic assignment                      |
 | `--locale`      | string  | Follows `NB_LOCALE`, CLI config, or system locale; final fallback is `en-US` | Language for CLI prompts and the local setup UI: `en-US` or `zh-CN`                    |
 | `--resume`      | boolean | `false`                                                                      | Continue the last unfinished initialization and reuse the saved workspace env config   |
@@ -184,6 +186,7 @@ The “Default” below means the value or behavior that `nb init` usually uses
 | `--npm-registry`                                     | string  | Empty                                                                                            | Registry used for npm/Git download and dependency installation                           |
 | `--build` / `--no-build`                             | boolean | `true`                                                                                           | Whether to build after installing npm/Git dependencies                                   |
 | `--build-dts`                                        | boolean | `false`                                                                                          | Whether to generate TypeScript declaration files during npm/Git builds                   |
+| `--hook-script`                                      | string  | None                                                                                             | Copy the specified hook module to `<app-path>/.nb/hooks.mjs` and save it in the env config; supports the `beforeDependencyInstall`, `beforeAppInstall`, and `afterAppStart` lifecycle hooks |
 
 ## Examples
 
@@ -233,6 +236,40 @@ nb init --env app1 --yes --source git --version latest \
   --git-url https://gitee.com/nocobase/nocobase.git
 ```
 
+### Extend the install flow with a hook script
+
+If you need to prepare extra content during installation, pass a local ESM module with `--hook-script`:
+
+```bash
+nb init --env app1 --yes --source git --hook-script ./hooks.mjs
+```
+
+The CLI copies this file to `<app-path>/.nb/hooks.mjs` and saves `hookScript: ".nb/hooks.mjs"` in the env config. Later `nb app start`, `nb app restart`, and `nb app upgrade` reuse it from that location.
+
+The hook file must default-export an object. Implement only the methods you need:
+
+```js
+export default {
+  beforeDependencyInstall: async (context) => {
+    // Runs after git clone / npm scaffold and before yarn install.
+  },
+  beforeAppInstall: async (context) => {
+    // Runs before the app-level install or upgrade command.
+  },
+  afterAppStart: async (context) => {
+    // Runs after the app actually starts and passes the health check.
+  },
+};
+```
+
+- `beforeDependencyInstall` only applies to npm/Git source and runs right before the real `yarn install`; Docker source does not run it
+- `beforeAppInstall` runs before app-level install or upgrade commands, and applies to npm/Git/Docker source
+- `afterAppStart` runs after the app actually starts and passes `__health_check`; `nb app start`, `nb app restart`, and `nb app upgrade` may all trigger it
+
+`--prepare-only` only saves the env config and copies the hook file. It does not execute hooks. When you later run `nb app start` for the first time, the CLI runs the first-install hooks with `context.phase` set to `init` and `context.command` set to `app:start`.
+
+`context` includes lifecycle information such as `phase`, `command`, `source`, `version`, `appPath`, `sourcePath`, `storagePath`, `hookScript`, and `envConfig`. If a hook throws, the current CLI command fails. Because `afterAppStart` can run repeatedly during start, restart, and upgrade flows, keep it idempotent.
+
 ### Quick install and use basic authentication
 
 If you want to quickly install a local app in non-interactive mode and directly save `basic` authentication after installation, you can also write it like this. This way, you do not need to open a browser to complete OAuth.

package/dist/ai/docs/nocobase/api/cli/plugin/import.md

@@ -71,4 +71,4 @@ You do not need to extract anything into `storage/plugins` by hand. `nb plugin i
 
 - [`nb app restart`](../app/restart.md)
 - [`nb plugin enable`](./enable.md)
-- [`Install and upgrade third-party plugins`](../../../quickstart/plugins/third-party.md)
+- [`Install and upgrade third-party plugins`](../../../nocobase-cli/plugins/third-party.md)

package/dist/ai/docs/nocobase/api/cli/self/check.md

@@ -6,7 +6,7 @@ keywords: "nb self check,NocoBase CLI,version check"
 
 # nb self check
 
-Check the current NocoBase CLI installation, resolve the latest version for the selected channel, and report whether automatic self-update is supported.
+Check the current NocoBase CLI installation, resolve the latest version for the selected channel, and report whether self-update is supported.
 
 ## Usage
 
@@ -18,9 +18,26 @@ nb self check [flags]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `--channel` | string | Release channel to compare with, default `auto`; options: `auto`, `latest`, `beta`, `alpha` |
+| `--channel` | string | Release channel to compare with, default `auto`; options: `auto`, `latest`, `test`, `beta`, `alpha` |
 | `--json` | boolean | Output JSON |
 
+## Install Method
+
+`nb self check` detects the current install method at runtime. It does not use the historical `self-install-methods.json` cache.
+
+The command can report these install methods:
+
+| Install method | Meaning |
+| --- | --- |
+| `npm-global` | The CLI is installed under the current `npm prefix -g`. |
+| `pnpm-global` | The CLI is installed under a pnpm global `node_modules` tree. |
+| `yarn-global` | The CLI is launched from `yarn global bin` or installed under `yarn global dir`. |
+| `package-local` | The CLI is installed in a local project dependency tree. |
+| `source` | The CLI is running from a repository checkout. |
+| `unknown` | The CLI install could not be matched to a supported install method. |
+
+Self-update is supported for `npm-global`, `pnpm-global`, and `yarn-global`. For `package-local` or `source`, update the parent project or repository checkout instead.
+
 ## Examples
 
 ```bash

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

@@ -19,7 +19,7 @@ nb self <command>
 | Command | Description |
 | --- | --- |
 | [`nb self check`](./check.md) | Check current CLI version and self-update support |
-| [`nb self update`](./update.md) | Update the globally npm-installed NocoBase CLI |
+| [`nb self update`](./update.md) | Update the globally npm-, pnpm-, or yarn-installed NocoBase CLI |
 
 ## Examples
 

package/dist/ai/docs/nocobase/api/cli/self/update.md

@@ -1,12 +1,12 @@
 ---
 title: "nb self update"
-description: "nb self update command reference: update the globally npm-installed NocoBase CLI."
+description: "nb self update command reference: update the globally npm-, pnpm-, or yarn-installed NocoBase CLI."
 keywords: "nb self update,NocoBase CLI,update,self update"
 ---
 
 # nb self update
 
-Update the installed NocoBase CLI when the current CLI is managed by a standard global npm installation.
+Update the installed NocoBase CLI when the current CLI is managed by a standard global npm, pnpm, or yarn installation.
 
 ## Usage
 
@@ -18,12 +18,26 @@ nb self update [flags]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `--channel` | string | Release channel to update to, default `auto`; options: `auto`, `latest`, `beta`, `alpha` |
+| `--channel` | string | Release channel to update to, default `auto`; options: `auto`, `latest`, `test`, `beta`, `alpha` |
 | `--yes`, `-y` | boolean | Skip update confirmation |
 | `--json` | boolean | Output JSON |
 | `--skills` | boolean | Also refresh the globally installed NocoBase AI coding skills |
 | `--verbose` | boolean | Show detailed update output |
 
+## Update Behavior
+
+`nb self update` first detects the current install method at runtime. It does not use the historical `self-install-methods.json` cache.
+
+When an update is available, the command uses the same package manager that manages the current global CLI install:
+
+| Install method | Update command |
+| --- | --- |
+| `npm-global` | `npm install -g @nocobase/cli@<channel>` |
+| `pnpm-global` | `pnpm add -g @nocobase/cli@<channel>` |
+| `yarn-global` | `yarn global add @nocobase/cli@<channel>` |
+
+Interactive confirmation defaults to yes. Use `--yes` to skip the prompt in scripts.
+
 ## Examples
 
 ```bash

package/dist/ai/docs/nocobase/api/cli/skills/install.md

@@ -27,6 +27,7 @@ nb skills install [flags]
 ```bash
 nb skills install
 nb skills install --yes
+nb skills install --verbose
 nb skills install --json
 ```
 

package/dist/ai/docs/nocobase/api/cli/skills/update.md

@@ -27,6 +27,7 @@ nb skills update [flags]
 ```bash
 nb skills update
 nb skills update --yes
+nb skills update --verbose
 nb skills update --json
 ```
 

package/dist/ai/docs/nocobase/api/cli/source/download.md

@@ -33,6 +33,7 @@ nb source download [flags]
 | `--npm-registry` | string | Registry used for npm/Git downloads and dependency installation |
 | `--build` / `--no-build` | boolean | Whether to build after npm/Git dependency installation |
 | `--build-dts` | boolean | Whether to generate TypeScript declaration files during npm/Git build |
+| `--hook-script` | string | Hook module to run after npm scaffold or Git clone and before dependency installation; only applies to npm/Git source |
 
 ## Examples
 
@@ -47,8 +48,26 @@ nb source download --source git --version alpha --git-url=git@github.com:nocobas
 nb source download --source git --version fix/cli-v2
 nb source download -y --source npm --version alpha --build-dts
 nb source download -y --source npm --version alpha --npm-registry=https://registry.npmmirror.com
+nb source download -y --source git --version beta --hook-script ./hooks.mjs
 ```
 
+## Pre-install hook
+
+`--hook-script` only affects the current `nb source download` run. If you want the hook to be saved with the env and reused by `nb app upgrade` or local source restore, pass it through [`nb init --hook-script`](../init.md) instead.
+
+The hook file must default-export an object with `beforeDependencyInstall(context)`:
+
+```js
+export default {
+  beforeDependencyInstall: async ({ sourcePath, version, envConfig }) => {
+    // Runs after git clone / npm scaffold and before yarn install.
+  },
+};
+```
+
+When you run `nb source download --hook-script` directly, `beforeDependencyInstall` receives `context.phase` as `source-download` and `context.command` as `source:download`. This command does not run `beforeAppInstall` or `afterAppStart`; those hooks belong to app install, start, restart, and upgrade flows.
+
+
 ## Version Aliases
 
 With Git source, common dist-tags are resolved to branches: `latest` -> `main`, `beta` -> `next`, `alpha` -> `develop`.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/validation.md

@@ -78,6 +78,9 @@ After configuring field rules, the corresponding validation rules will be trigge
 
 ![20250819201027](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819201027.png)
 
+When the field is used in a form, field validation rules are also displayed in the field validation settings. These rules appear under **Server-side field validation rules** and are read-only there. If you need to change them, edit the field in Data source → Collection configuration.
+
+You can still add extra rules for the current form field under **Client-side validation rules**. These rules only apply to the current field component. The final validation result combines **Server-side field validation rules** and **Client-side validation rules**.
 
 Validation rules also apply to sub-table and sub-form components:
 
@@ -93,12 +96,12 @@ Note that in sub-form or sub-table scenarios, required validation for associatio
 ![20250819203016](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203016.png)
 
 
-## Differences from Client-Side Field Validation
-Client-side and server-side field validation are applied in different scenarios, with significant differences in implementation and rule trigger timing, so they need to be managed separately.
+## Differences Between Server-Side Field Validation Rules and Client-Side Validation Rules
+Server-side field validation rules and client-side validation rules are configured in different places and have different scopes.
 
 ### Configuration Method Differences
-- **Client-side validation**: Configure rules in edit forms (as shown in the figure below)
-- **Server-side field validation**: Set field rules in Data Source → Collection Configuration
+- **Server-side field validation rules**: Set field rules in Data source → Collection configuration. These rules are the base rules of the field.
+- **Client-side validation rules**: Configure extra rules in a form field's settings. These rules only affect the current field component.
 
 ![20250819203836](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203836.png)
 
@@ -109,7 +112,7 @@ Client-side and server-side field validation are applied in different scenarios,
 
 
 ### Validation Trigger Timing Differences
-- **Client-side validation**: Triggers validation in real-time as users fill in fields, displaying error messages immediately.
-- **Server-side field validation**: Validates on the server side before data entry after data submission, with error messages returned through API responses.
-- **Application scope**: Server-side field validation takes effect not only during form submission but also triggers in all scenarios involving data addition or modification, such as workflows and data imports.
-- **Error messages**: Client-side validation supports custom error messages, while server-side validation does not currently support custom error messages.
+- **Server-side field validation rules**: Trigger frontend validation when the field is used in a form, and also validate before data is written. They also apply to scenarios that create or update data, such as workflows and data imports.
+- **Client-side validation rules**: Trigger frontend validation in the current form field only.
+- **Rule display**: Server-side field validation rules are shown as inherited read-only rules. Client-side validation rules are shown separately and can be edited there.
+- **Error messages**: Client-side validation rules support custom error messages, while server-side field validation rules do not currently support custom error messages.

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

@@ -2,8 +2,8 @@
 pageType: home
 pageName: development
 title: "NocoBase Development Guide"
-description: "NocoBase development guide: plugin development, FlowEngine, RunJS, block/field/action extensions, data source extensions, workflow extensions, authentication extensions."
-keywords: "NocoBase,development guide,plugin development,FlowEngine,RunJS,NocoBase extensions"
+description: "NocoBase development guide: plugin development, shared components, FlowEngine, RunJS, block/field/action extensions, data source extensions, workflow extensions, authentication extensions."
+keywords: "NocoBase,development guide,plugin development,shared components,FlowEngine,RunJS,NocoBase extensions"
 features:
   - title: Core Development
     details: Master NocoBase's underlying extension mechanism and advanced development capabilities, including the plugin system, AI assistance, FlowEngine and RunJS environment, to build a solid development foundation.
@@ -24,6 +24,10 @@ features:
         details: JavaScript execution environment for JS blocks, JS fields, and JS actions, and similar scenarios.
         link: /runjs
         showOnHome: true
+      - title: Shared Components
+        details: Reuse the built-in form, filter, table, and icon components in NocoBase client v2 when building plugin pages.
+        link: /shared-components
+        showOnHome: true
   - title: Plugin Ecosystem
     details: Extend the capabilities of existing plugins through other plugins, building a hierarchical and modular plugin ecosystem to enhance system extensibility and collaboration.
     items:
@@ -46,4 +50,7 @@ features:
       - title: File Preview Extension
         details: Extend file preview capabilities to support online preview and rendering of more file formats.
         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
 ---

package/dist/ai/docs/nocobase/file-manager/field-attachment.md

@@ -1,5 +1,11 @@
 # Attachment
 
+:::warning Note
+
+The Attachment field will be deprecated in a future version. For new apps or when adjusting existing business flows, migrate to a custom file collection as early as possible and manage related files with association fields.
+
+:::
+
 ## Introduction
 
 The system has a built-in "Attachment" field type to support file uploads in custom collections.

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

@@ -12,17 +12,8 @@ Currently, NocoBase provides the following file preview plugins:
 
 ## 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.
+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.
 
-If CORS is not configured, PDF downloads can still work normally, but preview may fail with a file loading error.
+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.
 
-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.
+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.