@nocobase/plugin-ai 3.0.0-alpha.3 → 3.0.0-alpha.4

package/dist/ai/docs/nocobase/ai-employees/dev/ai-employee/frontend-tool-ui.md

@@ -0,0 +1,296 @@
+---
+title: "Add Frontend Interaction to a Tool"
+description: "Explains frontend interaction for NocoBase AI employee Tools, including cards, modals, decisions.edit, and frontend execution."
+keywords: "NocoBase,Tool frontend card,ToolsUIProperties,decisions.edit,SuggestionsOptionsCard,frontend Tool"
+---
+
+# Add Frontend Interaction to a Tool
+
+Some Tools only need to run on the server and require no custom interface. Other Tools need the user to confirm, select, or edit arguments. In those cases, register a frontend card for the Tool with the same name.
+
+:::tip Distinguish the two concepts
+
+A **frontend card** only handles ToolCall display and human interaction. It does not mean that the Tool's business logic must run in the browser.
+
+If the card only displays options like `suggestions` and continues to the server-side `invoke()` after the user selects one, keep the default `execution: 'backend'`. Set `execution: 'frontend'` and implement a frontend `invoke` only when the Tool's actual logic must access the current browser page, FlowModel, or editor state.
+
+:::
+
+## Define arguments and execution logic on the server first
+
+The built-in `suggestions` Tool is located at:
+
+```text
+packages/plugins/@nocobase/plugin-ai/src/ai/tools/suggestions.ts
+```
+
+Its schema includes both the candidate options and the user's final selection:
+
+```ts
+schema: z.object({
+  option: z.string().describe('user selected option, ignore this param').optional(),
+  options: z.array(z.string()).describe('A list of suggested prompts for the user to choose from.'),
+})
+```
+
+According to the Tool description, the model should generate only `options` on the first call. Because this Tool does not set `defaultPermission: 'ALLOW'`, its default permission is `ASK`, and the ToolCall pauses for user input.
+
+After the user makes a selection, the frontend uses `decisions.edit()` to merge `option` into the original arguments and resume the ToolCall. The server-side `invoke()` then returns the selected content:
+
+```ts
+return {
+  status: 'success',
+  content: args?.option,
+};
+```
+
+The built-in implementation also writes the selection back to `aiMessages.toolCalls`, so rerendered historical messages can still show which option the user selected.
+
+## Write the card component
+
+A frontend card receives `ToolsUIProperties`:
+
+```tsx
+import { useState } from 'react';
+import type { ToolsUIProperties } from '@nocobase/client-v2';
+import { Button, Flex } from 'antd';
+
+interface DeveloperChoiceArgs {
+  options?: string[] | string;
+  option?: string;
+}
+
+const parseOptions = (value: DeveloperChoiceArgs['options']): string[] => {
+  if (Array.isArray(value)) {
+    return value.filter((option): option is string => typeof option === 'string');
+  }
+  if (typeof value !== 'string') {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return Array.isArray(parsed) ? parsed.filter((option): option is string => typeof option === 'string') : [];
+  } catch {
+    return [];
+  }
+};
+
+export const DeveloperChoiceCard = ({
+  toolCall,
+  decisions,
+}: ToolsUIProperties<DeveloperChoiceArgs>) => {
+  const [submitting, setSubmitting] = useState(false);
+  const options = parseOptions(toolCall.args?.options);
+
+  const handleSelect = async (option: string) => {
+    if (submitting) {
+      return;
+    }
+
+    setSubmitting(true);
+    try {
+      await decisions.edit({
+        ...toolCall.args,
+        option,
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Flex gap="small" wrap="wrap">
+      {options.map((option, index) => (
+        <Button
+          key={`${option}-${index}`}
+          disabled={toolCall.invokeStatus !== 'interrupted' || submitting}
+          onClick={() => handleSelect(option)}
+        >
+          {option}
+        </Button>
+      ))}
+    </Flex>
+  );
+};
+```
+
+:::warning Note
+
+This component demonstrates the general use of `decisions.edit()` and handles repeated clicks and JSON-string arguments. In production, you must also account for read-only conversations, the current active message, and historical selection state in the surrounding chat interface. See the complete implementation in `packages/plugins/@nocobase/plugin-ai/src/client-v2/ai-employees/tools/SuggestionsOptionsCard.tsx`.
+
+:::
+
+`decisions` provides three operations:
+
+| Method | Purpose |
+| --- | --- |
+| `approve()` | Continue with the original arguments |
+| `edit(args)` | Modify the arguments and continue |
+| `reject(message?)` | Reject execution and return the reason to the conversation flow |
+
+The built-in `SuggestionsOptionsCard.tsx` also handles these details:
+
+- Supports both array and JSON-string forms of `options`
+- Displays a loading state while the ToolCall is still being generated
+- Allows selection only for a ToolCall with the `interrupted` status
+- Disables buttons immediately after a click to prevent duplicate submission
+- Preserves and highlights the selected option in historical messages
+- Allows actions only in the current editable conversation
+
+## Register it in the client plugin
+
+The frontend registration name must exactly match the server-side Tool name:
+
+```tsx
+import { Plugin } from '@nocobase/client-v2';
+import { DeveloperChoiceCard } from './ai-employees/tools/DeveloperChoiceCard';
+
+export class PluginDeveloperHelperClient extends Plugin {
+  async load() {
+    this.ai.toolsManager.registerTools('developerChoice', {
+      ui: {
+        card: DeveloperChoiceCard,
+      },
+    });
+  }
+}
+
+export default PluginDeveloperHelperClient;
+```
+
+If the server-side file is `src/ai/tools/developerChoice.ts`, register `developerChoice` here.
+
+The built-in `suggestions` registration works the same way:
+
+```ts
+export const suggestionsTool = [
+  'suggestions',
+  {
+    ui: {
+      card: SuggestionsOptionsCard,
+    },
+  },
+];
+```
+
+`PluginAIClientV2.load()` then calls `registerPluginAIClientV2BuiltinTools(this.ai.toolsManager)` to merge the card into the same-named Tool definition returned by the server.
+
+## Choose a card, modal, or frontend execution
+
+### Use a card
+
+The following lists only the commonly used client-side `ToolsOptions` settings. See the complete type in `packages/core/client-v2/src/ai/tools-manager/types.ts`.
+
+```ts
+type ToolsOptions = {
+  ui?: {
+    card?: ComponentType<ToolsUIProperties>;
+    modal?: {
+      title?: string;
+      okText?: string;
+      Component?: ComponentType;
+      footer?: ComponentType;
+      hideOkButton?: boolean;
+      // modal.props、useOnOk 等配置请查看完整类型。
+    };
+  };
+  invoke?: (app, params) => unknown | Promise<unknown>;
+  // useHooks 等其他配置请查看完整类型。
+};
+```
+
+Use `card` first by default.
+
+### Use a modal
+
+Add a `modal` only when the content is extensive or requires a large preview or complex argument editing.
+
+### Execute a Tool in the browser
+
+If the server-side Tool sets `execution: 'frontend'`, the client must also provide `invoke`. Such Tools are suitable for reading the current page context, editor content, or FlowEngine state. They are not suitable for data writes that require server-side permission enforcement.
+
+## Complete example: Add a selection card to a built-in AI employee
+
+After completing [Complete Example: Create a Built-in AI Employee](./complete-example.md), turn `Dev Helper`'s follow-up question into clickable options by defining another Tool named `developerChoice` and registering a frontend card. Put the server-side file at:
+
+```text
+src/ai/ai-employees/dev-helper/skills/welcome-developer/tools/developerChoice.ts
+```
+
+This Tool declares the options and accepts the user's selection:
+
+```ts
+import type { Context } from '@nocobase/actions';
+import { defineTools } from '@nocobase/ai';
+import { z } from 'zod';
+
+export default defineTools({
+  scope: 'SPECIFIED',
+  introduction: {
+    title: '{{t("ai.tools.developerChoice.title", { ns: "@nocobase/plugin-developer-helper" })}}',
+    about: '{{t("ai.tools.developerChoice.about", { ns: "@nocobase/plugin-developer-helper" })}}',
+  },
+  definition: {
+    name: 'developerChoice',
+    description: 'Show a short list of plugin-development directions for the user to choose from.',
+    schema: z.object({
+      options: z.array(z.string()).min(2).max(4),
+      option: z.string().optional(),
+    }),
+  },
+  invoke: async (_ctx: Context, args: { options: string[]; option?: string }) => {
+    return {
+      status: 'success',
+      content: args.option,
+    };
+  },
+});
+```
+
+Because `developerChoice.ts` is in the `welcome-developer` Skill's `tools/` directory, it is automatically bound to the current Skill. However, binding only means the model can use the Tool; it does not guarantee that the model will call it.
+
+Also update the workflow in `SKILLS.md`, replacing the original steps 5–6 with:
+
+```md
+5. Use `content.name` to write a short welcome message in the same language as the user.
+6. Call `developerChoice` exactly once with 2–4 plugin-development directions written in the user's language.
+7. Wait for the user to select an option.
+8. Continue according to the selected option.
+```
+
+Reuse the `DeveloperChoiceCard` defined above and save it to:
+
+```text
+src/client-v2/ai-employees/tools/DeveloperChoiceCard.tsx
+```
+
+Finally, register it in `src/client-v2/plugin.tsx`:
+
+```tsx
+import { Plugin } from '@nocobase/client-v2';
+import { DeveloperChoiceCard } from './ai-employees/tools/DeveloperChoiceCard';
+
+export class PluginDeveloperHelperClient extends Plugin {
+  async load() {
+    this.ai.toolsManager.registerTools('developerChoice', {
+      ui: {
+        card: DeveloperChoiceCard,
+      },
+    });
+  }
+}
+
+export default PluginDeveloperHelperClient;
+```
+
+After registering the card, rebuild the client. When a conversation reaches `developerChoice`, the ToolCall pauses and displays clickable options.
+
+<!-- 需要一张对话中显示 developerChoice 可点击选项的截图 -->
+
+## Related links
+
+- [Define a server-side Tool](./define-tool.md) — Define the server-side Tool corresponding to a frontend card
+- [Complete example: Create a built-in AI employee](./complete-example.md) — Complete the basic example without frontend code first
+- [Internationalization for AI employee plugins](./internationalization.md) — Translate Tool and Skill management-interface text
+- [Client Plugin](../../../plugin-development/client/plugin.md) — Learn about the client plugin entry point and `load()`

