@nocobase/plugin-ai 2.1.0-beta.29 → 2.1.0-beta.32

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

@@ -0,0 +1,52 @@
+---
+title: "nb env status"
+description: "nb env status command reference: show status for the current env, one env, or all envs."
+keywords: "nb env status,NocoBase CLI,environment status,API Base URL"
+---
+
+# nb env status
+
+Show env status. By default it inspects the current env. You can also inspect one named env, or use `--all` to inspect all envs.
+
+This command prints a simplified status table with `Env`, `Status`, and `API Base URL`.
+
+## Usage
+
+```bash
+nb env status [name] [flags]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `[name]` | string | Configured environment name to inspect; uses the current env if omitted; cannot be used with `--all` |
+| `--all` | boolean | Show status for all configured envs |
+| `--json-output` | boolean | Output the result as JSON |
+
+`[name]` and `--all` cannot be used together.
+
+## Status values
+
+`Status` is the result returned after the CLI checks the target env. Typical values include:
+
+- `ok`: the env is reachable and authenticated
+- `auth failed`: the API is reachable but authentication failed
+- `unreachable`: the target address could not be reached
+- `unconfigured`: the env configuration is incomplete
+- `missing`: the managed app for this env no longer exists
+
+## Examples
+
+```bash
+nb env status
+nb env status app1
+nb env status --all
+nb env status --all --json-output
+```
+
+## Related Commands
+
+- [`nb env current`](./current.md)
+- [`nb env list`](./list.md)
+- [`nb env info`](./info.md)

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

@@ -18,7 +18,7 @@ nb env update [name] [flags]
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `[name]` | string | Env name; uses the current env if omitted |
+| `[name]` | string | Configured environment name to refresh; uses the current env if omitted |
 | `--verbose` | boolean | Show detailed progress |
 | `--api-base-url` | string | Override the NocoBase API URL and persist it to the target env |
 | `--role` | string | Role override sent as the `X-Role` request header |

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

@@ -8,6 +8,10 @@ keywords: "nb env use,NocoBase CLI,switch environment,current env"
 
 Switch the current CLI env. Commands that omit `--env` will use this env by default afterward.
 
+When session mode is enabled for the current shell or runtime, this change only affects the current session.
+
+When session mode is not enabled, this falls back to updating the global `last env`. In that case, other terminals or agent runtimes without session isolation may also be affected.
+
 ## Usage
 
 ```bash
@@ -18,7 +22,7 @@ nb env use <name>
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `<name>` | string | Configured env name |
+| `<name>` | string | Configured environment name to switch to |
 
 ## Examples
 
@@ -26,7 +30,13 @@ nb env use <name>
 nb env use local
 ```
 
+## Recommendation
+
+The default recommendation is to run [`nb session setup`](../session/setup.md) once first. That makes `nb env use` behave more like `use dbname` in a database client: switch the current session context first, then run follow-up commands that depend on that env.
+
 ## Related Commands
 
+- [`nb env current`](./current.md)
+- [`nb env status`](./status.md)
 - [`nb env list`](./list.md)
 - [`nb env info`](./info.md)

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

@@ -35,11 +35,12 @@ The root command mainly displays help and dispatches execution to command groups
 | [`nb app`](./app/index.md) | Manage NocoBase app runtimes: start, stop, restart, logs, and upgrades. |
 | [`nb config`](./config/index.md) | Manage CLI configuration defaults. |
 | [`nb db`](./db/index.md) | Manage the built-in database for the selected env. |
-| [`nb env`](./env/index.md) | Manage NocoBase project environments, status, details, and command runtimes. |
+| [`nb env`](./env/index.md) | Manage NocoBase project environments, current env, status, details, and command runtimes. |
 | [`nb license`](./license/index.md) | Manage commercial licensing and licensed plugins. |
 | [`nb plugin`](./plugin/index.md) | Manage plugins in the selected NocoBase env. |
 | [`nb scaffold`](./scaffold/index.md) | Generate NocoBase plugin development scaffolds. |
 | [`nb self`](./self/index.md) | Inspect or update the NocoBase CLI itself. |
+| [`nb session`](./session/index.md) | Configure `NB_SESSION_ID` so current env is isolated per shell or agent runtime. |
 | [`nb skills`](./skills/index.md) | Inspect or synchronize NocoBase AI coding skills for the current workspace. |
 | [`nb source`](./source/index.md) | Work with the local NocoBase source project: download, develop, build, and test. |
 
@@ -93,6 +94,8 @@ Connect an existing app:
 
 ```bash
 nb env add app1 --api-base-url http://localhost:13000/api
