Пакеты навыков

Как написать пакет навыков: манифест с инструментами, обработчики на defineSkill, настройки с секретами и шаблонами, области видимости и работа с файлами пространства.

Пакет навыков это npm-пакет с eva.kind: "skills". Он объявляет инструменты в манифесте и реализует их на JavaScript. Модель вызывает их в чате, оркестратор в агентах.

Манифест

{
  "name": "invoice-tools",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": { "@eva/skill-sdk": "*" },
  "eva": {
    "kind": "skills",
    "title": "Счета",
    "description": "Разбор и проверка счетов",
    "scopes": ["chat", "agent"],
    "tools": [
      {
        "name": "parse_invoice",
        "title": "Разобрать счёт",
        "description": "Извлекает реквизиты и суммы из файла счёта",
        "inputSchema": {
          "type": "object",
          "properties": { "path": { "type": "string", "description": "Путь к файлу в пространстве" } },
          "required": ["path"]
        }
      }
    ],
    "settings": {
      "type": "object",
      "required": ["api_token"],
      "properties": {
        "api_token": { "type": "string", "format": "password", "title": "Токен API" },
        "locale": { "type": "string", "x-eva-scope": "user", "title": "Язык отчёта" }
      }
    }
  }
}

Поле	Смысл
name	Домен пакета: mail, invoice-tools. Не одно действие
eva.tools[].name	Действие: send_message, parse_invoice
eva.tools[].description	По описанию модель решает, когда вызвать навык. Пишите конкретно
eva.tools[].inputSchema	JSON Schema аргументов. Аргументы проверяются до вызова
eva.scopes	Где виден пакет: chat, agent, studio

Как пакет выглядит для пользователей, видно в каталоге, например Jira или Exchange.

Код

import { defineSkill } from '@eva/skill-sdk';
import { readFile } from 'node:fs/promises';

export default defineSkill({
  async parse_invoice({ path }, ctx) {
    const text = await readFile(path, 'utf8');
    const total = /Итого:\s*([\d\s,.]+)/.exec(text)?.[1];
    return { ok: true, total, locale: ctx.settings.locale ?? 'ru' };
  },
});

• Имена в defineSkill совпадают с eva.tools[].name.
• Обработчик получает (args, ctx) и возвращает JSON.
• Исключение становится ошибкой инструмента, модель её увидит и сможет отреагировать.
• Путь относительно рабочей папки ведёт в пространство чата.

Настройки

Маркер	Что делает
x-eva-scope: "global"	Общее значение, задаёт администратор. По умолчанию
x-eva-scope: "user"	Личное значение, каждый пользователь вводит своё
format: "password" или x-eva-secret	Секрет: хранится зашифрованным, в интерфейсе не показывается
x-eva-template: true	Шаблон для общих несекретных полей: {{settings.key}}, {{user.login}}, {{user.name}}
x-eva-sections	Группировка полей по разделам в форме настроек

Если обязательной личной настройки нет, модель не вызывает пакет, а пользователь видит форму Нужны ваши настройки. После сохранения тот же вызов продолжается.

Шаблоны удобны для логинов: если логин в почте совпадает с логином в EVA, задайте его шаблоном {{user.login}}, и каждому пользователю останется ввести только свой пароль.

Как навыки называются в каталоге

• Один инструмент в пакете: в каталоге навык называется именем пакета.
• Несколько инструментов: пакет.инструмент, например jira.run_jql.

Доступ к навыкам по группам задаётся отдельно в Навыки → Доступ.