@nocobase/plugin-ai 2.2.0-beta.5 → 2.2.0-beta.6

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/settings.md

@@ -0,0 +1,77 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Settings"
+description: "Modify basic information, vector store, and default segmentation settings on the Settings page of a knowledge base, and understand the relation between knowledge-base-level and document-level segmentation settings."
+keywords: "knowledge base settings,segmentation settings,Chunk size,Chunk overlap,vector store,NocoBase"
+---
+
+# Settings
+
+## Open the Settings page
+
+After opening the knowledge base detail page, click Settings in the left sidebar. This page modifies basic information, file storage, vector store, and default segmentation settings of the current knowledge base.
+
+![](https://static-docs.nocobase.com/20260617005832.png)
+
+## Basic information
+
+Local knowledge base settings include:
+
+| Setting | Description |
+| --- | --- |
+| Key | Unique identifier of the knowledge base. It cannot be changed after creation |
+| Name | Knowledge base name |
+| File storage | Where documents and segment files are stored. It cannot be changed after creation |
+| Vector store | Vector store used by the current knowledge base |
+| Description | Knowledge base description |
+| Enabled | Whether the current knowledge base is enabled |
+
+:::tip Vector store changes
+
+After you modify Vector store, NocoBase asks for confirmation when saving. After the vector store changes, existing documents must be vectorized again before vector data can be written to the new vector store. Choose Save and vectorize to save the settings and vectorize immediately, or choose Save only to save the settings and later run Vectorization manually on the Documents page.
+
+:::
+
+![](https://static-docs.nocobase.com/20260617005951.png)
+
+## Default segmentation parameters
+
+The Settings page includes three segmentation parameters:
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| Split document | Enabled | Whether uploaded documents are automatically split into multiple segments |
+| Chunk size | `6000` | Maximum character count of each segment |
+| Chunk overlap | `1200` | Overlapping character count between adjacent segments |
+
+Chunk overlap cannot be greater than or equal to Chunk size. If the value is invalid, the backend normalizes it to keep overlap smaller than a single segment.
+
+## Relation to document-level segment settings
+
+These settings are knowledge-base-level defaults. They mainly affect documents uploaded or regenerated later.
+
+After a document enters the knowledge base, it keeps its own segmentation parameters. On the Documents page, click Segments for a document, then open Segment settings to set Split document, Chunk size, and Chunk overlap for that document and run Resegment.
+
+The relation between the two places is:
+
+- Segmentation parameters in Settings define the default strategy for the knowledge base and are suitable for controlling new documents consistently
+- Segmentation parameters in the Segments dialog only apply to the current document and are suitable for handling a document that is too long, too short, or structurally special
+- Existing generated segments are not automatically rebuilt after knowledge-base-level defaults change
+- To apply new parameters to an existing document, open its Segment settings and run Resegment
+
+:::warning Note
+
+Resegment discards manually edited segment content and related questions in that document. Changing knowledge-base-level defaults does not immediately overwrite existing segments; only document-level Resegment rebuilds segments.
+
+:::
+
+## When to adjust parameters
+
+Default parameters cover most plain text, Markdown, Word, and PDF documents. Adjust them only in these cases:
+
+- Segments are too long and matched results include too much unrelated content: reduce Chunk size
+- Segments are too short and context is incomplete: increase Chunk size
+- Sentence breaks are obvious between adjacent segments: increase Chunk overlap
+- You want the whole document to be one retrieval unit: turn off Split document
+
+After saving settings, newly uploaded documents use the new default parameters.

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/rag.md

@@ -19,7 +19,7 @@ Select the AI employee for which you want to enable RAG, click the `Edit` button
 In the `Knowledge base` tab, turn on the `Enable` switch.
 
 - In `Knowledge Base Prompt`, enter the prompt for referencing the knowledge base. `{knowledgeBaseData}` is a fixed placeholder and should not be modified.
-- In `Knowledge Base`, select the configured knowledge base. See: [Knowledge Base](/ai-employees/knowledge-base/knowledge-base).
+- In `Knowledge Base`, select the configured knowledge base. See: [Knowledge Base](./knowledge-base/).
 - In the `Top K` input box, enter the number of documents to retrieve, the default is 3.
 - In the `Score` input box, enter the document relevance threshold for retrieval.
 

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/knowledge/create-document.md

@@ -0,0 +1,79 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Workflow AI knowledge base node - Create document"
+description: "Use a collection event trigger and the AI knowledge base Create document node to synchronize newly added records to the AI knowledge base."
+keywords: "AI knowledge base,workflow,create document,collection event trigger,NocoBase"
+---
+
+# Create document
+
+<PluginInfo name="ai-knowledge-base"></PluginInfo>
+
+## Introduction
+
+In NocoBase, the **Create document** node writes new documents to an AI knowledge base from a workflow. In this example, it listens for new records in `Answers` and writes the answer body, document name, related questions, and a stable `Key` to the target knowledge base.
+
+AI knowledge base nodes are asynchronous nodes, so the workflow must use asynchronous execution. Prepare the target knowledge base and vector store first. See [Overview](./) for the full scenario.
+
+## Workflow structure
+
+The example workflow listens for new records in `Answers` and synchronizes each answer as one document in the target knowledge base.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-create-editable-overview.png)
+
+Where:
+
+- `Collection event` listens for newly added collection records
+- `Create document` writes record content to the AI knowledge base
+
+## Before you start
+
+The example uses the `Answers` / `Questions` collections and target knowledge base described in [Overview](./). Before configuring the workflow, confirm that:
+
+- A Local knowledge base has been created, with file storage and vector store configured. See [Knowledge base overview](../../../knowledge-base/knowledge-base) and [Vector store](../../../knowledge-base/vector-store)
+- The `Answers.questions` relation field is ready. To review the collection structure, return to [Overview](./)
+- The workflow uses asynchronous execution. See [Workflow](../../../../workflow) for the basics
+
+## Configure the trigger
+
+Create an asynchronous workflow and select `Collection event` as the trigger. In the trigger configuration:
+
+- Set `Collection` to the collection to synchronize, such as `Main / Answers`
+- Set `Trigger on` to `After record added`
+- If the document needs fields from related collections, preload relation fields in `Preload associations`
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-create-trigger-config.png)
+
+The example preloads the `questions` relation field so related questions can be written to `Related questions`.
+
+## Configure the Create document node
+
+Add a `Create document` node after the trigger.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-create-node-config.png)
+
+Key settings:
+
+These settings decide the knowledge base document name, body content, splitting behavior, and whether related questions are included.
+
+| Setting | Example value | Description |
+| --- | --- | --- |
+| `Knowledge base` | Target knowledge base | Select the same Local knowledge base prepared in the overview. The workflow creates a document in its `Documents` list and then enters splitting and vectorization. |
+| `Split document` | `No` | Controls whether the body is split into multiple segments. In this example, one answer is already a complete response. With splitting disabled, the whole document becomes one segment and works better with `Related questions`. |
+| `Related questions` | `Answers.questions.content` | Only takes effect when `Split document` is disabled. It writes common phrasings into `Related questions` for the current segment. It does not rewrite the body, but participates in retrieval. |
+| `Document type` | `Text` | Creates a knowledge base document from a text field. The example uses a collection field as the answer body, so `Text` is selected. Use `Attachment` if your business collection stores files or file URLs. |
+| `Content` | `Answers.Content` | Select the answer body as the knowledge base document body. The `Content` shown in segment management comes from this field. |
+| `Key` | `Answers.ID` | Sets the unique identifier of the knowledge base document. The example uses the `Answers` record ID so update and delete workflows can find the same document by the same `Key`. |
+| `Name` | `Answers.Title` | Sets the document name. The example uses the answer title, making it easier to identify the document in `Documents`, enter segment management, and run hit tests. |
+
+If `Related questions` references relation fields, configure `Preload associations` in the trigger first. Otherwise, the node can only access the current `Answers` record and cannot read the related `questions` data.
+
+:::warning Note
+
+`Key` is used by the later update and delete workflows. The Create, Update, and Delete workflows must use the same Key rule, usually the business collection record ID.
+
+:::
+
+## Next step
+
+The Create document workflow is the starting point of the synchronization chain. Continue with [Update document](./update-document) and [Delete document](./delete-document), then return to the "Verify the synchronization chain" section in [Overview](./) to verify add, update, and delete in order.

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/knowledge/delete-document.md