+nb env current
+nb env status
 ```
 
 Start the app and refresh runtime commands:
@@ -130,6 +133,7 @@ The following environment variables affect CLI behavior:
 | --- | --- |
 | `NB_CLI_ROOT` | Root directory where the CLI stores `.nocobase` config and local app files. Defaults to the current user's home directory. |
 | `NB_LOCALE` | Language for CLI prompts and the local setup UI. Supported values are `en-US` and `zh-CN`. |
+| `NB_SESSION_ID` | Session ID for the current shell or agent runtime. When set, `nb env use` and `nb env current` are isolated per session. |
 
 Example:
 
@@ -154,6 +158,14 @@ After setting `NB_CLI_ROOT=/your/workspace`, the config file path becomes:
 
 The CLI also keeps compatibility with legacy project config under the current working directory.
 
+Current env session cache is stored in:
+
+```text
+.nocobase/sessions/<NB_SESSION_ID>.json
+```
+
+The globally last-used env is stored in the `lastEnv` field in `config.json`. When `NB_SESSION_ID` is not set, the CLI falls back to that global value.
+
 Runtime command cache is stored in:
 
 ```text

package/dist/ai/docs/nocobase/api/cli/license/activate.md

@@ -25,7 +25,7 @@ nb license activate [flags]
 | `--account` | string | License service account for online activation |
 | `--password` | string | License service password for online activation |
 | `--desc` | string | Application name submitted for online activation |
-| `--yes` | boolean | Confirm that the submitted information is true and accurate |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--json` | boolean | Output JSON |
 
 ## Examples
@@ -34,6 +34,7 @@ nb license activate [flags]
 nb license activate --env app1 --key <licenseKey>
 nb license activate --env app1 --key-file ./license.txt
 nb license activate --env app1 --online
+nb license activate --env app1 --online --account aa --password bb --desc test24
 nb license activate --env app1 --online --account aa --password bb --desc test24 --yes
 nb license activate --env app1 --json --key-file ./license.txt
 ```
@@ -42,6 +43,8 @@ nb license activate --env app1 --json --key-file ./license.txt
 
 When online activation is used, the CLI requests a license key from the license service with the current env's instance ID and app URL.
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb license id`](./id.md)

package/dist/ai/docs/nocobase/api/cli/license/id.md

@@ -19,6 +19,7 @@ nb license id [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; when omitted, the current env is used |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--force` | boolean | Regenerate the instance ID even when one is already saved |
 | `--json` | boolean | Output JSON |
 
@@ -27,10 +28,13 @@ nb license id [flags]
 ```bash
 nb license id
 nb license id --env app1
+nb license id --env app1 --yes
 nb license id --env app1 --force
 nb license id --env app1 --json
 ```
 
+`--force` only forces regeneration of the instance ID. It does not replace cross-env confirmation; if an explicitly passed `--env` targets a non-current env, you still need confirmation or `--yes`.
+
 ## Related Commands
 
 - [`nb license activate`](./activate.md)

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

@@ -19,8 +19,9 @@ nb license plugins clean [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; when omitted, the current env is used |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--dry-run` | boolean | Preview which plugins would be removed without deleting anything |
-| `--verbose`, `-V` | boolean | Show detailed per-plugin clean logs |
+| `--verbose` | boolean | Show detailed per-plugin clean logs |
 | `--json` | boolean | Output JSON |
 
 ## Examples
@@ -28,11 +29,14 @@ nb license plugins clean [flags]
 ```bash
 nb license plugins clean
 nb license plugins clean --env app1
+nb license plugins clean --env app1 --yes
 nb license plugins clean --env app1 --dry-run
 nb license plugins clean --env app1 --verbose
 nb license plugins clean --env app1 --json
 ```
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb license plugins sync`](./sync.md)

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

