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

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

@@ -0,0 +1,206 @@
+---
+title: "Complete Example: Create a Built-in AI Employee"
+description: "Use a complete example to define a Tool, Skill, system prompt, and built-in AI employee in a NocoBase plugin."
+keywords: "NocoBase,Dev Helper,AI employee example,defineTools,defineAIEmployee,SKILLS.md"
+---
+
+# Complete Example: Create a Built-in AI Employee
+
+The following complete example creates a built-in AI employee that guides plugin development. The example names the employee `Dev Helper` and configures its Tool, Skill, and system prompt. When a user says “Please greet Alice,” the employee loads the `welcome-developer` Skill, calls the `greetDeveloper` Tool to confirm the name, and then generates a greeting in the user's current language.
+
+:::tip Prerequisites
+
+- [Define a server-side Tool](./define-tool.md) — Learn the basic structure of `defineTools()` and Tools
+- [Define a Skill](./define-skill.md) — Learn about `SKILLS.md` and Tool binding
+- [Define a built-in AI employee](./define-ai-employee.md) — Learn about `defineAIEmployee()` and employee directories
+
+:::
+
+## Final result
+
+When complete, the plugin provides these capabilities:
+
+- Creates a built-in AI employee named `Dev Helper`
+- Automatically binds the `welcome-developer` Skill to the employee
+- Uses the Skill to call the `greetDeveloper` Tool and confirm the developer's name
+- Generates a greeting and follow-up question in the user's current language
+
+<!-- 需要一张 AI 员工管理页中 Dev Helper 被标记为内置员工的截图 -->
+
+## Final directory structure
+
+```text
+src/ai/ai-employees/dev-helper/
+├── index.ts
+├── prompt.md
+└── skills/
+    └── welcome-developer/
+        ├── SKILLS.md
+        └── tools/
+            └── greetDeveloper.ts
+```
+
+This example requires no frontend code and no manual registration in `src/server/plugin.ts`.
+
+## Step 1: Define the Tool
+
+Create `src/ai/ai-employees/dev-helper/skills/welcome-developer/tools/greetDeveloper.ts`:
+
+```ts
+import type { Context } from '@nocobase/actions';
+import { defineTools } from '@nocobase/ai';
+import { z } from 'zod';
+
+export default defineTools({
+  scope: 'SPECIFIED',
+  defaultPermission: 'ALLOW',
+  introduction: {
+    title: '{{t("ai.tools.greetDeveloper.title", { ns: "@nocobase/plugin-developer-helper" })}}',
+    about: '{{t("ai.tools.greetDeveloper.about", { ns: "@nocobase/plugin-developer-helper" })}}',
+  },
+  definition: {
+    name: 'greetDeveloper',
+    description: 'Validate the developer name before the assistant writes a welcome message.',
+    schema: z.object({
+      name: z.string().min(1).describe('The developer name provided by the user.'),
+    }),
+  },
+  invoke: async (_ctx: Context, args: { name: string }) => {
+    return {
+      status: 'success',
+      content: {
+        name: args.name,
+      },
+    };
+  },
+});
+```
+
+## Step 2: Define the Skill
+
+Create `src/ai/ai-employees/dev-helper/skills/welcome-developer/SKILLS.md`:
+
+```md
+---
+scope: SPECIFIED
+name: welcome-developer
+description: Greet a developer by name and guide them to the next NocoBase plugin-development step.
+introduction:
+  title: '{{t("ai.skills.welcomeDeveloper.title", { ns: "@nocobase/plugin-developer-helper" })}}'
+  about: '{{t("ai.skills.welcomeDeveloper.about", { ns: "@nocobase/plugin-developer-helper" })}}'
+---
+
+You welcome developers who are starting NocoBase plugin development.
+
+# Workflow
+
+1. Read the developer name from the user's request.
+2. If the name is missing, ask the user for it.
+3. Call `greetDeveloper` exactly once.
+4. Wait for a tool result with `status: "success"`.
+5. Use `content.name` to write a short welcome message in the same language as the user.
+6. Ask which plugin capability the developer wants to build next, using the same language as the user.
+
+# Constraints
+
+- Do not invent a name.
+- Do not claim the Tool succeeded before receiving its result.
+- Write both the welcome message and the follow-up question in the same language as the user.
+```
+
+Because `greetDeveloper.ts` is in the current Skill's `tools/` directory, you do not need to add `tools: [greetDeveloper]`.
+
+## Step 3: Define the AI employee profile
+
+Create `src/ai/ai-employees/dev-helper/index.ts`:
+
+```ts
+import { defineAIEmployee } from '@nocobase/ai';
+
+export default defineAIEmployee({
+  username: 'developer-helper-dev-assistant',
+  category: 'developer',
+  description: 'AI employee for helping developers start NocoBase plugin development.',
+  avatar: 'nocobase-002-male',
+  nickname: 'Dev Helper',
+  position: 'Plugin development guide',
+  bio: 'Welcomes developers and guides them into a small, verifiable plugin-development task.',
+  greeting: 'Hello, I can help you begin a NocoBase plugin development task. Who are we welcoming today?',
+});
+```
+
+`username` is the unique identifier in the database. Do not change it casually after release, or NocoBase will treat the new value as a different built-in AI employee.
+
+:::warning Note
+
+The `username` must remain stable and must not conflict with another plugin or existing AI employee. If the database already contains the same `username`, loading the plugin updates that record instead of creating an isolated new employee.
+
+When the plugin reloads, the `category`, `nickname`, `position`, `avatar`, `bio`, `greeting`, default system prompt, Skill and Tool bindings, `chatSettings`, and `sort` from the code may all be written to the database again. For production plugins, use a plugin-prefixed name such as `developer-helper-dev-assistant`.
+
+:::
+
+## Step 4: Define the system prompt
+
+Create `src/ai/ai-employees/dev-helper/prompt.md`:
+
+```md
+You are Dev Helper, a NocoBase plugin development guide.
+
+Help users begin with a small, verifiable task.
+
+When the user asks you to greet or welcome a developer, load the `welcome-developer` skill and follow its workflow.
+
+Never claim that a Tool succeeded before receiving its result.
+```
+
+The directory relationships now provide automatic binding:
+
+```text
+greetDeveloper Tool
+  → welcome-developer Skill
+  → dev-helper AI employee
+```
+
+## Step 5: Enable and verify
+
+Rebuild or restart the development service and confirm that the plugin containing these files is enabled. Then check the AI employee management page:
+
+- `Dev Helper` is listed
+- The employee is marked as built-in
+- The employee's dedicated Skills include `welcome-developer`
+- `greetDeveloper` is available after the Skill loads
+
+Enter the following in a conversation:
+
+```text
+请向 Alice 打个招呼。
+```
+
+The expected sequence is:
+
+```text
+加载 welcome-developer
+  → 调用 greetDeveloper({ name: "Alice" })
+  → 收到 status: "success" 和 content.name
+  → Skill 使用用户当前语言生成问候语
+  → 询问接下来要开发什么插件能力
+```
+
+Set `defaultPermission: 'ALLOW'` if the Tool should not ask the user for confirmation before every call. For Tools that delete data, modify records in bulk, or have external side effects, keeping the default `ASK` is more appropriate.
+
+## Summary
+
+| File | Responsibility |
+| --- | --- |
+| `greetDeveloper.ts` | Validates input and returns a structured Tool result |
+| `SKILLS.md` | Defines the Tool call and response workflow |
+| `prompt.md` | Defines the employee role and global constraints |
+| `index.ts` | Defines the built-in AI employee profile |
+
+## Related links
+
+- [AI employee plugin development](./index.md) — Understand the relationship between Tools, Skills, and built-in AI employees
+- [Define a server-side Tool](./define-tool.md) — See the complete `defineTools()` configuration
+- [Define a Skill](./define-skill.md) — See the fields and format of `SKILLS.md`
+- [Define a built-in AI employee](./define-ai-employee.md) — Learn about `defineAIEmployee()` and directory binding
+- [Internationalization for AI employee plugins](./internationalization.md) — Add translations for management-interface text in this example

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