package/dist/ai/docs/nocobase/ai-employees/dev/ai-employee/index.md

@@ -0,0 +1,126 @@
+---
+title: "AI Employee Plugin Development"
+description: "Explains the relationships, directory conventions, and learning path for Tools, Skills, built-in AI employees, and frontend Tool UI in NocoBase plugins."
+keywords: "NocoBase,AI employee plugin development,Tool,Skill,defineAIEmployee,src/ai"
+---
+
+# AI Employee Plugin Development
+
+In NocoBase, plugins can make their business capabilities available to AI employees. Three extension points cover different layers:
+
+- **Tool** — Performs specific operations such as querying data, calling APIs, and modifying records
+- **Skill** — Tells the model when to use Tools and which steps to follow to complete a task
+- **Built-in AI Employee** — Assembles a role profile, system prompt, Skills, and Tools into an employee that is ready to use
+
+Usually, you do not need to call registration APIs manually. Put files in the plugin's conventional `src/ai` directories, and NocoBase automatically scans and registers them when the plugin loads. You only need to register the corresponding frontend component or execution logic in `src/client-v2/plugin.tsx` when a Tool requires a custom card, modal, or browser-side execution.
+
+Before you begin, make sure the application has installed and enabled `@nocobase/plugin-ai`. Plugin code can use the types and definition functions provided by `@nocobase/ai` and `@nocobase/actions`.
+
+:::tip Prerequisites
+
+- [Write your first plugin](../../../plugin-development/write-your-first-plugin.md) — If you are new to plugin development, start with the plugin directory, build, and activation workflow
+- [AI employees](../../index.md) — Learn how to configure and use AI employees first
+
+:::
+
+
+## Quick index
+
+| I want to... | Read this |
+| --- | --- |
+| Let AI call a server-side operation | [Define a server-side Tool](./define-tool.md) |
+| Specify the call sequence for multiple Tools | [Define a Skill](./define-skill.md) |
+| Provide a fixed AI role with a plugin | [Define a built-in AI employee](./define-ai-employee.md) |
+| See how a Tool, Skill, and employee work together | [Complete example: Create a built-in AI employee](./complete-example.md) |
+| Add confirmation, selection, or editing UI to a Tool | [Add frontend interaction to a Tool](./frontend-tool-ui.md) |
+| Add management-interface translations for Tools and Skills | [Internationalization for AI employee plugins](./internationalization.md) |
+| Troubleshoot registration, binding, and execution | [Troubleshooting AI employee plugin development](./troubleshooting.md) |
+
+## Decide which layer to extend first
+
+Tools, Skills, and built-in AI employees are not three separate features. They form layers that build on one another from the bottom up. Not every plugin needs to implement all three.
+
+```text
+Tool：让 AI 能执行一个具体动作
+  ↓
+Skill：让 AI 按固定方法完成一类任务
+  ↓
+内置 AI 员工：把这些能力装配成一个固定角色和使用入口
+```
+
+Choose the starting layer based on your requirements:
+
+- If AI only needs to query data, call an API, or modify records, defining a Tool is enough
+- If you need to specify Tool call order, confirmation steps, and output format, define a Skill for those Tools
+- If the plugin should provide a fixed role immediately after it is enabled, create a built-in AI employee and bind the corresponding Skills and Tools
+
+When all three layers are used, a task follows this sequence:
+
+1. The user gives the AI employee a task
+2. The AI employee uses its system prompt to decide which Skill is needed
+3. The Skill tells the model which Tools to call and in what order
+4. The Tool performs a query, write, or external request and returns the result
+5. The AI employee prepares the final response from the Tool result
+
+A frontend Tool card is not a fourth capability layer. It only adds an interaction UI to a ToolCall when the Tool needs the user to confirm, select an option, or edit arguments.
+
+## Put AI resources under `src/ai`
+
+NocoBase discovers a plugin's AI resources by directory convention. With the standard plugin layout, put Tools, Skills, and built-in AI employees under `src/ai`; you do not need to register them one by one in `load()` in `src/server/plugin.ts`.
+
+A complete directory can be organized like this:
+
+```text
+src/ai/
+├── tools/
+│   └── searchDocs.ts
+├── skills/
+│   └── document-search/
+│       ├── SKILLS.md
+│       └── tools/
+│           └── readDocument.ts
+└── ai-employees/
+    ├── translator.ts
+    └── developer/
+        ├── index.ts
+        ├── prompt.md
+        ├── skills/
+        └── tools/
+```
+
+Each location uses a different registration method:
+
+| File or directory | How NocoBase handles it |
+| --- | --- |
+| `src/ai/tools/<name>.ts` | Registers an independent Tool |
+| `src/ai/skills/<name>/SKILLS.md` | Registers a Skill |
+| `tools/` under a Skill directory | Registers Tools and automatically binds them to the current Skill |
+| `src/ai/ai-employees/<name>.ts` | Registers a single-file built-in AI employee |
+| `src/ai/ai-employees/<name>/index.ts` | Registers a directory-based built-in AI employee |
+| `prompt.md` under an AI employee directory | Provides the employee's default system prompt |
+| `skills/` and `tools/` under an AI employee directory | Registers resources and automatically binds them to the current employee |
+
+When a plugin loads, NocoBase completes these steps before running the plugin's own `load()` method:
+
+1. Scan and register Tools
+2. Parse `SKILLS.md` and bind Tools in each Skill directory to that Skill
+3. Load built-in AI employees and merge the `prompt.md`, Skills, and Tools in each employee directory
+
+`src/client-v2` is not part of this automatic scanning convention. Register something there only when a Tool needs a frontend card, modal, or browser-side execution logic.
+
+## Extension points and directory quick reference
+
+| Extension point | Responsibility | Default location |
+| --- | --- | --- |
+| Tool | Performs specific operations such as queries, writes, and external requests | `src/ai/**/tools/` |
+| Skill | Specifies the workflow, Tool call order, and output constraints | `src/ai/**/skills/<name>/SKILLS.md` |
+| Built-in AI employee | Defines a fixed role and assembles its system prompt, Skills, and Tools | `src/ai/ai-employees/` |
+| Frontend Tool card | Displays a ToolCall and collects confirmation, edits, or rejection | `src/client-v2/` |
+
+Implement the Tool first by default. Add a Skill when you need a fixed workflow, then create a built-in AI employee when you need a fixed role entry point. Add a frontend card only when the Tool requires browser interaction.
+
+## Related links
+
+- [Write your first plugin](../../../plugin-development/write-your-first-plugin.md) — Create and run a NocoBase plugin from scratch
+- [AI employees overview](../../index.md) — Learn where to access and use AI employees
+- [Prompt engineering guide](../../configuration/prompt-engineering-guide.md) — Write system prompts and task constraints

