SDK @eva/*

Справочник по пакетам SDK, которые платформа подставляет в каждый пакет: навыки, контекст, виджеты, статус агента, вызов модели и пути рабочей папки.

Пакеты SDK ставить из npm не нужно. Объявите их в dependencies со значением "*", платформа подставит свои реализации при запуске.

Пакет	Для чего
@eva/skill-sdk	Объявить навыки: defineSkill
@eva/context	Контекст текущего вызова: getContext
@eva/widget-sdk	HTTP-сервер виджетов: createWidgetServer
@eva/agent-sdk	Статус, лог и уведомления из долгой работы: reportStatus, appendLog, notify
@eva/agent-chat-sdk	Вызвать модель из пакета: complete
@eva/artifacts	Пути рабочей папки: workspacePath, workInPath, workOutPath

@eva/skill-sdk

import { defineSkill } from '@eva/skill-sdk';

export default defineSkill({
  async my_open_issues({ limit = 20 }, ctx) {
    return { items: await search(ctx.settings, limit) };
  },
});

Ключи объекта совпадают с eva.tools[].name. Подробнее: Пакеты навыков.

@eva/context

import { getContext } from '@eva/context';

const { settings, logger, signal, invocationId, chatSessionId } = getContext();

Поле	Что это
settings	Настройки пакета. В навыке уже с личными значениями пользователя
logger	Лог вызова или сервиса
signal	AbortSignal: пользователь остановил ответ или сервис останавливается
invocationId	Идентификатор вызова навыка
chatSessionId	Чат, из которого вызван навык, если вызов из чата

Передавайте signal в fetch, чтобы долгие запросы прерывались вместе с ответом.

@eva/widget-sdk

import { createWidgetServer } from '@eva/widget-sdk';

export async function main(ctx) {
  const app = createWidgetServer(ctx);
  app.serve('public');
  app.get('/api/items', (req, res) => res.json(listItems(req.ctx.settings)));
  await app.listen();
}

Обработчики получают (req, res, requestCtx). Личные настройки пользователя доступны в req.ctx.settings. Подробнее: Виджеты.

@eva/agent-sdk

import { reportStatus, appendLog, notify } from '@eva/agent-sdk';

await reportStatus({ phase: 'sync', message: 'Загружаю задачи', percent: 40 });
await appendLog('Загружено 120 задач');
await notify({ title: 'Синхронизация завершена', message: '120 задач', open: { page: 'widgets' } });

notify показывает системное уведомление в EVA Desktop. Поле open задаёт, какой экран открыть по клику, например chat, agentJob, widgets или packageSettings. В облаке уведомление не показывается.

@eva/agent-chat-sdk

import { complete } from '@eva/agent-chat-sdk';

const { text } = await complete({
  taskId: 'summarize',
  messages: [{ role: 'user', content: 'Кратко перескажи: ...' }],
});

taskId совпадает с eva.llmTasks[].id манифеста. Вызов работает только там, где платформа подключила к пакету доступ к моделям. Без него complete завершается ошибкой, поэтому предусмотрите запасной путь или вынесите работу с моделью в шаг агента.

@eva/artifacts

import { workInPath, workOutPath } from '@eva/artifacts';

const input = workInPath('report.docx');
const output = workOutPath('report.pdf');

Входные файлы агента лежат в /work/in, результаты кладите в /work/out: они появятся в артефактах запуска.

Контекст фонового сервиса

main(ctx) получает корневой контекст сервиса:

Поле	Что это
ctx.settings	Только общие настройки и шаблоны без данных пользователя
ctx.db	База SQLite пакета
ctx.startAgentJob(agentId, input)	Запустить агента
ctx.notify(...)	Уведомление в Desktop
ctx.logger, ctx.signal	Лог и сигнал остановки
ctx.packageId, ctx.packageRoot	Идентификатор и папка пакета