@@ -19,6 +19,7 @@ nb license plugins list [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; when omitted, the current env is used |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--json` | boolean | Output JSON |
 
 ## Examples
@@ -26,9 +27,12 @@ nb license plugins list [flags]
 ```bash
 nb license plugins list
 nb license plugins list --env app1
+nb license plugins list --env app1 --yes
 nb license plugins list --env app1 --json
 ```
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb license plugins sync`](./sync.md)

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

@@ -19,9 +19,10 @@ nb license plugins sync [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; when omitted, the current env is used |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--dry-run` | boolean | Preview changes without installing, upgrading, or removing plugins |
 | `--version` | string | Registry version or dist-tag to synchronize; defaults to the current workspace version |
-| `--verbose`, `-V` | boolean | Show detailed per-plugin sync logs |
+| `--verbose` | boolean | Show detailed per-plugin sync logs |
 | `--json` | boolean | Output JSON |
 
 ## Examples
@@ -29,6 +30,7 @@ nb license plugins sync [flags]
 ```bash
 nb license plugins sync
 nb license plugins sync --env app1
+nb license plugins sync --env app1 --yes
 nb license plugins sync --env app1 --dry-run
 nb license plugins sync --env app1 --json
 ```
@@ -37,6 +39,8 @@ nb license plugins sync --env app1 --json
 
 When `--version` is omitted, the CLI detects the current app version automatically and uses that to decide which registry version of commercial plugins should be downloaded.
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb license plugins list`](./list.md)

package/dist/ai/docs/nocobase/api/cli/license/status.md

@@ -19,6 +19,7 @@ nb license status [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; when omitted, the current env is used |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--doctor` | boolean | Run extra diagnostic checks and suggestions |
 | `--json` | boolean | Output JSON |
 
@@ -27,6 +28,7 @@ nb license status [flags]
 ```bash
 nb license status
 nb license status --env app1
+nb license status --env app1 --yes
 nb license status --env app1 --doctor
 nb license status --env app1 --json
 ```
@@ -35,6 +37,8 @@ nb license status --env app1 --json
 
 The new CLI does not fully implement backend license status checks yet. The command can still return basic context and diagnostic placeholders, but not a complete license verdict.
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb license activate`](./activate.md)

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

@@ -20,6 +20,7 @@ nb plugin disable <packages...> [flags]
 | --- | --- | --- |
 | `<packages...>` | string[] | Plugin package names, required; supports multiple values |
 | `--env`, `-e` | string | CLI env name; uses the current env if omitted |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 
 ## Examples
 
@@ -27,8 +28,11 @@ nb plugin disable <packages...> [flags]
 nb plugin disable @nocobase/plugin-sample
 nb plugin disable @nocobase/plugin-a @nocobase/plugin-b
 nb plugin disable -e local @nocobase/plugin-sample
+nb plugin disable -e local --yes @nocobase/plugin-sample
 ```
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb plugin list`](./list.md)

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

@@ -20,6 +20,7 @@ nb plugin enable <packages...> [flags]
 | --- | --- | --- |
 | `<packages...>` | string[] | Plugin package names, required; supports multiple values |
 | `--env`, `-e` | string | CLI env name; uses the current env if omitted |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 
 ## Examples
 
@@ -27,8 +28,11 @@ nb plugin enable <packages...> [flags]
 nb plugin enable @nocobase/plugin-sample
 nb plugin enable @nocobase/plugin-a @nocobase/plugin-b
 nb plugin enable -e local @nocobase/plugin-sample
+nb plugin enable -e local --yes @nocobase/plugin-sample
 ```
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb plugin list`](./list.md)

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

@@ -19,15 +19,19 @@ nb plugin list [flags]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name; uses the current env if omitted |
+| `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 
 ## Examples
 
 ```bash
 nb plugin list
 nb plugin list -e local
