From 7df8df956ebcd653bd5744355ecafdbaccd19442 Mon Sep 17 00:00:00 2001 From: hmo Date: Thu, 16 Jul 2026 18:17:44 +0800 Subject: [PATCH] =?UTF-8?q?restructure:=20=E5=BC=80=E5=8F=91=E5=8E=9F?= =?UTF-8?q?=E5=88=99=20Tab=20=E7=B2=BE=E7=AE=80=E4=B8=BA=20G+K+F+H=20+=20?= =?UTF-8?q?=E5=8E=86=E5=8F=B2=E7=89=88=E6=9C=AC=20+=20F=20=E5=81=A5?= =?UTF-8?q?=E5=BA=B7=E8=A7=86=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/PRD.md | 187 +++++++---------------- gateway/scripts/dashboard.py | 33 ++++ gateway/scripts/templates/dashboard.html | 105 ++++++------- 3 files changed, 134 insertions(+), 191 deletions(-) diff --git a/docs/PRD.md b/docs/PRD.md index f72d6b3..9578a2f 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -1,163 +1,78 @@ # AgentsMeeting — 产品需求文档 (PRD) -> 版本: v0.1 | 状态: 初稿 | 客户: hmo (老莫) | PM: mohe (莫荷) | 研发: xxm (小小莫) +> 版本: v0.2 | 精简: 2026-07-16 | 客户: hmo (老莫) --- -## 1. 项目背景 +## 一、项目背景 -老莫运营一套多 Agent 协作系统，涵盖 XMPP 消息通道、AI Gateway、会话管理、记忆系统、Provider 调用链、多 profile 隔离等模块。系统经过数月迭代已具备完整功能，但存在以下问题： +老莫运营一套多 Agent 协作系统，涵盖 XMPP 消息通道、AI Gateway、会话管理、记忆系统、Provider 调用链、Web Dashboard 等模块。 -- 频繁断连/失联 — 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） +| 层 | 组件 | 说明 | +|----|------|------| +| **消息通道** | XMPP (ejabberd + bot)、微信 (wechat_agent)、QQ (规划中) | 多渠道统一接入 | +| **Gateway** | Hermes API Server (:8642~8646)，各 profile 独立 | 消息路由、会话、Provider 调用 | +| **会话管理** | SQLite state.db，硬截断 200 条 | 各 profile 独立文件 | +| **记忆系统** | SOUL.md + MEMORY.md + USER.md | 系统提示 + 长期记忆 + 用户画像 | +| **Provider** | volcengine / ocg / omlx，多 key 轮询/fallback | 多供应商 LLM 调用 | +| **辅助系统** | cron 调度 (14 jobs)、MoFin 股票、MCP 服务、Skills 系统 | 扩展功能 | +| **基础设施** | Linux 246 (主阵地)、Windows 16 (桥接)、阿里云中转 | | +| **管理门户** | Dashboard (:5803) | 监控 + 测试 + 规范 + 健康 | --- -## 3. 数据流 +## 三、总体性需求（双轨体系未覆盖部分） -### 3.1 XMPP 消息流 +以下需求不适合放入模块级 `specs/*.json`，属于跨模块/架构层级的约束： -用户 → ejabberd → XMPP Bot → POST /v1/chat/completions → Gateway(localhost:{port}) → Session → Memory → Provider → 回复 → ejabberdctl send_stanza → ejabberd → 用户 +### 3.1 架构约束 -### 3.2 微信消息流 +1. **一条消息只经过一个 Session** — 通道级隔离，不跨 profile 共享上下文 +2. **数据流路径可追溯** — 消息来源 → Gateway → Session → LLM → 回复 → 目标通道，每一步可日志追踪 +3. **SOUL.md 是行为最高准则** — MEMORY 不应包含与 SOUL 冲突的规则 +4. **配置即代码** — 所有配置纳入版本管理，禁止手动改线上文件 +5. **不推倒重来** — 以现有代码为基础，只做文档化和查漏补缺 -微信 → 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 → 微信 +### 3.2 可用性要求 + +1. **所有进程必须支持健康检查 + 自动重启** — systemd / 看门狗守护 +2. **Gateway 异常退出后 30s 内自动拉起** — 系统级恢复，不依赖人工 +3. **XMPP bot 断线自动重连** — 应用层心跳 + systemd 兜底重启 +4. **微信通道崩了不影响其他通道** — 通道级故障隔离 + +### 3.3 安全约束 + +1. **敏感信息不得入 git** — API Key、Cookie、密码仅存环境变量或 `.gitignore` 文件 +2. **Dashboard 管理接口需鉴权** — 涉部署操作（启停服务）须 Bearer token +3. **记忆系统不持久化敏感对话** — LLM 产出的敏感内容不应写入长期记忆 + +### 3.4 性能基准 + +1. **消息端到端延迟 < 30s**（含 LLM 推理）— 超过 60s 视为异常 +2. **Session 上下文上限 200 条 / 12k tokens** — 硬截断防膨胀 +3. **Dashboard 页面加载 < 3s** — 所有 API 聚合到 `/api/health-overview` --- -## 4. 已知问题与风险 +## 四、需求分布说明 -| 编号 | 问题 | 影响 | 当前措施 | 优先级 | 当前状态 | -|------|------|------|----------|--------|----------| -| R01 | Gateway 进程意外退出未自动拉起 | 服务中断 | 无自动恢复 | P0 | 🔄 Gateway 健康已纳入监控(I/J Tab显示), 自动拉起待 systemd 配置 | -| R02 | XMPP Bot 断线后重连失败 | 消息丢失 | slixmpp reconnect 不可靠 | P0 | ✅ frp heartbeat + 应用层保活(60s检测×3→exit→systemd重启) | -| 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 | ⏸️ 暂缓 — 当前无迫切需求 | +绝大多数具体需求（功能细节、API 定义、UI 交互、模块边界）**不在本文档描述**，而是通过双轨同源体系记录： -### 4.1 根因详解 +``` +每个功能模块 → specs/{module}.json + ├── human_help（? 按钮 → 人类看说明/排错） + └── ai_spec（§ 按钮 → AI 看接口/约束/测试） +``` -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 排查走错路。 +当前已用双轨覆盖的模块：`usage_monitor`、`easytier`、`rdp`。 +新增模块必须走此流程。 --- -## 5. 设计原则 - -1. **一条消息只经过一个 Session** — 通道级隔离，不跨 profile 共享上下文。 -2. **SOUL.md 是行为最高准则** — MEMORY 不应包含与 SOUL 冲突的规则。 -3. **所有进程支持健康检查和自动重启** — systemd + 心跳检测。 -4. **数据流路径可追踪** — 消息来源 → Gateway → Session → LLM → 回复 → 目标通道，每一步可日志追踪。 -5. **配置即代码** — 所有配置纳入版本管理。 -6. **不推倒重来** — 以现有代码为基础，只做文档化和查漏补缺。 ---- - -## 6. 交付物清单 - -| 交付物 | 负责人 | 状态 | 实现情况 | -|--------|--------|------|----------| -| PRD (本文档) | xxm | 初稿 | ✅ 已完成, dashboard H Tab展示 | -| 系统架构设计文档 | xxm + mohe | 待起草 | 🔄 ARCHITECTURE.md+dev-spec.md已完成 | -| 模块接口规范 | xxm | 待起草 | ❌ 待起草 | -| 代码工程化 (src/ 迁移) | xxm | 待启动 | ❌ 待启动 | -| 部署与运维文档 | xxm + mohe | 待起草 | 🔄 架构图已完成(ARCHITECTURE.md) | -| 测试套件 | xxm | ✅ 已完成 | ✅ tests/test_health_checks.py (15/15 通过) | -| 断连根因修复清单 | mohe | 待整理 | 🔄 R02已修复, 其他待排查 | -| 部署脚本 | xxm + mohe | 待启动 | ✅ deploy/windows/ 已就绪 | - ---- - -## 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 — 文档结束* +*PRD v0.2 — 精简版，仅保留双轨体系覆盖不到的架构级需求* diff --git a/gateway/scripts/dashboard.py b/gateway/scripts/dashboard.py index ad09120..59e3c99 100644 --- a/gateway/scripts/dashboard.py +++ b/gateway/scripts/dashboard.py @@ -1179,6 +1179,39 @@ def api_spec(): return jsonify({"ok": False, "error": str(e), "content": ""}) +@app.route("/api/spec/history") +def api_spec_history(): + """返回 dev-spec.md 的 git 历史版本""" + return _git_history_for(".memory/dev-spec.md") + + +@app.route("/api/prd/history") +def api_prd_history(): + """返回 PRD.md 的 git 历史版本""" + return _git_history_for("docs/PRD.md") + + +def _git_history_for(filepath): + """Helper: run git log for a file and return formatted history""" + project_root = _PROJECT_DIR + try: + cmd = ["git", "log", "--oneline", "--date=short", "--format=%h %ai %s", "--", filepath] + result = subprocess.run( + cmd, + cwd=project_root, + capture_output=True, + text=True, + timeout=15, + ) + if result.returncode == 0 and result.stdout.strip(): + lines = result.stdout.strip().split("\n") + return jsonify({"ok": True, "log": lines, "count": len(lines)}) + else: + return jsonify({"ok": True, "log": [], "count": 0}) + except Exception as e: + return jsonify({"ok": True, "log": [], "count": 0, "error": str(e)}) + + @app.route("/api/prd") def api_prd(): """返回产品需求文档 (PRD) 内容""" diff --git a/gateway/scripts/templates/dashboard.html b/gateway/scripts/templates/dashboard.html index 9d87076..e26057c 100644 --- a/gateway/scripts/templates/dashboard.html +++ b/gateway/scripts/templates/dashboard.html @@ -83,8 +83,8 @@ th{color:var(--dim);font-weight:600;font-size:19px}
\ No newline at end of file