Поиск задач (work packages) в OpenProject.

Поиск по теме выполняется по синонимам: передавайте сразу несколько вариантов формулировки в subject (строка или список). Пример: subject=["баг", "ошибка"]. Не добавляйте перевод/транслитерацию автоматически — только если пользователь явно попросил.

Логика поиска по subject:

1. Ищем по теме задачи (фильтр subject ~) по очереди для каждого синонима, результаты объединяем (логическое ИЛИ), дедуплицируем по id.

2. Если по теме ничего не найдено — автоматически повторяем поиск по описанию задачи (фильтр description ~), если сервер его поддерживает.

Прочие параметры (project_id, status, type_id и т.д.) сужают область поиска (объединение И с условием по теме/описанию).

Если совпадений нет, возвращается пустой список с подсказкой переформулировать запрос — полный список задач НЕ выдаётся.

Args: subject: Тема задачи или список синонимов (строка либо список строк). Поиск по части темы (оператор содержания '~'), объединение ИЛИ между синонимами. Пример: "баг" или ["баг", "ошибка", "дефект"]. project_id: Фильтр по проекту; если задан — поиск ведётся в рамках проекта. status: Семантический статус: 'open' (открытые), 'closed' (закрытые), 'all'. type_id: Фильтр по типу задачи (например '1' для Task, '2' для Bug). assignee_id: Фильтр по исполнителю (ID пользователя или 'me'). priority_id: Фильтр по приоритету. filters: Произвольный JSON-массив фильтров API, например [{"status_id":{"operator":"o","values":null}}]. Объединяется (AND) с другими параметрами. Используется, когда не задан subject (поиск без текста), либо как доп. ограничение. page_size: Размер страницы (по умолчанию 20, максимум 100). При поиске по subject применяется к каждому синониму отдельно. offset: Номер страницы, начиная с 1. При поиске по subject игнорируется (возвращаются все найденные совпадения, дедуплицированные). sort_by: JSON-массив сортировки, например [["status","asc"],["id","desc"]].

Returns: JSON со списком задач (компактный вид) и сводкой. При поиске по синонимам добавляются поля searched_field (subject/description), matched_terms (сработавшие синонимы) и fallback_used. При пустом результате — список [] и note с подсказкой.

Получить список проектов и подпроектов в OpenProject.

Поиск по имени (параметр name) выполняется по синонимам: передавайте сразу несколько вариантов формулировки (строка или список). Пример: name=["демо", "тестовый"]. Не добавляйте перевод/транслитерацию автоматически — только если пользователь явно попросил.

Логика поиска по имени:

1. Ищем по имени проекта (фильтр name ~) по очереди для каждого синонима, результаты объединяем (ИЛИ), дедуплицируем по id.

2. Если по имени ничего не найдено и include_description_fallback=True — повторяем поиск по описанию проекта (фильтр description ~).

Режимы работы (без учёта name):

• Без parent_id и as_tree: плоский список всех видимых проектов.

• С parent_id: подпроекты. direct_children_only=False (по умолчанию) — фильтр ancestor, всё поддерево потомков любой глубины; direct_children_only=True — фильтр parent_id, только прямые дети.

• as_tree=True: запрашивает все видимые проекты и собирает дерево иерархии в памяти по _links.parent. При as_tree параметр name игнорируется (дерево строится по всем проектам).

Если совпадений по name нет, возвращается пустой список с подсказкой.

Args: parent_id: ID проекта-родителя. Если задан — вернуть его подпроекты. Игнорируется при as_tree=True. direct_children_only: True → только прямые дети parent_id (фильтр parent_id). False → всё поддерево потомков (фильтр ancestor). active: Фильтр по активности: True → только активные, False → только архивированные. None → без фильтра. name: Имя проекта или список синонимов (строка либо список строк). Поиск по части имени (оператор '~'), объединение ИЛИ между синонимами. Пример: "демо" или ["демо", "тест"]. include_description_fallback: True (по умолчанию) — если поиск по имени пуст, повторить по описанию. False — искать только по имени. filters: Произвольный JSON-массив фильтров API, например [{"public":{"operator":"=","values":["t"]}}]. Объединяется (AND) с другими параметрами. page_size: Размер страницы (по умолчанию 50). Игнорируется при as_tree и при поиске по name. offset: Номер страницы, начиная с 1. Игнорируется при as_tree и при поиске по name. sort_by: JSON-массив сортировки, например [["name","asc"]]. Допустимые поля: id, name, typeahead, created_at, public, latest_activity_at, required_disk_space. as_tree: True — вернуть дерево иерархии проектов вместо плоского списка (игнорирует parent_id/name/пагинацию).

Returns: JSON со списком проектов (компактный вид) и сводкой. При поиске по синонимам добавляются поля searched_field, matched_terms, fallback_used. При as_tree — дерево {'projects': [<узел>]}. При пустом результате — список [] и note с подсказкой.