package/dist/ai/docs/nocobase/ai-employees/dev/ai-employee/internationalization.md

@@ -0,0 +1,88 @@
+---
+title: "Internationalization for AI Employee Plugins"
+description: "Explains internationalization files, translation templates, and current limitations for NocoBase AI employee Tools, Skills, and built-in employee profiles."
+keywords: "NocoBase,AI employee plugin internationalization,Tool introduction,Skill introduction,locale"
+---
+
+# Internationalization for AI Employee Plugins
+
+Management-interface text in an AI employee plugin should follow the current interface language. Tools and Skills can use the plugin's own locale files through `introduction`, while AI employee profile fields are handled differently.
+
+## What needs internationalization
+
+Usually, you need to internationalize text displayed to administrators or users:
+
+- `introduction.title` and `introduction.about` for Tools
+- `introduction.title` and `introduction.about` for Skills
+- Text in frontend cards, modals, and action buttons
+
+`definition.name`, `definition.description`, schema descriptions, Skill content, and AI employee system prompts are primarily intended for the model. Do not change a Tool's stable name or workflow content for interface translation.
+
+## Translate Tool and Skill management-interface text
+
+A Tool's `introduction` can use the `{{t(...)}}` translation template:
+
+```ts
+introduction: {
+  title: '{{t("ai.tools.greetDeveloper.title", { ns: "@nocobase/plugin-developer-helper" })}}',
+  about: '{{t("ai.tools.greetDeveloper.about", { ns: "@nocobase/plugin-developer-helper" })}}',
+},
+```
+
+Use the same format in the frontmatter of a Skill's `SKILLS.md`:
+
+```yaml
+introduction:
+  title: '{{t("ai.skills.welcomeDeveloper.title", { ns: "@nocobase/plugin-developer-helper" })}}'
+  about: '{{t("ai.skills.welcomeDeveloper.about", { ns: "@nocobase/plugin-developer-helper" })}}'
+```
+
+The `ns` value must match the internationalization namespace actually used by the plugin.
+
+## Add locale files
+
+Plugin locale files are stored in `src/locale/`. Use the same keys for each language and change only the corresponding text.
+
+### Add English text
+
+Add the following to `src/locale/en-US.json`:
+
+```json
+{
+  "ai.tools.greetDeveloper.title": "Developer name check",
+  "ai.tools.greetDeveloper.about": "Validate the developer name before writing a welcome message.",
+  "ai.tools.developerChoice.title": "Developer choices",
+  "ai.tools.developerChoice.about": "Ask the developer to choose the next plugin capability.",
+  "ai.skills.welcomeDeveloper.title": "Developer welcome",
+  "ai.skills.welcomeDeveloper.about": "Welcome a developer and ask what plugin capability they want to build."
+}
+```
+
+### Add Chinese text
+
+Add the following to `src/locale/zh-CN.json`:
+
+```json
+{
+  "ai.tools.greetDeveloper.title": "开发者姓名确认",
+  "ai.tools.greetDeveloper.about": "在生成欢迎语之前确认开发者姓名。",
+  "ai.tools.developerChoice.title": "开发方向选择",
+  "ai.tools.developerChoice.about": "让开发者选择下一步要实现的插件能力。",
+  "ai.skills.welcomeDeveloper.title": "欢迎开发者",
+  "ai.skills.welcomeDeveloper.about": "欢迎开发者，并询问接下来要实现的插件能力。"
+}
+```
+
+## Current limitations for AI employee profiles
+
+The `nickname`, `position`, `bio`, and `greeting` fields in an AI employee profile do not use the `{{t(...)}}` template mechanism above. At runtime, built-in employees currently translate these raw strings in the `@nocobase/plugin-ai` namespace, so third-party plugins should not assume that a custom namespace will take effect automatically.
+
+Unless you add separate localization logic, choose one default language for the employee profile and put the interface text for Tools, Skills, and frontend interactions in the plugin's own locale files.
+
+## Related links
+
+- [AI employee plugin development](./index.md) — Return to the development guide overview
+- [Define a server-side Tool](./define-tool.md) — Use translation templates in a Tool introduction
+- [Define a Skill](./define-skill.md) — Use translation templates in Skill frontmatter
+- [Define a built-in AI employee](./define-ai-employee.md) — Learn about employee profile fields
+- [Add frontend interaction to a Tool](./frontend-tool-ui.md) — Add interface translations to frontend cards and modals