@@ -0,0 +1,71 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Workflow AI knowledge base node - Delete document"
+description: "Use a collection event trigger and the AI knowledge base Delete document node to delete knowledge base documents after collection records are deleted."
+keywords: "AI knowledge base,workflow,delete document,collection event trigger,NocoBase"
+---
+
+# Delete document
+
+<PluginInfo name="ai-knowledge-base"></PluginInfo>
+
+## Introduction
+
+In NocoBase, the **Delete document** node deletes a specified document from an AI knowledge base. In this example, it listens for deletion events in `Answers` and deletes the corresponding document from the target knowledge base by the same `Key` used by Create document, so removed data is no longer retrieved.
+
+The Delete document node is asynchronous. It depends on the `Key` written when the document was created, so it must use the same target knowledge base and the same `Key` rule as the Create and Update document nodes.
+
+## Workflow structure
+
+The example workflow listens for deletion events in `Answers` and deletes the document with the same `Key` from the target knowledge base.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-delete-editable-overview.png)
+
+Where:
+
+- `Collection event` listens for collection deletion
+- `Delete document` deletes the document from the target knowledge base
+
+## Before you start
+
+The example uses the target knowledge base and `Key` rule from [Create document](./create-document). Before configuring the workflow, confirm that:
+
+- The Create document workflow is enabled and the target knowledge base contains documents with the same `Key`
+- The delete workflow can read this `Key` from trigger data. The example uses the `Answers` record ID
+- If you need to review the full synchronization chain, see the workflow responsibilities in [Overview](./)
+
+## Configure the trigger
+
+Select `Collection event` as the trigger. In the trigger configuration:
+
+- Set `Collection` to the collection to listen to, such as `Main / Answers`
+- Set `Trigger on` to `After record deleted`
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-delete-trigger-config.png)
+
+Deleting a document only needs the document `Key`, so relation fields usually do not need to be preloaded.
+
+## Configure the Delete document node
+
+Add a `Delete document` node after the trigger.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-delete-node-config.png)
+
+Key settings:
+
+The Delete document node only needs to locate the document to delete. It does not need body content, title, or related questions.
+
+| Setting | Example value | Description |
+| --- | --- | --- |
+| `Knowledge base` | Target knowledge base | Select the same knowledge base used by the Create and Update document nodes. |
+| `Key` | `Answers.ID` | Select the exact same field used by the Create document node. The example continues to use the `Answers` record ID so the node deletes the document that corresponds to this answer. |
+
+:::warning Note
+
+The delete node does not look up documents by title or body content. It only locates documents by `Knowledge base` and `Key`. The Create, Update, and Delete workflows must use the same `Key`.
+
+:::
+
+## Next step
+
+After configuring the Delete document node, return to the "Verify the synchronization chain" section in [Overview](./) to verify add, update, and delete in order.

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/knowledge/index.md