Получить детальную информацию о задаче по её ID.

Args: work_package_id: Идентификатор задачи. include_comments: Если True — дополнительно подгрузить последние комментарии. include_attachments: Если True — дополнительно подгрузить список вложений.

Returns: JSON с полными полями задачи (тема, описание, тип, статус, даты, оценки времени, автор, ответственный, ссылки на действия) и, опционально, комментариями/вложениями.

Добавить комментарий (заметку) к задаче.

Args: work_package_id: Идентификатор задачи. comment: Текст комментария. internal: True для внутреннего комментария (требует права add_internal_comments).

Returns: JSON с созданной активностью (id, текст, автор, дата).

Загрузить файл как вложение к задаче.

OpenProject требует multipart/form-data ровно из двух частей: 'metadata' (JSON {fileName}) и 'file' (сырые байты).

Args: work_package_id: Идентификатор задачи. file_path: Абсолютный путь к локальному файлу, который нужно загрузить. file_name: Имя файла для сохранения (по умолчанию берётся из file_path).

Returns: JSON с созданным вложением (id, fileName, fileSize, contentType, ссылка).

Получить список доступных активностей учёта времени (Time Entry Activities).

Активность может быть обязательна при записи времени. Используйте ID/title из этого списка в параметре activity_id инструмента op_log_time.

Если список пуст или возвращена ошибка 404 — модуль учёта времени («Time and costs», либо «Time tracking activities» в Administration) не включён/не настроен на сервере.

Returns: JSON со списком активностей: [{id, title, ...}].

Записать затраченное время к задаче (time entry).

Требует, чтобы в проекте задачи был включён модуль «Time and costs» и у роли пользователя было право «Log time».

Args: work_package_id: Идентификатор задачи. hours: Затраченное время. Принимает человекочитаемые формы: '1.5h', '2h30m', '90m', '1:30', 'PT1H30M'. activity_id: ID активности учёта времени (из op_list_time_entry_activities). Необязательно: если не задан, используется активность по умолчанию (или сервер отклонит, если активности обязательны и не настроены). spent_on: Дата в формате YYYY-MM-DD (по умолчанию — сегодня). comment: Необязательный комментарий к записи времени.

Returns: JSON с созданной записью времени (id, hours, spentOn, activity, ...).

Отчёт по записям времени (time entries) за период.

Возвращает записи сгруппированными по проектам, с суммой часов по каждому проекту и общим итогом. Удобно для ответов вида «покажи время по мне за июль, сгруппированное по проектам, и общее количество часов».

Args: user_id: ID пользователя или 'me' (текущий). OpenProject принимает 'me' напрямую в фильтре user_id. project_id: Фильтр по проекту (числовой ID). date_from: Начало периода (YYYY-MM-DD, включительно). date_to: Конец периода (YYYY-MM-DD, включительно). Границы диапазона передаются в фильтр spent_on оператором <>d; агент считает границы месяца/недели сам («за июль» → 2026-07-01..2026-07-31). activity_id: Фильтр по активности учёта времени (ID). filters: Произвольный JSON-массив фильтров API, например [{"entity_id":{"operator":"=","values":["5"]}}]. Объединяется (AND) с другими параметрами. include_comments: True (по умолчанию) — выводить текст комментария каждой записи; False — только цифры (id, hours, дата, задача, активность), без комментариев. Компактнее для сводок. page_size: Размер страницы (по умолчанию 100). ВНИМАНИЕ: итог и группировка корректны только если выгружены ВСЕ записи периода — при total > возвращенного в ответе будет предупреждение, что итог неполон. Для полного отчёта увеличьте page_size. offset: Номер страницы, начиная с 1. sort_by: JSON-массив сортировки, по умолчанию [["spent_on","asc"], ["id","asc"]]. Допустимые поля: id, hours, spent_on, created_at, updated_at.

Returns: JSON: period, filters_applied, total (entries + hours ISO/decimal), by_project [{project, project_id, entries_count, hours, entries}], pagination. При total > count — note о неполном итоге.

Поиск пользователей по имени или логину.

Люди обращаются друг к другу по именам, а не по номерам. Этот инструмент помогает найти ID пользователя (например, для передачи в op_list_time_entries параметром user_id). Ищет по имени и логину (оба — оператор содержания).

Требует прав на чтение списка пользователей; при их отсутствии вернёт ошибку с подсказкой.

Args: query: Подстрока имени или логина (ищет и по name, и по login). filters: Произвольный JSON-массив фильтров API, например [{"status":{"operator":"=","values":["active"]}}]. Объединяется (AND) с query. page_size: Размер страницы (по умолчанию 50). offset: Номер страницы, начиная с 1.

Returns: JSON со списком пользователей [{id, name, login, email, self}] и сводкой пагинации.

Проверить соединение с OpenProject и корректность API-токена.

Returns: JSON с результатом: ok=true/false и информацией об экземпляре/пользователе.