@nocobase/plugin-ai 2.1.31 → 2.2.0-alpha.10

package/dist/ai/docs/nocobase/interface-builder/blocks/data-blocks/gantt.md

@@ -0,0 +1,204 @@
+---
+pkg: '@nocobase/plugin-gantt'
+title: 'Gantt Block'
+description: 'The Gantt block displays record start and end dates and progress on a timeline. It is suitable for project planning, task scheduling, and milestone tracking, and supports title fields, date fields, progress fields, color fields, time scale, the left table, and event popup settings.'
+keywords: 'Gantt block,Gantt,project planning,task scheduling,timeline,progress management,UI building,NocoBase'
+---
+
+# Gantt Block
+
+## Introduction
+
+The Gantt block displays record start and end dates and progress on a timeline. It is suitable for project planning, task scheduling, milestone tracking, and other scenarios where you need to view task duration by time.
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_30_AM.png)
+
+## Installation
+
+This block is a built-in plugin and does not require additional installation.
+
+## Add Block
+
+After selecting the Gantt block and choosing a data table, configure the fields required by the Gantt block in the popup:
+
+1. Select the title field, which is used to display the task name
+2. Select the start date field, which is used to determine the task start time
+3. Select the end date field, which is used to determine the task end time
+4. Optionally select the progress field, which is used to display and drag to update task progress
+5. Optionally select the color field, which is used to distinguish different tasks
+6. Select the time scale, which controls the granularity of the timeline
+
+After completing the configuration, you can create the Gantt block.
+
+![](<https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_27_AM%20(1).png>)
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_27_AM.png)
+
+## Block Settings
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_28_AM.png)
+
+### Gantt Fields
+
+Gantt fields determine how records are mapped to timeline tasks.
+
+They include:
+
+- The title field determines the name displayed on the task bar
+- The start date field determines where the task bar starts
+- The end date field determines where the task bar ends
+- The progress field determines the progress displayed inside the task bar
+- The color field determines the task bar color
+- The time scale determines whether the timeline is displayed by hour, day, week, month, and so on
+
+### Title Field
+
+Used to display the task name. Usually, you can select a string field such as task name, project name, or title.
+
+### Start Date Field
+
+Used to specify the task start time. The Gantt block uses this field to place the task on the timeline.
+
+### End Date Field
+
+Used to specify the task end time. When the start date and end date are the same, the task is displayed as a shorter time range.
+
+### Progress Field
+
+Used to display task completion progress, and supports updating it by dragging the progress handle on the task bar.
+
+The progress field uses a float field. Data is stored from `0` to `1`, and displayed as a percentage in the Gantt block. For example, `0.6` is displayed as `60%`.
+
+### Color Field
+
+Used to set the task bar color, making it easier to distinguish different task types, statuses, or priorities.
+
+The color field supports:
+
+- Single select field
+- Color field
+
+If a single select field is used, the Gantt block will prioritize the color configured for the selected option.
+
+### Time Scale
+
+Used to control the timeline display granularity.
+
+Currently supported:
+
+- Hour
+- Quarter of day
+- Half of day
+- Day
+- Week
+- Month
+- Year
+- Quarter
+
+For short task spans, use hour, half-day, or day. For longer task spans, use week, month, quarter, or year.
+
+### Show Table
+
+When enabled, the Gantt block displays a table area on the left. You can configure table columns to show key task attributes.
+
+When disabled, the block only displays the timeline on the right. This is suitable when page space is limited or you only need to view scheduling.
+
+### Table Width
+
+Used to set the width of the left table area. This setting only appears when Show table is enabled.
+
+If there are many table fields, increase the table width. If only a few fields are kept, reduce the width and leave more space for the timeline.
+
+### Enable Drag to Reschedule
+
+When enabled, you can drag task bars on the timeline to adjust start and end dates.
+
+Details:
+
+- Drag the whole task bar to adjust both the start date and end date
+- Drag the handles on both sides of the task bar to adjust the start date or end date
+- Drag the progress handle to update the progress field
+
+If you do not want users to modify schedules directly in the Gantt block, disable this option.
+
+### Scroll to Today on First Display
+
+When enabled, the Gantt block automatically scrolls to today when it is first displayed.
+
+This option is suitable for projects with long task spans. When the page opens, users can first see tasks near the current date.
+
+### Event Popup Settings
+
+Used to configure how a task bar opens after being clicked.
+
+You can configure:
+
+- Open mode, such as drawer, dialog, or page
+- Popup size
+- Popup template
+
+After clicking a task bar, NocoBase opens the current record according to this configuration, making it convenient to view or edit task details.
+
+### Data Scope
+
+Used to limit the data displayed in the Gantt block.
+
+For example: only show tasks under the current project, or only show unfinished tasks.
+
+For more details, refer to [Data Scope](../block-settings/data-scope).
+
+### Page Size
+
+Used to control the number of records loaded per page. When there are many records, users can switch pages to view more tasks.
+
+### Show Row Numbers
+
+When enabled, the left table displays row numbers, making it easier to locate records when there are many tasks.
+
+### Tree Table
+
+If the current data table is a tree table, the Gantt block can enable tree table mode. After enabling it, the left table displays records by parent-child hierarchy, and the timeline on the right displays tasks in the same hierarchy.
+
+In tree table mode, you can also configure Expand all rows by default.
+
+## Configure Fields
+
+The left table area uses table columns to display record fields.
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_29_AM.png)
+
+### Add Fields
+
+After Show table is enabled, you can add field columns to the left table. Field settings can refer to [Table Column](../../fields/generic/table-column).
+
+### Actions Column
+
+The Gantt block includes an actions column by default. You can add record actions such as view, edit, and delete to the actions column.
+
+If Event popup settings have already been configured, you can also click the task bar on the right to open record details.
+
+## Configure Actions
+
+The Gantt block supports configuring global actions at the top. Available action types depend on the enabled capabilities in the current environment.
+
+![](<https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_29_AM%20(1).png>)
+
+### Built-in Actions
+
+- Today: quickly scroll to today
+- Expand/Collapse: expand or collapse all rows in tree table mode
+
+### Global Actions
+
+- [Add New](../../actions/types/add-new)
+- [Popup](../../actions/types/pop-up)
+- [Link](../../actions/types/link)
+- [Refresh](../../actions/types/refresh)
+- [Filter](../../actions/types/filter)
+- [Bulk Edit](../../actions/types/bulk-edit)
+- [Bulk Update](../../actions/types/bulk-update)
+- [Trigger Workflow](../../actions/types/trigger-workflow)
+- [Custom Request](../../actions/types/custom-request)
+- [JS Item](../../actions/types/js-item)
+- [JS Action](../../actions/types/js-action)
+- [AI Employee](../../actions/types/ai-employee)