@@ -0,0 +1,84 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Workflow AI knowledge base nodes overview"
+description: "Introduces the workflow AI knowledge base node scenario, collection structure, and how Create, Update, and Delete document nodes synchronize knowledge base content."
+keywords: "AI knowledge base,workflow,collection event trigger,knowledge base synchronization,NocoBase"
+---
+
+# Overview
+
+<PluginInfo name="ai-knowledge-base"></PluginInfo>
+
+## Introduction
+
+AI knowledge base nodes allow workflows to manage knowledge base documents directly. When business data changes, you can synchronize added, updated, and deleted records to the knowledge base, keeping knowledge base content aligned with your business collections.
+
+This documentation uses a Q&A scenario as an example: administrators maintain standard answers and common phrasings for each answer. Workflows synchronize the answer body and related questions to the same target knowledge base, so AI employees or other processes can later use those knowledge base documents.
+
+## Example scenario
+
+The example uses two business collections:
+
+- `Answers`: stores answer content that can be synchronized to the knowledge base
+- `Questions`: stores common phrasings related to each answer
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-overview-collections.png)
+
+`Answers` is the source collection for knowledge base documents. When an answer is added, a document is created. When an answer is changed, the document is updated. When an answer is deleted, the document is removed.
+
+`Questions` is not an independent source of knowledge base documents. It is attached to answers through the `Answers.questions` relation field and supplements the different phrasings that can point to the same answer.
+
+Before synchronization, prepare a Local knowledge base. You can name it according to your environment. The Create, Update, and Delete workflows only need to select the same knowledge base.
+
+## Answers collection structure
+
+`Answers` mainly uses three fields:
+
+- `Title`: used as the knowledge base document name
+- `Content`: used as the knowledge base document body
+- `questions`: relation to the `Questions` collection for related questions
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-overview-answers-fields.png)
+
+`questions` is a one-to-many relation field. Its source collection is `Answers`, target collection is `Questions`, both source key and target key use `ID`, and the foreign key is stored in `Questions`.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-overview-answers-questions-relation.png)
+
+This relation field is preloaded when creating and updating documents. It writes related questions into `Related questions`, so one answer can be retrieved not only by body text but also by common phrasings.
+
+:::tip
+
+If your knowledge base documents do not need related questions, you do not need a relation field like `questions`. A stable `Key` field and body content are enough for create, update, and delete synchronization.
+
+:::
+
+## Workflow responsibilities
+
+The core of this example is three synchronization workflows. They process the same `Answers` data and write to the same target knowledge base:
+
+| Scenario | Trigger | Node | Purpose |
+| --- | --- | --- | --- |
+| Add answer | `Answers` collection `After record added` | `Create document` | Write the new answer to the AI knowledge base |
+| Update answer | `Answers` collection `After record updated` | `Update document` | Update the document by the same `Key` |
+| Delete answer | `Answers` collection `After record deleted` | `Delete document` | Delete the document by the same `Key` |
+
+`Key` is the most important field in the synchronization chain. Create, update, and delete workflows must use the same `Key` rule. The example directly uses the record ID of the `Answers` collection.
+
+## Operation guides
+
+- [Create document](./create-document)
+- [Update document](./update-document)
+- [Delete document](./delete-document)
+- [Retrieve document](./retrieve-document)
+
+## Verify the synchronization chain
+
+After configuring the Create, Update, and Delete workflows, use the same `Answers` record to verify the full synchronization chain.
+
+After adding an answer, check in this order:
+
+1. Go to `Documents` in the target knowledge base, confirm that the new document appears, and check that `Status` is `Success`. See [knowledge base document management](../../../knowledge-base/knowledge-base/documents) for details.
+2. Click `Segments` for the document and confirm that `Related questions` includes common phrasings from `Answers.questions`. See [segment management](../../../knowledge-base/knowledge-base/segments) for details.
+3. Go to `Hit tests`, enter a keyword from the answer body or a related question, and confirm that the synchronized answer can be hit. See [hit tests](../../../knowledge-base/knowledge-base/hit-tests) for details.
+
+After the add synchronization is correct, update the same `Answers` record and confirm that the target knowledge base document changes. Finally, delete the record and confirm that the corresponding document is removed from the target knowledge base.

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/knowledge/retrieve-document.md