+nb plugin list -e local --yes
 nb plugin list -e local-docker
 ```
 
+If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
+
 ## Related Commands
 
 - [`nb plugin enable`](./enable.md)

package/dist/ai/docs/nocobase/api/cli/session/id.md

@@ -0,0 +1,28 @@
+---
+title: "nb session id"
+description: "nb session id command reference: show the current effective NB_SESSION_ID."
+keywords: "nb session id,NocoBase CLI,NB_SESSION_ID,session id"
+---
+
+# nb session id
+
+Show the current effective session id.
+
+If no usable `NB_SESSION_ID` is available in the current shell or runtime, the command tells you to run [`nb session setup`](./setup.md) first, then open a new shell session or runtime.
+
+## Usage
+
+```bash
+nb session id
+```
+
+## Examples
+
+```bash
+nb session id
+```
+
+## Related Commands
+
+- [`nb session setup`](./setup.md)
+- [`nb env current`](../env/current.md)

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

@@ -0,0 +1,41 @@
+---
+title: "nb session"
+description: "nb session command reference: configure and inspect NB_SESSION_ID so current env is isolated per shell or agent runtime."
+keywords: "nb session,NocoBase CLI,NB_SESSION_ID,session mode"
+---
+
+# nb session
+
+Manage session mode for `NB_SESSION_ID`.
+
+After session mode is enabled, `nb env use` and `nb env current` use the current shell or agent runtime context first, instead of directly sharing a single global current env.
+
+## Usage
+
+```bash
+nb session <command>
+```
+
+## Subcommands
+
+| Command | Description |
+| --- | --- |
+| [`nb session setup`](./setup.md) | Install shell or runtime integration for `NB_SESSION_ID` |
+| [`nb session id`](./id.md) | Show the current effective session id |
+| [`nb session remove`](./remove.md) | Remove shell or runtime integration for `NB_SESSION_ID` |
+
+## When you need it
+
+The default recommendation is to run `nb session setup` once when you first start using the CLI. With it enabled:
+
+- terminal 1 can use `env1`
+- terminal 2 can use `env2` at the same time
+- an agent runtime can keep its own current env too
+
+Without session mode, different sessions fall back to sharing the global `last env`, which makes parallel work more likely to affect each other.
+
+## Related Commands
+
+- [`nb env current`](../env/current.md)
+- [`nb env use`](../env/use.md)
+- [`nb env status`](../env/status.md)

package/dist/ai/docs/nocobase/api/cli/session/remove.md

@@ -0,0 +1,35 @@
+---
+title: "nb session remove"
+description: "nb session remove command reference: remove shell or runtime integration for NB_SESSION_ID."
+keywords: "nb session remove,NocoBase CLI,NB_SESSION_ID,remove session integration"
+---
+
+# nb session remove
+
+Remove session integration for `NB_SESSION_ID`.
+
+This command cleans up shell configuration previously written by [`nb session setup`](./setup.md). If opencode plugin integration is detected, it removes that integration too.
+
+## Usage
+
+```bash
+nb session remove [flags]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `--shell` | string | Target shell. Supported values: `bash`, `zsh`, `fish`, `powershell`, `cmd` |
+
+## Examples
+
+```bash
+nb session remove
+nb session remove --shell zsh
+```
+
+## Related Commands
+
+- [`nb session setup`](./setup.md)
+- [`nb session id`](./id.md)

package/dist/ai/docs/nocobase/api/cli/session/setup.md

