Initial: multi-agent XMPP communication system with dashboard

- Platform-based architecture (Windows/Linux/Mac) - Agent instance registry (agents.yaml) - Management dashboard with cross-platform monitoring - xmpp_bot with HTTP bridge + health endpoints - wechat_agent with WeChat-Hermes bridging - Platform services: ProcessGuardian, HealthProbe, APIRouter, ChannelBridge - Deployment: systemd (Linux) + PowerShell (Windows) - Monitoring: SSH+ejabberdctl for cross-platform presence
2026-06-12 21:49:05 +08:00
commit 1b2b935832
76 changed files with 15943 additions and 0 deletions
@@ -0,0 +1,420 @@
+# AgentsMeeting — 系统架构设计文档
+
+> 版本: v0.2 | 状态: 草稿
+
+---
+
+## 1. 设计理念
+
+**不是特制零件拼装，而是通用框架。**
+
+核心原则：
+1. **平台抽象** — 按 Windows / Linux / Mac 分层，不按人名硬编码
+2. **实例化** — Agent 是一个可注册、可配置、可复制的组件，不是硬编码的个体
+3. **管理化** — 所有 Agent 通过 Dashboard 统一管理，不断联不黑盒
+4. **XMPP 是主通道** — 所有参与方通过 XMPP 通信，人类用标准客户端
+5. **通道解耦** — 微信/QQ 作为附属通道桥接到 XMPP，不绑死某个人或某台机器
+
+---
+
+## 2. 平台架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         AgentsMeeting 全沟通架构                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌─────────────────────┐         ┌─────────────────────────────────┐    │
+│  │ 人类客户端            │         │ XMPP 服务器                      │    │
+│  │ Gajim / Conversations│◄───────►│ ejabberd (Docker)               │    │
+│  │ Monal / 任意 XMPP    │  :3021  │ xmpp.yoin.fun:3021             │    │
+│  └─────────────────────┘         │  └─ MUC: coregroup@conference   │    │
+│                                    └─ MAM 消息归档                   │    │
+│                                   └─────────────────────────────────┘    │
+│                                              ▲ ▲ ▲                      │
+│                                     XMPP     │ │ │                      │
+│                              ┌───────────────┘ │ └─────────────┐         │
+│                              ▼                  ▼               ▼         │
+│  ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐      │
+│  │ Windows Platform  │ │ Linux Platform    │ │ Mac Platform      │      │
+│  │ 192.168.1.16      │ │ 192.168.1.246     │ │ 192.168.1.122     │      │
+│  │                   │ │                   │ │                   │      │
+│  │ ● Bot Engine      │ │ ● Bot Engine      │ │ ● Bot Engine      │      │
+│  │ ● WeChat Bridge   │ │ ● Hermes Gateways │ │ ● oMLX (本地LLM)  │      │
+│  │ ● API Proxy       │ │ ● Ejabberd Ops    │ │                   │      │
+│  │ ● Mgmt Dashboard  │ │ ● Cron Jobs       │ │                   │      │
+│  │ ● Health Monitor  │ │ ● Data Storage    │ │                   │      │
+│  │ ● Watchdog        │ │ ● Docker Fleet    │ │                   │      │
+│  └───────────────────┘ └───────────────────┘ └───────────────────┘      │
+│                                                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │ 附属通道 (Bridge Channels)                                        │    │
+│  │  ├─ WeChat: WeChat App → wxhelper DLL → wechat_agent → XMPP     │    │
+│  │  └─ QQ: QQ App → NapCat → QQ Bot → XMPP (规划中)                │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │ 管理门户 (Management Dashboard)                                    │    │
+│  │  Web UI → 查看 Agent 状态 → 启动/停止/重启 → 查看日志 → 配置管理   │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Agent 实例化体系
+
+### 3.1 Agent 定义
+
+一个 Agent 不再是一个硬编码的名字，而是一个**配置实例**：
+
+```yaml
+# config/agents.yaml — 所有已注册的 Agent 实例
+agents:
+  - id: "agent-001"
+    name: "研发助理"
+    display_name: "小小莫"
+    jid: "xxm@yoin.fun"
+    platform: windows          # windows | linux | mac
+    host: "192.168.1.16"
+    bot_type: xmpp             # xmpp | hermes | bridge
+    provider: volcengine
+    services:                  # 该 Agent 关联的服务
+      - type: xmpp_bot
+        script: xmpp_bot.py
+        port: 5802            # HTTP bridge
+      - type: wechat_bridge
+        script: wechat_agent.py
+        port: 5801
+
+  - id: "agent-002"
+    name: "自动化总管"
+    display_name: "莫荷"
+    jid: "mohe@yoin.fun"
+    platform: linux
+    host: "192.168.1.246"
+    bot_type: hermes
+    provider: ocg-new
+    services:
+      - type: hermes_gateway
+        port: 8642
+      - type: xmpp_bot
+
+  - id: "agent-003"
+    name: "本地推理"
+    display_name: "小果"
+    jid: "xiaoguo@yoin.fun"
+    platform: mac
+    host: "192.168.1.122"
+    bot_type: xmpp
+    provider: ocg-old
+    services:
+      - type: xmpp_bot
+      - type: omlx_server
+        port: 18003
+
+  - id: "agent-004"
+    name: "持仓分析"
+    display_name: "知微"
+    jid: "zhiwei@yoin.fun"
+    platform: linux
+    host: "192.168.1.246"
+    bot_type: hermes
+    provider: ocg-old
+    services:
+      - type: hermes_gateway
+        port: 8643
+      - type: xmpp_bot
+```
+
+### 3.2 添加新 Agent 流程
+
+```
+1. 在 config/agents.yaml 中添加一条记录（命名、选平台、分配 JID）
+2. 在 ejabberd 注册新 JID 账号
+3. 在对应平台机器上部署 bot 脚本
+4. 管理门户自动发现新 Agent（读 agents.yaml + 进程检测）
+5. 加入 MUC 群聊
+```
+
+### 3.3 平台能力矩阵
+
+| 能力 | Windows | Linux | Mac |
+|------|---------|-------|-----|
+| XMPP Bot | ✅ | ✅ | ✅ |
+| Hermes Gateway | ❌ | ✅ | ❌ |
+| WeChat Bridge | ✅ (wxhelper) | ❌ | ❌ |
+| QQ Bridge | ✅ (NapCat) | ✅ (NapCat) | ❌ |
+| API Proxy | ✅ | ✅ | ✅ |
+| 管理门户 | ✅ (主) | ❌ | ❌ |
+| Watchdog / Health | ✅ | ✅ (systemd) | ✅ |
+| 本地 LLM (oMLX) | ❌ | ❌ | ✅ |
+| Cron Jobs | ❌ (Scheduled Tasks) | ✅ | ❌ |
+| Docker 编排 | ✅ | ✅ | ❌ |
+| 数据存储 (SQLite) | ✅ | ✅ | ✅ |
+
+### 3.4 平台服务接口（统一接口，分平台实现）
+
+Agent 只管自己的业务逻辑（接收消息、调用 LLM、回复）。进程守护、健康检测、API 路由等是**平台服务**——每个平台用自己的方式实现，但对外接口一致。
+
+#### 服务类型定义
+
+| 服务类型 | 接口规范 | 职责 |
+|----------|---------|------|
+| **ProcessGuardian** | 暴露 `/health` 端点；提供 `start/stop/restart` 操作 | 守护目标进程存活，挂了自动拉起 |
+| **HealthProbe** | 返回 `{status: online\|degraded\|offline, last_msg_age: N}` | 检测消息流是否正常，识别"假活" |
+| **APIRouter** | 转发 `POST /v1/chat/completions`，provider fallback | 代理 LLM API 调用，吞掉错误码 |
+| **MessageObserver** | 监听指定 JID 的消息，写入日志 | 跨 Agent 通信监控 |
+| **ChannelBridge** | `POST /bridge/{channel}/send`，`GET /bridge/{channel}/messages` | 外部通道 ↔ XMPP 消息转发 |
+
+#### 各平台实现
+
+| 服务类型 | Windows | Linux | Mac |
+|----------|---------|-------|-----|
+| **ProcessGuardian** | `xmpp_watchdog.py`（30s 轮询） | systemd `Restart=always` | 待实现 |
+| **HealthProbe** | `health_check_xxm.py`（Task Scheduler 5min） | systemd timer / cron | 待实现 |
+| **APIRouter** | `api_proxy.py`（:8787） | hermes 内置 fallback | 不需要 |
+| **MessageObserver** | `mohe_watcher.py`（30s） | 不需要 | 不需要 |
+| **ChannelBridge** | `wechat_agent.py`（微信） | 无（微信需 Windows） | 不需要 |
+
+> **原则**：Agent 不关心平台用的是 watchdog 还是 systemd。它只需要知道"有人保证我活着"——这就是统一接口的意义。
+
+---
+
+## 4. 模块层级
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ Layer 6: 管理门户 (Management Dashboard)                        │
+│  Web UI · Agent 管理 · 状态监控 · 日志查看 · 启停控制           │
+├────────────────────────────────────────────────────────────────┤
+│ Layer 5: 运维层 (Operations)                                    │
+│  watchdog · health check · systemd/task scheduler · log rotate  │
+├────────────────────────────────────────────────────────────────┤
+│ Layer 4: 桥接层 (Bridge)                                        │
+│  wechat_agent · QQ bot (规划) · 消息格式转换 · 图片 OCR          │
+├────────────────────────────────────────────────────────────────┤
+│ Layer 3: 智能网关层 (AI Gateway)                                 │
+│  hermes-agent · profile 路由 · session 管理 · provider fallback │
+├────────────────────────────────────────────────────────────────┤
+│ Layer 2: Bot 引擎层 (Bot Engine)                                 │
+│  slixmpp 客户端 · HTTP bridge · MUC 群消息 · MAM 历史           │
+├────────────────────────────────────────────────────────────────┤
+│ Layer 1: 通信层 (Communication)                                  │
+│  ejabberd · MUC · XMPP/TLS · SRV DNS · 消息路由                 │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. 数据流
+
+### 5.1 群聊消息流（所有平台通用）
+
+```
+任意发送者（人类/Bot）
+  │
+  ▼
+ejabberd (MUC coregroup@conference.yoin.fun)
+  │ 广播
+  ▼
+所有在线 Bot（通过 slixmpp 接收）
+  │
+  ▼
+观察者模式判断：
+  ├─ @点名我 → 需要回复 → Gateway/LLM → 回复到群
+  ├─ 上下文指向我 → 需要回复 → Gateway/LLM → 回复到群
+  └─ 与我无关 → 仅记录上下文 → 不回复
+```
+
+### 5.2 Gateway 处理流
+
+```
+Bot 引擎收到需要回复的消息
+  │
+  ▼
+提取: sender_jid, message_body, context
+  │
+  ▼
+Gateway API (HTTP POST → localhost:{port}/v1/chat/completions)
+  │
+  ├─ 注入 SOUL.md + MEMORY.md + USER.md
+  ├─ 加载最近 200 条上下文
+  ├─ Provider 选择 (主 provider → fallback 链)
+  └─ LLM 生成
+       │
+       ▼
+  解析回复
+       ├─ ##command## → 执行工具调用 → 结果追加到上下文 → 循环
+       └─ 纯文本 → 返回
+            │
+            ▼
+       Bot 引擎 → XMPP 发送到群
+```
+
+### 5.3 微信通道流（Windows 平台专属）
+
+```
+微信消息
+  │
+  ▼
+WeChat App → wxhelper DLL 注入 → TCP :19099
+  │
+  ▼
+wechat_agent.py
+  ├─ 文字: POST → Hermes Gateway (Linux) → LLM → 回复
+  ├─ 图片: downloadAttach → decodeImage → OCR → 文字发给 Gateway
+  └─ 回复: wxhelper HTTP :19088 发送回微信
+```
+
+---
+
+## 6. 组件通信矩阵
+
+| 组件 | 协议 | 端口 | 说明 |
+|------|------|------|------|
+| Bot ↔ ejabberd | XMPP/TLS | 3021 | 标准 XMPP |
+| Bot ↔ Gateway | HTTP REST | 动态分配 | OpenAI 兼容 API |
+| WeChat Agent ↔ Gateway | HTTP | 8642 | Hermes API |
+| WeChat Agent ↔ wxhelper | HTTP | 19088 | 微信消息收发 |
+| WeChat Agent ↔ wxhelper | TCP | 19099 | 微信事件推送 |
+| 管理门户 ↔ Bot | HTTP | 5803 | Dashboard API |
+| 人类 ↔ ejabberd | XMPP/TLS | 3021 | 标准客户端 |
+| API Proxy → Provider | HTTPS | 443 | 转发到火山/OCG |
+| Bot 启动器 ↔ 进程 | subprocess | - | 进程管理 |
+
+---
+
+## 7. 管理门户设计
+
+### 7.1 功能
+
+| 功能 | 说明 |
+|------|------|
+| Agent 列表 | 所有已注册 Agent，含名称/JID/平台/状态 |
+| 连接状态 | XMPP 在线/离线、Bot 进程是否存活、最后消息时间 |
+| 启停控制 | 启动/停止/重启 单个 Agent 的 Bot 进程 |
+| 日志查看 | 实时 tail 关键日志（bot.log / health_check.log） |
+| 健康指标 | 最近 N 分钟消息数、响应延迟、错误率 |
+| 告警规则 | Agent 离线 >N 分钟告警、Bot 假死（在线但无消息）告警 |
+| 配置浏览 | 查看当前 agents.yaml 配置 |
+
+### 7.2 技术方案
+
+| 层 | 选型 | 理由 |
+|----|------|------|
+| 后端 | Python Flask (:5803) | 零依赖，和现有 bot 一致 |
+| 前端 | 单页 HTML + 原生 JS + CSS | 无构建步骤，直接 serve |
+| 数据源 | SSH + ejabberdctl → 跨平台在线检测 | 比 MUC/roster 更可靠，不依赖 Bot 自身状态 |
+| 本地补充 | 进程列表 + xmpp_bot /health 端点 | Windows 本地进程检测 |
+| 实时更新 | 前端 5s 轮询 | 简单可靠 |
+| 自动恢复 | 连续 3 次离线检测 → 自动重启 | 仅限 Windows 本地 Agent |
+
+### 7.3 监控架构
+
+```
+Dashboard (:5803)
+  │
+  ├── SSH → 192.168.1.246 → ejabberdctl connected_users
+  │     └── 返回所有在线 JID 列表（跨平台权威数据源）
+  │
+  ├── GET :5802/health
+  │     └── XMPP 连接状态 + ejabberd 是否存活
+  │
+  ├── GET :5802/presence/{jid}
+  │     └── Roster presence（备选）
+  │
+  └── 本地进程检测 (Get-CimInstance)
+        └── Windows 进程存活 + PID
+```
+
+### 7.3 后端 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/agents | 所有 Agent 状态 |
+| GET | /api/agents/{id} | 单个 Agent 详情 |
+| GET | /api/agents/{id}/logs | tail 日志 |
+| POST | /api/agents/{id}/start | 启动 Bot |
+| POST | /api/agents/{id}/stop | 停止 Bot |
+| POST | /api/agents/{id}/restart | 重启 Bot |
+| GET | /api/health | Dashboard 自身健康检查 |
+
+---
+
+## 8. 配置管理
+
+### 8.1 配置分层
+
+```
+config/
+├── agents.yaml           # Agent 实例注册表 (核心)
+├── providers.yaml        # AI 提供商配置
+├── platforms.yaml        # 平台能力声明
+├── .env.example          # 环境变量模板
+└── profiles/             # 每个 Agent 的个性化配置
+    └── {agent-name}/
+        ├── system_prompt.txt
+        ├── memory.txt
+        └── tools.yaml
+```
+
+### 8.2 Provider 配置
+
+```yaml
+# config/providers.yaml
+providers:
+  volcengine:
+    api_key: ${VOLCENGINE_KEY}
+    base_url: https://ark.cn-beijing.volces.com/api/coding/v3
+    models: [deepseek-v4-pro, deepseek-v4-flash]
+  ocg-new:
+    api_key: ${OCG_NEW_KEY}
+    base_url: https://opencode.ai/zen/go/v1
+  ocg-old:
+    api_key: ${OCG_OLD_KEY}
+    base_url: https://opencode.ai/zen/go/v1
+  omlx:
+    api_key: ${OMLX_KEY}
+    base_url: http://192.168.1.122:18003/v1
+```
+
+---
+
+## 9. 运维体系
+
+### 9.1 平台运维职责
+
+| 职责 | Windows | Linux | Mac |
+|------|---------|-------|-----|
+| 进程存活监控 | watchdog (30s) | systemd (auto-restart) | launchd / cron |
+| 消息流监控 | health_check (5min) | 待实现 | 待实现 |
+| 日志轮转 | watchdog 内置 (15min/5MB) | 待实现 | 待实现 |
+| 自动恢复 | 进程死→自动重启 | systemd Restart=always | 待实现 |
+| 假死检测 | 在线但无消息 >10min → 重启 | 待实现 | 待实现 |
+| 告警通知 | Dashboard 显示 | XMPP 群消息 | XMPP 群消息 |
+
+### 9.2 日志体系
+
+| 日志 | 位置 | 轮转 | 内容 |
+|------|------|------|------|
+| bot.log | gateway/logs/ | ✅ 15min/5MB | Bot 连接/消息/HTTP桥 |
+| bridge.log | gateway/logs/ | 无 | LLM API 调用/耗时 |
+| watchdog.log | gateway/logs/ | ✅ 15min/5MB | Watchdog 启停 |
+| health_check.log | gateway/logs/ | 无 | 健康检查结果 |
+| mohe_inbox.log | gateway/logs/ | 无 | 莫荷消息记录 |
+
+---
+
+## 10. 已知问题
+
+| ID | 问题 | 平台 | 状态 | 说明 |
+|----|------|------|------|------|
+| R01 | MUC join 超时 (conference.yoin.fun cert) | Linux (ejabberd) | 🟡 | 已加自签证书，join_muc_wait 仍超时；已用 SSH+ejabberdctl 绕过 |
+| R02 | xmpp_bot 频繁断连 (~50s) | Windows | 🔴 | 阿里云 Nginx 代理 TCP idle timeout |
+| R03 | 日志无系统级轮转（除 watchdog 内置） | Windows + Linux | 🟡 | |
+| R04 | Provider fallback 链可能无限循环 | 全部 | 🟡 | |
+| R05 | QQ 通道未实现 | Windows | 🟢 | |
+| R06 | 部分 Gateway 进程缺 systemd 管理 | Linux | 🟡 | |
+| R07 | API Key 明文在 config.yaml | Linux | 🟡 | |
@@ -0,0 +1,113 @@
+# AgentsMeeting 稳定性审计报告
+> 执行人: Sisyphus (xxm) | 日期: 2026-06-11 | 版本: v1
+
+---
+
+## 🔴 CRITICAL — 敏感信息泄露
+
+### C1. hermes-agent 配置文件中 API Key 明文
+**文件**: `hermes-agent/samples/config*/config.yaml`
+**内容**: 所有 profile 的 `providers` 节包含以下真实 key：
+- `ocg-new`: `sk-5miR8x...`
+- `ocg-old`: `sk-MBLGxs...`
+- `volcengine`: `b0359bed-...`
+- `omlx`: `7debc5f...`
+
+**风险**: 这些文件被复制到 AgentsMeeting 项目目录，如果不慎提交到 Git 或泄露，API key 全部暴露。
+**修复**: 用环境变量 `${HERMES_OCG_KEY}` 等模板替代，真实的 key 从 Linux 服务器上的实际部署配置加载。
+
+### C2. ViNote 项目 API Key 在 .env 文件
+**文件**: `systems/ViNote/.env`
+**内容**: `OPENAI_API_KEY=sk-56a8e42...` (DashScope key)
+**风险**: .env 文件在 .gitignore 中但实际存在，且包含真实 key。
+
+### C3. OpenCode config 中 MCP API Key 明文
+**文件**: `~/.config/opencode/config.json`
+**内容**: `MINIMAX_API_KEY=sk-cp-Mj6FH...` 直接写在 opencode 配置中
+**风险**: 该文件虽在用户目录，但任何能读 `~/.config/opencode/` 的进程都能获取该 key。
+
+---
+
+## 🟠 HIGH — 稳定性风险
+
+### H1. wechat_agent.py 无自动恢复机制
+- wechat_agent 有看门狗 (每120s检查) 但无系统级自动重启
+- 当前依赖 `start_agent.bat` 手动启动
+- 建议: systemd 或 Windows Task Scheduler 加守护
+
+### H2. XMPP Bot MUC 连接不稳定
+- MUC join 频繁超时（60s × 3次），DNS 解析 `conference.yoin.fun` 偶尔失败
+- Bot 依赖 MAM 订阅作为 fallback 收消息，但这不是正式通道
+- 建议: 解决 DNS 或 ejabberd MUC 组件配置
+
+### H3. wechat_agent 异常处理过于宽泛
+- 28 个 `except Exception as e` 块，但没有区分可恢复/不可恢复错误
+- 建议: 分类处理（网络重试 vs 致命错误报�?
+
+### H4. api_proxy.py:8787 单点故障
+- 代理用于绕过 opencode retry-cache，但如果挂了，chat_bridge 不经过代理直接调 API
+- 代理无守护/自恢复
+
+---
+
+## 🟡 MEDIUM — 设计问题
+
+### M1. Provider fallback 链可能有循环依赖
+```
+volcengine → ocg-old → ocg-new → volcengine (循环!)
+```
+如果三个 provider 同时出问题，fallback 会死循环。
+
+### M2. 跨 bot agent 的 identity 可能漂移
+- SOUL.md 文件内容不一致——有些 profile 有 `__SILENT__` 规则，有些没有
+- 规则冲突时会优先执行 MEMORY 而非 SOUL（已知问题 R05）
+
+### M3. 健康检查只检查 bot 进程，不检查 bot 是否真的能回应
+- `health_check_xxm.py` 只检查日志活跃度，不模拟真实消息
+- watchdog 只检查进程存活，不检查 LLM 是否能正常调�?
+
+---
+
+## 🟢 LOW — 代码规范
+
+### L1. 工具调用循环超限后产出垃圾
+- `_MAX_TOOL_LOOPS = 30`，超限后 final force 可能仍产出低质量回复
+- 缺少写入文件专用工具（只能用 run_command 模拟）
+- ✅ 已修复：final force 用干净上下文
+
+### L2. 文件写入效率低
+- LLM 用 `python -c` 覆盖写入文件，无法增量写入
+- 缺少 append 模式指导
+- ✅ 已修复：system prompt 加了文件写入指导
+
+### L3. `config/` 和 `src/` 目录为空
+- AgentsMeeting 的 `src/` 和 `config/` 完全空�?
+- 代码散落在根目录和 hermes-agent 子目录
+- 需要按项目结构整理
+
+---
+
+## 📊 进展统计
+
+### 已修复
+| # | 问题 | 状态 |
+|---|------|------|
+| 1 | `part_` 前缀 bug | ✅ 已修 |
+| 2 | final force XML 泄露 | ✅ 已修 |
+| 3 | shutup 模式太宽 | ✅ 已修 |
+| 4 | self-message 检查顺序 | ✅ 已修 |
+| 5 | ses_xxm_xmpp session 不存在 | ✅ 已修 |
+| 6 | MAX_TOOL_LOOPS 不够 | ✅ 已修 |
+| 7 | 旧数据 part_ 前缀 | ✅ 已修 |
+| 8 | con/nul 文件 | ✅ 已修 |
+| 9 | watchdog + 健康检查 | ✅ 已部署 |
+
+### 待修复
+| # | 问题 | 优先级 | 建议 |
+|---|------|--------|------|
+| C1-C3 | API Key 泄露 | 🔴 | 用 env var 替�?|
+| H1 | wechat_agent 无自动恢复 | 🟠 | systemd/scheduled task |
+| H2 | MUC 连接不稳定 | 🟠 | 查 ejabberd MUC 配置 |
+| H3 | 异常处理过宽 | 🟠 | 分类 error type |
+| M1 | Provider 循环依赖 | 🟡 | 设 max fallback depth |
+| M3 | 健康检查不检测实际功能 | 🟡 | 加 bot 实际响应检测 |
@@ -0,0 +1,124 @@
+# AgentsMeeting — 部署指南
+
+> 版本: v2.0 | 日期: 2026-06-12
+
+---
+
+## 部署概览
+
+| 组件 | 平台 | 守护 | 端口 |
+|------|------|------|------|
+| **Dashboard** | Linux (192.168.1.246) | systemd `agentsmeeting-dashboard` | 5803 |
+| **xmpp_bot (xxm)** | Windows (192.168.1.16) | watchdog (30s) | 5802 |
+| **wechat_agent** | Windows (192.168.1.16) | 内置看门狗 | 5801, 19088 |
+| **api_proxy** | Windows (192.168.1.16) | watchdog | 8787 |
+| **watchdog** | Windows (192.168.1.16) | 自身 | — |
+| **health_check** | Windows (192.168.1.16) | Task Scheduler | — |
+| **ejabberd** | Linux Docker (192.168.1.246) | Docker restart policy | 5222 |
+| **hermes-gateway** | Linux (192.168.1.246) | systemd | 8642, 8643, 8645 |
+| **mohe/xiaoguo/zhiwei bots** | Linux/Mac | systemd | — |
+
+---
+
+## 1. Linux 端 (192.168.1.246)
+
+### 1.1 Dashboard
+
+```bash
+# 服务文件: /etc/systemd/system/agentsmeeting-dashboard.service
+sudo systemctl status agentsmeeting-dashboard
+sudo systemctl restart agentsmeeting-dashboard
+
+# 日志
+sudo journalctl -u agentsmeeting-dashboard -f
+
+# 访问: http://192.168.1.246:5803
+```
+
+### 1.2 ejabberd
+
+```bash
+cd /opt/ejabberd
+docker compose restart
+docker exec ejabberd ejabberdctl connected_users
+```
+
+### 1.3 防火墙
+
+```bash
+sudo ufw status | grep -E '5803|5802'
+# Dashboard: 5803
+# xmpp_bot bridge: 5802 (from Windows)
+```
+
+---
+
+## 2. Windows 端 (192.168.1.16)
+
+### 2.1 前置条件
+
+- Python 3.10: `C:\Users\hmo\AppData\Local\Programs\Python\Python310\python.exe`
+- pip 包: `slixmpp`, `flask`, `pyyaml`, `requests`
+
+### 2.2 一键部署
+
+```powershell
+cd D:\F\NewI\opencode\daily-workspace\projects\AgentsMeeting
+powershell -File deploy\windows\start.ps1
+```
+
+自动完成：停止旧进程 → api_proxy → wechat_agent → xmpp_bot → watchdog → health_check 定时任务
+
+### 2.3 验证
+
+```powershell
+powershell -File deploy\windows\check.ps1
+```
+
+预期输出：
+
+```
+xmpp_bot:     RUNNING (PID xxxx)
+http_bridge:  OK (N msgs)
+wechat_agent: RUNNING (PID xxxx)
+watchdog:     RUNNING (PID xxxx)
+api_proxy:    RUNNING (:8787)
+dashboard:    http://192.168.1.246:5803
+```
+
+---
+
+## 3. 人类客户端
+
+| 客户端 | 平台 | 配置 |
+|--------|------|------|
+| Gajim | Windows/Linux | 服务器 `xmpp.yoin.fun`，端口 `3021`，STARTTLS |
+| Conversations | Android | 同上 |
+| Monal | iOS | 同上 |
+
+群聊：`coregroup@conference.yoin.fun`
+
+---
+
+## 4. 网络拓扑
+
+```
+Windows (192.168.1.16)          Linux (192.168.1.246)
+─────────────────────────        ────────────────────────
+xmpp_bot :5802  ──────────────►  Dashboard :5803
+wechat_agent :5801 ──health──►  Docker ejabberd :5222
+api_proxy :8787                  hermes-gateway :8642
+                                   frpc tunnel ──► Alibaba Cloud (47.115.32.206)
+                                                     └─ frps :3021 → XMPP traffic
+```
+
+---
+
+## 5. 故障恢复
+
+| 问题 | 命令 |
+|------|------|
+| Dashboard 挂了 | `ssh hmo@192.168.1.246 "sudo systemctl restart agentsmeeting-dashboard"` |
+| xmpp_bot 挂了 | `powershell -File deploy\windows\start.ps1` （watchdog 30s 自动重启） |
+| ejabberd 挂了 | `ssh hmo@192.168.1.246 "cd /opt/ejabberd && docker compose restart"` |
+| 全部瘫了 | 先 Linux: `docker compose restart` + `systemctl restart agentsmeeting-dashboard`，再 Windows: `start.ps1` |
@@ -0,0 +1,128 @@
+# AgentsMeeting — 运维手册
+
+> 版本: v2.0 | 日期: 2026-06-12
+
+---
+
+## 日常检查
+
+### Dashboard
+
+打开 `http://192.168.1.246:5803` 查看所有 Agent 和平台服务状态。
+
+- 绿色 = 在线
+- 黄色 = degraded（进程活着但 XMPP 不稳）
+- 红色 = 离线
+- 灰色 = 未知（远程 Agent，无法检测）
+
+展开 Agent 卡片可查看实时日志。
+
+### 命令行检查
+
+```powershell
+# Windows 快速状态
+powershell -File deploy\windows\check.ps1
+```
+
+```bash
+# Linux 所有 systemd 服务
+systemctl status agentsmeeting-dashboard hermes-gateway@{profile} xmpp-bot-{name}
+```
+
+---
+
+## 监控架构
+
+```
+Dashboard (:5803, Linux)
+  │
+  ├── Docker exec ejabberdctl → 在线 JID 列表（跨平台权威）
+  ├── GET 192.168.1.16:5802/health → xmpp_bot XMPP 连接状态
+  ├── GET 192.168.1.16:5801/health → wechat_agent hermes 连接状态
+  └── TCP connect 192.168.1.16:8787 → api_proxy 端口可达性
+```
+
+---
+
+## systemd 服务（Linux）
+
+| 服务 | 命令 |
+|------|------|
+| agentsmeeting-dashboard | `systemctl status/restart agentsmeeting-dashboard` |
+| hermes-gateway@main | `systemctl status hermes-gateway@main` |
+| hermes-gateway@zhiwei | `systemctl status hermes-gateway@zhiwei` |
+| hermes-gateway@xiaoguo | `systemctl status hermes-gateway@xiaoguo` |
+| xmpp-bot-mohe | `systemctl status xmpp-bot-mohe` |
+| xmpp-bot-zhiwei | `systemctl status xmpp-bot-zhiwei` |
+
+---
+
+## 健康端点
+
+| 服务 | URL | 含义 |
+|------|-----|------|
+| xmpp_bot | `GET :5802/health` | `xmpp_connected` = XMPP 是否在线 |
+| wechat_agent | `GET :5801/health` | `hermes_connected` = 到莫荷 gateway 是否通 |
+| Dashboard | `GET :5803/api/health` | Dashboard 自身是否正常 |
+| Dashboard | `GET :5803/api/ejabberd` | ejabberd 在线用户列表 |
+| Dashboard | `GET :5803/api/platform` | 平台服务状态 |
+
+---
+
+## 日志位置
+
+| 日志 | Windows 路径 | 用途 |
+|------|-------------|------|
+| xmpp_bot.log | `gateway\logs\` | bot 连接/消息/HTTP 桥 |
+| bridge.log | `gateway\logs\` | LLM API 调用 |
+| watchdog.log | `gateway\logs\` | 看门狗启停 |
+| health_check.log | `gateway\logs\` | 5 分钟健康检查 |
+| dashboard.log | `gateway\logs\` | Dashboard 运行日志 |
+| mohe_inbox.log | `gateway\logs\` | 莫荷消息记录 |
+
+Linux Dashboard 日志：`sudo journalctl -u agentsmeeting-dashboard -f`
+
+---
+
+## 常见故障
+
+### Bot 频繁断连
+
+**症状**: 日志每 ~50 秒出现 `disconnected, reconnecting...`
+
+**根因**: ejabberd `mod_ping: timeout_action: kill` 在 frp 隧道延迟下超时
+
+**已修复**: `timeout_action: none`
+
+### MUC 加群失败
+
+**症状**: `MUC join timeout (1/3) ... MUC setup failed`
+
+**根因**: ejabberd TLS 证书未覆盖 `conference.yoin.fun`
+
+**已修复**: 生成自签证书 `conference.pem` 并加入 certfiles；用 SSH+ejabberdctl 绕过跨平台监控
+
+### API Key 额度超限
+
+**症状**: bridge.log 显示 `HTTP 429`，bot 不回复
+
+**处理**: 等待配额重置（火山每月 15 日 00:00 CST），或切换 provider
+
+### 两个 bot 同时跑
+
+**症状**: 消息重复回应
+
+**根因**: watchdog 没杀旧进程就启动新进程
+
+**已修复**: watchdog `start_bot()` 先 kill 旧进程 + `proc_guard` PID 锁
+
+---
+
+## 数据管理
+
+```bash
+# Linux 端 — Hermes session 归档
+cd ~/.hermes/profiles/main/
+cp state.db state.db.$(date +%Y%m%d)
+hermes session prune --older-than 30d
+```
@@ -0,0 +1,163 @@
+# AgentsMeeting — 产品需求文档 (PRD)
+
+> 版本: v0.1 | 状态: 初稿 | 客户: hmo (老莫) | PM: mohe (莫荷) | 研发: xxm (小小莫)
+
+---
+
+## 1. 项目背景
+
+老莫运营一套多 Agent 协作系统，涵盖 XMPP 消息通道、AI Gateway、会话管理、记忆系统、Provider 调用链、多 profile 隔离等模块。系统经过数月迭代已具备完整功能，但存在以下问题：
+
+- 频繁断连/失联 — Gateway 进程意外退出、XMPP bot 掉线后重连失败、provider key 过期/配额超限
+- 架构文档缺失 — 系统仅以代码和配置形式存在，缺乏完整架构图、数据流文档和模块边界定义
+- 模块耦合不清晰 — Gateway、Session、Memory、Provider 之间的依赖关系未显式定义，排障困难
+- 部署标准化不足 — 各 profile 的启动/重启/监控流程不统一
+- 排查效率低 — 断联事件发生后需人工翻日志逐一排查，缺乏监控告警体系
+
+**立项目标：** 将现有系统按软件工程规范进行文档化、模块化整理，查漏补缺，不推倒重来。最终产出标准化源码包、部署脚本和运维文档，可稳定部署到服务器并支持客户端对接。
+
+---
+
+## 2. 系统范围
+
+### 2.1 消息通道层 (Channels)
+
+- **XMPP 通道** — 通过 ejabberd 服务器 + XMPP bot (slixmpp) 实现群聊/私聊消息收发。bot 进程：xmpp_bot.py (mohe)、xmpp_xiaoguo_bot.py、xmpp_zhiwei_bot.py。支持 __SILENT__/__REPLY__ 前缀机制控制 bot 输出行为。
+- **微信通道** — Windows 端 wechat_agent 桥接程序，抓取微信消息后通过 HTTP POST 到 Gateway，回复经 5801 端口推回微信窗口，长消息拆分为 2000 字/段。
+- **QQ 通道** — 规划中，未实现。
+
+### 2.2 Gateway 层
+
+- 基于 hermes-agent 框架，每个 profile 独立 Gateway 进程。
+- 职责：消息路由、会话管理、Provider 调用链、工具执行、回复生成。
+- 端口映射：8642(默认)、8643(知微)、8645(小果)、8646(mohe旧/废弃)
+- 超时配置：1800s 总超时，900s 告警，180s 通知间隔。
+- 健康检查：/v1/health 端点返回 pong。
+
+### 2.3 会话管理层 (Session)
+
+- 存储：SQLite (state.db)，各 profile 独立文件。
+- 核心机制：硬截断最近 200 条消息 (hermes_state.py LIMIT 200)。
+- session_rewrite：可设置重写规则（如默认 → sisyphus）。
+- 已知问题：Gateway 内存缓存 session，移走 state.db 后需重启进程才生效。
+
+### 2.4 记忆系统 (Memory)
+
+- **SOUL.md** — 系统提示，行为最高准则（身份锚定、行为规则、沉默机制）。
+- **MEMORY.md** — 长期记忆，被 LLM 检索并注入上下文。
+- **USER.md** — 用户画像，记录沟通风格和偏好。
+- 已知问题：SOUL 与 MEMORY 规则冲突时，LLM 优先执行 MEMORY 中的简略规则。
+
+### 2.5 Provider 调用链
+
+- 每个 profile 独立配置 provider 和 fallback 链。
+- 支持：volcengine (火山引擎)、ocg-old/ocg-new、omlx (本地 MLX)。
+- credential_pool_strategies：多 key 轮询/fallback 策略。
+- 已知问题：key 过期/配额超限后 fallback 可能因配置格式问题不触发。
+
+### 2.6 辅助系统
+
+- **cron 调度系统** — 14 个 job（价格监控、数据同步、持仓分析等）。
+- **MoFin 股票系统** — price_monitor、technical_analysis、strategy 模块。
+- **MCP 服务** — agentmemory (记忆检索)、websearch (网络搜索)。
+- **Skills 系统** — 34 个技能分类。
+- **Web Dashboard** — 状态监控页面。
+
+### 2.7 基础设施
+
+- **服务器** — Linux 192.168.1.246 (主阵地，所有 Gateway/cron/XMPP bot/ejabberd)
+- **客户端** — Windows 192.168.1.16 (跑 wechat_agent 桥 + xxm chat_bridge)
+- **阿里云中转** — 47.115.32.206 (备用/中转)
+- **XMPP 服务器** — ejabberd (Docker)
+- **进程管理** — systemd service（每个 Gateway + 每个 Bot 独立 service）
+
+---
+
+## 3. 数据流
+
+### 3.1 XMPP 消息流
+
+用户 → ejabberd → XMPP Bot → POST /v1/chat/completions → Gateway(localhost:{port}) → Session → Memory → Provider → 回复 → ejabberdctl send_stanza → ejabberd → 用户
+
+### 3.2 微信消息流
+
+微信 → wechat_agent(Windows) → POST 192.168.1.246:8642/v1/chat/completions → Gateway 8642 → Session + Memory + Provider → 回复 → POST 192.168.1.246:5801 → wechat_agent → 微信
+
+---
+
+## 4. 已知问题与风险
+
+| 编号 | 问题 | 影响 | 当前措施 | 优先级 |
+|------|------|------|----------|--------|
+| R01 | Gateway 进程意外退出未自动拉起 | 服务中断 | 无自动恢复 | P0 |
+| R02 | XMPP Bot 断线后重连失败 | 消息丢失 | slixmpp reconnect 不可靠 | P0 |
+| R03 | Provider key 过期/配额超限无告警 | LLM 调用失败 | fallback 不总能触发 | P0 |
+| R04 | Session 膨胀导致响应退化 | 回复质量下降 | 硬截断 200 条 | P1 |
+| R05 | SOUL vs MEMORY 规则冲突 | 行为异常 | 需手动清理 memory | P1 |
+| R06 | Gateway 非热加载 session | 更新需重启进程 | 手动 kill -9 | P1 |
+| R07 | 群聊消息路由混淆 | LLM 分不清职责 | 来源标记 + 身份锚定 | P2 |
+| R08 | 缺乏统一监控告警 | 排障依赖人工 | 无 | P1 |
+| R09 | QQ 通道未实现 | 缺少渠道 | 规划中 | P3 |
+
+### 4.1 根因详解
+
+1. **消息路由混淆** — 群聊消息进同一 session 后 LLM 分不清哪条是自己该处理的。已通过 [群聊] 时间戳来源标记 + 独立 session 隔离缓解。
+
+2. **粘性 session** — Gateway 进程即使移走 session 文件，内存中缓存的旧 session 仍存在，必须 kill 重启。
+
+3. **SOUL vs MEMORY 冲突** — SOUL 是系统提示，MEMORY 是上下文，LLM 检索 MEMORY 命中时会覆盖 SOUL 规则。这是小果“闭不了嘴”的根因。
+
+4. **会话膨胀 → 响应退化** — 知微曾出现 13.8 万 token 上下文，223 条消息中仅 26 条是用户消息。已用硬截断 200 条解决。
+
+5. **通道断连** — XMPP bot systemd 显示 active 但实际未连上 ejabberd。ejabberd 长期不活跃连接会被自动踢掉。
+
+6. **网络拓扑混乱** — 192.168.1.246 (Linux 服务器) 与 47.115.32.206 (阿里云) 混淆，曾导致 SSH 排查走错路。
+
+---
+
+## 5. 设计原则
+
+1. **一条消息只经过一个 Session** — 通道级隔离，不跨 profile 共享上下文。
+2. **SOUL.md 是行为最高准则** — MEMORY 不应包含与 SOUL 冲突的规则。
+3. **所有进程支持健康检查和自动重启** — systemd + 心跳检测。
+4. **数据流路径可追踪** — 消息来源 → Gateway → Session → LLM → 回复 → 目标通道，每一步可日志追踪。
+5. **配置即代码** — 所有配置纳入版本管理。
+6. **不推倒重来** — 以现有代码为基础，只做文档化和查漏补缺。
+---
+
+## 6. 交付物清单
+
+| 交付物 | 负责人 | 状态 |
+|--------|--------|------|
+| PRD (本文档) | xxm | 初稿 |
+| 系统架构设计文档 | xxm + mohe | 待起草 |
+| 模块接口规范 | xxm | 待起草 |
+| 代码工程化 (src/ 迁移) | xxm | 待启动 |
+| 部署与运维文档 | xxm + mohe | 待起草 |
+| 测试套件 | xxm | 待启动 |
+| 断连根因修复清单 | mohe | 待整理 |
+| 部署脚本 | xxm + mohe | 待启动 |
+
+---
+
+## 7. 项目时间线
+
+| 阶段 | 内容 | 时间 |
+|------|------|------|
+| 阶段0 | 资产盘点 | Day 1 ✅ |
+| 阶段1 | PRD + 架构设计 | Day 2-3 |
+| 阶段2 | 代码工程化 | Day 4-7 |
+| 阶段3 | 断连根因修复 + 测试 | Day 8-10 |
+| 阶段4 | 部署上线 + 验收 | Day 11-12 |
+
+---
+
+## 8. 角色与职责
+
+- **客户 (老莫 hmo)** — 需求提出方，审阅并确认所有交付物
+- **PM (莫荷 mohe)** — 资源协调、架构审核、进度跟踪、质量验收
+- **研发 (小小莫 xxm)** — 文档起草、代码工程化、部署实施
+
+---
+
+*PRD v0.1 — 文档结束*
@@ -0,0 +1,45 @@
+# AgentsMeeting — 快速操作手册
+
+## 每天例行
+
+```powershell
+# 查状态
+cd D:\F\NewI\opencode\daily-workspace\projects\AgentsMeeting
+powershell -File deploy\windows\check.ps1
+```
+
+## 查看群消息（不离开 TUI）
+
+```powershell
+# 查 mohe 说了什么
+uv run python -c "import json,urllib.request; d=json.loads(urllib.request.urlopen('http://127.0.0.1:5802/messages?from=mohe').read()); [print(f\"{m['ts']} [{m['from']}] {m['body'][:200]}\") for m in d['messages']]"
+```
+
+## 发消息到群里
+
+```powershell
+# 给 mohe 发消息
+$body = @{message="这里是消息内容"} | ConvertTo-Json -Compress
+Invoke-RestMethod "http://127.0.0.1:5802/send" -Method POST -Body $body -ContentType "application/json"
+```
+
+## Bot 无响应
+
+```powershell
+# 强制重启
+Stop-Process -Name python* -Force
+Start-Process -WindowStyle Hidden -FilePath "C:\Users\hmo\AppData\Local\Programs\Python\Python310\python.exe" `
+  -ArgumentList "D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway\scripts\xmpp_bot.py"
+```
+
+## 启动全套服务
+
+```powershell
+powershell -File deploy\windows\start.ps1
+```
+
+## 健康检查日志
+
+```powershell
+Get-Content "D:\F\NewI\opencode\daily-workspace\projects\wechat-hermes-gateway\logs\health_check.log" -Tail 5
+```