Files

T

hmo 1b2b935832 Initial: multi-agent XMPP communication system with dashboard

- Platform-based architecture (Windows/Linux/Mac)
- Agent instance registry (agents.yaml)
- Management dashboard with cross-platform monitoring
- xmpp_bot with HTTP bridge + health endpoints
- wechat_agent with WeChat-Hermes bridging
- Platform services: ProcessGuardian, HealthProbe, APIRouter, ChannelBridge
- Deployment: systemd (Linux) + PowerShell (Windows)
- Monitoring: SSH+ejabberdctl for cross-platform presence

2026-06-12 21:51:36 +08:00

18 KiB

Raw Blame History

AgentsMeeting — 系统架构设计文档

版本: v0.2 | 状态: 草稿

1. 设计理念

不是特制零件拼装，而是通用框架。

核心原则：

平台抽象 — 按 Windows / Linux / Mac 分层，不按人名硬编码
实例化 — Agent 是一个可注册、可配置、可复制的组件，不是硬编码的个体
管理化 — 所有 Agent 通过 Dashboard 统一管理，不断联不黑盒
XMPP 是主通道 — 所有参与方通过 XMPP 通信，人类用标准客户端
通道解耦 — 微信/QQ 作为附属通道桥接到 XMPP，不绑死某个人或某台机器

2. 平台架构

┌─────────────────────────────────────────────────────────────────────────┐
│                         AgentsMeeting 全沟通架构                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────┐         ┌─────────────────────────────────┐    │
│  │ 人类客户端            │         │ XMPP 服务器                      │    │
│  │ Gajim / Conversations│◄───────►│ ejabberd (Docker)               │    │
│  │ Monal / 任意 XMPP    │  :3021  │ xmpp.yoin.fun:3021             │    │
│  └─────────────────────┘         │  └─ MUC: coregroup@conference   │    │
│                                    └─ MAM 消息归档                   │    │
│                                   └─────────────────────────────────┘    │
│                                              ▲ ▲ ▲                      │
│                                     XMPP     │ │ │                      │
│                              ┌───────────────┘ │ └─────────────┐         │
│                              ▼                  ▼               ▼         │
│  ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐      │
│  │ Windows Platform  │ │ Linux Platform    │ │ Mac Platform      │      │
│  │ 192.168.1.16      │ │ 192.168.1.246     │ │ 192.168.1.122     │      │
│  │                   │ │                   │ │                   │      │
│  │ ● Bot Engine      │ │ ● Bot Engine      │ │ ● Bot Engine      │      │
│  │ ● WeChat Bridge   │ │ ● Hermes Gateways │ │ ● oMLX (本地LLM)  │      │
│  │ ● API Proxy       │ │ ● Ejabberd Ops    │ │                   │      │
│  │ ● Mgmt Dashboard  │ │ ● Cron Jobs       │ │                   │      │
│  │ ● Health Monitor  │ │ ● Data Storage    │ │                   │      │
│  │ ● Watchdog        │ │ ● Docker Fleet    │ │                   │      │
│  └───────────────────┘ └───────────────────┘ └───────────────────┘      │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ 附属通道 (Bridge Channels)                                        │    │
│  │  ├─ WeChat: WeChat App → wxhelper DLL → wechat_agent → XMPP     │    │
│  │  └─ QQ: QQ App → NapCat → QQ Bot → XMPP (规划中)                │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ 管理门户 (Management Dashboard)                                    │    │
│  │  Web UI → 查看 Agent 状态 → 启动/停止/重启 → 查看日志 → 配置管理   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

3. Agent 实例化体系

3.1 Agent 定义

一个 Agent 不再是一个硬编码的名字，而是一个配置实例：

