Перейти к основному содержимому

Отладка и тестирование

После написания пользовательского рабочего процесса вы можете использовать следующие методы для его проверки и отладки.

Включение режима отладки​

Включите режим отладки в настройках, чтобы разблокировать дополнительные инструменты отладки и информационные отображения:

Zotero → Настройки → Zotero Agents → Включить режим отладки

Когда режим отладки включен:

  • Рабочие процессы, связанные с отладкой, отображаются на Панели управления
  • Журналы выполнения становятся более подробными
  • Некоторые диагностические инструменты становятся доступными

Использование набора инструментов Debug Probe​

Плагин включает встроенный набор инструментов отладки workflow-debug-probe, содержащий несколько диагностических рабочих процессов:

Рабочий процессНазначение
Workflow Debug ProbeПроверка состояния перед выполнением рабочего процесса, открытие диагностической панели
Debug Sequence Linear ProbeПроверка последовательного выполнения и передачи handoff по умолчанию
Debug Sequence Workspace Reuse ProbeПроверка повторного использования рабочего пространства между шагами
Debug Sequence Context Isolation ProbeПроверка явной фильтрации handoff и изолированных рабочих пространств

Эти рабочие процессы видны в списке рабочих процессов на Панели управления (в режиме отладки) и могут быть запущены напрямую для проверки механизмов выполнения последовательностей.

Просмотр журналов​

Журналы выполнения​

Рабочие процессы генерируют журналы выполнения во время работы, доступные для просмотра на Панели управления:

  1. Откройте Панель управления
  2. Найдите запущенную или завершенную задачу
  3. Нажмите "View Logs", чтобы развернуть панель журналов

Запись журналов в хуках​

export function applyResult({ parent, bundleReader, runtime }) {
  // Запись в журнал выполнения
  runtime.hostApi.logging.appendRuntimeLog({
    level: "info",
    message: `Обработка parent: ${parent}`,
    workflowId: runtime.workflowId,
  });

  // Для сложной отладочной информации можно использовать console
  console.log("Debug:", { parent, workflowId: runtime.workflowId });
}

Устранение распространенных проблем​

Рабочий процесс не отображается на Панели управления​

  1. Проверьте, что workflow.json находится в правильном каталоге
  2. Убедитесь, что workflow.json правильно отформатирован (синтаксис JSON)
  3. Проверьте, что id уникален и не конфликтует с официальными рабочими процессами
  4. Убедитесь, что путь к скрипту applyResult корректен
  5. Проверьте журнал ошибок плагина (Zotero → Справка → Устранение неполадок → Просмотреть файл журнала)

Проверка выбора пропускает каждый элемент​

Если декларативная validateSelection или preflight пропускает каждый входной элемент, рабочий процесс не отправит запрос провайдеру. Проверьте политику выбора, правила исключения и любой результат preflight, возвращающий kind: "skip".

Конфликт между buildRequest и декларативным запросом​

Хук buildRequest и поле request в workflow.json являются взаимоисключающими. Если оба существуют, приоритет имеет buildRequest. Если поведение запроса не соответствует ожидаемому, проверьте, не были ли оба случайно определены одновременно.

Сбой выполнения скрипта хука​

  • Убедитесь, что скрипт хука имеет формат .mjs (ES Module)
  • Убедитесь, что экспортируются правильные имена функций: preflight, buildRequest, normalizeSettings или applyResult
  • Убедитесь, что сигнатура функции корректно принимает параметры, такие как { parent, bundleReader, runtime }
  • Проверьте, что относительные пути импорта корректны

Результат не записывается в Zotero​

Если applyResult использует hostApi.mutations.execute(), но это не вступает в силу, возможные причины:

  • Операции записи требуют подтверждения пользователя, но всплывающее окно подтверждения было проигнорировано или истекло
  • Была предпринята попытка операции записи, когда execution.zoteroHostAccess.required не было установлено в true
  • allowWriteApprovalBypass необходимо использовать совместно с настройкой разрешений плагина

Рекомендации по разработке​

Начните с простого​

  1. Сначала используйте провайдер pass-through с минимальным applyResult, чтобы убедиться, что рабочий процесс успешно загружается
  2. Сначала добавьте validateSelection, затем добавляйте preflight или buildRequest только при необходимости
  3. Наконец, подключитесь к реальному бэкенду

Используйте notifications.toast для быстрой обратной связи​

hostApi.notifications.toast({
  text: `buildRequest получил ${selectionContext.items.parents.length} родительских элементов`,
  type: "default",
});

Это быстрый метод отладки, позволяющий видеть результаты выполнения без проверки журналов.

Обращайтесь к официальным рабочим процессам​

Официальные рабочие процессы — лучший справочный материал для обучения. После установки официального пакета вы можете просмотреть исходный код в каталоге <Zotero Data>/zotero-agents/content/official/workflows/:

  • literature-workbench-package/literature-analysis/ — Полный пример skillrunner.job.v1
  • content/official/workflows/literature-workbench-package/export-notes/ — Простой пример pass-through
  • content/official/workflows/mineru/ — Пример с buildRequest + обработка файлов
  • content/official/workflows/literature-workbench-package/literature-search-ingest/ — Пример интерактивного режима

Следующие шаги​