Zotero Library Agent

Обзор

Zotero Library Agent — это ограниченная поверхность задач по требованию Host Bridge. Она позволяет AI-агентам работать с библиотекой Zotero для конечных запросов — проверять элементы, получать контекст, читать данные литературы и синтеза, выполнять workflow, применять одобренные изменения, передавать файлы и передавать доказательства — не становясь резидентной службой обслуживания библиотеки.

Host Bridge предоставляет три поверхности, каждая из которых выполняет свою роль:

Поверхность	Роль	Когда использовать
CLI Bundle (zotero-bridge)	Установка, подключение и низкоуровневые контракты команд	Необходим прямой CLI-доступ к возможностям Host Bridge
Library Agent	Ограниченное маршрутизация задач, передача доказательств и аудируемые результаты	Есть конечный запрос, требующий маршрутизации намерения и доказательства завершения
Librarian Profile (Hermes)	Резидентный индекс, плановое обслуживание и непрерывное обслуживание библиотеки	Необходимо постоянное локальное индексирование, cron-задачи или непрерывный мониторинг

Что предоставляет Library Agent

• Маршрутизация задач: Направляет текущее намерение к наименьшей подходящей семье команд без необходимости полного сканирования таблицы команд.
• Справочники Journey: Семь подробных справочников Journey охватывают конкретные категории задач, каждый из которых определяет ветви, пограничные случаи, требования к доказательствам, границы одобрения и пути восстановления.
• Передача доказательств: Портативные пакеты доказательств с детерминированной проверкой формы и вычислением дайджестов артефактов.
• Границы полномочий: Обеспечивает, что Host Bridge является единственным путём управления, предотвращая прямой доступ к хранилищу Zotero или поведение фоновой службы.
• Ограниченные операции: Каждая задача завершается, когда запрошенный результат и его доказательства становятся наблюдаемыми — подтверждение отправки или подготовленная передача сами по себе не являются завершением.

Ограниченный поток задач

1. Подтвердить подключение: Проверить загруженный CLI и профиль Host Bridge. Выполнить zotero-bridge surface identity --json для сравнения с упакованным манифестом и подтверждения releaseSetId репозитория.
2. Маршрутизировать намерение: Прочитать справочник маршрутизации задач, чтобы выбрать наименьшую семью команд, удовлетворяющую запрос.
3. Загрузить соответствующий Journey: Прочитать ровно один справочник Journey, соответствующий категории задачи.
4. Сохранить доказательства: Сохранить текущие факты Host, возвращённые дескрипторы, локальные артефакты и состояние одобрения как отдельные доказательства.
5. Выполнить или отправить: Для workflow следовать справочнику выполнения workflow; никогда не отправлять параметры workflow через режим выполнения, который их не принимает.
6. Построить и проверить: Построить финальный пакет доказательств и проверить его с помощью встроенного помощника.

Задача завершена только тогда, когда запрошенный результат и его доказательства наблюдаемы.

Категории Journey

Library Agent включает семь справочников Journey, каждый из которых охватывает конкретную предметную область задач:

Journey	Область
Текущий контекст и чтение библиотеки	Дейктический выбор, поиск против списка, детали элемента, заметки и доказательства вложений
Заметки, вложения и готовность	Фрагменты заметок и payloads, аннотации, готовность PDF/Markdown/анализа и сгенерированные вложения
Контекст синтеза исследований	Темы, виды графа цитирований, индексы, резолверы, артефакты, схемы и очереди внимания
Workflow, принадлежащий Host	Описание workflow, требования, проверка, отправка, мониторинг, разрешения, взаимодействие и доказательства Product
Передача, принадлежащая Agent	Выполнение bundle agent-run, проверка результатов, apply-back и восстановление квитанций
Конкретная запись	Предварительные изменения, семантические команды записи, одобрение и живая проверка
Product и файлы	Локальные пути, зарегистрированные файлы, Product Dashboard, загрузки и доставка вложений

Каждый Journey указывает на встроенные карточки команд CLI zotero-bridge, когда нужны точные поля payload или результата.

Границы полномочий и безопасности

Library Agent устанавливает строгие границы для предотвращения непреднамеренных изменений Zotero:

• Только Host Bridge: Рассматривать Host Bridge как единственный путь управления Zotero и Zotero Agents. Не читать и не записывать напрямую базы данных Zotero, каталоги хранилища, внутренности плагина или состояние браузера.
• Ограниченная работа: Не превращать Library Agent в фоновую службу библиотеки. Выполнять ограниченную работу для текущего запроса и возвращать управление, когда результат или требуемое решение пользователя доступно.
• Запрет необслуживаемых записей: Не выполнять запланированные или необслуживаемые записи. Текущий запрос пользователя и одобрение Host Bridge управляют каждой записью или apply-back.
• Запрет устаревших предположений: Не рассматривать записи кэша, сгенерированные ссылки или пакеты доказательств как живую истину Zotero; при необходимости актуальности подтверждать текущие факты через Host Bridge.

Передача доказательств

Library Agent создаёт портативные пакеты доказательств для непрерывности задач. Пакет доказательств содержит:

• Статус: completed, canceled или failed
• Сводка: Краткие локальные findings задачи
• Файл доказательств (опционально): Построенный и проверенный помощником пакет доказательств, который может быть потреблён другим агентом или задачей
• Диагностика (опционально): Структурированная диагностическая информация

Построить и проверить пакет доказательств с помощью встроенного помощника:

python scripts/zotero_library_agent.py evidence build --input evidence-input.json --output evidence.json
python scripts/zotero_library_agent.py evidence validate --input evidence.json

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

Обработка ошибок

• Сохранять структурированные коды ошибок и поля дескрипторов при сообщении об ошибке.
• Повторно обнаруживать команду или объект только тогда, когда ошибка указывает на устаревший синтаксис или идентичность; не угадывать альтернативные дескрипторы.
• Когда операция возвращает дескриптор файла или путь вывода, проверить объявленный файл перед использованием его в качестве входных данных для доказательства или apply-back.
• Когда отсутствуют требуемые полномочия, ввод или намерение пользователя, остановиться на границе и указать точное отсутствующее решение.

Интеграция

Library Agent зависит от Host Bridge для всего доступа к Zotero. Перед использованием Library Agent:

1. Убедиться, что Host Bridge запущен (Zotero → Настройки → Zotero Agents → Host Bridge → Запустить / Показать конечную точку).
2. Установить CLI zotero-bridge (использовать кнопку Установить CLI на панели настроек Host Bridge).
3. Настроить профиль подключения с URL конечной точки и Bearer-токеном. Подробную настройку см. в Конфигурация Host Bridge.

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

• Host Bridge — полный справочник по CLI zotero-bridge и возможностям Host Bridge
• Hermes Profiles — резидентная служба библиотеки с локальным индексированием и плановым обслуживанием
• Workflows — обзор всех встроенных и пользовательских workflow
• MCP Server — альтернативный интерфейс протокола для MCP-совместимых клиентов