# 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 | 🟡 | |