@@ -0,0 +1,87 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Workflow AI knowledge base node - Retrieve document"
+description: "Use the AI knowledge base Retrieve document node in a workflow to retrieve snippets and provide them as task context for an AI employee node."
+keywords: "AI knowledge base,workflow,retrieve document,AI employee,RAG,NocoBase"
+---
+
+# Retrieve document
+
+<PluginInfo name="ai-knowledge-base"></PluginInfo>
+
+## Introduction
+
+In NocoBase, the **Retrieve document** node searches an AI knowledge base in a workflow and returns matched document snippets. It is suitable before an AI employee node: retrieve knowledge base snippets with task input first, then pass the results to the AI employee as task context.
+
+The Retrieve document node is asynchronous. Before using it, configure the knowledge base and make sure it already contains vectorized documents.
+
+## Workflow structure
+
+The example workflow listens for new records in `Questions`, sends matching text to `Retrieve document`, and passes the retrieval result to a downstream `AI employee` node for task processing.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-retrieve-overview.png)
+
+Where:
+
+- `Collection event` receives task input
+- `Retrieve document` retrieves snippets from the knowledge base
+- `AI employee` processes the task based on snippets
+
+In real business workflows, the result generated by the AI employee usually needs to be saved. You can continue with database operation nodes after it. This guide omits those later saving steps to focus on the Retrieve document node.
+
+## Before you start
+
+This example is an independent retrieval workflow. Before configuring it, confirm that:
+
+- The knowledge base already contains vectorized documents. For document maintenance, see [Knowledge base overview](../../../knowledge-base/knowledge-base) and [Create document](./create-document)
+- A data source for matching text is ready. The example uses the `Questions` collection
+- A usable downstream AI employee node is ready. See [AI employee node](../employee/configuration)
+
+## Configure the trigger
+
+Select `Collection event` as the trigger. In the trigger configuration:
+
+- Set `Collection` to the matching-text source collection, such as `Main / Questions`
+- Set `Trigger on` to `After record added`
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-retrieve-trigger-config.png)
+
+Each time an input record is added, the workflow automatically enters retrieval and task processing.
+
+## Configure the Retrieve document node
+
+Add a `Retrieve document` node after the trigger. It is recommended to change the node key to an easy-to-reference name, such as `retrieve_docs`.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-retrieve-node-config.png)
+
+Key settings:
+
+- Select one or more knowledge bases in `Knowledge base`
+- Set `Input matching text` to the matching text field
+- Set `Top K` to the maximum number of snippets to return
+- Set `Score` to the minimum similarity threshold
+
+After execution, the node returns an array of document snippets. Each result contains `id`, `content`, `score`, and `metadata`, sorted by `score` from high to low.
+
+## Pass the result to the AI employee node
+
+In the `AI employee` node, write the retrieval result into the prompt. The example directly references the Retrieve document node output:
+
+```text
+Task input: {{$context.data.f_b2izf5j4xx0}}
+
+Knowledge base snippets:
+{{$jobsMapByNodeKey.retrieve_docs}}
+
+Use the snippets as context to complete the task. If the snippets are not enough, explain what information is missing.
+```
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-retrieve-ai-employee-config.png)
+
+`retrieve_docs` is the key of the retrieval node. If your node key is different, replace it with the actual key.
+
+:::tip
+
+If you only want to pass snippet text, reference the `content` field in the retrieval result through the variable selector. Passing the whole result array also includes `score` and `metadata`, which helps the AI judge source and relevance.
+
+:::