package/dist/ai/docs/nocobase/interface-builder/index.md

@@ -16,12 +16,9 @@ Edit mode:
 ![20251023215951](https://static-docs.nocobase.com/20251023215951.png)
 
 
-## Layout Template
+## UI Layout
 
-NocoBase ships with a default layout template: navigation on the top and left, and a content area on the right.
-
-
-![未命名.002](https://static-docs.nocobase.com/未命名.002.jpeg)
+NocoBase provides desktop and mobile layouts. The desktop layout works well for standard administration and adapts its navigation and page content on phones. The mobile layout provides separate mobile navigation and page configuration. See [UI Layout](./ui-layout/index.md) for details.
 
 
 ## Configuration Options
@@ -55,4 +52,8 @@ Action configuration options:
 Table column configuration options:
 
 
-![20251023221814](https://static-docs.nocobase.com/20251023221814.png)
+![20251023221814](https://static-docs.nocobase.com/20251023221814.png)
+
+## Related links
+
+- [UI Layout](./ui-layout/index.md) — Learn about desktop and mobile layouts

package/dist/ai/docs/nocobase/interface-builder/ui-layout/desktop.md

@@ -0,0 +1,97 @@
+---
+title: "Desktop Layout"
+description: "Learn about the navigation structure, page building, route management, and narrow-screen responsive behavior of the NocoBase desktop layout."
+keywords: "desktop layout,UI layout,narrow-screen responsive,page building,route management,UI Editor,NocoBase"
+---
+
+# Desktop Layout
+
+In NocoBase, the **desktop layout** is the default application interface. It is designed for data management, form entry, business configuration, and everyday work on a computer, and can also be used on mobile devices.
+
+The desktop layout is available at `/admin` by default. If the application has its own access prefix, the actual URL automatically includes that prefix.
+
+![20260715224020](https://static-docs.nocobase.com/20260715224020.png)
+
+![20260715224603](https://static-docs.nocobase.com/20260715224603.png)
+
+## Build a page
+
+### Step 1: Open the desktop layout
+
+Visit `/admin` to open the desktop layout. After signing in, the application usually opens this layout directly.
+
+![20260715225049](https://static-docs.nocobase.com/20260715225049.png)
+
+### Step 2: Open UI Editor
+
+Click 「UI Editor」 in the upper-right corner of the page to enter UI building mode. Configuration entries then appear around menus, pages, blocks, fields, and actions.
+
+![20260715225155_rec_](https://static-docs.nocobase.com/20260715225155_rec_.gif)
+
+### Step 3: Create menus and pages
+
+You can add groups, pages, or links in the navigation area, and enable tabs for a page. After creating a page, open it and add the blocks you need.
+
+Page content is built in the same way as other interfaces: add [blocks](../blocks/index.md) first, then configure [fields](../fields/index.md) and [actions](../actions/index.md) for your business needs.
+
+![20260715225316_rec_](https://static-docs.nocobase.com/20260715225316_rec_.gif)
+
+### Step 4: Configure page content
+
+Add table, form, details, filter, or other blocks to the page, then adjust the fields, actions, and arrangement of the blocks. Each change is reflected directly on the current page.
+
+![20260715225424_rec_](https://static-docs.nocobase.com/20260715225424_rec_.gif)
+
+## Manage routes and menus
+
+When you add a page or link in the navigation area, it also appears in the [Route Manager](../../routes/index.md). Changes made in the Route Manager also update the menu.
+
+The desktop layout supports these common route types:
+
+- **Group** — Organizes multiple pages and links under the same navigation group.
+- **Page** — Opens a page where you can continue adding blocks.
+- **Link** — Opens an internal or external URL.
+- **Tab** — Organizes multiple content tabs within a page.
+
+In the Route Manager, you can add, edit, delete, show, or hide routes. It is often the more convenient place to reorganize the entire menu structure.
+
+![20260715225711_rec_](https://static-docs.nocobase.com/20260715225711_rec_.gif)
+
+## Responsive behavior on narrow screens
+
+The desktop layout can be used directly on a phone or in a narrow browser window. In narrow-screen mode, it still uses the same desktop routes and pages. It does not automatically switch to the mobile layout.
+
+### Layout changes
+
+The navigation menu collapses, and top actions move into a more compact entry. Page margins and spacing between blocks also shrink, while the content area adapts to the visible height of the mobile browser.
+
+UI Editor is not available on narrow screens. To change menus or pages, you need to return to a desktop browser and make the changes there.
+
+![20260715224603](https://static-docs.nocobase.com/20260715224603.png)
+
+### How page content adapts
+
+Common components also adjust their interactions for narrow screens, making them easier to use on a phone. For instance, multi-column blocks switch to a single column, tables allow horizontal scrolling for columns that extend beyond the screen, and pagination and action entries become more compact. Selection, date and time, filter, and subpage interactions also use forms that are easier to operate on a phone.
+
+:::tip Desktop responsiveness and the mobile layout
+
+If you only access the application from a phone occasionally, the responsive desktop layout is usually enough. If you need separate bottom navigation, mobile pages, and mobile workflows, build a [mobile layout](./mobile.md) as well.
+
+:::
+
+## Recommendations
+
+- Use the desktop layout by default for work performed mainly on a computer.
+- Finish building the page on a wide screen, then narrow the window to check its responsive behavior.
+- If a page contains many table columns or horizontal actions, keep only the necessary content to reduce the workload on smaller screens.
+- If the desktop and mobile workflows differ significantly, separate pages are usually clearer.
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Mobile layout](./mobile.md) — Build separate mobile navigation and pages
+- [Blocks](../blocks/index.md) — Add and configure blocks on a page
+- [Fields](../fields/index.md) — Configure fields in tables, forms, and details blocks
+- [Actions](../actions/index.md) — Configure actions on pages and blocks
+- [Route Manager](../../routes/index.md) — Manage desktop menus and routes in one place
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which desktop routes each role can access

package/dist/ai/docs/nocobase/interface-builder/ui-layout/index.md

@@ -0,0 +1,50 @@
+---
+title: "UI Layout"
+description: "An overview of NocoBase UI layouts, including desktop and mobile layout features, use cases, and how their configurations relate."
+keywords: "UI layout,desktop layout,mobile layout,responsive layout,mobile pages,NocoBase"
+---
+
+# UI Layout
+
+NocoBase provides desktop and mobile layouts. Both layouts support UI building, so you can create pages and configure blocks, fields, and actions within them.
+
+The desktop layout is the default choice and works well for everyday administration and data processing on a computer. If you need dedicated navigation and pages for mobile devices, you can build a mobile layout as well.
+
+## Desktop layout
+
+The [desktop layout](./desktop.md) is available at `/admin` by default. It consists of top navigation, side navigation, and a page content area, making it suitable for common business scenarios such as managing tables, entering form data, and viewing records.
+
+The desktop layout also supports responsive behavior on narrow screens. When a page is displayed on a smaller screen, the navigation, spacing, and common components adjust to fit while continuing to use the existing desktop menus and pages.
+
+![20260715224020](https://static-docs.nocobase.com/20260715224020.png)
+
+## Mobile layout
+
+The [mobile layout](./mobile.md) is available at `/mobile` by default. It uses a bottom tab bar for primary navigation and provides separate mobile pages, links, and page tabs.
+
+The mobile layout works well for frequent phone-based tasks such as on-site data entry, mobile approvals, task processing, and data lookup. You can build and preview pages in a desktop browser, then use a QR code to check the result on a physical device.
+
+![20260715230725](https://static-docs.nocobase.com/20260715230725.png)
+
+## Which layout should I use?
+
+Use the desktop layout by default.
+
+| I want to... | Recommended layout |
+| --- | --- |
+| Work mainly on a computer and occasionally access pages from a phone | [Desktop layout](./desktop.md) |
+| Design separate navigation, pages, and workflows for phones | [Mobile layout](./mobile.md) |
+| Provide a complete experience for both computers and mobile devices | Build the desktop and mobile layouts separately |
+
+## How the configurations relate
+
+The desktop and mobile layouts use the same data sources and business data. You can use the same data table to build separate pages for different devices.
+
+Menus, routes, and page configurations are maintained separately. Changes to a desktop page do not automatically update its mobile counterpart, and changes to mobile navigation do not affect desktop navigation. [Route access permissions](../../users-permissions/acl/permissions.md) also need to be configured separately for each layout.
+
+## Related links
+
+- [Desktop layout](./desktop.md) — Build desktop pages and learn how they behave on narrow screens
+- [Mobile layout](./mobile.md) — Build separate mobile navigation and pages
+- [Route Manager](../../routes/index.md) — Manage desktop and mobile pages, links, and menus
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which menus and pages each role can access

package/dist/ai/docs/nocobase/interface-builder/ui-layout/mobile.md

@@ -0,0 +1,133 @@
+---
+title: "Mobile Layout"
+description: "Learn about NocoBase mobile navigation, page building, desktop preview, subpage interactions, routes, and permissions."
+keywords: "mobile layout,mobile pages,bottom navigation,mobile preview,mobile routes,UI Editor,NocoBase"
+---
+
+# Mobile Layout
+
+In NocoBase, the **mobile layout** is used to build dedicated navigation and pages for mobile devices. It is available at `/mobile` by default and uses a bottom tab bar as its primary navigation, making it more suitable for data entry, lookup, approval, and task processing on a phone.
+
+The mobile and desktop layouts use the same data sources and business data, but their menus, routes, and page content are configured separately. This lets you reorganize pages around mobile workflows without being constrained by the desktop page structure.
+
+<!-- Add a full-page screenshot of the mobile layout on a physical device -->
+
+## Open and preview the mobile layout
+
+By default, you can click 「Mobile」 in Settings to open the layout, or visit `/mobile` directly.
+
+It is best to build pages in a desktop browser. The desktop view provides a mobile preview area and a toolbar at the top:
+
+- 「UI Editor」 turns UI building mode on or off.
+- 「Tablet preview」 checks the display on wider mobile devices.
+- 「Mobile preview」 restores the phone-sized preview area.
+- 「QR code」 opens the current mobile URL on a phone.
+
+![20260715221712](https://static-docs.nocobase.com/20260715221712.png)
+
+After building the pages on a computer, scan the QR code and check them on a physical device. Pay particular attention to navigation, scrolling, form input, pop-up pages, and safe areas.
+
+## Build mobile navigation
+
+The mobile layout uses a bottom tab bar as its primary navigation. Primary navigation currently supports mainly pages and links.
+
+### Add a page
+
+1. Open 「UI Editor」.
+2. Click the add button on the right side of the bottom tab bar.
+3. Select 「Page」.
+4. Enter a page title and select an icon.
+5. Submit the form to open the new page, then continue adding page content.
+
+![20260715221823_rec_](https://static-docs.nocobase.com/20260715221823_rec_.gif)
+
+### Add a link
+
+To open an internal or external URL, select 「Link」 and configure its title, icon, and URL.
+
+A link can open in the current window or a new window, depending on its configuration.
+
+![20260715221950](https://static-docs.nocobase.com/20260715221950.png)
+
+### Arrange navigation
+
+In UI building mode, drag bottom tabs to reorder them. You can also edit a tab's title and icon, configure linkage rules, copy its UID, or delete it.
+
+To view, show, hide, or delete mobile routes in one place, open 「Settings / Routes / Mobile routes」.
+
+![20260715222113_rec_](https://static-docs.nocobase.com/20260715222113_rec_.gif)
+
+## Build a mobile page
+
+Create and open a mobile page before adding blocks to it. The approach to building page content is essentially the same as on desktop: use [blocks](../blocks/index.md), [fields](../fields/index.md), and [actions](../actions/index.md) to organize business content. However, mobile navigation and some component interactions are adjusted for smaller screens.
+
+### Add page content
+
+1. Open the mobile page you want to build.
+2. Make sure 「UI Editor」 is enabled.
+3. Click 「Add block」 on the page.
+4. Select a table, form, details, filter, or another block.
+5. Continue configuring fields, actions, and block settings.
+
+![20260715222230_rec_](https://static-docs.nocobase.com/20260715222230_rec_.gif)
+
+### Use page tabs
+
+A mobile page can also use tabs. If multiple pieces of content belong under the same navigation entry but remain relatively independent, place them in separate tabs.
+
+1. Open the page settings and enable 「Enable page tabs」. You can also edit the page under 「Settings / Routes / Mobile routes」 and select 「Enable page tabs」.
+2. Turn on 「UI Editor」.
+3. Click 「Add tab」 on the right side of the page tab bar.
+4. Add the tab, then configure its name and page content.
+
+If a mobile page contains only a small amount of content, use a single page. You do not need to enable tabs.
+
+![20260715222354_rec_](https://static-docs.nocobase.com/20260715222354_rec_.gif)
+
+### Mobile interactions for common components
+
+Common components adjust their arrangement and interactions for the mobile layout. For instance, multi-column content automatically switches to a single column that is easier to browse vertically; selection and date-time fields use mobile-friendly pickers; and filters, associated record selection, and subpages use interfaces designed for touch interaction.
+
+Tables remain tables on mobile, with horizontal scrolling for columns that extend beyond the screen. Any additional mobile behavior depends on the support provided by each block.
+
+## Pages and subpages
+
+Content opened from view, edit, associated record selection, and similar actions appears as a mobile subpage. The subpage provides a back button that returns you to the previous page.
+
+When you open a deeper subpage, the bottom tab bar is hidden to leave more room for the current content. It reappears when you close the subpage or return to the previous level.
+
+When switching between bottom tabs, the state of open pages is preserved, making it easier to move between mobile tasks.
+
+![20260715222828_rec_](https://static-docs.nocobase.com/20260715222828_rec_.gif)
+
+## Manage routes and permissions
+
+Mobile routes can be maintained in the [Route Manager](../../routes/index.md). Open 「Settings / Routes / Mobile routes」 to add, edit, delete, show, or hide pages and links, or to configure tabs for a page.
+
+Mobile route access permissions are configured separately from desktop permissions. Under role permissions, open 「Mobile routes」 and select the pages the current role can access. See [Permission configuration](../../users-permissions/acl/permissions.md) for details.
+
+![20260715223016_rec_](https://static-docs.nocobase.com/20260715223016_rec_.gif)
+
+![20260715223106_rec_](https://static-docs.nocobase.com/20260715223106_rec_.gif)
+
+## Relationship with the desktop layout
+
+You can build separate desktop and mobile pages from the same data table. For instance, a desktop page may use a table with many fields for data processing, while a mobile page may use a simpler list or form for on-site data entry.
+
+The two layouts do not synchronize pages automatically. Changes to desktop pages, menus, or routes do not update the mobile configuration, and mobile changes do not affect desktop pages.
+
+:::tip Recommendation
+
+If mobile users only need occasional access to desktop pages, try the responsive [desktop layout](./desktop.md) first. Build a separate mobile layout only when you need dedicated navigation and page workflows for mobile devices.
+
+:::
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Desktop layout](./desktop.md) — Use the default desktop layout and its narrow-screen responsiveness
+- [Blocks](../blocks/index.md) — Add business content to mobile pages
+- [Fields](../fields/index.md) — Configure mobile forms and data display fields
+- [Actions](../actions/index.md) — Configure actions on mobile pages
+- [Route Manager](../../routes/index.md) — Manage mobile pages, links, and tabs
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which mobile routes each role can access

package/dist/ai/docs/nocobase/nocobase-cli/production/index.md

@@ -69,6 +69,16 @@ If you happen to be stuck here "Why do you need `nb app autostart`", just contin
 - If you are going to connect to the reverse proxy, `appPort` has been saved in env
 - If you are ready to officially open it to the outside world, you have already planned the domain name, entrance port and HTTPS solution.
 
+:::warning Note
+
+Use a different `hostname`, such as a separate subdomain, for each independent NocoBase service. Do not distinguish services only by port. Browser cookies are not isolated by port, so services under the same `hostname` may overwrite login state and affect [stable URL](../../file-manager/stable-url.md) authorization.
+
+Sub-apps within the same NocoBase deployment are distinguished by app name and do not need separate hostnames. However, if another independent NocoBase service runs on a different port under the same `hostname` and contains a main app or sub-app with the same name, its cookies may still conflict.
+
+For example, use `app1.example.com` and `app2.example.com` instead of `example.com:13000` and `example.com:14000`.
+
+:::
+
 If you have not completed the CLI installation or env initialization, go back to [Install using CLI](../installation/cli.md).
 
 If the command prompts that env is missing `appPort`, first execute [`nb env update`](../../api/cli/env/update.md) to fill it in.

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

@@ -124,7 +124,7 @@ If you want to make up for Caddy site-level configuration, such as additional he
 
 If your application is not CLI hosted, or you explicitly want to maintain the complete Caddy configuration yourself, you can also write it by hand.
 
-However, for NocoBase, the production environment entry is usually not just a simple `reverse_proxy`. In addition to forwarding API requests to the backend application, a complete and working Caddy configuration usually also needs to handle the upload directory, front-end static resources, `.well-known` routing, WebSocket, and SPA fallback page.
+However, for NocoBase, the production environment entry is usually not just a simple `reverse_proxy`. In addition to forwarding API requests to the backend application, a complete and working Caddy configuration usually also needs to handle the upload directory, front-end static resources, the `/files/` file access route, `.well-known` routing, WebSocket, and SPA fallback pages.
 
 Taking `test2` as an example, key directories related to Caddy usually include:
 
@@ -139,6 +139,7 @@ In other words, handwritten configuration usually needs to cover at least the fo
 - `dist`: Expose the front-end build product directory
 - `oauth well-known`: Handle OAuth discovery paths
 - `openid well-known`: Handle OpenID discovery paths
+- `files`: Forward file access requests under `/files/` to the backend application
 - `api`: forward `/api/` request to the backend application
 - `ws`: forward WebSocket requests to the backend application
 - `spa v2`: Provides front-end entry and return page for `/v/`
@@ -187,6 +188,10 @@ c.local.nocobase.com {
         reverse_proxy host.docker.internal:56575
     }
 
+    handle /files/* {
+        reverse_proxy host.docker.internal:56575
+    }
+
     handle /api/* {
         reverse_proxy host.docker.internal:56575
     }
@@ -249,7 +254,15 @@ A more prudent approach is usually:
 2. Confirm the routing structure and actual path based on the generated results.
 3. Then make manual adjustments according to your domain name, running mode and mounting path.
 
-This is usually less likely to miss details related to WebSockets, static resources, upload directories, `.well-known` routes, or SPA fallback pages than handwriting a configuration from scratch.
+This is usually less likely to miss details related to `/files/`, WebSockets, static resources, upload directories, `.well-known` routes, or SPA fallback pages than handwriting a configuration from scratch.
+
+:::warning Note
+
+`/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.
+
+:::
 
 ## Check and reload configuration
 

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

@@ -9,7 +9,7 @@ keywords: "NocoBase,nb proxy nginx,nb proxy caddy, reverse proxy, Nginx, Caddy,
 
 This article only applies to applications installed using `nb init`.
 
-In NocoBase, the production environment reverse proxy does more than simply forward requests to the application process. Often the details of WebSockets, subpaths, front-end static resources, upload directories, and SPA fallback pages are also handled at the same time.
+In NocoBase, the production environment reverse proxy does more than simply forward requests to the application process. It also needs to handle WebSockets, subpaths, front-end static resources, upload directories, the `/files/` file access route, and SPA fallback pages.
 
 The function of `nb proxy` is to collect these easily missed details into a stable set of command entries.
 

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

@@ -122,7 +122,7 @@ If you want to add site-level Nginx configuration, such as current limiting, add
 
 If your application is not CLI hosted, or you explicitly want to maintain the complete Nginx configuration yourself, you can also write it by hand.
 
-However, for NocoBase, the production reverse proxy is usually more than a simple `proxy_pass`. In addition to forwarding API requests to the backend application, a complete and usable configuration usually needs to handle the upload directory, front-end static resources, WebSocket, `.well-known` route, and SPA fallback page.
+However, for NocoBase, the production reverse proxy is usually more than a simple `proxy_pass`. In addition to forwarding API requests to the backend application, a complete and usable configuration usually needs to handle the upload directory, front-end static resources, the `/files/` file access route, WebSocket, the `.well-known` route, and SPA fallback pages.
 
 Taking `test2` as an example, key files and directories related to Nginx usually include:
 
@@ -138,6 +138,7 @@ In other words, handwritten configuration usually needs to cover at least the fo
 - `uploads`: Expose the upload directory through `alias`
 - `dist`: Expose the front-end build product directory through `alias`
 - `well-known`: Handle OAuth / OpenID related discovery paths
+- `files`: Forward file access requests under `/files/` to the backend application
 - `api`: forward `/api/` request to the backend application
 - `ws`: forward WebSocket requests to the backend application
 - `spa`: Provides front-end entry and `try_files` fallback for `/` and `/v/`
@@ -180,6 +181,11 @@ server {
         include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
     }
 
+    location ^~ /files/ {
+        proxy_pass http://127.0.0.1:56575;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
+    }
+
     location ^~ /api/ {
         proxy_pass http://127.0.0.1:56575;
         include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
@@ -229,7 +235,15 @@ A more prudent approach is usually:
 2. Confirm the routing structure and actual path based on the generated results.
 3. Then make manual adjustments according to your domain name, running mode and mounting path.
 
-This is usually less likely to miss details related to WebSockets, static resources, upload directories, or SPA fallback pages than handwriting a configuration from scratch.
+This is usually less likely to miss details related to `/files/`, WebSockets, static resources, upload directories, or SPA fallback pages than handwriting a configuration from scratch.
+
+:::warning Note
+
+`/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 `location /` 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.
+
+:::
 
 ## How to handle HTTPS
 

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