Введение в MagiClaw: команда научных AI-агентов в Feishu, где совместная работа возникает естественно

Настройка за 15 минут｜Нативный опыт Feishu｜Оркестрация research Agent｜Базис EvoMaster — расширение в один клик

---

Обзор проекта

MagiClaw — это платформа AI-агентов, работающая внутри Feishu. Главная идея проекта такова: не нужно создавать отдельный инструмент, который вы специально открываете — вместо этого AI-агенты встраиваются прямо в Feishu, которым вы пользуетесь каждый день. В групповых или личных чатах вы описываете задачу, а команда интеллектуальных агентов сразу начинает работать.

За MagiClaw стоит фреймворк EvoMaster: лёгкая инфраструктура Agent’ов, отвечающая за вызов инструментов, Skills-навыки, управление памятью и соединение сессий. Это означает, что вы можете сосредоточиться на «том, что должен сделать агент», а не на многократной сборке инженерных слоёв. Весь проект с открытым исходным кодом (Apache 2.0), объём кода небольшой — легко выполнять доработки.

---

Портрет целевой аудитории

Эта статья адресована следующим разработчикам:

• Есть базовые знания Python, вы знакомы с Feishu или Lark и хотите встроить AI-возможности прямо в повседневное общение команды
• Вам интересны сценарии AI for Science и вы ищете масштабируемую инфраструктуру research-агентов
• Вы уже используете EvoMaster или аналогичный Agent-фреймворк и хотите расширить Feishu как слой пользовательского взаимодействия (frontend)

Если вы ищете автономный «набор» для research-агентов целиком, MagiClaw — не тот ответ. Он подключает экосистему EvoMaster к Feishu, чтобы исследовательские рабочие процессы естественно «заводились» внутри ваших командных инструментов коммуникации.

---

Ключевые зависимости и окружение

---

Полное дерево структуры проекта

MagiClaw/
├── evomaster/                    # основная библиотека фреймворка
│   ├── agent/                   # базовый класс Agent и runtime
│   ├── core/                    # основные вызовы инструментов, диспетчеризация задач
│   ├── interface/
│   │   └── feishu/             # реализация интерфейса Feishu (долгое соединение, Webhook)
│   ├── memory/                  # персистентное хранилище памяти
│   ├── skills/                  # наборы навыков (Skills), пригодные для повторного использования
│   └── scheduler/               # планировщик для многозадачной диспетчеризации
├── playground/
│   ├── magiclaw/               # диалоговый интеллект-агент Feishu по умолчанию
│   ├── agent_builder/           # meta-агент: дизайн / генерация новых Agent
│   ├── coding_agent/            # Agent, ориентированный на написание кода
│   ├── report_writer_agent/     # Agent, ориентированный на написание отчётов
│   └── web_search_agent/        # Agent, ориентированный на поиск по веб-страницам
├── configs/
│   ├── feishu/                  # учётные данные для подключения Bot Feishu
│   │   └── config.yaml
│   ├── magiclaw/               # конфигурация LLM, инструментов, MCP, памяти
│   │   └── config.yaml
│   └── agent_builder/           # конфигурация двух meta-агентов: планирование + сборка
├── run.py                       # точка входа для быстрого старта (CLI)
├── requirements.txt
└── pyproject.toml

---

Пошаговая установка

Шаг 1: клонировать код

git clone https://github.com/sjtu-sai-agents/MagiClaw.git
cd MagiClaw

Шаг 2: установить зависимости

pip install -r requirements.txt

Или через uv (быстрее):

uv pip install -r requirements.txt

Шаг 3: создать приложение в Feishu

1. Откройте Feishu Open Platform, войдите под учётной записью вашей команды
2. Нажмите Создать приложение, разработанное в компании, укажите название и описание
3. После входа в приложение в левом меню выберите Добавить возможности приложения, отметьте Бот

Шаг 4: настроить учётные данные приложения

Скопируйте шаблон переменных окружения:

cp .env.template .env

