企业官网建设流程全解析

MindEchoAgent（心境回响）：基于 hello-agents 框架的情绪驱动音乐推荐智能体实战

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

情绪驱动的音乐推荐智能体 MindEchoAgent（心境回响）是一个完全基于 hello-agents 框架（hello-agents>=0.2.7）构建的智能体应用：它通过「对话状态机 + 工具注册 + A2A 跨智能体协作」识别用户心境，进而完成情感安抚、音乐推荐与睡眠问题升级。阅读本文后，你将掌握如何使用 SimpleAgent、ToolRegistry、MemoryTool 与 A2ATool 搭建一个多状态、多工具、可扩展的情绪陪伴型智能体，并学会用 Gradio 为其快速落地可交互的 Web 演示界面。

项目定位：为什么是「情绪驱动」而非「标签驱动」

MindEchoAgent 的核心设计理念是情绪驱动，而非标签驱动：系统不依赖用户预先选择的音乐风格标签，而是通过自然语言理解用户当下心境（如"今天工作压力好大，想听放松的音乐"），结合对话状态与场景信息做动态推荐。该设计定位与代码结构在 README.md 中明确说明，同时项目强调「完全模拟、稳定可控」——内置高质量模拟数据，无需 API 密钥即可完整体验全部功能。

主要特点可归纳为四点：

• 情绪驱动：基于深度情绪识别而非简单标签匹配；
• Agent + Tool 架构：基于 hello-agents 框架，模块化设计，易于扩展；
• 完全模拟：内置模拟数据引擎，开箱即用；
• Gradio 快速演示：开箱即用的 Web 界面，支持实时交互；
• 跨智能体协作：通过 A2A 协议在必要时将失眠/焦虑问题升级给 SleepAgent 睡眠专家。

技术栈与运行环境

项目依赖清单位于 requirements.txt，关键依赖如下：

语言环境要求 Python 3.10+，数据处理依赖标准库json、datetime、typing。Docker 部署镜像基于python:3.12-slim，配置可见 Dockerfile。

快速启动

方式一：本地启动

# 1. 克隆项目 git clone https://github.com/pamdla/MindEchoAgent.git cd MindEchoAgent # 2. 安装依赖 pip install -r requirements.txt # 3. 启动应用 python main.py

启动后浏览器访问http://localhost:7860即可进入 Gradio 交互界面。

方式二：Docker Compose 部署

仓库同时提供了 docker-compose.yaml，编排了三个服务：

• mindechoagent：构建本项目镜像（image: mindechoagent），将当前目录挂载到/app，restart: unless-stopped保证自动重启；
• qdrant：向量数据库服务，暴露6333端口，数据持久化到./qdrant/data，并关闭遥测（QDRANT__TELEMETRY_DISABLED=true）；
• neosrv：Neo4j 图数据库（neo4j:2025.11.2-community），暴露7474（浏览器控制台）与7687（Bolt 协议）端口，默认认证neo4j/password，可选加载 APOC 插件。

docker compose up -d

项目结构解析

对照 README.md 中的目录说明与仓库实际文件，核心结构如下：

Co-creation-projects/pamdla-MindEchoAgent/ ├── main.py # Gradio 主界面 + SleepAgent 服务启动 ├── requirements.txt # 依赖列表 ├── Dockerfile # 容器镜像定义 ├── docker-compose.yaml # 多服务编排（应用 + Qdrant + Neo4j） ├── src/ # 源代码 │ ├── agents/ │ │ ├── sleep_agent.py # 子智能体（A2A 服务端） │ │ └── mind_echo_agent.py # 主智能体（Agent 组装） │ ├── tools/ │ │ ├── dialogue_state_tool.py # 对话状态工具 │ │ ├── mood_music_tool.py # 音乐推荐工具 │ │ ├── text_comfort_tool.py # 文字安慰工具 │ │ └── mood_summary_tool.py # 心情总结工具 │ └── utils/ │ ├── loader.py # 模拟数据加载 │ └── state.py # 状态枚举定义 └── data/ # 数据目录（心情记录等）

主智能体、工具、状态枚举三部分职责分离，是理解整个系统的关键入口。

核心功能详解

1. 情绪识别与响应

MindEchoAgent 的情绪识别并非单一模型判断，而是由「状态机 + 关键词规则 + LLM 生成」三层协作完成。

对话状态识别：系统定义了 6 种对话状态，见 src/utils/state.py：

class DialogueState(str, Enum): INIT = "init" # 初始状态 MOOD = "mood" # 情绪识别 COMFORT = "comfort" # 情感支持 MUSIC = "music" # 音乐推荐 REFLECT = "reflect" # 情绪反思 ESCALATE = "escalate" # 问题升级

状态判定由 dialogue_state_tool.py 的 MVP 规则完成（关键词触发，逻辑稳定可控）：

