# AgentsMeeting — 多智能体全沟通架构

> 基于 XMPP 的统一通信系统。按平台（Windows/Linux/Mac）部署，Agent 实例化注册，管理门户统一监控。
>
> **仓库**: [git.yoin.fun/hmo/AgentsMeeting](https://git.yoin.fun/hmo/AgentsMeeting) | **Dashboard**: [192.168.1.246:5803](http://192.168.1.246:5803)

### 当前已注册 Agent

| ID | 显示名 | JID | 平台 | 机器 | 职责 |
|----|--------|-----|------|------|------|
| agent-001 | 研发助理 | xxm@yoin.fun | Windows | 192.168.1.16 | 研发主力、微信桥接 |
| agent-002 | 自动化总管 | mohe@yoin.fun | Linux | 192.168.1.246 | 编排监控 |
| agent-003 | 本地推理 | xiaoguo@yoin.fun | Mac | 192.168.1.122 | 本地 LLM 推理 |
| agent-004 | 持仓分析 | zhiwei@yoin.fun | Linux | 192.168.1.246 | 股票监控 |

> **Agent 是实例化的** — 添加新 Agent = 在 `config/agents.yaml` 添加记录 + 在 ejabberd 注册 JID + 部署脚本。不需要改代码。

---

## 快速开始

### 平台操作

```powershell
# Windows — 一键启动所有服务
powershell -File deploy\windows\start.ps1

# Windows — 查看所有组件状态
powershell -File deploy\windows\check.ps1

# Windows — 停止所有服务
powershell -File deploy\windows\stop.ps1

# 管理门户（启动后访问）
http://127.0.0.1:5803
```

```bash
# Linux — 启动 Gateway 和 XMPP Bot
systemctl start hermes@{profile}
systemctl start xmpp-{bot}
```

### 人类客户端

- **Gajim**: Linux/Windows (推荐)
- **Conversations**: Android
- **Monal**: iOS

配置: 服务器 `xmpp.yoin.fun`，端口 `3021`，开启 STARTTLS

---

## 项目结构

```
AgentsMeeting/
├── xmpp_agent_core.py         # 统一 Bot 核心（所有 Agent 共享）
│                               用法: python xmpp_agent_core.py --agent xxm|mohe|zhiwei|xiaoguo
│                               功能: PID锁/重连/MUC/dedup/batching/coordinator协议/HTTP桥
├── xxm_bot.py                 # 兼容入口 → xmpp_agent_core.py --agent xxm
├── mohe_bot.py                # 兼容入口 → xmpp_agent_core.py --agent mohe
├── zhiwei_bot.py              # 兼容入口 → xmpp_agent_core.py --agent zhiwei
├── xiaoguo_bot.py             # 兼容入口 → xmpp_agent_core.py --agent xiaoguo
├── gateway/                   # 运行时组件（脚本+工具+日志）
│   ├── README.md              # gateway 自身说明
│   ├── scripts/               # 运行时脚本
│   │   ├── chat_bridge.py     # xxm LLM 桥接（SessionBridge）
│   │   ├── session_router.py  # 消息路由
│   │   ├── wechat_agent.py    # ⛔ 已停用（微信桥接，由 Linux Docker wechatbot-webhook 替代）
│   │   │                      #    保留代码，不再运行
│   │   ├── article_processor.py# 文章处理服务 (5810) ← 保持运行！
│   │   │                      #    抓微信链接全文、OCR，WeChat bot 和 莫荷 都依赖它
│   │   ├── api_proxy.py       # API 反向代理 (:8787)
│   │   ├── xmpp_watchdog.py   # 进程看门狗
│   │   ├── health_check_xxm.py# 消息流健康检查
│   │   ├── mohe_watcher.py    # 莫荷消息监控
│   │   ├── dashboard.py       # 管理门户后端
│   │   ├── proc_guard.py      # PID 锁（防重复启动）
│   │   ├── qq_bot.py          # QQ bot 桥接
│   │   ├── vc_webhook.py      # VoceChat webhook
│   │   └── templates/
│   │       └── dashboard.html # 管理门户前端
│   ├── logs/                  # 运行时日志
│   └── tools/                 # wxhelper DLL 等工具
├── docs/
│   ├── ARCHITECTURE.md        # 架构设计文档
│   ├── AUDIT.md               # 稳定性审计报告
│   ├── CLEANUP_PLAN.md        # 代码清理方案
│   ├── OBSERVER-PROTOCOL.md   # 群聊观察者模式协议
│   ├── SESSION-BRIDGE-PROTOCOL.md  # 跨Session消息桥接协议
│   ├── PRD_v0.2.md           # 产品需求文档
│   ├── DEPLOY.md              # 部署指南
│   └── OPS.md                 # 运维手册
├── config/
│   ├── agents.yaml            # Agent 实例注册
│   └── .env.example           # 环境变量模板
├── configs/                   # 各 Agent 配置/SOUL
│   ├── main/
│   ├── mohe/
│   ├── xiaoguo/
│   └── position-analyst/
├── src/
│   ├── shared/
│   │   ├── config.py          # 集中配置管理（env-var 方式）
│   │   └── bot_base.py        # Bot 基类（功能已合并进 xmpp_agent_core.py）
│   ├── channels/
│   │   └── qq/
│   │       └── bridge.py      # QQ 通道骨架
│   └── ops/
│       └── watch_group.py     # 群聊监控
├── deploy/
│   ├── windows/
│   │   ├── start.ps1          # 一键启动
│   │   ├── stop.ps1           # 一键停止
│   │   └── check.ps1          # 状态检查
│   └── linux/
│       ├── install.sh         # 安装脚本
│       └── hermes-*.service   # systemd 模板
└── tests/                     # 测试套件
```

---

## 监控

| 组件 | 方式 | 频率 |
|------|------|------|
| 管理门户 | dashboard.py + Web UI (:5803) | 实时轮询 5s |
| xmpp Agent Bot | watchdog (xmpp_watchdog.py) | 30s |
| xmpp Agent 消息流 | health_check_xxm.py | 5min (scheduled task) |
| wechat_agent | 内置看门狗 | 120s |
| 日志 | `logs/health_check.log` | 人工查看 |

---

## 通信方式

群聊 `coregroup@conference.yoin.fun` 是所有参与者的公共空间。@ 某个 Agent 可单独对话。

| 协议 | 说明 |
|------|------|
| `@Agent名` / 点名 | 被点名的 Agent 必须回复 |
| `__SILENT__` | Agent 标记沉默（不发消息，仅记录上下文） |
| `__REPLY__` | Agent 标记需要回复 |
| `##command:args##` | Agent 命令系统 |

---

## 已知问题

| ID | 问题 | 平台 | 状态 |
|----|------|------|------|
| R01 | MUC join 超时 (conference.yoin.fun DNS) | Linux (ejabberd) | 🟢 已修复（join_muc + raw presence 双保险） |
| R02 | wechat_agent 无系统级自动恢复 | Windows | 🟡 |
| R03 | Gateway 进程无 systemd auto-restart | Linux | 🔴 |
| R04 | 日志无系统级轮转 | Windows + Linux | 🟡 |
| R05 | QQ 通道未实现 | Windows | 🟢 |

---

## 开发流程

1. **架构设计** → `docs/ARCHITECTURE.md`
2. **核心修改** → `xmpp_agent_core.py`（统一 Bot 核心，所有 Agent 共享）
3. **部署脚本** → `deploy/` 一键启停
4. **测试** → `tests/` 自动化测试
5. **文档** → `docs/` 持续更新