@@ -0,0 +1,149 @@
+---
+title: "Define a Built-in AI Employee"
+description: "Explains how NocoBase plugins use defineAIEmployee, prompt.md, skills, and tools directories to create built-in AI employees."
+keywords: "NocoBase,built-in AI employee,defineAIEmployee,prompt.md,AIEmployeeOptions,Nathan"
+---
+
+# Define a Built-in AI Employee
+
+A built-in AI employee is registered with its plugin. When the plugin loads for the first time, NocoBase creates the corresponding employee record and marks it as built-in. On later plugin loads, the employee's default profile, prompt, Skills, and Tools are updated from the code.
+
+## Single-file and directory forms
+
+Use a single file when the profile is simple and does not need a separate prompt or dedicated resources:
+
+```text
+src/ai/ai-employees/lina.ts
+```
+
+Use a directory when you need `prompt.md`, dedicated Skills, or dedicated Tools:
+
+```text
+src/ai/ai-employees/nathan/
+├── index.ts
+├── prompt.md
+├── skills/
+└── tools/
+```
+
+The directory form is better suited to long-term maintenance.
+
+## Use `defineAIEmployee()`
+
+In `index.ts`, use `defineAIEmployee()` from `@nocobase/ai`:
+
+```ts
+import { defineAIEmployee } from '@nocobase/ai';
+
+export default defineAIEmployee({
+  username: 'developer-helper-dev-assistant',
+  category: 'developer',
+  description: 'AI employee for helping developers start NocoBase plugin development.',
+  avatar: 'nocobase-002-male',
+  nickname: 'Dev Helper',
+  position: 'Plugin development guide',
+  bio: 'Helps developers understand plugin structure and complete small development tasks.',
+  greeting: 'Hello, I can help you start a NocoBase plugin development task. What would you like to build?',
+});
+```
+
+The main fields are:
+
+| Field | Purpose |
+| --- | --- |
+| `username` | Unique AI employee identifier; required and must remain stable over time |
+| `category` | Employee category, such as `developer` or `business` |
+| `description` | Internal description and retrieval information |
+| `avatar` | Avatar identifier |
+| `nickname` | Name displayed to users |
+| `position` | Job title |
+| `bio` | Short biography |
+| `greeting` | Greeting for a new conversation |
+| `systemPrompt` | Default system prompt |
+| `skills` | Explicitly bound Skill names |
+| `tools` | Explicitly bound Tool configuration |
+| `chatSettings` | Chat settings such as whether Skills and Tools are enabled and which system-prompt mode is used |
+| `sort` | Sort order for built-in employees |
+
+The current type of `tools` is an array of objects:
+
+```ts
+tools: [
+  { name: 'greetDeveloper' },
+  { name: 'customDataExporter', autoCall: true }, // customDataExporter 的 scope 必须是 CUSTOM
+]
+```
+
+`autoCall` only overrides the current AI employee's call permission for a `CUSTOM` Tool. For `GENERAL` and `SPECIFIED` Tools, runtime behavior still follows the Tool's own `defaultPermission`. If a `CUSTOM` Tool has no employee-level configuration, it also falls back to the Tool's own `defaultPermission`.
+
+Tools discovered automatically in the directory are normalized to `{ name: 'toolName' }`.
+
+## Put long prompts in `prompt.md`
+
+When an AI employee uses the directory form, put its system prompt in the sibling `prompt.md` file:
+
+```text
+src/ai/ai-employees/dev-helper/prompt.md
+```
+
+```md
+You are Dev Helper, a NocoBase plugin development guide.
+
+Help the user break a plugin requirement into small, verifiable steps.
+
+When the user asks you to welcome a developer, load the `welcome-developer` skill and follow it.
+
+Never claim that a Tool succeeded before receiving its result.
+```
+
+When `prompt.md` exists, it overrides `systemPrompt` in `index.ts`. Long prompts are easier to review in a Markdown file and avoid escaping problems in TypeScript template strings.
+
+## Built-in AI employee example: Nathan
+
+The employee profile in `packages/plugins/@nocobase/plugin-flow-engine/src/ai/ai-employees/nathan/index.ts` is short:
+
+```ts
+export default defineAIEmployee({
+  username: 'nathan',
+  category: 'developer',
+  description: 'AI employee for coding',
+  avatar: 'nocobase-002-male',
+  nickname: 'Nathan',
+  position: 'Frontend code engineer',
+  greeting: 'Hello, I’m Nathan, your frontend code engineer...',
+});
+```
+
+Nathan's full capabilities come from other resources in the same directory:
+
+```text
+nathan/
+├── index.ts
+├── prompt.md
+└── skills/
+    └── frontend-developer/
+        ├── SKILLS.md
+        └── tools/
+            ├── getContextApis.ts
+            ├── getContextEnvs.ts
+            ├── getContextVars.ts
+            ├── lintAndTestJS.ts
+            ├── patchJSCode.ts
+            ├── readJSCode.ts
+            └── writeJSCode.ts
+```
+
+The loading process automatically completes three levels of binding:
+
+1. Files in `tools/` are registered as Tools
+2. The Tools are automatically bound to the `frontend-developer` Skill
+3. The Skill is automatically bound to Nathan
+
+As a result, `index.ts` does not need to list the complete `skills` and `tools` configuration again.
+
+## Related links
+
+- [AI employee plugin development](./index.md) — Understand the relationship between built-in AI employees, Tools, and Skills
+- [Define a Skill](./define-skill.md) — Create a dedicated Skill for an employee
+- [Complete example: Create a built-in AI employee](./complete-example.md) — See the complete employee directory and registration process
+- [Internationalization for AI employee plugins](./internationalization.md) — Learn how localization differs for employee profiles and Tool and Skill text

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