# config/agents.yaml — 所有已注册的 Agent 实例
agents:
  - id: "agent-001"
    name: "研发助理"
    display_name: "小小莫"
    jid: "xxm@yoin.fun"
    platform: windows          # windows | linux | mac
    host: "192.168.1.16"
    bot_type: xmpp             # xmpp | hermes | bridge
    provider: volcengine
    services:                  # 该 Agent 关联的服务
      - type: xmpp_bot
        script: xmpp_bot.py
        port: 5802            # HTTP bridge
      - type: wechat_bridge
        script: wechat_agent.py
        port: 5801

  - id: "agent-002"
    name: "自动化总管"
    display_name: "莫荷"
    jid: "mohe@yoin.fun"
    platform: linux
    host: "192.168.1.246"
    bot_type: hermes
    provider: ocg-new
    services:
      - type: hermes_gateway
        port: 8642
      - type: xmpp_bot

  - id: "agent-003"
    name: "本地推理"
    display_name: "小果"
    jid: "xiaoguo@yoin.fun"
    platform: mac
    host: "192.168.1.122"
    bot_type: xmpp
    provider: ocg-old
    services:
      - type: xmpp_bot
      - type: omlx_server
        port: 18003

  - id: "agent-004"
    name: "持仓分析"
    display_name: "知微"
    jid: "zhiwei@yoin.fun"
    platform: linux
    host: "192.168.1.246"
    bot_type: hermes
    provider: ocg-old
    services:
      - type: hermes_gateway
        port: 8643
      - type: xmpp_bot

3.2 添加新 Agent 流程

1. 在 config/agents.yaml 中添加一条记录（命名、选平台、分配 JID）
2. 在 ejabberd 注册新 JID 账号
3. 在对应平台机器上部署 bot 脚本
4. 管理门户自动发现新 Agent（读 agents.yaml + 进程检测）
5. 加入 MUC 群聊

3.3 平台能力矩阵

能力	Windows	Linux	Mac
XMPP Bot	✅	✅	✅
Hermes Gateway	❌	✅	❌
WeChat Bridge	✅ (wxhelper)	❌	❌
QQ Bridge	✅ (NapCat)	✅ (NapCat)	❌
API Proxy	✅	✅	✅
管理门户	✅ (主)	❌	❌
Watchdog / Health	✅	✅ (systemd)	✅
本地 LLM (oMLX)	❌	❌	✅
Cron Jobs	❌ (Scheduled Tasks)	✅	❌
Docker 编排	✅	✅	❌
数据存储 (SQLite)	✅	✅	✅

3.4 平台服务接口（统一接口，分平台实现）

Agent 只管自己的业务逻辑（接收消息、调用 LLM、回复）。进程守护、健康检测、API 路由等是平台服务——每个平台用自己的方式实现，但对外接口一致。

服务类型定义

服务类型	接口规范	职责
ProcessGuardian	暴露 `/health` 端点；提供 `start/stop/restart` 操作	守护目标进程存活，挂了自动拉起
HealthProbe	返回 `{status: online\|degraded\|offline, last_msg_age: N}`	检测消息流是否正常，识别"假活"
APIRouter	转发 `POST /v1/chat/completions`，provider fallback	代理 LLM API 调用，吞掉错误码
MessageObserver	监听指定 JID 的消息，写入日志	跨 Agent 通信监控
ChannelBridge	`POST /bridge/{channel}/send`，`GET /bridge/{channel}/messages`	外部通道 ↔ XMPP 消息转发

各平台实现

服务类型	Windows	Linux	Mac
ProcessGuardian	`xmpp_watchdog.py`（30s 轮询）	systemd `Restart=always`	待实现
HealthProbe	`health_check_xxm.py`（Task Scheduler 5min）	systemd timer / cron	待实现
APIRouter	`api_proxy.py`（:8787）	hermes 内置 fallback	不需要
MessageObserver	`mohe_watcher.py`（30s）	不需要	不需要
ChannelBridge	`wechat_agent.py`（微信）	无（微信需 Windows）	不需要

原则：Agent 不关心平台用的是 watchdog 还是 systemd。它只需要知道"有人保证我活着"——这就是统一接口的意义。

4. 模块层级

┌────────────────────────────────────────────────────────────────┐
│ Layer 6: 管理门户 (Management Dashboard)                        │
│  Web UI · Agent 管理 · 状态监控 · 日志查看 · 启停控制           │
├────────────────────────────────────────────────────────────────┤
│ Layer 5: 运维层 (Operations)                                    │
│  watchdog · health check · systemd/task scheduler · log rotate  │
├────────────────────────────────────────────────────────────────┤
│ Layer 4: 桥接层 (Bridge)                                        │
│  wechat_agent · QQ bot (规划) · 消息格式转换 · 图片 OCR          │
├────────────────────────────────────────────────────────────────┤
│ Layer 3: 智能网关层 (AI Gateway)                                 │
│  hermes-agent · profile 路由 · session 管理 · provider fallback │
├────────────────────────────────────────────────────────────────┤
│ Layer 2: Bot 引擎层 (Bot Engine)                                 │
│  slixmpp 客户端 · HTTP bridge · MUC 群消息 · MAM 历史           │
├────────────────────────────────────────────────────────────────┤
│ Layer 1: 通信层 (Communication)                                  │
│  ejabberd · MUC · XMPP/TLS · SRV DNS · 消息路由                 │
└────────────────────────────────────────────────────────────────┘