def run(self, query: str, current_state: str = "") -> str: if "睡不着" in query or "失眠" in query or "焦虑" in query: return DialogueState.ESCALATE.value if "听" in query or "音乐" in query: return DialogueState.MUSIC.value if "难受" in query or "不开心" in query: return DialogueState.COMFORT.value return DialogueState.MOOD.value

多维情绪检测：系统可识别 6 种核心情绪，同样定义在 src/utils/state.py：开心（happy）、悲伤（sad）、放松（relaxed）、专注（focused）、压力（stressed）、兴奋（excited）。

上下文感知与自然语言交互：系统提示词要求智能体每次对话先判断状态、再由状态决定调用哪个工具，因此可以理解"今天好累""心情美美的"等口语化表达，并自动映射到对应情绪与场景（工作、运动、学习、睡前等）。

2. 智能音乐推荐

音乐推荐由 mood_music_tool.py 实现，采用模拟数据引擎：通过 loader.py 从data/mood_music_map.json加载「情绪 → 歌曲」映射表（当前仓库中以模拟数据承载，覆盖多种风格和场景）。

def run(self, query: str) -> str: # 极简规则匹配（稳） for mood, songs in self.mood_map.items(): if mood in query: return self._format_result(mood, songs) # fallback return self._format_result( "未识别", ["Tycho - Awake", "Ólafur Arnalds - Near Light"] )

值得注意的设计点：

• 稳字优先：规则匹配保证确定性输出，LLM 只负责对话包装，避免推荐结果漂移；
• 优雅降级：未命中任何情绪时返回 fallback 歌单（后摇/新古典风格），保证任何输入都有响应；
• 播放时长计算：推荐结果附带播放列表总时长信息，优化聆听体验（README 中列为待完善项）。

3. 情感支持系统

情感支持采用双模式安慰引擎：预设回复模板 + LLM 生成。模板层由 text_comfort_tool.py 提供结构化安抚要点：

def run(self, query: str) -> str: return ( "安抚要点：\n" "1. 共情：承认情绪存在\n" "2. 允许停顿：不用强迫自己立刻变好\n" "3. 小动作：深呼吸、短暂休息、听轻音乐\n" "4. 若持续困扰，建议升级到 SleepAgent" )

LLM 层负责将这些要点组织成温暖、支持的自然语言（共情表达 + 适当 emoji），实现"稳定模板 + 创造性表达"的平衡，并给出可操作的情绪调节建议。

4. 心境记忆分析

心境记忆包含三层能力：历史记录（自动记录每次交互的心情状态）、模式识别（分析情绪变化趋势和时间分布）、个性化洞察（基于历史数据提供建议）。

源码层面，mind_echo_agent.py 注册了MemoryTool(user_id="user001")提供记忆读写，而 mood_summary_tool.py 生成长期记忆所需的心境总结模板，要求最终由 LLM 填充：

def run(self, query: str) -> str: return ( "请根据以下内容生成一个简短的心境总结（用于长期记忆）：\n" f"用户输入：{query}\n" "需要包含：\n" "1. 当前心境（1-2句）\n" "2. 触发因素（如果有）\n" "3. 可能的长期偏好（音乐/情绪）\n" )

该模块在 README 中标注为「待完善」，是后续版本的重点演进方向。

源码级原理剖析：Agent + Tool 如何组装

主智能体装配

create_mind_echo_agent 函数演示了 hello-agents 框架的标准装配流程：