@@ -0,0 +1,138 @@
+---
+title: "Define a Skill"
+description: "Explains the frontmatter, prompt content, Tool binding, and automatic directory discovery for NocoBase AI employee SKILLS.md files."
+keywords: "NocoBase,AI employee Skill,SKILLS.md,Skill Tool binding,business-analysis-report"
+---
+
+# Define a Skill
+
+A Skill does not execute code. It is an operating guide provided to the model that specifies the workflow, available Tools, validation steps, and output requirements.
+
+## Skill directory
+
+Each Skill uses its own directory:
+
+```text
+src/ai/skills/business-analysis-report/
+├── SKILLS.md
+└── tools/
+    └── businessReportGenerator.ts
+```
+
+Where:
+
+- `SKILLS.md` defines metadata and prompt content
+- `tools/` contains Tools used only with this Skill
+- Tools discovered in `tools/` are automatically added to this Skill's Tool list
+
+## `SKILLS.md` frontmatter
+
+A minimal Skill looks like this:
+
+```md
+---
+scope: SPECIFIED
+name: welcome-developer
+description: Greet a developer by name and explain the next step for starting NocoBase plugin development.
+introduction:
+  title: '{{t("ai.skills.welcomeDeveloper.title", { ns: "@nocobase/plugin-developer-helper" })}}'
+  about: '{{t("ai.skills.welcomeDeveloper.about", { ns: "@nocobase/plugin-developer-helper" })}}'
+---
+
+You help welcome developers who are starting NocoBase plugin development.
+
+When the user asks you to greet or welcome a developer:
+
+1. Extract the developer name from the request.
+2. Call `greetDeveloper` exactly once.
+3. Return the greeting from the tool result.
+4. Ask which plugin capability the developer wants to build next.
+
+Do not claim that the greeting was generated until the tool returns `status: "success"`.
+```
+
+Common frontmatter fields include:
+
+| Field | Purpose |
+| --- | --- |
+| `scope` | Availability scope of the Skill; defaults to `SPECIFIED` when omitted |
+| `name` | Unique name of the Skill |
+| `description` | Helps the model decide when to load this Skill |
+| `introduction.title` | Title displayed in the management interface |
+| `introduction.about` | Description displayed in the management interface |
+| `tools` | List of additional Tool names to bind |
+
+The Skill content is stored unchanged and added to the model context after the Skill is loaded. Focus the content on workflow and constraints; do not copy Tool implementation details into it.
+
+## Bind Tools to a Skill
+
+There are two methods.
+
+The first is to declare them explicitly in the frontmatter:
+
+```yaml
+tools:
+  - getSkill
+  - businessReportGenerator
+```
+
+The second is to put the Tool in the current Skill's `tools/` directory:
+
+```text
+src/ai/skills/welcome-developer/
+├── SKILLS.md
+└── tools/
+    └── greetDeveloper.ts
+```
+
+The loader automatically discovers `greetDeveloper` and merges it into the Skill's Tool list. By default, put a Tool that belongs exclusively to one Skill under that Skill's directory. The file location then expresses the binding relationship.
+
+## How to write an effective Skill
+
+A practical Skill usually includes:
+
+1. Role and task boundaries
+2. Required processing order
+3. Which Tool to call at each step
+4. When to ask the user for confirmation
+5. How to handle Tool failures
+6. Final output structure and validation conditions
+
+If a Tool modifies data, the Skill must explicitly require the model to wait for a successful Tool result. It must not claim that the operation is complete before the call returns.
+
+## Built-in Skill example: `business-analysis-report`
+
+`packages/plugins/@nocobase/plugin-ai/src/ai/skills/business-analysis-report/SKILLS.md` breaks business analysis into a clear workflow:
+
+```yaml
+---
+scope: GENERAL
+name: business-analysis-report
+description: Analyze business data with the data-query workflow and generate stakeholder-facing reports with markdown and ECharts.
+introduction:
+  title: '{{t("ai.skills.businessAnalysisReport.title", { ns: "@nocobase/plugin-ai" })}}'
+  about: '{{t("ai.skills.businessAnalysisReport.about", { ns: "@nocobase/plugin-ai" })}}'
+tools:
+  - getSkill
+  - businessReportGenerator
+---
+```
+
+Instead of merely saying “generate a business report,” the content goes on to require the following:
+
+- Understand the decision objective, audience, time range, and metrics first
+- When business data is involved, the first ToolCall must load the `data-query` Skill
+- Never guess tables, relationship paths, or query results
+- Call `businessReportGenerator` only after the data is ready
+- Generate charts and the Markdown report in the same ToolCall
+- Determine success from the returned `status`, `chartCount`, `errors`, and `warnings`
+- Retry a chart failure only once, then fall back to a Markdown-only report
+
+These rules are the main value of a Skill—they narrow “what the model can do” into a repeatable, verifiable process.
+
+## Related links
+
+- [AI employee plugin development](./index.md) — Understand where Skills fit into AI employee extensions
+- [Define a server-side Tool](./define-tool.md) — Define a Tool that a Skill can call
+- [Define a built-in AI employee](./define-ai-employee.md) — Bind a Skill to a fixed employee
+- [Complete example: Create a built-in AI employee](./complete-example.md) — See a complete Skill and Tool binding example

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

