refactor(xxm): consolidate 4 bot implementations into unified xmpp_agent_core.py

- Merge bot_base.py, gateway/scripts/xmpp_bot.py, bots/*, xmpp_bot_rest.py into single xmpp_agent_core.py with --agent flag (xxm|mohe|zhiwei|xiaoguo) - Add xxm_bot.py wrapper (encoding=utf-8 for Windows exec) - Fix slixmpp connect() API: use host=/port= keyword args (was tuple) - Clean up orphans: bots/, scripts/, hermes_state.py, xmpp_bot.py, xmpp_bot_rest.py - Add docs/CLEANUP_PLAN.md documenting the migration - Update README.md project structure - Also: fix WeChat agent path resolution (relative paths)
2026-06-21 16:13:57 +08:00
parent b9df510f31
commit babbc46801
22 changed files with 1273 additions and 5442 deletions
@@ -0,0 +1,268 @@
+# AgentsMeeting 代码清理方案
+
+> 目标：消除 XMPP Bot 代码碎片化，统一架构。所有 Agent 共享同一份核心代码。
+
+---
+
+## 1. 现状问题
+
+### 1.1 四套独立 Bot 实现
+
+| # | 位置 | 行数 | 状态 | 用途 | LLM 调用 |
+|---|------|-------|------|------|----------|
+| 1 | `gateway/scripts/xmpp_bot.py` | 943 | 活跃 | xxm bot | chat_bridge |
+| 2 | `xmpp_agent_core.py `（root） | 348 | 活跃 | mohe/zhiwei/xiaoguo | Hermes API |
+| 3 | `bots/xmpp_bot.py` + 姐妹文件 | 359 | 孤儿 | mohe/zhiwei/xiaoguo（旧版） | Hermes API |
+| 4 | `xmpp_bot_rest.py` | 72 | 废弃 | ejabberd REST 实验 | Hermes API |
+
+**问题**：同样的 XMPP 连接、MUC join、消息处理逻辑，在 4 套代码中重复实现。修复了其中一个，其他三个还是坏的。
+
+### 1.2 基础设施碎片化
+
+bot_base.py（263 行）已经提炼出完善的 XMPP 基类，但没有任何 bot 实际使用它：
+
+```
+bot_base.py 有：
+  ✓ PID 锁（proc_guard）
+  ✓ 自动重连 + MUC join 重试
+  ✓ 消息去重（dedup）
+  ✓ 消息合并（batching）
+  ✓ silence/shutup 协议
+  ✓ send_group / send_private
+
+没有被任何 bot 使用 ✗
+```
+
+### 1.3 重复/孤儿文件
+
+| 文件 | 问题 |
+|------|------|
+| `xmpp_bot.py`（root） | `xmpp_agent_core.py` 的较旧副本 |
+| `xmpp_bot_rest.py` | 废弃方案 |
+| `bots/` 目录（3 文件） | 被 xmpp_agent_core.py 取代 |
+| `hermes_state.py`（root） | 孤儿，import 已断 |
+| `scripts/`（6 文件） | 一次性脚本 |
+| `src/bots/{mohe,xiaoguo,xxm,zhiwei}/` | 空目录，重构未完成 |
+| `src/channels/wechat/` | 空目录 |
+
+---
+
+## 2. 目标架构
+
+```
+AgentsMeeting/
+├── xmpp_agent_core.py    ← 唯一 Bot 核心（统一架构）
+│                           支持 --agent xxm|mohe|zhiwei|xiaoguo
+│                           包含：PID锁/重连/MUC/dedup/batching/
+│                           coordinator协议/HTTP桥
+│
+├── xxm_bot.py            ← 兼容入口（python xxm_bot.py = python xmpp_agent_core.py --agent xxm）
+├── mohe_bot.py           ← 兼容入口
+├── xiaoguo_bot.py        ← 兼容入口
+├── zhiwei_bot.py          ← 兼容入口
+│
+└── gateway/
+    └── scripts/
+        ├── chat_bridge.py    ← xxm LLM 桥（不变）
+        ├── session_router.py ← 消息路由（不变）
+        └── ...（其他脚本不变）
+```
+
+**核心原则**：
+- `xmpp_agent_core.py` = 唯一核心，所有 Agent 共享
+- 每个 Agent 只有 LLM 调用方式不同（在配置中定义）
+- coordinator/GRANT/REVOKE 协议只有一个实现，所有 bot 统一遵守
+- `bot_base.py` 的基础设施合并进 `xmpp_agent_core.py`
+
+---
+
+## 3. 迁移步骤
+
+### Phase 0：确认基线（先保证现有 bot 正常工作）
+
+- [ ] 确认 `gateway/scripts/xmpp_bot.py` 当前运行正常，能收发群消息
+- [ ] 确认 `xmpp_agent_core.py`（mohe）当前运行正常
+
+### Phase 1：合并基础设施到 xmpp_agent_core.py
+
+将 `bot_base.py` 和 `gateway/scripts/xmpp_bot.py` 中的公共功能合并进 `xmpp_agent_core.py`：
+
+| 功能 | 来源 | 说明 |
+|------|------|------|
+| PID 锁（proc_guard） | bot_base.py / gateway | 防重复启动 |
+| 消息去重（dedup） | bot_base.py / gateway | 防重复处理同一条消息 |
+| 消息合并（batching） | bot_base.py / gateway | 3s debounce，附近消息合并一次 LLM 调用 |
+| 自动重连 | bot_base.py / gateway | slixmpp auto_reconnect + reconnect_max_delay |
+| MUC join 双重保证 | gateway | `join_muc()` + `send_raw(presence)` |
+| MAM 启动恢复 | gateway | 启动时拉取最近 50 条历史消息补上下文 |
+| HTTP 桥丰富 API | gateway | /health, /presence, /messages, POST /send |
+| sub-agent exec | gateway | `##exec:command##` 用于工具调用 |
+| delayed reply | gateway | `##delay:N##` 延迟回复 |
+
+### Phase 2：统一 coordinator 协议
+
+gateway/scripts/xmpp_bot.py 已经实现了 coordinator/GRANT/REVOKE 协议。将这套实现整合进 `xmpp_agent_core.py`，确保所有 Agent 使用同一份协议代码。
+
+### Phase 3：添加 xxm 作为支持 Agent
+
+在 `xmpp_agent_core.py` 的 AGENTS 配置中添加 xxm：
+
+```python
+AGENTS = {
+    "mohe":   {..., "gateway": "http://localhost:8642/v1/chat/completions"},
+    "zhiwei": {..., "gateway": "http://localhost:8643/v1/chat/completions"},
+    "xiaoguo":{..., "gateway": "http://localhost:8645/v1/chat/completions"},
+    "xxm":    {..., "bridge": "chat_bridge"},  # xxm 走本地 chat_bridge
+}
+```
+
+xxm 的 LLM 调用方式不同（不走 HTTP Hermes API，走本地 `chat_bridge.py`），所以需要在核心中抽象 LLM 调用层：
+
+```python
+def _call_llm(self, content: str) -> str:
+    if self.cfg.get("bridge") == "chat_bridge":
+        return _call_chat_bridge(content)    # 本地调用
+    else:
+        return _call_hermes_api(content, self.cfg["gateway"])  # HTTP 调用
+```
+
+### Phase 4：删除孤儿文件
+
+| 文件 | 操作 |
+|------|------|
+| `xmpp_bot.py`（root） | 移到 trashbox |
+| `xmpp_bot_rest.py` | 移到 trashbox |
+| `bots/` 整个目录 | 移到 trashbox |
+| `hermes_state.py`（root） | 移到 trashbox |
+| `scripts/gen_prd.py` | 移到 trashbox |
+| `scripts/write_prd.py` | 移到 trashbox |
+| `scripts/gen_prd_v02.py` | 移到 trashbox |
+| `scripts/write_prd_v02.py` | 移到 trashbox |
+| `scripts/build_prd.py` | 移到 trashbox |
+| `scripts/test_echo.py` | 移到 trashbox |
+| `scripts/gen_b64.py` | 保留（可能是通用工具） |
+
+### Phase 5：清理空目录
+
+| 目录 | 操作 |
+|------|------|
+| `src/bots/mohe/` | 删除 |
+| `src/bots/xiaoguo/` | 删除 |
+| `src/bots/xxm/` | 删除 |
+| `src/bots/zhiwei/` | 删除 |
+| `src/channels/wechat/` | 删除 |
+| `gateway/assets/` | 删除 |
+
+### Phase 6：整理 gateway/temp/
+
+保留：PID 文件、活跃缓存（.bridge_context.jsonl、.model_cache.json）
+其余 >200 个临时文件：移到 temp/archive/ 或按需清理。
+
+### Phase 7：文档更新
+
+- [ ] 更新 `docs/ARCHITECTURE.md` —— 反映统一架构
+- [ ] 更新 `README.md` —— 更新项目结构描述
+- [ ] 更新 `config/agents.yaml` —— 保持准确
+
+---
+
+## 4. 核心文件变更清单
+
+### 修改：xmpp_agent_core.py
+
+从 348 行扩展为 ~600 行，新增：
+
+```
+新增功能模块：
+├── proc_guard PID 锁
+├── 消息去重（_dedup_cache）
+├── 消息合并（_batch_* 系统，3s debounce）
+├── MAM 启动恢复（_fetch_mam_history）
+├── HTTP 桥丰富版（/health, /presence, /messages, POST /send）
+├── sub-agent exec（##exec:command##）
+├── delayed reply（##delay:N##）
+├── 抽象 LLM 调用层（支持 chat_bridge + Hermes API）
+└── coordinator/GRANT/REVOKE 协议（从 gateway 版提升）
+```
+
+新增 AGENTS 配置条目：
+
+```python
+"xxm": {
+    "jid": "xxm@yoin.fun",
+    "password": "hermes123",
+    "nick": "xxm",
+    "name_cn": "笑笑",
+    "bridge": "chat_bridge",           # 使用本地 chat_bridge
+    "http_port": 5802,                  # HTTP 桥端口
+    "muc_rooms": [
+        "coregroup@conference.yoin.fun",
+        "jujidina@conference.yoin.fun",
+    ],
+    "server": "192.168.1.246",          # LAN 直连
+    "port": 5222,
+    "session_id": "ses_xxm_xmpp",
+    "mention": "@xxm/@笑笑",
+}
+```
+
+### 创建：xxm_bot.py
+
+```
+#!/usr/bin/env python3
+"""Wrapper for xmpp_agent_core.py --agent xxm"""
+import sys, os
+sys.argv = [sys.argv[0], '--agent', 'xxm']
+exec(open(os.path.join(os.path.dirname(__file__), 'xmpp_agent_core.py')).read())
+```
+
+（与现有的 mohe_bot.py / zhiwei_bot.py / xiaoguo_bot.py 模式一致）
+
+### 保留不变
+
+| 文件 | 说明 |
+|------|------|
+| `gateway/scripts/chat_bridge.py` | xxm LLM 桥，不迁移 |
+| `gateway/scripts/session_router.py` | 消息路由，不迁移 |
+| `gateway/scripts/wechat_agent.py` | 微信桥接，独立组件 |
+| `gateway/scripts/qq_bot.py` | QQ bot，独立组件 |
+| `gateway/scripts/vc_webhook.py` | VoceChat webhook，独立组件 |
+| `gateway/scripts/dashboard.py` | 管理门户，独立组件 |
+| `gateway/scripts/health_check_xxm.py` | 健康检查，独立组件 |
+| `gateway/scripts/xmpp_watchdog.py` | 看门狗，独立组件 |
+| `gateway/scripts/mohe_watcher.py` | 莫荷消息监控，独立组件 |
+| `gateway/scripts/api_proxy.py` | API 代理，独立组件 |
+
+---
+
+## 5. 测试计划
+
+### 5.1 单元测试
+
+- [ ] `python tests/test_core.py` —— bot_base 测试保持通过
+- [ ] 新增测试：合并后的 xmpp_agent_core.py 的 LLM 抽象层
+
+### 5.2 集成测试
+
+- [ ] `python xmpp_agent_core.py --agent xxm` 能启动、连接、加入 MUC
+- [ ] `python xmpp_agent_core.py --agent mohe` 能启动、连接、加入 MUC
+- [ ] 各 Agent 在 coregroup 中能正确响应 @mention
+- [ ] coordinator/GRANT/REVOKE 协议各 Agent 一致
+
+### 5.3 部署验证
+
+- [ ] `python tests/verify_deploy.py` pass
+- [ ] gateway/scripts/xmpp_bot.py → 改为调用 xmpp_agent_core.py --agent xxm
+- [ ] Linux 端 update systemd service 指向新路径
+
+---
+
+## 6. 风险与回滚
+
+| 风险 | 缓解 |
+|------|------|
+| 合并后 xxm bot 不工作 | Phase 0 先备份当前 `gateway/scripts/xmpp_bot.py` |
+| 协议行为不一致 | coordinator 协议从 gateway 版提取，与 xmpp_agent_core 现有逻辑逐行对比 |
+| 启动命令需要改 | 兼容入口（xxm_bot.py 等）保持 CLI 不变 |
+
+**回滚方案**：Phase 1-4 每步完成后验证。出问题从 trashbox 恢复删除的文件。