@nocobase/plugin-ai 2.3.0-alpha.1 → 2.3.0-beta.2

package/dist/ai/docs/nocobase/get-started/installation/env.md

@@ -392,7 +392,7 @@ SERVER_REQUEST_WHITELIST=api.example.com,*.trusted.com,10.0.0.0/8,127.0.0.1
 
 **When not set**: All `http` / `https` outbound requests are allowed to keep existing behavior. However, if the target is a loopback, private, link-local, or metadata address, or if a domain resolves to one of these addresses, the server logs a warning.
 
-**When set**: Only requests whose host matches a whitelist entry are permitted; non-matching requests will raise an error. Future versions may gradually tighten the default behavior. If your deployment needs to access internal services, configure an explicit whitelist in advance.
+**When set**: The initial request and every redirect destination must match a whitelist entry; non-matching requests will raise an error before the next request is sent. Future versions may gradually tighten the default behavior. If your deployment needs to access internal services, configure an explicit whitelist in advance.
 
 Supported formats:
 

package/dist/ai/docs/nocobase/ops-management/migration-manager/built-in-tables.md

@@ -336,9 +336,8 @@ The “Data type” column comes from built-in classification. System base data
 | Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
 | --- | --- | --- | --- | --- | --- |
 | `aiKnowledgeBaseDocs` | Document chunks and index metadata stored in knowledge bases | Business runtime data | Schema-only | Not included | Backed up |
-| `aiKnowledgeBase` | Knowledge-base type, external ID, and base information | Business runtime data | Schema-only | Not included | Backed up |
+| `aiKnowledgeBase` | Knowledge-base type, external ID, vector database, LLM service, embedding model, and base information | Business runtime data | Schema-only | Not included | Backed up |
 | `aiVectorDatabases` | Vector database service and connection configuration | Business runtime data | Schema-only | Not included | Backed up |
-| `aiVectorStoreConfig` | Relationship between vector database connections and embedding models | Business runtime data | Schema-only | Not included | Backed up |
 
 ### Environment variables
 

package/dist/ai/docs/nocobase/plugin-development/build.md

@@ -6,7 +6,7 @@ keywords: "plugin build,plugin package,yarn build,tar,build.config.ts,Rsbuild,ts
 
 # Build and Package
 
-After plugin development is complete, you need to go through two steps — build (compile source code) and package (generate `.tar.gz`) — before distributing it to other NocoBase applications.
+After plugin development is complete, you need to go through two steps — build (compile source code) and package (generate `.tgz`) — before distributing it to other NocoBase applications.
 
 ## Build Plugin
 
@@ -26,13 +26,13 @@ If the plugin is created in a source code repository, the first build will trigg
 
 ## Package Plugin
 
-Packaging compresses the build artifacts into a `.tar.gz` file for easy upload to other environments:
+Packaging compresses the build artifacts into a `.tgz` file for easy upload to other environments:
 
 ```bash
 yarn nocobase tar @my-project/plugin-hello
 ```
 
-The package file is output to `storage/tar/@my-project/plugin-hello.tar.gz` by default.
+The package file is output to `storage/tar/` by default, named `<package-name>-<version>.tgz` — for example, `storage/tar/@my-project/plugin-hello-0.1.0.tgz`.
 
 You can also combine build and package into one step using the `--tar` flag:
 
@@ -42,7 +42,13 @@ yarn build @my-project/plugin-hello --tar
 
 ## Upload to Other NocoBase Applications
 
-Upload and extract the `.tar.gz` file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx).
+Upload and extract the `.tgz` file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx).
+
+If the target application was created with the NocoBase CLI (`nb init`), you can also import it directly with `nb plugin import` instead of extracting it manually:
+
+```bash
+nb plugin import /your/path/plugin-hello-0.1.0.tgz
+```
 
 ### Enable a Plugin by Default
 

package/dist/ai/docs/nocobase/plugin-development/client/appendix/faq.md

@@ -12,7 +12,7 @@ This page collects common pitfalls when developing client plugins. If you run in
 
 ### Plugin not visible in the Plugin Manager after creation
 
-Make sure you ran `yarn pm create` instead of manually creating the directory. `yarn pm create` not only generates files but also registers the plugin in the `applicationPlugins` database table. If you created the directory manually, run `yarn nocobase upgrade` to trigger a rescan.
+Make sure you ran `yarn pm create` instead of manually creating the directory. Besides generating files, `yarn pm create` updates `tsconfig.paths.json` and runs `yarn postinstall`, which links the plugin into `node_modules` and regenerates the client plugin index so the application can discover it. A manually created directory skips that step — run `yarn nocobase upgrade` to rescan and register it in the `applicationPlugins` table.
 
 ### No changes on the page after enabling a plugin
 