5. 数据流

5.1 群聊消息流（所有平台通用）

任意发送者（人类/Bot）
  │
  ▼
ejabberd (MUC coregroup@conference.yoin.fun)
  │ 广播
  ▼
所有在线 Bot（通过 slixmpp 接收）
  │
  ▼
观察者模式判断：
  ├─ @点名我 → 需要回复 → Gateway/LLM → 回复到群
  ├─ 上下文指向我 → 需要回复 → Gateway/LLM → 回复到群
  └─ 与我无关 → 仅记录上下文 → 不回复

5.2 Gateway 处理流

Bot 引擎收到需要回复的消息
  │
  ▼
提取: sender_jid, message_body, context
  │
  ▼
Gateway API (HTTP POST → localhost:{port}/v1/chat/completions)
  │
  ├─ 注入 SOUL.md + MEMORY.md + USER.md
  ├─ 加载最近 200 条上下文
  ├─ Provider 选择 (主 provider → fallback 链)
  └─ LLM 生成
       │
       ▼
  解析回复
       ├─ ##command## → 执行工具调用 → 结果追加到上下文 → 循环
       └─ 纯文本 → 返回
            │
            ▼
       Bot 引擎 → XMPP 发送到群

5.3 微信通道流（Windows 平台专属）

微信消息
  │
  ▼
WeChat App → wxhelper DLL 注入 → TCP :19099
  │
  ▼
wechat_agent.py
  ├─ 文字: POST → Hermes Gateway (Linux) → LLM → 回复
  ├─ 图片: downloadAttach → decodeImage → OCR → 文字发给 Gateway
  └─ 回复: wxhelper HTTP :19088 发送回微信

6. 组件通信矩阵

组件	协议	端口	说明
Bot ↔ ejabberd	XMPP/TLS	3021	标准 XMPP
Bot ↔ Gateway	HTTP REST	动态分配	OpenAI 兼容 API
WeChat Agent ↔ Gateway	HTTP	8642	Hermes API
WeChat Agent ↔ wxhelper	HTTP	19088	微信消息收发
WeChat Agent ↔ wxhelper	TCP	19099	微信事件推送
管理门户 ↔ Bot	HTTP	5803	Dashboard API
人类 ↔ ejabberd	XMPP/TLS	3021	标准客户端
API Proxy → Provider	HTTPS	443	转发到火山/OCG
Bot 启动器 ↔ 进程	subprocess	-	进程管理

7. 管理门户设计

7.1 功能

功能	说明
Agent 列表	所有已注册 Agent，含名称/JID/平台/状态
连接状态	XMPP 在线/离线、Bot 进程是否存活、最后消息时间
启停控制	启动/停止/重启单个 Agent 的 Bot 进程
日志查看	实时 tail 关键日志（bot.log / health_check.log）
健康指标	最近 N 分钟消息数、响应延迟、错误率
告警规则	Agent 离线 >N 分钟告警、Bot 假死（在线但无消息）告警
配置浏览	查看当前 agents.yaml 配置

7.2 技术方案

层	选型	理由
后端	Python Flask (:5803)	零依赖，和现有 bot 一致
前端	单页 HTML + 原生 JS + CSS	无构建步骤，直接 serve
数据源	SSH + ejabberdctl → 跨平台在线检测	比 MUC/roster 更可靠，不依赖 Bot 自身状态
本地补充	进程列表 + xmpp_bot /health 端点	Windows 本地进程检测
实时更新	前端 5s 轮询	简单可靠
自动恢复	连续 3 次离线检测 → 自动重启	仅限 Windows 本地 Agent

7.3 监控架构

