diff --git a/docs/PRD.md b/docs/PRD.md index 4fb5b95..d203870 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -4,7 +4,7 @@ --- -## 1. 项目背景 +## 1. 项目背景 老莫运营一套多 Agent 协作系统，涵盖 XMPP 消息通道、AI Gateway、会话管理、记忆系统、Provider 调用链、多 profile 隔离等模块。系统经过数月迭代已具备完整功能，但存在以下问题： @@ -18,15 +18,15 @@ --- -## 2. 系统范围 +## 2. 系统范围 -### 2.1 消息通道层 (Channels) +### 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 层 +### 2.2 Gateway 层 - 基于 hermes-agent 框架，每个 profile 独立 Gateway 进程。 - 职责：消息路由、会话管理、Provider 调用链、工具执行、回复生成。 @@ -34,28 +34,28 @@ - 超时配置：1800s 总超时，900s 告警，180s 通知间隔。 - 健康检查：/v1/health 端点返回 pong。 -### 2.3 会话管理层 (Session) +### 2.3 会话管理层 (Session) - 存储：SQLite (state.db)，各 profile 独立文件。 - 核心机制：硬截断最近 200 条消息 (hermes_state.py LIMIT 200)。 - session_rewrite：可设置重写规则（如默认 → sisyphus）。 - 已知问题：Gateway 内存缓存 session，移走 state.db 后需重启进程才生效。 -### 2.4 记忆系统 (Memory) +### 2.4 记忆系统 (Memory) - **SOUL.md** — 系统提示，行为最高准则（身份锚定、行为规则、沉默机制）。 - **MEMORY.md** — 长期记忆，被 LLM 检索并注入上下文。 - **USER.md** — 用户画像，记录沟通风格和偏好。 - 已知问题：SOUL 与 MEMORY 规则冲突时，LLM 优先执行 MEMORY 中的简略规则。 -### 2.5 Provider 调用链 +### 2.5 Provider 调用链 - 每个 profile 独立配置 provider 和 fallback 链。 - 支持：volcengine (火山引擎)、ocg-old/ocg-new、omlx (本地 MLX)。 - credential_pool_strategies：多 key 轮询/fallback 策略。 - 已知问题：key 过期/配额超限后 fallback 可能因配置格式问题不触发。 -### 2.6 辅助系统 +### 2.6 辅助系统 - **cron 调度系统** — 14 个 job（价格监控、数据同步、持仓分析等）。 - **MoFin 股票系统** — price_monitor、technical_analysis、strategy 模块。 @@ -63,7 +63,7 @@ - **Skills 系统** — 34 个技能分类。 - **Web Dashboard** — 状态监控页面。 -### 2.7 基础设施 +### 2.7 基础设施 - **服务器** — Linux 192.168.1.246 (主阵地，所有 Gateway/cron/XMPP bot/ejabberd) - **客户端** — Windows 192.168.1.16 (跑 wechat_agent 桥 + xxm chat_bridge) @@ -73,7 +73,7 @@ --- -## 3. 数据流 +## 3. 数据流 ### 3.1 XMPP 消息流 @@ -85,19 +85,19 @@ --- -## 4. 已知问题与风险 +## 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 | +| 编号 | 问题 | 影响 | 当前措施 | 优先级 | 当前状态 | +|------|------|------|----------|--------|----------| +| R01 | Gateway 进程意外退出未自动拉起 | 服务中断 | 无自动恢复 | P0 | ❌ 未修复 | +| R02 | XMPP Bot 断线后重连失败 | 消息丢失 | slixmpp reconnect 不可靠 | P0 | ✅ frp heartbeat已加 | +| R03 | Provider key 过期/配额超限无告警 | LLM 调用失败 | fallback 不总能触发 | P0 | 🔄 fallback链待验证 | +| R04 | Session 膨胀导致响应退化 | 回复质量下降 | 硬截断 200 条 | P1 | ✅ 硬截断200条已实现 | +| R05 | SOUL vs MEMORY 规则冲突 | 行为异常 | 需手动清理 memory | P1 | 🔄 需持续维护 | +| R06 | Gateway 非热加载 session | 更新需重启进程 | 手动 kill -9 | P1 | ❌ 非热加载问题未改 | +| R07 | 群聊消息路由混淆 | LLM 分不清职责 | 来源标记 + 身份锚定 | P2 | 🔄 已缓解 | +| R08 | 缺乏统一监控告警 | 排障依赖人工 | 无 | P1 | ✅ 监控体系已建立(Phase2) | +| R09 | QQ 通道未实现 | 缺少渠道 | 规划中 | P3 | ❌ 未开始 | ### 4.1 根因详解 @@ -115,7 +115,7 @@ --- -## 5. 设计原则 +## 5. 设计原则 1. **一条消息只经过一个 Session** — 通道级隔离，不跨 profile 共享上下文。 2. **SOUL.md 是行为最高准则** — MEMORY 不应包含与 SOUL 冲突的规则。 @@ -125,22 +125,22 @@ 6. **不推倒重来** — 以现有代码为基础，只做文档化和查漏补缺。 --- -## 6. 交付物清单 +## 6. 交付物清单 -| 交付物 | 负责人 | 状态 | -|--------|--------|------| -| PRD (本文档) | xxm | 初稿 | -| 系统架构设计文档 | xxm + mohe | 待起草 | -| 模块接口规范 | xxm | 待起草 | -| 代码工程化 (src/ 迁移) | xxm | 待启动 | -| 部署与运维文档 | xxm + mohe | 待起草 | -| 测试套件 | xxm | 待启动 | -| 断连根因修复清单 | mohe | 待整理 | -| 部署脚本 | xxm + mohe | 待启动 | +| 交付物 | 负责人 | 状态 | 实现情况 | +|--------|--------|------|----------| +| PRD (本文档) | xxm | 初稿 | ✅ 已完成, dashboard H Tab展示 | +| 系统架构设计文档 | xxm + mohe | 待起草 | 🔄 ARCHITECTURE.md+dev-spec.md已完成 | +| 模块接口规范 | xxm | 待起草 | ❌ 待起草 | +| 代码工程化 (src/ 迁移) | xxm | 待启动 | ❌ 待启动 | +| 部署与运维文档 | xxm + mohe | 待起草 | 🔄 架构图已完成(ARCHITECTURE.md) | +| 测试套件 | xxm | 待启动 | ❌ 待启动 | +| 断连根因修复清单 | mohe | 待整理 | 🔄 R02已修复, 其他待排查 | +| 部署脚本 | xxm + mohe | 待启动 | ✅ deploy/windows/ 已就绪 | --- -## 7. 项目时间线 +## 7. 项目时间线 | 阶段 | 内容 | 时间 | |------|------|------| @@ -152,7 +152,7 @@ --- -## 8. 角色与职责 +## 8. 角色与职责 - **客户 (老莫 hmo)** — 需求提出方，审阅并确认所有交付物 - **PM (莫荷 mohe)** — 资源协调、架构审核、进度跟踪、质量验收