@nocobase/plugin-ai 2.2.0-beta.8 → 2.2.0

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

package/dist/ai/docs/nocobase/plugins/@nocobase/plugin-block-comment/index.md

@@ -0,0 +1,14 @@
+---
+title: "Block: Comment"
+keywords: "Block: Comment,comment block,comment collection,plugin,NocoBase"
+displayName: "Block: Comment"
+packageName: '@nocobase/plugin-block-comment'
+description: |
+  Provides a Comment block for viewing and creating comments in record details, pop-ups, and similar scenarios.
+isFree: true
+builtIn: true
+defaultEnabled: false
+editionLevel: 0
+---
+
+# Block: Comment