Skip to main content

Агент Таскер

Архитектура ИИ-агента «Секретарь» для Element/Matrix на платформе n8n

1. Оценка реализуемости

На основе анализа документации Matrix API и возможностей n8n, техническое задание полностью реализуемо.

Ключевые технические возможности:

Matrix/Element API поддерживает:

  • ✅ Полное управление комнатами (создание, настройка, права доступа)
  • ✅ Работу с пространствами (Spaces)
  • ✅ Управление ролями и правами (Power Levels)
  • ✅ Отправку и получение сообщений через webhooks
  • ✅ Работу с emoji-реакциями для статусов задач
  • ✅ Управление участниками комнат

n8n предоставляет:

  • ✅ Нативную интеграцию с Matrix через специальный node
  • ✅ AI Agent с LangChain для обработки естественного языка
  • ✅ Интеграцию с OpenAI/Anthropic/другими LLM
  • ✅ Поддержку баз данных для хранения состояния
  • ✅ Планировщик для регулярных задач (cron)
  • ✅ Webhook триггеры для получения сообщений

2. Архитектурные принципы

2.1. Основные принципы проектирования

  1. Модульность - каждая функциональность реализуется отдельным workflow
  2. Масштабируемость - архитектура поддерживает работу с множеством проектов одновременно
  3. Отказоустойчивость - обработка ошибок на каждом уровне
  4. Безопасность - изоляция данных между проектами, шифрование чувствительных данных
  5. Расширяемость - легкое добавление новых типов сообщений и функций
  6. Идемпотентность - повторное выполнение операций не приводит к дублированию

2.2. Архитектурные слои

┌─────────────────────────────────────────────────┐
│           Presentation Layer (Element UI)        │
├─────────────────────────────────────────────────┤
│           Integration Layer (Matrix API)         │
├─────────────────────────────────────────────────┤
│         Processing Layer (n8n Workflows)         │
├─────────────────────────────────────────────────┤
│           AI Layer (LangChain + LLM)            │
├─────────────────────────────────────────────────┤
│         Data Layer (PostgreSQL/MongoDB)          │
└─────────────────────────────────────────────────┘

3. Схема основных компонентов

graph TB
    subgraph "Element/Matrix"
        U[User] --> M[Matrix Server]
        M --> R[Rooms/Spaces]
    end
    
    subgraph "n8n Platform"
        WH[Webhook Receiver] --> MW[Main Workflow]
        MW --> AI[AI Agent<br/>Message Classifier]
        
        AI --> TD[Task Director]
        AI --> ND[Note Director]
        AI --> ID[Idea Director]
        AI --> OD[Onboarding Director]
        
        TD --> TP[Task Processor]
        ND --> NP[Note Processor]
        ID --> IP[Idea Processor]
        OD --> OP[Onboarding Processor]
        
        CRON[Cron Scheduler] --> REM[Reminder Engine]
        CRON --> REP[Report Generator]
        
        TP --> DB[(Database)]
        NP --> DB
        IP --> DB
        OP --> DB
        REM --> DB
        REP --> DB
        
        TP --> MR[Matrix Responder]
        NP --> MR
        IP --> MR
        OP --> MR
        REM --> MR
        REP --> MR
    end
    
    M <--> WH
    MR --> M
    
    style AI fill:#f9f,stroke:#333,stroke-width:2px
    style DB fill:#bbf,stroke:#333,stroke-width:2px

4. Алгоритм обработки сообщений

flowchart TD
    Start([Новое сообщение]) --> Check{@Secretar"Secretar<br/>упомянут?"}
    Check -->|Нет| End([Игнорировать])
    Check -->|Да| Extract[Извлечение данных]
    
    Extract --> Parse[AI парсинг сообщения]
    Parse --> Classify{"Классификация<br/>типа"}
    
    Classify -->|Задача| TaskFlow[Обработка задачи]
    Classify -->|Идея| IdeaFlow[Обработка идеи]
    Classify -->|Заметка| NoteFlow[Обработка заметки]
    Classify -->|Onboarding| OnboardFlow[Обработка onboarding]
    Classify -->|Неопределено| Clarify[Запрос уточнения]
    
    TaskFlow --> ValidateTask{"Данные<br/>полные?"}
    ValidateTask -->|Нет| RequestTask["Запросить<br/>недостающее"]
    ValidateTask -->|Да| CreateTask[Создать задачу]
    CreateTask --> AssignID[Присвоить ID]
    AssignID --> SaveTask[Сохранить в БД]
    SaveTask --> NotifyTask[Уведомить исполнителя]
    
    IdeaFlow --> CheckIdeaRoom{"Комната ИДЕИ<br/>существует?"}
    CheckIdeaRoom -->|Нет| CreateIdeaRoom[Создать комнату]
    CheckIdeaRoom -->|Да| PostIdea[Опубликовать идею]
    CreateIdeaRoom --> PostIdea
    
    NoteFlow --> CheckNoteRoom{"Комната ЗАМЕТКИ<br/>существует?"}
    CheckNoteRoom -->|Нет| CreateNoteRoom[Создать комнату]
    CheckNoteRoom -->|Да| PostNote[Опубликовать заметку]
    CreateNoteRoom --> PostNote
    
    OnboardFlow --> CheckOnboardRoom{"Комната ONBOARDING<br/>существует?"}
    CheckOnboardRoom -->|Нет| CreateOnboardRoom[Создать комнату]
    CheckOnboardRoom -->|Да| PostOnboard[Опубликовать материал]
    CreateOnboardRoom --> PostOnboard
    
    NotifyTask --> Success([Успешно обработано])
    PostIdea --> Success
    PostNote --> Success
    PostOnboard --> Success
    Clarify --> Wait([Ожидание ответа])
    RequestTask --> Wait

