@nocobase/plugin-ai 2.2.0-beta.16 → 2.2.0-beta.18

package/dist/ai/docs/nocobase/ai-dev/watermark-plugin.md

@@ -85,6 +85,8 @@ yarn pm create @my-project/plugin-watermark
 
 AI generates a standard plugin directory structure under `packages/plugins/@my-project/plugin-watermark/`.
 
+Once the scaffold is created, 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.
+
 ### 3. Write Server-Side Code
 
 AI will generate the following files:

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

@@ -1,12 +1,12 @@
 ---
 title: "nb api resource create"
-description: "nb api resource create command reference: create a record in a selected NocoBase resource."
+description: "nb api resource create command reference: create one or more records in a selected NocoBase resource."
 keywords: "nb api resource create,NocoBase CLI,create record,CRUD"
 ---
 
 # nb api resource create
 
-Create a record in a selected resource. Pass record data as a JSON object through `--values`.
+Create records in a selected resource. Pass record data as a JSON object through `--values`, or as a JSON array of objects to create multiple records in a single request.
 
 ## Usage
 
@@ -21,7 +21,7 @@ nb api resource create --resource <resource> --values <json> [flags]
 | `--resource` | string | Resource name, required |
 | `--data-source` | string | Data source key, default `main` |
 | `--source-id` | string | Source record ID for association resources |
-| `--values` | string | Data for the new record as a JSON object, required |
+| `--values` | string | Data for the new records: a JSON object, or a JSON array of objects to create multiple records; required |
 | `--whitelist` | string[] | Fields allowed to write; repeatable or pass a JSON array |
 | `--blacklist` | string[] | Fields forbidden to write; repeatable or pass a JSON array |
 
@@ -31,6 +31,7 @@ Also supports common connection parameters from [`nb api resource`](./index.md).
 
 ```bash
 nb api resource create --resource users --values '{"nickname":"Ada"}'
+nb api resource create --resource users --values '[{"nickname":"Ada"},{"nickname":"Grace"}]'
 nb api resource create --resource posts.comments --source-id 1 --values '{"content":"Hello"}'
 ```
 

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

@@ -8,12 +8,53 @@ For file types that do not support native preview, you can enable preview functi
 
 Currently, NocoBase provides the following file preview plugins:
 
-* [Office File Preview Plugin](../file-preview/ms-office.md)
+- [Office File Preview Plugin](./ms-office.md)
 
-## PDF preview with external storage
+## PDF preview mechanism
 