package/dist/ai/docs/nocobase/ai-employees/workflow/nodes/knowledge/update-document.md

@@ -0,0 +1,70 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Workflow AI knowledge base node - Update document"
+description: "Use a collection event trigger and the AI knowledge base Update document node to synchronize collection updates to the AI knowledge base."
+keywords: "AI knowledge base,workflow,update document,collection event trigger,NocoBase"
+---
+
+# Update document
+
+<PluginInfo name="ai-knowledge-base"></PluginInfo>
+
+## Introduction
+
+In NocoBase, the **Update document** node updates existing documents in an AI knowledge base from a workflow. In this example, it listens for updated records in `Answers`, finds the document in the target knowledge base by the same `Key` used by Create document, and rewrites it with the latest fields.
+
+The Update document node is asynchronous. It is not used as an independent entry point. It should follow the Create document workflow and use the same target knowledge base and the same `Key` rule as Create and Delete document nodes.
+
+## Workflow structure
+
+The example workflow listens for updated records in `Answers` and synchronizes the latest answer content to the same document in the target knowledge base.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-update-editable-overview.png)
+
+Where:
+
+- `Collection event` listens for collection updates
+- `Update document` updates the document with the same `Key` in the target knowledge base
+
+## Before you start
+
+The example uses the target knowledge base and `Key` rule from [Create document](./create-document). Before configuring the workflow, confirm that:
+
+- The Create document workflow is enabled and has created at least one knowledge base document
+- `Key` uses a stable and unique business field. The example uses the `Answers` record ID
+- If updates should also synchronize related questions, preload the `questions` relation field in the trigger
+
+## Configure the trigger
+
+Select `Collection event` as the trigger. In the trigger configuration:
+
+- Set `Collection` to the collection to listen to, such as `Main / Answers`
+- Set `Trigger on` to `After record updated`
+- Use `Changed fields` to limit which field changes trigger the workflow, such as title or body changes
+- If the node needs relation fields, preload them in `Preload associations`
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-update-trigger-config.png)
+
+If `Changed fields` is not selected, any field change triggers this workflow.
+
+## Configure the Update document node
+
+Add an `Update document` node after the trigger.
+
+![](https://static-docs.nocobase.com/ai-employees/workflow/knowledge/2026-06-12/kb-update-node-config.png)
+
+Key settings:
+
+Most Update document settings are the same as [Create document](./create-document). Usually, continue using the same target knowledge base, splitting behavior, body field, and title field. If related questions also need to be synchronized, continue using `Answers.questions.content`.
+
+The important difference is `Key`: in the Update document node, `Key` is required and must be exactly the same as in the Create document node. The example continues to use `Answers.ID`, so the node can find and overwrite the same knowledge base document.
+
+:::warning Note
+
+If no document is found for the specified `Key`, the update fails. Before configuring this workflow, make sure the Create document workflow has already created documents with the same `Key`.
+
+:::
+
+## Next step
+
+After configuring the Update document node, continue with [Delete document](./delete-document). After all three workflows are configured, return to the "Verify the synchronization chain" section in [Overview](./) to verify add, update, and delete in order.

package/dist/ai/docs/nocobase/api/cli/app/restart.md

@@ -35,6 +35,10 @@ If you explicitly pass `--env` and it differs from the current env, the CLI asks
 
 By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting again, and Docker envs complete that step before recreating the container. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
 
+## Hook Scripts
+
+If the current env saved a hook with `nb init --hook-script`, `nb app restart` runs `afterAppStart(context)` once after the app restarts and passes `__health_check`. It uses `context.phase = 'app-start'` and `context.command = 'app:restart'`.
+
 ## Related Commands
 
 - [`nb app start`](./start.md)

package/dist/ai/docs/nocobase/api/cli/app/start.md

@@ -34,6 +34,13 @@ nb app start --env local-docker
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
 By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting, and Docker envs recreate the app container from saved env config. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
+
+## Hook Scripts
+
+If the current env saved a hook with `nb init --hook-script`, `nb app start` runs `afterAppStart(context)` after the app actually starts and passes `__health_check`. Installed envs use `context.phase = 'app-start'` and `context.command = 'app:start'`. If the app is already running, this command does not run the hook.
+
+For prepared envs created with `--prepare-only`, the first `nb app start` runs `beforeAppInstall(context)`, completes the first install and startup, then runs `afterAppStart(context)`. Both hooks receive `context.phase = 'init'` and `context.command = 'app:start'`.
+
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

package/dist/ai/docs/nocobase/api/cli/app/upgrade.md

@@ -58,6 +58,12 @@ Step 4 automatically completes any required upgrade preparation for the current
 
 If the final `nb env update` step fails, the upgrade still counts as successful. The CLI prints a warning and tells you to run `nb env update <envName>` manually afterward.
 
+## Hook Scripts
+
+If the current env saved a hook with `nb init --hook-script`, `nb app upgrade` passes the upgrade lifecycle to the hook. For npm/Git source, source refresh runs `beforeDependencyInstall(context)` before dependency installation with `context.phase = 'upgrade'` and `context.command = 'app:upgrade'`.
+
+The app upgrade startup step then runs `beforeAppInstall(context)`, and after the app starts and passes `__health_check`, it runs `afterAppStart(context)`. Both hooks also use `context.phase = 'upgrade'` and `context.command = 'app:upgrade'`. Docker source does not run `beforeDependencyInstall`, but it does run the app-level hooks.
+
 ## Related Commands
 
 - [`nb source download`](../source/download.md)

package/dist/ai/docs/nocobase/api/cli/init.md

@@ -42,7 +42,7 @@ nb init --env app1 --resume
 
 `--prepare-only` is intended for flows where the env should be prepared first, then the license is activated, and only after that the app is installed and started.
 
-If you want to save the env config, prepare the source files or image, and get the database ready first, but delay the actual app installation and first startup, you can use:
+If you want to save the env config and prepare the database first, while delaying dependency download, app installation, and first startup, you can use:
 
 ```bash
 nb init --env app1 --prepare-only
@@ -67,6 +67,7 @@ By default, the CLI organizes local files under `app-path` using the following c
 
 ```text
 <app-path>/
+├── .nb/      # CLI metadata for this env, such as hooks.mjs
 ├── source/   # Default directory for app source code or downloaded content
 ├── storage/  # Runtime data directory
 └── .env      # Optional app environment variable file
@@ -74,6 +75,7 @@ By default, the CLI organizes local files under `app-path` using the following c
 
 Typically:
 
+- `.nb/` stores CLI-managed metadata. A script passed with `--hook-script` is copied to `<app-path>/.nb/hooks.mjs`, so later `nb app upgrade` and local source restore can reuse it
 - `source/` mainly corresponds to the local app directory for npm / Git envs. For Docker envs, the CLI also keeps this default path derivation, but most of the time you do not need to care about it manually. Pay special attention during upgrades: the `source/` directory will be deleted and downloaded again, so do not put files you need to keep here
 - `storage/` is used for runtime data, such as built-in database data, plugins, logs, and more
 - `.env` is an optional app environment variable file. You only need to add it in `<app-path>/.env` when you want to customize environment variables; if this file exists, Docker, npm, and Git install sources will all read it by default
@@ -101,7 +103,7 @@ If you are following the local UI wizard step by step, you can first use the tab
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Getting started`         | `--env`、`--yes`、`--ui`、`--locale`、`--verbose`、`--skip-skills`、`--resume`                                                                                                                                    |
 | `App environment`         | `--lang`、`--app-path`、`--app-port`、`--force`                                                                                                                                                                   |
-| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts` |
+| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts`、`--hook-script` |
 | `Configure the database`  | `--builtin-db`、`--db-dialect`、`--builtin-db-image`、`--db-host`、`--db-port`、`--db-database`、`--db-user`、`--db-password`、`--db-schema`、`--db-table-prefix`、`--db-underscored`                             |
 | `Create an admin account` | `--root-username`、`--root-email`、`--root-password`、`--root-nickname`                                                                                                                                           |
 | `Remote connection`       | `--api-base-url`、`--auth-type`、`--access-token`、`--username`、`--password`、`--skip-auth`                                                                                                                      |
@@ -184,6 +186,7 @@ The “Default” below means the value or behavior that `nb init` usually uses
 | `--npm-registry`                                     | string  | Empty                                                                                            | Registry used for npm/Git download and dependency installation                           |
 | `--build` / `--no-build`                             | boolean | `true`                                                                                           | Whether to build after installing npm/Git dependencies                                   |
 | `--build-dts`                                        | boolean | `false`                                                                                          | Whether to generate TypeScript declaration files during npm/Git builds                   |
+| `--hook-script`                                      | string  | None                                                                                             | Copy the specified hook module to `<app-path>/.nb/hooks.mjs` and save it in the env config; supports the `beforeDependencyInstall`, `beforeAppInstall`, and `afterAppStart` lifecycle hooks |
 
 ## Examples
 
@@ -233,6 +236,40 @@ nb init --env app1 --yes --source git --version latest \
   --git-url https://gitee.com/nocobase/nocobase.git
 ```
 
+### Extend the install flow with a hook script
+
+If you need to prepare extra content during installation, pass a local ESM module with `--hook-script`:
+
+```bash
+nb init --env app1 --yes --source git --hook-script ./hooks.mjs
+```
+
+The CLI copies this file to `<app-path>/.nb/hooks.mjs` and saves `hookScript: ".nb/hooks.mjs"` in the env config. Later `nb app start`, `nb app restart`, and `nb app upgrade` reuse it from that location.
+
+The hook file must default-export an object. Implement only the methods you need:
+
+```js
+export default {
+  beforeDependencyInstall: async (context) => {
+    // Runs after git clone / npm scaffold and before yarn install.
+  },
+  beforeAppInstall: async (context) => {
+    // Runs before the app-level install or upgrade command.
+  },
+  afterAppStart: async (context) => {
+    // Runs after the app actually starts and passes the health check.
+  },
+};
+```
+
+- `beforeDependencyInstall` only applies to npm/Git source and runs right before the real `yarn install`; Docker source does not run it
+- `beforeAppInstall` runs before app-level install or upgrade commands, and applies to npm/Git/Docker source
+- `afterAppStart` runs after the app actually starts and passes `__health_check`; `nb app start`, `nb app restart`, and `nb app upgrade` may all trigger it
+
+`--prepare-only` only saves the env config and copies the hook file. It does not execute hooks. When you later run `nb app start` for the first time, the CLI runs the first-install hooks with `context.phase` set to `init` and `context.command` set to `app:start`.
+
+`context` includes lifecycle information such as `phase`, `command`, `source`, `version`, `appPath`, `sourcePath`, `storagePath`, `hookScript`, and `envConfig`. If a hook throws, the current CLI command fails. Because `afterAppStart` can run repeatedly during start, restart, and upgrade flows, keep it idempotent.
+
 ### Quick install and use basic authentication
 
 If you want to quickly install a local app in non-interactive mode and directly save `basic` authentication after installation, you can also write it like this. This way, you do not need to open a browser to complete OAuth.

package/dist/ai/docs/nocobase/api/cli/source/download.md

@@ -33,6 +33,7 @@ nb source download [flags]
 | `--npm-registry` | string | Registry used for npm/Git downloads and dependency installation |
 | `--build` / `--no-build` | boolean | Whether to build after npm/Git dependency installation |
 | `--build-dts` | boolean | Whether to generate TypeScript declaration files during npm/Git build |
+| `--hook-script` | string | Hook module to run after npm scaffold or Git clone and before dependency installation; only applies to npm/Git source |
 
 ## Examples
 
@@ -47,8 +48,26 @@ nb source download --source git --version alpha --git-url=git@github.com:nocobas
 nb source download --source git --version fix/cli-v2
 nb source download -y --source npm --version alpha --build-dts
 nb source download -y --source npm --version alpha --npm-registry=https://registry.npmmirror.com
+nb source download -y --source git --version beta --hook-script ./hooks.mjs
 ```
 
+## Pre-install hook
+
+`--hook-script` only affects the current `nb source download` run. If you want the hook to be saved with the env and reused by `nb app upgrade` or local source restore, pass it through [`nb init --hook-script`](../init.md) instead.
+
+The hook file must default-export an object with `beforeDependencyInstall(context)`:
+
+```js
+export default {
+  beforeDependencyInstall: async ({ sourcePath, version, envConfig }) => {
+    // Runs after git clone / npm scaffold and before yarn install.
+  },
+};
+```
+
+When you run `nb source download --hook-script` directly, `beforeDependencyInstall` receives `context.phase` as `source-download` and `context.command` as `source:download`. This command does not run `beforeAppInstall` or `afterAppStart`; those hooks belong to app install, start, restart, and upgrade flows.
+
+
 ## Version Aliases
 
 With Git source, common dist-tags are resolved to branches: `latest` -> `main`, `beta` -> `next`, `alpha` -> `develop`.