mxyj-health-agent 技术架构文档

1. 文档目的

本文用于说明 mxyj-health-agent 工程的实际技术架构、核心模块职责、运行时链路、数据与基础设施依赖，以及生产部署建议。

从现有代码实态看，该工程已经不再是 README 中描述的简单骨架，而是一个围绕健康业务场景构建的 Agent 后端雏形，包含：

• 健康咨询与健康数据问答能力
• Agent 运行时与会话治理能力
• Soul / 长期记忆 / 动态人格体系
• Skill / Tool / Toolkit 能力集成机制
• MySQL、Redis、Mem0、OpenAI Compatible Model 等基础设施接入
• H5、REST、SSE 等多种交互入口

因此，本文将其定义为一个 健康陪伴型 Agent 平台后端，而不是普通聊天接口。

2. 总体结论

mxyj-health-agent 最适合采用 5 层 Agent 化架构 描述：

接入交互层 → 应用编排层 → Agent 认知层 → 能力集成层 → 数据与基础设施层

该工程的核心价值不是简单调用大模型，而是在运行时将用户身份、应用配置、人格设定、长期记忆、会话上下文、健康数据工具和技能系统组合成一个可持续演化的健康 Agent。

一句话概括：

这是一个 以 Agent 编排为核心、以健康数据工具为增强、以 Soul / 长期记忆为差异化能力 的健康陪伴型 Agent 平台后端。

3. 架构分层

3.1 第 1 层：接入交互层

接入交互层负责承接用户侧请求，并将其转换为后端可处理的会话请求。

主要入口包括：

• H5 页面
• REST API
• SSE 流式输出

代表性文件：

• src/main/resources/static/index.html
• src/main/resources/static/app.js
• src/main/java/com/mxyj/health/agent/controller/ChatController.java

核心职责：

• 接收用户输入
• 维护前端交互状态
• 发起普通聊天或流式聊天请求
• 对接后端 Agent 会话接口
• 展示模型输出与业务结果

3.2 第 2 层：应用编排层

应用编排层是整个系统的主流程控制层，负责把一次用户请求组织成完整的 Agent 调用流程。

代表性文件：

• src/main/java/com/mxyj/health/agent/service/AgentConversationService.java
• src/main/java/com/mxyj/health/agent/service/RuntimeBootstrapService.java

核心职责：

1. 解析运行时身份：appId、userId、会话标识等。
2. 判断是否需要首次建档。
3. 初始化或加载用户 Soul。
4. 组装系统上下文。
5. 调用 Agent 运行时。
6. 持久化会话与聊天日志。
7. 触发后处理流程，例如 Soul 信号抽取与人格演化。

该层本质上承担的是 Agent 应用编排器 的角色，而不是传统意义上的业务 Service。

3.3 第 3 层：Agent 认知层

Agent 认知层负责构建 Agent 的“认知上下文”，决定模型在每一轮对话中以什么身份、什么记忆、什么边界、什么任务目标进行响应。

代表性文件：

• src/main/java/com/mxyj/health/agent/service/ContextAssembler.java
• src/main/java/com/mxyj/health/agent/service/AgentPromptBuilder.java
• src/main/java/com/mxyj/health/agent/hook/HealthLongTermMemoryHook.java
• src/main/java/com/mxyj/health/agent/service/SoulSignalExtractionService.java
• src/main/java/com/mxyj/health/agent/service/SoulEvolutionService.java

核心职责：

• 加载 agents.md 系统人格配置
• 加载或生成 soul.md 用户人格画像
• 注入长期记忆
• 构建最终 system prompt
• 抽取用户行为与偏好信号
• 异步演化 Soul
• 控制安全边界与提示词治理

该层体现了系统的关键差异化能力：动态人格 Agent。

系统提示词不是静态字符串，而是由以下内容在运行时拼装而成：

1

agent_config + soul + long-term memory + session context + active tools

3.4 第 4 层：能力集成层

能力集成层负责把 AgentScope、SkillBox、Toolkit、健康业务工具和 Session Provider 装配成可运行的 Agent 实例。

代表性文件：