@@ -0,0 +1,47 @@
+---
+title: "nb session setup"
+description: "nb session setup command reference: install shell or runtime integration for NB_SESSION_ID."
+keywords: "nb session setup,NocoBase CLI,NB_SESSION_ID,shell integration"
+---
+
+# nb session setup
+
+Install session integration for `NB_SESSION_ID`.
+
+This command detects the current shell, or uses the shell you pass with `--shell`, and writes the matching initialization file so new shell sessions automatically get `NB_SESSION_ID`.
+
+If opencode configuration is detected on the machine, it also writes the related plugin integration so the agent runtime can inject its own `NB_SESSION_ID`.
+
+## Usage
+
+```bash
+nb session setup [flags]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `--shell` | string | Target shell. Supported values: `bash`, `zsh`, `fish`, `powershell`, `cmd` |
+
+## Notes
+
+In most cases, you only need to run this once.
+
+After it finishes, open a new shell session or reload your profile so `NB_SESSION_ID` is initialized automatically.
+
+In agent runtimes such as Codex, if the runtime already injects a context variable such as `CODEX_THREAD_ID`, the CLI reuses that value first.
+
+## Examples
+
+```bash
+nb session setup
+nb session setup --shell zsh
+nb session setup --shell powershell
+```
+
+## Related Commands
+
+- [`nb session id`](./id.md)
+- [`nb session remove`](./remove.md)
+- [`nb env use`](../env/use.md)

package/dist/ai/docs/nocobase/interface-builder/actions/types/js-action.md

@@ -35,7 +35,7 @@ JS Action is used to execute JavaScript when a button is clicked, allowing for c
 ![jsaction-toolbars-20251029](https://static-docs.nocobase.com/jsaction-toolbars-20251029.png)
 
 
-- You can use AI employees to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- You can use AI employees to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage (Simplified Examples)
 

package/dist/ai/docs/nocobase/interface-builder/actions/types/js-item.md

@@ -47,7 +47,7 @@ The JS Item runtime injects common capabilities that you can use directly in the
 
 ![](https://static-docs.nocobase.com/JS-Item-03-27-2026_03_35_PM.png)
 
-- You can use AI employees to generate / modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- You can use AI employees to generate / modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage (Simplified Examples)
 

package/dist/ai/docs/nocobase/interface-builder/blocks/other-blocks/js-block.md

@@ -38,7 +38,7 @@ The JS Block's script editor supports syntax highlighting, error hints, and buil
 
 Additionally, you can directly summon the AI employee "Frontend Engineer · Nathan" from the top-right corner of the editor. Nathan can help you write or modify scripts based on the current context. You can then "Apply to editor" with one click and run the code to see the effect. For details, see:
 
-- [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Runtime Environment and Security
 

package/dist/ai/docs/nocobase/interface-builder/fields/specific/js-column.md

@@ -37,7 +37,7 @@ The script editor for JS Column supports syntax highlighting, error hints, and b
 
 You can also use an AI Employee to generate code:
 
-- [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage
 

package/dist/ai/docs/nocobase/interface-builder/fields/specific/js-field.md

@@ -58,7 +58,7 @@ The JS Field script editor supports syntax highlighting, error hints, and built-
 
 You can also generate code with the AI Employee:
 
-- [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage
 

package/dist/ai/docs/nocobase/interface-builder/fields/specific/js-item.md

@@ -32,7 +32,7 @@ JS Item is used for "custom items" (not bound to a field) in a form. You can use
 ![jsitem-toolbars-20251029](https://static-docs.nocobase.com/jsitem-toolbars-20251029.png)
 
 
-- Can be used with AI Employee to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/features/built-in-employee)
+- Can be used with AI Employee to generate/modify scripts: [AI Employee · Nathan: Frontend Engineer](/ai-employees/built-in/)
 
 ## Common Usage (Simplified Examples)
 

package/dist/ai/docs/nocobase/security/guide.md

@@ -213,6 +213,18 @@ If you need to store sensitive files, it is recommended to use a cloud storage s
 
 ![](https://static-docs.nocobase.com/202501031623549.png)
 
+For local storage or other public storage that can be accessed directly through same-origin application URLs, you should also pay extra attention to the risks introduced by active content files. Files such as `html`, `xhtml`, and `svg` may be parsed and executed directly by the browser. If an attacker can upload such a file and trick a user into opening it, the attacker may use your trusted application domain to host a malicious page or script.
+
+In most cases, we recommend that administrators:
+
+- Prefer private storage, signed URLs, or a separate file domain, so that user-uploaded files are not served directly from the same origin as the main application.
+- Enforce a strict MIME type allowlist for uploads and only allow the file types that are actually required by the business.
+- Be cautious about allowing active content types such as `text/html`, `application/xhtml+xml`, and `image/svg+xml`. Even if the system tries to return these files as downloads, this should not be considered a complete replacement for upload restrictions and origin isolation.
+- Apply consistent security settings to reverse proxies, CDNs, object storage, and any other static file delivery layer, so dangerous files are not returned inline by bypassing application-layer protections.
+- Do not use local/public storage to host untrusted web content. If you really need this capability, use an isolated domain and separately evaluate CSP, download behavior, and access control.
+
+If an administrator explicitly allows dangerous file types to be uploaded, they should assess the resulting phishing, same-origin script execution, and sensitive information leakage risks on their own, and ensure that the Web Server, gateway, CDN, and storage services in the deployment chain enforce consistent restrictions.
+
 
 ### Application Backup
 
@@ -293,4 +305,4 @@ NocoBase provides multiple log types to help users understand the system's runni
 - Request log: API request logs, including accessed URLs, HTTP methods, request parameters, response times, and status codes.
 - System log: Records application running events, including service startup, configuration changes, error messages, and key operations.
 - SQL log: Records database operation statements and their execution times, covering operations such as query, update, insert, and delete.
-- Workflow log: Execution log of the workflow, including execution time, running information, and error information.
+- Workflow log: Execution log of the workflow, including execution time, running information, and error information.

package/dist/ai/docs/nocobase/system-management/localization/index.md

@@ -4,6 +4,8 @@
 
 The Localization Management plugin is used to manage and implement NocoBase's localization resources. It can translate system menus, collections, fields, and all plugins to adapt to the language and culture of specific regions.
 
+If you want to contribute default translations for the system and official plugins to NocoBase, see [Translation Contribution](/get-started/translations).
+
 ## Installation
 
 This plugin is built-in and requires no additional installation.
@@ -36,6 +38,8 @@ After synchronization, the system will list all translatable entries for the cur
 Different modules may have the same original text entries, which need to be translated separately.
 :::
 
+If translations for system or plugin built-in entries are manually changed or overwritten by AI translation, select `Reset system built-in entry translations` during synchronization. After synchronization, the system will overwrite existing built-in entry translations for the current language with translations from the built-in language pack to restore the defaults.
+
 ### Automatically Create Translation Entries
 
 When editing a page, custom text within each block will automatically generate the corresponding i18n entry and simultaneously create the translation for the current language.
@@ -54,6 +58,26 @@ When defining text in code, you need to manually specify the ns (namespace), for
 
 <img src="https://static-docs.nocobase.com/202404202142836.png"/>
 
+### Using AI Translation
+
+Localization Management supports translating entries through the AI Employee Lina. After enabling AI Employees and configuring a model service, you can use AI translation on the Localization Management page to batch generate translations for the current language.
+
+![](https://static-docs.nocobase.com/202605121152196.png)
+
+Supported translation scopes:
+
+- **Full translation**: translate all eligible entries in the current language.
+- **Incremental translation**: only translate entries that do not have translations yet.
+- **Selected translation**: select entries in the table and translate only the selected content.
+
+AI translation creates a background task. You can view progress while the task runs. After completion, translations are written to the corresponding language and should still be reviewed and corrected according to the actual context.
+
+For the complete guide, see [AI Employee - Lina](/ai-employees/built-in/lina).
+
+:::warning{title=Note}
+AI-generated translations may have semantic deviations, inconsistent terminology, or insufficient context understanding. Before publishing, manually review important pages, business terminology, and user-facing copy.
+:::
+
 ### Publishing Translations
 
 After completing the translation, you need to click the "Publish" button to make the changes take effect.
@@ -76,4 +100,4 @@ Synchronize the entries.
 
 Translate and publish.
 
-<img src="https://static-docs.nocobase.com/202404202143135.png"/>
+<img src="https://static-docs.nocobase.com/202404202143135.png"/>