hmo
1b2b935832
- 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
421 lines
18 KiB
Markdown
421 lines
18 KiB
Markdown
# AgentsMeeting — 系统架构设计文档
|
||
|
||
> 版本: v0.2 | 状态: 草稿
|
||
|
||
---
|
||
|
||
## 1. 设计理念
|
||
|
||
**不是特制零件拼装，而是通用框架。**
|
||
|
||
核心原则：
|
||
1. **平台抽象** — 按 Windows / Linux / Mac 分层，不按人名硬编码
|
||
2. **实例化** — Agent 是一个可注册、可配置、可复制的组件，不是硬编码的个体
|
||
3. **管理化** — 所有 Agent 通过 Dashboard 统一管理，不断联不黑盒
|
||
4. **XMPP 是主通道** — 所有参与方通过 XMPP 通信，人类用标准客户端
|
||
5. **通道解耦** — 微信/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 不再是一个硬编码的名字，而是一个**配置实例**：
|
||
|
||
```yaml
|
||
# 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 配置
|
||
|
||
```yaml
|
||
# 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 | 🟡 | |
|