• src/main/java/com/mxyj/health/agent/service/AgentFactory.java
• src/main/java/com/mxyj/health/agent/service/AgentSkillService.java
• src/main/java/com/mxyj/health/agent/tool/SleepHealthTool.java
• src/main/java/com/mxyj/health/agent/config/AgentScopeSessionConfig.java

核心职责：

• 创建 AgentScope ReActAgent
• 装配 SkillBox
• 装配 Toolkit
• 注入睡眠、饮食、画像等健康工具
• 配置 AgentScope Session Provider
• 支持按 appId 加载技能
• 支持对话中的技能延迟激活

该层说明系统不是固定工具箱模式，而是 技能按需加载型 Agent。

3.5 第 5 层：数据与基础设施层

数据与基础设施层为 Agent 运行时提供数据、记忆、模型和可观测性能力。

代表性文件：

• src/main/resources/db/schema.sql
• src/main/java/com/mxyj/health/agent/mapper/B2cHealthDataMapper.java
• src/main/java/com/mxyj/health/agent/memory/HealthMem0LongTermMemory.java
• src/main/java/com/mxyj/health/agent/logging/RequestTraceFilter.java
• src/main/resources/application.yml

主要依赖：

• MySQL：业务健康数据、Agent 元数据、Skill、Soul、聊天日志
• Redis：生产环境 Session、活跃会话、缓存
• Mem0：长期记忆服务
• OpenAI Compatible Model：vLLM 或模型推理网关
• 日志 / Trace / Metrics：请求追踪与运行观测

4. 技术架构图

flowchart TB
    UI["H5 前端<br/>index.html + app.js"] --> API["Controller 接入层<br/>ChatController / AgentProfileController"]
    API --> APP["应用编排层<br/>AgentConversationService<br/>RuntimeBootstrapService"]
    APP --> COG["Agent 认知层<br/>ContextAssembler<br/>PromptBuilder<br/>Soul Extraction/Evolution"]
    APP --> FACTORY["能力装配层<br/>AgentFactory"]
    FACTORY --> AGENT["AgentScope ReActAgent"]
    AGENT --> AUTO["AutoContextMemory + Hook"]
    AGENT --> LTM["HealthLongTermMemoryHook"]
    AGENT --> SKILL["SkillBox + Toolkit"]
    SKILL --> TOOL1["SleepHealthTool"]
    SKILL --> TOOL2["DietHealthTool"]
    SKILL --> TOOL3["UserProfileTool"]
    TOOL1 --> HEALTH["HealthDataQueryService"]
    TOOL2 --> HEALTH
    TOOL3 --> PROFILE["UserProfileQueryService"]
    HEALTH --> MYSQL["MySQL<br/>b2c_hm503 / b2c_agent"]
    PROFILE --> MYSQL
    COG --> META["agent_config / agent_soul / history"]
    META --> MYSQL
    LTM --> MEM0["Mem0 长期记忆服务"]
    AGENT --> MODEL["OpenAI Compatible Model<br/>vLLM / 推理网关"]
    APP --> SESSION["AgentScope Session"]
    SESSION --> REDIS["Redis 或 InMemory"]
    API --> TRACE["RequestTraceFilter + Reactor Trace"]

5. 业务技术架构图

flowchart LR
    USER["用户"] --> Q1["健康咨询 / 图片问答 / 睡眠分析"]
    Q1 --> ENTRY["聊天入口"]
    ENTRY --> ID["运行时身份解析<br/>appId + userId"]
    ID --> BOOT["首次建档判断"]
    BOOT -->|未建档| INIT["LLM 初始化 soul.md"]
    BOOT -->|已建档| CTX["上下文组装"]
    INIT --> CTX

    CTX --> PROMPT["system prompt = agents.md + soul.md + long-term memory"]
    PROMPT --> ROUTE["技能路由判断"]
    ROUTE -->|睡眠问题| SLEEP["加载 sleep skill"]
    ROUTE -->|饮食问题| DIET["加载 diet skill"]
    ROUTE -->|普通问题| CHAT["直接问答"]

    SLEEP --> DATA["健康数据查询"]
    DIET --> DATA
    DATA --> TABLES["睡眠 / 饮水 / 热量 / 体重表"]

    CHAT --> ANSWER["生成回答"]
    SLEEP --> ANSWER
    DIET --> ANSWER

    ANSWER --> SAVE["保存 Session + 聊天日志"]
    SAVE --> EVOLVE["异步抽取信号并演化 soul"]
    EVOLVE --> NEXT["下轮对话个性化增强"]

