#Desenvolvimento de plugins para funcionários de IA

No NocoBase, um plugin pode disponibilizar suas próprias capacidades de negócio aos funcionários de IA. Três pontos de extensão cuidam de camadas diferentes:

• Tool (ferramenta) — executa operações específicas, como consultar dados, chamar APIs e alterar registros
• Skill (habilidade) — informa ao modelo quando usar as ferramentas e quais etapas seguir para concluir uma tarefa
• Funcionário de IA integrado (Built-in AI Employee) — reúne perfil, prompt de sistema, habilidades e ferramentas em um funcionário pronto para uso

Normalmente, não é necessário chamar manualmente uma API de registro. Depois que os arquivos são colocados nos diretórios convencionais de src/ai do plugin, o NocoBase faz a varredura e o registro durante o carregamento. Somente quando uma Tool precisa de cartão personalizado, modal ou lógica de execução no navegador é necessário registrar o componente ou a lógica correspondente em src/client-v2/plugin.tsx.

Antes de começar, verifique se o aplicativo tem o @nocobase/plugin-ai instalado e habilitado. O código do plugin pode usar os tipos e as funções de definição fornecidos por @nocobase/ai e @nocobase/actions.

#Índice rápido

#Primeiro, decida qual camada será ampliada

Tool, Skill e funcionário de IA integrado não são três recursos independentes. Eles formam capacidades combinadas, camada por camada, de baixo para cima. Nem todo plugin precisa implementar as três camadas.

Tool: permite que a IA execute uma ação específica
  ↓
Skill: orienta a IA a concluir um tipo de tarefa seguindo um método definido
  ↓
Funcionário de IA integrado: reúne essas capacidades em um papel fixo e um ponto de acesso

Escolha a camada inicial de acordo com a necessidade:

• Se a IA só precisa consultar dados, chamar uma API ou alterar registros, basta definir uma Tool
• Se for necessário definir a ordem de chamada das ferramentas, as etapas de confirmação e o formato de saída, crie também uma Skill para essas Tools
• Se o plugin deve oferecer diretamente um papel fixo quando for habilitado, crie também um funcionário de IA integrado e vincule a Skill e as Tools correspondentes

Quando as três camadas são usadas, uma tarefa é executada nesta ordem:

1. O usuário envia uma tarefa ao funcionário de IA
2. O funcionário de IA determina qual Skill usar com base no prompt de sistema
3. A Skill informa ao modelo quais Tools chamar e em que ordem
4. A Tool executa uma consulta, gravação ou solicitação externa e retorna o resultado
5. O funcionário de IA organiza a resposta final com base no resultado da Tool

O cartão de uma Tool no frontend não é uma quarta camada. Ele apenas adiciona uma interface de interação ao ToolCall quando a Tool precisa que o usuário confirme, selecione uma opção ou edite parâmetros.

#Coloque os recursos de IA em src/ai

O NocoBase encontra os recursos de IA de um plugin conforme a convenção de diretórios. Em uma estrutura padrão de plugin, basta colocar Tools, Skills e funcionários de IA integrados em src/ai; não é preciso registrá-los um a um em src/server/plugin.ts, dentro de load().

Uma estrutura completa pode ser organizada assim:

src/ai/
├── tools/
│   └── searchDocs.ts
├── skills/
│   └── document-search/
│       ├── SKILLS.md
│       └── tools/
│           └── readDocument.ts
└── ai-employees/
    ├── translator.ts
    └── developer/
        ├── index.ts
        ├── prompt.md
        ├── skills/
        └── tools/

Cada local corresponde a uma forma de registro:

Ao carregar o plugin, o NocoBase conclui as seguintes etapas, nesta ordem, antes de executar o método load() do próprio plugin:

1. Faz a varredura e registra as Tools
2. Analisa SKILLS.md e vincula as Tools do diretório da Skill à Skill correspondente
3. Carrega o funcionário de IA integrado e combina o prompt.md, as Skills e as Tools presentes no diretório do funcionário

src/client-v2 não faz parte desses diretórios de varredura automática. Um registro adicional em src/client-v2/plugin.tsx só é necessário quando a Tool precisa de cartão, modal ou lógica de execução no navegador.

#Referência rápida de pontos de extensão e diretórios

Por padrão, implemente primeiro a Tool. Adicione uma Skill quando precisar de um fluxo de trabalho fixo e crie um funcionário de IA integrado quando precisar de um papel fixo; adicione um cartão no frontend somente se a Tool exigir interação no navegador.

#Links relacionados

• Escrever seu primeiro plugin — crie e execute um plugin NocoBase do zero
• Visão geral dos funcionários de IA — conheça os pontos de acesso dos funcionários de IA
• Guia de engenharia de prompts — escreva prompts de sistema e restrições de tarefas