package/dist/ai/docs/nocobase/ai-employees/dev/ai-employee/troubleshooting.md

@@ -0,0 +1,86 @@
+---
+title: "Troubleshooting AI Employee Plugin Development"
+description: "Troubleshoot NocoBase AI employee Tools, Skills, built-in employees, and frontend Tool cards that are not registered or do not run."
+keywords: "NocoBase,AI employee troubleshooting,Tool not registered,Skill not loaded,frontend card"
+---
+
+# Troubleshooting AI Employee Plugin Development
+
+## The Tool is not registered
+
+Check the following in order:
+
+- The file is under `src/ai/**/tools/` within the plugin's build scope
+- The file uses the `.ts` or `.js` extension
+- It uses `export default defineTools(...)`
+- The Tool file is not mistakenly named with the `.d.ts` extension
+- There is no duplicate Tool name causing the later registration to be ignored
+- The plugin has been rebuilt and loaded
+
+## The Skill does not appear
+
+Check the filename first. It must currently be:
+
+```text
+SKILLS.md
+```
+
+Also confirm that the frontmatter contains a stable `name` and `description`, and that the file is located at `src/ai/**/skills/<skill-name>/SKILLS.md`.
+
+## The Skill loads but cannot call the Tool
+
+Check the following:
+
+- The Skill's `tools` list includes the Tool name
+- The Tool is in the current Skill's `tools/` directory
+- The Tool filename, `definition.name`, and Skill reference are consistent
+- The `scope` is appropriate for the current binding method
+- The Tool was not skipped because of a duplicate name
+
+Binding a Tool only means the model can use it. If the Tool appears in the Skill but the model still does not call it, explicitly state the call timing, parameter requirements, and result-waiting step in the `SKILLS.md` workflow.
+
+## The frontend card does not appear
+
+The frontend registration name must exactly match the final server-side Tool name:
+
+```ts
+this.ai.toolsManager.registerTools('developerChoice', options);
+```
+
+Also check:
+
+- The custom plugin uses the `src/client-v2/` runtime
+- The card is registered in the client plugin's `load()` method
+- The ToolCall has entered a state supported by the card
+- The card is not disabled by its `invokeStatus` check
+- The client plugin has been rebuilt and loaded
+
+## The Tool does not continue after clicking the card
+
+Confirm that one of `approve()`, `edit()`, or `reject()` is called. To write the user's selection back into the arguments, use:
+
+```ts
+await decisions.edit({
+  ...toolCall.args,
+  option: selectedOption,
+});
+```
+
+Also confirm that the server-side schema allows this field and that `invoke()` reads it.
+
+## Changing `definition.name` has no effect
+
+An automatically loaded Tool's name is determined by its filename or directory name. For example:
+
+```text
+src/ai/tools/developerChoice.ts
+```
+
+The final name is `developerChoice`. To rename it, also rename the file, Skill references, AI employee configuration, and frontend registration name.
+
+## Related links
+
+- [AI employee plugin development](./index.md) — Return to the development guide overview
+- [Define a server-side Tool](./define-tool.md) — Check Tool naming and registration
+- [Define a Skill](./define-skill.md) — Check Skill and Tool binding
+- [Add frontend interaction to a Tool](./frontend-tool-ui.md) — Check ToolCall and frontend registration