llm = HelloAgentsLLM() agent = SimpleAgent( name="MindEchoAgent", llm=llm, system_prompt=system_prompt # 声明状态判断 → 工具调用 → 升级的决策规则 ) registry = ToolRegistry() registry.register_tool(MemoryTool(user_id=user_id)) registry.register_tool(DialogueStateTool()) registry.register_tool(TextComfortTool()) registry.register_tool(MoodMusicTool()) registry.register_tool(MoodSummaryTool()) # A2A 工具：指向 SleepAgent 服务 sleep_tool = A2ATool( agent_url="http://localhost:6000", # SleepAgent 默认端口 name="sleep_agent", description="睡眠专家，处理失眠/焦虑等问题" ) registry.register_tool(sleep_tool) agent.tool_registry = registry agent.current_state = DialogueState.INIT.value

关键设计：

• System Prompt 即决策策略：提示词明确规定"每次对话先判断状态（MOOD/COMFORT/MUSIC/ESCALATE），状态决定调用哪个工具；若出现'持续焦虑、睡不着、失眠'等关键词或状态为 ESCALATE，必须升级到 SleepAgent（A2A）"；
• ToolRegistry 统一注册：5 个本地工具 + 1 个 A2A 远程工具，模块间解耦，新增能力只需"写一个 Tool 类 + 注册一行"；
• A2ATool 连接远程智能体：通过agent_url="http://localhost:6000"指向睡眠专家服务，实现跨智能体调用。

跨智能体协作：A2A 协议实践

SleepAgent 是一个独立的 A2A 服务端，定义在 sleep_agent.py：

from hello_agents.protocols import A2AServer sleep_agent = A2AServer( name="sleep_agent", description="睡眠专家，提供助眠建议与睡眠策略" ) @sleep_agent.skill("answer") def answer_sleep_question(text: str) -> str: # MVP：直接返回固定策略（可扩展） return ( "睡眠建议：\n" "1. 关闭电子设备，做 5 分钟深呼吸\n" "2. 选择一首轻柔音乐，音量调低\n" "3. 若持续焦虑，建议记录当下思绪并写下 3 件感恩的事\n" "\n（如需要更个性化建议，可继续描述你的睡眠情况）" )

而 main.py 在启动 Gradio 界面前，先用后台线程拉起该 A2A 服务：

threading.Thread(target=lambda: sleep_agent.run(port=6000), daemon=True).start() time.sleep(1)

这里形成了一个完整的MindEchoAgent（情绪陪伴/音乐推荐）→ A2A 升级 → SleepAgent（睡眠专家）的级联协作链路：普通情绪问题由主智能体就地解决，睡眠/焦虑问题自动转交给专家智能体处理，体现了多智能体系统"专业分工、按需升级"的架构思想。

Web 界面操作

启动应用后，在浏览器打开http://localhost:7860：

1. 在输入框输入心情描述，如"今天工作压力好大，想听放松的音乐"；
2. 点击「✨ 发送」，界面左侧「🤖 AI 回响」区域展示智能响应，右侧「🎧 音乐推荐」面板展示推荐结果；
3. 查看智能响应，包含四类信息：情绪识别结果、个性化音乐推荐、情感支持文字、心情分析报告。

界面实现细节（见 main.py）：

• 模拟播放器：右侧music-player面板以渐变卡片展示当前歌曲、艺术家、心情与播放列表数量，并保留播放/暂停/切歌/音量控制按钮（当前为 JavaScript 模拟，实际音乐服务需后续集成）；
• 响应解析：extract_music_info()从智能体响应文本中定位并解析 JSON 格式的音乐数据（找不到时降级为默认推荐信息）；
• 快速示例：内置 5 个示例输入（压力大想放松、心情开心要活力、晚上睡不着焦虑、专注工作背景音乐、运动兴奋音乐），一键体验不同情绪链路；
• 服务配置：demo.queue().launch(server_name="0.0.0.0", server_port=7860)，局域网内设备也可访问。

后续优化计划

近期（约 1 个月）：功能扩展

• 记忆系统：记录和分析情绪变化，打通MemoryTool+MoodSummaryTool的完整落盘链路；
• 音乐预览片段：30 秒试听功能，将模拟播放器升级为真实音频播放；
• 增加音乐文件：不同类型各 1~2 首歌曲，丰富模拟数据引擎曲库。

中期（约 2 个月）：用户体验优化

• 对话历史管理：支持多轮对话上下文；
• 情感强度调节滑块：用户可调整推荐强度；
• 个性化偏好设置：音乐风格、语言偏好等；
• 多端适配：支持家居设备（音箱、灯光、窗帘等）。

智能家居扩展方案（小米音箱集成）

README 中给出了小米音箱集成的分阶段方案：

阶段 1：基础对接，技术栈为 Python + MiService + WebSocket：

1. 创建小米音箱技能：注册小米开发者账号 → 创建智能家居技能 → 配置语音交互模型；
2. 实现语音接口：语音转文本（ASR）→ 文本转语音（TTS）→ 指令解析与响应；
3. 设备控制集成：播放控制（播放、暂停、切歌）、音量调节、播放列表管理。

该方案与现有sleep_agent的answer技能形成呼应：未来用户可通过音箱说"我睡不着"，指令经 ASR 进入 MindEchoAgent，由状态机判定为 ESCALATE 后升级给 SleepAgent，最终以 TTS 输出助眠建议并联动播放轻柔音乐，构成完整的"语音入口 → 智能体决策 → 设备执行"闭环。

总结

MindEchoAgent 是一个麻雀虽小、五脏俱全的 hello-agents 实战范例：它用 6 个对话状态 + 6 种情绪刻画了情绪识别的最小状态机，用 5 个本地工具 + 1 个 A2A 远程工具演示了 ToolRegistry 的模块化扩展方式，并用SimpleAgent + A2AServer展示了一条完整的跨智能体升级链路。对于希望学习如何在 hello-agents 框架上快速搭建领域智能体的开发者，从 mind_echo_agent.py 的装配代码入手，对照 tools 目录下的工具实现，再结合 main.py 的 Gradio 集成，即可完整复现这套"情绪陪伴 + 音乐推荐 + 必要时升级专家"的智能体应用。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents