Agent Node

Узел для совместной работы ИИ-агентов на нескольких машинах в локальной сети. Разверните по одному экземпляру на каждом компьютере — и получите «команду из нескольких машин и нескольких агентов»: автоматическое обнаружение в локальной сети, симметричное управляемое/дистанционное выполнение команд, состояние системы видно в трее, передача файлов между узлами, встроенный MCP Server для вызова из AI-клиентов.

Минимальный самостоятельный проект, выделенный из репозитория agent-bus. Запускается из исходного кода, без сборки и упаковки.

1. Возможности

2. Сценарии использования

• Многоузловая multi-agent коллаборация: один AI-клиент через MCP оборачивает возможности нескольких компьютеров в инструменты и оркестрирует их между машинами.

• Удалённое администрирование / отладка в локальной сети: с любого узла отправляйте команды другим узлам и получайте результаты.

• Передача файлов между машинами: двусторонняя отправка/получение отдельных файлов и каталогов (автоматическая упаковка в zip).

• Подключение AI-клиентов: «отправка задач / проверка входящих / выполнение команд / чтение и запись файлов / загрузка и скачивание» оформляются как стандартные инструменты для вызова из Claude / Cursor.

3. Техническая архитектура

┌──────────── 中心节点 (一台, --role hub) ────────────┐
│  mosquitto (MQTT broker)                           │
│  bus_server (FastAPI + SQLite, Web 面板 + 文件服务) │
│  自身控制节点 (带全部功能)                            │
└────────────────────────────────────────────────────┘
          ▲ MQTT / HTTP               ▲ UDP beacon 发现
          │                           │
┌─────────┴─────────┐       ┌─────────┴─────────┐
│ worker (对称控制节点) │  ...  │ worker (对称控制节点) │
│ 连总线 + 受控/遥控    │       │ 连总线 + 受控/遥控    │
└───────────────────┘       └───────────────────┘

• Коммуникационный слой: MQTT (mosquitto), сообщения маршрутизируются по топикам (agent/<id>/inbox, bus/register, bus/heartbeat/), QoS 1, retain-регистрация + завещание (LWT) для отметки офлайн.

• Слой обнаружения: UDP-широковещательный beacon (255.255.255.255:41830), симметричный, без главного/подчинённого; при запуске worker автоматически сканирует узлы is_master и получает реальный адрес broker (без ручной настройки).

• Файловый слой: HTTP (bus_server, FastAPI), загрузка/скачивание по схеме Claim-Check, автоматический zip для каталогов / безопасная распаковка (защита от path traversal + zip-slip).

• Центр: роль hub запускает mosquitto встроенно (если уже установлен локально — переиспользуется, иначе при первом запуске распаковывается из build/mosquitto.zip) + bus_server + веб-панель.

• MCP: FastMCP использует транспорт stdio, отделён от GUI-режима и может запускаться независимо.

MCP-инструменты (10): list_online_agents · send_task · check_inbox · run_command · read_file · upload_file · download_file · fetch_file · post_file · reply_task

4. Установка

4.1 Предварительные требования

• Python 3.10+ (на всех машинах)

• Взаимодействие в локальной сети + разрешения в брандмауэре (входящие на стороне hub):

  • TCP 1883 (MQTT, возможен откат в пуле портов 1884/1885/8883/18830)

  • TCP 8000 (HTTP-панель/файлы, откат в пуле 8001/8002/8010/8088)

  • UDP 41830 (широковещательное обнаружение)

4.2 Главная машина hub (одна)

Требуется полный каталог проекта + mosquitto.

# 1. 获取代码（git clone 或拷贝整个 agent-node 文件夹）
git clone <本仓库地址>

# 2. 安装依赖
cd agent-node
pip install -r requirements.txt

# 3. 启动中心节点（起 broker + Web 面板 + 自身控制节点 + 托盘）
python executor/control_app.py --role hub

• mosquitto: если уже установлен локально, автоматически переиспользуется (shutil.which("mosquitto") или C:\Program Files\mosquitto); если не установлен, при первом запуске автоматически распаковывается из build/mosquitto.zip в data/runtime/mosquitto, поэтому build/ необходимо сохранять.

• Веб-панель: после запуска откройте в браузере http://127.0.0.1:8000/ (при откате в пуле портов смотрите фактический порт в логах запуска).

• При первом запуске hub создаёт data/ (bus.db, files, broker.log, node_config.json); предварительная подготовка не требуется.

4.3 Worker на остальных машинах (несколько)

Нужен только урезанный набор: пакет agent_bus/ + executor/control_app.py + requirements.txt (server/, build/, scripts/ не нужны).

# 1. 拷贝精简子集到目标机器（或 git clone 后仅运行，多余的目录会被自动忽略）
#    agent_bus/  executor/control_app.py  requirements.txt

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动 worker（无参数，自动扫描局域网中心）
python executor/control_app.py

• Не нужно настраивать адрес broker: если worker запущен без --broker-host, он автоматически сканирует узлы is_master в локальной сети и получает реальный адрес (host / MQTT-порт / HTTP-порт — все три значения).

• Ручное указание центра (при разных подсетях / если автоматическое обнаружение не сработало): python executor/control_app.py --broker-host 192.168.1.10

• Входящие автоматически сохраняются в Downloads/agent-node/inbox, каталог конфигурации data/ создаётся автоматически — ничего предварительно готовить не нужно.

4.4 Сокращённый список файлов

5. Параметры командной строки

Пулы портов

• MQTT: 1883 → 1884 → 1885 → 8883 → 18830

• HTTP: 8000 → 8001 → 8002 → 8010 → 8088

• Обнаружение: 41830 → 41831 → 41832 → 41840 → 41850

6. Конфигурация MCP (для AI-клиентов)

--mcp работает через stdin/stdout и предназначен для запуска из MCP-клиентов, таких как Claude Desktop / Cursor, через JSON-конфигурацию.

{
  "mcpServers": {
    "agent-node": {
      "command": "python",
      "args": [
        "C:/path/to/agent-node/executor/control_app.py",
        "--mcp", "--role", "worker", "--agent-id", "my-agent"
      ],
      "env": { "BUS_BROKER_HOST": "192.168.1.10" }
    }
  }
}

BUS_BROKER_HOST можно опустить — worker автоматически обнаружит центр; при разных подсетях или сбое обнаружения укажите его явно.

7. Структура каталогов

agent-node/
├── executor/
│   └── control_app.py          # 节点主入口（对称 + 托盘 + MCP + 中心角色）
├── agent_bus/                  # 通信 SDK（client/config/discovery/provision/files/schema...）
├── server/
│   ├── bus_server.py           # 中心 HTTP + 消息服务（可编程 serve_bus_server 内联启动）
│   └── static/index.html       # Web 面板
├── scripts/
│   └── build_mosquitto_zip.py  # 重建 mosquitto 便携包
├── build/
│   └── mosquitto.zip           # 便携 mosquitto（hub 首启自解压）
├── docs/
│   ├── 需求与设计.md
│   └── BUGFIX_LOG_20260819.md
└── requirements.txt

8. Модель безопасности

Проект рассчитан на доверенную локальную сеть: broker allow_anonymous, управляющие сообщения передаются по MQTT открытым текстом, используется только белый список по префиксу sender_id (плоскость управления принимает только идентификаторы hub-*). Не выполняются HMAC-проверка подписи / шифрование / белый список узлов — при работе через недоверенную сеть требуется самостоятельное усиление защиты.