-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.
+NocoBase selects the PDF preview method according to whether the file URL has the same origin as the current page:
+
+| File URL | Common storage type | Preview method | CORS requirement |
+| --- | --- | --- | --- |
+| Same origin as NocoBase | Local storage | NocoBase reads the file and renders it with the built-in PDF.js viewer | No cross-origin CORS involved |
+| Cross-origin | Third-party storage such as OSS, S3, COS, or a CDN | The browser opens the file URL in an iframe | The iframe preview itself does not require CORS |
+
+:::tip What determines the preview method
+
+The preview method depends on whether the file URL is same-origin, not directly on the storage engine name. Local storage served from a separate file domain is treated as cross-origin. Third-party storage accessed through a same-origin NocoBase proxy is treated as same-origin.
+
+:::
+
+### Local storage or a same-origin URL
+
+Local storage URLs usually start with `/storage/uploads/` and have the same origin as the NocoBase page. During preview, NocoBase reads the PDF data and passes it to the built-in PDF.js viewer to render pages and text.
+
+This method does not depend on the browser's built-in PDF reader. Even if the file response uses `Content-Disposition: attachment` for security, NocoBase can still read and render the file in the preview component. The file URL must remain accessible with the current login state.
+
+### Third-party storage or a cross-origin URL
+
+Third-party storage such as OSS, S3, COS, and CDNs usually uses a separate domain. NocoBase places this PDF URL in an iframe, so the browser and the storage service's response headers determine the result.
+
+To open a PDF in the iframe, the storage service should normally return `Content-Type: application/pdf` and must not force a download with `Content-Disposition: attachment`. If the response requests a download, the browser downloads the file directly and NocoBase cannot override that behavior in the frontend.
+
+Loading a cross-origin PDF in an iframe does not itself require CORS. However, the download button in the preview component reads the file with `fetch` and creates a Blob, so cross-origin downloads still require the storage service to allow CORS requests from the NocoBase site.
+
+### Notes for Aliyun OSS
+
+In some cases, the default Aliyun OSS domain forces a download by returning `Content-Disposition: attachment` and `x-oss-force-download: true`. Images may still preview normally, while a PDF placed in an iframe is downloaded.
+
+You can usually resolve this by binding a custom domain to the bucket and configuring NocoBase to access files through that domain. See [Aliyun OSS troubleshooting](../storage/aliyun-oss.md#common-issues) for configuration and diagnostic steps.
+
+### Security boundary for cross-origin previews
+
+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.
 
 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.
 
 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.
+
+## Related links
+
+- [Office File Preview Plugin](./ms-office.md)
+- [Aliyun OSS](../storage/aliyun-oss.md)
+- [S3 Pro](../storage/s3-pro.md)

package/dist/ai/docs/nocobase/file-manager/storage/aliyun-oss.md

@@ -7,7 +7,7 @@ A storage engine based on Aliyun OSS. Before use, you need to prepare the releva
 
 This engine does not support private access. After a file is uploaded, NocoBase generates a directly accessible URL, and anyone who has that URL can access the file.
 
-Even if the OSS bucket itself is private, the built-in Aliyun OSS engine does not generate temporary signed URLs for file access. If you need private access, use [S3 Pro](./s3-pro). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
+Even if the OSS bucket itself is private, the built-in Aliyun OSS engine does not generate temporary signed URLs for file access. If you need private access, use [S3 Pro](./s3-pro.md). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
 
 :::
 
@@ -18,9 +18,13 @@ Even if the OSS bucket itself is private, the built-in Aliyun OSS engine does no
 
 
 :::info{title=Note}
-This section only introduces the specific parameters for the Aliyun OSS storage engine. For general parameters, please refer to [General Engine Parameters](./index#引擎通用参数).
+This section only introduces the specific parameters for the Aliyun OSS storage engine. For general parameters, see [General Engine Parameters](./index.md#common-parameters).
 :::
 
+### Base URL
+
+Enter the file access URL prefix, such as a custom domain bound to the current bucket: `https://oss.example.com`. Accessing PDFs through the default Aliyun OSS domain may cause the browser to download them. We recommend binding a custom domain first. See [Common issues](#common-issues) below for details.
+
 ### Region
 
 Enter the region of the OSS storage, for example: `oss-cn-hangzhou`.
@@ -43,4 +47,97 @@ Enter the name of the OSS bucket.
 
 ### Timeout
 
-Enter the timeout for uploading to Aliyun OSS, in milliseconds. The default is `60000` milliseconds (i.e., 60 seconds).
+Enter the timeout for uploading to Aliyun OSS, in milliseconds. The default is `60000` milliseconds (i.e., 60 seconds).
+
+## Common issues
+
+### A PDF is downloaded instead of previewed
+
+NocoBase previews cross-origin PDFs in an iframe. The browser accesses the OSS file URL directly, so the OSS response headers determine whether the file is displayed or downloaded.
+
+If a PDF is downloaded from the iframe, inspect the file request in the browser developer tools. A typical problematic response looks like this:
+
+```http
+Content-Type: application/pdf
+Content-Disposition: attachment
+x-oss-force-download: true
+```
+
+`Content-Type: application/pdf` identifies the file correctly, but `Content-Disposition: attachment` instructs the browser to download it. The default Aliyun OSS domain forces downloads in some cases. See the official Aliyun documentation: [How do I configure a PDF file to be previewed instead of downloaded?](https://help.aliyun.com/zh/oss/user-guide/how-do-i-configure-an-object-to-be-previewed-instead-of-downloaded).
+
+We recommend the following configuration:
+
+1. Follow [Access OSS resources through a custom domain](https://help.aliyun.com/zh/oss/user-guide/access-buckets-via-custom-domain-names) to bind a custom domain to the bucket
+2. Configure DNS and the HTTPS certificate, then verify that the custom domain can access the file directly
+3. Configure the access URL for the NocoBase storage engine in use
+
+For step 3:
+
+- With the built-in **Aliyun OSS** engine, set **Base URL** to the bound custom domain, such as `https://oss.example.com`
+- With [S3 Pro](./s3-pro.md) connected to Aliyun OSS, the upload endpoint can continue to use the regional OSS endpoint; set the access endpoint to the custom domain and set `Full access URL style` to `Ignore`
+
+Upload a new PDF to verify the configuration. If an existing file record stores a complete URL, also make sure that the URL returned to the frontend now uses the custom domain.
+
+:::tip Check the response headers
+
+Previewing a cross-origin PDF in an iframe does not itself require CORS. Whether the PDF can be displayed inline primarily depends on `Content-Type` and `Content-Disposition`. This is separate from the CORS requirement for the download button described below.
+
+:::
+
+### An image previews correctly, but the download button reports a CORS error
+
+Images are usually previewed with `<img>`, and cross-origin PDFs are previewed with an iframe. Both can display resources without CORS response headers. The download button, however, reads the file with `fetch` and creates a Blob for the browser to download. This request is subject to the browser's same-origin policy.
+
+The following console error means that OSS did not return `Access-Control-Allow-Origin` for the current NocoBase site:
+
+```text
+Access to fetch at 'https://oss.example.com/path/to/file.jpg' from origin
+'https://example.com' has been blocked by CORS policy:
+No 'Access-Control-Allow-Origin' header is present on the requested resource.
+```
+
+Follow the official Aliyun guide [Configure cross-origin resource sharing](https://help.aliyun.com/zh/oss/user-guide/configure-cross-origin-resource-sharing) and create a CORS rule for the bucket. For downloads from the preview component, use values like these:
+
+| Setting | Recommended value |
+| --- | --- |
+| Allowed Origins | The complete NocoBase origin, such as `https://example.com` |
+| Allowed Methods | `GET`, `HEAD` |
+| Allowed Headers | `*` |
+| Expose Headers | `ETag`, `Content-Disposition` |
+| MaxAgeSeconds | `600` |
+
+If S3 Pro also uploads files directly from the browser, add methods such as `PUT` and `POST` according to the actual upload requests shown in the browser Network panel, or create a separate upload rule.
+
+After saving the rule, request the file again with the NocoBase site origin. The response should include at least:
+
+```http
+Access-Control-Allow-Origin: https://example.com
+Access-Control-Allow-Methods: GET, HEAD
+```
+
+The browser may already have cached the response used for the image preview. That request did not include an `Origin` header, and the cached response may not contain `Access-Control-Allow-Origin`. If downloading still fails after you configure CORS, clear the browser cache for the file or select **Disable cache** in the developer tools and try again.
+
+### Verify the response headers
+
+Use `curl` to simulate a cross-origin request from the NocoBase site. Replace the example origin, file URL, and signature parameters with the actual values:
+
+```bash
+curl -sS -D - -o /dev/null \
+  -H 'Origin: https://example.com' \
+  'https://oss.example.com/path/to/file.pdf?<signed-query>'
+```
+
+Check the following results:
+
+- PDF preview returns `Content-Type: application/pdf` without `Content-Disposition: attachment`
+- Cross-origin download returns an `Access-Control-Allow-Origin` matching the NocoBase site
+- The actual file URL uses the custom domain instead of the default `*.oss-cn-*.aliyuncs.com` domain
+
+It is normal for a request without an `Origin` header to omit CORS response headers. Keep the `Origin` header in the example when verifying CORS.
+
+## Related links
+
+- [File Preview](../file-preview/index.md)
+- [S3 Pro](./s3-pro.md)
+- [Migrate to S3 Pro](./migrate-to-s3-pro.md)
+- [Storage Engines](./index.md)

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

package/dist/ai/docs/nocobase/users-permissions/sync/index.md

@@ -8,6 +8,13 @@ pkg: '@nocobase/plugin-user-data-sync'
 
 This feature allows you to register and manage user data synchronization sources. By default, an HTTP API is provided, but additional data sources can be supported through plugins. It supports syncing data to the **Users** and **Departments** collections by default, with the possibility to extend synchronization to other target resources using plugins.
 
+## Available data sources
+
+- [DingTalk](./sources/dingtalk.md) — Synchronize DingTalk users and departments, with incremental updates through HTTP callbacks or Stream mode.
+- [LDAP](./sources/ldap.md) — Synchronize LDAP users and optional organizational units by reusing an LDAP authenticator.
+- [WeCom](./sources/wecom.md) — Synchronize users and departments from WeCom.
+- [HTTP API](./sources/api.md) — Push user and department data through the synchronization API.
+
 ## Data Source Management and Synchronization
 
 
@@ -51,4 +58,4 @@ For failed synchronization tasks, you can click **Retry**.
 In case of synchronization failures, you can troubleshoot the issue through system logs. Additionally, raw synchronization records are stored in the `user-data-sync` directory under the application logs folder.
 
 
-![](https://static-docs.nocobase.com/202412041205655.png)
+![](https://static-docs.nocobase.com/202412041205655.png)