6. 核心运行链路

一次完整对话大致经过以下链路：

1. 用户通过 H5、REST 或 SSE 入口发起请求。
2. Controller 接收请求并转交应用编排层。
3. 应用编排层解析 appId、userId、会话 ID 等运行时身份。
4. 系统判断用户是否已完成 Agent 建档。
5. 如果未建档，则调用模型初始化用户 soul.md。
6. ContextAssembler 加载 Agent 配置、Soul、长期记忆和会话上下文。
7. AgentPromptBuilder 组装最终 system prompt。
8. AgentFactory 装配 AgentScope ReActAgent、SkillBox、Toolkit 与业务工具。
9. Agent 根据用户问题决定是否调用睡眠、饮食、画像等工具。
10. 工具访问健康业务数据表或用户画像数据。
11. 模型生成回答。
12. 系统保存聊天日志与 Session 状态。
13. 异步流程抽取本轮对话中的用户偏好、健康信号或人格信号。
14. SoulEvolutionService 更新 Soul，为下一轮对话提供更强个性化能力。

7. 关键架构判断

7.1 它是动态人格 Agent，而不是普通问答接口

普通问答接口通常只有固定 prompt、用户输入和模型输出。

该工程的核心机制是：

1

system prompt = agents.md + soul.md + long-term memory + runtime context

这意味着 Agent 的回答会随着用户画像、长期记忆和 Soul 演化持续变化。

7.2 它是会话托管型 Agent，而不是业务层手写 history

系统并不是单纯在业务表里拼接历史消息，而是将真实会话状态托管给 AgentScope Session。

业务层主要维护：

• 当前活跃会话映射
• 用户身份
• appId 上下文
• 持久化日志
• 后处理任务

这有利于后续支持多轮记忆、工具调用状态、复杂 Agent 执行链路和多实例部署。

7.3 它是技能按需加载型 Agent，而不是固定工具箱

系统中的 Skill 不是硬编码在 Agent 内部，而是可以从数据库发布、按 appId 装配，并在对话过程中延迟激活。

这使系统具备平台化扩展潜力：

• 不同 appId 可以有不同 Agent 能力包
• 不同健康业务场景可以注册不同工具
• 可以逐步扩展睡眠、饮食、运动、慢病、体检解读等垂直 Skill

8. 数据架构

8.1 Agent 元数据

主要用于保存 Agent 配置、Skill 配置、Soul 信息和对话运行所需的元信息。

建议归入 b2c_agent 库。

典型数据包括：

• agent_config
• agent_soul
• skill 定义
• skill 发布关系
• 会话日志
• 运行时配置

8.2 健康业务数据

主要用于支持健康问答和工具查询。

建议归入 b2c_hm503 库。

典型数据包括：

• 睡眠数据
• 饮水数据
• 热量数据
• 体重数据
• 用户画像数据
• 其他健康业务表

8.3 长期记忆数据

长期记忆通过 Mem0 服务承载，适合保存跨会话的用户偏好、行为信号和长期上下文。

长期记忆不应替代业务数据库。二者职责不同：

9. 推荐生产部署架构

flowchart TB
    U["Web / App / 内嵌 H5"] --> GW["Nginx / API Gateway / Ingress"]
    GW --> LB["Spring Boot Agent Service<br/>多副本无状态部署"]

    LB --> REDIS["Redis 主从或 Redis Cluster<br/>Session / 活跃会话 / 缓存"]
    LB --> MYSQL["MySQL 主从<br/>b2c_agent + b2c_hm503"]
    LB --> MODEL["模型网关 / vLLM 集群<br/>OpenAI Compatible"]
    LB --> MEM0["Mem0 服务"]
    LB --> OBS["日志 / Trace / Metrics<br/>ELK + Prometheus + Grafana"]
    LB --> SECRET["配置中心 / Secret Manager"]

    subgraph K8S["推荐生产环境：Kubernetes"]
        LB
    end