В .env заполните реквизиты, предоставленные Feishu Open Platform:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Шаг 5: импортировать диапазоны прав

В Feishu Open Platform перейдите в Управление правами → Массовый импорт/экспорт прав, вставьте следующий JSON:

{
  "scopes": {
    "tenant": [
      "im:resource",
      "docx:document",
      "docx:document:readonly",
      "drive:drive",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "wiki:wiki:readonly"
    ],
    "user": [
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive.version",
      "drive:drive.version:readonly"
    ]
  }
}

Шаг 6: настроить подписку на события

В разделе События и обратные вызовы → Конфигурация событий выберите Получение событий через долгие соединения, добавьте следующие события:

В разделе Конфигурация обратных вызовов также выберите долгие соединения и подпишитесь на:

Шаг 7: настроить LLM

Отредактируйте configs/magiclaw/config.yaml и заполните ваши учётные данные LLM:

llm:
  provider: openai              # или anthropic / custom
  model: gpt-4o
  api_key: sk-...               # из .env или напрямую в конфигурационном файле
  base_url: https://api.openai.com/v1  # опционально, для настройки собственного endpoint

Шаг 8: опубликовать приложение и запустить

В Feishu Open Platform в Управление версиями и публикация создайте версию и опубликуйте её, чтобы Bot начал работать.

Затем запустите робота:

python -m evomaster.interface.feishu --config configs/feishu/config.yaml

После успешного запуска отправьте Bot сообщение в Feishu — он ответит. По умолчанию он выступает как универсальный агент диалогов: поддерживает многоходовой контекст и память.

---

Архитектура с двумя ключевыми Agent

Настоящие возможности MagiClaw появляются благодаря совместной работе двух встроенных Playground: magiclaw отвечает за повседневные диалоги, а agent_builder помогает вам создавать новые специализированные интеллектуальные агенты.

magiclaw: оркестратор диалогов Feishu

magiclaw — это диалоговый агент Feishu по умолчанию, который обладает ключевой способностью — оркестрация и делегирование.

Когда вы отправляете сложный запрос, magiclaw не пытается решить всё самостоятельно. Он распознаёт, какие специализированные возможности нужны этому заданию, и затем через вызовы инструментов делегирует работу другим зарегистрированным Playground:

Вы в Feishu: «Помогите мне изучить последние достижения RAG-архитектуры в финансовой сфере и подготовить отчёт»

→ magiclaw получает запрос
→ Понимает, что нужны: обзор литературы (web_search_agent) + написание отчёта (report_writer_agent)
→ Отдельно вызывает эти два Agent
→ Сводит результаты и возвращает сообщение в Feishu

Эта модель делегирования позволяет magiclaw оставаться простым: ему не нужно «уметь всё», достаточно знать, когда и кого следует вызывать. Все возможности специализированных Agent расширяются через Skills и интерфейсы инструментов.

agent_builder: meta-агент

agent_builder — самая интересная часть MagiClaw: сам по себе это тоже Agent, но его задача — проектировать и генерировать новые Agent.

Вы рассказываете ему, какой тип задач хотите делать — и он:

1. Анализирует требования и выделяет ключевые компетенции, которые нужны агенту
2. Генерирует файлы навыков Agent (YAML frontmatter + описание в Markdown)
3. Записывает их в каталог playground/ и регистрирует в MagiClaw
4. Новый Agent сразу доступен, и magiclaw может делегировать ему задачи

Вы в Feishu: «Мне нужен Agent, который будет специально заниматься code review»

→ agent_builder анализирует требования
→ Генерирует `code_reviewer_agent.py` + соответствующий конфигурационный файл
→ Регистрирует в системе
→ Отвечает: «Создан code_reviewer; теперь magiclaw может делегировать ему задачи code review»

Такая функция self-bootstrapping позволяет команде непрерывно расширять библиотеку Agent под собственные направления исследований, а не один раз определить все сценарии заранее.

---

Настройка инструментов и механизмы Skills / памяти

Настройка уровня инструментов