package/dist/ai/docs/nocobase/ai-employees/{knowledge-base/dev → dev/knowledge-base}/external-knowledge-base.md

@@ -12,7 +12,7 @@ An external knowledge base plugin does not participate in document upload, segme
 
 :::tip Prereading
 
-- [Knowledge base overview](../knowledge-base/) - Understand the boundaries of Local, Readonly, and External knowledge bases
+- [Knowledge base overview](../../knowledge-base/knowledge-base/index.md) - Understand the boundaries of Local, Readonly, and External knowledge bases
 - [Plugin](../../../plugin-development/server/plugin.md) - Understand server-side plugin lifecycle and `this.app.pm`
 - [i18n](../../../plugin-development/server/i18n.md) - Prepare translations if the plugin provides a configuration form
 
@@ -312,7 +312,7 @@ At this point, the external knowledge base plugin can be called by AI employees.
 
 ## Related links
 
-- [Knowledge base overview](../knowledge-base/) - Boundaries of Local, Readonly, and External knowledge bases
+- [Knowledge base overview](../../knowledge-base/knowledge-base/index.md) - Boundaries of Local, Readonly, and External knowledge bases
 - [Plugin](../../../plugin-development/server/plugin.md) - Server-side plugin lifecycle and `this.app.pm`
 - [i18n](../../../plugin-development/server/i18n.md) - Plugin frontend and server-side translations
 - [Client plugin development overview](../../../plugin-development/client/index.md) - Client entry, components, and context capabilities

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