package/dist/ai/docs/nocobase/plugin-development/client/examples/custom-action.md

@@ -49,6 +49,8 @@ yarn pm create @my-project/plugin-simple-action
 
 For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Create Action Models
 
 Each action needs to declare the scenario it appears in via the `static scene` property:

package/dist/ai/docs/nocobase/plugin-development/client/examples/custom-block.md

@@ -51,6 +51,8 @@ yarn pm create @my-project/plugin-simple-block
 
 This will generate a basic file structure under `packages/plugins/@my-project/plugin-simple-block`. For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Create the Block Model
 
 Create `src/client-v2/models/SimpleBlockModel.tsx`. This is the core of the entire plugin -- defining how the block renders and how it's configured.

package/dist/ai/docs/nocobase/plugin-development/client/examples/custom-field.md

@@ -52,6 +52,8 @@ yarn pm create @my-project/plugin-field-simple
 
 For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Create the Field Model
 
 Create `src/client-v2/models/DisplaySimpleFieldModel.tsx`. This is the core of the plugin -- defining how the field renders and which field interface it binds to.

package/dist/ai/docs/nocobase/plugin-development/client/examples/fullstack-plugin.md

@@ -55,6 +55,8 @@ yarn pm create @my-project/plugin-custom-table-block-resource
 
 For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Define the Data Table (Server-Side)
 
 Create `src/server/collections/todoItems.ts`. NocoBase will automatically load collection definitions from this directory:

package/dist/ai/docs/nocobase/plugin-development/client/examples/settings-page.md

@@ -52,6 +52,8 @@ yarn pm create @my-project/plugin-settings-page
 
 This will generate a basic file structure under `packages/plugins/@my-project/plugin-settings-page`, including `src/client-v2/`, `src/server/`, `src/locale/`, and other directories. For detailed instructions, see [Writing Your First Plugin](../../write-your-first-plugin).
 
+Next, start development mode so your code changes hot-reload: for a project created by `nb init`, run `nb source dev` from the project root (`<app-path>`); for a NocoBase source repository you cloned yourself, run `yarn dev` from the source root.
+
 ## Step 2: Register the Settings Page
 
 Edit `src/client-v2/plugin.tsx`. In `load()`, use `this.pluginSettingsManager` to register the settings page. This is done in two steps -- first register the menu entry with `addMenuItem()`, then register the actual page with `addPageTabItem()`:

package/dist/ai/docs/nocobase/plugin-development/common/i18n.md

@@ -61,11 +61,11 @@ export class PluginSampleI18nServer extends Plugin {
           },
         ],
       });
-      await this.app.changeLanguage(answer1);
+      await this.app.i18n.changeLanguage(answer1);
       const answer2 = await input({
-        message: app.i18n.t('Enter your name'),
+        message: this.app.i18n.t('Enter your name'),
       });
-      console.log(app.i18n.t(`Your name is {{name}}`, { name: answer2 }));
+      console.log(this.app.i18n.t(`Your name is {{name}}`, { name: answer2 }));
     });
   }
 }

package/dist/ai/docs/nocobase/plugin-development/server/cache.md

@@ -212,7 +212,7 @@ export default class PluginCacheDemo extends Plugin {
     });
 
     // Create cache using newly registered store