@@ -0,0 +1,189 @@
+---
+title: "Define a Server-side Tool"
+description: "Explains defineTools, scope, schema, invoke, permissions, and directory registration for NocoBase AI employee server-side Tools."
+keywords: "NocoBase,AI employee Tool,defineTools,ToolsOptions,Zod,invoke"
+---
+
+# Define a Server-side Tool
+
+## Minimal Tool structure
+
+Define a server-side Tool with `defineTools()` from `@nocobase/ai`. The following Tool accepts a name and returns a greeting:
+
+```ts
+import type { Context } from '@nocobase/actions';
+import { defineTools } from '@nocobase/ai';
+import { z } from 'zod';
+
+export default defineTools({
+  scope: 'SPECIFIED',
+  defaultPermission: 'ALLOW',
+  introduction: {
+    title: '{{t("ai.tools.greetDeveloper.title", { ns: "@nocobase/plugin-developer-helper" })}}',
+    about: '{{t("ai.tools.greetDeveloper.about", { ns: "@nocobase/plugin-developer-helper" })}}',
+  },
+  definition: {
+    name: 'greetDeveloper',
+    description: 'Generate a short greeting for the developer named by the user.',
+    schema: z.object({
+      name: z.string().min(1).describe('The developer name to greet.'),
+    }),
+  },
+  invoke: async (_ctx: Context, args: { name: string }) => {
+    return {
+      status: 'success',
+      content: `Hello ${args.name}, welcome to NocoBase plugin development!`,
+    };
+  },
+});
+```
+
+If the file path is `src/ai/tools/greetDeveloper.ts`, the loader uses the filename `greetDeveloper` as the final Tool name. Even if `definition.name` contains another value, registration overrides it with the filename.
+
+Therefore, keep the filename, `definition.name`, the name referenced by the Skill, and the name registered on the frontend consistent by default.
+
+## Tool options
+
+The main `defineTools()` options are:
+
+| Option | Purpose | Default |
+| --- | --- | --- |
+| `scope` | Determines the Tool's availability scope | Required |
+| `execution` | Specifies whether the logic runs on the `backend` or `frontend` | `backend` |
+| `defaultPermission` | Allows the Tool directly or asks for confirmation before a call | `ASK` |
+| `silence` | Hides the Tool call indicator in the conversation | `false` |
+| `introduction` | Title and description displayed in the management interface | Uses the Tool name |
+| `definition` | Provides the name, description, and parameter schema to the model | Required |
+| `invoke` | Actual execution logic of the Tool | Required |
+
+The selected `scope` directly affects how the Tool enters an AI employee's context:
+
+| `scope` | Usage |
+| --- | --- |
+| `GENERAL` | Shared by all AI employees, usually for general foundational capabilities |
+| `SPECIFIED` | Available only to a Skill or AI employee that binds the Tool |
+| `CUSTOM` | Administrators can add it manually in AI employee configuration and set it to “Ask” or “Allow” |
+
+Use `SPECIFIED` by default. Use `GENERAL` only when every AI employee definitely needs the capability. Use `CUSTOM` when administrators should select it per employee.
+
+## `definition` is written for the model
+
+`definition.description` and `definition.schema` affect whether the model selects the Tool and how it constructs arguments. The description should explain three things:
+
+- When to call the Tool
+- What each argument represents
+- Which tasks the Tool should not handle
+
+Zod is recommended for the parameter schema:
+
+```ts
+schema: z.object({
+  query: z.string().describe('A specific search query.'),
+  limit: z.number().int().min(1).max(20).default(5).describe('Maximum number of records to return.'),
+})
+```
+
+The Tool name must also remain stable. Skills, AI employee configurations, frontend cards, and saved chat messages all locate it by name.
+
+## What `invoke()` receives
+
+A server-side `invoke()` receives three arguments:
+
+```ts
+invoke: async (ctx, args, runtime) => {
+  // ctx：当前 NocoBase action Context
+  // args：模型根据 schema 生成的参数
+  // runtime.toolCallId：当前 ToolCall ID
+  // runtime.writer(chunk)：流式写出中间结果
+}
+```
+
+Through `ctx`, you can access the current application, database, authentication information, and action arguments. For example:
+
+```ts
+const repository = ctx.app.db.getRepository('posts');
+const currentUser = ctx.auth?.user;
+const values = ctx.action?.params?.values;
+```
+
+A Tool should return a structure that clearly indicates success or failure. Built-in Tools commonly use this shape:
+
+```ts
+return {
+  status: 'success',
+  content: result,
+};
+```
+
+For expected business failures, return a clear status and reason instead of making the model guess whether the operation succeeded.
+
+## Directory-based Tools
+
+A Tool can use a directory instead of a single file:
+
+```text
+src/ai/tools/documentSearch/
+├── index.ts
+└── description.md
+```
+
+`index.ts` exports the result of `defineTools()` by default. When `description.md` exists, its entire content overrides `definition.description`, making it suitable for longer Tool instructions.
+
+The directory name `documentSearch` becomes the final registered name.
+
+## Built-in Tool example: `subAgentWebSearch`
+
+`packages/plugins/@nocobase/plugin-ai/src/ai/tools/subAgentWebSearch.ts` demonstrates a complete server-side Tool:
+
+```ts
+export default defineTools({
+  scope: 'SPECIFIED',
+  defaultPermission: 'ALLOW',
+  introduction: {
+    title: '{{t("Web search")}}',
+    about: '{{t("Use web search to quickly find up-to-date information from the internet.")}}',
+  },
+  definition: {
+    name: 'subAgentWebSearch',
+    description: 'Search the web for current information...',
+    schema: z.object({
+      query: z.array(z.string()),
+    }),
+  },
+  invoke: async (ctx, args) => {
+    // 获取 AI 插件和当前会话使用的模型配置。
+    const pluginAI = ctx.app.pm.get('ai') as PluginAIServer;
+    const { model } = ctx.action?.params?.values ?? {};
+    const { provider } = await pluginAI.aiManager.getLLMService({
+      ...model,
+      webSearch: true,
+      reasoning: { mode: 'off' },
+    });
+
+    // 独立查询并行执行，最后统一返回。
+    const result = await Promise.all(
+      args.query.map(async (query) => {
+        const content = await provider.invoke(/* messages */);
+        return { query, result: content.text };
+      }),
+    );
+
+    return { status: 'success', content: result };
+  },
+});
+```
+
+This implementation demonstrates several reusable practices:
+
+- Use `SPECIFIED` to limit the Tool to designated employees or Skills
+- Use Zod to constrain model-generated arguments
+- Read the current AI conversation configuration from `ctx.action.params.values`
+- Put multiple independent queries into one ToolCall and run them concurrently with `Promise.all()`
+- Return structured results with clear provenance for the higher-level model to process
+
+## Related links
+
+- [AI employee plugin development](./index.md) — Choose which capability layer to extend
+- [Define a Skill](./define-skill.md) — Use a Skill to organize the call flow for multiple Tools
+- [Complete example: Create a built-in AI employee](./complete-example.md) — See a runnable Tool example
+- [Add frontend interaction to a Tool](./frontend-tool-ui.md) — Add confirmation and selection UI to a ToolCall