hmo
babbc46801
- 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)
269 lines
9.3 KiB
Markdown
269 lines
9.3 KiB
Markdown
# 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 恢复删除的文件。
|