Agent-Knoten

Lokaler Multi-Rechner-Agenten-Kooperationsknoten. Einmal auf jedem Computer bereitgestellt, bildet er ein „Multi-Rechner-Multi-Agenten-Kooperationsteam": automatische LAN-Erkennung, symmetrische ferngesteuerte/fernsteuernde Befehlsausführung, sichtbares System-Tray-Symbol, knotenübergreifender Dateiversand und -empfang, eingebetteter MCP-Server für den Aufruf durch KI-Clients.

Ein minimalistisches, eigenständiges Projekt, das aus dem agent-bus-Repository extrahiert wurde. Läuft aus dem Quellcode, keine ausgelieferten Builds.

I. Fähigkeiten

II. Anwendungsfälle

• Multi-Rechner-Multi-Agenten-Kooperation: Ein KI-Client kapselt die Fähigkeiten mehrerer Computer über MCP als Tools und orchestriert sie maschinenübergreifend.

• LAN-Fernwartung / -Debugging: Befehle von einem beliebigen Knoten an andere Knoten senden und Ergebnisse abrufen.

• Maschinenübergreifender Dateitransfer: Senden und Empfangen von Einzeldateien / Verzeichnissen (automatisch als ZIP gepackt) in beide Richtungen.

• KI-Client-Anbindung: Kapselt „Aufgaben senden / Posteingang prüfen / Befehle ausführen / Dateien lesen/schreiben / Hoch- und Herunterladen" als Standard-Tools für Claude / Cursor.

III. Technische Architektur

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

• Kommunikationsebene: MQTT (mosquitto), Nachrichten werden über Topics geroutet (agent/<id>/inbox, bus/register, bus/heartbeat/), QoS 1, retain-Registrierung + Last-Will für Offline-Status.

• Discovery-Ebene: UDP-Broadcast-Beacon (255.255.255.255:41830), symmetrisch ohne Master/Slave; Worker scannt beim Start automatisch nach is_master-Knoten, um die echte Broker-Adresse zu erhalten (keine manuelle Konfiguration erforderlich).

• Dateiebene: HTTP (bus_server, FastAPI), Claim-Check-Upload/-Download, automatisches ZIP für Verzeichnisse / sicheres Entpacken (Schutz vor Pfadmanipulation + Zip-Slip).

• Zentrale: Die Hub-Rolle startet mosquitto (falls lokal installiert, wird es wiederverwendet, andernfalls wird es beim ersten Start aus build/mosquitto.zip entpackt) + bus_server + Web-Panel.

• MCP: FastMCP über stdio-Transport, entkoppelt vom GUI-Modus, separat startbar.

MCP-Tools (10 Stück): list_online_agents · send_task · check_inbox · run_command · read_file · upload_file · download_file · fetch_file · post_file · reply_task

IV. Installation

4.1 Voraussetzungen

• Python 3.10+ (auf allen Rechnern)

• LAN-Konnektivität + Firewall-Freigabe (eingehend auf der Hub-Seite):

  • TCP 1883 (MQTT, Port-Pool-Fallback möglich: 1884/1885/8883/18830)

  • TCP 8000 (HTTP-Panel/Dateien, Pool-Fallback: 8001/8002/8010/8088)

  • UDP 41830 (Discovery-Broadcast)

4.2 Hub-Hauptrechner (einer)

Benötigt vollständiges Projektverzeichnis + 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: Wenn lokal installiert, wird es automatisch verwendet (shutil.which("mosquitto") oder C:\Program Files\mosquitto); wenn nicht installiert, wird es beim ersten Start automatisch aus build/mosquitto.zip nach data/runtime/mosquitto entpackt. build/ muss daher erhalten bleiben.

• Web-Panel: Nach dem Start im Browser http://127.0.0.1:8000/ öffnen (bei Port-Pool-Fallback die tatsächliche Portnummer im Startprotokoll beachten).

• Beim ersten Start des Hubs wird data/ erstellt (bus.db, files, broker.log, node_config.json), keine Vorkonfiguration nötig.

4.3 Worker (andere Rechner, beliebig viele)

Nur eine reduzierte Teilmenge wird benötigt: agent_bus/-Paket + executor/control_app.py + requirements.txt (server/, build/, scripts/ werden nicht benötigt).

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

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

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

• Keine Broker-Adresse konfigurieren: Ohne --broker-host scannt der Worker automatisch das LAN nach is_master-Knoten und übernimmt die echte Adresse (Host / MQTT-Port / HTTP-Port).

• Manuelle Angabe des Zentrums (bei gerouteten Netzen / fehlgeschlagener automatischer Erkennung): python executor/control_app.py --broker-host 192.168.1.10

• Der Posteingang wird automatisch unter Downloads/agent-node/inbox abgelegt, das Konfigurationsverzeichnis data/ wird automatisch erstellt. Keine Vorkonfiguration nötig.

4.4 Reduzierte Dateiliste

V. Befehlszeilenargumente

Port-Pools

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

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

• Discovery: 41830 → 41831 → 41832 → 41840 → 41850

VI. MCP-Konfiguration (für KI-Clients)

--mcp läuft über stdin/stdout und kann von Claude Desktop / Cursor usw. als MCP-Client per JSON-Konfiguration gestartet werden.

{
  "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 kann weggelassen werden – der Worker erkennt das Zentrum automatisch; bei gerouteten Netzen oder fehlgeschlagener Erkennung explizit angeben.

VII. Verzeichnisstruktur

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

VIII. Sicherheitsmodell

Dieses Projekt ist für vertrauenswürdige lokale Netzwerke ausgelegt: Der Broker erlaubt anonyme Verbindungen (allow_anonymous), Steuernachrichten werden im Klartext über MQTT gesendet, es gibt nur eine Whitelist für das sender_id-Präfix (die Steuerebene akzeptiert nur hub-*-Identitäten). Keine HMAC-Signaturprüfung / Verschlüsselung / Knoten-Whitelist – für den Einsatz über nicht vertrauenswürdige Netzwerke hinweg sind eigene Sicherheitsmaßnahmen erforderlich.