AgentsMeeting/docs/CLEANUP_PLAN.md

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：

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 调用层：

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 配置条目：

"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 恢复删除的文件。