-    const redisCache = await this.app.createCache({
+    const redisCache = await this.app.cacheManager.createCache({
       name: 'redisCache',
       store: 'redis',
       prefix: 'app:',

package/dist/ai/docs/nocobase/plugin-development/server/collections.md

@@ -197,12 +197,6 @@ When a plugin is first activated, the system will automatically synchronize Coll
 yarn nocobase upgrade
 ```
 
-If exceptions or dirty data occur during synchronization, you can rebuild the table structure by reinstalling the application:
-
-```bash
-yarn nocobase install -f
-```
-
 If you need to migrate existing data during plugin upgrades -- such as renaming fields, splitting tables, backfilling default values, etc. -- you should handle it through [Migration](./migration.md) scripts rather than manually modifying the database.
 
 ## Making a Collection Appear in the UI Data Table List

package/dist/ai/docs/nocobase/plugin-development/server/command.md

@@ -30,7 +30,7 @@ export default function (app: Application) {
   app
     .command('echo')
     .option('-v, --version')
-    .action(async ([options]) => {
+    .action(async (options) => {
       console.log('Hello World!');
       if (options.version) {
         console.log('Current version:', await app.version.get());
@@ -68,7 +68,7 @@ export default class PluginHelloServer extends Plugin {
       app
         .command('echo')
         .option('-v, --version')
-        .action(async ([options]) => {
+        .action(async (options) => {
           console.log('Hello World!');
           if (options.version) {
             console.log('Current version:', await app.version.get());

package/dist/ai/docs/nocobase/plugin-development/server/context.md

@@ -56,7 +56,7 @@ resourceManager.use(async (ctx) => {
 
 ```ts
 resourceManager.use(async (ctx) => {
-  await ctx.cache.set('key', 'value', { ttl: 60 }); // Cache for 60 seconds
+  await ctx.cache.set('key', 'value', 60 * 1000); // Cache for 60 seconds (TTL is in milliseconds)
   const val = await ctx.cache.get('key');
   ctx.body = val;
 });
@@ -113,7 +113,7 @@ resourceManager.use(async (ctx) => {
 
 ```ts
 resourceManager.use(async (ctx) => {
-  const canEdit = await ctx.can('edit', 'posts');
+  const canEdit = ctx.can({ resource: 'posts', action: 'edit' });
   if (!canEdit) {
     ctx.throw(403, 'Forbidden');
   }

package/dist/ai/docs/nocobase/plugin-development/server/i18n.md

@@ -68,13 +68,13 @@ export class PluginSampleI18nServer extends Plugin {
         ]
       });
 
-      await this.app.changeLanguage(answer1);
+      await this.app.i18n.changeLanguage(answer1);
 
       const answer2 = await input({
-        message: app.i18n.t('Enter your name')
+        message: this.app.i18n.t('Enter your name')
       });
 
-      console.log(app.i18n.t('Your name is {{name}}', { name: answer2 }));
+      console.log(this.app.i18n.t('Your name is {{name}}', { name: answer2 }));
     });
   }
 }
@@ -129,7 +129,7 @@ export class PluginSampleI18nServer extends Plugin {
   load() {
     this.app.use(async (ctx, next) => {
       if (ctx.path === '/api/plugin-i18n') {
-        ctx.body = this.plugin.t('Hello');
+        ctx.body = this.t('Hello');
       }
       await next();
     });

package/dist/ai/docs/nocobase/plugin-development/write-your-first-plugin.md

@@ -28,50 +28,83 @@ yarn pm create @my-project/plugin-hello
 After the command runs successfully, it will generate basic files in the `packages/plugins/@my-project/plugin-hello` directory. The default structure is as follows:
 
 ```bash
-├─ /packages/plugins/@my-project/plugin-hello
-  ├─ package.json
-  ├─ README.md
-  ├─ client-v2.d.ts
-  ├─ client-v2.js
-  ├─ server.d.ts
-  ├─ server.js
-  └─ src
-     ├─ index.ts                 # Default export server-side plugin
-     ├─ client-v2                 # Client-side code location
-     │  ├─ index.tsx             # Default exported client-side plugin class
-     │  ├─ plugin.tsx            # Plugin entry (extends @nocobase/client-v2 Plugin)
-     │  ├─ models                # Optional: frontend models (such as flow nodes)
-     │  │  └─ index.ts
-     │  └─ utils
-     │     ├─ index.ts
-     │     └─ useT.ts
-     ├─ server                   # Server-side code location
-     │  ├─ index.ts              # Default exported server-side plugin class
-     │  ├─ plugin.ts             # Plugin entry (extends @nocobase/server Plugin)
-     │  ├─ collections           # Optional: server-side collections
-     │  ├─ migrations            # Optional: data migrations
-     │  └─ utils
-     │     └─ index.ts
-     ├─ utils
-     │  ├─ index.ts
-     │  └─ tExpr.ts
-     └─ locale                   # Optional: multi-language
-        ├─ en-US.json
-        └─ zh-CN.json
+packages/plugins/@my-project/plugin-hello/
+├─ package.json
+├─ README.md
+├─ .npmignore
+├─ client-v2.d.ts            # v2 client entry type declaration
+├─ client-v2.js              # v2 client entry
+├─ client.d.ts               # v1 client entry type declaration
+├─ client.js                 # v1 client entry
+├─ server.d.ts               # Server entry type declaration
+├─ server.js                 # Server entry
+└─ src
+   ├─ index.ts               # Default export server-side plugin
+   ├─ client-v2              # v2 client-side code location
+   │  ├─ index.tsx           # Default exported client-side plugin class
+   │  ├─ plugin.tsx          # Plugin entry (extends @nocobase/client-v2 Plugin)
+   │  └─ client.d.ts
+   ├─ client                 # v1 client-side code location
+   │  ├─ index.tsx
+   │  ├─ plugin.tsx
+   │  ├─ locale.ts
+   │  ├─ models
+   │  │  └─ index.ts
+   │  └─ client.d.ts
+   ├─ server                 # Server-side code location
+   │  ├─ index.ts            # Default exported server-side plugin class
+   │  ├─ plugin.ts           # Plugin entry (extends @nocobase/server Plugin)
+   │  └─ collections         # Server-side collections (empty directory initially)
+   └─ locale                 # Locale resources
+      ├─ en-US.json
+      └─ zh-CN.json
 ```
 
-After creation, you can access the plugin manager page in your browser (default URL: http://localhost:13000/admin/settings/plugin-manager) to confirm whether the plugin appears in the list.
+The scaffold generates a minimal skeleton — `src/client-v2/` contains only entry files. The `models/` directory and `locale.ts` used in the following steps are ones you create yourself.
+
+Next, start development mode so your code changes hot-reload:
+
+- If the project was created with the NocoBase CLI (`nb init`), run this from the project root (`<app-path>`):
+
+  ```bash
+  nb source dev
+  ```
+
+- If you cloned the NocoBase source repository yourself, run this from the source root:
+
+  ```bash
+  yarn dev
+  ```
+
+Once it is running, access the plugin manager page in your browser (default URL: http://localhost:13000/admin/settings/plugin-manager) to confirm whether the plugin appears in the list.
 
 ## Step 2: Implement a Simple Client Block
 
 Next, we'll add a custom block model to the plugin to display a welcome message.
 
-1. **Create a new block model file** `client-v2/models/HelloBlockModel.tsx`:
+1. **Create the translation helper file** `src/client-v2/locale.ts`. `tExpr` declares a namespaced translation expression, and `useT` provides the translation function inside components:
+
+```ts
+import { tExpr as _tExpr, useFlowEngine } from '@nocobase/flow-engine';
+// @ts-ignore
+import pkg from '../../package.json';
+
+export function useT() {
+  const engine = useFlowEngine();
+  return (str: string) => engine.context.t(str, { ns: [pkg.name, 'client'] });
+}
+
+export function tExpr(key: string) {
+  return _tExpr(key, { ns: [pkg.name, 'client'] });
+}
+```
+
+2. **Create a new block model file** `src/client-v2/models/HelloBlockModel.tsx`:
 
 ```tsx pure
-import { BlockModel } from '@nocobase/client-v2';
 import React from 'react';
-import { tExpr } from '../utils';
+import { BlockModel } from '@nocobase/client-v2';
+import { tExpr } from '../locale';
 
 export class HelloBlockModel extends BlockModel {
   renderComponent() {
@@ -89,18 +122,27 @@ HelloBlockModel.define({
 });
 ```
 
-2. **Register the block model**. Edit `client-v2/models/index.ts` to export the new model for frontend runtime loading:
+3. **Register the block model**. Creating the model file is not enough on its own — the frontend runtime does not scan the `models/` directory automatically, so you have to register it explicitly in the plugin entry. Edit `src/client-v2/plugin.tsx` and declare how the model is loaded via `registerModelLoaders` inside `load()`:
 
-```ts
-import { ModelConstructor } from '@nocobase/flow-engine';
-import { HelloBlockModel } from './HelloBlockModel';
+```tsx pure
+import { Plugin } from '@nocobase/client-v2';
+
+export class PluginHelloClientV2 extends Plugin {
+  async load() {
+    this.flowEngine.registerModelLoaders({
+      HelloBlockModel: {
+        loader: () => import('./models/HelloBlockModel'),
+      },
+    });
+  }
+}
 
-export default {
-  HelloBlockModel,
-} as Record<string, ModelConstructor>;
+export default PluginHelloClientV2;
 ```
 
-After saving the code, if you're running a development script, you should see hot-reload logs in the terminal output.
+`registerModelLoaders` takes lazy-loading functions, so a model is only loaded once it is actually used. The key (`HelloBlockModel`) must match the model class name — the runtime uses it to pick the model class out of the module's named exports.
+
+After saving the code, if you're running development mode, you should see hot-reload logs in the terminal output.
 
 ## Step 3: Activate and Test the Plugin
 
@@ -162,7 +204,7 @@ If the plugin is created in a source code repository, the first build will trigg
 
 :::
 
-After the build completes, the package file is located at `storage/tar/@my-project/plugin-hello.tar.gz` by default.
+After the build completes, the package file is located under `storage/tar/` by default, named `<package-name>-<version>.tgz` — for example, `storage/tar/@my-project/plugin-hello-0.1.0.tgz`.
 
 :::tip
 
@@ -174,6 +216,12 @@ It's recommended to write test cases to verify core logic before publishing a pl
 
 Upload and extract the package file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx).
 
+If the target application was created with the NocoBase CLI (`nb init`), you can also import it directly with `nb plugin import` instead of extracting it manually:
+
+```bash
+nb plugin import /your/path/plugin-hello-0.1.0.tgz
+```
+
 ## Related Links
 
 - [Plugin Development Overview](./index.md) — Understand NocoBase microkernel architecture and plugin lifecycle