aatex-messenger - SKILL.md Agent Skill

name: aatex-messenger description: Мессенджер ЦУП ААТех — чаты, сообщения, каналы. Применяй для "отправь сообщение", "напиши в чат", "прочитай чат", "сколько непрочитанных", "создай канал", "добавь в группу", "поиск по переписке". Поддерживает DM, группы, каналы, файлы через upload_message_file.

Мессенджер ЦУП ААТех

Когда использовать

Отправить сообщение пользователю или в группу/канал
Прочитать историю чата
Создать новый чат
Проверить непрочитанные
Искать по тексту сообщений
Добавить людей в группу/канал
Прикрепить файл к сообщению

Типы бесед

Тип	Участники	Когда использовать
`dm`	2 (личка)	Один на один
`group_dm`	3+ (приватная группа)	Рабочая группа
`channel`	Много (публично в орге)	Обсуждения, темы, объявления
`saved`	1 (только вы)	Заметки себе

Инструменты

Инструмент	Параметры	Назначение
`list_conversations`	`type?`	Беседы (фильтр по типу)
`list_messages`	`conversationId, limit?, before?`	История (курсорная пагинация)
`send_message`	`conversationId, content, attachmentIds?`	Отправить
`create_conversation`	`type, targetUserId?\|userIds?\|name, ...`	Создать чат
`get_unread_summary`	—	Сводка непрочитанных по всем
`add_conversation_participants`	`conversationId, userIds`	Добавить людей
`search_messages`	`query, conversationId?, limit?`	Поиск по тексту

Сценарии

1. Написать сообщение конкретному человеку (DM)

1. list_users(search="Иван") → userId = "uid_abc"
2. list_conversations(type: "dm") → проверь, есть ли уже DM
   # DM найти можно по type="dm" и одному из участников

3a. Если DM есть:
    send_message(conversationId, content)

3b. Если DM нет:
    create_conversation(type: "dm", targetUserId: "uid_abc") → conversationId
    send_message(conversationId, content)

Оптимизация: create_conversation(type: "dm") идемпотентен — если DM уже существует, вернёт существующую. Можно смело вызывать.

2. Создать групповой чат

1. list_users(search="...") → несколько userIds
2. create_conversation(
     type: "group_dm",
     userIds: ["uid1", "uid2", "uid3"],
     name: "Проект X - команда"
   )
   → conversationId
3. send_message(conversationId, "Привет, команда!")

3. Создать канал

create_conversation(
  type: "channel",
  name: "production-news",
  description: "Новости производства",
  isPrivate: false,       // true — только по приглашению
  userIds: ["..."]         // начальные участники (optional)
)

4. Прочитать последние сообщения

list_messages(conversationId, limit: 50)
→ массив сообщений (новые сверху)

5. Пагинация — более старые

# Первая страница:
list_messages(conversationId, limit: 50)
→ последнее сообщение id = "msg_xxx"

# Следующая (ещё старее):
list_messages(conversationId, limit: 50, before: "msg_xxx")

6. Сводка непрочитанных

get_unread_summary

Возвращает:

{
  "totalUnread": 17,
  "conversations": [
    {"conversationId": "...", "name": "Проект X", "type": "group_dm", "unreadCount": 8},
    ...
  ]
}

Отсортировано по unreadCount убыв. — первые самые «горящие».

7. Поиск по тексту

search_messages(query: "договор", limit: 20)
→ массив сообщений из всех чатов, где вы участник

Ограничить поиск одним чатом:

search_messages(query: "срок", conversationId: "...")

8. Добавить участников в группу

add_conversation_participants(
  conversationId: "...",
  userIds: ["uid1", "uid2"]
)

Работает для group_dm и channel. Для dm нельзя — только 2 участника.

9. Отправить с файлом

1. Прочитать файл локально и закодировать в base64
2. upload_message_file(
     conversationId,
     fileName: "contract.pdf",
     mimeType: "application/pdf",
     base64Content: "<base64>"
   ) → attachmentId
3. send_message(
     conversationId,
     content: "Вот договор",
     attachmentIds: [attachmentId]
   )

Лимит: ~20 МБ на файл.

Важные нюансы

Socket.io + push

send_message автоматически:

Создаёт сообщение в БД
Эмитит socket event в комнату беседы
Отправляет push-уведомления участникам (fire-and-forget)

Сообщение сразу видно всем участникам в UI в реальном времени.

Типы сообщений

message.type:

text — обычное
file — с прикреплёнными файлами (ставится автоматически при attachmentIds)
system — системное (создание чата, добавление участников)
bot — от бота
call — звонок (метаданные в metadata)

Через MCP отправляются только text и file.

Непрочитанные

MCP не отмечает сообщения как прочитанные автоматически. Если прочитал через list_messages — счётчик не изменится. Для отметки прочитанным — только UI.

Поиск — ilike по содержимому

search_messages использует ILIKE '%query%' по messages.content. Не fuzzy, не морфология — точное вхождение. Для русского может потребоваться попробовать разные формы слова.

Права доступа к беседам

dm, group_dm — видны только участникам
channel public — все в орге
channel private — только приглашённые
Все операции проверяют conversationMembers

Типичные ошибки

Ошибка	Причина
`targetUserId is required for dm type`	Забыл `targetUserId` в create_conversation для dm
`userIds is required for group_dm type`	Забыл `userIds` для group_dm
`name is required for channel type`	Забыл `name` для канала
`You are not a member of this conversation`	Нет доступа к беседе
`File too large`	> 20 МБ в `upload_message_file`

Связь с другими скиллами

aatex-files — работа с файлами в сообщениях
aatex-cards — list_users для поиска получателя (тот же инструмент)

Пример диалога

Пользователь: «Напиши Петру в личку, что заказ №42 готов»

1. list_users(search="Пётр")
   → [{id: "uid_petr", name: "Пётр Петров"}, ...]
2. create_conversation(type: "dm", targetUserId: "uid_petr")
   → { id: "conv_abc", type: "dm", ... }  (или существующая)
3. send_message(
     conversationId: "conv_abc",
     content: "Пётр, заказ №42 готов ✓"
   )
   → отправлено