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

package/dist/ai/docs/nocobase/file-manager/storage/s3-pro.md

@@ -12,7 +12,7 @@ Building on the File Manager plugin, this adds support for S3 protocol-compatibl
 
 1. Client-side upload: The file upload process does not go through the NocoBase server, but directly connects to the file storage service, providing a more efficient and faster upload experience.
     
-2. Private access: When accessing files, all URLs are signed temporary authorized addresses, ensuring the security and timeliness of file access.
+2. Private access: Signed URLs with an expiration are used by default. Unsigned URLs can also be generated for public buckets.
 
 
 ## Use Cases
@@ -39,6 +39,57 @@ Building on the File Manager plugin, this adds support for S3 protocol-compatibl
 
 ![](https://static-docs.nocobase.com/20250413190828536.png)
 
+## URL Configuration
+
+In addition to the File Manager's common NocoBase URL, Original URL, and Allow public access options, S3 Pro lets you configure upload and access URL formats separately and choose whether to use signed URLs. See [Storage Engine Overview](./index.md#file-urls-and-access-control) for the common options.
+
+These options control different stages:
+
+- NocoBase URL / Original URL controls which address the file record returns
+- Allow public access controls whether file record view permissions are checked when a NocoBase URL is accessed
+- Do not use signed URL controls whether the object storage service validates a URL signature
+
+These settings can be combined independently. The recommended default is NocoBase URL, Allow public access unchecked, and signed URLs enabled.
+
+![S3 Pro URL configuration](https://static-docs.nocobase.com/20260723221441.png)
+
+### How to choose
+
+| Use case | File URL | Allow public access | Do not use signed URL |
+| --- | --- | --- | --- |
+| Files must follow role and data permissions while the bucket remains private | NocoBase URL | Unchecked | Unchecked |
+| A public NocoBase file address is required while the bucket remains private | NocoBase URL | Checked | Unchecked |
+| An external service needs temporary access to the storage address | Original URL | Not applicable | Unchecked; configure Access URL expiration |
+| A public bucket or CDN requires an unsigned original address | Original URL | Not applicable | Checked |
+
+### Upload URL format
+
+Upload URL format controls the S3 URL used by the client when uploading files. Select the format supported by your storage service. The configuration form displays an example based on the current Endpoint, Bucket, and path:
+
+- Bucket as subdomain: `https://bucket-name.s3.example.com/path/to/object`
+- Bucket as subpath: `https://s3.example.com/bucket-name/path/to/object`
+- Ignore bucket: `https://upload.example.com/path/to/object`
+
+### Access URL format
+
+Access URL format controls whether the Bucket appears in the domain, in the path, or not at all when S3 Pro generates a file access address. It provides the same three formats as Upload URL format, but can be configured separately—for example, uploads can use an S3 Endpoint while access uses a CDN domain that does not include the Bucket.
+
+This option affects Original URLs and the storage address that a NocoBase URL ultimately redirects to, but it does not change the NocoBase URL format itself.
+
+### Do not use signed URL
+
+S3 Pro uses signed URLs by default. A generated Original URL includes signature parameters, for example:
+
+```text
+https://bucket-name.s3.example.com/path/to/object?X-Amz-Signature=xxxx
+```
+
+The signed URL remains valid for the configured Access URL expiration, and the bucket can remain private. When NocoBase URL is used, NocoBase generates or redirects to a signed address after the permission check succeeds.
+
+When Do not use signed URL is checked, S3 Pro generates an address without signature parameters. The bucket and uploaded objects must then allow public read access, and Access URL expiration no longer takes effect.
+
+Do not use signed URL only controls whether the storage service validates a signature; it does not change NocoBase file record permissions. If NocoBase URL is selected and Allow public access is unchecked, the request must still pass the NocoBase permission check first.
+
 
 
 ## Service Provider Configuration
@@ -146,9 +197,9 @@ Building on the File Manager plugin, this adds support for S3 protocol-compatibl
 ![](https://static-docs.nocobase.com/file-storage-s3-pro-1735355971345.png)
 
 
-#### Public Access (Optional)
+#### Unsigned Public Access (Optional)
 
-This is an optional configuration. Configure it when you need to make uploaded files completely public.
+Configure this only when unsigned URLs are required, because the Bucket and uploaded objects must allow public read access. If you only need to share a public NocoBase URL, check Allow public access and keep signed URLs enabled; the Bucket does not need to be public.
 
 1. Go to the Permissions panel, scroll down to Object Ownership, click edit, and enable ACLs.
 
@@ -162,7 +213,7 @@ This is an optional configuration. Configure it when you need to make uploaded f
 ![](https://static-docs.nocobase.com/file-storage-s3-pro-1735355971668.png)
 
 
-3. Check Public access in NocoBase.
+3. Check Do not use signed URL in NocoBase.
 
 
 #### Thumbnail Configuration (Optional)
@@ -193,7 +244,7 @@ This configuration is optional and is used to optimize image preview size or eff
 5. In the NocoBase configuration, there are several points to note:
    1. `Thumbnail rule`: Fill in image processing-related parameters, for example, `?width=100`. For details, refer to the [AWS documentation](https://docs.aws.amazon.com/solutions/latest/serverless-image-handler/use-supported-query-param-edits.html).
    2. `Access endpoint`: Fill in the value of Outputs -> ApiEndpoint after deployment.
-   3. `Full access URL style`: You need to check **Ignore** (because the bucket name was already filled in during configuration, it is no longer needed for access).
+   3. Access URL format: Select **Ignore bucket** because the bucket name is already included in the configuration and is not needed in the access URL.
    
    
 ![](https://static-docs.nocobase.com/20250414152135514.png)
@@ -312,7 +363,7 @@ This configuration is optional and should only be used when you need to optimize
 
 1. Fill in the `Thumbnail rule` related parameters. For specific parameter settings, refer to [Image Processing Parameters](https://www.alibabacloud.com/help/en/object-storage-service/latest/process-images).
 
-2. `Full upload URL style` and `Full access URL style` can be kept the same.
+2. Upload URL format and Access URL format can use the same setting.
 
 #### Configuration Example
 
@@ -357,7 +408,7 @@ This configuration is optional and should only be used when you need to optimize
    - **AccessKey ID** and **AccessKey Secret** are the values saved in the previous step.
    - **Region**: A self-hosted MinIO does not have the concept of a Region, so it can be configured as "auto".
    - **Endpoint**: Fill in the domain name or IP address of your deployment.
-   - Full access URL style must be set to Path-Style.
+   - Set Access URL format to Bucket as subpath.
 
 #### Configuration Example
 

package/dist/ai/docs/nocobase/get-started/installation/docker-nginx.mdx

@@ -96,8 +96,11 @@ services:
 - `./storage` must be mounted into both the `app` and `nginx` containers so they can share proxy config, static assets, and uploaded files
 - The `nginx` container should wait until `nocobase.conf` is generated, then link it to `/etc/nginx/conf.d/default.conf` with `ln -sf`
 - The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
+- Before Nginx returns a legacy `/storage/uploads/` file through `alias`, the generated config uses `auth_request` to ask NocoBase to verify the login state; anonymous access returns `401` by default
 - If you use an external Nginx container, let the `nginx` container handle the host port mapping. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
 
+If an existing program depends on anonymous access to `/storage/uploads/`, add `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` to `app.environment` and restart the application container. Do not remove or rewrite the `auth_request` in the generated config; the auth endpoint uses this variable to decide whether anonymous access is allowed. This variable does not change record-level permissions for `/files/`.
+
 ## If you use a local host Nginx
 
 If your Nginx is installed directly on the host instead of running in a Docker container, it is better to use a separate `docker-compose.yml`. In this setup, the `app` service must expose a host port directly, and the proxy-related environment variables should use host-side values.
@@ -171,7 +174,7 @@ sudo systemctl reload nginx
 
 If your host Nginx does not use the `conf.d` directory, replace the link target with your own config path. Usually it is safer to keep `nocobase.conf` as a file included from the `http {}` context instead of copying its content manually.
 
-If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
+If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. When serving `/storage/uploads/` through `alias`, you must also configure `auth_request` so the static directory cannot bypass the application login check. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
 
 ## Related links
 

package/dist/ai/docs/nocobase/get-started/installation/docker.mdx

@@ -660,6 +660,8 @@ If you also want to enable HTTPS, configure `443` and the certificate on the hos
 
 The `location /` block in this root-path configuration also proxies `/api/`, `/ws`, and `/files/`. If you split static assets from application routes, make sure `/files/` is still forwarded to NocoBase and is not handled as a static directory.
 
+Before returning a legacy `/storage/uploads/` file, the built-in Nginx asks NocoBase to verify the login state; anonymous access returns `401` by default. If a program already depended on anonymous access to these legacy URLs before an upgrade, add `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` to `app.environment` and restart the container. Keep forwarding this path from the host Nginx to the container. Do not expose the host upload directory directly with another `alias`, because that would bypass the check.
+
 ### Subpath deployment
 
 If you want to deploy the app under a subpath, such as `https://your_domain.com/nocobase/`, configure the `APP_PUBLIC_PATH` environment variable first:

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

@@ -107,6 +107,18 @@ NocoBase uses cookies to maintain login state and to authorize [stable file URLs
 Prefer serving the pages and the API from the same origin through a reverse proxy and leaving `API_BASE_URL` empty.
 :::
 
+### LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS
+
+Controls whether legacy local file URLs under `/storage/uploads/` allow anonymous access. The default is `false`, so only signed-in users can access them.
+
+If an existing integration depends on public access through these URLs, explicitly enable compatibility mode:
+
+```bash
+LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true
+```
+
+Restart the application after changing this variable. It affects only legacy `/storage/uploads/` URLs and does not change record-level permissions for `/files/`. Public access may expose uploaded files, so enable it only after confirming that the files are safe to publish.
+
 ### CORS_ORIGIN_WHITELIST
 
 Whitelist of origins allowed to access the API cross-origin with credentials (cookies). Multiple origins are separated by commas. Empty by default.
@@ -392,7 +404,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/nocobase-cli/production/reverse-proxy/caddy.md

@@ -135,7 +135,7 @@ Taking `test2` as an example, key directories related to Caddy usually include:
 In other words, handwritten configuration usually needs to cover at least the following types of entries:
 
 - `v`: Redirect `/v` to `/v/`
-- `uploads`: Expose upload directory
+- `uploads`: Expose the upload directory after NocoBase authentication
 - `dist`: Expose the front-end build product directory
 - `oauth well-known`: Handle OAuth discovery paths
 - `openid well-known`: Handle OpenID discovery paths
@@ -164,10 +164,31 @@ c.local.nocobase.com {
     }
 
     handle_path /storage/uploads/* {
-        root * NB_CLI_ROOT/test2/storage/uploads
-        header Cache-Control public
-        header X-Content-Type-Options nosniff
-        file_server
+        route {
+            request_header -X-NocoBase-Auth-Set-Cookie
+            forward_auth host.docker.internal:56575 {
+                uri /api/auth:checkLegacyFileAccess
+                header_up X-App {query.__appName}
+                copy_headers Set-Cookie>X-NocoBase-Auth-Set-Cookie
+            }
+
+            @refreshedAuth header X-NocoBase-Auth-Set-Cookie *
+            header @refreshedAuth Set-Cookie {header.X-NocoBase-Auth-Set-Cookie}
+            header Cache-Control "private, no-store"
+            header Content-Security-Policy sandbox
+            header X-Content-Type-Options nosniff
+            header Content-Disposition inline
+
+            @activeUploadedContent path_regexp activeUploadedContent (?i)\.(?:htm|html|pdf|svg|svgz|xht|xhtml|xml|xsl|xslt)$
+            header @activeUploadedContent Content-Disposition attachment
+            @download query download=1
+            header @download Content-Disposition attachment
+            @markdown path_regexp markdown (?i)\.md$
+            header @markdown Content-Type text/markdown
+
+            root * NB_CLI_ROOT/test2/storage/uploads
+            file_server
+        }
     }
 
     handle_path /dist/* {
@@ -258,6 +279,8 @@ This is usually less likely to miss details related to `/files/`, WebSockets, st
 
 :::warning Note
 
+URLs under `/storage/uploads/` are legacy local file URLs and must pass NocoBase sign-in authentication by default. Do not expose the upload directory with `file_server` alone, because that bypasses access control. The example above uses `forward_auth` to call the NocoBase auth endpoint before Caddy sends the file. Set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` and restart the application only when anonymous access is explicitly required for compatibility.
+
 `/files/` is an application route that must pass through NocoBase authorization. Do not handle it as a static directory or let it fall through to the SPA fallback. Forward it to the NocoBase backend and place the rule before `handle_path /*` and other front-end fallback rules.
 
 If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/*`. Keep the root-level `/files/*` rule for compatibility with existing file URLs.

package/dist/ai/docs/nocobase/nocobase-cli/production/reverse-proxy/nginx.md

@@ -111,6 +111,7 @@ in:
 - `NB_CLI_ROOT/test2/storage/...` The following are the application's own static resources and upload directories
 - `app.conf` can be changed, but the NocoBase managed block must be retained
 - `index-v1.html` and `index-v2.html` will automatically rewrite resource addresses according to the current env subpath, active client version, and `CDN_BASE_URL`
+- `maps-http.conf` and `uploads-location.conf` protect legacy `/storage/uploads/` URLs together: the former resolves the sub-application parameter, and the latter runs an `auth_request` login check before Nginx returns a local file
 
 :::warning note
 
@@ -154,6 +155,11 @@ location / {
 For a CLI-hosted application like `test2`, a structure closer to a real deployment would usually look like this:
 
 ```nginx
+map $request_uri $legacy_file_app {
+    default "";
+    ~[?&]__appName=(?<legacy_file_app_name>[A-Za-z0-9_-]+)(?:&|$) $legacy_file_app_name;
+}
+
 server {
     listen 80;
     server_name c.local.nocobase.com;
@@ -165,6 +171,19 @@ server {
     include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/mime-types.conf;
     include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/gzip.conf;
 
+    location = /_nocobase_legacy_file_auth {
+        internal;
+        proxy_pass http://127.0.0.1:56575/api/auth:checkLegacyFileAccess;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header Cookie $http_cookie;
+        proxy_set_header Authorization $http_authorization;
+        proxy_set_header X-App $legacy_file_app;
+        proxy_set_header X-Original-URI $request_uri;
+        proxy_set_header Host $final_host;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+    }
+
     location /storage/uploads/ {
         alias NB_CLI_ROOT/test2/storage/uploads/;
         include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/uploads-location.conf;
@@ -216,6 +235,8 @@ server {
 }
 ```
 
+The `map` directive must be placed in Nginx's `http {}` context, not inside `server {}` or `location {}`. It identifies a sub-application from the `__appName` query parameter in a legacy file URL. The `/api/` segment in `proxy_pass` must match the application's actual `API_BASE_PATH`; when `APP_PUBLIC_PATH` is configured, use the same prefix for both the upload location and auth endpoint.
+
 There are two key points here:
 
 - `NB_CLI_ROOT/.nocobase/proxy/nginx/...` The following are agent auxiliary files maintained by CLI
@@ -243,6 +264,10 @@ This is usually less likely to miss details related to `/files/`, WebSockets, st
 
 If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/`. Keep the root-level `/files/` rule for compatibility with existing file URLs.
 
+Legacy `/storage/uploads/` URLs also require sign-in by default. When serving files directly with `alias`, run an `auth_request` to NocoBase's `auth:checkLegacyFileAccess` endpoint first. Configuring only the static directory bypasses the login check. The `uploads-location.conf` snippet in the example already contains the `auth_request` directive; if you do not use the CLI snippets, add the equivalent logic to the upload location yourself.
+
+If an existing integration must access legacy URLs anonymously, set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` for the NocoBase application and restart it. The auth endpoint evaluates this setting, so do not regenerate or remove the Nginx `auth_request` configuration. The switch affects only `/storage/uploads/` and does not change record-level permissions for `/files/`.
+
 :::
 
 ## How to handle HTTPS

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();
     });