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