В configs/magiclaw/config.yaml можно настроить разные типы инструментов:

tools:
  mcp:
    # Инструменты по протоколу MCP (например, файловая система, Git, базы данных и т.д.)
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # опционально: bing / google / serpapi

  feishu:
    read_document: true           # чтение документов Feishu
    send_file: true               # отправка файлов

Конфигурация инструментов определяет, что Agent может «делать», а Skills — насколько хорошо он это «делает».

Система Skills

Skills — это упакованные структурированные подсказки (prompt), которые помогают Agent лучше справляться с конкретными задачами. Директория Skills фреймворка EvoMaster находится в evomaster/skills/, и каждый Skill — это файл Markdown:

---
name: research-paper-summary
trigger: literature survey, paper review, paper analysis
agent: research
---

# Research Paper Summary Skill

Когда пользователь просит суммировать или проанализировать статьи, выполните следующие шаги:

1. Извлеките заголовок статьи, авторов и venue
2. Извлеките ключевой вклад (contribution)
3. Извлеките основные пункты методологии
4. Извлеките ограничения (limitations)
5. Выведите структурированное резюме (не более 300 слов)

Если пользователь предоставляет ссылку на ArXiv, сначала извлеките содержимое страницы, а затем выполните анализ.

Skills загружаются по мере необходимости: при обработке определённого типа задач Agent автоматически подбирает соответствующий Skill, вручную ничего не нужно запускать.

Персистентная память

Память MagiClaw управляется модулем evomaster/memory/ и поддерживает разные бэкенды хранения:

memory:
  backend: sqlite               # опционально: sqlite / redis / file
  session_ttl: 86400            # время хранения памяти сессии (секунды)
  long_term:
    enabled: true
    store: file                 # сохранять на диск
    path: ./memory_store/

После каждой беседы Agent автоматически записывает ключевой контекст в память. Когда начинается новая сессия, Agent читает историю памяти и сохраняет связность между беседами.

---

Демонстрация полного рабочего процесса

Сценарий: сборка для команды агента «Быстрое чтение статей»

Цель: отправить Bot в Feishu ссылку на ArXiv — он автоматически вернёт структурированное резюме статьи.

Шаг 1: создать Agent через agent_builder

Отправьте в Feishu сообщение MagiClaw:

Создай для меня Agent быстрого чтения статей, имя paper_reader

agent_builder создаст каталог playground/paper_reader/, включающий:

playground/paper_reader/
├── __init__.py
├── agent.py                   # основная логика Agent
└── config.yaml                 # конфигурация уровня Agent

Шаг 2: зарегистрировать в magiclaw

После создания нового Agent отредактируйте configs/magiclaw/config.yaml и зарегистрируйте его в playgrounds:

playgrounds:
  - name: paper_reader
    path: playground/paper_reader
    enabled: true

После перезапуска робота magiclaw сможет распознать и делегировать задачи paper_reader.

Шаг 3: проверка

В Feishu:

@Bot paper_reader https://arxiv.org/abs/2401.01234

paper_reader выполнит автоматически:

1. Получит страницу ArXiv
2. Извлечёт заголовок, автора и аннотацию
3. Сгенерирует структурированное резюме (вклад + метод + ограничения)
4. Вернёт сообщение в Feishu

---

Частые проблемы и их устранение

Q1: после запуска Bot в Feishu нет ответа

Причина: неверно настроена подписка на события или конфигурация долгого соединения.

Проверка:

# 1. Убедитесь, что Bot опубликован (Feishu Open Platform → Управление версиями и публикация)
# Непубликованный Bot не может отправлять/получать сообщения в production-среде

# 2. Убедитесь, что long connection настроено корректно
# Feishu Open Platform → События и обратные вызовы → Конфигурация событий → выберите «long connection»

# 3. Проверьте, нет ли ошибок в логах запуска
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2: Bot получает сообщение, но отвечает «не поддерживается операция»

Причина: недостаточный набор прав или приложение не опубликовано для нужного диапазона.