10. 部署建议

10.1 生产必须使用 Redis Session

当前配置默认使用 memory session。该方案适合本地开发或单机验证，但不适合生产多实例部署。

生产环境应切换到 Redis Session，否则可能出现：

• 多实例之间会话不一致
• 用户请求被负载均衡到不同节点后上下文丢失
• AgentScope Session 状态无法跨节点共享
• 容器重启后会话状态丢失

10.2 应用节点应无状态化

Spring Boot 服务应只负责 Agent 编排，不应依赖本地内存保存关键状态。

推荐原则：

• 会话状态放 Redis
• 业务数据放 MySQL
• 长期记忆放 Mem0
• 文件与密钥外置
• 模型推理服务独立部署

10.3 模型层应独立扩缩容

LLM 推理耗时长、资源消耗大，不应与业务 API 强耦合。

推荐将模型层拆为：

• 模型网关
• vLLM 推理集群
• 限流与熔断层
• 模型调用监控

这样可以避免长推理、慢响应或模型故障拖垮整个业务服务。

10.4 MySQL 应按职责拆分

建议将数据职责明确分层：

• b2c_agent：Agent 元数据、Skill、Soul、会话日志
• b2c_hm503：健康业务数据、用户健康记录、业务画像

这种拆分有利于后续治理权限、备份策略、慢查询优化和业务域演进。

10.5 密钥必须外置

如果 application.yml 中存在模型、Mem0 或数据库明文配置，生产必须迁移到：

• 环境变量
• Kubernetes Secret
• 云厂商 Secret Manager
• 配置中心

严禁将生产密钥提交到代码仓库。

11. 风险与改进建议

12. 后续演进路线

12.1 第一阶段：生产可用性加固

目标：让系统具备稳定上线条件。

建议事项：

• Redis Session 替换 memory session
• 密钥外置
• 模型调用超时、重试、熔断
• 完善日志 Trace ID
• 增加 Agent 调用链路监控
• 补充核心 Service 单元测试

12.2 第二阶段：Agent 能力治理

目标：让 Agent 行为可控、可审计、可回滚。

建议事项：

• Soul 版本管理
• Soul 演化审计
• 长期记忆写入策略
• Prompt 版本管理
• Skill 权限模型
• Tool Call 审计日志

12.3 第三阶段：健康业务能力扩展

目标：从通用健康陪伴扩展到垂直健康 Agent 平台。

建议事项：

• 睡眠分析 Skill 深化
• 饮食分析 Skill 深化
• 运动建议 Skill
• 体检报告解读 Skill
• 慢病管理 Skill
• 用户画像与健康目标管理

12.4 第四阶段：平台化与多租户

目标：支持多个 appId、多个健康业务场景和多种 Agent 配置。

建议事项：

• appId 级别 Agent 配置隔离
• Skill 市场或 Skill 发布机制
• 多租户数据隔离
• Agent 模板体系
• 灰度发布与 A/B 测试

13. 总结

mxyj-health-agent 的本质不是传统三层后端，也不是简单的大模型聊天 Demo。

它已经具备 Agent 平台后端的关键雏形：

• 有接入层：H5、REST、SSE
• 有编排层：会话解析、建档、上下文组装、持久化、后处理
• 有认知层：agents.md、soul.md、长期记忆、提示词治理
• 有能力层：AgentScope、SkillBox、Toolkit、健康工具
• 有基础设施层：MySQL、Redis、Mem0、模型网关、日志追踪

最准确的架构定位是：

健康陪伴型动态人格 Agent 平台后端。

后续架构工作的重点不应是继续堆业务接口，而应围绕三条主线推进：

1. 生产稳定性：Session、模型调用、密钥、可观测性。
2. Agent 可治理性：Prompt、Soul、Memory、Skill、Tool Call 的版本与审计。
3. 健康业务专业化：围绕睡眠、饮食、运动、慢病、体检等场景沉淀可复用 Skill。