Files

T

hmo 1b2b935832 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:51:36 +08:00

7.7 KiB

Raw Permalink Blame History

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 根因详解

消息路由混淆 — 群聊消息进同一 session 后 LLM 分不清哪条是自己该处理的。已通过 [群聊] 时间戳来源标记 + 独立 session 隔离缓解。
粘性 session — Gateway 进程即使移走 session 文件，内存中缓存的旧 session 仍存在，必须 kill 重启。
SOUL vs MEMORY 冲突 — SOUL 是系统提示，MEMORY 是上下文，LLM 检索 MEMORY 命中时会覆盖 SOUL 规则。这是小果“闭不了嘴”的根因。
会话膨胀 → 响应退化 — 知微曾出现 13.8 万 token 上下文，223 条消息中仅 26 条是用户消息。已用硬截断 200 条解决。
通道断连 — XMPP bot systemd 显示 active 但实际未连上 ejabberd。ejabberd 长期不活跃连接会被自动踢掉。
网络拓扑混乱 — 192.168.1.246 (Linux 服务器) 与 47.115.32.206 (阿里云) 混淆，曾导致 SSH 排查走错路。

5. 设计原则

一条消息只经过一个 Session — 通道级隔离，不跨 profile 共享上下文。
SOUL.md 是行为最高准则 — MEMORY 不应包含与 SOUL 冲突的规则。
所有进程支持健康检查和自动重启 — systemd + 心跳检测。
数据流路径可追踪 — 消息来源 → Gateway → Session → LLM → 回复 → 目标通道，每一步可日志追踪。
配置即代码 — 所有配置纳入版本管理。
不推倒重来 — 以现有代码为基础，只做文档化和查漏补缺。

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 — 文档结束

7.7 KiB Raw Permalink Blame History Unescape Escape