Проверка:

В Feishu Open Platform → Управление правами подтвердите, что открыты следующие минимальные права:

"im:message",
"im:message:send_as_bot",
"im:chat:readonly"

Если Bot должен вступать в групповые чаты, также потребуется im:message.group_at_msg:readonly.

---

Q3: после создания Agent agent_builder magiclaw не распознаёт его

Причина: новый Agent не зарегистрирован в configs/magiclaw/config.yaml.

Решение:

Убедитесь, что в списке playgrounds в configs/magiclaw/config.yaml добавлен новый Agent и установлено enabled: true. После изменения конфигурации нужно перезапустить робота.

---

Q4: память не сохраняется между сессиями, и при каждом новом диалоге Agent «как будто забывает»

Причина: не настроен корректно бэкенд хранения памяти или директория не доступна для записи.

Проверка:

# 1. Проверьте memory-конфигурацию в config.yaml
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. Убедитесь, что директория memory_store существует и доступна для записи
mkdir -p memory_store
chmod 755 memory_store

# 3. Перезапустите робота, отправьте сообщение, чтобы триггернуть запись памяти

---

Q5: Web Search возвращает пустой результат или происходит таймаут

Причина: сеть не может достучаться до поискового сервиса или не настроены реквизиты Search API.

Решение:

Если вы используете DuckDuckGo (бесплатно, без API Key), убедитесь, что Python-среда имеет доступ в интернет:

# тест сети
python -c "import requests; print(requests.get('https://api.duckduckgo.com/?q=test&format=json').status_code)"

Если статус возвращается 200, но Bot всё равно таймаутит, проверьте корректность конфигурации tools.web_search.provider в configs/magiclaw/config.yaml.

---

Q6: MCP-инструмент не запускается, появляется ошибка command not found

Причина: npx для MCP Server или путь к Node.js не добавлены в системную переменную PATH.

Решение:

# убедитесь, что npx доступен
npx --version

# если npx не находится, укажите путь вручную
# отредактируйте configs/magiclaw/config.yaml:
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

Дополнительное чтение и направления развития

1. Подключение экосистемы SciMaster

MagiClaw — Feishu-вход для экосистемы EvoMaster, а полный набор SciMaster (ML-Master, X-Master, Browse-Master и т.д.) находится в upstream-репозитории EvoMaster. Если ваше направление исследований требует анализа материалов в мульти-модальном режиме или согласованной работы нескольких экспериментов, вы можете синхронизировать эти специализированные Agent из EvoMaster и подключить слой оркестрации MagiClaw.

2. Собственные MCP-инструменты

Интерфейс MCP-инструментов MagiClaw поддерживает подключение любого MCP Server. Вы можете написать MCP Server на Python, чтобы обернуть внутренние API, инструменты запросов по исследовательским базам данных или скрипты отправки задач в HPC-кластере, а затем зарегистрировать его в MagiClaw — и Agent сможет вызывать ваши инструменты прямо из Feishu.

3. Архитектура с сотрудничеством нескольких Bot

Если в команде есть несколько Bot под разные роли (например, один ведёт календарь, другой — код, третий — литературу), можно организовать их взаимодействие через групповые чаты Feishu: интегрируйте несколько Bot в один чат, а каждый будет отвечать за свою функцию, переключаясь через @.

4. Развёртывание приватных моделей в команде

EvoMaster поддерживает custom Provider, позволяя подключать LLM, развёрнутые внутри компании (Llama, Mistral, Qwen и т.п.). Если исследовательские данные нельзя передавать наружу, можно развернуть модель локально или в приватном облаке, а управлять ей через интерфейс MagiClaw: данные полностью не выходят за пределы внутренней сети.

5. Настройка поведения Agent

Поведение Agent в каждом Playground в основном контролируется prompt и skills из config.yaml. Если вы обнаружите, что Agent плохо справляется с некоторыми сценариями, можно отредактировать соответствующий Skill-файл: изменить шаги рассуждений и формат вывода, не трогая код.