@@ -39,7 +39,7 @@ The three knowledge base types have different capability boundaries:
 | --- | --- |
 | Local | Documents, segment files, and vector data are managed by NocoBase. It supports uploading documents in the UI, and also supports creating, updating, deleting, and retrieving knowledge base documents through workflow nodes |
 | Readonly | Documents and vector data are maintained by an external system. NocoBase cannot maintain this data in the UI or workflows, and only uses the knowledge base as a RAG retrieval source. Currently, PGVector is the only supported vector database |
-| External | Documents, vector data, and retrieval logic are all handled by an external system. NocoBase cannot directly maintain documents or vector data. Developers need to provide a plugin and implement the retrieval logic in that plugin, such as connecting to a vector database not yet supported by NocoBase or calling a third-party retrieval API. For development details, see [External Knowledge Base plugin](../dev/external-knowledge-base) |
+| External | Documents, vector data, and retrieval logic are all handled by an external system. NocoBase cannot directly maintain documents or vector data. Developers need to provide a plugin and implement the retrieval logic in that plugin, such as connecting to a vector database not yet supported by NocoBase or calling a third-party retrieval API. For development details, see [External Knowledge Base plugin](../../dev/knowledge-base/external-knowledge-base.md) |
 
 Local knowledge bases are recommended by default. Only consider Readonly or External when documents and vector data are already maintained outside NocoBase and NocoBase only needs to read retrieval results.
 

package/dist/ai/docs/nocobase/development/index.md

@@ -52,5 +52,5 @@ features:
         link: /file-manager/development
       - title: Knowledge Base Extension
         details: Connect external knowledge bases or custom retrieval services to extend RAG retrieval sources for AI employees.
-        link: /ai-employees/knowledge-base/dev/external-knowledge-base
+        link: /ai-employees/dev/knowledge-base/external-knowledge-base
 ---