5. Структура базы данных

erDiagram
    PROJECTS ||--o{ ROOMS : has
    PROJECTS ||--o{ TASKS : contains
    PROJECTS ||--o{ IDEAS : contains
    PROJECTS ||--o{ NOTES : contains
    PROJECTS ||--o{ ONBOARDING : contains
    PROJECTS ||--o{ USERS : includes
    
    PROJECTS {
        uuid id PK
        string name
        string space_id
        string main_room_id
        json admins
        timestamp created_at
    }
    
    ROOMS {
        uuid id PK
        uuid project_id FK
        string room_id
        string room_type
        string room_name
        timestamp created_at
    }
    
    TASKS {
        uuid id PK
        uuid project_id FK
        string task_number
        text description
        string assignee_id
        datetime deadline
        string status
        string creator_id
        json history
        timestamp created_at
        timestamp updated_at
    }
    
    IDEAS {
        uuid id PK
        uuid project_id FK
        text content
        string author_id
        timestamp created_at
    }
    
    NOTES {
        uuid id PK
        uuid project_id FK
        text content
        string author_id
        timestamp created_at
    }
    
    ONBOARDING {
        uuid id PK
        uuid project_id FK
        text content
        string author_id
        timestamp created_at
    }
    
    USERS {
        uuid id PK
        string matrix_id
        string display_name
        json projects
        json preferences
    }

6. Workflow архитектура в n8n

6.1. Основные workflow модули

graph LR
    subgraph "Входящие сообщения"
        W1[Webhook Listener]
        W2[Message Parser]
        W3[AI Classifier]
    end
    
    subgraph "Обработчики типов"
        T1[Task Handler]
        T2[Idea Handler]
        T3[Note Handler]
        T4[Onboarding Handler]
    end
    
    subgraph "Регулярные задачи"
        C1[Daily Reminder 10:00]
        C2[Deadline Monitor]
        C3[Weekly Report]
        C4[Monthly Analytics]
    end
    
    subgraph "Утилиты"
        U1[Room Creator]
        U2[Space Manager]
        U3[Permission Manager]
        U4[Notification Sender]
    end
    
    W1 --> W2 --> W3
    W3 --> T1
    W3 --> T2
    W3 --> T3
    W3 --> T4
    
    T1 --> U1
    T1 --> U4
    T2 --> U1
    T3 --> U1
    T4 --> U1
    
    C1 --> U4
    C2 --> U4
    C3 --> U1
    C4 --> U1

6.2. Примерная структура Main Workflow

// Псевдокод основного workflow
{
  "nodes": [
    {
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "webhookId": "matrix-messages",
      "httpMethod": "POST"
    },
    {
      "name": "Parse Message",
      "type": "n8n-nodes-base.function",
      "functionCode": `
        // Извлечение данных из Matrix события
        const event = items[0].json;
        return {
          room_id: event.room_id,
          sender: event.sender,
          body: event.content.body,
          msgtype: event.content.msgtype
        };
      `
    },
    {
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "agentType": "toolsAgent",
      "prompt": `
        Классифицируй сообщение как:
        1. Задача (task)
        2. Идея (idea)
        3. Заметка (note)
        4. Onboarding (onboarding)
        
        Извлеки:
        - Тип сообщения
        - Ответственного (@username)
        - Срок выполнения
        - Описание
        
        Сообщение: {message}
      `
    },
    {
      "name": "Router",
      "type": "n8n-nodes-base.switch",
      "rules": [
        {"value": "task", "output": 0},
        {"value": "idea", "output": 1},
        {"value": "note", "output": 2},
        {"value": "onboarding", "output": 3}
      ]
    }
  ]
}

7. Интеграция с Matrix API

7.1. Основные API endpoints

Authentication:
  - POST /_matrix/client/r0/login
  - GET /_matrix/client/r0/account/whoami

Room Management:
  - POST /_matrix/client/r0/createRoom
  - POST /_matrix/client/r0/rooms/{roomId}/join
  - PUT /_matrix/client/r0/rooms/{roomId}/state/m.room.name
  - PUT /_matrix/client/r0/rooms/{roomId}/state/m.room.power_levels

Messaging:
  - PUT /_matrix/client/r0/rooms/{roomId}/send/m.room.message/{txnId}
  - GET /_matrix/client/r0/rooms/{roomId}/messages
  - PUT /_matrix/client/r0/rooms/{roomId}/state/m.room.member/{userId}

Spaces:
  - PUT /_matrix/client/r0/rooms/{roomId}/state/m.space.child/{stateKey}
  - PUT /_matrix/client/r0/rooms/{roomId}/state/m.space.parent/{stateKey}

Reactions:
  - PUT /_matrix/client/r0/rooms/{roomId}/send/m.reaction/{txnId}

7.2. Обработка emoji-статусов

stateDiagram-v2
    [*] --> Новая
    Новая --> В_процессе: 🔄
    В_процессе --> Выполнена: ✅
    В_процессе --> Есть_вопрос: ❓
    В_процессе --> Риск_срыва: ❗
    В_процессе --> Срыв_дедлайна: ⚠️
    В_процессе --> Невозможно: ➖
    
    Есть_вопрос --> В_процессе: Ответ получен
    Риск_срыва --> Групповой_чат: Создать чат
    Срыв_дедлайна --> Запрос_срока: Новый дедлайн
    Невозможно --> Архив: Причина указана
    Выполнена --> Архив: Отчет сформирован

8. Развертывание и конфигурация

8.1. Требования к инфраструктуре

Минимальные требования:
  n8n:
    CPU: 2 cores
    RAM: 4 GB
    Storage: 20 GB
    
  Database:
    Type: PostgreSQL 14+
    RAM: 2 GB
    Storage: 50 GB
    
  Matrix Bot:
    Account: Dedicated bot account
    Permissions: Admin in managed rooms
    
Рекомендуемые требования:
  n8n:
    CPU: 4 cores
    RAM: 8 GB
    Storage: 50 GB
    
  Database:
    Type: PostgreSQL 14+ with replication
    RAM: 4 GB
    Storage: 100 GB
    Backup: Daily snapshots

8.2. Переменные окружения

# n8n Configuration
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=secure_password
N8N_ENCRYPTION_KEY=your_encryption_key
N8N_HOST=0.0.0.0
N8N_PORT=5678
N8N_WEBHOOK_URL=https://your-domain.com/webhook

# Database
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=localhost
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=secretary_bot
DB_POSTGRESDB_USER=secretary
DB_POSTGRESDB_PASSWORD=secure_db_password

# Matrix Configuration
MATRIX_HOMESERVER=https://matrix.your-domain.com
MATRIX_BOT_USER=@secretary:your-domain.com
MATRIX_BOT_ACCESS_TOKEN=your_access_token

# AI Configuration
OPENAI_API_KEY=your_openai_key
# или
ANTHROPIC_API_KEY=your_anthropic_key

9. Безопасность

9.1. Меры безопасности

  1. Аутентификация

    • Использование access token для Matrix API
    • JWT токены для webhook endpoints
    • Rate limiting для защиты от DDoS

  2. Авторизация

    • Проверка прав доступа перед каждой операцией
    • Изоляция данных между проектами
    • Ролевая модель доступа (админ/модератор/участник)

  3. Шифрование

    • TLS для всех API вызовов
    • Шифрование чувствительных данных в БД
    • End-to-end encryption для приватных комнат (опционально)

  4. Аудит

    • Логирование всех операций
    • Мониторинг аномальной активности
    • Регулярные бэкапы

10. Мониторинг и отладка

10.1. Метрики для мониторинга

Системные метрики:
  - CPU использование
  - RAM использование
  - Disk I/O
  - Network latency

Бизнес-метрики:
  - Количество обработанных сообщений/час
  - Среднее время обработки сообщения
  - Количество активных проектов
  - Количество созданных задач/день
  - Процент выполненных задач вовремя

Метрики ошибок:
  - Количество ошибок классификации
  - Количество таймаутов API
  - Количество необработанных сообщений

10.2. Система логирования

// Структура логов
{
  "timestamp": "2025-01-20T10:00:00Z",
  "level": "INFO|WARN|ERROR",
  "workflow": "main_processor",
  "node": "ai_classifier",
  "project_id": "uuid",
  "room_id": "!abc:matrix.org",
  "message": "Task classified successfully",
  "metadata": {
    "task_id": "T-001",
    "assignee": "@user:matrix.org",
    "deadline": "2025-01-25T18:00:00Z"
  }
}

11. Roadmap развития

Фаза 1: MVP (1-2 месяца)

  • ✅ Базовая обработка сообщений
  • ✅ Классификация типов сообщений
  • ✅ Создание и управление задачами
  • ✅ Ежедневные напоминания
  • ✅ Базовые отчеты

Фаза 2: Расширение (2-3 месяца)

  • 🔄 Управление пространствами
  • 🔄 Расширенная аналитика
  • 🔄 Интеграция с внешними системами (Jira, Trello)
  • 🔄 Веб-интерфейс для настройки

Фаза 3: Enterprise (3-6 месяцев)

  • 📋 Multi-tenancy
  • 📋 SSO интеграция
  • 📋 Расширенные права доступа
  • 📋 API для внешних интеграций
  • 📋 Machine Learning для улучшения классификации

Заключение

Архитектура ИИ-агента «Секретарь» обеспечивает полную реализацию требований технического задания с использованием современных технологий и лучших практик. Модульная структура позволяет легко расширять функциональность и адаптировать систему под специфические требования организаций.

Back to top