Dashboard (:5803)
  │
  ├── SSH → 192.168.1.246 → ejabberdctl connected_users
  │     └── 返回所有在线 JID 列表（跨平台权威数据源）
  │
  ├── GET :5802/health
  │     └── XMPP 连接状态 + ejabberd 是否存活
  │
  ├── GET :5802/presence/{jid}
  │     └── Roster presence（备选）
  │
  └── 本地进程检测 (Get-CimInstance)
        └── Windows 进程存活 + PID

7.3 后端 API

方法	路径	说明
GET	/api/agents	所有 Agent 状态
GET	/api/agents/{id}	单个 Agent 详情
GET	/api/agents/{id}/logs	tail 日志
POST	/api/agents/{id}/start	启动 Bot
POST	/api/agents/{id}/stop	停止 Bot
POST	/api/agents/{id}/restart	重启 Bot
GET	/api/health	Dashboard 自身健康检查

8. 配置管理

8.1 配置分层

config/
├── agents.yaml           # Agent 实例注册表 (核心)
├── providers.yaml        # AI 提供商配置
├── platforms.yaml        # 平台能力声明
├── .env.example          # 环境变量模板
└── profiles/             # 每个 Agent 的个性化配置
    └── {agent-name}/
        ├── system_prompt.txt
        ├── memory.txt
        └── tools.yaml

8.2 Provider 配置

# config/providers.yaml
providers:
  volcengine:
    api_key: ${VOLCENGINE_KEY}
    base_url: https://ark.cn-beijing.volces.com/api/coding/v3
    models: [deepseek-v4-pro, deepseek-v4-flash]
  ocg-new:
    api_key: ${OCG_NEW_KEY}
    base_url: https://opencode.ai/zen/go/v1
  ocg-old:
    api_key: ${OCG_OLD_KEY}
    base_url: https://opencode.ai/zen/go/v1
  omlx:
    api_key: ${OMLX_KEY}
    base_url: http://192.168.1.122:18003/v1

9. 运维体系

9.1 平台运维职责

职责	Windows	Linux	Mac
进程存活监控	watchdog (30s)	systemd (auto-restart)	launchd / cron
消息流监控	health_check (5min)	待实现	待实现
日志轮转	watchdog 内置 (15min/5MB)	待实现	待实现
自动恢复	进程死→自动重启	systemd Restart=always	待实现
假死检测	在线但无消息 >10min → 重启	待实现	待实现
告警通知	Dashboard 显示	XMPP 群消息	XMPP 群消息

9.2 日志体系

日志	位置	轮转	内容
bot.log	gateway/logs/	✅ 15min/5MB	Bot 连接/消息/HTTP桥
bridge.log	gateway/logs/	无	LLM API 调用/耗时
watchdog.log	gateway/logs/	✅ 15min/5MB	Watchdog 启停
health_check.log	gateway/logs/	无	健康检查结果
mohe_inbox.log	gateway/logs/	无	莫荷消息记录

10. 已知问题

ID	问题	平台	状态	说明
R01	MUC join 超时 (conference.yoin.fun cert)	Linux (ejabberd)	🟡	已加自签证书，join_muc_wait 仍超时；已用 SSH+ejabberdctl 绕过
R02	xmpp_bot 频繁断连 (~50s)	Windows	🔴	阿里云 Nginx 代理 TCP idle timeout
R03	日志无系统级轮转（除 watchdog 内置）	Windows + Linux	🟡
R04	Provider fallback 链可能无限循环	全部	🟡
R05	QQ 通道未实现	Windows	🟢
R06	部分 Gateway 进程缺 systemd 管理	Linux	🟡
R07	API Key 明文在 config.yaml	Linux	🟡

18 KiB Raw Blame History Unescape Escape

AgentsMeeting — 系统架构设计文档

1. 设计理念

2. 平台架构

3. Agent 实例化体系

3.1 Agent 定义

3.2 添加新 Agent 流程

3.3 平台能力矩阵

3.4 平台服务接口（统一接口，分平台实现）

服务类型定义

各平台实现

4. 模块层级

5. 数据流

5.1 群聊消息流（所有平台通用）

5.2 Gateway 处理流

5.3 微信通道流（Windows 平台专属）

6. 组件通信矩阵

7. 管理门户设计

7.1 功能

7.2 技术方案

7.3 监控架构

7.3 后端 API

8. 配置管理

8.1 配置分层

8.2 Provider 配置

9. 运维体系

9.1 平台运维职责

9.2 日志体系

10. 已知问题

18 KiB

Raw Blame History